微信截图整理 · 快照OCR + LLM协作版（低TOKEN）

把微信聊天截图变成可检索的「群/人/消息」知识库。不联网、不连微信、不自动截图。

与旧版「全 LLM 版」相比，本版把日常整理收进一个独立本地桌面工具（本地 OCR，截图不进 WorkBuddy 聊天 → 0 token），WorkBuddy 只保留建档这一处视觉出场（每群一次）。这样既保住识别率下限，又彻底解决了"粘贴即扣 prefill"的问题。

> 最常见误区：以为日常整理也要在 WorkBuddy 里粘贴截图。错——日常全在本地小工具里完成（0 token）；只有"新群建档"才来 WorkBuddy 用视觉。

两种角色 / 两出场

关键：截图走工具的"捕获/添加文件"，绝不粘贴进 WorkBuddy 聊天。图不进 LLM 上下文，prefill 成本归零。

★ EXE 与 WorkBuddy 的通讯通道（双向闭环，必须理解）

两端不联网、不直接调用，唯一的"通讯"是一个固定在用户家目录的小文本文件：

~\.wechat_archive_db.txt   ← 存「最近一次使用的持久库绝对路径」

• EXE 端（tool/tool_config.py）：用户首次选/建库时，把库路径写进这个文件（remember_workdir）。
• WorkBuddy 端（scripts/workdir_resolver.py）：建档 / 入库脚本现在自动读这个文件决定 workdir；用完还会把实际用掉的库写回（双向记忆）。

> 所以不再有"建档文件跑错文件夹"的漏洞：无论用户「先开 EXE 再建档」还是「先建档再开 EXE」，两端永远锁同一个目录。建档时不必手动传 --workdir 也能落对库（代码会自动从记忆文件解析）；若显式传了则以显式为准。
>
> 唯一前提：建档前 EXE 至少成功开过一次（写过记忆文件）。若用户第一次就直接拿截图来 WorkBuddy 建档（还没开过 EXE），记忆文件可能不存在 → 技能必须询问用户库目录（或新建一个），并把路径写进 ~/.wechat_archive_db.txt（直接 python -c "import sys;sys.path.insert(0,'scripts');from workdir_resolver import remember_workdir;remember_workdir(r'库路径')" 即可），之后 EXE 打开就会自动用同一个库。

> ★ 握手信号 .wb_link（v2 新增，反向通道）：~/.wechat_archive_db.txt 只解决「EXE 知道库在哪、WB 能找到库」，但不表示 WB 当前已连接。v2 增加反向握手：当运行本技能的 AGENT 解析到/创建好持久库后，立刻往该库写入一个标记文件 <持久库>/.wb_link。该 JSON 必须含 agent 字段（即真正执行握手的 Agent 名，如 "WorkBuddy" / "Hermes" / "Claude Cowork"），EXE 据此显示绿灯「与 <agent> 已握手」/红灯「未连接」——纯文件检测、零网络，亮灯只代表「该 AGENT 没忘记这个 EXE」，不做实时心跳。界面 agent 名统一参数化（2026-08-20 用户定）：EXE 里所有 WorkBuddy/LLM/AGENT 文案均从 .wb_link 的 agent 字段取真实名（如 TRAE 环境下显示 TRAE）；获取失败才统一兜底 "agent"（不再回退 WorkBuddy）。建档与 LLM 推导回写这两条必须握手成功才放行；整理已建档老群只靠本地 OCR，红灯也能用。
> - 默认库目录：生成 EXE 时，技能应把默认库目录写进本文档/记忆，使 WB 天生知道 EXE 的库（参见下方「第三步」）。
> - 自定义目录：若用户特地要求把库建在新目录，WB 处理该要求时必须把新地址写进记忆（同 ~/.wechat_archive_db.txt 机制），方便后续握手找到。

第一步：建持久库（Phase 1）

持久库是用户自选的稳定目录（如 ~/Documents/WeChatArchive/），不放 WorkBuddy 临时目录。里面存 groups.jsonl / people.jsonl / messages.jsonl 与 outputs/（每群一份 <群名>.xlsx + group_coverage.xlsx 跨群概览），以及 inbox/ pending_archive/ roster_review/ notes/。

• 老用户（你既是开发者又是老用户）：旧版全 LLM 已攒的群/人/消息直接当种子，迁移进持久库即可。
• 新用户：小工具（EXE）已由开发者预编译，装好技能即可直接运行，不存在「先生成工具」这一步。首次启动 EXE 会引导你选一个持久位置并初始化空库（工具要靠库判群建档）→ 回 WorkBuddy 视觉建档第一个群 → 再回 EXE 整理。

小工具启动时会：① 检测记忆/默认路径的库在不在；② 不在则弹窗让你选目录并初始化。库路径记在 ~/.wechat_archive_db.txt，下次自动复用。

第二步：建档（Phase 2，WorkBuddy 视觉出场①）

