ctrlrun 是 AI 智能体的执行安全层，一个 Python 库，位于智能体“决定行动”与“实际调用”之间。它不检测提示注入，而是约束后果：每个动作在执行前都会根据你定义的规则检查，允许的通过，敏感的等待人工，禁止的被阻止。有后果的动作至多执行一次、严格按批准内容执行，并留下收据。当结果未知时，ctrlrun 会明确标记为 AMBIGUOUS，而不是猜测。
主要能力
- 策略检查：读取即将离开进程的参数，回答“允许运行、询问人工、还是直接阻止”。策略文件 ctrlrun.yaml 中，金额使用整数最小单位（50000 表示 500 欧元），每个区间两端都绑定，未列出的动作默认拒绝，没有默认允许。
- 审批与委托：审批 ID 按运行生成，绑定到具体动作的哈希，单次使用、会过期，参数变更后审批失效。委托不能扩大权限。
- 至多一次执行：通过效果键（如 refund:txn_1）在一次原子写入中预留，第二个调用者（无论进程或主机）会被拒绝。
- 未知结果处理：丢失的回复标记为 AMBIGUOUS，而非 FAILED；在人工或 reconcile 钩子说明结果前，拒绝重试。
- 收据链：每次尝试（包括拒绝）都生成可移植 JSON 收据，包含谁、什么、决策、审批、效果键、结果及策略哈希，并链接到前一条收据。
- 权限与预算：每个主体需要授权，动作需要同时满足权限和策略两个轴，取更严格者。自 0.9 起授权可携带预算（滚动窗口内的指标限制），在预留时消耗。
- 存储：默认 SQLite（无服务器、无运维），跨进程预留；多主机写入时可指向 Postgres（pip install "ctrlrun[postgres]"）。
使用方式
- 编写策略文件 ctrlrun.yaml，声明智能体可以做什么。
- 用装饰器包裹有后果的调用：装饰器命名动作，效果键命名现实世界后果，上下文命名执行者。
- 人工从 shell 审批，授权绑定到人类阅读的确切动作哈希。
集成方式包括：@protect 装饰器覆盖进程内任何调用（原始模型调用、LangChain 工具、手写循环、cron 任务）；网关覆盖通过 MCP 到达工具的任何语言调用。适配器用于将审批决策路由到框架自身的中断，例如 ctrlrun-langgraph 提供预防，ctrlrun-openai-agents 提供归因。ctrlrun-langchain 是官方 LangChain 中间件集成，其 CTRLRunMiddleware 放入 create_agent(middleware=[...])，通过 LangChain 自身的 wrap_tool_call 门控每个工具调用。
适用场景
当智能体只能读取和回答时，不需要 ctrlrun；一旦它能发送、支付、退款、删除、部署、授予、撤销、批准、提交、购买或取消，就需要。示例领域包括退款、部署、IAM、删除、邮件、MCP 等九个领域，每个领域一个策略。
限制
- 不检测提示注入：它约束后果而非读取原因。
- 无法对不受控制的远程承诺恰好一次：它拒绝明知故犯地执行两次，也不回滚任何操作。
- 收据是链式的，可检测篡改，但无法检测末尾截断和伪造追加，因为捕获它们的头部是同一数据库中的一行；ctrlrun anchor 用于解决此问题。收据未签名：篡改不等于作者身份。
- 徽章表示声明的保证在运行环境中通过，不代表安全、合规、认证或审计。OWASP-AGENTIC-TOP10.md 列出了未涉及的四个条目。
其他信息
Apache-2.0 许可，执行内核将保持完全开源。文档位于 docs.ctrlrun.dev。安装：pip install ctrlrun && ctrlrun demo 可在本地运行演示。
