Agent-Safe Pipeline

这是什么？适合谁？

Agent-Safe Pipeline 是 Decionis 开源的 AI Agent 动作安全参考架构，核心理念一句话：“Let agents propose. Let policy decide.”——Agent 可以推理、规划、提议动作，但绝不能自己决定动作是否被授权。所有动作经过一条不可变意图（immutable intent）→ 独立授权门（ALLOW / ESCALATE / BLOCK）→ SafeExecutor 的流水线执行，人审与策略闸门在 2026 年 Agent 治理中已是刚需。

适合人群：构建生产级 Agent 系统的架构师和团队、需要为 Agent 动作加授权边界的平台工程师、研究 Agent 安全合规的技术管理者。 使用前提：Node.js 22.14+、pnpm 9、TypeScript 基础、对 Agent 工具调用机制有基本了解。

快速上手（3 步）

第一步：克隆并安装

git clone https://github.com/decionis/agent-safe-pipeline.git
cd agent-safe-pipeline
pnpm install --frozen-lockfile

第二步：跑五分钟 Demo

pnpm --filter @decionis/agent-safe-example-basic demo

Demo 使用显式声明的”非生产 fixture 授权器”，完整走一遍 Agent 提议 → 不可变意图捕获 → 授权决策 → 受控执行的链路。

第三步：读懂核心 API

const captured = intentCapture.capture(agentProposal, trustedContext);
const decision = await gate.evaluate(captured);
const result = await executor.run(captured, decision);

执行器只接受”已捕获的意图 + 决策”，不接受 Agent 传来的任意回调。密封的 ActionRegistry 把动作名映射到可信 handler，并在消费一次性 grant 前校验参数。

初级用法

• 先跑最小 BLOCK 流：examples/basic-agent 演示了提议被直接阻断的最小场景，理解”拒绝”也是一等结果。
• 看金额分级示例：examples/shopify-refund-agent 展示按金额决定 ALLOW / ESCALATE / BLOCK——小额放行、中额升级人审、大额阻断。
• 看环境管控示例：examples/github-deploy-agent 展示按部署环境和 force-push 标志做策略控制。

高级玩法

1. Presence 人审协调：决策为 ESCALATE 时，通过 Presence 机制发起已验证的人工审批，批准后进入 Decionis 再评估再执行——把”人审”做成可审计的协议而非群聊里喊一嗓子。
2. 接入生产凭证体系：生产集成用 DecionisGate + DecionisGrantVerifier 挂载服务端凭证，grant 一次性消费防重放。
3. 扩展示例矩阵：参照仓库的 examples 目录结构，为自己的业务动作（退款、删除、发邮件）各写一个策略示例，形成团队的策略测试集。

常见踩坑（5 条）

踩坑 1：把它当托管授权服务用

• 现象：直接拿 demo 授权器上生产
• 原因：demo 的 fixture authority 明确声明非生产用途
• 解决：生产必须实现自己的 DecionisGate / DecionisGrantVerifier 并用服务端凭证

踩坑 2：以为它能替代云侧安全

• 现象：跳过最小权限、网络隔离、事件响应建设
• 原因：README 明确声明本仓库不替代 provider 侧身份、最小权限、网络隔离与应急响应
• 解决：把 pipeline 当作纵深防御的一层，而非全部

踩坑 3：Agent 仍持有下游特权凭证

• 现象：授权门形同虚设
• 原因：Agent 自己口袋里就有生产 API key，绕过边界直接调用
• 解决：凭证只存在于可信 handler 侧，Agent 侧零特权凭证

踩坑 4：忽略信任边界前提

• 现象：安全声明与实际部署不匹配
• 原因：项目安全声明仅在”文档化的信任边界被保持”时成立
• 解决：部署前核对信任边界文档，改动架构需重新评估声明适用性

踩坑 5：Node 版本过低

• 现象：安装或运行报语法错误
• 原因：要求 Node.js 22.14+
• 解决：用 nvm 切换到 22.14 以上版本

FAQ（5 个常见问题）

Q1：Agent-Safe Pipeline 免费吗？ A：Apache-2.0 开源免费，无托管费用，成本仅在自建部署与维护。

Q2：它和 MCP 权限控制有什么区别？ A：MCP 的工具权限是”能不能调这个工具”；本项目的边界是”这次具体动作是否被授权”——意图级、参数级、不可变、可审计。

Q3：支持哪些 Agent 框架？ A：它是框架无关的库 + 参考实现，任何能产出”动作提议”的 Agent（LangChain、Claude、自研）都能接入捕获层。

Q4：和 OpenAI 的 Approval API 类机制重复吗？ A：互补。厂商审批机制是单点能力；这里是独立于 Agent 与厂商的授权边界参考架构，强调不可变意图与一次性 grant。

Q5：性能开销大吗？ A：主要是每次动作前的捕获与评估开销（本地计算为主），相对 Agent 推理本身的延迟可忽略；具体数值未实测，建议按自己的策略复杂度压测。

小技巧（5 条）

1. 先写策略再写集成：把”哪些动作 ALLOW / 哪些必须人审”列成矩阵，直接映射到 gate 配置。
2. 用 examples 当回归测试：每个示例都是可运行的策略用例，改动核心包后全量跑一遍。
3. grant 一次性消费是红线：自研 handler 时严禁缓存复用 grant。
4. 审计日志单独存：不可变意图 + 决策记录是审计金矿，落到 append-only 存储。
5. 把 ESCALATE 当产品功能设计：人审界面、通知触达、超时策略都值得投入，别只做 BLOCK。

进阶学习建议

• 精读 packages/pipeline 中 IntentCapture、DecionisGate、Presence、SafeExecutor 四个组件的职责划分
• 对照 decionis.com/docs 理解信任边界的正式定义与安全声明适用条件
• 把 shopify-refund 与 github-deploy 两个示例的策略改写成自己业务域的等价物
• 研究一次性 grant 的密封与验证机制，思考如何防重放与时序攻击

参考链接

• Agent-Safe Pipeline GitHub 仓库
• Decionis 官方文档

本文基于公开资料于 2026-08-17 整理，社区指标反映 GitHub 公开数据。独立实测未进行，功能和配置项可能随版本更新而变化，请以官方文档为准。