建档的正确交接（v2 设计，重要！）：截图绝不直接贴到 WorkBuddy 聊天（那会产生 prefill 成本、且不构成 v2 流程）。用户在 EXE 建档页用区域截图/粘贴/添加把「群成员面板截图」放进 <持久库>/roster_review/_draft/（草稿区），点「下一步（提交建档）」后 EXE 把它搬到 <持久库>/roster_review/（建档交接区顶层）并弹窗提示「去 AGENT 输入『建档』」。用户回来说"建档 [群名]"：
1. 技能自动从 <持久库>/roster_review/（建档交接区顶层，剔除 _draft/_archived）读取提交的截图（无需用户贴图；图仍留在库里、不进 WB 上下文），用一次视觉读全成员（头像特征 + 规范名），写 <持久库>/roster_llm.json；
2. 跑 python scripts/ocr_pipeline.py <成员截图> --roster（--workdir 可省略，脚本自动从 ~/.wechat_archive_db.txt 解析）→ 直写 groups.jsonl + people.jsonl；
3. （可选）问用户：客户方公司 / 我方公司 / 群目的——建档阶段暂不强制，留空由下游 SKILL 结合知识库/组织图填写（见下方职责边界）。

> ★ 建档双验证（2026-08-19 用户策略：重要处多仔细）：build_roster 在采用视觉 LLM（roster_llm.json）名单时，会自动对同一张成员面板截图跑本地 OCR 交叉校验：
> - OCR 文本行按名字分隔符（.．、· 等）拆成单名候选，与视觉 short_name 逐一比对（包含/相等，剥离尾部省略号占位）；
> - 找不到包含 → 找「形近感知编辑距离≤1」的近似（2026-08-19 升级：只有形近字差异如「股↔服」才算 OCR 变体；「孔↔服」字形差异大按距离 2 计、不算冲突——见 scripts/confusable.py），消费机制避免误配到已匹配的近似名；
> - 不一致 → 按等级处理（2026-08-19 用户策略：股/服类形近歧义 ≠ 强制人工）：
> - 低危·待定（候选只与本人视觉名形近、不与其他成员形近）：name_pending=true + ocr_candidate（OCR 读到的版本），needs_manual_completion 保持 false——不强制人工，后续聊天里出现全名时自动确定（见「待定人员自动确定」，AGENT 端整理回写时执行）；
> - 高危·强制（候选与本群其他成员名字也形近，可能抢名字）：needs_manual_completion=true + ocr_candidate，建档完成面板列出「视觉=X / OCR=Y，且与成员 Z 形近，必须人工」；
> - OCR 漏读的成员不误报（保持视觉为主源）。
>
> ★ 待定人员自动确定（2026-08-19 用户策略：聊天全名到了就定，不用人工）：name_pending=true 的成员（如「示例股…」vs OCR「示例服」），在整理回写（AGENT 端）时，若聊天记录里出现完整全名（含「股」或「服」），AGENT 用形近感知匹配唯一命中该人 → 自动确定：
> - canonical_name ← 聊天全名（如「示例服」）、name_pending 清 false、needs_manual_completion 清 false、补 aliases[wechat_name]（带 resolved_from_pending: true）、merge_log 记 auto_resolve_pending（可逆）；
> - 触发条件：聊天名长于建档短名 / 等于 ocr_candidate、且 ≤12 字防整句误并；只对仍处 pending 状态的人生效（已确定的不会反复改）；
> - ★ 端侧归属（2026-08-19 澄清·用户纠正）：这步天然在 AGENT 端，不改 EXE、不重打包。理由：① 识别层（speaker_raw）由布局解析器按区域忠实提取，从不查花名册；② 归属层（person_id）由 EXE 端本地确定性算法兜底（文字→头像描述→头像哈希三层，见 ingest），EXE 自己就能把「示例服」归到 P007（头像哈希大概率命中）；③ AGENT 端独有的只是「名字精化」——从「示例股…」定到「示例服」需要后续聊天全名作证据，EXE 没有任何依据做这个二选一。故自动确定 = 建档的延续，归 AGENT 端整理回写时执行。
>
> ★ 交接区自动归档（2026-08-19）：build_roster 建档成功后，会把建档交接区 roster_review/ 顶层的该成员面板图自动移到 roster_review/_archived/<群名>/——交接区只留"待建档"图，已建档的图不会在下次建档时被重复视觉读取，也不会越积越多。_draft/（草稿区）与 _archived/ 内的图天然不被建档流程读取。

> ★ 架构红线：建档必须由视觉 LLM 完成，OCR 只能兜底（build_roster 三级优先级：roster_llm.json → llm_notes → OCR 兜底）。反过来（OCR 当主）会漏整列成员，且 LLM 永远见不到漏的人。

