Human Feedback
將任何 HTML 頁面轉換為使用者可以註解的頁面：左側有大綱，右側有他們針對正在查看內容的筆記，以及一個複製按鈕：空白時顯示 複製我的回饋，在首次複製前顯示 複製 N 則筆記，之後顯示 複製 N 則新筆記 或 再次複製。使用者將複製的文字貼到對話中；你來應用它。每次按鍵都會儲存在他們的瀏覽器中。
此版本不發送使用計數。
- Claude Code 和 Codex 都可以載入此檔案。
allowed-tools是 Claude Code 的欄位；Codex 會忽略它。 $SKILL_DIR表示載入此 SKILL.md 的資料夾（例如~/.claude/skills/human-feedback或~/.codex/skills/human-feedback）；將該文字路徑寫入指令中。每個 shell 呼叫都是一個新的 shell。- 在 Codex sandbox 中，
add_notes.py會透過show.py開啟頁面，後者會使用 AppleScript 驅動 Chrome，可能需要批准：要求批准，而不是跳過步驟 3。 - 他們的頁面在每個步驟的行為（你的游標、每輪的開啟、Received 和 Done）記錄在
references/what-the-user-sees.md中：當使用者詢問頁面如何運作時，請閱讀該檔案。
使用時機
- 你要求使用者審查、批准或從你製作的內容（報告、計畫、草稿、模型、選項、提議的規則）中選擇，或者他們要求審查 → 在未經要求的情況下，將其放到此頁面上。
- 內容尚未是頁面 → 從中建立純 HTML 並保留原始檔案作為來源。
- 不需要審查頁面的獨立問題則留在對話中。
- 在筆記中回答使用者的問題。 對提出問題的筆記使用
--reply，即使它也要求更改。將更改、較長的說明和你自己的審查問題放在頁面的相關部分。僅在使用者要求時，才使用--ask或--again來建立帶有你問題的氣泡。 - 一旦頁面準備好讓使用者註解，以及在後續每一輪中：如果
inbox-for-human在你的可用技能清單中（其名稱，可能帶有外掛前綴），請使用技能工具載入它（在 Codex 中，開啟其技能清單指向的SKILL.md）並將頁面加入佇列。如果不在清單中，則說一次：「已在沒有 inbox-for-human 技能的情況下執行，該技能會將此頁面保留在審查清單上。」
首次使用
在設定的第一個頁面之前，執行 python3 "$SKILL_DIR/scripts/self_check.py" 並以純文字傳遞其訊息。通過後不要重新執行；腳本會記住檢查已通過。需要時使用 --force 重新執行。
如果你完全無法在此執行指令，請不要嘗試。確切地說：「human-feedback 無法在此模式下運作，因為我無法在此處理你電腦上的檔案。在 Claude 桌面應用程式中，開啟「程式碼」標籤並選擇「本機」工作階段。在 ChatGPT 桌面應用程式中，切換到 Codex 並保持在本機模式。」
退出碼 2，或該訊息，表示停止：不要嘗試建立頁面。退出碼 1 會產生一個使用者可以自行開啟檢查的檔案。
1. 標記各部分
在使用者可能作為一個單元註解的每個部分上放置 data-note：卡片、區段、選項、表格行。標籤來自該部分的第一個標題，因此單純的 data-note 通常就足夠。沒有標題，或其標題與另一個部分重複的部分，會獲得自己的標籤：data-note="選項 B · 冷靜"。標籤在頁面上必須是唯一的。
一個從其自身腳本繪製部分的頁面也會在這些部分上獲得註解，只要腳本立即繪製它們，而不是在後續事件（如 DOMContentLoaded 或點擊）上繪製。不要將它們複製到 HTML 中；步驟 2 的計數僅涵蓋寫入其中的部分。
標記 <iframe> 中顯示的本地頁面周圍的部分。步驟 2 會標記框架頁面，使其文字提供「註解」、「編輯」和「反白」。審查頁面會儲存回饋，並在複製的編輯中命名框架來源。
永遠不要標記供使用者填寫或重寫的文字，也永遠不要要求使用者編輯頁面：使用者隨時可以自行重寫任何一行，方法是使用點擊或選取時彈出的選單中的「編輯」（⌘Z 可以復原編輯）。改為提出問題（步驟 6）。
不要自行建立註解框、輸入欄位或複製按鈕。圖層會處理所有這些。
左側的大綱已經是頁面的導覽：它列出每個部分，將各部分外部的區段標題顯示為標題，標記正在檢視的部分，並跳轉到頁面自身頂部欄之外的部分。在為頁面提供其自身的導覽（區段標籤、內容清單、跳轉連結、帶有上一步和下一步的步驟計數器）之前，判斷什麼對使用者最簡單，這樣使用者就不會遇到兩種方式來做一件事：
- 它只會重複大綱 → 省略它。將各部分和區段標題命名為其按鈕本來會說的內容。
- 它做了大綱無法做到的事情（深色/淺色切換、篩選器、逐部分捲動單一頁面的上一步和下一步按鈕）→ 只保留那部分。
- 它以標籤或其他隱藏面板顯示部分 → 使其成為一個連續捲動的頁面。使用者要求使用標籤 → 標記它們，不要寫其他任何東西：一個
role="tablist"包含<button role="tab" aria-controls="…">，每個按鈕命名一個role="tabpanel"，然後像往常一樣在面板內放置data-note部分。圖層會切換面板、繪製一個簡單的固定欄、在大綱中將每個標籤列出為其層級結構的一部分、它在頁面上的位置、在重新載入和版本之間保持開啟的標籤、為大綱行、步驟器或其中的#連結開啟一個標籤，並保留一個執行緒直到其標籤開啟。具有自己標籤腳本的頁面會保留它，而帶有class的標籤清單會保留頁面自身的樣式。 - 每個頁面從其第二輪開始獲得版本（步驟 5）→ 不要綁定 ← 和 → 鍵；版本步驟器會使用它們。
掛載點，適用於任何託管圖層的頁面（由其他技能或手動製作的頁面）：
data-note部分為大綱和註解欄提供內容，如上所述。- 一旦圖層繪製完成，
data-notes-layer會設定在<html>上，並且在沒有圖層的頁面上不存在。主機頁面使用它來隱藏其自身的大綱，或僅在沒有圖層時才有意義的行，這樣使用者就不會看到兩個：html[data-notes-layer] .its-outline { display: none; }。沒有東西可以關閉圖層，因此標記會保留。不要依賴圖層添加的任何其他內容。
2. 啟用註解
python3 "$SKILL_DIR/scripts/add_notes.py" <page.html> --agent "Claude"
它會在 </body> 之前添加一個標籤，列印輪次和部分計數，並透過 show.py 開啟頁面。重新執行、--next-round 和新版本的後續執行也會開啟它；單獨的 --new-version、--received 和 --converged 則不會。如果開啟失敗，頁面會保持就緒狀態，並列印原因和手動開啟的指令。在第一輪，它還會在頁面的 head 中放置一個小型樣式，使頁面保持隱藏直到圖層繪製它。重新執行會取代標籤，因此在重寫頁面後再次執行它。如果出現關於沒有部分或重複標籤的警告 → 修正標記並重新執行。
-
--hold：準備好頁面但不開啟它，同時你建立或檢查它，或者當使用者只要求連結時（步驟 3）。 -
--pictures off：為與其他人共用或公開建置的頁面停用圖片附件；後續執行會保留此設定。 -
--agent：你的名稱，就像人們知道的那樣。Claude Code 傳遞Claude，Codex 傳遞Codex，任何其他代理人傳遞其自身的產品名稱。一個帶有該名稱和你標誌的游標會在你的部分在他們的頁面上執行：它會輸入你的訊息，並點擊其註解欄的狀態（步驟 4 中的 Received 和 Updating，步驟 8 中的 Done）。後續執行會保留此名稱，因此在第一次執行時傳遞它。 -
--helper "<name>"和--owns "<name>:[Part label]"：另一個代理人製作了頁面的部分（你發送的子代理人、Codex，或任何非你本人）。每個助手命名一次，就像人們知道的那樣，以及它製作的每個部分使用--owns，標籤如大綱所示；兩者都會重複，最多三個助手。你仍然是主要負責人（--agent）。在頁面上，每個代理人的游標只執行它擁有的部分。後續執行會保留它們；帶有任一旗標的執行會取代它們；新版本從無開始，因此如果其部分仍然是他們的，請在後續執行中再次傳遞它們。如果你製作了所有內容 → 兩者都省略。python3 "$SKILL_DIR/scripts/add_notes.py" <page.html> --agent "Claude" --helper "Codex" --owns "Codex:[選項 B · 冷靜]" -
--workspace <dir>：你的工作區（你工作的專案資料夾）。每次執行都會建立<dir>/human-feedback/attachments/（如果缺少），並在human-feedback/中建立一個標記檔案；頁面會將使用者附上的圖片儲存在那裡，在使用者先在 Chrome 中選擇該human-feedback資料夾之後，並且頁面的提示會命名你（「在 Claude 的工作區資料夾中，選擇 human-feedback 子資料夾…」）。沒有它：使用頁面的儲存庫，否則使用你當前目錄的儲存庫，否則使用當前目錄。後續執行會保留標籤命名的資料夾。 -
頁面是透過 http 提供服務（它使用
fetch、模組或../資產）→ 添加--copy，這會將human-feedback.js放在頁面旁邊。後續執行、重寫和新版本會保留它，並會告知。 -
永遠不要將
human-feedback.js貼上或內嵌到頁面中，也永遠不要讀取它：標籤就是頁面所需的一切。 -
將關於頁面的問題放在它們所涉及的部分中（步驟 6）。
外觀
- 預設跟隨系統外觀。當審查的材料是共享閱讀樣式中的散文，或者當使用者要求控制項時，提供自動、淺色和深色選項。在其他審查中則關閉它。
- 當提供控制項時，如果閱讀欄已經有兩種色調並且你可以檢查兩者，則使用
--appearance page。在同一頁面中重複使用它們。對於具有獨立主題、未經測試的色調或外觀是審查一部分的頁面，使用--appearance sidebars僅切換大綱和註解欄。保持螢幕截圖和嵌入內容不變。 - 在閱讀欄的 CSS 中，
html[data-notes-layer="light"]和html[data-notes-layer="dark"]是明確的選擇。保留用於自動模式和頁面在沒有圖層時開啟的系統媒體查詢。使用者的選擇會在這次審查的各輪次之間保留。其他審查則從自動模式開始。 - 重新執行或由
--new-version複製的版本會保留此設定。傳遞--appearance off以移除控制項，或者在從頭開始重建檔案時再次傳遞預期的設定。
3. 顯示它
對於任何類型的審查，在每一輪中：
- 一旦審查準備就緒，就在每一輪中在使用者的瀏覽器中開啟它。當開啟器在較早的輪次中找到該標籤時，它會在 Chrome 中重複使用現有的標籤。在建立或檢查頁面時使用
--hold，或者當使用者明確只要求連結時使用。 - 對於本地審查，使用不帶
--hold的add_notes.py完成。在專用資料夾中，其資產位於該資料夾內的新審查，會為所有輪次使用一個本地網頁位址，因此瀏覽器會保留其頁面縮放和註解。將輪次及其資產保留在該資料夾或其子資料夾中，並使用相對資產路徑。連結開啟器列印的審查位址。 - 對於已經透過 HTTP 提供服務的頁面，使用
--hold --copy準備，並執行show.py <local page.html> --preview-url <new round's HTTP URL>。在各輪次之間保持相同的預覽伺服器，以便開啟器可以找到現有的標籤，並且瀏覽器可以保留使用者的註解。 - 在每一輪的回覆中放置頁面的連結。使用你的專案連結格式，並使用開啟器的結果來說明頁面的位置。如果開啟器失敗或表示它讓頁面保持關閉狀態，請說明原因並提供連結。
- 使用者從
file://開啟的較早輪次或版本的頁面 → 繼續從file://顯示它（show.py在其路徑上），並且不提供 localhost 連結，即使專案要求一個：瀏覽器會按位址保留使用者的回答，因此 localhost 副本不會顯示任何回答，並會重新開啟他們關閉的執行緒。在回覆中說明為什麼沒有連結。
僅在頁面準備好讓使用者註解時才執行此操作。
一旦頁面準備好讓使用者註解，就執行不帶 --hold 的 add_notes.py。先完成頁面內容並標記每個部分。在該執行中傳遞任何「完成」標記和使用者要求的任何氣泡（新版本的步驟 5 的後續執行）。
你告訴過使用者正在進行的修正也會保留到下一個版本。一旦該修正生效，就顯示它。
對於檢查，使用 --hold 準備，然後在啟用註解圖層的情況下自行檢查（或讓子代理人截圖），因為圖層會縮小頁面，並修正你發現的問題。你的訊息（問題、回覆）僅在標籤具有焦點時才會出現，而無頭瀏覽器除非焦點模擬已開啟（tests/harness.mjs 會開啟它），否則永遠不會讓它獲得焦點。沒有它，請改為檢查標籤資料中的訊息，而頁面本身在其開啟畫面後面保持空白：使用閱讀頁面格式的 shoot_page.py 來拍攝它，它會截圖然後刪除一個不帶標籤及其保持樣式的裸複本。該裸複本會填滿整個視窗，但在他們的螢幕上，註解欄每邊約佔 375px（在 2560 寬度下測量，2026-11-01）。因此也要在該較窄的寬度下拍攝它，並在顯示之前修正任何換行或溢位。裸複本無法顯示覆蓋頁面的欄，因此也要載入帶有圖層的保持頁面，並檢查 document.querySelector('h1').getBoundingClientRect().left 是否在大綱邊緣的右側；在沒有 h1 的頁面上，第一個文字元素也可以。只有這樣才能使用上面的本地或 HTTP 指令開啟頁面。告訴使用者頁面已準備好讓他們註解，它在哪裡（開啟器列印的那行），並讓他們貼上「複製」按鈕提供的內容。如果你問了問題或留下了回覆，請說明頁面中有多少正在等待。
一旦頁面顯示出來，將對話保持在就緒行、連結以及任何阻止頁面開啟的內容或其他技能所需的行。將更改、發現、來源、注意事項、檢查和問題放在它們所涉及的部分中。當頁面有「更多資訊」時，使用它來提供來源和詳細資訊。
你框架的頁面會攜帶框架標籤，因此當單獨開啟時，它會顯示註解欄並被壓縮，對它的檢查會報告錯誤的缺陷。改為從你暫存區中的裸複本檢查它：移除保持樣式
…
[已截斷以進行翻譯]