Kanban Worker

Hermes Kanban worker 的陷阱、示例和邊緣情況。生命週期本身會作為 KANBAN_GUIDANCE（來自 agent/prompt_builder.py）自動注入到每個 worker 的系統提示中；當你想要了解特定場景的更詳細信息時，可以加載此技能。

技能元數據


來源	捆綁（默認安裝）
路徑	`skills/devops/kanban-worker`
版本	`2.0.0`
平臺	linux, macos, windows
標籤	`kanban`, `multi-agent`, `collaboration`, `workflow`, `pitfalls`
相關技能	`kanban-orchestrator`

參考：完整 SKILL.md

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理看到的指令。

Kanban Worker — 陷阱與示例

你看到此技能是因為 Hermes Kanban 調度器使用 --skills kanban-worker 將你生成為 worker —— 它為每個被調度的 worker 自動加載。生命週期（6 個步驟：orient → work → heartbeat → block/complete）也存在於自動注入到你係統提示中的 KANBAN_GUIDANCE 塊中。此技能提供更深入的細節：良好的交接形式、重試診斷、邊緣情況。

工作區處理

你的工作區類型決定了你在 $HERMES_KANBAN_WORKSPACE 中應如何行為：

類型	說明	工作方式
`scratch`	全新的臨時目錄，僅供你使用	自由讀寫；任務歸檔時會被垃圾回收。
`dir:<path>`	共享持久化目錄	其他運行將讀取你寫入的內容。將其視為長期狀態。路徑保證為絕對路徑（內核會拒絕相對路徑）。
`worktree`	解析路徑處的 Git worktree	如果 `.git` 不存在，首先從主倉庫運行 `git worktree add <path> ${HERMES_KANBAN_BRANCH:-wt/$HERMES_KANBAN_TASK}`，然後 cd 進入並正常工作。在此提交工作。

租戶隔離

如果設置了 $HERMES_TENANT，則任務屬於租戶命名空間。在讀取或寫入持久化內存時，使用租戶前綴標記內存條目，以防止上下文在不同租戶間洩露：

好：business-a: Acme 是我們最大的客戶
壞（洩露）：Acme 是我們最大的客戶

良好的摘要 + 元數據形式

kanban_complete(summary=..., metadata=...) 交接是下游 worker 讀取你所做工作的方式。有效的模式：

編碼任務：

kanban_complete(
    summary="shipped rate limiter — token bucket, keys on user_id with IP fallback, 14 tests pass",
    metadata={
        "changed_files": ["rate_limiter.py", "tests/test_rate_limiter.py"],
        "tests_run": 14,
        "tests_passed": 14,
        "decisions": ["user_id primary, IP fallback for unauthenticated requests"],
    },
)

需要人工審查的編碼任務（review-required）：

對於大多數更改代碼的任務，直到人工審查者查看後，工作才算真正完成。使用 block 而非 complete，並將 reason 前綴設為 review-required: ，以便儀表板將該行顯示為需要審查。首先將結構化元數據（更改的文件、測試計數、diff/PR URL）放入評論中，因為 kanban_block 僅攜帶人類可讀的原因——評論是持久的註釋渠道。審查者要麼批准並運行 hermes kanban unblock <id>（這將重新生成你並附帶評論線程以進行任何後續操作），要麼通過另一條評論要求更改。

import json

kanban_comment(
    body="review-required handoff:\n" + json.dumps({
        "changed_files": ["rate_limiter.py", "tests/test_rate_limiter.py"],
        "tests_run": 14,
        "tests_passed": 14,
        "diff_path": "/path/to/worktree",  # or PR url if pushed
        "decisions": ["user_id primary, IP fallback for unauthenticated requests"],
    }, indent=2),
)
kanban_block(
    reason="review-required: rate limiter shipped, 14/14 tests pass — needs eyes on the user_id/IP fallback choice before merging",
)

