screenshot-delivery

name	screenshot-delivery
description	BoardGame 截图交付流程。用于打开图、给我看图、看截图、图呢、端到端截图；最终验收图默认走图片预览站。

Screenshot Delivery

这是 BoardGame 项目专用的截图交付 skill，依赖全局 D:\codex-home\skills\artifact-preview-publisher\SKILL.md、仓库脚本 npm run verify:open-image 和项目截图验收口径。

默认交付通道

• 端到端截图、验收截图、PC/移动端对比图：先完成 AI 图面验收，再按 artifact-preview-publisher 发布到服务器相册。
• 默认详情页： http://8.148.71.102:18080/#/boardgame/<task-id>。
• 发布只允许更新 /home/admin/image-preview/data/projects/boardgame/tasks/<task-id>/； 禁止为了展示当前截图修改图片站页面、路由或根目录。
• 只有用户明确说“本机打开 / 用 PureRef 看 / 在电脑上打开”时，才使用 npm run verify:open-image 或系统图片查看器。
• 未通过 AI 图面验收的候选图、失败图、中间排查图不得上传为最终 passed，也不得打开给用户冒充最终验收图。

术语先分清

• AI 看图 / 核图 / 验收截图：指助手自己需要读取图片内容来判断 UI 是否达标。只有这一类默认需要考虑压缩后再用 view_image，避免上下文过大或图片过重。
• 用户打开图 / 图呢 / 给我打开 / 我自己看：指把图片用本机图片查看器或仓库开图脚本打开给用户看。这里的“打开”默认就是在本机真实打开图片文件，不是让 AI 调 view_image 看一眼，也不是把对话里出现的 Viewed Image 当成交付。若图片已经自检达标，默认直接打开目标图片，不要求先压缩；若图片还是候选验收图、失败图或未核图，必须先自检，确认达标后才打开给用户。
• 压缩图 只是 AI 核图或轻量预览的辅助产物，不是“打开给用户看”的必要前置步骤。
• 端到端产物图 / 流程交付图：指为了向用户解释一条玩法链路而后处理生成的图，不是原始截图真相。它可以作为最终交付，但必须按玩家可读标准制作：关键截图足够大、文字能直接读、流程边界清楚，并包含本轮规则/剧本/验收口径摘要。

何时使用

• 用户明确说 打开图、给我看图、看截图、1 图呢、把图真正打开
• 用户要 端到端截图、关键截图、每步操作截图
• 你准备在最终回复里说 截图已看过、图片已打开、请按图验收

核心不变量

1. view_image 只证明 AI 已核图，不等于用户已经看到图；工具结果里的 Viewed Image / 聊天内嵌图片只算“AI 读图证据”，不得称为“已打开图片”。
2. 用户要端到端截图或验收图时，默认发布服务器相册并交付详情链接；只有用户明确要求本机打开时，才执行 npm run verify:open-image -- <绝对路径...> 或系统开图命令。
3. 但候选验收图、刚生成的截图、用户正在质疑是否达标的截图，必须先由 AI 自检并确认达标；自检不达标时禁止打开给用户当收口证据，只能明确写“不达标”并继续修。
4. 用户要打开图时，不得先把任务转成“AI 压缩后核图”；除非该图还未达标自检、用户明确说要压缩图，或原图无法直接打开。
5. 没有开图成功证据时，不得说“已经打开给你看了”；只能说“我已核图，并附路径”或“我已尝试打开，但当前无法证明图片窗口已显示”。
6. 用于交付的截图目录和截图文件名都必须能让用户一眼看懂含义：目录名默认用中文写清 游戏 / 流程或交互，文件名默认用中文写清 编号 / 阶段 / 结果。英文 gameId、日期、编号可作为辅助前缀，但不能只交 basic-flow、runtime、shot-1 这类抽象名。
7. 用户要“整体图 / 整体图片 / 整体截图 / 端到端截图”时，主交付只能是当前真实页面的整屏图或等价真实主容器图；禁止把局部裁图、单元素截图、overlay-only 图、contact sheet、拼接图或脚本标注图放在第一位当主证据。局部图只能作为第二层排查辅助，文件名和回复都必须明确写“局部 / 裁图 / 排查辅助”。
8. 牌桌、棋盘、地图、战场或主游戏视图问题，默认先交能看见完整上下文的整体真实截图；只有主图已经存在且仍看不清细节时，才补局部图。若用户当轮已经批评“只给局部图”，本轮后续不得再以局部图收口。
9. AI 自己核图前必须先做上下文预算门禁：检查文件大小、尺寸和待读张数；禁止连续 view_image 多张 JPG/PNG/WebP 大图或 atlas 裁图。若单图明显偏大或需要多图对比，先生成低分辨率预览、局部文字 OCR、缩略 contact sheet，或只把原图用系统查看器打开给用户看。
10. 官方已知问题：openai/codex#28316 记录图片/base64 工具输出可能进入后续模型上下文并反复重发，导致上下文暴涨和会话卡死；openai/codex#28975 尚未合入前，本项目把“直接读大图”视为高风险操作。触发过卡死后，继续任务前必须改走轻量预览/OCR/外部开图，不得继续反复 view_image 原图。
11. 最终回复必须同时给：

• 服务器相册详情链接
• 肉眼结论
• PC/移动端各自对应的图片标题
• 仅在用户明确要求本机打开时，补充已打开的图片绝对路径与开图证据

