結構化報告
一個獨立的 HTML 檔案（無需網路），讓忙碌的讀者能夠
- 將整個工作視為一個任務地圖，並查看每個任務內部有哪些事項等待處理，
- 展開任何任務及其內部的任何階段，審計其如何完成以及為何相信每個斷言，
- 直接在報告中回答代理的提問，並查看他們的哪些提示產生了哪些結果。
結構 vs. 內容
- 結構屬於模板 (
assets/template.html)：佈局、區段名稱（問題、任務、背景資訊、結論、假設、結果、未檢查事項、工作流程、需要核准、您的行動）、它們的順序、狀態、每個圖示和每個 UI 標籤。固定不變，始終為英文。圖示僅標記結構，絕不涉及內容主題。 - 內容是您的：JSON，使用使用者的語言。
scripts/build.py會驗證 JSON 並填入模板的佔位符。您無需編寫 HTML，也無需發明區段。
工作流程
- 收集素材：訊息、工具結果、檔案、指令、連結、測試、度量、決策。僅報告實際發生的情況。
- 將其劃分為任務（1–12 個）：一個任務 = 一個具有自身成果的目標。使用
links連接它們：depends、blocks、related。 - 依照下方規則和
references/schema.md填寫每個任務。 - 編寫 JSON — 預設為工作目錄中的
reports/<YYYY-MM-DD>-<slug>.json。 - 建構：
python3 <skill>/scripts/build.py <file>.json→<file>.html。修正每個error:；閱讀每個warning:並修正它，除非它確實是事實。 - 在本機開啟（
open/xdg-open/start）並提供路徑。切勿上傳。 - 在對話中：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。偏好 repo / 網頁 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）。 - next steps are planned stages — 任何仍待完成的事項都是一個帶有
status: "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 個提示的日誌。