> ★ 建档职责边界（2026-08-16 切割）：建档只负责「准确记录谁在这个群里」，不做我方/对方判定，不做跨群合并。我方识别、跨群认人、公司簇归类等「全维度组织分析」全部交给下游独立 SKILL（结合公司知识库 / 组织结构图 / 客户名单）。理由：建档是高频步骤，必须快准狠；重分析拆出去才能各司其职。
> - ① 同群内幂等：同一 group_key + 同一 short_name → 同一 person_id，保证重复建档不产生重复 ID。
> - ② 跨群默认完全拆开：不同群的同名 / 近似名一律各自独立 person_id，绝不跨群合并。宁可重复 ID，不并错——将来要做跨群认人，交给下游 SKILL（告诉它「这两人是同一人」后合并很轻）。
> - our_side 字段与 AUTO_CROSS_GROUP_MERGE 常量已从 build_roster 移除；下游 SKILL 可据 people.jsonl 的 aliases[].group_key 自行判定我方 / 跨群关系。
> - 我方识别已闭环（2026-08-19 补记）：右侧(自己)消息由建档强制收集的 my_nickname 直接渲染（见「Excel 消息表·发言人渲染约定」），建档阶段无需再做 our_side 判定。
> - 跨群认人 / 公司簇归类 = 唯一负责方是人工或下游 SKILL：本工具绝不自动跨群合并（沿「宁可重复 ID，不并错」）。要做时：在 notes/needs_review.md 登记「P01 与 P07 是同一人」→ 由执行方把被并人 merged_into 设为保留人 person_id、active=false（字段已有，撤回/合并见 references/FAQ.md Q5/Q6）。若要扩展公司维度，people.jsonl 每人可加 company（所属公司/客户方）/ tags（标签数组）/ merge_from（来源 person_id 列表）字段，字段契约见 references/schema.md。
> - 详细名单见 <持久库>/notes/company_team.md（含示例厂服务/技术团队 9 人 + 已知客户公司）。
> - 空白昵称头像（微信允许昵称为空）：用 [空白] 占位建档，并在 avatar_note 写明网格坐标便于人查。
> - ★ 人工介入三类（视觉 LLM 建档硬要求，v2 新增）：
> - 全符号名（无字、纯图标/emoji）：short_name 写 [全符号·X行Y列]（坐标从 1 起），avatar_note 写头像/名字开关描述，needs_manual_completion=true。永不跨群合并（不同群网格结构不同，宁可拆开也不并错）。
> - 短位名（≤1 字含 emoji）：只输出提醒，不强制拆开——只要群内不重复，不影响后续 OCR 聊天记录里特征辨识。
> - 近似重名（群内两两 编辑距离≤1 或 长度差≤1 且前 2 字相同）：合并到同人后剩下的近似配对，列出供人工用头像/消息特征二次辨识。
> - roster_llm.json member 字段扩展（v2）：除原有 short_name / canonical_name / avatar_note，可携带 position: {row, col}（网格坐标1起）/ needs_manual_completion: true|false / name_pending / name_length_warning / ocr_candidate / ocr_candidates；build_roster 会透传到 groups.jsonl snapshot member 和 people.jsonl person 字段，不会丢。注意（2026-08-19）：name_pending（形近待定）与 needs_manual_completion（强制人工）互斥——ROSTER_VERIFY 只会置其一；重跑建档时以本次快照为准直接覆盖，避免旧标记残留（如上一轮 needs_manual=true、本轮降级为 name_pending 时旧 true 必须清掉）。

> 注意：建档结果必须落在小工具用的同一个持久库。现在 ocr_pipeline.py 会自动读 ~/.wechat_archive_db.txt 定位该库（无需手动传 --workdir）；建档完还会把库路径写回该文件，保证 EXE 下次打开用同一个目录。若记忆文件缺失，技能应询问用户库目录并先用 remember_workdir 写入（见上方「通讯通道」）。

第三步 + 日常：本地小工具（Phase 3 / 4）

运行：python tool/archive_gui.py（开发）或 dist/WeChatArchiveTool.exe（打包，见 tool/build_exe.py）。

★ v2 信息架构（欢迎页 / 建档页 / 清爽整理页 / 预览确认 / 生成完成）

工具改为「先选群再整理」的四屏流程，去掉了原「自动/聊天图/成员图」标注下拉（选完群后图片天然是聊天截图）。

欢迎页（首页）
- 顶部握手灯：<持久库>/.wb_link 文件存在 = 绿灯（显示「与 <agent> 已握手」，agent 取自 .wb_link 的 agent 字段；获取失败兜底显示 agent），否则红灯。纯文件检测，零网络。
- 使用指南（5 步，含 AGENT 握手）+ 两入口按钮：未建档 / 已建档（已建档按钮第 2 行动态显示「点击查看群清单」/「点击关闭群清单」）。
- 未建档 → 建档页；已建档 → 右侧「群清单」浮层（同一按钮 toggle 开关）选群 → 清爽整理页。
- 红灯时仍能整理已建档老群（本地 OCR），但建档 / LLM 推导需先到 WorkBuddy 建立连接（点未建档会提示先去连接）。

建档页（未建档入口）
- 把「群成员面板截图」用 区域截图 / 粘贴 / 添加 放进 roster_review/_draft/（草稿区，支持多张分页）；截图先落草稿，不会自动建档，重启可恢复。
- 勾选要提交的截图 → 点 「下一步（提交建档）」：OCR 校验是否成员面板（不像会询问仍要提交？）→ 搬进 roster_review/（建档交接区）→ 弹窗提示「已提交，去 AGENT 输入『建档』」。
- 去 WorkBuddy 说「建档」；建完回本页点 「刷新建档状态」：发现新群即显示「✅ 建档成功：群名」并启用 「进入整理（刚建档的群）」 直达该群清爽整理页（底部「建档状态」区，不含群清单——群清单是首页的活）。
- 一次只建一个群；若误投了别的群成员图，WB 侧会让你二选一先建哪个。

