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 文件，回答關於 <topic> 的一組特定問題，
讀者對此沒有任何背景知識。

簡報：
<簡報——包含要回答的問題、深度與受眾>

素材（快照模式）：
- 父對話：代理執行 ID <current_run_id>。使用 search_conversation_history，
  並將 agent_run_id 設為該 ID。進行多次有針對性的查詢——每次查詢對應簡報中的一個問題——
  而非一次廣泛查詢；有針對性的查詢能挖掘出更多可用的細節。
- 程式碼庫位於 <絕對路徑>。對話是你的起點，但不是限制：在引用檔案前先驗證，
  當某個章節需要更多深度才能獨立存在時，直接閱讀程式碼並補足缺口。

素材（研究模式）：
- 直接在位於 <絕對路徑> 的程式碼庫中進行調查。讓簡報中的問題驅動調查：
  追蹤實際的程式碼路徑，閱讀真實的實作，並將每個主張建立在 file:line 參考上。
  區分已驗證與推測的內容。不要用一般知識填充文件——其價值在於對**這個**程式碼庫為真的事實。

- 用於連結程式碼參考的儲存庫主機與提交（如果已知）：<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。如果研究子代理可用，將對話挖掘或程式碼調查委派給它，以保持你的上下文精簡。
• 子代理無法搜尋對話歷史（快照模式；它會回報此情況）：回覆子代理，提供一份精煉的發現摘要，以便它繼續進行——這是唯一一種將內容放入提示是正確做法的情況。
• 使用者提供素材而非對話（例如逐字稿、檔案、連結）：將該素材視為來源；工作流程的其他部分保持不變。