helm 是做什麼的？
一個即時的單任務工作面板。人類在瀏覽器中保持它開啟；你在工作時用低廉的 helm 呼叫更新它；短暫的本機伺服器會將變更即時串流到頁面上。人類可以隨時接手——編輯目標/方向——而你在下一次檢查點時跟隨它。
兩條規則
- 永遠只呼叫
helm。絕對不要手動寫入或編輯 HTML、伺服器、或 state.json。 每次helm呼叫只耗費少量 token，這正是重點：讓面板在工作時保持誠實且成本低廉。重新產生一個排版完整的頁面會花費 10 倍成本，並使其失去意義。 - 每次檢查點（在計畫步驟之間、任何不可逆操作之前）重新讀取人類的方向，使用
helm goal。人類透過頁面操控方向；你只有在查看時才會看到。如果目標或方向已改變，遵循新的版本並在event中說明。
輔助工具
helm 以建置好的、無依賴的 Node 腳本形式提供，位於 dist/helm.mjs（可以在裸的 node 上執行——不需要 npm install，安裝時也不需要建置）。只需抓取其路徑一次並重複使用：
HELM="<此技能目錄>/dist/helm.mjs" # 例如 ~/.claude/skills/helm/dist/helm.mjs
透過此路徑呼叫——"$HELM" … 可透過 shebang 執行，或使用 node "$HELM" …。如果你同時使用 Kubernetes，不要將其別名為單純的 helm——那是另一個不同的 helm。執行 init 後，面板會從當前工作目錄向上搜尋自動找到，因此後續呼叫不需要 --dir。
工作流程
-
初始化一次，在值得觀察的任務開始時。賦予它目標，讓人類從第一秒就能操控：
"$HELM" init --title "將認證遷移至 JWT" --agent "Claude Code" --model claude-opus-4-8 \ --goal "將 session 從 cookie 轉為無狀態 JWT，不遺失任何人"這會啟動伺服器並開啟瀏覽器。告訴使用者面板已上線，他們可以隨時在面板中編輯目標/方向。
-
規劃工作藍圖，讓他們看到工作的輪廓，然後逐步推進。
step N將較早的步驟標記為完成，將 N 設為當前活動，並更新進度——一次呼叫就能移動所有東西："$HELM" plan "備份使用者資料" "新增 RS256 發行/驗證" "遷移 session" "切換" "回歸測試" "$HELM" step 2 -
邊做邊記錄——小而頻繁、保持誠實。每次只是一個呼叫：
"$HELM" event ok "使用者資料表已備份至 backups/users.sql" "$HELM" event warn "3 個 session 使用舊的 cookie 格式，需要手動遷移" # 陷阱也在這裡 "$HELM" decide "選擇 RS256 而非 HS256，以便服務僅需公開金鑰即可驗證" "$HELM" decide "預設先部屬至 staging 環境，正式環境需等待人類確認" --assumption # 標記未經確認的假設 -
檢查點——讀取人類的方向並遵循：
"$HELM" goal # 印出目標 + 方向；如果人類編輯過，該行會顯示——遵循它如果方向改變，適應並記錄：
"$HELM" event info "方向已變更 → 僅進行 staging 環境"。 -
一旦出現真正的阻礙就提出；一旦得到答案就解決：
"$HELM" ask "先遷移 staging 還是正式資料庫？" # 僅限真正需要人類介入的問題 "$HELM" status "等待您決定正式環境" --state blocked # blocked/new 問題會通知人類 "$HELM" resolve 1 -
完成：
"$HELM" done "所有 session 已遷移，測試通過"。面板仍可檢視，然後伺服器在無人觀看時自動結束。"$HELM" stop立即結束它；"$HELM" open重新開啟它。
頻繁且小量更新。 狀態變更、完成一個步驟、一個陷阱、一個決策、一個新產出——每個都是一次呼叫。只有在逐分鐘追蹤真實情況時，面板才值得存在。
命令
| 命令 | 功能說明 |
|---|---|
helm init --title T [--subtitle S] [--agent A] [--model M] [--goal G] [--theme light|dark] [--no-open] | 建立面板、啟動伺服器、開啟面板。 |
helm status TEXT [--state running|blocked|waiting|done] [--phase P] [--pct N] | 設定當前活動行。blocked 會通知人類。 |
helm plan A B C … · helm plan --add TEXT | 設定計畫步驟，或追加一個步驟。 |
helm step N [--text NOW] | 前進到步驟 N：較早步驟標記為完成，N 設定為活動中，並更新 NOW 與進度。 |
helm event KIND TEXT | 附加一個時間軸條目。KIND ∈ ok fail warn info run。陷阱/死路 → warn/fail。 |
helm decide TEXT [--assumption] | 記錄一個決策；--assumption 標記為未經確認（以便人類糾正）。 |
helm ask QUESTION · helm resolve N | 新增/移除「需要你的輸入」項目（會通知人類）。 |
helm goal · helm goal --set TEXT | 讀取人類的目標 + 方向（在檢查點時這麼做），或設定目標。 |
helm link LABEL URL · helm image PATH [--label L] · helm data LABEL VALUE | 附加一個產出（連結/圖片/狀態）。 |
helm meta [--title …] [--subtitle …] [--theme …] [--agent …] [--model …] | 稍後編輯標頭欄位。 |
helm done [TEXT] · helm stop · helm open | 完成 · 立即停止伺服器 · 重新開啟面板。 |
慣例（會自動處理，或需要你遵守）
ask僅用於真正的決策。 絕不加入已經解決或反問式的問題。如果不需要人類介入，就保持空白——安靜的面板才是誠實的面板。--state控制即時脈衝、顏色和通知。 工作時使用running，卡住或等待人類時使用blocked/waiting（這些會透過桌面通知 + 標題列的 🔴 計數器提醒他們），結束時使用done。- 決策 vs 假設。 對於你已承諾的選擇使用
decide；對於你假設但尚未確認的事情使用--assumption。假設標記正是人類會及早發現你出錯的地方，所以誠實地標記它們。 - 來源頁尾和活動圖例會自動渲染——不要自己建構。
- 程序是短暫的。 當任務完成且無人觀看時會自行結束，且永遠不會重啟。如果頁面關閉期間有更新，它們仍會被儲存；
helm open會顯示最新狀態。
檔案
執行所需檔案（已提交、無依賴——位於 dist/）：
dist/helm.mjs——每次更新時呼叫的 CLI。dist/server.mjs——短暫的本機伺服器：提供 UI、透過 SSE 串流狀態、接收方向寫回、被遺棄時自行結束。dist/board.html——面板 UI（雙欄、薰衣草色淺色 + 深色主題），由伺服器提供。
建置方式（僅開發用，執行不需要）：src/*.ts（TypeScript 原始碼，共用一個 types.ts 定義資料模型）、build.mjs（esbuild）、package.json。編輯 src/ 後，執行 npm run build。參閱 DEVRULES.md 了解不可違反的規範。