delego

delego

网站： delegohq.com · 文档： delegohq.com/docs · 规范： Delego-Dev/specification

面向 AI Agent 的意图绑定操作授权。 它位于 Agent 与持有用户密钥的任意凭据代理之间， 并回答代理无法回答的那个问题：这一具体操作是否正是人类实际要求的事情？

   agent  ──propose──▶  delego  ──if allowed──▶  credential broker  ──▶  service
   (LLM)               (policy +                (Agent Vault /         (bank,
                        approval +               OneCLI /               SaaS,
                        audit)                   Browser Use…)          API)
                           │
                           └── needs_approval ──▶  human (CLI)

📜 协议： delego 实现开放 delego wire specification 的 protocol 0.3 —— 规范化、策略 schema、意图/指纹绑定（包括 §4.2 query-fold），以及签名的审计链。授权令牌（spec §9）是可选的 profile，尚未实现。

为什么需要它

"Agent 拥有自己的作用域凭据，且绝不直接持有用户密钥"这一模式如今已是拥挤且趋同的领域 —— Infisical 的 Agent Vault、OneCLI、Browser Use、Nango 等都在做凭据代理。

更棘手的问题在上一层 —— 混淆代理（confused deputy）：Agent 持有一个有效凭据，提示词注入将其重定向，作用域覆盖该操作，于是代理欣然注入密钥，操作顺利通过。凭据并非拦截此问题的合适位置 —— 它是有效的。OAuth 令牌并不携带对原始指令的任何承诺。

对操作（而不仅是凭据）进行授权是一个活跃领域 —— 参见确定性策略引擎（OPA/Cedar、Permit）、人机协同审批（HumanLayer）、MCP 网关/防火墙，以及"操作前授权"这一研究路线。delego 是其中一个小巧的、确定性、本地、Apache-2.0 参考实现：决策路径中无大模型、不托管凭据、审批绑定到精确的操作指纹，并带有签名的哈希链审计追踪 —— 依托现有代理层，而非与之竞争。

它是什么 / 不是什么

• 是决策与审计层。确定性策略、敏感操作的人工审批、签名的仅追加审计账本。
• 不是凭据保险库或代理。它通过一个轻量的 BrokerAdapter 接口将执行委托给代理 —— 你依托现有层，而非重建它。
• 授权是纯 Python，循环中无大模型。 模型可在上游提供建议；而把关凭据的决策在随机循环之外做出，因此注入无法靠说辞蒙混过关。

关键特性

1. 意图绑定 —— 每个操作都携带原始人类指令的哈希，记录在审计账本中，并在解析时重新校验，因此审批无法被重新指向另一条声称的指令。
2. 绑定操作、单次使用的审批 —— 人类的"同意"绑定到一个精确的操作指纹。为操作 A 获得审批的 Agent 无法复用它来执行操作 B（混淆代理防护），也无法重放同一个审批来执行操作 A 两次 —— 一个审批恰好释放其操作一次。
3. 防篡改审计 —— 收据构成 Ed25519 签名的哈希链。编辑、重排、删除收据，或丢弃某个字段，都会破坏验证，验证会报告故障而非信任账本。 *注意事项（务必精确）：*哈希链无法捕获最近收据的截断（尾部截断的前缀可干净通过验证），而本地签名密钥无法抵御主机被攻陷。对于回滚检测，请将链头外部锚定并传给 verify(expected_head=…)；对于密钥安全，请使用 HSM/KMS。参见 SECURITY.md。

快速开始

pip install delego          # the `delego` library + CLI
# pip install "delego[mcp]" # add the `delego-mcp` server (MCP is an optional extra)
delego init               # creates ~/.delego with signing keys and an example policy
delego policy             # inspect the active policy

从克隆开始端到端跑通整个闭环——一次被允许的读取、一次被禁止的拒绝、一次超限额拒绝、一次审批流程、confused-deputy 防护拒绝被替换的操作，以及审计链防篡改检测（无需 Agent 或实时服务）：

git clone https://github.com/Delego-Dev/delego && cd delego
pip install -e ".[dev]"
python examples/demo.py
pytest

人类一侧（命令行）

delego policy            # show the active policy
delego pending           # list actions awaiting approval
delego approve apr_xxxx  # release a parked action (or: delego deny apr_xxxx)
delego log -n 20         # read recent receipts
delego verify            # check the audit chain (hashes, linkage, signatures)

Agent 一侧（MCP）——接入 Claude Code

delego 通过 stdio 提供一个 MCP 服务（delego_mcp）——用 mcp extra 安装它：pip install "delego[mcp]"。在你的 MCP 配置中注册它（对于 Claude Code，是项目根目录下的 .mcp.json），这样 Agent 就能提议操作。设置 DELEGO_HOME，让策略、签名密钥和账本以项目为范围保存在 .claude/.delego 下：

{
  "mcpServers": {
    "delego": {
      "command": "delego-mcp",
      "env": { "DELEGO_HOME": "/abs/path/to/project/.claude/.delego" }
    }
  }
}

初始化该 home，并从同一个 home 进行审批（命令行和 MCP 服务必须共享同一个 home）：

