zhukang/content-forge-vault

Fork 0

lizikk 09aad62ec3 vault: auto-sync 2026-03-25 02:00

2026-03-25 02:00:01 +08:00

38 KiB

Raw Permalink Blame History

title

slug

status

content_type

channels

language

source_urls

assets

cover_image

template

owner

created_at

updated_at

published_at

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、Matt Biilmann - Introducing AX

ACI（Agent-Computer Interface，智能体-计算机接口）

定义：Anthropic 提出的概念，指 Agent 与外部工具/系统交互的界面设计。类比 HCI（Human-Computer Interface），强调 Agent 的工具接口设计需要与人类界面设计同等的投入和迭代。

核心原则：

投入与 HCI 同等精力设计 ACI
从模型视角思考："仅凭工具名和描述，是否显而易见该如何使用？如果不是，模型也会困惑。"
好的工具定义 = 给一个靠谱但字面理解一切的初级工程师写文档
用 Claude 自身协作改进工具定义，比人工创建效果更好

关系：ACI 是 AX 在工具层的具体实现方法论。

出处：Anthropic - 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

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

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 公告

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

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

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）：

Take away from the agent：一致性关键行为写入脚本/模板/规则，不靠 LLM 推理
Let agent reason where it adds value：解释、选择、对话是 Agent 的领地
Constitutional constraints：SKILL.md 是契约——精确步骤 + 边缘情况 + NEVER 规则

出处：The New Stack - Agent Skills

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

WebMCP

定义：Google 于 2026 年 2 月提出的协议，让 AI Agent 在浏览器中与网站进行结构化交互（而非模拟点击）。

状态：Chrome Canary 预览阶段。

A2UI（Agent-to-User Interface，智能体到用户界面协议）

定义：Google 开源（Apache 2.0）的协议，让 Agent 能跨信任边界发送富 UI 组件。Agent 发送声明式组件描述，客户端用原生 widget 渲染。

解决问题：Agent 需要产生可视化输出，但直接执行渲染代码有安全风险。

出处：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 幻觉——不需要猜测下一步该调什么接口，响应本身就告诉它。

示例：

{
  "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 身份的框架。

三个问题：

Who is this agent?（身份）
Who controls it?（权限方）
Can it be trusted?（信誉）

实现：密码学签名、数字证书、Agent 身份注册。

行业动态：78% 金融机构预计 AI 购物 Agent 将带来欺诈风险上升。

出处：Sumsub、AgentFacts KYA Standard

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 分。

八个支柱：

META（元数据）：operationId、summary、description
ERR（错误）：4xx/5xx 定义、错误 Schema、429 定义
INTRO（内省）：参数类型、required 标记、枚举、示例
NAME（命名）：一致大小写、RESTful 路径、HTTP 语义
PRED（可预测性）：响应 Schema、分页、日期格式
DOC（文档）：认证、频率限制、API 概述
PERF（性能）：频率限制头、缓存头、批量端点
DISC（发现）：OpenAPI 版本、Server URL、多环境

通过阈值：≥ 70 分且 8 项 Critical 全部通过。

出处：Postman 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

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

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/代码的系统访问能力。

隔离级别（从弱到强）：

进程隔离（最弱）
容器（Docker/gVisor）——不足以作为安全边界
MicroVM（Firecracker/Kata）——推荐
完全虚拟化

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

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 上下文窗口的三层策略，防止长会话中记忆过载。

三层：

微压缩（每轮）：替换旧 tool_result 为占位符
自动压缩（>50K token）：完整记录存磁盘，LLM 生成摘要
手动压缩：模型主动调用 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%+	行业测试

38 KiB Raw Permalink Blame History Unescape Escape