AI Skills
herdr

herdr

熱門

控制 Herdr，一個專為程式碼代理設計的終端多工器。僅在使用者明確提及 Herdr 或要求使用 Herdr 來檢查或控制窗格、分頁、工作區、終端機、指令，或與其他代理通訊時使用。不要僅因為任務可以從背景終端、委派或平行工作中受益就使用。需要 HERDR_ENV=1。

1.7萬星標
1140分支
更新於 2026/7/16
獲取技能源代碼

相關技能

video-editing23萬ponytail-help8.4萬obsidian-markdown3.6萬
SKILL.md
readonlyread-only
name
herdr
description

控制 Herdr，一個專為程式碼代理設計的終端多工器。僅在使用者明確提及 Herdr 或要求使用 Herdr 來檢查或控制窗格、分頁、工作區、終端機、指令，或與其他代理通訊時使用。不要僅因為任務可以從背景終端、委派或平行工作中受益就使用。需要 HERDR_ENV=1。

Herdr

Herdr 是一個專為程式碼代理設計的終端多工器與執行環境。它將終端組織成工作區、分頁和窗格，偵測代理身分與狀態，並透過 herdr CLI 暴露執行中的工作階段。

在發出任何控制指令前，請確認此代理正在 Herdr 管理的窗格內執行：

test "${HERDR_ENV:-}" = 1

如果檢查失敗，請說明你不在 Herdr 內執行並停止。不要從 Herdr 外部檢查或控制焦點所在的 Herdr 工作階段。

當檢查通過時，PATH 中的 herdr 二進位檔會與執行中的工作階段溝通。用它來檢查鄰近的工作、建立隔離的終端環境、啟動代理與指令、讀取它們的輸出，以及等待狀態變更。

了解目前的 CLI

已安裝的二進位檔是指令語法的權威來源。從以下開始：

herdr --help

然後執行相關的指令群組（不帶子指令）：

herdr pane
herdr workspace
herdr worktree
herdr tab
herdr wait
herdr terminal
herdr notification
herdr integration
herdr session

不要為了探索而直接執行裸的 herdr，它會啟動或附加 TUI。不要透過省略引數來探測會變更狀態的巢狀指令；有些指令（包括 herdr workspace create）在預設情況下是有效的，並且會執行。請改用上述的指令群組輸出。

大多數控制指令會輸出 JSON。請從這些回應中讀取識別碼和狀態，而不是預測它們。

識別碼與當前上下文

公開識別碼是簡短穩定的代號：

  • 工作區：w1
  • 分頁：w1:t1
  • 窗格：w1:p1
  • 終端機：term_...

編碼的後綴可能包含字母，且可能超過一個字元。請將每個識別碼視為不透明的字串。

已關閉的分頁和窗格識別碼不會被重複使用，也不會指向後來的資源。移動到另一個工作區的窗格會獲得一個新的公開窗格識別碼。在變更後重新讀取 create、split、move、list 或 get 的回應；永遠不要從工作區或顯示編號來建構識別碼。

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"

透過窗格控制代理

代理在窗格內執行。使用窗格識別碼作為代理、shell、伺服器、測試和日誌的控制目標。這能將產生、輸入、讀取、等待和清理集中在一個穩定的控制面上。

使用工作區和分頁指令進行組織。僅在你刻意希望 Herdr 建立、開啟或移除 Git 簽出時，才使用 worktree 指令。

窗格記錄會在有可用資訊時暴露 agent、agent_status 和原生工作階段中繼資料。代理狀態為 idle、working、blocked、done 或 unknown。

idle 和 done 是相同的底層語義狀態，但具有不同的注意力狀態：

  • idle：代理正在等待，且其結果被視為已看過。
  • done：代理已完成，且其結果尚未被看過。

一個首次在其提示符開啟的代理會回報 idle，即使在背景窗格中也是如此。在 working 或 blocked 的代理完成後，如果其分頁或工作區在背景中，它會回報 done。如果它在前景客戶端有焦點時於作用中分頁完成，則回報 idle。如果前景客戶端明確失去焦點，即使是在作用中分頁，完成也可能變成 done。

聚焦一個窗格、切換到其分頁，或重新取得外部終端焦點，會將可見的分頁標記為已看過，因此 done 會變成 idle。切換離開不會將現有的 idle 狀態變成 done；done 是由後續在窗格未被看到時的完成所產生的。如果沒有前景客戶端，全域作用中分頁中的新完成會被視為已看過，而背景分頁中的完成仍會變成 done。

