emiliaprotocol/emilia-protocol · 上手攻略

仓库：emiliaprotocol/emilia-protocol
链接：https://github.com/emiliaprotocol/emilia-protocol
分类：AI Agent 安全与授权基础设施
作者：Tom
更新：2026-08-26

是什么

EMILIA Protocol 是一个面向 AI Agent 行动的后果防火墙（Consequence Firewall）。它的核心思路是：给 AI Agent 的每一次高风险操作都加一道"收费站"——在真正的写操作（转账、删库、写代码、部署服务）执行前，验证 Agent 是否持有本次操作的精确授权，并留下可离线验证的凭证（Receipt）。

一句话说清楚：Agent 可以继续跑，但它的权限在该截停的地方必须截停。

该项目并非一条"去中心化全球网络"，而是在客户自己控制的边界上部署的本地收费站，可与 GitHub Merge Gate、支付路径、部署流水线等具体场景组合。

解决什么问题

当前 AI Agent 的授权模型有两个根本缺陷：

身份 ≠ 权限：Agent 拿到了凭证（API Key / OAuth Token），但这套凭证可能覆盖远超本次任务所需的权限范围。
没有退出凭证：操作完成后没有可验证的记录，证明"这笔钱确实经过了人工授权才转出"。

EMILIA 为此构建了四层结构：

层次	职责
Authority Map	扫描本地已声明的工具表面，生成权限清单
EMILIA Gate	将操作 mandate 转化为可执行的前置拦截控制
EMILIA Protocol	开放协议底层：Trust Receipt、Trust Profile、Trust Decision 的互操作规范
EMILIA Approver	捕获设备绑定的人工审批（WebAuthn/Passkey）

快速安装

无需后端，纯本地即可跑通核心链路：

# 扫描本地工具表面，生成权限地图（dry run）
npx @emilia-protocol/scan protect ./tools.json

# 离线签发一张演示收据（无需 API key）
npx @emilia-protocol/issue demo

# 启动 MCP Server（接入 Claude / Cursor / Cline）
npx -y @emilia-protocol/mcp-server

# 验证自己浏览器的收据（完全离线，零上传）
# 访问 https://www.emiliaprotocol.ai/verify

⚠️ 版本注记：npm 包 @emilia-protocol/verify 最新版本请以 npmjs.com/package/@emilia-protocol/verify 页面为准，README 中标注 badge 对应版本可能滞后。

核心用法

1. 扫描并保护工具表面

# 生成权限地图（不实际保护，只扫描）
npx @emilia-protocol/scan protect ./tools.json

# 应用保护（生成 Gate wrapper）
npx @emilia-protocol/scan protect ./tools.json --apply

# 验证本地方案是否正确配置
node emilia/verify-setup.mjs

tools.json 示例格式（类 MCP 工具声明）：

[
  { "name": "release_payment", "params": ["amount", "recipient"] },
  { "name": "delete_repo",    "params": ["repo"] },
  { "name": "deploy_production", "params": ["env"] }
]

2. 本地 MCP 示例

EMILIA 提供了三个可直接运行的 MCP 演示：

# release_payment — 无收据则拒绝
node examples/mcp/payment-server.mjs

# delete_repo — 无收据则拒绝
node examples/mcp/github-admin.mjs

# deploy_production — 无收据则拒绝
node examples/mcp/prod-deploy.mjs

每个示例都会检查收到的操作是否携带有效收据；没有收据或收据被篡改，则操作被拒绝。

3. 离线验证收据

EMILIA 的一大特性是收据可在完全离线状态下验证：

npm run demo:receipt-program

这个 demo 执行一笔 CAID 绑定的委托付款，通过 Gate 的有界能力路径，然后离线验证签名执行证书。不包含任何区块链或模拟零知识声明。

4. 跑安全证据检查

⚠️ 注意：以下命令执行的是仓库自带的 conformance 测试包（AEB-1），这是自我声称的符合性证据，不等于第三方审计：

# 运行 AEB-1 Conformance 测试包
npx @emilia-protocol/verify aeb-conformance --reference

# 运行 Gate 路径参考证明（本地示例）
npm run proof:gate:reference

5. GitHub Merge Gate（生产分发示例）

