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
new file mode 100644
index 0000000..2a6b1c0
--- /dev/null
+++ b/docs/zh-cn/stage-3/core-skills/3.1-claude-mcp/index.md
@@ -0,0 +1,1650 @@
+# 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 <name>` | 获取特定服务器详情 |
+| `claude mcp remove <name>` | 移除服务器 |
+
+#### 配置文件位置
+
+| 级别 | 配置文件位置 |
+|-----|-------------|
+| **用户级** | `~/.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.1-mcp-claude-code-skills/index.md b/docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/index.md
deleted file mode 100644
index 16395ed..0000000
--- a/docs/zh-cn/stage-3/core-skills/3.1-mcp-claude-code-skills/index.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# 高级一：MCP 与 Claude Code Skills
-
-> 本章节正在编写中，敬请期待...
diff --git a/docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/index.md b/docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/index.md
deleted file mode 100644
index e0073c8..0000000
--- a/docs/zh-cn/stage-3/core-skills/3.2-long-running-tasks/index.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# 高级二：如何让 Coding Tools 长时间工作
-
-> 本章节正在编写中，敬请期待...
diff --git a/docs/zh-cn/stage-3/core-skills/3.2-skills/index.md b/docs/zh-cn/stage-3/core-skills/3.2-skills/index.md
new file mode 100644
index 0000000..8e9e139
--- /dev/null
+++ b/docs/zh-cn/stage-3/core-skills/3.2-skills/index.md
@@ -0,0 +1,984 @@
+# Claude Code Skills 完全指南
+
+## Skills 简介
+
+**Claude Code Skills** 是一种将专业知识、工作流程和最佳实践打包成"可复用技能包"的功能。
+
+想象一下，Skills 就像是给 Claude 配备的"技能书"——当你需要它完成特定任务时，它不再需要你一遍遍地解释要求，而是直接按照预先定义好的技能标准来执行工作。
+
+### 为什么需要 Skills？
+
+在没有 Skills 之前，使用 Claude Code 存在一些问题：
+
+- **重复指令**：每次都要解释"代码要符合什么风格"、"提交信息要怎么写"
+- **知识无法沉淀**：团队成员各自的使用经验无法共享
+- **标准不统一**：不同的人用 Claude，结果可能完全不同
+- **效率低下**：常见的任务每次都要从头解释
+
+Skills 解决了这些问题，让 Claude 变成一个"有经验的团队成员"——它知道你的项目规范、工作流程和最佳实践。
+
+---
+
+## 快速开始
+
+### 第一步：安装 find-skills（强烈推荐必装）
+
+在开始使用 Skills 之前，强烈推荐先安装 `find-skills` —— 这是 AI Agent 领域的"技能搜索神器"，目前已有 60K+ 订阅量。
+
+**find-skills 是什么？**
+
+简单来说，find-skills 就像是 AI Agent 的"应用商店搜索器"。当你需要完成某个任务但本地没有对应的 Skill 时，它会自动帮你搜索并推荐最合适的 Skill。
+
+**安装 find-skills**：
+
+```bash
+npx skills add vercel-labs/agent-skills@find-skills -g -y
+```
+
+安装完成后，你就可以直接告诉 Claude 你的需求，它会通过 find-skills 自动搜索相关技能。
+
+**使用示例**：
+
+```
+我需要做一个 React 组件的性能优化，帮我找找有什么技能可以用
+```
+
+Claude 会通过 find-skills 搜索，然后告诉你找到了哪些相关技能，你可以选择安装。
+
+**为什么推荐先装 find-skills？**
+
+没有 find-skills 之前：
+- 手动在 GitHub 搜索相关技能
+- 逐个复制、安装、配置
+- 反复调试适配
+
+有了 find-skills 之后：
+- 一句话描述需求
+- AI 自动搜索最匹配的技能
+- 一键安装，立即可用
+
+**Windows 用户注意**：官方版本对 Windows 支持有限，社区制作了 Windows 适配版本，支持 CMD 和 PowerShell，并增加了中文搜索功能。
+
+下载 Windows 版本：[github.com/tongbei821/customize-skills](https://github.com/tongbei821/customize-skills/blob/main/findskills/SKILL.md)
+
+安装步骤：
+1. 下载 Windows 版本的 SKILL.md
+2. 替换 `C:/Users/你的用户名/.agents/skills/find-skills` 目录下的文件
+3. 重启 Claude Code 即可生效
+
+**相关链接**：
+- [Skills 官网](https://skills.sh/) - 浏览所有可用技能
+- [find-skills 仓库](https://github.com/vercel-labs/agent-skills) - 官方源码
+
+---
+
+### 5 分钟上手 Skills（使用官方有趣 Skills 测试）
+
+让我们通过官方提供的 Skills 来快速体验 Skills 的强大功能。
+
+#### 测试 1：skill-creator（创建技能的技能）
+
+**安装官方 Skills 仓库**：
+
+```bash
+/plugin marketplace add anthropics/skills
+```
+
+或者直接克隆：
+
+```bash
+git clone https://github.com/anthropics/skills.git ~/.claude/skills/official
+```
+
+**体验 skill-creator**：
+
+在 Claude Code 中输入：
+
+```
+/skill-creator
+
+我想创建一个技能，功能是自动格式化 JavaScript 代码。
+```
+
+Claude 会引导你：
+1. 明确技能用途和场景
+2. 生成 SKILL.md 草稿
+3. 创建测试用例
+4. 运行评估并优化
+
+**预期效果**：你不需要手动写任何文件，Claude 会帮你完成整个创建流程。
+
+#### 测试 2：slack-gif-creator（创建 Slack GIF）
+
+**体验创作技能**：
+
+```
+/slack-gif-creator
+
+帮我创建一个 128x128 的 GIF：
+- 蓝色背景渐变
+- 一个白色星星从左飞到右边
+- 同时带一点旋转效果
+```
+
+Claude 会：
+1. 分析需求
+2. 生成 Python 代码（使用 PIL）
+3. 创建动画
+4. 优化文件大小
+
+**预期效果**：一个可用的 GIF 文件，符合 Slack 规范。
+
+#### 测试 3：mcp-builder（构建 MCP 服务器）
+
+**体验 MCP 开发技能**：
+
+```
+/mcp-builder
+
+我想创建一个 MCP 服务器来连接我的 Notion workspace。
+```
+
+Claude 会：
+1. 引导你完成需求分析
+2. 生成 MCP 服务器代码（Python 或 TypeScript）
+3. 配置工具和资源
+4. 提供测试方法
+
+**预期效果**：一个可运行的 MCP 服务器代码。
+
+#### 查看所有可用 Skills
+
+```
+/skills
+```
+
+或
+
+```
+你有哪些技能？
+```
+
+### 理解 Skills 的价值
+
+通过这三个测试，你可以看到 Skills 的核心价值：
+
+1. **技能组合**：不同技能解决不同问题，可以灵活组合
+2. **AI 协作**：让 Claude 引导你完成复杂任务
+3. **可复用性**：创建一次，反复使用
+4. **可共享**：团队成员都可以使用相同的 Skills
+
+接下来，我们会深入探讨 Skills 的各个方面。
+
+---
+
+### 实战：用 find-skills 安装并体验第一个 Skill
+
+安装 find-skills 后，让我们用它来搜索并安装第一个好玩 的 Skill —— Remotion 视频制作工具。
+
+#### 第一步：用 find-skills 搜索 Remotion
+
+在 Claude Code 中输入：
+
+```
+帮我找找 Remotion 相关的技能，我想做视频
+```
+
+Claude 会通过 find-skills 搜索，推荐 `remotion-dev/skills`。
+
+#### 第二步：安装 Remotion Skills
+
+```bash
+npx skills add remotion-dev/skills -g
+```
+
+#### 第三步：用它做个好玩的！
+
+Remotion 是一个用 React 代码制作视频的框架，安装这个 Skill 后，你可以用自然语言让 Claude 帮你写视频代码。
+
+**任务 1：做个炫酷的文字动画视频**
+
+```
+用 Remotion 做一个视频：
+- 1920x1080，5 秒
+- 一行文字 "Hello World" 从左边飞进来
+- 同时带旋转和缩放效果
+- 背景是渐变色
+```
+
+Claude 会生成完整的 Remotion 代码，你可以运行它看到动画效果。
+
+**任务 2：做一个数据可视化视频**
+
+```
+做一个 10 秒的视频，展示数据增长：
+- 开始是一个柱状图
+- 柱子逐个长高（带动画）
+- 数字滚动增加
+- 最后显示 "增长 300%" 的大字
+```
+
+**任务 3：做一个多场景切换的演示视频**
+
+```
+做一个产品演示视频，三个场景：
+场景 1：Logo 淡入显示，2 秒
+场景 2：产品特性列表逐个出现，3 秒
+场景 3：CTA 按钮弹出，2 秒
+每个场景之间有平滑过渡
+```
+
+**运行代码**：
+
+Claude 生成的代码是完整的 Remotion 项目，你可以：
+
+1. 创建新项目：`npx create-video my-video`
+2. 把 Claude 生成的代码复制进去
+3. 运行预览：`npm start`
+4. 渲染视频：`npm run build`
+
+---
+
+### 第二个 Skill：用 find-skills 解决"前端又丑又卡"
+
+#### 第一步：用自然语言描述你的问题
+
+直接告诉 Claude 你的抽象需求：
+
+```
+我的网页看起来很土，而且加载很慢，帮我找找有什么技能可以用
+```
+
+或者更具体一点：
+
+```
+我想让前端变好看，然后别那么卡
+```
+
+#### 第二步：Claude 会用 find-skills 搜索
+
+Claude 会通过 find-skills 搜索 skills.sh 数据库，推荐相关的技能。对于"变好看+不卡"的需求，它会推荐：
+
+**anthropics/skills/frontend-design**（官方技能）
+
+这个技能专门解决 AI 生成的界面"看起来很土"的问题，让 Claude 设计出：
+
+- 独特的视觉风格（避开千篇一律的"AI 模板感"）
+- 专业的配色和字体
+- 流畅的动画效果
+- 生产级别的代码质量（代码干净，性能自然好）
+
+#### 第三步：安装并使用
+
+**安装**：
+
+```bash
+npx skills add anthropics/skills/frontend-design -g
+```
+
+**可以用它完成的任务**：
+
+```
+帮我重新设计这个页面，要看起来很专业，别像 AI 生成的
+```
+
+```
+这个 UI 太丑了，用更现代的设计风格重写
+```
+
+```
+做一个暗色主题的 Dashboard，要有科技感
+```
+
+Claude 会根据这个技能的规范，帮你设计出：
+- 独特的视觉方向（极简主义、复古未来主义、野兽派等）
+- 精心挑选的配色和字体
+- 合理的间距和布局
+- 流畅的交互动画
+
+---
+
+### 两个 Skills 的对比
+
+| Skills | 解决什么问题 | 好玩程度 |
+|--------|-------------|---------|
+| **remotion-dev/skills** | 用代码做视频 | ⭐⭐⭐⭐⭐ |
+| **anthropics/skills/frontend-design** | 让前端变好看 | ⭐⭐⭐⭐ |
+
+---
+
+### 安装后如何使用
+
+安装完成后，你不需要做任何额外配置。当你向 Claude 提出相关任务时，它会自动调用对应的 Skill。
+
+查看已安装的 Skills：
+
+```bash
+npx skills list
+```
+
+---
+
+## Skills 是什么？
+
+### 核心概念
+
+**Skills 是存储在文件系统中的"技能包"**，包含：
+
+- **SKILL.md**：技能的定义文件（必需）
+- **scripts/**：辅助脚本（可选）
+- **templates/**：输出模板（可选）
+- **references/**：参考文档（可选）
+
+### Skills vs 提示词
+
+你可能会有疑问：Skills 和直接给 Claude 发提示词有什么区别？
+
+| 提示词 | Skills |
+|--------|--------|
+| 临时性的，每次都要重复说 | 持久化的，写一次反复用 |
+| 存在对话历史中，占用 Token | 按需加载，节省 Token |
+| 无法在会话间共享 | 可以在团队中共享 |
+| 难以版本控制 | 可以用 Git 管理 |
+
+### Skills 的两种类型
+
+**全局 Skills（个人）**：
+- 存放位置：`~/.claude/skills/`
+- 作用范围：所有项目
+- 适用场景：个人通用技能
+
+**项目 Skills（团队）**：
+- 存放位置：`项目目录/.claude/skills/`
+- 作用范围：当前项目
+- 适用场景：团队共享、项目特定规范
+
+### Skills 如何工作
+
+当 Claude Code 启动时，它会：
+
+1. 扫描 Skills 目录
+2. 解析每个 SKILL.md 文件
+3. 提取 YAML frontmatter 元数据
+4. 将技能内容加入"知识库"
+5. 根据 description 自动匹配触发
+
+---
+
+## SKILL.md 文件结构
+
+### 基本结构
+
+一个完整的 Skill 目录是这样的：
+
+```
+my-skill/
+├── SKILL.md          # 必需：技能定义文件
+├── scripts/          # 可选：辅助脚本
+├── templates/        # 可选：输出模板
+├── references/       # 可选：参考文档
+└── examples/         # 可选：示例文件
+```
+
+### SKILL.md 模板
+
+SKILL.md 文件分为两个部分：
+
+**第一部分：YAML Frontmatter（元数据）**
+
+```yaml
+---
+name: skill-name              # 技能名称，会变成 /skill-name 命令
+description: 简短描述         # 用于 Claude 自动匹配触发
+category: development         # 分类
+tags:                           # 标签
+  - code
+  - automation
+---
+```
+
+**第二部分：Markdown 内容（指令）**
+
+```markdown
+# 技能标题
+
+## 使用场景
+什么时候用这个技能
+
+## 执行步骤
+1. 第一步
+2. 第二步
+
+## 注意事项
+- 注意点 1
+- 注意点 2
+```
+
+### 关键字段说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `name` | 是 | 技能名称，只能用小写字母、数字、连字符 |
+| `description` | 是 | 技能描述，越具体越容易被 Claude 自动匹配 |
+| `category` | 否 | 分类标签 |
+| `tags` | 否 | 更多分类标签 |
+| `allowed-tools` | 否 | 允许使用的工具，无需权限即可用 |
+
+---
+
+## Skills vs MCP：有什么区别？
+
+很多初学者会混淆 Skills 和 MCP，它们是完全不同的两个东西。
+
+### 核心区别
+
+| 维度 | Skills | MCP |
+|------|--------|-----|
+| **本质** | 知识和流程 | 工具和接口 |
+| **提供什么** | 告诉 AI "怎么做" | 给 AI "能用什么" |
+| **存储位置** | `skills/` 目录 | MCP 服务器 |
+| **配置方式** | Markdown 文件 | JSON 配置文件 |
+| **触发方式** | `/skill-name` 或自动识别 | 通过配置自动加载 |
+
+### 形象比喻
+
+如果把 Claude 比作一个"工作人员"：
+
+- **MCP** 是给这个工作人员配备的"工具"（扳手、电脑、访问权限）
+- **Skills** 是给这个工作人员的"操作手册"（怎么做代码审查、怎么提交代码）
+
+### 它们的关系
+
+Skills 和 MCP 不是竞争关系，而是互补关系：
+
+```
+用户任务 → Claude 识别需求
+               ↓
+        加载相关 Skills（知道怎么做）
+               ↓
+        通过 MCP 调用工具（有工具可用）
+               ↓
+        完成任务
+```
+
+### 举例说明
+
+**场景：代码审查**
+
+- **Skills** 定义：审查步骤、检查清单、输出格式
+- **MCP** 提供：访问 GitHub PR、获取代码 diff 的能力
+
+两者配合：Skills 告诉 Claude "怎么审查"，MCP 给 Claude "访问代码的能力"。
+
+### 选择建议
+
+| 你的需求 | 推荐方案 |
+|----------|----------|
+| 需要定义工作流程 | 用 Skills |
+| 需要访问外部数据 | 用 MCP |
+| 需要两者都有 | 配合使用 |
+
+---
+
+## 常用 Skills 获取资源
+
+### 官方资源
+
+- [Anthropic 官方 Skills 仓库](https://github.com/anthropics/skills) - 官方维护的技能集合
+- [Claude Code 官方文档 - Skills](https://docs.anthropic.com/en/docs/claude-code/configuration/skills) - 官方文档
+
+### GitHub 社区资源
+
+| 仓库 | 说明 |
+|------|------|
+| [shanraisshan/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) | Boris Cherny（Claude Code 负责人）维护，包含 Skills、Agents、Hooks 等 |
+| [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) | 综合工具包，包含预配置 Skills |
+| [JackyST0/awesome-agent-skills](https://github.com/JackyST0/awesome-agent-skills) | 精选 Skills 资源列表 |
+| [jeffallan/claude-skills](https://github.com/jeffallan/claude-skills) | 66 个专业技能，300+ 参考文档 |
+| [GitCode/awesome-claude-skills](https://gitcode.com/GitHub_Trending/aw/awesome-claude-skills) | 开源精选 |
+
+### 如何安装社区 Skills
+
+使用 find-skills，只需要告诉 Claude 你需要什么，它会自动搜索并推荐：
+
+```
+帮我找找有什么 React 性能优化相关的技能
+```
+
+Claude 会通过 find-skills 搜索 skills.sh 数据库，然后列出最相关的技能，你选择安装即可。
+
+**搜索技巧**：
+
+- 使用具体关键词："react testing" 优于 "testing"
+- 组合「领域 + 动作」："nextjs deploy"、"typescript lint"
+- 优先选择高安装量的技能（10K+ 说明经过实战检验）
+- 关注 Trending 榜单发现新兴技能
+
+---
+
+## 如何创建自己的 Skills
+
+创建 Skills 有两种方法：一种是直接让 Claude 帮你创建，另一种使用专门的 skill-creator 工具。
+
+### 方法一：直接让 Claude 帮你创建
+
+这是最简单的方式，直接用自然语言告诉 Claude 你的需求。
+
+**示例**：
+
+```
+请帮我创建一个名为 "format-code" 的 skill，功能是自动格式化代码。
+
+要求：
+1. 自动检测编程语言类型
+2. 应用对应的格式化规则
+3. 返回格式化前后的 diff
+```
+
+Claude 会自动：
+1. 创建目录结构
+2. 生成 SKILL.md 文件
+3. 填写 YAML frontmatter
+4. 编写技能内容
+
+**适用场景**：
+- 快速创建简单技能
+- 你知道要什么，但不熟悉 SKILL.md 格式
+- 想要快速迭代和修改
+
+### 方法二：使用 skill-creator
+
+skill-creator 是一个专门用来创建 Skills 的工具，会引导你一步步完成。
+
+**安装**：
+
+```bash
+npx skills add anthropics/skills@skill-creator -g
+```
+
+或者安装整个官方 skills 仓库：
+
+```bash
+npx skills add anthropics/skills -g
+```
+
+**使用**：
+
+```
+/skill-creator
+```
+
+然后按提示填写：
+- 技能名称
+- 功能描述
+- 使用场景
+- 执行步骤
+
+skill-creator 会：
+1. 引导你明确技能用途
+2. 生成 SKILL.md 草稿
+3. 创建测试用例
+4. 运行评估并优化
+
+**适用场景**：
+- 创建复杂的技能
+- 需要规范的创建流程
+- 想要测试和验证技能
+
+### 两种方法对比
+
+| 方法一：直接创建 | 方法二：skill-creator |
+|-----------------|---------------------|
+| 快速简单 | 步骤引导 |
+| 适合简单技能 | 适合复杂技能 |
+| 直接对话完成 | 规范流程 |
+| 灵活修改 | 有测试验证 |
+
+### 技巧：如何写好需求
+
+**好的需求描述**：
+
+```
+创建一个 "git-commit" skill，功能是自动提交代码。
+
+执行步骤：
+1. 检查有哪些文件被修改
+2. 生成符合 Conventional Commits 规范的提交信息
+3. 执行 git commit
+4. 询问是否需要 push
+
+注意事项：
+- 提交前先检查是否有敏感信息
+- 不要提交 dist/node_modules/ 等目录
+```
+
+**不好的需求描述**：
+
+```
+帮我写一个提交代码的 skill
+```
+
+太模糊了，Claude 不知道具体要做什么。
+
+---
+
+## 常用 Skills 实例
+
+### 实例 1：代码审查 Skill
+
+创建目录和文件：
+
+```bash
+mkdir -p ~/.claude/skills/review-pr
+```
+
+```bash
+cat > ~/.claude/skills/review-pr/SKILL.md << 'EOF'
+---
+name: review-pr
+description: 审查 Pull Request 的代码质量、安全性和测试覆盖率
+---
+
+你是一位资深的代码审查者。
+
+## 审查流程
+
+1. **代码风格检查**
+   - 代码是否符合团队规范
+   - 命名是否清晰
+   - 注释是否充分
+
+2. **安全性检查**
+   - 是否有安全漏洞
+   - 敏感信息是否暴露
+   - 输入验证是否完善
+
+3. **测试检查**
+   - 是否有足够的测试
+   - 测试用例是否覆盖边界情况
+   - 测试是否可运行
+
+4. **总体评价**
+   - 优点是什么
+   - 需要改进的地方
+   - 建议是否批准合并
+
+## 输出格式
+
+请以清晰的结构输出审查结果，使用列表形式。
+EOF
+```
+
+使用方式：
+
+```
+/review-pr
+请审查当前分支的 PR
+```
+
+### 实例 2：Git 自动提交 Skill
+
+```bash
+mkdir -p ~/.claude/skills/git-commit
+```
+
+```bash
+cat > ~/.claude/skills/git-commit/SKILL.md << 'EOF'
+---
+name: git-commit
+description: 自动检测修改、生成提交信息并提交代码
+---
+
+你是一位熟练的 Git 用户。
+
+## 执行流程
+
+1. **检查修改**
+   运行 `git status` 查看修改的文件
+   运行 `git diff` 查看具体改动
+
+2. **生成提交信息**
+   分析改动的性质
+   生成符合 Conventional Commits 格式的提交信息
+   格式：`type(scope): description`
+
+3. **安全检查**
+   检查是否有敏感信息（密钥、密码、token）
+   检查是否包含了不该提交的目录
+
+4. **确认后执行**
+   显示提交信息供确认
+   执行 `git add` 和 `git commit`
+   询问是否需要 push
+
+## 注意事项
+
+- 不要提交 node_modules/、dist/、.next/ 等目录
+- 提交前先运行测试确保代码可用
+- 提交信息要清晰说明改动内容
+EOF
+```
+
+使用方式：
+
+```
+/git-commit
+```
+
+### 实例 3：测试生成 Skill
+
+```bash
+mkdir -p ~/.claude/skills/gen-test
+```
+
+```bash
+cat > ~/.claude/skills/gen-test/SKILL.md << 'EOF'
+---
+name: gen-test
+description: 为代码自动生成单元测试，确保功能正确性
+---
+
+你是一位测试开发工程师。
+
+## 工作流程
+
+1. **分析代码**
+   - 理解函数/类的功能
+   - 识别输入和输出
+   - 找出边界情况
+
+2. **生成测试**
+   - 使用合适的测试框架
+   - 覆盖正常情况
+   - 覆盖边界情况
+   - 覆盖异常情况
+
+3. **验证测试**
+   - 确保测试可以运行
+   - 确保测试能检测到问题
+   - 不要过度模拟实现
+
+## 测试框架
+
+- JavaScript/TypeScript：Jest 或 Vitest
+- Python：pytest
+- Go：testing 包
+
+## 输出格式
+
+先输出测试代码，然后说明如何运行测试。
+EOF
+```
+
+使用方式：
+
+```
+/gen-test
+为 src/utils.ts 生成单元测试
+```
+
+### 实例 4：文档生成 Skill
+
+```bash
+mkdir -p ~/.claude/skills/gen-readme
+```
+
+```bash
+cat > ~/.claude/skills/gen-readme/SKILL.md << 'EOF'
+---
+name: gen-readme
+description: 为项目自动生成 README 文档
+---
+
+你是一位技术文档专家。
+
+## 工作流程
+
+1. **分析项目**
+   - 扫描项目目录结构
+   - 查看 package.json 或其他配置文件
+   - 阅读现有代码
+
+2. **生成内容**
+   - 项目简介
+   - 安装方法
+   - 使用说明
+   - API 文档
+   - 开发指南
+
+3. **格式化**
+   - 使用清晰的章节结构
+   - 添加代码示例
+   - 添加适当的徽章
+   - 添加许可证信息
+
+## 标准 README 结构
+
+- 项目标题和简介
+- 功能特点
+- 安装方法
+- 快速开始
+- 使用说明
+- API 文档
+- 开发指南
+- 贡献指南
+- 许可证
+EOF
+```
+
+使用方式：
+
+```
+/gen-readme
+为当前项目生成 README 文档
+```
+
+---
+
+## 进阶技巧
+
+### Skills 与 Hooks 配合
+
+Hooks 可以在特定事件时自动执行操作，结合 Skills 可以实现更强大的自动化。
+
+例如：代码保存后自动格式化
+
+```json
+// .claude/hooks.json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": {
+        "tool_name": "Edit"
+      },
+      "hook": {
+        "type": "command",
+        "command": "/format-code"  // 调用 format-code skill
+      }
+    }]
+  }
+}
+```
+
+### Skills 与 Commands 配合
+
+Commands 是简单的快捷命令，Skills 是复杂的工作流。两者可以配合使用。
+
+### 团队协作
+
+**共享项目 Skills**：
+
+1. 将 Skills 放在 `.claude/skills/` 目录
+2. 提交到 Git 仓库
+3. 团队成员克隆项目后即可使用
+
+**版本控制**：
+
+- Skills 可以像代码一样进行版本控制
+- 每个 commit 都可以记录 Skills 的变更
+- 可以回滚到旧版本
+
+---
+
+## 常见问题
+
+### Q1：Skill 没有被触发？
+
+可能的原因：
+- YAML frontmatter 格式错误
+- description 不够具体
+- Claude Code 没有重启
+
+解决方法：
+- 检查 YAML 格式是否正确
+- 改进 description，包含具体的使用场景
+- 重启 Claude Code
+
+### Q2：description 怎么写才准确？
+
+好的 description 包含：
+- 技能的具体功能
+- 使用场景（"当用户提到..."）
+- 触发关键词
+
+**不好的例子**：
+```
+description: 审查代码
+```
+
+**好的例子**：
+```
+description: 审查 Pull Request 的代码。当用户提到 PR、review、代码审查时触发。
+```
+
+### Q3：Skills 和 Commands 的区别？
+
+| Commands | Skills |
+|----------|--------|
+| 简单快捷命令 | 完整工作流 |
+| 单个 `.md` 文件 | 目录结构（SKILL.md + 可选文件） |
+| 手动触发 | 可自动触发 |
+| 适合简单操作 | 适合复杂流程 |
+
+### Q4：如何调试 Skill？
+
+1. 使用 `/skills` 查看技能是否被识别
+2. 直接输入技能名称手动触发
+3. 检查 SKILL.md 文件内容是否正确
+4. 查看 Claude Code 日志
+
+---
+
+## 参考资料
+
+### 官方资源
+
+- [Claude Code 官方文档 - Skills](https://docs.anthropic.com/en/docs/claude-code/configuration/skills)
+- [Agent Skills 标准](https://agentskills.io/)
+- [Anthropic 官方工程文章（Agent Skills 实战理念）](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
+- [Anthropic 官方 Skills GitHub 仓库](https://github.com/anthropics/skills)
+- [VS Code Copilot Agent Skills 文档](https://code.visualstudio.com/docs/copilot/customization/agent-skills)
+
+### 资源入口
+
+- [skills.sh](https://skills.sh/) - Vercel 出品的 Agent Skills 应用商店，48000+ 技能库
+- [find-skills](https://github.com/vercel-labs/agent-skills) - 智能技能搜索工具，60K+ 订阅
+- [Skills 市场（中文界面）](https://skillsmp.com/zh) - 发现和安装社区 Skills
+
+### GitHub 社区项目
+
+- [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) - Vercel Labs 官方 Agent Skills 集合（含 find-skills）
+- [claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) - Boris Cherny 维护的官方最佳实践
+- [everything-claude-code](https://github.com/affaan-m/everything-claude-code) - 综合工具包，包含预配置 Skills
+- [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) - 精选 Skills 资源列表
+- [superpowers](https://github.com/obra/superpowers) - 软件开发自动化工作流 Skills 集合
+- [jeffallan/claude-skills](https://github.com/jeffallan/claude-skills) - 66 个专业技能，300+ 参考文档
+- [awesome-agent-skills](https://github.com/JackyST0/awesome-agent-skills) - 精选资源列表
+
+### 官方 Skills 示例
+
+- [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) - 创建新技能的技能
+- [mcp-builder](https://github.com/anthropics/skills/tree/main/skills/mcp-builder) - 构建 MCP 服务器的技能
+- [slack-gif-creator](https://github.com/anthropics/skills/tree/main/skills/slack-gif-creator) - 创建 Slack GIF 的技能
+
+### 中文教程
+
+- [Claude Code 高级配置与使用技巧完全指南](https://blog.csdn.net/2601_95335870/article/details/158460599)
+- [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)
+
+---
+
+## 总结
+
+Skills 是让 Claude Code 从"通用助手"变成"团队专家"的关键。
+
+通过 Skills，你可以：
+- 标准化工作流程
+- 复用团队知识
+- 提高协作效率
+- 减少重复解释
+
+记住：**如果你发现自己重复两次同样的指令，就应该考虑创建一个 Skill**。
+
+现在就开始创建你的第一个 Skill 吧！
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/3.3-long-running-tasks/index.md
new file mode 100644
index 0000000..b0a3494
--- /dev/null
+++ b/docs/zh-cn/stage-3/core-skills/3.3-long-running-tasks/index.md
@@ -0,0 +1,577 @@
+# 高级二：如何让 Claude Code 长时间工作
+
+## 引言
+
+传统的 AI 编程助手是"对话式"的——你说一句，它回一句，然后停下了。但对于真正的开发任务来说，这种模式远远不够。
+
+想象一下这些场景：你想让 Claude 帮你重构整个项目，但它写完几个文件就说"我完成了"；你想让 Claude 持续修复 bug 直到测试全部通过，但它跑一次就停下来；你想让 Claude "过夜干活"，但第二天发现它早就停了。
+
+本章要解决的核心问题是：如何让 Claude Code 像真正的开发者一样，持续工作直到任务真正完成。
+
+---
+
+## 核心原理：为什么 AI 会"过早停止"？
+
+在介绍各种方法之前，先理解问题的根源。
+
+### AI 的"完成判断"不可靠
+
+LLM（大语言模型）有一个根本缺陷：它无法准确判断自己的工作是否真正完成。
+
+人类的完成标准是客观的——所有测试通过、功能完整可用、代码质量达标。但 AI 只能基于"感觉"来判断。它可能会觉得"看起来差不多了"就停止，或者觉得"输出够多了"就停下，又或者不知道接下来该干什么而停下。
+
+这就是为什么我们需要一个外部系统来判断任务是否真正完成，而不是依赖 AI 自己的感觉。
+
+### 解决方案的核心思想
+
+解决方案的核心是：让 AI 在一个"循环"中工作。
+
+每次它想退出时，外部系统会检查三个问题——真的完成了吗？符合客观标准了吗？还有没有遗漏？如果没有，就重新注入任务，继续下一轮。
+
+这个思想的实现形式多种多样，从简单的 bash 脚本到复杂的编排系统，本质都是一样的。
+
+---
+
+## 方法一：While True Bash Loop（最原始的方法）
+
+这是最简单、最直接的实现方式。本质上就是写一个无限循环，每次循环都重新启动 Claude Code 并喂给它同样的任务描述。
+
+最简单的实现只需要 5 行代码：
+
+```bash
+#!/bin/bash
+while true; do
+    cat PROMPT.md | claude
+done
+```
+
+### 工作原理
+
+这个脚本的工作流程很直接。第一步是读取 PROMPT.md 文件中的任务描述。第二步是启动 Claude Code 并将任务描述传递给它。第三步是 Claude 开始工作并输出结果。第四步是 Claude 完成后退出。第五步是循环自动重新启动，整个过程回到第一步，形成无限循环——除非你手动按 Ctrl+C 中断。
+
+### 优缺点
+
+这种方法的优点是极其简单，任何人都能看懂，不需要任何配置，立即可用，适合快速实验。
+
+但缺点也很明显：它无法判断任务是否真的完成，可能无限空转，没有安全保护机制，会浪费 API 调用。
+
+### 实际使用示例
+
+首先创建一个 PROMPT.md 文件来描述任务。比如重构用户认证模块的任务可以这样写：
+
+```markdown
+# 任务：重构用户认证模块
+
+要求：
+1. 将所有认证逻辑抽取到独立的 AuthService 类
+2. 添加单元测试，覆盖率 > 80%
+3. 更新相关文档
+
+当所有测试通过且文档更新完成后，输出：任务完成
+```
+
+然后创建循环脚本并运行：
+
+```bash
+chmod +x loop.sh
+./loop.sh
+```
+
+### 安全改进版
+
+为了避免无限循环，可以添加迭代次数限制：
+
+```bash
+#!/bin/bash
+MAX_ITERATIONS=50
+iteration=0
+
+while true; do
+    iteration=$((iteration + 1))
+    echo "=== 迭代 $iteration/$MAX_ITERATIONS ==="
+
+    cat PROMPT.md | claude
+
+    if [ $iteration -ge $MAX_ITERATIONS ]; then
+        echo "达到最大迭代次数，停止"
+        break
+    fi
+
+    sleep 5  # 稍作等待，避免 API 限流
+done
+```
+
+这个改进版本添加了最大迭代次数限制，每次循环显示当前进度，达到限制后自动停止。同时在每次循环之间添加 5 秒延迟，避免触发 API 限流。
+
+---
+
+## 方法二：Ralph Wiggum Plugin（官方推荐）
+
+Ralph Wiggum 是 Anthropic 官方推出的插件，专门解决长时间任务问题。它以《辛普森一家》中的角色命名，象征着"尽管失败，仍坚持尝试"的精神。
+
+### 核心机制：Stop Hook
+
+Ralph 的核心机制是 Stop Hook。当 Claude 想要退出时，Stop Hook 会拦截这个退出信号。然后系统会检查：输出了特定的完成标记吗？如果没有找到完成标记，就重新注入原始 prompt，开始下一轮迭代。如果找到了完成标记，才允许 Claude 退出。
+
+这个机制保证了 Claude 不会因为"感觉差不多了"就停下来，而是必须真正完成明确标记的任务。
+
+### 安装
+
+安装很简单，只需要在 Claude Code 中运行：
+
+```bash
+claude /plugins:add ralph-wiggum
+```
+
+### 基本使用
+
+基本使用方式是通过 `/ralph-loop` 命令：
+
+```bash
+/ralph-loop "构建一个待办事项 API，包含 CRUD 操作、输入验证、测试。
+             全部完成后输出 <promise>COMPLETE</promise>" \
+  --max-iterations 50 \
+  --completion-promise "COMPLETE"
+```
+
+### 参数说明
+
+最重要的两个参数是 `--max-iterations` 和 `--completion-promise`。
+
+`--max-iterations` 设置最大迭代次数，这是安全机制，推荐值在 20-100 之间。即使任务没有完成，达到这个次数后也会停止，防止无限循环消耗 API 额度。
+
+`--completion-promise` 指定完成标记文本，需要是一个明确唯一的标识。当 Claude 的输出中包含这个标记时，Ralph 才会认为任务完成并允许退出。推荐使用像 `COMPLETE`、`TASK_DONE` 这样清晰的标记，避免使用模糊的词汇。
+
+### Prompt 编写最佳实践
+
+编写好的 Prompt 是 Ralph 成功的关键。
+
+不好的 Prompt 往往没有明确的完成标准。比如简单地说"写一个 todo API"，这样 AI 可能写个基础框架就说完成了，没有测试、没有验证、没有文档。
+
+好的 Prompt 应该包含详细的阶段性要求和明确的验收标准。比如可以这样写：
+
+首先分阶段描述任务。阶段 1 是基础功能，列出所有 CRUD 端点：POST /todos 创建任务、GET /todos 获取列表、GET /todos/:id 获取单个、PUT /todos/:id 更新、DELETE /todos/:id 删除。阶段 2 是输入验证，标题不能为空，完成状态必须是布尔值。阶段 3 是测试，为每个端点编写测试，覆盖率要大于 80%。
+
+然后列出验收标准：所有测试通过、代码通过 linter 检查、README 包含 API 文档。
+
+最后指定一个唯一的完成标记：`<promise>TODO_API_COMPLETE</promise>`。
+
+这样 Claude 就知道确切要做什么，什么时候才算真正完成。
+
+### 实战案例
+
+有一个著名的案例是在 Y Combinator 黑客松上，一个团队使用 Ralph Loop。晚上 11 点他们设置任务：根据 specs 目录下的 6 个产品需求，依次实现每个项目的 MVP，每完成一个输出特定的完成标记。设置最大迭代次数 200 次，然后就去睡觉了。
+
+第二天早上醒来，他们发现有 6 个可演示的项目，而 API 调用成本只有 297 美元。这就是 Ralph 的威力——你睡觉的时候，AI 在工作。
+
+另一个案例来自 Boris Cherny（Claude Code 负责人）。他使用 Ralph 加上 Opus 4.5 模型，在 30 天内提交了 259 个 PR，包含 497 次提交，新增 40,000 行代码、删除 38,000 行代码。最惊人的是，这 100% 都是由 Claude Code 完成的，没有人工编写一行代码。
+
+### Ralph 的哲学
+
+Ralph 体现了三个核心哲学思想。
+
+第一是迭代大于完美。不要指望一次就完美，让循环来改进。第一次可能只写个框架，第二次修复 bug，第三次优化代码，第四次添加测试，每次都比上一次更好。
+
+第二是失败是数据。每次测试失败都是改进的机会，不要害怕失败，要从失败中学习。
+
+第三是持续尝试。Keep trying until it works——这就是 Ralph 的精神。
+
+---
+
+## 方法三：增强版 Ralph
+
+这是社区对官方 Ralph 的增强实现，在 GitHub 上可以找到 [frankbria/ralph-claude-code](https://github.com/frankbria/ralph-claude-code) 项目，增加了更多安全机制。
+
+### 额外特性
+
+增强版提供了几个额外的安全特性。
+
+第一个是双重退出条件。官方 Ralph 只需要检查完成标记，但增强版需要同时满足完成标记和显式 EXIT_SIGNAL 才会真正停止。这意味着即使 Claude 输出了完成标记，如果它没有明确表示要退出，循环还会继续，可以进一步验证和改进。
+
+第二个是速率限制功能。默认设置为 100 次/小时，防止因为某种 bug 导致无限循环时，API 账单爆炸。你可以根据需要调整这个限制。
+
+第三个是智能熔断器。如果系统连续 5 次检测到完成标记，会强制退出。这是为了防止某种边缘情况导致循环无法正常结束。
+
+第四个是实时仪表盘。增强版提供了一个命令行界面，可以显示当前迭代次数、任务进度、预估成本等信息，让你随时掌握状态。
+
+### 安装
+
+安装增强版 Ralph 需要先从 GitHub 克隆仓库：
+
+```bash
+git clone https://github.com/frankbria/ralph-claude-code.git
+cd ralph-claude-code
+./install.sh
+```
+
+安装脚本会自动设置好所需的文件和配置。
+
+### 使用
+
+使用增强版 Ralph 分两步。首先用 `ralph-setup` 命令初始化项目：
+
+```bash
+ralph-setup my-project
+```
+
+这会在项目中创建所需的配置文件。然后用 `ralph loop` 命令启动循环：
+
+```bash
+ralph loop
+```
+
+### 配置文件
+
+增强版 Ralph 使用配置文件 `.claude/ralph-config.json` 来设置参数：
+
+```json
+{
+  "maxIterations": 50,
+  "rateLimitPerHour": 100,
+  "completionPromise": "TASK_COMPLETE",
+  "exitSignal": "EXIT_NOW",
+  "costAlertThresholds": [10, 50, 100]
+}
+```
+
+`maxIterations` 是最大迭代次数。`rateLimitPerHour` 是每小时速率限制。`completionPromise` 是完成标记文本。`exitSignal` 是显式退出信号。`costAlertThresholds` 是成本预警阈值，当花费达到这些金额时会发出警告。
+
+---
+
+## 方法四：Agent Teams（多代理并行）
+
+当任务足够大时，单个 Claude 不够用，需要"团队协作"。
+
+Agent Teams 是一个高级功能，允许多个 Claude 实例并行工作，通过共享任务列表协调依赖关系。这适合超大型项目，比如 Nicholas Carlini 的实验中，16 个并行 Agent 在 2 周内编写了 100,000+ 行代码，构建出一个能编译 Linux 内核的 C 编译器。
+
+Agent Teams 的内容比较复杂，我们将在下一节《3.3 Agent Teams 多代理协作》中详细讲解。
+
+---
+
+## 方法五：后台任务（Ctrl+B）
+
+这是一个简单但实用的非阻塞执行方法。
+
+### 基本操作
+
+使用方式很直观。当 Claude 开始运行一个任务时，你可以按 `Ctrl+B` 把它推送到后台。
+
+比如你说："运行完整测试套件"。Claude 开始运行。你可以按 `Ctrl+B`，Claude 会返回："任务已推送到后台（ID: task_abc123）"。然后你可以继续说："同时，帮我分析这个日志文件"。Claude 会在后台运行测试的同时，帮你分析日志。
+
+### 查看后台任务
+
+有几种方式查看后台任务。使用 `/tasks` 命令可以列出所有后台任务，包括任务 ID、状态、启动时间等信息。按 `Ctrl+T` 可以快速查看任务状态的摘要。你也可以从任务列表中选择某个任务，把它恢复到前台（Bring to foreground），查看它的实时输出。
+
+### 适用场景
+
+后台任务适合几个典型场景。
+
+第一个是长时间运行的测试。完整测试套件可能需要几十分钟，用后台任务可以在测试运行的同时继续开发。
+
+第二个是大型项目构建。构建过程可能需要很长时间，后台运行不会阻塞其他工作。
+
+第三个是批量文件处理。比如批量重命名、批量格式化等，可以在后台进行。
+
+第四个是任何你不想等待的事情。
+
+---
+
+## 安全机制：防止无限循环
+
+任何自动循环系统都必须有安全保护，否则可能出现失控的情况。
+
+### 硬性限制
+
+最基本的保护是设置 `--max-iterations`（最大迭代次数），这是必须的。无论任务是否完成，达到这个次数后都会停止，防止无限循环消耗 API 额度。
+
+你还可以设置时间限制，比如最长运行 4 小时后自动停止。或者设置 API 预算警告，当花费达到一定金额（比如 10 美元、50 美元、100 美元）时暂停并通知你。
+
+### 智能检测
+
+可以添加智能检测来发现死循环。比如检查最近几次提交有没有实质变化：
+
+```bash
+if [ $(git diff HEAD~5 | wc -l) -eq 0 ]; then
+    echo "最近 5 次提交没有实质变化，可能陷入循环"
+    exit 1
+fi
+```
+
+如果最近 5 次提交的代码差异很小，说明可能陷入了死循环，应该停止并报警。
+
+### 成本预警
+
+配置文件中可以设置成本预警阈值：
+
+```json
+{
+  "costAlertThresholds": [10, 50, 100],
+  "alertAction": "pause_and_notify"
+}
+```
+
+当花费达到 10、50、100 美元时，系统会暂停任务并发送通知，让你决定是否继续。
+
+### 人工检查点
+
+对于特别重要的任务，可以设置人工检查点：
+
+```bash
+if [ $((iteration % 10)) -eq 0 ]; then
+    read -p "已完成 $iteration 次迭代，继续吗？(y/n)" answer
+    if [ "$answer" != "y" ]; then
+        break
+    fi
+fi
+```
+
+这样每 10 次迭代暂停一次，等待你确认是否继续。这样可以在出现问题时及时干预。
+
+---
+
+## 实战：用 Ralph Loop 构建完整的 BBS 论坛系统
+
+让我们通过一个完整的例子来展示 Ralph Loop 的威力。我们将从零开始构建一个仿造 BBS 论坛系统，包含用户鉴权、发帖、用户中心和管理后台。
+
+### 项目目标
+
+构建一个功能完整的 BBS 论坛系统，包含：
+
+**用户端功能**：
+- 用户注册、登录、退出
+- 浏览帖子列表（分页）
+- 查看帖子详情
+- 发布新帖
+- 评论功能
+- 个人中心（查看自己的帖子、修改个人信息）
+
+**管理后台功能**：
+- 管理员登录
+- 用户管理（封禁、解封）
+- 帖子管理（删除、置顶）
+- 评论管理
+- 系统统计
+
+**技术栈**：
+- 后端：Node.js + Express + SQLite 数据库
+- 前端：React + React Router + Axios
+- 认证：JWT Token
+- 样式：Tailwind CSS
+
+### 准备工作
+
+首先安装 Ralph Wiggum 插件：
+
+```bash
+claude /plugins:add ralph-wiggum
+```
+
+### 启动 Ralph Loop
+
+现在启动 Ralph Loop，让它完成整个项目：
+
+```bash
+/ralph-loop "
+请从零开始构建一个完整的 BBS 论坛系统，使用 TDD 方式开发。
+
+项目结构要求：
+- backend/ 目录：Express API 服务器
+- frontend/ 目录：React 前端应用
+- 两个目录都有各自的测试
+
+后端功能要求：
+- 使用 Express 框架
+- SQLite 数据存储（better-sqlite3）
+- JWT 用户认证（jsonwebtoken + bcrypt）
+- 用户表：id、username、password、email、role、createdAt
+- 帖子表：id、title、content、authorId、category、pinned、createdAt
+- 评论表：id、content、postId、authorId、createdAt
+
+后端 API 端点：
+- POST /api/auth/register - 用户注册
+- POST /api/auth/login - 用户登录
+- GET /api/posts - 获取帖子列表（分页、分类筛选）
+- GET /api/posts/:id - 获取帖子详情
+- POST /api/posts - 发布帖子（需登录）
+- PUT /api/posts/:id - 编辑帖子（作者或管理员）
+- DELETE /api/posts/:id - 删除帖子（作者或管理员）
+- POST /api/posts/:id/comments - 发表评论（需登录）
+- GET /api/user/profile - 获取个人信息（需登录）
+- PUT /api/user/profile - 更新个人信息（需登录）
+- GET /api/admin/stats - 管理员统计（需管理员）
+- GET /api/admin/users - 用户列表（需管理员）
+- PUT /api/admin/users/:id/ban - 封禁用户（需管理员）
+
+前端页面要求：
+- /login - 登录页
+- /register - 注册页
+- / - 首页（帖子列表）
+- /post/:id - 帖子详情
+- /new - 发布帖子
+- /profile - 个人中心
+- /admin - 管理后台（需管理员权限）
+
+管理后台功能：
+- 用户管理（查看、封禁、解封）
+- 帖子管理（查看、删除、置顶）
+- 评论管理（查看、删除）
+- 系统统计（用户数、帖子数、评论数）
+
+TDD 要求：
+- 先写测试，后写代码
+- 每个功能都要有对应的测试
+- 后端使用 Jest，API 测试要覆盖所有端点
+- 前端使用 Vitest，组件测试要覆盖主要功能
+- 认证中间件要有测试
+
+验收标准：
+- 运行 npm test（后端）全部通过
+- 运行 npm test（前端）全部通过
+- 前端可以正常启动并使用
+- 后端 API 可以正常响应
+- 普通用户和管理员权限正确隔离
+- 代码通过 ESLint 检查
+
+完成后输出：<promise>BBS_SYSTEM_COMPLETE</promise>
+" --max-iterations 150 --completion-promise "BBS_SYSTEM_COMPLETE"
+```
+
+### 预计时间
+
+根据项目复杂度：
+
+**如果人工编写**：大约 40-60 小时（包括数据库设计、认证系统、前后端联调、测试）
+
+**使用 Ralph Loop**：
+- 基础版本（核心功能）：约 3-5 小时
+- 完整版本（包含管理后台、测试）：约 6-10 小时
+
+### 监控进度
+
+Ralph Loop 运行时，你可以通过几个方式监控进度：
+
+**查看迭代次数**：Ralph 会显示当前迭代次数和最大次数，你可以估算剩余时间。
+
+**查看日志**：你可以看到 Claude 正在做什么——设计数据库、写 API、实现前端组件、修复 bug。
+
+**测试状态**：每次测试运行的结果会显示，通过的测试会增加，失败的测试会减少。当失败的测试开始变少，说明项目接近完成。
+
+### 完成后验证
+
+当 Ralph Loop 输出完成标记后，你需要手动验证：
+
+```bash
+# 后端测试
+cd backend
+npm test
+
+# 前端测试
+cd frontend
+npm test
+
+# 启动后端
+cd backend
+npm start
+
+# 启动前端（另一个终端）
+cd frontend
+npm run dev
+```
+
+打开浏览器，测试以下流程：
+
+1. 注册新用户
+2. 登录
+3. 浏览帖子
+4. 发布新帖
+5. 发表评论
+6. 访问个人中心
+7. 退出后用管理员登录（默认账号：admin/admin123）
+8. 测试管理后台功能
+
+### 注意事项
+
+Ralph Loop 虽然强大，但有几个注意事项：
+
+**第一，Prompt 越详细，结果越好**。模糊的 Prompt 导致需要更多迭代来修正。
+
+**第二，设置合理的迭代次数**。BBS 系统比较复杂，建议至少 100 次迭代。
+
+**第三，TDD 是推荐方式**。先写测试可以大幅减少调试时间。
+
+**第四，最终需要人工验证**。AI 可能遗漏边界情况或特殊场景，特别是安全相关的功能。
+
+**第五，数据库设计要仔细**。Ralph 可能需要几次迭代才能设计出合理的数据库结构。
+
+---
+
+## 方法对比与选择
+
+各种方法各有特点，适合不同场景。
+
+While True Loop 最简单，只需要 5 行代码就能工作，适合快速实验和原型验证。但功能有限，没有完成检测，只能靠迭代次数限制。
+
+Ralph Wiggum 是通用推荐，适合大部分场景。它有完整的 Stop Hook 机制，支持完成标记检测，有官方支持，文档完善。
+
+增强版 Ralph 更适合生产环境，有双重退出条件、速率限制、智能熔断器等额外的安全机制。
+
+后台任务适合简单的非阻塞执行，只需要按 `Ctrl+B` 就能用。但它只是简单的后台运行，没有循环机制。
+
+---
+
+## 总结
+
+让 Claude Code 长时间工作的核心思想很简单：不要让它"一次完成"，而是让它"持续尝试直到真正完成"。
+
+所有方法本质上都是在做同一件事：给 Claude 一个任务，让它工作，检查是否真的完成，如果没有，继续下一轮。
+
+选择哪种方法取决于你的具体需求。
+
+如果想要简单快速，用 While True Loop。5 行代码就能工作，但功能有限。
+
+如果想要通用推荐，用 Ralph Wiggum。官方支持，功能完整，适合大部分场景。
+
+如果是生产环境，用增强版 Ralph。有额外的安全机制，更可靠。
+
+（Agent Teams 多代理协作的内容请参考下一节《3.3 Agent Teams 多代理协作》）
+
+希望这一章的内容能帮助你更好地利用 Claude Code，让 AI 真正成为你的生产力工具，而不仅仅是聊天机器人。
+
+---
+
+## 参考资料
+
+### 官方资源
+
+- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code) - Claude Code 的完整官方文档
+- [Ralph Wiggum Plugin README](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-wiggum) - Ralph Wiggum 插件的官方文档
+- [Claude Code Hooks 系统](https://docs.anthropic.com/en/docs/claude-code/configuration/hooks) - Hooks 系统的官方文档
+
+### 社区项目
+
+- [frankbria/ralph-claude-code](https://github.com/frankbria/ralph-claude-code) - 增强版 Ralph 实现，包含额外的安全机制
+- [win4r/claude-code-hooks](https://github.com/win4r/claude-code-hooks) - Hook 示例和工具集合
+- [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 的逆向工程分析
+
+### 实战案例
+
+- [16 Agents Build C Compiler](https://arxiv.org/abs/2408.01342) - Nicholas Carlini 的实验论文
+- [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
diff --git a/docs/zh-cn/stage-3/core-skills/3.4-agent-teams/index.md b/docs/zh-cn/stage-3/core-skills/3.4-agent-teams/index.md
new file mode 100644
index 0000000..4d67bde
--- /dev/null
+++ b/docs/zh-cn/stage-3/core-skills/3.4-agent-teams/index.md
@@ -0,0 +1,2756 @@
+# Claude Agent Teams 完全指南
+
+## Agent Teams 简介
+
+**Agent Teams** 是 Claude Code 的一个革命性功能，它让**多个独立的 AI 实例可以像真正的开发团队一样协同工作**。
+
+想象一下，以前你使用 Claude Code，就像是一个项目经理带着一个超级能干的助手工作。无论任务多复杂，只有这一个助手在干活。现在有了 Agent Teams，你可以组建一支完整的 AI 开发团队——有的负责前端，有的负责后端，有的负责测试，它们可以**同时工作、互相交流、协同完成复杂任务**。
+
+### 从单助手到团队协作
+
+在深入了解 Agent Teams 之前，让我们先理解它解决的问题。
+
+**单 AI 模式的局限性**：
+
+当你用单个 Claude 实例处理复杂项目时，会遇到这些瓶颈：
+
+- **串行处理瓶颈**：AI 只能一次做一件事。比如要重构一个项目，它需要先分析认证模块，再分析数据库模块，最后分析 API 模块。这些步骤必须串行进行，即使它们之间没有依赖关系。
+
+- **上下文拥挤问题**：所有信息都在一个对话窗口里。当对话变长，早期的关键细节容易被淹没，AI 可能忘记之前讨论的重要决策。
+
+- **单一视角局限**：只有一个 AI 在思考，缺乏多角度的讨论和验证。当遇到复杂的设计决策时，没有"同事"可以辩论或提供不同观点。
+
+- **效率天花板**：大型重构或多模块开发需要很长时间，无法通过并行加速来提升效率。
+
+**Agent Teams 的解决方案**：
+
+Agent Teams 通过**多实例并行协作**解决了这些问题：
+
+- **真正的并行工作**：多个 AI 可以同时处理不同的任务。一个负责前端 UI，一个负责后端 API，一个负责数据库设计，三者互不干扰。
+
+- **独立的上下文空间**：每个团队成员都有自己完整的 200K token 上下文窗口，不会因为对话过长而"忘记"重要信息。
+
+- **团队协作能力**：成员之间可以直接通信，讨论设计决策，互相验证代码质量，就像真正的开发团队一样。
+
+- **效率大幅提升**：根据 Anthropic 内部测试，大型项目重构的效率可以提升约 50%。
+
+---
+
+## Agent Teams vs Subagent
+
+在深入 Agent Teams 的架构之前，有必要先澄清一个常见的混淆：**Agent Teams 和 Subagent 有什么区别**？
+
+这两种功能都涉及"多个 AI 协同工作"，但它们的协作模式完全不同，适用于不同的场景。
+
+### 核心区别对比
+
+| 对比维度 | Subagent（子代理） | Agent Teams（团队代理） |
+|---------|-------------------|----------------------|
+| **拓扑结构** | 星型拓扑——所有子代理向主代理汇报 | 网状拓扑——成员可以互相通信 |
+| **通信方式** | 单向——子代理只能向主代理报告结果 | 双向——成员之间可以直接交流 |
+| **上下文管理** | 子代理与主代理共享上下文 | 每个成员拥有完全独立的上下文 |
+| **并行能力** | 有限的并行或串行执行 | 真正的并行开发 |
+| **任务协调** | 由主代理统一派发和协调 | 成员可以自主认领任务 |
+| **成本** | 较低（共享上下文） | 较高（每个成员独立上下文） |
+
+### 形象比喻
+
+**Subagent 就像**：一个经理给几个助理分配任务。每个助理领到任务后去完成，完成后向经理汇报。助理之间不直接交流，所有信息都通过经理中转。
+
+```
+你 → 主代理 → 子代理 A："去分析这个文件"
+你 → 主代理 → 子代理 B："去搜索那个函数"
+         ↓
+    子代理 A 完成 → 向主代理汇报结果
+    子代理 B 完成 → 向主代理汇报结果
+         ↓
+    主代理综合结果 → 向你汇报
+```
+
+**Agent Teams 就像**：一个项目经理带领一个真正的开发团队。团队成员之间可以直接沟通、讨论、协作，不是所有事情都要通过项目经理中转。
+
+```
+你 → Team Lead："做用户认证功能"
+         ↓
+    Team Lead 创建团队，分配任务
+         ↓
+    Teammate A："@Teammate B，API 接口设计好了吗？"
+    Teammate B："设计好了，格式是这样的..."
+    Teammate C："我看了接口，有个问题需要讨论一下..."
+         ↓
+    团队成员协作完成 → Team Lead 综合结果 → 向你汇报
+```
+
+### 什么时候用哪个
+
+**使用 Subagent 的场景**：
+
+- 快速、明确的单一任务（如"搜索这个错误代码"）
+- 任务之间没有太多依赖关系
+- 成本敏感，不需要复杂的协作
+
+**使用 Agent Teams 的场景**：
+
+- 复杂的系统重构，涉及多个模块
+- 需要多角度分析和讨论（如安全专家和性能专家辩论方案）
+- 需要真正的并行开发（前端、后端、测试同时进行）
+- 任务之间需要频繁协调和信息共享
+
+### 简单总结
+
+- **Subagent**：任务分发工具，把大任务拆成小任务，派发给不同的"工人"完成
+- **Agent Teams**：真正的协作团队，成员之间可以像真实团队一样交流、讨论、协同工作
+
+---
+
+## 核心架构
+
+Agent Teams 不是一个简单的"多开"功能，而是一套完整的**多代理协作系统**。要理解它，我们需要了解其核心组件和它们之间的协作方式。
+
+### 团队组成
+
+一个 Agent Team 由四种核心组件构成，它们各司其职，共同完成复杂任务。
+
+**Team Lead（团队负责人）**
+
+Team Lead 是整个团队的"大脑"和"协调者"，它不直接执行具体的编码任务，而是负责：
+
+- **需求分析与任务拆解**：将用户的复杂需求分解成多个可并行执行的子任务
+- **团队创建与管理**：根据任务特点决定需要多少成员、每个成员的职责
+- **任务分配与调度**：将任务分配给合适的成员，管理任务的依赖关系
+- **结果综合与质量把控**：收集所有成员的工作成果，进行整合和最终审查
+
+**Teammates（团队成员）**
+
+Teammates 是真正干活的"开发者"，每个 Teammate 都是一个独立的 Claude 实例：
+
+- **独立的上下文窗口**：每个成员拥有完整的 200K token 上下文，与 Team Lead 和其他成员完全隔离
+- **完整的工具权限**：可以使用 Read、Write、Edit、Bash 等所有工具
+- **自主任务认领**：可以从共享任务板上自主选择和认领任务
+- **直接通信能力**：可以与其他成员直接交流，不一定要通过 Team Lead
+
+**TaskList（共享任务板）**
+
+TaskList 是团队的"项目管理工具"，类似于 Jira 或 Trello：
+
+- **任务状态管理**：每个任务有明确的状态——pending（待处理）、in_progress（进行中）、completed（已完成）
+- **依赖关系管理**：任务可以定义依赖关系，只有依赖的任务完成后，被依赖的任务才能开始
+- **自动解锁机制**：当一个任务完成时，系统会自动检查并解锁那些等待它的任务
+- **文件锁机制**：当成员认领并开始处理任务时，会在任务目录中创建锁文件，防止多个成员同时修改同一文件
+
+**Messaging System（消息系统）**
+
+消息系统是团队成员之间"聊天工具"：
+
+- **点对点通信**：成员 A 可以直接向成员 B 发送消息
+- **群发广播**：可以同时向所有成员发送公告
+- **基于文件系统**：消息以 JSON 文件形式存储在 `~/.claude/teams/{team-name}/inboxes/` 目录下
+- **无需网络**：完全基于本地文件系统，不需要网络连接或端口监听
+
+### 协作流程
+
+一个典型的 Agent Teams 工作流程是这样的：
+
+```
+用户提出复杂需求
+       ↓
+Team Lead 分析需求，拆解任务
+       ↓
+创建团队成员，初始化 TaskList
+       ↓
+       ├─→ Teammate A 认领任务 1 ─┐
+       ├─→ Teammate B 认领任务 2 ─┼→ 并行执行
+       ├─→ Teammate C 认领任务 3 ─┤
+       │                           ↓
+       └────────────────────────── 成员间通过消息系统通信协调
+                                   ↓
+                          所有任务完成后，Team Lead 综合结果
+                                   ↓
+                          向用户输出最终成果
+```
+
+### 文件系统布局
+
+Agent Teams 在你的本地文件系统中创建专门的目录来管理团队状态：
+
+```
+~/.claude/
+├── teams/
+│   └── {team-name}/
+│       ├── config.json          # 团队配置（成员列表、模型选择等）
+│       └── inboxes/
+│           ├── team-lead.json   # Team Lead 的收件箱
+│           ├── teammate-1.json  # 成员 1 的收件箱
+│           └── teammate-2.json  # 成员 2 的收件箱
+└── tasks/
+    └── {team-name}/
+        ├── task-1.json          # 任务 1 的详细信息
+        ├── task-2.json          # 任务 2 的详细信息
+        └── current_tasks/
+            └── parse_if_statement.txt  # 任务执行时的锁文件
+```
+
+这种设计的好处是**完全透明**——你可以随时查看团队的运行状态、任务进展、成员之间的通信记录。
+
+---
+
+## 快速开始
+
+### 开启实验性功能
+
+Agent Teams 目前是一个**实验性功能**，默认是关闭的。要使用它，需要先开启。
+
+**最简单的方法：让 Claude Code 帮你开启**
+
+直接在 Claude Code 中输入：
+
+```
+帮我在 settings.json 中开启 Agent Teams 功能
+```
+
+或者：
+
+```
+开启实验性功能 agentTeams
+```
+
+Claude Code 会自动修改 `~/.claude/settings.json` 文件，添加以下配置：
+
+```json
+{
+  "experimental": {
+    "agentTeams": true
+  }
+}
+```
+
+**重启 Claude Code**
+
+配置完成后，**完全退出并重启 Claude Code**，功能就会生效。
+
+**手动配置（如果自动方法不工作）**：
+
+你可以手动编辑 `~/.claude/settings.json` 文件，添加或修改：
+
+```json
+{
+  "experimental": {
+    "agentTeams": true
+  }
+}
+```
+
+**验证是否开启成功**
+
+重启 Claude Code 后，你可以尝试这样的对话来验证：
+
+```
+你：你可以帮我创建一个 Agent Team 吗？
+
+Claude：可以！我可以帮你创建一个 Agent Team 来协作完成任务...
+```
+
+如果 Claude 能够理解并响应创建团队的需求，说明功能已经成功开启。
+
+### 可视化模式配置（可选）
+
+如果你想实时看到团队成员的工作状态，可以配置**分屏显示模式**。
+
+**让 Claude Code 帮你配置**：
+
+直接在 Claude Code 中输入：
+
+```
+帮我在 settings.json 中开启 Agent Teams 的分屏显示模式，使用 tmux
+```
+
+或者：
+
+```
+配置 agent-teams 使用 split-panes 模式
+```
+
+**安装 tmux（如果没有）**：
+
+如果你还没有安装 tmux，可以让 Claude Code 帮你安装：
+
+```
+帮我安装 tmux
+```
+
+Claude Code 会根据你的操作系统（macOS 或 Linux）自动执行相应的安装命令。
+
+**配置后的效果**：
+
+配置完成后，团队成员会在 tmux 的不同分屏中工作，你可以同时看到所有成员的输出，就像有一个"监控墙"一样。
+
+```
+┌─────────────────┬─────────────────┬─────────────────┐
+│  Teammate 1     │  Teammate 2     │  Teammate 3     │
+│  正在分析代码... │  正在实现 API... │  正在编写测试... │
+│                 │                 │                 │
+└─────────────────┴─────────────────┴─────────────────┘
+```
+
+**手动配置（如果自动方法不工作）**：
+
+你可以手动编辑 `~/.claude/settings.json` 文件：
+
+```json
+{
+  "experimental": {
+    "agentTeams": true
+  },
+  "agent-teams": {
+    "displayMode": "split-panes",
+    "terminalMultiplexer": "tmux"
+  }
+}
+```
+
+---
+
+### 实战：用 Agent Teams 开发一个宝可梦风格的 RPG 游戏
+
+让我们通过一个完整的项目，体验 Agent Teams 的强大功能。这个例子会展示多个 AI 团队成员如何协作，从零开始开发一个有战斗系统、对话功能和探索元素的 RPG 游戏。
+
+**项目需求**：
+
+开发一个宝可梦风格的网页 RPG 游戏，包含以下功能：
+
+- **角色系统**：玩家可以创建角色，有等级、HP、攻击力、防御力等属性
+- **战斗系统**：回合制战斗，有攻击、技能、道具、逃跑等选项
+- **怪物系统**：多种野怪，有不同的属性和技能
+- **对话系统**：NPC 对话，支线任务
+- **地图探索**：简单的 2D 地图，可以在不同场景之间移动
+- **存档系统**：保存游戏进度（角色等级、位置、完成任务等）
+- **音效和动画**：攻击、受伤、升级的视觉效果和音效
+
+**在 Claude Code 中输入**：
+
+```
+我想开发一个宝可梦风格的网页 RPG 游戏。
+
+创建一个团队来协作开发：
+
+团队成员分工：
+- Teammate A（游戏架构师）：设计整体架构，定义游戏状态机，规划数据结构
+- Teammate B（战斗系统）：实现回合制战斗逻辑、技能系统、伤害计算
+- Teammate C（对话系统）：实现 NPC 对话、任务系统、剧情脚本
+- Teammate D（地图渲染）：使用 Canvas 实现 2D 地图渲染、角色移动、场景切换
+- Teammate E（UI 音效）：设计游戏界面、战斗 UI、音效播放
+
+技术要求：
+- 使用 React + TypeScript + Vite
+- 使用 Tailwind CSS 做样式
+- 使用 Framer Motion 做动画
+- 使用 Zustand 做状态管理
+- 回合制战斗系统
+- 存档使用 localStorage
+- 音效使用 Web Audio API
+
+每个成员使用 Sonnet 模型，Team Lead 使用 Opus。
+
+请先让架构师设计整体方案，定义好数据结构后，其他成员再并行开发。
+```
+
+**Claude 会如何执行**：
+
+**第一阶段：架构设计**
+
+Team Lead 会先让 Teammate A（游戏架构师）进行整体设计：
+
+```
+Teammate A 正在设计游戏架构...
+
+技术栈：React 18 + TypeScript + Vite + Tailwind CSS + Framer Motion + Zustand
+
+项目初始化：
+npm create vite@latest pokemon-rpg -- --template react-ts
+npm install zustand framer-motion
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+
+文件结构：
+src/
+├── App.tsx                 # 主应用组件
+├── main.tsx                # 入口文件
+├── types/
+│   ├── player.ts           # 玩家类型定义
+│   ├── monster.ts          # 怪物类型定义
+│   ├── skill.ts            # 技能类型定义
+│   └── game.ts             # 游戏状态类型
+├── stores/
+│   └── gameStore.ts        # Zustand 状态管理
+├── components/
+│   ├── map/                # 地图相关组件
+│   │   ├── MapCanvas.tsx   # 地图 Canvas
+│   │   ├── PlayerSprite.tsx # 玩家精灵
+│   │   └── NPCSprite.tsx   # NPC 精灵
+│   ├── battle/             # 战斗相关组件
+│   │   ├── BattleScreen.tsx    # 战斗界面
+│   │   ├── BattleMenu.tsx      # 战斗菜单
+│   │   ├── HPBar.tsx           # 血条组件
+│   │   └── BattleLog.tsx       # 战斗日志
+│   ├── dialog/             # 对话相关组件
+│   │   ├── DialogBox.tsx   # 对话框
+│   │   └── Choices.tsx     # 选项组件
+│   └── ui/                 # 通用 UI 组件
+│       ├── Button.tsx
+│       ├── ProgressBar.tsx
+│       └── StatCard.tsx
+├── systems/
+│   ├── BattleSystem.ts     # 战斗系统逻辑
+│   ├── DialogSystem.ts     # 对话系统逻辑
+│   ├── QuestSystem.ts      # 任务系统逻辑
+│   └── MapSystem.ts        # 地图系统逻辑
+├── hooks/
+│   ├── useBattle.ts        # 战斗 Hook
+│   ├── useDialog.ts        # 对话 Hook
+│   └── useAudio.ts         # 音频 Hook
+├── data/
+│   ├── monsters.ts         # 怪物数据
+│   ├── skills.ts           # 技能数据
+│   ├── dialogues.ts        # 对话脚本
+│   └── maps.ts             # 地图数据
+└── utils/
+    ├── audio.ts            # 音频工具
+    └── storage.ts          # 存档工具
+
+核心数据结构设计：
+
+// types/player.ts - 玩家类型
+interface Player {
+  id: string;
+  name: string;
+  level: number;
+  exp: number;
+  maxExp: number;
+  hp: number;
+  maxHp: number;
+  attack: number;
+  defense: number;
+  skills: Skill[];
+  position: { x: number; y: number };
+  direction: 'UP' | 'DOWN' | 'LEFT' | 'RIGHT';
+  gold: number;
+  items: string[];
+}
+
+// types/skill.ts - 技能类型
+  id: string,
+  name: string,
+  type: 'attack' | 'heal' | 'buff' | 'special',
+  power: number,
+  accuracy: number,
+  pp: number,
+  maxPp: number,
+  effect?: string
+}
+
+// 游戏状态
+{
+  screen: 'map' | 'battle' | 'dialog' | 'menu',
+  player: Player,
+  currentMap: string,
+  position: {x: number, y: number},
+  inBattle: boolean,
+  dialogQueue: Array<Dialog>,
+  gameData: {
+    completedQuests: string[],
+    items: string[],
+    visitedMaps: string[]
+  }
+}
+
+战斗系统设计：
+- 回合制，玩家先行动
+- 每回合可以选择：攻击、技能、道具、逃跑
+- 技能有 PP 限制，用完需要回复
+- 伤害公式：(攻击方攻击力 / 防御方防御力) × 技能威力 × 随机因子(0.85~1.0)
+
+对话系统设计：
+- 打字机效果显示文字
+- 支持选项分支
+- 支持条件触发（完成任务后）
+- NPC 有朝向，玩家靠近自动触发
+```
+
+**第二阶段：并行开发**
+
+架构确定后，Team Lead 会创建任务列表，其他成员开始并行工作：
+
+```
+任务列表：
+├── [Teammate B] 实现战斗系统核心逻辑 (进行中...)
+├── [Teammate C] 实现对话和任务系统 (进行中...)
+├── [Teammate D] 实现 2D 地图渲染 (进行中...)
+└── [Teammate E] 设计 UI 和音效 (进行中...)
+```
+
+<details>
+<summary>📁 Teammate B：战斗系统核心代码</summary>
+
+```javascript
+// battle.js - 战斗系统
+class BattleSystem {
+  constructor(player, monster) {
+    this.player = player;
+    this.monster = monster;
+    this.turn = 'player';
+    this.log = [];
+    this.state = 'active'; // active, victory, defeat, flee
+  }
+
+  // 玩家攻击
+  playerAttack(skill) {
+    if (this.turn !== 'player') return;
+
+    const damage = this.calculateDamage(this.player, this.monster, skill);
+    this.monster.hp = Math.max(0, this.monster.hp - damage);
+
+    this.log.push(`${this.player.name} 使用了 ${skill.name}！`);
+    this.log.push(`造成了 ${damage} 点伤害！`);
+
+    // 技能效果
+    if (skill.effect) {
+      this.applyEffect(this.player, this.monster, skill.effect);
+    }
+
+    // 检查战斗结束
+    if (this.monster.hp <= 0) {
+      this.state = 'victory';
+      this.log.push(`${this.monster.name} 倒下了！`);
+      this.giveExp();
+    } else {
+      this.turn = 'monster';
+      setTimeout(() => this.monsterAttack(), 1000);
+    }
+  }
+
+  // 怪物攻击
+  monsterAttack() {
+    if (this.state !== 'active') return;
+
+    // 随机选择技能
+    const skill = this.monster.skills[Math.floor(Math.random() * this.monster.skills.length)];
+    const damage = this.calculateDamage(this.monster, this.player, skill);
+
+    this.player.hp = Math.max(0, this.player.hp - damage);
+
+    this.log.push(`${this.monster.name} 使用了 ${skill.name}！`);
+    this.log.push(`造成了 ${damage} 点伤害！`);
+
+    if (this.player.hp <= 0) {
+      this.state = 'defeat';
+      this.log.push(`${this.player.name} 倒下了...`);
+    } else {
+      this.turn = 'player';
+    }
+  }
+
+  // 伤害计算
+  calculateDamage(attacker, defender, skill) {
+    const levelFactor = (2 * attacker.level / 5 + 2);
+    const attackDefense = attacker.attack / defender.defense;
+    const baseDamage = levelFactor * attackDefense * skill.power + 2;
+    const randomFactor = 0.85 + Math.random() * 0.15;
+
+    // 属性克制加成（简化版）
+    let typeBonus = 1;
+    // if (skill.type > defender.type) typeBonus = 1.5;
+
+    return Math.floor(baseDamage * randomFactor * typeBonus);
+  }
+
+  // 应用技能效果
+  applyEffect(user, target, effect) {
+    switch(effect) {
+      case 'burn':
+        this.log.push(`${target.name} 被烧伤了！`);
+        break;
+      case 'heal':
+        const healAmount = Math.floor(user.maxHp * 0.3);
+        user.hp = Math.min(user.maxHp, user.hp + healAmount);
+        this.log.push(`${user.name} 恢复了 ${healAmount} 点 HP！`);
+        break;
+      case 'buff':
+        user.attack = Math.floor(user.attack * 1.2);
+        this.log.push(`${user.name} 的攻击力上升了！`);
+        break;
+    }
+  }
+
+  // 获得经验
+  giveExp() {
+    const baseExp = this.monster.level * 50;
+    const expGain = Math.floor(baseExp * (1 + this.player.level / 10));
+
+    this.player.exp += expGain;
+    this.log.push(`${this.player.name} 获得了 ${expGain} 点经验！`);
+
+    // 升级检查
+    while (this.player.exp >= this.player.maxExp) {
+      this.levelUp();
+    }
+  }
+
+  // 升级
+  levelUp() {
+    this.player.level++;
+    this.player.exp -= this.player.maxExp;
+    this.player.maxExp = Math.floor(this.player.maxExp * 1.5);
+
+    // 属性提升
+    const hpGain = 10 + Math.floor(Math.random() * 5);
+    const atkGain = 3 + Math.floor(Math.random() * 2);
+    const defGain = 2 + Math.floor(Math.random() * 2);
+
+    this.player.maxHp += hpGain;
+    this.player.hp = this.player.maxHp;
+    this.player.attack += atkGain;
+    this.player.defense += defGain;
+
+    this.log.push(`${this.player.name} 升到了 ${this.player.level} 级！`);
+    this.log.push(`HP +${hpGain}, 攻击 +${atkGain}, 防御 +${defGain}`);
+  }
+
+  // 逃跑
+  flee() {
+    if (Math.random() < 0.7) {
+      this.state = 'flee';
+      this.log.push('成功逃跑了！');
+      return true;
+    } else {
+      this.log.push('逃跑失败！');
+      this.turn = 'monster';
+      setTimeout(() => this.monsterAttack(), 1000);
+      return false;
+    }
+  }
+}
+
+// monster.js - 怪物数据
+const MONSTER_DATA = [
+  {
+    id: 'slime',
+    name: '史莱姆',
+    baseHp: 30,
+    baseAtk: 8,
+    baseDef: 5,
+    skills: [
+      {id: 'tackle', name: '撞击', type: 'attack', power: 40, accuracy: 100, pp: 35}
+    ],
+    expGain: 20
+  },
+  {
+    id: 'goblin',
+    name: '哥布林',
+    baseHp: 45,
+    baseAtk: 12,
+    baseDef: 8,
+    skills: [
+      {id: 'tackle', name: '撞击', type: 'attack', power: 40, accuracy: 100, pp: 35},
+      {id: 'scratch', name: '抓击', type: 'attack', power: 55, accuracy: 100, pp: 25}
+    ],
+    expGain: 35
+  },
+  {
+    id: 'dragon',
+    name: '幼龙',
+    baseHp: 80,
+    baseAtk: 20,
+    baseDef: 15,
+    skills: [
+      {id: 'scratch', name: '抓击', type: 'attack', power: 55, accuracy: 100, pp: 25},
+      {id: 'ember', name: '火花', type: 'attack', power: 70, accuracy: 90, pp: 15},
+      {id: 'growl', name: '吼叫', type: 'buff', power: 0, accuracy: 100, pp: 20}
+    ],
+    expGain: 80
+  }
+];
+```
+
+</details>
+
+<details>
+<summary>📁 Teammate C：对话和任务系统代码</summary>
+
+```javascript
+// dialog.js - 对话系统
+class DialogSystem {
+  constructor() {
+    this.dialogQueue = [];
+    this.currentDialog = null;
+    this.isShowing = false;
+    this.onComplete = null;
+  }
+
+  // 显示对话
+  showDialog(dialog, onComplete) {
+    this.dialogQueue = Array.isArray(dialog) ? dialog : [dialog];
+    this.onComplete = onComplete;
+    this.isShowing = true;
+    this.showNext();
+  }
+
+  // 显示下一条对话
+  showNext() {
+    if (this.dialogQueue.length === 0) {
+      this.isShowing = false;
+      if (this.onComplete) this.onComplete();
+      return;
+    }
+
+    this.currentDialog = this.dialogQueue.shift();
+
+    // 处理特殊类型的对话
+    if (typeof this.currentDialog === 'function') {
+      this.currentDialog();
+      this.showNext();
+      return;
+    }
+
+    this.renderDialog();
+  }
+
+  // 渲染对话框
+  renderDialog() {
+    const dialogBox = document.getElementById('dialogBox');
+    const speakerEl = document.getElementById('dialogSpeaker');
+    const textEl = document.getElementById('dialogText');
+
+    if (this.currentDialog.speaker) {
+      speakerEl.textContent = this.currentDialog.speaker;
+      speakerEl.style.display = 'block';
+    } else {
+      speakerEl.style.display = 'none';
+    }
+
+    // 打字机效果
+    textEl.textContent = '';
+    let i = 0;
+    const text = this.currentDialog.text;
+    const speed = this.currentDialog.speed || 30;
+
+    const typeWriter = setInterval(() => {
+      if (i < text.length) {
+        textEl.textContent += text.charAt(i);
+        i++;
+      } else {
+        clearInterval(typeWriter);
+      }
+    }, speed);
+
+    // 显示选项（如果有）
+    this.renderChoices();
+  }
+
+  // 渲染选项
+  renderChoices() {
+    if (!this.currentDialog.choices) return;
+
+    const choicesEl = document.getElementById('dialogChoices');
+    choicesEl.innerHTML = '';
+    choicesEl.style.display = 'block';
+
+    this.currentDialog.choices.forEach(choice => {
+      const btn = document.createElement('button');
+      btn.textContent = choice.text;
+      btn.onclick = () => {
+        if (choice.condition === undefined || choice.condition()) {
+          this.dialogQueue = [];
+          this.showDialog(choice.dialog, this.onComplete);
+        }
+      };
+      choicesEl.appendChild(btn);
+    });
+  }
+
+  // 下一条
+  next() {
+    if (this.currentDialog && this.currentDialog.choices) return; // 有选项时需要选择
+    this.showNext();
+  }
+}
+
+// 任务系统
+class QuestSystem {
+  constructor() {
+    this.quests = {};
+    this.activeQuests = [];
+    this.completedQuests = [];
+  }
+
+  // 接受任务
+  acceptQuest(questId) {
+    if (this.completedQuests.includes(questId)) return false;
+    if (this.activeQuests.includes(questId)) return false;
+
+    this.activeQuests.push(questId);
+    return true;
+  }
+
+  // 更新任务进度
+  updateProgress(type, target) {
+    this.activeQuests.forEach(questId => {
+      const quest = this.quests[questId];
+      if (!quest) return;
+
+      quest.objectives.forEach(obj => {
+        if (obj.type === type && obj.target === target && !obj.completed) {
+          obj.current = (obj.current || 0) + 1;
+          if (obj.current >= obj.required) {
+            obj.completed = true;
+          }
+        }
+      });
+
+      this.checkCompletion(questId);
+    });
+  }
+
+  // 检查任务完成
+  checkCompletion(questId) {
+    const quest = this.quests[questId];
+    if (!quest) return;
+
+    const allComplete = quest.objectives.every(obj => obj.completed);
+    if (allComplete) {
+      this.completeQuest(questId);
+    }
+  }
+
+  // 完成任务
+  completeQuest(questId) {
+    const index = this.activeQuests.indexOf(questId);
+    if (index > -1) {
+      this.activeQuests.splice(index, 1);
+      this.completedQuests.push(questId);
+
+      // 给予奖励
+      const quest = this.quests[questId];
+      this.giveRewards(quest.rewards);
+    }
+  }
+
+  // 给予奖励
+  giveRewards(rewards) {
+    if (rewards.exp) player.gainExp(rewards.exp);
+    if (rewards.gold) player.gold += rewards.gold;
+    if (rewards.items) rewards.items.forEach(item => player.addItem(item));
+  }
+}
+
+// dialogues.js - 对话脚本示例
+const DIALOGUES = {
+  villageChief: {
+    firstMeeting: [
+      {speaker: '村长', text: '哦，冒险者啊...你终于来了。'},
+      {speaker: '村长', text: '我们村子附近最近出现了很多野生的怪物，村民们都很害怕。'},
+      {speaker: '村长', text: '如果你能帮忙驱赶那些怪物，我将不胜感激！'},
+      {
+        choices: [
+          {text: '好的，我接受这个任务', dialog: () => {
+            quests.acceptQuest('defeatMonsters');
+            return [
+              {speaker: '村长', text: '太好了！请击败北边的 3 只史莱姆。'},
+              {speaker: '系统', text: '任务【驱赶史莱姆】已接受！'}
+            ];
+          }},
+          {text: '我现在有点忙', dialog: [
+            {speaker: '村长', text: '好吧，等你准备好了再来找我。'}
+          ]}
+        ]
+      }
+    ],
+    afterQuest: [
+      {speaker: '村长', text: '你真的做到了！太感谢你了！'},
+      {speaker: '系统', text: '任务【驱赶史莱姆】完成！获得 100 经验值！'},
+      {speaker: '村长', text: '请收下这个，这是我的一点心意。'}
+    ]
+  },
+
+  shopkeeper: [
+    {speaker: '店主', text: '欢迎光临！要买点什么吗？'},
+    {
+      choices: [
+        {text: '查看商品', dialog: () => {
+          game.openShop();
+          return [{speaker: '店主', text: '看中什么就拿去吧！'}];
+        }},
+        {text: '离开', dialog: [{speaker: '店主', text: '下次再来！'}]}
+      ]
+    }
+  ]
+};
+```
+
+</details>
+
+<details>
+<summary>📁 Teammate D：2D 地图渲染系统代码</summary>
+
+```javascript
+// map.js - 地图渲染系统
+class MapRenderer {
+  constructor(canvas) {
+    this.canvas = canvas;
+    this.ctx = canvas.getContext('2d');
+    this.tileSize = 32;
+    this.currentMap = null;
+    this.player = null;
+    this.npcs = [];
+    this.camera = {x: 0, y: 0};
+  }
+
+  // 加载地图
+  loadMap(mapData) {
+    this.currentMap = mapData;
+    this.npcs = mapData.npcs || [];
+    this.updateCamera();
+  }
+
+  // 渲染地图
+  render() {
+    if (!this.currentMap) return;
+
+    // 清空画布
+    this.ctx.fillStyle = '#000';
+    this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
+
+    // 保存上下文
+    this.ctx.save();
+
+    // 应用摄像机偏移
+    this.ctx.translate(-this.camera.x, -this.camera.y);
+
+    // 渲染地图层
+    this.renderLayers();
+
+    // 渲染 NPC
+    this.renderNPCs();
+
+    // 渲染玩家
+    this.renderPlayer();
+
+    // 恢复上下文
+    this.ctx.restore();
+  }
+
+  // 渲染地图层
+  renderLayers() {
+    const map = this.currentMap;
+
+    for (let layer = 0; layer < map.layers.length; layer++) {
+      const data = map.layers[layer].data;
+
+      for (let y = 0; y < map.height; y++) {
+        for (let x = 0; x < map.width; x++) {
+          const tileId = data[y * map.width + x];
+          if (tileId === 0) continue;
+
+          const tileX = x * this.tileSize;
+          const tileY = y * this.tileSize;
+
+          this.renderTile(tileX, tileY, tileId);
+        }
+      }
+    }
+  }
+
+  // 渲染单个地块
+  renderTile(x, y, tileId) {
+    // 根据地块 ID 绘制不同的地块
+    const tileType = this.getTileType(tileId);
+
+    switch(tileType) {
+      case 'grass':
+        this.ctx.fillStyle = '#4a8f4a';
+        this.ctx.fillRect(x, y, this.tileSize, this.tileSize);
+        // 草地纹理
+        this.ctx.fillStyle = '#3d7f3d';
+        for (let i = 0; i < 3; i++) {
+          const px = x + Math.random() * this.tileSize;
+          const py = y + Math.random() * this.tileSize;
+          this.ctx.fillRect(px, py, 2, 2);
+        }
+        break;
+
+      case 'water':
+        this.ctx.fillStyle = '#4a90d9';
+        this.ctx.fillRect(x, y, this.tileSize, this.tileSize);
+        // 水波纹效果
+        const wave = Math.sin(Date.now() / 500 + x / 20) * 2;
+        this.ctx.fillStyle = '#5aa0e9';
+        this.ctx.fillRect(x, y + 10 + wave, this.tileSize, 2);
+        break;
+
+      case 'wall':
+        this.ctx.fillStyle = '#8b7355';
+        this.ctx.fillRect(x, y, this.tileSize, this.tileSize);
+        this.ctx.fillStyle = '#7a6248';
+        this.ctx.fillRect(x + 2, y + 2, this.tileSize - 4, this.tileSize - 4);
+        break;
+
+      case 'path':
+        this.ctx.fillStyle = '#c4a77d';
+        this.ctx.fillRect(x, y, this.tileSize, this.tileSize);
+        break;
+
+      case 'house':
+        this.ctx.fillStyle = '#a0522d';
+        this.ctx.fillRect(x, y, this.tileSize, this.tileSize);
+        // 屋顶
+        this.ctx.fillStyle = '#8b4513';
+        this.ctx.beginPath();
+        this.ctx.moveTo(x, y);
+        this.ctx.lineTo(x + this.tileSize / 2, y - 10);
+        this.ctx.lineTo(x + this.tileSize, y);
+        this.ctx.fill();
+        break;
+    }
+  }
+
+  // 获取地块类型
+  getTileType(tileId) {
+    const types = {
+      1: 'grass', 2: 'water', 3: 'wall', 4: 'path', 5: 'house'
+    };
+    return types[tileId] || 'grass';
+  }
+
+  // 渲染 NPC
+  renderNPCs() {
+    this.npcs.forEach(npc => {
+      const x = npc.x * this.tileSize;
+      const y = npc.y * this.tileSize;
+
+      // 绘制 NPC
+      this.ctx.fillStyle = npc.color || '#ff6b6b';
+      this.ctx.beginPath();
+      this.ctx.arc(
+        x + this.tileSize / 2,
+        y + this.tileSize / 2,
+        this.tileSize / 3,
+        0,
+        Math.PI * 2
+      );
+      this.ctx.fill();
+
+      // 绘制名字
+      this.ctx.fillStyle = '#fff';
+      this.ctx.font = '10px Arial';
+      this.ctx.textAlign = 'center';
+      this.ctx.fillText(npc.name, x + this.tileSize / 2, y - 5);
+    });
+  }
+
+  // 渲染玩家
+  renderPlayer() {
+    if (!this.player) return;
+
+    const x = this.player.x * this.tileSize;
+    const y = this.player.y * this.tileSize;
+
+    // 玩家身体
+    this.ctx.fillStyle = '#4ecdc4';
+    this.ctx.beginPath();
+    this.ctx.arc(
+      x + this.tileSize / 2,
+      y + this.tileSize / 2,
+      this.tileSize / 3,
+      0,
+      Math.PI * 2
+    );
+    this.ctx.fill();
+
+    // 玩家朝向指示
+    const directions = {UP: [0, -8], DOWN: [0, 8], LEFT: [-8, 0], RIGHT: [8, 0]};
+    const [dx, dy] = directions[this.player.direction] || [0, 0];
+
+    this.ctx.fillStyle = '#2d3436';
+    this.ctx.beginPath();
+    this.ctx.arc(
+      x + this.tileSize / 2 + dx,
+      y + this.tileSize / 2 + dy,
+      4,
+      0,
+      Math.PI * 2
+    );
+    this.ctx.fill();
+  }
+
+  // 更新摄像机位置
+  updateCamera() {
+    if (!this.player) return;
+
+    // 摄像机跟随玩家，保持在画面中心
+    const targetX = this.player.x * this.tileSize - this.canvas.width / 2;
+    const targetY = this.player.y * this.tileSize - this.canvas.height / 2;
+
+    // 平滑移动
+    this.camera.x += (targetX - this.camera.x) * 0.1;
+    this.camera.y += (targetY - this.camera.y) * 0.1;
+
+    // 限制摄像机不要超出地图边界
+    const maxX = this.currentMap.width * this.tileSize - this.canvas.width;
+    const maxY = this.currentMap.height * this.tileSize - this.canvas.height;
+    this.camera.x = Math.max(0, Math.min(this.camera.x, maxX));
+    this.camera.y = Math.max(0, Math.min(this.camera.y, maxY));
+  }
+
+  // 检查碰撞
+  checkCollision(x, y) {
+    // 检查地图边界
+    if (x < 0 || x >= this.currentMap.width || y < 0 || y >= this.currentMap.height) {
+      return true;
+    }
+
+    // 检查地块碰撞
+    const tileId = this.currentMap.layers[0].data[y * this.currentMap.width + x];
+    const solidTiles = [3, 5]; // 墙和房子是障碍物
+
+    if (solidTiles.includes(tileId)) {
+      return true;
+    }
+
+    // 检查 NPC 碰撞
+    for (const npc of this.npcs) {
+      if (npc.x === x && npc.y === y) {
+        // 触发 NPC 对话
+        this.triggerNPC(npc);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  // 触发 NPC 对话
+  triggerNPC(npc) {
+    if (npc.dialogue) {
+      game.dialogSystem.showDialog(npc.dialogue);
+    }
+  }
+}
+
+// 示例地图数据
+const VILLAGE_MAP = {
+  name: '新手村',
+  width: 20,
+  height: 15,
+  layers: [
+    {
+      name: 'ground',
+      data: [
+        // 地图数据（简化展示）
+        1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
+        1,4,4,4,1,1,5,5,5,1,1,4,4,4,4,1,1,1,1,1,
+        1,4,1,4,1,1,5,5,5,1,1,4,1,1,4,1,1,1,1,1,
+        1,4,4,4,1,1,1,1,1,1,1,4,4,4,4,1,2,2,1,1,
+        1,1,1,1,1,1,4,4,4,1,1,1,1,1,1,1,2,2,1,1,
+        1,4,4,4,1,1,4,4,4,1,1,1,1,1,1,1,2,2,1,1,
+        1,4,1,4,1,1,1,1,1,1,1,4,4,4,1,1,1,1,1,1,
+        1,4,4,4,1,1,1,1,1,1,1,4,1,1,4,1,1,1,1,1,
+        // ... 更多地图数据
+      ]
+    }
+  ],
+  npcs: [
+    {
+      id: 'village_chief',
+      name: '村长',
+      x: 5,
+      y: 5,
+      color: '#ffd93d',
+      dialogue: DIALOGUES.villageChief.firstMeeting,
+      direction: 'DOWN'
+    },
+    {
+      id: 'shopkeeper',
+      name: '店主',
+      x: 15,
+      y: 8,
+      color: '#6bcf7f',
+      dialogue: DIALOGUES.shopkeeper,
+      direction: 'DOWN'
+    }
+  ],
+  exits: [
+    {x: 10, y: 0, to: 'forest_map', spawnX: 5, spawnY: 14}
+  ]
+};
+```
+
+</details>
+
+<details>
+<summary>📁 Teammate E：战斗 UI 界面代码</summary>
+
+```html
+<!-- 战斗界面 HTML -->
+<div id="battleScreen" class="screen hidden">
+  <!-- 敌方区域 -->
+  <div class="enemy-area">
+    <div class="monster-sprite">
+      <canvas id="monsterSprite" width="128" height="128"></canvas>
+    </div>
+    <div class="monster-info">
+      <div class="name" id="enemyName">史莱姆</div>
+      <div class="level">Lv. <span id="enemyLevel">3</span></div>
+      <div class="hp-bar">
+        <div class="hp-fill" id="enemyHpBar" style="width: 100%"></div>
+      </div>
+      <div class="hp-text">
+        <span id="enemyHp">30</span> / <span id="enemyMaxHp">30</span>
+      </div>
+    </div>
+  </div>
+
+  <!-- 玩家区域 -->
+  <div class="player-area">
+    <div class="player-info">
+      <div class="name" id="playerName">勇者</div>
+      <div class="level">Lv. <span id="playerLevel">5</span></div>
+      <div class="hp-bar">
+        <div class="hp-fill" id="playerHpBar" style="width: 80%"></div>
+      </div>
+      <div class="hp-text">
+        <span id="playerHp">80</span> / <span id="playerMaxHp">100</span>
+      </div>
+      <div class="exp-bar">
+        <div class="exp-fill" id="expBar" style="width: 60%"></div>
+      </div>
+    </div>
+    <div class="player-sprite">
+      <canvas id="playerSprite" width="128" height="128"></canvas>
+    </div>
+  </div>
+
+  <!-- 战斗菜单 -->
+  <div class="battle-menu" id="battleMenu">
+    <div class="menu-row">
+      <button class="menu-btn" data-action="attack">攻击</button>
+      <button class="menu-btn" data-action="skills">技能</button>
+      <button class="menu-btn" data-action="items">道具</button>
+      <button class="menu-btn" data-action="flee">逃跑</button>
+    </div>
+  </div>
+
+  <!-- 技能子菜单 -->
+  <div class="submenu hidden" id="skillsMenu">
+    <div class="submenu-title">选择技能</div>
+    <div class="submenu-list" id="skillsList"></div>
+    <button class="back-btn" onclick="hideSubmenu()">返回</button>
+  </div>
+
+  <!-- 战斗日志 -->
+  <div class="battle-log">
+    <div id="battleLog"></div>
+  </div>
+</div>
+```
+
+```css
+/* battle.css - 战斗界面样式 */
+.battle-screen {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background: linear-gradient(180deg, #87ceeb 0%, #e0f7fa 50%, #4a5568 50%, #2d3748 100%);
+  display: flex;
+  flex-direction: column;
+}
+
+.enemy-area {
+  flex: 1;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  padding: 40px;
+}
+
+.monster-sprite canvas {
+  image-rendering: pixelated;
+  filter: drop-shadow(0 4px 8px rgba(0,0,0,0.3));
+  animation: float 2s ease-in-out infinite;
+}
+
+@keyframes float {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-10px); }
+}
+
+.monster-info {
+  margin-left: 40px;
+  text-align: center;
+}
+
+.monster-info .name {
+  font-size: 24px;
+  font-weight: bold;
+  color: #2d3748;
+}
+
+.monster-info .level {
+  font-size: 14px;
+  color: #718096;
+  margin: 8px 0;
+}
+
+.hp-bar {
+  width: 200px;
+  height: 20px;
+  background: #e2e8f0;
+  border-radius: 10px;
+  overflow: hidden;
+  border: 2px solid #4a5568;
+}
+
+.hp-fill {
+  height: 100%;
+  background: linear-gradient(90deg, #48bb78, #38a169);
+  transition: width 0.3s ease;
+}
+
+.hp-text {
+  margin-top: 8px;
+  font-size: 14px;
+  color: #4a5568;
+}
+
+.player-area {
+  flex: 1;
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-end;
+  padding: 40px;
+}
+
+.player-info {
+  background: rgba(255,255,255,0.9);
+  border-radius: 12px;
+  padding: 20px;
+  border: 3px solid #4a5568;
+}
+
+.exp-bar {
+  width: 200px;
+  height: 8px;
+  background: #e2e8f0;
+  border-radius: 4px;
+  margin-top: 8px;
+}
+
+.exp-fill {
+  height: 100%;
+  background: linear-gradient(90deg, #4299e1, #3182ce);
+  border-radius: 4px;
+}
+
+.battle-menu {
+  background: rgba(255,255,255,0.95);
+  border: 3px solid #4a5568;
+  border-radius: 12px;
+  padding: 20px;
+  margin: 0 40px 40px;
+}
+
+.menu-row {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 12px;
+}
+
+.menu-btn {
+  padding: 16px 24px;
+  font-size: 18px;
+  font-weight: bold;
+  background: linear-gradient(180deg, #fff 0%, #e2e8f0 100%);
+  border: 2px solid #4a5568;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.menu-btn:hover {
+  background: linear-gradient(180deg, #4299e1 0%, #3182ce 100%);
+  color: white;
+  transform: translateY(-2px);
+  box-shadow: 0 4px 8px rgba(0,0,0,0.2);
+}
+
+.battle-log {
+  position: absolute;
+  bottom: 120px;
+  left: 40px;
+  right: 40px;
+  max-height: 100px;
+  overflow-y: auto;
+  background: rgba(0,0,0,0.7);
+  border-radius: 8px;
+  padding: 12px;
+}
+
+#battleLog {
+  color: #fff;
+  font-size: 14px;
+  line-height: 1.8;
+}
+
+.log-entry {
+  margin-bottom: 4px;
+  opacity: 0;
+  animation: fadeIn 0.3s forwards;
+}
+
+@keyframes fadeIn {
+  to { opacity: 1; }
+}
+
+/* 受击动画 */
+@keyframes shake {
+  0%, 100% { transform: translateX(0); }
+  25% { transform: translateX(-5px); }
+  75% { transform: translateX(5px); }
+}
+
+.shake {
+  animation: shake 0.3s ease-in-out;
+}
+
+/* 攻击动画 */
+@keyframes attackRight {
+  0% { transform: translateX(0); }
+  50% { transform: translateX(30px); }
+  100% { transform: translateX(0); }
+}
+
+.attack-right {
+  animation: attackRight 0.3s ease-in-out;
+}
+```
+
+</details>
+
+<details>
+<summary>📁 音频系统代码</summary>
+
+```javascript
+// audio.js - 音频系统
+class AudioManager {
+  constructor() {
+    this.audioContext = null;
+    this.sounds = {};
+    this.musicVolume = 0.3;
+    this.sfxVolume = 0.5;
+    this.currentBgm = null;
+  }
+
+  // 初始化音频上下文
+  init() {
+    if (!this.audioContext) {
+      this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
+    }
+    if (this.audioContext.state === 'suspended') {
+      this.audioContext.resume();
+    }
+  }
+
+  // 播放背景音乐
+  playBgm(bgmName) {
+    if (this.currentBgm === bgmName) return;
+
+    this.stopBgm();
+
+    // 使用振荡器生成简单的 BGM
+    this.currentBgm = bgmName;
+    this.playGeneratedBgm(bgmName);
+  }
+
+  // 生成简单的背景音乐
+  playGeneratedBgm(type) {
+    const melodies = {
+      battle: [262, 294, 330, 262, 294, 330, 349, 330],
+      village: [330, 349, 392, 349, 330, 294, 262, 294],
+      victory: [392, 440, 494, 523, 494, 440, 392, 349]
+    };
+
+    const melody = melodies[type] || melodies.village;
+    let noteIndex = 0;
+
+    const playNote = () => {
+      if (this.currentBgm !== type) return;
+
+      const osc = this.audioContext.createOscillator();
+      const gain = this.audioContext.createGain();
+
+      osc.connect(gain);
+      gain.connect(this.audioContext.destination);
+
+      osc.frequency.value = melody[noteIndex];
+      osc.type = 'triangle';
+
+      gain.gain.setValueAtTime(this.musicVolume, this.audioContext.currentTime);
+      gain.gain.exponentialRampToValueAtTime(
+        0.01,
+        this.audioContext.currentTime + 0.4
+      );
+
+      osc.start(this.audioContext.currentTime);
+      osc.stop(this.audioContext.currentTime + 0.4);
+
+      noteIndex = (noteIndex + 1) % melody.length;
+      setTimeout(playNote, 500);
+    };
+
+    playNote();
+  }
+
+  // 停止背景音乐
+  stopBgm() {
+    this.currentBgm = null;
+  }
+
+  // 播放音效
+  playSfx(sfxName) {
+    this.init();
+
+    switch(sfxName) {
+      case 'attack':
+        this.playAttackSound();
+        break;
+      case 'hit':
+        this.playHitSound();
+        break;
+      case 'victory':
+        this.playVictorySound();
+        break;
+      case 'levelup':
+        this.playLevelUpSound();
+        break;
+      case 'dialog':
+        this.playDialogSound();
+        break;
+    }
+  }
+
+  // 攻击音效
+  playAttackSound() {
+    const osc = this.audioContext.createOscillator();
+    const gain = this.audioContext.createGain();
+
+    osc.connect(gain);
+    gain.connect(this.audioContext.destination);
+
+    osc.frequency.setValueAtTime(200, this.audioContext.currentTime);
+    osc.frequency.exponentialRampToValueAtTime(
+      100,
+      this.audioContext.currentTime + 0.1
+    );
+    osc.type = 'sawtooth';
+
+    gain.gain.setValueAtTime(this.sfxVolume, this.audioContext.currentTime);
+    gain.gain.exponentialRampToValueAtTime(
+      0.01,
+      this.audioContext.currentTime + 0.1
+    );
+
+    osc.start(this.audioContext.currentTime);
+    osc.stop(this.audioContext.currentTime + 0.1);
+  }
+
+  // 受击音效
+  playHitSound() {
+    const osc = this.audioContext.createOscillator();
+    const gain = this.audioContext.createGain();
+
+    osc.connect(gain);
+    gain.connect(this.audioContext.destination);
+
+    osc.frequency.value = 100;
+    osc.type = 'square';
+
+    gain.gain.setValueAtTime(this.sfxVolume * 0.8, this.audioContext.currentTime);
+    gain.gain.exponentialRampToValueAtTime(
+      0.01,
+      this.audioContext.currentTime + 0.2
+    );
+
+    osc.start(this.audioContext.currentTime);
+    osc.stop(this.audioContext.currentTime + 0.2);
+  }
+
+  // 胜利音效
+  playVictorySound() {
+    const notes = [523, 659, 784, 1047];
+    notes.forEach((freq, i) => {
+      setTimeout(() => {
+        const osc = this.audioContext.createOscillator();
+        const gain = this.audioContext.createGain();
+
+        osc.connect(gain);
+        gain.connect(this.audioContext.destination);
+
+        osc.frequency.value = freq;
+        osc.type = 'sine';
+
+        gain.gain.setValueAtTime(this.sfxVolume, this.audioContext.currentTime);
+        gain.gain.exponentialRampToValueAtTime(
+          0.01,
+          this.audioContext.currentTime + 0.5
+        );
+
+        osc.start(this.audioContext.currentTime);
+        osc.stop(this.audioContext.currentTime + 0.5);
+      }, i * 150);
+    });
+  }
+
+  // 升级音效
+  playLevelUpSound() {
+    const notes = [392, 523, 659, 784, 1047];
+    notes.forEach((freq, i) => {
+      setTimeout(() => {
+        const osc = this.audioContext.createOscillator();
+        const gain = this.audioContext.createGain();
+
+        osc.connect(gain);
+        gain.connect(this.audioContext.destination);
+
+        osc.frequency.value = freq;
+        osc.type = 'triangle';
+
+        gain.gain.setValueAtTime(this.sfxVolume, this.audioContext.currentTime);
+        gain.gain.exponentialRampToValueAtTime(
+          0.01,
+          this.audioContext.currentTime + 0.3
+        );
+
+        osc.start(this.audioContext.currentTime);
+        osc.stop(this.audioContext.currentTime + 0.3);
+      }, i * 100);
+    });
+  }
+
+  // 对话音效
+  playDialogSound() {
+    const osc = this.audioContext.createOscillator();
+    const gain = this.audioContext.createGain();
+
+    osc.connect(gain);
+    gain.connect(this.audioContext.destination);
+
+    osc.frequency.value = 800;
+    osc.type = 'sine';
+
+    gain.gain.setValueAtTime(this.sfxVolume * 0.3, this.audioContext.currentTime);
+    gain.gain.exponentialRampToValueAtTime(
+      0.01,
+      this.audioContext.currentTime + 0.05
+    );
+
+    osc.start(this.audioContext.currentTime);
+    osc.stop(this.audioContext.currentTime + 0.05);
+  }
+}
+```
+
+</details>
+
+**成员之间的协作对话**：
+
+```
+Teammate B → Teammate C：
+"战斗系统已经完成了，当玩家获胜时会调用 giveExp() 方法升级。
+请你检查一下任务系统，确保升级后能正确保存。"
+
+Teammate C → Teammate B：
+"收到。任务系统使用 localStorage 保存游戏数据，
+包括等级、经验值、已完成任务列表等。我会添加一个自动保存机制。"
+
+Teammate D → All：
+"地图渲染系统完成了，NPC 的朝向数据已经和对话系统对接。
+当玩家面向 NPC 时会自动触发对话，请确认对话系统的触发逻辑。"
+
+Teammate C → Teammate D：
+"确认了。DialogSystem 有 showDialog() 方法可以接收对话数组，
+我会确保所有 NPC 的对话数据都是这个格式。"
+
+Teammate E → Teammate B：
+"战斗 UI 已经做好了，但是需要知道玩家和怪物的实时数据来更新血条。
+请问战斗系统有提供回调函数吗？"
+
+Teammate B → Teammate E：
+"有的。BattleSystem 有 onUpdate 回调，每回合结束时会触发。
+你可以注册这个回调来更新 UI。"
+
+Teammate E → Teammate D：
+"地图切换时需要重新定位摄像机。
+请问 MapRenderer 有 updateCamera() 方法吗？"
+
+Teammate D → Teammate E：
+"有。每次 loadMap() 后都会自动调用 updateCamera()。
+你也可以在玩家移动后手动调用它来平滑移动摄像机。"
+```
+
+**第三阶段：集成和测试**
+
+所有组件完成后，Team Lead 会负责整合：
+
+<details>
+<summary>📁 游戏主控制器代码</summary>
+
+```javascript
+// game.js - 游戏主控制器
+class Game {
+  constructor() {
+    this.state = 'map'; // map, battle, dialog, menu
+    this.canvas = document.getElementById('gameCanvas');
+    this.ctx = this.canvas.getContext('2d');
+
+    // 初始化各个系统
+    this.player = this.createPlayer();
+    this.mapRenderer = new MapRenderer(this.canvas);
+    this.battleSystem = null;
+    this.dialogSystem = new DialogSystem();
+    this.questSystem = new QuestSystem();
+    this.audioManager = new AudioManager();
+
+    // 加载地图
+    this.currentMapId = 'village';
+    this.mapRenderer.loadMap(VILLAGE_MAP);
+    this.mapRenderer.player = this.player;
+
+    // 输入处理
+    this.setupInput();
+
+    // 开始游戏循环
+    this.lastTime = 0;
+    this.gameLoop = this.gameLoop.bind(this);
+    requestAnimationFrame(this.gameLoop);
+
+    // 自动加载存档
+    this.loadGame();
+  }
+
+  // 创建玩家
+  createPlayer() {
+    return {
+      name: '勇者',
+      level: 1,
+      exp: 0,
+      maxExp: 100,
+      hp: 50,
+      maxHp: 50,
+      attack: 15,
+      defense: 10,
+      skills: [
+        {id: 'tackle', name: '撞击', type: 'attack', power: 40, accuracy: 100, pp: 35}
+      ],
+      x: 10,
+      y: 7,
+      direction: 'DOWN',
+      gold: 100,
+      items: ['potion', 'potion', 'antidote']
+    };
+  }
+
+  // 设置输入处理
+  setupInput() {
+    document.addEventListener('keydown', (e) => {
+      if (this.state === 'map') {
+        this.handleMapInput(e);
+      } else if (this.state === 'dialog') {
+        this.handleDialogInput(e);
+      } else if (this.state === 'battle') {
+        this.handleBattleInput(e);
+      }
+    });
+  }
+
+  // 地图输入处理
+  handleMapInput(e) {
+    if (this.dialogSystem.isShowing) {
+      if (e.key === ' ' || e.key === 'Enter') {
+        this.dialogSystem.next();
+      }
+      return;
+    }
+
+    let dx = 0, dy = 0;
+    switch(e.key) {
+      case 'ArrowUp': case 'w': dy = -1; this.player.direction = 'UP'; break;
+      case 'ArrowDown': case 's': dy = 1; this.player.direction = 'DOWN'; break;
+      case 'ArrowLeft': case 'a': dx = -1; this.player.direction = 'LEFT'; break;
+      case 'ArrowRight': case 'd': dx = 1; this.player.direction = 'RIGHT'; break;
+      default: return;
+    }
+
+    const newX = this.player.x + dx;
+    const newY = this.player.y + dy;
+
+    if (!this.mapRenderer.checkCollision(newX, newY)) {
+      this.player.x = newX;
+      this.player.y = newY;
+      this.mapRenderer.updateCamera();
+
+      // 检查随机战斗
+      if (Math.random() < 0.05) {
+        this.startBattle();
+      }
+
+      // 保存游戏
+      this.saveGame();
+    }
+  }
+
+  // 对话输入处理
+  handleDialogInput(e) {
+    if (e.key === ' ' || e.key === 'Enter') {
+      this.dialogSystem.next();
+      if (!this.dialogSystem.isShowing) {
+        this.state = 'map';
+      }
+    }
+  }
+
+  // 战斗输入处理
+  handleBattleInput(e) {
+    if (!this.battleSystem) return;
+    if (this.battleSystem.turn !== 'player') return;
+  }
+
+  // 开始战斗
+  startBattle(monsterData) {
+    // 随机选择怪物
+    const randomMonster = MONSTER_DATA[Math.floor(Math.random() * MONSTER_DATA.length)];
+
+    // 生成怪物实例
+    const monster = {
+      ...randomMonster,
+      level: Math.max(1, this.player.level + Math.floor(Math.random() * 3) - 1),
+      hp: randomMonster.baseHp + randomMonster.baseHp * 0.2 * this.player.level,
+      maxHp: randomMonster.baseHp + randomMonster.baseHp * 0.2 * this.player.level,
+      attack: randomMonster.baseAtk + randomMonster.baseAtk * 0.15 * this.player.level,
+      defense: randomMonster.baseDef + randomMonster.baseDef * 0.1 * this.player.level
+    };
+
+    this.battleSystem = new BattleSystem(this.player, monster);
+    this.state = 'battle';
+
+    // 播放战斗音乐
+    this.audioManager.playBgm('battle');
+
+    // 显示战斗界面
+    document.getElementById('battleScreen').classList.remove('hidden');
+    document.getElementById('mapScreen').classList.add('hidden');
+
+    // 更新战斗 UI
+    this.updateBattleUI();
+  }
+
+  // 更新战斗 UI
+  updateBattleUI() {
+    if (!this.battleSystem) return;
+
+    const player = this.battleSystem.player;
+    const monster = this.battleSystem.monster;
+
+    document.getElementById('playerName').textContent = player.name;
+    document.getElementById('playerLevel').textContent = player.level;
+    document.getElementById('playerHp').textContent = Math.floor(player.hp);
+    document.getElementById('playerMaxHp').textContent = player.maxHp;
+    document.getElementById('playerHpBar').style.width =
+      (player.hp / player.maxHp * 100) + '%';
+
+    document.getElementById('enemyName').textContent = monster.name;
+    document.getElementById('enemyLevel').textContent = monster.level;
+    document.getElementById('enemyHp').textContent = Math.floor(monster.hp);
+    document.getElementById('enemyMaxHp').textContent = Math.floor(monster.maxHp);
+    document.getElementById('enemyHpBar').style.width =
+      (monster.hp / monster.maxHp * 100) + '%';
+
+    // 更新战斗日志
+    const logEl = document.getElementById('battleLog');
+    this.battleSystem.log.forEach(log => {
+      const entry = document.createElement('div');
+      entry.className = 'log-entry';
+      entry.textContent = log;
+      logEl.appendChild(entry);
+    });
+    logEl.scrollTop = logEl.scrollHeight;
+  }
+
+  // 结束战斗
+  endBattle() {
+    this.state = 'map';
+    this.battleSystem = null;
+
+    // 隐藏战斗界面
+    document.getElementById('battleScreen').classList.add('hidden');
+    document.getElementById('mapScreen').classList.remove('hidden');
+
+    // 播放地图音乐
+    this.audioManager.playBgm('village');
+
+    // 保存游戏
+    this.saveGame();
+  }
+
+  // 保存游戏
+  saveGame() {
+    const saveData = {
+      player: this.player,
+      currentMapId: this.currentMapId,
+      completedQuests: this.questSystem.completedQuests,
+      timestamp: Date.now()
+    };
+
+    localStorage.setItem('rpgSave', JSON.stringify(saveData));
+  }
+
+  // 加载游戏
+  loadGame() {
+    const saveData = localStorage.getItem('rpgSave');
+    if (saveData) {
+      const data = JSON.parse(saveData);
+      this.player = {...this.player, ...data.player};
+      this.questSystem.completedQuests = data.completedQuests || [];
+      this.currentMapId = data.currentMapId || 'village';
+    }
+  }
+
+  // 游戏主循环
+  gameLoop(timestamp) {
+    const deltaTime = timestamp - this.lastTime;
+    this.lastTime = timestamp;
+
+    // 清空画布
+    this.ctx.fillStyle = '#000';
+    this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
+
+    // 根据状态渲染
+    if (this.state === 'map') {
+      this.mapRenderer.render();
+    }
+
+    requestAnimationFrame(this.gameLoop);
+  }
+}
+
+// 启动游戏
+window.addEventListener('DOMContentLoaded', () => {
+  window.game = new Game();
+});
+```
+
+</details>
+
+**最终成果**：
+
+大约 1-2 小时后，一个功能完整的宝可梦风格 RPG 游戏就完成了！
+
+```
+项目完成总结：
+✅ 游戏架构设计 - Teammate A
+✅ 回合制战斗系统 - Teammate B
+✅ 对话和任务系统 - Teammate C
+✅ 2D 地图渲染 - Teammate D
+✅ UI 界面和音效 - Teammate E
+
+项目文件：
+├── index.html (120 行)
+├── css/
+│   ├── main.css (100 行)
+│   ├── battle.css (180 行)
+│   └── dialog.css (80 行)
+├── js/
+│   ├── game.js (250 行)
+│   ├── state.js (60 行)
+│   ├── player.js (50 行)
+│   ├── monster.js (80 行)
+│   ├── battle.js (220 行)
+│   ├── dialog.js (180 行)
+│   ├── map.js (280 行)
+│   └── audio.js (150 行)
+└── data/
+    ├── monsters.js (100 行)
+    ├── skills.js (80 行)
+    └── dialogues.js (120 行)
+
+总计：约 2050 行代码，5 个 AI 团队成员协作完成！
+
+游戏功能：
+🎮 回合制战斗系统（攻击、技能、道具、逃跑）
+💬 NPC 对话系统（打字机效果、选项分支）
+📜 任务系统（接受任务、更新进度、完成奖励）
+🗺️ 2D 地图探索（多场景切换、NPC 交互）
+💾 自动存档（localStorage 保存进度）
+🔊 音效和 BGM（Web Audio API）
+📊 角色成长（经验、升级、属性提升）
+```
+
+**观察团队工作**：
+
+如果你配置了 tmux 分屏模式，你会看到多个终端窗口同时工作：
+
+```
+┌─────────────────┬─────────────────┬─────────────────┐
+│  Teammate B     │  Teammate C     │  Teammate D     │
+│  实现伤害公式... │  编写对话脚本... │  渲染地块...     │
+│                 │                 │                 │
+│  "Teammate E，  │  "MapRenderer   │  "怪物需要      │
+│   血条宽度是    │   准备好了吗？" │   攻击动画..."   │
+│   百分比吗？"   │                 │                 │
+└─────────────────┴─────────────────┴─────────────────┘
+```
+
+**关键要点**：
+
+这个实战案例展示了 Agent Teams 的几个核心优势：
+
+1. **真正的并行开发**：5 个成员同时开发不同的游戏系统
+2. **复杂项目管理**：2000+ 行代码被合理拆分和整合
+3. **专业分工协作**：战斗、对话、地图、UI 各有专人负责
+4. **接口协调**：成员之间通过消息系统协商接口和数据格式
+5. **快速交付**：原本需要一个人几周的工作，团队几小时就完成了
+
+你可以尝试运行这个游戏，体验 AI 团队协作开发的宝可梦风格 RPG！
+
+---
+
+### 单个 Prompt vs Agent Teams：你可以自己测试
+
+为了让你直观感受 Agent Teams 的强大，我们准备了两套测试方案，你可以自己尝试对比差异。
+
+#### 测试方案 A：单个 Prompt 方式
+
+这是传统的使用方式，用一个完整的 prompt 让 AI 帮你开发游戏。
+
+**在 Claude Code 中输入**：
+
+```
+帮我开发一个宝可梦风格的网页 RPG 游戏，包含以下功能：
+- 角色系统（等级、HP、攻击、防御）
+- 回合制战斗系统（攻击、技能、道具、逃跑）
+- NPC 对话系统
+- 2D 地图探索
+- 存档功能
+- 音效系统
+
+使用 React + TypeScript + Vite + Tailwind CSS。
+请给我完整的代码，可以直接运行的。
+```
+
+**预期结果**：
+
+| 项目 | 预期情况 |
+|------|---------|
+| **代码质量** | AI 会尝试生成所有代码，但由于上下文限制，很多细节会省略或用注释代替 |
+| **功能完整性** | 核心功能可能有，但很多高级功能会缺失或简化 |
+| **代码可运行性** | 可能有一些 bug，需要多次调试才能运行 |
+| **开发时间** | 一次对话可能需要 30-60 分钟，且需要多次往返修改 |
+| **代码量** | 约 500-800 行（因为 AI 会压缩代码） |
+
+**你可能遇到的问题**：
+
+1. **代码被截断**：AI 回复有长度限制，代码可能生成到一半就停止了
+2. **功能不完整**：对话系统可能只有基础版本，没有任务系统
+3. **缺少细节**：音效可能只是一个 TODO 注释
+4. **难以调试**：如果代码有问题，需要让 AI 在同一对话中修改，上下文会越来越混乱
+
+#### 测试方案 B：Agent Teams 方式
+
+这是本文介绍的方式，让多个 AI 团队成员协作开发。
+
+**在 Claude Code 中输入**（开启 Agent Teams 后）：
+
+```
+我想开发一个宝可梦风格的网页 RPG 游戏。
+
+创建一个团队来协作开发：
+
+团队成员分工：
+- Teammate A（游戏架构师）：设计整体架构，定义游戏状态机，规划数据结构
+- Teammate B（战斗系统）：实现回合制战斗逻辑、技能系统、伤害计算
+- Teammate C（对话系统）：实现 NPC 对话、任务系统、剧情脚本
+- Teammate D（地图渲染）：使用 Canvas 实现 2D 地图渲染、角色移动、场景切换
+- Teammate E（UI 音效）：设计游戏界面、战斗 UI、音效播放
+
+技术要求：
+- 使用原生 HTML/CSS/JavaScript
+- 使用 Canvas 渲染游戏画面
+- 回合制战斗系统
+- 存档使用 localStorage
+- 音效使用 Web Audio API
+
+每个成员使用 Sonnet 模型，Team Lead 使用 Opus。
+
+请先让架构师设计整体方案，定义好数据结构后，其他成员再并行开发。
+```
+
+**预期结果**：
+
+| 项目 | 预期情况 |
+|------|---------|
+| **代码质量** | 每个成员专注自己的领域，代码更加专业和完整 |
+| **功能完整性** | 所有功能都有完整实现，包括任务系统、多场景地图等 |
+| **代码可运行性** | 成员之间会互相检查接口，集成问题更少 |
+| **开发时间** | 约 1-2 小时完成全部功能（因为并行开发） |
+| **代码量** | 约 2000+ 行（完整实现，没有压缩） |
+
+#### 量化对比表
+
+| 对比维度 | 单个 Prompt | Agent Teams |
+|---------|-------------|-------------|
+| **总代码行数** | 500-800 行 | 2000+ 行 |
+| **开发时间** | 30-60 分钟（但功能不完整） | 1-2 小时（功能完整） |
+| **功能完整性** | 60-70% | 95%+ |
+| **代码可维护性** | 中等（一个大文件） | 高（模块化设计） |
+| **Bug 数量** | 较多（缺少测试） | 较少（成员互相验证） |
+| **后期扩展** | 困难（代码耦合） | 容易（模块化结构） |
+| **Token 消耗** | ~50K tokens | ~200K tokens（5 个成员） |
+| **成本** | ~$0.50 | ~$2.00 |
+
+#### 实际测试建议
+
+**步骤 1：先测试单个 Prompt 方式**
+
+```
+1. 打开一个新的 Claude Code 对话
+2. 使用上面的"测试方案 A"的 prompt
+3. 记录：花了多长时间？代码有多少行？哪些功能缺失？
+```
+
+**步骤 2：再测试 Agent Teams 方式**
+
+```
+1. 确认 Agent Teams 已开启
+2. 使用上面的"测试方案 B"的 prompt
+3. 观察：团队成员如何协作？代码是否更完整？
+```
+
+**步骤 3：对比两个结果**
+
+```
+1. 分别运行两个版本的代码
+2. 对比功能列表：哪些功能单个 Prompt 有缺失？
+3. 对比代码结构：Agent Teams 的代码是否更模块化？
+4. 评估：如果让你继续开发这个游戏，哪个版本更容易扩展？
+```
+
+#### 为什么会有这些差异？
+
+**单个 Prompt 的局限**：
+
+1. **上下文压力**：AI 需要在一个回复中处理所有信息，必然会简化
+2. **注意力分散**：同时关注战斗、对话、地图、UI，细节容易遗漏
+3. **没有协作验证**：没有人检查接口是否匹配，bug 容易产生
+
+**Agent Teams 的优势**：
+
+1. **专业分工**：每个成员专注一个领域，可以深入细节
+2. **并行处理**：战斗、对话、地图同时开发，效率更高
+3. **互相验证**：成员之间会协商接口，减少集成问题
+4. **独立上下文**：每个成员有自己的 200K 上下文，不会互相干扰
+
+#### 结论
+
+Agent Teams 的核心价值不在于"更快"，而在于**"更完整、更专业"**。
+
+- 对于简单项目（如贪吃蛇），单个 Prompt 就够了
+- 对于复杂项目（如宝可梦 RPG），Agent Teams 能产生更好的结果
+
+关键是**选择合适的工具**：不要用 Agent Teams 去做变量重命名，也不要用单个 Prompt 去做一个完整的 RPG 游戏。
+
+---
+
+## 最佳实践
+
+Agent Teams 是一个强大的工具，但要用好它，需要掌握一些最佳实践。这些经验来自社区使用者的实战总结，能帮你避免常见陷阱，发挥团队协作的最大价值。
+
+### 实践一：合同优先（Contract-First）
+
+在多个 Agent 开始并行工作之前，先花时间定义清晰的"合同"——也就是接口契约。
+
+**为什么重要**：
+
+假设 Teammate A 负责后端 API，Teammate B 负责前端调用。如果他们同时开工，没有事先约定接口格式，很可能出现这种情况：
+
+```
+Teammate A：实现了 POST /api/login，接收 {username, password}
+Teammate B：实现了前端调用，发送 {user, pass}
+结果：对不上，需要返工修改
+```
+
+**如何做**：
+
+在启动团队之前，先让 Claude 帮你设计接口：
+
+```
+先别急着开发，先帮我设计一下用户认证系统的接口：
+
+1. 登录接口的请求和响应格式
+2. 注册接口的请求和响应格式
+3. 密码重置的流程和接口
+4. 错误处理的规范
+
+把这些接口定义清楚地写下来，然后再让团队开始开发。
+```
+
+**合同应该包含**：
+
+- 函数签名和数据结构
+- 输入输出的 JSON 格式
+- HTTP 状态码的含义
+- 错误处理的约定
+- 字段验证规则
+
+### 实践二：合理分配模型
+
+不同的任务需要不同能力的模型，合理分配可以平衡效果和成本。
+
+**Team Lead 用 Opus**：
+
+Team Lead 负责任务拆解、结果综合，这些需要强大的推理能力，推荐使用 Opus：
+
+```
+创建一个团队，Team Lead 使用 Opus 模型，负责整体规划和结果审核。
+Teammates 使用 Sonnet 模型，负责具体实现。
+```
+
+**Teammates 用 Sonnet**：
+
+具体的编码、测试等任务，Sonnet 完全胜任，而且成本更低：
+
+- Opus 4.6：约 $15/百万输出 tokens
+- Sonnet 4.5：约 $3/百万输出 tokens
+
+使用 Sonnet 作为成员可以显著降低整体成本。
+
+**特殊情况用 Haiku**：
+
+对于简单的任务（如文档更新、简单测试编写），可以考虑使用 Haiku（约 $0.80/百万输出 tokens）。
+
+### 实践三：控制任务粒度
+
+任务太大或太小都会影响效率，需要找到合适的粒度。
+
+**经验法则**：
+
+每个任务应该让一个成员在 **15-30 分钟内**独立完成。
+
+**任务太大**：
+
+```
+不好：实现用户认证系统
+```
+
+这个任务太大了，包含多个子任务，一个人需要很长时间才能完成，失去了并行优势。
+
+**任务太小**：
+
+```
+不好：创建一个名为 auth.js 的空文件
+```
+
+这个任务太细碎，成员之间花在协调上的时间比实际干活时间还多。
+
+**合适的粒度**：
+
+```
+好：实现登录 API 接口，包括：
+1. POST /api/login 接口
+2. 验证用户名密码
+3. 返回 JWT token
+4. 错误处理
+```
+
+这个任务有明确的边界和交付物，一个人可以独立完成，也不会太细碎。
+
+**推荐配置**：
+
+每个成员负责 **5-6 个中等粒度的任务**，这样既有足够的并行度，又不会让协调成本过高。
+
+### 实践四：避免文件冲突
+
+多个成员同时修改同一个文件会导致合并冲突，这是 Agent Teams 最常见的问题。
+
+**分配原则**：
+
+尽量让不同成员负责**不同的文件**：
+
+```
+好：
+- Teammate A：负责 src/auth/ 目录下的所有文件
+- Teammate B：负责 src/api/ 目录下的所有文件
+- Teammate C：负责 tests/auth/ 目录下的所有文件
+
+不好：
+- Teammate A 和 Teammate B 都要修改 src/app.js
+```
+
+**如果必须修改同一文件**：
+
+设计串行修改阶段：
+
+```
+阶段 1（并行）：
+- Teammate A：分析 auth.js 需要添加什么功能
+- Teammate B：设计新功能的接口
+- Teammate C：编写测试用例
+
+阶段 2（串行）：
+- Team Lead 综合所有输入
+- 一个成员统一修改 auth.js
+```
+
+### 实践五：提供丰富的初始上下文
+
+Teammates 启动时，对话历史是空的——它们不知道 Team Lead 和用户之前讨论了什么。
+
+**错误做法**：
+
+```
+创建团队，让成员开始干活。
+```
+
+成员们启动后会一脸茫然：什么项目？用什么技术栈？要做什么？
+
+**正确做法**：
+
+```
+这是一个 React + Node.js 的电商项目，使用 TypeScript。
+
+项目结构是：
+- src/frontend/：React 前端代码
+- src/backend/：Node.js 后端代码
+- prisma/：数据库模型
+
+代码风格：
+- 使用函数组件和 Hooks
+- 后端使用 Express.js
+- 数据库用 PostgreSQL
+
+现在创建一个团队，让成员在 src/auth/ 下添加用户认证功能。
+```
+
+提供充分的上下文，成员们才能高效工作。
+
+### 实践六：先研究再实现
+
+不要让成员直接开始编码，先让它们研究和设计方案。
+
+**两阶段流程**：
+
+**阶段 1：研究和设计**
+
+```
+创建一个团队，第一阶段是研究：
+- 一个成员调研现有的认证方案（JWT vs Session）
+- 一个成员分析项目的技术栈，确定最佳实践
+- 一个成员设计数据库表结构
+
+完成研究后，成员们通过消息系统讨论，确定最终方案。
+```
+
+**阶段 2：实现**
+
+```
+方案确定后，第二阶段开始实现：
+- 一个成员实现后端认证逻辑
+- 一个成员实现前端登录页面
+- 一个成员编写测试
+```
+
+这样做的好处是：**提前发现架构不匹配的问题**，避免写到一半发现方案行不通。
+
+### 实践七：主动监控和干预
+
+即使配置了自动化，你还是应该主动监控团队的工作状态。
+
+**使用分屏模式**：
+
+如果你配置了 tmux 分屏，可以实时看到所有成员的输出：
+
+```
+┌─────────────────┬─────────────────┐
+│  Teammate 1     │  Teammate 2     │
+│  正在分析代码... │  正在实现 API... │
+│                 │                 │
+│  等等，这个方案  │                 │
+│  似乎有问题...   │                 │
+└─────────────────┴─────────────────┘
+```
+
+当你发现某个成员走偏了，可以及时干预：
+
+```
+@Teammate1 停一下，你分析的方向不对。认证模块应该在 src/auth/ 下，不是 src/user/。
+```
+
+**定期检查任务状态**：
+
+使用 TaskList 命令查看所有任务的状态：
+
+```
+/tasks
+```
+
+这会显示所有任务的当前状态，你可以看到哪些任务完成了、哪些还在进行中、哪些被阻塞了。
+
+---
+
+## 适用场景
+
+Agent Teams 很强大，但不是所有任务都适合用它。了解它的适用场景，可以帮你做出正确的选择。
+
+### 适合 Agent Teams 的场景
+
+**复杂系统重构**
+
+当你的重构涉及多个模块，且模块之间有明确边界时：
+
+```
+场景：将单体应用拆分为微服务
+
+创建团队：
+- Teammate A：分析用户模块的依赖关系
+- Teammate B：分析订单模块的依赖关系
+- Teammate C：分析支付模块的依赖关系
+- Teammate D：设计服务间的通信协议
+```
+
+三个模块可以同时分析，最后综合结果，比串行分析快得多。
+
+**多角度代码审查**
+
+当你需要从多个维度审查代码时：
+
+```
+场景：全面审查支付模块的安全性
+
+创建团队：
+- Teammate A：专注安全漏洞（SQL 注入、XSS 等）
+- Teammate B：检查性能问题（N+1 查询、内存泄漏等）
+- Teammate C：验证错误处理的完整性
+- Teammate D：评估测试覆盖率
+```
+
+每个成员专注于一个维度，审查更深入，最终综合成一份完整的报告。
+
+**前后端并行开发**
+
+当你需要同时开发前后端时：
+
+```
+场景：开发用户管理功能
+
+创建团队：
+- Teammate A（前端）：实现用户列表页面
+- Teammate B（前端）：实现用户编辑页面
+- Teammate C（后端）：实现 CRUD API
+- Teammate D（协调）：设计 API 接口，确保前后端一致
+```
+
+前后端可以同时开发，只要 API 接口事先定义好（合同优先原则）。
+
+**竞争性调试**
+
+当你有多个可能的解决方案时：
+
+```
+场景：修复一个复杂的 bug，有两个可能的修复方案
+
+创建团队：
+- Teammate A：实施方案 1
+- Teammate B：实施方案 2
+- Teammate C：评估两个方案的优劣
+```
+
+两个方案同时实施和测试，最后比较效果，选择更好的。
+
+**文档生成**
+
+当你需要生成大量文档时：
+
+```
+场景：为整个项目编写文档
+
+创建团队：
+- Teammate A：编写 API 文档
+- Teammate B：编写部署指南
+- Teammate C：编写开发指南
+- Teammate D：编写故障排查手册
+```
+
+多个文档可以同时编写，大幅提升效率。
+
+### 不适合 Agent Teams 的场景
+
+**简单修改任务**
+
+```
+不适合：变量重命名、单个 bug 修复、小功能添加
+```
+
+这些任务启动团队的开销比实际干活时间还长，得不偿失。
+
+**高度串行的任务**
+
+```
+不适合：必须按顺序执行的步骤
+```
+
+如果任务 B 必须等任务 A 完成才能开始，那就没有并行空间了。
+
+**成本敏感的任务**
+
+Agent Teams 的 Token 消耗是单实例的 **2-4 倍**（取决于团队规模）。如果成本是首要考虑，单实例可能是更好的选择。
+
+### 决策流程图
+
+```
+是否有多个独立的子任务？
+    │
+    ├─ 否 → 使用单实例
+    │
+    └─ 是 →
+         │
+         子任务是否可以分配给不同文件？
+         │
+         ├─ 否 → 考虑串行执行或拆分任务
+         │
+         └─ 是 →
+              │
+              成本是否可接受（2-4x）？
+              │
+              ├─ 否 → 使用单实例
+              │
+              └─ 是 → 使用 Agent Teams ✓
+```
+
+---
+
+## 成本和性能
+
+使用 Agent Teams 会增加成本，但也可能带来显著的效率提升。理解这个权衡，可以帮助你做出明智的决策。
+
+### 成本分析
+
+**Token 消耗与团队规模**
+
+Agent Teams 的 Token 消耗大致与团队规模呈**线性关系**：
+
+| 团队规模 | 相对成本 | 适用场景 |
+|---------|---------|---------|
+| 1 人（单实例） | 1x | 简单任务 |
+| 2 人团队 | 2-2.5x | 中等复杂度 |
+| 3 人团队 | 3-4x | 复杂任务 |
+| 5+ 人团队 | 5-6x+ | 大型项目 |
+
+**为什么不是精确的线性关系**：
+
+- **启动开销**：每个成员启动时需要接收初始上下文
+- **协调开销**：成员之间通过消息系统通信也消耗 tokens
+- **Team Lead 成本**：Team Lead 通常使用 Opus，成本更高
+
+**具体数字示例**（Claude 4.5 Sonnet）：
+
+- 输入：$3/百万 tokens
+- 输出：$15/百万 tokens
+
+假设一个任务需要：
+- Team Lead（Opus）：50K 输入 + 20K 输出 ≈ $2.25
+- 3 个 Teammates（Sonnet）：各 30K 输入 + 15K 输出 ≈ $2.7 × 3 = $8.1
+- **总计**：约 $10.35
+
+同样的任务用单实例（Sonnet）：
+- 100K 输入 + 50K 输出 ≈ $1.05
+
+**成本倍数**：约 10 倍
+
+**但时间节省**：可能从 3 小时缩短到 1 小时
+
+### 效率提升
+
+**Anthropic 内部测试数据**：
+
+- 大型项目重构：效率提升约 **50%**
+- 多模块并行开发：效率提升约 **60-70%**
+- 文档生成任务：效率提升约 **80%**
+
+**真实案例**：
+
+Anthropic 工程团队曾用 **16 个并行代理**，在约 2 周时间内构建了一个能够编译 Linux 6.9 内核的 C 编译器（约 10 万行 Rust 代码），通过了 99% 的 GCC 测试。
+
+### 成本优化策略
+
+**策略 1：混合使用模型**
+
+```
+Team Lead：Opus（需要强大推理）
+Teammates：Sonnet（性价比高）
+简单任务：Haiku（最便宜）
+```
+
+**策略 2：动态调整团队规模**
+
+```
+分析阶段：5 人团队（多角度分析）
+实现阶段：3 人团队（并行编码）
+测试阶段：2 人团队（测试和修复）
+```
+
+**策略 3：分阶段使用 Agent Teams**
+
+不是整个项目都用 Agent Teams，只在最复杂的阶段使用：
+
+```
+阶段 1（需求分析）：单实例
+阶段 2（架构设计）：Agent Teams（多方案并行）
+阶段 3（编码实现）：单实例
+阶段 4（代码审查）：Agent Teams（多维度审查）
+阶段 5（文档编写）：Agent Teams（并行编写）
+```
+
+### 什么时候值得
+
+**值得的情况**：
+
+- 项目时间紧张，效率提升带来的价值 > Token 成本
+- 任务复杂度高，单实例容易遗漏细节
+- 需要多角度分析和验证
+
+**不值得的情况**：
+
+- 简单任务，启动团队的开销太大
+- 成本敏感，Token 预算有限
+- 任务高度串行，没有并行空间
+
+---
+
+## 常见问题
+
+### Q1：Agent Teams 稳定吗？可以用于生产环境吗？
+
+Agent Teams 目前是**实验性功能**，可能会有一些 bug 和不稳定的情况。建议：
+
+- 重要项目先做好备份
+- 先在小项目上测试和熟悉
+- 关注官方更新日志，了解新版本的改进
+- 遇到问题时及时反馈给官方
+
+### Q2：最多可以创建多少个成员？
+
+理论上没有硬性限制，但从实用角度考虑：
+
+- 小项目：2-3 人
+- 中等项目：3-5 人
+- 大型项目：5-10 人
+
+成员过多会带来以下问题：
+
+- 协调开销急剧增加
+- Token 消耗线性增长
+- 文件冲突概率上升
+- 难以监控和管理
+
+### Q3：团队成员可以互相看到对方的上下文吗？
+
+**不能**。每个 Teammate 有完全独立的上下文窗口，它们通过消息系统通信，而不是共享上下文。
+
+这是设计上的选择，好处是：
+
+- 每个成员的思路不会被其他成员污染
+- 上下文不会因为对话过长而混乱
+- 更接近真实团队的协作方式（每个人都有自己的大脑）
+
+### Q4：如何在不同成员之间切换？
+
+如果没有配置分屏模式，可以使用快捷键：
+
+- `Shift+Up`：切换到上一个成员
+- `Shift+Down`：切换到下一个成员
+- `Ctrl+O`：回到 Team Lead
+
+### Q5：任务失败了怎么办？
+
+如果某个成员的任务失败了：
+
+1. 查看失败原因：读取该成员的输出日志
+2. 重新分配任务：可以将任务重新分配给其他成员
+3. 手动干预：你可以直接介入，帮助解决卡住的问题
+
+### Q6：可以中途添加或删除成员吗？
+
+可以。你可以随时向 Team Lead 发出指令：
+
+```
+添加一个新成员，让它负责 XXX 任务。
+```
+
+```
+让 Teammate 3 完成当前任务后退出团队。
+```
+
+### Q7：Agent Teams 和之前学的 MCP、Skills 能一起用吗？
+
+完全可以！而且配合使用效果更好：
+
+- **Agent Teams + Skills**：每个成员可以携带不同的技能
+- **Agent Teams + MCP**：不同成员可以通过不同的 MCP 服务器访问外部资源
+
+```
+创建一个团队：
+- Teammate A：携带 frontend-design Skill，负责 UI
+- Teammate B：通过 GitHub MCP 访问仓库，负责 PR 管理
+- Teammate C：通过 Database MCP 查询数据，负责数据分析
+```
+
+---
+
+## 参考资料
+
+### 官方资源
+
+- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code) - Claude Code 完整文档
+- [Anthropic 官方工程博客](https://www.anthropic.com/engineering) - 官方技术博客与更新
+
+### Agent Teams 专题教程
+
+**中文完全指南**：
+
+- [Claude Code Agent Teams 完全指南：从入门到实战](https://m.blog.csdn.net/u010634066/article/details/157903022) - 包含配置细节和实战案例，16 个并行代理构建 C 编译器的震撼案例
+- [使用 Claude Code Agent Team 协作开发项目：完整实战指南](https://m.blog.csdn.net/u010028049/article/details/158126612) - 完整项目协作开发流程
+- [手把手教你设置和使用 Claude Code Agent Teams](https://cloud.tencent.com/developer/article/2630088) - 腾讯云，详细配置教程
+
+**上手实战**：
+
+- [Claude Code 原生 Agent Teams 上手实战：从开启到跑通一个三人团队](https://www.cnblogs.com/147api/p/19606317) - 三人团队实战
+- [Claude Code Agent Teams 新鲜入门实践](https://m.toutiao.com/article/7606744384960266793/) - 新手入门，包含合同优先等最佳实践
+- [不再单打独斗！用 Agent Teams 让 7 个 Claude 同时帮你开发](https://m.toutiao.com/a7605229732241736202/) - 7 人团队协作案例
+
+**最佳实践**：
+
+- [Agent Teams 最佳实践：合同优先、任务粒度、模型分配](https://blog.csdn.net/sinat_37574187/article/details/144727588) - 7 大最佳实践详解
+- [七年大厂老兵的 Claude Code 实战手册：从入门到精通的八条军规](https://new.qq.com/rain/a/20260111A02HE900) - 企业级实战经验
+
+**原理与对比**：
+
+- [Claude Code Agent Teams：多 Agent 协作的正确打开方式](https://post.m.smzdm.com/p/adoezrmz/) - 多代理协作深度解析
+- [Claude Code 多 Agent 组队开发：从原理到踩坑全指南](https://m.toutiao.com/a7605229732241736202/) - 原理与踩坑经验
+
+### 官方指南翻译
+
+- [Claude 官方发布《Agent 构建指南》(附 PDF 下载)](https://m.blog.csdn.net/sinat_37574187/article/details/144724124) - 官方 Agent 构建指南
+- [Claude 官方发布《构建高效的 Agents 指南》全文翻译版](https://m.blog.csdn.net/gyn_enyaer/article/details/144827922) - 完整中文翻译
+
+### 相关技术
+
+- [Agent Skills 标准](https://agentskills.io/) - Skills 生态系统
+- [skills.sh - Agent Skills 应用商店](https://skills.sh/) - 70,000+ 技能库
diff --git a/docs/zh-cn/stage-3/core-skills/3.5-superpowers/index.md b/docs/zh-cn/stage-3/core-skills/3.5-superpowers/index.md
new file mode 100644
index 0000000..43af554
--- /dev/null
+++ b/docs/zh-cn/stage-3/core-skills/3.5-superpowers/index.md
@@ -0,0 +1,623 @@
+# 高级五：Claude Code Superpowers 工程级开发
+
+## Superpowers 简介
+
+**Superpowers** 是由 Jesse Vincent（网名 obra）开发的开源代理技能框架，专门解决 AI 编程中的一个核心问题：如何让 AI 写出"工程级"的代码，而不是"玩具级"的代码。
+
+想象一下，普通 AI 编程助手就像一个"聪明的实习生"——它能写出能跑的代码，但可能没有测试、没有文档、没有遵循最佳实践。而 Superpowers 则像是给这个实习生配备了一位"资深工程师导师"，强制它遵循完整的软件开发流程。
+
+### 为什么需要 Superpowers？
+
+在没有 Superpowers 之前，使用 Claude Code 存在一些问题：
+
+- **Vibe Coding 的混乱**：AI 直接开始写代码，没有规划，导致频繁返工
+- **缺少 TDD 纪律**：AI 习惯先写代码再补测试，甚至干脆不写测试
+- **需求模糊直接动手**：用户说"做一个登录功能"，AI 就开始写，结果做出来不是想要的
+- **代码质量不稳定**：没有代码审查机制，质量依赖 AI 的"心情"
+
+Superpowers 解决了这些问题，让 Claude 变成一个"有纪律的开发团队"——它先帮你澄清需求，然后制定计划，再用 TDD 方式开发，最后通过代码审查确保质量。
+
+---
+
+## 快速开始
+
+### 第一步：安装 Superpowers
+
+在 Claude Code 中运行：
+
+```bash
+# 添加 marketplace
+/plugin marketplace add obra/superpowers-marketplace
+
+# 安装 superpowers
+/plugin install superpowers@superpowers-marketplace
+```
+
+或者手动克隆：
+
+```bash
+git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers
+```
+
+### 第二步：体验第一个 Skill
+
+让我们用 Superpowers 的 **brainstorming**（头脑风暴）技能来体验它的价值。
+
+在 Claude Code 中输入：
+
+```
+我做一个用户登录功能
+```
+
+**没有 Superpowers 之前**：Claude 直接开始写代码，可能做出来不是你想要的。
+
+**有 Superpowers 之后**：Claude 会通过苏格拉底式提问帮你澄清需求：
+
+> 这个登录功能是为 Web 应用还是移动应用设计的？
+>
+> 需要支持哪些登录方式？邮箱密码？第三方登录（Google、GitHub）？
+>
+> 是否需要"记住我"功能？
+>
+> 密码重置流程是邮件还是短信？
+>
+> ...
+
+这些问题迫使你在编码前想清楚真正需要什么，避免写出一堆用不上的代码。
+
+### 第三步：了解技能触发机制
+
+Superpowers 不是"魔法开关"，它是一组**技能集合**。了解技能如何触发很重要。
+
+**技能触发的三种方式**：
+
+1. **关键词触发**
+   - 当你提到 "TDD"、"测试驱动开发"、"先写测试" 时
+   - `test-driven-development` 技能会被激活
+
+2. **场景触发**
+   - 当需求模糊时，`brainstorming` 技能会主动提问
+   - 当出现 bug 时，`systematic-debugging` 技能会被激活
+
+3. **手动调用**
+   - 直接使用技能名称：`/test-driven-development`
+
+#### 💡 重要理解：不指定 TDD 会怎样？
+
+这是一个常见误解，让我们澄清：
+
+```
+# 情况 A：不提 TDD
+"实现一个计算器"
+→ Claude 可能写测试，也可能不写
+→ 取决于模型本身的训练习惯
+
+# 情况 B：提到 TDD
+"用 TDD 方式实现一个计算器"
+→ test-driven-development 技能被激活
+→ 强制遵循 RED-GREEN-REFACTOR 流程
+```
+
+**Superpowers 的真正价值**：不是"无中生有"，而是"强化纪律"。
+
+- 没有 TDD 技能时：Claude 写测试是"看心情"
+- 有 TDD 技能时：Claude 被强制遵循 TDD 流程
+
+### 理解 Superpowers 的价值
+
+通过上面的解释，你可以看到 Superpowers 的核心价值：
+
+1. **需求优先**：`brainstorming` 技能在需求模糊时主动提问
+2. **流程纪律**：`test-driven-development` 强制 TDD 红绿重构循环
+3. **任务分解**：`writing-plans` 将大项目拆解为小任务
+4. **质量控制**：`code-review` 技能确保代码质量
+
+---
+
+## Superpowers 核心技能详解
+
+Superpowers 包含 **20+ 个可组合技能**，覆盖整个软件开发生命周期。让我们按类别了解它们。
+
+### 🧪 测试类技能
+
+#### test-driven-development（测试驱动开发）
+
+**如何触发**：提到 "TDD"、"测试驱动开发"、"先写测试" 等关键词。
+
+**这个技能做什么**：强制 Claude 遵循 TDD 红绿重构循环，而不是"想起来再写测试"。
+
+**传统开发方式**（常见问题）：
+1. 直接写代码
+2. 手动测试一下
+3. 发现 bug，修改代码
+4. 重复...（测试？下次再说吧）
+
+**TDD 方式**（技能激活后）：
+1. 🔴 **RED**：先写一个失败的测试
+2. 🟢 **GREEN**：写最少的代码让测试通过
+3. 🔵 **REFACTOR**：重构代码，保持测试通过
+4. 重复
+
+**使用示例**：
+
+```
+用 TDD 方式实现一个用户认证模块
+```
+
+Claude 会：
+1. 先编写测试（测试用户名密码验证、测试 token 生成...）
+2. 运行测试，确认全部失败（RED）
+3. 编写最小实现代码
+4. 运行测试，确认通过（GREEN）
+5. 重构代码，提取公共逻辑
+6. 再次运行测试，确认仍然通过（REFACTOR）
+
+> **注意**：如果你不提 "TDD"，Claude 可能也可能不写测试。这个技能的作用是**强化流程纪律**，确保测试不会"被遗忘"。
+
+### 🐛 调试类技能
+
+#### systematic-debugging（系统化调试）
+
+当出现 bug 时，人类开发者往往会随机尝试各种修复方案。Superpowers 强制使用四阶段根因分析：
+
+**阶段 1：复现问题**
+- 确认 bug 可以稳定复现
+- 记录复现步骤
+
+**阶段 2：隔离根因**
+- 通过二分法缩小范围
+- 添加日志定位问题代码
+
+**阶段 3：验证假设**
+- 提出根因假设
+- 设计验证实验
+
+**阶段 4：修复并验证**
+- 实施修复
+- 确认 bug 解决
+- 添加回归测试
+
+#### verification-before-completion（完成前验证）
+
+这个技能防止 Claude "感觉差不多"就停止工作。它要求 Claude 在声称任务完成前：
+
+1. 运行所有测试
+2. 手动测试关键功能
+3. 检查代码质量（lint）
+4. 确认文档已更新
+
+### 🤝 协作类技能
+
+#### brainstorming（头脑风暴）
+
+这是 Superpowers 最有趣的技能之一。它使用苏格拉底式提问法帮你澄清需求。
+
+**工作方式**：当你提出一个模糊需求时，Claude 不会直接动手，而是会问你问题：
+
+```
+你：做一个博客系统
+
+Claude：
+- 这个博客主要是给谁看的？技术读者还是大众？
+- 需要支持 Markdown 编辑吗？
+- 需要评论功能吗？
+- 需要搜索功能吗？
+- 是单用户还是多作者？
+- ...
+```
+
+这些问题迫使你思考真正需要什么功能，避免开发出一堆用不上的东西。
+
+#### writing-plans（编写计划）
+
+这个技能将大任务分解为 2-5 分钟可完成的小任务。
+
+**示例**：
+
+```
+用 writing-plans 规划一个待办事项 API 的开发
+```
+
+Claude 会生成详细计划：
+
+```markdown
+# 实现计划
+
+## 任务 1：设计数据库 schema（预计 5 分钟）
+- 创建 todos 表
+- 定义字段：id, title, completed, createdAt
+
+## 任务 2：创建 Express 路由（预计 10 分钟）
+- POST /todos - 创建任务
+- GET /todos - 获取列表
+- GET /todos/:id - 获取单个
+- PUT /todos/:id - 更新
+- DELETE /todos/:id - 删除
+
+## 任务 3：添加输入验证（预计 10 分钟）
+- 标题不能为空
+- completed 必须是布尔值
+
+## 任务 4：编写测试（预计 15 分钟）
+- 为每个端点编写测试
+- 覆盖边界情况
+
+## 任务 5：启动服务器并验证（预计 5 分钟）
+- 运行测试
+- 手动测试 API
+
+验收标准：
+- 所有测试通过
+- curl 测试每个端点正常
+```
+
+#### executing-plans（执行计划）
+
+这个技能批量执行计划，并在每个检查点暂停确认。
+
+**使用示例**：
+
+```
+执行上面的计划，每完成一个任务暂停一下
+```
+
+Claude 会：
+1. 完成任务 1，然后暂停：`✅ 数据库 schema 完成，继续吗？`
+2. 你确认后完成任务 2，再次暂停
+3. 以此类推
+
+这让你可以在每个阶段检查方向是否正确，避免跑远了才发现错了。
+
+#### dispatching-parallel-agents（并行代理调度）
+
+这个技能可以同时启动多个子代理并行工作。
+
+**使用场景**：当你需要同时处理多个独立任务时。
+
+```
+用并行代理同时完成：
+- 代理 A：编写后端 API
+- 代理 B：编写前端组件
+- 代理 C：编写测试
+```
+
+每个代理在自己的隔离环境中工作，互不干扰。
+
+#### subagent-driven-development（子代理驱动开发）
+
+这个技能为每个小任务启动一个独立的子代理。
+
+**优势**：
+- 每个子代理有独立的上下文
+- 任务失败不会影响其他任务
+- 可以并行执行多个任务
+
+#### using-git-worktrees（使用 Git Worktrees）
+
+这个技能使用 Git 的 worktree 功能创建隔离的开发环境。
+
+**好处**：
+- 多个功能可以并行开发
+- 每个 worktree 是独立的
+- 不会互相冲突
+
+### 👀 代码审查类技能
+
+#### requesting-code-review（请求代码审查）
+
+当你完成代码后，这个技能会自动请求代码审查。
+
+```
+完成功能后自动触发代码审查
+```
+
+#### receiving-code-review（接收代码审查）
+
+这个技能定义了如何接收和处理审查反馈。
+
+**审查流程**：
+1. 提交代码
+2. 自动触发审查
+3. 审查者检查代码质量、安全性、测试覆盖率
+4. 提出改进建议
+5. 修复问题
+6. 重新审查直到批准
+
+---
+
+## Superpowers 完整工作流程
+
+Superpowers 的真正威力在于将多个技能组合成完整的开发流程。
+
+### 标准开发流程
+
+```
+1. Brainstorming（头脑风暴）
+   ↓ 通过问答澄清真实需求
+
+2. Design Document（设计文档）
+   ↓ 分块展示设计，等待确认
+
+3. Writing Plans（编写计划）
+   ↓ 分解为 2-5 分钟的小任务
+
+4. Subagent Development（子代理开发）
+   ↓ 每个任务启动独立子代理
+   ↓ 两阶段审查：规格符合性 + 代码质量
+
+5. TDD（测试驱动开发）
+   ↓ 强制 RED-GREEN-REFACTOR
+
+6. Code Review（代码审查）
+   ↓ 质量把关
+
+7. 完成
+```
+
+### 实战案例：用 Superpowers 构建用户认证系统
+
+让我们通过一个完整的例子来体验 Superpowers 的工作流程。
+
+#### 第一步：Brainstorming 澄清需求
+
+```
+我需要一个用户认证系统
+```
+
+Claude 会问你：
+- Web 应用还是移动应用？
+- 支持哪些登录方式？
+- 需要密码重置吗？
+- 需要"记住我"功能吗？
+- ...
+
+#### 第二步：生成设计文档
+
+确认需求后，Claude 会生成设计文档：
+
+```markdown
+# 用户认证系统设计
+
+## 功能需求
+1. 用户注册（邮箱 + 密码）
+2. 用户登录
+3. 密码重置（邮件）
+4. 记住我（JWT + Refresh Token）
+
+## 技术选型
+- 后端：Node.js + Express
+- 数据库：SQLite
+- 认证：JWT
+- 加密：bcrypt
+
+## API 设计
+- POST /api/auth/register
+- POST /api/auth/login
+- POST /api/auth/refresh
+- POST /api/auth/reset-password
+```
+
+#### 第三步：编写实现计划
+
+```
+用 writing-plans 制定实现计划
+```
+
+Claude 会生成详细的任务列表，每个任务 2-5 分钟可完成。
+
+#### 第四步：执行开发
+
+```
+用 TDD 方式执行上面的计划
+```
+
+Claude 会：
+1. 先写测试
+2. 确认测试失败（RED）
+3. 写实现代码
+4. 确认测试通过（GREEN）
+5. 重构代码（REFACTOR）
+
+#### 第五步：代码审查
+
+完成后自动触发代码审查，检查：
+- 代码质量
+- 安全性（SQL 注入、XSS 等）
+- 测试覆盖率
+- 文档完整性
+
+---
+
+## Superpowers vs 直接使用 Claude Code
+
+| 维度 | 直接使用 Claude Code | 使用 Superpowers |
+|------|---------------------|-----------------|
+| **需求澄清** | AI 直接开始写代码 | 苏格拉底式提问澄清需求 |
+| **开发流程** | 随 AI 自由发挥 | 强制 TDD 红绿重构 |
+| **任务管理** | 一次性完成 | 分解为小任务，带检查点 |
+| **代码质量** | 依赖 AI 判断 | 强制代码审查 |
+| **可预测性** | 结果不稳定 | 流程可重复 |
+| **适用场景** | 简单任务、原型验证 | 复杂项目、生产代码 |
+
+### 形象比喻
+
+如果把 Claude Code 比作一个"聪明的实习生"：
+
+- **直接使用**：告诉实习生"做一个登录功能"，他直接开始写，可能做出你觉得不对的东西
+- **使用 Superpowers**：给实习生配备一位资深导师，导师会问清楚需求、制定计划、检查代码质量
+
+---
+
+## 安装与配置详解
+
+### 方法一：通过 Marketplace（推荐）
+
+```bash
+# 添加 marketplace
+/plugin marketplace add obra/superpowers-marketplace
+
+# 安装
+/plugin install superpowers@superpowers-marketplace
+
+# 验证安装
+/skills
+```
+
+### 方法二：手动克隆
+
+```bash
+# 创建目录
+mkdir -p ~/.claude/skills
+
+# 克隆仓库
+git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers
+```
+
+### 方法三：项目级别安装
+
+如果你想在特定项目中使用 Superpowers：
+
+```bash
+# 在项目根目录
+mkdir -p .claude/skills
+
+# 克隆或复制 superpowers
+cp -r ~/.claude/skills/superpowers .claude/skills/
+```
+
+这样团队成员可以共享相同的 Superpowers 配置。
+
+---
+
+## 常用技能速查表
+
+| 技能名称 | 功能 | 使用场景 |
+|---------|------|---------|
+| `brainstorming` | 苏格拉底式提问澄清需求 | 需求不明确时 |
+| `writing-plans` | 分解任务为小步骤 | 大项目开始前 |
+| `executing-plans` | 执行计划并检查点 | 按计划开发时 |
+| `test-driven-development` | TDD 红绿重构循环 | 所有功能开发 |
+| `systematic-debugging` | 四阶段根因分析 | 出现 bug 时 |
+| `verification-before-completion` | 完成前验证 | 任务结束时 |
+| `requesting-code-review` | 请求代码审查 | 提交代码前 |
+| `subagent-driven-development` | 子代理驱动开发 | 并行任务 |
+| `using-git-worktrees` | Git worktree 隔离 | 并行开发功能 |
+
+---
+
+## 最佳实践
+
+### 1. 明确触发关键词
+
+Superpowers 的技能是通过关键词触发的，了解常用触发词：
+
+| 技能 | 触发关键词 |
+|------|-----------|
+| `test-driven-development` | "TDD"、"测试驱动"、"先写测试" |
+| `brainstorming` | 需求模糊时自动触发 |
+| `systematic-debugging` | "调试"、"bug"、"不工作" |
+| `writing-plans` | "制定计划"、"规划" |
+
+### 2. 需要流程纪律时用 Superpowers
+
+- 生产级代码开发 → 提到 "TDD"
+- 需求不明确时 → 让 `brainstorming` 帮你澄清
+- 复杂项目 → 用 `writing-plans` 分解任务
+
+### 3. 简单任务不必强求
+
+如果是快速原型或一次性脚本，不需要强制走完整流程。Superpowers 适合需要长期维护的代码。
+
+### 4. 技能可以组合使用
+
+```
+用 TDD 方式实现用户认证，完成后帮我做代码审查
+```
+
+这会同时触发 `test-driven-development` 和 `code-review` 技能。
+
+---
+
+## 常见问题
+
+### Q1：Superpowers 会让开发变慢吗？
+
+初期可能会感觉慢，因为：
+- 需要时间澄清需求
+- 要先写测试再写代码
+- 要经过代码审查
+
+但长期来看，由于减少了返工和 bug，整体效率更高。
+
+### Q2：小项目也需要 Superpowers 吗？
+
+对于原型验证或非常简单的任务，可以直接使用 Claude Code。Superpowers 更适合：
+- 生产级项目
+- 多人协作项目
+- 需要长期维护的项目
+
+### Q3：Superpowers 和 Skills 有什么区别？
+
+| 维度 | Superpowers | Skills |
+|------|-------------|--------|
+| **本质** | 完整的开发方法论框架 | 可复用的技能包 |
+| **范围** | 覆盖整个开发流程 | 聚焦特定功能 |
+| **关系** | Superpowers 内部使用 Skills | Superpowers 是 Skills 的集合 |
+
+### Q4：可以自定义 Superpowers 技能吗？
+
+可以！Superpowers 是开源的，你可以：
+1. Fork 仓库
+2. 修改现有技能
+3. 添加新的技能
+4. 贡献回社区
+
+---
+
+## 参考资料
+
+### 官方资源
+
+- [obra/superpowers GitHub](https://github.com/obra/superpowers) - 官方仓库（50,000+ ⭐）
+- [Superpowers 详细用法教程](https://www.cnblogs.com/gyc567/p/19510203) - 中文详细教程
+- [Superpowers 环境配置指南](https://m.blog.csdn.net/gitblog_00683/article/details/144768992) - 配置指南
+
+### 社区资源
+
+| 仓库 | 说明 |
+|------|------|
+| [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) | 综合工具包，包含 TDD 工作流 |
+| [shanraisshan/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) | 官方最佳实践 |
+
+### 相关文章
+
+- [告别 Vibe Coding！用 Superpowers 让 Claude Code 写出工程级代码](https://juejin.cn/post/7593573617648123956)
+- [我如何用 Superpowers MCP 强制 Claude Code 在编码前进行规划](https://juejin.cn/post/7570341520551673871)
+- [Claude Code + Superpowers 保姆级入门教程](https://juejin.cn/post/7594832320030638123)
+
+---
+
+## 总结
+
+Superpowers 是一组**工程级开发技能集合**，让 Claude Code 从"聪明的实习生"变成"有纪律的开发团队"。
+
+### 核心要点
+
+1. **Superpowers 是技能集合，不是魔法**
+   - 安装后，技能在后台可用
+   - 通过关键词或场景触发
+   - 可以手动调用特定技能
+
+2. **记住关键触发词**
+   - 想要 TDD → 说 "用 TDD 方式"
+   - 需求模糊 → `brainstorming` 会主动提问
+   - 出现 bug → 提到 "调试" 触发 `systematic-debugging`
+
+3. **适用场景**
+   - ✅ 生产级代码开发
+   - ✅ 需要长期维护的项目
+   - ✅ 团队协作项目
+   - ❌ 快速原型（可选）
+   - ❌ 一次性脚本（可选）
+
+记住：**Superpowers 不让 AI 更聪明，而是让 AI 更有纪律。**