Atlas-X-AI/hermes-kanban-watch

Hermes Kanban 監控（Watch）

在不佔用卡片的情況下，在 Claude Code 中顯示 Hermes 工作者的執行狀態。執行中的卡片會顯示即時行，佇列中的卡片會顯示等待行，而停止的卡片則會顯示「需要您處理」行。被監控卡片的已提交子卡片會自動加入，除非設定 follow_new: false。

安裝與檢查

使用 claude --plugin-dir /path/to/hermes-kanban-watch/plugin 啟動 Claude Code。呼叫方需解析此技能的外掛根目錄；請使用同目錄下的 scripts/doctor.py。

首先執行 python3 <plugin-root>/scripts/doctor.py --board default。此操作為唯讀。 --fix 會建立缺少的預設看板（使用 hermes kanban --board default init）或缺少的命名看板（使用 hermes kanban boards create <slug>），同時建立使用者路由和一個 hermes-kanban-live 墊片，且不會覆蓋現有檔案。請將 ~/.local/bin 加入 PATH 並重新執行 doctor。

Doctor 要求 hermes-kanban-live --version 必須精確輸出 hermes-kanban-watch 0.3.0。若遇到外部/舊版命令，則會顯示 FAIL 及其解析路徑；移動該命令或修正 PATH 後再重新執行 --fix，此選項不會覆蓋它。 --probe 會以 PONG 明確測試每個路由模型，並可能消耗配額。

需求：Python 3.11+、PATH 中有 Hermes、支援 Workflow 的 Claude Code，以及現有的 Hermes 設定檔。模型和金鑰屬於每個 Hermes 設定檔：API 金鑰、訂閱登入或本地模型，由 Hermes 配置，而非此外掛。 該外掛不提供帳戶或複製憑證。Claude 觀察者模型的使用量與 Hermes 工作者的提供者使用量是分開計算的。

正常提交卡片

首先使用 hermes kanban boards create demo 建立一個命名看板，然後使用 hermes kanban --board demo create "建置功能" --assignee builder。 使用 hermes kanban swarm --help 來選擇上游的 swarm 旗標。提交操作不會 啟動調度器。請透過 Hermes 分別啟動/委派工作者。 Post-Bash 鉤子會在 create/swarm 之後建議 /kanban-watch；它本身絕不會啟動 或調度任何操作。避免在同一個波次上建立重複的監控。

提交一個已路由、已固定的卡片

僅在明確的提交請求時使用：python3 <plugin-root>/scripts/file_card.py --board demo --class app-code --title "建置功能" --body-file /path/to/brief.txt --routes /path/to/routes.yaml --worktree /absolute/path/to/worktree。 --routes 和 --worktree 為選用。該命令會透過 route.py 解析工作者/不同系列驗證器，建立一個已固定的工作者，執行 set-model，驗證 show --json，然後輸出其 ID 和精確的 /kanban-watch 參數。它不會建立驗證器、調度器、Workflow 或 worktree，也不會開啟任何設定檔或憑證。切勿將此授權命令授予觀察者。 --dry-run 會驗證檔案/路由/看板，並列印命令而不執行 Hermes；會列印簡報內容，因此請確保 secrets 不包含在其中。會拒絕缺少的看板/無效的路由。部分失敗後，請檢查傳回的 ID，切勿盲目重新提交。請參閱完整提交細節；僅在要求時啟動監控。

在 PONG 檢查後建議路由

僅在獲得明確的容量批准後執行 python3 <plugin-root>/scripts/doctor.py --board demo --routes /path/to/routes.yaml --probe --suggest-routes /path/to/routes-checked.yaml。它需要 --probe，拒絕已存在的目的地（包括目錄/符號連結），絕不改變來源路由或啟用提案。在選擇它之前審查設定檔/提供者/成本變更。 兩個通道都必須通過本次執行的 PONG，並具有不同的宣告系列，而不僅僅是不同的主機。會保留通過的工作者/驗證器；替換使用字典序通道順序。沒有配對的類別將被省略，並附上診斷註解；沒有配對則表示路由無法使用。原始失敗仍會以 exit 1 終止。PONG 不代表適用性或持久容量。請參閱選擇與稽核細節。

