内容
# 代理合约协议
> **ACP** 是用于自治代理的受控执行层。
> 任何工具源都可以输入。签署、身份绑定、排序、可审计的执行结果输出。
>
> **状态：** 公共概念验证 · v0.2 草案 · 2026 年 6 月 **所有者：** Clawdlinux / NineVigil
---
## 简介
MCP 回答了**存在哪些工具**的问题。Claude 代码工具搜索和语义检索使得工具选择更加廉价。这是件好事。这也意味着原始代币减少不是一个可持续的产品理论。
真正的问题现在是执行信任。
在自治代理触及真实系统之前，您需要知道：
1. **它以谁的名义执行？** 合约将执行绑定到代理身份和凭证别名。原始凭证永远不会进入模型上下文。
2. **它被允许执行什么？** 合约声明出口、审批门、TTL、速率限制和审计级别。
3. **之后发生了什么？** 每个操作都可以追溯到合约、操作 ID、主体、结果和审计记录。
ACP 接受代理意图并返回**执行合约**。当前线型仍为 v0.1 兼容的 `ExecutionManifest`，但合约是产品基元：范围能力、排序操作、代理身份验证和在代理处处理的策略声明。
## 为什么存在
自治代理卡在演示中，因为团队无法控制其影响范围。工具发现正在解决，但生产执行治理尚未解决。
ACP 是一种小型开放合约格式和参考运行时，用于解决这一问题：
- **与 MCP 兼容。** 现有的 MCP 服务器继续工作。ACP 消耗它们的 `tools/list` 并发出受控的执行合约。
- **源无关。** MCP、Kubernetes 服务和未来的 OpenAPI/gRPC/CLI 适配器都规范为相同的合约形状。
- **边界策略。** 代理强制出口和审批。模型不允许自我监管。
- **审计建设。** 反馈和代理执行事件附加到相同的合约 ID。
## 代币效率是副作用
ACP 仍然减少工具上下文代币，因为合约只包含意图所需的权限。
基准测试数据见
[`results/2026-05-02-week3-summary.md`](results/2026-05-02-week3-summary.md)。
| 场景 | ACP / MCP 代币 | ACP / MCP 往返次数 | 减少百分比 |
|---|---:|---:|---:|
| S1 简单数据库查询 | 111 / 373 | 1 / 3 | 70.2% |
| S2 多工具工作流 | 295 / 837 | 1 / 5 | 64.7% |
| S3 复杂 DAG | 306 / 1,257 | 1 / 7 | 75.6% |
| S4 规模，50 个工具和 2 个相关工具 | 241 / 9,223 | 1 / 21 | 97.4% |
| S5 认证密集型 | 359 / 1,431 | 1 / 7 | 74.9% |
这些数字很有用，但不是核心竞争力。核心竞争力是受控的执行合约。
## 仓库布局
```text
agent-contract-protocol/
├── SPEC.md # ACP 协议规范
├── cmd/
│ ├── acp-server/ # ACP 服务器入口
│ ├── acp-bridge/ # MCP 桥接器，用于 IDE 风格的客户端
│ └── benchmark/ # 基准测试 CLI
├── internal/
│ ├── builder/ # 合约构建器和排序
│ ├── proxy/ # 认证注入和策略强制
│ ├── registry/ # 工具注册表
│ ├── resolver/ # 意图到能力解析器
│ └── sources/ # MCP 和 Kubernetes 源适配器
├── pkg/
│ ├── acp/ # 公共 Go SDK
│ └── manifest/ # 线型
├── adapters/python/ # Python 适配器，用于常见代理堆栈
├── benchmark/ # 可重复的 MCP 与 ACP 基準測試
├── docs/ # 架构、定位、验证
└── deploy/ # Docker Compose 和 Kubernetes 資產
```
## 快速入门
### 从源代码构建
```bash
git clone https://github.com/Clawdlinux/agent-contract-protocol
cd agent-contract-protocol
make build
ACP_AUTH_TOKEN=dev-token ./bin/acp-server --addr :8080
```
### 连接到 VS Code MCP
对于正常的 MCP 用户，安装桥接器并在 VS Code 中注册一个 MCP 服务器：
```bash
go install github.com/Clawdlinux/agent-contract-protocol/cmd/acp-bridge@latest
```
`~/Library/Application Support/Code/User/mcp.json`:
```json
{
"servers": {
"acp-bridge": {
"type": "stdio",
"command": "acp-bridge",
"args": ["--import-vscode"]
}
}
}
```
`acp-bridge` 导入现有的 VS Code stdio MCP 服务器，跳过其自己的条目，将下游服务器作为子进程启动，压缩 `tools/list`，在观察到调用后缩小工具表面，并将真实的 `tools/call` 请求转发到原始 MCP 服务器。VS Code HTTP MCP 条目暂时被跳过。
对于显式配置而不是自动导入：
```bash
acp-bridge --config ./examples/bridge.json
```
### 请求执行合约
```bash
curl -sS -X POST http://localhost:8080/v1/context \
-H "Authorization: Bearer dev-token" \
-H "Content-Type: application/json" \
-d '{"intent":"query customer data, render report, email the team","agent_id":"demo"}' \
| python3 -m json.tool
```
### Go 安装
```bash
go install github.com/Clawdlinux/agent-contract-protocol/cmd/acp-server@main
ACP_AUTH_TOKEN=dev-token acp-server --addr :8080
```
使用第一个 Agent Contract Protocol 标签创建后的发布标签。
## 与现有的 MCP 服务器一起使用
ACP 不会取代 MCP。它使用 MCP 作为发现供应链。
```text
代理运行时
│
│ POST /v1/context {"intent":"...", "agent_id":"..."}
▼
┌──────────────────────────────┐ ┌─────────────────────────┐
│ ACP 服务器 │ ────▶ │ 现有 MCP 服务器 │
│ 意图 → 执行合约 │ 工具 │ GitHub, Slack, DB, 等 │
└──────────────────────────────┘ /list └─────────────────────────┘
│
│ 作用域操作、策略、认证别名、排序
▼
代理通过 /v1/exec/{contract_id}/{action_id} 执行
```
MCP 导入器位于 [`internal/sources/mcp`](internal/sources/mcp)，读取标准的 MCP `tools/list` 信封，并在 ACP 的注册表中注册每个工具。
```bash
python3 scripts/fake-mcp.py 19090 &
go run ./cmd/import-demo \
-source name=files,url=http://127.0.0.1:19090,caps=filesystem
```
每个导入的工具都会获得：
- 命名空间 ID，如 `<source>.<tool>`。
- 意图解析的能力标签。
- 通过 ACP 代理路由的端点。
- 认证模式，防止原始凭证进入模型上下文。
> **诚实状态：** `acp-bridge` 是即插即用的 IDE 路径。它可以导入 VS Code MCP 配置，启动 stdio MCP 服务器，并转发真实的工具调用。
> 目前，HTTP MCP 条目被自动导入路径跳过。
> `acp-server` 仍然使用清单/代理路径和种子注册表，除非您运行上述导入流程。
## 当前状态
今天正在工作：
- `POST /v1/context` 使用现有的 v0.1 `ExecutionManifest` 线型返回作用域合约。
- 代理强制认证头部并注入服务器端凭证。
- 合约中表示出口和审批边界。
- 存在 MCP 和 Kubernetes 源适配器。
- Python 适配器涵盖 OpenAI 函数调用、LangGraph 和 CrewAI。
- 基准测试重现 MCP 基线和代币差异。
### ACP 不执行的操作
- **解析交互式 VS Code `${input:...}` 提示。** 将机密放入环境或现有的下游 MCP 服务器配置中。
- **替换下游 MCP 服务器。** ACP 启动并转发到它们。它不重新实现提供者 API。
- **无限期缓存 `tools/list`。** 每个 `ImportSource` 调用都会重新获取；当 MCP 服务器的工具集更改时，重新调用调度（或在 webhook 上）。
### 下一步强化工作
- 在代理处强制执行合约 TTL。
- 持久化仅追加审计日志。
- 在执行前签署合约和验证签名。
- 将每个合约绑定到主体和凭证别名。
- 添加 OpenAPI 源适配器以证明源无关执行。
参见 [`docs/positioning.md`](docs/positioning.md) 和
[`docs/validation/signals.md`](docs/validation/signals.md)。
## Python 适配器
```bash
pip install "git+https://github.com/Clawdlinux/agent-contract-protocol.git@main#subdirectory=adapters/python/acp_common"
pip install "git+https://github.com/Clawdlinux/agent-contract-protocol.git@main#subdirectory=adapters/python/acp_langgraph"
pip install "git+https://github.com/Clawdlinux/agent-contract-protocol.git@main#subdirectory=adapters/python/acp_openai"
pip install "git+https://github.com/Clawdlinux/agent-contract-protocol.git@main#subdirectory=adapters/python/acp_crewai"
```
## Go SDK
```go
client := acp.NewClient("http://localhost:8080", acp.WithToken("dev-token"))
contract, err := client.Context(ctx, manifest.ContextRequest{
Intent: "query the customer db",
AgentID: "agent-01",
})
```
## 许可证
- **协议规范** (`SPEC.md`, `docs/protocol.md`)：CC BY 4.0
- **适配器 / SDK** (`pkg/`, `adapters/`)：Apache 2.0
- **ACP 服务器运行时** (`cmd/`, `internal/`)：BSL 1.1，在 3 年后转换为 Apache 2.0
参见 [`LICENSE`](LICENSE) 和 [`docs/LICENSING.md`](docs/LICENSING.md)。
