safe-image-reading

name	safe-image-reading
description	BoardGame 安全读图流程。用于 JPG/PNG/WebP、图集裁片、卡图、房间图、规则页、OCR 或截图验收；默认轻量裁图。

Safe Image Reading

这是 BoardGame 项目专用的需求交接式安全图片处理 workflow。图片只是用户当前需求的输入之一，读图过程本身不构成交付。默认做法不是“禁止看图”，也不是把压缩图当成额外能力待确认；压缩图、轻量预览、局部裁图就是给主线程看的默认输入，目的只是减少后续对话反复携带原图/base64 时触发的上下文膨胀和请求错误。普通单图默认由主线程生成并读取压缩图，然后给出当前任务所需结论；只有大图、批量图、atlas/整页图、SpriteSheet，或用户明确要求“本会话安全读取图片”时，才升级为带目的和验收标准的子代理 / OCR / 外部开图严格链路。主线程必须把用户当前需求、业务对象、图片需要补足的字段/判断点、结果要写回哪里或用于哪个判断一起交给子代理或本地 OCR。子代理不是另接一个新任务，而是补足当前用户需求里依赖图片判断的部分。子代理返回什么，由用户需求决定：

• 数据录入 / 规则录入需求：返回官方原文、原子子句、结构化规则字段和合同状态。
• 实现验收 / UI 对比 / 资源核对需求：返回是否满足用户预期、失败点、证据路径和最小修复指向。
• 排障定位：返回图片能证明或不能证明的链路事实，不展开无关视觉描述。

任何返回都必须能推进当前用户需求；不能为了证明“读过图”产出与录入、验收或排障无关的过程文字。

何时使用

• 用户要求“看图 / 读图 / OCR / 根据卡图录入 / 根据房间图录入效果 / 从图片补规则 / 图片验收 / 图片审计”。
• 任务涉及 JPG、PNG、WebP、atlas、卡牌裁图、房间裁图、规则页截图、UI 截图。
• 当前对话已经因为 view_image、图片上下文、JPG、base64、context window 卡住或变慢。
• 主线程准备让图片辅助完成用户当前需求里的数据录入、规则提取、实现验收、UI 对比、资源核对、排障定位或审计判断。

核心不变量

