From 09aad62ec3df9220e1ed99594fc3057f3ba8670c Mon Sep 17 00:00:00 2001 From: lizikk Date: Wed, 25 Mar 2026 02:00:01 +0800 Subject: [PATCH] vault: auto-sync 2026-03-25 02:00 --- .../2026-03-24-agent-friendly-architecture.md | 761 +++++++++++++ ...2026-03-24-agent-friendly-deep-research.md | 289 +++++ ...6-03-24-agent-friendly-development-spec.md | 519 +++++++++ .../2026-03-24-agent-friendly-glossary.md | 1001 +++++++++++++++++ ...2026-03-24-harness-engineering-analysis.md | 359 ++++++ 5 files changed, 2929 insertions(+) create mode 100644 00-inbox/2026-03-24-agent-friendly-architecture.md create mode 100644 00-inbox/2026-03-24-agent-friendly-deep-research.md create mode 100644 00-inbox/2026-03-24-agent-friendly-development-spec.md create mode 100644 00-inbox/2026-03-24-agent-friendly-glossary.md create mode 100644 00-inbox/2026-03-24-harness-engineering-analysis.md diff --git a/00-inbox/2026-03-24-agent-friendly-architecture.md b/00-inbox/2026-03-24-agent-friendly-architecture.md new file mode 100644 index 0000000..399bf39 --- /dev/null +++ b/00-inbox/2026-03-24-agent-friendly-architecture.md @@ -0,0 +1,761 @@ +--- +id: "2026-03-24-agent-friendly-architecture" +title: "Agent Friendly 概念关系与架构全景图" +slug: "agent-friendly-architecture" +status: "inbox" +content_type: "article" +channels: ["wechat", "x"] +language: "zh-CN" +source_urls: + - "https://www.anthropic.com/research/building-effective-agents" + - "https://modelcontextprotocol.io/specification/2025-06-18/server/tools" + - "https://a2a-protocol.org" + - "https://agentexperience.ax/" +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", "architecture", "concept-map", "MCP", "A2A", "AX"] +--- + +# Agent Friendly 概念关系与架构全景图 + +--- + +## 一、总体架构：五层模型 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ │ +│ ⑤ 治理与生态层 (Governance) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │ +│ │ AAIF │ │ CoSAI │ │ OWASP │ │ OpenAPI Initiative│ │ +│ │ 标准治理 │ │ 安全联盟 │ │ 安全标准 │ │ API 描述标准 │ │ +│ └──────────┘ └──────────┘ └──────────┘ └───────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ④ 发现与身份层 (Discovery) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ llms.txt │ │AGENTS.md │ │ Agent │ │ KYA │ │ +│ │ 文档发现 │ │ 项目指令 │ │ Card │ │ 身份验证 │ │ +│ └──────────┘ └──────────┘ │ 能力声明 │ └──────────┘ │ +│ ┌──────────┐ ┌──────────┐ └──────────┘ ┌──────────┐ │ +│ │ JSON-LD │ │Schema.org│ │ OpenAPI │ │ +│ │ 语义标注 │ │ 词汇表 │ │ API 描述 │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ③ 协议与连接层 (Protocol) │ +│ │ +│ ┌───────────────────────┐ ┌───────────────────────┐ │ +│ │ MCP │ │ A2A │ │ +│ │ Agent ←→ Tool │ │ Agent ←→ Agent │ │ +│ │ 垂直连接（纵向） │ │ 水平互操作（横向） │ │ +│ │ JSON-RPC 2.0 │ │ HTTP / SSE / gRPC │ │ +│ └───────────────────────┘ └───────────────────────┘ │ +│ ┌───────────────────────┐ ┌───────────────────────┐ │ +│ │ Agentic Commerce │ │ A2UI │ │ +│ │ Protocol │ │ Agent → 富 UI 渲染 │ │ +│ │ Agent 支付/商务 │ │ │ │ +│ └───────────────────────┘ └───────────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ② 设计与实现层 (Design) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ AX 设计 │ │ ACI 接口 │ │ Tool │ │ Agent │ │ +│ │ 10 原则 │ │ 设计方法 │ │ Design │ │ Skills │ │ +│ └──────────┘ └──────────┘ │ 7 子规约 │ │ 可移植知识│ │ +│ ┌──────────┐ ┌──────────┐ └──────────┘ └──────────┘ │ +│ │ Schema- │ │ Outcome- │ ┌──────────┐ ┌──────────┐ │ +│ │ First │ │ Oriented │ │Idempotent│ │ Content │ │ +│ │ 契约优先 │ │ 结果导向 │ │ 幂等设计 │ │Negotiation│ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ① 安全与运维层 (Security & Ops) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Least │ │ Sandbox │ │ Policy │ │ Audit │ │ +│ │ Agency │ │ /MicroVM │ │ Engine │ │ Trail │ │ +│ │ 最小代理权│ │ 沙箱隔离 │ │ 策略引擎 │ │ 审计日志 │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ HITL │ │ Circuit │ │ Token │ │ Kill │ │ +│ │ 人在环路 │ │ Breaker │ │ Exchange │ │ Switch │ │ +│ │ │ │ 熔断器 │ │ 令牌交换 │ │ 紧急停止 │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +**阅读方式**：从下往上。安全是地基，设计是砖墙，协议是管道，发现是门牌，治理是法规。 + +--- + +## 二、层间依赖关系 + +``` +⑤ 治理层 ─── 制定规则 ──→ 所有下层必须遵循 + │ + │ 产出标准 + ▼ +④ 发现层 ─── 让 Agent 找到你 ──→ 是协议层的前提 + │ + │ 提供元数据 + ▼ +③ 协议层 ─── 让 Agent 连接你 ──→ 是设计层的载体 + │ + │ 定义通信方式 + ▼ +② 设计层 ─── 让 Agent 正确使用你 ──→ 是安全层的对象 + │ + │ 约束行为边界 + ▼ +① 安全层 ─── 让 Agent 安全运行 ──→ 保护所有上层 +``` + +**关键洞察**：每一层都是上一层的前提条件。没有安全层的设计是裸奔；没有发现层的协议是隐身；没有治理层的生态是丛林。 + +--- + +## 三、协议层关系图：MCP vs A2A vs 商务协议 + +``` + ┌─────────────┐ + │ 人类用户 │ + └──────┬──────┘ + │ 委托 + ▼ + ┌─────────────┐ + │ AI Agent │ + │ (客户端) │ + └──┬───┬───┬──┘ + │ │ │ + ┌────────────┘ │ └────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌────────────────┐ ┌────────────┐ ┌────────────────┐ + │ MCP 协议 │ │ A2A 协议 │ │ 商务协议 │ + │ Agent → Tool │ │ Agent → │ │ Agent → 支付 │ + │ │ │ Agent │ │ │ + │ "我需要用工具" │ │ "我需要 │ │ "我需要付款" │ + │ │ │ 别的Agent │ │ │ + │ │ │ 帮忙" │ │ │ + └───────┬────────┘ └─────┬──────┘ └───────┬────────┘ + │ │ │ + ▼ ▼ ▼ + ┌────────────────┐ ┌────────────┐ ┌────────────────┐ + │ MCP Server │ │ 其他 Agent │ │ Stripe / Visa │ + │ (工具/数据) │ │ (协作者) │ │ (支付网关) │ + │ │ │ │ │ │ + │ 数据库、API、 │ │ 客服Agent、│ │ ACP, TAP, │ + │ 文件系统 │ │ 分析Agent │ │ Agent Pay │ + └────────────────┘ └────────────┘ └────────────────┘ + + ─── 垂直连接 ─── ── 水平互操作 ── ── 商务能力 ── +``` + +**核心关系**：MCP 和 A2A **互补而非竞争**。 + +| 维度 | MCP | A2A | +|------|-----|-----| +| 方向 | 垂直（Agent→Tool） | 水平（Agent→Agent） | +| 类比 | USB 线（连接设备） | WiFi（设备间通信） | +| 对方可见性 | Agent 知道 Tool 内部实现 | Agent 对另一个 Agent 不透明 | +| 发现机制 | Server 定义 Tool 列表 | Agent Card (.well-known) | +| 典型场景 | 查数据库、调 API | 跨组织 Agent 协作 | + +--- + +## 四、发现层关系图：Agent 如何找到你 + +``` +Agent 寻找能力 + │ + ├─── ① 我要找一个网站/产品的信息 + │ │ + │ ▼ + │ ┌──────────┐ ┌───────────────┐ + │ │ llms.txt │────▶│ llms-full.txt │ + │ │ 摘要索引 │ │ 完整内容 │ + │ └──────────┘ └───────────────┘ + │ │ + │ │ 结构化理解 + │ ▼ + │ ┌──────────┐ ┌──────────┐ + │ │ JSON-LD │◀───▶│Schema.org│ + │ │ 语义标注 │ │ 词汇表 │ + │ └──────────┘ └──────────┘ + │ + ├─── ② 我要调用一个 API + │ │ + │ ▼ + │ ┌──────────┐ ┌──────────┐ + │ │ OpenAPI │────▶│ Arazzo │ + │ │ 端点描述 │ │ 工作流序列│ + │ └──────────┘ └──────────┘ + │ + ├─── ③ 我要在一个代码仓库工作 + │ │ + │ ▼ + │ ┌──────────┐ ┌──────────┐ + │ │AGENTS.md │ │CLAUDE.md │ + │ │ 通用指令 │ │ Claude专属│ + │ └──────────┘ └──────────┘ + │ + └─── ④ 我要找另一个 Agent 协作 + │ + ▼ + ┌──────────┐ ┌──────────┐ + │Agent Card│────▶│ KYA 验证 │ + │ 能力声明 │ │ 身份信任 │ + └──────────┘ └──────────┘ +``` + +**关键洞察**：四种发现场景使用四种不同的元数据格式——但它们共享一个原则：**机器可读 > 人类可读**。 + +--- + +## 五、安全层关系图：纵深防御 + +``` + ┌─────────────────────┐ + │ 人类用户 │ + │ （最终权限来源） │ + └──────────┬──────────┘ + │ 委托 + 权限边界 + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Kill Switch（紧急停止） │ │ +│ │ 随时可中断所有 Agent 活动的全局开关 │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─── 第 1 道防线：身份与授权 ──────────────────────────┐ │ +│ │ │ │ +│ │ KYA ──→ Token Exchange ──→ Scoped Token │ │ +│ │ 身份验证 权限降级 有限范围临时令牌 │ │ +│ │ │ │ +│ │ Policy Engine (OPA/Cedar) ──→ 每次调用实时鉴权 │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─── 第 2 道防线：输入验证与消毒 ──────────────────────┐ │ +│ │ │ │ +│ │ Agent Gateway ──→ 元数据扫描（工具投毒检测） │ │ +│ │ │ │ │ +│ │ └──→ Prompt 注入检测 ──→ 外部数据消毒 │ │ +│ │ │ │ +│ │ JSON Schema 验证 ──→ 每个工具调用参数校验 │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─── 第 3 道防线：执行隔离 ────────────────────────────┐ │ +│ │ │ │ +│ │ Sandbox / MicroVM ──→ 每个 MCP Server 独立隔离 │ │ +│ │ │ │ │ +│ │ └──→ 零信任网络（显式允许 > 默认放行） │ │ +│ │ │ │ +│ │ 四层预算 ──→ 成本 + Token + 步骤 + 时间 │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─── 第 4 道防线：运行时保护 ──────────────────────────┐ │ +│ │ │ │ +│ │ HITL ──→ 不可逆操作前人类确认 │ │ +│ │ │ │ │ +│ │ Intent Preview ──→ 意图预览 + Dry-run │ │ +│ │ │ │ │ +│ │ Circuit Breaker ──→ 连续失败自动熔断 │ │ +│ │ │ │ +│ │ Graceful Degradation ──→ 降级而非崩溃 │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─── 第 5 道防线：审计与追溯 ──────────────────────────┐ │ +│ │ │ │ +│ │ Audit Trail ──→ 不可篡改 + 密码学可验证 │ │ +│ │ │ │ │ +│ │ └──→ 全链路追踪（who/what/why/tools/outcome） │ │ +│ │ │ │ +│ │ A2A 链路 ──→ 每次交接独立验证身份/权限/负载 │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────┘ +``` + +**关键关系**： + +``` +Least Privilege（能访问什么） + └──→ Least Agency（能做什么 + 做多少次） + └──→ HITL（高风险操作人类确认） + └──→ Kill Switch（极端情况全局停止） + +四者是递进关系：权限 → 行为 → 确认 → 中断 +``` + +--- + +## 六、攻击面与防御映射 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 攻击面全景 │ +├──────────────────┬──────────────────┬───────────────────────┤ +│ 输入侧攻击 │ 元数据侧攻击 │ 链路侧攻击 │ +├──────────────────┼──────────────────┼───────────────────────┤ +│ │ │ │ +│ Direct Prompt │ Tool Poisoning │ Cascading │ +│ Injection │ 工具投毒 │ Hallucination │ +│ 直接注入 │ │ 级联幻觉 │ +│ │ │ Schema Poisoning │ │ │ +│ │ │ Schema 投毒 │ Memory Poisoning │ +│ Indirect Prompt │ │ 记忆投毒 │ +│ Injection │ MPMA │ │ │ +│ 间接注入 │ 偏好操纵攻击 │ Slopsquatting │ +│ │ │ 包名抢注 │ +│ │ │ │ +├──────────────────┼──────────────────┼───────────────────────┤ +│ 防御措施 │ 防御措施 │ 防御措施 │ +├──────────────────┼──────────────────┼───────────────────────┤ +│ │ │ │ +│ 输入消毒 │ 元数据扫描 │ 独立验证输入 │ +│ 模式匹配检测 │ 版本锁定 │ 不可变共享上下文 │ +│ RAG 隔离 │ 代码签名 │ 行为基线监控 │ +│ 外部数据消毒 │ 基线监控 │ 依赖锁定 + hash │ +│ │ │ │ +└──────────────────┴──────────────────┴───────────────────────┘ +``` + +--- + +## 七、设计概念关系图：从理念到实现 + +``` + ┌──────────────┐ + │ AX (理念) │ + │ Agent 体验学科 │ + └───────┬──────┘ + │ 具体化为 + ┌───────────┼───────────┐ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │ ACI │ │ 10 条 │ │ LLMO │ + │接口设计法 │ │ AX 原则 │ │搜索优化法 │ + └────┬─────┘ └────┬─────┘ └────┬─────┘ + │ │ │ + ┌──────────┤ ┌──────┤ ┌──────┤ + ▼ ▼ ▼ ▼ ▼ ▼ + ┌─────────┐┌──────┐┌─────┐┌─────┐┌─────┐┌──────┐ + │Schema- ││Tool ││Idem-││HATE-││JSON-││llms. │ + │First ││Annot.││poten││OAS ││LD ││txt │ + │契约优先 ││工具注解││幂等 ││自描述││语义 ││文档 │ + └─────────┘└──────┘└─────┘└─────┘└─────┘└──────┘ + │ │ │ │ │ │ + └──────────┴──────┴──────┴──────┴──────┘ + │ + ▼ + ┌──────────────────┐ + │ Outcome-Oriented │ + │ Tool Design │ + │ 面向结果的工具设计 │ + └──────────────────┘ + │ + ┌──────────┼──────────┐ + ▼ ▼ ▼ + ┌──────────┐┌──────────┐┌──────────┐ + │ 更少工具 ││ 更扁 Schema││ 更丰富描述│ + │ (粒度) ││ (结构) ││ (四要素) │ + └──────────┘└──────────┘└──────────┘ +``` + +**核心逻辑**：AX 是顶层理念 → ACI/原则/LLMO 是三个实现方向 → 每个方向分解为具体设计模式 → 所有模式汇聚到"面向结果的工具设计"这一实操方法。 + +--- + +## 八、评估体系关系图 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 评估体系全景 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─── API 层面（你的 API 对 Agent 友好吗？）────────────┐ │ +│ │ │ │ +│ │ Postman 48 Checks (0-100 分) │ │ +│ │ └─→ 8 支柱 × 6 项 = 48 项检查 │ │ +│ │ └─→ 通过线：≥70 分 + 0 Critical 失败 │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ API 通过后 │ +│ ▼ │ +│ ┌─── 工具层面（你的 Tool 设计合格吗？）────────────────┐ │ +│ │ │ │ +│ │ 工具质量 10 项评分 (binary pass/fail) │ │ +│ │ └─→ 名称/描述/类型/扁平/示例/返回/错误/效率/职责/ns│ │ +│ │ └─→ 通过线：≥8/10 │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ 工具通过后 │ +│ ▼ │ +│ ┌─── 安全层面（你的安全措施到位吗？）──────────────────┐ │ +│ │ │ │ +│ │ SlowMist MCP 安全清单 (~90 项, High/Med/Low) │ │ +│ │ └─→ 通过线：所有 High 项通过 │ │ +│ │ │ │ +│ │ CoSAI 白皮书 8 项优先建议 │ │ +│ │ └─→ 通过线：8/8 实施 │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ 安全通过后 │ +│ ▼ │ +│ ┌─── 系统层面（你的 Agent 系统整体可靠吗？）──────────┐ │ +│ │ │ │ +│ │ Google Cloud 三支柱 (A/B/C/F) │ │ +│ │ ├─→ 最终输出（集成测试） │ │ +│ │ ├─→ 决策过程（单元测试） │ │ +│ │ └─→ 韧性（压力测试） │ │ +│ │ │ │ +│ │ 复合精度公式 │ │ +│ │ └─→ 端到端成功率 = (单步准确率)^步骤数 │ │ +│ │ └─→ 10 步工作流通过线：≥80% │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**评估顺序**：API → 工具 → 安全 → 系统。每一层是下一层的前提。 + +--- + +## 九、治理组织关系图 + +``` + ┌──────────────────────┐ + │ Linux Foundation │ + │ 开源治理伞组织 │ + └──────────┬───────────┘ + │ + ┌────────────────┼────────────────┐ + ▼ ▼ ▼ + ┌────────────────┐ ┌────────────┐ ┌────────────────┐ + │ AAIF │ │ AGNTCY │ │ A2A Project │ + │ Agentic AI │ │ Agent │ │ Agent-to-Agent │ + │ Foundation │ │ 互联网 │ │ Protocol │ + │ │ │ │ │ │ + │ 创始: │ │ 75+ 公司 │ │ 创始: Google │ + │ Anthropic │ │ Cisco │ │ 150+ 组织 │ + │ OpenAI │ │ LangChain │ │ │ + │ Block │ │ Galileo │ │ │ + ├────────────────┤ └────────────┘ └────────────────┘ + │ 治理项目: │ + │ ├── MCP │ + │ ├── AGENTS.md │ ┌─────────────────────┐ + │ └── goose │ │ 独立标准组织 │ + └────────────────┘ ├─────────────────────┤ + │ CoSAI → MCP 安全 │ + │ OWASP → LLM/Agent │ + │ 安全 Top 10 │ + │ OpenAPI → API 描述 │ + │ Initiative 标准 │ + └─────────────────────┘ +``` + +--- + +## 十、时间线：从碎片到标准化 + +``` +2024 +│ +├── 09 ── Jeremy Howard 提出 llms.txt 规范 +│ +├── 11 ── Anthropic 发布 MCP (Model Context Protocol) +│ +│ +2025 +│ +├── 01 ── Matt Biilmann 命名 AX (Agent Experience) +│ +├── 04 ── Google 发布 A2A 协议 (Cloud Next) +│ +├── 07 ── A2A 捐赠给 Linux Foundation +│ +├── 08 ── AGENTS.md 标准发布 (OpenAI + 多方) +│ 60,000+ 仓库采纳 +│ +├── 11 ── MCP spec 更新 (服务端身份、异步操作) +│ Mastercard Agent Pay 全美上线 +│ Visa 完成数百笔 Agent 交易 +│ +├── 12 ── AAIF 成立 (Linux Foundation) +│ Anthropic 捐赠 MCP +│ Agent Skills 标准发布 +│ OWASP Top 10 for Agentic Applications +│ Meta 收购 Manus +│ +│ +2026 +│ +├── 01 ── CoSAI MCP 安全白皮书 +│ A2A 达到 RC 1.0 +│ Google 发布 Universal Commerce Protocol +│ +├── 02 ── Google 发布 WebMCP (Chrome Canary) +│ +├── 03 ── MCP Tool Annotations 博客发布 +│ Microsoft 发布端到端 Agent 安全指南 +│ +└── ── 当前位置 ── + + ┌──────────────────────────────────────────┐ + │ 从"各自为政"到"统一标准"用了不到 2 年 │ + │ 类比 HTTP 标准化花了 ~5 年 (1991-1996) │ + │ Agent 生态标准化的速度快了 2.5 倍 │ + └──────────────────────────────────────────┘ +``` + +--- + +## 十一、概念分类矩阵：按角色 × 关注层 + +``` + 你是谁？ + │ + ├── API/产品开发者 ──────────────────────────────┐ + │ "我要让 Agent 能用我的 API" │ + │ │ + │ 必须掌握: │ + │ ├── AX 10 原则 │ + │ ├── OpenAPI spec 完整度 │ + │ ├── llms.txt │ + │ ├── 错误响应格式 │ + │ ├── Idempotency │ + │ ├── Content Negotiation │ + │ ├── Postman 48 Checks │ + │ └── JSON-LD / Schema.org │ + │ │ + ├── MCP Server 开发者 ───────────────────────────┤ + │ "我要给 Agent 提供工具" │ + │ │ + │ 必须掌握: │ + │ ├── ACI (Agent-Computer Interface) │ + │ ├── Tool Design 7 子规约 │ + │ │ (命名/描述/inputSchema/outputSchema/ │ + │ │ 错误/注解/粒度) │ + │ ├── Outcome-Oriented 设计 │ + │ ├── Schema-First │ + │ ├── MCP 协议细节 │ + │ ├── SlowMist 安全清单 │ + │ └── 工具质量 10 项评分 │ + │ │ + ├── Agent 系统架构师 ────────────────────────────┤ + │ "我要构建多 Agent 系统" │ + │ │ + │ 必须掌握: │ + │ ├── A2A 协议 + Agent Card │ + │ ├── Agent Skills │ + │ ├── Least Agency (非仅 Least Privilege) │ + │ ├── 纵深防御五道防线 │ + │ ├── 级联幻觉 / 记忆投毒防御 │ + │ ├── 复合精度公式 │ + │ ├── Google 三支柱评估 │ + │ ├── KYA (Know Your Agent) │ + │ └── Token Exchange (RFC 8693) │ + │ │ + └── 安全工程师 ──────────────────────────────────┤ + "我要保证 Agent 系统安全" │ + │ + 必须掌握: │ + ├── 10 条不可协商安全约束 │ + ├── 8 类攻击向量 + 防御映射 │ + ├── CoSAI 白皮书 8 项建议 │ + ├── OWASP LLM/Agentic Top 10 │ + ├── SlowMist MCP 安全清单 │ + ├── Prompt 不是安全边界（铁律） │ + ├── Sandbox / MicroVM 隔离 │ + ├── Policy Engine (OPA/Cedar) │ + └── 不可篡改审计日志 │ + │ + ────────────────────────────────────────────────┘ +``` + +--- + +## 十二、一张图总结：Agent Friendly 的本质 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ │ +│ Agent Friendly 的本质 │ +│ │ +│ = 好工程实践 × 强制化程度 │ +│ │ +│ ┌────────────────────┐ ┌────────────────────┐ │ +│ │ 人类开发者时代 │ │ Agent 消费者时代 │ │ +│ ├────────────────────┤ ├────────────────────┤ │ +│ │ 好命名 → "建议" │ ──▶│ 好命名 → "必须" │ │ +│ │ 类型化 → "最好有" │ ──▶│ 类型化 → "必须" │ │ +│ │ 错误信息 → "方便" │ ──▶│ 错误信息 → "必须" │ │ +│ │ 文档 → "对人有帮助" │ ──▶│ 文档 → "对机器可解析"│ │ +│ │ 幂等性 → "好实践" │ ──▶│ 幂等性 → "必须" │ │ +│ │ 最小权限 → "安全建议"│ ──▶│ 最小权限 → "不可协商"│ │ +│ └────────────────────┘ └────────────────────┘ │ +│ │ +│ ────────────────────────────────────────────────── │ +│ │ +│ 每一个"新"标准都不是新发明: │ +│ │ +│ MCP ──────────── 借鉴了 ──→ LSP (Language Server Protocol) │ +│ llms.txt ──────── 借鉴了 ──→ robots.txt │ +│ Agent Card ────── 借鉴了 ──→ .well-known URI (RFC 5785) │ +│ AX ──────────── 借鉴了 ──→ DX (Developer Experience) │ +│ AGENTS.md ────── 借鉴了 ──→ README.md / CONTRIBUTING.md │ +│ A2A ──────────── 借鉴了 ──→ HTTP + Service Discovery │ +│ Tool Annotations ─ 借鉴了 ─→ HTTP Method Semantics │ +│ │ +│ ────────────────────────────────────────────────── │ +│ │ +│ Agent Friendly 不是革命，是好设计的自然演进。 │ +│ 人类容忍的模糊性，Agent 不能容忍。 │ +│ 当 Agent 成为主要消费者，"建议"变成了"必须"。 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 十三、完整画面：被调用方 + 构建方 + +``` + Agent Friendly 完整画面 +┌─────────────────────────────────────────────────────────────┐ +│ │ +│ 被调用方（你的系统） 构建方（Agent Harness） │ +│ Agent Friendly 规约 Harness Engineering │ +│ ══════════════════ ═══════════════════ │ +│ │ +│ "怎么让 Agent 用好 "怎么给 Agent 建好 │ +│ 你的系统" 运行环境" │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ §5 发现层 │ │ s05 知识加载 │ │ +│ │ llms.txt │◀──找到──▶ │ 两层按需加载 │ │ +│ │ Agent Card │ │ │ │ +│ ├──────────────┤ ├──────────────┤ │ +│ │ §2 工具设计 │ │ s02 工具调度 │ │ +│ │ Schema/描述 │◀──调用──▶ │ 调度映射+沙箱 │ │ +│ │ 7 子规约 │ │ │ │ +│ ├──────────────┤ ├──────────────┤ │ +│ │ §3 API 设计 │ │ s01 Agent Loop│ │ +│ │ 10 条 AX 原则 │◀──交互──▶ │ 30 行核心循环 │ │ +│ ├──────────────┤ ├──────────────┤ │ +│ │ §4 安全规约 │ │ s04/s12 隔离 │ │ +│ │ 10 条安全约束 │◀──保护──▶ │ Subagent + │ │ +│ │ │ │ Worktree │ │ +│ ├──────────────┤ ├──────────────┤ │ +│ │ §6 评估规约 │ │ 12 课渐进验证 │ │ +│ │ Postman 48 │ │ 3.6KB → 36KB │ │ +│ └──────────────┘ └──────────────┘ │ +│ │ │ │ +│ └───────────┬───────────────┘ │ +│ ▼ │ +│ ┌────────────────┐ │ +│ │ Agent 成功完成 │ │ +│ │ 用户的任务 │ │ +│ └────────────────┘ │ +│ │ +│ 共享哲学根基： │ +│ 1. 模型比你想的更聪明 → 给好 Schema，不预设工作流 │ +│ 2. 约束是最好的礼物 → NEVER 清单 > 功能列表 │ +│ 3. 好设计是透明的 → 你几乎忘记它的存在 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Harness 12 课与规约概念的逐项映射 + +``` +┌─────────────────────────────────┬────────────────────────────────┐ +│ Harness Engineering │ Agent Friendly 规约 │ +│ (构建方) │ (被调用方) │ +├─────────────────────────────────┼────────────────────────────────┤ +│ s01 Agent Loop │ — (规约不涉及 Agent 内部循环) │ +│ s02 Tool dispatch + safe_path │ §2 Tool Design + §4 Least Agency│ +│ s03 TodoWrite 一次一个 │ P2 约束>能力 │ +│ s04 Subagent 上下文隔离 │ §4 Sandbox / 隔离 │ +│ s05 Skill 两层加载 │ §5 发现层 (llms.txt 索引+全文) │ +│ s06 Context Compact │ — (Harness 独有：内部记忆管理) │ +│ s07 Task DAG 磁盘持久 │ Agent Skills 标准 │ +│ s08 Background tasks │ — (Harness 独有：异步执行管理) │ +│ s09 Team mailbox │ A2A 协议 (简化版) │ +│ s10 Shutdown/Plan protocols │ HITL + Agent 协商 │ +│ s11 Autonomous task claiming │ Agent Card 发现 (去中心化) │ +│ s12 Worktree isolation │ §4 Sandbox / MicroVM (轻量版) │ +│ mcp-builder skill │ §2 + §3 全部 (MCP Server 构建) │ +│ "Trust the model" (全局) │ P2 约束>能力 (同一哲学) │ +├─────────────────────────────────┼────────────────────────────────┤ +│ 独有领域：循环、上下文、持久化 │ 独有领域：Schema、发现、评分 │ +│ 关注动词：加载、隔离、持久化 │ 关注动词：暴露、描述、约束 │ +└─────────────────────────────────┴────────────────────────────────┘ +``` + +--- + +## 附录：五份文档的关系 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ │ +│ deep-research.md 本质：证据层 │ +│ 原始研究素材 "数据和来源在这里" │ +│ (289 行) │ +│ │ │ +│ │ 提炼出 │ +│ ▼ │ +│ glossary.md 本质：知识层 │ +│ 概念与名词解释 "每个概念是什么意思" │ +│ (1001 行, ~115 概念) │ +│ │ │ +│ │ 揭示关系 │ +│ ▼ │ +│ architecture.md 本质：结构层 │ +│ 概念关系与架构图 "概念之间如何连接" │ +│ (761 行, 13 张图) │ +│ │ │ +│ │ 转化为约束 │ +│ ▼ │ +│ development-spec.md 本质：规约层 │ +│ 开发规约 v1.0 "必须/禁止做什么" │ +│ (519 行, 25 NEVER) │ +│ │ │ +│ │ 补充构建方视角 │ +│ ▼ │ +│ harness-engineering.md 本质：实现层 │ +│ Harness Engineering 分析 "Agent 内部怎么运作" │ +│ (359 行, 12 课映射) │ +│ │ +│ 五层关系: 证据 → 知识 → 结构 → 约束 → 实现 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` diff --git a/00-inbox/2026-03-24-agent-friendly-deep-research.md b/00-inbox/2026-03-24-agent-friendly-deep-research.md new file mode 100644 index 0000000..3acb72d --- /dev/null +++ b/00-inbox/2026-03-24-agent-friendly-deep-research.md @@ -0,0 +1,289 @@ +--- +id: "2026-03-24-agent-friendly-deep-research" +title: "Agent Friendly 深度研究：让系统对 AI Agent 友好的设计范式" +slug: "agent-friendly-deep-research" +status: "inbox" +content_type: "article" +channels: ["wechat", "x"] +language: "zh-CN" +source_urls: + - "https://agentexperience.ax/" + - "https://llmstxt.org/" + - "https://agents.md/" + - "https://modelcontextprotocol.io/specification/2025-11-25" + - "https://a2a-protocol.org" + - "https://github.com/stefanbuck/ai-api-best-practices" + - "https://github.com/janwilmake/agent-friendly" + - "https://workos.com/blog/build-agent-friendly-products" + - "https://biilmann.blog/articles/introducing-ax/" + - "https://blogs.mulesoft.com/automation/api-design-for-agentic-ai/" + - "https://www.apideck.com/blog/api-design-principles-agentic-era" + - "https://refactoring.fm/p/how-to-design-apis-for-an-ai-world" + - "https://www.postman.com/ai/ai-ready-apis/" + - "https://arxiv.org/abs/2505.02279" + - "https://arxiv.org/abs/2504.16736" +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", "AX", "MCP", "A2A", "API-design", "agentic-AI"] +--- + +# Agent Friendly 深度研究报告 + +## 一、定义与演进 + +**Agent Friendly** = 让 AI Agent 能自主**发现、理解、调用、验证**你的系统，无需人类在旁翻译。 + +类比链： +``` +Mobile Friendly (2010s) → Developer Friendly / DX (2011) → Agent Friendly / AX (2025) + 网站适配手机 API 适配开发者 系统适配 AI Agent +``` + +**AX（Agent Experience）** 由 Netlify CEO **Matt Biilmann** 于 2025 年初正式命名，定位为 UX → DX 之后的第三代体验设计范式。 + +> "Your documentation is now your product's UI -- for agents." — WorkOS + +--- + +## 二、为什么现在重要？ + +| 数据点 | 来源 | +|--------|------| +| 89% 开发者日常使用 AI 工具，但仅 **24%** 为 Agent 设计 API | Postman 2025 | +| Cloudflare 2024 年首次报告自动化流量超过人类流量 | Cloudflare | +| RAG Agent 流量 2025 年初飙升 **49%** | Apideck | +| Gartner：2026 年底 **40%** 企业应用将嵌入 AI Agent | Gartner | +| Gartner：2028 年 **90%** B2B 采购由 Agent 代理，涉及 **$15T** | Gartner | +| AI 引荐流量转化率高 **31%**，单次访问收入高 **254%** | Adobe | +| Agentic AI 市场：$7B (2025) → **$236B (2034)** | 多方预测 | + +--- + +## 三、协议栈全景（The "Big Five"） + +``` +┌──────────────────────────────────────────────────────────────┐ +│ Agentic AI Foundation (AAIF) │ +│ Linux Foundation · Anthropic + OpenAI + Block │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ +│ │ llms.txt │ │ AGENTS.md │ │ Schema.org/JSON-LD│ │ +│ │ 文档发现层 │ │ 项目指令层 │ │ 结构化数据层 │ │ +│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │ +│ │ │ │ │ +│ ┌──────▼──────────────────────────────────────▼──────────┐ │ +│ │ MCP (Model Context Protocol) │ │ +│ │ Agent ←→ Tool 垂直连接 │ │ +│ │ Anthropic 创建，97M+ 月下载 │ │ +│ └──────────────────────┬────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────▼────────────────────────────────┐ │ +│ │ A2A (Agent-to-Agent Protocol) │ │ +│ │ Agent ←→ Agent 水平互操作 │ │ +│ │ Google 创建，150+ 组织支持，RC 1.0 │ │ +│ └───────────────────────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────┘ +``` + +### 协议对比 + +| 维度 | MCP | A2A | llms.txt | AGENTS.md | +|------|-----|-----|----------|-----------| +| **层** | Agent→Tool | Agent→Agent | 文档发现 | 项目指令 | +| **传输** | JSON-RPC, stdio | HTTP, SSE, gRPC | 静态文件 | 静态文件 | +| **发现** | 服务端定义 | Agent Card (.well-known) | /llms.txt | 仓库根目录 | +| **治理** | AAIF/Linux Foundation | Linux Foundation | 社区 | AAIF | +| **采纳量** | 10,000+ MCP Server | 150+ 组织 | 600+ 网站 | 60,000+ 仓库 | + +--- + +## 四、Agent Friendly 的 10 条设计原则 + +综合自 Apideck、Stefan Buck、O'Reilly、The New Stack、WorkOS 等多个权威来源。 + +| # | 原则 | 说明 | +|---|------|------| +| 1 | **Schema-First** | 完整 OpenAPI 3.0+ spec，每个端点/参数/响应都有富描述 | +| 2 | **可预测 & 一致** | 统一命名、一致 JSON 结构、类型化错误码 | +| 3 | **自描述** | 响应中包含足够上下文让 Agent 知道下一步做什么（HATEOAS） | +| 4 | **可组合** | 小而可链的端点，非巨型操作 | +| 5 | **程序化认证** | API Key / OAuth 2.0，无 CAPTCHA、无"联系销售" | +| 6 | **丰富错误响应** | 说明 WHY 失败 + HOW 修复 + is_retriable + retry_after | +| 7 | **机器可读文档** | llms.txt、Markdown-first、结构化元数据 | +| 8 | **逻辑下沉到 API** | 计算和验证在 API 端完成，LLM 只做语言理解 | +| 9 | **安全机制** | dry-run 模式、不可逆操作确认步、成本感知 | +| 10 | **内容协商** | 按 Accept header 返回 HTML（浏览器）或 Markdown/JSON（Agent） | + +--- + +## 五、标杆实践 + +### Stripe — 当前最完整的 Agent Friendly 生态 + +``` +┌─────────────────────────────────────────────┐ +│ Stripe Agent 生态 │ +├─────────────┬───────────────────────────────┤ +│ Agent Toolkit │ @stripe/agent-toolkit │ +│ (SDK 集成) │ OpenAI / LangChain / CrewAI │ +├─────────────┼───────────────────────────────┤ +│ Remote MCP │ mcp.stripe.com (OAuth) │ +├─────────────┼───────────────────────────────┤ +│ ACP 协议 │ Agentic Commerce Protocol │ +│ │ (与 OpenAI 联合，Apache 2.0) │ +├─────────────┼───────────────────────────────┤ +│ 集成基准 │ 首个生产级 Agent 集成评测 │ +│ │ "支付必须 100% 正确" │ +├─────────────┼───────────────────────────────┤ +│ llms.txt │ 含 instructions section │ +│ │ 主动纠正模型漂移 │ +└─────────────┴───────────────────────────────┘ +``` + +### 其他标杆 + +| 公司 | Agent Friendly 举措 | +|------|---------------------| +| **Shopify** | 双 MCP Server（Dev + Storefront）、Catalog API（数十亿商品）、Checkout Kit | +| **Twilio** | AI Assistants 框架、ConversationRelay（电话→LLM）、BYOLLM | +| **HubSpot** | 双 MCP 架构（远程 CRM + 本地开发） | +| **Clerk** | 全自动 Agent 认证流程（零人工介入） | +| **Visa** | Trusted Agent Protocol (TAP)，2025 年底完成数百笔 Agent 交易 | +| **Mastercard** | Agent Pay，2025 年 11 月全美上线 | + +--- + +## 六、文档发现层三剑客 + +| 标准 | 角色 | 格式 | 采纳 | +|------|------|------|------| +| **llms.txt** | "robots.txt for AI" — 网站摘要 | Markdown @ `/llms.txt` | 600+ 网站 | +| **llms-full.txt** | 完整文档单文件 | Markdown @ `/llms-full.txt` | Mintlify/Anthropic 联合 | +| **Agent Card** | Agent 能力声明 | JSON @ `/.well-known/agent-card.json` | A2A 生态 | + +**现实检查**：截至 2025 年 8 月，主要 LLM 爬虫（GPTBot、ClaudeBot）尚未主动读取 llms.txt。robots.txt 仍是实际控制机制。llms.txt 更多被 MCP/RAG 管道消费。 + +--- + +## 七、Agent SEO — 让 Agent 发现你 + +``` +传统 SEO Agent SEO (LLMO) +───────────────── ───────────────── +关键词密度 结构化数据 (JSON-LD) +反向链接 llms.txt + Agent Card +HTML Schema.org markup +Google SERP 排名 AI Overview 引用率 +点击率 (CTR) 零点击占比 (58.5%) +``` + +关键数据： +- 58.5% Google 搜索零点击 +- AI Overview 出现时，有机 CTR 下降 **61%+** +- Google（2025 年 5 月）官方推荐 JSON-LD +- SearchVIU 测试确认 ChatGPT/Claude/Perplexity/Gemini 均处理 Schema Markup + +--- + +## 八、中国生态：智能体友好 + +国内 MCP 采纳爆发式增长： +- 支付宝 MCP 服务（首个国内 AI 支付场景工具） +- MiniMax 多模态 MCP 服务 +- 多个"MCP 广场"（市场）上线 +- 讯飞星辰（StarAgent）支持 MCP Server 发布 + +国内实践共识的 4 层 Agent 架构： + +``` +┌─────────────────────────┐ +│ 认知层 (Cognitive) │ LLM 意图理解 + 任务分解 +├─────────────────────────┤ +│ 技能层 (Skill) │ 原子执行单元，明确输入/输出 Schema +├─────────────────────────┤ +│ 连接层 (Connection) │ MCP / 数据库 / SaaS / 企业内网 +├─────────────────────────┤ +│ 持续层 (Persistence) │ 状态、记忆、任务检查点管理 +└─────────────────────────┘ +``` + +--- + +## 九、学术论文 + +| 论文 | arXiv | 焦点 | +|------|-------|------| +| Survey of Agent Interoperability Protocols | 2505.02279 | MCP→ACP→A2A→ANP 分阶段采纳路线图 | +| A Survey of AI Agent Protocols | 2504.16736 | 类比早期碎片化 Internet | +| Multi-Agent Collaboration Mechanisms | 2501.06322 | 协作维度可扩展框架 | +| Orchestration of Multi-Agent Systems | 2601.13671 | 统一架构框架 | +| Evolution of AI Agent Registry Solutions | 2508.03095 | 5 种注册发现架构对比 | + +--- + +## 十、关键引用 + +> "Designing for AI agents is designing for the strictest, most literal and tireless user imaginable." — Apidog + +> "APIs weren't built for machines that think." — MuleSoft + +> "Your documentation is now your product's UI -- for agents." — WorkOS + +> "All the usual best practices in API design matter **more** when making an API agent-ready. LLMs are pattern-followers." — Apideck + +> "Gartner predicts that by 2026, over 30% of the growing demand for APIs will come not from human developers, but from AI agents." + +--- + +## 十一、核心资源链接 + +### 协议 & 标准 +- MCP 规范: https://modelcontextprotocol.io/specification/2025-11-25 +- A2A 协议: https://a2a-protocol.org +- llms.txt 规范: https://llmstxt.org +- AGENTS.md: https://agents.md +- AAIF: https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation +- Agentic Commerce Protocol (Stripe + OpenAI): https://stripe.com/blog/developing-an-open-standard-for-agentic-commerce + +### 设计指南 +- AX 官网: https://agentexperience.ax +- Stefan Buck AI API 最佳实践: https://github.com/stefanbuck/ai-api-best-practices +- Agent-Friendly Web 原则: https://github.com/janwilmake/agent-friendly +- AX 设计模式库 (26 patterns): https://agent-experience.dev +- Apideck 设计原则: https://www.apideck.com/blog/api-design-principles-agentic-era +- WorkOS "How to build agent-friendly products": https://workos.com/blog/build-agent-friendly-products +- Biilmann "Introducing AX": https://biilmann.blog/articles/introducing-ax/ +- MuleSoft "API Design for Agentic AI": https://blogs.mulesoft.com/automation/api-design-for-agentic-ai/ +- Refactoring.fm "APIs for an AI World": https://refactoring.fm/p/how-to-design-apis-for-an-ai-world +- O'Reilly "How to Write a Good Spec for AI Agents": https://www.oreilly.com/radar/how-to-write-a-good-spec-for-ai-agents/ + +### 评估工具 +- Postman API Agent Readiness (48 项检查): https://www.postman.com/ai/ai-ready-apis/ +- FourWeekMBA Readiness Checker: https://fourweekmba.com/api-agent-readiness-checker/ + +### 行业报告 +- Postman 2025 State of API: https://voyager.postman.com/doc/postman-state-of-the-api-report-2025.pdf + +### 关键人物 +- **Matt Biilmann** (Netlify CEO) — 命名 AX (Agent Experience) +- **Jeremy Howard** (Answer.AI) — 提出 llms.txt 规范 +- **janwilmake** — Agent-Friendly Web 原则 +- **Stefan Buck** — AI API 最佳实践 + +--- + +## 十二、写作角度备选 + +1. **"好设计的自然延伸"** — Agent Friendly 不是新概念，MCP 借鉴 LSP，llms.txt 借鉴 robots.txt，Agent Card 借鉴 .well-known，每个"新"标准都是已验证设计智慧的重组 +2. **"从 DX 到 AX"** — 开发者体验演进史，UX→DX→AX 三代范式对比 +3. **"API 的新用户不是人"** — 从 Postman 89% vs 24% 的数据切入，Agent 作为 API 第一消费者 +4. **"Agent Friendly = 约束 > 能力"** — 与 content-forge 项目设计哲学呼应，好的 Agent Friendly 设计是消除 Agent 需要猜测的一切 +5. **"协议战争"** — MCP vs A2A vs ACP，类比 HTTP 早期标准化历史 +6. **"中国智能体友好生态"** — 国内 MCP 广场爆发、4 层架构共识、安全挑战 diff --git a/00-inbox/2026-03-24-agent-friendly-development-spec.md b/00-inbox/2026-03-24-agent-friendly-development-spec.md new file mode 100644 index 0000000..6a95c41 --- /dev/null +++ b/00-inbox/2026-03-24-agent-friendly-development-spec.md @@ -0,0 +1,519 @@ +--- +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 状态可追踪 | diff --git a/00-inbox/2026-03-24-agent-friendly-glossary.md b/00-inbox/2026-03-24-agent-friendly-glossary.md new file mode 100644 index 0000000..56c8460 --- /dev/null +++ b/00-inbox/2026-03-24-agent-friendly-glossary.md @@ -0,0 +1,1001 @@ +--- +id: "2026-03-24-agent-friendly-glossary" +title: "Agent Friendly 概念与名词解释词典" +slug: "agent-friendly-glossary" +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://modelcontextprotocol.io/specification/2025-06-18/server/tools" + - "https://agentexperience.ax/" + - "https://llmstxt.org/" + - "https://agents.md/" + - "https://a2a-protocol.org" + - "https://github.com/shareAI-lab/learn-claude-code" +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", "glossary", "AX", "MCP", "A2A", "agentic-AI"] +--- + +# Agent Friendly 概念与名词解释词典 + +> 本词典按主题分组，每个词条包含：定义、核心要点、与其他概念的关系、出处。 + +--- + +## 一、核心范式 + +### Agent Friendly（智能体友好） + +**定义**：一种系统设计理念——让 AI Agent 能自主发现、理解、调用、验证你的系统，无需人类在旁翻译或适配。 + +**类比**：如同 "Mobile Friendly" 让网站适配手机，"Agent Friendly" 让数字基础设施适配 AI Agent 作为一等公民消费者。 + +**核心层面**： +- Agent-Friendly API：自描述、Schema-first、可预测响应、类型化错误 +- Agent-Friendly Documentation：机器可读文档（llms.txt、Markdown-first） +- Agent-Friendly Product：程序化认证、即时 onboarding、无 CAPTCHA 墙 +- Agent-Friendly Web：内容协商（同一 URL 按 user-agent 返回 HTML 或 Markdown/JSON） + +**关系**：Agent Friendly 是 AX 的实现手段；AX 是 Agent Friendly 的学科化表达。 + +--- + +### AX（Agent Experience，智能体体验） + +**定义**：Agent Experience 的缩写，由 Netlify CEO Matt Biilmann 于 2025 年初命名。指为 AI Agent 设计产品、API、文档的用户体验学科，与 UX（用户体验）和 DX（开发者体验）平行。 + +**演进链**： +``` +UX (User Experience, 1993, Don Norman) + → DX (Developer Experience, 2011, Jeremiah Lee Cohick) + → AX (Agent Experience, 2025, Matt Biilmann) +``` + +**三个核心维度**： +- **Context**（上下文）：Agent 能否理解你的站点/API 做什么？ +- **Access**（访问）：Agent 能否通过程序化方式认证和操作？ +- **Navigation**（导航）：Agent 能否通过机器可读路径在产品中导航？ + +**关键洞察**：AX 改善 DX，而非替代 DX。让 API 对 Agent 更友好的改进，同时让人类开发者受益。 + +**出处**：[agentexperience.ax](https://agentexperience.ax/)、[Matt Biilmann - Introducing AX](https://biilmann.blog/articles/introducing-ax/) + +--- + +### ACI（Agent-Computer Interface，智能体-计算机接口） + +**定义**：Anthropic 提出的概念，指 Agent 与外部工具/系统交互的界面设计。类比 HCI（Human-Computer Interface），强调 Agent 的工具接口设计需要与人类界面设计同等的投入和迭代。 + +**核心原则**： +- 投入与 HCI 同等精力设计 ACI +- 从模型视角思考："仅凭工具名和描述，是否显而易见该如何使用？如果不是，模型也会困惑。" +- 好的工具定义 = 给一个靠谱但字面理解一切的初级工程师写文档 +- 用 Claude 自身协作改进工具定义，比人工创建效果更好 + +**关系**：ACI 是 AX 在工具层的具体实现方法论。 + +**出处**：[Anthropic - Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) + +--- + +### LLMO（Large Language Model Optimization，大语言模型优化） + +**定义**：针对 AI 大语言模型（而非搜索引擎）优化内容的实践。目标是让你的内容被 LLM 正确理解、引用和推荐，类似于 SEO 针对 Google 的优化。 + +**也称为**：GEO（Generative Engine Optimization）、AIO（AI Optimization）、Agent SEO + +**关键区别**： +| 维度 | 传统 SEO | LLMO | +|------|---------|------| +| 优化对象 | Google 爬虫 | LLM / AI Agent | +| 核心手段 | 关键词、反向链接 | 结构化数据 (JSON-LD)、llms.txt | +| 成功指标 | SERP 排名、CTR | AI Overview 引用率、Agent 调用率 | +| 内容格式 | HTML | Markdown、JSON Schema | + +**数据**：58.5% Google 搜索已零点击；AI Overview 出现时有机 CTR 下降 61%+。 + +--- + +## 二、协议与标准 + +### MCP（Model Context Protocol，模型上下文协议） + +**定义**：由 Anthropic 于 2024 年 11 月创建的开放协议，标准化 AI Agent 与工具/数据源的连接方式。2025 年 12 月捐赠给 Linux Foundation AAIF。 + +**架构**：客户端-服务器模型，基于 JSON-RPC 2.0（受 LSP 启发）。 + +**三个原语**： +- **Tools**（工具）：模型控制的可调用函数，如 `search_documents`、`create_issue` +- **Resources**（资源）：应用控制的数据源，如文件、数据库记录 +- **Prompts**（提示）：用户控制的预定义提示模板 + +**采纳规模**：10,000+ 已发布 MCP Server；97M+ 月 SDK 下载；Claude、ChatGPT、Cursor、Gemini、VS Code、Copilot 均支持。 + +**定位**：**垂直连接**——Agent 到 Tool/Data 的标准通道。 + +**关系**：与 A2A 互补（MCP 管 Agent→Tool，A2A 管 Agent→Agent）。 + +**出处**：[modelcontextprotocol.io](https://modelcontextprotocol.io/) + +--- + +### A2A（Agent-to-Agent Protocol，智能体间协议） + +**定义**：Google 于 2025 年 4 月在 Cloud Next 发布的开放协议，标准化不同 Agent 之间的跨平台通信。2025 年 7 月捐赠给 Linux Foundation，2026 年 1 月达到 RC 1.0。 + +**架构**：基于 HTTP、SSE、JSON-RPC 的客户端-服务器模型，支持 gRPC（v0.3+）。 + +**关键概念**： +- **Agent Card**（智能体名片）：JSON 元数据文件，发布在 `/.well-known/agent-card.json`，描述 Agent 的名称、能力和端点 +- **Task**（任务）：跨 Agent 的工作单元，有可追踪的 ID 和生命周期 +- 支持多模态交互（包括音视频流） + +**定位**：**水平互操作**——Agent 到 Agent 的跨组织通信。 + +**支持者**：150+ 组织，包括 Salesforce、SAP、PayPal、Atlassian、IBM、Microsoft。 + +**实际应用**：Tyson Foods 和 Gordon Food Service 用于供应链 Agent 协作。 + +**出处**：[a2a-protocol.org](https://a2a-protocol.org) + +--- + +### AAIF（Agentic AI Foundation，智能体 AI 基金会） + +**定义**：2025 年 12 月在 Linux Foundation 下成立的开放治理组织，旨在统一 Agent 生态标准，防止供应商锁定和碎片化。 + +**创始成员**：Anthropic、OpenAI、Block（三方联合创立）。 +**白金会员**：AWS、Google、Microsoft、Bloomberg、Cloudflare。 + +**治理的三个创始项目**： +- **MCP**（Anthropic 捐赠）：Agent→Tool 连接 +- **AGENTS.md**（OpenAI 联合创建）：项目级 Agent 指令 +- **goose**（Block 捐赠）：开源本地优先 Agent 框架 + +**类比**：如同 W3C 之于 Web 标准，AAIF 之于 Agent 标准。 + +**出处**：[Linux Foundation AAIF 公告](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) + +--- + +### llms.txt + +**定义**：由 Jeremy Howard（Answer.AI 联合创始人）于 2024 年 9 月提出的标准，在网站根目录放置一个 `/llms.txt` 文件，为 LLM 提供优化的站点摘要。被称为"AI 版 robots.txt"。 + +**格式**：Markdown 文件，包含站点标题（H1）、结构化分区、链接及一句话描述。 + +**配套文件**： +- `/llms.txt`：轻量摘要 + 链接索引 +- `/llms-full.txt`：完整文档内容编译为单一 Markdown 文件（Mintlify + Anthropic 联合定义） + +**采纳**：600+ 网站，包括 Anthropic、Stripe、Perplexity、Cursor、Zapier、Cloudflare、Hugging Face。 + +**关键洞察**： +- AI Agent 访问 `llms-full.txt` 的频率是 `llms.txt` 的 **2 倍以上** +- Stripe 利用 llms.txt 的 instructions section 主动纠正模型漂移 +- 截至 2025 年 8 月，主要 LLM 爬虫（GPTBot、ClaudeBot）**尚未主动读取** llms.txt；更多被 MCP/RAG 管道消费 + +**出处**：[llmstxt.org](https://llmstxt.org/) + +--- + +### AGENTS.md + +**定义**：为编码 AI Agent 提供项目级指令的开放标准。纯 Markdown 文件，放置在仓库根目录。 + +**设计哲学**：极致简洁——单文件、纯 Markdown、工具无关、人类优先。 + +**采纳**：60,000+ 开源仓库；GitHub Copilot、Codex、Gemini CLI、Cursor、Devin、Factory、Jules、VS Code 均支持。 + +**优先级规则**：离编辑文件最近的 AGENTS.md 优先；用户的显式 prompt 覆盖一切。 + +**关系**：AGENTS.md 是通用标准；CLAUDE.md 是 Claude Code 专属的项目指令文件（功能类似但仅 Claude 识别）。 + +**类似物**： +| 文件 | 适用工具 | +|------|---------| +| `AGENTS.md` | 所有支持的 AI 编码工具（通用） | +| `CLAUDE.md` | Claude Code | +| `.cursorrules` / `.cursor/rules/*.mdc` | Cursor | +| `.github/copilot-instructions.md` | GitHub Copilot | +| `.windsurfrules` | Windsurf | + +**出处**：[agents.md](https://agents.md/) + +--- + +### Agent Card（智能体名片） + +**定义**：A2A 协议中的标准化 JSON 元数据文件，发布在 `/.well-known/agent-card.json`，描述一个 Agent 的身份、能力、技能和服务端点。 + +**功能**：让其他 Agent 能够**发现**并**理解**你的 Agent 能做什么，类似于 OpenAPI spec 描述 API 能力。 + +**字段示例**：名称、描述、能力列表、认证方式、端点 URL。 + +**意义**：第一个被 IANA 注册的 AI Agent 专属 `.well-known` 条目。 + +--- + +### Agent Skills（智能体技能） + +**定义**：Anthropic 于 2025 年 12 月提出的标准化可移植程序化知识格式。让 Agent 能够携带和共享结构化的操作知识（步骤、约束、NEVER 规则）。 + +**结构**：SKILL.md 文件包含——精确步骤、边缘情况处理、NEVER 列表、输入/输出规范。 + +**设计三原则**（Block）： +1. **Take away from the agent**：一致性关键行为写入脚本/模板/规则，不靠 LLM 推理 +2. **Let agent reason where it adds value**：解释、选择、对话是 Agent 的领地 +3. **Constitutional constraints**：SKILL.md 是契约——精确步骤 + 边缘情况 + NEVER 规则 + +**出处**：[The New Stack - Agent Skills](https://thenewstack.io/agent-skills-anthropics-next-bid-to-define-ai-standards/) + +--- + +### ACP（Agent Communication Protocol，智能体通信协议） + +**定义**：由 Cisco、LangChain、Galileo 联合推动的"Agent 互联网"协议。 + +**也称为**：AGNTCY 项目的核心协议之一。 + +**定位**：组织内部 Agent 协调（比 A2A 更偏内部场景）。 + +**状态**：规范阶段，75+ 公司参与。后期 IBM 的 ACP 实现也合并进入 A2A 生态。 + +--- + +### ANP（Agent Naming Protocol / Agent Network Protocol） + +**定义**：去中心化的 Agent 注册和发现协议，基于 DID（去中心化标识符）实现点对点 Agent 发现。 + +**定位**：开放互联网上的 Agent 发现（无中心注册机构）。 + +**类比**：如同 DNS 之于域名，ANP 之于 Agent 身份。 + +**状态**：早期规范阶段。 + +--- + +### Agentic Commerce Protocol（智能体商务协议） + +**定义**：Stripe 与 OpenAI 联合开发的开放规范，让 AI 平台能嵌入商务流程（搜索、选品、结账、支付）。 + +**关键机制**：Shared Payment Tokens (SPTs)——仅需一行代码变更即可实现 Agent 支付。 + +**许可**：Apache 2.0 开源。 + +**出处**：[Stripe Blog](https://stripe.com/blog/developing-an-open-standard-for-agentic-commerce) + +--- + +### WebMCP + +**定义**：Google 于 2026 年 2 月提出的协议，让 AI Agent 在浏览器中与网站进行结构化交互（而非模拟点击）。 + +**状态**：Chrome Canary 预览阶段。 + +--- + +### A2UI（Agent-to-User Interface，智能体到用户界面协议） + +**定义**：Google 开源（Apache 2.0）的协议，让 Agent 能跨信任边界发送富 UI 组件。Agent 发送声明式组件描述，客户端用原生 widget 渲染。 + +**解决问题**：Agent 需要产生可视化输出，但直接执行渲染代码有安全风险。 + +**出处**：[a2ui.org](https://a2ui.org/) + +--- + +### x402 + +**定义**：复活 HTTP 402 "Payment Required" 状态码的协议，用于 Agent 到 API 的实时微支付。 + +**场景**：Agent 调用付费 API 时，API 返回 402 + 支付指令，Agent 自动完成支付后重试请求。 + +--- + +## 三、工具与 Schema 概念 + +### Tool（工具） + +**定义（MCP 语境）**：MCP 服务器暴露的可调用函数，由模型控制调用。每个 Tool 有 name、description、inputSchema，可选 outputSchema 和 annotations。 + +**设计核心**：一个 Tool = 一个用户目标 = 一个风险级别。 + +**与 Function Calling 的关系**：Tool 是 MCP 协议内的术语；Function Calling 是 OpenAI/Anthropic API 层的术语。本质相同——让 LLM 调用外部函数。 + +--- + +### Function Calling（函数调用） + +**定义**：LLM API 提供的能力，让模型在对话中识别何时需要调用外部函数，并生成结构化的函数调用参数。 + +**工作流**： +``` +用户提问 → LLM 判断需要调用函数 → 生成 {name, arguments} JSON +→ 客户端执行函数 → 结果返回 LLM → LLM 整合回答 +``` + +**提供商**：OpenAI（function_call / tool_choice）、Anthropic（tool_use）、Google（function_calling）。 + +--- + +### inputSchema / outputSchema + +**定义（MCP）**：Tool 的输入和输出数据结构定义，遵循 JSON Schema 规范。 + +**inputSchema 规则**： +- 必须是 `"type": "object"` 的 JSON Schema +- 扁平化（顶层原语，禁止 3 层+嵌套） +- 所有字段列入 required（可选字段用 `["string", "null"]`） +- `additionalProperties: false` +- 有限值域用 enum + +**outputSchema 规则**（MCP spec 2025-06-18+）： +- 返回 `structuredContent`（类型化 JSON）+ `TextContent`（向后兼容文本） +- 只返回高信号字段，非全量数据 + +--- + +### Tool Annotations（工具注解） + +**定义（MCP spec 2025-03-26+）**：附加在 Tool 上的元数据提示，帮助客户端做 UI/安全决策。 + +| 注解 | 含义 | 默认值 | +|------|------|--------| +| `readOnlyHint` | 不修改环境（读操作） | false | +| `destructiveHint` | 可能破坏数据（删除操作） | true | +| `idempotentHint` | 重复调用结果相同 | false | +| `openWorldHint` | 与外部实体交互 | true | + +**关键警告**：注解是**提示**（hints），不是安全保证。客户端不得仅基于注解做安全关键决策。 + +--- + +### OpenAPI / Swagger + +**定义**：描述 RESTful API 的标准规范（当前版本 3.1）。定义端点、参数、请求/响应 Schema、认证方式等。 + +**与 Agent 的关系**：OpenAPI spec 是 Agent 理解 API 的基础"地图"。Agent 通过解析 OpenAPI spec 来选择端点、构造请求、解析响应。 + +**Agent 要求**： +- 每个操作必须有 `operationId`（Critical） +- 每个操作必须有 `summary` + `description` +- 参数必须有 type + description + format +- 错误响应必须有 Schema 定义 + +--- + +### JSON Schema + +**定义**：描述 JSON 数据结构的标准（当前 Draft 2020-12）。定义字段类型、约束、必填性、枚举值等。 + +**在 Agent 生态中的角色**： +- MCP Tool 的 inputSchema/outputSchema 基于 JSON Schema +- OpenAI Function Calling 的参数定义基于 JSON Schema +- Agent 通过 JSON Schema 验证输入/输出，减少幻觉 + +--- + +### JSON-LD（JSON for Linking Data） + +**定义**：在 JSON 中嵌入语义化链接数据的 W3C 标准。用 `@context` 和 `@type` 将 JSON 数据连接到 Schema.org 等词汇表。 + +**与 Agent 的关系**： +- Google（2025 年 5 月）官方推荐 JSON-LD 作为 AI 优化内容的格式 +- SearchVIU 测试确认 ChatGPT、Claude、Perplexity、Gemini 均处理 JSON-LD +- Agent 通过 JSON-LD 理解实体关系（作者、发布者、日期、权威性信号） + +**常用 Schema 类型**：FAQPage、HowTo、Product、Review、Article、Organization。 + +--- + +### Schema.org + +**定义**：Google、Microsoft、Yahoo、Yandex 联合创建的结构化数据词汇表。为网页内容提供标准化的语义标注。 + +**与 Agent 的关系**：Schema.org 标记让 Agent 能理解网页中实体的类型和关系，而非仅解析文本。 + +--- + +### Arazzo + +**定义**：OpenAPI Initiative 推出的标准，定义 API 操作的序列（workflow）。不同于 OpenAPI 描述单个端点，Arazzo 描述多个端点如何组合成完整工作流。 + +**与 Agent 的关系**：Agent 执行多步任务时，Arazzo 提供"路线图"——先调什么、再调什么、用什么条件分支。 + +--- + +### HATEOAS（Hypermedia as the Engine of Application State） + +**定义**：REST 架构约束，要求 API 响应中包含导航链接，告诉客户端下一步可以做什么。 + +**与 Agent 的关系**：HATEOAS 式响应减少 Agent 幻觉——不需要猜测下一步该调什么接口，响应本身就告诉它。 + +**示例**： +```json +{ + "order_id": "12345", + "status": "pending", + "_links": { + "cancel": "/orders/12345/cancel", + "pay": "/orders/12345/pay" + } +} +``` + +--- + +## 四、安全概念 + +### Least Privilege（最小权限） + +**定义**：只授予完成任务所需的最小权限集合。安全基础原则。 + +**在 Agent 语境中**：Agent 只获得当前任务需要的工具、数据和操作权限。 + +--- + +### Least Agency（最小代理权） + +**定义**：比 Least Privilege 更进一步的约束。不仅限制"能访问什么"，还限制"能做什么动作"和"做多少次"。 + +**为什么需要**：一个拥有 `email:send` 权限的 Agent 技术上可以给通讯录每个人发邮件。Least Privilege 允许这么做（有权限），Least Agency 不允许（超出代理范围）。 + +**实现**：通过集中化策略引擎（OPA/Cedar/Oso）在每次特权操作时检查。 + +**出处**：OWASP LLM06 (Excessive Agency) + +--- + +### KYA（Know Your Agent，了解你的智能体） + +**定义**：类比金融领域的 KYC（Know Your Customer），KYA 是识别和验证 AI Agent 身份的框架。 + +**三个问题**： +1. **Who is this agent?**（身份） +2. **Who controls it?**（权限方） +3. **Can it be trusted?**（信誉） + +**实现**：密码学签名、数字证书、Agent 身份注册。 + +**行业动态**：78% 金融机构预计 AI 购物 Agent 将带来欺诈风险上升。 + +**出处**：[Sumsub](https://sumsub.com/blog/know-your-agent/)、[AgentFacts KYA Standard](https://agentfacts.org/kya/) + +--- + +### Prompt Injection（提示注入） + +**定义**：通过精心构造的输入文本，覆盖或绕过 LLM 的系统指令，使其执行非预期行为。Agent 安全的头号威胁。 + +**两种形式**： +- **直接注入**：用户输入中包含 "ignore previous instructions" +- **间接注入**：Agent 检索的外部数据（网页、邮件、文档）中嵌入恶意指令 + +**防御原则**：Prompt 不是安全边界。危险能力通过策略/allowlist 移除，而非通过 prompt 禁止。 + +--- + +### Tool Poisoning（工具投毒） + +**定义**：攻击者通过操纵 MCP Tool 的元数据（name、description、parameter schema）或输出内容，引导 LLM 执行恶意操作。 + +**攻击方式**： +- 在工具描述中嵌入隐藏 prompt 指令 +- 在工具返回值中注入影响后续推理的内容 +- 修改工具定义后重新部署（rug pull） + +**防御**：MCP 网关层扫描所有工具元数据；版本锁定 + 代码签名。 + +--- + +### Schema Poisoning（Schema 投毒） + +**定义**：操纵工具的 JSON Schema 字段（如描述、默认值、示例）来影响 LLM 的工具选择和参数生成。 + +--- + +### Cascading Hallucination（级联幻觉） + +**定义**：多 Agent 系统中，一个 Agent 的幻觉输出被下游 Agent 当作事实处理，在链路中逐级放大。 + +**示例**：Agent A 幻觉出一个不存在的 SKU → Agent B 查询价格 → Agent C 检查库存 → Agent D 生成订单——全部基于虚假数据。 + +**防御**：每个 Agent 独立验证输入；不信任上游 Agent 的输出。 + +--- + +### Memory Poisoning（记忆投毒） + +**定义**：污染 Agent 的共享记忆/上下文存储，影响所有后续决策。 + +**数据**：Galileo AI 研究显示，初始记忆投毒后 4 小时内 87% 的下游决策受到影响。 + +**防御**：共享上下文使用不可变存储 + 密码学验证。 + +--- + +### Slopsquatting + +**定义**：利用 LLM 幻觉出不存在的软件包名这一特性，在 npm/PyPI 等包管理平台注册这些虚假包名，嵌入恶意代码。 + +**数据**：一项 2.23M 样本研究发现 LLM 幻觉包名的比率高达 19.7%。 + +**防御**：所有依赖锁定版本 + hash 校验。 + +--- + +### MPMA（MCP Preference Manipulation Attack，MCP 偏好操纵攻击） + +**定义**：攻击者改变 Agent 排序和选择工具的方式，使其优先使用恶意工具或绕过安全工具。 + +**防御**：建立工具选择行为基线，监控偏离。 + +--- + +### Circuit Breaker（熔断器） + +**定义**：借鉴电路熔断的软件设计模式。当连续失败达到阈值时自动"断开"（停止调用），周期性探测恢复。 + +**在 Agent 中的应用**：防止 Agent 在工具失败时陷入无限重试循环。N 次连续失败后自动熔断，避免资源浪费。 + +--- + +### HITL（Human-in-the-Loop，人在环路中） + +**定义**：在 Agent 自动执行流程中保留人类审批/确认节点。对于不可逆或高影响操作是强制要求。 + +**MCP 规范原文**："For trust & safety and security, there SHOULD always be a human in the loop with the ability to deny tool invocations."——业界共识：将 SHOULD 视为 MUST。 + +--- + +### Dry-run（干跑/预演） + +**定义**：执行操作的所有步骤但不产生实际副作用。用于让 Agent（或人类）在提交前预览操作结果。 + +**实现**：API 提供 `?dry_run=true` 参数；返回"如果真正执行会发生什么"的结果。 + +--- + +### Intent Preview（意图预览） + +**定义**：在 Agent 执行多步或破坏性操作前，以人类可读的方式展示计划执行的所有步骤。 + +**包含**： +- 每一步的动作摘要 +- 每步的可逆性标记 +- 人类可编辑/取消的能力 +- 永不自动消失 + +--- + +### Token Exchange（令牌交换，RFC 8693） + +**定义**：OAuth 2.0 扩展，允许将一个高权限 token 交换为一个范围更小、时间更短的 token。 + +**在 Agent 中的应用**：人类用户的全权限 token 不直接传给 Agent，而是通过 Token Exchange 签发仅限特定任务、特定时间的受限 token。 + +--- + +## 五、评估框架 + +### Postman 8 Pillars / 48 Checks（Postman 八支柱 / 48 项检查） + +**定义**：Postman 开发的 API Agent 就绪度评估框架。对任何 OpenAPI spec 执行 48 项检查，产生 0-100 分。 + +**八个支柱**： +1. **META**（元数据）：operationId、summary、description +2. **ERR**（错误）：4xx/5xx 定义、错误 Schema、429 定义 +3. **INTRO**（内省）：参数类型、required 标记、枚举、示例 +4. **NAME**（命名）：一致大小写、RESTful 路径、HTTP 语义 +5. **PRED**（可预测性）：响应 Schema、分页、日期格式 +6. **DOC**（文档）：认证、频率限制、API 概述 +7. **PERF**（性能）：频率限制头、缓存头、批量端点 +8. **DISC**（发现）：OpenAPI 版本、Server URL、多环境 + +**通过阈值**：≥ 70 分且 8 项 Critical 全部通过。 + +**出处**：[Postman AI-Ready APIs](https://www.postman.com/ai/ai-ready-apis/) + +--- + +### SlowMist MCP Security Checklist（慢雾 MCP 安全清单） + +**定义**：慢雾安全团队开发的 MCP 安全检查清单，涵盖 ~90+ 检查项。 + +**六大类**：MCP Server 安全、MCP Client/Host 安全、LLM 适配安全、多 MCP 场景、加密特定、自评工具。 + +**优先级**：High（必须实现）/ Medium（强烈推荐）/ Low（推荐）。 + +**出处**：[github.com/slowmist/MCP-Security-Checklist](https://github.com/slowmist/MCP-Security-Checklist) + +--- + +### CoSAI MCP Security Whitepaper（CoSAI MCP 安全白皮书） + +**定义**：Coalition for Secure AI（安全 AI 联盟）于 2026 年 1 月发布的 MCP 安全白皮书。识别 12 类威胁、~40 个具体威胁，提出 8 项优先建议。 + +**八项优先建议**：端到端 Agent 身份追踪、最小权限、输入消毒（严格 allowlist）、所有 LLM/MCP 输出视为不可信、沙箱隔离 MCP Server、传输保护（mTLS）、敏感操作 HITL、供应链控制（代码签名 + 依赖锁定）。 + +**出处**：[CoSAI GitHub](https://github.com/cosai-oasis/ws4-secure-design-agentic-systems/blob/main/model-context-protocol-security.md) + +--- + +### OWASP Top 10 for LLM Applications + +**定义**：OWASP 针对 LLM 应用的十大安全风险清单（2025 版）。 + +**Agent 相关重点**： +- **LLM01 Prompt Injection**：提示注入 +- **LLM06 Excessive Agency**：过度代理权（三个根因：过度功能、过度权限、过度自治） +- **LLM10 Unbounded Consumption**：无限制资源消耗 + +**扩展**：2025 年 12 月另发布了 **OWASP Top 10 for Agentic Applications**（专门针对 Agent 系统）。 + +--- + +### Google Cloud 三支柱评估 + +**定义**：Google Cloud 提出的 Agent 系统评估方法论。 + +| 支柱 | 测试类型 | 测什么 | +|------|---------|--------| +| 最终输出 | 集成测试 | 任务完成率、正确性、事实基础 | +| 决策过程 | 单元测试 | 工具选择准确率、推理逻辑 | +| 韧性 | 压力测试 | 优雅降级、错误恢复、对抗鲁棒性 | + +**评分**：A / B / C / F + +--- + +### 复合精度公式 + +**定义**：多步 Agent 工作流的端到端成功率计算公式。 + +``` +端到端成功率 = (单步准确率) ^ 步骤数 +``` + +**含义**：95% 单步准确率的 Agent 在 10 步工作流中只有 60% 成功率。每一个工具设计决策都在影响单步准确率；更少的步骤 = 指数级更高的可靠性。 + +--- + +## 六、设计概念 + +### Schema-First（Schema 优先） + +**定义**：先定义数据契约（Schema），再实现业务逻辑。Schema 同时充当文档、验证规则和测试基准。 + +**在 Agent 语境中**：Agent 通过 Schema 理解如何调用你的系统。没有 Schema = Agent 只能猜测。 + +**关系**：与 content-forge 的 "Frontmatter-First" 原则同构。 + +--- + +### Content Negotiation（内容协商） + +**定义**：HTTP 机制，客户端通过 `Accept` header 告知服务器期望的响应格式，服务器返回对应格式。 + +**Agent Friendly 应用**： +- 浏览器请求 → 返回 HTML（人类可读） +- Agent 请求 → 返回 Markdown 或 JSON（机器可读） +- 通过 User-Agent 或 Accept header 区分 + +--- + +### Idempotency（幂等性） + +**定义**：同一操作执行多次，结果与执行一次相同。 + +**为什么对 Agent 关键**：Agent 在不确定时会重试。网络可能中断。没有幂等性，重试会导致重复状态变更（重复创建订单、重复发送邮件）。 + +**示例**： +- 幂等：`DELETE /file/123`（删除已删除的文件是无操作） +- 非幂等：`POST /send-email`（每次调用都发一封新邮件） + +**实现**：客户端生成 Idempotency Key，服务端去重。 + +--- + +### Progressive Autonomy（渐进式自治） + +**定义**：Agent 从最低权限/最多人工确认开始，随着用户建立信任，逐步增加自动化程度。 + +**原则**：每个动作默认可逆；高风险操作永远需要确认。 + +--- + +### Graceful Degradation（优雅降级） + +**定义**：当工具/服务不可用或 Agent 遇到错误时，系统有序地降低功能级别（而非崩溃或幻觉）。 + +**Agent 应用**： +- 预算耗尽 → 降级到更便宜的模型 +- 工具超时 → 返回缓存结果或明确告知失败 +- 外部服务不可用 → 建议替代操作路径 + +--- + +### Outcome-Oriented Tool（面向结果的工具） + +**定义**：工具设计围绕用户最终目标，而非 API 端点的 1:1 映射。 + +**示例**： +- 面向端点：`get_customer_by_email` → `list_customer_orders` → `get_order_status`（3 次调用） +- 面向结果：`track_order(email)`（1 次调用，内部完成 3 步） + +**Block 经验**：Linear MCP 从 30+ 工具重建三次，最终缩减到 2 个。 + +--- + +### Task-Oriented vs Entity-Oriented + +**定义**：两种工具设计哲学。 + +- **Entity-Oriented**（实体导向）：CRUD 操作映射到数据实体——`create_user`、`get_user`、`update_user`、`delete_user` +- **Task-Oriented**（任务导向）：映射到用户实际想完成的任务——`onboard_new_employee`、`schedule_meeting`、`track_order` + +**Agent 偏好**：Task-Oriented 减少链式调用步骤，提高端到端成功率。 + +--- + +## 七、基础设施概念 + +### MCP Server + +**定义**：实现 MCP 协议的服务端程序，暴露 Tools、Resources、Prompts 供 Agent 使用。 + +**类比**：如同 Web Server 服务网页，MCP Server 服务 Agent 工具。 + +**运行模式**： +- **stdio**：通过标准输入/输出通信（本地进程） +- **HTTP + SSE**：通过 HTTP 通信（远程/云端） + +--- + +### MCP Client / MCP Host + +**定义**： +- **MCP Client**：Agent 侧的 MCP 协议实现，负责连接 MCP Server、调用工具 +- **MCP Host**：运行 MCP Client 的应用（如 Claude Desktop、VS Code、Cursor） + +**关系**：Host 包含 Client；Client 连接 Server。 + +--- + +### Agent Gateway（智能体网关） + +**定义**：Agent 与外部工具/API 之间的中间层，集中处理认证、授权、流量控制、安全扫描、审计。 + +**功能**： +- MCP 元数据扫描（检测工具投毒） +- 请求级鉴权（策略引擎集成） +- 流量限制和预算执行 +- 审计日志集中收集 + +**类比**：如同 API Gateway 之于微服务，Agent Gateway 之于 Agent 工具调用。 + +--- + +### Sandbox / MicroVM + +**定义**：隔离执行环境，限制 Agent/代码的系统访问能力。 + +**隔离级别**（从弱到强）： +1. 进程隔离（最弱） +2. 容器（Docker/gVisor）——不足以作为安全边界 +3. **MicroVM**（Firecracker/Kata）——推荐 +4. 完全虚拟化 + +**Agent 规则**：每个 MCP Server 应运行在独立隔离上下文中。合并多个 Server（如 Git + Filesystem）会创建"有毒组合"。 + +--- + +### Policy Engine（策略引擎） + +**定义**：外部化的授权决策系统，将权限规则从应用代码中解耦。 + +**主流工具**： +- **OPA**（Open Policy Agent）：通用策略引擎，Rego 语言 +- **Cedar**（AWS）：类似 IAM 策略的声明式语言 +- **Oso**：嵌入式授权引擎 + +**在 Agent 中的角色**：每次工具调用时，策略引擎实时判断"这个 Agent 在这个上下文下能否执行这个操作"。 + +--- + +## 八、Harness Engineering 概念 + +### Harness（驾驶舱 / 运行环境） + +**定义**：Agent（模型）运行所需的一切外围代码和基础设施。模型是司机，Harness 是车辆。 + +**公式**： +``` +Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions +``` + +**核心原则**：模型决定，Harness 执行。模型推理，Harness 提供上下文。好的 Harness 代码是"几乎无聊的"——简单循环、清晰工具定义、干净的上下文管理。 + +**来源**：[shareAI-lab/learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) + +--- + +### Harness Engineering（驾驶舱工程） + +**定义**：构建 Agent 运行环境的工程学科。与 Agent Friendly（被调用方视角）互补——Harness Engineering 是构建方视角。 + +**核心工作**： +- 实现工具（给 Agent 手） +- 策划知识（给 Agent 专业领域） +- 管理上下文（给 Agent 清晰记忆） +- 控制权限（给 Agent 边界） +- 采集 Task-Process 数据（给未来模型训练信号） + +**关键心智转换**："我不是在写智能。我是在构建智能栖息的世界。" + +--- + +### Agent Loop（智能体循环） + +**定义**：Agent 运行的核心循环——调用 LLM、检查是否需要工具调用、执行工具、将结果返回 LLM、重复。 + +**最小实现**：~30 行 Python，`while True` + `stop_reason != "tool_use"` 作为退出条件。 + +**设计不变量**：所有后续机制（规划、压缩、团队）叠加在循环**周围**，循环本身从不改变。 + +**Agent-Friendly 关键**：模型决定何时停止，代码永不强制决策。 + +--- + +### Tool Dispatch Map（工具调度映射） + +**定义**：`{tool_name: handler_function}` 的字典/映射，Harness 通过它将 LLM 的工具调用请求路由到正确的处理函数。 + +**意义**：添加新工具 = 添加一个 handler + Schema，核心循环无需改变。 + +**关系**：Dispatch Map 是构建方的概念；对应被调用方的 MCP Tool 定义和 OpenAPI operationId。 + +--- + +### Context Compact / Compression（上下文压缩） + +**定义**：管理 Agent 上下文窗口的三层策略，防止长会话中记忆过载。 + +**三层**： +1. **微压缩**（每轮）：替换旧 tool_result 为占位符 +2. **自动压缩**（>50K token）：完整记录存磁盘，LLM 生成摘要 +3. **手动压缩**：模型主动调用 compact 工具 + +**关键**：信息不丢失，只是从活跃上下文移到磁盘。模型可以随时触发手动压缩。 + +**独有领域**：这是 Harness Engineering 独有概念，Agent Friendly 规约不涉及（规约关注被调用方接口，不管 Agent 内部记忆）。 + +--- + +### Subagent（子智能体） + +**定义**：从主 Agent 分叉出的一次性子 Agent，获得空白 messages 上下文，执行完后只返回摘要文本。所有中间消息丢弃。 + +**与 Agent Teams 的区别**：Subagent 是一次性的（执行完即消失）；Team Agent 是持久化的（跨多轮工作）。 + +**关键约束**：子 Agent 不能再生子 Agent（禁止递归）。 + +**对应规约概念**：§4 安全 / Sandbox 隔离——上下文隔离是一种轻量级沙箱。 + +--- + +### Task DAG（任务有向无环图） + +**定义**：磁盘持久化的任务依赖图。每个任务是一个 JSON 文件，包含 `blockedBy`/`blocks` 依赖关系。完成一个任务自动解锁其依赖者。 + +**回答三个问题**：什么能做？什么被阻塞？什么已完成？ + +**意义**：任务图是所有后续机制（团队、自治）的协调骨架。跨会话持久，不受上下文压缩影响。 + +--- + +### Agent Teams（智能体团队） + +**定义**：多个持久化 Agent 通过 JSONL 邮箱通信，各自运行完整 Agent Loop。每个 Agent 有名字、角色和状态生命周期（WORKING↔IDLE↔SHUTDOWN）。 + +**与 A2A 的关系**：Team mailbox 是 A2A 协议的简化版——同一进程内的 Agent 间通信，而非跨组织通信。 + +--- + +### Autonomous Task Claiming（自治任务领取） + +**定义**：Agent 在 IDLE 状态时自动轮询任务板（5 秒间隔），领取未被认领的、未被阻塞的任务。无需领导者分配。 + +**关键机制**：60 秒空闲无任务 → 自动关闭。身份重注入——上下文压缩后如果消息 ≤ 3 条，自动重新注入 Agent 身份信息。 + +**对应规约概念**：Agent Card 发现 + 去中心化自组织。 + +--- + +### Worktree Isolation（工作树隔离） + +**定义**：每个任务获得独立的 Git worktree（工作树），通过 Task ID 绑定。两个平面分离：控制面（`.tasks/`，做什么）和执行面（`.worktrees/`，在哪做）。 + +**对应规约概念**：§4 Sandbox / MicroVM 的轻量级版本——目录级别的隔离而非进程/VM 级别。 + +--- + +### Nag Reminder（催促提醒） + +**定义**：Harness 在 Agent 连续 3 轮未更新 TodoWrite 时自动注入的提醒消息，督促模型回到计划轨道。 + +**设计思想**：不干预决策，只提醒纪律。约束聚焦，非限制。 + +--- + +### Identity Re-injection（身份重注入） + +**定义**：上下文压缩后，如果 Agent 的消息数量 ≤ 3 条，自动重新注入 Agent 身份信息块（名字、角色、职责）。 + +**解决问题**：压缩后 Agent 可能"忘记自己是谁"。身份重注入确保 Agent 保持自我意识。 + +--- + +### Task-Process Data（任务-过程数据） + +**定义**：Agent 在 Harness 中执行任务时产生的感知-推理-行动序列数据。这些数据是训练下一代 Agent 模型的原始材料。 + +**意义**：Harness 不仅服务当前 Agent，还为未来 Agent 改进提供训练信号。 + +--- + +## 九、关键人物 + +| 人物 | 角色 | 贡献 | +|------|------|------| +| **Matt Biilmann** | Netlify CEO | 命名 AX (Agent Experience)，推动 AX 作为设计学科 | +| **Jeremy Howard** | Answer.AI 联合创始人 | 提出 llms.txt 规范 | +| **janwilmake** | 开发者 | 创建 Agent-Friendly Web 原则仓库 | +| **Stefan Buck** | 开发者 | 创建 AI API Best Practices 仓库 | +| **Phil Schmid** | Hugging Face → 独立 | MCP 最佳实践 6 条规则 | +| **Simon Willison** | Django 联合创始人 | MCP 安全（Prompt Injection）深度分析 | +| **Dario Amodei / Anthropic** | Anthropic CEO | 推动 MCP 标准 + AAIF 成立 | + +--- + +## 九、行业组织 + +| 组织 | 定位 | 成员 | +|------|------|------| +| **AAIF** | Agent 标准治理（Linux Foundation） | Anthropic, OpenAI, Block, AWS, Google, Microsoft | +| **CoSAI** | 安全 AI 联盟 | 多方联合，发布 MCP 安全白皮书 | +| **OWASP** | Web/应用安全标准 | 社区驱动，发布 LLM/Agentic Top 10 | +| **AGNTCY** | "Agent 互联网"生态 | 75+ 公司，Linux Foundation | +| **OpenAPI Initiative** | API 描述标准 | Google, Microsoft, IBM 等 | + +--- + +## 十、市场数据速查 + +| 指标 | 数值 | 来源 | +|------|------|------| +| 开发者日常使用 AI 工具 | 89% | Postman 2025 | +| 为 Agent 设计 API 的比例 | 24% | Postman 2025 | +| 自动化流量超过人类流量 | 2024 年首次 | Cloudflare | +| RAG Agent 流量增长 | 49% (2025 Q1) | Apideck | +| AI 引荐流量转化率提升 | +31% | Adobe | +| AI 引荐单次访问收入提升 | +254% | Adobe | +| AI 零售支出 | $20.9B (2026) | eMarketer | +| Agentic AI 市场 | $7B → $236B (2025→2034) | 多方 | +| B2B 采购 Agent 代理比例 | 90% by 2028 | Gartner | +| B2B Agent 交易规模 | $15T by 2028 | Gartner | +| 企业应用嵌入 Agent | 40% by 2026 | Gartner | +| 组织有 Agent 在生产 | 11% (2025) | Deloitte | +| Agent 项目失败率预测 | 40%+ by 2027 | Gartner | +| Google 搜索零点击比例 | 58.5% | SEM 研究 | +| AI Overview 出现时 CTR 下降 | 61%+ | 行业测试 | diff --git a/00-inbox/2026-03-24-harness-engineering-analysis.md b/00-inbox/2026-03-24-harness-engineering-analysis.md new file mode 100644 index 0000000..7372434 --- /dev/null +++ b/00-inbox/2026-03-24-harness-engineering-analysis.md @@ -0,0 +1,359 @@ +--- +id: "2026-03-24-harness-engineering-analysis" +title: "Harness Engineering 分析 — learn-claude-code 仓库逆向解读" +slug: "harness-engineering-analysis" +status: "inbox" +content_type: "article" +channels: ["wechat", "x"] +language: "zh-CN" +source_urls: + - "https://github.com/shareAI-lab/learn-claude-code" +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: ["harness-engineering", "agent-friendly", "claude-code", "agent-loop", "MCP"] +--- + +# Harness Engineering 分析 + +> 来源仓库：[shareAI-lab/learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) +> 定位：将 Claude Code 架构逆向工程为 12 课的 Harness Engineering 教程 + +--- + +## 一、核心论点 + +### 1.1 Agent = Model，不是代码 + +``` +Agent 的历史证据链： + +2013 DeepMind DQN → 一个神经网络学会玩 49 款 Atari 游戏 +2019 OpenAI Five → 五个网络打败 Dota 2 世界冠军 OG +2019 AlphaStar → 星际争霸 II 登顶 Grandmaster（前 0.15%） +2019 腾讯绝悟 → 王者荣耀 5v5 击败 KPL 职业选手 +2024 LLM Coding Agents → 读代码库、写实现、调试、团队协作 + +共同真相：Agent 从来不是代码，Agent 始终是模型。 +``` + +### 1.2 Harness = 驾驶舱，不是司机 + +``` +Harness = Tools + Knowledge + Observation + Action + Permissions + +模型决定。Harness 执行。 +模型推理。Harness 提供上下文。 +模型是司机。Harness 是车辆。 +``` + +### 1.3 对 "Prompt Plumbing" 的批判 + +仓库明确批判了一整个行业：拖拽工作流构建器、无代码 "AI Agent" 平台、Prompt 链编排库——它们不是 Agent，是"带有幻想的 shell 脚本"。 + +> "You cannot engineer your way to agency. Agency is learned, not programmed." + +--- + +## 二、12 课架构 + +### 2.1 全景层级图 + +``` +Phase 1: 循环 Phase 2: 规划与知识 +┌───────────────────┐ ┌───────────────────┐ +│ s01 Agent Loop │ │ s03 TodoWrite │ +│ 30 行 Python │ │ 模型自管计划 │ +│ = 完整 Agent │ │ 一次一个 in_prog. │ +│ │ │ │ +│ s02 Tool Use │ │ s04 Subagent │ +│ 调度映射表 │ │ 上下文隔离 │ +│ 路径沙箱 │ │ 子任务清洁上下文 │ +│ │ │ │ +│ │ │ s05 Skills │ +│ │ │ 两层按需加载 │ +│ │ │ │ +│ │ │ s06 Compact │ +│ │ │ 三层上下文压缩 │ +└───────────────────┘ └───────────────────┘ + +Phase 3: 持久化 Phase 4: 团队 +┌───────────────────┐ ┌───────────────────┐ +│ s07 Task System │ │ s09 Agent Teams │ +│ 任务 DAG 磁盘持久 │ │ 持久化队友 + 邮箱 │ +│ 依赖自动解锁 │ │ │ +│ │ │ s10 Protocols │ +│ s08 Background │ │ 结构化握手协议 │ +│ 后台线程异步执行 │ │ shutdown/plan │ +│ 通知队列注入 │ │ │ +│ │ │ s11 Autonomous │ +│ │ │ 自组织领取任务 │ +│ │ │ 60s 空闲自动退出 │ +│ │ │ │ +│ │ │ s12 Worktree │ +│ │ │ Git worktree 隔离│ +│ │ │ 控制面 + 执行面 │ +└───────────────────┘ └───────────────────┘ +``` + +### 2.2 每课核心机制 + +| 课 | Harness 层 | 核心机制 | 代码量 | +|---|-----------|---------|--------| +| s01 | Loop | `while True` + `stop_reason != "tool_use"` 退出 | 3.6KB | +| s02 | Tool dispatch | `{tool_name: handler}` 调度映射 + `safe_path()` 沙箱 | ~5KB | +| s03 | Planning | TodoManager 状态机（pending→in_progress→completed），一次一个 | ~7KB | +| s04 | Context isolation | 子 Agent 清空 messages，只返回摘要文本 | ~9KB | +| s05 | Knowledge | 两层注入：系统提示含索引（~100 token/skill）+ load_skill 工具返回全文 | ~11KB | +| s06 | Compression | 三层压缩：每轮微压 → 50K token 自动压 → 手动压缩工具 | ~14KB | +| s07 | Persistence | JSON 文件 DAG，blockedBy/blocks 依赖，完成自动解锁 | ~17KB | +| s08 | Async | 守护线程 + 通知队列，每次 LLM 调用前排空队列 | ~19KB | +| s09 | Teams | 持久化队友 + JSONL 邮箱，WORKING↔IDLE↔SHUTDOWN 生命周期 | ~21KB | +| s10 | Protocols | request_id FSM（pending→approved/rejected），一个状态机两种协议 | ~23KB | +| s11 | Autonomy | IDLE 轮询（5s 间隔）+ 任务板自主领取 + 身份重注入 | ~25KB | +| s12 | Isolation | Git worktree 绑定 Task ID，控制面(.tasks/) + 执行面(.worktrees/) | 25.9KB | + +### 2.3 设计不变量 + +每一课都叠加在 s01 的循环之上，**循环本身从不改变**： + +```python +# s01: 永不改变的核心循环 +while True: + response = client.messages.create( + model=model, + system=system_prompt, + messages=messages, + tools=tools + ) + + # 模型决定何时停止 + if response.stop_reason != "tool_use": + break + + # Harness 执行工具调用 + for block in response.content: + if block.type == "tool_use": + result = dispatch[block.name](block.input) + messages.append(tool_result(block.id, result)) +``` + +--- + +## 三、Harness Engineering 七原则 + +### P1: 循环永不改变（The Loop Never Changes） + +每一课在循环**周围**添加机制，而非**修改**循环。Agent（模型）拥有循环；Harness 拥有机制。 + +### P2: 工具是 Agent 的手（Tools Are Hands） + +原子、可组合、描述清晰。调度映射模式（`{name: handler}`）意味着添加能力无需改变核心。 + +### P3: 知识按需加载，不预加载（Knowledge On-Demand） + +两层 Skill 加载——系统提示中的廉价索引（~100 token）+ tool_result 中的昂贵内容（~2000 token）——是标准模式。 + +### P4: 上下文是珍贵资源（Context Is Precious） + +三种策略保护上下文：子 Agent 隔离（s04）、三层压缩（s06）、磁盘持久化（s07）。 + +### P5: 约束聚焦，非限制（Constraints Focus, Not Limit） + +"一次一个 in_progress"（s03）、"只读子 Agent"（s04）、"路径沙箱"（s02）——都是让模型性能**更好**的护栏。 + +### P6: 持久化跨越会话（Persistence Outlives Sessions） + +磁盘任务（s07）、团队配置 JSON（s09）、事件 JSONL（s12）——Harness 维护模型上下文窗口无法持有的状态。 + +### P7: 信任模型（Trust the Model） + +最强主题。不预设工作流。不构建决策树。给工具和知识，让模型推理。 + +> "You are not writing intelligence. You are building the world intelligence inhabits." + +--- + +## 四、附带 Skills + +### agent-builder + +核心哲学："模型已经知道如何做 Agent。你的工作是让开。" + +三要素：Capabilities（能做什么）+ Knowledge（知道什么）+ Context（发生了什么） + +渐进复杂度：从 3-5 个能力起步。大多数 Agent 不需要超过 Level 2（规划）。 + +反模式清单：过度工程、工具太多、刚性工作流、预加载知识、微管理。 + +### mcp-builder + +MCP Server 构建模板（Python + TypeScript）。最佳实践：清晰工具描述、输入验证、错误处理、默认异步、安全、幂等。 + +### code-review + +五维审查：安全（Critical）→ 正确性 → 性能 → 可维护性 → 测试。结构化输出：摘要 + 关键问题 + 改进 + 亮点 + 结论。 + +### pdf + +PDF 读取（pdftotext/PyMuPDF）、创建（pandoc/reportlab）、合并/拆分。实用工具检测 + 大文件逐页处理。 + +--- + +## 五、与 Agent Friendly 开发规约的对照 + +### 5.1 同一枚硬币的两面 + +``` +┌──────────────────────────────────────────────────────────┐ +│ │ +│ Agent Friendly 规约 Harness Engineering │ +│ (被调用方视角) (构建方视角) │ +│ │ +│ "怎么让 Agent 用好 "怎么给 Agent 建好 │ +│ 你的系统" 运行环境" │ +│ │ +│ ┌──────────┐ ┌──────────┐ │ +│ │ 你的 API │◀── MCP ──────────▶│ Agent │ │ +│ │ 你的工具 │ A2A │ Harness │ │ +│ │ 你的文档 │ │ 循环+工具 │ │ +│ └──────────┘ └──────────┘ │ +│ │ +│ 规约约束: Harness 约束: │ +│ - Schema-First - 循环永不改变 │ +│ - 工具设计 7 子规约 - 工具原子可组合 │ +│ - 10 条安全约束 - 路径沙箱 │ +│ - 25 条 NEVER - 信任模型 │ +│ │ +└──────────────────────────────────────────────────────────┘ +``` + +### 5.2 概念映射表 + +| Harness Engineering 概念 | Agent Friendly 规约对应 | 关系 | +|---|---|---| +| **Agent Loop**（s01）| — | Harness 独有概念，规约不涉及 Agent 内部循环 | +| **Tool dispatch map**（s02）| §2 Tool Design 7 子规约 | 构建方的调度 = 被调用方的 Schema | +| **safe_path() 沙箱**（s02）| §4.1 Least Agency | 同一约束的两侧实现 | +| **TodoWrite 一次一个**（s03）| P2 约束>能力 | 约束聚焦的典型实例 | +| **Subagent 上下文隔离**（s04）| §4 安全 / Sandbox | 隔离是双方共识 | +| **Skill 两层加载**（s05）| §5 文档发现层 (llms.txt) | 索引层+内容层 = 同一模式 | +| **Context Compact**（s06）| — | Harness 独有（管理 Agent 内部记忆） | +| **Task DAG 磁盘持久**（s07）| Agent Skills 标准 | 持久化知识的不同形式 | +| **Background tasks**（s08）| — | Harness 独有（异步执行管理） | +| **Team mailbox**（s09）| A2A 协议 | 邮箱 = 简化版 A2A | +| **Shutdown/Plan protocols**（s10）| HITL + Agent 协商 | 结构化握手 = Agent 间礼仪 | +| **Autonomous task claiming**（s11）| Agent Card 发现 | 自组织 = 去中心化发现 | +| **Worktree isolation**（s12）| §4 Sandbox / MicroVM | 目录隔离 ≈ 轻量级沙箱 | +| **"Trust the model"**（全局）| P2 约束>能力 | 同一哲学的不同表达 | +| **mcp-builder skill** | §2 + §3 全部 | MCP Server 构建 = 规约的执行 | + +### 5.3 互补关系全景 + +``` + Agent Friendly 完整画面 + ──────────────────────── + + 被调用方（你的系统） 构建方（Agent Harness） + ════════════════ ═══════════════════ + + §5 发现层 s05 Skill 两层加载 + llms.txt / Agent Card 系统提示索引 + 按需加载 + │ │ + │ Agent 找到你 │ Agent 获取知识 + ▼ ▼ + §2 工具设计 s02 Tool dispatch + Schema / 描述 / 注解 调度映射 + 沙箱 + │ │ + │ Agent 理解你 │ Agent 执行工具 + ▼ ▼ + §3 API 设计 s01 Agent Loop + 10 条 AX 原则 while True 核心循环 + │ │ + │ Agent 调用你 │ Agent 决策 + ▼ ▼ + §4 安全规约 s04/s12 隔离 + 10 条安全约束 子 Agent + Worktree + │ │ + │ Agent 安全运行 │ Agent 安全执行 + ▼ ▼ + §6 评估规约 agent-builder skill + Postman 48 / 10 项评分 渐进复杂度 + 反模式 + │ │ + └───────────┬───────────────┘ + │ + ▼ + ┌────────────────┐ + │ Agent 成功完成 │ + │ 用户的任务 │ + └────────────────┘ +``` + +### 5.4 核心差异 + +| 维度 | Agent Friendly 规约 | Harness Engineering | +|------|-------------------|-------------------| +| **视角** | 被调用方（API/工具提供者） | 构建方（Agent 运行环境） | +| **关注点** | 接口契约、发现性、安全 | 循环、上下文、持久化 | +| **不涉及** | Agent 内部循环和记忆管理 | API/工具的 Schema 设计 | +| **核心动词** | "暴露"、"描述"、"约束" | "加载"、"隔离"、"持久化" | +| **评估方式** | 量化评分（48 Checks） | 12 课渐进验证 | +| **共识** | 约束 > 能力；信任模型；Schema-First | 约束聚焦；信任模型；循环不变 | + +--- + +## 六、整合洞察 + +### 6.1 Agent Friendly 的完整定义（整合后） + +``` +Agent Friendly = 被调用方友好 + 构建方友好 + +被调用方友好（规约）： + 让 Agent 能发现、理解、调用、验证你的系统 + +构建方友好（Harness）： + 让 Agent 有清晰的感知、精准的行动、丰富的知识、安全的边界 + +两者的交汇点： + 工具设计 ←→ 工具调度 + 文档发现 ←→ 知识加载 + 安全约束 ←→ 沙箱隔离 + Agent 协议 ←→ 团队通信 +``` + +### 6.2 为什么两个视角都需要 + +``` +只有规约（被调用方）： + → Agent 能找到你的 API，但不知道怎么高效使用 + → 好的菜单，但没有好的厨房 + +只有 Harness（构建方）： + → Agent 有好的运行环境，但外部工具难以对接 + → 好的厨房，但食材（API）质量参差不齐 + +两者结合： + → Agent 能发现好的工具 + 在好的环境中高效使用它们 + → 好的厨房 + 好的食材 = 好的菜 +``` + +### 6.3 共享的哲学根基 + +两个视角共享三条根本信念： + +**信念 1：模型比你想的更聪明** +- 规约：不要猜测 Agent 的意图，给它好的 Schema 它会自己搞定 +- Harness：不要预设工作流，给它工具和知识让它推理 + +**信念 2：约束是最好的礼物** +- 规约：NEVER 清单比功能列表更重要（§10.7 约束>能力） +- Harness：一次一个 in_progress 让模型更专注（s03） + +**信念 3：好设计是透明的** +- 规约：好的工具描述让 Agent 像读文档一样理解接口 +- Harness：好的循环设计让你几乎忘记它的存在