Hermes Kanban 完整說明

架構概念

Kanban 是一套內建在 Hermes 裡的持久化多人協作任務隊列，核心由三個角色組成：

┌─────────────────┐
│  你（調度者）      │  ← 拆任務、指派、看進度
│  Orchestrator    │
└────────┬────────┘
         │ 建立任務卡片
         ▼
┌─────────────────┐
│   Kanban Board   │  ← SQLite 持久儲存
│  (任務狀態機)     │
└────────┬────────┘
         │ 自動分配
         ▼
┌─────────────────┐     ┌─────────────────┐
│  backend-worker  │     │ frontend-worker  │  ← 不同機器上的 Profile
│  (機器 A)        │     │ (機器 B)         │
└─────────────────┘     └─────────────────┘

– Board：SQLite 資料庫，所有任務卡片、狀態、留言都存在這裡
– Profile：每個 worker 是一個獨立的 Hermes profile，有自己的設定、技能、記憶
– Dispatcher：內建在 gateway 裡的排程器，自動把 ready 狀態的任務分配給對應的 profile

—

任務生命週期

一張任務卡片會經歷以下狀態流轉：

todo → ready → in_progress → done
                  ↓
              blocked (等人類介入)
                  ↓
              ready (解鎖後重新分配)

– todo：已建立但有未完成的父任務，等父任務全部完成後自動升為 ready
– ready：等待 Dispatcher 分配 worker
– in_progress：worker 正在執行
– blocked：worker 需要人類決策，暫停等待
– done：任務完成，附帶總結和 metadata

Dispatcher 會自動處理：
– 相依任務的自動升等（父任務完成 → 子任務從 todo 變 ready）
– Claim TTL（約 15 分鐘）：worker 掛掉會自動回收任務
– 失敗重試：連續 spawn 失敗 N 次後自動 block（預設 2 次）

—

工作空間（Workspace）

每個任務執行時有三種工作空間模式：

scratch
• 說明: 獨立暫存目錄，任務結束後 GC
• 適合場景: 一次性計算、研究

dir:<path>
• 說明: 共享持久目錄，多次執行共享
• 適合場景: 需要累積狀態的任務

worktree
• 說明: Git worktree，獨立分支
• 適合場景: 寫程式（最常用）

worktree 模式最適合開發：每個任務在獨立 git 分支上工作，commit 後合併，不會互相踩腳。

—

跨機器協作：實際怎麼做

假設你有兩台機器：

機器 A（你的主力機） — 跑 gateway + 調度者 profile
機器 B（另一台伺服器） — 跑 worker profile

步驟 1：在兩台機器上都安裝 Hermes

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

步驟 2：建立 Profile

# 機器 A — 建立 orchestrator profile
hermes profile create orchestrator

# 機器 B — 建立 worker profile
hermes profile create backend-worker

步驟 3：共享 Kanban Board

Kanban board 是一個 SQLite 檔案，預設在 ~/.hermes/kanban.db。跨機器共享的方式：

– NFS / 共享檔案系統：兩台機器 mount 同一個目錄
– rsync / syncthing：同步 ~/.hermes/profiles/<name>/ 目錄
– Git：把 board 放在 shared repo 裡
– 雲端儲存：掛載 S3、Dropbox 等

最簡單的做法是讓兩台機器指向同一個 HERMES_HOME：

# 兩台機器都設定
export HERMES_HOME=/mnt/shared/hermes

步驟 4：啟動 Dispatcher

Dispatcher 通常內建在 gateway 裡（kanban.dispatch_in_gateway: true），只要 gateway 在跑就會自動分配任務：

# 機器 A
hermes gateway run

步驟 5：建立任務

# 機器 A — 拆解任務、建立看板
hermes kanban init
hermes kanban create "實作 RFID 簽到 API" --assignee backend-worker
hermes kanban create "撰寫單元測試" --assignee backend-worker --parent <上一張卡的ID>
hermes kanban create "更新前端簽到頁面" --assignee frontend-worker