1. 先交接需求，不先锁图片：主线程必须先说明用户当前要什么、业务对象是什么、图片需要补足哪一个字段或判断、结果要写回哪里或用于哪个判断；不能把需求降级成“读一下图片有什么”。
2. 按需求返回最小有用结果：数据录入返回详细字段；验收返回是否符合用户预期和失败点；排障返回链路事实。禁止固定要求子代理输出过程说明。
3. 默认压缩后读取：普通单图默认先生成轻量预览、单对象裁图或低分辨率副本给主线程看；压缩图就是模型读取输入，不再把压缩输入写成额外能力确认或链路兼容性问题。
4. 主线程默认不反复读原图：主线程负责锁定图片路径、业务对象、用户需求、图片判断点和结果用途；普通单图默认直接读取压缩图并产出结论。只有大图、批量图、atlas/整页图，或用户明确要求本会话安全读取图片时，才把图片读取升级交给短子代理、本地 OCR 或外部开图。
5. 子代理只返回需求结果：用户已授权子代理时，子代理可以读取原图或裁图，但只能返回结构化文字、表格、结论、路径/hash，不得返回 base64、markdown 图片或大段二进制内容。
6. 批量规则录入优先子代理直读裁图：当目标是从多张卡牌、房间或事件裁图录入规则文本和结构化效果，且已经有单对象完整裁图时，默认分批交给可读图子代理直接提取字段；OCR 只用于候选索引、粗定位、比对子代理输出或子代理不可用时的兜底，不得作为 locked 官方原文。
7. 需要复用时才落证据：数据录入、规则真相、审计结论、验收证据必须写入 evidence / 合同表 / 真相表；一次性排障若不改变后续实现或审计真相源，可只在回复中说明结论和证据路径。
8. 局部不确定只阻塞对应字段或验收点：文字模糊、裁图不完整、缺官方来源时，只标记具体字段或具体验收点 blocked/disputed/partial，不能把图片过程描述当成主结论。
9. 一次读图，多轮复用：凡已形成合同或验收证据，后续实现、审计、测试只读文字合同和图片引用，不再反复读取同一张原图。
10. 官方已知风险：openai/codex#28316 说明历史图片/base64 工具输出可能被后续请求反复携带，导致上下文膨胀、请求超大和 502/524/流中断；openai/codex#28975 仍是 open 状态，只能把压缩/resize/外置证据称为规避或止血，不能说官方根因已修复。采用压缩图的现实原因是避免原图/base64 污染后续上下文并引发请求错误，不是因为模型不能读取图片。
11. 图片链路失败不得反复硬试：图片导致上下文溢出、请求报错、OCR 不可用或裁图不可读时，禁止继续用同一方式重试。必须改走文本真相源、本地轻量裁图/OCR 脚本、已有合同，或把具体字段/交付点标为 blocked，让当前用户需求继续推进。
12. 已锁审计合同不得再进图片链路（强制）：当审计对象已有 locked 合同和实现对照矩阵时，safe-image-reading 不得作为普通续跑入口。只有合同字段检查已经明确指出缺主真相源、缺完整单对象图/可读裁图、缺对象归属、缺规则原文/原子子句、缺索引入口、来源冲突，或用户明确要求复核图片时，才允许重新读图、OCR、裁图或让子代理看图；否则必须回到审计 skill 消费已锁合同。
13. 验收产物只在需求需要时生成：图片读取默认只回写当前需求的字段、合同或判断点。只有当前用户需求、既有 E2E 证据链或项目 workflow 明确要求验收产物时，才生成对应 json/md 结果文件；不得为了证明“读过图”额外造过程文件。
14. 状态口径必须按当前验收目标判定：图片验收不是开放式识图汇报，也不是“识别出一点内容就 partial”。passed / failed / blocked / partial 必须按当前用户需求的通过门槛判定；如果使用子代理，必须把目的、验收标准和返回格式传给它。
15. 格式选择服务可读性：优先保留能让 AI 看清目标字段的格式，而不是追求最小体积。UI 截图、文字、卡牌规则、像素图、SpriteSheet 局部优先用 PNG 或 WebP lossless；照片类、纹理类和大面积渐变可用 WebP lossy 或 JPG。WebP 通常比 JPG 更省体积且可被当前读图链路使用；如果文字边缘、像素格或小图标被压糊，改用 PNG/WebP lossless。
16. 不做链路能力确认：普通压缩图就是当前 AI 要读取的图片输入；不要再问“链路是否支持读取压缩图片”，也不要把压缩图交付变成工具兼容性验证。真正要验证的是图片内容是否满足当前用户需求的验收标准。
17. 子代理结论必须抽样复核后写回：当本轮升级到子代理安全读图时，主线程必须读取同一张压缩图或同批关键裁图做抽样复核；只有子代理和主线程对通过项、阻塞项、失败原因一致，才允许把结果写入真相表、验收 JSON、审计文档或代码。若不一致，先标 partial/disputed/blocked，不要硬写 passed。
18. 子代理只在升级场景使用：普通单图默认由主线程读取压缩图。只有大图、批量图、atlas/整页图、SpriteSheet、长线程明确要求“本会话安全读取图片”，或用户要求验证安全读图流程本身时，才启动子代理。启动子代理的目的必须是“按验收门槛判断能否通过”，不是让它泛泛汇报识图结果。

状态判定口径

对子代理或本地 OCR 的输出，必须使用以下状态定义：

• passed：当前验收目标所需字段全部锁定，且可直接进入当前任务的下一步。例如普通手牌反写必须同时锁定中文牌名、牌类、规则效果摘要；军备牌还要锁定军备目标。
• failed：图片能被明确排除为当前目标之外，或能证明不满足当前目标。例如人物牌、牌背、棋子/图标、单位素材、资源色块、错误页面、错误 UI 状态。只要已经能正向证明“不是本次目标”，就用 failed。
• blocked：图片本身不给出足够信息，无法判断当前目标字段。例如纯色底块、空白、严重模糊、裁切缺失、文件打不开、文字区缺失。blocked 只阻塞该图片或该字段，不能扩展成整个任务失败。
• partial：图片属于当前目标类别或仍有合理可能属于当前目标，但只锁定了部分必需字段，缺少另一些必需字段。例如能确认是军备牌但缺军备目标，或能确认牌名和牌类但规则效果不可读。

状态边界：

• 纯色底块、空白、打不开、无可读字段：blocked，不是 failed。
• 明确是非目标对象：failed，不是 partial。例如普通手牌验收里，“炮”棋子图标只有一个可见字，但它是图标/棋子资源，不是普通手牌候选，所以应为 failed。
• 只有在“仍可能是目标对象，但字段不完整”时才使用 partial。

主线程固定流程

