---
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%+ | 行业测试 |