互動式啟動代理

預設在目前分頁和目前工作目錄中建立一個兄弟窗格。除非使用者明確要求特定的拓撲或位置，否則不要建立工作區、分頁、worktree 或不同的工作目錄。

遵循使用者要求的方向。否則檢查呼叫窗格的當前矩形：

herdr pane layout --pane "$HERDR_PANE_ID"

將寬窗格向右分割，將窄或高的窗格向下分割。避免重複相同方向的分割，以免產生無法使用的狹窄欄位或短行。將使用者的焦點保留在呼叫窗格中：

herdr pane split --current --direction right --no-focus

當版面配置需要時，將 right 替換為 down。

從 JSON 回應中讀取 result.pane.pane_id。為窗格取一個有用的標籤，然後僅執行其正常可執行檔來啟動要求的代理，以便其互動式 TUI 開啟：

herdr pane rename <returned-pane-id> "reviewer"
herdr pane run <returned-pane-id> "codex"

使用所要求代理的對應可執行檔：

  • Codex：codex
  • Claude Code：claude
  • pi：pi
  • OpenCode：opencode
  • OMP：omp

預設不要將任務作為 argv 提示傳遞。不要添加非互動式旗標。僅在使用者明確要求不同的啟動模式或指令時，才更改正常的互動式啟動。

啟動後檢查窗格。如果 agent_status 尚未是 idle，請等待 idle 轉換。一旦 idle，使用 pane run 提交任務：

herdr pane get <returned-pane-id>
herdr wait agent-status <returned-pane-id> --status idle --timeout 30000
herdr pane run <returned-pane-id> "Review the current diff and report only actionable findings."

狀態等待會立即比對當前狀態，或等待未來符合的轉換。

pane run 會同時傳送文字和 Enter。請用它來處理初始提示和後續追問，而不是分別協調 send-text 和 send-keys。

對於一般的背景工作，請等待代理開始工作。如果窗格保持在背景分頁或工作區中，請在讀取其記錄前等待 done：

herdr wait agent-status <returned-pane-id> --status working --timeout 30000
herdr wait agent-status <returned-pane-id> --status done --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120

如果使用者正在觀看該分頁，完成時會回報 idle，因此請等待 idle。在檢查 pane get 時，一律將 idle 或 done 視為已完成；差別在於結果是否已被看過。

如果等待超時，請在決定下一步行動前檢查 herdr pane get <returned-pane-id> 和 pane read。blocked 的代理需要輸入；unknown 的窗格可能尚未包含已偵測或整合的代理。

以相同方式提交後續追問：

herdr pane run <returned-pane-id> "Now check the failing test."

在另一個窗格中執行一般指令

使用相同的幾何規則分割呼叫窗格，而不移動使用者的焦點：

herdr pane split --current --direction right --no-focus

從 JSON 回應中讀取新的 pane_id，然後執行並檢查指令：

herdr pane run <returned-pane-id> "just test"
herdr wait output <returned-pane-id> --match "test result" --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120

在等待未來輸出之前，先檢查現有輸出。等待超時會以狀態碼 1 退出。

使用符合任務的讀取來源：

  • visible：當前渲染的視口
  • recent：最近的捲回內容（已渲染，包含軟換行）
  • recent-unwrapped：最近的捲回內容（軟換行已合併）；偏好用於日誌和記錄
  • detection：代理偵測使用的底部緩衝區快照

當顏色和終端樣式是證據時，使用 --format ansi。否則使用純文字。

如果使用者明確要求另一個分頁、工作區或 worktree，請探索該指令群組並使用回傳的識別碼。不要從啟動代理或指令的請求中推斷出更大的拓撲。

安全與協調規則

  • 除非使用者要求切換上下文，否則對背景工作使用 --no-focus。
  • 使用 --current 或明確的識別碼。不要依賴其他客戶端的焦點窗格。
  • 從 JSON 回應中解析識別碼。不要從側邊欄順序或範例中推導。
  • 先檢查再等待。先讀取當前輸出，然後等待你預期的下一個狀態或輸出。
  • 除非使用者明確要求，否則不要關閉你未建立的工作區、分頁、窗格或工作階段。
  • 除非使用者明確打算停止伺服器及其窗格程序，否則不要從作用中工作階段執行 herdr server stop。
  • 永遠不要終止主要的 Herdr 程序。對於需要隔離伺服器的實驗，請使用命名的測試工作階段。