AI 编程助手工具体系指南

AI 编程助手（Claude Code、Cursor、Copilot 等）在帮你写代码时，背后调用了多种不同来源的工具。本文从工程师视角系统讲解这些工具的分类、协议原理和选择逻辑，帮你从"能用"到"理解为什么这样设计"。

本文用到的基础术语（已熟悉可跳过）

术语	含义
进程（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    │  mkdocs build      │
│  WebSearch       │  create_branch   │  npm test          │
├──────────────────┼──────────────────┼────────────────────┤
│  进程内直接执行    │  JSON-RPC 协议    │  子进程执行 shell    │
│  最快、最安全     │  结构化、可扩展    │  万能、风险最高      │
└──────────────────┴──────────────────┴────────────────────┘

表中出现的 JSON-RPC 是 MCP 使用的通信格式，§3.3 会详细讲解。

还有一个经常被混淆的概念：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 解决什么问题

每个 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

这三个不是抽象概念，是你电脑上真实运行的进程（不熟悉"进程"概念可回看文章开头的术语表）：

你在终端敲: 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 负责把订单翻译成每个厨房能理解的格式。

用 Activity Monitor 验证

在 macOS 上打开 Activity Monitor，搜索 claude，可以看到主进程（Host）。搜索 npx 或 MCP server 名称，可以看到各个 server 子进程。这能帮你直观验证"1 个 Host + N 个 Server"的进程模型。

3.3 通信基础：JSON-RPC

所有 MCP 消息都用 JSON-RPC 2.0 格式。只有三种消息类型：

Request（请求）。要求对方做事，等回复：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run_sql",
    "arguments": { "sql": "SELECT * FROM users LIMIT 5" }
  }
}

Response（响应）。回复请求结果：

{ "jsonrpc": "2.0", "id": 1, "result": { "content": [{"type": "text", "text": "..."}] } }

Notification（通知）。单向消息，不需要回复（没有 id 字段）：

{ "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 完全由用户主动触发，是最安全的。

Resources 的高级特性

Resource Templates。URI 支持模板语法（如 db:///{table}/schema），客户端动态填充参数，避免 server 注册海量静态 URI。

Subscriptions。Client 可以订阅特定 resource。当 resource 内容变化时，server 推送 notifications/resources/updated，client 自动重新获取。适用于数据库 schema、配置文件等会变的数据。

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 操作范围：

{ "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 只知道"授权成功了"。

AskUserQuestion vs Elicitation

两者都是"向用户提问"，但发起者和协议不同：

维度	AskUserQuestion	Elicitation
发起者	AI 模型（LLM 决定要问）	MCP Server（外部程序决定要问）
协议	Built-in tool 调用	MCP JSON-RPC elicitation/create
适用场景	AI 需要澄清需求	Server 需要运行时配置（环境、分支等）
示例	"你想用 OAuth 还是 JWT？"	"请选择部署目标环境"

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。

什么是 stdin/stdout 管道

每个进程都有两个内置的文本通道：

• stdin（standard input）：进程的"耳朵"，用来接收输入
• stdout（standard output）：进程的"嘴巴"，用来输出结果

当 Host 启动 MCP server 子进程时，会建立一条管道（pipe）：Host 写数据到 server 的 stdin，server 写结果到自己的 stdout，Host 读取。就像两个人通过一根管子传纸条。

3.7 一次 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) — 万能后备

当没有 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 "mkdocs 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 一个工作流程：

---
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：当遇到某种任务时，应该按什么步骤、用什么工具来完成。

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。

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

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 运行日志

完整事件列表

除上述 6 个常用事件外，还有：SessionStart（会话开始）、SessionEnd（会话结束）、SubagentStart（子 agent 启动）、PostToolUseFailure（工具执行失败后）、PermissionRequest（权限请求时）、PreCompact（context 压缩前）等，共计 17 个生命周期事件。完整列表参见 Claude Code 官方文档。

7.3 配置示例

Hook 在 settings.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，声明元数据：

{
  "name": "my-plugin",
  "description": "A plugin that adds code review capabilities",
  "version": "1.0.0",
  "author": "your-name"
}

组件不在清单中声明，而是按目录约定自动发现：

目录结构示例

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/<project>/CLAUDE.md	项目级私有	否（个人偏好）

三层指令叠加生效，不互相覆盖。

9.2 Auto-memory

Claude Code 还有一个自动记忆目录：~/.claude/projects/<project>/memory/。其中 <project> 由项目路径派生（如 -Users-maxwsy-workspace-docs）。

AI 在工作过程中自动学习并记住：项目结构、调试经验、用户偏好、架构决策。这些记忆跨 session 持久化，下次对话时 AI 已经"认识"你的项目。

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 调用创建一个临时子进程

常见误解

查 2 个 AWS 资源 ≠ 启动 2 个 MCP server。Bash 子进程是临时的，跑完就销毁。MCP server 才是常驻进程。两者本质不同，参见第四章。

场景 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 使用时才创建，跑完就销毁）    │
└────────────────────────────────────────────────────────┘

---

十一、选择决策树

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e8eaf6', 'lineColor': '#666'}}}%%
flowchart TD
    A["我要让 AI 做一件事"] --> B{"需要连接外部系统？<br/>数据库/API/第三方服务"}
    B -->|是| C{"有对应的 MCP server？"}
    C -->|有| D["用 MCP Tool"]
    C -->|没有| E{"系统上有对应的 CLI？"}
    E -->|有| F["用 Bash 执行 CLI"]
    E -->|没有| G["需要写一个 MCP server<br/>或安装 CLI 工具"]
    B -->|否| H{"操作本地文件？"}
    H -->|是| I["用 Built-in Tool<br/>Read / Write / Edit / Grep"]
    H -->|否| J{"要教 AI 遵循特定流程？"}
    J -->|是| J2{"需要独立 context 或并行？"}
    J2 -->|是| J3["写一个 Custom Agent"]
    J2 -->|否| K["写一个 Skill<br/>（Markdown 指令文件）"]
    J -->|否| M{"要在特定时刻自动执行？"}
    M -->|是| N["配置 Hook"]
    M -->|否| L["用 Built-in Tool<br/>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 为例：

{
  "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（原因见下方折叠）

为什么用 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
MCP GitHub	github.com/modelcontextprotocol
Claude Code 官方文档	docs.anthropic.com/en/docs/claude-code
skills.sh 注册表	skills.sh
Anthropic Skills 仓库	github.com/anthropics/skills
Claude Code Plugins 指南	docs.anthropic.com/en/docs/claude-code/plugins