From d8eb93663d61b24748189dc3c0272df8d4a392b6 Mon Sep 17 00:00:00 2001 From: sanbuphy Date: Sun, 1 Mar 2026 12:26:02 +0800 Subject: [PATCH] refactor(docs): restructure stage-3 core-skills directory - Rename numbered directories to descriptive names - Add new basics and workflow sections - Improve content organization for better readability --- .../core-skills/3.1-claude-mcp/index.md | 1650 ---------------- .../{3.4-agent-teams => agent-teams}/index.md | 0 .../zh-cn/stage-3/core-skills/basics/index.md | 1731 +++++++++++++++++ .../index.md | 239 ++- docs/zh-cn/stage-3/core-skills/mcp/index.md | 568 ++++++ .../{3.2-skills => skills}/index.md | 138 ++ .../{3.5-superpowers => superpowers}/index.md | 2 +- .../stage-3/core-skills/workflow/index.md | 684 +++++++ 8 files changed, 3344 insertions(+), 1668 deletions(-) delete mode 100644 docs/zh-cn/stage-3/core-skills/3.1-claude-mcp/index.md rename docs/zh-cn/stage-3/core-skills/{3.4-agent-teams => agent-teams}/index.md (100%) create mode 100644 docs/zh-cn/stage-3/core-skills/basics/index.md rename docs/zh-cn/stage-3/core-skills/{3.3-long-running-tasks => long-running-tasks}/index.md (71%) create mode 100644 docs/zh-cn/stage-3/core-skills/mcp/index.md rename docs/zh-cn/stage-3/core-skills/{3.2-skills => skills}/index.md (85%) rename docs/zh-cn/stage-3/core-skills/{3.5-superpowers => superpowers}/index.md (99%) create mode 100644 docs/zh-cn/stage-3/core-skills/workflow/index.md diff --git a/docs/zh-cn/stage-3/core-skills/3.1-claude-mcp/index.md b/docs/zh-cn/stage-3/core-skills/3.1-claude-mcp/index.md deleted file mode 100644 index 2a6b1c0..0000000 --- a/docs/zh-cn/stage-3/core-skills/3.1-claude-mcp/index.md +++ /dev/null @@ -1,1650 +0,0 @@ -# Claude MCP 完全指南 - -## MCP 简介 - -**MCP（Model Context Protocol，模型上下文协议）** 是由 Anthropic 公司开发的一个**开放协议标准**，于 2024 年 11 月正式发布。 - -想象一下，MCP 就像是 AI 世界的「USB-C 接口」——它提供了一种标准化的方式，让 AI 大模型（如 Claude、GPT）能够与外部数据源、工具和 API 进行交互。 - -### 为什么需要 MCP？ - -在没有 MCP 之前，AI 模型与外部系统的交互存在诸多问题： - -- **缺乏统一标准**：每个工具都需要单独的集成方式 -- **开发成本高**：为每个新功能编写专用连接器 -- **安全性难以保证**：没有统一的权限和认证机制 -- **模型无关性差**：不同 AI 平台需要重复开发 - -MCP 解决了这些问题，提供了一套统一的协议，让 AI 能够「即插即用」地连接各种外部服务。 - -## 快速开始 - -### 5 分钟上手 MCP - -让我们通过一个简单的例子，快速体验 MCP 的强大功能。 - -#### 步骤 1：安装 Claude Desktop（如果还没有） - -访问 [Claude Desktop 下载页面](https://claude.ai/download) 下载并安装。 - -#### 步骤 2：找到配置文件 - -| 操作系统 | 配置文件路径 | -|---------|-------------| -| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` | -| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` | -| **Linux** | `~/.claude/mcp-config.json` | - -#### 步骤 3：添加你的第一个 MCP 服务器 - -以 **GitHub 服务器**为例——它让 Claude 能够**操作你的 GitHub 仓库**，这是 AI 原本做不到的！ - -```json -{ - "mcpServers": { - "github": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-github"], - "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx" - } - } - } -} -``` - -**获取 GitHub Token：**访问 [GitHub Settings > Personal Access Tokens](https://github.com/settings/tokens)，创建一个 Classic Token，勾选 `repo`、`issues`、`pull_requests` 权限。 - -#### 步骤 4：重启 Claude Desktop - -保存配置文件后，完全退出 Claude Desktop 并重新打开。 - -#### 步骤 5：查看已安装的 MCP 服务器 - -在 Claude Desktop 中，输入以下命令查看： - -``` -你：你现在有哪些可用的工具？ - -Claude：[会列出所有 MCP 服务器提供的工具] -``` - -配置成功后，你会看到类似这样的输出： - -``` -可用工具： -- github_create_issue: 在 GitHub 仓库中创建 Issue -- github_list_issues: 列出仓库的 Issues -- github_create_pull_request: 创建 Pull Request -- github_add_comment: 添加评论 -... -``` - -#### 步骤 6：开始使用 - -现在 Claude 可以操作你的 GitHub 仓库了： - -``` -你：帮我在 anthropic/claude-code 仓库里创建一个 Issue，标题是"添加新功能"，内容是描述需要添加的功能 - -Claude：[会调用 github_create_issue 工具创建 Issue] - -你：帮我看看最近有哪些开放的 Issue 需要处理 - -Claude：[会调用 github_list_issues 工具并列出 Issues] -``` - -### 尝试更多 MCP 服务器 - -#### SQLite 服务器 - 查询本地数据库 - -让 Claude 能够查询和分析你的 SQLite 数据库： - -```json -{ - "mcpServers": { - "sqlite": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "/path/to/your/database.db"] - } - } -} -``` - -**配置后你可以让 Claude：** -- 执行 SQL 查询 -- 分析数据库结构 -- 生成数据报表 - -#### 文件系统服务器 - 安全访问本地文件 - -让 Claude 能够访问指定目录的文件： - -```json -{ - "mcpServers": { - "filesystem": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/你的用户名/Documents"] - } - } -} -``` - -**配置后你可以让 Claude：** -- 读取和编辑文件 -- 搜索文件内容 -- 创建新文件 - -#### Puppeteer 服务器 - 浏览器自动化 - -让 Claude 能够控制浏览器进行自动化操作： - -```json -{ - "mcpServers": { - "puppeteer": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-puppeteer"] - } - } -} -``` - -**配置后你可以让 Claude：** -- 截取网页截图 -- 填写表单 -- 点击按钮 -- 抓取动态网页内容 - -### 在 Claude Code 中使用 MCP - -如果你使用的是 **Claude Code（CLI 工具）**，配置更加简单： - -```bash -# 添加一个 MCP 服务器 -claude mcp add --transport http https://mcp.notion.com/mcp - -# 查看已安装的 MCP 服务器 -/mcp - -# 检查 MCP 连接状态 -/doctor -``` - -**配置文件位置：** -- 用户级：`~/.claude.json` -- 项目级：`.claude/mcp.json` - -## MCP 原理 - -### 核心架构 - -MCP 采用 **客户端-服务器架构**，包含以下几个核心组件： - -``` -┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ -│ MCP Host │────▶│ MCP Client │────▶│ MCP Server │ -│ (Claude Desktop)│ │ (协议适配层) │ │ (工具提供者) │ -└─────────────────┘ └─────────────────┘ └─────────────────┘ - │ - ┌───────────────────────────────┘ - ▼ - ┌─────────────────────────────┐ - │ Tools / Resources / Prompts │ - │ (工具 / 资源 / 提示模板) │ - └─────────────────────────────┘ -``` - -### 三大核心能力 - -MCP 定义了三种主要的能力类型： - -#### 1. Tools（工具） -- **定义**：可执行的函数，AI 模型可以调用 -- **特点**：可以修改外部状态，产生副作用 -- **示例**：发送邮件、执行代码、文件操作、API 调用 -- **操作**：`tools/list`（发现）、`tools/call`（执行） - -#### 2. Resources（资源） -- **定义**：服务器向客户端暴露的只读数据 -- **特点**：提供数据和上下文，不修改外部状态 -- **示例**：文件内容、配置信息、数据库记录、系统状态 -- **操作**：`resources/list`（发现）、`resources/read`（读取） - -#### 3. Prompts（提示） -- **定义**：可重用的提示模板和工作流 -- **特点**：预定义的参数化模板，提供标准化指令 -- **示例**：欢迎消息、工作流模板、角色特定提示、数据库调试模板 -- **操作**：`prompts/list`（发现）、`getPrompt()`（获取） - -### 通信机制 - -MCP 基于 **JSON-RPC 2.0** 规范进行消息交互： - -```json -// 请求示例 -{ - "jsonrpc": "2.0", - "id": 1, - "method": "tools/call", - "params": { - "name": "get_weather", - "arguments": { - "city": "北京" - } - } -} - -// 响应示例 -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "content": [ - { - "type": "text", - "text": "北京今天晴天，温度 15-25°C" - } - ] - } -} -``` - -### 传输方式 - -MCP 支持三种传输方式，各有适用场景： - -| 传输方式 | 部署方式 | 延迟 | 安全性 | 适用场景 | -|---------|---------|------|--------|----------| -| **STDIO** | 本地 | 零延迟 | 高 | 本地工具集成、开发环境 | -| **SSE** | 远程 | 低 | 中等 | 微服务架构、远程调试 | -| **Streamable HTTP** | 远程 | 中等 | 高（需认证） | 企业级生产环境 | - -#### STDIO（标准输入/输出） -- 客户端启动服务器为子进程 -- 消息通过 stdin/stdout 传输 -- 数据不经过网卡，安全性最高 -- 生命周期与客户端绑定 - -#### SSE（Server-Sent Events） -- 下游使用 SSE 长连接推送 -- 上游使用 HTTP POST 请求 -- 支持远程部署和独立运行 -- 需要持久连接 - -#### Streamable HTTP -- HTTP POST 发送消息 -- 支持流式实时响应 -- 跨越网络边界 -- 需要严格的认证机制（OAuth 2.1） - ---- - -### 三种传输方式深度对比 - -#### 1. 核心区别对比表 - -| 对比维度 | STDIO | SSE | HTTP | -|---------|-------|-----|------| -| **通信方向** | 双向（stdin/stdout） | 单向（Server→Client）+ POST | 双向（请求/响应） | -| **连接方式** | 子进程管道 | 长连接（SSE）+ 短连接（POST） | 短连接/流式 | -| **部署位置** | 必须本地 | 本地或远程 | 本地或远程 | -| **启动方式** | 客户端启动子进程 | 独立进程/服务 | 独立进程/服务 | -| **网络依赖** | 无（不经过网卡） | 需要网络 | 需要网络 | -| **并发处理** | 单连接 | 多客户端 | 多客户端 | -| **适用场景** | 本地工具、CLI | 实时推送、监控 | REST API、微服务 | -| **配置复杂度** | 低 | 中 | 中 | -| **调试难度** | 低 | 中 | 中 | - -#### 2. 各传输方式的详细特点 - -##### 简单比喻理解三种传输方式 - -在深入了解技术细节之前，让我们先用**同一个场景**来理解这三种传输方式的区别——想象你需要从一个仓库（MCP 服务器）获取货物（数据）： - -**STDIO 就像「仓库就在你家地下室」**：仓库和你在同一栋房子里，你走下楼梯就能拿到货物。这种方式最快（零延迟），最安全（外人进不来），但仓库只能服务你一个人，而且必须和你住在一起（本地运行）。当你离开家（关闭 Claude），仓库也关门了。 - -**SSE 就像「仓库开通了送货上门服务」**：仓库可以开在小区任何地方（本地或远程）。你办了一张会员卡（建立 SSE 连接），仓库会主动把新到的货物送到你家门口（服务器推送）。你不需要每天去问，有新货自动送来。这张卡可以被多个邻居办理（多客户端），大家各自收到各自的货物。 - -**HTTP 就像「你在网上商城下单」**：仓库可以开在任何地方（本地或远程）。每次需要货物时，你打开 App 下单（发送 HTTP 请求），仓库处理后发货（返回响应）。每次下单都是独立的，仓库不需要记住你是谁。如果订单太多，商城可以自动分配给多个仓库处理（负载均衡），保证服务不中断。 - ---- - -##### STDIO（标准输入/输出）传输方式 - -STDIO 是 MCP 最简单也是最常用的传输方式，它通过操作系统的标准输入输出管道进行通信。当你使用 STDIO 方式时，MCP 客户端（如 Claude Desktop）会启动 MCP 服务器作为一个子进程，然后通过 stdin（标准输入）向服务器发送消息，通过 stdout（标准输出）接收服务器的响应。 - -STDIO 方式的最大特点是**数据不经过网络协议栈**，所有通信都在本机内存中通过管道完成。这意味着它的延迟几乎为零，而且安全性极高——数据不会离开本机，不会被网络嗅探，也不需要考虑网络认证和加密的问题。由于客户端直接管理服务器的生命周期，当 Claude Desktop 关闭时，STDIO 服务器也会自动终止，这种绑定关系简化了资源管理。 - -STDIO 特别适合那些只需要访问本地资源的工具，比如文件系统操作、本地数据库查询、系统命令执行等。例如，你想让 Claude 帮你读取本地文件、查询 SQLite 数据库、或者执行 Git 命令，STDIO 是最佳选择。它的配置也非常简单，只需要指定启动命令和参数即可。 - -不过，STDIO 也有其局限性。由于服务器是作为子进程运行的，它只能运行在本地机器上，无法部署到远程服务器。同时，每个 STDIO 服务器只能服务于一个客户端连接，不支持多客户端并发访问。 - -##### SSE（Server-Sent Events）传输方式 - -SSE 传输方式让 MCP 服务器可以作为独立的 HTTP 服务运行，支持本地或远程部署。它采用了一种混合通信模式：服务器通过 SSE（Server-Sent Events）长连接向客户端推送消息，而客户端则通过普通的 HTTP POST 请求向服务器发送消息。 - -这种设计的巧妙之处在于，SSE 本身就是基于 HTTP 的，因此它可以天然地穿透防火墙和代理服务器，同时又能保持服务器向客户端主动推送数据的能力。当你建立 SSE 连接后，服务器可以随时将数据推送到客户端，而不需要客户端不断轮询，这对于实时监控、日志流式输出、进度通知等场景非常有用。 - -SSE 服务器独立于客户端运行，这意味着它可以部署在远程服务器上，多个客户端可以同时连接到同一个 SSE 服务器。例如，你可以在公司内网部署一个 SSE 类型的 MCP 服务器，让团队成员的 Claude Desktop 都能连接使用。服务器有自己的生命周期，不会因为某个客户端断开而停止运行。 - -SSE 的适用场景包括：需要服务器主动推送数据的实时监控工具、日志收集和分析服务、多用户共享的企业级工具等。相比 STDIO，SSE 的配置稍微复杂一些，需要指定服务器的 URL 地址，并且可能需要处理 CORS（跨域资源共享）和网络认证的问题。 - -##### HTTP（Streamable HTTP）传输方式 - -HTTP 传输方式采用传统的请求-响应模式，客户端通过 HTTP POST 请求向服务器发送消息，服务器处理完成后返回响应。这是最常见的 Web 服务通信方式，也是最容易与现有基础设施集成的方案。 - -Streamable HTTP 在普通 HTTP 的基础上增加了流式响应的支持，这意味着服务器可以在处理过程中逐步返回结果，而不需要等到全部处理完成。这对于处理耗时操作（如大文件处理、复杂计算）时特别有用，因为客户端可以实时看到进度，而不需要一直等待。 - -HTTP 方式的最大优势在于**无状态设计**。每个请求都是独立的，服务器不需要维护客户端的连接状态，这使得 HTTP 服务器可以轻松地水平扩展——你可以部署多个服务器实例，通过负载均衡器分发请求，实现高可用和高性能。HTTP 方式也最容易与现有的 Web 基础设施集成，比如使用 Nginx 反向代理、CDN 缓存、API 网关等。 - -HTTP 服务器同样支持本地或远程部署，可以服务于多个客户端。由于 HTTP 是无状态的，它特别适合构建 RESTful API 风格的 MCP 服务。企业级部署时，通常会在 HTTP 层添加认证机制（如 OAuth 2.1、JWT），确保只有授权用户才能访问 MCP 工具。 - -HTTP 方式适用于：需要水平扩展的微服务架构、需要与现有 Web 服务集成的场景、需要 RESTful API 风格的工具服务、企业级生产环境部署等。它的配置相对复杂，需要处理 URL、认证头部、错误重试等问题。 - ---- - -##### 稳定性与可靠性对比 - -**STDIO：最稳定，最不容易出问题** -- **稳定性**：⭐⭐⭐⭐⭐ 极高。因为所有通信都在本机内存中进行，不依赖网络，不存在网络抖动、丢包、超时等问题 -- **故障点**：几乎没有。唯一的故障点是进程崩溃，但这种情况很少见 -- **常见问题**：命令配置错误（路径不对、参数错误）、权限不足（无法执行命令） -- **排查难度**：低。错误日志通常很直观，直接在终端就能看到 - -**SSE：中等稳定性，长连接可能断开** -- **稳定性**：⭐⭐⭐ 中等。依赖网络连接，长连接可能因网络波动、防火墙超时、代理服务器中断而断开 -- **故障点**：网络不稳定、服务器重启、Nginx/代理超时配置、CORS 配置错误 -- **常见问题**：连接突然断开、收不到推送、跨域错误、心跳机制配置不当 -- **排查难度**：中等。需要检查网络状态、服务器日志、浏览器/客户端控制台 - -**HTTP：高稳定性，但依赖基础设施** -- **稳定性**：⭐⭐⭐⭐ 高。无状态设计让服务更健壮，单点故障可以通过负载均衡解决 -- **故障点**：网络问题、服务器过载、认证失败、DNS 解析失败、证书过期 -- **常见问题**：请求超时、503 服务不可用、401/403 认证错误、重试风暴 -- **排查难度**：中等。需要监控 HTTP 状态码、响应时间、错误率等指标 - -**总结**： -- **追求极致稳定**：选 STDIO（本地场景） -- **需要推送能力但能接受偶尔重连**：选 SSE -- **需要高可用和容错能力**：选 HTTP（配合负载均衡） - ---- - -##### 资源消耗对比 - -| 资源类型 | STDIO | SSE | HTTP | -|---------|-------|-----|------| -| **内存占用** | 低（单进程） | 中（维护连接状态） | 低（无状态，请求完即释放） | -| **CPU 消耗** | 低 | 中（维护长连接、心跳检测） | 低-中（看请求频率） | -| **网络带宽** | 无（不走网络） | 中（保持连接有开销） | 按需使用 | -| **连接资源** | 1 个进程 | 每个客户端 1 个长连接 | 短暂连接，用完即放 | -| **扩展成本** | 无法水平扩展 | 中等（需要会话同步） | 低（无状态，随意扩容） | - -**详细说明：** - -**STDIO 资源消耗**： -- 内存：只占用一个进程的内存，通常几十到几百 MB -- CPU：只在处理请求时使用 CPU，空闲时几乎不消耗 -- 网络：零网络开销，数据通过内存管道传输 -- 适合：资源受限的本地环境、笔记本电脑、边缘设备 - -**SSE 资源消耗**： -- 内存：需要为每个客户端维护连接状态，内存占用随客户端数量线性增长 -- CPU：需要定期发送心跳包保持连接，有一定 CPU 开销 -- 网络：保持长连接需要持续占用网络资源，防火墙/代理可能限制连接数 -- 适合：客户端数量可控的场景（几十到几百个连接） - -**HTTP 资源消耗**： -- 内存：无状态设计，每个请求处理完即释放资源，内存占用稳定 -- CPU：只在处理请求时使用，空闲时资源完全释放 -- 网络：按需使用，没有空闲连接的开销 -- 适合：高并发场景、云原生部署、Serverless 架构 - ---- - -##### 选择建议：什么情况用什么？ - -**无脑选择 STDIO 的场景（推荐优先尝试）：** -- 工具只访问本地资源（文件、数据库、系统命令） -- 个人使用，不需要分享给他人 -- 快速验证想法、原型开发 -- 对安全性要求极高（金融、医疗等敏感数据） -- 网络环境不稳定或没有网络 - -**选择 SSE 的场景：** -- 需要服务器主动推送数据（实时日志、进度通知、监控告警） -- 多个用户需要共享同一个服务（小团队协作） -- 需要远程访问，但客户端数量不多（< 100） -- 需要双向通信，但不想用复杂的 WebSocket - -**选择 HTTP 的场景：** -- 企业级部署，需要高可用和容错 -- 客户端数量大（几百到几千） -- 需要与现有微服务架构集成 -- 需要 RESTful API 风格，方便调试和测试 -- 需要缓存、CDN、API 网关等基础设施支持 -- 需要 Serverless 部署（如 AWS Lambda、Vercel） - -**决策流程图：** - -``` -开始 - │ - ├─ 是否只需要访问本地资源？ - │ ├─ 是 → 使用 STDIO ✅ - │ └─ 否 → 继续 - │ - ├─ 是否需要服务器主动推送数据？ - │ ├─ 是 → 使用 SSE ✅ - │ └─ 否 → 继续 - │ - ├─ 是否需要高并发/高可用？ - │ ├─ 是 → 使用 HTTP ✅ - │ └─ 否 → 继续 - │ - └─ 默认推荐：STDIO（最简单）✅ -``` - ---- - -#### 3. 配置方式对比 - -**STDIO 配置（Claude Desktop）：** -```json -{ - "mcpServers": { - "my-local-tool": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"], - "env": { - "API_KEY": "your-api-key" - } - } - } -} -``` - -**SSE 配置（Claude Desktop）：** -```json -{ - "mcpServers": { - "my-sse-server": { - "url": "http://localhost:3000/sse", - "transport": "sse" - } - } -} -``` - -**HTTP 配置（Claude Desktop）：** -```json -{ - "mcpServers": { - "my-http-server": { - "url": "http://localhost:3000/mcp", - "transport": "http", - "headers": { - "Authorization": "Bearer your-token" - } - } - } -} -``` - -#### 3. 配置方式对比 - -**STDIO 配置（Claude Desktop）：** -```json -{ - "mcpServers": { - "my-local-tool": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"], - "env": { - "API_KEY": "your-api-key" - } - } - } -} -``` - -**SSE 配置（Claude Desktop）：** -```json -{ - "mcpServers": { - "my-sse-server": { - "url": "http://localhost:3000/sse", - "transport": "sse" - } - } -} -``` - -**HTTP 配置（Claude Desktop）：** -```json -{ - "mcpServers": { - "my-http-server": { - "url": "http://localhost:3000/mcp", - "transport": "http", - "headers": { - "Authorization": "Bearer your-token" - } - } - } -} -``` - ---- - -### 利用大模型生成不同类型 MCP 服务器 - -你可以根据需要的传输方式，使用特定的 Prompt 让 AI 生成对应类型的 MCP 服务器。 - -#### Prompt 模板 1：生成 STDIO 类型 MCP 服务器 - -``` -# 角色 -你是一个 MCP 服务器开发专家，精通 STDIO 传输方式。 - -# 任务 -请帮我创建一个 STDIO 类型的 MCP 服务器，功能是：[描述你的功能需求] - -# 传输方式要求 -- 使用 STDIO（标准输入/输出）传输 -- 客户端通过 command + args 启动服务器为子进程 -- 消息通过 process.stdin/process.stdout 传输 - -# 技术要求 -1. 使用 TypeScript + @modelcontextprotocol/sdk -2. 使用 StdioServerTransport -3. 服务器作为独立可执行文件运行 -4. 支持通过 npx 直接运行 -5. 包含完整的 package.json，配置 bin 入口 - -# 必须包含的文件 ---- package.json --- -（包含 "bin": { "my-server": "./dist/index.js" }） - ---- src/index.ts --- -（使用 StdioServerTransport 创建服务器） - ---- tsconfig.json --- ---- README.md --- -（包含 Claude Desktop 配置示例，使用 command + args 方式） -``` - -#### Prompt 模板 2：生成 SSE 类型 MCP 服务器 - -``` -# 角色 -你是一个 MCP 服务器开发专家，精通 SSE 传输方式。 - -# 任务 -请帮我创建一个 SSE 类型的 MCP 服务器，功能是：[描述你的功能需求] - -# 传输方式要求 -- 使用 SSE（Server-Sent Events）传输 -- 服务器作为独立 HTTP 服务运行 -- 客户端通过 /sse 端点建立长连接接收消息 -- 客户端通过 POST 请求发送消息到 /message 端点 -- 支持多客户端并发连接 - -# 技术要求 -1. 使用 TypeScript + @modelcontextprotocol/sdk -2. 使用 SSEServerTransport -3. 基于 Express 或原生 HTTP 服务器 -4. 实现 /sse 和 /message 两个路由 -5. 支持 CORS 配置 - -# 必须包含的文件 ---- package.json --- ---- src/index.ts --- -（创建 HTTP 服务器，实现 /sse 和 /message 路由） - ---- tsconfig.json --- ---- README.md --- -（包含 Claude Desktop 配置示例，使用 url + transport: "sse"） -``` - -#### Prompt 模板 3：生成 HTTP 类型 MCP 服务器 - -``` -# 角色 -你是一个 MCP 服务器开发专家，精通 HTTP 传输方式。 - -# 任务 -请帮我创建一个 HTTP 类型的 MCP 服务器，功能是：[描述你的功能需求] - -# 传输方式要求 -- 使用 Streamable HTTP 传输 -- 服务器作为独立 HTTP 服务运行 -- 支持流式响应（streamable） -- 支持身份验证（Bearer Token 或 API Key） -- 支持无状态请求处理 - -# 技术要求 -1. 使用 TypeScript + @modelcontextprotocol/sdk -2. 使用 StreamableHTTPServerTransport -3. 基于 Express 或 Fastify -4. 实现 /mcp 端点处理所有请求 -5. 添加认证中间件 -6. 支持流式响应 - -# 必须包含的文件 ---- package.json --- ---- src/index.ts --- -（创建 HTTP 服务器，实现 /mcp 端点，支持认证和流式响应） - ---- tsconfig.json --- ---- README.md --- -（包含 Claude Desktop 配置示例，使用 url + transport: "http" + headers） -``` - -#### Prompt 模板 4：生成支持多种传输方式的 MCP 服务器 - -``` -# 角色 -你是一个 MCP 服务器开发专家。 - -# 任务 -请帮我创建一个支持多种传输方式的 MCP 服务器，功能是：[描述你的功能需求] - -# 传输方式要求 -- 同时支持 STDIO、SSE、HTTP 三种传输方式 -- 通过环境变量或命令行参数选择传输方式 -- 共享相同的业务逻辑代码 - -# 技术要求 -1. 使用 TypeScript + @modelcontextprotocol/sdk -2. 根据启动参数动态选择 Transport -3. 核心逻辑封装为独立模块 -4. 支持通过 --transport 参数切换 - -# 启动方式示例 -- STDIO: node dist/index.js --transport stdio -- SSE: node dist/index.js --transport sse --port 3000 -- HTTP: node dist/index.js --transport http --port 3000 - -# 必须包含的文件 ---- package.json --- ---- src/index.ts --- -（根据参数选择 Transport） ---- src/server.ts --- -（核心业务逻辑，与传输方式无关） ---- tsconfig.json --- ---- README.md --- -（包含三种传输方式的配置示例） -``` - ---- - -### 实战示例：浏览器自动化 MCP 服务器 - -下面以**浏览器自动化**为例，展示三种传输方式的完整实现。 - -#### 场景说明 -创建一个 MCP 服务器，让 Claude 能够控制浏览器进行自动化操作： -- 打开网页 -- 截取屏幕截图 -- 点击元素 -- 填写表单 -- 获取页面内容 - -#### 选项 1：STDIO 方式（本地浏览器控制） - -**适用场景：** 在本地机器上控制本地安装的 Chrome/Edge 浏览器 - -**Claude Desktop 配置：** -```json -{ - "mcpServers": { - "browser-stdio": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-puppeteer"] - } - } -} -``` - -**使用 Prompt 生成 STDIO 版本：** - -``` -# 角色 -你是一个 MCP 服务器开发专家。 - -# 任务 -创建一个基于 Puppeteer 的浏览器自动化 MCP 服务器，使用 STDIO 传输。 - -# 功能要求 -1. navigate(url): 导航到指定 URL -2. screenshot(): 截取当前页面截图（返回 base64） -3. click(selector): 点击指定元素 -4. type(selector, text): 在输入框中输入文本 -5. get_content(): 获取页面文本内容 -6. evaluate(script): 执行 JavaScript 代码 - -# 技术要求 -1. 使用 TypeScript + @modelcontextprotocol/sdk -2. 使用 StdioServerTransport -3. 使用 puppeteer 控制浏览器 -4. 浏览器以 headless 模式启动 -5. 每个工具调用后保持页面状态 -6. 支持错误处理（如元素不存在、导航失败） - -# 输出格式 -请提供完整的 package.json、tsconfig.json 和 src/index.ts -``` - -#### 选项 2：SSE 方式（远程浏览器控制） - -**适用场景：** 浏览器运行在远程服务器，Claude 通过 SSE 长连接实时接收浏览器事件 - -**Claude Desktop 配置：** -```json -{ - "mcpServers": { - "browser-sse": { - "url": "http://localhost:3000/sse", - "transport": "sse" - } - } -} -``` - -**使用 Prompt 生成 SSE 版本：** - -``` -# 角色 -你是一个 MCP 服务器开发专家。 - -# 任务 -创建一个基于 Playwright 的浏览器自动化 MCP 服务器，使用 SSE 传输。 - -# 功能要求 -1. navigate(url): 导航到指定 URL -2. screenshot(): 截取当前页面截图 -3. click(selector): 点击指定元素 -4. type(selector, text): 在输入框中输入文本 -5. get_content(): 获取页面文本内容 -6. wait_for_selector(selector): 等待元素出现 -7. on_page_event(): 监听页面事件（console, request, response） - -# 传输方式要求 -- 使用 SSE 传输 -- 服务器运行在 http://localhost:3000 -- /sse 端点用于建立 SSE 连接 -- /message 端点用于接收客户端消息 -- 支持多浏览器实例管理（每个客户端独立浏览器） - -# 技术要求 -1. 使用 TypeScript + @modelcontextprotocol/sdk -2. 使用 SSEServerTransport -3. 使用 playwright 控制浏览器 -4. 基于 Express 创建 HTTP 服务器 -5. 实现会话管理（每个 SSE 连接对应一个浏览器上下文） -6. 支持 CORS - -# 输出格式 -请提供完整的项目文件和 README.md -``` - -#### 选项 3：HTTP 方式（RESTful 浏览器服务） - -**适用场景：** 将浏览器自动化作为微服务部署，支持水平扩展和负载均衡 - -**Claude Desktop 配置：** -```json -{ - "mcpServers": { - "browser-http": { - "url": "http://browser-service.company.com/mcp", - "transport": "http", - "headers": { - "Authorization": "Bearer your-api-token" - } - } - } -} -``` - -**使用 Prompt 生成 HTTP 版本：** - -``` -# 角色 -你是一个 MCP 服务器开发专家。 - -# 任务 -创建一个基于 Playwright 的浏览器自动化 MCP 服务器，使用 HTTP 传输。 - -# 功能要求 -1. navigate(url): 导航到指定 URL -2. screenshot(): 截取当前页面截图 -3. click(selector): 点击指定元素 -4. type(selector, text): 在输入框中输入文本 -5. get_content(): 获取页面文本内容 -6. create_session(): 创建新的浏览器会话 -7. close_session(sessionId): 关闭指定会话 - -# 传输方式要求 -- 使用 Streamable HTTP 传输 -- 服务器运行在 http://localhost:3000 -- /mcp 端点处理所有 MCP 请求 -- 支持 Bearer Token 认证 -- 支持流式响应（大页面内容分块返回） -- 支持会话持久化（通过 sessionId） - -# 技术要求 -1. 使用 TypeScript + @modelcontextprotocol/sdk -2. 使用 StreamableHTTPServerTransport -3. 使用 playwright 控制浏览器 -4. 基于 Express 创建 HTTP 服务器 -5. 实现 JWT 认证中间件 -6. 实现会话池管理 -7. 支持流式响应 - -# 输出格式 -请提供完整的项目文件、Dockerfile 和部署说明 -``` - ---- - -### 浏览器 MCP 使用示例 - -配置好浏览器 MCP 后，你可以在 Claude 中进行以下操作： - -#### 示例 1：网页截图分析 -``` -用户：帮我打开 https://example.com 并截图，然后分析一下这个网页的设计 - -Claude： -1. 调用 browser_navigate 导航到网页 -2. 调用 browser_screenshot 截取屏幕 -3. 分析截图中的布局、配色、字体等设计元素 -``` - -#### 示例 2：自动化表单填写 -``` -用户：帮我登录 GitHub，用户名是 xxx，密码是 yyy - -Claude： -1. 调用 browser_navigate 打开 https://github.com/login -2. 调用 browser_type 在 #login_field 输入用户名 -3. 调用 browser_type 在 #password 输入密码 -4. 调用 browser_click 点击登录按钮 -5. 调用 browser_screenshot 确认登录成功 -``` - -#### 示例 3：数据抓取 -``` -用户：帮我抓取 https://news.ycombinator.com 上的前 10 条新闻标题 - -Claude： -1. 调用 browser_navigate 打开 Hacker News -2. 调用 browser_get_content 获取页面内容 -3. 解析并返回前 10 条新闻标题和链接 -``` - -#### 示例 4：网页测试 -``` -用户：帮我测试一下我们的登录页面是否能正常工作 - -Claude： -1. 调用 browser_navigate 打开登录页 -2. 调用 browser_type 输入测试账号 -3. 调用 browser_click 点击登录 -4. 调用 browser_wait_for_selector 等待登录后的元素 -5. 调用 browser_screenshot 记录结果 -6. 返回测试报告 -``` - -### 工作流程 - -``` -1. 用户输入提示 - │ -2. MCP Client 发送（用户提示 + 系统提示 + 可用工具/资源）→ LLM - │ -3. 模型分析提示，决定调用哪个工具 - │ -4. 模型返回 API 调用及参数 → MCP Client - │ -5. MCP Client 发送请求 → MCP Server - │ -6. 工具执行并返回结果 - │ -7. MCP Server 返回结果 → MCP Client - │ -8. MCP Client 返回最终结果 → 用户 -``` - -## MCP 使用方式 - -### Claude Desktop 配置 - -Claude Desktop 是最常用的 MCP 客户端之一。 - -#### 配置文件位置 - -| 操作系统 | 配置文件路径 | -|---------|-------------| -| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` | -| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` | -| **Linux** | `~/.claude/mcp-config.json` | - -#### 基本配置格式 - -```json -{ - "mcpServers": { - "server-name": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"], - "env": { - "API_KEY": "your-api-key" - } - } - } -} -``` - -### Claude Code 配置 - -Claude Code（CLI 工具）也支持 MCP，配置更加灵活。 - -#### 用户级（全局）配置 - -```bash -claude mcp add-json --scope user '{ - "mcpServers": { - "server-name": { - "url": "http://127.0.0.1:8888/mcp", - "transport": "http" - } - } -}' -``` - -#### 项目级（本地）配置 - -```bash -claude mcp add-json --scope local '{ - "mcpServers": { - "server-name": { - "url": "http://127.0.0.1:8888/mcp", - "transport": "http" - } - } -}' -``` - -#### 添加远程 HTTP 服务器 - -```bash -claude mcp add --transport http https://mcp.notion.com/mcp -``` - -#### 验证命令 - -| 命令 | 功能 | -|-----|------| -| `/mcp` | 列出所有已连接的服务器 | -| `/doctor` | 检查 MCP 连接错误 | -| `claude mcp list` | 列出所有配置的 MCP 服务器 | -| `claude mcp get ` | 获取特定服务器详情 | -| `claude mcp remove ` | 移除服务器 | - -#### 配置文件位置 - -| 级别 | 配置文件位置 | -|-----|-------------| -| **用户级** | `~/.claude.json`（全局，所有项目） | -| **项目级** | `.claude/mcp.json`（项目特定） | - -## 推荐的 MCP 服务器 - -### 官方服务器 - -Anthropic 提供了 15 个官方参考服务器： - -| 服务器 | 功能 | 安装命令 | -|-------|------|---------| -| **@modelcontextprotocol/server-filesystem** | 文件系统访问 | `npx -y @modelcontextprotocol/server-filesystem /path` | -| **@modelcontextprotocol/server-sqlite** | SQLite 数据库 | `npx -y @modelcontextprotocol/server-sqlite` | -| **@modelcontextprotocol/server-postgres** | PostgreSQL 数据库 | `npx -y @modelcontextprotocol/server-postgres` | -| **@modelcontextprotocol/server-github** | GitHub 集成 | `npx -y @modelcontextprotocol/server-github` | -| **@modelcontextprotocol/server-git** | Git 操作 | `npx -y @modelcontextprotocol/server-git` | -| **@modelcontextprotocol/server-brave-search** | Brave 搜索 | `npx -y @modelcontextprotocol/server-brave-search` | -| **@modelcontextprotocol/server-fetch** | 网页抓取 | `npx -y @modelcontextprotocol/server-fetch` | -| **@modelcontextprotocol/server-puppeteer** | 浏览器自动化 | `npx -y @modelcontextprotocol/server-puppeteer` | - -### 社区热门服务器 - -根据 GitHub 星标数，以下是最受欢迎的社区 MCP 服务器： - -| 服务器 | Stars | 功能描述 | -|-------|-------|---------| -| **MarkItDown** (Microsoft) | 84,703⭐ | 将 PDF、Word、Excel、图片、音频转换为 Markdown | -| **Netdata** | 77,164⭐ | 实时基础设施监控 | -| **Context7** (Upstash) | 40,332⭐ | 最新代码库文档和示例 | -| **GitHub** (Official) | 25,487⭐ | GitHub 仓库管理、Issues、PR 工作流 | -| **Playwright** (Microsoft) | 24,855⭐ | 浏览器自动化和 Web 测试 | -| **ChromeDevTools** | 18,136⭐ | Chrome DevTools 协议集成 | -| **Serena** (Oraios) | 17,796⭐ | 语义代码搜索和编辑 | -| **Firecrawl** | 5,137⭐ | 网页抓取转为结构化数据 | -| **Unity** | 4,453⭐ | 通过本地桥接控制 Unity 编辑器 | -| **Notion** (Official) | 3,632⭐ | 官方 Notion API 接口 | - -### MCP 服务器资源网站 - -| 网站 | URL | 描述 | -|-----|-----|------| -| **Awesome MCP Servers** | [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) | GitHub 上最全面的列表，3,000+ 服务器 | -| **Official MCP Registry** | https://registry.modelcontextprotocol.io | Anthropic 官方「应用商店」 | -| **MCP.so** | https://mcp.so | 社区 MCP 服务器中心 | -| **Glama.ai** | https://glama.ai/mcp/servers | 分类良好的 MCP 目录 | -| **Smithery** | https://smithery.ai | MCP 服务器市场 | - -## MCP 地点服务 - -地点和地图服务是 MCP 的重要应用场景之一。以下是目前主流的地点类 MCP 服务器： - -### 高德地图 MCP Server - -高德地图是中文环境下最推荐的地图服务 MCP 服务器。 - -**功能特性（12+ 核心服务）：** - -| 功能 | 说明 | -|-----|------| -| **地理编码** | 地址 → 坐标转换 | -| **逆地理编码** | 坐标 → 详细地址 | -| **POI 搜索** | 关键词搜索、周边搜索、多边形区域搜索 | -| **路线规划** | 驾车、步行、骑行、公交路线 | -| **坐标转换** | 支持 GPS、百度、图吧坐标系 | -| **距离测量** | 精确距离计算 | -| **IP 定位** | 通过 IP 地址获取位置 | -| **天气查询** | 实时天气和预报数据 | - -**配置方式：** - -```json -{ - "mcpServers": { - "amap": { - "command": "npx", - "args": ["-y", "mcp-amap"], - "env": { - "AMAP_API_KEY": "your-amap-api-key" - } - } - } -} -``` - -**获取 API Key：** 访问 [高德开放平台](https://lbs.amap.com/) 注册并创建应用。 - -### 腾讯位置服务 MCP - -**功能特性：** - -- 地理编码和逆地理编码 -- IP 定位 -- 天气查询 -- 路线规划（驾车、步行、骑行、公交） -- 距离测量 -- 关键词搜索和周边搜索 - -**优势：** -- 无需本地部署 -- 自动更新 -- 针对 LLM 理解优化的语义 JSON 转换 -- 支持 SSE 协议 - -### Google Maps MCP Server - -**NPM 包：** `@cablate/mcp-google-map` - -**功能特性：** - -| 功能 | 说明 | -|-----|------| -| **地点搜索** | 根据关键词或类型搜索地点 | -| **地理编码** | 地址 → 坐标 | -| **逆地理编码** | 坐标 → 地址 | -| **路线规划** | 驾车、步行、骑行、公交路线 | -| **周边搜索** | 搜索指定位置附近的地点 | -| **地点详情** | 获取地点的详细信息 | - -**配置示例：** - -```json -{ - "mcpServers": { - "google-map": { - "command": "npx", - "args": ["-y", "@cablate/mcp-google-map"], - "env": { - "GOOGLE_MAPS_API_KEY": "your-google-maps-api-key" - } - } - } -} -``` - -**获取 API Key：** 访问 [Google Cloud Console](https://console.cloud.google.com/) 启用 Maps JavaScript API。 - -### OpenStreetMap MCP Server - -OpenStreetMap 是开源的地图服务，使用 Nominatim API 进行地点查询。 - -**Python 实现示例（使用 FastMCP）：** - -```python -from fastmcp import FastMCP -import requests - -mcp = FastMCP("osm-mcp-server") - -@mcp.tool() -def search_location(query: str) -> str: - """搜索地点并返回坐标和地址信息 - - Args: - query: 地点名称或地址 - """ - url = "https://nominatim.openstreetmap.org/search" - params = { - "q": query, - "format": "json", - "addressdetails": 1 - } - response = requests.get(url, params=params) - return response.json() - -@mcp.tool() -def reverse_geocode(lat: float, lon: float) -> str: - """根据坐标获取详细地址 - - Args: - lat: 纬度 - lon: 经度 - """ - url = "https://nominatim.openstreetmap.org/reverse" - params = { - "lat": lat, - "lon": lon, - "format": "json" - } - response = requests.get(url, params=params) - return response.json() -``` - -**优势：** -- 完全免费 -- 无需 API Key -- 开源数据 - -### 天气 MCP Server - -天气服务通常与地点服务配合使用。 - -#### 彩云天气 MCP Server - -**GitHub：** [caiyunapp/mcp-caiyun-weather](https://github.com/caiyunapp/mcp-caiyun-weather) - -**提供工具：** - -| 工具 | 功能 | -|-----|------| -| `get_realtime_weather` | 获取实时天气 | -| `get_hourly_forecast` | 获取 72 小时预报 | -| `get_weekly_forecast` | 获取 7 天预报 | -| `get_historical_weather` | 获取 24 小时历史数据 | -| `get_weather_alerts` | 获取天气预警 | - -#### OpenWeatherMap MCP Server - -**GitHub：** [CodeByWaqas/weather-mcp-server](https://github.com/CodeByWaqas/weather-mcp-server) - -**功能特性：** -- 实时天气数据 -- 温度、湿度、风速 -- 日出日落时间 -- 天气描述 - -**安装命令：** -```bash -npx -y @smithery/cli install @CodeByWaqas/weather-mcp-server --client claude -``` - -### 实际应用示例 - -#### 示例 1：旅行规划助手 - -结合高德地图和彩云天气，可以创建一个智能旅行规划助手： - -``` -用户：帮我规划从北京到上海的行程，想知道沿途天气情况 - -Claude： -1. 调用 maps_text_search 搜索北京到上海的路线 -2. 调用 maps_weather 获取沿途城市天气 -3. 返回带天气信息的旅行建议 -``` - -#### 示例 2：周边服务查找 - -``` -用户：帮我找附近的咖啡店 - -Claude： -1. 调用 maps_ip_location 获取当前位置 -2. 调用 maps_around_search 搜索周边咖啡店 -3. 返回按距离排序的咖啡店列表 -``` - -#### 示例 3：坐标地址转换 - -``` -用户：这个坐标 39.9087,116.3975 在哪里？ - -Claude： -1. 调用 maps_regeocode 进行逆地理编码 -2. 返回：北京市东城区长安街（天安门广场附近） -``` - -## 用 AI 生成 MCP 服务 - -你不需要从头编写 MCP 服务器——让 AI 帮你完成！以下是经过验证的提示词模板。 - -### 方式一：让 Claude 生成完整 MCP 服务器 - -``` -# 角色 -你是一个 MCP 服务器开发专家。 - -# 任务 -请帮我创建一个 MCP 服务器，功能是：[描述你的功能需求] - -# 要求 -1. 使用 TypeScript/Python（二选一） -2. 基于 @modelcontextprotocol SDK 或 FastMCP -3. 包含完整的 package.json 和安装说明 -4. 实现错误处理和日志输出 -5. 添加详细的 JSDoc/docstring 注释 -6. 提供 Claude Desktop 配置示例 - -# 输出格式 -请直接输出完整的代码文件内容，每个文件用 --- 文件名 --- 分隔。 -``` - -### 示例：生成天气 MCP 服务器 - -``` -# 角色 -你是一个 MCP 服务器开发专家。 - -# 任务 -请帮我创建一个天气查询 MCP 服务器。 - -# 功能要求 -1. 提供获取实时天气的工具（get_weather） -2. 支持城市名称查询 -3. 使用免费的 wttr.in API（无需 API key） -4. 返回温度、天气状况、湿度等信息 - -# 技术要求 -1. 使用 Python + FastMCP -2. 包含完整的 setup.py 和 requirements.txt -3. 实现错误处理（城市不存在时给出友好提示） -4. 添加使用说明 - -# 输出格式 -请按以下格式输出： - ---- main.py --- -[代码内容] - ---- requirements.txt --- -[内容] - ---- README.md --- -[使用说明] - ---- claude-config.json --- -[Claude Desktop 配置示例] -``` - -### 方式二：让 Cursor/Windsurf AI 生成项目 - -在使用 Cursor 或 Windsurf 等 AI IDE 时，可以使用这个提示词： - -``` -创建一个完整的 MCP 服务器项目，功能是 [你的需求]。 - -项目要求： -1. 语言：TypeScript -2. 包含完整的 tsconfig.json 和 package.json -3. 使用 @modelcontextprotocol/sdk -4. 实现至少 2 个工具 -5. 添加单元测试 -6. 包含 README.md 和使用示例 -7. 支持 npx 直接运行 - -请创建完整的项目结构。 -``` - -### 示例：生成笔记 MCP 服务器 - -``` -创建一个完整的 MCP 服务器项目，功能是管理本地 Markdown 笔记。 - -项目要求： -1. 语言：TypeScript -2. 包含完整的 tsconfig.json 和 package.json -3. 使用 @modelcontextprotocol/sdk - -工具要求： -1. list_notes(): 列出指定目录下的所有笔记 -2. read_note(path): 读取笔记内容 -3. create_note(title, content): 创建新笔记 -4. search_notes(keyword): 搜索包含关键词的笔记 -5. delete_note(path): 删除笔记 - -额外要求： -1. 笔记存储在 ~/notes 目录 -2. 每个笔记是独立的 .md 文件 -3. 文件名使用日期-标题格式（如 2025-02-28-my-note.md） -4. 添加单元测试 -5. 包含 README.md 和 Claude Desktop 配置示例 - -请创建完整的项目结构。 -``` - -### 方式三：增量开发提示词 - -如果你已经有基础代码，想让 AI 帮你完善： - -``` -# 当前代码 -[粘贴你现有的 MCP 服务器代码] - -# 需要添加的功能 -1. [具体功能1] -2. [具体功能2] - -# 要求 -1. 保持现有代码结构 -2. 只输出修改/新增的部分 -3. 标注修改的位置 -``` - -### 调试提示词 - -当 MCP 服务器出现问题时： - -``` -我的 MCP 服务器有问题，请帮我诊断： - -# 问题现象 -[描述具体问题，如：工具无法调用、报错等] - -# 配置 -[粘贴 claude_desktop_config.json 中的服务器配置] - -# 错误日志 -[粘贴 Claude Desktop 的错误日志或服务器输出] - -# 服务器代码 -[粘贴相关代码片段] - -请分析可能的原因并给出解决方案。 -``` - -### AI 生成后的验证清单 - -生成代码后，让 AI 帮你验证： - -``` -请检查这个 MCP 服务器： - -# 验证清单 -1. [ ] 是否正确实现了 MCP 协议？ -2. [ ] 工具的 inputSchema 是否符合 JSON Schema 规范？ -3. [ ] 错误处理是否完善？ -4. [ ] 是否有安全风险（如路径遍历、命令注入）？ -5. [ ] 配置示例是否正确？ -6. [ ] README 是否包含完整的使用说明？ - -如果发现问题，请指出并给出修复建议。 -``` - -## 开发自定义 MCP 服务器 - -### TypeScript 实现 - -```typescript -import { Server } from "@modelcontextprotocol/sdk/server/index.js"; -import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; -import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js"; - -// 创建服务器实例 -const server = new Server( - { - name: "my-mcp-server", - version: "0.1.0", - }, - { - capabilities: { - tools: {}, - }, - } -); - -// 注册工具列表 -server.setRequestHandler(ListToolsRequestSchema, async () => { - return { - tools: [ - { - name: "my_tool", - description: "我的自定义工具", - inputSchema: { - type: "object", - properties: { - param: { - type: "string", - description: "参数描述", - }, - }, - required: ["param"], - }, - }, - ], - }; -}); - -// 处理工具调用 -server.setRequestHandler(CallToolRequestSchema, async (request) => { - const { name, arguments: args } = request.params; - - if (name === "my_tool") { - return { - content: [ - { - type: "text", - text: `执行结果：${args.param}`, - }, - ], - }; - } - - throw new Error(`Unknown tool: ${name}`); -}); - -// 启动服务器 -async function main() { - const transport = new StdioServerTransport(); - await server.connect(transport); - console.error("My MCP Server running on stdio"); -} - -main().catch(console.error); -``` - -### Python 实现（使用 FastMCP） - -```python -from mcp.server.fastmcp import FastMCP - -# 创建 MCP 服务器 -mcp = FastMCP("my-mcp-server") - -@mcp.tool() -def calculate(expression: str) -> str: - """计算数学表达式 - - Args: - expression: 数学表达式，如 "2 + 2" - """ - try: - result = eval(expression) - return f"结果: {result}" - except Exception as e: - return f"错误: {str(e)}" - -@mcp.resource("data://config") -def get_config() -> str: - """获取配置信息""" - return '{"setting": "value"}' - -# 启动服务器 -if __name__ == "__main__": - mcp.run() -``` - -## MCP 最佳实践 - -### 安全建议 - -1. **最小权限原则**：只授予 MCP 服务器必要的权限 -2. **沙箱隔离**：使用容器或虚拟环境运行不可信的服务器 -3. **认证授权**：HTTP 传输使用 OAuth 2.1 或类似机制 -4. **数据验证**：验证所有输入参数，防止注入攻击 -5. **审计日志**：记录所有工具调用和资源访问 - -### 开发建议 - -1. **渐进式实现**：先实现核心功能，再逐步添加高级特性 -2. **错误处理**：提供清晰的错误消息和恢复建议 -3. **文档完善**：为每个工具提供详细描述和示例 -4. **性能优化**：缓存频繁访问的资源，减少延迟 -5. **兼容性测试**：在不同客户端上测试服务器兼容性 - -### 生产环境建议 - -1. **容器化部署**：使用 Docker 打包 MCP 服务器 -2. **健康检查**：实现健康检查端点 -3. **监控告警**：监控服务器性能和错误率 -4. **优雅降级**：服务不可用时提供友好降级方案 -5. **特性开关**：使用特性开关控制新功能发布 - -## MCP 生态现状 - -根据 2025 年的数据统计： - -| 指标 | 数量 | -|-----|------| -| MCP 服务器总数 | ~14,000 | -| MCP 客户端 | ~300 | -| 官方参考服务器 | 15 | -| GitHub 社区服务器 | 200+ | -| 企业级服务器 | 50+ | -| 实验性项目 | 235+ | - -**主要支持的 AI 平台：** -- Claude Desktop / Claude Code -- Cursor IDE -- Cherry Studio -- ModelScope (通义千问) -- Gemini CLI -- Windsurf - -## MCP 服务器资源 - 去哪里找更多 MCP 服务器？ - -### 官方资源 - -- [Official MCP Registry](https://registry.modelcontextprotocol.io) - Anthropic 官方「应用商店」 -- [MCP 官方文档](https://modelcontextprotocol.io) - 官方文档和规范 -- [MCP 官方 GitHub](https://github.com/modelcontextprotocol) - 官方服务器和 SDK - -### MCP 市场与目录 - -- [MCPmarket.cn](https://mcpmarket.cn) - 中文 MCP 市场 -- [MCP.so](https://mcp.so) - 社区 MCP 中心 -- [MCPServers](https://www.mcpservers.cn) - 中文 MCP 社区 -- [MCP.ad](https://mcp.ad) - 国际聚合平台 -- [MCPFlow](https://mcpflow.io/home) - 中文社区平台 -- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) - GitHub 最全面列表 -- [Glama.ai MCP](https://glama.ai/mcp/servers) - 带评分评论的 MCP 目录 -- [Smithery](https://smithery.ai) - MCP 服务器市场 -- [MCPHub](https://mcphub.io/registry) - 界面简洁的目录 -- [MCPHunt](https://www.mcphunt.com/zh) - 「MCP 版 Product Hunt」 -- [PulseMCP](https://www.pulsemcp.com/servers) - 实时更新的 MCP 目录 -- [LobeHub MCP](https://lobehub.com/zh/mcp) - 中文 MCP 目录 - -### IDE 专属市场 - -- [Cursor Directory MCP](https://cursor.directory/mcp) - Cursor 优化 -- [Cline MCP Marketplace](https://cline.bot/mcp-marketplace) - VSCode 集成 - -### 国内大厂平台 - -- [ModelScope MCP 广场](https://www.modelscope.cn/mcp) - 阿里魔搭社区 -- [百度 MCP 平台](https://sai.baidu.com/ai/mcp) - 百度千帆 -- [阿里云百练 MCP](https://bailian.console.aliyun.com) - 阿里云 - -## 参考资源 - -### 官方文档 -- [Model Context Protocol 官方网站](https://modelcontextprotocol.io/) -- [MCP 规范文档](https://modelcontextprotocol.io/specification/) -- [Claude Code MCP 官方文档](https://docs.anthropic.com/zh-CN/docs/claude-code/mcp) -- [MCP GitHub 仓库](https://github.com/modelcontextprotocol) - -### 教程文章 -- [一文讲透 MCP 的原理及实践](https://view.inews.qq.com/a/20250414A023WV00) -- [MCP（Model Context Protocol）架构与工作原理](https://m.toutiao.com/w/1826385835060307/) -- [2025 最全 MCP 图像生成指南](https://juejin.cn/post/7576838552472043563) -- [Claude MCP 完全策略：AI 应用的无限可能](https://juejin.cn/post/7576838552472043563) -- [2025 大模型最新教程：MCP 协议从入门到精通](https://m.blog.csdn.net/weixin_45653328/article/details/150916706) -- [从零开始学 MCP（八）- 构建一个 MCP server](https://juejin.cn/post/7582510291667419187) - -### 配置指南 -- [Claude Code MCP 配置完全指南](https://juejin.cn/post/7576838552472043563)（2025 年 8 月最新） -- [最新 Claude Code 超详细完全指南](https://m.blog.csdn.net/) -- [Claude Code 最佳实践](https://www.anthropic.com/engineering/claude-code-best-practices) - -### 开发教程 -- [零基础构建 MCP 服务器 TypeScript/Python 双语言实战指南](https://m.blog.csdn.net/ztt123654/article/details/150844207) -- [终极 MCP 服务器构建指南：TypeScript 与 Python 双版本完整教程](https://m.blog.csdn.net/gitblog_00703/article/details/154862128) -- [使用 TypeScript 构建一个最简单的 MCP 服务器](https://m.blog.csdn.net/weixin_45653525/article/details/148433757) -- [使用 Azure 容器应用生成 TypeScript MCP 服务器](https://learn.microsoft.com/zh-cn/azure/developer/ai/build-mcp-server-ts) - -### 地图和天气服务 -- [高德地图 MCP Server](https://lobehub.com/zh/mcp/luozengchang-mcp-amap) -- [腾讯位置服务 MCP 文档](https://lbs.qq.com/service/MCPServer/MCPServerGuide/overview) -- [彩云天气 MCP Server](https://github.com/caiyunapp/mcp-caiyun-weather) -- [OpenWeatherMap MCP Server](https://github.com/CodeByWaqas/weather-mcp-server) -- [Valhalla MCP Server（OpenStreetMap 路由）](https://lobehub.com/mcp/aatakansalar-valhalla-mcp) - -### 社区资源 -- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) - 最全面的 MCP 服务器列表 -- [Everything Claude Code Config](https://github.com/affaan-m/everything-claude-code) - 生产级 Claude Code 配置集合 -- [AI Coding Guide](https://github.com/hacket/AICodingGuide) - Claude Code 中文学习路径 - -### 实际应用案例 -- [BlenderMCP - AI 驱动的 3D 建模](https://github.com/Belthur/blender-mcp) - 4,100+ ⭐ -- [MCP 生产环境 15 条最佳实践](https://learn.microsoft.com/zh-cn/azure/azure-functions/scenario-mcp-apps) diff --git a/docs/zh-cn/stage-3/core-skills/3.4-agent-teams/index.md b/docs/zh-cn/stage-3/core-skills/agent-teams/index.md similarity index 100% rename from docs/zh-cn/stage-3/core-skills/3.4-agent-teams/index.md rename to docs/zh-cn/stage-3/core-skills/agent-teams/index.md diff --git a/docs/zh-cn/stage-3/core-skills/basics/index.md b/docs/zh-cn/stage-3/core-skills/basics/index.md new file mode 100644 index 0000000..ded2e9e --- /dev/null +++ b/docs/zh-cn/stage-3/core-skills/basics/index.md @@ -0,0 +1,1731 @@ +# Claude Code 快速上手核心指南 + +Claude Code 是 Anthropic 官方出品的 AI 原生编码工具，它将大型语言模型的能力直接集成到终端中，让你可以用自然语言与 AI 协作完成编程任务。不同于传统的代码补全工具，Claude Code 能够理解整个项目的上下文，执行复杂的开发任务，从代码生成到重构、从调试到文档编写，它都能胜任。 + +本章将带你快速掌握 Claude Code 的核心用法，包括安装配置、基础操作、实用技巧和常用指令。无论你是第一次接触 AI 编程工具，还是想更高效地使用 Claude Code，这里都有你需要的知识。 + +--- + +## 快速安装 + +Claude Code 基于 Node.js 构建，因此安装前请确保你的系统已安装 Node.js 18 或更高版本。安装过程非常简单，通常只需要几分钟。 + +### 为什么需要 Claude Code + +在传统的开发流程中，开发者需要在编辑器、终端、浏览器和文档之间频繁切换。Claude Code 将这些工作流整合到一个统一的界面中：你可以在同一个终端窗口里编写代码、运行测试、查看文档、甚至与团队成员协作。更重要的是，它能理解你的项目结构，记住你的编码习惯，真正成为你的编程助手。 + +### 方法一：手动安装 + +手动安装适合喜欢掌控每个步骤的开发者，也让你更清楚工具的组成部分。 + +```bash +# 全局安装 Claude Code CLI +# 使用 -g 参数将命令安装到全局，这样在任何目录都能使用 +npm install -g @anthropic-ai/claude-code + +# 验证安装是否成功 +# 如果显示版本号（如 0.1.25），说明安装成功 +claude --version +``` + +安装过程中，npm 会自动下载所有依赖并配置好环境变量。如果遇到权限问题，可以尝试在命令前加 `sudo`（macOS/Linux）或以管理员身份运行终端（Windows）。 + +### 方法二：让 AI Agent 帮你安装 + +如果你已经在使用其他 AI 编程助手（如 Cursor、Windsurf 或本项目的 AI Agent），可以让它们帮你完成安装。这种方式的好处是 AI 会自动检测你的环境，处理可能出现的依赖冲突，并根据你的系统配置选择最优的安装方式。 + +**直接这样说就行：** + +``` +帮我装 anthropic 的 claude code +``` + +或者更具体一点： + +``` +安装 claude code cli，并检查 Node.js 版本是否兼容 +``` + +AI Agent 会： +1. 检查当前 Node.js 版本 +2. 如果不符合要求，提示你升级 +3. 执行安装命令 +4. 验证安装结果 +5. 如有问题，自动尝试修复 + +### 首次启动与初始化 + +安装完成后，进入你的项目目录启动 Claude Code： + +```bash +# 进入项目目录（Claude Code 会在当前目录下工作） +cd /path/to/your/project + +# 启动 Claude Code +claude +``` + +首次启动时，Claude Code 会引导你完成几个重要的初始化步骤： + +1. **登录 Anthropic 账户**：你需要有一个 Anthropic 账户才能使用 Claude Code。如果没有，系统会提示你注册。 + +2. **选择使用计划**： + - **免费计划**：适合个人学习和轻量级使用，有一定的调用限制 + - **Pro 计划**：适合专业开发者，提供更高的调用配额和优先响应 + +3. **同意使用条款**：阅读并同意 Anthropic 的服务条款和隐私政策 + +4. **可选：配置 API 密钥**：如果你有自定义的 API 密钥（比如通过第三方服务提供商获取的），可以在此时配置 + +::: info 中国区用户的特别说明 + +由于网络原因，中国区的用户可能无法直接访问 Anthropic 的官方服务。Claude Code 支持使用兼容 Anthropic API 格式的第三方服务，这在技术上是完全可行的。 + +**你有两个选择：** + +1. **直接使用 API Token**：购买兼容 Anthropic API 的服务商提供的 Token，通过环境变量配置 +2. **使用 Coding Plan**：一些服务商提供专门的 Coding Plan，针对代码场景优化，通常更实惠 + +**推荐做法**：直接让 AI Agent 帮你完成配置。只需提供厂商给的配置信息（如 API 地址、密钥等），AI 会自动设置正确的环境变量。 + +**更详细的配置指南请参考：** [如何安装 claudecode 以及如何配置环境变量](/zh-cn/stage-2/backend/2.6-modern-cli/) + +::: + +--- + +## 快速开始：做点小实验 + +安装完成后，不要急于在正式项目中使用，建议先做几个小实验来熟悉 Claude Code 的工作方式。这 3 个实验设计得由浅入深，分别对应 Claude Code 的三种核心能力：自然语言理解、内容生成和代码执行。 + +### 实验 1：对话 —— 感受 AI 的理解能力 + +这个实验的目的是让你体验 Claude Code 的自然语言理解能力。与普通的搜索引擎不同，Claude Code 能够理解上下文、进行多轮对话，并根据你的反馈调整回答。 + +**试试这些对话：** + +``` +你好，你是谁？ +``` +Claude 会介绍自己是 Claude Code，Anthropic 开发的 AI 编程助手。 + +``` +什么是闭包？太长不看版本 +``` +观察 Claude 如何根据"太长不看"这个提示，给出简洁但准确的解释。 + +``` +JavaScript 和 TypeScript 有什么区别？ +``` +这个问题涉及技术对比，看 Claude 能否给出结构化的、有深度的回答。 + +**实验要点**：注意 Claude 的回答风格——它通常会先给出核心结论，再展开细节。这种"倒金字塔"式的回答方式非常适合快速获取信息。 + +### 实验 2：生成 Markdown 文档 —— 体验内容创作 + +这个实验展示 Claude Code 的内容生成能力。对于开发者来说，写文档往往是最头疼的事情之一。Claude 可以根据你的要求快速生成结构清晰、内容完整的文档。 + +**输入这个指令：** + +``` +帮我写一份 Git 常用命令的 Markdown 文档 +要求：包含命令、说明、示例 +``` + +**Claude 会做什么：** + +1. 分析你的需求：Git 常用命令、Markdown 格式、三要素（命令、说明、示例） +2. 规划文档结构：通常会按使用场景分类（初始化、日常开发、分支管理、远程协作等） +3. 生成内容：为每个命令提供简洁说明和实用示例 +4. 格式化输出：使用 Markdown 语法，确保格式规范 + +**预期输出示例**： + +```markdown +# Git 常用命令速查表 + +## 初始化仓库 + +| 命令 | 说明 | 示例 | +|------|------|------| +| `git init` | 初始化新仓库 | `git init my-project` | +| `git clone` | 克隆远程仓库 | `git clone https://github.com/user/repo.git` | + +... +``` + +**进阶尝试**：你可以增加更多要求，比如"添加中文注释"、"按使用频率排序"、"包含常见错误处理"等，观察 Claude 如何调整输出。 + +### 实验 3：编写并运行游戏 —— 完整的代码工作流 + +这个实验是最具挑战性的，它展示了 Claude Code 的完整代码工作流：理解需求、编写代码、创建文件、运行程序、处理错误。通过这个实验，你能真正感受到 AI 编程助手的威力。 + +**输入这个指令：** + +``` +用 Python 写一个贪吃蛇游戏 +要求： +1. 使用 pygame 库 +2. 有分数显示 +3. 按 ESC 退出 + +写完后帮我运行它 +``` + +**Claude 会执行以下步骤：** + +**步骤 1：检查环境** +- 检查 Python 是否安装 +- 检查 pygame 库是否可用 +- 如有缺失，提示你安装 + +**步骤 2：编写代码** +- 创建游戏主文件（如 `snake_game.py`） +- 实现游戏逻辑：蛇的移动、食物生成、碰撞检测 +- 添加分数显示功能 +- 实现 ESC 键退出 + +**步骤 3：运行游戏** +- 执行 Python 脚本启动游戏 +- 游戏窗口会弹出，你可以用方向键控制蛇 + +**步骤 4：后续支持** +- 如果游戏有 bug，你可以直接说"蛇穿墙了，修复一下" +- 如果想加功能，比如"增加难度随分数提升"，Claude 会继续修改 + +**这个实验的价值**： + +1. **验证安装**：确保 Claude Code 能正常执行代码 +2. **体验交互**：感受与 AI 协作开发的过程 +3. **建立信心**：看到 AI 能独立完成一个完整的可运行程序 + +**常见问题**： + +- **Q: 如果我没有安装 pygame？** + - A: Claude 会检测到并提示你运行 `pip install pygame`，你也可以让 Claude 帮你安装 + +- **Q: 游戏运行后终端被占用了怎么办？** + - A: 按 ESC 退出游戏，或者在其他终端窗口继续使用 Claude Code + +- **Q: 可以换成其他编程语言吗？** + - A: 当然可以！试试"用 JavaScript 写"、"用 HTML5 Canvas 写"等 + +--- + +## 核心技巧 + +掌握这些技巧，能让你的 Claude Code 使用效率提升数倍。这些技巧来自实际开发经验，涵盖了最常用的操作场景。 + +### 技巧 1：双击 Esc 回退对话 —— 撤销误操作 + +这是 Claude Code 中最常用、最重要的快捷键。在与 AI 协作时，你可能会说错话、给错指令，或者对 AI 的回答不满意。双击 Esc 能让你快速"时光倒流"。 + +**快捷键详解：** + +``` +按一次 Esc → 清除当前正在输入的内容（类似 Ctrl+C） +按两次 Esc → 回退到上一次对话状态（撤销上一轮对话） +按三次 Esc → 清除所有对话历史（重新开始） +``` + +**使用场景：** + +- **场景 A**：你不小心发了一个错误的指令，Claude 开始执行了。快速按两次 Esc，回到执行前的状态。 +- **场景 B**：Claude 的回复不是你想要的，你想换个方式提问。双击 Esc 撤销，重新组织语言。 +- **场景 C**：对话已经进行了很多轮，上下文混乱了。三击 Esc 清空，重新开始。 + +**⚠️ 重要注意**：双击 Esc 回退的是**对话状态**，不是代码修改。如果 Claude 已经修改了你的文件，这些修改不会被自动撤销。你需要手动用 `git checkout` 或 `git reset` 恢复文件。 + +**建议**：在进行可能大幅修改代码的操作前，先提交当前工作（`git commit` 或 `git stash`），这样即使出了问题也能快速恢复。 + +### 技巧 2：@ 引用文件 —— 精准指定上下文 + +Claude Code 虽然能自动读取项目文件，但显式地引用文件能让 AI 更准确地理解你的意图，也能避免 AI 读取不相关的文件浪费 Token。 + +**基本用法：** + +与其模糊地说： +``` +解释 src/utils.ts 这个文件 +``` + +不如直接引用： +``` +@src/utils.ts 解释这个文件 +``` + +**高级用法：** + +**多文件对比分析：** +``` +@src/app.tsx @src/components/Header.tsx 这两个文件的关系是什么？ +``` + +**引用目录：** +``` +@src/components/ 总结一下这个目录下的所有组件 +``` + +**引用特定行（配合代码编辑器）：** +``` +@src/utils.ts:45-60 解释这段代码的作用 +``` + +**使用技巧：** + +1. **Tab 补全**：输入 `@` 后按 Tab 键，Claude 会显示当前目录下的文件列表，可以用方向键选择 +2. **相对路径**：支持相对路径引用，如 `@./config.json` 或 `@../shared/types.ts` +3. **模糊匹配**：可以输入部分文件名，如 `@utils` 会匹配 `src/utils.ts` 或 `src/utils/index.ts` + +### 技巧 3：! 执行命令 —— 终端集成 + +Claude Code 内置了终端命令执行能力，无需切换到另一个终端窗口就能运行命令。 + +**基本用法：** + +``` +!npm test # 运行测试 +!git status # 查看 Git 状态 +!ls -la # 列出文件 +``` + +**实际应用场景：** + +**场景：运行测试并分析失败原因** +``` +!npm test +# 测试失败后 +分析一下测试失败的原因，并修复代码 +``` + +**场景：查看 Git 差异** +``` +!git diff +# 然后让 Claude 解释变更内容 +总结一下这些变更的主要内容 +``` + +**场景：构建项目** +``` +!npm run build +# 如果构建失败 +构建报错了，帮我修复 +``` + +**⚠️ 安全提示：** + +Claude Code 会询问是否执行某些敏感命令（如 `rm -rf`、`sudo` 等）。这是保护机制，请谨慎确认。 + +### 技巧 4：/plan 先规划后编码 —— 复杂任务的正确打开方式 + +对于复杂的开发任务，直接开始编码往往效率低下。`/plan` 命令让 Claude 进入规划模式，先制定详细的实施计划，再一步步执行。 + +**使用方式：** + +``` +/plan +我想添加用户认证功能，请帮我制定实施计划 +``` + +**Claude 会做什么：** + +1. **分析需求**：理解你要实现的功能 +2. **评估现状**：查看当前项目结构和技术栈 +3. **制定计划**：分步骤列出需要做的事情 +4. **确认方案**：与你讨论计划，根据反馈调整 + +**示例输出：** + +``` +📋 用户认证功能实施计划 + +阶段 1：数据库设计 +- [ ] 创建 users 表（id, email, password_hash, created_at） +- [ ] 创建 sessions 表（id, user_id, expires_at） + +阶段 2：后端 API +- [ ] POST /api/auth/register - 用户注册 +- [ ] POST /api/auth/login - 用户登录 +- [ ] POST /api/auth/logout - 用户登出 +- [ ] GET /api/auth/me - 获取当前用户 + +阶段 3：前端集成 +- [ ] 创建登录页面 +- [ ] 创建注册页面 +- [ ] 添加路由守卫 + +阶段 4：测试 +- [ ] 编写单元测试 +- [ ] 编写集成测试 + +你想从哪个阶段开始？或者需要调整计划？ +``` + +**最佳实践：** + +- 对于超过 30 分钟的任务，先用 `/plan` +- 计划制定后，可以逐阶段执行，每完成一个阶段检查一次 +- 如果需求变更，可以重新运行 `/plan` 调整计划 + +### 技巧 5：/init 自动生成配置 —— 快速初始化项目 + +`/init` 是 Claude Code 最强大的命令之一。它能自动扫描你的项目，理解技术栈和结构，然后生成一份完整的 `CLAUDE.md` 配置文件。 + +**使用方式：** + +``` +/init +``` + +**Claude 会执行以下步骤：** + +1. **扫描项目结构**：识别框架、语言、构建工具 +2. **分析配置文件**：读取 package.json、tsconfig.json 等 +3. **检查代码风格**：了解命名规范、文件组织方式 +4. **生成 CLAUDE.md**：创建包含项目信息的配置文件 + +**生成的 CLAUDE.md 示例：** + +```markdown +# My Project + +## 技术栈 +- 框架：Next.js 14 (App Router) +- 语言：TypeScript +- 样式：Tailwind CSS +- 状态管理：Zustand +- 数据库：Prisma + PostgreSQL + +## 常用命令 +```bash +npm run dev # 启动开发服务器 +npm run build # 生产构建 +npm run test # 运行测试 +npx prisma migrate dev # 数据库迁移 +``` + +## 代码规范 +- 使用函数组件 + Hooks +- 文件命名：PascalCase（组件）、camelCase（工具函数） +- 提交规范：Conventional Commits +``` + +**为什么这很重要：** + +`CLAUDE.md` 是 Claude Code 的"项目记忆"。每次启动时，Claude 会自动读取这个文件，了解项目背景。这意味着： + +- 你不需要每次都解释项目用什么框架 +- Claude 会知道你的代码规范和最佳实践 +- 团队协作时，新成员也能快速了解项目 + +**建议**：新项目初始化后，立即运行 `/init`，然后根据实际情况调整生成的配置。 + +### 技巧 6：/compact 压缩上下文 —— 节省 Token + +Claude Code 的上下文窗口是有限的（通常 200K Token）。长对话会消耗大量 Token，不仅增加成本，还可能导致重要的早期信息被挤出上下文窗口。 + +**使用方式：** + +``` +/compact +``` + +**工作原理：** + +`/compact` 会分析当前对话历史，提取关键信息（如已做出的决策、已生成的代码、已确认的需求），然后生成一份简洁的摘要。之后的对话基于这份摘要，而不是完整的历史记录。 + +**什么时候使用：** + +- 对话进行了 5-6 轮后 +- 感觉 Claude 开始"遗忘"之前的内容 +- 要切换到新的子任务，但想保留关键背景 + +**使用建议：** + +``` +# 长对话后压缩 +/compact + +# 压缩后继续工作 +现在我们已经完成了用户模块，接下来做订单模块 +``` + +### 技巧 7：/commit 自动提交 —— Git 工作流自动化 + +`/commit` 让 Git 提交变得 effortless。Claude 会自动查看变更，生成符合规范的提交信息。 + +**使用方式：** + +```bash +/commit +``` + +**Claude 会做什么：** + +1. **查看变更**：运行 `git diff` 和 `git status` +2. **分析变更内容**：理解修改的目的和影响 +3. **生成提交信息**：按照 Conventional Commits 规范 +4. **执行提交**：运行 `git commit` + +**示例输出：** + +``` +检测到以下变更： +- src/components/UserCard.tsx - 新增用户卡片组件 +- src/types/user.ts - 添加 User 类型定义 +- tests/UserCard.test.tsx - 添加单元测试 + +建议的提交信息： +feat(components): add UserCard component with type definitions and tests + +是否执行提交？(y/n/e - 编辑信息) +``` + +**进阶用法：** + +```bash +# 自动提交，不询问 +/commit --yes + +# 生成提交信息但不执行 +/commit --dry-run +``` + +### 技巧 8：Shift+Tab 自动接受 —— 提高流畅度 + +默认情况下，Claude 修改代码前会询问你的确认。这在学习阶段很有帮助，但熟悉后可能会觉得繁琐。`Shift+Tab` 开启自动接受模式，让工作流更流畅。 + +**使用方式：** + +- 按 `Shift+Tab` → 进入自动接受模式 +- 再按 `Shift+Tab` → 退出自动接受模式 + +**模式对比：** + +| 模式 | 行为 | 适用场景 | +|------|------|----------| +| 默认模式 | 每次修改都询问确认 | 学习阶段、重要代码 | +| 自动接受 | 直接应用修改 | 熟悉后、快速迭代 | + +**⚠️ 注意事项：** + +- 自动接受模式下，Claude 会直接修改文件，没有二次确认 +- 建议配合 Git 使用，这样即使出问题也能回滚 +- 对于敏感操作（如删除文件、修改配置），Claude 仍会询问 + +### 技巧 9：Ctrl+C 取消操作 —— 紧急制动 + +当 Claude 正在执行一个长时间运行的任务，或者你意识到给错了指令时，`Ctrl+C` 是你的"紧急制动"按钮。 + +**使用方式：** + +- 按一次 `Ctrl+C` → 取消当前正在执行的操作 +- 按两次 `Ctrl+C` → 完全退出 Claude Code + +**使用场景：** + +- Claude 正在运行一个耗时的命令，你想中断 +- Claude 开始生成大量不相关的代码 +- 你意识到给错了指令，想立即停止 + +**与双击 Esc 的区别：** + +- `Ctrl+C`：停止正在进行的**操作**（如运行命令、生成代码） +- `双击 Esc`：回退**对话状态**（撤销上一轮对话） + +### 技巧 10：/context 查看上下文使用 —— 优化 Token 消耗 + +`/context` 显示当前会话的上下文使用情况，帮助你了解 Token 消耗，优化使用成本。 + +**使用方式：** + +``` +/context +``` + +**输出示例：** + +``` +📊 上下文使用情况 + +Token 使用：45,230 / 200,000 (22.6%) +文件引用：12 个文件 +对话轮数：8 轮 + +最消耗 Token 的文件： +1. src/api/users.ts (3,420 tokens) +2. node_modules/@types/react/index.d.ts (2,890 tokens) +3. src/components/Dashboard.tsx (1,560 tokens) + +建议： +- 当前使用率健康，无需压缩 +- 如需减少消耗，可在 .claudeignore 中添加 node_modules +``` + +**如何利用这个信息：** + +1. **识别大文件**：如果某个文件消耗了大量 Token，考虑是否真的需要它 +2. **优化 .claudeignore**：将不相关的文件（如 node_modules、构建产物）加入忽略列表 +3. **决定何时压缩**：当使用率超过 70% 时，考虑使用 `/compact` + +--- + +## 核心配置 + +合理的配置能让 Claude Code 更好地适应你的项目和团队。本节介绍配置文件的作用、优先级以及如何针对不同的使用场景进行优化。 + +### 配置文件位置与优先级 + +Claude Code 采用分层配置策略，不同级别的配置有不同的作用范围和优先级。理解这个机制，能让你更灵活地管理配置。 + +**配置优先级（从高到低）：** + +| 位置 | 作用域 | 用途 | 是否提交 Git | +|------|--------|------|--------------| +| `.claude/settings.local.json` | 项目本地 | 个人偏好设置 | ❌ 否 | +| `.claude/settings.json` | 项目共享 | 团队统一配置 | ✅ 是 | +| `~/.claude/settings.json` | 全局 | 个人默认配置 | ❌ 否 | + +**配置合并规则：** + +- 高优先级的配置会覆盖低优先级的相同配置项 +- 不冲突的配置项会合并生效 +- 项目级配置优先于全局配置，个人本地配置优先于共享配置 + +**实际应用场景：** + +**场景 1：团队项目** +``` +~/.claude/settings.json # 你的个人默认编辑器设置 +.claude/settings.json # 团队统一的代码规范、权限配置 +.claude/settings.local.json # 你自己的调试偏好、主题设置 +``` + +**场景 2：个人项目** +``` +~/.claude/settings.json # 全局默认配置 +.claude/settings.json # 项目特定配置（如特殊的权限规则） +``` + +### CLAUDE.md - 项目记忆 + +`CLAUDE.md` 是 Claude Code 最重要的配置文件，它相当于项目的"说明书"。每次启动 Claude Code 时，它会自动读取当前目录下的 `CLAUDE.md`，了解项目背景、技术栈和规范。 + +**为什么 CLAUDE.md 如此重要？** + +想象这样一个场景：你加入一个新项目，需要了解技术栈、代码规范、常用命令。通常你要花几个小时阅读文档、看代码、问同事。而有了 `CLAUDE.md`，Claude Code 在启动时就知道了所有这些信息，你可以立即开始高效协作。 + +**最小可用模板：** + +```markdown +# [项目名称] + +## 技术栈 +- 框架：React 18 + TypeScript +- 状态管理：Zustand +- 样式方案：Tailwind CSS +- 构建工具：Vite + +## 常用命令 +```bash +npm run dev # 启动开发服务器（端口 5173） +npm run test # 运行单元测试 +npm run build # 生产构建 +npm run lint # 代码检查 +``` + +## 代码规范 +- 组件使用函数组件 + Hooks +- 文件命名：PascalCase（组件）、camelCase（工具函数） +- Git 提交使用 Conventional Commits 规范 +- 所有 API 调用必须经过统一的 request 封装 +``` + +**完整模板（推荐）：** + +```markdown +# [项目名称] + +## 项目概述 +一句话描述项目的主要功能和目标用户。 + +## 技术栈 +### 前端 +- 框架：React 18 + TypeScript +- 路由：React Router v6 +- 状态：Zustand + React Query +- 样式：Tailwind CSS + Headless UI +- 构建：Vite + +### 后端（如适用） +- 运行时：Node.js + Express +- 数据库：PostgreSQL + Prisma +- 认证：JWT + bcrypt + +## 项目结构 +``` +src/ +├── components/ # 可复用组件 +├── pages/ # 页面组件 +├── hooks/ # 自定义 Hooks +├── lib/ # 工具函数 +├── types/ # TypeScript 类型 +└── api/ # API 调用 +``` + +## 常用命令 +```bash +# 开发 +npm run dev # 启动开发服务器 +npm run dev:mock # 使用 Mock 数据开发 + +# 测试 +npm run test # 运行所有测试 +npm run test:watch # 监听模式运行测试 +npm run test:coverage # 生成测试覆盖率报告 + +# 代码质量 +npm run lint # ESLint 检查 +npm run lint:fix # 自动修复 ESLint 问题 +npm run format # Prettier 格式化 +npm run typecheck # TypeScript 类型检查 + +# 构建 +npm run build # 生产构建 +npm run preview # 预览生产构建 +``` + +## 开发规范 +### 代码风格 +- 使用函数组件，避免类组件 +- 优先使用自定义 Hooks 封装逻辑 +- 组件 Props 必须定义 TypeScript 接口 + +### Git 工作流 +- 分支命名：`feature/`、`fix/`、`refactor/` 前缀 +- 提交信息遵循 Conventional Commits +- PR 必须通过 CI 检查和 Code Review + +### 性能要求 +- 组件懒加载，减少首屏时间 +- 图片使用 WebP 格式，开启懒加载 +- API 响应时间控制在 200ms 以内 + +## 环境变量 +```bash +# .env.local +VITE_API_BASE_URL=http://localhost:3000 +VITE_APP_NAME=MyApp +``` + +## 常见问题 +### 开发服务器启动失败？ +检查端口 5173 是否被占用，或尝试 `npm run dev -- --port 3000` + +### 类型错误？ +运行 `npm run typecheck` 查看详细错误信息 +``` + +**快速生成 CLAUDE.md：** + +如果你已经有一个项目，但还没有 `CLAUDE.md`，运行 `/init` 命令让 Claude 自动生成： + +```bash +claude +# 在 Claude Code 中输入 +/init +``` + +Claude 会分析你的项目结构、package.json、现有代码，生成一份符合实际情况的 `CLAUDE.md`。生成后建议人工检查并根据需要调整。 + +### .claudeignore - 节省 Token + +`.claudeignore` 文件告诉 Claude Code 哪些文件不应该被读取到上下文中。合理配置可以显著减少 Token 消耗（通常能减少 40-60%），同时提高响应速度。 + +**为什么需要 .claudeignore？** + +Claude Code 在理解项目时，会尝试读取相关文件。但有些文件对理解项目没有帮助，反而会： +- 消耗大量 Token（如 node_modules 中的类型定义文件） +- 引入噪音（如日志文件、构建产物） +- 包含敏感信息（如 .env 文件） + +**推荐配置：** + +``` +# ===== 依赖目录 ===== +# 这些目录包含大量第三方代码，不需要 Claude 读取 +node_modules/ +.pnp/ +.pnp.js + +# ===== 构建产物 ===== +# 生成的文件，不包含源代码信息 +dist/ +build/ +.next/ +out/ +*.tsbuildinfo + +# ===== 日志文件 ===== +# 运行时生成的日志，对理解项目无帮助 +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* +lerna-debug.log* + +# ===== 测试相关 ===== +# 测试覆盖率报告、coverage 数据 +coverage/ +.nyc_output/ + +# ===== 编辑器/IDE ===== +# 编辑器配置和临时文件 +.vscode/* +!.vscode/extensions.json +.idea/ +*.suo +*.ntvs* +*.njsproj +*.sln +*.sw? + +# ===== 系统文件 ===== +# macOS、Windows 系统文件 +.DS_Store +Thumbs.db + +# ===== 环境变量 ===== +# 包含敏感信息，不应被读取 +.env +.env.local +.env.*.local + +# ===== 大型资源文件 ===== +# 图片、视频等二进制文件 +*.png +*.jpg +*.jpeg +*.gif +*.svg +*.ico +*.mp4 +*.webm + +# ===== 锁文件（可选） ===== +# 如果你不需要 Claude 分析依赖版本，可以忽略 +# package-lock.json +# yarn.lock +# pnpm-lock.yaml +``` + +**配置技巧：** + +1. **从最小配置开始**：先忽略 node_modules 和构建产物，观察 Token 消耗 +2. **根据项目调整**：如果是图片密集型项目，添加图片格式忽略；如果是文档项目，保留 Markdown 文件 +3. **定期优化**：使用 `/context` 查看哪些文件消耗了最多 Token，考虑是否加入忽略列表 + +### 权限配置 + +Claude Code 默认会在执行敏感操作前询问确认。通过 `settings.json` 中的 `permissions` 配置，你可以精细控制哪些操作可以自动执行，哪些需要确认，哪些完全禁止。 + +**权限配置结构：** + +```json +{ + "permissions": { + "allow": [ + // 自动允许，不询问 + ], + "ask": [ + // 执行前询问确认 + ], + "deny": [ + // 完全禁止 + ] + } +} +``` + +**配置语法：** + +权限规则使用 `操作类型(匹配模式)` 的格式： + +| 操作类型 | 说明 | 示例 | +|----------|------|------| +| `Bash` | 执行终端命令 | `Bash(git status)` | +| `Edit` | 编辑文件 | `Edit(src/**/*.ts)` | +| `Read` | 读取文件 | `Read(README.md)` | +| `Write` | 创建新文件 | `Write(src/components/*.tsx)` | + +**匹配模式支持通配符：** + +- `*` 匹配任意字符（不包括 `/`） +- `**` 匹配任意路径 +- `?` 匹配单个字符 + +**实际配置示例：** + +```json +{ + "permissions": { + "allow": [ + "Bash(git status)", + "Bash(git log:*)", + "Bash(git diff:*)", + "Bash(npm test:*)", + "Bash(npm run lint:*)", + "Edit(src/**/*.{ts,tsx})", + "Edit(tests/**/*.test.ts)", + "Read(src/**/*.ts)", + "Write(src/components/*.tsx)" + ], + "ask": [ + "Bash(git commit:*)", + "Bash(git push:*)", + "Bash(git pull:*)", + "Bash(npm install:*)", + "Bash(npm run build)", + "Edit(package.json)", + "Edit(tsconfig.json)", + "Read(.env)", + "Read(config/secrets.*)" + ], + "deny": [ + "Bash(rm -rf:*)", + "Bash(sudo:*)", + "Bash(curl * | sh)", + "Bash(wget * | sh)", + "Edit(.git/*)", + "Write(/etc/*)", + "Read(/etc/passwd)" + ] + } +} +``` + +**配置建议：** + +1. **开发阶段**：设置较宽松的权限，提高迭代速度 +2. **生产环境**：收紧权限，特别是涉及部署、敏感数据的操作 +3. **团队协作**：将基础权限放在 `settings.json`（共享），个人调整放在 `settings.local.json` + +### Rules 规则目录 + +对于大型项目，单个 `CLAUDE.md` 可能变得臃肿且难以维护。Claude Code 支持使用 **Rules 规则目录** 进行模块化管理，将不同方面的规范拆分成独立的文件。 + +**目录结构：** + +``` +.claude/ +├── settings.json # 主配置文件 +├── CLAUDE.md # 项目概述（仍需要） +└── rules/ # 规则目录 + ├── 00-security.md # 安全规则（全局） + ├── 01-coding-style.md # 编码风格（全局） + ├── 10-api.md # API 开发规范 + ├── 11-frontend.md # 前端开发规范 + ├── 12-backend.md # 后端开发规范 + └── 20-testing.md # 测试规范 +``` + +**文件命名建议：** + +使用数字前缀控制加载顺序（如 `00-`、`01-`），确保基础规则先加载，特定规则后加载。 + +**规则文件格式：** + +规则文件支持 YAML frontmatter，用于控制规则的适用范围： + +```markdown +--- +# 可选：指定规则适用的文件路径 +globs: + - "src/api/**/*.ts" + - "src/services/**/*.ts" + +# 可选：指定规则适用的命令 +commands: + - "generate api" + - "create endpoint" + +# 可选：规则优先级（数字越小优先级越高） +priority: 10 +--- + +# API 开发规范 + +## 路由设计 +- RESTful 风格，使用名词复数 +- 版本控制：/api/v1/users +- 嵌套资源：/api/v1/users/123/orders + +## 请求/响应格式 +- 统一使用 JSON +- 错误响应必须包含 code 和 message +- 分页响应使用 { data, pagination } 结构 + +## 安全要求 +- 所有端点必须验证认证（除公开端点） +- 敏感操作需要二次确认 +- 实现速率限制防止滥用 +``` + +**规则继承与覆盖：** + +- 全局规则（无 frontmatter 或 `globs: *`）适用于所有文件 +- 特定路径规则只适用于匹配的文件 +- 当多个规则冲突时，优先级高的规则生效 +- 特定规则可以覆盖全局规则 + +**使用场景示例：** + +**场景 1：前后端分离项目** +``` +.claude/rules/ +├── 00-general.md # 通用规范（提交信息、命名约定） +├── 10-backend.md # 后端规范（NestJS 特定） +├── 11-frontend.md # 前端规范（React 特定） +└── 20-database.md # 数据库规范（Prisma 特定） +``` + +**场景 2：微服务架构** +``` +.claude/rules/ +├── 00-global/ # 全局规则 +│ ├── security.md +│ └── logging.md +├── 10-services/ # 服务特定规则 +│ ├── user-service.md +│ ├── order-service.md +│ └── payment-service.md +└── 20-shared/ # 共享组件规则 + ├── shared-lib.md + └── common-utils.md +``` + +**迁移建议：** + +如果你已经有一个庞大的 `CLAUDE.md`，可以按以下步骤迁移到 Rules 目录： + +1. 创建 `.claude/rules/` 目录 +2. 将 `CLAUDE.md` 中的内容按主题拆分 +3. 为每个规则文件添加适当的 frontmatter +4. 保留 `CLAUDE.md` 作为项目概述，移除详细规范 +5. 测试确保规则正确加载 + +--- + +## 核心操作指令 + +Claude Code 提供了一套丰富的操作指令，让你能够高效地与 AI 协作。这些指令分为几类：Slash 命令（内置功能）、符号系统（快捷操作）、以及自然语言指令（日常开发）。 + +### Slash 命令速查 + +Slash 命令是 Claude Code 的内置功能，以 `/` 开头。它们提供标准化的操作，如初始化项目、管理配置、查看状态等。 + +| 命令 | 功能 | 使用场景 | +|------|------|----------| +| `/help` | 显示所有命令 | 忘记命令时快速查看 | +| `/init` | 初始化项目，生成 CLAUDE.md | 新项目或添加配置 | +| `/plan` | 进入规划模式 | 复杂任务前先制定计划 | +| `/clear` | 清除对话历史 | 上下文混乱时重新开始 | +| `/compact` | 压缩上下文 | 长对话后节省 Token | +| `/commit` | 创建 Git 提交 | 快速提交变更 | +| `/review` | 审查未提交的变更 | 提交前检查代码 | +| `/context` | 查看上下文使用 | 优化 Token 消耗 | +| `/cost` | 查看本次会话费用 | 关注使用成本 | +| `/config` | 打开配置面板 | 修改设置 | +| `/permissions` | 权限管理 | 调整操作权限 | +| `/model` | 切换 AI 模型 | 选择不同模型 | + +**命令组合示例：** + +```bash +# 完整开发工作流 +/plan # 1. 制定计划 +# ... 执行开发 ... +/review # 2. 审查变更 +/commit # 3. 提交代码 +/cost # 4. 查看成本 +``` + +### 符号系统 + +符号系统是 Claude Code 的快捷操作方式，通过特殊符号快速触发特定功能。 + +| 符号 | 名称 | 用途 | 示例 | +|------|------|------|------| +| `/` | Slash 命令 | 执行内置操作 | `/help`, `/plan` | +| `@` | At 引用 | 引用文件/目录 | `@src/app.tsx` | +| `!` | Bang 模式 | 执行终端命令 | `!npm test` | +| `&` | 后台运行 | 后台执行任务 | `&npm run dev` | + +**符号组合技巧：** + +```bash +# 组合使用多个符号 +@src/utils.ts !npm test +# 解释：读取 utils.ts，然后运行测试 + +@src/components/ @src/pages/ 比较这两个目录的结构 +# 解释：同时引用两个目录进行对比 + +!git diff @src/app.tsx 解释这些变更 +# 解释：查看 Git 差异，然后让 Claude 解释特定文件的变更 +``` + +### 文件操作 + +文件操作是日常开发中最常用的功能。Claude Code 支持读取、编辑、创建、删除等各种文件操作。 + +**读取文件：** + +```bash +# 基本读取 +@src/app.tsx 解释这个文件 + +# 读取并分析 +@src/utils/helpers.ts 找出潜在的性能问题 + +# 对比读取 +@src/components/OldButton.tsx @src/components/NewButton.tsx 对比这两个组件的差异 +``` + +**编辑文件：** + +```bash +# 简单编辑 +将 src/utils/date.ts 的 formatDate 函数改为支持中文格式 + +# 复杂编辑 +@src/api/users.ts 重构这个文件： +1. 将重复的错误处理逻辑抽取到统一的 handleError 函数 +2. 使用 async/await 替代 Promise 链 +3. 添加 JSDoc 注释 + +# 批量编辑 +将 src/components/ 下所有类组件转换为函数组件 +``` + +**创建文件：** + +```bash +# 创建单个文件 +创建 src/components/UserCard.tsx，实现一个展示用户信息的卡片组件 + +# 创建多个相关文件 +创建用户模块： +1. src/types/user.ts - 定义 User 接口 +2. src/api/users.ts - 用户相关 API 调用 +3. src/components/UserCard.tsx - 用户卡片组件 +4. src/hooks/useUser.ts - 获取用户数据的 Hook +``` + +**删除文件：** + +```bash +# 删除前确认 +删除 src/old-component.tsx（这个组件已经不再使用） + +# Claude 会询问确认，并可能建议你检查是否有其他文件引用它 +``` + +### Git 操作 + +Claude Code 深度集成了 Git，让你可以在不离开终端的情况下完成完整的版本控制工作流。 + +**查看状态：** + +```bash +# 查看 Git 状态 +显示 Git 状态和未提交的变更 + +# 查看详细变更 +!git diff +解释 src/api/users.ts 的变更内容 +``` + +**创建提交：** + +```bash +# 自动提交 +/commit + +# 提交前审查 +/review +/commit +``` + +**分支操作：** + +```bash +# 创建功能分支 +!git checkout -b feature/user-authentication + +# 完成开发后 +/commit +!git push -u origin feature/user-authentication +``` + +**完整 Git 工作流示例：** + +```bash +# 1. 开始新功能 +!git checkout -b feature/payment-integration + +# 2. 开发功能（Claude 协助编码） +创建支付模块，包含支付宝和微信支付 + +# 3. 运行测试 +!npm test + +# 4. 审查变更 +/review + +# 5. 提交代码 +/commit + +# 6. 推送到远程 +!git push -u origin feature/payment-integration + +# 7. 创建 PR（可选，配合 GitHub CLI） +!gh pr create --title "feat: add payment integration" --body "支持支付宝和微信支付" +``` + +### 代码操作 + +代码操作是 Claude Code 的核心能力，包括生成、解释、重构、优化等。 + +**生成代码：** + +```bash +# 生成组件 +创建一个 React Hook 管理用户认证状态，包含登录、登出、权限检查功能 + +# 生成工具函数 +创建一个日期格式化工具函数，支持相对时间（如"2小时前"） + +# 生成完整模块 +创建订单模块，包含： +- 订单列表页面 +- 订单详情页面 +- 创建订单 API +- 订单状态管理 +``` + +**解释代码：** + +```bash +# 逐行解释 +逐行解释 src/algorithms/quicksort.ts + +# 高层次解释 +@src/services/payment.ts 解释这个模块的架构设计 + +# 解释复杂逻辑 +解释 src/utils/dataTransformer.ts 中的 reduce 操作在做什么 +``` + +**重构代码：** + +```bash +# 架构重构 +将 src/components/ 的类组件转换为函数组件 + +# 性能重构 +优化 src/App.tsx 的渲染性能，减少不必要的重渲染 + +# 代码清理 +@src/utils/helpers.ts 重构这个文件： +1. 删除未使用的函数 +2. 将重复逻辑抽取为通用函数 +3. 添加类型定义 +4. 优化函数命名 +``` + +**调试代码：** + +```bash +# 分析错误 +运行 npm test 失败了，分析错误原因并修复 + +# 性能分析 +@src/components/DataTable.tsx 这个组件渲染很慢，找出性能瓶颈 + +# 日志分析 +!cat logs/error.log +分析这些错误日志，找出根本原因 +``` + +### 测试操作 + +测试是保证代码质量的重要手段。Claude Code 可以协助你生成测试、运行测试、分析测试结果。 + +**生成测试：** + +```bash +# 生成单元测试 +为 src/utils/math.ts 生成单元测试，覆盖所有边界情况 + +# 生成组件测试 +为 src/components/UserForm.tsx 生成 React Testing Library 测试 + +# 生成集成测试 +创建用户注册流程的集成测试，覆盖从表单提交到数据库写入的完整流程 +``` + +**运行和调试测试：** + +```bash +# 运行测试 +!npm test + +# 调试失败测试 +分析测试失败原因并修复 +@tests/auth.test.ts + +# 查看测试覆盖率 +!npm run test:coverage +哪些代码没有被测试覆盖？ +``` + +**测试策略建议：** + +```bash +# 为新功能添加测试 +我添加了用户认证功能，请： +1. 为 auth.service.ts 生成单元测试 +2. 为 LoginForm 组件生成组件测试 +3. 运行所有测试确保通过 +``` + +### 指令组合与链式操作 + +高效的 Claude Code 使用方式是将多个指令组合起来，形成完整的工作流。 + +**场景 1：Bug 修复工作流** + +```bash +# 1. 查看问题 +!npm test +测试报错了，分析一下 + +# 2. 定位问题 +@src/utils/validation.ts 问题出在这个文件吗？ + +# 3. 修复问题 +修复 validation.ts 中的 isEmail 函数，使其正确处理包含 + 的邮箱地址 + +# 4. 验证修复 +!npm test + +# 5. 提交修复 +/commit +``` + +**场景 2：代码审查工作流** + +```bash +# 1. 查看变更 +!git diff --stat +有哪些文件被修改了？ + +# 2. 详细审查 +@src/components/ 审查这些组件的变更 + +# 3. 提出改进建议 +基于审查结果，有哪些可以改进的地方？ + +# 4. 实施改进 +优化 UserList 组件的性能 + +# 5. 最终审查 +/review +``` + +**场景 3：新功能开发工作流** + +```bash +# 1. 制定计划 +/plan +我要添加购物车功能 + +# 2. 创建分支 +!git checkout -b feature/shopping-cart + +# 3. 开发功能 +按照计划逐步实现 + +# 4. 添加测试 +为购物车模块生成测试 + +# 5. 运行测试 +!npm test + +# 6. 代码审查 +/review + +# 7. 提交代码 +/commit +!git push +``` + +--- + +## 常见问题 + +在使用 Claude Code 的过程中，你可能会遇到各种问题。本节整理了最常见的问题及其解决方案。 + +### Token 消耗太快？ + +Token 消耗过快是使用 Claude Code 时最常见的问题。以下是优化 Token 使用的完整策略。 + +**问题诊断：** + +首先，使用 `/context` 命令查看当前的 Token 使用情况： +``` +/context +``` + +关注以下指标： +- **Token 使用率**：如果超过 70%，需要考虑压缩上下文 +- **文件引用数量**：引用的文件越多，Token 消耗越大 +- **大文件**：查看哪些文件占用了最多 Token + +**优化策略：** + +**1. 完善 .claudeignore 配置** + +确保你的 `.claudeignore` 文件包含了所有不需要的文件： +``` +# 必须忽略的 +node_modules/ +dist/ +build/ +*.log +.env + +# 根据项目类型添加 +# React 项目 +.next/ +out/ + +# Vue 项目 +.nuxt/ +.output/ + +# 通用 +.vscode/ +.idea/ +coverage/ +*.min.js +*.bundle.js +``` + +**2. 定期压缩上下文** + +长对话会累积大量 Token。建议每 5-6 轮对话后使用 `/compact`： +``` +# 长对话后 +/compact + +# 继续工作 +现在我们来实现订单模块... +``` + +**3. 精准引用文件** + +不要引用整个目录，而是引用具体需要的文件： +```bash +# 不推荐（会读取整个目录） +@src/ 解释这些代码 + +# 推荐（只读取需要的文件） +@src/utils/auth.ts @src/components/Login.tsx 解释登录流程 +``` + +**4. 避免读取大文件** + +如果 `/context` 显示某个文件占用了大量 Token，考虑： +- 是否真的需要这个文件？ +- 能否只引用其中的部分代码？ +- 能否将大文件拆分成小模块？ + +### Claude 不理解项目？ + +当 Claude 的回答不够准确，或者频繁询问项目的基本信息时，说明它缺乏足够的项目背景知识。 + +**解决方案：** + +**1. 生成 CLAUDE.md** + +运行 `/init` 让 Claude 自动生成项目配置文件： +```bash +/init +``` + +生成后，检查并完善以下内容： +- 项目概述是否准确？ +- 技术栈是否完整？ +- 常用命令是否正确？ +- 代码规范是否明确？ + +**2. 手动编辑 CLAUDE.md** + +如果自动生成的配置不够详细，手动添加： +```markdown +## 项目特定信息 + +### 架构决策 +- 为什么选择 X 而不是 Y？ +- 核心设计模式是什么？ + +### 常见陷阱 +- 使用 useEffect 时要注意... +- 数据库查询必须... + +### 第三方集成 +- 支付使用 Stripe +- 邮件使用 SendGrid +- 文件存储使用 AWS S3 +``` + +**3. 使用 Rules 目录** + +大型项目可以使用 Rules 目录组织规范： +``` +.claude/rules/ +├── 00-architecture.md # 架构概述 +├── 01-coding-style.md # 代码风格 +├── 10-frontend.md # 前端规范 +├── 11-backend.md # 后端规范 +└── 20-testing.md # 测试规范 +``` + +**4. 即时补充上下文** + +对于特定任务，可以在指令中补充背景： +``` +我们使用自定义的 useAuth Hook 处理认证， +它返回 { user, login, logout, isLoading }。 +请基于这个 Hook 实现用户菜单组件。 +``` + +### 如何回退操作？ + +Claude Code 提供了多种回退机制，适用于不同的场景。 + +**场景 1：回退对话状态** + +如果只是说错了话，或者对 Claude 的回答不满意： +``` +双击 Esc → 回退到上一轮对话 +三击 Esc → 清除所有对话历史 +``` + +**⚠️ 注意**：这只会回退对话状态，不会撤销文件修改。 + +**场景 2：撤销文件修改** + +如果 Claude 已经修改了文件，你需要手动撤销： + +```bash +# 查看变更 +!git status +!git diff + +# 撤销特定文件 +git checkout -- src/utils/helpers.ts + +# 撤销所有变更 +git checkout -- . + +# 如果已经提交了 +# 软回退（保留变更） +git reset --soft HEAD~1 + +# 硬回退（丢弃变更） +git reset --hard HEAD~1 +``` + +**场景 3：使用 Git 工作流预防** + +最佳实践是在使用 Claude Code 前提交当前工作： +```bash +# 开始前保存当前状态 +git add . +git commit -m "WIP: before Claude Code session" +# 或使用 git stash +git stash push -m "before claude" + +# 使用 Claude Code 进行开发... + +# 如果结果不满意，完全回退 +git reset --hard HEAD~1 +# 或 +git stash pop +``` + +### 权限提示太多？ + +频繁的权限确认会影响开发效率。通过合理配置权限，可以让工作流更流畅。 + +**理解权限系统：** + +Claude Code 的权限分为三级： +- **allow**：自动允许，不询问 +- **ask**：执行前询问确认 +- **deny**：完全禁止 + +**优化配置：** + +编辑 `.claude/settings.json`： + +```json +{ + "permissions": { + "allow": [ + // Git 只读操作 + "Bash(git status)", + "Bash(git log:*)", + "Bash(git diff:*)", + "Bash(git branch)", + + // 测试和检查 + "Bash(npm test:*)", + "Bash(npm run lint:*)", + "Bash(npm run typecheck)", + + // 开发服务器 + "Bash(npm run dev:*)", + + // 源代码编辑 + "Edit(src/**/*.{ts,tsx})", + "Edit(tests/**/*.test.ts)", + "Write(src/**/*.ts)" + ], + "ask": [ + // Git 写操作 + "Bash(git commit:*)", + "Bash(git push:*)", + "Bash(git pull:*)", + + // 包管理 + "Bash(npm install:*)", + "Bash(npm uninstall:*)", + + // 构建和部署 + "Bash(npm run build)", + "Bash(npm run deploy:*)", + + // 配置文件修改 + "Edit(package.json)", + "Edit(tsconfig.json)", + + // 敏感文件读取 + "Read(.env)", + "Read(config/secrets.*)" + ], + "deny": [ + // 危险命令 + "Bash(rm -rf:*)", + "Bash(sudo:*)", + "Bash(curl * | sh)", + "Bash(wget * | sh)", + + // 系统文件 + "Edit(/etc/*)", + "Write(/usr/*)", + + // Git 目录 + "Edit(.git/*)" + ] + } +} +``` + +**渐进式权限策略：** + +- **学习阶段**：保持默认设置，了解 Claude 会执行哪些操作 +- **熟悉阶段**：将常用的安全操作（如 git status、npm test）加入 allow +- **高效阶段**：根据项目特点，配置更精细的权限规则 + +### 国内如何使用？ + +由于网络原因，中国用户可能无法直接访问 Anthropic 的官方服务。以下是几种解决方案。 + +**方案 1：使用 API 代理服务** + +许多云服务商提供兼容 Anthropic API 的代理服务： + +```bash +# 设置环境变量 +export ANTHROPIC_BASE_URL="https://your-api-proxy.com/v1" +export ANTHROPIC_API_KEY="your-api-key" + +# 启动 Claude Code +claude +``` + +**方案 2：使用第三方 Claude Code 兼容工具** + +一些国内服务商提供兼容 Claude Code 的工具： + +```bash +# 安装兼容版本 +npm install -g @some-provider/claude-code + +# 配置 API 密钥 +claude config set api.key your-api-key +claude config set api.baseUrl https://api.some-provider.com +``` + +**方案 3：使用其他 AI 编程工具** + +如果 Claude Code 无法使用，可以考虑以下替代方案： + +| 工具 | 特点 | 适用场景 | +|------|------|----------| +| Cursor | 基于 VS Code，功能完善 | 需要完整 IDE 体验 | +| GitHub Copilot | 代码补全能力强 | 主要需要代码补全 | +| 通义灵码 | 国产，国内访问稳定 | 国内开发环境 | +| Codeium | 免费额度多 | 预算有限 | + +**方案 4：让 AI Agent 帮你配置** + +如果你不确定如何配置，可以让 AI Agent 协助： + +``` +我要使用 Claude Code，但国内无法直接访问。 +我购买了 XXX 服务商的 API， +API 地址是 https://api.xxx.com， +密钥是 sk-xxx。 + +请帮我配置好环境变量，确保 Claude Code 能正常使用。 +``` + +**常见问题：** + +- **Q: 配置后仍然无法连接？** + - A: 检查 API 地址是否正确，确认是否包含 `/v1` 路径 + - A: 检查 API 密钥是否有效，是否已充值 + - A: 检查本地网络是否需要代理 + +- **Q: 响应速度很慢？** + - A: 选择地理位置更近的服务商 + - A: 使用 Coding Plan 而非通用 API + - A: 考虑使用 `/compact` 减少 Token 消耗 + +- **Q: 某些功能无法使用？** + - A: 部分第三方服务可能不完全兼容所有 Claude Code 功能 + - A: 检查服务商的文档，了解支持的功能范围 + +--- + +## 参考资源 + +- [Claude Code 官方文档](https://code.claude.com/docs) +- [Claude Code GitHub](https://github.com/anthropics/claude-code) +- [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) diff --git a/docs/zh-cn/stage-3/core-skills/3.3-long-running-tasks/index.md b/docs/zh-cn/stage-3/core-skills/long-running-tasks/index.md similarity index 71% rename from docs/zh-cn/stage-3/core-skills/3.3-long-running-tasks/index.md rename to docs/zh-cn/stage-3/core-skills/long-running-tasks/index.md index b0a3494..7809642 100644 --- a/docs/zh-cn/stage-3/core-skills/3.3-long-running-tasks/index.md +++ b/docs/zh-cn/stage-3/core-skills/long-running-tasks/index.md @@ -1,4 +1,4 @@ -# 高级二：如何让 Claude Code 长时间工作 +# 如何让 Claude Code 长时间工作 ## 引言 @@ -6,6 +6,10 @@ 想象一下这些场景：你想让 Claude 帮你重构整个项目，但它写完几个文件就说"我完成了"；你想让 Claude 持续修复 bug 直到测试全部通过，但它跑一次就停下来；你想让 Claude "过夜干活"，但第二天发现它早就停了。 +2025 年夏天，一位名叫 Geoffrey Huntley 的澳大利亚开发者（他也是个牧羊人）写了一个只有 5 行的 bash 脚本。这个脚本很简单，就是不断重启 Claude Code 并喂给它同样的任务。他把它命名为 "Ralph Wiggum"——取自《辛普森一家》中那个不断尝试、从不放弃的角色。 + +这个简单的脚本震惊了整个硅谷。在短短两周内，相关项目在 GitHub 上获得了 7,000+ 星标。人们用它一晚上生成了 6 个完整项目，用 $297 的 API 成本完成了 $50,000 的合同工作。甚至有人用它在 3 个月内构建了一门完整的编程语言。 + 本章要解决的核心问题是：如何让 Claude Code 像真正的开发者一样，持续工作直到任务真正完成。 --- @@ -117,12 +121,40 @@ Ralph 的核心机制是 Stop Hook。当 Claude 想要退出时，Stop Hook 会 ### 安装 -安装很简单，只需要在 Claude Code 中运行： +Ralph Wiggum 是 Claude Code 的官方插件，有两种安装方式。 + +**方式一：通过官方插件市场安装（推荐）** ```bash -claude /plugins:add ralph-wiggum +# 在 Claude Code 中运行 +claude + +# 添加官方插件市场 +/plugin marketplace add anthropics/claude-code + +# 安装 Ralph Wiggum +/plugin install ralph-wiggum@claude-code-plugins + +# 验证安装 +/plugin ``` +**方式二：直接从 GitHub 安装** + +```bash +# 进入插件目录 +cd ~/.claude/plugins/ + +# 克隆插件仓库 +git clone https://github.com/anthropics/ralph-wiggum-plugin.git +``` + +安装完成后，你可以使用以下命令： + +- `/ralph-wiggum:ralph-loop` - 启动循环 +- `/ralph-wiggum:cancel-ralph` - 取消循环 +- `/ralph-wiggum:help` - 查看帮助 + ### 基本使用 基本使用方式是通过 `/ralph-loop` 命令： @@ -158,6 +190,115 @@ claude /plugins:add ralph-wiggum 这样 Claude 就知道确切要做什么，什么时候才算真正完成。 +### 更多 Prompt 模板示例 + +这里有一些常见任务的 Prompt 模板，你可以直接使用或根据需要修改。 + +**模板 1：测试迁移（Jest → Vitest）** + +``` +/ralph-loop " +将项目中所有测试从 Jest 迁移到 Vitest： +- 保持所有测试逻辑不变 +- 更新配置文件（vite.config.js、vitest.config.js） +- 替换 Jest 特有的 API（如 jest.mock → vi.mock） +- 确保所有测试通过 +- 移除 Jest 相关依赖 + +验收标准： +- npm test 全部通过 +- package.json 中无 jest 依赖 +- 项目能正常构建 + +完成后输出：VITEST_MIGRATION_COMPLETE +" --max-iterations 40 --completion-promise "VITEST_MIGRATION_COMPLETE" +``` + +**模板 2：UI/UX 优化（移动端优先）** + +``` +/ralph-loop " +把这个项目的 UI/UX 做得更像一款精致的、移动端优先的语言学习 App： +- 统一间距与留白（使用 4px 基础单位） +- 建立清晰的字体层级（标题/正文/辅助信息） +- 统一卡片、列表等组件样式 +- 添加底部导航（Home/Learn/Quiz/Progress/Settings） +- 确保在移动设备上显示良好 + +验收标准： +- npm run build 成功 +- 无 TypeScript 错误 +- 主要页面在移动端预览正常 + +完成后输出：UI_UX_COMPLETE +" --max-iterations 25 --completion-promise "UI_UX_COMPLETE" +``` + +**模板 3：批量添加 TypeScript 类型** + +``` +/ralph-loop " +给项目中所有函数添加 TypeScript 类型注解： +- 优先处理 src/ 目录 +- 为函数参数和返回值添加类型 +- 避免使用 any，使用具体类型或 unknown +- 添加必要的类型定义 + +验收标准： +- npm run typecheck 通过 +- 无 @ts-ignore 或 @ts-any 注释 +- 代码能正常运行 + +完成后输出：TYPES_ADDED +" --max-iterations 30 --completion-promise "TYPES_ADDED" +``` + +**模板 4：TDD 驱动功能开发** + +``` +/ralph-loop " +使用 TDD 方式实现用户结账功能： +1. 先写测试（checkout.test.ts） +2. 运行测试（会失败） +3. 编写最小代码使测试通过 +4. 重构优化 +5. 重复直到所有测试通过 + +功能要求： +- 购物车商品列表 +- 运费计算 +- 优惠券应用 +- 支付表单验证 + +验收标准： +- 所有测试通过（npm test checkout.test.ts） +- 代码覆盖率 > 80% +- ESLint 无错误 + +完成后输出：CHECKOUT_COMPLETE +" --max-iterations 25 --completion-promise "CHECKOUT_COMPLETE" +``` + +**模板 5：代码风格统一** + +``` +/ralph-loop " +统一项目代码风格： +- 使用 Prettier 格式化所有文件 +- 统一命名规范（变量 camelCase，组件 PascalCase） +- 移除未使用的导入和变量 +- 统一字符串引号（单引号） +- 统一分号使用（不使用） + +验收标准： +- npm run lint 通过 +- 代码风格一致 +- 构建成功 + +完成后输出：STYLE_UNIFIED +" --max-iterations 20 --completion-promise "STYLE_UNIFIED" +``` + ### 实战案例 有一个著名的案例是在 Y Combinator 黑客松上，一个团队使用 Ralph Loop。晚上 11 点他们设置任务：根据 specs 目录下的 6 个产品需求，依次实现每个项目的 MVP，每完成一个输出特定的完成标记。设置最大迭代次数 200 次，然后就去睡觉了。 @@ -166,6 +307,26 @@ claude /plugins:add ralph-wiggum 另一个案例来自 Boris Cherny（Claude Code 负责人）。他使用 Ralph 加上 Opus 4.5 模型，在 30 天内提交了 259 个 PR，包含 497 次提交，新增 40,000 行代码、删除 38,000 行代码。最惊人的是，这 100% 都是由 Claude Code 完成的，没有人工编写一行代码。 +还有一个更疯狂的案例：CURSED 编程语言。这是 Ralph 的创作者 Geoffrey Huntley 用 Ralph Loop 在 3 个月内自主构建的一门完整编程语言。这门语言的特点是使用 Gen Z 俚语作为关键字（比如 `slay`、`sus`、`based`），但更重要的是它包含了一个完整的 LLVM 编译器实现、标准库和部分编辑器支持。这个项目展示了 Ralph Loop 的真正潜力——你给它一个清晰的目标，它就能持续工作几个月，直到把复杂的项目真正完成。 + +### 更多真实案例 + +**一夜完成 $50,000 合同项目** + +有一个开发团队接到了一个价值 $50,000 的外包合同。他们在晚上设置好 Ralph Loop，详细描述了项目需求，设置了最大迭代次数，然后就去睡觉了。 + +第二天早上醒来，项目已经完成了——包括所有功能、测试、文档。而 API 调用成本只有 $297。这个案例展示了 Ralph 的经济价值：你花费的是 API 费用，节省的是几周的人工时间。 + +**自动重构项目** + +另一个开发者用 Ralph 重构一个遗留项目。项目代码混乱，没有测试，文档缺失。他给 Ralph 的任务是： + +1. 为现有代码添加测试 +2. 逐步重构，每次重构后确保测试通过 +3. 更新文档 + +设置好后让 Ralph 运行了一整个周末。周一回来，发现项目已经发生了 47 次提交，代码结构清晰，测试覆盖率达到 75%，并且有完整的 API 文档。成本约 $12。 + ### Ralph 的哲学 Ralph 体现了三个核心哲学思想。 @@ -176,6 +337,47 @@ Ralph 体现了三个核心哲学思想。 第三是持续尝试。Keep trying until it works——这就是 Ralph 的精神。 +### 什么时候适合/不适合使用 Ralph + +了解 Ralph 的适用场景很重要，这能帮你节省时间和成本。 + +**✅ 适合使用 Ralph 的场景** + +这些任务有明确的完成标准，适合 Ralph 自动迭代： + +| 场景 | 原因 | +|------|------| +| 测试迁移 | 有明确目标（新框架），测试通过即可验证 | +| 大规模重构 | 可以定义具体的重构规则 | +| 框架迁移 | 迁移完成后代码能正常运行 | +| 批量添加类型 | typecheck 通过即完成 | +| 测试覆盖率提升 | 覆盖率百分比是客观指标 | +| 文档生成 | API 文档可以自动验证 | +| UI/UX 统一改进 | 可以定义具体的设计规范 | +| Bug 修复（有复现步骤） | 测试通过即修复成功 | + +**❌ 不适合使用 Ralph 的场景** + +这些任务需要人类判断或探索，不适合 Ralph： + +| 场景 | 原因 | +|------|------| +| 架构设计决策 | 微服务 vs 单体需要权衡 | +| 安全相关代码 | 安全漏洞可能很隐蔽 | +| 需求模糊的任务 | 没有明确完成标准 | +| 探索性工作 | 需要不断调整方向 | +| 创意性设计 | 需要人类审美判断 | +| 简单一次性任务 | 使用 Ralph 是浪费 | + +**💡 判断标准** + +问自己三个问题： +1. **我能定义明确的完成标准吗？** 如果不能，不适合 +2. **有客观的验证方法吗？**（测试、构建、类型检查）如果没有，不适合 +3. **这个任务需要我持续反馈吗？** 如果是，不适合 + +如果三个答案都是"否"，那就放手让 Ralph 去做吧！ + --- ## 方法三：增强版 Ralph @@ -549,29 +751,32 @@ Ralph Wiggum 是通用推荐，适合大部分场景。它有完整的 Stop Hook ### 社区项目 -- [frankbria/ralph-claude-code](https://github.com/frankbria/ralph-claude-code) - 增强版 Ralph 实现，包含额外的安全机制 -- [win4r/claude-code-hooks](https://github.com/win4r/claude-code-hooks) - Hook 示例和工具集合 +- [frankbria/ralph-claude-code](https://github.com/frankbria/ralph-claude-code) (2.1k⭐) - 增强版 Ralph 实现，包含额外的安全机制 +- [Awesome Ralph](https://github.com/snwfdhmp/awesome-ralph) - Ralph 资源和示例精选列表 +- [Ralph Ryan](https://github.com/wquguru/ralph-ryan) - 结合 PRD 生成和 Ralph 循环的实现 - [snarktank/ralph](https://github.com/snarktank/ralph) - 原始 Ralph 实现 -- [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) - 生产级配置模板 -- [claude-flow](https://github.com/ruvnet/claude-flow) - 企业级编排平台 ### 文章与教程 +**英文资源** + - [Geoffrey Huntley - Ralph Technique](https://ghuntley.com/ralph/) - Ralph 技术的原创者 -- [O'Reilly - Conductors to Orchestrators](https://www.oreilly.com/radar/conductors-to-orchestrators-the-future-of-agentic-coding/) - AI 编程从指挥到编排的演进 - [构建可靠长时运行AI代理的有效框架实践](https://m.blog.csdn.net/weixin_48708052/article/details/158044721) - Anthropic 工程博客精读 -- [Claude Code 最佳实践（作者亲授）](https://juejin.cn/post/7366666666666666666) - 官方最佳实践分享 - [Claude Code 全攻略](https://developer.aliyun.com/article/1705912) - 完整的使用指南 -- [Reverse Engineering Analysis](https://m.blog.csdn.net/qq_33778762/article/details/149490953) - Claude Code 的逆向工程分析 + +**中文教程** + +- [保姆级教程 - CSDN](https://m.blog.csdn.net/zsr154278963/article/details/156637281) - 详细的安装指南和使用教程 +- [深度解析 - 头条](https://m.toutiao.com/a7585579989207188006/) - 工作机制和核心原理 +- [全栈式白话指南](https://www.jdon.com/90167-ralph-wigum-loop-explained-for-teens.html) - 从原理到实战完整讲解 +- [入门和实战教程 - 博客园](https://www.cnblogs.com/buwai/p/19625356) - 基础知识与实践案例 +- [Ralph Loop 深度解析 - CSDN](https://m.blog.csdn.net/roamingcode/article/details/156732443) - Stop Hook 机制详解 +- [Claude Code 永动机 - CSDN](https://m.blog.csdn.net/qq_44866828/article/details/156736656) - 无限循环迭代插件详解 +- [Ralph Loop 新手入门 - CNblogs](https://www.cnblogs.com/gyc567/p/19495639) - 最佳实践和提示词汇总 ### 实战案例 -- [16 Agents Build C Compiler](https://arxiv.org/abs/2408.01342) - Nicholas Carlini 的实验论文 +- [CURSED 编程语言](https://github.com/geoffreyhuntley/cursed) - 用 Ralph 在 3 个月内构建的完整编程语言 - [Boris Cherny's 30 Days](https://twitter.com/boriskirov/status/1756002385683786616) - 259 PRs 案例分享 - [Y Combinator Hackathon](https://github.com/geoffreyhuntley/ralph) - 6 个项目过夜生成的案例 - -### 工具文档 - -- [Tmux 官方文档](https://github.com/tmux/tmux/wiki) - Tmux 的完整文档 -- [GitHub Actions 文档](https://docs.github.com/en/actions) - GitHub Actions 的官方文档 -- [Agent SDK](https://docs.anthropic.com/en/docs/agents) - 构建自定义代理的 SDK +- [Geoffrey Huntley's Blog](https://ghuntley.com/) - Ralph 创始人的技术博客 diff --git a/docs/zh-cn/stage-3/core-skills/mcp/index.md b/docs/zh-cn/stage-3/core-skills/mcp/index.md new file mode 100644 index 0000000..82671ac --- /dev/null +++ b/docs/zh-cn/stage-3/core-skills/mcp/index.md @@ -0,0 +1,568 @@ +# Claude Code MCP 完全指南 + +## 什么是 Claude Code MCP？ + +**Claude Code** 是 Anthropic 官方推出的 AI 命令行工具，而 **MCP（Model Context Protocol）** 则是让 Claude Code 能够连接外部工具和服务的协议。 + +简单来说，MCP 让 Claude Code 从一个「只能读写本地文件」的 AI 助手，变成一个「能访问 GitHub、数据库、API、云服务」的超级助手！ + +## 为什么需要在 Claude Code 中使用 MCP？ + +### 没有 MCP 的 Claude Code + +``` +你能做的： +✓ 读取本地文件 +✓ 编辑代码 +✓ 运行命令 +✓ 使用 Bash 工具 + +你不能做的： +✗ 查看你的 GitHub Issues +✗ 访问云数据库 +✗ 调用外部 API +✗ 获取实时天气 +``` + +### 有了 MCP 的 Claude Code + +``` +你能做的： +✓ 所有原来的功能 +✓ 查看/创建 GitHub Issues 和 PR +✓ 查询 SQLite、PostgreSQL 数据库 +✓ 访问 Notion、Slack 等外部服务 +✓ 获取实时天气、地图数据 +✓ 浏览器自动化 +✓ ...以及更多！ +``` + +## 快速开始 + +### 步骤 1：了解配置文件位置 + +Claude Code 的 MCP 配置文件位于： + +| 级别 | 配置文件路径 | 作用范围 | +|-----|-------------|----------| +| **用户级** | `~/.claude.json` | 所有项目 | +| **项目级** | `.claude/mcp.json` | 当前项目 | + +推荐优先使用**项目级配置**，让不同项目使用不同的 MCP 服务。 + +### 步骤 2：用自然语言添加 MCP 服务器 + +在 Claude Code 中，你不需要手动编辑配置文件或记忆命令，直接用自然语言描述即可： + +``` +你：帮我添加 GitHub MCP 服务器，我的 token 是 ghp_xxx + +Claude：我来帮你配置 GitHub MCP 服务器... + +[自动更新 .claude/mcp.json] +``` + +``` +你：添加一个 SQLite 数据库服务器，数据库文件在 ./data/app.db + +Claude：好的，我来配置 SQLite MCP 服务器... +``` + +``` +你：添加一个 HTTP 类型的 MCP 服务器，地址是 https://api.example.com/mcp + +Claude：我来添加这个远程 MCP 服务器... +``` + +### 步骤 3：验证配置 + +直接询问 Claude Code： + +``` +你：现在有哪些可用的 MCP 服务器？ + +Claude：当前已配置的 MCP 服务器： +• github - GitHub 集成 +• sqlite - SQLite 数据库 +• filesystem - 文件系统访问 +``` + +或使用诊断命令： + +``` +/doctor +``` + +### 步骤 4：开始使用 + +配置成功后，直接用自然语言调用 MCP 功能： + +``` +你：帮我在 GitHub 上创建一个 Issue + +Claude：我可以帮你创建 GitHub Issue。请告诉我： +- 仓库地址（如 owner/repo） +- Issue 标题 +- Issue 描述 +``` + +## Claude Code 的自然语言管理 + +### 查看和管理 MCP 服务器 + +你可以完全用自然语言与 Claude Code 交互： + +``` +你：列出所有已配置的 MCP 服务器 + +你：检查一下 MCP 服务器的连接状态 + +你：删除 notion 这个 MCP 服务器 + +你：更新 github 服务器的 token +``` + +### 诊断问题 + +当遇到问题时： + +``` +你：检查一下 MCP 连接有什么问题 + +Claude：[会自动运行诊断，分析配置文件，检查服务器状态] +``` + +## 配置方式详解 + +### 用户级配置（全局） + +编辑 `~/.claude.json`： + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"] + }, + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token" + } + } + } +} +``` + +### 项目级配置（推荐） + +编辑项目根目录的 `.claude/mcp.json`： + +```json +{ + "mcpServers": { + "project-db": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data/app.db"] + } + } +} +``` + +**项目级配置优势：** +- 团队成员可以共享配置（提交到 Git） +- 不同项目使用不同的 MCP 服务 +- 配置更灵活，不会污染全局设置 + +### 传输方式配置 + +Claude Code 支持三种传输方式： + +#### STDIO（本地进程） + +```json +{ + "mcpServers": { + "local-tool": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] + } + } +} +``` + +#### HTTP（远程服务） + +```json +{ + "mcpServers": { + "remote-api": { + "url": "https://api.example.com/mcp", + "transport": "http", + "headers": { + "Authorization": "Bearer your-token" + } + } + } +} +``` + +#### SSE（服务器推送） + +```json +{ + "mcpServers": { + "streaming": { + "url": "https://api.example.com/sse", + "transport": "sse" + } + } +} +``` + +## 实战示例 + +### 示例 1：GitHub 工作流自动化 + +``` +你：帮我把当前的修改推送到 GitHub，然后创建一个 PR，标题是"添加新功能" + +Claude： +1. 检查当前 git 状态... +2. 创建新分支 feature/new-feature... +3. 提交更改... +4. 推送到远程... +5. 调用 github_create_pull_request 创建 PR... +6. PR 已创建：https://github.com/owner/repo/pull/123 +``` + +### 示例 2：数据库查询 + +``` +你：查询数据库中最近注册的 10 个用户 + +Claude： +1. 连接到 SQLite 数据库... +2. 执行查询：SELECT * FROM users ORDER BY created_at DESC LIMIT 10 +3. 返回结果： + - 张三 (zhang@example.com) - 2025-02-28 + - 李四 (li@example.com) - 2025-02-27 + ... +``` + +### 示例 3：网页截图分析 + +``` +你：打开 https://example.com 并截图，分析一下页面设计 + +Claude： +1. 启动浏览器... +2. 导航到 https://example.com... +3. 截取屏幕... +4. [返回截图] +5. 页面设计分析： + - 布局采用居中设计，最大宽度 1200px + - 主色调为蓝色 (#3b82f6) + - 导航栏固定在顶部 + ... +``` + +### 示例 4：与 Notion 集成 + +``` +你：把我刚才的笔记保存到 Notion + +Claude： +1. 使用 Notion MCP 服务器... +2. 创建新页面... +3. 已保存：https://notion.so/page/xxx +``` + +## 调试技巧 + +### 使用自然语言诊断 + +遇到问题时，直接告诉 Claude Code： + +``` +你：我的 MCP 服务器连接不上了，帮我检查一下 + +你：GitHub MCP 工具调用失败，是什么原因？ + +你：为什么 sqlite 服务器一直显示连接中？ +``` + +Claude Code 会自动： +1. 检查配置文件格式 +2. 验证环境变量 +3. 测试服务器连接 +4. 提供具体的修复建议 + +### 常见问题排查 + +| 问题 | 可能原因 | 解决方案 | +|-----|---------|----------| +| 服务器未连接 | 配置文件格式错误 | 检查 JSON 语法 | +| 工具无法调用 | 权限不足 | 检查环境变量 | +| 连接超时 | 网络问题 | 检查 URL 或网络 | +| 进程崩溃 | 服务器代码错误 | 查看服务器日志 | + +### 手动诊断命令 + +``` +/doctor +``` + +输出示例： +``` +系统诊断报告： +=============== + +Claude Code: v2.5.0 ✓ +Node.js: v20.0.0 ✓ + +MCP 服务器状态： +• github: ✓ 已连接 (12 tools) +• sqlite: ✗ 连接失败 - Database file not found +• puppeteer: ✓ 已连接 (8 tools) + +建议： +1. 检查 sqlite 数据库路径是否正确 +2. 确保 .claude/mcp.json 格式正确 +``` + +## 最佳实践 + +### 1. 项目级配置优先 + +**为什么推荐项目级配置？** + +不同的项目往往需要不同的 MCP 服务。例如，前端项目可能需要浏览器测试工具，而后端项目则需要数据库连接。使用项目级配置可以让每个项目拥有自己专属的 MCP 服务器集合，避免全局配置的混乱。 + +更重要的是，项目级配置可以提交到 Git 仓库，团队成员克隆项目后就能直接使用相同的 MCP 服务，无需重复配置。 + +``` +项目 A（前端项目）→ .claude/mcp.json 包含浏览器测试 MCP +项目 B（后端项目）→ .claude/mcp.json 包含数据库 MCP +``` + +### 2. 敏感信息环境变量化 + +**永远不要在配置文件中硬编码密钥！** + +配置文件可能会被意外提交到 Git 仓库，导致密钥泄露。正确的做法是将敏感信息存储在环境变量中，配置文件只引用变量名。这样即使配置文件被公开，也不会暴露实际的密钥。 + +```json +{ + "env": { + "GITHUB_TOKEN": "$GITHUB_TOKEN", // ✓ 好 - 从环境变量读取 + "GITHUB_TOKEN": "ghp_abc123" // ✗ 不好 - 硬编码密钥 + } +} +``` + +### 3. 版本锁定 + +**为什么需要锁定版本？** + +默认情况下，`npx -y` 会总是使用最新版本的 MCP 服务器。这可能导致问题：新版本可能引入不兼容的更改，或者某个服务器突然被下架/改名。 + +通过在包名后添加 `@版本号`，可以确保始终使用经过验证的特定版本，避免因自动更新导致的意外问题。 + +```json +{ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github@1.2.3"] // 固定版本 +} +``` + +### 4. 文档化你的 MCP 配置 + +**让团队成员快速理解 MCP 配置** + +当项目中有多个 MCP 服务器时，新成员可能不清楚每个服务器的用途和配置要求。在 `.claude/` 目录下创建一个 `README.md` 文件，说明每个服务器的用途、所需的配置项以及获取方式，可以大大降低团队的沟通成本。 + +在项目中创建 `.claude/README.md`： + +在项目中创建 `.claude/README.md`： + +```markdown +# MCP 配置说明 + +本项目使用的 MCP 服务器： + +## github +用于自动化 GitHub 操作，需要配置 GITHUB_TOKEN。 + +## sqlite +连接到 ./data/app.db，用于查询和修改数据。 + +## puppeteer +用于 E2E 测试。 +``` + +## Claude Code vs Claude Desktop + +| 特性 | Claude Code | Claude Desktop | +|-----|-------------|----------------| +| **配置文件** | `~/.claude.json` 或 `.claude/mcp.json` | `claude_desktop_config.json` | +| **项目级配置** | ✓ 支持 | ✗ 不支持 | +| **自然语言管理** | ✓ 支持 | ✗ 需手动编辑 | +| **诊断工具** | ✓ `/doctor` | ✗ 无 | +| **热重载** | ✓ 自动重载 | ✗ 需重启应用 | +| **适用场景** | 开发工作流、CI/CD | 日常使用、办公 | + +## 常用 MCP 服务器 + +> 💡 完整的 MCP 服务器列表请参考附录 [MCP 服务器大全](/zh-cn/appendix/mcp-servers/) + +### GitHub 服务器 + +**功能：** Issues、PR、仓库管理 + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token" + } + } + } +} +``` + +**获取 Token：** https://github.com/settings/tokens + +### SQLite 服务器 + +**功能：** 查询和管理 SQLite 数据库 + +```json +{ + "mcpServers": { + "sqlite": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data/database.db"] + } + } +} +``` + +### 文件系统服务器 + +**功能：** 访问指定目录的文件 + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"] + } + } +} +``` + +### Puppeteer 浏览器自动化 + +**功能：** 浏览器控制、截图、自动化测试 + +```json +{ + "mcpServers": { + "puppeteer": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-puppeteer"] + } + } +} +``` + +### Brave 搜索服务器 + +**功能：** 网络搜索 + +```json +{ + "mcpServers": { + "brave-search": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-brave-search"], + "env": { + "BRAVE_API_KEY": "your-brave-api-key" + } + } + } +} +``` + +## 参考资源 + +### 官方文档 + +- [Claude Code 官方文档 - MCP](https://docs.anthropic.com/zh-CN/docs/claude-code/mcp) +- [MCP 官方网站](https://modelcontextprotocol.io/) +- [MCP 规范文档](https://modelcontextprotocol.io/specification/) +- [MCP GitHub 仓库](https://github.com/modelcontextprotocol) + +### 官方服务器 + +- [@modelcontextprotocol/server-github](https://github.com/modelcontextprotocol/servers/tree/main/src/github) - GitHub 集成 +- [@modelcontextprotocol/server-sqlite](https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite) - SQLite 数据库 +- [@modelcontextprotocol/server-postgres](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) - PostgreSQL 数据库 +- [@modelcontextprotocol/server-filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) - 文件系统访问 +- [@modelcontextprotocol/server-puppeteer](https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer) - 浏览器自动化 +- [@modelcontextprotocol/server-fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) - 网页抓取 +- [@modelcontextprotocol/server-brave-search](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search) - Brave 搜索 +- [@modelcontextprotocol/server-git](https://github.com/modelcontextprotocol/servers/tree/main/src/git) - Git 操作 + +### 教程文章 + +- [一文讲透 MCP 的原理及实践](https://view.inews.qq.com/a/20250414A023WV00) +- [MCP（Model Context Protocol）架构与工作原理](https://m.toutiao.com/w/1826385835060307/) +- [2025 大模型最新教程：MCP 协议从入门到精通](https://m.blog.csdn.net/weixin_45653328/article/details/150916706) +- [从零开始学 MCP（八）- 构建一个 MCP server](https://juejin.cn/post/7582510291667419187) + +### 配置指南 + +- [Claude Code 最佳实践](https://www.anthropic.com/engineering/claude-code-best-practices) +- [Claude Code 完全配置指南](https://juejin.cn/post/7576838552472043563) + +### 开发教程 + +- [零基础构建 MCP 服务器 TypeScript/Python 双语言实战指南](https://m.blog.csdn.net/ztt123654/article/details/150844207) +- [终极 MCP 服务器构建指南：TypeScript 与 Python 双版本完整教程](https://m.blog.csdn.net/gitblog_00703/article/details/154862128) +- [使用 TypeScript 构建一个最简单的 MCP 服务器](https://m.blog.csdn.net/weixin_45653525/article/details/148433757) +- [使用 Azure 容器应用生成 TypeScript MCP 服务器](https://learn.microsoft.com/zh-cn/azure/developer/ai/build-mcp-server-ts) + +### MCP 服务器资源 + +- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) - 最全面的 MCP 服务器列表 +- [Official MCP Registry](https://registry.modelcontextprotocol.io) - Anthropic 官方「应用商店」 +- [MCP.so](https://mcp.so) - 社区 MCP 服务器中心 +- [Glama.ai MCP](https://glama.ai/mcp/servers) - 带评分评论的 MCP 目录 +- [Smithery](https://smithery.ai) - MCP 服务器市场 +- [MCPHub](https://mcphub.io/registry) - 界面简洁的目录 +- [LobeHub MCP](https://lobehub.com/zh/mcp) - 中文 MCP 目录 + +### 地图和天气服务 + +- [高德地图 MCP Server](https://lobehub.com/zh/mcp/luozengchang-mcp-amap) +- [腾讯位置服务 MCP 文档](https://lbs.qq.com/service/MCPServer/MCPServerGuide/overview) +- [彩云天气 MCP Server](https://github.com/caiyunapp/mcp-caiyun-weather) +- [OpenWeatherMap MCP Server](https://github.com/CodeByWaqas/weather-mcp-server) + +### 社区资源 + +- [Everything Claude Code Config](https://github.com/affaan-m/everything-claude-code) - 生产级 Claude Code 配置集合 +- [AI Coding Guide](https://github.com/hacket/AICodingGuide) - Claude Code 中文学习路径 + +### 实际应用案例 + +- [BlenderMCP - AI 驱动的 3D 建模](https://github.com/Belthur/blender-mcp) - 4,100+ ⭐ +- [MCP 生产环境 15 条最佳实践](https://learn.microsoft.com/zh-cn/azure/azure-functions/scenario-mcp-apps) diff --git a/docs/zh-cn/stage-3/core-skills/3.2-skills/index.md b/docs/zh-cn/stage-3/core-skills/skills/index.md similarity index 85% rename from docs/zh-cn/stage-3/core-skills/3.2-skills/index.md rename to docs/zh-cn/stage-3/core-skills/skills/index.md index 8e9e139..f74e933 100644 --- a/docs/zh-cn/stage-3/core-skills/3.2-skills/index.md +++ b/docs/zh-cn/stage-3/core-skills/skills/index.md @@ -307,6 +307,140 @@ Claude 会根据这个技能的规范，帮你设计出： --- +### 第三个 Skill：用 frontend-slides 快速制作精美 PPT + +#### 简介 + +**frontend-slides** 是一个让你用自然语言创建精美 HTML 演示文稿的 Skill —— 即使你不懂任何 CSS 或 JavaScript！ + +它的核心特点是"**展示而非讲述**"：当你描述不出想要的设计风格时，它会生成 3 个视觉预览让你选择，而不是让你用语言描述"蓝色背景、大字体"这种抽象需求。 + +#### 安装 frontend-slides + +**方式一：手动安装** + +```bash +# 创建 skill 目录 +mkdir -p ~/.claude/skills/frontend-slides + +# 下载文件（或从 GitHub 复制） +# 1. 访问 https://github.com/zarazhangrui/frontend-slides +# 2. 下载 SKILL.md 和 STYLE_PRESETS.md +# 3. 放到 ~/.claude/skills/frontend-slides/ 目录 +``` + +**方式二：使用 find-skills 安装** + +``` +帮我找找做 PPT 演示文稿相关的技能 +``` + +Claude 会通过 find-skills 搜索并推荐 frontend-slides。 + +#### 使用场景 + +**场景 1：从零创建演示文稿** + +``` +/frontend-slides + +我想创建一个 AI 创业项目的融资路演 PPT，大概 10 页 +``` + +Claude 会引导你： +1. 询问每页内容（标题、要点、图片） +2. 询问你想要的感觉（惊艳？专业？温馨？） +3. 生成 3 个视觉风格预览供你选择 +4. 创建完整的 HTML 演示文稿 +5. 在浏览器中打开预览 + +**场景 2：转换 PowerPoint 文件** + +``` +/frontend-slides + +把我的 presentation.pptx 转成网页版演示 +``` + +Claude 会： +1. 提取 PPT 中的所有文本、图片和备注 +2. 显示提取的内容供你确认 +3. 让你选择视觉风格 +4. 生成保留所有原始内容的 HTML 演示文稿 + +**场景 3：快速生成风格预览** + +``` +/frontend-slides + +我想做一个技术分享的 PPT，先给我看看可选的视觉风格 +``` + +Claude 会直接生成 3 个不同风格的预览页面： +- **暗色主题**：Neon Cyber、Terminal Green、Deep Space +- **亮色主题**：Paper & Ink、Swiss Modern、Soft Pastel +- **特殊风格**：Brutalist、Gradient Wave + +#### 内置的视觉风格 + +| 风格名称 | 特点 | 适用场景 | +|---------|------|---------| +| **Neon Cyber** | 未来科技感、粒子效果 | 技术分享、AI 产品 | +| **Midnight Executive** | 高端商务、值得信赖 | 商务汇报、融资路演 | +| **Paper & Ink** | 编辑风格、文学气息 | 内容创作、教育分享 | +| **Swiss Modern** | 简洁几何、包豪斯风格 | 设计作品、极简主义 | +| **Brutalist** | 原始大胆、抓人眼球 | 艺术展示、个性表达 | + +#### 输出效果 + +生成的演示文稿是一个**单文件 HTML**，包含： + +- 完整的样式和交互代码 +- 键盘导航（方向键、空格） +- 触摸/滑动支持 +- 鼠标滚轮翻页 +- 进度条和导航点 +- 滚动触发动画 +- 响应式设计 + +```html + + + + + + +
+

