safe-image-reading

Safe Image Reading

本 workflow 只服务当前用户需求中“必须从图片补足的判断”。读图过程本身不是交付；交付必须落到数据字段、规则合同、验收结论、排障事实或阻塞项。

触发

使用本 skill：

• 用户要求看图、读图、OCR、根据卡图/规则页/房间图录入、图片验收或截图审计。
• 任务涉及 JPG、PNG、WebP、atlas、SpriteSheet、卡牌裁图、规则页截图、UI 截图。
• 当前对话因原图、base64、图片上下文过大而变慢或报错。
• 图片是数据录入、规则提取、实现验收、UI 对比、资源核对、排障定位或审计判断的真相来源之一。

核心原则

• 先交接需求，不先泛读图片：必须写清用户要什么、业务对象是什么、图片需要补哪个字段/判断、结果要写回哪里。
• 默认轻量读取：普通单图先生成压缩图、低分辨率预览或单对象裁图给主线程读取；不要反复把原图或 base64 带进长上下文。
• 按需求返回结果：数据录入返回字段和合同状态；验收返回是否达标和失败点；排障返回图片能证明/不能证明的链路事实。
• 子代理只在升级场景用：大图、批量图、atlas/整页图、SpriteSheet、长线程安全读图或用户明确要求时，才交给子代理 / OCR / 外部开图。
• 一次读图，多轮复用：已形成合同或验收证据后，后续实现和审计读文字合同与图片引用，不重复读原图。
• 失败不硬试：图片链路导致上下文溢出、请求报错、OCR 不可用或裁图不可读时，换文本真相源、本地裁图/OCR、已有合同，或只把对应字段标为阻塞。
• 已锁合同优先：审计对象已有 locked 合同和实现对照矩阵时，不把 safe-image-reading 当普通续跑入口；只有合同缺主真相源、缺完整单对象图、来源冲突，或用户明确要求复核图片时才重新读图。

状态口径

读图结果只按当前验收目标判定：

• passed：当前目标需要的字段全部锁定，可进入下一步。
• failed：图片能正向证明不是当前目标对象，或明确不满足验收目标。
• blocked：图片无法提供足够信息，例如空白、打不开、严重模糊、文字区缺失、裁切缺失。
• partial：图片仍可能属于目标对象，但只锁定部分必需字段。
• disputed：图片与其它真相源冲突，不能单边裁决。
• not-applicable：图片与当前目标无关。

边界：纯色/空白/打不开是 blocked，不是 failed；明确是非目标对象是 failed，不是 partial；只有“可能是目标但字段不全”才用 partial。

主线程流程

1. 锁图片判断点

记录：

• 原图或裁图路径。
• 需求类型：数据录入、规则录入、实现验收、UI 对比、资源核对、排障定位。
• 业务对象和现实作用。
• 图片要补足的字段、判断或证据。
• 输出落点：evidence、合同表、真相表、验收结果，或当轮回复。

2. 生成轻量输入

• 普通单图优先生成压缩图或低清预览。
• 文字、像素边界、小图标优先 PNG / WebP lossless；照片、纹理和渐变可用 WebP lossy / JPG。
• atlas、整页图或 SpriteSheet 先裁到单对象完整图；局部放大图只能辅助，不替代完整单对象图。
• 批量图先做 contact sheet 或分批裁图；规则/数据录入优先让子代理直读完整单对象裁图，OCR 只作索引或兜底。
• 如果轻量图已经足够判断当前目标，直接结论，不再升级开放式识图。

3. 读取或委托

主线程自己读图或委托子代理时，都必须带验收标准，不能变成开放式视觉描述。

子代理输入必须包含：图片路径、对象名、用户需求、图片判断点、通过条件、失败/阻塞/partial 边界、结果用途和返回格式。输出只允许结构化字段、结论、失败点、路径/hash；禁止返回 base64、data URL、markdown 图片或大段二进制内容。

参数错误时，修正调用形态后只重试一次。连续失败后换真相源，不继续同路硬试。

4. 写回

按需求写回：

• 数据 / 规则录入：写入 evidence、录入合同或真相表，至少包含对象、图片路径、hash、原文/字段、原子子句、结构化字段、合同状态。
• 实现验收 / UI 对比 / 资源核对：写入验收 evidence 或当轮回复，至少包含用户预期、图片判断点、状态、失败点、证据路径。
• 排障定位：记录图片证明的链路事实和下一步，不生成无关过程文件。

只有当前需求、既有 E2E 证据链或项目 workflow 明确要求独立图片验收产物时，才生成：