给人看的汇报

由 explain-diff-for-human-review 重构，保留 GitHubxsy/agent-skills 的来源与 Apache-2.0 归属；原上游版本与本地修改见仓库 sources.lock.json。 本机修改于 2026-11-02：从用户认可的部署报告增加温和的运维汇报范例；保留上游蓝色主题与生成器。来源与适用边界见 运维范例。

本地修订（#61）：增加跟随系统／浅色／深色三态，保留默认浅色及已有证据规则。

让读者只看标题和主图，就能说出：现在是什么、需要我决定什么（或无需决策）、依据是什么、下一步谁做什么。完成深入取证，再把解释压缩成可视化 HTML。

先选要回答的问题

• 按主问题选一个主视觉；必要时组合两个。小改动用紧凑前后对照，不铺完整架构；纯讲解不强造 PR 或合入结论。
• 创建新 PR 后立即给初版 HTML，标明仍在运行的 CI/Review；后续事实变化时更新同份报告，不等审查全绿才汇报。
• 汇报不授予实现、发送、发布或合并权限，不替用户批准；用户只要解释时，保持只读。

先把事实讲对

1. 固定任务范围和取证时间，读取真实来源。区分事实、推断、未知、模拟；将改变当前判断的证据缺口及其影响提炼为一句，放在首屏可见处。注释和 README 不自动等于上游强制要求。
2. 要求类报告区分用户要求、外部规范、接口契约、项目配置及建议；没有权威来源时写“待核实”，不要虚构标准编号或强制性。
3. 现状类报告分开代码合入、上传受理、注册表核验、Release 和上游收录；计划触发、实际开始、完成与单条数据采集时间分别记录。同一时区展示。
4. 改动类报告逐项对照需求及真实调用路径；PR 读取实际 base_sha / head_sha、差异、测试与审查状态，使用 PR 审查规则。非 PR 的本地差异保留快照标识。
5. 本次执行、历史/CI、源码推断、未验证分别表述。跨轮证据复用、性能/交互、制品或特殊差异读取 证据边界。同树可复用适用源码证据，不能据此认定 tarball 字节相同。
6. 用于业务决策的报告应提供支撑关键判断的实际截图；缺图时按 证据边界中的“截图与补采” 在对应事项中记录缺口、文字证据和判断限制，下次执行同一事项的探索或复测前先提醒补采。

先选择已经认可的范例

用户指定或明确认可现有报告时，以它为设计锚点：保留阅读顺序、比喻和视觉关系，更新事实与验证；不要为满足默认模板把好报告重做。用户要求“用原报告进化技能”时，保留原件，从中提炼可复用范例，不能反向拿技能样式替换原报告。

• 部署、兼容性与验收汇报：优先读 运维范例，查看 assets/operations-report.html 和 assets/operations-preview.png。从该 HTML 复制到交付路径，替换虚构内容；沿用米白与墨绿、结果状态条、前后分层、职责对照、验收与必要参考。按问题删减，不强填所有区块。
• 单一改动、要求、阶段或分支流程：使用下方蓝色主题与生成器。复杂分支仍优先责任流程图；温和配色不能替代必要关系。

两套范例都遵守相同的事实、可读性与验证边界；不是每份报告都固定用同一种颜色或卡片数量。

每份报告都有的阅读工具

顶部必须提供跟随系统／浅色／深色三态主题选择器与复制文件位置按钮，蓝色、运维和自定义报告均适用。保留首次默认浅色；用户可显式选择跟随系统，并随系统主题变化更新。记住三态选择，兼容已有浅色/深色记录；存储受限时仍能在当前页切换。实际配色仍使用 html[data-report-theme="light|dark"]，区分用户选择与解析后的配色，不只改控件文案。

蓝色生成器已内置共用控件并记录最终输出路径。运维范例或自定义 HTML 落到实际交付位置后，都执行：

python <skill-root>/scripts/add_report_controls.py --input <report.html>

该脚本原位内联共用样式与交互，可重复运行，不会重复添加控件；自定义配色须响应上述主题属性。文件位置是生成时记录的真实来源路径，不是浏览器预览地址。 生成器将最终文件绝对路径写入 report-source-path 元数据；经 sandbox/托管预览打开时仍复制该路径。执行环境路径与用户实际路径不同时，用 --source-path <用户实际绝对路径> 显式绑定，不能猜测挂载映射；移动文件后重新运行绑定新位置。未记录真实路径时明确提示未绑定，不能退回复制预览 URL。只在用户点击时写剪贴板；失败时显示并选中真实位置供手动复制，不能误报成功。打印隐藏工具栏，无脚本仍可读正文与凭据。

复现蓝色主题

先读 视觉配方，查看 assets/reference-report.html；有图像工具时查看 assets/reference-preview.png（历史配色参考，当前结构以 HTML 为准）。它们来自本次认可的 Piano 发布地图的视觉语言，内容已去项目化且明确为虚构示例。

