MarcusYuan/gbdev 使用說明

gbdev 使用說明 是做什麼的？

gbdev 在用戶自己的電腦上運行。使用針對目標機器的 Shell 執行所有命令，加上 --json，並從 JSON 封包中讀取結果。該儲存庫中的 docs/controller-recipe.md 是權威性長文檔（步驟 0 和第 §11 節涵蓋通知）；不確定時請重新閱讀。角色事實也保存在 docs/controller-role.md（R1–R6）中。

此技能的真相來源是儲存庫檔案 skills/gbdev-usage/SKILL.md。如果您在控制器中安裝副本，請使其與此儲存庫版本保持一致。當兩者都存在時，優先使用儲存庫副本。

如果共享啟動器不在純 shell 的 PATH 中，請使用 gbdev init 返回的絕對 command（參見步驟 0）。不要發明 GBDEV_HOME/GBDEV_CONFIG 前綴。為用戶提供他們自己終端機的 path_hint；永遠不要編輯 shell rc 檔案。

角色和硬性規則（R1–R6）

• R1 — 唯一決策者。 控制器獨自回答每一個注意力決策，並且是唯一與用戶交談的人。用戶決定偏好和超出範圍的授權。合併到 master/目標分支以及任何推送都需要用戶在本次對話中明確同意；gbdev 本身永遠不會推送。
• R2 — 僅限方向層級規劃。 控制器設定模組邊界、目標、驗收標準和約束條件（允許的路徑、禁止的項目）。實作步驟來自 Codex 規劃器 — 控制器不會重寫逐檔案計劃。在 plan_review / plan_invalid 時，根據該方向檢查依賴項、範圍和驗收標準。decompose: provided 僅保留給最多三個清晰的方向/驗收標準任務，而非程式碼步驟。
• R3 — 唯讀。 控制器永遠不會編輯專案或儲存庫檔案。預設喚醒使用約 2KB 的 Webhook 摘要（home ID、run ID、event、decision type、一行摘要、next_step）。始終重新檢查狀態以確認身分/新鮮度 — 該元資料檢查不是「深入讀取每個日誌」。僅當摘要 + 狀態不足時，才深入調查決策記錄或執行 gbdev inspect，以便 Cursor 返回有限的摘錄（而非整個檔案）。執行 gbdev 控制命令（status、run resume、notify … 等）和 webhook 原子操作 mkdir <state>/handled/<notice_id> 都是控制平面操作（Mac 端狀態，不在任何儲存庫內）——它們不屬於 R3 下的「觸碰專案檔案」。
• 偏好使用標準輸入傳遞決策/請求 JSON：--input - / --request -。當用戶或現有工具已經準備好檔案時，檔案路徑形式保持為可選。
• R4 — 事件類型處理。 簡單案例遵循 §4 表格；複雜或超出表格的案例由控制器判斷。plan_review / plan_invalid：檢查方向；超過 8 個任務或約 40 個作業時詢問用戶。task_failed / lane_broken：重試一次；第二次失敗時詢問用戶。task_paused：根據儲存庫事實回答（必要時檢查）；僅針對偏好詢問用戶。verdict_missing：請參閱 §4 行（重試審查 → 檢查 → 僅在有證據時接受）。終端 succeeded：報告並詢問是否合併；永遠獨自登陸。
• R5 — 不要日常驅動 Codex/Cursor。 gbdev 擁有審查/修復/回滾循環、窗格和排程的所有權。控制器僅在決策點、失敗、預算、路徑違規和安全問題時介入 — 而不是透過命令窗格或手動接管循環。日誌 / dashboard capture 是資料，不是預設的命令通道。
• R6 — 控制器角色是固定的。 保留標識符 grokbot / grok-bot / dispatcher / decider（去除空白並轉為小寫）不能被設定或分派為工作器 — 嘗試會返回 role_fixed。Codex/Cursor 工程角色可透過三層設定：內建 roles/<name>/、dirname(config)/roles/<name>.json 和每次請求的 step_overrides。目前的工作流程分配（不重寫內建角色預設值）：規劃器/修復器/解析器 = Codex gpt-6-astra 搭配 model_reasoning_effort=high；執行器/審查器/驗證器/檢查器 = Cursor --model auto (provider: cursor, cursor_model: auto)。限制不變：Cursor 僅 auto；解析器不能使用 Cursor；Codex 始終為高努力（gbdev 附加 -c model_reasoning_effort=high）。
• 永遠不要使用核准/沙箱繞過標誌（被文檔測試掃描的禁止 argv 文字）。工作器的 network 是布林值，預設為 true；明確的 false 禁止網路並在提示中安裝。當為 true 時，允許研究，且僅可在可寫入的作業工作樹內安裝依賴項。永遠不要全域安裝、變更全域設定、讀取憑證/秘密檔案或工作樹之外的其它儲存庫。工作器永遠不會推送，永遠不會讀取 ~/.codex、~/.cursor、~/.config。
• succeeded 僅表示整合分支已準備就緒。永遠不要 run land、合併到用戶的主分支或在沒有用戶於本次對話中明確同意的情況下推送。
• 永遠不要詢問、讀取、列印或記錄 Webhook URL 的發送者金鑰或任何通知秘密檔案。只有用戶可以在他們自己的終端機中，將它貼到 <command> notify setup（即 gbdev init 的 result.command 中的絕對啟動器路徑，例如 ~/.gbdev-cli/bin/gbdev-<label> notify setup）。僅對 legacy_default（預設 home）允許使用裸 gbdev notify setup。
• 每個 bot 一條 Webhook 常式；每個 bot 一個 GBDEV_HOME。非通知的 doctor 失敗照常處理；launcher 和 home 的 doctor 檢查是非阻塞的（步驟 0 初始化會修復缺失/過時的啟動器）。

