Shoon A2A Trust Services (pilot)

A2A 服务系统 — 第 0 阶段沙盒（仅限本地测试）

测试沙盒。 所有内容均免费（$0.00），采用测试网语义，仅绑定到 127.0.0.1。没有真实加密货币、真实付款或外部账户，也不会发生资金转移。这里的任何内容都不公开，也不用于商业用途。

运行

cd ~/workspace/compound/a2a-economy/sandbox
pip3 install --user --break-system-packages -r requirements.txt
# admin secret is REQUIRED — the server refuses to start without it
export A2A_SANDBOX_ADMIN="$(cat ~/.config/a2a-sandbox-admin)"
python3 -m uvicorn app:app --host 127.0.0.1 --port 8741

生成一次密钥（以仅所有者可访问的权限存储，绝不出现在聊天或日志中）：

mkdir -p ~/.config
python3 -c "import secrets; print(secrets.token_hex(32))" > ~/.config/a2a-sandbox-admin
chmod 600 ~/.config/a2a-sandbox-admin

然后在另一个终端中：

# machine-readable catalog (Tier A)
curl -s http://127.0.0.1:8741/v1/catalog.json | head -c 600

# public free-slot counter
curl -s http://127.0.0.1:8741/v1/slots

# synthetic buyer harness (full loop per service, green/red per stage)
python3 harness.py

# human test page
# open http://127.0.0.1:8741/test.html in a browser (test API key prefilled)

真实功能与模拟功能

真实（协议已完整实现）：

• POST /quote — 免费、零代币、基于公式生成绑定报价，有效期 15 分钟，并进行输入上限和策略检查，同时写入账本
• POST /execute — 未付款时返回 402（x402 格式的响应）；模拟先提交后结算的授权验证（结构、报价匹配和 validBefore 过期时间）；返回 202 + task_id，使用异步作业队列，对交付物进行 Ed25519 签名，并生成结算事件
• 配额执行：必须提供身份；每个钱包或 API 密钥每天最多 10 个任务；每项服务每天最多 20 个任务，并带有公开的名额计数器；全局每日代币预算达到上限时自动暂停
• 将终止开关作为功能标志（POST /v1/admin/kill / POST /v1/admin/resume，通过 A2A_SANDBOX_ADMIN 环境变量设置令牌——未设置时，服务器会拒绝启动）；不会自动恢复
• SSRF 防护：解析任务提供的 URL，并要求每个地址都必须是公网地址（拒绝环回地址、专用 LAN、链路本地和云元数据范围，包括重定向访问到的地址）；拒绝非 http(s) 协议
• 仅追加的 JSONL 账本 + CSV/JSON 税务导出模拟接口（/v1/ledger/export）
• 按任务隔离隐私（针对每位买家锁定）： 每个任务在接受时都会获得一个随机的 256 位 read_token（在 202 响应中返回——请保密，并将其视同密码）。任务状态、交付物、签名检查以及该任务的账本条目，都必须通过 Authorization: Bearer <token> 请求头提供令牌才能访问。此处设计为仅使用请求头：若将令牌放入 URL，就会记录在服务器访问日志中。未提供令牌 → 401。完整账本（所有买家的数据）仅管理员可访问（X-Admin-Token 请求头）。任务和报价 ID 均为 128 位随机值；管理员令牌使用恒定时间比较。
• 持久化配额： 使用计数器和暂停状态保存在 SQLite（data/quotas.db）中——重启不再会重置每日上限或终止开关状态。
• MCP（模型上下文协议）： POST /mcp 使用 Streamable HTTP（无状态 JSON-RPC 2.0）：initialize、tools/list（列出 5 项服务）、tools/call（同步执行报价 → 接受 → 等待，并返回已签名的交付物）。支持两种身份验证流程：人工单步流程（X-API-KEY 请求头 + arguments.input），或机器双步流程（先调用 POST /quote，再通过 arguments.quote_id 和用于授权该报价的 X-PAYMENT 请求头调用 tools/call）。调用计入 mcp 来源流量。
• 来源跟踪： 每个已接受的任务都会按渠道统计——human、machine、mcp——并与配额用量一同显示在仅管理员可访问的 GET /v1/admin/stats 中。
• Tier A 机器可读文件：/v1/catalog.json、/.well-known/agent.json、/llms.txt、/v1/openapi.json、/robots.txt（允许 AI 爬虫访问）
• 诚实的服务逻辑：真实获取用户提供的 HTTPS URL；结果会明确标注

模拟功能：

• EIP-3009 授权为模拟实现（X-PAYMENT 请求头中使用 base64 JSON）——验证只检查格式、报价匹配和过期时间，不验证链上签名
• 结算是采用“测试网语义”的 $0.00 账本事件——不会与区块链交互，也没有水龙头资金
• 代币预算为模拟值（根据输入字节数估算），并非真实的大模型代币
• 新闻触发条件按需检查；尚无后台调度程序
• 没有 facilitator、托管服务或 webhook 投递（接受 webhook_url，但不会调用），也没有 Postgres/Inngest
• 人工试点 API 密钥是固定测试密钥，不会按用户单独发放

诚实规则（在代码中强制执行）

• 每项交付内容都包含 "sandbox": true
• 声明验证：“supported” = 在引用的来源中找到逐字匹配的引文，不代表“该声明属实”。无法核验 → “unverified”
• 引用审计：报告真实的 HTTP 状态码 + 逐字匹配的文本
• 工作证明：仅检查证据是否已解析；绝不声称工作已得到验证
• QA 闸门：任何缺少 sandbox 标志或必需输出键的结果都会导致失败

文件

• app.py — FastAPI 网关
• catalog.py — 5 项服务定义（架构、上限、插槽）
• services.py — 诚实的最简服务逻辑 + QA 闸门
• signing.py — Ed25519 密钥管理
• ledger.py — 仅追加的 JSONL 账本
• quotas.py — 稀缺配额、令牌预算、紧急停止开关
• harness.py — 合成买方测试框架
• static/ — agent.json、llms.txt、robots.txt、test.html（面向用户的页面）
• data/ — 密钥 + ledger.jsonl（运行时创建，按惯例由 git 忽略）