僅在任務真正終止時使用 kanban_complete —— 例如單行拼寫錯誤修復、沒有功能後果的文檔更改，或者工件本身就是撰寫的研究任務。

研究任務：

kanban_complete(
    summary="3 competing libraries reviewed; vLLM wins on throughput, SGLang on latency, Tensorrt-LLM on memory efficiency",
    metadata={
        "sources_read": 12,
        "recommendation": "vLLM",
        "benchmarks": {"vllm": 1.0, "sglang": 0.87, "trtllm": 0.72},
    },
)

審查任務：

kanban_complete(
    summary="reviewed PR #123; 2 blocking issues found (SQL injection in /search, missing CSRF on /settings)",
    metadata={
        "pr_number": 123,
        "findings": [
            {"severity": "critical", "file": "api/search.py", "line": 42, "issue": "raw SQL concat"},
            {"severity": "high", "file": "api/settings.py", "issue": "missing CSRF middleware"},
        ],
        "approved": False,
    },
)

塑造 metadata 的形式，以便下游解析器（審查者、聚合器、調度器）無需重讀你的散文即可使用它。

聲明你實際創建的卡片

如果你的運行產生了新的 kanban 任務（通過 kanban_create），請在 kanban_complete 的 created_cards 中傳遞這些 id。內核會驗證每個 id 是否存在且由你的配置文件創建；任何虛假 id 都會導致完成失敗，並列出錯誤信息，被拒絕的嘗試會永久記錄在任務的事件日誌中。僅列出你從成功的 kanban_create 返回值中捕獲的 id —— 切勿從散文中虛構 id，切勿粘貼 earlier runs 的 id，切勿聲明其他 worker 創建的卡片。

# GOOD — capture return values, then claim them.
c1 = kanban_create(title="remediate SQL injection", assignee="security-worker")
c2 = kanban_create(title="fix CSRF middleware", assignee="web-worker")

kanban_complete(
    summary="Review done; spawned remediations for both findings.",
    metadata={"pr_number": 123, "approved": False},
    created_cards=[c1["task_id"], c2["task_id"]],
)

# BAD — claiming ids you don't have captured return values for.
kanban_complete(
    summary="Created remediation cards t_a1b2c3d4, t_deadbeef",  # hallucinated
    created_cards=["t_a1b2c3d4", "t_deadbeef"],                   # → gate rejects
)

如果 kanban_create 調用失敗（異常、tool_error），則卡片未創建 —— 不要為其包含虛假 id。重試創建，或省略該 id 並在摘要中提及失敗。散文掃描過程還會捕獲你自由格式摘要中無法解析的 t_<hex> 引用；這些不會阻止完成，但會在儀表板的任務上顯示為建議性警告。

能快速得到回覆的阻塞原因

壞："stuck" —— 人類沒有上下文。

好：用一句話命名你需要的具體決策。將更長的上下文留作評論。

kanban_comment(
    task_id=os.environ["HERMES_KANBAN_TASK"],
    body="Full context: I have user IPs from Cloudflare headers but some users are behind NATs with thousands of peers. Keying on IP alone causes false positives.",
)
kanban_block(reason="Rate limit key choice: IP (simple, NAT-unsafe) or user_id (requires auth, skips anonymous endpoints)?")

阻塞消息是出現在儀表板/網關通知器中的內容。評論是人類打開任務時閱讀的更深層次上下文。

值得發送的心跳

良好的心跳名稱應體現進度："epoch 12/50, loss 0.31"、"scanned 1.2M/2.4M rows"、"uploaded 47/120 videos"。

不良的心跳："still working"、空備註、亞秒級間隔。最多每隔幾分鐘一次；對於耗時約 2 分鐘以下的任務，完全跳過心跳。

重試場景

如果你打開任務時，kanban_show 返回 runs: [...] 且其中包含一個或多個已關閉的運行記錄，則你處於重試狀態。先前運行的 outcome / summary / error 會告訴你哪裡出了問題。不要重複相同的路徑。典型的重試診斷如下：