12. 如果验收目标是某个新控件、开关、按钮、入口或视觉改点，肉眼结论必须能说清它在画面里的位置；用户追问“在哪里 / 是否通过 / 能不能圈出来”时，必须从原始真实截图派生红圈、箭头或等价标注辅助图，并同时保留原图路径。无法指出目的改点位置时，不得写“截图验收通过”。
13. 多人确认、可跳过、交易、手牌调换、响应窗口这类多阶段交互，不能只交“选择中”截图。主证据至少要覆盖本地确认后的等待态、全员/对方同意后的下一阶段；如果存在“不执行 / 跳过 / 空选择”分支，还要截一张跳过后的等待态，证明不是被强制执行。
14. 用户验收图、最终产物图和要打开给用户看的图，禁止默认压缩、缩略或只交 contact sheet。AI 自己核图可以另做轻量预览，但交给用户验收的目标图必须是高清原图或等价高清导出版。
15. 若最终产物图是流程图、剧本链路图、规则验收图或类似后处理图，不能只拼截图和短标签。它必须包含玩家能读懂的剧本/规则摘要、当前实现边界、关键动作、胜负或验收结论；用户点名“剧本 / 规则 / 文本说明”时，应主动从规则合同、规则书或 evidence 中提取摘要写入图或同目录说明。

固定流程

1. 先锁图

• 先确认哪些图片是本轮主收口图，不要把候选失败图、历史旧图、未达标图拿去开。
• 若文件名不足以唯一定位，先回到截图目录核路径。
• 若截图目录名不足以让用户理解验收主题，先改成本轮可读的中文目录名，再重跑或迁移本轮主证据；不要只把图片文件名改中文、目录仍保留抽象英文桶名。
• 若用户要整体图，先确认目标图尺寸覆盖完整可见视口或真实主容器；不得拿局部图、裁切图或 contact sheet 进入开图流程。

2. 判断是 AI 核图还是用户开图

• 如果用户问的是“这个图对不对 / 你看下图 / 看图验收”，走 AI 核图：先做文件大小/尺寸/数量门禁，必要时先压缩成轻量预览或抽取 OCR，再用 view_image 核对。
• 如果用户说的是“打开图 / 图呢 / 我自己看 / 给我把图片打开”，且目标图已经确认达标，走用户开图：直接打开目标图片，不把压缩作为默认前置步骤；禁止只调用 view_image 后回复“已打开”。
• 如果目标图是刚生成的验收图、候选图或用户正在质疑的图，先走 AI 核图；达标后再走用户开图，不达标则禁止打开并继续修。

3. AI 先核图

• 若当前会话支持 view_image，只能读取已经锁定且经过预算门禁的主图；多张图要优先合成一张小 contact sheet 或改走 OCR 摘录，避免把多份 base64 图片写进后续上下文。
• 对 atlas、高清截图、JPG 裁图、整页设计稿，默认不直接 view_image 原图；先用本地脚本生成长边受控的临时预览图，或用系统查看器打开给用户看。
• 没核图前，不得直接调用开图脚本就宣称“这就是要交付的图”。
• 这一步只适用于需要 AI 自己下视觉结论的场景；用户只是要打开图片自己看时，可以跳过 AI 核图，直接执行真开图。

4. 真开图

• 用仓库脚本打开同一批目标图：

npm run verify:open-image -- "<绝对路径1>" "<绝对路径2>"

• 以脚本输出里的 OPENED_IMAGE= 作为最小成功证据。
• 如果用户明确要求 PureRef，使用同一脚本的 PureRef 模式一次性打开整批图：

npm run verify:open-image -- --viewer pureref --paths "<绝对路径1>" "<绝对路径2>"

• 多图进 PureRef 时必须一次性传入整组路径，不要循环逐张启动 PureRef。
• 若只开一张，也保持同样写法。
• 如果用户明确只是要“本机打开给我看”，也可以直接用系统图片查看器打开目标图，例如 PowerShell 的 Start-Process -FilePath "<绝对路径>"。这同样属于用户开图动作，不需要先压缩。
• 如果只拿到了 view_image / Viewed Image 结果，还没有 OPENED_IMAGE=、Start-Process 成功或等价系统开图证据，必须继续执行真开图；不得停在“AI 看到了图”。

5. 回复口径

• 若脚本成功：
  • 可以说“我已经调用仓库脚本在本机真实打开了这些图”
  • 但不要偷换成“你在聊天窗口里一定已经看到”
• 若脚本或系统开图失败：
  • 直接贴完整绝对路径
  • 说明失败点
  • 不得继续说“已经打开”

默认回复模板

我已经先核过图，并且刚刚用仓库脚本真实打开了这几张：

- <绝对路径1>
- <绝对路径2>

脚本成功证据：
- OPENED_IMAGE=<绝对路径1>
- OPENED_IMAGE=<绝对路径2>

肉眼结论：
- <图 1 结论>
- <图 2 结论>

如果你当前说“还是没看到”，默认解释不是“我已经展示到聊天窗口”，而是“本机开图动作已执行，但当前对话通道未必承载图片窗口”；这时继续按绝对路径定位，不得混称为“已经打开给你看了”。

落点

• 截图验收总规则：docs/ai-rules/e2e-verification.md
• 仓库开图脚本：scripts/verify/open-verified-image.mjs
• npm 命令：npm run verify:open-image