content-forge-vault/00-inbox/2026-03-24-agent-friendly-development-spec.md

id	title	slug	status	content_type	channels	language	source_urls	assets	cover_image	template	owner	created_at	updated_at	published_at	tags
2026-03-24-agent-friendly-development-spec	Agent Friendly 开发规约 v1.0 — 构建对 AI Agent 友好的系统	agent-friendly-development-spec	inbox	article	wechat x	zh-CN	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/			article	content-forge	2026-03-24T00:00:00+08:00	2026-03-24T00:00:00+08:00	null	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 中，不要抛协议级错误。

{
  "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）

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）

通过阈值：总分 ≥ 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
• Anthropic — Writing Tools for Agents
• Anthropic — Effective Context Engineering
• MCP 规范 (2025-06-18)
• OpenAI — Function Calling Guide

设计最佳实践

• Phil Schmid — MCP Best Practices
• Block — MCP Server Design Playbook
• Stefan Buck — AI API Best Practices
• Apideck — API Design for Agentic Era
• WorkOS — Build Agent-Friendly Products

安全标准

• CoSAI — MCP Security Whitepaper
• SlowMist — MCP Security Checklist
• OWASP — Top 10 for LLM Applications 2025
• OWASP — Top 10 for Agentic Applications

评估框架

• Postman — API Agent Readiness (48 Checks)
• Google ADK — Evaluation Criteria
• Anthropic — Demystifying Evals for AI Agents

行业报告

• Postman 2025 State of API Report — 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 状态可追踪