<!-- Source: https://hermesbible.com/docs/user-guide/features/kanban-tutorial -->

章節: 核心功能 · 網址: https://hermesbible.com/docs/user-guide/features/kanban-tutorial

Kanban 教學

本教程會帶著你實際操作 Hermes Kanban 系統的四個使用情境，全程搭配瀏覽器上的儀表板。如果你還沒有看過 Kanban 概覽，建議先回去看 — 本文假設你已經知道 task（任務）、run（執行紀錄）、assignee（負責人）和 dispatcher（派發器）是什麼。

設定

hermes kanban init           # 可選；第一次執行 `hermes kanban <任何指令>` 會自動初始化
hermes dashboard             # 在瀏覽器開啟 http://127.0.0.1:9119
# 點選左側導覽列的 Kanban

儀表板是你觀察系統最舒適的地方。Dispatcher 派出去的 Agent worker 看不到儀表板或 CLI — 它們透過專屬的 kanban_* 工具集（kanban_show、kanban_list、kanban_complete、kanban_block、kanban_heartbeat、kanban_comment、kanban_create、kanban_link、kanban_unblock）來操作看板。三個介面 — 儀表板、CLI、worker 工具 — 都連到同一個看板的 SQLite 資料庫（預設看板使用 ~/.hermes/kanban.db，你之後建立的任何看板則使用 ~/.hermes/kanban/boards/<slug>/kanban.db），所以不論變更是從哪個端點發生的，看板的狀態永遠是一致的。

本教程全程使用 default 看板。如果你需要多個獨立的佇列（每個專案 / repo / 領域一個），請參考概覽中的 看板（多專案） — 同樣的 CLI / 儀表板 / worker 流程適用於每個看板，而且 worker 物理上無法看到其他看板的任務。

在整篇教程中，標示為 bash 的程式碼區塊是你親自執行的指令。 標示為 # worker tool calls 的程式碼區塊是 worker 模型發出的工具呼叫 — 顯示在這裡是讓你看懂完整的迴圈流程，並不是要你親自執行。

看板一覽

從左到右六個欄位：

• Triage（分類） — 原始想法。預設情況下，Dispatcher 會自動對此欄位的任務執行分解器：內建的分解器使用 auxiliary.kanban_decomposer，讀取你的個人檔案清單和描述，產生一組子任務的圖譜，並將它們派發給最適合的專家。原始任務會保留為父任務，讓它的負責人（kanban.orchestrator_profile，未設定時使用當前的預設 profile）在所有子任務完成後醒來判斷是否完成。你可以切換 Kanban 頁面頂部的 Orchestration: Auto/Manual 切換鈕來切換模式。在手動模式下，點選卡片上的 ⚗ Decompose，或執行 hermes kanban decompose <id> / /kanban decompose <id>。對於不需要展開的單一任務，✨ Specify 會進行一次性規格重寫（目標、方法、驗收標準）並提升至 todo。在 config.yaml 的 auxiliary.kanban_decomposer 和 auxiliary.triage_specifier 下設定模型。詳見 Kanban 主指南中的 自動 vs 手動編排。
• Todo（待辦） — 已建立但等待依賴項，或尚未指派。
• Ready（就緒） — 已指派，等待 Dispatcher 認領。
• In progress（進行中） — Worker 正在執行此任務。預設開啟「Lanes by profile（按 profile 分道）」時，此欄位會按負責人分子群組，讓你一目了然每個 worker 正在做什麼。
• Blocked（阻塞） — Worker 請求人工介入，或斷路器觸發。
• Done（完成） — 已完成。

頂部工具列有搜尋、租戶和負責人的篩選器，以及一個 Lanes by profile 切換鈕和一個 Nudge dispatcher 按鈕，後者會立刻執行一次派發 tick，不用等到守護程式下一個週期。點選任意卡片會在右側展開其抽屜。

平面檢視

如果 profile 分道太雜亂，關閉「Lanes by profile」後，In Progress 欄位會合併為單一平面清單，按認領時間排序：

情境一 — 單一開發者交付功能

你要建一個功能。經典流程：設計 schema、實作 API、撰寫測試。三個任務，有 parent→child 的依賴關係。

SCHEMA=$(hermes kanban create "Design auth schema" \
    --assignee backend-dev --tenant auth-project --priority 2 \
    --body "Design the user/session/token schema for the auth module." \
    --json | jq -r .id)

API=$(hermes kanban create "Implement auth API endpoints" \
    --assignee backend-dev --tenant auth-project --priority 2 \
    --parent $SCHEMA \
    --body "POST /register, POST /login, POST /refresh, POST /logout." \
    --json | jq -r .id)

