Claude Code 外部扩展

前置知识

阅读本文前，建议先了解：

• 02-Claude Code 基础使用 - 掌握基础使用技巧
• 03-Claude Code 核心功能 - 理解 CLAUDE.md、权限系统

---

一、扩展系统概览

Claude Code 的强大之处在于其可扩展性。通过四种扩展机制，可以大幅增强 Claude 的能力：

┌─────────────────────────────────────────┐
│       Claude Code 扩展生态系统           │
├─────────────────────────────────────────┤
│  MCP 服务器   → 连接外部工具和数据源      │
│  Hooks        → 自动化生命周期事件       │
│  Subagents    → 隔离的专业工作者         │
│  Skills       → 可重用的工作流模板        │
└─────────────────────────────────────────┘

扩展类型	作用	上下文成本
MCP 服务器	连接外部服务（数据库、API、工具）	每个请求
Hooks	在特定事件触发确定性脚本	零成本
Subagents	隔离上下文的专业工作者	隔离
Skills	可重用的提示模板/工作流	低（仅描述）

---

二、MCP 服务器（Model Context Protocol）

2.1 什么是 MCP

MCP（Model Context Protocol） 是连接 Claude 与外部工具/数据源的开放标准。

[!比喻] MCP 像什么？ 如果把 Claude 比作一个”博学的人”，MCP 就是给他的”外部工具箱”——通过 MCP，Claude 可以操作数据库、发送消息、控制浏览器等。

┌─────────────────────────────────────────┐
│          MCP 的作用                     │
├─────────────────────────────────────────┤
│ • 连接外部服务（数据库、API、工具）       │
│ • 扩展 Claude 的能力边界                 │
│ • 标准化的协议接口                       │
└─────────────────────────────────────────┘

2.2 配置位置与优先级

文件	作用域	是否提交
.claude/.mcp.local.json	项目级（本地）	❌ gitignore
.claude/.mcp.json	项目级	✅ 提交到仓库
~/.claude/.mcp.json	用户级	个人配置

┌─────────────────────────────────────────┐
│     MCP 服务器优先级（高 → 低）           │
├─────────────────────────────────────────┤
│ 1. 本地 (.mcp.local.json)               │
│ 2. 项目级 (.mcp.json)                   │
│ 3. 用户级 (~/.claude/.mcp.json)         │
└─────────────────────────────────────────┘

2.3 配置示例

基本配置结构：

{
  "mcp": {
    "servers": {
      "server-name": {
        "type": "stdio",
        "command": "npx",
        "args": ["@modelcontextprotocol/server-name"],
        "env": {
          "API_KEY": "${API_KEY}"
        }
      }
    }
  }
}

完整配置示例：

{
  "mcp": {
    "servers": {
      "github": {
        "type": "http",
        "url": "https://api.github.com/mcp",
        "headers": {
          "Authorization": "Bearer ${GITHUB_TOKEN}"
        }
      },
      "postgres": {
        "type": "stdio",
        "command": "npx",
        "args": ["@modelcontextprotocol/server-postgres"],
        "env": {
          "DATABASE_URL": "${DATABASE_URL}"
        }
      },
      "slack": {
        "type": "sse",
        "url": "http://localhost:3000/sse"
      },
      "filesystem": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
        "env": {}
      }
    }
  }
}

2.4 服务器类型

类型	说明	适用场景
stdio	本地进程通信	本地工具、CLI 命令
http	远程 HTTP 服务器	云服务、API
sse	Server-Sent Events	实时流式连接

stdio 示例：

{
  "postgres": {
    "type": "stdio",
    "command": "npx",
    "args": ["@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "${DATABASE_URL}"
    }
  }
}

http 示例：

{
  "github": {
    "type": "http",
    "url": "https://api.github.com/mcp",
    "headers": {
      "Authorization": "Bearer ${GITHUB_TOKEN}"
    }
  }
}

sse 示例：