1. 交接用户需求与图片判断点

   • 记录原图或裁图绝对路径。
   • 记录用户当前需求类型：数据录入 / 规则录入 / 实现验收 / UI 对比 / 资源核对 / 排障定位。
   • 记录业务对象和现实作用，例如“倒塌房间的房间文字效果”“房间探索 UI 是否满足预期”“卡图与牌堆归属是否一致”。
   • 记录图片判断点：当前需求需要图片补足什么字段、判断或证据，失败时要返回哪个具体字段或交付点无法推进。
   • 记录输出落点：写入 evidence / 合同表 / 真相表，或仅作为当轮排障结论。

2. 生成轻量输入

   • 默认先压缩或降采样成轻量预览后由主线程读取；普通单图优先使用压缩副本，不直接把原图/base64 带进长线程。
   • 普通截图/卡图压缩优先顺序：文字或像素边界敏感用 PNG/WebP lossless；一般彩图用 WebP；只有 WebP 不便查看或工具不支持时才退回 JPG。
   • 优先使用已有裁图。
   • 若只有 atlas 或整页图，先裁到单对象完整图；局部文字放大图只能辅助，不得替代完整单对象图。
   • 若需要批量看图，先做小 contact sheet 或分批交给子代理。
   • 若批量图的目标是规则/数据录入，优先把单对象完整裁图分批交给子代理直读；本地 OCR 只提供候选索引，不替代子代理直读裁图。
   • 大图、批量图、atlas/整页图，或用户明确要求“本会话安全读取图片”时，进入子代理/OCR/外部开图的严格流程；否则普通单图默认由主线程读取压缩图并产出结论，不额外开子代理。
   • 如果压缩图已经足够判断当前目标，直接给结论；不要再把同一张压缩图升级给子代理做开放式识图。

3. 按需求读取或委托图片处理

   • 主线程自己读取轻量图时，也必须带着当前需求和验收标准读；不能变成开放式视觉描述。
   • 普通单图不要为了“更安全”默认交给子代理；主线程读压缩图给结论就是默认安全路径。
   • 子代理任务必须是“按验收标准判断是否通过”，不是“返回完整识图结果汇报”。输入必须包含图片路径、对象名、用户当前需求、图片需要补足的判断点、通过条件、失败/阻塞/部分通过边界、结果用途和返回格式。
   • 子代理调用输入必须使用最小附件形态：图片附件用本地图片类型（如 local_image），验收目的和返回格式用文本附件；不要同时传互斥的 message 与 items，也不要把普通文件类型误当图片附件。若参数错误，修正调用形态后只重试一次。
   • 子代理或 OCR 输入只包含完成上述判断所需的最小信息。
   • 对批量规则录入，子代理输入必须是“请从这些裁图提取可落表字段”，不是“评价这些图是否清晰”。输出必须能直接写入数据录入合同；看不清的字段标 blocked，不能整体退回给主线程。
   • 输出只允许需求结果、必要字段、失败点、路径/hash。
   • 委托语必须写明上面的状态口径，尤其是 failed、blocked、partial 的边界，防止子代理把“识别出一点内容”误写成 partial，或把纯色/空白误写成 failed。
   • 数据录入 / 规则录入需求才提取详细字段：
     • 房间：房间名、房间文字、进入/翻开/停留/离开触发、检定/支付、分支、抽卡标记、楼层/门位索引。
     • 卡牌：卡名、类型、原文、使用时机、目标、消耗/弃置、常驻/特殊行动/武器/场景特例、结果分支。
     • 事件：事件名、原文、检定属性、结果档位、每档效果、是否弃置、是否结束行动。
   • 验收 / 对比需求只返回：通过/不通过/无法判断、命中的用户预期、失败点、最小证据，不要转写无关文字。