hermes kanban create "Write auth integration tests" \
    --assignee qa-dev --tenant auth-project --priority 2 \
    --parent $API \
    --body "Cover happy path, wrong password, expired token, concurrent refresh."

因為 API 的 parent 是 SCHEMA，tests 的 parent 是 API，所以只有 SCHEMA 會以 ready 狀態開始。另外兩個會留在 todo，直到它們的 parent 完成。這就是依賴提升引擎在運作 — 在有 API 可測試之前，不會有其他 worker 接手撰寫測試。

在下一次 Dispatcher tick（預設 60 秒，或你按下 Nudge dispatcher 時立即執行），backend-dev profile 會被派出去成為一個 worker，環境變數中帶有 HERMES_KANBAN_TASK=$SCHEMA。以下是 worker 模型在 agent 內部的工具呼叫迴圈：

# worker tool calls — 不是你執行的指令
kanban_show()
# → 回傳 title、body、worker_context、parents、prior attempts、comments

# （worker 讀取 worker_context，使用終端/檔案工具來設計 schema、
#   撰寫 migration、執行檢查、提交 — 真正的工作在這裡發生）

kanban_heartbeat(note="schema drafted, writing migrations now")

kanban_complete(
    summary="users(id, email, pw_hash), sessions(id, user_id, jti, expires_at); "
            "refresh tokens stored as sessions with type='refresh'",
    metadata={
        "changed_files": ["migrations/001_users.sql", "migrations/002_sessions.sql"],
        "decisions": ["bcrypt for hashing", "JWT for session tokens",
                      "7-day refresh, 15-min access"],
    },
)

kanban_show 會將 task_id 預設為 $HERMES_KANBAN_TASK，所以 worker 不需要知道自己的 id。kanban_complete 會將摘要和 metadata 寫入當前的 task_runs 列，關閉那次執行，並將任務狀態轉換為 done — 全部透過 kanban_db 的一次原子操作完成。

當 SCHEMA 進入 done 狀態時，依賴引擎會自動將 API 提升為 ready。API worker 在接手時，會呼叫 kanban_show() 並在父任務移交資料中看到 SCHEMA 的摘要和 metadata — 因此它不需要重新閱讀冗長的設計文件就能知道 schema 的決策。

點選看板上已完成的 schema 任務，抽屜會顯示所有資訊：

底部的執行紀錄區段是關鍵新增功能。一次嘗試：結果 completed，worker @backend-dev，耗時、時間戳記，以及完整的移交摘要。Metadata 資料（changed_files、decisions）也儲存在 run 上，並提供給任何讀取此 parent 的下游 worker。

你可以隨時在終端中查看相同的資料 — 這些指令是你在查看看板，不是 worker：

hermes kanban show $SCHEMA
hermes kanban runs $SCHEMA
# #  OUTCOME       PROFILE       ELAPSED  STARTED
# 1  completed     backend-dev        0s  2026-04-27 19:34
#     → users(id, email, pw_hash), sessions(id, user_id, jti, expires_at); refresh tokens ...

情境二 — 多 worker 批次作業

你有三個 worker（一個翻譯、一個逐字稿轉錄、一個文案撰寫），和一堆獨立的任務。你希望三個同時平行執行，並看到明顯的進度。這是最簡單的 kanban 使用情境，也是原始設計優化的目標。

建立工作項目：

for lang in Spanish French German; do
    hermes kanban create "Translate homepage to $lang" \
        --assignee translator --tenant content-ops
done
for i in 1 2 3 4 5; do
    hermes kanban create "Transcribe Q3 customer call #$i" \
        --assignee transcriber --tenant content-ops
done
for sku in 1001 1002 1003 1004; do
    hermes kanban create "Generate product description: SKU-$sku" \
        --assignee copywriter --tenant content-ops
done

啟動閘道然後離開 — 它承載了內建的 Dispatcher，會在同一个 kanban.db 上撿取三個專家 profile 的任務：

hermes gateway start

現在將看板篩選為 content-ops（或搜尋「Transcribe」），你會看到：

兩個逐字稿已完成，一個正在執行，兩個就緒等待下一次 Dispatcher tick。In Progress 欄位按 profile 分組（預設的「Lanes by profile」），讓你不需掃描混合清單就能看到每個 worker 的活躍任務。Dispatcher 會在目前任務完成後立即將下一個就緒任務提升為運行中。三個守護程式同時平行處理三個負責人的任務池，整個內容佇列在不需要人工介入的情況下就會被排空。

情境一中提到的所有結構化移交機制在此同樣適用。 翻譯 worker 完成一通電話時會發出 kanban_complete(summary="translated 4 pages, style matched existing marketing voice", metadata={"duration_seconds": 720, "tokens_used": 2100}) — 對分析和任何依賴此任務的下游任務都很有用。

情境三 — 角色管線與重試

