BENZEMA216/wechat-archive-harness

DeepSeek Harness 微信归档插件

一个面向 macOS、本地优先、默认拒绝危险状态的微信归档插件。它把四个边界明确的操作接入
DeepSeek Harness：诊断、查看状态、同步和校验；同时提供 Agent Skill，以及一个可选的 macOS
LaunchAgent，用于脱离对话会话的周期运行。

0.1.0 版本能够从一个静止、已 checkpoint 的 Mac 微信数据库快照中，扫描所有已发现的
message_N.db 分片及其中的全部 Msg_ 表。它将消息保存为可重放、可校验的 JSONL 增量，
并把本机可取得的图片容器、MP4 和语音 BLOB 保存成私有的内容寻址对象。

发布状态： 实现与合成安全测试已经完成，但制作本次发布时没有运行真实聊天同步
（NOT_RUN）*。同步默认保持关闭，也不会自动安装 LaunchAgent。

Mac 微信数据源
|
v
确定性 Python core ----> 私有状态 + JSONL 增量 + 媒体对象
|                                  |
+---- stdio MCP ---- DeepSeek Harness
|                                  +---- 重放与哈希校验
+---- 单次调度入口 ---- 可选 macOS LaunchAgent

提供的能力

| 界面 | 操作 | 是否写入归档？ |
| --- | --- | --- |
| MCP | wechat_doctor | 否——检查应用、数据源、WAL、密钥和权限 |
| MCP | wechat_status | 否——返回有界的运行状态信息 |
| MCP | wechat_sync | 是——必须同时打开服务端开关并传入 confirm=true |
| MCP | wechat_verify | 否——重放消息历史并校验哈希和覆盖关系 |
| Agent Skill | wechat-archive | 指导模型遵守强制安全流程 |
| 调度器 | 先 sync，再 verify | 只有操作者亲自安装 LaunchAgent 后才会写入 |

MCP 结果只暴露状态、数量、覆盖关系和完整性信息，不会返回联系人姓名、账号标识、消息正文、
密钥或私有数据库路径。

完整性与隐私边界

- 工具参数不能选择账号、文件路径、SQL、可执行文件或密钥。
- 插件不会抓取密钥、附加 LLDB、重签或替换 WeChat、结束应用进程，也不会忽略 WAL。
- 当 WeChat 正在运行、WAL 含有事务帧或短头畸形、应用不符合固定的官方签名、密钥失效，
或数据源在采集期间发生变化时，同步会失败，并且不会发布新快照。
- 每个加密数据库都独立派生并通过 HMAC 校验密钥。解密后的暂存文件保持私有，经过 SQLite
quick_check，并在本次运行结束后删除。
- 不可变 JSONL 增量会先 fsync，再提交索引事务。校验会重放完整历史，并对当前和历史上
登记过的所有媒体对象进行哈希验证。
- 密钥只能保存在 macOS Keychain 中，不能出现在工具参数、命令行参数、环境变量、日志、
提交到 Git 的配置或发布文件中。

SOURCE_FAITHFUL_V1 的准确含义

图片始终保留原始 .dat 字节。只有强文件魔数或唯一的单字节 XOR 转换通过验证时，才会另外
写入解码图片。视频必须带有 MP4 ftyp 标记。语音 BLOB 会被保留，但不会宣称已经转写或可播放。

表情、通用附件、未下载到这台 Mac 的媒体和部分私有容器仍可能处于未解决状态。因此公开结果
始终明确为 media_complete=false。SOURCE_FAITHFUL_V1 表示本机可取得的源字节已经被保存
和校验，不代表它是一个完全解码、全部可播放的多模态导出。

同样，“完整”最多只能描述一个经过验证、静止的 Mac 数据库快照。它不包括已删除、仅云端、
仅手机端，或从未由 WeChat 保存到本机的历史。

环境要求

- macOS
- Python 3.10 或更新版本
- Node.js 24 或更新版本
- pnpm 11
- uv
- libzstd，用于解码 zstd 压缩的消息载荷；缺少它时，原始压缩字节仍会以 base64 保存
- 官方 WeChat 安装，以及对本人本地账号数据的合法访问权

只能对你有权归档的数据使用本项目。即使账号属于你，聊天归档仍包含他人的私人信息；请把归档
保存在本机受控目录中，不要提交到 Git。

安装 core 与 MCP Server

进入本仓库的本地 checkout：

cd /path/to/wechat-archive
PROJECT_DIR="$(pwd -P)"
CONFIG_PATH="${HOME}/Library/Application Support/WeChatArchive/config.json"

uv venv
uv pip install -e '.[test]'
pnpm --dir mcp-server install --frozen-lockfile

