Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/kanban-worker-lanes

Kanban Worker Lanes

Worker lane 是 kanban 分派器可以路由任務的一類程序。每個 lane 有一個身份識別（assignee 字串）、一個衍生機制，以及一個在衍生後必須對任務執行的合約。

本頁面就是這個合約。它的受眾有兩類：

操作員：決定要將哪些 lane 接入看板（建立哪些 profile、使用哪些 assignee）。
外掛 / 整合開發者：想要新增一種 lane 類型（包裝 Codex / Claude Code / OpenCode 的 CLI worker、容器化的審查 worker、透過 API 拉取任務的非 Hermes 服務）。

如果你要編寫 worker 程式碼本身 — 在 lane 內部運行的 agent — kanban-worker 技能有更詳細的流程說明。

層級架構

Hermes Kanban  =  標準任務生命週期 + 稽核軌跡
Worker lane    =  已分配卡片的實作執行器
Reviewer       =  閾控「完成」的人員或人員代理
GitHub PR      =  可上游化的產物（可選，用於代碼 lane）

Hermes Kanban 擁有生命週期的真實性 — ready → running → blocked / done / archived。Worker lane 執行工作但永遠不擁有那個真實性；它們所做的一切都透過 kanban_* 工具回流到 kanban 核心（對於非 Hermes 的外部 worker，則透過 API）。Reviewer 閾控從「程式碼變更已寫入」到「任務完成」的轉換。

Lane 提供什麼

要成為 kanban worker lane，整合必須提供三件事：

1. Assignee 字串

分派器將 task.assignee 與 Hermes profile 名稱（預設 lane 類型）或已註冊的不可衍生識別碼（外掛 lane 類型 — 參見下方新增外部 CLI worker lane）進行比對。無法解析 assignee 的任務會保持在 ready 狀態，並帶有 skipped_nonspawnable 事件，以便看板操作員可以修正它們；它們不會被靜默丟棄或由任意回退機制執行。

2. 衍生機制

對於 Hermes profile lane，分派器的 _default_spawn 會在任務的固定工作區內執行 hermes -p <assignee> chat -q <prompt>（或當 hermes shim 不在 $PATH 上時的等效模組形式），並設定以下環境變數：

變數	內容
`HERMES_KANBAN_TASK`	worker 正在處理的任務 ID
`HERMES_KANBAN_DB`	各看板 SQLite 檔案的絕對路徑
`HERMES_KANBAN_BOARD`	看板識別碼
`HERMES_KANBAN_WORKSPACES_ROOT`	看板工作區樹的根目錄
`HERMES_KANBAN_WORKSPACE`	此任務工作區的絕對路徑
`HERMES_KANBAN_RUN_ID`	目前執行的 ID（用於生命週期閾控）
`HERMES_KANBAN_CLAIM_LOCK`	claim lock 字串（`<host>:<pid>:<uuid>`）
`HERMES_PROFILE`	worker 自身的 profile 名稱（用於 `kanban_comment` 作者歸屬）
`HERMES_TENANT`	租戶命名空間（如果任務有的話）

對於非 Hermes lane（透過外掛註冊），外掛提供自己的 spawn_fn 可呼叫函式，接收 task、workspace 和 board，並回傳可選的 pid 用於崩潰偵測。

3. 生命週期終止器

每個 claim 必須以以下其中一種方式結束：

kanban_complete(summary=..., metadata=...) — 任務成功，狀態翻轉為 done。
kanban_block(reason=...) — 任務等待人工輸入，狀態翻轉為 blocked。當 kanban_unblock 運行時分派器會重新衍生。
Worker 程式在沒有工具調用的情況下退出。核心會回收它並發出 crashed（PID 死亡）、gave_up（連續失敗斷路器觸發）或 timed_out（超過 max_runtime）。這是失敗路徑；健康的 worker 不會走到這裡。

Kanban 核心強制要求每次執行恰好以其中一種方式結束。既沒有呼叫其中任何一個又正常退出的 worker 會被視為崩潰。

輸出與 review-required 約定

對於大多數涉及程式碼變更的任務，工作在 worker 完成的那一刻並非真正完成 — 需要人工審查者。Kanban 核心不強制執行這個區別（「涉及程式碼變更的任務」定義模糊，強制每個代碼 worker 都用 block 而不是 complete 會破壞不需要審查的流程）。它是在上層疊加的約定：

用 block 而非 complete，reason 前綴為 review-required: ，讓看板 / hermes kanban show 將該行顯示為等待審查。
先將結構化中繼資料放入 kanban_comment，因為 kanban_block 只攜帶人類可讀的 reason。Comment 是持久的註解通道 — 所有與稽核相關的欄位（changed_files、tests_run、diff_path 或 PR url、decisions）都屬於那裡。
Reviewer 要麼批准並 unblock（讓 worker 以 comment thread 為基礎重新執行後續動作），要麼透過另一則 comment 要求修改（下次 worker 執行時會在 kanban_show 的上下文中看到）。