這就是 Kanban 相比平面 TODO 清單的價值所在。PM 寫規格，工程師實作，審查者第一次被打回，工程師修改後再次嘗試，審查者通過。

儀表板視圖，篩選為 auth-project：

可以看到三階段鏈：Spec: password reset flow（DONE，pm）、Implement password reset flow（DONE，backend-dev）、Review password reset PR（READY，reviewer）。每個任務在底部以綠色顯示其 parent，以及作為依賴的 child。

最有意思的是實作任務，因為它被阻塞後重試過。以下是完整的三個 agent 協作流程，以每個 worker 模型發出的工具呼叫來呈現：

# --- PM worker 在 $SPEC 上啟動，撰寫驗收標準 ---
# worker tool calls
kanban_show()
kanban_complete(
    summary="spec approved; POST /forgot-password sends email, "
            "GET /reset/:token renders form, POST /reset applies new password",
    metadata={"acceptance": [
        "expired token returns 410",
        "reused last-3 password returns 400 with message",
        "successful reset invalidates all active sessions",
    ]},
)
# → $SPEC 完成；$IMPL 自動從 todo 提升為 ready

# --- Engineer worker 在 $IMPL 上啟動（第一次嘗試）---
# worker tool calls
kanban_show()   # 在 worker_context 中讀取 $SPEC 的摘要和驗收 metadata
# （工程師撰寫程式碼、執行測試、開啟 PR）
# 審查者回饋到達 — 工程師判斷問題合理並阻塞
kanban_block(
    reason="Review: password strength check missing, reset link isn't "
           "single-use (can be replayed within 30min)",
)
# → $IMPL 轉換為 blocked；run 1 以 outcome='blocked' 關閉

現在你（或另一個審查者 profile）讀取阻塞原因，判斷修復方向明確，從儀表板的「Unblock」按鈕解除阻塞 — 或從 CLI / 斜線指令：

hermes kanban unblock $IMPL
# 或從聊天中：/kanban unblock $IMPL

Dispatcher 將 $IMPL 重新提升為 ready，並在下一個 tick 派出 backend-dev worker。第二次啟動是同一個任務上的新 run：

# --- Engineer worker 在 $IMPL 上啟動（第二次嘗試）---
# worker tool calls
kanban_show()
# → worker_context 現在包含 run 1 的阻塞原因，所以這個 worker 知道
#   要修復哪兩件事，不需要重新閱讀整個規格
# （工程師加入 zxcvbn 檢查，讓 reset token 變成一次性使用，重新執行測試）
kanban_complete(
    summary="added zxcvbn strength check, reset tokens are now single-use "
            "(stored + deleted on success)",
    metadata={
        "changed_files": [
            "auth/reset.py",
            "auth/tests/test_reset.py",
            "migrations/003_single_use_reset_tokens.sql",
        ],
        "tests_run": 11,
        "review_iteration": 2,
    },
)

點選實作任務。抽屜顯示兩次嘗試：

• Run 1 — 被 @backend-dev 阻塞。審查回饋就在結果下方：「password strength check missing, reset link isn't single-use (can be replayed within 30min)」。
• Run 2 — 由 @backend-dev 完成。全新的摘要和 metadata。

每次 run 是 task_runs 中的一列，有自己的結果、摘要和 metadata。重試歷史不是疊加在「最新狀態」任務上的概念性事後補充 — 它是主要的表示方式。當重試的 worker 開啟任務時，build_worker_context 會顯示之前的嘗試，讓第二次嘗試的 worker 看到第一次為何被阻塞，並針對那些特定問題進行修復，而不是從頭重來。

審查者接手。當他們開啟 Review password reset PR 時，他們會看到：

Parent 連結指向已完成的實作。當審查者的 worker 在 Review password reset PR 上啟動並呼叫 kanban_show() 時，回傳的 worker_context 包含 parent 最近一次完成 run 的摘要和 metadata — 所以審查者在看 diff 之前，就已經拿到「added zxcvbn strength check, reset tokens are now single-use」和變更檔案清單。

情境四 — 斷路器與崩潰復原

真正的 worker 會失敗。缺少憑證、OOM 殺掉、暫時性網路錯誤。Dispatcher 有兩道防線：斷路器在連續 N 次失敗後自動阻塞，防止看板無限循環；崩潰偵測會回收那些 worker PID 已消失但 TTL 尚未到期的任務。

斷路器 — 看似永久性的失敗

一個部署任務因為 profile 的環境中沒有設定 AWS_ACCESS_KEY_ID 而無法啟動 worker：

hermes kanban create "Deploy to staging (missing creds)" \
    --assignee deploy-bot --tenant ops \
    --max-retries 3