选择蓝色主题时，默认使用随附生成器，继承版式而非重新凭印象设计：

python <skill-root>/scripts/render_report.py --input <verified-report.json> --output <report.html>

按 examples/change.json、requirements.json、status.json、mechanism.json 的同类结构填写已核验事实。生成器只负责呈现，不获取来源、不判断事实、不自动声称通过。先运行一份最接近的示例，再替换内容。

• 采用浅灰画布、白色大留白、深蓝结论区、蓝色重点和稳定的参与方配色。主标题约 32–44px、正文至少 16px；主视觉宽约 1180px，文字块保持短行。
• 首屏保留一个结果标题、一两句回答、一个当前状态或关键判断；同时明确本次要作的决定、建议与下一步；无决策时如实写明。随后只保留解释当前判断所需的主视觉，详细证据默认折叠。每张卡片表达一个关系，不把所有段落装成卡片。
• 生成器不能表达任务的关键分支时，沿用同一主题与组件扩展 HTML/SVG。读取 讲解图式，明确箭头传递什么、条件如何改变结果；不为装饰加图。
• 蓝色主题自定义时把 assets/report-theme.css 与 assets/report-layout.css 内联到 HTML 的 <style>；根节点使用 .human-report。运维主题复用其模板的内联样式。两者均保留打印、焦点与窄屏规则；prefers-color-scheme: dark 仅在选择跟随系统时生效，不得覆盖显式浅色或深色选择。不继承示例的项目事实、版本号、标志或证据链接。
• 自定义 Prompt/代码等长文本块时，字色与底色须成对指定；沿用布局中的 pre 配色，让内部 code 继承字色，展开后检查明暗主题和打印可读性。

把文字留在该在的位置

多列长文或用户反馈列宽不合理时，先读 表格可读性与列宽。按内容角色分配宽度，窄屏保留可读字号与局部滚动；需要时显式启用可用鼠标和键盘操作的列宽工具，保留默认布局、重置与打印。不要把所有表前两列强制压窄或统一等分。

标题说结果；图上用短标签表达关系；正文只解释图中不明显的因果。默认可见文字约 250–600 中文字，小改动更短；影响当前决定的风险和限制必须常显，完整记录放在补充材料中。

默认只展示当前决定/建议、必要事实与下一步。检验某段是否改变读者现在的决定；不改变就放原生闭合 <details>，而不是用 tabs 继续占据主阅读区。技术验证、版本/字段说明和持续跟踪通常属于补充；其中若有阻断或风险，仅把改变决定的一句话提到首屏，完整证据仍可展开追溯。按本次问题判断，不把主题名称当固定禁词，也不把所有内容一概折叠。

Tabs 只用于确实需要切换对照的同级方案或业务参考，不是验证日志的通用导航。首屏决定与共同风险不能只存在于某个 tab。生成器中 evidence 默认折叠；只有作者明确提炼的 decision_facts 常显，字段约定见 阅读导航。

GitHub 报告一律不在 HTML 中复制 raw diff、patch 或 diff hunk；使用固定 SHA compare 与文件永久链接。不复制仓库源码、凭据、私有接口或大段日志；文本正确转义，保留原访问边界。报告默认不修改产品代码、不审批或合并 PR。

附图默认适中展示、保持完整比例，点击或键盘可放大；不得为缩略图裁掉待证事实。先读 决策、参考导航与附图，复用共用 tabs／图片查看组件与合成示例，保持三态主题、无脚本和打印可读。

验证并交付

• 创建 UTF-8、自包含 HTML5，不加载远程字体、脚本、CSS 或图片。交互只在本页展示已标注的假设，不请求网络或执行真实操作；无脚本仍能读懂默认状态，打印展开证据和必要状态摘要。
• 实际检查桌面和移动端宽度（约 1440px / 390px）、三态主题切换、跟随系统的实时变化及刷新后的选择、tabs 与附图的键盘、关闭及返回焦点、打印和外部资源。复制检查同时覆盖 file:// 与 sandbox/托管预览，确认得到实际文件绝对路径，并覆盖剪贴板被拒绝时的手动复制。主图在手机上重排为可读关系，不能只把桌面字缩小；工具不可用时如实说明未做视觉验证。用户指定验收设备或材料不得外发时，按该范围执行；静态检查、逻辑测试不能替代该设备上的实际视觉验收。
• 用 scripts/resolve_report_path.py 选择用户指定路径 → 仓库 reports/ → 工作区 → 临时目录。生成物不写回 Skill 安装目录，不提交业务仓库；按环境要求完成保存。
• 校对标题、主图、当前状态、关键限制和证据指向同一版本；删除不改变理解与判断的段落。返回实际 HTML 链接和一到两句结论。

维护时按 评估规则 做生成与视觉回归；复杂任务可按 PR 规则使用只读独立审查，不提供预期结论，失败时单 Agent 回退。