{
  "slack": {
    "type": "sse",
    "url": "http://localhost:3000/sse"
  }
}

2.5 常用 MCP 服务器

官方服务器：

服务器	功能	安装命令
filesystem	文件系统访问	npx @modelcontextprotocol/server-filesystem
postgres	PostgreSQL 数据库	npx @modelcontextprotocol/server-postgres
git	Git 操作	npx @modelcontextprotocol/server-git
memory	知识图谱记忆	npx @modelcontextprotocol/server-memory

第三方服务器：

服务器	功能
GitHub	代码审查、Issue 跟踪
Slack	团队沟通
Sentry	错误监控
Google Drive	文档访问
Notion	知识库管理
Playwright	浏览器自动化

2.6 环境变量与安全

MCP 配置中可以使用环境变量：

{
  "github": {
    "type": "http",
    "url": "https://api.github.com/mcp",
    "headers": {
      "Authorization": "Bearer ${GITHUB_TOKEN}"
    }
  }
}

设置环境变量：

# macOS / Linux
export GITHUB_TOKEN=your_token_here
 
# Windows PowerShell
$env:GITHUB_TOKEN="your_token_here"

安全建议

• ✅ 使用 .mcp.local.json 存储敏感配置
• ✅ 使用环境变量引用密钥
• ✅ 在 .gitignore 中包含 .mcp.local.json
• ❌ 避免直接在 .mcp.json 中硬编码密钥
• ❌ 避免将包含密钥的文件提交到仓库

2.7 在 Subagent 中配置 MCP

Subagent 可以拥有独立的 MCP 配置：

---
name: browser-tester
description: 浏览器测试助手
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["@playwright/mcp@latest"]
---
 
你是一个浏览器测试专家，可以使用 Playwright 进行浏览器自动化测试。

2.8 工具延迟加载

MCP 工具定义默认被延迟加载，并通过工具搜索按需加载：

会话开始时：仅工具名称消耗上下文
    ↓
Claude 需要使用时：加载完整工具定义
    ↓
使用后：可清理出上下文

检查成本：

# 查看 MCP 服务器的上下文成本
/mcp

---

三、Hooks 自动化

3.1 什么是 Hooks

Hooks 是在 Claude Code 生命周期特定节点执行的确定性 Shell 命令。

[!比喻] Hooks 像什么？ Hooks 就像程序的”回调函数”——在特定事件发生时自动执行预定义的脚本，无需 LLM 参与。

┌─────────────────────────────────────────┐
│          Hooks 的特点                   │
├─────────────────────────────────────────┤
│ • 确定性执行（非 LLM）                   │
│ • 在特定事件触发时运行                   │
│ • 完全在循环外作为脚本运行               │
│ • 零上下文成本（除非返回额外内容）       │
└─────────────────────────────────────────┘

3.2 Hook 事件类型

事件	触发时机
SessionStart	会话开始/恢复时
UserPromptSubmit	Claude 处理提示之前
InstructionsLoaded	CLAUDE.md 加载时
PreToolUse	工具执行前（可阻止）
PostToolUse	工具执行成功后
PostToolUseFailure	工具执行失败后
PermissionRequest	权限请求时
Notification	等待用户输入时
SubagentStart / SubagentStop	子代理生命周期
Stop	Claude 完成响应时
ConfigChange	配置文件变更时
PreCompact / PostCompact	上下文压缩前后

3.3 配置示例

配置文件位置：

Hooks 配置在 settings.json 中：

{
  "hooks": {
    "事件名称": [
      {
        "matcher": "匹配条件",
        "hooks": [
          {
            "type": "command",
            "command": "要执行的命令"
          }
        ]
      }
    ]
  }
}

自动格式化（编辑后运行 Prettier）：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

桌面通知（Claude 等待输入时）：

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude 需要你的输入\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

阻止危险操作：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo $TOOL_INPUT | jq -r '.command' | grep -q 'rm -rf /' && echo 'BLOCKED' >&2 && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