kanban-worker 技能包含 kanban_complete（真正終結的任務 — 修正錯字、文件變更、研究報告）和 review-required block 模式的實作範例。

日誌與稽核軌跡

分派器將各任務 worker 的 stdout/stderr 寫入 <board-root>/logs/<task_id>.log。日誌可從 kanban 中繼資料進行稽核：

task_runs 列攜帶 log_path、退出碼（如有）、摘要和中繼資料。
task_events 列攜帶每次狀態轉換（promoted、claimed、heartbeat、completed、blocked、gave_up、crashed、timed_out、reclaimed、claim_extended）。
kanban_show 兩者都回傳，因此審查者（或後續 worker）讀取任務時可以獲得完整歷史，無需看板存取權限。

看板會以摘要、中繼資料區塊和退出狀態標記來渲染執行歷史。CLI 使用者可以執行 hermes kanban tail <task_id> 來追蹤即時狀態，或執行 hermes kanban runs <task_id} 查看歷史嘗試列表。

現有的 lane 類型

Hermes profile lane（預設）

目前每個 kanban worker 採用的類型：assignee 是 profile 名稱，分派器衍生 hermes -p <profile>，worker 自動載入 kanban-worker 技能加上 KANBAN_GUIDANCE 系統提示區塊，並使用 kanban_* 工具來終止執行。除了定義 profile 外不需要額外設定。

為你的機群建立 profile 時，選擇與你希望編排器路由的角色相符的名稱。編排器（如果有的話）透過 hermes profile list 發現你的 profile 名稱 — 系統沒有假設固定的名冊（參見 kanban-orchestrator 技能了解編排器側的合約）。

Orchestrator profile lane

Profile lane 的特化版本：orchestrator 是一個 Hermes profile，其工具集包含 kanban 但排除 terminal / file / code / web 實作工具。它的任務是透過 kanban_create + kanban_link 將高階目標分解為子任務，然後退居幕後。orchestrator 技能編碼了防誘惑規則。

新增外部 CLI worker lane

將非 Hermes 的 CLI 工具（Codex CLI、Claude Code CLI、OpenCode CLI、本機 coding-model 執行器等）接入 kanban worker lane 尚未有標準化路徑。分派器的衍生函式是可插拔的（spawn_fn 是 dispatch_once 的參數），外掛可以為非 Hermes 的 assignee 註冊自己的 spawn_fn，但周圍的整合工作 — 將 CLI 的退出碼包裝為 kanban_complete / kanban_block 調用、將 CLI 的工作區/沙箱約定對應到分派器的 HERMES_KANBAN_WORKSPACE 環境變數、處理驗證和各 CLI 的策略 — 仍然是每個整合的設計工作。

如果你正在考慮新增 CLI lane，請開一個 issue 描述具體的 CLI 和你想要實現的工作流程。上方的合約是此類 lane 必須滿足的限制條件；實作形式（每個 CLI 一個外掛 vs 透過設定參數化的通用 CLI 執行器外掛）仍然開放。

相關的歷史 issue 為 #19931，以及已關閉但未合併的 Codex 專用 PR #19924 — 它們描述了原始架構提案但未實作執行器。

分派器處理的失敗模式

lane 作者不需要重新實作這些：

過期的 claim TTL — worker claim 後從未 heartbeat / complete / block 的話，會在 DEFAULT_CLAIM_TTL_SECONDS（預設 15 分鐘）後被收回 — 但前提是 worker 程式確實已死亡。存活的 worker（慢模型在一次無工具 LLM 呼叫中花費 20+ 分鐘）的 claim 會被延長而非被終止；只有死亡的 PID 才會被收回。
崩潰的 worker — 工作主機本地 PID 消失的 worker 會被 detect_crashed_workers 偵測並回收；任務會遞增 consecutive_failures，當斷路器觸發時可能自動阻塞。
執行層級重試 — 當任務被重試（block 後、崩潰後、收回後），worker 可以在終止工具上使用 expected_run_id 參數，在自己的執行已被取代時快速失敗。
各任務最大執行時間 — task.max_runtime_seconds 硬性限制每次執行的壁鐘時間，不論 PID 存活狀態。用來捕獲真正死鎖的 worker，這些 worker 如果靠存活 PID 延長機制會繼續運行。
擱淺任務偵測 — ready 任務的 assignee 在 kanban.stranded_threshold_seconds（預設 30 分鐘）內從未產生 claim 時，會在 hermes kanban diagnostics 中顯示為 stranded_in_ready 警告。嚴重度在 2 倍閾值時升級為 error，6 倍時升級為 critical。能一次捕獲拼錯的 assignee、已刪除的 profile 和已宕機的外部 worker 池 — 與身份識別無關，無需逐看板維護允許清單。