outcome: "timed_out" — 之前的嘗試達到了 max_runtime_seconds。你可能需要將工作分塊或縮短執行時間。
outcome: "crashed" — 內存溢出（OOM）或段錯誤（segfault）。減少內存佔用。
outcome: "spawn_failed" + error: "..." — 通常是配置文件問題（缺少憑據、錯誤的 PATH）。通過 kanban_block 向人類求助，而不是盲目重試。
outcome: "reclaimed" + summary: "task archived..." — 操作員在之前的運行期間歸檔了該任務；你可能根本不應該運行，請仔細檢查狀態。
outcome: "blocked" — 之前的嘗試被阻塞；解除阻塞的評論此時應該已出現在線程中。

通知路由

你可以通過在 ~/.hermes/config.yaml 中添加 notification_sources 來配置網關，以接收跨配置文件的 Kanban 任務通知。

notification_sources: ['*'] 接受來自所有配置文件的訂閱。
notification_sources: ['default', 'zilor-ppt'] 或 "default,zilor-ppt" 將訂閱限制為指定的配置文件。
省略該鍵則保持默認行為（配置文件隔離）。

禁止事項

不要調用 delegate_task 作為 kanban_create 的替代方案。delegate_task 用於你的運行內部的短期推理子任務；kanban_create 用於跨越單個 API 循環生命週期的跨代理交接。
不要調用 clarify 向人類提問。你是無頭模式運行 — 沒有實時用戶來回答。調用將超時（默認約 120 秒），任務將靜默地停留在 running 狀態，沒有任何需要輸入的信號。請改用 kanban_comment（提供上下文）+ kanban_block(reason=...)（表示需要決策）— 任務在看板上顯示為被阻塞，操作員會看到它，並在評論中用答案解除阻塞，然後你帶著線程內容重新生成。
除非任務正文明確說明，否則不要修改 $HERMES_KANBAN_WORKSPACE 之外的文件。
不要創建分配給你自己的後續任務 — 應分配給合適的專家。
不要完成你實際上並未完成的任務。改為將其阻塞。

常見陷阱

任務狀態可能在調度與你啟動之間發生變化。 在調度器認領任務到你的進程實際啟動之間，任務可能已被阻塞、重新分配或歸檔。務必首先調用 kanban_show。如果報告為 blocked 或 archived，請立即停止 — 你不應該繼續運行。

工作區可能存在殘留 artifacts。 特別是 dir: 和 worktree 工作區可能包含之前運行留下的文件。閱讀評論線程 — 它通常解釋了為什麼你要再次運行以及工作區當前的狀態。

當有可用指導工具時，不要依賴 CLI。 kanban_* 工具適用於所有終端後端（Docker、Modal、SSH）。從你的終端工具中調用 hermes kanban <verb> 會在容器化後端中失敗，因為那裡未安裝 CLI。如有疑問，請使用工具。

CLI 回退（用於腳本編寫）

每個工具都有供人類操作員和腳本使用的等效 CLI 命令：

kanban_show ↔ hermes kanban show <id> --json
kanban_complete ↔ hermes kanban complete <id> --summary "..." --metadata '{...}'
kanban_block ↔ hermes kanban block <id> "reason"
kanban_create ↔ hermes kanban create "title" --assignee <profile> [--parent <id>]
等等。

在代理內部使用工具；CLI 是供終端前的人類使用的。

技能元數據​

參考：完整 SKILL.md​

Kanban Worker — 陷阱與示例

工作區處理​

租戶隔離​

良好的摘要 + 元數據形式​

聲明你實際創建的卡片​

能快速得到回覆的阻塞原因​

值得發送的心跳​

重試場景​

通知路由​

禁止事項​

常見陷阱​

CLI 回退（用於腳本編寫）​