微信群关键词台账
把微信群里的固定内容按关键词抓取成 Excel 台账。全程本地运行：截屏 + 离线 OCR 识别，不上传任何数据，不读取微信进程内存，不解密本地数据库。
适用于需要把群里每天发的固定内容（如各平台发布情况、进度报送、问题反馈）沉淀成台账的岗位。
何时使用
用户提出以下需求时使用本技能：
- 「把微信群里的发布贴文整理成台账」
- 「XX群的消息导出成表」
- 「群里发的内容按关键词提取到 Excel」
- 「每天自动记一下群里的发布内容」
- 「把群里的记录整理成台账」
不适用以下需求，不要误用：
- 导出微信群全部聊天记录做备份（本技能按关键词筛选，不做全量导出）
- 往群里发送消息或通知（本技能只读，绝不发送）
- 读取或解密微信本地数据库（本技能不做，也不建议做）
第一步：环境检查
任何抓取之前先跑自检。不要跳过这一步直接执行。
python scripts/wechat_ledger.py check --emit-probe-results probe-results.json
python scripts/check_environment.py --probe-results probe-results.json
按输出状态路由：
| 状态 | 处理 |
|---|---|
| ready | 跳过全部配置说明，直接进入下一步 |
| partial | 继续可用流程，只说明受影响功能与降级范围 |
| needs_setup | 只展示缺失项的配置步骤，完成后重新检查 |
| unavailable | 说明故障原因与恢复步骤，或按降级执行 |
配置齐全时不要重复讲解安装步骤。缺失项的完整指引见 @references/setup-guide.md。
四项依赖：Windows 10/11、Python 3.10+、三个 Python 包（Pillow / openpyxl / rapidocr_onnxruntime）、微信 Windows 版已登录。
第二步：首次配置
1. 生成配置并填写群与关键词
python scripts/wechat_ledger.py init
打开生成的 config.json，在 群组 里填写群名与关键词。每个群各出一份台账。
字段含义与写法建议见 @references/config-guide.md。
关键词要点：写群里实际出现的原话，不要写规范说法。实测中群里写「发布帖文」而需求写「发布贴文」，差一个字，严格匹配会全部漏掉。
2. 标定窗口分区
python scripts/wechat_ledger.py calibrate
执行前确认微信已登录、保持打开、且打开着任意一个会话。
执行后打开 calibration/calibration_check.png，确认三个框都框对了。
细节见 @references/calibration.md。
3. 先干跑验证关键词
python scripts/wechat_ledger.py run --dry-run
看输出里「解析去重」与「关键词命中」两个数字：
- 解析去重为 0：取值或识别有问题，回去检查标定。
- 解析正常但命中为 0：关键词没写对，调整关键词后重跑。
- 命中明显偏多：收窄关键词或加排除词。
确认无误后再去掉 --dry-run 正式运行。
第三步：日常运行
python scripts/wechat_ledger.py run
程序会自动完成：唤醒微信 → 切到目标群 → 滚到最新消息 → 逐屏截屏 → 本地 OCR → 结构化为发言人/时间/正文 → 关键词筛选 → 增量写入台账 → 写日志 → 还原窗口状态与光标位置。
要定时执行，就把上面这条命令交给计划任务，安排在用户不使用电脑的时段：运行时微信会被置前、鼠标会被占用（滚动必须把光标停在消息区）。
第四步：回溯历史
python scripts/wechat_ledger.py run --since 2025-10-09
--since 指定回溯截止日期，扫到更早的消息即停。跑完会自动把台账重排为时间线并按时间线重编序号。
先读日志里的「滚到底: 到达=」。为 False 说明扫描起点不在最新消息处，会漏掉起点之后的一段历史，需要重跑。 这一点务必核对。
微信 PC 端只保存有限的本地历史。滚到最前端会报「连续 2 屏画面完全未动」，属正常结束。要更早的历史，需先在手机端做聊天记录迁移，见 @references/troubleshooting.md。
输出
台账默认落在工作目录 output/<群名>_台账.xlsx。结构固定为 6 列机器列 + 1 列人工列：
| 列 | 归属 | 说明 |
|---|---|---|
| 序号 | 机器 | L-0001 形式，稳定编号，不随排序变化 |
| 命中关键词 | 机器 | 多个用「、」连接 |
| 消息时间 | 机器 | YYYY-MM-DD HH:MM，取自微信的时间分隔条 |
| 发言人 | 机器 | 群昵称 |
| 消息内容 | 机器 | 正文全文，自动换行 |
| 消息指纹 | 机器 | 灰色小字，用于判重 |
| 相关链接 | 人工 | 脚本永不写入 |
表头灰底为机器列、黄底为人工列。冻结首行、自动筛选、按消息时间升序；写入前自动备份，保留最近若干份。
真实内容示例（已脱敏处理过的字段用方括号标注）：
L-0006 | 发布贴文 | 2026-09-30 15:24 | 某报社编辑 | 0930集团号脸书、推特、优兔发布帖文：
| | | | 近日，中国石化携手新加坡社区共度佳节。猜灯谜、手作灯笼、
| | | | 书法体验等丰富活动吸引邻里参与…（共 15 行）
同时产出：
raw/<时间戳>.json：本次解析出的全部消息与命中清单，用于溯源。backup/：台账自动备份。logs/run_<时间戳>.log：本次运行的逐屏明细与结论。calibration/calibration_check.png：标定验证图。
质量自查清单
每次运行后核对：
- [ ] 日志里「滚到底: 到达=True」
- [ ] 日志里没有
[失败]行 - [ ] 「关键词命中」条数与预期量级相符（明显偏少多为关键词写法问题）
- [ ] 台账新增条数与日志里的「新增=」一致
- [ ] 抽查一两条记录，发言人、时间、正文都对得上原消息
- [ ] 人工列（相关链接）在增量运行后仍原样保留
边界与停止条件
绝不执行：发送、删除、修改任何聊天内容；读取微信进程内存；解密或直读本地数据库；把任何数据传出本机。
必须停止的情况：
- 微信无法登录，或电脑持续处于锁屏状态：停止本次抓取，写日志，不重试性破坏动作。
- 未能切到目标群：停止该群的抓取，不抓取任何内容，避免抓到别的群。
- 自动标定未探到分区（结果标为
fallback）：先人工确认验证图，确认前不要正式运行。 - 累计删除或覆盖类操作涉及人工列：立即停止，人工列的值与链接不允许被程序改写。
已知限制（如实告知用户，不要掩饰）：
- 时间精度受微信限制：同一时间段落内多条消息共享分隔条时间，精确到分钟。
- 以图片形式发布、且无配套文字的内容，只能取到图内 OCR 文字，可能不完整。
- 依赖微信 PC 端本地缓存的深度，回溯未必能覆盖到期望的起始日期。
排障
按现象查 @references/troubleshooting.md。想逐屏复核时加 --keep-shots。
改动识别逻辑或标定参数前，先读 @references/implementation-notes.md，里面是实测得出的阈值与六个必须避开的坑。
