Step Switch

Step Switch 将有限的业务流程转化为可执行数据。给定一个 Machine Spec、一个快照和一个事件，它确定性地接受或拒绝转换，返回下一个快照，并发出符号化的效果意图。它从不执行这些效果。

该仓库包含一个共享的 TypeScript 核心、一个 CLI、Codex 插件中的六个只读 MCP 工具，以及一个浏览器编辑器/模拟器。

它刻意保持比完整的 statechart 运行时更小的规模：守卫是调用方显式提供的事实，效果是符号化意图，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 定义，检查验证与拓扑，选择显式的守卫结果，运行事件，检查轨迹与效果意图，找到通往目标状态的路径，并导入或导出规范。

如需带热重载的开发模式：

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

规范格式是 YAML 或 JSON，包含 version: "0.1"、一个 initial 状态、声明的上下文与事件字段、命名守卫以及状态映射。每个状态/事件对最多拥有一个转换。上下文赋值仅使用带标签的 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 有意排除层次化、并行、历史、延迟、actor 和无事件 statechart 语义。它还排除表达式求值、效果执行、生产编排、AI 生成的业务规则以及 XState/SCXML 兼容性声明。当前的产品边界维护在 docs/PRODUCT_MODEL.md 中。

许可证

Step Switch 采用 Apache License 2.0 许可。请参阅 LICENSE 和 NOTICE。独立插件包含其自身的副本，以及捆绑到浏览器和 MCP 发行版中的软件的许可证与署名文本。