wechat-chat-ocr

---
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`：

```bash
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`）：

```json
{
  "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` 消息：

```json
{
  "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 存在的意义。

• SKILL.md 6 KB
• references/ocr-backends.md 2 KB
• scripts/wechat_ocr.py 22 KB