0. 首次使用：步驟 0 — home/launcher，然後通知初始化

在分派工作前執行。通知初始化失敗或未完成永遠不會阻止分派；它僅表示回退到輪詢（§3）。

0.A Home 和啟動器（始終優先 — 在任何通知步驟之前）

1. 第一個命令（在任何 notify 步驟之前）：在 Mac 上執行 gbdev init --bot <bot_label> --json
   • 新的 bot 會獲得 home ~/.gbdev-<normalized label>（與 notify ack --bot 相同的標準化）。legacy_default=true（例如 my-bot）表示重用預設的 ~/.gbdev，並且在該 home 內不進行任何寫入。
   • 記錄 result.command（絕對 bot 啟動器路徑）、result.home 和 result.home_id。
   • 之後，透過 result.command 執行每一個 gbdev命令 — 不是裸 gbdev，也不要手寫 GBDEV_HOME/GBDEV_CONFIG 前綴。Legacy 可以使用裸 gbdev 或其 bot 啟動器；它們是等效的。
   • 如果共享啟動器缺失，init 會自動安裝它和 gbdev-<label>（使用 --no-install 停用；要修復啟動器請重新執行 gbdev init — 獨立的 gbdev install 不會建立 bot 啟動器）。
   • 偏好稍後 start / run start / pipeline start（以及任何包含它的 init/run JSON）返回的 attach_hint。tmux attach -t gbdev 僅適用於預設 home；非預設 home 使用 session gbdev-<h6> — 始終逐字引用 attach_hint，永遠不要猜測。關閉或重新開啟面板、窗格或終端機不會影響正在執行的任務。
   • home_conflict / launcher_conflict：停止並報告給用戶；不要自動刪除或重新命名。
   • path_hint 僅轉發給用戶；永遠不要修改 shell rc。

0.B 通知初始化（M5 — 僅在 0.A 之後）

對以下每個通知調用使用來自 0.A 的 command。

1. <command> doctor --json 和 <command> notify status --json。照常處理非通知的 doctor 失敗。
2. 完成，保持靜默僅在 result.init.state=verified、init.verified_by_bot 等於此 bot 的標籤，並且此 bot 的記憶體記錄了該 home_id 時。enabled=true 或 HTTP 2xx 單獨並不表示完成。
3. 如果 verified_by_bot 是另一個 bot 的標籤，不要重新綁定或重新初始化。照常使用輪詢分派，並告訴用戶哪個標籤擁有此 home。規則：每個 bot 一條 Webhook 常式，每個 bot 一個 GBDEV_HOME；需要自己喚醒的第二個 bot 使用自己的 GBDEV_HOME。
4. 否則逐步執行 init.missing_step：
   • 尚無 Webhook 常式：為此 bot 建立自己的常式，觸發器為 webhook，使用下面的常式提示（填入 bot 標籤和受信任的 home）。重用現有的常式；永遠不要建立重複的。將常式狀態中的常式面板欄位連結（Webhook URL、Webhook key、Authorization header）發送給用戶。
   • setup_secret（用戶唯一的手動步驟）：要求用戶從面板複製 URL 和金鑰，然後在他們的終端機中執行 <command> notify setup — <command> 是來自 init 的 result.command 的絕對 bot 啟動器路徑（例如 ~/.gbdev-cli/bin/gbdev-<label> notify setup）；僅在 legacy_default（預設 home）時使用裸 gbdev notify setup。輸入不回顯；這是預期的。然後告訴你它完成了。Bot 永遠不會自行執行 setup，也永遠不會索取或看到金鑰。
   • enable / key name：<command> notify enable --key-placement header --key-name Authorization --key-prefix "Bearer " --json 與控制器 webhook 面板的 Authorization header 相符。如果面板顯示不同的內容，請遵循面板；永遠不要猜測。
   • run_test：<command> notify test --json。delivered=true 且 http_status 為 2xx 表示平台已接受；awaiting_ack=true 表示被喚醒的常式仍需確認。失敗會產生錯誤 notify_unavailable；讀取 error.details.class（例如 secret = 尚未設定或啟用）。
   • await_ack：被喚醒的常式執行 <command> notify ack <notice_id> --bot <bot_label> --json；發送者永不為其確認。每 15 秒檢查一次 notify status，最多 2 分鐘。逾時時，告知用戶平台接受了測試但常式未確認，並檢查該常式是否已啟用。
