readout

Readout

Readout将一次调查转化为一份持久的HTML文档，即使几周后阅读，也无需任何原始上下文。它通过以下两种方式之一启动：

• 快照模式 —— 在对话过程中调用（例如“write this up”）：对话中积累的发现作为源材料。
• 研究模式 —— 全新调用（例如“/readout on how github webhook events are processed in the server”）：没有可挖掘的对话，因此调查本身成为任务的一部分。

无论哪种方式，调用此技能都是一个侧任务。作为主代理，你的工作是明确范围，向子代理提供一份良好的简报，然后退出——子代理负责挖掘/研究和写作，将这些（通常较大的）工作排除在你的上下文窗口之外。

编排器工作流程

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

模糊的简报会产生模糊的文档。在启动之前，你应该能够列出文档将回答的具体问题；如果不能，先与用户沟通：

• 提出2-4个有针对性的问题，提供具体选项而非开放式提示——先快速查看代码或主题，使选项真实可行（子系统、入口点、竞争关注点）。对于“/readout on how github webhook events are processed”：哪个方向重要——入站触发、回发，还是两者？当前状态参考还是陷阱排查？哪些仓库？
• 始终确定深度和受众：高层概述 vs. 带有行级基础的深层机制；个人笔记 vs. 团队共享。
• 尊重用户的随意态度。“只是一个高层概述”是有效答案——在简报中记录下来并继续，而不是追问。即便如此，尝试提取读者最需要回答的两三个问题；具体性正是readout的价值所在。
• 当范围已经具体时跳过提问——例如聚焦对话的快照，或精确的研究请求，无需提问。在快照模式下，对话通常提供了问题；仅当调用对包含哪些线程存在歧义时才提问。

2. 编写简报

编写一份简短的简报（大约10-20行），包含指针，而非负载：

• 工作标题/主题，以及模式（快照或研究）
• 文档必须回答的具体问题（来自对话或访谈），以及深度和受众
• 范围：涵盖哪些线程/子系统，以及明确排除的内容
• 快照模式：值得作为文档中心的主要结论，每行一个——子代理自行从对话历史中提取完整内容，因此不要粘贴全部发现
• 研究模式：起始指针——你已经知道的入口点文件、符号或目录
• 支撑工作的仓库/目录的绝对路径
• 每个仓库的托管URL和检查的提交（如果已知，例如github.com/org/repo @ abc123），以便文档可以超链接代码引用

3. 启动一个本地子代理

通过run_agents生成恰好一个子代理，本地执行。本地执行很重要：文档将保存在用户文件系统上并在浏览器中打开。将子代理命名为readout-<topic-slug>。

根据下面的模板构建子代理的提示。它必须包含：

• 简报
• 与模式匹配的源材料块（快照模式还需要你的代理运行ID——来自编排运行时上下文的current_run_id——以便子代理可以使用search_conversation_history挖掘父对话）
• 指示在写作前阅读此技能目录下的references/doc-guide.md
• 输出路径约定和完成协议

4. 返回工作

启动后，恢复你正在做的事情，或结束你的回合——子代理的完成消息会自行到达；当它到达时，将文件路径和一行描述转发给用户。在研究模式下，新对话可能没有其他待办事项；只需结束回合。除非用户要求等待文档，否则不要处于等待循环中。

子代理提示模板

根据实际情况调整；保持结构，并包含与模式匹配的源材料块。

你正在生成一份“readout”：一份自包含的HTML文档，回答关于<主题>的一组特定问题，面向没有任何上下文的读者。

简报：
<简报——包括要回答的问题、深度和受众>

源材料（快照模式）：
- 父对话：代理运行ID <current_run_id>。使用search_conversation_history，并将agent_run_id设置为该ID。进行几次有针对性的查询——每次查询对应简报中的一个问题——而不是一次宽泛的查询；有针对性的查询能提供更多可用的细节。
- 位于<绝对路径>的代码库。对话是你的起点，而非限制：在断言文件引用之前先验证它们，并且当某个部分需要更多深度才能独立时，去阅读代码并填补空白。

源材料（研究模式）：
- 直接在位于<绝对路径>的代码库中进行调查。让简报中的问题驱动调查：追踪实际的代码路径，阅读真实的实现，并将每个断言建立在文件:行引用上。区分已验证和推断的内容。不要用通用知识填充文档——其价值在于对当前代码库的真实性。
- 用于链接代码引用的仓库主机和提交（如果已知）：<github.com/org/repo @ commit>（否则从git派生；参见文档指南的“链接代码引用”）。

从<技能目录>/assets/template.html中的规范模板开始——其data-readout chrome块必须逐字复制，以便每个readout看起来都一样。在写作前，阅读<技能目录>/references/doc-guide.md并遵循它。

输出：
- 将一份自包含的HTML文件写入~/.readouts/<YYYY-MM-DD>-<topic-slug>.html（如果~/.readouts不存在则创建；如果名称已被占用，则添加后缀-2、-3等；从`date +%F`获取日期）。
- 当仓库已检出时，根据文档指南嵌入引用的源代码（<技能目录>/scripts/embed_snippets.py）。
- 刷新readouts索引：python3 <技能目录>/scripts/update_index.py（完全重新生成~/.readouts/index.html，列出所有readout）。
- 文件写入后，使用`open <path>`打开它（如果环境是无头的，则跳过此步骤）。
- 向你的编排器报告：绝对文件路径、文档涵盖内容的2-3句摘要，以及你无法验证的任何内容。

回退方案

• 子代理生成不可用或被拒绝：自行生成文档，遵循references/doc-guide.md。如果研究子代理可用，将对话挖掘或代码调查委托给它，以保持你的上下文精简。
• 子代理无法搜索对话历史（快照模式；它会报告此问题）：向子代理回复一份提炼后的发现摘要，以便它继续——这是唯一一种在提示中传递负载的正确情况。
• 用户提供材料而非对话（转录、文件、链接）：将该材料视为源材料；工作流程中的其他所有内容不变。