delego --home .claude/.delego init       # keys, example policy, and a .gitignore
delego --home .claude/.delego pending    # ...then: delego --home .claude/.delego approve apr_xxxx

如果未设置 DELEGO_HOME，当从项目根目录运行时，命令行也会自动使用 ./.claude/.delego，否则回退到 ~/.delego。（在 MCP env 中使用绝对路径，因为服务的启动目录无法保证。）

暴露的工具：

工具	作用
delego_propose_action	提交一个操作；返回 allow / deny / needs_approval
delego_resolve_action	完成一个已批准的操作（指纹必须匹配）
delego_pending	列出等待人工审批的操作（只读）
delego_audit_tail	读取最近的收据
delego_show_policy	显示当前生效的策略

批准和拒绝被有意不通过 MCP 暴露——提议操作的 Agent 绝不能批准它；由人类在带外决定。

典型流程：Agent 调用 delego_propose_action。如果返回 needs_approval 并带有 approval_id，由人类运行 delego approve <id>，然后 Agent 用完全相同的操作调用 delego_resolve_action 来完成它。

策略格式

一条规则基于 method / host / path（glob）/ path_contains 进行匹配，决定 allow 或 needs_approval，并可附加约束。顺序为 禁止（硬拒绝）→ 规则（首个匹配生效）→ default。匹配到的规则若约束不满足则变为拒绝（fail-closed）。参见 policy.example.yaml。

rules:
  - name: place-order
    decision: needs_approval
    match: { method: POST, host: api.example.com, path: /orders }
    constraints:
      amount:     { field: amount, max: 5000, currency: USD }
      allow_list: { field: destination, in: [internal] }

支持的约束：amount（上限 + 货币）、allow_list（字段属于集合）、rate_limit（每分钟/小时/天的上限，从账本计数）。

基于 delego 构建

有三种使用方式，按上手难度从低到高排列：

• 作为 MCP 服务——delego init，将 delego-mcp 服务添加到你的 MCP 配置，你的 Agent 就会提议操作而非直接执行。无需写代码。
• 作为库——pip install delego，编写策略 + 一个 BrokerAdapter，并在你的工具调用路径中调用 fw.propose(...)。
• 作为服务后端——将 Firewall 包装成 HTTP API，让多个 Agent 共享一个决策点和一个审计链。

唯一的扩展点是 broker——你的凭据所在之处，也是被授权的操作实际运行之处。delego 从不持有密钥：

• NullBroker（默认）——模拟执行；用于演示和测试。
• HTTPProxyBroker(gateway_url)——将被授权的操作转发到外部凭据网关（OneCLI / vault / proxy），由其向上游注入密钥。
• 你自己的——在 delego/brokers.py 中针对 BrokerAdapter 协议实现 execute(action) -> dict。

▶ Delego-Dev/sample-app——一个基于已发布包构建的 FastAPI 服务，包含完整的 propose → approve → resolve 闭环以及可直接复制粘贴的 curl 演练。构建你自己的项目的最佳起点。

参见 ROADMAP.md 了解 delego 的发展方向以及可以在哪里提供帮助。

状态

• 已实现（协议 0.3）： 策略引擎、意图哈希、动作指纹（URL 查询参数已并入指纹）（规范 §4.2 —— /orders?to=me 和 /orders?to=attacker 是不同的动作）、混淆代理防护、绑定意图且一次性使用的人工审批、带签名和哈希链的审计账本（支持验证及外部头部锚点检查 delego verify --expected-head），以及 §9 授权令牌（可选配置）—— 一个短期有效、由 EdDSA 签名的 JWS，由独立 broker 在注入凭证前进行验证（build_firewall(..., mint_tokens=True)；verify_token / require_fingerprint）。
• 单写入者守护进程（delego daemon）：一个长期运行的进程持有账本，因此所有客户端都通过它路由，rate_limit 在所有客户端之间都是精确的 —— 而不仅仅是单一主机上的文件锁。CLI 的 approve/deny/pending 会自动路由到正在运行的守护进程。可选：没有守护进程时，一切仍像以前一样基于文件运行。
• Broker： 默认的 NullBroker 不持有任何凭证，也不发起真实请求 —— 它记录将会发送的内容（用于演示和测试）。HTTPProxyBroker 将已授权的动作 —— 及其授权令牌 —— 转发到外部凭证网关；或者按照 delego/brokers.py 中的 BrokerAdapter 协议编写你自己的 broker。
• 尚未完成： MCP Agent 界面自动路由到守护进程（它仍然直接与防火墙通信 —— 接线是下一步）、TCP/跨主机守护进程传输（目前是本地 Unix socket），以及非 MCP 的 HTTP 界面。
• 已知限制： 在没有守护进程的情况下，对基于文件的账本和审批存储的并发写入通过操作系统文件锁进行串行化（防损坏），并且 rate_limit 仅在共享同一主机上同一 home 目录的进程之间是精确的。运行 delego daemon 以实现跨所有客户端的精确速率限制（单一写入者）。守护进程一次串行化一个进行中的动作（预留后执行的吞吐量优化，以及面向其他主机的 TCP 传输，是未来的工作）。路径通配是粗粒度的（** 和 * 会折叠）。

许可证

基于 Apache License 2.0 许可。