4. 按需求写回

   • 若当前需求、既有 E2E 证据链或项目 workflow 要求独立验收产物，路径建议为：
     • test-results/evidence-image-validation/<e2e-id>.json
     • test-results/evidence-image-validation/<e2e-id>.md
   • <e2e-id> 必须能唯一表达当前验收链路，例如 qidahen-formal-handcard-2.4、qidahen-tutorial-diplomacy、qidahen-board-ui。
   • 只有当前需求或既有 workflow 要求独立验收产物时，.json 才作为机器校验主文件，至少包含 objective / criteria / summary / items / verdict；summary.total 必须等于各状态数量之和，items 必须逐项记录 idx/path/status/reason/lockedFields。
   • 只有当前需求或既有 workflow 要求独立验收产物时，.md 才作为人读摘要，只写当前链路验收目标、状态统计、关键失败点和裁决。
   • 同一链路重复跑时允许覆盖同名 json/md，但不得覆盖其他端到端链路的结果；需要历史留存时再另建 runs/<timestamp>/，不要把历史和当前结果混进一个总文档。
   • 需要子代理参与时，验收产物必须记录子代理 ID、压缩图路径、主线程抽样复核结论，以及哪些项升级、哪些项保留 partial/blocked/failed。
   • 数据录入 / 规则录入：写入 evidence / 录入合同 / 真相表。每条至少包含对象、图片路径、hash、官方原文、子句拆分、结构化字段、合同状态。
   • 实现验收 / UI 对比 / 资源核对：写入验收 evidence 或当轮回复。每条至少包含用户预期、图片判断点、通过状态、失败点、证据路径。
   • 排障定位：记录图片证明的链路事实和下一步动作，不生成无关表格。
   • 状态只允许表达需求状态：passed / failed / locked / blocked / disputed / partial / not-applicable。图片不可读、裁图缺失或字段模糊只能写成具体字段/判断点的阻塞原因，不得作为独立汇报结论。

5. 继续业务任务

   • 后续实现/审计只引用需求结果、规则合同或验收证据。
   • locked/passed 项进入实现对照、最小测试补证或缺口登记。
   • blocked/disputed/partial/failed 项只阻塞对应字段或验收点；不得脑补实现，也不得让已锁字段白读。

6. 图片链路失败时换真相源

   • 若子代理、图片直传或主线程读图连续失败，不再继续尝试同一路径。
   • 优先查项目内官方文本、现有录入合同、图集索引、代码配置和测试证据。
   • 能从文本或配置锁定的字段照常入表；只把图片原文、数值、分支等确实缺失的字段标为 blocked/partial。
   • 禁止因为图片链路失败就暂停整个用户需求。

子代理返回格式

可选端到端验收产物

只有当前需求、既有 E2E 证据链或项目 workflow 明确要求独立图片验收产物时，主线程才把子代理结果整理成每条链路独立的覆盖式产物，不能混进一个总文档：

test-results/evidence-image-validation/<e2e-id>.json
test-results/evidence-image-validation/<e2e-id>.md

.json 最小结构：

{
  "id": "<e2e-id>",
  "objective": "<本链路图片验收目标>",
  "criteria": ["<验收字段或判断点>"],
  "summary": {
    "total": 0,
    "passed": 0,
    "failed": 0,
    "blocked": 0,
    "partial": 0
  },
  "items": [
    {
      "idx": 1,
      "path": "<图片路径>",
      "status": "passed/failed/blocked/partial",
      "lockedFields": {},
      "reason": "<通过或失败原因>"
    }
  ],
  "verdict": "<本链路裁决>"
}

写入后必须做最小校验：summary.total == items.length，且 passed + failed + blocked + partial == total。长期审计文档只引用 <e2e-id>.json/.md 和摘要结论，不复制所有原始行。

数据录入 / 规则录入

| 对象 | 类型 | 图片路径 | sha256 | 官方原文 | 原子子句 | 结构化规则字段 | 合同状态 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| <中文对象名> | 房间/物品/预兆/事件 | <路径> | <hash> | <逐字转写> | C1... | <触发/目标/检定/分支/清理> | locked/partial/blocked/disputed |

验收 / 对比 / 排障

| 对象 | 用户需求 | 图片判断点 | 结果 | 失败点或证据 | 下一步 |
| --- | --- | --- | --- | --- | --- |
| <中文对象名> | <验收/对比/排障> | <用户预期/图片需回答的问题> | passed/failed/blocked | <最小证据> | <最小动作> |

若无法完整判断，只能补“阻塞字段/阻塞交付点”，不能把需求变成泛泛的视觉 QA。

禁止行为

• 禁止子代理把图片以 base64、data URL、markdown 图片形式返回给主线程。
• 禁止主线程把“子代理看过图”当作最终证据；必须有需求结果、合同或验收结论。
• 禁止用单张模糊裁图直接改规则实现。
• 禁止把缩略图或 OCR 错字当成官方原文。
• 禁止在同一长线程里为了同一对象反复 view_image 原图。
• 禁止把图片处理结果写成泛泛的过程说明后就停止；必须落到具体字段、判断点或交付点。
• 禁止把图片处理固定成过程汇报或留档动作；必须服务当前用户需求、图片判断点和结果用途。