啟動

將 $ARGUMENTS 視為 JSON 參數物件。解析已安裝外掛的 workflows/kanban-watch.js，然後呼叫 Workflow({scriptPath: "<plugin-root>/workflows/kanban-watch.js", args: <args>})。 如果 Workflow 不可用，請報告該限制並直接執行唯讀的 hermes-kanban-live 命令，切勿假裝已建立即時工作流程行。

參數範例：

• {"board":"default","tasks":["t_1234abcd"]}
• {"board":"demo","phases":[{"title":"建置","tasks":["t_1234abcd"]},{"title":"驗證","tasks":["t_11111111"]}]}
• {"board":"demo","follow_new":false,"stale_days":7,"max_hours":12}

單純的看板監控會包含佇列中/執行中的卡片，跳過閒置時間超過 stale_days（預設 7）的佇列中卡片。設定 stale_days: 0 會停用過濾；明確的 ID 會始終保留。使用 verbose: true 顯示舊版工作者文字和工具結果。 讀取器是 PATH 上的 hermes-kanban-live；live_cmd 可以用安全命令覆蓋它，例如 python3 ~/plugins/hermes-kanban-watch/plugin/scripts/kanban_live.py。只接受字母、數字、空格、/、.、_、-、~。不允許 shell 運算子。 每行預設使用外掛的 hermes-kanban-watch:kanban-watcher 代理；不需要私人使用者代理。agent_type 可以指定其他可用的代理，使用 ASCII 字母、數字、-、_，並可在非空名稱之間加上一個可選的 :。

讀取結果

DONE 是觀察到的卡片結果，而非整合或使用者驗收。請檢查實際模型、備用方案、警告、摘要和可交付成果。BLOCKED/REVIEW 會顯示「需要您處理」行，並可能在恢復時重新啟動。NOT_STARTING 表示已準備就緒但調度器未啟動它。UNKNOWN 表示讀取失敗，而非卡片消失。逾時僅在以 exit 3 結束時重試；270 秒的喚醒間隔可將等待時間保持在提示快取 TTL 以下。觀察者絕不會對工作者的文字採取行動、變更卡片、修復任何問題或繞過權限。

當工作者訊息不可用時，每個執行/觀察者會遵循一次報告，並使用卡片日誌；心跳不計入次數。 增長的/變更的日誌可防止發出可能卡住的警告。僅有連續兩次相同運行的執行呼叫且日誌無變動時，才會被標記；首次觀察、運行變更和不可讀訊號不計入。有訊息時，連續兩次安靜呼叫會觸發標記。

使用 python3 <plugin-root>/scripts/route.py --class app-code 檢查選用的 路由表。它會傳回工作者和不同系列驗證器的 JSON；它絕不會提交 或調度卡片。編輯使用者路由以指定您自己的設定檔和模型系列。

人類詢問約定

對於 hermes-kanban-live needs，請以 ASK OPERATOR: 開頭開始註解行，後接 問題。在行文中提及如「還沒有 ASK OPERATOR」不算詢問。受阻或 依賴等待的理由必須包含 waiting on operator、waiting for operator 或 needs operator 以匹配當前的人類等待。這些是明確的文字約定， 而非自然語言意圖偵測。需要您處理的工作流程行會分別標記 受阻/審查結果以及已準備就緒但未啟動的卡片。

報告一波任務的實際運行次數與經過時間

執行 hermes-kanban-live report --board demo，可選擇重複 --task T 或 加入 --since EPOCH。不提供任務 ID 時，這會包含所有狀態，包括 已完成/已封存。--since 選擇卡片建立時間；它與任務選擇相交集 且不會裁剪個別運行。JSON 在 cards 中包含每個卡片的物件，以及 totals、read_status、now 和 missing。每個卡片包含 id/title/status、 assignee、實際最後一次運行的 model_used、provider_used、fallback_from、runs、 retried、duration_s 和最後一次運行的警告計數。未知的運行資料保持為 null。

