---

name: wechat-chat-ocr description: | 把微信聊天截图还原成结构化对话（不是纯文本提取）。OCR 保留文字 bounding box → 估计气泡 → 检测左右头像 → 只用同一水平带附近的头像判定发言人，专治"左右气泡 speaker 判断错误"；头像失败再 fallback 到气泡贴边位置。输出 Markdown + JSON，低置信度项保留 confidence/reason，不硬判；OCR 后端失败或 0 行时输出 ocr_failed 交给人工/视觉模型。 Use whenever the user provides WeChat / 微信 chat screenshots (one or many) and wants：把聊天截图转成文字/对话、还原聊天记录、判断每句话是谁说的、区分"我"和"对方"、左右气泡分不清、把截图整理成 Markdown/JSON、who said what。触发词例：「微信聊天截图转文字」「把这几张截图整理成对话」「这句话是谁说的」「左右气泡老是判错」「screenshot to chat / wechat ocr / who said this」。 仅针对微信聊天截图布局（左对方 / 右我 / 居中系统）；非聊天类截图、文档扫描、通用 OCR 不适用。

wechat-chat-ocr

微信截图 OCR 的难点不在认字，在认人——短消息、连续同侧、头像稀疏时，"这句是我说的还是对方说的"经常判错。本 skill 用"同一水平带内的头像"作为主信号、气泡贴边位置作 fallback，来稳住 speaker 判断。

何时触发

用户给出一张或多张微信聊天截图，想要：转成文字、还原成对话、判断谁说的、区分我/对方、把截图整理成 Markdown/JSON。

用法

脚本在 scripts/wechat_ocr.py：

python scripts/wechat_ocr.py input_screenshots/ --out outputs/chat.json --markdown outputs/chat.md
# 单张：
python scripts/wechat_ocr.py one.png --out outputs/chat.json
# 指定后端 / "我"在左：
python scripts/wechat_ocr.py imgs/ --backend easyocr --me-side left --markdown outputs/chat.md

• 目录输入时按文件名排序拼接（聊天会跨截图延续，截图命名建议带序号）。
• 先装一个 OCR 后端（vision / easyocr / paddleocr / tesseract），见 references/ocr-backends.md。脚本 --backend auto 会自动挑可用的；Vision 底层失败或某后端读出 0 行时会继续试下一个后端。Codex 受限沙箱里 macOS Vision 可能返回 performRequests_error_ returned False without NSError detail；这不是图片质量问题，优先申请/改用沙箱外运行，或装 easyocr/paddleocr/tesseract。

处理流水线

1. 读图，拿到宽高 W、H。
2. OCR（必须保留 bounding box） → 文本行 {text, box=(x0,y0,x1,y1), conf}。
3. 气泡聚类：按垂直间距 + 同侧把相邻文本行合并成气泡（合并同一气泡的多行文本）。
4. 头像候选检测（纯 numpy）：在最左 / 最右边栏里找"彩色、方形"的图块 → {box, side, conf}。
5. 就近匹配：每个气泡只看 y 范围（±容差）内的头像，不做全局头像判断。
6. 判定 speaker（见下）。
7. 头像失败 → fallback 到气泡贴边位置。
8. OCR 失败/0 行：输出一条 speaker: "ocr_failed"、type: "ocr_failed" 的消息，reason 写明每个后端失败或 0 行原因；workflow 应转人工或让带视觉的模型直接看原图。
9. 图片/表情：消息区里有纹理的大块（扁平气泡不算 → 不会误报）标成 〔图片〕/〔表情〕 占位，按贴边定 speaker。只有 OCR 读出文字时才做该步，避免空 OCR 后把整张图误报成图片/表情。
10. 输出 JSON + Markdown；低置信度保留 confidence + reason。

占位符只给粗类型。具体是什么（柴犬照片 / 狗头表情）由运行时带视觉的模型看原图命名——脚本本身不做语义识别。

speaker 判定规则

按优先级：

1. 气泡 y 范围附近只有左侧头像 → other（--me-side right 时）。
2. 气泡 y 范围附近只有右侧头像 → me。
3. 居中、灰字、且附近无头像 → system（时间戳 / "撤回了一条消息" / 日期等）。
4. 头像缺失 → fallback：看气泡贴哪边——贴左边 → other、贴右边 → me；都不贴、居中且窄 → system；再不确定 → 低置信兜底。
5. 居中/两侧信号冲突/无法判定 → unknown（绝不硬判）。

--me-side 控制"我"在哪侧（微信默认 right；左右镜像时改 left，me/other 会跟着翻转）。

输出格式

JSON（--out）：

{
  "source_images": ["01.png", "02.png"],
  "backend": "vision",
  "me_side": "right",
  "count": 12,
  "messages": [
    {
      "index": 0,
      "speaker": "other",          // other | me | system | unknown | ocr_failed
      "text": "在吗",
      "confidence": 0.92,
      "reason": "附近左侧头像",
      "avatar_side": "left",        // left | right | null(头像未命中)
      "ocr_confidence": 0.97,
      "bbox": [44, 210, 320, 250],
      "image": "01.png"
    }
  ]
}

OCR 全部失败或只返回 0 行时，每张图输出一条 ocr_failed 消息：

{
  "speaker": "ocr_failed",
  "type": "ocr_failed",
  "text": "⚠️ OCR 失败：这张图没读出可用聊天文字。请换 OCR 后端，或让带视觉的模型直接看原图。",
  "reason": "vision: RuntimeError: Vision OCR request failed: ...；easyocr: ModuleNotFoundError: ..."
}

若 reason 里出现 Vision OCR request failed: performRequests_error_ returned False without NSError detail，按 Codex/受限沙箱问题处理：不要判断截图不可读；优先在普通终端/沙箱外重跑 --backend vision，没有权限时再用其它 OCR 后端或视觉模型直接读图。

Markdown（--markdown）：**对方：** … / **我：** … / *— 系统提示 —*；置信度 < 0.75 的行尾追加 _(conf 0.66 · 原因)_，让人一眼看到哪些是估的。

低置信度原则

• 不确定就给 unknown 或降低 confidence，并在 reason 写清楚为什么（无头像 / 居中 / OCR 置信度低 / 信号冲突）。
• OCR 后端失败或全后端 0 行时给 ocr_failed，不要继续用头像/图片检测伪造聊天消息。
• Vision 返回 performRequests_error_ returned False without NSError detail 时，视作运行环境/沙箱限制优先，不要归咎于截图内容。
• OCR 行置信度 < 0.4 时，连带下调该消息 confidence 并在 reason 标注。
• 宁可标"不确定"，不要假装确定——这正是这个 skill 存在的意义。