跳到主要內容

看板工作器通道（Worker Lanes）

工作器通道（worker lane） 是看板調度程序可以將任務路由到的一類進程。每個通道都有一個身份標識（assignee 字符串）、一個生成機制，以及一旦生成後必須對任務執行的操作契約。

本頁即為該契約。它面向兩類受眾：

  • 運維人員：選擇將哪些通道接入看板（創建哪些配置文件，使用哪些 assignee）。
  • 插件/集成作者：希望添加新的通道形態（例如封裝 Codex / Claude Code / OpenCode 的 CLI 工作器、容器化的審查工作器，或通過 API 拉取任務的非 Hermes 服務）。

如果你正在編寫工作器本身的代碼——即在通道內部運行的代理——kanban-worker skill 提供了更深層的過程細節。

層級結構​

Hermes Kanban  =  canonical task lifecycle + audit trail
Worker lane    =  implementation executor for one assigned card
Reviewer       =  human or human-proxy that gates "done"
GitHub PR      =  upstreamable artifact (optional, for code lanes)

Hermes Kanban 擁有生命週期真相——ready → running → blocked / done / archived。工作器通道執行工作，但從不擁有該真相；它們所做的一切都通過 kanban_* 工具（或者對於非 Hermes 外部工作器，通過 API）迴流到看板內核。審查者負責把控從“代碼變更已編寫”到“任務完成”的過渡。

通道提供的內容​

要成為看板工作器通道，集成必須提供以下三要素：

1. Assignee 字符串​

調度程序將 task.assignee 與 Hermes 配置文件名稱（默認通道形態）或註冊的非可生成標識符（插件通道形態——參見下文添加外部 CLI 工作器通道）進行匹配。如果任務的 assignee 無法解析，任務將保留在 ready 狀態，並附帶 skipped_nonspawnable 事件，以便看板運維人員進行修復；它們不會被靜默丟棄或由任意回退機制執行。

2. 生成機制​

對於 Hermes 配置文件通道，調度程序的 _default_spawn 會在任務固定的工作空間內運行 hermes -p <assignee> chat -q <prompt>（如果 $PATH 中沒有 hermes shim，則運行等效的模塊形式），並設置以下環境變量：

變量攜帶內容
HERMES_KANBAN_TASK工作器正在操作的任務 ID
HERMES_KANBAN_DB每個看板的 SQLite 文件的絕對路徑
HERMES_KANBAN_BOARD看板 slug
HERMES_KANBAN_WORKSPACES_ROOT看板工作空間樹的根目錄
HERMES_KANBAN_WORKSPACE當前任務工作空間的絕對路徑
HERMES_KANBAN_RUN_ID當前運行的 ID（用於生命週期門控）
HERMES_KANBAN_CLAIM_LOCK認領鎖字符串（<host>:<pid>:<uuid>）
HERMES_PROFILE工作器自身的配置文件名稱（用於 kanban_comment 作者歸屬）
HERMES_TENANT租戶命名空間（如果任務有的話）

對於非 Hermes 通道（通過插件註冊），插件提供自己的 spawn_fn 可調用對象，該對象接收 task、workspace 和 board，並返回一個可選的 pid 用於崩潰檢測。

3. 生命週期終止器​

每個認領必須以以下三種方式之一確切結束：

  • kanban_complete(summary=..., metadata=...) —— 任務成功，狀態翻轉為 done。
  • kanban_block(reason=...) —— 任務等待人工輸入，狀態翻轉為 blocked。當運行 kanban_unblock 時，調度程序會重新生成任務。
  • 工作器進程在沒有調用工具的情況下退出。內核會回收該進程併發出 crashed（PID 死亡）、gave_up（連續失敗斷路器觸發）或 timed_out（超過 max_runtime）。這是失敗路徑；健康的工作器不應在此結束。

看板內核強制要求每次運行必須由上述其中一種方式終止。既不調用任何終止工具又正常退出的工作器將被視為崩潰。

輸出與“需要審查”約定​

對於大多數涉及代碼變更的任務，工作器完成的那一刻工作並未真正完成——它需要人工審查。看板內核不強制執行這種區分（“涉及代碼變更的任務”定義模糊，且強制每個代碼工作器使用 block 而非 complete 會破壞不需要審查的工作流）。這是一種疊加在其上的約定：

  • 使用 Block 而非 Complete，且 reason 前綴為 review-required: ，以便儀表盤 / hermes kanban show 將該行顯示為等待審查。
  • 首先在 kanban_comment 中放入結構化元數據，因為 kanban_block 僅攜帶人類可讀的 reason。評論是持久的註釋渠道——每個與審計相關的字段（changed_files、tests_run、diff_path 或 PR url、decisions）都應放在那裡。
  • 審查者要麼批准並解除阻塞，這會帶著評論線程重新生成工作器以進行後續操作；要麼通過另一條評論要求更改，下一個工作器運行會在 kanban_show 的上下文中看到這些內容。

