human-in-the-loop

Human in the Loop

專案負責人與 AI 代理之間的一次性介面層。代理描述負責人需要查看和決定的內容，腳本構建一個自包含的 HTML 頁面，負責人在瀏覽器中以任意順序回應並返回 JSON。頁面無需手動編寫：只需 spec.json 和 scripts/build.py。

$SKILL 下方指的是此文件所在資料夾。

何時使用

• 文件批准：規格、PRD、提案、計畫。按區塊顯示狀態、就地編輯文字、回答開放問題。
• 同時根據多個問題從選項中進行選擇，每個問題都有代理提供的選項和自己的答案。
• 盲標記基準：負責人回答，模型答案儲存在單獨檔案中且不顯示在頁面上，然後 score.py 計算匹配度。
• 按量表評估提案。

如果只有一兩個問題，請在聊天中詢問。

流程

1. 規範。 收集 spec.json（格式：references/spec-format.md）。對於 Markdown 文件，有一個模板： python3 $SKILL/scripts/from_markdown.py doc.md --options options.json -o spec.json （## 和 ### 區塊變成可編輯區塊，「開放問題」區塊變成帶有 options.json 中選項的問題）。 對於盲標記，將隱藏答案放入單獨的 sidecar.json，spec.json 中不應包含它們。
2. 頁面。 python3 $SKILL/scripts/build.py spec.json -o page.html 構建並開啟頁面。將 spec 和頁面放在專案附近（例如 private/），而不是 scratchpad，以便負責人可以返回。用一句話告訴負責人打開了什麼以及需要他做什麼。
3. 負責人 回應並將 JSON 貼到聊天中（「複製 JSON 給代理」按鈕）。JSON 僅包含他修改過的內容：status、comment、markdown_old/markdown_new、answers、notes，加上 decision 和 general_comment。
4. 代理應用 根據 JSON 中的 task 欄位回應，並報告：修改了什麼，還有什麼未處理。如果存在決策按鈕但 decision 為空，則表示決定尚未做出：重新詢問，不要認為文件已批准。對於標記：儲存 JSON 並執行 python3 $SKILL/scripts/score.py labels.json sidecar.json --spec spec.json。 以列表形式向負責人顯示差異，不要自行修正標記錯誤。

如果 spec 發生變化，頁面會使用新版本重新構建，瀏覽器中之前的回應不會應用於新版本。

測試

python3 $SKILL/tests/selftest.py [資料夾] 構建 examples/ 中的兩個範例，在 headless Chromium 中運行它們，並檢查輸出。在對模板或腳本進行任何更改後執行此操作。