> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # AI 编程助手工具体系指南 AI 编程助手（Claude Code、Cursor、Copilot 等）在帮你写代码时，背后调用了多种不同来源的工具。本文从工程师视角系统讲解这些工具的分类、协议原理和选择逻辑，帮你从"能用"到"理解为什么这样设计"。 ::: details 本文用到的基础术语（已熟悉可跳过） | 术语 | 含义 | | ---------------------- | -------------------------------------------------------------------------------------------------------- | | **进程（process）** | 一个正在运行的程序。打开 Chrome 是一个进程，打开 VS Code 是另一个进程。在 macOS 的 Activity Monitor 或 Windows 的 Task Manager 里能看到所有进程 | | **子进程（child process）** | 由一个进程启动的另一个进程。比如 VS Code 启动一个 Node.js 进程来跑你的代码，那个 Node.js 进程就是 VS Code 的子进程 | | **Shell** | 命令行解释器。你在终端（Terminal）里敲命令，Shell 负责理解并执行。常见的 Shell 有 Bash 和 Zsh | | **协议（protocol）** | 两个程序之间"怎么对话"的约定格式。类比：中文是人与人的协议，HTTP 是浏览器与网站的协议，MCP 是 AI 与外部工具的协议 | | **API** | Application Programming Interface。一个程序对外暴露的调用接口。比如你的代码调用 Anthropic API，就能让 Claude 帮你处理请求 | | **JSON** | 一种用 `{}` 和 `[]` 组织数据的文本格式。程序之间传数据最常用的格式。例：`{"name": "Max", "age": 25}` | | **LLM** | Large Language Model（大语言模型）。ChatGPT、Claude、Gemini 背后的 AI 模型。你在 AI 助手里打字，实际上是在跟 LLM 对话 | ## ::: ## 一、扩展体系全景 AI 编程助手"调用了某个东西然后返回结果"。表面上看起来都一样，但来源完全不同： ``` ┌──────────────────┬──────────────────┬────────────────────┐ │ Built-in Tools │ MCP Tools │ CLI (Bash) │ │ 原生内置 │ 外部插件协议 │ 系统命令行 │ ├──────────────────┼──────────────────┼────────────────────┤ │ Read / Write │ run_sql │ git status │ │ Edit / Grep │ query-docs │ aws dynamodb ... │ │ Glob / Bash │ read_channel │ npm run docs:build │ │ WebSearch │ create_branch │ npm test │ ├──────────────────┼──────────────────┼────────────────────┤ │ 进程内直接执行 │ JSON-RPC 协议 │ 子进程执行 shell │ │ 最快、最安全 │ 结构化、可扩展 │ 万能、风险最高 │ └──────────────────┴──────────────────┴────────────────────┘ ``` 表中出现的 JSON-RPC 是 MCP 使用的通信格式，[§3.3](#33-json-rpc) 会详细讲解。 还有一个经常被混淆的概念：**Skills**。Skills 不是工具，而是教 AI "怎么做事"的 Markdown 指令文件。它指挥 AI 去调用上面这三层工具。 | 层级 | 本质 | 职责 | 类比 | | ------------------ | ----------- | ------------- | ----------------- | | **Skills** | Markdown 指令 | 教 AI 怎么做（HOW） | 员工培训手册 | | **Built-in Tools** | 内置代码 | AI 的基础能力 | 手机自带相机 | | **MCP Tools** | 外部协议插件 | 连接外部系统（WHAT） | App Store 下载的 app | | **CLI (Bash)** | Shell 命令 | 万能后备 | 越狱后跑任意程序 | **选择优先级：Built-in > MCP > Bash。** AI 助手被设计为优先使用内置工具（比如用 `Read` 而不是 `cat`，用 `Grep` 而不是 `grep`），其次使用 MCP 工具，最后才用 Bash 执行 CLI 命令。 ### 完整扩展体系 但工具只是 AI 助手能力的一部分。以 Claude Code 2026 为例，完整的扩展体系有 **6 层**： | 层级 | 机制 | 本质 | 职责 | 类比 | | ------- | -------------------- | ----------------------- | ----------------- | --------------- | | **配置层** | CLAUDE.md | Markdown 指令文件 | 告诉 AI "你是谁、规矩是什么" | 公司规章制度 | | **指令层** | Skills | Markdown 工作流 | 教 AI 按特定步骤做事 | 员工培训手册 | | **工具层** | Built-in / MCP / CLI | 内置代码 / JSON-RPC / Shell | 执行具体操作 | 手 / 工具 / 万能钥匙 | | **代理层** | Custom Agents | 独立子进程 + 独立 context | 派专家去做特定任务 | 外包给专业顾问 | | **事件层** | Hooks | Shell 命令绑定生命周期事件 | 在特定时刻自动执行代码 | 门禁系统（刷卡触发） | | **打包层** | Plugins | 上述所有的打包分发 | 一键安装整套能力 | App Store 的 app | 本文接下来按层详解。§二～§四 讲工具层（Built-in / MCP / CLI），§五 讲指令层（Skills），§六～§九 讲代理层、事件层、打包层和配置层。 *** ## 二、Built-in Tools — 出厂自带的能力 Built-in Tools 是 AI 编程助手自带的功能，安装时就有，不需要额外配置，也不能增删。以 Claude Code 为例，共有约 28 个内置工具，按功能分为 7 组： ### 2.1 文件操作 | Tool | 做什么 | 为什么不用 CLI 替代 | | ---------------- | -------------------------------------- | ---------------------------------- | | **Read** | 读文件，返回带行号的文本。支持图片、PDF、Jupyter notebook | 进程内直接读，不起子进程；能看图片和 PDF | | **Write** | 创建新文件，或完全覆盖已有文件 | 显示完整内容让你确认，防止误覆盖 | | **Edit** | 精确查找替换，`old_string` → `new_string` | 显示 diff 让你审核；要求先 Read 才能 Edit，防止盲改 | | **NotebookEdit** | 编辑 Jupyter notebook 的单个 cell | 支持 replace / insert / delete 操作 | **Read → Edit 是最安全的编辑流程。** AI 被强制要求"先读再改"，不可能修改一个它没看过的文件。 ### 2.2 搜索 | Tool | 做什么 | 区别 | | -------- | -------------------- | ----------- | | **Glob** | 按文件名模式匹配（`**/*.md`） | "叫什么名字的文件？" | | **Grep** | 按内容正则搜索（底层是 ripgrep） | "文件里写了什么？" | ### 2.3 执行 | Tool | 做什么 | 说明 | | --------------------------------- | ------------------- | --------------------------------- | | **Bash** | 执行任意 shell 命令 | 万能后备。能做一切，但没有结构化输出，安全风险最高 | | **LSP**（Language Server Protocol） | 代码智能分析：跳转定义、查引用、看类型 | 比 Grep 更精准。它理解语法，不会把注释里的同名字符串当成定义 | ### 2.4 网络 | Tool | 做什么 | 区别 | | ------------- | ------------------------ | -------------- | | **WebSearch** | 搜索互联网，返回摘要和链接 | 相当于 Google 搜索框 | | **WebFetch** | 抓取指定 URL，HTML → Markdown | 相当于打开一个网页阅读内容 | 通常配合使用：WebSearch 找到 URL → WebFetch 读取具体页面。 ### 2.5 Agent 协作 | Tool | 做什么 | | ------------------------------------------------ | ---------------------------------- | | **Task** | 启动子 agent 执行复杂任务（搜索代码库、设计方案、代码审查等） | | **TaskCreate / TaskUpdate / TaskList / TaskGet** | 任务列表管理，跟踪多步骤工作进度 | | **TaskOutput / TaskStop** | 读取后台任务输出 / 终止后台任务 | | **TeamCreate / TeamDelete / SendMessage** | 创建和销毁 agent 团队，多 agent 并行协作 | ### 2.6 交互与流程控制 | Tool | 做什么 | | -------------------------------- | -------------------------------------------- | | **AskUserQuestion** | 弹出选择题让用户回答 | | **EnterPlanMode / ExitPlanMode** | 进入/退出计划模式（只做调研，不写代码） | | **EnterWorktree** | 创建隔离的 git worktree 工作区，在独立分支上修改不影响主分支 | | **Skill** | 加载并执行 skill（`/pr`、`/commit` 等 slash command） | ### 2.7 MCP 相关 | Tool | 做什么 | | ---------------------------------------------- | ----------------------------- | | **ToolSearch** | 搜索并加载 MCP tools（延迟加载，不搜索就不能用） | | **ListMcpResourcesTool / ReadMcpResourceTool** | 列出和读取 MCP server 提供的资源 | *** ## 三、MCP — AI 的标准插件协议 ### 3.1 MCP 解决什么问题 \{ #31-mcp-解决什么问题 } 每个 AI 工具（Claude、ChatGPT、Cursor）都想连接外部系统（数据库、GitHub、Slack）。没有标准的话，需要 N × M 个定制集成： ``` 没有 MCP: 有了 MCP: Claude ──→ GitHub Claude ──┐ Claude ──→ Slack │ ChatGPT ──→ GitHub ChatGPT ──┤── MCP ──→ GitHub Server ChatGPT ──→ Slack │ Slack Server Cursor ──→ GitHub Cursor ──┘ DB Server Cursor ──→ Slack ...（N×M 个连接） ...（N+M 个连接） ``` MCP（Model Context Protocol）就是 AI 世界的 USB 接口。一个开放协议，让任何 AI client 连接任何 MCP server。由 Anthropic 发起，2025 年底捐给 Linux Foundation 的 Agentic AI Foundation。OpenAI、Google、Microsoft、AWS 都是支持者。 ### 3.2 三层架构：Host / Client / Server \{ #32-三层架构host--client--server } 这三个不是抽象概念，是**你电脑上真实运行的进程**（不熟悉"进程"概念可回看文章开头的术语表）： ``` 你在终端敲: claude 你的电脑上启动了这些进程： ┌─────────────────────────────────────────────────────────┐ │ PID 12345: claude (Node.js 进程) ← 这就是 Host │ │ │ │ 内部包含： │ │ ├── LLM 连接（与 Anthropic API 通信） │ │ ├── 终端 UI │ │ ├── Built-in tools 代码 │ │ ├── Client 实例 1 → 管理与 Neon server 的连接 │ │ ├── Client 实例 2 → 管理与 Lark server 的连接 │ │ └── Client 实例 3 → 管理与 Cloudflare server 的连接 │ └─────────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ PID 12346 PID 12347 PID 12348 Neon MCP Server Lark Server CF Server ← 独立子进程 ``` 图中 PID（Process ID）是操作系统分配给每个进程的编号，每次启动都不同。 | 角色 | 是什么 | 数量 | | ---------- | ---------------------------------- | ------------------------- | | **Host** | AI 助手主进程。管理所有连接，控制权限，聚合上下文 | 永远 **1 个** | | **Client** | Host 进程内部的连接管理模块，每个 MCP server 配一个 | **N 个**（N = 配置的 server 数） | | **Server** | 独立进程（或远程服务），提供具体工具能力 | **N 个**（启动时全部创建，后台常驻） | **美团类比：** Host = 美团 App，Client = App 里连接每家餐厅的模块，Server = 每家餐厅的厨房。你只跟 App 交互，App 负责把订单翻译成每个厨房能理解的格式。 ::: details 用 Activity Monitor 验证 在 macOS 上打开 Activity Monitor，搜索 `claude`，可以看到主进程（Host）。搜索 `npx` 或 MCP server 名称，可以看到各个 server 子进程。这能帮你直观验证"1 个 Host + N 个 Server"的进程模型。 ::: ### 3.3 通信基础：JSON-RPC \{ #33-json-rpc } 所有 MCP 消息都用 JSON-RPC 2.0 格式。只有三种消息类型： **Request（请求）**。要求对方做事，等回复： ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "run_sql", "arguments": { "sql": "SELECT * FROM users LIMIT 5" } } } ``` **Response（响应）**。回复请求结果： ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [{"type": "text", "text": "..."}] } } ``` **Notification（通知）**。单向消息，不需要回复（没有 `id` 字段）： ```json { "jsonrpc": "2.0", "method": "notifications/tools/list_changed" } ``` 连接建立时有**能力协商**：双方各报自己支持什么，之后只能用已声明的能力。 ### 3.4 Server 提供的三大能力 MCP server 可以向 client 暴露三种东西，**控制权分属不同角色**： | 能力 | 谁决定用不用 | 做什么 | 例子 | | ------------- | ----------- | -------- | ------------------------- | | **Tools** | AI 模型自动判断 | 可调用的函数 | `run_sql`、`create_branch` | | **Resources** | 应用程序/用户手动选择 | 提供上下文数据 | 文件内容、数据库 schema | | **Prompts** | 用户显式触发 | 预定义的对话模板 | slash commands、菜单选项 | 控制权分层是刻意的安全设计。Tools 让 AI 有行动力，但 Host 必须征求人类确认（权限弹窗）。Resources 由应用决定注入。Prompts 完全由用户主动触发，是最安全的。 ::: details Resources 的高级特性 **Resource Templates**。URI 支持模板语法（如 `db:///{table}/schema`），客户端动态填充参数，避免 server 注册海量静态 URI。 **Subscriptions**。Client 可以订阅特定 resource。当 resource 内容变化时，server 推送 `notifications/resources/updated`，client 自动重新获取。适用于数据库 schema、配置文件等会变的数据。 ::: ::: details Tool 的错误处理协议 Tool 调用失败时，MCP 区分**协议错误**和**执行错误**： - 协议错误（tool 不存在、参数格式错）：返回 JSON-RPC error response - 执行错误（SQL 语法错、API 返回 500）：仍然返回正常 response，但 `content` 里标记 `isError: true` 这样 LLM 能看到执行错误的详情，尝试修正后重试（比如改 SQL 语法）。 ::: ### 3.5 Client 提供的三大能力 方向相反。Server 也可以向 Client 发请求： **Sampling（采样）**。Server 借用 Host 的 LLM 能力： ``` Server: "帮我用 LLM 分析一下这段代码" → Client 转发给 LLM → LLM 返回结果 → Client 把结果发回 Server ``` Server 不需要自己的 API key，借用 Host 的 LLM。 **Roots（根目录）**。Client 告诉 Server 操作范围： ```json { "roots": [{ "uri": "file:///Users/max/workspace/docs", "name": "Docs Project" }] } ``` **Elicitation（信息收集）**。Server 主动向用户提问。两种模式： Form 模式。弹出表单收集非敏感信息： ``` 部署 Server 需要更多信息，于是主动向用户提问： ┌────────────────────────────────────────┐ │ 部署助手需要以下信息： │ │ 目标环境: [staging ▼] │ │ 分支: [main___________] │ │ 是否跑迁移: [✓] 是 │ │ [Submit] [Decline] │ └────────────────────────────────────────┘ ``` URL 模式。跳转到网页处理敏感操作（OAuth 授权登录、支付等）： ``` GitHub MCP Server 不能通过聊天收集密码（不安全）， 所以引导用户直接在浏览器里完成 OAuth 授权（类似"用 Google 登录"的流程）。 密码/token 完全不经过 AI 助手，AI 只知道"授权成功了"。 ``` ::: details AskUserQuestion vs Elicitation 两者都是"向用户提问"，但发起者和协议不同： | 维度 | AskUserQuestion | Elicitation | | ---- | ------------------- | --------------------------------- | | 发起者 | AI 模型（LLM 决定要问） | MCP Server（外部程序决定要问） | | 协议 | Built-in tool 调用 | MCP JSON-RPC `elicitation/create` | | 适用场景 | AI 需要澄清需求 | Server 需要运行时配置（环境、分支等） | | 示例 | "你想用 OAuth 还是 JWT？" | "请选择部署目标环境" | ::: ::: details Elicitation 在当前 Claude Code 中还不常见 截至 2026 年初，大多数 MCP server 还没有实现 Elicitation。它是 2025-11 spec 新增的能力，生态支持仍在早期。你在 Claude Code 里看到的"向用户提问"基本都是 `AskUserQuestion`（Built-in tool），而不是 Elicitation。 ::: ### 3.6 Transport: stdio vs HTTP MCP 定义了两种传输方式： | Transport | 适用场景 | 工作方式 | | ------------------- | ------------- | ------------------------------- | | **stdio** | 本地 MCP server | Host 启动子进程，通过 stdin/stdout 管道通信 | | **Streamable HTTP** | 远程 MCP server | Host 通过 HTTP 请求与远程服务通信 | 大多数 MCP server 使用 stdio（本地子进程）。远程服务（如飞书 Meegle）使用 HTTP。 ::: details 什么是 stdin/stdout 管道 每个进程都有两个内置的文本通道： - **stdin**（standard input）：进程的"耳朵"，用来接收输入 - **stdout**（standard output）：进程的"嘴巴"，用来输出结果 当 Host 启动 MCP server 子进程时，会建立一条**管道（pipe）**：Host 写数据到 server 的 stdin，server 写结果到自己的 stdout，Host 读取。就像两个人通过一根管子传纸条。 ::: ### 3.7 一次 MCP 调用的完整流程 \{ #37-一次-mcp-调用的完整流程 } 用户问"帮我看 users 表结构"时，电脑上**物理发生的事**： ``` 步骤 1: Claude Code 主进程把你的话发给 Anthropic API 你的电脑 ──HTTP──→ api.anthropic.com 步骤 2: API 返回 LLM 的决定："调用 describe_table_schema" api.anthropic.com ──HTTP──→ 你的电脑 步骤 3: 弹出权限确认 [Allow? (y/n)] 步骤 4: 你按 y 步骤 5: Client 通过 stdin 管道写 JSON 给 Server 子进程 主进程 PID 12345 子进程 PID 12346 ┌──────────────┐ stdin 管道 ┌──────────────┐ │ Client 代码 │ ──────────────→ │ Neon MCP │ │ │ {"method": │ Server │ │ │ "tools/call"} │ → 连接 Neon │ │ │ stdout 管道 │ → 执行查询 │ │ 收到结果 │ ←────────────── │ → 返回结果 │ └──────────────┘ └──────────────┘ 步骤 6: 主进程再调 Anthropic API，附上工具结果 步骤 7: API 返回自然语言回答，显示在终端 ``` **MCP 章节小结：** 1 个 Host 管理 N 个 Client，每个 Client 对接 1 个 Server。Server 提供 Tools / Resources / Prompts 三种能力，Client 提供 Sampling / Roots / Elicitation 三种反向能力。通信用 JSON-RPC 2.0，传输用 stdio（本地）或 Streamable HTTP（远程）。 *** ## 四、CLI (Bash) — 万能后备 \{ #cli-bash } 当没有 Built-in tool 也没有 MCP tool 能做某件事时，AI 通过 Bash 执行 CLI 命令。 ### MCP Server 子进程 vs Bash 子进程 两者都是子进程，但性质完全不同： | 维度 | MCP Server 子进程 | Bash 子进程 | | -------- | ---------------- | -------------- | | **创建时机** | AI 助手启动时就创建 | 需要执行命令时才创建 | | **存活时间** | 一直在后台跑，等待请求 | 命令跑完就退出，消失 | | **通信方式** | JSON-RPC 协议（结构化） | 读 stdout 纯文本 | | **交互次数** | 可以来回对话无数次 | 只有一次，跑完就没了 | | **类比** | 餐厅厨房（一直开着，随时接单） | 自动售货机（投币出货，结束） | 时间线对比： ``` 你启动 AI 助手的那一刻: 时间 ──────────────────────────────────────────→ Neon MCP Server: ████████████████████████████ (常驻) Lark MCP Server: ████████████████████████████ (常驻) Bash "aws ls": ██ (2 秒) Bash "git status": █ (0.5 秒) Bash "npm run docs:build": ████ (4 秒) ``` ### 什么时候用 CLI vs MCP | 场景 | CLI 更好 | MCP 更好 | | ------ | ----------------- | ------------------------ | | AWS 操作 | ✅ CLI 覆盖全部 AWS 服务 | MCP 通常只包装部分 API | | 数据库查询 | 需要安装 psql 等客户端 | ✅ MCP server 自带连接管理 | | 安全性 | 能跑任何命令（包括危险的） | ✅ 只暴露定义好的 tools | | 输出格式 | 纯文本，LLM 自己解析 | ✅ 结构化 JSON，有 schema | | 安装成本 | 系统已有的命令直接用 | 需要配置 settings.json | | 跨平台复用 | 只在当前机器可用 | ✅ 同一 server 可被多个 AI 工具使用 | *** ## 五、Skills — 教 AI 怎么做事的指令集 ### 5.1 Skills 是什么 **Skills 就是 Markdown 文件。** 没有任何魔法。它被注入到 AI 的 context window（上下文窗口，即 AI 当前能"看到"的全部文本，包括你的对话历史、文件内容、工具结果等）里，教 AI 一个工作流程： ```markdown --- name: code-review description: Review code for bugs, style, and test coverage --- # Code Review Skill When asked to review code: 1. Run `git diff` to see changes 2. Check style against project conventions 3. Verify test coverage 4. Generate a structured report with severity ratings ``` Skills 不能直接执行任何操作。它只是告诉 AI：当遇到某种任务时，应该按什么步骤、用什么工具来完成。 ::: details Skills 的三层 Progressive Disclosure Skills 不会浪费 context window。它用三层渐进加载： | 层级 | 内容 | 大小 | 何时加载 | | ------- | ---------------------------------------- | -------------- | ----------- | | Level 1 | YAML frontmatter（`name` + `description`） | \~30-50 tokens | 始终加载（触发判断用） | | Level 2 | Skill body（完整指令） | 几百 tokens | 激活时加载 | | Level 3 | 子目录文件（`references/*.md`） | 按需 | 只在需要时读取 | 这意味着装 50 个 skills，闲置时只消耗 50 × \~40 tokens ≈ 2000 tokens。 ::: ### 5.2 Skills vs MCP vs CLI 的定位 ``` 用户: "帮我查一下数据质量问题" Skills 的角色（指挥官）: → "先理解问题 → 多角度调查 → 交叉验证 → 写报告" MCP 的角色（执行者）: → mcp__Neon__run_sql("SELECT COUNT(*) WHERE field IS NULL") CLI 的角色（后备）: → Bash("git log --oneline -5") 查最近改了什么 ``` | 维度 | Skills | MCP Tools | CLI (Bash) | | ----------- | --------------------------- | --------------------- | ------------------ | | **本质** | Markdown 指令 | JSON-RPC 协议 + 外部进程 | Shell 命令 | | **创建难度** | 写 Markdown，5 分钟 | 写 JSON-RPC server，几小时 | 装命令行工具 | | **能做外部操作？** | ❌ 自己不能，但指挥 AI 调 MCP/Bash | ✅ 直接操作外部系统 | ✅ 直接执行 | | **分发方式** | `npx skills add` / Git repo | `settings.json` 配置 | brew install / apt | | **跨平台** | ✅ 任何 LLM 都能读 Markdown | ✅ MCP 协议跨平台 | ❌ 依赖系统环境 | ### 5.3 2026 生态现状 | 维度 | 数据 | | ------------------------------ | -------------------------------------------------------- | | skills.sh 注册 skill 数 | 数千个 | | anthropics/skills GitHub Stars | 90K+ | | MCP SDK 月下载量 | 9700 万+（Python + TypeScript） | | MCP 活跃 server 数 | 10,000+ | | 支持 Skills 的平台 | Claude Code、Cursor、Copilot、Gemini CLI、Codex 等 | | 支持 MCP 的平台 | Claude、ChatGPT、Cursor、VS Code、JetBrains、Copilot Studio 等 | **Skills 和 MCP 是互补的，不是替代关系。** Skills 爆发式增长是因为创建门槛极低（写 Markdown），但它们解决的是不同问题。 *** ## 六、Custom Agents — 独立 context 的专家子进程 ### 6.1 什么是 Custom Agent Custom Agent 是一个 Markdown 文件，定义在 `~/.claude/agents/` 或项目的 `.claude/agents/` 目录下。AI 通过 `Task` tool 启动它作为**独立子进程**，拥有独立的 context window。 ```markdown --- name: code-reviewer model: sonnet tools: - Glob - Grep - Read - Bash --- # Code Review Agent 你是一个专注于代码质量的 reviewer。 检查以下维度：安全漏洞、性能问题、代码风格... ``` - `name` — agent 名称，在 `Task` tool 的 `subagent_type` 参数中引用 - `model` — 可以指定不同于主 agent 的模型（如主 agent 用 opus，reviewer 用 sonnet 降低成本） - `tools` — 限制 agent 可用的工具（最小权限原则） ### 6.2 Agent vs Skill 两者都是 Markdown 文件，但运行方式完全不同： | 维度 | Skills | Custom Agents | | ----------- | -------------------------- | ----------------------- | | **context** | 共享主 agent 的 context window | 独立 context window | | **model** | 用主 agent 的 model | 可指定不同 model | | **并行** | 不能并行 | 可并行多个 | | **创建方式** | 写 Markdown | 写 Markdown（一样简单） | | **适用场景** | 重复工作流（PR review、commit） | 需要专业知识或隔离的任务（深度调研、并行审查） | **经验法则：** 如果任务能在 10 步内完成且不需要隔离 → Skill。如果任务需要深度探索、可能污染主 context、或需要并行 → Agent。 ::: details Agent Teams：多 agent 协作 多个 agent 可以组成团队并行工作： 1. `TeamCreate` — 创建团队和共享任务列表 2. `Task` — 启动多个 agent 加入团队 3. `SendMessage` — agent 之间发消息协作 4. `TaskList` / `TaskUpdate` — 通过共享任务列表协调分工 典型模式是 **orchestrator-workers**：一个 leader agent 拆分任务，多个 worker agent 并行执行，leader 汇总结果。 ## ::: ## 七、Hooks — 生命周期事件处理 ### 7.1 什么是 Hook Hook 是绑定在 AI 助手**生命周期事件**上的 shell 命令。当特定事件发生时，自动执行你定义的代码。 与 Skills 的关键区别： | 维度 | Skills | Hooks | | ---- | ---------------- | ----------------- | | 本质 | 非确定性指令（AI 理解后执行） | 确定性代码（shell 直接执行） | | 触发 | AI 判断是否需要 | 事件驱动，每次必触发 | | 能做什么 | 教 AI 工作流程 | 拦截操作、格式化代码、注入提示 | ### 7.2 常用事件 | 事件 | 触发时机 | 典型用途 | | ------------------ | ------------- | -------------------- | | `PreToolUse` | 工具执行**前** | 拦截危险操作（如阻止 `rm -rf`） | | `PostToolUse` | 工具执行**后** | 自动格式化已修改的文件 | | `Stop` | Agent 停止时 | 播放提示音通知用户 | | `Notification` | 发送通知时 | 播放声音、发送桌面通知 | | `UserPromptSubmit` | 用户提交 prompt 时 | 注入上下文（如当前日期、安全提醒） | | `SubagentStop` | 子 agent 停止时 | 记录子 agent 运行日志 | ::: details 完整事件列表 除上述 6 个常用事件外，还有：`SessionStart`（会话开始）、`SessionEnd`（会话结束）、`SubagentStart`（子 agent 启动）、`PostToolUseFailure`（工具执行失败后）、`PermissionRequest`（权限请求时）、`PreCompact`（context 压缩前）等，共计 17 个生命周期事件。完整列表参见 [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code/hooks)。 ::: ### 7.3 配置示例 Hook 在 `settings.json` 中配置（项目级或全局级均可）： ```json { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" } ] } ] } } ``` `matcher` 用正则匹配工具名。不指定 `matcher` 则对所有该事件触发。 *** ## 八、Plugins — 打包分发层 ### 8.1 什么是 Plugin Plugin 是 Skills + Agents + Hooks + MCP + Commands 的**打包分发单元**。一个 plugin 可以包含上述任意组合的组件，通过一条命令安装到 Claude Code 中。 **Plugin 不是新能力，而是现有能力的快递包裹。** 它解决的是分发和复用问题。 ### 8.2 Plugin 的内部结构 Plugin 的清单文件位于 `.claude-plugin/plugin.json`，声明元数据： ```json { "name": "my-plugin", "description": "A plugin that adds code review capabilities", "version": "1.0.0", "author": "your-name" } ``` 组件不在清单中声明，而是按**目录约定**自动发现： ::: details 目录结构示例 ``` my-plugin/ ├── .claude-plugin/ │ └── plugin.json # 清单文件（name/version/author） ├── skills/ │ └── review.md # Skill 定义 ├── agents/ │ └── reviewer.md # Agent 定义 ├── hooks/ │ └── hooks.json # Hook 配置 └── .mcp.json # MCP server 配置 ``` ::: ### 8.3 与其他机制的关系 Plugin 是**组合层**。你可以单独使用 Skills、Agents、Hooks，不需要打包成 plugin。Plugin 的价值在于： - **分享给团队** — 通过 `/plugin install` 命令或 `claude --plugin-dir` 加载 - **版本管理** — 清单文件支持 semver 版本号 - **组合发布** — 一个 plugin 把相关的 skill + agent + hook 捆绑在一起 *** ## 九、CLAUDE.md — 指令与记忆 ### 9.1 文件层级 CLAUDE.md 是 AI 助手启动时**自动读取**的指令文件，按三个层级叠加生效： | 文件位置 | 作用域 | 是否进 Git | | ---------------------------------------- | -------- | --------- | | `~/.claude/CLAUDE.md` | 全局（所有项目） | 否 | | `./CLAUDE.md`（项目根目录） | 项目级 | ✅ 是（团队共享） | | `~/.claude/projects//CLAUDE.md` | 项目级私有 | 否（个人偏好） | 三层指令叠加生效，不互相覆盖。 ### 9.2 Auto-memory Claude Code 还有一个自动记忆目录：`~/.claude/projects//memory/`。其中 `` 由项目路径派生（如 `-Users-maxwsy-workspace-docs`）。 AI 在工作过程中自动学习并记住：项目结构、调试经验、用户偏好、架构决策。这些记忆跨 session 持久化，下次对话时 AI 已经"认识"你的项目。 ::: details CLAUDE.md vs Skills 的区别 | 维度 | CLAUDE.md | Skills | | ---- | ---------- | --------- | | 加载时机 | 启动时自动加载 | 按需激活 | | 生效范围 | 永远生效（全局规矩） | 特定任务才生效 | | 内容 | 规则、约束、偏好 | 工作流程、操作步骤 | | 类比 | 公司规章制度 | 员工培训手册 | CLAUDE.md 告诉 AI "你不能做什么"（约束），Skills 告诉 AI "你应该怎么做"（流程）。 ## ::: ## 十、实战场景分析 ### 场景 1: 纯 CLI——查 AWS 资源 ``` 你: "帮我看一下 DynamoDB 有哪些表" AI 的决策：没有 DynamoDB MCP server → 用 Bash Bash("aws dynamodb list-tables") → 起一个临时 shell 子进程 → 跑完退出 ``` | 项目 | 数量 | 说明 | | ------------- | -- | -------------------- | | Host | 1 | AI 助手主进程 | | MCP Client 参与 | 0 | 没用到 MCP | | MCP Server 参与 | 0 | 后台有 server 在跑，但这次没调用 | | Bash 子进程 | 1 | 跑完就销毁 | ### 场景 2: 多次 CLI 查询 ≠ 多个 Server ``` 你: "帮我看 DynamoDB 有哪些表，再看一下 S3 有哪些 bucket" AI 的决策：两次查询都没有 MCP server → 用 Bash Bash("aws dynamodb list-tables") → 临时子进程 1，跑完销毁 Bash("aws s3 ls") → 临时子进程 2，跑完销毁 ``` | 项目 | 数量 | 说明 | | ------------- | ----- | ------------------- | | Host | 1 | 永远只有 1 个 | | MCP Client 参与 | 0 | 没用到 MCP | | MCP Server 参与 | 0 | 后台 server 在跑，但没被调用 | | Bash 子进程 | **2** | 每次 Bash 调用创建一个临时子进程 | ::: warning 常见误解 查 2 个 AWS 资源 ≠ 启动 2 个 MCP server。Bash 子进程是临时的，跑完就销毁。MCP server 才是常驻进程。两者本质不同，参见[第四章](#cli-bash)。 ::: ### 场景 3: 纯 MCP。查 Neon 数据库 ``` 你: "帮我看 phonebook 表的 schema" AI 的决策：有 MCP tool → 用 mcp__Neon__describe_table_schema → Client 通过 stdin 管道发 JSON-RPC 给 Neon Server → Server 连接 Neon 数据库查询 → 返回结构化 JSON 结果 ``` | 项目 | 数量 | 说明 | | ------------- | -- | ------------------- | | Host | 1 | AI 助手主进程 | | MCP Client 参与 | 1 | Neon 的 client | | MCP Server 参与 | 1 | Neon server（已在后台运行） | | Bash 子进程 | 0 | 不需要 CLI | ### 场景 4: 混合使用。Neon + AWS CLI + 本地文件 ``` 你: "帮我对比 Neon 的 phonebook 表和 DynamoDB 的 PhoneBook 表， 顺便看看文档怎么描述这个表的" AI 需要三种不同来源： 操作 1: MCP → mcp__Neon__describe_table_schema 操作 2: Bash → aws dynamodb describe-table --table-name PhoneBook 操作 3: Read → Read("docs/system-design/database-schema.md") ``` | 项目 | 数量 | 说明 | | ------------- | -- | -------------------- | | Host | 1 | 永远只有 1 个 | | MCP Client 参与 | 1 | 只有 Neon 的 client 被用到 | | MCP Server 参与 | 1 | Neon server | | Built-in Tool | 2 | Bash + Read | | 临时 shell 进程 | 1 | 跑 aws cli | ### 全局进程图 不管执行什么任务，你电脑上的进程布局始终是： ``` ┌────────────────────────────────────────────────────────┐ │ 1 个 Host（AI 助手主进程） │ │ ├── N 个 MCP Client（每个 server 配一个，启动时创建） │ │ ├── 所有 Built-in Tools │ │ └── LLM 连接 │ ├────────────────────────────────────────────────────────┤ │ M 个 MCP Server（settings.json 里配几个就有几个） │ │ 不管用不用，它们都在后台跑。用到时才收到 JSON-RPC 请求 │ ├────────────────────────────────────────────────────────┤ │ 临时 shell 进程（Bash tool 使用时才创建，跑完就销毁） │ └────────────────────────────────────────────────────────┘ ``` *** ## 十一、选择决策树 ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e8eaf6', 'lineColor': '#666'}}}%% flowchart TD A["我要让 AI 做一件事"] --> B{"需要连接外部系统？
数据库/API/第三方服务"} B -->|是| C{"有对应的 MCP server？"} C -->|有| D["用 MCP Tool"] C -->|没有| E{"系统上有对应的 CLI？"} E -->|有| F["用 Bash 执行 CLI"] E -->|没有| G["需要写一个 MCP server
或安装 CLI 工具"] B -->|否| H{"操作本地文件？"} H -->|是| I["用 Built-in Tool
Read / Write / Edit / Grep"] H -->|否| J{"要教 AI 遵循特定流程？"} J -->|是| J2{"需要独立 context 或并行？"} J2 -->|是| J3["写一个 Custom Agent"] J2 -->|否| K["写一个 Skill
（Markdown 指令文件）"] J -->|否| M{"要在特定时刻自动执行？"} M -->|是| N["配置 Hook"] M -->|否| L["用 Built-in Tool
WebSearch / Task / LSP 等"] style D fill:#c8e6c9 style F fill:#fff9c4 style I fill:#bbdefb style K fill:#f3e5f5 style J3 fill:#e1bee7 style N fill:#ffe0b2 style L fill:#bbdefb ``` 简化版： | 需求 | 选择 | | --------------------- | ----------------------------------- | | 读/写/搜索本地文件 | Built-in（Read / Edit / Grep / Glob） | | 连接外部系统且有 MCP server | MCP Tool | | 连接外部系统但没有 MCP server | Bash + CLI | | 教 AI 按特定流程做事 | Skill（Markdown 文件） | | 需要独立 context 或并行的专家任务 | Custom Agent | | 在特定时刻自动执行（格式化、拦截等） | Hook | | 搜索互联网 | Built-in（WebSearch / WebFetch） | | 代码智能分析（跳转定义、查引用） | Built-in（LSP） | *** ## 附录 ### A. MCP Server 安装配置示例 MCP server 在 AI 助手的配置文件中声明。以 Claude Code 的 `~/.claude/settings.json` 为例： ```json { "mcpServers": { "Neon": { "command": "npx", "args": ["-y", "@neondatabase/mcp-server-neon"], "env": { "NEON_API_KEY": "your-api-key" } }, "lark-mcp": { "command": "npx", "args": ["-y", "@larksuiteoapi/lark-mcp", "--appId=xxx", "--appSecret=xxx"] }, "meegle": { "type": "url", "url": "https://project.larksuite.com/mcp_server/v1" } } } ``` - `command` + `args` = 怎么启动这个 server 子进程（stdio transport） - `env` = 传给子进程的环境变量（API key 等） - `type: "url"` = 远程 server，不启动子进程，直接 HTTP 连接（HTTP transport） ### B. MCP 2025-11 Spec 新增特性 | 特性 | 说明 | | --------------------- | ------------------------------------------- | | **Elicitation** | Server 主动向用户收集信息（Form + URL 两种模式） | | **Tool Annotations** | 标记 tool 是否只读、破坏性、幂等 | | **Structured Output** | Tool 返回带 schema 验证的结构化 JSON（`outputSchema`） | | **Icons** | Server / Tool / Resource 可带图标 | | **Async Tasks** | 长时间操作的异步执行支持 | | **Server Identity** | 服务端身份验证，防恶意 server | | **Auth Extensions** | 官方 OAuth 2.1 认证标准 | | **Streamable HTTP** | 替代旧的 SSE（原因见下方折叠） | ::: details 为什么用 Streamable HTTP 替代 SSE 旧版 MCP 用 SSE（Server-Sent Events）做远程传输，有三个问题： 1. **双端口问题**。Client → Server 用 HTTP POST，Server → Client 用 SSE 长连接。两个独立通道，部署和防火墙配置复杂 2. **有状态**。SSE 要求保持长连接，server 必须记住每个 client 的 session。无法水平扩展（加机器就丢 session） 3. **基础设施不友好**。很多 CDN、负载均衡器对 SSE 支持不好，会提前断开连接 Streamable HTTP 合并为单一 HTTP 端点。Server 可以选择返回普通 JSON（无状态）或升级为 SSE stream（需要推送时）。这让 MCP server 能像普通 REST API 一样部署在 Cloudflare Workers、Vercel 等 serverless 平台上。 ::: ### B+. MCP 2026 Roadmap MCP 2025-11-25 spec 仍为当前最新稳定版。社区和核心团队正在推进的方向： | 特性 | 状态 | 说明 | | -------------------- | --- | ------------------------- | | **MCP Apps** | 提案中 | 将 MCP server 打包为可独立分发的应用 | | **Server Discovery** | 提案中 | 自动发现和注册 MCP server，无需手动配置 | | **Tasks primitive** | 提案中 | 长时间运行任务的标准化管理（进度、取消、恢复） | ### C. 参考资源 | 资源 | 链接 | | ------------------------ | -------------------------------------------------------------------------------------------------------- | | MCP 官方 Spec (2025-11-25) | [modelcontextprotocol.io/specification](https://modelcontextprotocol.io/specification/2025-11-25) | | MCP GitHub | [github.com/modelcontextprotocol](https://github.com/modelcontextprotocol) | | Claude Code 官方文档 | [docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code/overview) | | skills.sh 注册表 | [skills.sh](https://skills.sh/) | | Anthropic Skills 仓库 | [github.com/anthropics/skills](https://github.com/anthropics/skills) | | Claude Code Plugins 指南 | [docs.anthropic.com/en/docs/claude-code/plugins](https://docs.anthropic.com/en/docs/claude-code/plugins) |