kanban-worker skill 包含了 kanban_complete（真正終結的任務——錯別字修復、文檔變更、研究撰寫）和 review-required 阻塞模式的工作示例。

日誌與審計軌跡​

調度程序將每個任務的工作器 stdout/stderr 寫入 <board-root>/logs/<task_id>.log。可以從看板元數據中審計日誌：

  • task_runs 行攜帶 log_path、退出碼（如果可用）、摘要和元數據。
  • task_events 行攜帶每一次狀態轉換（promoted、claimed、heartbeat、completed、blocked、gave_up、crashed、timed_out、reclaimed、claim_extended）。
  • kanban_show 返回上述兩者，因此審閱者（或後續工作者）在閱讀任務時無需訪問儀表板即可獲取完整歷史記錄。

儀表板渲染帶有摘要、元數據塊和退出狀態徽章的運行歷史。CLI 用戶可以運行 hermes kanban tail <task_id> 來實時跟蹤，或者運行 hermes kanban runs <task_id> 查看歷史嘗試列表。

現有泳道形態​

Hermes 配置泳道（默認）​

這是當前每個看板工作者採用的形態：受讓人是一個配置名稱，調度器生成 hermes -p <profile>，工作者自動加載 kanban-worker 技能以及 KANBAN_GUIDANCE 系統提示塊，並使用 kanban_* 工具來終止運行。除了定義配置外，無需其他設置。

當為你的集群創建配置時，選擇的名稱應與你希望編排器路由到的角色相匹配。編排器（如果存在）通過 hermes profile list 發現你的配置名稱——系統不假設任何固定的名冊（請參閱 kanban-orchestrator 技能以瞭解合約中編排器一側的情況）。

編排器配置泳道​

配置泳道的一個特化：編排器是一個 Hermes 配置，其工具集包含 kanban，但排除用於實現的 terminal / file / code / web。它的工作是通過 kanban_create + kanban_link 將高層目標分解為子任務，然後退後一步。編排器技能編碼了防誘惑規則。

添加外部 CLI 工作者泳道​

將非 Hermes CLI 工具（Codex CLI、Claude Code CLI、OpenCode CLI、本地代碼模型運行器等）作為看板工作者泳道接入尚不是一條平坦的道路。調度器的生成函數是可插拔的（spawn_fn 是 dispatch_once 的一個參數），插件可以為非 Hermes 受讓人註冊自己的 spawn_fn，但周圍的集成工作——將 CLI 的退出碼包裝到 kanban_complete / kanban_block 調用中，將 CLI 的工作區/沙箱約定映射到調度器的 HERMES_KANBAN_WORKSPACE 環境變量，處理身份驗證和每個 CLI 的策略——仍然是針對每個集成的設計工作。

如果你考慮添加 CLI 泳道，請創建一個 issue，描述具體的 CLI 和你試圖啟用的工作流。上述合約是任何此類泳道必須滿足的約束；實現形態（每個 CLI 一個插件 vs 一個由配置參數化的通用 CLI 運行器插件）是開放的。

此問題的歷史 issue 是 #19931，以及未合併已關閉的 Codex 特定 PR #19924——這些描述了最初的架構提案，但未落地運行器。

調度器處理的故障模式​

因此，泳道作者無需重新實現這些：

  • 過期的認領 TTL —— 一個認領後從未發送心跳/完成/阻塞的工作者會在 DEFAULT_CLAIM_TTL_SECONDS（默認 15 分鐘）後被重新認領——但僅當工作者進程確實已死亡時。活躍的工作者（在單個無工具 LLM 調用中花費 20 多分鐘的慢速模型）其認領會被延長而不是被殺死；只有死亡的 PID 才會被重新認領。
  • 崩潰的工作者 —— 主機本地 PID 消失的工作者會被 detect_crashed_workers 檢測並回收；任務增加 consecutive_failures 計數，並在斷路器觸發時可能自動阻塞。
  • 運行級重試 —— 當任務被重試（阻塞後、崩潰後、重新認領後）時，工作者可以在終止工具上使用 expected_run_id 參數，以便在其自己的運行已被取代時快速失敗。
  • 每任務最大運行時 —— task.max_runtime_seconds 硬性限制每次運行的掛鐘時間，無論 PID 是否存活。捕獲那些真正死鎖的工作者，否則活躍 PID 延長機制會讓它們繼續運行。
  • 滯留任務檢測 —— 一個就緒任務，如果其受讓人在 kanban.stranded_threshold_seconds（默認 30 分鐘）內未產生認領，將在 hermes kanban diagnostics 中顯示為 stranded_in_ready 警告。嚴重程度在閾值的 2 倍時升級為錯誤，在 6 倍時升級為嚴重。在一個信號中捕獲拼寫錯誤的受讓人、已刪除的配置和宕機的外部工作者池——與身份無關，無需維護每個看板的允許列表。