statewright/statewright

statewright – AI代理工具使用的防护机制

是什么 – 一个开源框架，可将基于LLM的代理（Claude Code、Codex、Cursor、OpenCode、Pi等）封装在确定性状态机中。每个状态定义了代理可调用的工具（读取、编辑、bash、测试等）、使用的模型、预算限制以及状态转移条件。引擎在运行时强制执行这些规则，拒绝非法工具调用，并提示用户进入适当的阶段。

为何重要 – 现代代码生成代理容易出现“脆弱”行为：反复读取文件、执行破坏性命令，或在测试未通过前就部署。Statewright通过限制代理行为缩小问题空间，将自由形式的提示转化为受控工作流，在无需更大模型的情况下提升可靠性。

核心组件

• 引擎（Rust） – 纯Rust状态机评估器，不依赖LLM，具有确定性。
• 代理二进制文件（sw-agent） – 通过Ollama或主机API在当前状态内执行LLM，流式输出JSONL事件，并遵守各状态的工具策略。
• 执行器 / MCP 网关 – 连接代理与主机平台（Claude Code、Codex、Cursor等），处理认证、会话隔离和遥测。
• TUI（statewright） – 基于 ratatui 构建的终端UI，可视化工作流，并支持通过斜杠命令启动/转移工作流。

主要功能

• 状态级工具强制 – 仅允许调用 allowed_tools 中列出的工具。
• Bash安全性 – 除非状态明确允许写入级操作，否则阻止破坏性重定向、rm -rf 和脚本解释器。
• 编辑限制 – 每个状态对编辑的行数/文件数有限制。
• 命令白名单 – 白名单测试命令（如 pytest）。
• 条件转移与审批门 – 转移可依赖运行时数据（测试结果）或需要人工审批。
• 模型路由 – 不同状态可指定不同模型（如诊断用廉价Haiku，修复用昂贵Opus）。
• 自托管 – 包含BYO Ollama的Docker-Compose堆栈（PocketBase + 网关）；Apache-2.0 许可的引擎。

快速开始（选择你的主机）

# Codex
npx statewright-codex@latest init
# Claude Code
/plugin marketplace add statewright/statewright && /plugin install statewright
# OpenCode、Cursor等
npx statewright-<host>@latest init

然后在 statewright.ai 注册，获取API密钥，运行工作流：

❯ start the bugfix workflow — fix the failing tests in calc.py
…
[statewright] testing => completed
Workflow complete. 46 s.

你也可以通过斜杠命令 /statewright start bugfix 调用。

研究快照 – 在SWE-bench的5个任务子集上，13GB以下的本地模型无法正确编辑文件，而13GB及以上的模型在Statewright约束下实现了10/10通过，证明了防护机制的有效性。

许可 – 引擎和代理为Apache 2.0；项目整体包含一个FSL-1.1-ALv2组件，将于2029年转换为Apache 2.0。专利承诺涵盖独立实现。

了解更多 – 完整文档、工作流模式和可视化编辑器请访问 https://docs.statewright.ai。仓库还包含示例工作流、Rust源码（`crates/*`）以及各支持主机的插件适配器。