CTRLRun：AI 智能体执行安全层

项目简介

CTRLRun 是一个开源的 AI 智能体执行安全层（Execution Safety Layer），以 Python 库的形式夹在智能体决策层和实际执行调用之间，在每次工具调用真正发出前核验其行为是否符合预定义规则，从根本上防止 AI 做出超权限操作。

核心功能

• 精确参数核验：在工具调用发出前，检查传入参数是否在合法范围内，例如退款金额不超过规定上限，防止一个多余零导致超额转账。
• 去重效果（Effect）机制：通过唯一效果键（effect key）标记操作，防止网络丢包导致的重复执行或 retry 风暴，即使智能体因超时重试，相同效果的操作也只执行一次。
• 人工审批工作流：对于敏感操作，系统可选择暂停等待人工确认，确认通过后才放行执行，整个过程留下完整操作凭证（receipt）。
• 并发冲突防护：多智能体协作场景下，自动检测对同一资源的并发操作请求，防止幽灵重复扣款等竞态条件问题。
• 审批溯源机制：每一次人工审批都与具体操作哈希绑定，审批后若参数被篡改，调用直接被拦截，确保审批内容与实际执行内容一致。
• 操作全链路审计：每次请求、决策、结果（包括拒绝）均被记录，支持事后审计和合规回溯。
• 单文件轻量部署到生产级扩展：一行 pip install 后即可在单个 Python 文件中快速集成，也可扩展至 Postgres 多主机分布式部署。
• 灵活的规则引擎：四条核心规则（精确参数、一次生效、结果确认、完整记录）可通过规则文件自定义，无需修改业务代码。

技术实现

CTRLRun 架构上分为三个层次：

决策层（Decision Layer）：AI 智能体在本地做出工具调用决策后，并不直接向外部服务发起 HTTP 请求，而是将请求发送至 CTRLRun 的规则引擎。

核验层（Validation Layer）：规则引擎根据预定义的规则文件（YAML）对请求进行核验。核验维度包括：参数值是否在允许范围、是否为重复操作、上次执行结果是否已知等。核验结果分为三种：ALLOW（直接放行）、WAIT（等待人工审批）、BLOCK（直接拒绝）。

执行层（Execution Layer）：经核验通过的操作才会真正调用外部工具。执行结果由 CTRLRun 统一路由回智能体，并将操作记录持久化至本地或数据库。

整个系统以「操作效果」为核心抽象，而非传统 ACL 的主体-客体-动作模型。效果（effect）是一个业务语义的不可分割单元，例如「退款 txn_123」是一个效果，即使因网络原因重试了三次，CTRLRun 也只允许其最终执行一次。

快速上手

第一步：安装 CTRLRun

pip install ctrlrun && ctrlrun demo

第二步：编写规则文件（policy.yaml）

定义哪些操作需要审批，例如：

refunds: amount <= 1000: allow amount 10000: block

第三步：集成到智能体代码

import ctrlrun

client = ctrlrun.Client(policy="policy.yaml") result = client.call("refund", amount=500, txn_id="txn_123")

第四步：处理审批事件

result.wait() # WAIT 状态时阻塞 result.approve() # 人工审批

第五步：验证保障效果

ctrlrun demo

该命令展示五种典型的 AI 失误场景，以及 CTRLRun 如何一一拦截，帮助开发者直观理解系统能力边界。

适用人群

• 金融与支付系统开发者：需要严格控制 AI 智能体财务操作权限的后台工程师。
• 企业内部流程自动化团队：RPA 场景下需要 AI 代理执行敏感审批流程的运维人员。
• AI Agent 框架开发者：构建多智能体协作系统时需要安全隔离层的基础设施工程师。
• 合规与安全审计人员：需要对 AI 操作日志进行完整追溯的企业安全团队。

官方链接

GitHub 仓库：https://github.com/CTRLRun/ctrlrun PyPI：https://pypi.org/project/ctrlrun/ 文档：https://docs.ctrlrun.dev/