docs: 新增 sync_instances.py 使用文档

- docs/SYNC_INSTANCES.md: 完整使用文档（含命令行参数、输出示例、工作流程、FAQ、Python API）
- README.md: 在 CLI 子命令后添加 sync_instances.py 推荐入口

README.md

@@ -59,6 +59,18 @@ python cli.py serve \
 | `serve` | 启动 HTTP 服务（多实例 namespaced） |
 | `launch` | 一键启动（旧版兼容） |
 
+## 多实例自动同步（推荐）
+
+`sync_instances.py` — 一键发现所有 WeChat 实例、自动解析 wxid、智能同步 keys：
+
+```bash
+python3 sync_instances.py               # 查看状态
+python3 sync_instances.py --export     # 自动导出缺失 keys
+python3 sync_instances.py --watch      # 持续监控，新实例自动处理
+```
+
+详细文档：[docs/SYNC_INSTANCES.md](docs/SYNC_INSTANCES.md)
+
 ## HTTP API（多实例 namespaced）
 
 ```bash

docs/SYNC_INSTANCES.md

@@ -0,0 +1,194 @@
+# sync_instances.py 使用文档
+
+> **功能**：WeChat 多实例自动发现 + wxid 解析 + keys 同步
+> **位置**：`wechat-decrypt-toolkit/sync_instances.py`
+
+---
+
+## 快速开始
+
+```bash
+# 查看所有实例状态
+python3 sync_instances.py
+
+# 自动导出缺失 keys
+python3 sync_instances.py --export
+
+# JSON 输出（供脚本调用）
+python3 sync_instances.py --json
+```
+
+---
+
+## 依赖
+
+- Python 3.10+
+- 系统工具：`pgrep`、`lsof`（macOS）、`ps`（macOS）
+- 同一仓库：`wechat_db/` 模块
+- 扫描器：`bin/find_all_keys_macos`（C 编译二进制）
+
+无需 frida，无需注入，无需关闭 SIP。
+
+---
+
+## 命令行参数
+
+| 参数 | 说明 |
+|------|------|
+| 无参数 | 扫描所有 WeChat 实例，显示 PID、wxid、keys 状态 |
+| `--export` | 为缺失 keys 的实例自动执行导出 |
+| `-f, --force` | 强制重新导出（覆盖已有 .keys 文件） |
+| `--watch` | 持续监控模式，新实例出现时自动导出 |
+| `--interval N` | watch 模式检测间隔（秒，默认 10） |
+| `--wxid <id>` | 只处理指定 wxid 的实例 |
+| `--json` | JSON 格式输出，适合脚本集成 |
+
+---
+
+## 输出示例
+
+### 默认模式（人类可读）
+
+```
+   PID  wxid                             keys  状态
+--------------------------------------------------------------
+ 85121  wxid_0368623686311                 24  ✅ keys 已就绪 (24 个密钥)
+--------------------------------------------------------------
+共 1 个实例， 1 已就绪， 0 待导出
+```
+
+### 缺失 keys
+
+```
+   PID  wxid                             keys  状态
+--------------------------------------------------------------
+ 85121  wxid_0368623686311                  0  ❌ keys 缺失
+--------------------------------------------------------------
+共 1 个实例， 0 已就绪， 1 待导出
+```
+
+### watch 模式
+
+```
+🔄 监控模式启动（间隔 10s）
+    Ctrl+C 退出
+
+[15:32:01] 🆕 新实例发现: {85121}
+[85121] → wxid_0368623686311  开始导出密钥...
+[85121] ✅ 导出完成，共 24 个密钥
+[15:33:45] 🔻 实例退出: {85121}
+^C
+👋 监控已停止
+```
+
+### JSON 模式
+
+```json
+[
+  {
+    "pid": 85121,
+    "wxid": "wxid_0368623686311",
+    "wxid_raw": "wxid_0368623686311",
+    "has_keys": true,
+    "key_count": 24,
+    "scanner_bin": ".../bin/find_all_keys_macos"
+  }
+]
+```
+
+---
+
+## 工作流程
+
+```
+1. pgrep -x WeChat        → 获取所有 WeChat PID 列表
+2. ps -o state            → 过滤 Stopped(T) 状态进程（lsof 会阻塞）
+3. lsof -c WeChat + grep  → 零开销获取 PID → wxid 映射
+   （SIGPIPE trick：grep -m1 让 lsof 0.05s 内退出）
+4. ~/.wechat-decrypt-toolkit/keys/{wxid}.keys
+                        → 检查 keys 缓存是否存在
+5. 若缺失 + --export      → 调用 C 扫描器导出密钥
+```
+
+---
+
+## 自动导出示例
+
+```bash
+# 启动时自动检查并导出（一次性）
+python3 sync_instances.py --export
+
+# 输出：
+# [85121] → wxid_0368623686311  开始导出密钥...
+# [85121] ✅ 导出完成，共 24 个密钥
+```
+
+---
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 正常执行（无论是否有实例） |
+| 1 | 指定 `--wxid` 但未找到对应运行实例 |
+
+---
+
+## 常见问题
+
+### Q: lsof 超时/卡住
+
+A: 检查是否有 WeChat 进程处于 `T`（Stopped/Traced）状态：
+
+```bash
+ps aux | grep WeChat | grep -v grep | awk '{print $2, $8}'
+```
+
+若发现 `T` 状态，先恢复：
+
+```bash
+kill -CONT <PID>
+```
+
+`get_wechat_pids()` 会自动过滤 T 状态进程。
+
+### Q: 所有实例都显示 `?（未登录?）`
+
+A: lsof 在 `grep -m1` 时可能找到错误的 wxid（其他进程的路径）。检查实际路径：
+
+```bash
+lsof -c WeChat 2>/dev/null | grep 'wxid_'
+```
+
+### Q: 想只刷新某个 wxid 的 keys
+
+```bash
+python3 sync_instances.py --wxid wxid_0368623686311 --export --force
+```
+
+---
+
+## Python API
+
+```python
+from sync_instances import (
+    discover_instances,
+    export_instance,
+    export_all_missing,
+    WeChatInstance,
+)
+
+# 发现所有实例
+instances = discover_instances()
+for inst in instances:
+    print(f"PID={inst.pid}, wxid={inst.wxid}, has_keys={inst.has_keys}")
+
+# 导出指定实例
+inst = instances[0]
+export_instance(inst, force=False)
+
+# 导出所有缺失的
+results = export_all_missing(force=False)
+print(results)
+# {'exported': [...], 'skipped': [...], 'failed': [...]}
+```