Dispatcher 嘗試啟動 worker。啟動失敗（RuntimeError: AWS_ACCESS_KEY_ID not set）。Dispatcher 釋放認領、遞增失敗計數器，並在下一個 tick 重試。因為此範例設定了 --max-retries 3，斷路器在三次連續失敗後觸發：任務進入 blocked，結果為 gave_up。如果你省略此旗標，Hermes 使用 kanban.failure_limit（預設值：2）。在人工解除阻塞之前不會再重試。

點選被阻塞的任務：

三次 run，error 欄位都有相同的錯誤。前兩次是 spawn_failed（可重試），第三次是 gave_up（終止）。上方的事件日誌顯示完整序列：created → claimed → spawn_failed → claimed → spawn_failed → claimed → gave_up。

在終端中：

hermes kanban runs t_ef5d
# #   OUTCOME        PROFILE        ELAPSED  STARTED
# 1   spawn_failed   deploy-bot          0s  2026-04-27 19:34
#       ! AWS_ACCESS_KEY_ID not set in deploy-bot env
# 2   spawn_failed   deploy-bot          0s  2026-04-27 19:34
#       ! AWS_ACCESS_KEY_ID not set in deploy-bot env
# 3   gave_up        deploy-bot          0s  2026-04-27 19:34
#       ! AWS_ACCESS_KEY_ID not set in deploy-bot env

如果已接入 Telegram / Discord / Slack，閘道會在 gave_up 事件時發送通知，讓你不用查看看板就能得知中斷。

崩潰復原 — Worker 執行中途死亡

有時候啟動成功但 worker 之後死亡 — 當機、OOM、systemctl stop。Dispatcher 透過 kill(pid, 0) 輪詢偵測到死亡的 PID；認領釋放、任務回到 ready，下一個 tick 會交給新的 worker。

seed data 中的範例是一個 migration 執行時記憶體不足：

# Worker 認領任務，開始掃描 240 萬列，在約 230 萬列時被 OOM 殺掉
# Dispatcher 偵測到死亡的 PID，釋放認領，遞增嘗試計數器
# 使用分段策略重試，成功完成

抽屜顯示完整的兩次嘗試歷史：

Run 1 — crashed，錯誤為 OOM kill at row 2.3M (process 99999 gone)。Run 2 — completed，metadata 中有 "strategy": "chunked with LIMIT + WHERE id > last_id"。重試的 worker 在 context 中看到 run 1 的崩潰，並選擇了更安全的策略；metadata 讓未來的觀察者（或事後檢討者）一目了然地知道改變了什麼。

結構化移交 — 為什麼 summary 和 metadata 很重要

在上面每個情境中，worker 都在最後呼叫 kanban_complete(summary=..., metadata=...)。這不是裝飾 — 它是工作流各階段之間的主要移交通道。

當任務 B 的 worker 被啟動並呼叫 kanban_show() 時，它取得的 worker_context 包含：

• B 的先前嘗試（之前的 run：結果、摘要、錯誤、metadata），讓重試的 worker 不會重蹈覆轍。
• Parent 任務結果 — 每個 parent 最近一次完成 run 的摘要和 metadata — 讓下游 worker 看到上游工作為何以及如何完成。

這取代了困擾平面 kanban 系統的「翻留言和工作輸出」的窘境。PM 在規格的 metadata 中撰寫驗收標準，工程師的 worker 在父任務移交資料中結構化地看到它們。工程師記錄執行了哪些測試以及通過了多少，審查者的 worker 在看 diff 之前就已經手握那份清單。

批次關閉守護機制的存在是因為這些資料是按 run 儲存的。hermes kanban complete a b c --summary X（你從 CLI 執行）會被拒絕 — 將相同的摘要複製貼上到三個任務幾乎總是錯的。不帶移交標誌的批次關閉仍適用於常見的「我完成了一堆行政任務」情境。工具介面完全不提供批次變體；kanban_complete 始終是每次一個任務，原因相同。

檢查目前正在執行的任務

為求完整 — 以下是一個仍在進行中的任務的抽屜（情境一中的 API 實作，被 backend-dev 認領但尚未完成）：

狀態為 Running。活躍的 run 出現在執行紀錄區段，結果為 active 且沒有 ended_at。如果這個 worker 死亡或逾時，Dispatcher 會以相應的結果關閉這次 run，並在下一次認領時開新的 run — 嘗試列永遠不會消失。

後續步驟

• Kanban 概覽 — 完整的資料模型、事件詞彙表和 CLI 參考。
• hermes kanban --help — 所有子指令、所有旗標。
• hermes kanban watch --kinds completed,gave_up,timed_out — 即時串流整個看板的終止事件。
• hermes kanban notify-subscribe <task> --platform telegram --chat-id <id> — 在特定任務完成時取得閘道通知。

---

---

持久化目標