a2eo

A2EO — Agent-to-Enterprise Operations

让 AI Agent 更安全地执行真实企业操作
中文优先 · China-first · Global-compatible · Experimental Public Alpha

中文文档中心 | English | 快速开始 | AIP 集成 | 安全边界

v0.4.5-alpha / 0.4.5a0 — Chinese Documentation & AIP Trust Release
这一版不追求更多协议和更多 ERP，而是解决两个问题：中国开发者能不能快速理解并跑通 A2EO；AIP 已验证的可信身份能不能安全贯穿到一次真实企业操作的授权、Effect 与证据。

30 秒理解：A2EO 到底解决什么？

AI Agent 能调用 ERP API，不代表它能安全地改变企业业务状态。

Agent：创建采购订单
        ↓
ERP：订单实际上已经创建成功
        ↓
网络：响应丢失 / timeout
        ↓
Agent：只知道“没收到成功响应”
        ↓
直接重试？
        ↓
可能创建第二张采购单

A2EO 不把 timeout 当成“没发生”，而是给真实副作用建立稳定 Effect：

稳定 effect_key
      ↓
RESERVED       ← 表示“外部结果尚未证明”，不是“没有发生”
      ↓
INVOKE
      ↓
响应丢失
      ↓
RECONCILE      ← 查询 ERP 外部事实
      ↓
FOUND
      ↓
确认原操作，不盲目创建第二张单

一句话：AIP / MCP / A2A 负责让 Agent 连接、发现、认证、协作和调用；A2EO 负责这些能力真正改变 ERP / MES / WMS / TMS 后，操作仍然可授权、可识别、可恢复、可审计。

---

第一次使用：只跑这 3 条命令

要求 Python 3.11+。

python -m pip install -e .
a2eo doctor
a2eo cn-quickstart

a2eo doctor 会用中文检查本地环境。

a2eo cn-quickstart 不需要 Docker、不需要 ERPNext、不需要真正 AIP CA/Registry，会在本地跑完：

模拟上游已验证 AIP 身份
        ↓
A2EO 服务端委托
        ↓
本次企业操作授权
        ↓
稳定 Effect
        ↓
本地教学 Connector
        ↓
PO-000001
        ↓
Trust / Delegation / Authorization Evidence
        ↓
防篡改事件链验证

成功时你会看到：

结果：✅ 已跑通
...
本次授权：True (DELEGATION_ALLOWED)
Effect 状态：COMPLETED
外部对象：PO-000001
审计链校验：True

然后按中文文档中心继续：docs/zh-CN/README.md。

---

v0.4.5 的核心技术升级：AIP Trust Context v2

v0.4.4 已经完成 AIP AIC / senderId / CAI / ACS provenance / channel 的可信投影。v0.4.5 继续向企业真实授权推进：

AIP 已验证身份
 AIC / senderId / CAI / ACS / channel
                 ↓
          AIPTrustContext
                 ↓
       A2EO Principal
                 ↓
  server-side delegation_ref
                 ↓
issuer / tenant / action / resource / amount / currency
                 ↓
       Authorization Decision
                 ↓
     Effect execution_context
                 ↓
      Audit / Reconciliation

新增 AIPEnterpriseAuthorityContext 和 bind_aip_enterprise_authority()，用于把可信身份与企业权限明确分开。

最重要的规则：

CAI 边界说明： ACPs v02.01 将 CAI 定义为智能体身份证书（Certificate of Agent Identity）。A2EO 的可选 a2eo-cai://{AIC} 只是项目自己的实验性引用映射，不是 ACPs 官方 URI scheme，也不构成 AIP/ACPs 认证声明。

Capability ≠ Authority

错误：

ACS.skills = purchase_order.create
→ 自动允许采购

A2EO 的做法：

ACS skill = 能力描述
        ↓
AIP 上游身份验证
        ↓
A2EO 从服务端可信存储解析 delegation_ref
        ↓
检查 tenant / action / resource / amount / currency / expiry
        ↓
本次 Authorization Decision

Agent 声称“会做什么”，永远不等于企业已经授权它做这一次操作。

Trust Context 现在真正进入 Effect

v0.4.5 的 Effect 可以持久化经过清洗的 execution_context，包括：

• 哪个 AIP Agent 发起；
• 通过哪个 AIP channel；
• 代表谁/由谁委托；
• 哪个 delegation_ref；
• 本次具体 action / resource / 金额 / 币种；
• 为什么允许/拒绝；
• Evidence Hash。

同时增加一条 fail-closed 规则：

