Step Switch

Step Switch verwandelt einen festgelegten Geschäftsablauf in ausführbare Daten. Bei einer gegebenen Machine Spec, einem Snapshot und einem Ereignis akzeptiert oder verwirft es deterministisch den Übergang, liefert den nächsten Snapshot zurück und gibt symbolische Effekt-Absichten aus. Es führt diese Effekte niemals aus.

Das Repository enthält einen gemeinsamen TypeScript-Kern, eine CLI, sechs schreibgeschützte MCP- Tools in einem Codex-Plugin sowie einen Browser-Editor/Simulator.

Es bleibt bewusst kleiner als eine vollständige Statechart-Laufzeitumgebung: Guards sind explizite, vom Aufrufer bereitgestellte Fakten, Effekte sind symbolische Absichten, Agent-Eingaben sind inline und abgeschlossen, und keine Oberfläche führt Benutzercode aus.

Codex-Plugin installieren

Der öffentliche Vertriebskanal ist der GitHub-Marktplatz. Sobald die Version v0.1.0 verfügbar ist:

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

Starten Sie ChatGPT oder Codex neu, öffnen Sie eine neue Aufgabe und verwenden Sie eine konkrete Machine Spec. Zum Beispiel bitten Sie es, examples/order.machine.yaml zu validieren, zu testen, ob ein Ereignis aus einem Snapshot zulässig ist, oder eine Ereignissequenz zu simulieren. Eine gewöhnliche unterstützte Anfrage sollte genau einen machine.*-Toolaufruf erfordern.

Das Repository enthält .agents/plugins/marketplace.json und den eingecheckten vorgebauten Server, sodass Plugin-Nutzer kein npm, TypeScript oder einen Build-Schritt benötigen. Siehe die aktuelle OpenAI-Plugin-Verpackungsdokumentation für Marktplatz- und Host-Verhalten.

Aus dem Quellcode entwickeln

npm ci
npm run check

Node.js 22 oder neuer und npm 10 oder neuer sind erforderlich. Das Node-Paket ist bewusst privat und kein npm-Vertriebskanal.

Editor ausführen

npm ci
npm run build
npm run start:ui

Öffnen Sie http://127.0.0.1:4317. Der Arbeitsbereich enthält ein Bestelllebenszyklus- Beispiel. Bearbeiten Sie die YAML-Definition, prüfen Sie Validierung und Topologie, wählen Sie explizite Guard-Ergebnisse, führen Sie Ereignisse aus, prüfen Sie Ablauf und Effekt-Absichten, finden Sie eine Route zu einem Zielzustand und importieren oder exportieren Sie die Spec.

Für Entwicklung mit Live-Neuladen:

npm run dev:ui

CLI verwenden

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

Die CLI unterstützt außerdem inspect und diff. Führen Sie sie ohne Argumente aus, um die vollständige Befehlsübersicht zu erhalten. Exit-Code 0 bedeutet, dass der Vorgang abgeschlossen wurde, einschließlich gewöhnlicher abgelehnter Übergänge und unerreichbarer Pfade. Exit-Code 1 bedeutet, dass die Maschine oder das Operationsergebnis ungültig ist; Exit-Code 2 ist für Befehls-, Datei- oder JSON-Nutzungsfehler reserviert. Jedes Ergebnis wird weiterhin als JSON ausgegeben.

Agent-Tools verwenden

Das gebaute Plugin ist plugins/state-machine. Es enthält den gebündelten Stdio-MCP- Server, das Manifest und die use-state-machine-Fähigkeit. Dieses Repository ändert keinen persönlichen Marktplatz und installiert sich nicht automatisch selbst. Mitwirkende können einen lokalen Checkout für Vorabversionstests hinzufügen:

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

Starten Sie den Host neu und testen Sie in einer neuen Aufgabe nach der Installation oder dem Upgrade.

Öffentliche Tools:

Alle Tools akzeptieren Inline-Daten, nehmen keine externen Änderungen vor und veröffentlichen strenge Eingabe- schemata. Ergebnisse werden gegen die ausführbaren Ausgabeschemata geprüft, bevor sie den Server verlassen. Der Discovery-Katalog mit sechs Tools ist auf 36 KiB durch den Laufzeitvertrag begrenzt. Eine normale Anfrage sollte genau einen direkten Toolaufruf verwenden.

Machine Spec

Das kanonische Format ist YAML oder JSON mit version: "0.1", einem initial-Zustand, deklarierten Kontext- und Ereignisfeldern, benannten Guards und einer Zustandsabbildung. Jedes Zustands-/Ereignis- paar besitzt höchstens einen Übergang. Die Kontextzuweisung verwendet nur getaggte literal-, event- oder context-Wertquellen. Effekte enthalten nur einen symbolischen type und Eingabewertquellen.

Siehe Machine Spec v0.1, das generierte machine-spec.schema.json und die mitgelieferte order.machine.yaml.

Projekt verifizieren

npm run check

Dies führt Typprüfungen, Kerntests, Schema-Abweichungsprüfungen, alle Builds, gebaute CLI- und MCP-Stdio-Tests, eine isolierte Paketinstallation, Browser-Interaktion und reaktionsfähige Regressionen sowie Plugin-/Vertragsprüfungen aus. Die gesamte visuelle und geschäftliche Abnahme bleibt dem Urteil des Eigentümers zur Laufzeitdarstellung überlassen; die aktuelle Route ist dokumentiert in docs/REVIEW_CONTRACT.md.

Beitrags- und Veröffentlichungsdetails finden Sie in CONTRIBUTING.md und docs/RELEASE.md. Stabile öffentliche Bezeichner sind dokumentiert in docs/PRODUCT_IDENTITY.md.

Abgrenzung

v0.1 schließt bewusst hierarchische, parallele, verzögerte, Akteurs- und ereignislose Statechart-Semantik aus. Es schließt außerdem Ausdrucksauswertung, Effektausführung, Produktionsorchestrierung, KI-generierte Geschäftsregeln und XState/SCXML-Kompatibilitätsansprüche aus. Die aktuelle Produktabgrenzung wird gepflegt in docs/PRODUCT_MODEL.md.

Lizenz

Step Switch ist unter der Apache License 2.0 lizenziert. Siehe LICENSE und NOTICE. Das eigenständige Plugin enthält eigene Kopien sowie den Lizenz- und Quellenangabetext für Software, die in die Browser- und MCP- Distributionen eingebettet ist.