3.4 Hook 类型

类型	说明	适用场景
command	运行 Shell 命令	文件操作、通知、自动化
http	POST 到端点	Webhook、外部服务通知
prompt	单次 LLM 评估	简单文本处理
agent	多轮验证（带工具）	复杂验证任务

command 类型示例：

{
  "type": "command",
  "command": "echo 'Hello from hook'"
}

http 类型示例：

{
  "type": "http",
  "url": "https://your-webhook.com/endpoint",
  "method": "POST",
  "body": {
    "event": "${EVENT_NAME}",
    "data": "${TOOL_INPUT}"
  }
}

3.5 退出码

退出码	含义
0	允许操作继续
2	阻止操作（stderr 输出原因）

阻止操作示例：

{
  "type": "command",
  "command": "echo '此操作被禁止' >&2 && exit 2"
}

3.6 Matcher 匹配器

Matcher 用于过滤特定工具或事件：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [...]
      },
      {
        "matcher": "Bash",
        "hooks": [...]
      }
    ]
  }
}

常用匹配模式：

模式	匹配内容
Edit	文件编辑操作
Write	文件写入操作
Bash	Shell 命令执行
Read	文件读取操作
Edit|Write	编辑或写入（正则或）

3.7 调试 Hooks

# 启用调试日志
export CLAUDE_DEBUG_HOOKS=1
 
# 查看已配置的 Hooks
/hooks

---

四、Subagents 子代理

4.1 什么是 Subagents

Subagents（子代理） 是在隔离的上下文中运行自己的循环，返回摘要的独立工作者。

[!比喻] Subagents 像什么？ 如果把主 Claude 比作”项目经理”，Subagents 就是”专业工人”——项目经理分配任务给工人，工人独立完成工作后返回结果摘要。

┌─────────────────────────────────────────┐
│          Subagents 的特点               │
├─────────────────────────────────────────┤
│ • 独立的上下文窗口                      │
│ • 与主对话隔离执行                      │
│ • 仅返回摘要到主会话                     │
│ • 可预加载特定的 Skills                  │
└─────────────────────────────────────────┘

4.2 内置子代理

代理	模型	用途
Explore	Haiku	只读代码探索，快速搜索
Plan	继承主模型	安全规划分析
General-purpose	继承主模型	多步骤复杂任务

使用内置子代理：

# 在会话中调用
/agents
 
# 或使用命令
> 使用 Explore 代理搜索代码
> 使用 Plan 代理分析架构

4.3 创建自定义子代理

存放位置：

位置	作用域	是否提交
.claude/agents/	项目级	✅ 提交到仓库
~/.claude/agents/	用户级	个人配置

创建方式：

# 方式一：使用 /agents 命令
/agents
# 跟随引导创建
 
# 方式二：手动创建文件
mkdir -p .claude/agents
touch .claude/agents/code-reviewer.md

子代理文件示例：

<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: 专业代码审查员，检查质量、安全和性能问题
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
permissionMode: plan
---
 
你是一个专业的代码审查员。审查代码时关注：
- 代码质量和可读性
- 安全漏洞（OWASP Top 10）
- 性能问题
- 测试覆盖率
- 错误处理完整性

4.4 配置字段详解

---
name: code-reviewer              # 代理名称
description: 专业代码审查员       # 描述
tools: Read, Grep, Glob, Bash    # 允许的工具
disallowedTools: Write, Edit     # 禁止的工具
model: sonnet                    # 使用的模型
permissionMode: plan             # 权限模式
skills:                          # 预加载的 skills
  - api-docs
  - security-guidelines
mcpServers:                      # MCP 服务器配置
  - playwright:
      type: stdio
      command: npx
      args: ["@playwright/mcp@latest"]
---

字段	说明	示例
name	代理名称（用于调用）	code-reviewer
description	描述（决定何时触发）	“专业代码审查员”
tools	允许使用的工具	Read, Grep, Glob
disallowedTools	禁止使用的工具	Write, Edit
model	使用的模型	sonnet, haiku
permissionMode	权限模式	plan, default
skills	预加载的 skills	api-docs
mcpServers	MCP 服务器配置	playwright

