Step Switch

Step Switchは、有限のビジネスワークフローを実行可能なデータに変換します。1つのMachine Spec、スナップショット、イベントが与えられると、遷移を決定論的に受理または拒否し、次のスナップショットを返し、シンボリックなエフェクトインテントを出力します。エフェクトを実行することはありません。

リポジトリには、1つの共有TypeScriptコア、CLI、Codexプラグイン内の6つの読み取り専用MCPツール、ブラウザエディタ/シミュレータが含まれています。

完全なステートチャートランタイムよりも意図的に小さく保たれています。ガードは明示的な呼び出し元提供のファクトであり、エフェクトはシンボリックなインテントであり、Agentの入力はインラインでクローズドワールドであり、ユーザーコードを評価するサーフェスはありません。

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.*ツール呼び出しが1回必要です。

リポジトリには.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スキルが含まれています。このリポジトリは個人用マーケットプレイスを変更したり、自動的にインストールしたりすることはありません。コントリビューターは、プレリリーステスト用にローカルチェックアウトを追加できます：

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

インストールまたはアップグレード後、ホストを再起動し、新しいタスクでテストします。

公開ツール：

すべてのツールはインラインデータを受け入れ、外部変更を行わず、厳密な入力スキーマを公開します。結果は、サーバーを離れる前に実行可能な出力スキーマに対してチェックされます。6ツールのディスカバリカタログは、ランタイム契約により36 KiBに制限されています。通常のリクエストでは、直接ツール呼び出しを1回使用する必要があります。

Machine Spec

正規形式はYAMLまたはJSONで、version: "0.1"、initial状態、宣言されたコンテキストとイベントフィールド、名前付きガード、状態マップを持ちます。各状態/イベントのペアは、最大1つの遷移を所有します。コンテキストの割り当ては、タグ付けされた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ディストリビューションにバンドルされているソフトウェアのライセンスと帰属テキストに加えて、独自のコピーが含まれています。