520 lines
25 KiB
Markdown
520 lines
25 KiB
Markdown
---
|
||
id: "2026-03-24-agent-friendly-development-spec"
|
||
title: "Agent Friendly 开发规约 v1.0 — 构建对 AI Agent 友好的系统"
|
||
slug: "agent-friendly-development-spec"
|
||
status: "inbox"
|
||
content_type: "article"
|
||
channels: ["wechat", "x"]
|
||
language: "zh-CN"
|
||
source_urls:
|
||
- "https://www.anthropic.com/research/building-effective-agents"
|
||
- "https://www.anthropic.com/engineering/writing-tools-for-agents"
|
||
- "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents"
|
||
- "https://modelcontextprotocol.io/specification/2025-06-18/server/tools"
|
||
- "https://www.philschmid.de/mcp-best-practices"
|
||
- "https://engineering.block.xyz/blog/blocks-playbook-for-designing-mcp-servers"
|
||
- "https://workos.com/blog/build-agent-friendly-products"
|
||
- "https://www.apideck.com/blog/api-design-principles-agentic-era"
|
||
- "https://github.com/stefanbuck/ai-api-best-practices"
|
||
- "https://github.com/slowmist/MCP-Security-Checklist"
|
||
- "https://github.com/cosai-oasis/ws4-secure-design-agentic-systems/blob/main/model-context-protocol-security.md"
|
||
- "https://www.postman.com/ai/ai-ready-apis/"
|
||
assets: []
|
||
cover_image: ""
|
||
template: "article"
|
||
owner: "content-forge"
|
||
created_at: "2026-03-24T00:00:00+08:00"
|
||
updated_at: "2026-03-24T00:00:00+08:00"
|
||
published_at: null
|
||
tags: ["agent-friendly", "development-spec", "MCP", "AX", "API-design", "security"]
|
||
---
|
||
|
||
# Agent Friendly 开发规约 v1.0
|
||
|
||
> "Designing for AI agents is designing for the strictest, most literal and tireless user imaginable." — Apidog
|
||
|
||
---
|
||
|
||
## §0 元信息
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| 版本 | 1.0.0 |
|
||
| 日期 | 2026-03-24 |
|
||
| 适用范围 | MCP Server、API、Tool/Function、文档、Agent 系统架构 |
|
||
| 核心来源 | Anthropic 官方指南、MCP 规范、Postman 8 Pillars、CoSAI 安全白皮书、Block MCP Playbook、SlowMist 安全清单 |
|
||
|
||
---
|
||
|
||
## §1 基本原则（5 条铁律）
|
||
|
||
### P1: Schema-First — 先契约后代码
|
||
|
||
> 数据结构和协议是万恶之源，也是万善之源。
|
||
|
||
- 所有能力必须有机器可读的 Schema（OpenAPI / MCP inputSchema / JSON Schema）
|
||
- 先定义接口契约，再实现逻辑
|
||
- Schema 即文档、Schema 即验证、Schema 即测试
|
||
|
||
### P2: 约束 > 能力 — 定义边界比扩展功能更重要
|
||
|
||
> Agent 不需要更多能力，需要更清晰的边界。
|
||
|
||
- 70% 精力花在「不做什么」（NEVER 清单），30% 花在「怎么做」
|
||
- 消除 Agent 需要猜测的一切
|
||
- 如果人类工程师无法明确判断该用哪个工具，Agent 更不可能判断对
|
||
|
||
### P3: 最小惊讶 — 可预测性是 Agent 的氧气
|
||
|
||
> LLM 是模式跟随者（pattern-followers），不一致性会导致幻觉。
|
||
|
||
- 统一命名、统一结构、统一错误格式
|
||
- 同类操作的行为必须一致
|
||
- 10 个一致的端点胜过 50 个风格各异的端点
|
||
|
||
### P4: 最小权限 + 最小代理权 — 不信任 Agent 的自律
|
||
|
||
> "请不要删除客户记录" 不是安全策略——那是许愿。
|
||
|
||
- 通过策略引擎（而非 prompt）限制行为
|
||
- 每次工具调用独立鉴权，而非连接时一次性授权
|
||
- 危险能力通过 allowlist 移除，而非通过 prompt 禁止
|
||
|
||
### P5: 可观测性 — 看不到的就无法修复
|
||
|
||
> "没有 trace 级可观测性就上线 Agent 系统，是工程事故。"
|
||
|
||
- 每个 Agent 动作必须记录：谁发起、调了什么工具、什么参数、什么结果、什么授权范围
|
||
- 不只记输入输出，还要记被拒绝的候选工具和推理链
|
||
- 审计日志不可篡改、有时间戳、可密码学验证
|
||
|
||
---
|
||
|
||
## §2 工具设计规约（Tool Design）
|
||
|
||
### 2.1 命名
|
||
|
||
| 规则 | 正确 | 错误 |
|
||
|------|------|------|
|
||
| 动词优先 + 资源 | `search_documents`, `create_issue` | `do_stuff`, `process`, `run` |
|
||
| 服务前缀消歧义 | `slack_send_message`, `jira_create_issue` | `send_message`（哪个服务？） |
|
||
| 统一大小写 | 全 `snake_case` 或全 `kebab-case` | 混用 `getUser` 和 `search_issues` |
|
||
| 长度 ≤ 60 字符 | `asana_projects_search` | `asana_project_management_system_search_all_projects_v2` |
|
||
| 自解释 | 读名字就知道功能 | 需要看描述才懂 |
|
||
|
||
### 2.2 描述
|
||
|
||
**最低 3-4 句，包含四要素**：
|
||
|
||
```
|
||
1. 做什么（一句话）
|
||
2. 何时用 / 何时不用（与相似工具的边界）
|
||
3. 返回什么（响应结构的关键字段）
|
||
4. 限制和前提（频率限制、前置条件、不返回什么）
|
||
```
|
||
|
||
**示例**：
|
||
|
||
```
|
||
BAD: "Gets data from the system"
|
||
GOOD: "Search for issues in the project tracker by keyword, status, or assignee.
|
||
Returns issue ID, title, status, and assignee for each match.
|
||
Results are paginated (max 50 per page); use the `cursor` parameter for subsequent pages.
|
||
Does NOT return issue comments or attachments -- use get_issue for full details.
|
||
Use when the user wants to find, filter, or list issues."
|
||
```
|
||
|
||
**影响**：经过优化的工具描述将工具激活可靠性从 ~20% 提升到 ~90%。Anthropic 报告：在 SWE-bench Verified 上，仅调整工具描述就产生了显著分数提升。
|
||
|
||
### 2.3 输入 Schema
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| **扁平化** | 顶层原语类型，禁止 3 层以上嵌套 |
|
||
| **严格类型** | 每个参数有 type + description + format |
|
||
| **枚举约束** | 有限值域必须用 enum，不用 freeform string |
|
||
| **required 显式** | 所有 properties 字段列入 required，可选字段用 `["string", "null"]` |
|
||
| **additionalProperties: false** | 禁止未定义字段 |
|
||
| **参数 ≤ 20** | 超过拆分工具 |
|
||
| **提供 examples** | 复杂参数附 input_examples |
|
||
|
||
**反模式**：手写 JSON Schema（必然出错）→ 从 OpenAPI spec 自动生成。
|
||
|
||
### 2.4 输出 Schema
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 高信号字段 | 只返回 Agent 需要推理的字段，非整个数据库记录 |
|
||
| 稳定标识符 | 返回 slug/UUID，非自增 ID 或内部引用 |
|
||
| 分页 | 列表操作必须返回 `next_cursor` + `has_more` |
|
||
| 截断 | 默认限制响应 ≤ 25,000 token，超出提供续取指令 |
|
||
| 双格式 | structuredContent (typed) + TextContent (backward compat) |
|
||
|
||
### 2.5 错误响应
|
||
|
||
**铁律：工具错误放在 result 中，不要抛协议级错误。**
|
||
|
||
```json
|
||
{
|
||
"content": [{"type": "text", "text": "Failed to create issue: title field is required and was empty. Provide a non-empty title string."}],
|
||
"isError": true
|
||
}
|
||
```
|
||
|
||
| 必含字段 | 说明 |
|
||
|---------|------|
|
||
| WHY | 为什么失败 |
|
||
| HOW | 怎么修复 |
|
||
| is_retriable | 是否可重试 |
|
||
| retry_after | 重试等待时间 |
|
||
| alternative_action | 建议替代操作（可选） |
|
||
|
||
**反模式**：返回 stack trace、返回 "An error occurred"、静默吞掉错误。
|
||
|
||
### 2.6 工具注解（MCP Annotations）
|
||
|
||
```typescript
|
||
interface ToolAnnotations {
|
||
readOnlyHint?: boolean; // 不修改环境 → 客户端可自动批准
|
||
destructiveHint?: boolean; // 可能破坏数据 → 客户端应加确认步骤
|
||
idempotentHint?: boolean; // 重复调用 = 相同效果
|
||
openWorldHint?: boolean; // 与外部实体交互
|
||
}
|
||
```
|
||
|
||
| 工具 | readOnly | destructive | idempotent | openWorld |
|
||
|------|----------|-------------|------------|-----------|
|
||
| `search_documents` | true | - | - | false |
|
||
| `create_issue` | false | false | false | false |
|
||
| `update_issue` | false | false | true | false |
|
||
| `delete_issue` | false | true | true | false |
|
||
| `send_notification` | false | false | false | true |
|
||
|
||
**注解是提示（hints），不是安全保证。客户端不得仅基于注解做安全关键决策。**
|
||
|
||
### 2.7 工具粒度
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ 粒度决策树 │
|
||
├──────────────────────────────────────────────┤
|
||
│ 工具数 > 20？ → 审查重叠，合并 │
|
||
│ 工具数 < 5 但 → 审查过度合并，拆分 │
|
||
│ 每个 > 15 参数？ （硬限制 ≤ 20，见 §2.3）│
|
||
│ 两个工具人类无法 → 合并或重写描述消歧义 │
|
||
│ 区分何时用哪个？ │
|
||
│ 常见任务需要 > 3 → 提供组合工具 │
|
||
│ 次连续调用？ │
|
||
│ 一个工具混合读写？ → 拆分为独立风险级别 │
|
||
└──────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Block 经验**：Linear MCP server 从 30+ 工具重建三次，最终缩减到 2 个。GitHub Copilot 从 40 个工具缩减到 13 个后基准测试提升。
|
||
|
||
> "更多工具 = 对数级递减的选择准确率。"
|
||
|
||
---
|
||
|
||
## §3 API 设计规约（API Design）
|
||
|
||
### 3.1 十条 AX 设计原则
|
||
|
||
| # | 原则 | 检查标准 |
|
||
|---|------|---------|
|
||
| 1 | **机器可读 spec 在固定位置** | `/.well-known/openapi.json` 可访问 |
|
||
| 2 | **语义化操作摘要** | 每个端点有 operationId + summary + description |
|
||
| 3 | **扁平可预测 JSON** | 无深层嵌套，含元数据（分页、类型、可用动作） |
|
||
| 4 | **可执行错误响应** | 含 why + how + is_retriable + retry_after |
|
||
| 5 | **频率限制透明** | 响应头含 X-RateLimit-Remaining/Limit/Reset |
|
||
| 6 | **幂等键** | 状态变更操作支持 idempotency key |
|
||
| 7 | **批量端点** | 高频操作提供 batch 接口 |
|
||
| 8 | **引导下一步** | 响应含 recommendedNextAction / availableActions |
|
||
| 9 | **Dry-run 模式** | 破坏性操作支持无副作用预演 |
|
||
| 10 | **内容协商** | 按 Accept header 返回 HTML / Markdown / JSON |
|
||
|
||
### 3.2 Postman 8 支柱 48 项检查（摘录核心项，完整清单见 [Postman Agent Readiness](https://www.postman.com/ai/ai-ready-apis/)）
|
||
|
||
**通过阈值：总分 ≥ 70/100 且 0 项 Critical 失败。**
|
||
|
||
| 支柱 | Critical 项 | 核心检查 |
|
||
|------|------------|---------|
|
||
| **META** 元数据 | operationId | 每个操作有 operationId + summary + description |
|
||
| **ERR** 错误 | 4xx 定义 + 错误 Schema | 含机器可读 ID + 人类可读消息 + 429 定义 |
|
||
| **INTRO** 内省 | 参数类型 + required 标记 | 枚举约束 + 请求/响应示例 |
|
||
| **NAME** 命名 | — | 一致大小写 + RESTful 路径 + 正确 HTTP 语义 |
|
||
| **PRED** 可预测性 | 响应 Schema 定义 | 一致响应信封 + 分页文档 + ISO 8601 |
|
||
| **DOC** 文档 | 认证文档 | 频率限制文档 + API 概述 |
|
||
| **PERF** 性能 | — | 频率限制头 + 缓存头 + 批量端点 |
|
||
| **DISC** 发现 | Server URL 定义 | OpenAPI 3.0+ + 多环境文档 + 版本化 |
|
||
|
||
**8 项 Critical（必须全部通过）**：
|
||
META_001(operationId), ERR_001(4xx), ERR_002(错误Schema), INTRO_001(参数类型), INTRO_002(required), PRED_001(响应Schema), DOC_001(认证文档), DISC_002(Server URL)
|
||
|
||
---
|
||
|
||
## §4 安全规约（Security）
|
||
|
||
### 4.1 十条不可协商的安全约束
|
||
|
||
| # | 约束 | 一句话规则 |
|
||
|---|------|-----------|
|
||
| 1 | **最小代理权** | 每次工具调用通过策略引擎鉴权，而非仅在 token 签发时 |
|
||
| 2 | **临时凭证** | 短期、有限范围 token；任务完成即撤销；禁止长期 standing access |
|
||
| 3 | **Prompt 不是安全边界** | 危险能力通过 allowlist/策略移除，绝不通过 system prompt |
|
||
| 4 | **扫描所有元数据** | MCP 网关扫描工具名、描述、参数中的隐藏 prompt 注入 |
|
||
| 5 | **不可逆操作必须 HITL** | 意图预览 + diff + 确认弹窗，任何无法撤销的操作 |
|
||
| 6 | **四层预算** | 成本 + token + 步骤 + 时间预算在运行时强制执行 |
|
||
| 7 | **每次交接验证** | A2A 链路中每一跳独立验证身份、权限和负载 |
|
||
| 8 | **沙箱隔离** | 代码执行用 microVM（Firecracker/Kata）；容器不够 |
|
||
| 9 | **不可篡改审计** | who + what + why + tools + outcome + auth scope，密码学可验证 |
|
||
| 10 | **Kill Switch 永远可用** | 带键盘快捷键的全局停止机制，中断所有 Agent 活动 |
|
||
|
||
### 4.2 权限模型
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 权限层级模型 │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 人类用户身份 │
|
||
│ └── 委托给 Agent（继承用户权限） │
|
||
│ └── 每个任务签发 Scoped Token │
|
||
│ └── 每次工具调用实时鉴权 │
|
||
│ └── 策略引擎（OPA/Cedar/Oso） │
|
||
│ │
|
||
│ 用户失去权限 → Agent 立即失去权限 │
|
||
│ 任务完成 → Token 立即撤销 │
|
||
│ Session 内权限不得累积 │
|
||
│ │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.3 Prompt 注入防御
|
||
|
||
| 防御层 | 措施 |
|
||
|--------|------|
|
||
| **工具元数据** | MCP 网关扫描 tool name / description / parameter schema 中的隐藏指令 |
|
||
| **外部数据** | Agent 检索的网页/邮件/文档必须消毒后再注入 LLM 上下文 |
|
||
| **版本锁定** | MCP Server 锁定版本 + 代码签名验证，防 rug pull 攻击 |
|
||
| **RAG 隔离** | 检索管道独立隔离，验证上下文数据完整性 |
|
||
| **能力裁剪** | 不需要的工具从 catalog 中移除，而非靠 prompt 禁止 |
|
||
|
||
### 4.4 已知攻击向量
|
||
|
||
| 攻击类型 | 描述 | 防御 |
|
||
|---------|------|------|
|
||
| **直接 Prompt 注入** | "ignore previous rules" | 模式匹配检测 + 输入消毒 |
|
||
| **间接 Prompt 注入** | 外部数据中嵌入恶意指令 | 数据消毒 + RAG 隔离 |
|
||
| **工具投毒** | 工具描述/输出中引导模型执行危险操作 | 元数据扫描 + 版本锁定 |
|
||
| **Schema 投毒** | 操纵 Schema 字段影响工具选择 | Schema 校验 + 基线监控 |
|
||
| **级联幻觉** | Agent A 的错误通过 Agent B/C 毫秒级传播 | 每个 Agent 独立验证输入 |
|
||
| **记忆投毒** | 污染共享上下文影响后续决策 | 不可变存储 + 密码学验证 |
|
||
| **Slopsquatting** | LLM 幻觉出不存在的包名，攻击者注册 | 依赖锁定 + hash 校验 |
|
||
| **偏好操纵 (MPMA)** | 改变 Agent 排序和选择工具的方式 | 工具选择基线监控 |
|
||
|
||
---
|
||
|
||
## §5 文档规约（Documentation）
|
||
|
||
### 5.1 文档发现层
|
||
|
||
| 文件 | 路径 | 用途 | 格式 |
|
||
|------|------|------|------|
|
||
| `llms.txt` | `/llms.txt` | 站点摘要（robots.txt for AI） | Markdown |
|
||
| `llms-full.txt` | `/llms-full.txt` | 完整文档单文件 | Markdown |
|
||
| `openapi.json` | `/.well-known/openapi.json` | API Schema | JSON/YAML |
|
||
| Agent Card | `/.well-known/agent-card.json` | Agent 能力声明（A2A） | JSON |
|
||
| `AGENTS.md` | 仓库根目录 | 编码 Agent 项目指令 | Markdown |
|
||
|
||
### 5.2 文档质量标准
|
||
|
||
| 维度 | 要求 |
|
||
|------|------|
|
||
| **机器可读** | Schema 优先于散文；结构化 frontmatter 优先于自由文本 |
|
||
| **自包含** | 所有必要上下文内联，减少跳转；Agent 无法"点击链接" |
|
||
| **显式假设** | 前提条件和约束显式声明，不依赖读者推断 |
|
||
| **示例驱动** | 每个端点/工具至少 1 个完整示例 |
|
||
| **内容协商** | 按 Accept header 返回 HTML（浏览器）或 Markdown（Agent） |
|
||
| **结构化数据** | JSON-LD / Schema.org 标记主要实体 |
|
||
|
||
---
|
||
|
||
## §6 评估规约（Evaluation）
|
||
|
||
### 6.1 工具质量评分（10 项，二值通过）
|
||
|
||
| # | 检查项 | Pass | Fail |
|
||
|---|--------|------|------|
|
||
| 1 | 名称清晰度 | 动词+资源，自解释 | 泛化（`do_stuff`）或歧义 |
|
||
| 2 | 描述完整度 | 四要素齐全（做什么/何时用/返回什么/限制） | 一句话或无描述 |
|
||
| 3 | 参数类型化 | 每个参数有 type+description+format | 缺类型或缺描述 |
|
||
| 4 | Schema 扁平度 | 顶层原语，≤ 2 层 | 深层嵌套 |
|
||
| 5 | 示例提供 | 至少 1 个 input example | 无示例 |
|
||
| 6 | 返回结构化 | 有 status key + 人类可读字段 | 自由文本或内部代码 |
|
||
| 7 | 错误可执行 | 含 why + how + 重试建议 | 不透明错误码 |
|
||
| 8 | Token 效率 | 分页+过滤+截断 | 返回全量数据 |
|
||
| 9 | 单一职责 | 一个工具=一个任务=一个风险级别 | 混合读写或多动作 |
|
||
| 10 | 命名空间 | `{service}_{action}_{resource}` | 无前缀，歧义 |
|
||
|
||
**阈值：≥8/10 = 可接受。7/10 = 需改进。≤6/10 = 必须重新设计。**
|
||
|
||
### 6.2 系统级评估（Google Cloud 三支柱）
|
||
|
||
| 支柱 | 测试类型 | 指标 |
|
||
|------|---------|------|
|
||
| **最终输出** | 集成测试 | 任务完成率、正确性、一致性、事实基础 |
|
||
| **决策过程** | 单元测试 | 工具选择准确率、推理逻辑、效率 |
|
||
| **韧性** | 压力测试 | 优雅降级、错误恢复、对抗鲁棒性 |
|
||
|
||
**评分**：A（全通过）、B（2/3 通过）、C（1/3 通过）、F（全不通过）
|
||
|
||
### 6.3 生产准入检查清单
|
||
|
||
```
|
||
□ 所有工具通过 §6.1 质量评分 ≥ 8/10
|
||
□ OpenAPI spec 通过 Postman 48 项检查 ≥ 70 分且 0 Critical
|
||
□ §6.2 三支柱评估 ≥ B 级（至少 2/3 支柱通过）
|
||
□ 安全检查通过 SlowMist MCP 安全清单所有 High 项
|
||
□ 错误注入测试覆盖：超时、500、频率限制、畸形响应
|
||
□ Agent 在 10 步工作流中端到端成功率 ≥ 80%
|
||
□ Trace 级可观测性已部署
|
||
□ Kill Switch 功能验证通过
|
||
□ 审计日志不可篡改性验证通过
|
||
□ 权限模型通过最小代理权审查
|
||
□ llms.txt / AGENTS.md / openapi.json 发现层完备
|
||
```
|
||
|
||
---
|
||
|
||
## §7 NEVER 清单（反模式速查）
|
||
|
||
### 工具设计 NEVER
|
||
|
||
| # | NEVER | 正确做法 |
|
||
|---|-------|---------|
|
||
| N1 | 1:1 包装 REST 端点为 MCP 工具 | 按用户目标设计组合工具 |
|
||
| N2 | 手写 JSON Schema | 从 OpenAPI spec 自动生成 |
|
||
| N3 | 返回数百条无分页记录 | 分页 + 截断 + 续取指令 |
|
||
| N4 | 泛化工具名（`process`, `run`） | `{service}_{action}_{resource}` |
|
||
| N5 | 描述只写一句话 | 四要素：做什么/何时用/返回什么/限制 |
|
||
| N6 | 返回 stack trace | 消毒后的高层消息 + 修复建议 |
|
||
| N7 | 工具错误抛协议级异常 | 错误放在 result 中 + isError: true |
|
||
| N8 | 同一工具混合读写操作 | 按风险级别拆分 |
|
||
| N9 | Session 中途改变工具列表 | 工具集稳定，按需动态加载 |
|
||
| N10 | 返回低信号技术标识符 | 返回人类可读的高信号字段 |
|
||
|
||
### 安全 NEVER
|
||
|
||
| # | NEVER | 正确做法 |
|
||
|---|-------|---------|
|
||
| N11 | 靠 prompt 指令当安全策略 | 策略引擎 (OPA/Cedar) 强制执行 |
|
||
| N12 | 给 Agent 全权限 token | Token Exchange (RFC 8693) 签发有限范围临时 token |
|
||
| N13 | 连接时一次性授权 | 每次工具调用实时鉴权 |
|
||
| N14 | 不可逆操作自动执行 | HITL 确认 + 意图预览 + diff |
|
||
| N15 | 只靠 dashboard 配置预算 | 运行时四层预算强制执行 |
|
||
| N16 | 合并人类和 Agent 审计日志 | 分开记录，标注 Agent 身份 |
|
||
| N17 | 多个 MCP Server 共享沙箱 | 每个 Server 独立隔离上下文 |
|
||
| N18 | 信任上游 Agent 的输出 | 每个 Agent 独立验证输入 |
|
||
| N19 | 未锁定 MCP Server 版本 | 版本锁定 + 代码签名 |
|
||
| N20 | 人类认证流程给 Agent 用 | 无 CAPTCHA/MFA 的程序化认证 |
|
||
|
||
### 架构 NEVER
|
||
|
||
| # | NEVER | 正确做法 |
|
||
|---|-------|---------|
|
||
| N21 | 单 Agent 没跑通就上多 Agent | 先证明单 Agent 方案的痛点 |
|
||
| N22 | 把所有数据灌进向量库期望 LLM 自己搞定 | 精选高信号上下文 |
|
||
| N23 | 跳过错误注入测试 | 注入超时/500/畸形响应并断言恢复行为 |
|
||
| N24 | 只做输入输出日志 | Trace 级：含被拒绝的候选工具和推理链 |
|
||
| N25 | 让 LLM 决定何时放弃重试 | 硬编码退出标准：max retries + timeout + circuit breaker |
|
||
|
||
---
|
||
|
||
## §8 复合精度公式
|
||
|
||
> Agent 准确率的数学是残酷的。
|
||
|
||
```
|
||
端到端成功率 = (单步准确率) ^ 步骤数
|
||
|
||
| 单步准确率 | 5 步 | 10 步 | 20 步 |
|
||
|-----------|------|-------|-------|
|
||
| 95% | 77% | 60% | 36% |
|
||
| 90% | 59% | 35% | 12% |
|
||
| 85% | 44% | 20% | 4% |
|
||
| 80% | 33% | 11% | 1% |
|
||
```
|
||
|
||
**含义**：
|
||
- 每一个工具设计决策都在影响那个「单步准确率」
|
||
- 好的工具描述将激活准确率从 ~20% 提升到 ~90%
|
||
- 更少的步骤 = 指数级更高的可靠性 → 组合工具减少链式调用
|
||
|
||
---
|
||
|
||
## §9 协议栈速查
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ 发现层 │
|
||
│ llms.txt + AGENTS.md + openapi.json + Agent Card │
|
||
├──────────────────────────────────────────────────────────┤
|
||
│ 工具连接层 (MCP) │
|
||
│ Agent ←→ Tool · JSON-RPC 2.0 · 三原语：工具/资源/提示 │
|
||
├──────────────────────────────────────────────────────────┤
|
||
│ Agent 互操作层 (A2A) │
|
||
│ Agent ←→ Agent · HTTP/SSE/gRPC · Agent Card 发现 │
|
||
├──────────────────────────────────────────────────────────┤
|
||
│ 安全层 │
|
||
│ OAuth 2.1 + 策略引擎 + 沙箱 + 审计 + KYA(Know Your Agent)│
|
||
├──────────────────────────────────────────────────────────┤
|
||
│ 商务层 │
|
||
│ ACP(Stripe+OpenAI) + Agent Pay(Visa/MC) + x402(微支付) │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## §10 参考来源
|
||
|
||
### 权威指南
|
||
- [Anthropic — Building Effective Agents](https://www.anthropic.com/research/building-effective-agents)
|
||
- [Anthropic — Writing Tools for Agents](https://www.anthropic.com/engineering/writing-tools-for-agents)
|
||
- [Anthropic — Effective Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
|
||
- [MCP 规范 (2025-06-18)](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
|
||
- [OpenAI — Function Calling Guide](https://platform.openai.com/docs/guides/function-calling)
|
||
|
||
### 设计最佳实践
|
||
- [Phil Schmid — MCP Best Practices](https://www.philschmid.de/mcp-best-practices)
|
||
- [Block — MCP Server Design Playbook](https://engineering.block.xyz/blog/blocks-playbook-for-designing-mcp-servers)
|
||
- [Stefan Buck — AI API Best Practices](https://github.com/stefanbuck/ai-api-best-practices)
|
||
- [Apideck — API Design for Agentic Era](https://www.apideck.com/blog/api-design-principles-agentic-era)
|
||
- [WorkOS — Build Agent-Friendly Products](https://workos.com/blog/build-agent-friendly-products)
|
||
|
||
### 安全标准
|
||
- [CoSAI — MCP Security Whitepaper](https://github.com/cosai-oasis/ws4-secure-design-agentic-systems/blob/main/model-context-protocol-security.md)
|
||
- [SlowMist — MCP Security Checklist](https://github.com/slowmist/MCP-Security-Checklist)
|
||
- [OWASP — Top 10 for LLM Applications 2025](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
|
||
- [OWASP — Top 10 for Agentic Applications](https://genai.owasp.org/2025/12/09/owasp-top-10-for-agentic-applications/)
|
||
|
||
### 评估框架
|
||
- [Postman — API Agent Readiness (48 Checks)](https://www.postman.com/ai/ai-ready-apis/)
|
||
- [Google ADK — Evaluation Criteria](https://google.github.io/adk-docs/evaluate/criteria/)
|
||
- [Anthropic — Demystifying Evals for AI Agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
|
||
|
||
### 行业报告
|
||
- [Postman 2025 State of API Report](https://voyager.postman.com/doc/postman-state-of-the-api-report-2025.pdf) — 89% 用 AI, 24% 为 Agent 设计
|
||
- Gartner — 40% 企业应用嵌入 Agent (2026), 90% B2B 采购 Agent 代理 (2028) [付费报告，无公开链接]
|
||
|
||
---
|
||
|
||
## 附录 A：本规约与 content-forge 项目设计原则的对应关系
|
||
|
||
| 本规约原则 | content-forge CLAUDE.md 对应 | 映射 |
|
||
|-----------|---------------------------|------|
|
||
| P1 Schema-First | CLAUDE.md §10.7 Frontmatter-First | frontmatter 是机器可读契约层 |
|
||
| P2 约束 > 能力 | CLAUDE.md §10.7 约束 > 能力 | 70% NEVER + 30% 执行步骤 |
|
||
| P3 最小惊讶 | CLAUDE.md §4.2 frontmatter 统一规范 | 一致字段命名和状态机 |
|
||
| P4 最小权限 | CLAUDE.md §6.1.1 NEVER 规则 | Agent 只读 Vault，不写 |
|
||
| P5 可观测性 | CLAUDE.md §4.3 阶段退出标准 | frontmatter 状态可追踪 |
|