4.5 调用方式

# 方式一：使用代理名称
> 使用 code-reviewer 代理审查 src/api/auth.ts
 
# 方式二：@引用
> @"code-reviewer (agent)" 审查最近的代码变更
 
# 方式三：自然语言
> 让代码审查员检查一下这个文件

4.6 上下文隔离优势

主会话上下文有限？
    ↓
使用 Subagent 处理长任务
    ↓
Subagent 读取数十个文件
    ↓
主会话仅接收摘要
    ↓
主上下文不被消耗

适用场景：

场景	为什么用 Subagent
读取大量文件	不消耗主上下文
并行工作	多个子代理同时执行
专门任务	专业化配置和工具
长运行任务	后台执行，不影响主会话

4.7 Subagents vs Skills

方面	Skill	Subagent
它是什么	可重用的说明、知识或工作流	具有自己上下文的隔离工作者
关键优势	在上下文之间共享内容	上下文隔离，工作独立进行
最适合	参考材料、可调用的工作流	读取许多文件的任务、并行工作
上下文成本	低（仅描述）	隔离（不消耗主上下文）

4.8 Agent Teams（代理团队）

Agent Teams 协调多个独立的 Claude Code 会话，具有共享任务和点对点消息传递。

场景	说明
并行研究	多个代理同时研究不同方向
新功能开发	并行开发不同模块
调试	使用竞争假设进行调试

示例配置：

---
name: review-team
type: agent-team
members:
  - security-reviewer
  - performance-reviewer
  - test-reviewer
---
 
# 团队协作审查代码

---

五、Skills 自定义命令

5.1 什么是 Skills

Skills（技能） 是可重用的提示模板，通过斜杠命令调用。

[!比喻] Skills 像什么？ Skills 就像”快捷命令”或”宏”——把常用的工作流打包成一个命令，需要时一键调用。

┌─────────────────────────────────────────┐
│          Skills 的特点                  │
├─────────────────────────────────────────┤
│ • 可重用的说明、知识和工作流             │
│ • 通过斜杠命令调用（如 /deploy）         │
│ • 按需加载，降低上下文成本               │
│ • 可在主会话或子代理中运行               │
└─────────────────────────────────────────┘

5.2 创建 Skill

存放位置：

位置	作用域	是否提交
.claude/skills/	项目级	✅ 提交到仓库
~/.claude/skills/	用户级	个人配置

目录结构：

.claude/skills/
├── deploy/
│   └── SKILL.md       # /deploy 命令
├── review/
│   └── SKILL.md       # /review 命令
└── api-docs/
    └── SKILL.md       # /api-docs 命令

创建步骤：

# 1. 创建目录
mkdir -p .claude/skills/deploy
 
# 2. 创建 Skill 文件
touch .claude/skills/deploy/SKILL.md
 
# 3. 编辑内容
vim .claude/skills/deploy/SKILL.md

5.3 Skill 文件结构

基本结构：

---
name: deploy
description: 部署应用到生产环境
allowed-tools: Bash, Read
---
 
按以下步骤部署应用：
1. 运行测试：`npm test`
2. 构建项目：`npm run build`
3. 部署：`npm run deploy`
4. 验证部署状态

前置字段详解：

字段	说明	示例
name	斜杠命令名称	deploy
description	描述（决定何时触发）	“部署应用到生产环境”
allowed-tools	限制可用工具	Bash, Read
disable-model-invocation	仅手动调用时设为 true	true
user-invocable	隐藏菜单时设为 false	false
context: fork	在子代理中运行	fork

完整示例（代码审查 Skill）：

---
name: code-review
description: 专业代码审查，检查质量和安全问题
allowed-tools: Read, Grep, Glob, Bash
disable-model-invocation: false
---
 
