Metadata-Version: 2.4
Name: a2eo
Version: 0.4.5a0
Summary: A2EO: trusted execution and interoperability between agents and enterprise operations
Author: Kafalah
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Kafalah/a2eo
Project-URL: Repository, https://github.com/Kafalah/a2eo
Project-URL: Documentation, https://github.com/Kafalah/a2eo/tree/main/docs
Project-URL: Issues, https://github.com/Kafalah/a2eo/issues
Project-URL: Changelog, https://github.com/Kafalah/a2eo/blob/main/CHANGELOG.md
Keywords: agent,interoperability,logistics,industrial,connector,aip,a2a,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: COPYRIGHT
Requires-Dist: jsonschema>=4.0
Requires-Dist: fastapi<1,>=0.128
Requires-Dist: uvicorn<1,>=0.48
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.13
Dynamic: license-file

# A2EO — Agent-to-Enterprise Operations

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

[中文文档中心](docs/zh-CN/README.md) | [English](README.en.md) | [快速开始](docs/zh-CN/01-快速开始.md) | [AIP 集成](docs/zh-CN/06-AIP集成.md) | [安全边界](SECURITY.md)

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

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

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

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

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

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

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

---

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

要求 Python 3.11+。

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

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

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

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

成功时你会看到：

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

然后按中文文档中心继续：[`docs/zh-CN/README.md`](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 继续向企业真实授权推进：

```text
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

错误：

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

A2EO 的做法：

```text
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 的位置

```text
                       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`](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`](docs/zh-CN/11-ERPNext真实Demo.md)。

---

## 中文文档已经成为主路径

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

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

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

---

## 一键验证

跨平台推荐：

```bash
python scripts/run_release_gate.py
```

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

也可以单独运行：

```bash
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 的？**
