zhukang/content-forge-vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault: auto-sync 2026-03-25 02:00

Browse Source
This commit is contained in:
lizikk 2026-03-25 02:00:01 +08:00
parent 7ca0d00164
commit 09aad62ec3
5 changed files with 2929 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

761
00-inbox/2026-03-24-agent-friendly-architecture.md Normal file
View File

@ -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 课映射) │
│ │
│ 五层关系: 证据 → 知识 → 结构 → 约束 → 实现 │
│ │
└─────────────────────────────────────────────────────────────┘
```

289
00-inbox/2026-03-24-agent-friendly-deep-research.md Normal file
View File

@ -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 <title> 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 层架构共识、安全挑战

519
00-inbox/2026-03-24-agent-friendly-development-spec.md Normal file
View File

@ -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 状态可追踪 |

1001
00-inbox/2026-03-24-agent-friendly-glossary.md Normal file
View File

File diff suppressed because it is too large Load Diff

359
00-inbox/2026-03-24-harness-engineering-analysis.md Normal file
View File

@ -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：好的循环设计让你几乎忘记它的存在