totals.by_status 計算卡片數量；run_seconds 計算所選卡片的所有已知運行持續時間總和 （正在運行的運行在 now 時測量）；fell_back 計算在任何嘗試中回退的卡片數量；retried 計算具有保守重試防護（多次運行或重試/阻塞歷史事件）的卡片數量。這些是經過的秒數， 而非計費的代幣/貨幣成本。加入 --format text 以獲得對齊的純文字 列和總計，不使用 Markdown。Exit 4 表示缺少明確的 ID；exit 5 表示無法讀取的看板。僅被 --since 排除的卡片不算遺失。

檢查實際工作者/驗證器系列獨立性

執行 hermes-kanban-live verify-pair --board demo --worker T --verifier V， 可選用 --families FILE。它使用每個卡片最新完成的運行（非 null ended_at，最新的運行 id），而非模型固定或更新的未完成嘗試。JSON 包含每個實際的 model_used、provider_used、run_id、映射的 family 和 different_families。運行的實際提供者透過路由檔案中的 providers 映射到其模型系列。將相同系列的主機映射一致；多系列 主機需要特定於系列的識別符。這不會從模型前綴推斷系列，也不證明 審查工作已發生。

查詢順序與 route.py 相同：明確的 --families、KANBAN_WATCH_ROUTES、 ~/.config/hermes-kanban-watch/routes.yaml、隨附的範本。只需要有效、非空 的 providers 映射。Exit 0 表示不同系列，1 表示相同系列或 無效/未知分類，3 表示任一 ID 沒有完成的運行，5 表示無法讀取的看板。分類錯誤會將 different_families 設為 null 並包含 error； 切勿將 UNKNOWN 轉換為成功的檢查。 對於直接 Claude Code 呼叫，僅請求 Bash(hermes-kanban-live report:*) 和 Bash(hermes-kanban-live verify-pair:*)，而非不受限制的 Bash 權限。

在逾時期間保持父問題監控啟動

執行 hermes-kanban-live needs --board demo --loop --created-by PARENT --cursor-key WAVE 一次，而非在每次 exit 3 後重建命令。在循環模式中 --since 為選用，在啟動時若未提供則捕獲一次，且在逾時視窗期間絕不推進。 其首次輪詢包括仍有效的既有等待，包括 建立者較舊的父問題。已回答/已恢復/已取代的舊等待會保持排除，且現有的已見過游標重複資料刪除仍然適用。

循環模式在 --interval 休眠，並僅重試一般的逾時，不會造成逾時 JSON 更新。它在第一個非空 items 結果時以 exit 0 退出，或在遇到錯誤時失敗 而不重試。--max-seconds 限制每個視窗，而非命令的總生命週期； 取消呼叫者以停止安靜的監控。沒有 --loop 時，必需的 --since、 exit-3 逾時和輸出行為保持不變。這仍然是讀取器，絕不授予 回答、調度或變更卡片的權限。

功能指南

• 波次時間與實際運行報告：實際運行、重試和經過秒數，而非計費成本。
• 驗證實際執行的系列：已完成運行的系列證據，而非模型固定。
• 使用自己的逾時循環一次性啟動 needs：在逾時期間唯讀的父問題等待。
• 列印固定頭部 PR 合併收據：獨立驗證器、精確頭部、CI 和合併狀態檢查；永不進行合併。
• 觀察者代幣成本：僅計數的 Claude 觀察者使用量，與工作者時間分開。
• 父卡片上的重複工作者與問題：觀察流程警告和父等待；永不修復它們。
• 提交修復並重新驗證先前的裁決：僅限明確授權；重複使用驗證器固定，可選的父註解，不進行調度。
• 工作流程擁有的等待回合：在一個截止時間下的健康唯讀等待。
• 建議固定答案而不發布：為授權審查列印提案，永不發布。