清爽整理页（已建档群）
- 顶栏：群名 + 成员概要（人数 + 前几位成员）+【回到首页】。
- 区域截图 / 粘贴截图 / 添加文件 把聊天截图加入队列（三种方式均不立即识别，先预览）。
- 勾选后点「识别选中」 → 本地 OCR 预筛：已知群入库（0 token）/ 未知群入 pending_archive/ / 成员面板图入 roster_review/。
- 误粘/截错：勾选后「丢弃选中」。打开工具自动把 inbox/ 残留图列进队列，确认后才识别。
- 点「生成中转区(待LLM)」 → 预览确认面板（改最早/最晚识别日期、OCR 逐行、零散备注）→ 生成 llm_inbox/batch_*.json → 去 WorkBuddy 让 LLM 推导回写 → Excel 双列（准确/推断日期时间）。回写 + Excel 生成后，该批次自动归档到 llm_inbox/_done/（中转区顶层清空，积压清单消失）；回到「中转区已生成」页点「刷新状态」即可确认批次已消费，无需手动进文件夹。

> 区域截图（替代原全屏截图）：点「区域截图」后工具最小化，屏幕出现半透明遮罩，鼠标拖框选范围即截该区域，松开恢复工具并加入队列。不再截整个桌面，也不需要用户会 Win+Shift+S。

工具的 OCR 预筛路由（本地免费）

• 裁顶部 ~15% 取群名 → 去 (N) → 模糊匹配 groups.jsonl 键（≥0.85 已知 / 0.6–0.85 歧义问用户 / <0.6 未知入队）；
• detect_mode 判 roster/chat（锚词：搜索群成员 / 群聊名称 / 我在本群的昵称…）。v2 已去掉手动「聊天图/成员图」标注下拉：群在进整理页前已选定，故聊天截图均走自动聊天判定；成员面板图在建档页单独收集进 roster_review/。

建档硬性校验（v 本次新增）

• 每个群 groups.jsonl 必须含：非空 group_key（群名） 与 非空 my_nickname（我在本群的昵称）。
• my_nickname 由成员面板截图「我在本群的昵称」字段 OCR 提取（ocr_pipeline）。若提取为空，建档完成面板须单列「必须补齐」项提示用户补真名，不可带空入库——否则右侧(自己)消息在 Excel 无法归到「我方」。
• 群名同理：group_key 为空视为建档失败，须回 EXE 重截成员面板。

Excel 消息表·发言人渲染约定（v 本次新增·不改结构）

• 右侧(自己)消息（side=="right"，绿泡右对齐）：发言人直接填 groups.jsonl 的 my_nickname（我在本群的昵称），不新增「方向 / 我方·对方」列。
• 左侧 / 居中(别人 / 系统)消息：沿用 OCR 名 → 人员匹配（person_name）；系统事件（system_tip，如「X 加入群聊」「X 撤回了一条消息」）发言人显示「（系统）」。
• 设计取舍：用「我在本群的昵称」直接标识我方，比新增方向列更简单；因群建档已强制收集该昵称，故可行。下游 ingest.py 须把解析器的 side 透传进 messages.jsonl（否则 Excel 读不到左右）。

大模型端（WorkBuddy）交互协议 ——「程序面板」风格

> 目标：即使用自然语言聊天，也要让用户感到这是「KING 微信群整理程序」的大模型端在干活，而不是一段普通闲聊。凡是涉及与本 EXE / 本 skill 对接的功能（握手、建档、识别中转区、回写、状态查询），都用下方「程序面板框」包裹输出，与常规对话区分开，营造"命令行程序在汇报状态"的延续感——EXE 那边是桌面面板，WB 这边是文本面板，两端一个程序两种形态。

何时使用面板框

• 报告握手（.wb_link）状态时；
• 建档（roster_review → groups.jsonl / people.jsonl）成功/失败时；
• 识别中转区（batch_*.json 生成 / LLM 推导回写）成功/失败时；
• 查询/确认归档库、skill 地址、EXE 位置等元信息时；
• 任何"程序在推进状态"的汇报节点。
• 正常的提问 / 澄清 / 引导仍用普通文字，不塞进框里——框只承载"程序状态汇报"，避免把对话也框进去导致反而更乱。

面板框格式（Unicode 横线/竖线组成的小框）

┌──────────────────────────────────────────────────────┐
│  KING 微信群整理程序 —— 大模型端                                │
├──────────────────────────────────────────────────────┤
│  握手状态 : 已连接                                          │
│  归档库   : ~/Documents/WeChatArchive/...               │
│  Skill    : ~/.workbuddy/skills/                     │
│  wechat-snap-ocr-llm-cowork-king                     │
│  EXE      : ...\dist\WeChatArchiveTool.exe           │
│  建档成果 : 示例客户群（32 人）已写入 groups.jsonl                  │
│  识别     : batch_20260814_xxxx.json 已生成 / 已推导回写       │
└──────────────────────────────────────────────────────┘

