Herdr
Herdr 將終端組織成工作區、分頁與窗格，辨識窗格內運行的編碼代理，並透過 herdr CLI 暴露當前工作階段。
在發出任何控制命令之前，請先確認此代理正在 Herdr 管理的窗格內執行：
test "${HERDR_ENV:-}" = 1
如果檢查失敗，請說明您不在 Herdr 內部並停止操作。請勿從 Herdr 外部檢查或控制焦點內的 Herdr 工作階段。
當檢查通過時，PATH 中的 herdr 二進位檔會與當前工作階段通訊。用它來檢查鄰近的工作、建立終端佈局、啟動代理與命令、讀取輸出及等待狀態變更。
學習當前 CLI
已安裝的二進位檔是命令語法的權威依據。從以下指令開始：
herdr --help
然後執行相關的命令群組（不帶子命令）來查看：
herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr session
不要為了探索而直接執行裸 herdr，它會啟動或附加 TUI。也不要透過省略引數來探測會變更狀態的巢狀命令。像 herdr workspace create 這樣的命令是有效的（會帶預設值執行）。
大多數控制命令會回傳 JSON。請從這些回應中讀取識別碼與狀態，而不是自行預測。
了解佈局、窗格與代理
選擇符合任務的原始類型：
- 工作區、分頁與窗格的拓撲結構組織終端位置。
- 窗格命令控制原始終端、Shell、測試、伺服器、輸入與輸出。
- 代理命令控制目前佔據窗格的已識別編碼代理。
無論窗格內是否有代理，窗格本身都存在。agent start 需要一個現有的可用 Shell 窗格，且絕不會建立、分割或移動佈局。一般行程請使用窗格命令。當 Herdr 需要驗證代理身份或解讀 idle（閒置）、working（工作中）、blocked（受阻）、done（完成）與 unknown（未知）等生命週期狀態時，請使用代理命令。
代理命令接受唯一的活躍代理名稱，或目前承載該代理的窗格 ID。它們不接受終端 ID 或純代理種類標籤。名稱必須符合 [a-z][a-z0-9_-]{0,31} 且在所有活躍代理中唯一。名稱跟隨當前窗格的佔用者，並在該代理退出、被釋放或被取代時清除。
idle 表示代理已準備好接收輸入，且其分頁已在焦點 Herdr UI 中被看見。done 是相同的底層閒置狀態，發生在未見的背景工作完成之後。將分頁聚焦或使用焦點命令鎖定窗格或代理會將其標記為「已見」。CLI 讀取不會將其標記為「已見」。blocked 表示 Herdr 辨識到批准或詢問 UI。unknown 表示代理存在但 Herdr 無法自信地分類；它不代表完成。
使用 ID 與呼叫者上下文
公開 ID 是不透明的穩定句柄：
- 工作區：
w1 - 分頁：
w1:t1 - 窗格：
w1:p1
已關閉的分頁與窗格 ID 不會重複使用。移動到另一個工作區的窗格會獲得一個新的工作區限定窗格 ID。在 pane move 之後，請繼續使用 .result.move_result.pane.pane_id 或活躍代理名稱。舊值會被回報為 .result.move_result.previous_pane_id；只有被移動行程的繼承呼叫者上下文會繼續解析該舊 ID，因此請勿將其用作一般代理目標。
Herdr 會將呼叫者的上下文注入每個受管理的窗格：
printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"
當窗格命令應鎖定呼叫窗格時，請優先使用 --current。省略目標可能會使用 UI 聚焦的窗格，而該窗格可能屬於使用者或其他客戶端。
使用以下指令探索即時狀態：
herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent list
建立回應會暴露後續要使用的 ID。workspace create 回傳 .result.workspace、.result.tab 與 .result.root_pane。tab create 回傳 .result.tab 與 .result.root_pane。pane split 回傳新窗格為 .result.pane。
啟動並協調代理
預設使用目前分頁中的同層窗格與當前工作目錄。除非使用者明確要求特定的拓撲或位置，否則不要建立工作區、分頁、工作樹或不同的 cwd。
遵守使用者要求的方向。否則檢查呼叫窗格：
herdr pane layout --pane "$HERDR_PANE_ID"
將寬窗格向右分割，將窄或高窗格向下分割。避免重複的相同方向分割，導致欄寬或列高過窄而無法使用。將使用者的焦點保持在呼叫窗格，並明確保留呼叫者的工作目錄：
herdr pane split --current --direction right --cwd "$PWD" --no-focus
在適當時將 right 替換為 down。從 .result.pane.pane_id 讀取新窗格 ID。
可用的 Shell 窗格必須處於其互動提示狀態，Shell 本身在前景，且沒有前景命令、編輯器或代理在執行。在該窗格中啟動一個支援的代理，並賦予一個有用的唯一名稱：
herdr agent start reviewer --kind codex --pane <回傳的窗格-id>
使用使用者要求的種類。執行 herdr agent 來查看已安裝的種類列表與選項。僅在 -- 之後傳遞原生代理引數：
herdr agent start reviewer --kind codex --pane <回傳的窗格-id> -- <代理引數...>
agent start 只有在 Herdr 偵測到預期的代理位於同一窗格並認為其已準備好接受互動輸入時才會回傳。預設啟動超時為 30 秒。
透過代理界面提交工作：
herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000
agent prompt 會原子性地提交文字與編碼後的 Enter，同時尊重窗格的即時括號貼上模式。對於一般的代理工作，--wait 就足夠了：它會等待第一個穩定的 idle、done 或 blocked 狀態。請不要用 --until 重複這些預設值。
從非工作狀態發送的提示必須在五秒內產生可觀察到的生命週期變化。否則 Herdr 會回傳 agent_prompt_stalled，而不是無限等待。此等待追蹤的是生命週期狀態，而非單一回合；如果代理已在工作中，則其當前回合的完成可能滿足此條件。
僅在需要特定狀態的工作流程時使用 --until，例如等待一個已運行的代理請求輸入：
herdr agent wait reviewer --until blocked --timeout 120000
沒有 --until 時，獨立的 agent wait 使用與 agent prompt --wait 相同的穩定狀態預設值。
使用邏輯按鍵來控制互動式代理 UI：
herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+c
Herdr 會在寫入任何位元組之前驗證所有按鍵。透過已解析的代理讀取結果：
herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120
如果等待失敗或回傳 blocked，請先檢查 agent get 與 agent read，再決定要傳送什麼輸入。僅當需要原始終端控制時，才使用窗格界面。
在另一個窗格中執行一般命令
使用相同的幾何規則建立一個同層窗格，保留呼叫者的工作目錄，並保持使用者焦點不變：
herdr pane split --current --direction right --cwd "$PWD" --no-focus
從 .result.pane.pane_id 讀取新窗格 ID，然後執行並檢查命令：
herdr pane run <回傳的窗格-id> "just test"
herdr pane wait-output <回傳的窗格-id> --match "test result" --timeout 120000
herdr pane read <回傳的窗格-id> --source recent-unwrapped --lines 120
pane run 會原子性地傳送命令文字與 Enter。pane wait-output 會立即搜尋所選的快照，因此已存在的輸出也能匹配。使用 --match <文字> 進行文字子字串匹配，或使用 --regex <模式> 進行 Rust 正則表達式匹配。省略 --timeout 則允許無限等待。
選擇符合任務的讀取來源：
visible：目前渲染的視口。recent：最近渲染的輸出，包含軟換行。recent-unwrapped：最近的輸出，軟換行已被合併；記錄與轉錄稿優先使用此選項。detection：用於代理偵測的純文字底部緩衝區快照。
當顏色與終端樣式是證據時，使用 --format ansi。否則使用純文字。
--lines 要求 Herdr 從窗格的可用螢幕與主機回滾中提供更多行。如果增加行數並未顯示更多已完成回應的內容，則窗格可能正在終端的替代螢幕上運行代理。離開替代螢幕的行不會進入 Herdr 的主機回滾，因此更大的行數無法恢復它們。
在該次讀取失敗後，要求代理將其完整回應以 Markdown 格式寫入一個臨時目錄，並僅回覆檔案路徑，然後直接讀取該檔案。僅將此作為備用方案；請勿在初始提示中要求檔案輸出。
安全與協調規則
- 除非使用者要求切換上下文，否則對背景工作使用
--no-focus。 - 使用
--current、明確的窗格 ID 或唯一的代理名稱。請勿依賴其他客戶端的焦點窗格。 - 從 JSON 回應中解析 ID。請勿從側邊欄順序或範例推導。
- 除非使用者明確要求，否則不要關閉您未建立的工作區、分頁、窗格或工作階段。
- 除非使用者明確打算停止伺服器及其窗格行程，否則切勿從活躍工作階段執行
herdr server stop。 - 切勿終止主要的 Herdr 程序。使用具名測試工作階段進行需要隔離伺服器的實驗。
- CLI 伺服器錯誤為 JSON 格式，輸出至 stderr，並以 exit status 1 退出。CLI 語法錯誤以 exit status 2 退出。
本地慣例
上述的 HERDR_ENV=1 檢查適用於從窗格內部控制當前工作階段。主機層級的工作——例如編輯設定、安裝外掛、除錯代理偵測、建構圍繞 socket/CLI 的自動化——可以從任何終端合法進行。針對這些任務，請閱讀 references/local-idioms.md：其中包含通知傳送設定、代理偵測維護、來自 Claude Code 掛鉤的側邊欄元資料、事件訂閱模式、工作樹流程以及外掛編寫注意事項。