Step Switch

Step Switch는 유한한 비즈니스 워크플로우를 실행 가능한 데이터로 변환합니다. 하나의 Machine Spec, 스냅샷, 이벤트가 주어지면 전환을 결정론적으로 수락하거나 거부하고, 다음 스냅샷을 반환하며, 상징적 효과 의도를 생성합니다. 그 효과를 실제로 실행하지는 않습니다.

이 저장소에는 공유 TypeScript 코어 하나, CLI, Codex 플러그인의 읽기 전용 MCP 도구 여섯 개, 브라우저 편집기/시뮬레이터가 포함되어 있습니다.

완전한 statechart 런타임보다 의도적으로 작게 유지됩니다. 가드는 명시적으로 호출자가 제공하는 사실이고, 효과는 상징적 의도이며, Agent 입력은 인라인이고 폐쇄 세계(closed-world)이며, 어떤 표면도 사용자 코드를 평가하지 않습니다.

Codex 플러그인 설치

공개 소스 배포 채널은 GitHub 저장소 마켓플레이스입니다. v0.1.0 릴리스가 제공된 후:

codex plugin marketplace add tetracoralla/state-machine --ref v0.1.0
codex plugin add state-machine@state-machine

ChatGPT 또는 Codex를 다시 시작하고, 새 작업을 열고, 구체적인 Machine Spec을 사용하세요. 예를 들어 examples/order.machine.yaml 검증을 요청하거나, 스냅샷에서 이벤트가 합법적인지 테스트하거나, 이벤트 시퀀스를 시뮬레이션하도록 요청하세요. 일반적인 지원 요청은 machine.* 도구 호출 한 번이면 충분합니다.

저장소에는 .agents/plugins/marketplace.json과 커밋된 사전 빌드 서버가 포함되어 있어, 플러그인 사용자는 npm, TypeScript 또는 빌드 단계가 필요 없습니다. 마켓플레이스 및 호스트 동작에 대한 자세한 내용은 현재 OpenAI 플러그인 패키징 문서를 참조하세요.

소스에서 개발

npm ci
npm run check

Node.js 22 이상과 npm 10 이상이 필요합니다. Node 패키지는 의도적으로 비공개이며 npm 배포 채널이 아닙니다.

편집기 실행

npm ci
npm run build
npm run start:ui

http://127.0.0.1:4317을 여세요. 워크스페이스에는 주문 수명 주기 예제가 포함되어 있습니다. YAML 정의를 편집하고, 검증 및 토폴로지를 검사하고, 명시적 가드 결과를 선택하고, 이벤트를 실행하고, 추적 및 효과 의도를 검사하고, 대상 상태로의 경로를 찾고, 스펙을 가져오거나 내보낼 수 있습니다.

라이브 리로드로 개발하려면:

npm run dev:ui

CLI 사용

npm run build

node dist/node/adapters/cli.js validate examples/order.machine.yaml --pretty

node dist/node/adapters/cli.js step examples/order.machine.yaml \
  --event '{"type":"PAYMENT_SUCCESS","payload":{"amount":128,"payment_id":"pay_1024"}}' \
  --guards '{"payment_amount_matches":true}' \
  --pretty

node dist/node/adapters/cli.js simulate \
  examples/order.machine.yaml \
  examples/order.events.yaml \
  --pretty

node dist/node/adapters/cli.js path \
  examples/order.machine.yaml \
  completed \
  --pretty

CLI는 inspect와 diff도 지원합니다. 인수 없이 실행하면 전체 명령 요약이 표시됩니다. 종료 코드 0은 일반적인 전환 거부와 도달 불가능 경로를 포함하여 작업이 완료되었음을 의미합니다. 종료 코드 1은 머신 또는 작업 결과가 유효하지 않음을 의미하며, 종료 코드 2는 명령, 파일 또는 JSON 사용 오류를 위해 예약되어 있습니다. 모든 결과는 여전히 JSON으로 출력됩니다.

Agent 도구 사용

내장 플러그인은 plugins/state-machine입니다. 번들된 stdio MCP 서버, 매니페스트, use-state-machine Skill이 포함되어 있습니다. 이 저장소는 개인 마켓플레이스를 수정하거나 자동으로 설치하지 않습니다. 기여자는 사전 릴리스 테스트를 위해 로컬 체크아웃을 추가할 수 있습니다:

codex plugin marketplace add /absolute/path/to/state-machine
codex plugin add state-machine@state-machine

설치 또는 업그레이드 후 호스트를 다시 시작하고 새 작업에서 테스트하세요.

공개 도구:

모든 도구는 인라인 데이터를 수락하고, 외부 변경을 만들지 않으며, 엄격한 입력 스키마를 게시합니다. 결과는 서버를 떠나기 전에 실행 가능한 출력 스키마에 대해 검사됩니다. 여섯 도구 검색 카탈로그는 런타임 계약에 따라 36 KiB로 제한됩니다. 일반 요청은 직접 도구 호출 하나를 사용해야 합니다.

Machine Spec

정식 형식은 version: "0.1", initial 상태, 선언된 컨텍스트 및 이벤트 필드, 명명된 가드, 상태 맵을 포함하는 YAML 또는 JSON입니다. 각 상태/이벤트 쌍은 최대 하나의 전환을 소유합니다. 컨텍스트 할당은 태그가 지정된 literal, event, 또는 context 값 소스만 사용합니다. 효과는 상징적 type과 입력 값 소스만 포함합니다.

Machine Spec v0.1, 생성된 machine-spec.schema.json, 그리고 제공된 order.machine.yaml을 참조하세요.

프로젝트 검증

npm run check

이것은 타입 검사, 코어 테스트, 스키마 드리프트 검사, 모든 빌드, 내장 CLI 및 MCP stdio 테스트, 격리된 패키지 설치, 브라우저 상호작용 및 반응형 회귀, 플러그인/계약 검사를 실행합니다. 전반적인 시각적 및 비즈니스 수락은 소유자의 렌더링된 런타임 판단에 달려 있으며, 현재 경로는 docs/REVIEW_CONTRACT.md에 기록되어 있습니다.

기여 및 릴리스 세부 사항은 CONTRIBUTING.md 및 docs/RELEASE.md에 있습니다. 안정적인 공개 식별자는 docs/PRODUCT_IDENTITY.md에 기록되어 있습니다.

경계

v0.1은 의도적으로 계층적, 병렬, 기록, 지연, 행위자, 이벤트 없는 상태차트 의미를 제외합니다. 또한 표현식 평가, 효과 실행, 프로덕션 오케스트레이션, AI 생성 비즈니스 규칙, XState/SCXML 호환성 주장도 제외합니다. 현재 제품 경계는 docs/PRODUCT_MODEL.md에 유지됩니다.

라이선스

Step Switch는 Apache License 2.0에 따라 라이선스가 부여됩니다. LICENSE 및 NOTICE를 참조하세요. 독립형 플러그인에는 자체 사본과 브라우저 및 MCP 배포에 번들된 소프트웨어에 대한 라이선스 및 귀속 텍스트가 포함됩니다.