EMILIA 的第一个付费场景假设是 GitHub 合并控制：

# 在受保护分支配置 Merge Gate
# 触发条件：base commit + head commit 与 mandate 匹配
# 产出： detached receipt 与 exact commits 绑定

⚠️ 该功能是产品分发实验，不代表已在生产环境大规模采用。

典型适用场景

财务操作拦截：支付释放、银行账户变更，需要精确到金额和收款人的授权验证
代码部署控制：生产环境部署必须经过人机双重授权
权限最小化：用 EMILIA Gate 替代"拥有所有权限的 API Token"
合规审计：需要为 AI 操作提供可验证凭证的监管场景（如 SOC 2、ISO 42001）

坑与注意

这不是认证服务：EMILIA 验证的是"本次操作是否在 mandate 范围内"，不是"这个人是谁"。身份认证仍需配合原有 IdP。
离线验证 ≠ 去中心化：收据可离线验证，但 Gate 本身是本地部署的，不是链上合约。
PostgreSQL 支持是参考实现：README 提到参考实现覆盖本地内存和 PostgreSQL 控制域；生产环境需要评估共享状态一致性（leased-edge propagation 仍为已知实现缺口）。
IETF Draft 状态：README 链接了 IETF Internet-Draft，但草案本身仍在演进，不等于已批准标准。
自我声称的 conformance：AEB-1 测试是自运行的符合性测试，不是第三方安全审计；README 中提到的 35 条安全声明、20 个 Tamarin 引理属于仓库自身的安全案例，外部验证有限。
Emergency Freeze 范围有限：冻结操作阻止新预约，但不能撤销已进入的效果，也不能跨断开连接的leased domain 立即生效。

与同类对比

项目	核心思路	验证方式	离线验证	开源协议
EMILIA Protocol	精确 mandate + 收据	WebAuthn / Passkey + 本地签名	✅	Apache 2.0
OPA / Gatekeeper	策略即代码	Rego 策略语言	❌	Apache 2.0
Cabinets / SPIFFE	工作负载身份	X.509 SVID	❌	Apache 2.0
zkTLS / TLS attestations	传输层证明	零知识证明	✅	各家不同
Anthropic's CAI	AI 操作审计	外部日志	❌	闭源

EMILIA 的独特价值在于Exact Action Binding（精确到字段级别的操作绑定）+ 可移植收据，而非笼统的"API Key 授权"或"角色策略"。

一句话推荐结论

如果你的 AI Agent 已经在操作真实金钱、删除真实资源或修改真实权限，EMILIA 是目前唯一开源且可离线验证的精确授权防火墙——在 Agent 继续跑之前，先把它的权限关进笼子里。

最小可跑命令

# 环境：Node.js ≥ 18，无其他依赖
# 1. 安装 MCP server
npx -y @emilia-protocol/mcp-server

# 2. 离线签发演示收据
npx @emilia-protocol/issue demo

# 3. 运行支付拦截示例（无收据 → 拒绝）
node examples/mcp/payment-server.mjs

# 4. 运行 GitHub 管理拦截示例
node examples/mcp/github-admin.mjs

# 5. 运行生产部署拦截示例
node examples/mcp/prod-deploy.mjs

# 验证收据（浏览器打开）
# https://www.emiliaprotocol.ai/verify

硬件/CUDA/模型版本要求：无；纯本地 Node.js 环境即可运行所有核心示例。

来源与引用

主 README：https://github.com/emiliaprotocol/emilia-protocol
IETF Draft：draft-schrock-ep-authorization-receipts
EMILIA 官网（收据验证入口）：https://www.emiliaprotocol.ai/verify
安全案例证据地图：https://www.emiliaprotocol.ai/proof
CHANGELOG（版本记录）：https://github.com/emiliaprotocol/emilia-protocol/blob/main/CHANGELOG.md
OSS Insight 数据（2026-08 快照）：Stars 593 · Forks 7 · 主语言 TypeScript

⚠️ 不确定处：EMILIA Gate 的 PostgreSQL 控制域在分布式场景下的leased-edge传播尚未完全实现（README 自述），生产级部署请关注 CHANGELOG 中的 Activation pass 版本记录。