第 3 章 Claude Code 安装与配置
- 说明 Claude Code 的核心功能与工作模式
- 完成 环境配置和 API 连接的独立配置
- 应用 /clear、/compact、/resume 进行会话管理
- 创建 并配置 CLAUDE.md 项目文件
- 配置 自定义命令、技能与智能体
- 理解 MCP 协议的基本概念并完成初步配置
在前两章中，我们认识了智能体的基本概念，也学习了 Vibe Coding 的协作理念。现在，是时候动手实践了。本章将带你完成 Claude Code 的安装配置，掌握会话管理技巧，学会通过 CLAUDE.md、Skills 和 MCP 协议扩展智能体能力。
3.1 环境配置与安装
3.1.1 系统要求与准备
开始安装前，检查你的系统是否满足这些要求。
操作系统要求
| 操作系统 | 最低版本 | 备注 |
|---|---|---|
| macOS | 10.15 及以上 | 推荐 macOS 12+ |
| Windows | Windows 10 及以上 | 原生支持 |
| Linux | Ubuntu 20.04+ | 其他发行版需自行测试 |
软件依赖
- Node.js 18.0.0 或更高版本（推荐 v20.x LTS）
- npm 8.0.0 或更高版本（随 Node.js 安装）
- Git（用于版本控制）
硬件要求
- 内存：至少 4GB RAM
- 存储：至少 500MB 可用空间
- 网络：稳定的互联网连接
账户要求
你需要以下账户之一：
- Claude Pro / Max / Teams / Enterprise 订阅账户（推荐）
- Anthropic Console 账户（API 方式，需预充值）
Claude 订阅账户与 API 账户有何不同？订阅账户按月付费，使用体验更流畅；API 账户按调用量计费，适合开发和集成场景。初学者推荐使用订阅账户。
3.1.2 安装 Node.js 和 Git
检查现有版本
打开终端（macOS/Linux）或 PowerShell（Windows），运行：
# 检查 Node.js 版本
node --version
# 检查 npm 版本
npm --version
# 检查 Git 版本
git --version如果 Node.js 版本低于 18 或未安装，按以下方式安装。
macOS 用户
使用 Homebrew 安装：
# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 Node.js
brew install node
# 安装 Git
brew install gitWindows 用户
- 访问 Node.js 官网
- 下载 LTS 版本安装包
- 运行安装程序，按提示完成安装
- 安装 Git for Windows
- 关闭并重新打开 PowerShell（重启后 PATH 才会生效）
- 验证安装：
node --version和git --version
Linux 用户（Ubuntu/Debian）
# 使用 NodeSource 安装 Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs git3.1.3 安装 Claude Code
Claude Code 提供多种安装方式，选择适合你的方法。
方式一：原生安装（推荐）
原生安装最简单，支持自动更新。
macOS/Linux：
curl -fsSL https://claude.ai/install.sh | sh或使用 Homebrew（macOS）：
brew install anthropic/tap/claude-codeWindows PowerShell（管理员模式）：
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd或使用 WinGet：
winget install Anthropic.ClaudeCode方式二：npm 全局安装
如果你更熟悉 npm：
npm install -g @anthropic-ai/claude-code验证安装
claude --version看到版本号输出，说明安装成功。
3.1.4 首次登录与认证
安装完成后，首次运行需要登录认证。
# 进入你的项目目录（或创建一个测试目录）
mkdir ~/claude-code-lab
cd ~/claude-code-lab
# 启动 Claude Code
claude首次运行时，系统会打开浏览器引导你登录：
- 使用你的 Claude 账户登录
- 授权 Claude Code 访问你的账户
- 登录成功后，回到终端继续使用
登录凭据存储在 ~/.claude.json（macOS/Linux）或 %APPDATA%\.claude.json（Windows），使用系统密钥链加密。请勿将此文件分享或提交到版本控制。
测试 API 连接
在 Claude Code 中输入：
你好，请简单介绍一下自己如果 Claude 正常回复，说明 API 连接成功。
运行健康检查
/doctor这个命令会诊断系统状态，帮你发现潜在问题。
3.1.5 中国用户网络配置
在中国大陆使用 Claude Code，可能需要额外的网络配置。
npm 镜像源配置
如果 npm 安装速度慢：
# 临时使用淘宝镜像
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
# 或永久设置镜像源
npm config set registry https://registry.npmmirror.com网络代理配置
如果需要通过代理访问：
# macOS/Linux - 在 ~/.zshrc 或 ~/.bashrc 中添加
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
# Windows PowerShell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"3.1.6 API 密钥安全
API 密钥是访问 Claude API 的关键凭证，务必妥善保管。
基本安全原则
- 不要公开分享 —— 不要提交到 Git，不要在社交媒体展示
- 使用环境变量 —— 不要硬编码到代码文件里
- 定期轮换 —— 如怀疑泄露，立即吊销并生成新密钥
推荐做法
将 API 密钥存储在环境变量中：
# macOS/Linux - 在 ~/.zshrc 或 ~/.bashrc 中添加
export ANTHROPIC_API_KEY="你的API密钥"
# 使配置生效
source ~/.zshrc在 .gitignore 中排除敏感文件：
.env
.env.local
*.key对经济金融专业学生来说，API 密钥管理类似银行密码管理：
- 不要在微信群、GitHub 等公开场合展示
- 定期更换（类似银行卡密码）
- 发现泄露立即吊销（类似挂失）
密钥泄露后的处理
- 立即登录 Anthropic Console
- 吊销泄露的密钥
- 生成新密钥并更新配置
- 检查使用日志，确认是否有异常调用
3.1.7 常见问题排查
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
command not found: claude |
PATH 未配置 | 重启终端，或手动添加到 PATH |
| 权限错误（EACCES） | npm 目录权限问题 | sudo chown -R $(whoami) /usr/local/lib/node_modules |
| 认证失败 | 凭据过期 | 运行 claude logout 后重新 claude |
| 连接超时 | 网络问题 | 检查代理配置 |
3.2 会话管理与工作模式
掌握会话管理是高效使用 Claude Code 的关键。本节介绍会话的生命周期、核心命令和三种工作模式。
3.2.1 理解上下文窗口
在深入会话管理之前，我们需要理解一个核心概念：上下文窗口（Context Window）。
上下文窗口就像人的工作记忆 —— 模型在单次推理时能处理的信息量。Claude 的上下文窗口约有 200K tokens，但这个容量并非越满越好。
什么是 token？token 是模型处理文本的基本单位。英文中，一个单词通常是 1-2 个 tokens；中文中，一个汉字通常是 1-2 个 tokens。200K tokens 大约相当于一本 300 页的书。
上下文腐化问题
研究发现，当上下文过长时，模型性能会下降，这种现象称为上下文腐化（Context Rot）。具体表现为：
- 信息埋在中间时容易被忽略（中间迷失问题）
- 随着输入长度增加，响应质量下降
- 干扰信息会放大模型的困惑
什么是「中间迷失问题」？想象你在读一篇 100 页的论文，开头和结尾印象深刻，但中间部分容易遗忘。模型也有同样问题 —— 对话太长时，中间的重要信息容易被忽略。这就是为什么要用 /compact 压缩上下文。
这就是为什么我们需要主动管理上下文 —— 不是填满它，而是保持它精简、相关。
3.2.2 会话生命周期
启动会话
# 基本启动：在当前目录启动新会话
claude
# 带提示启动：直接开始一个任务
claude "分析这个项目的架构"
# 使用特定模型启动
claude --model opus会话存储
Claude Code 自动保存每个会话：
- 存储位置：
~/.claude/projects/目录 - 存储格式：JSONL 格式
- 默认保留期：30 天
结束会话
# 正常退出
/exit
# 或按 Ctrl+C3.2.3 五个核心会话命令
掌握这五个命令，你就能高效管理会话。
/clear —— 清除上下文
功能：完全清除当前对话历史，从空白状态重新开始。
/clear使用场景：
- 完成一个任务后，开始不相关的新任务
- 上下文被无关信息污染时
- 想要完全重置对话状态
注意：这是破坏性操作，清除后无法恢复。
/compact —— 压缩上下文
功能：将当前对话压缩为更短的摘要，保留重要信息，释放上下文空间。
/compact使用场景：
- 长时间会话后，上下文接近 70%
- 想保留对话连续性但减少占用
- 在开始大型任务之前
与 /clear 的区别：
| 特性 | /clear | /compact |
|---|---|---|
| 保留上下文 | 否 | 是（压缩形式） |
| 破坏性 | 是 | 否 |
| 适用场景 | 切换无关任务 | 继续相关任务 |
/resume —— 恢复会话
功能：恢复之前保存的会话。
# 交互式选择器
/resume
# 按名称恢复
/resume api-migration命令行方式：
claude --resume # 打开选择器
claude -c # 继续最近的会话
claude --resume auth-refactor # 按名称恢复/rename —— 命名会话
功能：给当前会话一个有意义的名称，方便日后查找。
/rename 金融数据分析-v2命名建议：
- 使用「项目名-功能模块」格式
- 包含版本号便于区分迭代
- 保持简洁但有辨识度
/export —— 导出对话
功能：将整个对话导出为 Markdown 格式。
/export用途：复盘开发过程、编写文档、分享给团队。
3.2.4 三种工作模式
Claude Code 提供三种工作模式，通过 Shift+Tab 循环切换。
Normal Mode（默认模式）
特点：所有操作需要手动确认，最安全。
适用场景：
- 新手学习阶段
- 不熟悉的代码库
- 敏感操作
UI 显示：无特殊标识
Auto-Accept Mode（自动接受模式）
特点：自动执行文件编辑，无需逐步确认，效率最高。
适用场景：
- 执行已确认的详细计划
- 大规模重构操作
- 长时间自动化任务
UI 显示：底部显示 auto-accept edit on
风险提示：没有确认提示，Claude 会立即执行所有更改。建议配合版本控制使用。
Plan Mode（规划模式）
特点：只读模式，只分析和规划，不修改文件系统。
适用场景：
- 复杂项目的前期规划
- 架构决策和技术选型
- 需要与 Claude 迭代讨论方向
UI 显示：底部显示 plan mode on
新手建议
- 第 1-2 周：只用 Normal Mode，熟悉 Claude 的工作方式
- 第 3-4 周：尝试 Plan Mode 做规划，然后切回 Normal Mode 执行
- 熟练后：在可控的重构任务中尝试 Auto-Accept Mode
使用 Auto-Accept Mode 前，务必：
- 确认当前目录已初始化 Git
- 所有重要修改已提交
- 了解如何用
git reset --hard回滚
推荐工作流
1. Plan Mode：分析问题、制定计划
2. Normal Mode：小范围修改、验证效果
3. Auto-Accept Mode：执行已确认的计划3.2.5 上下文管理策略
策略一：主动监控
注意终端右下角的 context left 指示器，当使用率达到 70% 时主动执行 /compact。
策略二：任务分组
将相关工作分组完成，避免在一个会话中混合太多不相关任务。每个会话专注单一目的。
策略三：定期清理
长时间调试会话中定期使用 /compact。新任务前使用 /clear 重置上下文。
长会话最佳实践
1. 开始时：/rename 给会话命名
2. 工作中：监控右下角上下文指示器
3. 70% 时：执行 /compact
4. 任务完成：/clear 或开始新会话
5. 需要返回：使用 /resume 恢复3.2.6 快捷键速查
| 快捷键 | 功能 |
|---|---|
Shift+Tab |
切换工作模式 |
Shift+M |
切换思考模式 |
Ctrl+C |
取消当前操作 |
Ctrl+L |
清屏（不清除上下文） |
↑ |
查看命令历史 |
Ctrl+R |
切换详细模式 |
3.3 CLAUDE.md 介绍与配置
CLAUDE.md 是 Claude Code 的核心配置文件 —— 给 AI 写的项目说明书。通过它，Claude 在每次会话开始时就能像一个熟悉项目的团队成员一样工作。
3.3.1 什么是 CLAUDE.md
CLAUDE.md 的核心作用：
- 帮助 Claude 快速理解项目结构和技术栈
- 跨会话保持一致的行为和风格
- 在团队间共享项目规范和最佳实践
- 减少重复解释，节省上下文空间
本质上，CLAUDE.md 是上下文工程的高杠杆点 —— 花 10 分钟配置，可以在之后每次对话中节省大量解释时间。
3.3.2 文件位置与层级
Claude Code 支持多层级的配置文件系统：
| 位置 | 路径 | 用途 | 适用场景 |
|---|---|---|---|
| 用户级 | ~/.claude/CLAUDE.md |
个人偏好设置 | 代码风格、个人工具 |
| 项目级 | ./CLAUDE.md |
团队共享指令 | 项目架构、编码规范 |
| 规则目录 | ./.claude/rules/*.md |
模块化规则 | 大型项目分类管理 |
| 本地私有 | ./CLAUDE.local.md |
个人项目偏好 | 测试 URL、本地配置 |
优先级：项目级 > 用户级。同名规则，项目配置覆盖个人配置。
加载机制
- Claude Code 从当前工作目录向上递归查找 CLAUDE.md
- 子目录中的 CLAUDE.md 仅在访问该目录文件时按需加载
.claude/rules/目录下的所有.md文件自动加载
3.3.3 推荐内容结构
最简 CLAUDE.md（适合快速上手）
## 这是什么项目
Python 量化回测系统，使用 pandas 分析股票数据。
## 常用命令
- `python main.py` - 运行回测
- `pytest tests/` - 运行测试
## 重要规则
- 金额用 Decimal，不要用 float
- 日期格式 YYYY-MM-DD
- 年化假设 252 个交易日这个 20 行的版本就能让 Claude 理解你的项目核心规范。需要更详细的配置时，再逐步扩充。
完整版结构
一个好的 CLAUDE.md 应该回答三个核心问题：
| 问题 | 内容类型 | 示例 |
|---|---|---|
| WHAT（是什么） | 技术栈、项目结构 | 这是一个使用 Python + FastAPI 的量化系统 |
| WHY（为什么） | 设计决策、约束 | 选择 PostgreSQL 是因为需要复杂查询 |
| HOW（怎么做） | 常用命令、工作流程 | 部署流程：先运行测试，再执行 deploy 脚本 |
推荐模板
## 项目概述
[项目名称] - [2 行简要描述]
技术栈：[框架/语言/数据库]
架构：[单体/微服务/Serverless]
## 常用命令
- `npm run dev` - 启动开发服务器
- `npm test` - 运行测试
- `npm run lint` - 代码检查
## 项目结构
- `/src` - 源代码
- `/tests` - 测试文件
- `/docs` - 文档
## 代码规范
- 使用 ES modules，不用 CommonJS
- 变量命名使用 camelCase
- 2 空格缩进
## 工作流程
- 完成代码修改后运行类型检查
- 优先运行单个测试而非整个测试套件
- 提交前确保通过 lint 检查
## 重要说明
- [Claude 需要特别注意的事项]3.3.4 金融项目 CLAUDE.md 示例
针对经济金融类项目，这里提供一个实用模板：
## 项目概述
量化交易策略回测系统 - 支持多因子策略的历史回测与风险分析
技术栈：Python, pandas, numpy, SQLite
架构：单体应用 + 模块化设计
## 数据说明
- 数据来源：Wind、东方财富 API
- 数据格式：CSV / Parquet
- 关键字段：date, open, high, low, close, volume
- 更新频率：日频
## 常用命令
- `python -m pytest tests/` - 运行测试
- `python scripts/data_update.py` - 更新数据
- `python main.py --backtest` - 回测策略
## 代码规范
- 遵循 PEP8 风格指南
- 金融计算使用 Decimal 类型，避免浮点误差
- 时间序列数据统一使用 UTC 时区
## 金融领域约定
- 收益率计算使用对数收益率：np.log(price_t / price_t-1)
- 年化计算假设 252 个交易日
- 风险指标包含：夏普比率、最大回撤、波动率
- 日期格式统一使用 YYYY-MM-DD
## 数据处理规范
- 缺失值处理：优先前向填充，明确记录处理逻辑
- 异常值检测：使用 3 倍标准差或 IQR 方法
- 数据验证：检查日期连续性、价格合理性
## 回测注意事项
- 避免未来信息泄露（look-ahead bias）
- 考虑交易成本和滑点
- 使用滚动窗口进行参数优化3.3.5 最佳实践
少即是多
Claude Code 的系统提示已包含约 7000 tokens 的内置指令。CLAUDE.md 内容过多会占用宝贵的上下文空间。
建议：
- 控制在 100-300 行（约占用 500-1500 tokens，仅系统提示的 7%-20%）
- 5-10 条核心规则为宜
- 定期清理过时内容
具体而非笼统
避免：
- 提供有用的错误消息
- 为新功能编写测试
- 遵循最佳实践
推荐：
- 错误响应使用
{ error: string, code: number }格式 - 新 API 端点需要在
/tests/api/下添加对应测试文件 - 数据库查询使用 Prisma ORM
不要做 Linter 的工作
代码格式化交给确定性工具（Prettier、ESLint），不要在 CLAUDE.md 中写大量格式规则。
导入功能
CLAUDE.md 支持使用 @ 语法导入其他文件：
参考 @README.md 了解项目概述
查看 @package.json 获取可用的 npm 命令
@docs/architecture.md这样可以保持主文件简洁，详细内容放在单独文件中。
3.3.6 初始化与验证
创建 CLAUDE.md
方式一：使用 /init 命令自动生成，然后手动精简：
/init方式二：手动创建并编写：
touch CLAUDE.md验证配置加载
在 Claude Code 中运行：
/memory这会显示已加载的记忆文件列表，确认你的 CLAUDE.md 被正确识别。
快速添加规则
在对话中按 # 键可以快速添加指令到 CLAUDE.md，非常适合迭代优化。
3.4 用户自定义命令、技能与智能体配置文件
Claude Code 提供多种扩展机制，让你可以根据需要定制 AI 助手的行为。本节介绍 Skills、斜杠命令和子智能体。
3.4.1 扩展机制概览
| 机制 | 用途 | 触发方式 |
|---|---|---|
| Skills | 给 Claude 专业知识 | Claude 根据上下文自动触发 |
| 斜杠命令 | 创建可复用的提示模板 | 用户手动输入 /命令名 |
| 子智能体 | 委托任务到独立上下文 | Claude 自动委派或显式调用 |
| CLAUDE.md | 设置项目级全局指令 | 会话启动时自动加载 |
关键区别：Skills 根据对话自动激活，斜杠命令要你手动输入 /命令名。
3.4.2 Skills（技能）
什么是 Skill
Skill 是 Claude Code 的功能扩展机制，本质上是一个 Markdown 文件（SKILL.md），用于教 Claude 在特定场景下按照你定义的方式执行任务。
工作原理
- 启动时加载元数据：Claude 仅加载每个 Skill 的名称和描述
- 匹配描述：当请求与 Skill 描述匹配时，Claude 请求使用该 Skill
- 加载完整内容：确认后，完整的 SKILL.md 被加载到上下文
- 执行指令：Claude 按照 Skill 的指令执行
存储位置
| 位置 | 路径 | 作用域 |
|---|---|---|
| 个人 | ~/.claude/skills/ |
所有项目可用 |
| 项目 | .claude/skills/ |
当前仓库内 |
创建第一个 Skill
我们来创建一个代码解释技能：
步骤 1：创建目录
mkdir -p ~/.claude/skills/code-explainer步骤 2：创建 SKILL.md 文件
---
name: code-explainer
description: 用通俗易懂的方式解释代码。当用户询问代码如何工作、需要代码讲解、或说「解释这段代码」时使用。
---
# 代码解释技能
当解释代码时，请遵循以下步骤：
## 1. 先给出类比
用日常生活中的事物来类比代码的功能。
## 2. 分步骤讲解
- 输入是什么
- 处理过程
- 输出是什么
- 可能的边界情况
## 3. 使用示意图
用简单的 ASCII 图表展示流程：
```txt
输入 → 处理 → 输出4. 提供简单示例
给出一个最简单的调用示例。
步骤 3：验证 Skill 加载
重启 Claude Code，然后查看：
```txt
/skills你应该能看到 code-explainer 及其描述。
步骤 4：测试 Skill
这段代码是怎么工作的？
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)Claude 会请求使用该 Skill，然后按照定义的格式进行解释。
如果 Claude 没有自动请求使用该 Skill：
- 检查 YAML frontmatter 是否正确（
---包裹） - 运行
/skills确认 Skill 已加载 - 重启 Claude Code 重新加载配置
- 确认提问包含 description 中的关键词（如「解释代码」）
SKILL.md 格式说明
---
name: skill-name
description: 功能描述，Claude 用此决定何时应用该 Skill
allowed-tools:
- Read
- Write
- Bash(python:*)
---
# Skill 标题
具体指令和内容...常用字段：
| 字段 | 说明 | 必需 |
|---|---|---|
name |
Skill 名称 | 是 |
description |
功能描述和使用时机 | 是 |
allowed-tools |
可使用的工具列表 | 否 |
fork |
在独立上下文中运行 | 否 |
allowed-tools 中的通配符 * 表示匹配任意字符。例如 Bash(python:*) 允许执行所有以 python 开头的命令。使用通配符时要谨慎 —— 过于宽泛的权限可能带来安全风险。建议在测试阶段使用宽泛权限，正式使用时收紧到具体命令。
3.4.3 斜杠命令
斜杠命令是预定义的提示模板，与 Skills 的关键区别是需要用户显式调用。
存储位置
| 作用域 | 路径 | 命令前缀 |
|---|---|---|
| 项目命令 | .claude/commands/ |
/project:命令名 |
| 个人命令 | ~/.claude/commands/ |
/user:命令名 |
创建命令
创建项目命令 .claude/commands/review.md：
---
description: 分析代码的性能问题
argument-hint: [文件路径]
---
分析 @$ARGUMENTS 文件的代码性能，包括：
1. 时间复杂度分析
2. 空间复杂度分析
3. 潜在的性能瓶颈
4. 优化建议使用方式：
/project:review src/utils/helpers.py参数使用
$ARGUMENTS：捕获所有参数$1, $2, $3：位置参数
文件引用
使用 @ 前缀引用文件内容：
审查 @src/utils/helpers.js 中的实现执行 Bash 命令
使用 ! 前缀执行 bash 命令：
当前 git 状态：
!git status
基于以上状态，创建一个 commit。3.4.4 子智能体（Subagents）
子智能体是运行在独立上下文窗口中的专用 AI 助手，每个子智能体可以拥有独立的系统提示、模型和工具权限。
核心优势
- 独立上下文：不污染主对话
- 任务专精：专注特定领域
- 工具隔离：可配置只读权限
创建子智能体
方式一：使用 /agents 命令
/agents选择「创建新代理」，Claude 会引导你填写功能描述、工具权限等。
方式二：手动创建文件
项目级：.claude/agents/your-agent.md 用户级：~/.claude/agents/your-agent.md
配置文件示例
创建一个金融分析专用子智能体：
---
name: financial-analyst
description: 专门处理金融数据分析任务。当任务涉及财务报表分析、市场数据处理或投资研究时使用。
allowed-tools:
- Read
- Write
- Bash(python:*)
model: claude-sonnet-4-5-20250929
---
# 金融分析专家
你是一位专业的金融分析师，专注于：
## 专长领域
- 财务报表分析
- 市场数据处理
- 风险指标计算
- 投资研究报告
## 工作原则
1. 数据精确性优先，使用 Decimal 类型处理金额
2. 所有分析结论需注明假设和局限
3. 遵循项目的金融领域约定
## 输出规范
- 数值保留适当精度
- 日期使用 YYYY-MM-DD 格式
- 百分比使用小数形式激活子智能体
- 自动委托：Claude 根据任务描述自动匹配
- 显式调用：在对话中指定使用某个子智能体
- 通过 CLAUDE.md 强化：在项目配置中说明何时使用哪个子智能体
验证子智能体是否被识别
创建子智能体文件后，运行以下命令检查：
/agents你应该能在列表中看到刚创建的子智能体。如果没有显示：
- 检查文件路径是否正确（
.claude/agents/目录） - 确认 YAML frontmatter 格式正确（
---包裹） - 重启 Claude Code 重新加载配置
3.4.5 金融领域应用示例
金融数据分析 Skill
创建 .claude/skills/financial-data-analyzer/SKILL.md：
---
name: financial-data-analyzer
description: 分析金融数据，生成统计报告和可视化。处理股票数据、财务报表或市场分析时使用。
allowed-tools:
- Read
- Write
- Bash(python:*)
---
# 金融数据分析技能
## 分析流程
1. **数据验证**
- 检查数据完整性
- 识别缺失值和异常值
- 验证日期格式和数值范围
2. **描述性统计**
- 计算均值、标准差、偏度、峰度
- 生成分位数统计
- 识别极端值
3. **可视化**
- 时间序列图
- 相关性热力图
- 收益分布直方图
## 输出格式
```markdown
## 数据分析报告
### 数据概览
- 时间范围：[开始日期] 至 [结束日期]
- 样本数量：[N]
- 数据完整性：[百分比]
### 关键统计量
| 指标 | 值 |
|------|-----|
| 均值 | ... |
| 标准差 | ... |
### 发现与建议
...
## 3.5 MCP 初识与配置
MCP（Model Context Protocol，模型上下文协议）让 Claude Code 能够走出对话框，连接外部工具和数据源。
### 3.5.1 什么是 MCP
MCP 是一个开放标准协议，允许 AI 模型与外部工具、数据源和服务进行安全、标准化的交互。
可以把 MCP 想象成 AI 模型的万能遥控器 —— 就像 USB 标准让各种设备都能通过统一接口连接，MCP 为 AI 世界做了同样的事情。
**MCP 能做什么**
通过 MCP，Claude Code 可以：
- 搜索网页获取最新信息
- 读写本地文件
- 查询数据库
- 操作 GitHub 仓库
- 调用各种 API 服务
**核心概念**
MCP 定义了三种主要能力：
| 能力类型 | 说明 | 示例 |
|---------|------|------|
| 工具（Tools） | 可执行的功能 | 搜索网页、创建文件 |
| 资源（Resources） | 可访问的数据源 | 文件内容、数据库记录 |
| 提示（Prompts） | 预定义的提示模板 | 代码审查模板 |
### 3.5.2 MCP 架构
MCP 采用客户端-服务器架构。Claude Code 作为 MCP 客户端，通过协议通信与各种 MCP 服务器（工具提供者）交互。客户端负责发送请求和接收结果，服务器负责执行工具和访问数据。
**服务器类型**
| 类型 | 工作方式 | 适用场景 |
|------|----------|----------|
| stdio | 标准输入输出 | 本地工具 |
| SSE | HTTP + 事件流 | 远程服务 |
初学者主要使用 stdio 模式，配置简单，无需网络。
### 3.5.3 配置 MCP 服务器
**查看已配置的服务器**
在 Claude Code 中：
```txt
/mcp在终端中：
claude mcp list添加 MCP 服务器
基本语法：
claude mcp add <服务器名称> <命令> [参数...]配置范围
| 范围 | 说明 | 使用场景 | 示例 |
|---|---|---|---|
| local（默认） | 仅当前项目，不提交 Git | 个人实验、测试 MCP | 测试新的搜索 API |
| project | 团队共享，提交 Git | 团队都需要的工具 | 公司内部数据库 MCP |
| user | 所有项目可用 | 个人常用工具 | GitHub、Tavily 搜索 |
配置建议
- 学习阶段：用
local（不污染项目配置） - 确认有用后：改为
user（跨项目复用） - 团队需要：提交到
project（写入版本控制）
claude mcp add --scope project shared-server /path/to/server3.5.4 常用 MCP 服务器示例
文件系统访问
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents这会让 Claude Code 能够访问指定目录的文件。
验证 MCP 是否正常工作
# 查看已配置的 MCP 服务器
claude mcp list
# 获取详细配置
claude mcp get filesystem然后在 Claude Code 中测试：
/mcp应该能看到 filesystem 服务器及其提供的工具（如 read_file、list_directory）。
GitHub 操作
claude mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=你的token -- npx -y @modelcontextprotocol/server-github需要先在 GitHub 创建 Personal Access Token。
网络搜索（Brave Search）
claude mcp add brave-search --env BRAVE_API_KEY=你的apikey -- npx -y @modelcontextprotocol/server-brave-search需要在 Brave Search API 注册获取 API Key。
金融相关 MCP
| MCP 服务器 | 功能 | 适用场景 |
|---|---|---|
| Finance MCP Server | 股票/加密货币价格 | 市场数据获取 |
| PostgreSQL MCP | 数据库查询 | 金融数据存储 |
| Tavily MCP | 网络搜索 | 研究信息收集 |
3.5.5 MCP 安全考虑
核心安全原则
| 原则 | 说明 |
|---|---|
| 最小权限 | 只授予完成任务所需的最小权限 |
| 数据最小化 | 只传输和存储必要的数据 |
| 深度防御 | 多层安全控制 |
安全最佳实践
- 保护 API 密钥 —— 使用环境变量存储，不要硬编码
- 限制访问范围 —— 文件系统 MCP 只授权必要目录
- 审计日志 —— 定期检查操作记录
敏感信息处理
不要在 MCP 配置中包含：
- 数据库密码（使用环境变量）
- API 密钥（使用环境变量）
- 个人身份信息
3.5.6 故障排除
诊断命令
# 启动调试模式
claude --mcp-debug
# 检查服务器状态
claude mcp list
# 获取详细配置
claude mcp get <服务器名称>常见问题
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 连接失败 | 命令路径错误 | 检查 command 是否可执行 |
| 工具不显示 | 配置错误 | 使用 –mcp-debug 排查 |
| 权限错误 | 环境变量未设置 | 检查 API 密钥配置 |
案例 3A：联网搜索并保存
本案例演示如何使用 Claude Code 配合 MCP 实现联网搜索，并将结果保存到本地文件。
案例背景
在经济金融研究中，经常需要获取最新的市场信息、政策动态或学术资料。通过 MCP 协议，Claude Code 可以实现联网搜索、整理结果、保存到本地的完整工作流。
准备工作
前置条件
- 已完成 Claude Code 安装和认证
- 了解基本的会话管理命令
- 有稳定的网络连接
获取 Brave Search API Key
- 访问 Brave Search API
- 注册账户并创建 API Key
- 免费版每月有 2000 次查询额度
配置 MCP 搜索服务
添加 Brave Search MCP
# 先设置环境变量
export BRAVE_API_KEY="你的API密钥"
# 添加 MCP 服务器
claude mcp add brave-search --env BRAVE_API_KEY -- npx -y @modelcontextprotocol/server-brave-search验证配置
claude mcp list
claude mcp get brave-search启动 Claude Code 并检查：
/mcp应该能看到 brave-search 服务器及其提供的工具。
执行搜索任务
启动会话并命名
/rename 汇率政策研究发起搜索请求
搜索最近一个月关于人民币汇率政策的新闻和分析报告Claude 会调用 brave-search 工具，获取并整理搜索结果。
常见问题处理
- 搜索无结果：
- 调整时间范围（如「最近一个月」改为「最近三个月」）
- 简化关键词（如「人民币汇率中间价形成机制改革」简化为「人民币汇率改革」）
- 尝试英文关键词（如「RMB exchange rate policy」）
- API 配额耗尽：
- Brave Search 免费版每月 2000 次查询
- 运行
/mcp查看当前配额使用情况 - 考虑注册多个账户或升级付费版
- 搜索结果质量不佳：
- 在提示中明确要求「只返回学术来源」或「只返回新闻报道」
- 指定时间范围：「2024 年 1 月至今」
- 排除特定网站：「不要返回 xxx.com 的结果」
保存搜索结果
保存为 Markdown 文件
请将搜索结果整理成 Markdown 格式，保存到 research/rmb-policy-202601.md 文件中Claude 会创建一个结构化的文件，包含搜索主题、日期、结果列表和来源链接。
保存为 JSON 格式
如果需要程序处理：
将搜索结果保存为 JSON 格式到 data/search-results.json进阶：创建搜索 Skill
为常用搜索任务创建 Skill，简化操作流程。
创建 .claude/skills/research-search/SKILL.md：
---
name: research-search
description: 执行金融研究相关的网络搜索并整理保存结果。当进行市场调研、政策分析或文献搜索时使用。
allowed-tools:
- mcp__brave-search
- Write
- Read
---
# 金融研究搜索技能
## 搜索流程
1. **明确搜索目标**
- 确认搜索关键词
- 设定时间范围
- 确定来源偏好
2. **执行搜索**
- 使用 brave-search 工具
- 获取前 10 条相关结果
3. **整理结果**
- 按相关性排序
- 提取关键信息
- 标注来源和日期
4. **保存文件**
- 保存到 research/ 目录
- 使用 Markdown 格式
- 包含元数据和引用链接案例总结
通过本案例，你学习了：
- MCP 搜索配置：如何添加 brave-search MCP 服务器
- 搜索执行：如何通过自然语言发起搜索
- 结果保存：如何将结果保存为 Markdown 或 JSON
- 进阶扩展：如何创建 Skill 简化重复操作
这个工作流可以应用于市场调研、政策跟踪、学术文献检索等场景。
本章小结
本章我们完成了 Claude Code 的完整配置，掌握了以下核心技能：
- 环境配置：安装 Node.js、Claude Code，完成账户认证和 API 连接
- 会话管理：使用 /clear、/compact、/resume 管理会话，理解三种工作模式
- CLAUDE.md 配置：创建项目记忆文件，让 Claude 快速理解项目上下文
- 扩展机制：创建 Skills、斜杠命令和子智能体，定制 AI 助手行为
- MCP 协议：连接外部工具和数据源，扩展 Claude Code 能力边界
上下文工程核心原则回顾
| 层级 | 内容 | 优化策略 |
|---|---|---|
| 系统提示层 | CLAUDE.md、Skill | 精简、结构化 |
| 检索文档层 | RAG 结果、文件内容 | 相关性过滤 |
| 工具输出层 | 函数调用结果 | 格式化、摘要 |
| 隐式数据层 | 对话历史、状态 | 定期清理 |
实验：Claude Code 环境配置与 Skills 开发实践
实验前置检查
开始实验前，确认以下准备工作：
建议准备的工具
- 文本编辑器（VS Code、Sublime Text 等）
- 终端工具（macOS Terminal、Windows PowerShell）
实验时长：2 学时（120 分钟）
实验目标：
- 独立完成 Claude Code 安装与 API 配置
- 掌握基础会话管理操作
- 理解 Skills 系统架构
- 开发简单的自定义 Skill
实验步骤：
| 阶段 | 内容 | 时间 |
|---|---|---|
| 1 | 环境安装验证（Node.js、Git、Claude Code、API） | 15 分钟 |
| 2 | 基础操作体验（首个对话、会话管理、工作模式） | 25 分钟 |
| 3 | CLAUDE.md 配置 | 20 分钟 |
| 4 | MCP 基础配置 | 15 分钟 |
| 5 | Skills 体验与触发机制 | 15 分钟 |
| 6 | Skill 开发实践 | 30 分钟 |
评估标准：
- Claude Code 正常运行，API 连接成功
- 能正确使用 /clear、/compact、/resume
- CLAUDE.md 文件结构规范
- 成功配置至少一个 MCP Server
- 成功开发并调用自定义 Skill
详细实验指南请参考本章配套实验手册。
思考题
为什么 CLAUDE.md 的内容应该保持精简？过长的配置文件会带来什么问题？
/compact 和 /clear 命令的使用场景有何不同？请举例说明。
Skills 由 Claude 自动触发，斜杠命令需要手动输入。请思考：
- 什么类型的任务适合用 Skills？什么适合用斜杠命令？
- 如果所有扩展都需要手动调用，会有什么问题？
- 如果所有扩展都自动触发，又会有什么问题？
在金融研究场景中，你会如何设计 MCP 工具组合来提高研究效率？
上下文腐化问题对长文档分析（如年报分析）有什么影响？如何应对？