字段约定

• 标题行固定：KING 微信群整理程序 —— 大模型端；
• 握手状态：已连接（.wb_link 存在）/ 未连接；红灯情形下顶部标红提示「先去 EXE 握手 / 去 WorkBuddy 建立连接」；
• 归档库：库目录绝对路径；
• Skill 地址：本 skill 文件夹绝对路径；
• EXE 位置：dist/WeChatArchiveTool.exe 绝对路径；
• 建档成果：群名 + 人数 + 落地文件；
• 识别：batch 文件名 + 状态（已生成 / 已推导回写 N 条）；
• 缺失字段写 — 或 未获取，不臆造路径。

字段约定·人工介入清单（建档时三类·v2 新增）

建档汇报框后，可附加三类独立成段的人工介入清单（不是表格，是「! / ? / ??」三段文本，序号清晰，便于用户按序号复制真实名字）。build_roster 会把提醒打印到 stdout，agent 端读取后转成下面格式：

! 全符号名字难以建档，影响OCR，请人工补齐如下人员：
  1 第1行第2列，头像是天空大地，像是海边，名字开关好像是一个列车加星星
  2 第X行第Y列，头像是……

? 短位名（≤1字）请人工确认辨识（不影响 OCR跨群追踪）：
  1 第3行第4列，短名：[王]
  2 ……

?? 近似重名（高度相似）请人工用头像/消息特征二次辨识：
  1 第2行第1列，[王晓]  与  第5行第3列，[王晓晓]
  2 ……

三类可各自成段，但序号必须全局连续（从 1 起跨段递增、不每段重置），确保用户说「补序号 N」能唯一对应到某一项；截断名不属三类，不进入序号序列（仅透明列出供校验，不编号）。

范围红线（v2 明确，勿扩展）：三类之外一律不问。尤其「截断名」（微信 UI 把完整昵称截短显示成 王建军…/Shado… 这类带省略号、但本身有字且超 1 字）不属三类，不得塞进 !/?/??，也不得向用户追问——只把「可见真实前缀 + 头像描述」存进 people.jsonl 的 roster_short_name/avatar_note 即可；将来若两个前缀相同造成歧义，自然落进 ?? 再问。agent 不得自行新增第 4 类「待问」去扩大打扰面（曾犯：把 10 个截断名当待补项列出，被批"连问都多余"）。
>
> ★ 截断名的归人策略（2026-08-19 用户定案：文字优先，哈希仅兜底）：
> - 截断名不设 avatar_only_identity=true（那字段只给真·无文字昵称：全符号/空白/纯 emoji）。截断名有文字核心（如「王建军」「示例股」），聊天 OCR 出现全名时靠文字匹配归人——ingest.find_person_by_alias 已支持：完全相等 → 前缀包含 → 编辑距离≤1（OCR 变体如「示例服↔示例股」），候选唯一才自动选，群内近似名并存时不猜（防误并）。
> - 建档完成面板/对截断名的提示不得写「按头像哈希归人」（曾误导为哈希优先）；应写「截断名靠文字匹配归人，哈希仅兜底/LLM 怀疑时辅助」。
> - 哈希只用于真·avatar_only（无文字头像）的兜底，以及文字匹配歧义/失败时的辅助。

字段约定·建档完成面板（v2 新增·收尾）

! / ? / ?? 三类清单回答完毕、用户补齐后，agent 必须用「建档完成」面板收尾，不要直接聊完就走。此面板是流程闭环的最后一步——告诉用户"建档结束了，EXE 这边的活干完了，请回 EXE 截具体内容"，避免用户困惑下一步。

┌──────────────────────────────────────────────────────┐
│  KING 微信群整理程序 —— 大模型端                                │
│  建档完成 · <群名>                                         │
├──────────────────────────────────────────────────────┤
│  群成员 : <N> 人（全员就位，<K> 项面板已归 0）                       │
│  待补齐 : —（无 ! / ? / ?? 未决项）                           │
│                                                      │
│  ★ 头像哈希已就位（avatar_only_identity）                     │
│  <Pxxx> <昵称/特征>  <头像描述>                              │
│  → 聊天 OCR 端按 dHash 兜底归人                              │
│  （列本群所有 avatar_only_identity=true 的人，                │
│  这就是"特别标识给 EXE"——后续聊天 OCR 不读昵称文字、                    │
│  也能精准对号入座）                                           │
│                                                      │
│  ▷ 下一步                                               │
│  回到 EXE → 截聊天内容                                      │
│  （区域截图/粘贴 进「整理」队列）                                   │
│  读到 <头像特征> 时自动按头像哈希归到 <Pxxx>                         │
└──────────────────────────────────────────────────────┘

