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/*`）以及各支援主機的插件適配器。