wechat-decrypt-toolkit/docs/SYNC_INSTANCES.md

sync_instances.py 使用文档

功能：WeChat 多实例自动发现 + wxid 解析 + keys 同步 位置：wechat-decrypt-toolkit/sync_instances.py

---

快速开始

# 查看所有实例状态
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 模式

[
  {
    "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 扫描器导出密钥

---

自动导出示例

# 启动时自动检查并导出（一次性）
python3 sync_instances.py --export

# 输出：
# [85121] → wxid_0368623686311  开始导出密钥...
# [85121] ✅ 导出完成，共 24 个密钥

---

退出码

退出码	含义
0	正常执行（无论是否有实例）
1	指定 --wxid 但未找到对应运行实例

---

常见问题

Q: lsof 超时/卡住

A: 检查是否有 WeChat 进程处于 T（Stopped/Traced）状态：

ps aux | grep WeChat | grep -v grep | awk '{print $2, $8}'

若发现 T 状态，先恢复：

kill -CONT <PID>

get_wechat_pids() 会自动过滤 T 状态进程。

Q: 所有实例都显示 ?（未登录?）

A: lsof 在 grep -m1 时可能找到错误的 wxid（其他进程的路径）。检查实际路径：

lsof -c WeChat 2>/dev/null | grep 'wxid_'

Q: 想只刷新某个 wxid 的 keys

python3 sync_instances.py --wxid wxid_0368623686311 --export --force

---

Python API

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': [...]}