Step Switch

Step Switch превращает конечный бизнес-процесс в исполняемые данные. Получив одну Machine Spec, снимок и событие, он детерминированно принимает или отклоняет переход, возвращает следующий снимок и формирует символические намерения эффектов. Он никогда не выполняет эти эффекты.

Репозиторий включает одно общее ядро на TypeScript, CLI, шесть инструментов MCP только для чтения в плагине Codex и браузерный редактор/симулятор.

Он намеренно остаётся меньше, чем полноценная среда выполнения statechart: guards — явные факты, предоставляемые вызывающей стороной, эффекты — символические намерения, входные данные 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.*.

Репозиторий включает .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, проверяйте валидацию и топологию, выбирайте явные результаты guard, запускайте события, просматривайте трассировку и намерения эффектов, находите маршрут к целевому состоянию и импортируйте или экспортируйте спецификацию.

Для разработки с живой перезагрузкой:

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

Перезапустите хост и протестируйте в новой задаче после установки или обновления.

Публичные инструменты:

Все инструменты принимают встроенные данные, не вносят внешних изменений и публикуют строгие схемы ввода. Результаты проверяются по исполняемым схемам вывода, прежде чем покинуть сервер. Каталог обнаружения из шести инструментов ограничен 36 КиБ контрактом среды выполнения. Обычный запрос должен использовать один прямой вызов инструмента.

Machine Spec

Канонический формат — YAML или JSON с version: "0.1", начальным состоянием initial, объявленными полями контекста и событий, именованными guards и картой состояний. Каждая пара состояние/событие имеет максимум один переход. Присваивание контекста использует только тегированные источники значений 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 намеренно исключает иерархическую, параллельную, историческую, отложенную, акторную и бессобытийную семантику statechart. Он также исключает вычисление выражений, выполнение эффектов, производственную оркестрацию, бизнес-правила, сгенерированные ИИ, и заявления о совместимости с XState/SCXML. Текущая граница продукта поддерживается в docs/PRODUCT_MODEL.md.

Лицензия

Step Switch лицензируется по Apache License 2.0. См. LICENSE и NOTICE. Автономный плагин включает собственные копии, а также текст лицензии и атрибуции для программного обеспечения, включённого в браузерные и MCP-дистрибутивы.