┌────────────────────────────────────────────────────────────┐
│ 消费层   Claude Code (MCP+Skill) │ Codex (MCP) │ 终端 CLI  │
└──────────┬───────────────────────┬──────────────┬───────────┘
           │      stdio (JSON-RPC) │              │
┌──────────▼───────────────────────▼──────────────▼───────────┐
│ mcp_server.py —— 15 个工具的薄适配层（无业务逻辑）            │
├──────────────────────────────────────────────────────────────┤
│ 核心层（Python，可脱离 MCP 独立使用）                         │
│  account   登录态/账号发现（pgrep + lsof，只读）              │
│  keys      passphrase 缓存 + PBKDF2 派生 + HMAC 自验证        │
│  bootstrap lldb 断点捕获 passphrase（唯一需要 sudo 的环节）   │
│  decrypt   db+wal+shm 快照 → sqlcipher 解密（用后即焚）       │
│  reader    消息解码（zstd/类型掩码/群前缀）与流式产出          │
│  export    流式导出管道（幂等 upsert + 水位线 + 长任务）      │
│  store     本地检索库（SQLite + FTS5 trigram）                │
│  search    检索路由（trigram / LIKE 兜底）                    │
│  vector    向量索引与语义检索（本地 fastembed + sqlite-vec）  │
│  purge     本地数据销毁（清单→计划→执行→核查，CLI 专属）      │
│  exclusions 被销毁会话的排除清单（唯一不可重建的产物）        │
├──────────────────────────────────────────────────────────────┤
│ 数据层                                                        │
│  微信容器（只读） │ ~/.agent-wechat/（0700：密钥缓存+索引库） │
└──────────────────────────────────────────────────────────────┘

# 1. 安装（macOS + 微信 4.1.x，见 INSTALL.md 的完整前置条件）
cd ~/agent-wechat && uv sync

# 2. 一次性引导（仅首次 / 微信升级后；需 sudo，期间要在微信里重新登录一次）
killall WeChat
sudo codesign --force --deep --sign - /Applications/WeChat.app
open /Applications/WeChat.app        # 然后在微信中登录
sudo uv run --directory ~/agent-wechat agent-wechat bootstrap
#    启动后 5 分钟内：微信内 退出登录 → 重新登录，触发密钥捕获

# 3. 验证
uv run agent-wechat status --verify-keys     # 期望：HMAC 33/33

# 4. 使用
uv run agent-wechat recent filehelper -n 5   # 实时读取
uv run agent-wechat export                   # 全量导出（~2 分钟）
uv run agent-wechat search "关键词"           # 检索

# 5.（可选）向量语义检索：先建索引（首次会下载约 95MB 本地模型，之后完全离线）
uv run agent-wechat vector-build
uv run agent-wechat semantic "上次说的那个爬山的安排"

agent-wechat/
├── README.md              ← 本文件
├── CONTEXT.md             领域词表（代码与文档共用的术语）
├── .mcp.json              Claude Code 项目级 MCP 配置
├── .codex/config.toml     Codex 项目级 MCP 配置（与 .mcp.json 同构的 TOML 版）
├── src/agent_wechat/      核心包（模块职责见 ARCHITECTURE.md）
│   ├── paths.py           路径常量与账号目录解析
│   ├── account.py         登录态检测与账号识别
│   ├── keys.py            密钥派生/校验/缓存
│   ├── bootstrap.py       lldb 捕获（sudo）
│   ├── decrypt.py         快照与解密
│   ├── errors.py          统一错误契约
│   ├── messages.py        messages 行契约
│   ├── appmsg.py          appmsg 原始载荷的规范化与解析
│   ├── msgextra.py        位置/名片原始载荷的解析
│   ├── roster.py          显示名规则（群昵称/备注/昵称优先级）
│   ├── schema.py          微信库结构声明与能力探测
│   ├── reader.py          消息读取与解码
│   ├── media.py           媒体导出（图片解密 / 语音 SILK→WAV / 视频定位）
│   ├── moments.py         朋友圈解析（sns.db，只读不联网）
│   ├── sns_media.py       朋友圈远程媒体下载与解密（HTTP、默认关；media.py 另有贴纸 CDN 取件一条，同为 HTTP、默认关——两者是本项目仅有的两条外发路径）
│   ├── moments_html.py    朋友圈渲染（单文件 HTML）
│   ├── chat_text.py       两个会话模板共享的措辞与纯函数
│   ├── chatview.py        会话时间线组装与落盘
│   ├── chat_html.py       会话时间线的 HTML 模板
│   ├── chat_md.py         会话时间线的 Markdown 模板
│   ├── chat_index.py      会话索引页模板
│   ├── export.py          导出管道与水位线续跑
│   ├── store.py           本地检索库
│   ├── search.py          检索路由
│   ├── vector.py          向量索引与语义检索
│   ├── tasks.py           长任务注册表
│   ├── usecases.py        用例层（两个入口共享的入口策略）
│   ├── purge.py           数据销毁（CLI 专属）
│   ├── exclusions.py      会话销毁的排除清单（唯一不可重建的产物）
│   ├── webui.py           本地只读工作台（Phase 07，仅 loopback）
│   ├── derived.py         本地 OCR/ASR 派生文本与事实记忆（Phase 06）
│   ├── retrieval.py       统一检索与两阶段披露（Phase 05）
│   ├── sync.py            同步编排与只读诊断（Phase 04）
│   ├── mcp_server.py      MCP 工具层
│   └── cli.py             命令行入口
├── tests/                 集成测试（合成加密库，不依赖真机）
├── skills/                随仓库分发的 Claude Code Skill（wechat-reply）
├── spike/                 密钥可行性探索脚本（一次性，留档）
└── docs/
    ├── INSTALL.md         安装与配置
    ├── USAGE.md           使用指南
    ├── TOOLS.md           MCP 工具参考
    ├── ARCHITECTURE.md    架构设计
    ├── DATA_MODEL.md      数据与存储
    ├── SECURITY.md        隐私与安全
    ├── TROUBLESHOOTING.md 故障排查
    ├── FAQ.md             常见问题
    ├── schema-4.1.13.md   微信库结构实测记录
    ├── CHANGELOG.md       版本记录
    └── CONTRIBUTING.md    贡献指南