statewright/statewright

源地址：https://github.com/statewright/statewright

智能体是建议，状态才是法律。状态机护栏控制你的 AI 智能体在每个阶段可以使用哪些工具。一次定义工作流，在 Claude Code、Codex、Cursor、opencode 和 Pi 中强制执行。完整文档 → (https://statewright.ai/docs)

Statewright 工作流编辑器

快速开始

在 Claude Code 的免费层级中运行以下命令即可体验：

/plugin marketplace add statewright/statewright
/plugin install statewright
/reload-plugins

然后运行 start the bugfix workflow 或 /statewright start bugfix。系统提示时需要粘贴你的 API 密钥。最新版本的 Claude 可能会提出异议——再次粘贴 API 密钥并明确表达你的意图，Claude 只是出于谨慎。

问题所在

AI 智能体强大但脆弱。给模型提供 40+ 种工具和开放式问题，它往往难以起步。常见的解决方案是使用更大的模型和更长的提示词……这有时有效。可观测性告诉你事后哪里出错了；但它无法预防问题。

解决方法

与其增大模型，不如缩小问题范围。状态机约束工具和解决方案空间，使模型在每一步都能在专注的上下文中推理。规划状态获取只读工具。当智能体过渡到实现阶段时，编辑工具解锁并限制 shell 访问权限（即使允许 Bash，重定向写入和破坏性操作也被阻止）。测试仅允许指定的测试命令。如果你调用当前阶段不可用的工具，会收到拒绝消息，告知你可用工具及如何过渡。

这种方式在前沿模型上效果相同（减少完成所需的 token），在本地模型上效果更明显，13B+ 的模型开始解决原本无法完成的任务。

研究结果

*使用专门的 edit_line 工具适配
†仅在 5 个任务中的 2 个上测试（在初始实验运行后添加）

我们在本地模型上进行了验证，因为效果最可衡量。在我们包含 5 个任务的 SWE-bench 子集中，两个模型（13.8GB 和 19.9GB）在 statewright 约束下从 2/10 提升到 10/10。相同的任务，相同的硬件。低于 13GB 的模型可以生成工具调用，但无法保留足够的文件内容以进行准确编辑——这是下限，而非 statewright 的限制。

前沿模型使用默认系统提示处理明显的灾难性操作（数据库删除、凭证泄露）……大多数时候可以。结构上的优势更大：打破反复读取相同文件 5 次以上却从未编辑的循环，以及保持工具空间足够小，使模型实际进行推理而非盲目尝试。

研究简报 → (https://statewright.ai/research)

快速入门

安装到 Claude Code：

/plugin marketplace add statewright/statewright
/plugin install statewright

浏览器将打开 → 在 statewright.ai (https://statewright.ai) 注册 → 生成密钥 → 粘贴 → 完成。

然后启动工作流：

❯ start the bugfix workflow — fix the failing tests in calc.py
◆ statewright — statewright_start (workflow: bugfix)
◆ [statewright] Workflow activated: bugfix
◆ statewright — statewright_get_state (MCP)
◆ Current phase: planning. Let me read the code first. Read 2 files
[statewright] planning => implementing
◆ statewright — statewright_transition (READY)
Edit calc.py: 1 line changed
[statewright] implementing => testing
◆ statewright — statewright_transition (DONE)
Bash: pytest -x — 7 passed
[statewright] testing => completed
◆ [statewright] Workflow complete. 46 seconds.

你也可以直接使用斜杠命令：/statewright start bugfix。

工作原理

核心是一个 Rust 引擎，用于评估状态机定义：状态、转换、守卫、工具限制。它是确定性的。循环中不包含 LLM。

在其之上是一个插件层，通过 MCP 与你的代码智能体集成。当你激活工作流时，钩子会自动强制执行每个状态的工具限制。模型看到 5 个工具而不是 30 个，获得当前阶段的清晰指令，并在满足条件时进行转换。

护栏

完整护栏参考见文档 (https://statewright.ai/docs/tools/reference)。

定义你自己的工作流

{
  "id": "bugfix",
  "initial": "planning",
  "states": {
    "planning": {
      "allowed_tools": ["Read", "Grep", "Glob"],
      "max_iterations": 8,
      "on": {
        "READY": "implementing"
      }
    },
    "implementing": {
      "allowed_tools": ["Read", "Edit", "Write"],
      "max_edit_lines": 20,
      "max_files_per_state": 3,
      "on": {
        "DONE": "testing"
      }
    },
    "testing": {
      "allowed_tools": ["Read", "Bash"],
      "allowed_commands": ["pytest", "cargo test", "npm test"],
      "on": {
        "PASS": {
          "target": "completed",
          "guard": "tests_passed"
        },
        "FAIL_TEST": "implementing"
      }
    },
    "completed": {
      "type": "final"
    }
  },
  "guards": {
    "tests_passed": {
      "field": "test_result",
      "op": "eq",
      "value": "pass"
    }
  }
}

状态机不是 DAG——它们会循环和重试，这正是智能体工作所需要的。指向 JSON schema (https://statewright.ai/workflow-schema.json)，智能体通过 statewright_create_workflow 生成工作流。在可视化编辑器 (https://statewright.ai/workflows) 中调整工具、命令和环境块。

支持的智能体

硬强制 = 在模型看到之前，在协议层阻止工具调用。
建议性 = 规则注入到上下文中但不强制执行。

定价

个人开发者免费。statewright.ai (https://statewright.ai) 的托管云处理工作流存储、运行历史和 MCP 网关。（这些层级可能会变化：价格不会增加，层级配额只会增加）

自托管

引擎 (crates/engine) 采用 Apache 2.0 许可，可嵌入且无运行时依赖。在 FSL 许可下允许单开发者和单团队自托管全栈。

use statewright_engine::{MachineDefinition, resolve_transition, validate_definition};

权衡

• 需要智能体支持 MCP（或非 MCP 智能体如 Codex 的钩子）
• 工作流定义需手动编写，尽管智能体可以通过 statewright_create_workflow 生成
• Cursor 的强制执行为建议性，非硬强制。MCP 本身无法在 Cursor 的架构中门控工具调用
• 研究结果来自 5 个任务的 SWE-bench 子集，而非完整的 2294 个实例基准
• 如果工作流过于严格，智能体会卡住。statewright_deactivate 是逃生舱口

文档

statewright.ai/docs (https://statewright.ai/docs) — 安装指南、工作流编写、schema 参考 (https://statewright.ai/docs/workflows/schema-reference)、MCP 工具参考 (https://statewright.ai/docs/tools/reference) 以及智能体生成的工作流 (https://statewright.ai/docs/tools/agent-generated-workflows)。

贡献

欢迎提交工作流定义、模板和错误报告。参见创建你自己的 (https://statewright.ai/docs/workflows/create-your-own/) 了解如何编写工作流。

许可证

Apache 2.0 — 部分采用 FSL-1.1-ALv2 (https://fsl.software)（2029 年 5 月 3 日转换为 Apache 2.0）。statewright.ai (https://statewright.ai) 的托管云。

一个钩子统治它们。