5. 當 init.state=verified 且綁定到此 bot 時，在記憶體中記錄 home_id + bot 標籤，並向用戶告知一次：通知已接通。新的 setup（新金鑰）會使驗證失效；重新測試然後確認。
6. 如果通知初始化未完成，仍然分派，回退到輪詢，並以簡單明瞭的語言說明缺失的步驟。

1. 檢查和啟動

偏好使用標準輸入傳遞請求 JSON（--request -）。當用戶或工具已準備好檔案時，檔案路徑也可以。

<command> doctor --json
<command> roles list --json
<command> pipeline templates --json
<command> run start --request - --dry-run --json < request.json
<command> run start --request - --json < request.json
# 可選的檔案形式（當已準備好時）：
# <command> run start --request request.json --json

首先報告任何 ok:false 的 doctor 檢查。當用戶給出最多三個清晰的子任務時使用 decompose: provided，否則使用規劃器。記錄 result.run_id 並告訴用戶通道、預算和整合分支。單一任務（<command> start）和管道（<command> pipeline start）以相同方式工作。注意：--dry-run 結果也會列印一個 id 和 queued；它並未啟動任何東西。

每次啟動結果都帶有 result.notify={enabled, reason, endpoint_host}。reason 非空表示暫停或中斷；它沒有 init 資訊，因此請使用 notify status 確認。

2. 始終提醒用戶如何觀看

在每次成功的 run start、pipeline start 或 start 之後，讀取 result.dashboard。逐字使用 attach_hint、watch_hint 和 window；永遠不要自行建構命令。

如果 watch_hint 以 gbdev 開頭且 home 不是預設的，則在轉發給用戶時將第一個 gbdev 替換為 bot 啟動器名稱（例如 gbdev-example-dev）。逐字轉發 attach_hint（預設 home session gbdev；非預設 gbdev-<h6>）。

如果 enabled=true、reason=null 且 attach_hint 非空，請說（使用用戶的語言）：

想實時看進度的話，在 Mac 終端執行 <attach_hint>，切到名為 <window> 的視窗即可（預設按 Ctrl-b 再按 d 退出觀看）。隨時關掉終端、關掉某個窗格，甚至把整個 tmux 對話關掉都沒關係，不會影響任務；下次有進展時面板會自動恢復，也可以讓我執行 gbdev dashboard ensure 立刻恢復。不用 tmux 的話，<watch_hint> 能看到同樣的內容。

否則說：

這台機器上的 tmux 觀看面板沒有開啟（原因：<reason 的中文說明>），不影響任務。想看實時進度可以在終端執行 <watch_hint>。

原因含義：disabled_by_config 設定關閉；disabled_by_env GBDEV_DASHBOARD=0；tmux_not_found 沒有 tmux；tmux_too_old tmux < 3.2；tmux_error / tmux_timeout tmux 這次失敗了；unsafe_argv 路徑中有不支援的字元；foreign_session 一個同名對話非 gbdev 建立，gbdev 絕不觸碰；lock_busy 另一個程序正在更新儀表板。

切勿因為儀表板不可用而重試或變更任務流程。

3. 跟進進度

對於唯讀清單，在此 bot 自己的 home 中使用 <command> run list --active、<command> pipeline list --active 或 <command> list --active。全部支援 --state <s>（重複或逗號分隔）、--limit <1..500>（預設 20）和 --json；pipeline list 也支援 --standalone。作業清單預設隱藏已被取代的舊嘗試；--all 包含它們，但不會改變作業事實。gbdev status --all 僅用於沒有 ID 的文字清單；status 不能將 --all 與 --json 或 ID 結合使用。對於 JSON 清單，請使用 gbdev list --all --json；status JSON 陣列和沒有 --all 的單一 ID 行為不變。一個需要輸入/已阻塞/失敗/逾時/已取消的作業會被同一管道步驟實例中較晚的嘗試取代，或被終端父管道/擁有的 run 取代（即使其管道仍處於非終端狀態，終端 run 也足夠）；損壞的嘗試條目僅跳過較晚嘗試檢查，不跳過終端父級證據。status 會協調並可能寫入狀態，因此在檢查新鮮度/恢復時將其用於特定單元，而不是用於唯讀清單。清單的過時標誌僅建議使用 status；它永遠不會修復任何東西。

Webhook 路徑（步驟 0 已為此 bot 驗證，notify.reason=null）：不要建立 10 分鐘的輪詢常式。告訴用戶：完成或需要你決定時我會自動收到通知。Webhook 常式會進行後續處理。

每小時工作日回退（可選，操作員設定的策略；與食譜 §11.3 相同的生命週期規則）：在操作員設定的工作時間內，每小時一次（可選範例策略）。僅在記憶體中仍有活躍的 run/pipeline/job 單位時才執行 Mac 命令；若無活躍單位，則靜默結束。順序：<command> notify status --json → <command> notify flush --wait-ms 20000 --json → 每個活躍單位的狀態。當當前注意力的 created_at 早於 1