Metadata-Version: 2.4
Name: a2eo
Version: 0.4.4a0
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

**面向企业真实业务操作的 Agent 安全执行层**  
**China-first · Global-compatible · Experimental Public Alpha**

[简体中文](README.md) | [English](README.en.md) · [文档入口](HANDBOOK.md) · [路线图](ROADMAP.md) · [安全边界](SECURITY.md)

> **v0.4.4-alpha / `0.4.4a0`**：中国开发者优先版本。AIP 成为国内首选 Binding，MCP / A2A 继续保持兼容；新增 ACPs v2.1.0 Trust Context 映射与 ERPNext 真实 Connector。A2EO 不替代 AIP、MCP、A2A，也不重新实现它们的身份系统。

## 30 秒理解 A2EO

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

最危险的情况不是“API 报错”，而是：

```text
Agent：创建采购订单
        ↓
ERPNext：订单实际上已经创建成功
        ↓
网络：响应丢失 / timeout
        ↓
Agent：不知道成功还是失败
        ↓
直接 retry？ → 可能生成第二张采购单
```

A2EO 把这类真实副作用显式建模为稳定 `Effect`：

```text
stable effect_key
      ↓
RESERVED          ← 此时含义是“外部结果未知”，不是“没有发生”
      ↓
INVOKE
      ↓
response lost
      ↓
RECONCILE         ← 按同一个 effect_key 查询 ERP 外部真相
      ↓
FOUND
      ↓
CONFIRMED         ← 不盲目重试，不制造第二张单
```

**一句话定位：AIP / MCP / A2A 让 Agent 能连接、发现、认证、协作和调用；A2EO 负责在一次操作真正改变 ERP / MES / WMS / TMS 后，仍然能够可靠确认、恢复、补偿和审计。**

## v0.4.4 为什么把 AIP 放到第一优先级

A2EO 现在采用 **China-first, Global-compatible** 的 Binding 策略：

```text
                        Agent Ecosystem
                             │
             ┌───────────────┼───────────────┐
             │               │               │
            AIP             A2A             MCP
      国内首选互联路径     Agent 协作       Tool / Resource
             │               │               │
             └───────────────┼───────────────┘
                             ▼
                       A2EO Binding Layer
                             ▼
                       A2EO Execution Core
          Effect / Reservation / Confirmation / Reconcile
               Delegation / Compensation / Audit Evidence
                             ▼
                    Connector SPI / SDK
                             ▼
                    ERP / MES / WMS / TMS
```

### AIP 深度绑定，但不越界

v0.4.4 新增 `bindings.aip.AIPTrustContext`，消费上游 AIP 已验证的可信上下文：

- `authenticated_aic`：经 AIP 身份/传输层验证后的 AIC；
- `senderId`：必须与已验证 AIC 完全一致，防止消息自报身份冒充；
- CAI URI：若提供，必须绑定到同一 AIC；
- ACS：仅接受 Registry / Discovery 来源作为可信身份元数据，并检查 `active`、AIC、协议版本；
- Direct RPC / Group / Hybrid / MQ Inbox：可携带一致的 A2EO Principal / Audit Context；
- **ACS skills / capabilities 只作为描述性证据，不自动变成企业操作权限。**

随后 A2EO 再用自己的服务端 Delegation / Policy 判断：

```text
AIP：你是谁、可信身份是什么
        ↓
A2EO：这一次 purchase_order.create 是否被授权
        ↓
A2EO：为这一次业务意图生成稳定 Effect Identity
        ↓
ERPNext：执行真实副作用
        ↓
A2EO：确认 / reconcile / 人工异常闭环
```

> 版本细节：ACPs 社区发行版是 **v2.1.0**；当前 A2EO 精确交互线协议映射仍锁定官方 `ACPs-spec-AIP-v02.01`。这两个版本号不是一回事，v0.4.4 在代码中明确分离 `acps_release="2.1.0"` 与 `protocol_version="02.01"`。

详见：[AIP v2.1 Trust Context 集成](docs/zh-CN/aip-integration.md)。

## 第一个真实企业 Connector：ERPNext

v0.4.4 新增 `ERPNextPurchaseOrderConnector`，不是 Fake ERP：

- 使用 Frappe / ERPNext REST API 创建真实 `Purchase Order`；
- 使用 Token Auth；
- 把稳定 A2EO `effect_key` 写入 ERPNext 自定义字段（默认 `custom_a2eo_effect_key`）；
- timeout / 5xx / response lost 不会被错误标成“失败且未发生”；
- 可按 effect key 查询外部 Purchase Order 并 reconcile；
- 若查询到多个相同 effect key，判定 `UNKNOWN`，不猜；
- 默认 **不** 宣称自动重试安全；只有操作者明确确认 ERPNext 端该字段具有唯一约束后，才可设置 `effect_key_unique=True`；
- v0.4.4 不伪造“通用 Purchase Order compensation”，因为 ERP 取消/撤销语义取决于真实业务工作流。

