statewright/statewright

Statewright 是什么？

Statewright 是一个开源框架，允许您运行具有明确、可执行阶段的代理工作流。它为任务的每个步骤（例如，规划、实施、测试）定义了一个状态机，并控制每个阶段允许使用哪些 LLM 工具。当您将其插入受支持的 AI 客户端（Claude Code、Codex、Cursor、OpenCode、Pi、OMX 或自定义 MCP 主机）时，集成会拦截工具调用，阻止不允许的操作，并可以将不同阶段路由到不同的模型。

为什么重要

典型的 AI 辅助编码代理可以在整个任务过程中使用相同的工具，这使得它们很容易在审查之前编辑代码或在测试完成之前部署。Statewright 使这些边界变得明确，并且在主机支持的情况下，强制执行。这为您提供：

安全性 – 文件编辑或破坏性 shell 命令等工具仅在您指定的状态中允许。
细粒度模型路由 – 您可以为廉价阶段运行廉价模型，并为繁重阶段切换到更大的模型。
审批门 – 工作流可以在继续之前暂停以进行人工审查。
可重复、可审计的运行 – 每次转换、防护和工具使用都会被记录。

核心组件（如 README 中所述）

组件	语言 / 角色	主要职责
引擎 (`crates/engine`)	Rust	纯状态机评估器 – 无 LLM，确定性，提供防护、转换和工具允许列表。
代理二进制文件 (`crates/cli`, `sw-agent`)	Rust	在受限循环中执行 LLM，流式传输 JSONL 事件，尊重每状态模型路由，可以按需运行单个状态。
执行器 / 插件层 (`plugins/*`, `crates/mcp-gateway`)	Rust + 主机适配器	保存工作流会话、凭据、遥测，并为每个受支持的客户端（Claude、Codex、Pi 等）转换原生工具钩子。
TUI (`crates/tui`, `statewright`)	Rust (ratatui)	运行 `sw-agent` 的终端 UI，显示实时 JSONL 事件，并允许您与工作流交互。

工作流的外观

工作流是一个 JSON 定义，列出状态、允许的工具、可选的每状态模型、防护和转换。示例（简化）：

{
  "id": "bugfix",
  "initial": "planning",
  "meta": {"default_model": "claude-sonnet-4"},
  "states": {
    "planning": {"allowed_tools": ["Read","Grep"], "model": "claude-haiku"},
    "implementing": {"allowed_tools": ["Read","Edit","Write"]},
    "testing": {"allowed_tools": ["Read","Bash"], "allowed_commands": ["pytest"]},
    "completed": {"type": "final"}
  }
}

引擎强制执行 allowed_tools 列表，阻止不允许的 Bash 命令，并且可以在转换时要求人工批准。

支持的 AI 主机

Statewright 附带原生插件，支持：

Claude Code (0.3.4 候选版) – 原生 OAuth，预权限检查。
Codex – 托管 App-Server 适配器。
Pi、OpenCode、Cursor、OMX – 每个都有薄桥接，强制执行相同的护栏。自定义 MCP 主机也可以通过网关连接。

研究快照

在 5 任务 SWE-bench 子集上进行的小型实验表明，在 Statewright 约束下，较大的模型（13.8 GB gpt-oss:20b 和 19.9 GB gemma4:31b）解决了所有任务，而较小的模型失败了。作者指出，这不证明最小模型大小；它只是说明护栏有助于代理保持在正轨上。

定价与部署

托管云 在 [statewright.ai] – 免费层级（3 个工作流，200 次转换/月）和付费层级（$9/月 Pro，$99/月 Team，企业自定义）。计费涵盖工作流存储、运行历史和 MCP 网关。
自托管 – Docker-Compose 堆栈（PocketBase + 网关 + 编辑器）。您自带 Ollama 用于模型服务。引擎和代理是 Apache-2.0；网关目前是 FSL-1.1-ALv2（将在 2029 年转换为 Apache-2.0）。

权衡 / 限制

需要支持 MCP 的客户端或自定义钩子 – 并非所有 AI 聊天工具都支持。
工作流是手写 JSON（尽管代理可以通过 statewright_create_workflow 生成它们）。
过度限制的工作流可能导致代理卡住；statewright_deactivate 命令可以绕过防护。
研究结果仅限于一个很小的基准子集。

谁可能使用它？

开发团队 想要安全、可审计的 AI 辅助代码更改。
工具构建者 希望嵌入具有严格策略执行的 LLM 代理。
研究人员 探索状态机引导的提示或每状态模型路由。

TL;DR: Statewright 是一个基于 Rust 的开源工具包，允许您定义由状态机驱动的 AI 代理工作流，强制执行每状态工具权限，并将不同阶段路由到不同的模型。它与几个现代 AI 编码助手集成，可以自托管或通过托管云服务使用。