约定：
- 只要某群建档完成（含所有 needs_manual_completion 已归 0）就必须出此面板，不可省略；否则用户不知下一步回 EXE 干嘛，流程断了。
- "★ 头像哈希已就位"段只列 avatar_only_identity=true 的人（真·无文字昵称：全符号/空白/纯 emoji，needs_manual_completion）；截断名（有文字核心）与 name_pending（形近待定）不列此段——它们靠文字匹配（见上方「截断名的归人策略」/「待定人员自动确定」）。字段由 scripts/avatar_match.py build_hashes_for_group 写入。
- "▷ 下一步"必须明确告诉用户「回 EXE 截聊天内容」；对真·无文字头像提示"读到该头像特征时自动按头像哈希归人"；对截断名提示"聊天出现全名时按文字自动归人"；对 name_pending 待定的人提示"聊天出现 股/服 等全名时自动确定，无需人工"。
- 本群无 avatar_only_identity 的人时，"★ 头像哈希已就位"段写 —（本群无无文字专用头像），不要省略本段。

完整示例（建档成功）

┌──────────────────────────────────────────────────────┐
│  KING 微信群整理程序 —— 大模型端                                │
├──────────────────────────────────────────────────────┤
│  握手状态 : 已连接                                          │
│  归档库   : ~/Documents/WeChatArchive                   │
│  Skill    : ~/.workbuddy/skills/                     │
│  wechat-snap-ocr-llm-cowork-king                     │
│  EXE      : ~/.workbuddy/skills/                     │
│  wechat-snap-ocr-llm-cowork-king\dist\WeChatArchiveTo│
│  建档成果 : 示例客户群（28 人）已写入 groups.jsonl /                │
│  people.jsonl；回写 .wb_link 握手信号                       │
└──────────────────────────────────────────────────────┘

建档完成，请回 EXE 点「刷新建档状态」即可见该群，进入清爽整理页开始截图整理。

完整示例（识别中转区回写）

┌──────────────────────────────────────────────────────┐
│  KING 微信群整理程序 —— 大模型端                                │
├──────────────────────────────────────────────────────┤
│  握手状态 : 已连接                                          │
│  归档库   : ~/Documents/WeChatArchive                   │
│  识别     : batch_20260814_181809_001.json             │
│  → 推导回写 4/4 条；accurate_ts 已纠正                        │
│  → 批次回写后归档到 llm_inbox/_done/（顶层清空）                   │
│  下一步   : 回 EXE 重新生成 Excel，查看「准确/推断」双列                │
└──────────────────────────────────────────────────────┘

首页 / 帮助面板（新用户首次自动出现 · /help 召回）

除上面"状态汇报"用法外，WB 端还有一张首页 / 帮助面板：新装 skill 或新生成一版 EXE（=新用户）时默认出现一次；用户任何时候输入 /help 怎么用 ? 帮助 使用方法 说明书 也回到本页。面板按当前握手状态切换两个变体，只放终端用户要看的内容，不夹带设计理由。

变体 A —— 未连接（初始态）

┌──────────────────────────────────────────────────────────────┐
│  KING 微信群整理程序 —— 大模型端                                        │
├──────────────────────────────────────────────────────────────┤
│  握手状态 : 未连接（初始状态）                                            │
│  归档库   : —（打开 EXE 选/建库后显示）                                   │
│  EXE      : …\dist\WeChatArchiveTool.exe                     │
│  Skill    : ~/.workbuddy/skills/                             │
│  wechat-snap-ocr-llm-cowork-king                             │
├──────────────────────────────────────────────────────────────┤
│  ■ 这是什么                                                      │
│  日常截图整理在本地 EXE 完成（0 token）；建档、推导回写由我                         │
│  （WorkBuddy）完成。两端仅用本地文件通讯，不联网。                               │
├──────────────────────────────────────────────────────────────┤
│  ■ 第一次使用（只需完成握手）                                             │
│  1. 打开上面的 EXE，选或新建一个「持久库」目录                                  │
│  2. 在本对话框输入「握手 / 建立握手 / 开始握手 / 尝试握手」                         │
│  → 我自动从记忆文件检测库位置，写入 .wb_link 握手信号                            │
│  → 若检测不到库，会请你从 EXE 复制库地址粘贴过来                                 │
│  完成后，确认上方「握手状态」已变为「已连接」✓                                     │
├──────────────────────────────────────────────────────────────┤
│  ■ 新群建档（仅新群时需要）                                              │
│  EXE 建档页提交「成员面板截图」（→ roster_review/）→                        │
│  回来说「建档」（图不贴给 WB）                                            │
│  → 我从建档交接区读图、视觉识别成员，写入                                       │
│  groups.jsonl / people.jsonl                                 │
│  （建档是独立步骤；建完 EXE「刷新建档状态」可见）                                  │
├──────────────────────────────────────────────────────────────┤
│  ■ 日常整理（已建档老群 · 全在 EXE）                                      │
│  EXE 里区域截图→识别选中→生成中转区 → 把 batch_*.json 发我                    │
│  → 我按方向感知外推(正序/倒序+锚点日期)推导回写                                  │
│  → 回写后批次归档到 _done/，你回 EXE 点「刷新状态」确认                          │
│  → 重生成 Excel 看「准确/推断」双列                                      │
├──────────────────────────────────────────────────────────────┤
│  ■ 常用指令（任何时间输入）                                              │
│  /help  怎么用  ?  帮助  → 回到本页                                   │
│  握手 / 建立握手            → 建立 WB↔EXE 连接                         │
│  建档 <群名>               → 视觉建档（附群成员面板截图）                      │
│  整理 / 识别中转区         → 发我 batch_*.json，推导回写                   │
│  握手状态 / 连接状态        → 查当前灯                                   │
│  库在哪 / 换库              → 查或改持久库目录                            │
│  群清单                     → 列出已建档群                            │
├──────────────────────────────────────────────────────────────┤
│  ⚠ 日常聊天截图请走 EXE，不要粘贴进 WB（否则产生 token 消耗）                      │
│  授权声明：CC BY-NC 4.0（署名-非商业），详见 LICENSE。                           │
│                                                              │
└──────────────────────────────────────────────────────────────┘

