wechat-cli-skill — 微信聊天记录读取与群消息总结
0. 流程导航（先判断场景，再进入对应流程）
| 场景 | 进入 |
|---|---|
| 首次使用 / wechat-cli 不可用 | 流程A → 完成后接流程B |
| 密钥缺失 / 查询报错 / 微信更新或换号后 | 流程B |
| 用户要查看、导出聊天记录 | 流程C |
| 环境搭建（A+B）首次完成 | 流程D 初始化引导（必须执行一次） |
| 用户要总结群消息 / 定时任务触发 | 流程E（前置：A、B 已完成） |
通用约定：SKILL_DIR=本 skill 目录；VENV=~/.wechat-cli/venv；Windows 解释器 <VENV>/Scripts/python.exe、可执行文件 <VENV>/Scripts/wechat-cli.exe，macOS 为 <VENV>/bin/python、<VENV>/bin/wechat-cli。命令完整参数见 references/commands.md。
禁止事项（Do NOT）
- 禁止
pip install wechat-cli——PyPI 无此包，必然失败，只能用scripts/install_wechat_cli.py - 禁止修改 wechat-cli CLI 本体——适配一律通过 skill 附带脚本
- 禁止为非登录账号伪造或猜测密钥——密钥只属于当前登录账号，其余账号仅限用已存密钥校验
- 密钥校验直接用派生后密钥，禁止走 PBKDF2 派生路线（4.1.12+ blob 中已是派生结果）
- 禁止把聊天数据、密钥上传到任何外部服务
- 禁止对微信 3.x 做兼容承诺（进程名与数据结构均不同）
- 禁止静默代装 Python 等系统级软件——引导用户自行安装
- 报告默认只存本机；外发给联系人前必须先经用户确认
流程A：环境搭建
任务与实现
1. 检测 Python：python --version，要求 ≥ 3.10。缺失 → 引导用户自行安装（winget 或官网），不静默代装，装好后重走本步。
2. 检测 CLI：wechat-cli --version 有版本输出 → 本流程结束。
3. 自动安装（PyPI 无此包，禁用 pip install wechat-cli）：
bash
python -m venv ~/.wechat-cli/venv
python "<SKILL_DIR>/scripts/install_wechat_cli.py" --python "<VENV>/Scripts/python.exe"
安装器经 jsDelivr 从 3 个开源 fork（xmx0632 / huohuoer / kenchikuliu）重建源码安装；首次安装时告知用户来源。
4. 复验：wechat-cli --version 输出版本号（当前 0.2.4）。
输入
- 用户需提供：无（仅 Python 缺失时配合装 Python）。
- 自动获取：Python 版本、CLI 安装状态。
输出
- 内容：可用的 wechat-cli 命令。
- 格式：wechat-cli --version 正常输出版本号。完成 → 接流程B。
流程B：账号检测与密钥提取
任务与实现
1. 检测微信运行：Windows tasklist /FI "IMAGENAME eq Weixin.exe"（Git Bash 转义 //FI；Weixin.exe=4.0+ ✅，WeChat.exe=3.x ❌）；macOS pgrep -x WeChat。未运行 → 引导用户：「请打开微信并登录，登录好了告诉我」，用户确认后继续。
2. 定位数据目录（配置反推，不猜路径）：
- Windows：读 %APPDATA%\Tencent\xwechat\config\*.ini 的文件内容 = 数据根路径 → <根>/xwechat_files/<wxid>/db_storage
- macOS：~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage
枚举 xwechat_files 下全部 wxid_* 目录，得候选账号列表。
3. 检测当前登录账号（自动判定，无需用户指认）：
- 候选排序：按 db_storage 内数据库文件修改时间降序（活跃账号在持续写入，mtime 最新）。
- 逐个验证：对候选账号目录执行第 4 步提取，输出 matched N/N（N>0）者即当前登录账号——内存中的密钥只会命中登录账号的数据库盐值。
- 全部 0 命中 → 询问用户当前登录账号并确认微信在线，稍后重试；仍失败查排错决策树。
4. 提取密钥（分版本路线）：
- Windows 4.0.x：wechat-cli init
- Windows 4.1.12+：python "<SKILL_DIR>/scripts/extract_keys.py" --db-dir "<db_storage>" --out ~/.wechat-cli/all_keys.json
（原理：dump Weixin.exe 内存中 Cipher blob → XOR 循环 mask 解码 → hex 密钥直接 HMAC 校验。派生后密钥直接校验，勿走 PBKDF2。已实测 24/24 库。）
- macOS 4.0.x~4.1.8：先重签名（见 references/troubleshooting.md）→ sudo wechat-cli init
- macOS 4.1.12+：未实测，如实告知用户暂不支持。
5. 写配置：echo '{"db_dir": "<db_storage>"}' > ~/.wechat-cli/config.json
6. 验证链路：wechat-cli sessions --limit 8 --format text 能列出会话即通。
输入
- 用户需提供：无（账号自动判定）；仅自动判定失败时询问「当前登录的是哪个账号」。
- 自动获取：微信进程、数据目录、账号列表、密钥。
输出
- 内容：解密后的数据库密钥与配置。
- 格式：matched N/N 提取结果 + ~/.wechat-cli/config.json、all_keys.json（格式见「运行时状态」节）+ sessions 会话列表。首次执行成功 → 接流程D。
- 自愈：微信更新/重装/换号导致查询报错时，重跑本流程即可，无需重装 CLI。
流程C：读取消息
任务与实现
1. 模糊找群/找人：wechat-cli contacts --query "关键词" --limit 10 --format json；系统占位会话（brandsessionholder、@placeholder_foldgroup）无实际消息，忽略。
2. 按时间段读消息：wechat-cli history "精确群名" --start-time "YYYY-MM-DD 00:00:00" [--end-time "..."] --limit 2000 --format json
3. 补充数据：members "群名" --format json（成员）、stats "群名" --format json（活跃统计）、search "关键词" --chat "群名" --format json（--limit ≤500，翻页用 --offset）。
4. 导出：wechat-cli export "群名" --limit 100000 --format markdown --output out.md。
5. 输出重定向到文件再解析，避免终端中文乱码。
输入
- 用户需提供：群名（模糊名即可，用 contacts 校正为精确名后向用户复述确认）；时间段（未给则默认今天）。
- 自动获取：消息 JSON、成员、统计。
输出
- 内容：指定群、指定时间段的全部消息（中间产物）或导出文件。
- 格式：JSON（供后续流程解析）或 Markdown 导出文件（用户直接要文件时）。
流程D：初始化引导（环境搭建完成后必须执行一次）
环境就绪后，按顺序与用户确认以下三件事，对话式逐项进行：
引导1 · 账号登录确认
- 复述流程B的自动检测结果：「当前登录账号 wxid_xxx ✅ 微信在线。」请用户确认。
- 未登录/离线 → 引导用户登录后重跑流程B。
引导2 · 初始配置（逐项询问并记录）
1. 「需要我每天帮你总结群消息日报吗？」（是/否）
2. 「总结哪些群？直接把群名发给我即可，不用打全名，我来匹配。」→ contacts 校正为精确群名，向用户复述确认。
3. 「报告给谁 / 放哪里？」→ 默认本机生成单文件 HTML 并打开预览；可指定其他目录，或（宿主具备发送能力时）发给指定联系人。
引导3 · 自动化任务
- 询问：「要不要设定时自动总结？」
- 若要：借助宿主的定时任务能力（如 WorkBuddy 自动化）创建定时任务，逐项确认入参——精确群名、统计时间段（如"每天总结前一天全天"）、触发时间（如每天 21:00）、报告输出位置。未来运行看不到本次对话，以上入参必须原样写进定时任务的提示词。
- 若宿主无定时能力 → 告知用户每天手动说一句即可。
输入
- 用户需提供：是否要日报、群名列表、报告去向、是否自动化及其入参。
输出
- 内容：初始化配置确认清单（账号 ✅ / 日报开关 / 群名列表 / 报告去向 / 自动化有无及入参）；必要时已创建的定时任务。
流程E：群消息总结
任务与实现
1. 前置检查：wechat-cli sessions 可用（不可用先重跑流程B）。
2. 用流程C读取目标群、目标时间段全部消息（JSON）。
3. 内容归纳（产出前先在内部完成，规则如下）：
- 话题归组：把消息按讨论主题归为 2-5 个话题。每话题提炼四件套：标题（格式「话题N：主题词」，主题词是编辑过的概括，不是原话）、参与人（mono 行，按发言量降序，如「张三 16条 · 李四 3条」）、观点脉络（每人一条「谁 + 短句」，关键判断带 ≤15 字原话短引）、状态结论（四选一：已确认 / 待评审 / 已落地 / 信息补充）。
- 总结：3-5 条分点短句（每条 ≤25 字），首条 = 最重要事件。
- 后续行动：从消息中提取任务/承诺/被指派事项，按负责人分组（同人多项只写一次名字），每条带截止（无截止标「未定」）；@某人未回复、认领后无下文也要入列。
- AI 建议：0-3 条，每条指向具体的人和事，标注「非群内决议」，不与群内事实混排。
4. 生成报告（模板填充，禁止自由发挥样式）：
- 复制 <SKILL_DIR>/assets/digest-template.html，替换全部 {{占位符}}，按各区块内注释增删内容块（话题块/行动组复制样例块，空区块整卡删除）。
- 硬约束：禁止修改模板的样式与脚本区（脚本通用自适应，无需改动）；禁止 emoji、额外配色；{{DIGEST_KEY}} 必须替换为「群名+日期」唯一串（浏览器据此本地记忆行动项勾选状态）；导航条 chip 与内容块一一对应（每个话题一个 chip，无行动/建议块时删对应 chip）；状态 pill 语义固定——已确认=p-green / 待评审=p-amber / 已落地=p-blue / 信息补充=p-gray；人名色点六色轮换（d-blue/d-amber/d-green/d-violet/d-slate/d-cyan），同一人全报告同色；模板为移动端优先（390px 基准），不得"优化"成宽栏。
- 结构（极光皮肤：浅底紫粉青光晕 + 毛玻璃卡 + 渐变标题字）：头部卡（eyebrow+群名渐变字+统计圆，待办=hl 渐变实底）→ 总结块（POINT_1=紫描边高亮块 hlb，POINT_2..5=绿序号列表）→ 话题块 ×N（sec-tag 数字 + h2「话题N：」+ 副题=参与人行）→ 后续行动 → AI 建议（S 编号自动生成）；"状态总览"独立卡已取消，状态只在话题块 pill 上呈现。
- 文件名：群聊总结-{群名}-{YYYYMMDD}.html（跨天用起止日期，如 -20260930-20261001.html）。
- 保存到流程D约定的位置，打开预览交付。
5. 多群/多天：逐群逐段各出一份报告；用户明确要求合并时才合并。
输入
- 用户需提供：群名 + 时间段 + 输出要求（来自用户当次指令、流程D配置或定时任务入参）。
输出
- 内容：用户可读的群消息总结报告。
- 格式：默认单文件 HTML（按 assets/digest-template.html 填充）；用户指定其他格式时从其要求。消息分析工作流详见 references/analysis-guide.md。
端到端示例（新电脑首次使用）
用户说：「帮我总结"嗨啤时刻公司群"今天的消息」——按流程导航依次执行：
- 流程A：
wechat-cli --version报命令不存在 → 建 venv → 运行install_wechat_cli.py --python <venv python>→ 复验输出wechat-cli, version 0.2.4 - 流程B：
-tasklist /FI "IMAGENAME eq Weixin.exe"→ Weixin.exe 运行中 ✅
- 读%APPDATA%\Tencent\xwechat\config\xxxx.ini内容得数据根D:\files\weixin→ 枚举出 2 个候选账号wxid_aaa、wxid_bbb
- 按 db 修改时间降序先试 wxid_bbb：extract_keys.py --db-dir .../wxid_bbb/db_storage→matched 24/24✅ 登录账号判定完成
- 写config.json→sessions --limit 8列出会话，链路通 - 流程C：
contacts --query "嗨啤"→ 精确群名「嗨啤时刻公司群」；history "嗨啤时刻公司群" --start-time "<今天> 00:00:00" --limit 2000 --format json > msgs.json→ 13 条消息 - 流程D（首次搭建完成）：确认账号 → 询问日报需求并记录群名、报告去向 → 询问是否设定时任务
- 流程E：话题归组+归纳 → 复制
assets/digest-template.html填充生成群聊总结-嗨啤时刻公司群-<日期>.html→ 打开预览交付
全程用户只需做两件事：保持微信登录、回答流程D的配置问题。
排错决策树（症状 → 原因 → 动作）
| 症状 | 原因 | 动作 |
|---|---|---|
pip install wechat-cli 报 404 |
PyPI 无此包 | 改用 scripts/install_wechat_cli.py（流程A第3步） |
wechat-cli init 提取 0 命中 |
微信 4.1+ 不再缓存明文密钥（正常现象） | 改用 scripts/extract_keys.py（流程B第4步） |
| extract_keys.py ImportError | 依赖脚本不在同目录 | 确认 wcdb_key_tool_windows.py 与之同目录（skill 已捆绑） |
| blobs 有几百个但 matched 0 | ① 目标目录不是登录账号；② 版本超出已适配 XOR 结构 | ① 重跑流程B自动判定；② 如实告知暂不支持 |
| matched 部分库（如 20/24） | 个别库新建，内存尚无密钥 | 重启微信并打开几次聊天后重跑；缺库通常不影响读消息 |
sessions 报错/为空 |
db_dir 与密钥不属同一账号 | 重跑流程B并重写配置（见「运行时状态」绑定关系） |
| contacts/history 找不到群 | 群名不匹配 / 群太旧 | contacts --query 模糊找，用返回精确名 |
| history 中文乱码 | 终端编码 | 输出重定向到文件，用 --format json |
| jsDelivr 全部仓库不可达 | 网络/CDN 故障 | 检查网络；或人工下载仓库 zip 解压后 pip install <目录> |
运行时状态与配置（~/.wechat-cli/，skill 目录之外）
| 文件 | 格式 | 作用 |
|---|---|---|
config.json |
{"db_dir": "<当前账号db_storage绝对路径>"} |
CLI 读取的数据目录指向 |
all_keys.json |
{"<库相对路径>": {"enc_key": "<64位hex>", "salt": "<32位hex>", "size_mb": n}} |
各库解密密钥 |
venv/ |
Python 虚拟环境 | CLI 及依赖安装位置 |
last_check.json |
new-messages 断点状态 |
增量消息（可删除重置） |
绑定关系：config.json 的 db_dir ↔ all_keys.json 的密钥 ↔ 微信当前登录账号，三者一致 sessions 才有数据。skill 目录改名/迁移不影响本目录。
隐私与合规
- 仅读取用户本人已登录账号的本机数据；密钥提取需扫描微信进程内存，仅限此用途。
- 密钥与聊天数据均存本机
~/.wechat-cli/，零外送；本 skill 无任何上传/遥测逻辑。 - 提醒用户：总结报告含聊天内容，外发前自行斟酌。
文件清单
wechat-cli-skill/
├── SKILL.md # 本文档（流程编排）
├── assets/
│ └── digest-template.html # 群聊总结报告模板（移动端优先，流程E填充用）
├── references/
│ ├── commands.md # 11 个命令完整参数手册
│ ├── analysis-guide.md # 消息分析工作流
│ └── troubleshooting.md # 排错手册（版本/重签名/查询/权限）
└── scripts/
├── install_wechat_cli.py # 跨平台 CLI 安装器（jsDelivr 方案，标准库实现）
├── extract_keys.py # Windows 4.1.12+ 密钥提取（XOR 修复，已实测）
└── wcdb_key_tool_windows.py # extract_keys.py 的依赖（校验/XOR 工具函数）
