Graph 技能 是做什麼的？
從宣告式 JSON 描述檔案執行確定性編排圖。
運行時會使用 src/graph/* 中的 sealed-descriptor 與 pure-scheduler 合約，並透過獨立的作業系統程序 (omc graph run) 執行，因此崩潰恢復（中途殺死、重新執行、從日誌恢復）是真實可用的。
使用方式
/oh-my-claudecode:graph <descriptor.json>
/oh-my-claudecode:graph "build then test then ask me before deploy" (先建立描述檔案)
執行介面始終是 CLI 子命令：
omc graph run <descriptor.json> [--runs-root <dir>]
對於非互動式圖，透過 Bash 工具執行。進度行會以 [run], [node], [ok], [fail], [join], [done] 的形式串流輸出。
何時使用
- 可重複的多步驟管線，具有明確的依賴關係 (DAG)
- 必須能承受中斷的工作：殺死/重啟從日誌恢復
- 可審計的運行：
.omc/graph-runs/<run_id>/下的 OCC 日誌 + 投影快照
何時不應使用：探索性的一次性工作（使用對話或 /team）； 需要在中途進行適應性重新規劃的任何工作（圖是確定性的）。
工作流程
-
已給定描述檔案 -> 前往步驟 3。
-
管線已描述 -> 建立描述 JSON（架構如下），將其寫在專案旁（建議
.omc/graphs/<name>.json），並在執行前顯示給使用者。run_id在每個邏輯管線中必須唯一；使用同一個run_id重新執行是恢復，而不是重新開始。 -
審批節點：如果描述檔案包含任何
"kind": "human-approval"節點，請勿透過 Bash 工具執行（stdin 在那裡不是互動式的；EOF 會以拒絕作為失敗關閉）。請告知使用者以互動方式執行：! omc graph run <file>!前綴會在此工作階段內執行，並啟用即時 stdin，因此 y/n 可以正常運作。 -
執行並回報進度。退出碼（規範）： 0 成功 | 1 終端失敗 | 19 另一個寫入者擁有此運行（忙碌） 20 損毀/遭篡改的日誌（失敗關閉）| 21 恢復時描述檔案偏移 | 70 運行時崩潰（未對應的錯誤）
-
恢復：崩潰後重新執行相同命令會重播已提交的轉換並繼續。已完成的節點絕不會重新執行。
描述檔案架構（最小化）
{ "descriptor_version": 1, "run_id": "unique-pipeline-id", "revision_id": "rev-1", "goal": "one line", "nodes": [ { "id": "n1", "kind": "command", "title": "...", "timeout_ms": 60000, "max_attempts": 2, "effect_policy": { "policy": "side_effect_free" }, "command": "npm test" }, { "id": "a1", "kind": "agent", "title": "...", "timeout_ms": 300000, "max_attempts": 1, "effect_policy": { "policy": "side_effect_free" }, "instructions": "..." }, { "id": "gate", "kind": "human-approval", "title": "...", "prompt": "Proceed?" } ], "edges": [ { "id": "e1", "kind": "fixed", "from": "n1", "to": "a1" } ], "entry_node_ids": ["n1"], "concurrency_limit": 2, "terminal_verification_node_id": "a1" }
邊的種類：fixed | conditional | fan_out/join 配對
| back_edge（透過 max_traversals 限制重試次數）。請參閱 src/graph/schema.ts 以取得權威的 Zod 架構 — 並閱讀上方「能力邊界」章節，了解哪些內建執行器目前實際可執行。
能力邊界與語意（建立前請閱讀）
- 邊支援：內建的 command/agent 執行器涵蓋
fixed邊與fan_out/join配對。conditional和back_edge路徑完全受運行時和排程器合約支援，但需要一個自訂的NodeExecutor來在其結果上發出route— 內建執行器從不產生路線，因此依賴它們的圖會在route_required時快速失敗，而不是猜測。 - 崩潰恢復保證：對於命令節點是至少一次：在外部副作用與其日誌附加之間發生的崩潰，會在恢復時重新執行該節點。對於
idempotent命令，解析的金鑰在命令開始前可作為GRAPH_IDEMPOTENCY_KEY提供給命令，並記錄下來供下游重複資料刪除使用。內建執行器拒絕reconcile；協調需要一個具有實際外部協調權限的自訂執行器。外部副作用的恰好一次處理不在 v1 範圍內。 - 命令信任邊界：命令節點是任意的 shell 行，在目前工作目錄具有程序權限。只能執行您撰寫或信任的描述檔案。命令子程序會接收一個允許清單環境（PATH, HOME/USERPROFILE, TEMP/TMP, locale/timezone, USER 身分,
GRAPH_*，以及可選的冪等性金鑰），而不是主機的完整機密。命令不會進行檔案系統或程序沙箱隔離。 - 代理權限邊界：內建代理節點是明確的唯讀模式。它們在目前工作目錄中執行，沒有額外的目錄，僅有
Read,Glob, 和Grep，permissionMode: dontAsk，停用工作階段持久性，以及一個提供者特定的環境允許清單。代理超時會中止並中斷 SDK 查詢。對於任何需要變更或外部效果的代理，請使用自訂執行器。請將.omc/graph-runs/<run_id>/descriptor.json視為可執行內容。