变体 B —— 已连接（同一样式，第一次使用打勾"已完成"）

┌──────────────────────────────────────────────────────────────┐
│  KING 微信群整理程序 —— 大模型端                                        │
├──────────────────────────────────────────────────────────────┤
│  握手状态 : 已连接 ✓                                                │
│  归档库   : ~/Documents/WeChatArchive                           │
│  EXE      : …\dist\WeChatArchiveTool.exe                     │
│  Skill    : ~/.workbuddy/skills/                             │
│  wechat-snap-ocr-llm-cowork-king                             │
├──────────────────────────────────────────────────────────────┤
│  ■ 这是什么（同变体 A）                                               │
├──────────────────────────────────────────────────────────────┤
│  ■ 第一次使用（已完成 ✓）                                              │
│  ✓ 1. 已打开 EXE 并选/建持久库                                        │
│  ✓ 2. 已握手（.wb_link 已写入，上方灯为「已连接」）                            │
├──────────────────────────────────────────────────────────────┤
│  ■ 新群建档（仅新群时需要）                                              │
│  EXE 建档页提交「成员面板截图」（→ roster_review/）→                        │
│  回来说「建档」（图不贴给 WB）                                            │
│  → 我从建档交接区读图、视觉识别成员，写入                                       │
│  groups.jsonl / people.jsonl                                 │
│  （建档是独立步骤；建完 EXE「刷新建档状态」可见）                                  │
├──────────────────────────────────────────────────────────────┤
│  ■ 日常整理 / ■ 常用指令（同变体 A）                                      │
└──────────────────────────────────────────────────────────────┘

自动出现一次 / 召回规则

• 自动出现（新用户）：用「版本标记 + .wb_link 是否存在」双判定——<持久库>/.wb_link 不存在一定弹变体 A；存在但 skill 本地记录的已见版本低于当前 EXE 版本也弹（覆盖"开发者重打包新 EXE"场景）。弹过即在 skill 本地记 seen_home_v<版本>。
• 随时召回：/help 怎么用 ? 帮助 使用方法 说明书 任一命中 → 按当前握手状态弹变体 A 或 B。
• 面板内"位置"三行：未连接时归档库显示 —，EXE/Skill 写死默认路径。

> 上方首页面板与前面两个状态示例（建档/识别），就是未来"WB 端"对 EXE 的正式回报形态：用户无论在 EXE 还是 WB，看到的都是同一套 KING 整理程序，只是面板一图形一文。

工作流（命令参考）

# 建档（WorkBuddy 侧）：--workdir 可省略，脚本自动读 ~/.wechat_archive_db.txt 定位 EXE 的库
python scripts/ocr_pipeline.py <成员截图> --roster [--workdir <持久库>] --capture-date 2026-07-27
# ★ 运行环境：AGENT 端 OCR 用的是 scripts/ocr/rapidocr_backend.py 本地封装（非 PyPI rapidocr 包），
#   任意能相对导入 ocr 包的 python 即可（实测 envs/default/Scripts/python.exe 可跑通 ROSTER_VERIFY），
#   不必因 "import rapidocr 缺失" 去换 venv 或重打包 EXE。详见"关键设计点 1"。

# 工具内部对已知群聊天图的入库（工具自动调，无需手敲）
python scripts/ocr_pipeline.py <聊天图> [--workdir <持久库>] --group-key <群名> --capture-date <日期>
python scripts/run_all.py [--workdir <持久库>]

# 若记忆文件缺失，建档前先把库路径写进去（EXE 之后会自动用同一目录）
python -c "import sys;sys.path.insert(0,'scripts');from workdir_resolver import remember_workdir;remember_workdir(r'库路径')"

# 打包小工具为 exe
python tool/build_exe.py

Token 政策（修正说明）

> 历史版本曾写"消息截图 0 token"未加前提；本版因截图不走 WorkBuddy 聊天，才真正字面 0 token。若有人把截图直接粘贴进 WorkBuddy 聊天，模型仍会付 prefill——所以日常务必用本地小工具。

核心架构原则

高能力模型产出指导低能力 OCR，绝不反过来。 建档（难、要准）用视觉；日常提取（简单、量大）用 OCR。详见第二步红线。

文件结构