同一个 effect_key 不能在不同企业授权上下文下被重新利用。

业务 payload 一样，不代表“代表谁执行、由谁授权”也一样。

---

AIP / MCP / A2A 的位置

                       Agent Ecosystem
                            │
            ┌───────────────┼───────────────┐
            │               │               │
           AIP             MCP             A2A
      国内优先互联路径    Tool/Resource    Agent 协作
            │               │               │
            └───────────────┼───────────────┘
                            ▼
                      A2EO Binding
                            ▼
                  A2EO Execution Core
      Identity Projection / Delegation / Authorization
        Effect / Reconciliation / Compensation / Evidence
                            ▼
                      Connector SPI
                            ▼
                   ERP / MES / WMS / TMS

v0.4.5 的策略很明确：

• AIP：重点推进 Trust Context → Enterprise Authority。
• MCP：兼容维护，不重新造 MCP 安全体系。
• A2A：兼容维护，不重新造 A2A 安全体系。

A2EO 不做自己的 AIP CA、Agent Registry 或通用 Authorization Server。

AIP 版本说明

当前映射明确区分：

• ACPs 社区发行映射：2.1.0
• AIP interaction wire：ACPs-spec-AIP-v02.01 已验证子集

它们不是同一个版本号。详见 docs/zh-CN/06-AIP集成.md。

---

真实 ERP 参考：ERPNext

项目保留 ERPNextPurchaseOrderConnector 和 response-loss-after-commit Demo：

• REST API + Token Auth；
• 稳定 A2EO effect key 写入 ERPNext 自定义字段；
• timeout/5xx/响应丢失不会被错误标记成“确定没发生”；
• 可按 effect key 查询 Purchase Order；
• 多条匹配 → UNKNOWN，不猜；
• 默认不宣称自动 retry 安全；
• 没有真实唯一约束，就不会为了 Demo 好看偷偷重试；
• 不伪造通用 ERP compensation。

详见 docs/zh-CN/11-ERPNext真实Demo.md。

---

中文文档已经成为主路径

从 v0.4.5 开始，新用户不需要先读英文或中英混排手册：

1. 00 项目总览
2. 01 快速开始
3. 02 核心概念
4. 03 Effect 生命周期
5. 04 安全、身份与委托
6. 05 Connector 开发
7. 06 AIP 集成
8. 07 MCP 集成
9. 08 A2A 集成
10. 09 对账、补偿与人工处置
11. 10 一致性与测试
12. 11 ERPNext 真实 Demo
13. 12 部署与 PoC
14. 13 贡献指南

历史 *-zh-en.md 文档暂时保留以兼容旧链接，但不再作为中国开发者主入口。

---

一键验证

跨平台推荐：

python scripts/run_release_gate.py

它会运行 Core、Enterprise Interop、Integration、Release Consistency 和 Publication Audit。

也可以单独运行：

python scripts/run_core_gate.py
python scripts/run_enterprise_interop_gate.py
python scripts/run_integration_gate.py

这些是 A2EO 自己的回归与 conformance evidence，不代表 AIP 官方认证、ERPNext 厂商认证、GB/Z 185 认证或生产认证。

---

8 条设计底线

1. Capability ≠ Authority：能力描述不等于企业授权。
2. RESERVED ≠ 未发生：表示外部事实尚未证明。
3. Timeout ≠ rollback：网络失败不能证明 ERP 没提交。
4. No hidden retry：Connector 不偷偷重试真实 mutation。
5. External truth wins：恢复以真实企业系统事实为准。
6. Weak NOT_FOUND cannot authorize replay：弱查询不到不能证明从未发生。
7. Compensation is also an Effect：撤销同样需要稳定身份和恢复。
8. Human exceptional control is durable：无法自动证明时进入可审计人工闭环，不让 Agent 猜。

---

A2EO 现在不是什么

当前版本不是：

• 中国版 MCP；
• AIP 竞争协议；
• A2A 替代品；
• 通用工作流引擎；
• 生产级 IAM / CA / Registry；
• SAP、用友、金蝶、ERPNext 官方认证产品；
• 国家标准认证产品；
• 可直接无人值守控制支付、PLC、机器人或高风险工业设备的生产系统。

A2EO v0.4.5-alpha 仍是 Experimental Public Alpha。

License

Apache License 2.0 · Copyright 2026 Kafalah

如果你做企业 Agent 集成，最有价值的反馈不是“支持再多一个协议”，而是告诉项目一个真实问题：外部系统已经 commit、但响应丢失时，你们今天是怎么处理 retry 的？