真实故障演示见：[ERPNext Demo](docs/zh-CN/erpnext-demo.md)。

## 5 分钟本地 Quickstart

### 1. 从源码安装

```bash
git clone https://github.com/Kafalah/a2eo.git
cd a2eo
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python -m pip install -U pip
python -m pip install -e .
```

### 2. 看 CLI 是否可用

```bash
a2eo happy
```

### 3. 跑三个独立 Gate

```bash
python scripts/run_core_gate.py
python scripts/run_enterprise_interop_gate.py
bash scripts/run_integration_gate.sh
```

v0.4.4 的发布基线目标：

```text
85 Core
72 Enterprise Interop
34 Integration
---------------------
191 tests
```

> 这些测试是 A2EO 自己的回归 / conformance evidence，不代表 AIP 官方认证、ERPNext 官方认证、生产环境认证或任何国家标准符合性认证。

### 4. 最小 AIP Trust Context

```python
from bindings.aip import AIPTrustContext

AIC = "1.2.156.3088.1.1.34C2.478BDF.3GF546.0JU4"

ctx = AIPTrustContext(
    authenticated_aic=AIC,          # 必须来自上游已验证身份边界
    message_sender_id=AIC,          # AIP wire senderId
    identity_verified=True,
    authentication_method="CAI/mTLS",
    cai_uri=f"acps://{AIC}",
    transport_security="TLS1.3+mTLS",
)

print(ctx.principal())
print(ctx.audit_metadata())
```

A2EO **不会**把 `identity_verified=True` 当成自己完成了证书验证；在真实部署中，这个字段必须由你的 AIP Gateway / Identity Adapter 在完成 CAI/mTLS/AIA 验证后生成。

## 设计底线

A2EO v0.4.4 继续坚持这些不变量：

1. **Agent capability ≠ enterprise authorization**：能描述“会创建采购单”不等于有权创建这一张采购单。
2. **`RESERVED` ≠ 未发生**：它表示外部结果尚未被证明。
3. **Timeout ≠ rollback**：网络失败不能证明 ERP 没有提交。
4. **No hidden retry**：Connector 不偷偷重试真实副作用。
5. **External truth wins**：恢复必须以 ERP/WMS/MES/TMS 可验证外部事实为准。
6. **Weak NOT_FOUND cannot authorize replay**：普通查询不到不等于“确定从未发生”。
7. **Compensation is also an Effect**：撤销本身同样可能 timeout，同样需要稳定身份和恢复。
8. **Human exceptional control is durable**：无法自动证明时，必须进入可审计人工异常闭环，而不是猜。

## 项目不是这些东西

A2EO 当前**不是**：

- 中国版 MCP；
- AIP 的竞争协议；
- A2A 的替代品；
- 通用工作流引擎；
- ERP 厂商 SDK 大全；
- 生产级 IAM / CA / Registry 实现；
- SAP、用友、金蝶、ERPNext 的官方认证产品；
- 国家标准认证或符合性认证。

更准确的关系是：

> **Connect with AIP / MCP / A2A. Execute enterprise effects safely with A2EO.**

## 文档路线

- 中国开发者第一次使用：[`docs/zh-CN/quickstart.md`](docs/zh-CN/quickstart.md)
- 核心概念：[`docs/zh-CN/concepts.md`](docs/zh-CN/concepts.md)
- AIP v2.1 Trust Context：[`docs/zh-CN/aip-integration.md`](docs/zh-CN/aip-integration.md)
- ERPNext 真实 Demo：[`docs/zh-CN/erpnext-demo.md`](docs/zh-CN/erpnext-demo.md)
- 英文入口：[`README.en.md`](README.en.md)
- 完整手册索引：[`HANDBOOK.md`](HANDBOOK.md)
- 架构定位：[`POSITIONING.md`](POSITIONING.md)
- Roadmap：[`ROADMAP.md`](ROADMAP.md)

## 当前状态与边界

**v0.4.4-alpha 是 Experimental Public Alpha。**

它的目标是提供：

- 可审查的企业副作用执行语义；
- AIP / MCP / A2A 共生 Binding；
- 中国开发者优先的文档和参考路径；
- 可复现的安全失败案例；
- 第一个真实 ERP Connector；
- 公开的 conformance / regression evidence。

它还没有资格承诺：生产级高可用、企业 SLA、真实厂商兼容认证、完整 AIP SDK/Registry/CAI 实现或工业安全系统直接控制。

## License

Apache License 2.0 · Copyright 2026 Kafalah

欢迎用具体的企业现实问题来挑战 A2EO：**“外部系统实际已提交，但响应丢失时，你们现在怎么处理 Agent retry？”** 这类 Issue 对项目比单纯增加抽象模块更有价值。
