readout

Readout（调查报告）

Readout 会将调查结果整理为一份持久保存的 HTML 文档，让读者即使过了几周，也能在没有任何原始背景信息的情况下阅读。它有两种启动方式：

• 快照模式 — 在对话中途调用（“把这些内容整理成文档”）：对话中累积的调查结果就是素材。
• 研究模式 — 直接调用（“/readout on how github webhook events are processed in the server”）：没有可供梳理的对话，因此调查本身也是任务的一部分。

无论哪种方式，调用此技能都是一项辅助任务。作为主 Agent，你的工作是明确范围、向子 Agent 提供清晰的任务说明，然后退到一旁——由子 Agent 负责梳理或研究并撰写文档，将这部分（通常工作量很大）的内容留在你的上下文窗口之外。

编排工作流

1. 明确范围 — 启动前先提问

模糊的任务说明只会产出模糊的文档。启动前，你应该能够列出文档要回答的具体问题；如果做不到，就先询问用户：

• 提出 2–4 个有针对性的问题，并提供具体选项，而不是开放式提问——先快速查看代码或主题，确保选项切实可行（子系统、入口点、相互竞争的关注点）。例如，对于“/readout on how github webhook events are processed”：关注哪个方向——入站触发、回传，还是两者都要？需要现状参考，还是排查易踩的坑？涉及哪些仓库？
• 务必明确深度和受众：高层概览，还是有逐行依据的底层机制；个人笔记，还是供团队共享。
• 尊重用户的含糊回答。“只要高层概览”也是有效答复——在任务说明中记录，然后继续，不要追问。即便如此，也要尽量提炼出读者最需要了解的两三个问题；明确具体的问题才能让调查报告更有用。
• 如果范围已经明确，就跳过访谈——围绕具体主题的对话快照或精准的研究请求都无需提问。快照模式下，对话通常已经包含所需问题；只有在调用时未明确要涵盖哪些讨论线索的情况下才提问。

2. 编写任务说明

撰写一份简短的任务说明（约 10–20 行），包含线索，而非内容全文：

• 工作标题或主题，以及模式（快照或研究）
• 文档必须回答的具体问题（来自对话或访谈），以及深度和受众
• 范围：要涵盖哪些讨论线索或子系统，以及明确排除哪些内容
• 快照模式：值得作为文档重点的主要结论，每条一行——子 Agent 会自行从对话历史中提取完整内容，因此不要大段粘贴调查结果
• 研究模式：已知的起始线索——入口文件、符号或目录
• 作为工作依据的仓库或目录的绝对路径
• 每个仓库托管平台上的 URL，以及已知的检查提交版本（例如 github.com/org/repo @ abc123），以便文档可以为代码引用添加超链接

3. 启动一个本地子 Agent

通过 run_agents 启动且仅启动一个子 Agent，并使用本地执行。必须使用本地执行：这样文档才会写入用户的文件系统，并能在其浏览器中打开。将子 Agent 命名为 readout-<topic-slug>。

根据以下模板编写子 Agent 的提示词。必须包含：

• 任务说明
• 与模式对应的源材料区块（快照模式还需要提供你的 Agent 运行 ID——即编排运行时上下文中的 current_run_id，以便子 Agent 通过 search_conversation_history 梳理父对话）
• 在撰写前阅读此技能目录中的 references/doc-guide.md 的指示
• 输出路径约定和完成协议

4. 继续处理工作

启动后，继续处理手头的工作，或者结束本轮对话——子任务完成消息会自行到达；收到后，用一句话向用户说明文件路径及其内容。在研究模式下，新对话可能没有其他待处理事项；直接结束本轮对话即可。除非用户要求等待文档，否则不要一直循环等待。

子 Agent 提示词模板

根据需要进行调整；保持结构，并加入与模式相匹配的源材料部分。

You are producing a "readout": a single self-contained HTML document that answers a
specific set of questions about <topic>, for a reader who has none of this context.

Brief:
<brief — including the questions to answer, depth, and audience>

Source material (snapshot mode):
- The parent conversation: agent run ID <current_run_id>. Use search_conversation_history
  with agent_run_id set to that ID. Make several targeted queries — one per question in
  the brief — rather than one broad query; targeted queries surface far more usable detail.
- The codebase(s) at <absolute paths>. The conversation is your starting point, not a cage:
  verify file references before asserting them, and where a section needs more depth to
  stand on its own, go read the code and fill the gap.

Source material (research mode):
- Investigate directly in the codebase(s) at <absolute paths>. Let the brief's questions
  drive the investigation: trace the actual code paths, read the real implementations, and
  ground every claim in file:line references. Distinguish verified from inferred. Do not
  pad the document with generic knowledge — its value is what's true of THIS codebase.

- Repo host + commit for linked code references, if known: <github.com/org/repo @ commit>
  (otherwise derive from git; see the doc guide's "Linked code references").

Start from the canonical template at <skill-directory>/assets/template.html — its
data-readout chrome blocks must be copied verbatim so every readout looks like every
other. Before writing, read <skill-directory>/references/doc-guide.md and follow it.

Output:
- Write ONE self-contained HTML file to ~/.readouts/<YYYY-MM-DD>-<topic-slug>.html
  (create ~/.readouts if it doesn't exist; suffix -2, -3, ... if the name is taken;
  get the date from `date +%F`).
- Embed referenced source per the doc guide when a repo is checked out
  (<skill-directory>/scripts/embed_snippets.py).
- Refresh the readouts index: python3 <skill-directory>/scripts/update_index.py
  (fully regenerates ~/.readouts/index.html listing every readout).
- When the file is written, open it with `open <path>` (skip this if the environment is
  headless).
- Report back to your orchestrator: the absolute file path, a 2–3 sentence summary of what
  the document covers, and anything you could not verify.

后备方案

• 无法启动子任务或启动请求被拒绝：按照 references/doc-guide.md 自行生成文档。如果有可用的研究子 Agent，请将对话挖掘或代码调查任务委派给它，以保持自身上下文精简。
• 子 Agent 无法搜索对话历史（快照模式；它会报告此情况）：向子 Agent 回复经过提炼的调查结果，供其继续处理——这是唯一适合在提示词中直接传递内容的情况。
• 用户提供的材料，而非对话（文字稿、文件、链接）：将这些材料作为来源；工作流程的其他部分保持不变。