步驟 6：Worker 接任務

# 機器 B — worker profile 跑起來，自動接任務
hermes -p backend-worker

Worker 啟動後會：
1. 讀取 kanban_show 看任務內容
2. 在 workspace 裡執行
3. 定期發 heartbeat 回報進度
4. 完成後呼叫 kanban_complete 附上總結

—

任務相依與平行化

Kanban 支援精細的相依關係：

# 研究任務 — 平行執行
t1 = kanban_create(title="研究方案 A", assignee="researcher")
t2 = kanban_create(title="研究方案 B", assignee="researcher")

# 整合任務 — 等 t1, t2 都完成才觸發
t3 = kanban_create(
    title="綜合分析並產出建議",
    assignee="analyst",
    parents=[t1["task_id"], t2["task_id"]]
)

# 實作任務 — 等分析完成
t4 = kanban_create(
    title="實作推薦方案",
    assignee="backend-worker",
    parents=[t3["task_id"]]
)

這個設計可以做到：
– Fan-out：多個獨立任務同時跑（研究 A + 研究 B 平行）
– Fan-in：結果匯集到一個整合任務
– Pipeline：企劃 → 實作 → 審查，階段式推進

—

審查流程

對於需要人類確認或跨 worker 審查的任務：

# Worker 完成程式碼後，不是 kanban_complete，而是 kanban_block
kanban_comment(body="變更檔案: api/auth.py, tests/test_auth.py\n測試: 14/14 passed")
kanban_block(reason="review-required: JWT 實作完成，請確認 token 過期策略")

# 審查者通過後：
hermes kanban unblock <task_id>

# 或審查者要求修改（建立新任務）：
hermes kanban create "修正 JWT refresh token 邏輯" --assignee backend-worker --parent <原任務ID>

—

失敗恢復

當 worker 出問題時，Kanban 看板會顯示 ⚠ 狀態，提供三種恢復方式：

1. Reclaim：立刻中止執行中的 worker，重置為 ready 讓 dispatcher 重新分配
2. Reassign：把任務換給另一個 profile（例如從壞掉的 backend-worker 換到 backend-worker-2）
3. 換模型：hermes -p backend-worker model 換一個模型再重試

—

實際案例：BuXiBan 專案拆分

假設你的 BuXiBan 有三台機器：
(1/2)

機器 A（你的筆電）: orchestrator + 前端開發
機器 B（伺服器）: 後端開發 + 資料庫
機器 C（NAS）: 測試執行

可以這樣分工：

Task 1: 分析現有 API 結構        → researcher (機器 B)
Task 2: 設計新資料表 schema       → db-designer (機器 B)
Task 3: 實作簽到 API              → backend-worker (機器 B)  ← 等 T1+T2
Task 4: 更新前端簽到 UI           → frontend-worker (機器 A) ← 等 T3
Task 5: 撰寫整合測試              → test-runner (機器 C)     ← 等 T3+T4
Task 6: Discord Bot 簽到通知      → backend-worker (機器 B)  ← 等 T3

Dispatcher 會自動處理順序：T1 和 T2 同時跑 → T3 和 T6 同時跑 → T4 等 T3 → T5 最後驗收。

—

限制與注意事項

– Profile 名稱必須真實存在：Dispatcher 不會自動建立 profile，指派到不存在的名稱會讓任務永遠卡在 ready
– Board 是硬邊界：不同 board 的任務無法互相參照
– 跨機器需要共享存儲：SQLite board 必須兩台機器都能讀寫
– 不適合即時同步：如果兩台機器的時鐘差距很大，可能影響 claim TTL

—

要我幫你實際在 BuXiBan 專案上設定 Kanban 嗎？先看看你目前有哪些 profile，然後我們可以建立一個適合你架構的看板。 (2/2)