wechat-snap-ocr-llm-cowork-king/
├── SKILL.md
├── ocr_config.json
├── scripts/                 ← 复用，不重写 OCR
│   ├── ocr/                 ← OCR 后端（AGENT 端用本地封装，非 PyPI 包；详见"关键设计点 1"）
│   ├── wechat_layout_parser.py
│   ├── ocr_pipeline.py      ← 建档 + 聊天处理 CLI（--workdir 可选，自动读记忆文件）
│   ├── workdir_resolver.py  ← EXE↔WorkBuddy 共享的库路径解析/记忆（唯一的通讯通道）
│   ├── ingest.py / build_outputs.py / build_coverage.py / run_all.py
│   └── manual_media.py
├── tool/                    ← 本地桌面小工具（新）
│   ├── tool_config.py       ← 持久库定位/选择/初始化
│   ├── ingest_router.py     ← OCR 预筛路由 + 入库 + 待建档队列
│   ├── archive_gui.py       ← Tkinter 界面
│   └── build_exe.py         ← PyInstaller 打包
├── references/
│   ├── schema.md            ← 字段 + 持久库布局
│   ├── core_reference.md / FAQ.md / memory_rules.md
└── （持久库，用户自选目录，不在本仓库内）
    ├── groups.jsonl / people.jsonl / messages.jsonl
    ├── .wb_link               ← 握手信号（AGENT 连接后写入；含 agent 字段；EXE 据此显示「与 <agent> 已握手」绿灯）
    ├── outputs/              ← 每群一份 <群名>.xlsx（消息表+群信息表）+ group_coverage.xlsx 跨群概览
    ├── inbox/ pending_archive/ roster_review/ notes/
    └── tool_config.json

参考文档导航（按需查阅）

关键设计点

1. OCR 引擎可换（ocr_config.json）：默认 rapidocr。★ AGENT 端 OCR 不依赖 PyPI rapidocr 包（重要·2026-08-20 实证）：AGENT 侧跑 ocr_pipeline.py --roster 时，get_backend() 走的是 scripts/ocr/rapidocr_backend.py 这个本地相对导入封装（不是 pip install rapidocr 那个 PyPI 包）。因此——
   - venv 里 import rapidocr 报 ModuleNotFoundError 是正常的、不影响运行，无需去各 venv 逐个试装 / 重装；ROSTER_VERIFY 交叉校验能照常跑通（[OCR] engine=rapidocr 会打印，校验 N 人：一致 X，可疑 Y）。
   - 即便真的缺后端包，_verify_roster_with_ocr 有 try/except 兜底跳过，视觉名单仍是主源，建档主流程不中断。
   - 运行环境：用哪个 python 跑都行（只要脚本目录在 sys.path 能相对导入 ocr 包）；实测 envs/default/Scripts/python.exe 即可跑通。别因为"没装 rapidocr"就纠结要不要换 venv 或重打包 EXE——那是两码事。
2. 版面解析：Y 聚类 + X 对齐 + 时间戳 + 发言人匹配。
3. 建档走视觉 LLM（不绕过）：avatar_note 是后续"按头像绑定人物"基础。
4. 建档路径直写库（groups/people），因 ingest 只在处理 messages 时建 person。
5. 短名/全名双字段：roster_short_name + canonical_name；无冲突静默补全 / 冲突强制人工。
6. 双面板图（聊天+成员同屏）只用于建档，不用于聊天入库：实测 ocr_pipeline 在双面板图上把整屏当文本流，聊天 OCR 解析全空、还会误建无关人员。聊天入库务必用纯聊天截图（不带右栏成员面板），经本地工具 0 token 入库。详见 notes/needs_review.md。
7. 媒体消息：标 file/image/video + 占位 + 进 manual_media.md。
8. LLM 兜底：低置信消息入 llm_refine_queue.json（仍在 WorkBuddy 侧消费）。
9. 集中待处理清单：notes/needs_review.md。
10. 静默汇报 vs 阻塞询问分级。

触发规则（Prologue，两出场）

• 出场① 首次/设置：用户问"怎么用/怎么整理"或加载技能首次使用时，先问"本地小工具在不在"。
• 不在 → 引导 Phase1 选持久库（老用户迁移种子/新用户建空库）+ Phase2 至少在 WorkBuddy 视觉建档第一个群（EXE 已预编译就绪，无需「生成工具」）。
• 在 → 直接进入日常（提醒用户去小工具操作，不是在 WorkBuddy 粘贴截图）。
• 出场② 按需建档：用户在 EXE 建档页提交「成员面板截图」（落到 <持久库>/roster_review/ 建档交接区），回来说"建档" → 技能自动从建档交接区读图 → 视觉读 → 写 <持久库>/roster_llm.json → 跑 python scripts/ocr_pipeline.py <成员截图> --roster（--workdir 自动从 ~/.wechat_archive_db.txt 解析）。截图绝不贴到 WorkBuddy 聊天。
• /help 首页：/help 怎么用 ? 帮助 使用方法 说明书 任一命中 → 输出「首页/帮助面板」（见上方大模型端协议章节），按握手状态给变体 A（未连接）/ B（已连接）。
• 日常整理不在 WorkBuddy：若用户直接在 WorkBuddy 粘贴聊天截图，应提醒"请改用本地小工具，否则图会进 LLM 上下文产生 token 消耗"。