graph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Graph Skill

Run a deterministic orchestration graph from a declarative JSON descriptor. The runtime consumes the sealed-descriptor and pure-scheduler contracts in

src/graph/*

and executes through an independent OS process (

omc graph run

), so crash recovery (kill mid-run, rerun, resume from journal) works for real.

从声明式JSON描述符运行确定性编排图。运行时使用

src/graph/*

中的密封描述符和纯调度器契约，并通过独立的OS进程执行（

omc graph run

），因此崩溃恢复（运行中途终止、重新运行、从日志恢复）可真正生效。

Usage

使用方法

/oh-my-claudecode:graph <descriptor.json>
/oh-my-claudecode:graph "build then test then ask me before deploy"   (author the descriptor first)

The execution surface is always the CLI subcommand:

omc graph run <descriptor.json> [--runs-root <dir>]

Run it via the Bash tool for non-interactive graphs. Progress lines stream as

[run]

[node]

[ok]

[fail]

[join]

[done]

/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]

流式输出。

When To Use

适用场景

Repeatable multi-step pipelines with explicit dependencies (DAG)
Work that must survive interruption: kill/restart resumes from journal
Auditable runs: OCC journal + projection snapshots under
```
.omc/graph-runs/<run_id>/
```

When NOT to use: exploratory one-off work (use conversation or /team); anything needing adaptive re-planning mid-run (graphs are deterministic).

具有显式依赖关系的可重复多步骤流水线（DAG）
必须能在中断后继续的工作：终止/重启后从日志恢复
可审计的运行：OCC日志和投影快照存储在
```
.omc/graph-runs/<run_id>/
```
下

不适用场景：探索性一次性工作（使用对话或/team）；运行中途需要自适应重新规划的任务（图是确定性的）。

Workflow

工作流程

Descriptor given -> go to step 3.
Pipeline described -> author the descriptor JSON (schema below), write it next to the project (suggest
```
.omc/graphs/<name>.json
```
) and show it to the user before running.
```
run_id
```
must be unique per logical pipeline; rerunning with the same
```
run_id
```
RESUMES, not restarts.
Approval nodes: if the descriptor contains any
```
"kind": "human-approval"
```
node, do NOT run it through the Bash tool (stdin is not interactive there; EOF fails closed to denied). Tell the user to run interactively instead:
```
! omc graph run <file>
```
The
```
!
```
prefix runs it inside this session with live stdin so y/n works.
Run and relay progress. Exit codes (normative): 0 succeeded | 1 terminal failed | 19 another writer owns this run (busy) 20 corrupt/tampered journal (fail-closed) | 21 descriptor drift on resume | 70 runtime crash (unmapped error)
Resume: rerunning the same command after a crash replays committed transitions and continues. Completed nodes never re-execute.

已提供描述符 -> 进入步骤3。
描述流水线 -> 编写描述符JSON（如下所示的 schema），将其放在项目旁边（建议路径为
```
.omc/graphs/<name>.json
```
），运行前展示给用户。
```
run_id
```
必须为每个逻辑流水线唯一；使用相同
```
run_id
```
重新运行将恢复而非重启。
审批节点：如果描述符包含任何
```
"kind": "human-approval"
```
节点，请勿通过Bash工具运行（此处标准输入非交互式；EOF将导致拒绝执行）。请告知用户改为交互式运行：
```
! omc graph run <file>
```
```
!
```
前缀会在当前会话中运行，并支持实时标准输入，以便进行y/n确认。
运行并传递进度信息。退出码（规范定义）： 0 成功 | 1 终端失败 | 19 该运行已被其他写入者占用（忙碌） 20 日志损坏/被篡改（执行失败） | 21 恢复时描述符发生变更 | 70 运行时崩溃（未映射错误）
恢复：崩溃后重新运行同一命令将重放已提交的转换并继续执行。已完成的节点不会重新执行。

Descriptor Schema (minimal)

描述符Schema（最简版）

{ "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" }

Edge kinds: fixed | conditional | fan_out/join pairs | back_edge (bounded retries via max_traversals). See src/graph/schema.ts for the authoritative Zod schema — and read the Capability Boundary section above for what built-in executors actually execute today.

边类型：fixed | conditional | fan_out/join 配对 | back_edge（通过max_traversals实现有限次数重试）。请查看src/graph/schema.ts获取权威的Zod schema — 同时请阅读上方的能力边界部分，了解当前内置执行器实际支持的功能。

Capability Boundary & Semantics (read before authoring)

能力边界与语义（编写前请阅读）

Edge support: built-in command/agent executors cover
```
fixed
```
edges and
```
fan_out
```
/
```
join
```
pairs.
```
conditional
```
and
```
back_edge
```
routes are fully supported by the runtime and scheduler contracts but require a custom NodeExecutor that emits
```
route
```
on its results — built-in executors never produce routes, so graphs relying on them fail fast with
```
route_required
```
rather than guessing.
Crash-recovery guarantee is at-least-once for command nodes: a crash between an external side effect and its journal append re-executes that node on resume. For
```
idempotent
```
commands, the resolved key is available to the command as
```
GRAPH_IDEMPOTENCY_KEY
```
before it starts and is also recorded for downstream dedupe. Built-in executors reject
```
reconcile
```
; reconciliation requires a custom executor with an actual external reconciliation authority. Exactly-once for external side effects is out of scope for v1.
Command trust boundary: command nodes are arbitrary shell lines with process authority in the current working directory. Only run descriptors you wrote or trust. Command children receive an allowlisted environment (PATH, HOME/USERPROFILE, TEMP/TMP, locale/timezone, USER identity,
```
GRAPH_*
```
, and the optional idempotency key), not the host's full secrets. Commands are not filesystem/process sandboxed.
Agent authority boundary: built-in agent nodes are explicitly read-only. They run in the current working directory with no additional directories, only
```
Read
```
,
```
Glob
```
, and
```
Grep
```
,
```
permissionMode: dontAsk
```
, session persistence disabled, and a provider-specific environment allowlist. Agent timeouts abort and interrupt the SDK query. Use a custom executor for any agent that needs mutation or external effects. Treat
```
.omc/graph-runs/<run_id>/descriptor.json
```
as executable content.

边支持：内置命令/agent执行器支持
```
fixed
```
边和
```
fan_out
```
/
```
join
```
配对。
```
conditional
```
和
```
back_edge
```
路由完全受运行时和调度器契约支持，但需要自定义NodeExecutor在结果中输出
```
route
```
— 内置执行器不会生成路由，因此依赖这些路由的图会快速失败并提示
```
route_required
```
，而非猜测执行。
崩溃恢复保证：命令节点至少执行一次：在外部副作用和日志追加之间发生崩溃时，恢复时会重新执行该节点。对于
```
idempotent
```
命令，解析后的键会在命令启动前以
```
GRAPH_IDEMPOTENCY_KEY
```
的形式提供，同时也会记录下来用于下游去重。内置执行器拒绝
```
reconcile
```
；协调需要带有实际外部协调权限的自定义执行器。v1版本不支持外部副作用的恰好一次执行。
命令信任边界：命令节点是具有当前工作目录进程权限的任意Shell命令行。仅运行您自己编写或信任的描述符。命令子进程会接收允许列表中的环境变量（PATH、HOME/USERPROFILE、TEMP/TMP、区域/时区、USER身份、
```
GRAPH_*
```
以及可选的幂等键），而非主机的完整机密。命令未进行文件系统/进程沙箱隔离。
Agent权限边界：内置agent节点明确为只读。它们在当前工作目录中运行，无额外目录权限，仅拥有
```
Read
```
、
```
Glob
```
和
```
Grep
```
权限，
```
permissionMode: dontAsk
```
，会话持久化已禁用，并使用特定于提供者的环境变量允许列表。Agent超时会中止并中断SDK查询。任何需要修改或外部副作用的agent请使用自定义执行器。请将
```
.omc/graph-runs/<run_id>/descriptor.json
```
视为可执行内容。