DELTA37/结构化报告

结构化报告 是做什么的？

一个自包含的 HTML 文件（无需网络），让忙碌的读者能够：

1. 将整个工作视为任务地图，了解每个任务内部正在等待什么，
2. 打开任意任务及其内部的任意阶段，审查如何完成以及为什么相信每个声明，
3. 在报告中直接回答代理的问题，并查看他们的哪些提示产生了什么结果。

结构与内容

• 结构属于模板 (assets/template.html)：布局、区块名称（问题、任务、背景、结论、假设、结果、未检查、工作流、需要批准、您的行动）、顺序、状态、每个图标和每个 UI 标签。固定不变，始终为英文。图标仅标记结构，从不标记内容。
• 内容属于您：JSON 文件，使用用户的语言。scripts/build.py 验证内容并填充模板的占位符。您从不编写 HTML，也从不发明新区块。

工作流程

1. 收集素材：消息、工具结果、文件、命令、链接、测试、度量、决策。仅报告实际发生的事件。
2. 将素材切分为任务（1-12 个）：一个任务 = 一个目标及其对应的成果。使用 links 连接它们：depends、blocks、related。
3. 按照以下规则和 references/schema.md 填写每个任务。
4. 编写 JSON — 默认保存到工作目录下的 reports/<YYYY-MM-DD>-<slug>.json。
5. 构建: python3 <skill>/scripts/build.py <file>.json → <file>.html。修复每个 error:；阅读每个 warning: 并在确实为真时才忽略它。
6. 在本地打开（open / xdg-open / start）并提供路径。切勿上传。
7. 在聊天中：2-4 行 — 主要结果以及等待读者处理的内容。

动态报告：跟踪会话，接收答案

当用户希望报告在整个会话期间保持最新（或者要求一个跟踪/动态报告）时，一次性绑定会话：

python3 <skill>/scripts/track.py start reports/<file>.json      # 创建 <file>.journal.json

此后，UserPromptSubmit 钩子（一次性安装：track.py install-hook，它也会同时添加 Stop 钩子）会将每个用户提示记录到日志中，并提醒您提示编号。在每次更改工作的提示之后，更新 JSON 并重新构建 — build.py 会为每个块（每个节点 × 区块）生成指纹，并用当前提示编号标记新的或更改过的块。切勿手动编写标记。报告显示一个提示轨道；选择某个提示会高亮显示该提示中出现（绿色）或更改（蓝色）的内容。

面向读者的问题。 将决策放在 approvals 中。每个决策是一个带有 options 的问题 — 默认互斥（一个答案）或 "multi": true（可多选）— 同时提供您的 recommend（对于多选是一个列表）、why 和 due。读者始终有一个额外的选项“您自己的答案”；没有选项的问题则通过自由文本回答。在报告中，需要批准区块的未回答问题构成一个连续系列，一次显示一个问题：一个互斥选项即可回答并继续，多选或自定义答案需要通过“下一步”确认，该系列以所有答案的回顾结束，然后提交答案将它们发送给您 — 这是唯一的发送方式，并且 actions（读者执行的步骤）没有输入。答案会发送到本地答案服务（127.0.0.1:47319，由构建脚本启动并保持更新），即使报告作为普通文件打开也是如此，并且答案会作为下一个提示存储在日志中。当报告中有未回答的问题时，请保持一个等候器作为后台命令运行：

python3 <skill>/scripts/track.py wait reports/<file>.json

当读者发送答案时，wait 会打印答案并退出 — 该输出会返回给您：将其完全视为用户的提示并继续；如果仍有问题，请再次启动 wait。如果没有运行等候器，Stop 钩子会在您的轮次结束前将排队中的答案交给您，而 UserPromptSubmit 钩子会将它们附加到用户的下一条消息中 — 答案永远不会丢失。在下次构建后，已回答的问题会显示为已回答。--static 构建一个不包含答案通道的报告（用于在本地机器之外共享）：问题显示为只读，没有输入框。