你的标题

+
+ + + +``` + +#### 为什么推荐？ + +1. **零依赖**：单个 HTML 文件，10 年后还能打开 +2. **视觉发现**：不用描述设计，直接选择喜欢的 +3. **PPT 转换**：保留现有内容，换上更好的皮肤 +4. **生产级代码**：可访问性好、注释清晰、易于定制 + +**相关链接**： +- [frontend-slides GitHub 仓库](https://github.com/zarazhangrui/frontend-slides) - 6.1k+ Star +- [在线预览示例](https://github.com/zarazhangrui/frontend-slides#output-example) + +--- + +### 三个 Skills 的对比 + +| Skills | 解决什么问题 | 好玩程度 | 实用程度 | +|--------|-------------|---------|---------| +| **remotion-dev/skills** | 用代码做视频 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | +| **anthropics/skills/frontend-design** | 让前端变好看 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | +| **frontend-slides** | 快速制作精美 PPT | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | + +--- + ### 安装后如何使用 安装完成后，你不需要做任何额外配置。当你向 Claude 提出相关任务时，它会自动调用对应的 Skill。 @@ -967,6 +1101,10 @@ description: 审查 Pull Request 的代码。当用户提到 PR、review、代 - [Vibe Coding - CLAUDE.md、Skills、Subagents 全链路实战](https://blog.csdn.net/yangshangwei/article/details/158319117) - [手把手教你自定义 Claude Code Skills](https://m.blog.csdn.net/u010028049/article/details/157979705) +### 深入阅读 + +- [Claude Skills 内部核心机制](/easy-vibe/zh-cn/appendix/8-artificial-intelligence/skills-internal-mechanism) - 深入理解 Skills 的工作原理、三层加载架构、双上下文注入机制 + --- ## 总结 diff --git a/docs/zh-cn/stage-3/core-skills/3.5-superpowers/index.md b/docs/zh-cn/stage-3/core-skills/superpowers/index.md similarity index 99% rename from docs/zh-cn/stage-3/core-skills/3.5-superpowers/index.md rename to docs/zh-cn/stage-3/core-skills/superpowers/index.md index b05844b..fdcf454 100644 --- a/docs/zh-cn/stage-3/core-skills/3.5-superpowers/index.md +++ b/docs/zh-cn/stage-3/core-skills/superpowers/index.md @@ -1,4 +1,4 @@ -# 高级五：Claude Code Superpowers 工程级开发 +# Claude Code Superpowers 工程级开发 ## Superpowers 简介 diff --git a/docs/zh-cn/stage-3/core-skills/workflow/index.md b/docs/zh-cn/stage-3/core-skills/workflow/index.md new file mode 100644 index 0000000..9c8160a --- /dev/null +++ b/docs/zh-cn/stage-3/core-skills/workflow/index.md @@ -0,0 +1,684 @@ +# Claude Code 工作流最佳实践 + +## 前言 + +Claude Code 不仅仅是一个 AI 编程助手，更是一种全新的开发方式。它改变了开发者与代码、与工具、与团队的交互模式。掌握正确的工作流，可以让你的开发效率提升 10 倍，代码质量显著提高，同时减少重复性工作带来的疲惫感。 + +### 为什么需要专门的工作流？ + +传统的开发工作流是基于人类开发者设计的：阅读文档、理解代码、编写实现、手动测试、代码审查。而 AI 辅助开发需要一种全新的协作模式： + +- **上下文管理**：AI 有上下文窗口限制，需要策略性地传递信息 +- **任务分解**：复杂任务需要拆分成 AI 可以理解和执行的小步骤 +- **验证机制**：AI 生成的代码需要系统化的验证流程 +- **知识沉淀**：团队需要共享 AI 的配置和项目知识 + +### 本文涵盖的内容 + +本文将系统介绍 Claude Code 在不同场景下的最佳实践，包括： + +1. **日常开发工作流** - 新功能开发、Bug 修复的标准流程 +2. **代码重构工作流** - 安全、高效地进行大规模重构 +3. **Code Review 工作流** - 利用 AI 提升代码审查质量 +4. **团队协作配置** - 共享配置、统一规范、知识管理 +5. **CI/CD 集成** - 将 Claude Code 融入自动化流程 + +### 核心原则 + +使用 Claude Code 需要建立正确的工作方式。它能力强大，但并非万能，需要合理的分工和有效的协作。 + +**合理的分工** + +Claude 适合处理重复性工作，例如阅读代码、生成样板、查找 Bug、统一代码格式等。但架构设计、业务理解、关键决策等需要由人来把控。 + +**建立信任** + +初次使用时，建议从简单任务开始（如变量重命名、简单函数重构），观察 Claude 的理解能力和执行效果。随着对其能力边界的了解，再逐步增加任务复杂度。 + +**清晰的上下文传递** + +项目背景应通过 CLAUDE.md 文档提供，具体修改目标需使用 `@文件名` 明确指向，预期结果也要描述清楚。模糊的指令会导致偏离预期的输出。 + +**验证环节不可省略** + +Claude 生成的代码需要经过测试验证、类型检查和风格审查。最终的代码质量责任仍在于开发者，AI 是辅助工具而非替代品。 + +## 日常开发工作流 + +日常开发占据了程序员大部分的工作时间。建立标准化的日常开发工作流，可以让你更高效地完成新功能开发和 Bug 修复，同时保持代码质量。 + +### 新功能开发流程 + +新功能开发是最常见的开发任务。一个完整的 AI 辅助开发流程包含以下步骤： + +``` +1. 理解需求 → 2. 分析现有代码 → 3. 设计实现方案 +→ 4. 编写代码 → 5. 测试与调试 → 6. 代码审查 → 7. 提交代码 +``` + +#### 快速开始 + +**1. 了解项目结构** + +```text +@directory src/ +``` + +让 Claude 快速浏览项目目录结构，了解： + +- 代码组织方式（是否分层、模块如何划分） +- 使用的技术栈（框架、库类型） +- 现有的命名和文件组织规范 + +> **为什么？** 在不熟悉的项目中开发，盲目动手容易写出不符合项目风格的代码。让 Claude 先"看"一遍项目，生成的代码会更契合现有架构。 + +--- + +**2. 查找相关代码** + +```text +@grep "关键词" --glob "*.ts" +``` + +查找与当前任务相关的现有代码： + +- 是否已有类似功能可以复用 +- 其他人是如何处理类似场景的 +- 需要修改或关联哪些文件 + +> **为什么？** 避免"重复造轮子"，同时确保新代码与现有代码风格一致。 + +--- + +**3. 制定计划** + +```text +使用 /plan 或直接描述需求 +``` + +让 Claude 制定详细的实施计划： + +- 涉及哪些文件的修改 +- 实现的先后顺序 +- 可能遇到的技术难点 + +> **为什么？** 复杂任务拆分成小步骤后，执行更可控，出错也更容易定位。 + +--- + +**4. 生成代码** + +```text +让 Claude 根据计划生成代码框架 +``` + +按计划逐步生成代码，从基础框架开始： + +- 先生成类型定义和接口 +- 再生成核心逻辑 +- 最后处理边界情况和错误处理 + +> **为什么？** 框架先行可以确保结构合理，细节后填可以边写边验证。 + +--- + +**5. 运行测试** + +```text +!npm test +``` + +每次代码修改后立即运行测试： + +- 单元测试验证函数逻辑 +- 集成测试验证模块交互 +- 手动测试验证用户交互 + +> **为什么？** 及早发现问题，避免错误累积到最后难以定位。 + +--- + +**6. 代码审查** + +```text +使用 /review 或让 Claude 审查变更 +``` + +让 Claude 从多个维度审查代码： + +- 安全问题（SQL 注入、XSS 等） +- 性能问题（N+1 查询、内存泄漏等） +- 代码风格（是否符合项目规范） + +> **为什么？** AI 能发现人眼容易遗漏的问题，提高代码质量。 + +--- + +**7. 提交代码** + +```text +/commit +``` + +生成符合规范的提交信息： + +- 自动分析代码变更 +- 生成 conventional commit 格式的提交信息 +- 包含变更摘要和关键细节 + +> **为什么？** 清晰的提交信息让代码历史更易读，后续回溯问题更方便。 + +### Bug 修复流程 + +Bug 修复需要快速定位问题、理解根因、实施修复并验证。 + +**标准流程：** + +1. **收集错误信息** - 错误消息、复现步骤、环境信息 +2. **定位问题代码** - 搜索相关代码、分析调用链 +3. **分析根因** - 理解为什么会出错、评估影响范围 +4. **实施修复** - 编写修复代码、添加回归测试 +5. **提交修复** - 生成提交信息、记录 Bug 原因 + +**实用命令：** + +```bash +# 搜索错误信息 +@grep "错误消息" --glob "*.ts" + +# 查看函数调用链 +@grep "functionName" --context 5 + +# 运行相关测试 +!npm test -- 文件名.test.ts + +# 查看最近改动 +!git diff +``` + +### 日常开发 Checklist + +| 阶段 | 检查项 | 操作命令/方法 | +|-----|--------|--------------| +| **开始前** | 了解项目结构 | `@directory src/` | +| | 查看相关代码 | `@grep "keyword" --glob "*.ts"` | +| **编码中** | 制定实施计划 | `/plan` | +| | 生成代码框架 | 直接描述需求 | +| **测试阶段** | 运行单元测试 | `!npm test` | +| | 检查测试覆盖率 | `!npm run test:coverage` | +| **审查阶段** | 自动代码审查 | `/review` | +| | 类型检查 | `!npm run typecheck` | +| **提交阶段** | 生成提交信息 | `/commit` | + +### 常见陷阱 + +**陷阱 1：一次性给太多任务** + +``` +❌ "帮我实现一个完整的电商系统" +✅ "先实现用户注册功能" +``` + +**陷阱 2：不提供足够的上下文** + +``` +❌ "修复这个 bug" +✅ "登录功能报错'Invalid token'，错误在 src/middleware/auth.ts" +``` + +**陷阱 3：不验证 AI 生成的代码** + +``` +❌ 直接接受所有修改 +✅ 每次修改后运行测试，手动验证关键功能 +``` + +## 代码重构工作流 + +重构就是"在不改变功能的前提下，改善代码结构"。听起来简单，但实际操作中很容易出问题。 + +### 重构前：先看清楚再动手 + +动手之前，先搞清楚两件事：要改哪些文件？这些文件被谁引用？ + +```bash +# 找出需要重构的文件 +@grep "旧模式代码" --glob "*.ts" + +# 看看这些文件被哪些地方引用 +@grep "import.*ModuleName" --glob "*.ts" +``` + +### 创建安全网 + +重构就像走钢丝，需要安全网。 + +```bash +# 第一步：创建新分支，别在主分支上搞 +!git checkout -b refactor/描述你的重构 + +# 第二步：确认现有测试都能通过 +!npm test +``` + +如果测试本来就不过，先修测试再重构。否则你根本不知道重构是不是搞坏了东西。 + +### 自动验证配置 + +让 Claude 每次改代码后自动跑测试，省心又安全： + +::: details 点击查看配置 +```json +// .claude/settings.json +{ + "hooks": { + "afterEdit": ["npm run test:related"], + "beforeCommit": ["npm run test"] + } +} +``` +::: + +这样配置后，每次 Claude 修改代码都会自动运行测试，失败了会提醒你。 + +### 重构的核心原则 + +记住三句话： + +1. **小步走** - 别想着一次改完，改一点验证一点 +2. **有测试才动** - 没测试的代码先补测试，再重构 +3. **重构别改功能** - 只改结构，不改行为。想优化性能？另开一个 PR + +### 重构检查清单 + +每改完一批代码，跑一遍这些检查： + +| 检查项 | 命令 | 通过标准 | +|--------|------|----------| +| 类型检查 | `npm run type-check` | 无类型错误 | +| 相关测试 | `npm run test:related` | 相关测试通过 | +| 全部测试 | `npm test` | 所有测试通过 | +| 代码风格 | `npm run lint` | 无 lint 错误 | +| 构建测试 | `npm run build` | 构建成功 | + +只要有一项不过，别继续改，先修复。 + +## Code Review 工作流 + +代码审查就是让同事检查你的代码，帮你发现问题和改进点。但这事儿挺累人的——看代码费眼，还容易漏掉问题。 + +Claude 可以帮你做第一轮审查，把明显的问题先筛出来，人只要关注重要的东西就行。 + +### 审查要看什么？ + +按优先级排个序： + +| 优先级 | 检查项 | 说明 | +| :--- | :--- | :--- | +| 🔴 最高 | 安全问题 | SQL 注入、密码硬编码、权限漏洞 | +| 🟡 高 | 性能问题 | N+1 查询、内存泄漏 | +| 🟢 中 | 代码质量 | 命名不规范、重复代码 | +| ⚪ 低 | 风格问题 | 缺少空格、注释不完整 | + +### 提交 PR 前：先自己审一遍 + +```text +@file src/你改的文件.ts 审查这段代码，看看有没有安全问题 +``` + +让 Claude 帮你检查： + +- 有没有安全漏洞 +- 有没有性能问题 +- 逻辑有没有明显错误 + +### 写好 PR 描述 + +好的 PR 描述能让审查者快速理解你在做什么。 + +::: details 标准模板 + +```markdown +## 做了什么 +用一句话说清楚改了啥 + +## 为什么改 +说明改动的背景和原因 + +## 改了哪些地方 +- 改动点 1 +- 改动点 2 + +## 测试情况 +- [ ] 单元测试通过 +- [ ] 手动验证通过 + +## 注意事项 +如果会影响其他功能，在这里说明 +``` + +::: + +### 审查别人的 PR + +用 Claude 帮你快速了解 PR 的内容： + +```text +帮我审查这个 PR，重点检查安全问题和性能问题 +``` + +Claude 会列出发现的问题，你再重点看这些问题是否属实。 + +### 本地预提交检查 + +在提交前自动跑一遍快速检查： + +::: details 点击查看配置 + +```bash +#!/bin/bash +# .git/hooks/pre-commit + +echo "检查代码..." + +claude "快速检查暂存的代码： +1. 有没有明显的安全问题 +2. 有没有明显的 bug" --strict || exit 1 +``` + +::: + +配置后，每次提交都会自动检查，发现问题会阻止提交。 + +## 团队协作配置共享 + +在团队中使用 Claude Code，需要建立共享的配置和知识库，确保所有成员都能获得一致的 AI 辅助体验。 + +### 项目级配置 + +将 Claude Code 配置提交到仓库，实现团队共享： + +**配置结构：** + +```text +.claude/ +├── settings.json # 团队共享配置 +├── settings.local.json # 个人本地配置（不提交） +├── CLAUDE.md # 项目主文档 +├── .claudeignore # 忽略文件配置 +└── memory/ # 项目记忆 + ├── project-context.md + ├── conventions.md + ├── architecture.md + └── common-pitfalls.md +``` + +**团队共享配置示例：** + +::: details 点击查看 settings.json + +```json +{ + "hooks": { + "beforeEdit": ["npm run type-check"], + "afterEdit": ["npm run lint"], + "beforeCommit": ["npm run test"] + }, + "permissions": { + "allow": [ + "Bash(git status)", + "Bash(git log:*)", + "Bash(npm test:*)", + "Edit(src/**/*.{ts,tsx})" + ], + "ask": [ + "Bash(git commit:*)", + "Bash(git push:*)" + ] + } +} +``` + +::: + +### 项目记忆系统 + +**记忆系统结构：** + +- **project-context.md** - 项目整体上下文 +- **conventions.md** - 代码规范和约定 +- **architecture.md** - 架构设计说明 +- **common-pitfalls.md** - 常见陷阱和解决方案 + +### 团队协作最佳实践 + +| 实践 | 说明 | 实施方法 | +| :--- | :--- | :--- | +| **共享配置** | 将 .claude/ 加入版本控制 | `git add .claude/` | +| **文档规范** | 在 memory/ 中记录项目约定 | 每次架构决策更新文档 | +| **代码审查** | 用 Claude 辅助 Code Review | 提交前运行审查 | +| **统一 Hooks** | 团队使用相同的 pre-commit hooks | 配置在 settings.json | +| **知识同步** | 定期更新项目记忆 | 每迭代更新一次 | + +## CI/CD 集成 + +将 Claude Code 集成到 CI/CD 流程中，可以实现自动化的代码审查、测试生成、安全检查等。 + +### GitHub Actions 集成 + +#### 场景 1：PR 自动审查 + +::: details 点击查看配置 + +```yaml +# .github/workflows/claude-review.yml +name: Claude Code Review + +on: + pull_request: + types: [opened, synchronize] + +jobs: + claude-review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Run Claude Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(ts|tsx|js|jsx)$' || true) + + if [ -z "$CHANGED_FILES" ]; then + echo "No relevant files changed" + exit 0 + fi + + claude "审查以下文件的变更： + $CHANGED_FILES + + 检查维度： + 1. 安全漏洞 + 2. 性能问题 + 3. 代码质量 + + 输出格式： + - 🔴 严重问题（阻塞） + - 🟡 警告（建议修复） + - 🟢 建议（可选）" \ + --output pr-review.md + + - name: Comment PR + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = fs.readFileSync('pr-review.md', 'utf8'); + + const hasBlockingIssues = review.includes('🔴'); + + const header = hasBlockingIssues + ? '## ❌ Code Review 未通过\n\n' + : '## ✅ Code Review 通过\n\n'; + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: header + review + }); + + if (hasBlockingIssues) { + core.setFailed('发现严重问题'); + } +``` + +::: + +#### 场景 2：部署前安全检查 + +::: details 点击查看配置 + +```yaml +# .github/workflows/pre-deploy-security.yml +name: Pre-deploy Security Check + +on: + push: + branches: [main] + +jobs: + security-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Security Scan + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + claude "对代码进行全面的安全扫描： + + 检查以下安全问题： + 1. SQL 注入漏洞 + 2. XSS（跨站脚本攻击） + 3. CSRF（跨站请求伪造） + 4. 敏感信息泄露 + 5. 不安全的依赖项 + + 输出格式： + - 🔴 高危漏洞（立即修复） + - 🟡 中危漏洞（建议修复） + - 🟢 低危漏洞（可选修复）" \ + --output security-report.md + + - name: Check for critical issues + run: | + if grep -q "🔴" security-report.md; then + echo "发现高危安全漏洞！" + cat security-report.md + exit 1 + fi +``` + +::: + +### 本地 Pre-commit Hook + +::: details 点击查看配置 + +```bash +#!/bin/bash +# .git/hooks/pre-commit + +set -e + +echo "🔍 运行 Claude Code 预提交检查..." + +STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx)$' || true) + +if [ -z "$STAGED_FILES" ]; then + echo "✅ 没有需要检查的代码文件" + exit 0 +fi + +claude "对以下文件进行快速检查： +$STAGED_FILES + +检查项目： +1. 明显的语法错误 +2. 类型错误 +3. 明显的安全问题 +4. 代码风格问题 + +如果发现严重问题，返回非零退出码。" \ + --strict || { + echo "❌ 预提交检查失败" + exit 1 + } + +echo "✅ 预提交检查通过！" +``` + +::: + +### CI/CD 集成最佳实践 + +**分层检查策略：** + +```text +本地开发 → Pre-commit → PR 审查 → 合并前检查 → 部署前检查 + ↓ ↓ ↓ ↓ ↓ + 快速检查 基础检查 深度审查 全面检查 安全检查 + (1-2秒) (10-30秒) (1-2分钟) (3-5分钟) (5-10分钟) +``` + +**成本控制：** 只在必要时运行 Claude 检查，通过条件判断避免不必要的 API 调用。 + +## 工作流速查表 + +| 场景 | 命令/操作 | +| :--- | :--- | +| **开始新功能** | `@directory src/` 了解项目结构 | +| **查找代码** | `@grep "functionName"` | +| **理解代码** | 直接描述代码文件让 Claude 解释 | +| **重构代码** | 描述重构需求，让 Claude 制定计划 | +| **修复 Bug** | 提供错误信息和复现步骤 | +| **代码审查** | 让 Claude 审查指定文件或目录 | +| **生成测试** | "为 xxx 文件生成单元测试" | +| **提交代码** | `/commit` | + +## 总结 + +掌握这些工作流后，你会发现： + +1. **日常开发**：用 @语法快速理解代码，让 Claude 处理重复工作 +2. **代码重构**：让 Claude 制定计划，逐步验证 +3. **Code Review**：自动发现潜在问题，提高代码质量 +4. **团队协作**：共享配置和记忆，保持团队一致性 +5. **CI/CD**：将 Claude 集成到自动化流程中 + +**核心原则：** +- 让 Claude 做它擅长的事：理解代码、生成代码、发现问题 +- 你做决策：审查结果、做架构选择、把控方向 +- 逐步信任：从简单任务开始，建立对 Claude 的信任 +- 持续优化：根据项目特点调整工作流