53 KiB
53 KiB
| id | title | slug | status | content_type | channels | language | source_urls | assets | cover_image | template | owner | created_at | updated_at | published_at | tags | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2026-03-24-agent-friendly-architecture | Agent Friendly 概念关系与架构全景图 | agent-friendly-architecture | inbox | article |
|
zh-CN |
|
article | content-forge | 2026-03-24T00:00:00+08:00 | 2026-03-24T00:00:00+08:00 | null |
|
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 课映射) │
│ │
│ 五层关系: 证据 → 知识 → 结构 → 约束 → 实现 │
│ │
└─────────────────────────────────────────────────────────────┘