输入框下方的链接。 scripts/statusline.py 为会话报告打印一行状态行 — 其标题作为可点击链接，在浏览器中打开 HTML，并显示还有多少问题在等待。将其用作状态行，或将其输出附加到现有状态行；对于没有报告的会话，它不打印任何内容。

报告的每个块都有一个复制为 Markdown 按钮（整个报告、任务卡片、报告、区块、单项、步骤、提示）— 当读者想将内容粘贴到其他地方时，请指向该按钮。

使报告值得信赖的规则

将每件事的知晓方式分开；切勿混淆。

• context — 您实际查看的来源：id（C1…）、简短的 title、真实的 url 以及 note 中记录的确切事实。切勿捏造 URL。优先使用仓库/网页 URL：file:// 链接无法在读者机器上打开（构建会发出警告；丢失的本地文件视为错误）。
• inferences — 结论，每个都带有 basis（上下文 ID）和 confidence。没有基础 → 假设。
• assumptions — 未经验证就当作真：why、如何 verify、如果错误则 risk。
• unchecked — 您没有检查或做的事情，以及 why 未做。读者对此的依赖超过其他任何东西；请直说。一个已完成的任务如果没有 unchecked 会收到警告（[] 表示“检查了所有内容” — 仅当为真时）。
• result — 现在存在的内容，以有类型的项目表示。每个 verified 项目都需要 how：证明它的命令、测试或链接 — 构建失败如果没有它。
• stages — 您实际采取的步骤，每个层级 2-8 个。阶段与任务是同一种节点：id + title 必填，允许任何任务字段，可以有它自己的 stages + flow，深度不限。在卡片上显示 detail（您做了什么）、outcome（产出了什么）、status、when、uses。点击一个阶段会以相同结构打开它的报告，因此为真正工作的阶段提供真实内容。死胡同也是阶段（failed / skipped）。
• 下一步是计划中的阶段 — 任何待完成的事情都是状态为 "planned" 的阶段，包含 detail（将要做什么）和 when（条件或时间：“等待您的批准”、“周一”）。一个未完成的任务如果没有计划中或进行中的阶段会收到警告。
• approvals — 只有读者才能做的决策：问题、why 这是他们的决策、options（互斥，或 multi: true）、您的 recommend（选项之一；对于多选是一个列表）、due。一个节点中几个相关的问题会成为系列 — 按读者应回答的顺序排列。切勿要求批准已经完成的事情。
• actions — 只有读者才能做的事情，带有准确的 command 和相关的 due。
• secrets — 报告可能会被转发。构建会失败如果任何内容看起来像密钥、令牌、私钥、JWT、密码赋值或 URL 中的凭据（如果安装了 gitleaks 也会使用）。将其从内容中移除；切勿手动“遮盖”。已记录提示中的密钥会自动遮盖。

编写结构，而非散文

每个文本字段都渲染结构，因此请赋予它结构：

• - item → 项目符号；1. item → 编号（仅限真实序列）；两行或更多 Key: value 行 → 对齐表格；一个 JSON 字符串数组 → 项目符号。
• 每行用 **bold** 标记读者不可错过的一两件事；==text== 用于高亮；`code` 用于标识符、路径、命令。
• 段落不超过两个句子；没有副标题或引言行。

字段指南：brief — 地图卡片的 1-3 行 Key: value。problem — 键/值事实。goal — 完成意味着什么的项目符号。result.summary — 键/值或项目符号。

语言

内容使用用户的语言，meta.lang 设置为其代码。结构标签保持英文。

文件

• assets/template.html — 结构：带有占位符的标记、样式、图标以及用于布局、导航、搜索、提示轨道和回答的脚本。
• scripts/build.py — 验证内容（上述检查、密钥）、标记日志、渲染模板。--check 仅验证；--template 使用其他模板。
• scripts/track.py — start、wait、hook、stop-hook、daemon、status、install-hook（参见其文档字符串）。
• scripts/statusline.py — 用于 Claude Code 状态行的报告链接。
• references/schema.md — 每个字段。
• examples/ — 英文和俄文示例；俄文示例带有 5 个提示的日志。