mkdir -p "$(dirname "$CONFIG_PATH")"
chmod 700 "$(dirname "$CONFIG_PATH")"
cp config.example.json "$CONFIG_PATH"
chmod 600 "$CONFIG_PATH"

参考 config.example.json 的结构编辑私有配置。source.root 与
archive.root 必须是绝对、规范化且彼此分离的路径；归档根目录不能位于数据源目录内。
生产配置应使用 Keychain provider。file provider 只用于迁移一个既有的、归当前用户所有、
mode 为 0600 的常规文件；symlink 会被拒绝。

密钥获取和应用修复被刻意放在插件能力之外。请遵循
docs/BOOTSTRAP.md 中的人工监督边界，不要把密钥写进 shell 历史，也不要
要求 Agent 修改 WeChat。

先运行只读预检：

.venv/bin/wechat-archive --config "$CONFIG_PATH" doctor

命令只会向 stdout 写入一个 wechat-archive.command/v1 JSON 对象。只有 READY 才允许另行
确认同步。状态模型见架构与完整性说明。

安装到 DeepSeek Harness

安装器默认只做 dry-run，只有传入 --install 才会修改：

python3 scripts/install_dsh.py
python3 scripts/install_dsh.py --install

它只管理 Harness profile 中一块带标记的内容，以及一个指向当前 checkout 的
~/.dsh/skills/wechat-archive symlink。它不会修改 DeepSeek Harness 的源码 checkout，也不会
覆盖无关 Skill。修改 live profile 之前，会创建一份 mode 为 0600 的备份。

Harness 中暴露的名称是：

- mcp__wechat__wechat_doctor
- mcp__wechat__wechat_status
- mcp__wechat__wechat_sync
- mcp__wechat__wechat_verify

随附的安全 overlay 设置 WECHAT_ARCHIVE_ALLOW_SYNC=0。所以安装之后只能
进行只读诊断和状态查看，不会同步。所有实机安全门都通过后，操作者仍需明确把服务端开关设为
1、重启 MCP 进程，并在调用 wechat_sync 时传入 confirm=true。

卸载同样默认 dry-run：

python3 scripts/uninstall_dsh.py
python3 scripts/uninstall_dsh.py --uninstall

可选的周期同步

定时采集会直接调用确定性 core，不依赖浏览器标签页、语言模型或正在运行的 Harness 对话。
下面的命令只渲染并检查一个每天 03:15 执行的 LaunchAgent，不会安装它：

REVIEW_DIR="${TMPDIR:-/tmp}/wechat-archive-review"
REVIEW_PLIST="${REVIEW_DIR}/local.wechat-archive.sync.plist"
mkdir -p "$REVIEW_DIR"

python3 scripts/render_launchagent.py \
--project-root "$PROJECT_DIR" \
--python "$PROJECT_DIR/.venv/bin/python" \
--config "$CONFIG_PATH" \
--hour 3 --minute 15 \
--sync-timeout-seconds 1800 \
--verify-timeout-seconds 7200 \
--output "$REVIEW_PLIST"
plutil -lint "$REVIEW_PLIST"
python3 scripts/install_launchagent.py --plist "$REVIEW_PLIST"

最后一条命令仍然只是 dry-run。只有下面这个明确动作才会安装并 bootstrap 任务：

python3 scripts/install_launchagent.py --plist "$REVIEW_PLIST" --install

在 doctor 返回 READY，并且人工确认的 sync 后紧接 verify 成功之前，不应安装它。
每次定时运行会先同步、再做完整校验。如果 WeChat 正在使用或 WAL 非空，本次运行会安全退出，
并可以在下一次调度时重试。

同步和完整校验分别使用独立的有界超时：默认 30 分钟和 2 小时，最高可配置到 8 小时。
完整校验会读取全部历史媒体对象，因此应根据归档体量选择校验超时。

校验与发布检查

仓库测试全部使用合成 fixture，请勿替换为真实聊天数据。

.venv/bin/python -m pytest -q
pnpm --dir mcp-server test
python3 scripts/check_manifest.py --scan-content
python3 scripts/build_release.py \
--output "${TMPDIR:-/tmp}/wechat-archive-0.1.0.tar.gz"

进程退出码为零并不足以证明真实归档成功。验收条件是 SYNCED 或 NO_CHANGE，随后立即得到
VERIFIED，且数据源覆盖符合预期。完整门禁见验收标准。

许可证与第三方工作

项目代码采用 MIT License。经过审计或参考的上游项目及其许可证列在
THIRD_PARTY_NOTICES.md 中。真实聊天、数据库、密钥、媒体、日志、
本地配置和历史 handoff 压缩包永远不属于发布物。