Graph 스킬
선언적 JSON 설명자로 결정론적 오케스트레이션 그래프를 실행합니다.
런타임은 src/graph/*에 있는 sealed-descriptor 및 pure-scheduler 계약을 사용하며,
독립적인 OS 프로세스(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 도구를 통해 실행하지 마십시오(표준 입력이 인터랙티브하지 않으며; EOF는 거부로 간주됩니다). 대신 사용자에게 인터랙티브하게 실행하도록 알리십시오:! omc graph run <file>!접두사는 현재 세션 내에서 라이브 표준 입력으로 실행하여 y/n 입력이 작동하도록 합니다. -
실행 및 진행 상황 전달. 종료 코드(표준): 0 성공 | 1 종료 실패 | 19 다른 작성자가 이 실행을 소유 중(사용 중) 20 저널 손상/변조(실패-폐쇄) | 21 재개 시 설명자 불일치 | 70 런타임 충돌(매핑되지 않은 오류)
-
재개: 충돌 후 동일한 명령을 재실행하면 커밋된 전환을 재생하고 계속 진행합니다. 완료된 노드는 다시 실행되지 않습니다.
설명자 스키마 (최소)
{
"descriptor_version": 1,
"run_id": "unique-pipeline-id",
"revision_id": "rev-1",
"goal": "한 줄 설명",
"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": "진행하시겠습니까?" }
],
"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을 통한 제한된 재시도). 권위 있는 Zod 스키마는 src/graph/schema.ts를 참조하고,
아래 기능 경계 섹션에서 현재 기본 제공 실행기가 실제로 실행하는 내용을 확인하세요.
기능 경계 및 의미 (작성 전 읽기)
- 에지 지원: 기본 제공 명령/에이전트 실행기는
fixed에지와fan_out/join쌍을 지원합니다.conditional및back_edge경로는 런타임 및 스케줄러 계약에서 완전히 지원되지만, 결과에route를 내보내는 사용자 정의 NodeExecutor가 필요합니다 — 기본 제공 실행기는 경로를 생성하지 않으므로 이러한 그래프를 사용하면 추측 없이route_required오류와 함께 빠르게 실패합니다. - **충돌 복구 보장은 명령 노드에 대해 최소 한 번(at-least-once)**입니다. 외부 부작용과
저널 추가 사이에 충돌이 발생하면 재개 시 해당 노드가 다시 실행됩니다.
idempotent명령의 경우 확인된 키가 명령 시작 전에GRAPH_IDEMPOTENCY_KEY로 명령에 제공되며 다운스트림 중복 제거를 위해 기록됩니다. 기본 제공 실행기는reconcile을 거부합니다. 조정을 위해서는 실제 외부 조정 권한이 있는 사용자 정의 실행기가 필요합니다. 외부 부작용에 대한 정확히 한 번(exactly-once)은 v1 범위를 벗어납니다. - 명령 신뢰 경계: 명령 노드는 현재 작업 디렉토리에서 프로세스 권한을 가진 임의의 셸 라인입니다.
직접 작성했거나 신뢰하는 설명자만 실행하십시오. 명령 자식 프로세스는 허용 목록에 포함된 환경
(PATH, HOME/USERPROFILE, TEMP/TMP, 로케일/시간대, USER 식별자,
GRAPH_*및 선택적 idempotency 키)을 수신하며, 호스트의 전체 비밀은 포함되지 않습니다. 명령은 파일시스템/프로세스 샌드박스 처리가 되지 않습니다. - 에이전트 권한 경계: 기본 제공 에이전트 노드는 명시적으로 읽기 전용입니다.
현재 작업 디렉토리에서 추가 디렉토리 없이 실행되며,
Read,Glob,Grep,permissionMode: dontAsk만 사용하고, 세션 지속성은 비활성화되며, 제공자별 환경 허용 목록이 적용됩니다. 에이전트 시간 초과는 SDK 쿼리를 중단하고 인터럽트합니다. 변경 또는 외부 효과가 필요한 에이전트에는 사용자 정의 실행기를 사용하십시오..omc/graph-runs/<run_id>/descriptor.json을 실행 가능한 콘텐츠로 취급하십시오.