# 代码审查流程
 
## 1. 收集信息
 
- 使用 Glob 查找变更的文件
- 使用 Git diff 查看具体变更
 
## 2. 审查要点
 
### 代码质量
- 命名是否清晰
- 函数是否过长
- 是否有重复代码
 
### 安全性
- 输入验证
- SQL 注入风险
- 敏感信息泄露
 
### 性能
- 时间复杂度
- 不必要的循环
- 内存泄漏风险
 
## 3. 输出报告
 
按以下格式输出审查报告：
 
## 审查结果
 
### ✅ 优点
- ...
 
### ⚠️ 建议改进
- ...
 
### ❌ 必须修复
- ...
 
### 5.4 动态内容
 
在 Skill 中嵌入命令输出：
 
---
name: pr-summary
description: 生成 PR 摘要
---
 
# PR 变更摘要
 
## 当前 PR 变更
 
!\`gh pr diff\`
 
## PR 评论
 
!\`gh pr view --comments\`
 
## 审查清单
 
- [ ] 代码质量检查通过
- [ ] 测试覆盖完整
- [ ] 文档已更新
 
**调用方式：**
 
# 调用 Skill
/pr-summary
 
# Claude 会自动执行嵌入的命令并输出结果

5.5 调用方式

斜杠命令调用：

# 基本调用
/deploy
 
# 带参数调用
/deploy production
 
# 带焦点调用
/deploy focus on the API changes

@引用调用：

# @引用 Skill
@deploy
 
# 描述性调用
@skill-name 执行部署

自动触发：

当用户请求与 Skill 描述匹配时，Claude 可能自动触发：

用户：帮我部署到生产环境
      ↓
Claude 自动调用 /deploy Skill

5.6 运行上下文

配置	运行位置	说明
默认	主会话	在当前上下文中运行
context: fork	子代理	在隔离上下文中运行

在子代理中运行：

---
name: deep-analysis
description: 深度分析代码库
context: fork
---
 
这是一个需要读取大量文件的任务，在子代理中运行以避免消耗主上下文。

5.7 Skills vs 其他功能

Skills vs CLAUDE.md：

方面	CLAUDE.md	Skills
加载时机	每次会话自动加载	按需调用
内容类型	项目约定、始终规则	参考材料、工作流
上下文成本	每个请求	低（仅描述）
适用场景	”始终执行 X"	"需要时执行 Y”

Skills vs Subagents：

方面	Skills	Subagents
本质	可重用的内容	隔离的工作者
执行位置	主会话（默认）	独立上下文
最适合	参考、工作流	读取大量文件
组合	Skill 可以启动 Subagent	Subagent 可以预加载 Skills

5.8 Plugin Skills

Plugin 是打包层，将 skills、hooks、subagents 和 MCP servers 捆绑到单个可安装单元。

Plugin Skills 是命名空间的：
    ↓
/my-plugin:review
    ↓
避免多个 plugins 之间的名称冲突

Plugin 结构：

plugin/
├── skills/
│   └── review/
│       └── SKILL.md
├── hooks/
│   └── hooks.json
└── plugin.json

5.9 Skill 优先级

┌─────────────────────────────────────────┐
│     Skill 优先级（高 → 低）              │
├─────────────────────────────────────────┤
│ 1. 托管（Hosted）                       │
│ 2. 用户级（~/.claude/skills/）          │
│ 3. 项目级（.claude/skills/）            │
│ 4. Plugin（命名空间）                   │
└─────────────────────────────────────────┘

---

六、组合使用模式

6.1 MCP + Skills

MCP 提供连接 → Skill 教导如何使用

示例：
- MCP 连接到数据库
- Skill 记录架构和查询模式

配置示例：

{
  "mcp": {
    "servers": {
      "postgres": {
        "type": "stdio",
        "command": "npx",
        "args": ["@modelcontextprotocol/server-postgres"],
        "env": {
          "DATABASE_URL": "${DATABASE_URL}"
        }
      }
    }
  }
}

配合 Skill 使用：

---
name: db-query
description: 数据库查询助手
---
 
# 数据库架构
 
## users 表
- id: UUID
- name: STRING
- email: STRING
 
## 查询示例
SELECT * FROM users WHERE email = '...'

6.2 Hooks + MCP

Hook 触发 → MCP 执行外部操作

示例：
- 编辑后 Hook 触发
- 通过 MCP 发送 Slack 通知

配置示例：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.slack.com/services/xxx",
            "body": {
              "text": "文件被修改：${TOOL_INPUT.file_path}"
            }
          }
        ]
      }
    ]
  }
}

6.3 Skills 生成 Subagents

/audit skill
    ↓
启动安全性、性能、风格 subagents
    ↓
每个 subagent 在隔离上下文中工作
    ↓
返回各自的摘要

---

七、最佳实践

7.1 MCP 设计原则

原则	说明
使用本地配置存储敏感信息	.mcp.local.json 不提交
使用环境变量	避免硬编码密钥
按需加载	利用工具延迟加载降低成本
专用 Subagent	为特定 MCP 任务创建子代理

7.2 Hooks 设计原则

原则	说明
保持简单	Hook 应该是确定性的、快速的
避免 LLM	除非必要，否则使用 command 类型
错误处理	使用退出码 2 阻止危险操作
日志记录	输出到 stderr 便于调试

推荐场景：

场景	推荐 Hook
自动格式化	PostToolUse (Edit/Write)
桌面通知	Notification
阻止危险命令	PreToolUse (Bash)
会话日志	SessionStart / Stop
自动提交	PostToolUse (多次编辑后)

7.3 Subagent 设计原则

原则	说明
专注单一职责	每个子代理做好一件事
限制工具使用	只授予必要的工具权限
明确输出格式	定义清晰的摘要格式
预加载 Skills	为子代理配置相关知识

推荐子代理：

代码审查员（code-reviewer）
    - 检查代码质量
    - 安全漏洞
    - 性能问题

测试编写员（test-writer）
    - 生成单元测试
    - 集成测试
    - E2E 测试

文档生成器（doc-generator）
    - API 文档
    - README 更新
    - 变更日志

安全审计员（security-auditor）
    - 安全漏洞扫描
    - 依赖检查
    - 配置审计

7.4 Skill 设计原则

原则	说明
单一职责	每个 Skill 做好一件事
清晰描述	描述决定何时自动触发
限制工具	只授予必要的工具权限
结构化输出	定义清晰的输出格式

推荐 Skills：

/deploy          - 部署工作流
/review          - 代码审查
/test            - 测试生成
/api-docs        - API 文档参考
/release         - 发布流程
/migrate         - 数据库迁移

---

八、总结

扩展系统对比

┌─────────────────────────────────────────┐
│       扩展系统快速对比                  │
├─────────────────────────────────────────┤
│ MCP         → 连接外部工具和数据源       │
│ Hooks       → 自动化生命周期事件         │
│ Subagents   → 隔离的专业工作者           │
│ Skills      → 可重用的工作流模板          │
└─────────────────────────────────────────┘

核心要点

1. MCP 服务器：连接外部服务，支持 stdio/http/sse 三种类型
2. Hooks 自动化：确定性脚本，零上下文成本，12+ 种事件可触发
3. Subagents 子代理：隔离上下文，专业化配置，可预加载 Skills 和 MCP
4. Skills 自定义命令：可重用工作流，斜杠命令调用，按需加载
5. 组合使用：四种扩展可以互相配合，发挥最大效能

---

延伸阅读

• 编程开发（Claude Code） - 返回总览
• 02-Claude Code 基础使用 - 基础使用与配置
• 03-Claude Code 核心功能 - CLAUDE.md、权限、Memory
• 05-Claude Code 进阶使用 - 高级功能与最佳实践
• 模型上下文协议 MCP - MCP 协议详解