Skip to content

A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.

feat(zh): add Chinese translations in zh/ directory

Luong NGUYEN89e89d4aa38c
diff --git a/scripts/check_cross_references.py b/scripts/check_cross_references.py
index 0d9539c..7dd28c3 100644
--- a/scripts/check_cross_references.py
+++ b/scripts/check_cross_references.py
@@ -3,6 +3,7 @@
import re
import sys
+import unicodedata
from pathlib import Path
IGNORE_DIRS = {
@@ -63,7 +64,7 @@ def main() -> int:
errors = []
for file_path in iter_md_files():
- content = file_path.read_text()
+ content = file_path.read_text(encoding="utf-8")
# Strip code blocks before scanning for links/anchors to avoid false positives
# from documentation examples inside code fences.
scannable = strip_code_blocks(content)
diff --git a/zh/.github/ISSUE_TEMPLATE/bug_report.md b/zh/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..bda438d
--- /dev/null
+++ b/zh/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,43 @@
+---
+name: Bug Report
+about: 报告示例、指南或文档中的问题
+title: "[BUG] "
+labels: bug
+assignees: ''
+
+---
+
+## 问题描述
+简要说明问题。
+
+## 复现步骤
+1. 第 1 步
+2. 第 2 步
+3. 第 3 步
+
+## 预期行为
+应该发生什么?
+
+## 实际行为
+实际发生了什么?
+
+## 环境
+- **Claude Code 版本**:(例如 1.0.5)
+- **操作系统**:(例如 macOS 14.1、Ubuntu 22.04、Windows 11)
+- **Python 版本**:(如有相关,例如 3.11)
+- **受影响的组件**:(例如 01-slash-commands、03-skills 等)
+
+## 示例代码
+如果适用,请提供无法正常工作的示例代码:
+```
+[在这里插入代码]
+```
+
+## 截图
+如果适用,请附上显示问题的截图。
+
+## 其他上下文
+还有哪些信息可能有助于我们理解这个问题?
+
+## 可能的解决方案
+如果你有修复建议,也可以写在这里。
diff --git a/zh/.github/ISSUE_TEMPLATE/documentation.md b/zh/.github/ISSUE_TEMPLATE/documentation.md
new file mode 100644
index 0000000..b53cec1
--- /dev/null
+++ b/zh/.github/ISSUE_TEMPLATE/documentation.md
@@ -0,0 +1,44 @@
+---
+name: Documentation Issue
+about: 报告文档中的不清晰、错别字或缺失信息
+title: "[DOCS] "
+labels: documentation
+assignees: ''
+
+---
+
+## 问题类型
+- [ ] 拼写或语法错误
+- [ ] 解释不清
+- [ ] 缺少信息
+- [ ] 链接或引用损坏
+- [ ] 内容过时
+- [ ] 需要更好的示例
+
+## 位置
+哪一部分有问题?
+- **文件**:(例如 README.md、03-skills/README.md)
+- **章节**:(例如 "Installation Quick Reference")
+- **行号/区域**:(如有具体位置)
+
+## 当前内容
+当前写的是什么?
+```
+[在这里粘贴当前文本]
+```
+
+## 问题说明
+哪里有问题?
+
+## 建议改进
+应该如何改进或澄清?
+```
+[在这里提供改进后的文本或建议]
+```
+
+## 这样做的重要性
+这个问题会怎样影响用户?
+
+## 相关文档
+相关章节链接:
+- 相关指南:<!-- 在这里添加链接 -->
diff --git a/zh/.github/ISSUE_TEMPLATE/feature_request.md b/zh/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..7a328d7
--- /dev/null
+++ b/zh/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,46 @@
+---
+name: Feature Request
+about: 建议新增示例、指南或改进
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+
+---
+
+## 描述
+描述你希望看到的功能或改进。
+
+## 它解决了什么问题
+它解决了什么问题或缺口?
+
+示例:
+- 没有 X 功能的示例
+- Y 功能的现有文档不清楚
+- 我们需要 Z 场景的指南
+- 结构可以通过以下方式改进……
+
+## 使用场景
+这个功能会在什么时候、怎样使用?请包含真实场景。
+
+## 建议方案
+应该如何实现或记录?
+
+## 示例
+如果适用,请提供你设想的示例:
+```
+[在这里插入示例]
+```
+
+## 相关示例
+链接任何已有的相关示例或指南:
+- 现有指南:<!-- 在这里添加链接 -->
+- 功能:(例如 Skills、Hooks、Subagents)
+
+## 其他上下文
+还有哪些可能有帮助的信息?
+
+## 验收标准
+怎样才算这个功能完成?
+- [ ] 标准 1
+- [ ] 标准 2
+- [ ] 标准 3
diff --git a/zh/.github/ISSUE_TEMPLATE/question.md b/zh/.github/ISSUE_TEMPLATE/question.md
new file mode 100644
index 0000000..954585c
--- /dev/null
+++ b/zh/.github/ISSUE_TEMPLATE/question.md
@@ -0,0 +1,40 @@
+---
+name: Question
+about: 提出关于 Claude Code 或本指南的问题
+title: "[QUESTION] "
+labels: question
+assignees: ''
+
+---
+
+## 问题
+你想了解什么?
+
+## 背景
+请提供一些背景或上下文:
+- 你想做什么?
+- 你已经尝试过什么?
+- 你看过哪些示例或指南?
+
+## 相关主题
+这个问题属于哪个主题?
+- [ ] Slash Commands
+- [ ] Memory
+- [ ] Skills
+- [ ] Subagents
+- [ ] MCP Protocol
+- [ ] Hooks
+- [ ] Plugins
+- [ ] Checkpoints
+- [ ] Advanced Features
+- [ ] CLI Reference
+- [ ] 其他
+
+## 你尝试过什么
+你已经尝试了什么?结果如何?
+
+## 期望结果
+什么样的结果能帮助你解决问题?
+
+## 其他资源
+还有哪些可能相关的链接或资源?
diff --git a/zh/.github/SECURITY_REPORTING.md b/zh/.github/SECURITY_REPORTING.md
new file mode 100644
index 0000000..3b8b84a
--- /dev/null
+++ b/zh/.github/SECURITY_REPORTING.md
@@ -0,0 +1,309 @@
+# 安全漏洞报告
+
+本文说明如何向 Claude How To 项目报告安全漏洞。
+
+## 快速链接
+
+- **私密报告**:<https://github.com/luongnv89/claude-howto/security/advisories>
+- **安全政策**:[SECURITY.md](../SECURITY.md)
+- **报告模板**:见下文
+
+## 报告漏洞
+
+### 选项 1:GitHub 私密漏洞报告(推荐)
+
+这是报告安全漏洞的首选方式。
+
+**步骤:**
+1. 访问:<https://github.com/luongnv89/claude-howto/security/advisories>
+2. 点击 “Report a vulnerability”
+3. 填写详情(可使用下方模板)
+4. 提交
+
+**优点:**
+- 在修复发布前保持漏洞私密
+- 自动通知维护者
+- 内置协作功能
+- 与 GitHub 安全工具集成
+
+### 选项 2:GitHub 安全警报(依赖漏洞)
+
+如果你在依赖中发现漏洞:
+
+1. 访问:<https://github.com/luongnv89/claude-howto/security/advisories>
+2. 查看警报
+3. 提交包含修复的 pull request
+4. 加上 `security` 标签
+
+### 选项 3:私密邮箱(GitHub 不可用时)
+
+如果你无法使用 GitHub 的报告系统:
+
+**即将提供**:这里会补充安全联系邮箱
+
+目前请优先使用上面的 GitHub 私密漏洞报告。
+
+## 漏洞报告模板
+
+报告漏洞时可使用以下模板:
+
+```
+**标题**:[漏洞简述]
+
+**严重性**:[Critical/High/Medium/Low]
+Estimated CVSS Score: [0-10]
+
+**类型**:[代码/文档/依赖/配置]
+
+**受影响组件**:
+- File: [path/to/file.py]
+- Section: [文档章节名,如适用]
+- Version: [latest/具体版本]
+
+**描述**:
+[对漏洞的清晰说明]
+
+**潜在影响**:
+[攻击者可以利用该漏洞做什么?]
+[可能影响哪些人?]
+
+**复现步骤**:
+1. [第一步]
+2. [第二步]
+3. [第三步]
+[预期结果与实际结果]
+
+**PoC**(如有):
+[用于演示漏洞的代码或步骤]
+
+**建议修复**:
+[你的建议方案,如有]
+
+**附加上下文**:
+[任何其他相关信息]
+
+**你的信息**:
+- Name: [你的名字或匿名]
+- Email: [你的邮箱]
+- Credit: [你希望如何署名,如有]
+```
+
+## 提交后会发生什么
+
+### 时间线
+
+1. **立刻(< 1 小时)**
+ - 自动通知会发送给项目维护者
+
+2. **24 小时内**
+ - 对报告进行初步评估
+ - 确认已收到
+ - 初步严重性评估
+
+3. **48 小时内**
+ - 安全团队给出详细回复
+ - 如需更多信息会继续询问
+ - 如果确认漏洞存在,会给出修复时间线
+
+4. **1-7 天内**(取决于严重性)
+ - 完成修复并测试
+ - 准备安全公告
+ - 发布修复并公开公告
+
+### 沟通方式
+
+我们会通过以下方式与你保持沟通:
+- GitHub 私密漏洞讨论
+- 邮件(如果你提供了)
+- 讨论线程中的更新
+
+你可以:
+- 提出澄清问题
+- 补充更多信息
+- 建议改进修复方案
+- 请求调整时间线
+
+### 披露时间线
+
+**严重问题(CVSS 9.0-10.0)**
+- 修复:立即发布(24 小时内)
+- 披露:当天发布公开公告
+- 通知:提前 24 小时通知报告者
+
+**高危问题(CVSS 7.0-8.9)**
+- 修复:48-72 小时内发布
+- 披露:发布时公开公告
+- 通知:提前 5 天通知报告者
+
+**中危问题(CVSS 4.0-6.9)**
+- 修复:纳入下一次常规更新
+- 披露:发布时公开公告
+- 通知:协调时间线
+
+**低危问题(CVSS 0.1-3.9)**
+- 修复:纳入下一次常规更新
+- 披露:发布时公告
+- 通知:与发布同日
+
+## 安全漏洞标准
+
+### 范围内
+
+我们接受以下类型的报告:
+
+- **代码漏洞**
+ - 注入攻击(命令、SQL 等)
+ - 示例中的跨站脚本(XSS)
+ - 认证/授权缺陷
+ - 路径穿越漏洞
+ - 密码学问题
+
+- **文档安全**
+ - 暴露的秘密或凭据
+ - 不安全代码模式
+ - 安全反模式
+ - 误导性的安全声明
+
+- **依赖漏洞**
+ - 依赖中的已知 CVE
+ - 供应链攻击
+ - 恶意依赖
+
+- **配置问题**
+ - 不安全默认值
+ - 缺失安全头
+ - 示例中的凭据暴露
+
+### 范围外
+
+以下内容不接受报告:
+
+- Claude Code 本身的漏洞(请联系 Anthropic)
+- 外部服务中的漏洞
+- 没有证明的理论漏洞
+- 已向上游项目报告的问题
+- 社会工程学或钓鱼
+- 用户教育 / 培训问题
+
+## 负责任披露指南
+
+### 应该做的 ✅
+
+- **先私下报告**,再公开披露
+- **尽量具体**,提供文件路径和行号
+- **提供证明**,说明漏洞确实存在
+- **给我们时间**修复(协调披露)
+- **补充更新**,如果你发现了更多细节
+- **保持专业**,在所有沟通中都如此
+- **尊重保密性**,直到我们公开发布
+
+### 不应该做的 ❌
+
+- **不要在修复前公开披露**
+- **不要超出测试所需范围去利用漏洞**
+- **不要修改**其他用户的数据
+- **不要索要**报酬或好处
+- **不要把漏洞**分享给其他人
+- **不要用于**任何有害用途
+- **不要用**非安全相关 issue 刷屏
+
+## 协调披露
+
+我们遵循负责任披露流程:
+
+1. **私密报告**:你先私下告诉我们
+2. **我们评估**:判断并评估严重性
+3. **开发修复**:我们开发并测试修复
+4. **提前通知**:在公开披露前提前通知你
+5. **公开发布**:我们同时发布修复和公告
+6. **你的署名**:如你愿意,会在公告中致谢
+
+**具体时间会根据严重性变化**(见上文)
+
+## 修复发布后
+
+### 公开公告
+
+公开安全公告通常包含:
+- 漏洞描述
+- 受影响版本
+- 严重性(CVSS 分数)
+- 修复步骤
+- 修复链接
+- 对报告者的致谢(如获许可)
+
+### 你的署名
+
+如果你希望被致谢:
+- 公告中会写上你的名字/昵称
+- 可附上你的个人资料或网站链接
+- 在发布说明中致谢
+- 如果未来建立名人堂,也可能加入
+
+### 不提供金钱补偿
+
+请注意:
+- 这是一个志愿者维护的开源项目
+- 我们无法提供金钱奖励
+- 但会提供认可和署名
+- 你的贡献会帮助整个社区
+
+## 安全研究
+
+如果你在做安全研究:
+
+1. **先取得许可**:先联系维护者
+2. **明确范围**:约定你会测试什么
+3. **报告发现**:使用本流程
+4. **尊重时间线**:给我们时间修复
+5. **负责任地发布**:与我们协调
+
+## 有问题?
+
+如果你对这个流程有疑问:
+
+1. 查看 [SECURITY.md](../SECURITY.md) 的完整政策
+2. 查看下方的 [FAQ](#faq)
+3. 使用 `[SECURITY]` 标签发起 discussion
+4. 对敏感问题使用私密漏洞报告
+
+## FAQ
+
+**Q: 我的报告会保密吗?**
+A: 会,直到修复发布。我们只会与参与修复的人共享细节。
+
+**Q: 我需要等多久才能公开披露?**
+A: 我们会按照严重性遵循负责任披露时间线(24 小时到 7 天)。如有需要,你可以同意延长。
+
+**Q: 我会获得署名吗?**
+A: 会,会出现在安全公告和发布说明中(除非你希望匿名)。
+
+**Q: 如果漏洞很小怎么办?**
+A: 所有真实的安全问题都会被认真对待,即使很小也会被记录和致谢。
+
+**Q: 我可以只报告文档里的漏洞吗?**
+A: 可以。文档安全同样重要。不安全示例也在范围内。
+
+**Q: 如果我不确定这是不是安全问题呢?**
+A: 先报告即可!如果不是安全问题,我们会告诉你。误报没关系。
+
+**Q: 报告后我可以公开讨论吗?**
+A: 不可以,请在我们公开公告前保持私密。过早披露可能让用户面临风险。
+
+**Q: 我怎么知道你收到了我的报告?**
+A: GitHub 会发送自动通知,我们会在 24 小时内跟进。
+
+**Q: 如果我一直没收到回复怎么办?**
+A: 检查 GitHub security advisories 页面。如果仍看不到回复,可以在私密报告里继续留言跟进。
+
+## 资源
+
+- [SECURITY.md](../SECURITY.md) - 完整安全政策
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - 贡献指南
+- [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) - 社区标准
+- [OWASP Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html) - 负责任披露最佳实践
+- [Coordinated Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerable_Dependency_Management_Cheat_Sheet.html)
+
+---
+
+感谢你帮助维护项目安全!🔒
diff --git a/zh/.github/TESTING.md b/zh/.github/TESTING.md
new file mode 100644
index 0000000..22612a6
--- /dev/null
+++ b/zh/.github/TESTING.md
@@ -0,0 +1,341 @@
+# 测试指南
+
+本文档说明 Claude How To 的测试基础设施。
+
+## 概览
+
+项目使用 GitHub Actions 在每次 push 和 pull request 时自动运行测试。测试覆盖:
+
+- **单元测试**:使用 pytest 的 Python 测试
+- **代码质量**:使用 Ruff 做 lint 和格式化
+- **安全**:使用 Bandit 做漏洞扫描
+- **类型检查**:使用 mypy 做静态类型分析
+- **构建验证**:EPUB 生成测试
+
+## 在本地运行测试
+
+### 前置条件
+
+```bash
+# 安装 uv(快速 Python 包管理器)
+pip install uv
+
+# 或者在 macOS 上使用 Homebrew
+brew install uv
+```
+
+### 配置环境
+
+```bash
+# 克隆仓库
+git clone https://github.com/luongnv89/claude-howto.git
+cd claude-howto
+
+# 创建虚拟环境
+uv venv
+
+# 激活虚拟环境
+source .venv/bin/activate # macOS/Linux
+# 或者
+.venv\Scripts\activate # Windows
+
+# 安装开发依赖
+uv pip install -r requirements-dev.txt
+```
+
+### 运行测试
+
+```bash
+# 运行所有单元测试
+pytest scripts/tests/ -v
+
+# 运行带覆盖率的测试
+pytest scripts/tests/ -v --cov=scripts --cov-report=html
+
+# 运行指定测试文件
+pytest scripts/tests/test_build_epub.py -v
+
+# 运行指定测试函数
+pytest scripts/tests/test_build_epub.py::test_function_name -v
+
+# 以 watch 模式运行测试(需要 pytest-watch)
+ptw scripts/tests/
+```
+
+### 运行 lint
+
+```bash
+# 检查代码格式
+ruff format --check scripts/
+
+# 自动修复格式问题
+ruff format scripts/
+
+# 运行 lint
+ruff check scripts/
+
+# 自动修复 lint 问题
+ruff check --fix scripts/
+```
+
+### 运行安全扫描
+
+```bash
+# 运行 Bandit 安全扫描
+bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/
+
+# 生成 JSON 报告
+bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ -f json -o bandit-report.json
+```
+
+### 运行类型检查
+
+```bash
+# 使用 mypy 检查类型
+mypy scripts/ --ignore-missing-imports --no-implicit-optional
+```
+
+## GitHub Actions 工作流
+
+### 触发条件
+
+- 推送到 `main` 或 `develop` 分支(当 `scripts` 有变更时)
+- 向 `main` 提交 Pull Request(当 `scripts` 有变更时)
+- 手动触发 workflow
+
+### 作业
+
+#### 1. 单元测试(pytest)
+
+- **运行环境**:Ubuntu latest
+- **Python 版本**:3.10、3.11、3.12
+- **执行内容**:
+ - 从 `requirements-dev.txt` 安装依赖
+ - 运行 pytest 并生成覆盖率报告
+ - 将覆盖率上传到 Codecov
+ - 归档测试结果和 HTML 覆盖率报告
+
+**结果**:如果任何测试失败,工作流失败(关键)
+
+#### 2. 代码质量(Ruff)
+
+- **运行环境**:Ubuntu latest
+- **Python 版本**:3.11
+- **执行内容**:
+ - 使用 `ruff format` 检查格式
+ - 使用 `ruff check` 运行 lint
+ - 报告问题,但不会让整个工作流失败
+
+**结果**:非阻塞(仅警告)
+
+#### 3. 安全扫描(Bandit)
+
+- **运行环境**:Ubuntu latest
+- **Python 版本**:3.11
+- **执行内容**:
+ - 扫描安全漏洞
+ - 生成 JSON 报告
+ - 将报告作为 artifact 上传
+
+**结果**:非阻塞(仅警告)
+
+#### 4. 类型检查(mypy)
+
+- **运行环境**:Ubuntu latest
+- **Python 版本**:3.11
+- **执行内容**:
+ - 执行静态类型分析
+ - 报告类型不匹配
+ - 帮助尽早发现 bug
+
+**结果**:非阻塞(仅警告)
+
+#### 5. 构建 EPUB
+
+- **运行环境**:Ubuntu latest
+- **依赖**:pytest、lint、安全扫描(都必须通过)
+- **执行内容**:
+ - 使用 `scripts/build_epub.py` 构建 EPUB
+ - 验证 EPUB 是否成功生成
+ - 将 EPUB 作为 artifact 上传
+
+**结果**:如果构建失败,工作流失败(关键)
+
+#### 6. 总结
+
+- **运行环境**:Ubuntu latest
+- **依赖**:所有其他作业
+- **执行内容**:
+ - 生成工作流总结
+ - 列出所有 artifacts
+ - 汇总总体状态
+
+## 编写测试
+
+### 测试结构
+
+测试应放在 `scripts/tests/` 中,文件名形如 `test_*.py`:
+
+```python
+# scripts/tests/test_example.py
+import pytest
+from scripts.example_module import some_function
+
+def test_basic_functionality():
+ """测试 some_function 是否正常工作。"""
+ result = some_function("input")
+ assert result == "expected_output"
+
+def test_error_handling():
+ """测试 some_function 是否能优雅处理错误。"""
+ with pytest.raises(ValueError):
+ some_function("invalid_input")
+
+async def test_async_function():
+ """测试异步函数。"""
+ result = await async_function()
+ assert result is not None
+```
+
+### 测试最佳实践
+
+- **使用有描述性的名称**:例如 `test_function_returns_correct_value()`
+- **尽量每个测试只做一个断言**:更容易排查失败原因
+- **使用 fixture** 复用初始化逻辑:见 `scripts/tests/conftest.py`
+- **Mock 外部服务**:使用 `unittest.mock` 或 `pytest-mock`
+- **测试边界情况**:空输入、None 值、错误情况
+- **保持测试快速**:避免 `sleep()` 和外部 I/O
+- **使用 pytest 标记**:例如 `@pytest.mark.slow` 标记慢测试
+
+### Fixtures
+
+常用 fixture 定义在 `scripts/tests/conftest.py`:
+
+```python
+# 在测试中使用 fixture
+def test_something(tmp_path):
+ """tmp_path fixture 提供临时目录。"""
+ test_file = tmp_path / "test.txt"
+ test_file.write_text("content")
+ assert test_file.read_text() == "content"
+```
+
+## 覆盖率报告
+
+### 本地覆盖率
+
+```bash
+# 生成覆盖率报告
+pytest scripts/tests/ --cov=scripts --cov-report=html
+
+# 在浏览器中打开覆盖率报告
+open htmlcov/index.html
+```
+
+### 覆盖率目标
+
+- **最低覆盖率**:80%
+- **分支覆盖率**:启用
+- **重点区域**:核心功能和错误路径
+
+## Pre-commit Hooks
+
+项目使用 pre-commit hooks 在每次提交前自动运行检查:
+
+```bash
+# 安装 pre-commit hooks
+pre-commit install
+
+# 手动运行 hooks
+pre-commit run --all-files
+
+# 跳过某次提交的 hooks(不推荐)
+git commit --no-verify
+```
+
+在 `.pre-commit-config.yaml` 中配置的 hooks:
+- Ruff formatter
+- Ruff linter
+- Bandit security scanner
+- YAML validation
+- 文件大小检查
+- 合并冲突检测
+
+## 排障
+
+### 本地测试通过,但 CI 失败
+
+常见原因:
+1. **Python 版本差异**:CI 使用 3.10、3.11、3.12
+2. **依赖缺失**:更新 `requirements-dev.txt`
+3. **平台差异**:路径分隔符、环境变量
+4. **测试不稳定**:依赖时序或执行顺序的测试
+
+解决方案:
+```bash
+# 使用相同的 Python 版本测试
+uv python install 3.10 3.11 3.12
+
+# 使用干净环境测试
+rm -rf .venv
+uv venv
+uv pip install -r requirements-dev.txt
+pytest scripts/tests/
+```
+
+### Bandit 报告误报
+
+某些安全警告可能是误报。可在 `pyproject.toml` 中配置:
+
+```toml
+[tool.bandit]
+exclude_dirs = ["scripts/tests"]
+skips = ["B101"] # 跳过 assert_used 警告
+```
+
+### 类型检查太严格
+
+对特定文件放宽类型检查:
+
+```python
+# 放在文件顶部
+# type: ignore
+
+# 或者针对特定行
+some_dynamic_code() # type: ignore
+```
+
+## 持续集成最佳实践
+
+1. **保持测试快速**:每个测试最好在 1 秒内完成
+2. **不要测试外部 API**:用 mock 替代外部服务
+3. **测试要隔离**:每个测试都应独立
+4. **断言要清晰**:写 `assert x == 5`,不要写 `assert x`
+5. **处理异步测试**:使用 `@pytest.mark.asyncio`
+6. **生成报告**:覆盖率、安全扫描、类型检查
+
+## 资源
+
+- [pytest Documentation](https://docs.pytest.org/)
+- [Ruff Documentation](https://docs.astral.sh/ruff/)
+- [Bandit Documentation](https://bandit.readthedocs.io/)
+- [mypy Documentation](https://mypy.readthedocs.io/)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+
+## 贡献测试
+
+提交 PR 时:
+
+1. **为新功能编写测试**
+2. **本地运行测试**:`pytest scripts/tests/ -v`
+3. **检查覆盖率**:`pytest scripts/tests/ --cov=scripts`
+4. **运行 lint**:`ruff check scripts/`
+5. **安全扫描**:`bandit -r scripts/ --exclude scripts/tests/`
+6. **如果测试变化,更新文档**
+
+所有 PR 都必须包含测试!🧪
+
+---
+
+如果你对测试有问题或疑问,请在 GitHub 上创建 issue 或 discussion。
diff --git a/zh/.github/pull_request_template.md b/zh/.github/pull_request_template.md
new file mode 100644
index 0000000..03bf75f
--- /dev/null
+++ b/zh/.github/pull_request_template.md
@@ -0,0 +1,57 @@
+## 描述
+简要说明这个 PR 做了什么。
+
+## 变更类型
+- [ ] 新增示例或模板
+- [ ] 文档改进
+- [ ] Bug 修复
+- [ ] 功能指南
+- [ ] 其他(请说明)
+
+## 相关 Issues
+Closes #(issue number)
+
+## 已做的修改
+- 修改 1
+- 修改 2
+- 修改 3
+
+## 需要重点查看的内容
+审阅者应该重点关注什么?
+
+## 变更文件
+- `path/to/file1.md`
+- `path/to/file2.md`
+
+## 测试
+你如何测试的?
+- [ ] 已在 Claude Code 本地测试
+- [ ] 已验证示例可用
+- [ ] 已检查链接和引用
+- [ ] 已检查拼写和清晰度
+
+## 检查清单
+- [ ] 符合项目结构和规范
+- [ ] 包含清晰的文档 / 示例
+- [ ] 代码 / 示例可直接复制使用
+- [ ] 所有链接都已验证且可用
+- [ ] 没有包含敏感信息(密钥、token、凭证)
+- [ ] 已更新相关 README 文件
+- [ ] Commit 信息符合 conventional commit 格式
+- [ ] 没有添加大文件(>1MB)
+
+## 截图或示例
+如有必要,展示这个 PR 增加的内容:
+```
+[示例代码或前后对比]
+```
+
+## 破坏性变更
+这个变更是否影响现有内容或行为?
+- [ ] 没有破坏性变更
+- [ ] 是,并已在下方说明
+
+如果有,请描述:
+
+## 其他说明
+还有哪些信息需要审阅者了解?
diff --git a/zh/01-slash-commands/README.md b/zh/01-slash-commands/README.md
new file mode 100644
index 0000000..29f4523
--- /dev/null
+++ b/zh/01-slash-commands/README.md
@@ -0,0 +1,551 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Slash Commands 参考指南
+
+## 概览
+
+Slash command 是你在 Claude 的交互式会话中用来控制行为的快捷方式,主要分为几类:
+
+- **内置命令**:Claude Code 自带,例如 `/help`、`/clear`、`/model`
+- **Skills**:你自己定义的命令,基于 `SKILL.md` 文件,例如 `/optimize`、`/pr`
+- **插件命令**:来自已安装插件的命令,例如 `/frontend-design:frontend-design`
+- **MCP prompts**:来自 MCP server 的命令,例如 `/mcp__github__list_prs`
+
+> **注意**:自定义 slash command 已经合并进 Skills。`.claude/commands/` 仍然可用,但现在更推荐使用 `.claude/skills/`。两者都会创建 `/command-name` 形式的快捷命令。完整参考请见 [Skills 指南](../03-skills/README.md)。
+
+## 内置命令速查
+
+Claude Code 目前提供 55+ 个内置命令和 5 个内置 Skills。你可以在 Claude Code 中输入 `/` 查看全部,也可以输入 `/` 后继续键入字母进行筛选。
+
+| 命令 | 作用 |
+|---------|---------|
+| `/add-dir <path>` | 添加工作目录 |
+| `/agents` | 管理 agent 配置 |
+| `/branch [name]` | 将当前对话分支到新会话(别名:`/fork`。注意:`/fork` 在 v2.1.77 中更名为 `/branch`) |
+| `/btw <question>` | 额外问题,不写入历史 |
+| `/chrome` | 配置 Chrome 浏览器集成 |
+| `/clear` | 清空对话(别名:`/reset`、`/new`) |
+| `/color [color|default]` | 设置提示栏颜色 |
+| `/compact [instructions]` | 压缩对话,可附带聚焦指令 |
+| `/config` | 打开设置(别名:`/settings`) |
+| `/context` | 用彩色网格可视化上下文占用 |
+| `/copy [N]` | 将 assistant 回复复制到剪贴板;`w` 会写入文件 |
+| `/cost` | 查看 token 使用统计 |
+| `/desktop` | 继续在桌面应用中处理(别名:`/app`) |
+| `/diff` | 查看未提交更改的交互式 diff |
+| `/doctor` | 检查安装健康状态 |
+| `/effort [low|medium|high|max|auto]` | 设置推理强度;`max` 需要 Opus 4.6 |
+| `/exit` | 退出 REPL(别名:`/quit`) |
+| `/export [filename]` | 将当前对话导出为文件或剪贴板内容 |
+| `/extra-usage` | 配置额外用量以应对速率限制 |
+| `/fast [on|off]` | 切换快速模式 |
+| `/feedback` | 提交反馈(别名:`/bug`) |
+| `/help` | 显示帮助 |
+| `/hooks` | 查看 hook 配置 |
+| `/ide` | 管理 IDE 集成 |
+| `/init` | 初始化 `CLAUDE.md`,可设置 `CLAUDE_CODE_NEW_INIT=true` 启用交互式流程 |
+| `/insights` | 生成会话分析报告 |
+| `/install-github-app` | 配置 GitHub Actions app |
+| `/install-slack-app` | 安装 Slack app |
+| `/keybindings` | 打开快捷键配置 |
+| `/login` | 切换 Anthropic 账号 |
+| `/logout` | 退出当前 Anthropic 账号 |
+| `/mcp` | 管理 MCP servers 和 OAuth |
+| `/memory` | 编辑 `CLAUDE.md`,切换自动记忆 |
+| `/mobile` | 生成移动端扫码二维码(别名:`/ios`、`/android`) |
+| `/model [model]` | 选择模型,并可用左右箭头调整 effort |
+| `/passes` | 分享一周免费 Claude Code 使用权 |
+| `/permissions` | 查看或更新权限(别名:`/allowed-tools`) |
+| `/plan [description]` | 进入规划模式 |
+| `/plugin` | 管理插件 |
+| `/pr-comments [PR]` | 获取 GitHub PR 评论 |
+| `/privacy-settings` | 隐私设置(仅 Pro/Max) |
+| `/release-notes` | 查看更新日志 |
+| `/reload-plugins` | 重新加载当前插件 |
+| `/remote-control` | 从 claude.ai 进行远程控制(别名:`/rc`) |
+| `/remote-env` | 配置默认远程环境 |
+| `/rename [name]` | 重命名会话 |
+| `/resume [session]` | 恢复对话(别名:`/continue`) |
+| `/review` | **已弃用**,请改用 `code-review` 插件 |
+| `/rewind` | 回退对话和/或代码(别名:`/checkpoint`) |
+| `/sandbox` | 切换沙盒模式 |
+| `/schedule [description]` | 创建/管理定时任务 |
+| `/security-review` | 分析分支中的安全漏洞 |
+| `/skills` | 列出可用 Skills |
+| `/stats` | 可视化每日使用量、会话和连续天数 |
+| `/status` | 显示版本、模型、账号 |
+| `/statusline` | 配置状态栏 |
+| `/tasks` | 列出/管理后台任务 |
+| `/terminal-setup` | 配置终端快捷键 |
+| `/theme` | 更改颜色主题 |
+| `/vim` | 切换 Vim/Normal 模式 |
+| `/voice` | 切换按住说话语音输入 |
+
+### 内置 Skills
+
+以下 Skills 随 Claude Code 一起提供,调用方式和 slash command 一样:
+
+| Skill | 作用 |
+|-------|---------|
+| `/batch <instruction>` | 使用 worktree 编排大规模并行修改 |
+| `/claude-api` | 加载 Claude API 参考,便于为项目所用语言编写代码 |
+| `/debug [description]` | 启用调试日志 |
+| `/loop [interval] <prompt>` | 按固定间隔重复运行提示词 |
+| `/simplify [focus]` | 审查改动文件的代码质量 |
+
+### 已弃用命令
+
+| 命令 | 状态 |
+|---------|--------|
+| `/review` | 已弃用,已被 `code-review` 插件替代 |
+| `/output-style` | 自 v2.1.73 起弃用 |
+| `/fork` | 已重命名为 `/branch`(别名仍可用,v2.1.77) |
+
+### 最近变化
+
+- `/fork` 已更名为 `/branch`,但保留 `/fork` 作为别名(v2.1.77)
+- `/output-style` 已弃用(v2.1.73)
+- `/review` 已弃用,推荐改用 `code-review` 插件
+- 新增 `/effort`,其中 `max` 级别需要 Opus 4.6
+- 新增 `/voice`,用于按住说话语音输入
+- 新增 `/schedule`,用于创建和管理定时任务
+- 新增 `/color`,用于自定义提示栏颜色
+- `/model` 选择器现在显示人类可读标签,例如 “Sonnet 4.6”
+- `/resume` 支持 `/continue` 别名
+- MCP prompts 可作为 `/mcp__<server>__<prompt>` 命令使用,见 [MCP Prompts as Commands](#mcp-prompts-作为命令)
+
+## 自定义命令(现已归入 Skills)
+
+自定义 slash command 已经**合并到 Skills**。两种方式都可以通过 `/command-name` 调用:
+
+| 方式 | 位置 | 状态 |
+|----------|----------|--------|
+| **Skills(推荐)** | `.claude/skills/<name>/SKILL.md` | 当前标准 |
+| **旧式命令** | `.claude/commands/<name>.md` | 仍可使用 |
+
+如果 skill 和 command 同名,**skill 优先**。例如同时存在 `.claude/commands/review.md` 和 `.claude/skills/review/SKILL.md` 时,会使用 skill 版本。
+
+### 迁移路径
+
+你现有的 `.claude/commands/` 文件可以继续直接使用。若要迁移到 Skills:
+
+**迁移前(Command):**
+```text
+.claude/commands/optimize.md
+```
+
+**迁移后(Skill):**
+```text
+.claude/skills/optimize/SKILL.md
+```
+
+### 为什么用 Skills
+
+- **目录结构**:可以把脚本、模板、参考文件打包在一起
+- **自动触发**:相关场景下 Claude 可以自动调用
+- **调用控制**:可以决定由用户、Claude 或两者共同调用
+- **子 agent 执行**:可在隔离上下文中运行 skill
+- **渐进披露**:只在需要时加载额外文件
+
+### 把自定义命令做成 Skill
+
+创建一个包含 `SKILL.md` 的目录:
+
+```bash
+mkdir -p .claude/skills/my-command
+```
+
+**文件:** `.claude/skills/my-command/SKILL.md`
+
+```yaml
+---
+name: my-command
+description: 这个命令的作用,以及何时使用它
+---
+
+# 我的命令
+
+当该命令被触发时,Claude 需要遵循的说明。
+
+1. 第一步
+2. 第二步
+3. 第三步
+```
+
+### Frontmatter 参考
+
+| 字段 | 作用 | 默认值 |
+|-------|---------|---------|
+| `name` | 命令名(会变成 `/name`) | 目录名 |
+| `description` | 简短说明,帮助 Claude 判断何时使用 | 第一段 |
+| `argument-hint` | 自动补全时显示的参数提示 | 无 |
+| `allowed-tools` | 命令可无权限使用的工具 | 继承 |
+| `model` | 指定要使用的模型 | 继承 |
+| `disable-model-invocation` | 若为 `true`,只有用户能调用,Claude 不能自动调用 | `false` |
+| `user-invocable` | 若为 `false`,不会出现在 `/` 菜单中 | `true` |
+| `context` | 设为 `fork` 时,在隔离 subagent 中运行 | 无 |
+| `agent` | `context: fork` 时使用的 agent 类型 | `general-purpose` |
+| `hooks` | Skill 范围内的 hooks(PreToolUse、PostToolUse、Stop) | 无 |
+
+### 参数
+
+命令可以接收参数:
+
+**使用 `$ARGUMENTS` 接收全部参数:**
+
+```yaml
+---
+name: fix-issue
+description: 根据编号修复 GitHub issue
+---
+
+按团队编码规范修复 #$ARGUMENTS
+```
+
+调用 `/fix-issue 123` 时,`$ARGUMENTS` 会变成 `123`。
+
+**使用 `$0`、`$1` 等接收单个参数:**
+
+```yaml
+---
+name: review-pr
+description: 按优先级审查 PR
+---
+
+审查 #$0,优先级为 $1
+```
+
+调用 `/review-pr 456 high` 时,`$0="456"`,`$1="high"`。
+
+### 用 Shell 命令注入动态上下文
+
+在 prompt 发送前,可用 `!` 命令先执行 shell 命令:
+
+```yaml
+---
+name: commit
+description: 使用上下文创建 git commit
+allowed-tools: Bash(git *)
+---
+
+## 上下文
+
+- 当前 git 状态:!`git status`
+- 当前 diff:!`git diff HEAD`
+- 当前分支:!`git branch --show-current`
+- 最近提交:!`git log --oneline -5`
+
+## 你的任务
+
+根据以上变更,创建一个 git commit。
+```
+
+### 文件引用
+
+使用 `@` 引用文件内容:
+
+```markdown
+审查 @src/utils/helpers.js 中的实现
+比较 @src/old-version.js 和 @src/new-version.js
+```
+
+## 插件命令
+
+插件可以提供自定义命令:
+
+```text
+/plugin-name:command-name
+```
+
+如果没有命名冲突,也可以直接使用 `/command-name`。
+
+**示例:**
+```bash
+/frontend-design:frontend-design
+/commit-commands:commit
+```
+
+## MCP Prompts 作为命令
+
+MCP servers 可以把 prompt 暴露成 slash command:
+
+```text
+/mcp__<server-name>__<prompt-name> [arguments]
+```
+
+**示例:**
+```bash
+/mcp__github__list_prs
+/mcp__github__pr_review 456
+/mcp__jira__create_issue "Bug title" high
+```
+
+### MCP 权限语法
+
+在权限中控制 MCP server 访问:
+
+- `mcp__github` - 访问整个 GitHub MCP server
+- `mcp__github__*` - 通配符访问全部工具
+- `mcp__github__get_issue` - 访问某个特定工具
+
+## 命令架构
+
+```mermaid
+graph TD
+ A["用户输入:/command-name"] --> B{"命令类型?"}
+ B -->|内置| C["执行内置命令"]
+ B -->|Skill| D["加载 SKILL.md"]
+ B -->|插件| E["加载插件命令"]
+ B -->|MCP| F["执行 MCP Prompt"]
+
+ D --> G["解析 Frontmatter"]
+ G --> H["替换变量"]
+ H --> I["执行 Shell 命令"]
+ I --> J["发送给 Claude"]
+ J --> K["返回结果"]
+```
+
+## 命令生命周期
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Claude as Claude Code
+ participant FS as File System
+ participant CLI as Shell/Bash
+
+ User->>Claude: 输入 /optimize
+ Claude->>FS: 搜索 .claude/skills/ 和 .claude/commands/
+ FS-->>Claude: 返回 optimize/SKILL.md
+ Claude->>Claude: 解析 frontmatter
+ Claude->>CLI: 执行 !`command` 替换
+ CLI-->>Claude: 命令输出
+ Claude->>Claude: 替换 $ARGUMENTS
+ Claude->>User: 处理 prompt
+ Claude->>User: 返回结果
+```
+
+## 本文件中的可用命令
+
+这些示例命令可以作为 skill 或旧式命令安装。
+
+### 1. `/optimize` - 代码优化
+
+分析性能问题、内存泄漏和优化机会。
+
+**用法:**
+```text
+/optimize
+[粘贴你的代码]
+```
+
+**文件:** [optimize.md](optimize.md)
+
+### 2. `/pr` - Pull Request 准备
+
+引导你完成 PR 准备清单,包括 lint、测试和提交格式整理。
+
+**用法:**
+```text
+/pr
+```
+
+**文件:** [pr.md](pr.md)
+
+**截图:**
+![/pr](pr-slash-command.png)
+
+### 3. `/generate-api-docs` - API 文档生成器
+
+从源码生成完整的 API 文档。
+
+**用法:**
+```text
+/generate-api-docs
+```
+
+**文件:** [generate-api-docs.md](generate-api-docs.md)
+
+### 4. `/commit` - 带上下文的 Git Commit
+
+基于仓库中的动态上下文创建 git commit。
+
+**用法:**
+```text
+/commit [可选说明]
+```
+
+**文件:** [commit.md](commit.md)
+
+### 5. `/push-all` - 暂存、提交并推送
+
+会先暂存所有改动,再提交,并带安全检查地推送到远端。
+
+**用法:**
+```text
+/push-all
+```
+
+**文件:** [push-all.md](push-all.md)
+
+**安全检查:**
+- 密钥文件:`.env*`、`*.key`、`*.pem`、`credentials.json`
+- API Keys:识别真实 key 与占位符
+- 大文件:未使用 Git LFS 且大于 10MB
+- 构建产物:`node_modules/`、`dist/`、`__pycache__/`
+
+### 6. `/doc-refactor` - 文档重构
+
+重组项目文档,让结构更清晰、可访问性更好。
+
+**文件:** [doc-refactor.md](doc-refactor.md)
+
+### 7. `/setup-ci-cd` - CI/CD 流水线配置
+
+实现 pre-commit hooks 和 GitHub Actions 质量保障流程。
+
+**文件:** [setup-ci-cd.md](setup-ci-cd.md)
+
+### 8. `/unit-test-expand` - 测试覆盖率扩展
+
+针对未测试分支和边界情况,提升测试覆盖率。
+
+**文件:** [unit-test-expand.md](unit-test-expand.md)
+
+## 安装
+
+### 作为 Skills(推荐)
+
+复制到你的 skills 目录:
+
+```bash
+# 创建 skills 目录
+mkdir -p .claude/skills
+
+# 对每个命令文件,创建一个 skill 目录
+for cmd in optimize pr commit; do
+ mkdir -p .claude/skills/$cmd
+ cp 01-slash-commands/$cmd.md .claude/skills/$cmd/SKILL.md
+done
+```
+
+### 作为旧式命令
+
+复制到 commands 目录:
+
+```bash
+# 项目范围(团队)
+mkdir -p .claude/commands
+cp 01-slash-commands/*.md .claude/commands/
+
+# 个人使用
+mkdir -p ~/.claude/commands
+cp 01-slash-commands/*.md ~/.claude/commands/
+```
+
+## 创建你自己的命令
+
+### Skill 模板(推荐)
+
+创建 `.claude/skills/my-command/SKILL.md`:
+
+```yaml
+---
+name: my-command
+description: 这个命令做什么。用于 [触发条件]。
+argument-hint: [可选参数]
+allowed-tools: Bash(npm *), Read, Grep
+---
+
+# Command Title
+
+## 上下文
+
+- 当前分支:!`git branch --show-current`
+- 相关文件:@package.json
+
+## 指令
+
+1. 第一步
+2. 第二步,参数:$ARGUMENTS
+3. 第三步
+
+## 输出格式
+
+- 如何格式化回复
+- 需要包含什么
+```
+
+### 仅用户可调用的命令(无自动触发)
+
+对于带副作用、Claude 不应自动触发的命令:
+
+```yaml
+---
+name: deploy
+description: 部署到生产环境
+disable-model-invocation: true
+allowed-tools: Bash(npm *), Bash(git *)
+---
+
+将应用部署到生产环境:
+
+1. 运行测试
+2. 构建应用
+3. 推送到部署目标
+4. 验证部署
+```
+
+## 最佳实践
+
+| 应该做 | 不要做 |
+|------|---------|
+| 使用清晰、以动作导向的命名 | 为一次性任务创建命令 |
+| 在 `description` 中写清触发条件 | 在命令里写太复杂的逻辑 |
+| 保持命令聚焦于单一任务 | 硬编码敏感信息 |
+| 有副作用时使用 `disable-model-invocation` | 跳过 description 字段 |
+| 用 `!` 前缀注入动态上下文 | 假设 Claude 知道当前状态 |
+| 把相关文件组织进 skill 目录 | 所有内容都塞进一个文件 |
+
+## 故障排查
+
+### 找不到命令
+
+**解决办法:**
+- 检查文件是否位于 `.claude/skills/<name>/SKILL.md` 或 `.claude/commands/<name>.md`
+- 确认 frontmatter 中的 `name` 与预期命令名一致
+- 重启 Claude Code 会话
+- 运行 `/help` 查看可用命令
+
+### 命令没有按预期执行
+
+**解决办法:**
+- 补充更具体的指令
+- 在 skill 文件中加入示例
+- 如果使用 bash 命令,检查 `allowed-tools`
+- 先用简单输入测试
+
+### Skill 与 Command 冲突
+
+如果同名同时存在,**skill 优先**。删除其中一个或重命名即可。
+
+## 相关指南
+
+- **[Skills](../03-skills/README.md)** - 完整的 Skills 参考
+- **[Memory](../02-memory/README.md)** - 带 `CLAUDE.md` 的持久上下文
+- **[Subagents](../04-subagents/README.md)** - 委派式 AI agents
+- **[Plugins](../07-plugins/README.md)** - 打包好的命令集合
+- **[Hooks](../06-hooks/README.md)** - 事件驱动自动化
+
+## 其他资源
+
+- [官方交互模式文档](https://code.claude.com/docs/en/interactive-mode) - 内置命令参考
+- [官方 Skills 文档](https://code.claude.com/docs/en/skills) - 完整 Skills 参考
+- [CLI Reference](https://code.claude.com/docs/en/cli-reference) - 命令行选项
+
+---
+
+*Claude How To 指南系列的一部分*
diff --git a/zh/01-slash-commands/commit.md b/zh/01-slash-commands/commit.md
new file mode 100644
index 0000000..99d6fa2
--- /dev/null
+++ b/zh/01-slash-commands/commit.md
@@ -0,0 +1,26 @@
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*)
+argument-hint: [message]
+description: 创建带上下文的 Git 提交
+---
+
+## 上下文
+
+- 当前 git 状态: !`git status`
+- 当前 git diff: !`git diff HEAD`
+- 当前分支: !`git branch --show-current`
+- 最近的提交: !`git log --oneline -10`
+
+## 你的任务
+
+根据上面的变更创建一个单独的 Git 提交。
+
+如果通过参数传入了 message,就直接使用它:$ARGUMENTS
+
+否则,分析这些变更,并按照 conventional commits 格式生成合适的提交信息:
+- `feat:` 新功能
+- `fix:` 修复 bug
+- `docs:` 文档变更
+- `refactor:` 代码重构
+- `test:` 新增测试
+- `chore:` 维护任务
diff --git a/zh/01-slash-commands/doc-refactor.md b/zh/01-slash-commands/doc-refactor.md
new file mode 100644
index 0000000..4569912
--- /dev/null
+++ b/zh/01-slash-commands/doc-refactor.md
@@ -0,0 +1,24 @@
+---
+name: 文档重构
+description: 为项目重新组织文档结构,以提升清晰度和可访问性
+tags: documentation, refactoring, organization
+---
+
+# 文档重构
+
+根据项目类型重构项目文档结构:
+
+1. **分析项目**:识别类型(库/API/Web 应用/CLI/微服务)、架构和用户角色
+2. **集中管理文档**:将技术文档迁移到 `docs/`,并保留正确的交叉引用
+3. **整理根目录 README.md**:将其精简为入口页,包含概览、快速开始、模块/组件摘要、许可证和联系方式
+4. **为组件补充文档**:添加模块/包/服务级别的 README 文件,包含安装和测试说明
+5. **按主题组织 `docs/`**:
+ - 架构、API Reference、数据库、设计、故障排查、部署、贡献(根据项目需要调整)
+6. **创建指南**(按需选择):
+ - 用户指南:面向应用最终用户的文档
+ - API 文档:API 的端点、认证和示例
+ - 开发指南:环境搭建、测试、贡献流程
+ - 部署指南:服务/应用的生产部署
+7. **所有图表都使用 Mermaid**(架构图、流程图、Schema 图)
+
+保持文档简洁、易扫读,并与项目类型保持上下文一致。
diff --git a/zh/01-slash-commands/generate-api-docs.md b/zh/01-slash-commands/generate-api-docs.md
new file mode 100644
index 0000000..8075f67
--- /dev/null
+++ b/zh/01-slash-commands/generate-api-docs.md
@@ -0,0 +1,19 @@
+---
+description: 根据源代码生成完整的 API 文档
+---
+
+# API 文档生成器
+
+按以下步骤生成 API 文档:
+
+1. 扫描 `/src/api/` 下的所有文件
+2. 提取函数签名和 JSDoc 注释
+3. 按端点/模块进行组织
+4. 生成带示例的 Markdown
+5. 包含请求/响应 Schema
+6. 添加错误文档
+
+输出格式:
+- 输出为 `/docs/api.md` 中的 Markdown 文件
+- 为所有端点加入 curl 示例
+- 添加 TypeScript 类型
diff --git a/zh/01-slash-commands/optimize.md b/zh/01-slash-commands/optimize.md
new file mode 100644
index 0000000..e8ebe08
--- /dev/null
+++ b/zh/01-slash-commands/optimize.md
@@ -0,0 +1,19 @@
+---
+description: 分析代码中的性能问题并提出优化建议
+---
+
+# 代码优化
+
+按优先级审查提供的代码,重点关注以下问题:
+
+1. **性能瓶颈** - 识别 O(n²) 操作和低效循环
+2. **内存泄漏** - 查找未释放的资源、循环引用
+3. **算法改进** - 建议更好的算法或数据结构
+4. **缓存机会** - 识别重复计算
+5. **并发问题** - 查找竞态条件或线程问题
+
+请按以下格式输出:
+- 问题严重性(Critical/High/Medium/Low)
+- 代码位置
+- 解释
+- 推荐修复方案,附代码示例
diff --git a/zh/01-slash-commands/pr.md b/zh/01-slash-commands/pr.md
new file mode 100644
index 0000000..81dfdec
--- /dev/null
+++ b/zh/01-slash-commands/pr.md
@@ -0,0 +1,26 @@
+---
+description: 清理代码、暂存变更并准备 Pull Request
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(npm test:*), Bash(npm run lint:*)
+---
+
+# Pull Request 准备清单
+
+在创建 PR 之前,请执行以下步骤:
+
+1. 运行格式化:`prettier --write .`
+2. 运行测试:`npm test`
+3. 查看 git diff:`git diff HEAD`
+4. 暂存变更:`git add .`
+5. 按 conventional commits 创建提交信息:
+ - `fix:` bug 修复
+ - `feat:` 新功能
+ - `docs:` 文档
+ - `refactor:` 代码重构
+ - `test:` 测试新增
+ - `chore:` 维护
+
+6. 生成 PR 摘要,包含:
+ - 变更了什么
+ - 为什么变更
+ - 做了哪些测试
+ - 可能的影响
diff --git a/zh/01-slash-commands/push-all.md b/zh/01-slash-commands/push-all.md
new file mode 100644
index 0000000..6974c32
--- /dev/null
+++ b/zh/01-slash-commands/push-all.md
@@ -0,0 +1,152 @@
+---
+description: 暂存所有变更,创建提交并推送到远程(请谨慎使用)
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git push:*), Bash(git diff:*), Bash(git log:*), Bash(git pull:*)
+---
+
+# 提交并推送全部内容
+
+⚠️ **注意**:将所有变更都暂存、提交并推送到远程。只有在你确认所有改动都应该放在一起时才使用。
+
+## 工作流
+
+### 1. 分析变更
+并行运行:
+- `git status` - 显示已修改/已添加/已删除/未跟踪文件
+- `git diff --stat` - 显示变更统计
+- `git log -1 --oneline` - 查看最近一次提交,便于统一提交信息风格
+
+### 2. 安全检查
+
+**❌ 如果发现以下内容,立即停止并警告:**
+- Secrets:`.env*`、`*.key`、`*.pem`、`credentials.json`、`secrets.yaml`、`id_rsa`、`*.p12`、`*.pfx`、`*.cer`
+- API Keys:任何 `*_API_KEY`、`*_SECRET`、`*_TOKEN` 变量包含真实值,而不是占位符,如 `your-api-key`、`xxx`、`placeholder`
+- 大文件:`>10MB` 且未使用 Git LFS
+- 构建产物:`node_modules/`、`dist/`、`build/`、`__pycache__/`、`*.pyc`、`.venv/`
+- 临时文件:`.DS_Store`、`thumbs.db`、`*.swp`、`*.tmp`
+
+**API Key 校验:**
+检查修改文件中是否存在以下模式:
+```bash
+OPENAI_API_KEY=sk-proj-xxxxx # ❌ 检测到真实密钥!
+AWS_SECRET_KEY=AKIA... # ❌ 检测到真实密钥!
+STRIPE_API_KEY=sk_live_... # ❌ 检测到真实密钥!
+
+# ✅ 可接受的占位符:
+API_KEY=your-api-key-here
+SECRET_KEY=placeholder
+TOKEN=xxx
+API_KEY=<your-key>
+SECRET=${YOUR_SECRET}
+```
+
+**✅ 确认:**
+- `.gitignore` 配置正确
+- 没有合并冲突
+- 分支正确(如果是 `main`/`master` 要提醒)
+- API key 只是占位符
+
+### 3. 请求确认
+
+展示摘要:
+```
+📊 变更摘要:
+- X 个文件已修改,Y 个文件已新增,Z 个文件已删除
+- 总计:+AAA 行新增,-BBB 行删除
+
+🔒 安全性:✅ 无 secrets | ✅ 无大文件 | ⚠️ [警告]
+🌿 分支: [name] → origin/[name]
+
+我将执行:git add . → commit → push
+
+请输入 'yes' 继续,或输入 'no' 取消。
+```
+
+**在收到明确的 "yes" 之前不要继续。**
+
+### 4. 执行(确认后)
+
+按顺序运行:
+```bash
+git add .
+git status # 验证暂存状态
+```
+
+### 5. 生成提交信息
+
+分析变更并创建 conventional commit:
+
+**格式:**
+```
+[type]: 简要摘要(最多 72 个字符)
+
+- 关键改动 1
+- 关键改动 2
+- 关键改动 3
+```
+
+**类型:** `feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`、`perf`、`build`、`ci`
+
+**示例:**
+```
+docs: 更新概念文档,补充完整说明
+
+- 添加架构图和表格
+- 补充实用示例
+- 扩展最佳实践部分
+```
+
+### 6. 提交并推送
+
+```bash
+git commit -m "$(cat <<'EOF'
+[生成的提交信息]
+EOF
+)"
+git push # 如果失败:git pull --rebase && git push
+git log -1 --oneline --decorate # 验证
+```
+
+### 7. 确认成功
+
+```
+✅ 已成功推送到远程!
+
+Commit: [hash] [message]
+Branch: [branch] → origin/[branch]
+Files changed: X (+insertions, -deletions)
+```
+
+## 错误处理
+
+- `git add` 失败:检查权限、锁定文件,确认仓库已初始化
+- `git commit` 失败:修复 pre-commit hooks,检查 git 配置(user.name/email)
+- `git push` 失败:
+ - 非快进:`git pull --rebase && git push`
+ - 没有远程分支:`git push -u origin [branch]`
+ - 受保护分支:改用 PR 工作流
+
+## 适用场景
+
+✅ **适合:**
+- 多文件文档更新
+- 同时包含测试和文档的功能
+- 跨多个文件的 bug 修复
+- 项目级格式化/重构
+- 配置变更
+
+❌ **避免:**
+- 不确定要提交哪些内容
+- 包含 secrets/敏感数据
+- 受保护分支且未经过审核
+- 存在合并冲突
+- 想保留更细粒度的提交历史
+- pre-commit hooks 失败
+
+## 替代方案
+
+如果用户想保留控制权,可以建议:
+1. **选择性暂存**:查看并暂存特定文件
+2. **交互式暂存**:使用 `git add -p` 逐块选择
+3. **PR 工作流**:创建分支 → 推送 → 发起 PR(使用 `/pr` 命令)
+
+**⚠️ 记住**:在推送前始终先检查变更。拿不准时,使用单独的 git 命令会更可控。
diff --git a/zh/01-slash-commands/setup-ci-cd.md b/zh/01-slash-commands/setup-ci-cd.md
new file mode 100644
index 0000000..7e21df8
--- /dev/null
+++ b/zh/01-slash-commands/setup-ci-cd.md
@@ -0,0 +1,25 @@
+---
+name: 设置 CI/CD 流水线
+description: 实现 pre-commit hooks 和 GitHub Actions 质量保障
+tags: ci-cd, devops, automation
+---
+
+# 设置 CI/CD 流水线
+
+根据项目类型实现完整的 DevOps 质量门禁:
+
+1. **分析项目**:检测语言、框架、构建系统和现有工具链
+2. **配置 pre-commit hooks**,使用与语言匹配的工具:
+ - 格式化:Prettier/Black/gofmt/rustfmt 等
+ - 代码检查:ESLint/Ruff/golangci-lint/Clippy 等
+ - 安全:Bandit/gosec/cargo-audit/npm audit 等
+ - 类型检查:TypeScript/mypy/flow(如适用)
+ - 测试:运行相关测试套件
+3. **创建 GitHub Actions 工作流**(`.github/workflows/`):
+ - 在 push/PR 时镜像 pre-commit 检查
+ - 多版本/多平台矩阵(如适用)
+ - 构建和测试验证
+ - 部署步骤(如需要)
+4. **验证流水线**:本地测试、创建测试 PR,确认所有检查都通过
+
+使用免费/开源工具。尊重已有配置。保持执行快速。
diff --git a/zh/01-slash-commands/unit-test-expand.md b/zh/01-slash-commands/unit-test-expand.md
new file mode 100644
index 0000000..9867ec0
--- /dev/null
+++ b/zh/01-slash-commands/unit-test-expand.md
@@ -0,0 +1,25 @@
+---
+name: 扩充单元测试
+description: 通过覆盖未测试分支和边界情况来提高测试覆盖率
+tags: testing, coverage, unit-tests
+---
+
+# 扩充单元测试
+
+根据项目的测试框架,扩充现有单元测试:
+
+1. **分析覆盖率**:运行覆盖率报告,找出未测试分支、边界情况和低覆盖区域
+2. **识别缺口**:审查代码中的逻辑分支、错误路径、边界条件、空值/空输入
+3. **编写测试**,使用项目现有框架:
+ - Jest/Vitest/Mocha(JavaScript/TypeScript)
+ - pytest/unittest(Python)
+ - Go testing/testify(Go)
+ - Rust test framework(Rust)
+4. **针对具体场景**:
+ - 错误处理和异常
+ - 边界值(最小/最大、空值、空输入)
+ - 边缘情况和极端情况
+ - 状态转换和副作用
+5. **验证提升**:再次运行覆盖率,确认有可衡量的提升
+
+只展示新增的测试代码块。遵循现有测试模式和命名约定。
diff --git a/zh/02-memory/README.md b/zh/02-memory/README.md
new file mode 100644
index 0000000..5bc1734
--- /dev/null
+++ b/zh/02-memory/README.md
@@ -0,0 +1,305 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Memory 指南
+
+## 概览
+
+Memory 让 Claude Code 在不同会话之间保留上下文。你可以把团队规范、项目规则、个人偏好和目录级约束写进 `CLAUDE.md`,让 Claude 在合适的时候自动加载。
+
+## Memory 命令速查
+
+| 命令 | 作用 |
+|------|------|
+| `/init` | 初始化项目级 `CLAUDE.md` |
+| `/memory` | 打开并编辑记忆文件 |
+| `#` | 快速把当前规则写入 memory |
+
+## 快速上手:初始化 Memory
+
+### 使用 `/init`
+
+在项目目录中运行:
+
+```bash
+/init
+```
+
+Claude 会根据当前项目生成一个 `CLAUDE.md`,通常包含类似如下结构:
+
+```md
+# 项目配置
+## 项目概览
+## 开发规范
+```
+
+### 使用 `#` 快速更新记忆
+
+当你想把一句规则写入 memory 时,可以直接在输入前加 `#`:
+
+```text
+# 这个项目始终使用 TypeScript 严格模式
+# 优先使用 async/await,而不是 promise 链
+# 每次提交前都运行 npm test
+# 文件名统一使用 kebab-case
+```
+
+这会把规则加入当前会话能感知到的记忆中。
+
+### 使用 `/memory`
+
+`/memory` 会打开记忆编辑器,让你在不同范围之间切换:
+
+1. 受管策略记忆
+2. 项目记忆(`./CLAUDE.md`)
+3. 用户记忆(`~/.claude/CLAUDE.md`)
+4. 本地项目记忆
+
+适合你把长期规则、项目规范和个人偏好分层管理。
+
+## Memory 架构
+
+Claude Code 的记忆系统通常有以下层级:
+
+| 层级 | 作用范围 | 典型内容 |
+|------|----------|----------|
+| 受管策略 | 组织级 | 合规、安全、统一流程 |
+| 项目记忆 | 单个项目 | 架构、编码标准、工作流 |
+| 目录记忆 | 子目录 | 模块约束、局部规范 |
+| 用户记忆 | 单个用户 | 个人偏好、默认设置 |
+
+## 记忆层级
+
+Claude 会按更接近当前上下文的规则优先使用更具体的 memory。一般来说:
+
+- 组织级规则优先于普通偏好
+- 项目规则优先于个人偏好
+- 目录级规则优先于项目级通用规则
+
+## 排除规则
+
+如果某些 `CLAUDE.md` 不应该被自动加载,可以通过 `claudeMdExcludes` 之类的设置排除。
+
+## 配置文件层级
+
+项目设置、用户设置和企业托管设置会共同影响 memory 的加载方式。你可以把它理解为:
+
+1. 组织策略
+2. 项目设置
+3. 本地设置
+4. 临时会话输入
+
+## 模块化规则系统
+
+Memory 不一定要写成一个巨大文件。你可以把规则拆成多个目录文件,再按路径组织。
+
+### 通过 YAML frontmatter 设置路径规则
+
+```md
+---
+description: API development rules
+---
+
+# API Development Rules
+```
+
+### 子目录与符号链接
+
+你可以用子目录和 symlink 把局部规则复用到多个项目区域。
+
+## Memory 位置表
+
+常见位置包括:
+
+- 项目根目录的 `CLAUDE.md`
+- 用户目录的 `~/.claude/CLAUDE.md`
+- 子目录的 `CLAUDE.md`
+
+## Memory 更新生命周期
+
+一般流程是:
+
+1. 创建或编辑 `CLAUDE.md`
+2. Claude 重新加载
+3. 新规则在后续会话中生效
+
+## Auto Memory
+
+Auto memory 让 Claude 根据当前目录自动寻找并加载合适的记忆文件。
+
+### 工作方式
+
+Claude 会根据当前工作目录、父目录和已配置路径,逐层查找相关 memory。
+
+### 目录结构
+
+```text
+project/
+├── CLAUDE.md
+├── src/
+│ ├── CLAUDE.md
+│ └── api/
+│ └── CLAUDE.md
+```
+
+### 版本要求
+
+某些 auto memory 行为依赖较新的 Claude Code 版本。
+
+### 自定义 auto memory 目录
+
+如果默认目录不适合你的项目,可以在设置中指定新的 memory 路径。
+
+### worktree 和仓库共享
+
+在 worktree、monorepo 或多人协作场景中,auto memory 可以帮助保持规则一致。
+
+### Subagent 记忆
+
+Subagents 也可以拥有自己的记忆范围,用于在各自职责内保持一致性。
+
+### 控制 auto memory
+
+```bash
+# 当前会话禁用 auto memory
+
+# 显式开启 auto memory
+```
+
+## 通过 `--add-dir` 添加额外目录
+
+你可以用 `--add-dir` 把额外目录也加入 Claude 的可见范围,适合多目录协作。
+
+## 实战示例
+
+### 示例 1:项目记忆结构
+
+```md
+# 项目配置
+## 项目概览
+## 架构
+## 开发规范
+### 代码风格
+### 命名约定
+### Git 工作流
+### 测试要求
+### API 规范
+### 数据库
+### 部署
+## 常用命令
+## 团队联系人
+## 已知问题与解决办法
+## 相关项目
+```
+
+### 示例 2:目录级记忆
+
+```md
+# API 模块规范
+## API 专属规范
+### 请求校验
+### 身份验证
+### 响应格式
+### 分页
+### 限流
+### 缓存
+```
+
+### 示例 3:个人记忆
+
+```md
+# 我的开发偏好
+## 关于我
+## 代码偏好
+### 错误处理
+### 注释
+### 测试
+### 架构
+## 调试偏好
+## 沟通方式
+## 项目组织
+## 工具链
+```
+
+### 示例 4:会话中更新记忆
+
+两种常见方式:
+
+1. 直接提要求,让 Claude 把规则写进 memory
+2. 使用 `# new rule into memory` 这种模式追加规则
+
+## 最佳实践
+
+### 应该做的
+
+- 用项目记忆保存团队标准
+- 用目录记忆保存局部差异
+- 先写简洁规则,再逐步补充
+- 把可重复内容写进 `CLAUDE.md`
+
+### 不应该做的
+
+- 不要把 README 整份复制进 `CLAUDE.md`
+- 不要把明显属于代码的实现细节硬塞进 memory
+- 不要让 memory 变成垃圾桶
+
+### 记忆管理建议
+
+- 优先引用已有文档,而不是重复粘贴
+- 只保留真正影响 Claude 行为的信息
+- 定期整理过期或冲突的规则
+
+## 安装说明
+
+### 设置项目记忆
+
+#### 方法 1:使用 `/init`(推荐)
+
+```bash
+/init
+```
+
+#### 方法 2:手动创建
+
+```bash
+cp project-CLAUDE.md CLAUDE.md
+```
+
+#### 方法 3:快速更新
+
+```text
+# Use semantic versioning for all releases
+# Always run tests before committing
+# Prefer composition over inheritance
+```
+
+### 设置个人记忆
+
+```bash
+cp personal-CLAUDE.md ~/.claude/CLAUDE.md
+```
+
+### 设置目录记忆
+
+```bash
+cp directory-api-CLAUDE.md src/api/CLAUDE.md
+```
+
+### 验证安装
+
+- 重新打开 Claude Code 会话
+- 检查 `CLAUDE.md` 是否被自动加载
+- 用一条明显会受 memory 影响的提示词测试
+
+## 官方文档
+
+如果你想看更详细的行为定义、兼容性和最新限制,建议参考 Claude Code 官方 memory 文档。
+
+## 相关概念
+
+- [Slash Commands 中文参考](../01-slash-commands/README.md)
+- [Skills 中文指南](../03-skills/README.md)
+- [Subagents 中文参考](../04-subagents/README.md)
+- [Advanced Features 中文指南](../09-advanced-features/README.md)
diff --git a/zh/02-memory/directory-api-CLAUDE.md b/zh/02-memory/directory-api-CLAUDE.md
new file mode 100644
index 0000000..200187d
--- /dev/null
+++ b/zh/02-memory/directory-api-CLAUDE.md
@@ -0,0 +1,62 @@
+# API 模块规范
+
+本文件会覆盖 `/src/api/` 下所有内容对应的根目录 `CLAUDE.md`。
+
+## API 专属规范
+
+### 请求校验
+- 使用 Zod 做 schema 校验
+- 始终校验输入
+- 校验失败时返回 400
+- 提供字段级别的错误详情
+
+### 认证
+- 所有端点都需要 JWT token
+- token 放在 `Authorization` header 中
+- token 24 小时后过期
+- 实现 refresh token 机制
+
+### 响应格式
+
+所有响应都必须遵循下面的结构:
+
+```json
+{
+ "success": true,
+ "data": { /* 实际数据 */ },
+ "timestamp": "2025-11-06T10:30:00Z",
+ "version": "1.0"
+}
+```
+
+错误响应:
+
+```json
+{
+ "success": false,
+ "error": {
+ "code": "VALIDATION_ERROR",
+ "message": "用户可读消息",
+ "details": { /* 字段错误 */ }
+ },
+ "timestamp": "2025-11-06T10:30:00Z"
+}
+```
+
+### 分页
+- 使用基于 cursor 的分页,而不是 offset
+- 包含 `hasMore` 布尔值
+- 单页最大数量限制为 100
+- 默认页大小:20
+
+### 限流
+- 已认证用户每小时 1000 次请求
+- 公开端点每小时 100 次请求
+- 超出时返回 429
+- 包含 `retry-after` header
+
+### 缓存
+- 使用 Redis 做会话缓存
+- 缓存时长默认 5 分钟
+- 写操作时失效缓存
+- 用资源类型给缓存键打标签
diff --git a/zh/02-memory/personal-CLAUDE.md b/zh/02-memory/personal-CLAUDE.md
new file mode 100644
index 0000000..9a5c612
--- /dev/null
+++ b/zh/02-memory/personal-CLAUDE.md
@@ -0,0 +1,61 @@
+# 我的开发偏好
+
+## 关于我
+- **经验水平**:8 年全栈开发经验
+- **偏好语言**:TypeScript、Python
+- **沟通风格**:直接,最好带例子
+- **学习风格**:配合代码的可视化图示
+
+## 代码偏好
+
+### 错误处理
+我偏好显式的错误处理,使用 `try-catch` 和有意义的错误消息。
+避免使用泛化错误。为了便于调试,始终记录错误日志。
+
+### 注释
+注释应解释“为什么”,而不是“是什么”。代码本身应该尽量能自解释。
+注释应该说明业务逻辑或者不明显的设计决策。
+
+### 测试
+我偏好 TDD(测试驱动开发)。
+先写测试,再写实现。
+重点关注行为,而不是实现细节。
+
+### 架构
+我偏好模块化、低耦合的设计。
+使用依赖注入提升可测试性。
+拆分关注点,例如 Controllers、Services、Repositories。
+
+## 调试偏好
+- 使用带前缀的 `console.log`:`[DEBUG]`
+- 包含上下文:函数名、相关变量
+- 如果有堆栈信息,优先使用
+- 日志里始终带时间戳
+
+## 沟通方式
+- 用图示解释复杂概念
+- 先给具体例子,再讲理论
+- 提供修改前 / 修改后的代码片段
+- 在结尾总结关键点
+
+## 项目组织
+我通常会这样组织项目:
+
+```text
+project/
+ ├── src/
+ │ ├── api/
+ │ ├── services/
+ │ ├── models/
+ │ └── utils/
+ ├── tests/
+ ├── docs/
+ └── docker/
+```
+
+## 工具链
+- **IDE**:VS Code,带 vim 键位
+- **终端**:Zsh + Oh-My-Zsh
+- **格式化**:Prettier,行宽 100 字符
+- **Linter**:ESLint,airbnb 配置
+- **测试框架**:Jest + React Testing Library
diff --git a/zh/02-memory/project-CLAUDE.md b/zh/02-memory/project-CLAUDE.md
new file mode 100644
index 0000000..57114e0
--- /dev/null
+++ b/zh/02-memory/project-CLAUDE.md
@@ -0,0 +1,88 @@
+# 项目配置
+
+## 项目概览
+- **名称**:电商平台
+- **技术栈**:Node.js、PostgreSQL、React 18、Docker
+- **团队规模**:5 名开发者
+- **截止时间**:2025 年第 4 季度
+
+## 架构
+@docs/architecture.md
+@docs/api-standards.md
+@docs/database-schema.md
+
+## 开发规范
+
+### 代码风格
+- 使用 Prettier 格式化
+- 使用带 airbnb 配置的 ESLint
+- 最大行长度:100 字符
+- 使用 2 空格缩进
+
+### 命名规范
+- **文件**:kebab-case(`user-controller.js`)
+- **类**:PascalCase(`UserService`)
+- **函数 / 变量**:camelCase(`getUserById`)
+- **常量**:UPPER_SNAKE_CASE(`API_BASE_URL`)
+- **数据库表**:snake_case(`user_accounts`)
+
+### Git 工作流
+- 分支命名:`feature/description` 或 `fix/description`
+- 提交信息:遵循 conventional commits
+- 合并前必须有 PR
+- 所有 CI/CD 检查都必须通过
+- 至少需要 1 个 approval
+
+### 测试要求
+- 最低 80% 代码覆盖率
+- 所有关键路径都必须有测试
+- 单元测试使用 Jest
+- E2E 测试使用 Cypress
+- 测试文件名:`*.test.ts` 或 `*.spec.ts`
+
+### API 规范
+- 只允许 RESTful 端点
+- 请求 / 响应都使用 JSON
+- 正确使用 HTTP 状态码
+- API 版本路径:`/api/v1/`
+- 所有端点都要带示例文档
+
+### 数据库
+- schema 变更使用 migrations
+- 绝不硬编码凭据
+- 使用连接池
+- 开发环境启用查询日志
+- 需要定期备份
+
+### 部署
+- 基于 Docker 的部署
+- 使用 Kubernetes 编排
+- 蓝绿部署策略
+- 失败时自动回滚
+- 部署前先执行数据库迁移
+
+## 常用命令
+
+| 命令 | 作用 |
+|---------|---------|
+| `npm run dev` | 启动开发服务器 |
+| `npm test` | 运行测试套件 |
+| `npm run lint` | 检查代码风格 |
+| `npm run build` | 构建生产版本 |
+| `npm run migrate` | 执行数据库迁移 |
+
+## 团队联系人
+- 技术负责人:Sarah Chen(@sarah.chen)
+- 产品经理:Mike Johnson(@mike.j)
+- 运维:Alex Kim(@alex.k)
+
+## 已知问题与解决方案
+- PostgreSQL 连接池在高峰期限制为 20
+- 解决方法:实现查询排队
+- Safari 14 对 async generator 的兼容性有问题
+- 解决方法:使用 Babel 转译器
+
+## 关联项目
+- 分析仪表盘:`/projects/analytics`
+- 移动端 App:`/projects/mobile`
+- 管理后台:`/projects/admin`
diff --git a/zh/03-skills/README.md b/zh/03-skills/README.md
new file mode 100644
index 0000000..00bf0d1
--- /dev/null
+++ b/zh/03-skills/README.md
@@ -0,0 +1,271 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Agent Skills 指南
+
+## 概览
+
+Skills 是可以复用、可自动触发的能力包。一个 skill 通常包含 `SKILL.md`、参考文件、脚本和模板。Claude 在合适的场景下会自动加载它。
+
+### 主要好处
+
+- 可复用
+- 可渐进加载
+- 可以把脚本、模板、说明放在一起
+- 适合标准化流程
+
+## Skills 的工作方式:渐进式披露
+
+Skills 不会一次性把所有内容都塞进上下文,而是按需加载。
+
+### 三层加载
+
+1. **只看描述**:先判断这个 skill 是否相关
+2. **加载 `SKILL.md`**:读取核心说明
+3. **按需加载支持文件**:脚本、模板、参考资料
+
+## Skill 加载流程
+
+1. Claude 扫描技能目录
+2. 根据描述判断是否匹配当前任务
+3. 读取 `SKILL.md`
+4. 如有需要,再加载脚本和辅助文件
+
+## Skill 类型与位置
+
+Skills 可以放在:
+
+- 项目目录下的 `.claude/skills/`
+- 用户目录下的 `~/.claude/skills/`
+
+### 自动发现
+
+只要目录结构正确,Claude 就会自动发现这些 Skills。
+
+## 创建自定义 Skills
+
+### 基本目录结构
+
+```text
+my-skill/
+└── SKILL.md
+```
+
+### `SKILL.md` 格式
+
+```yaml
+---
+name: my-skill
+description: 这个 skill 的用途,以及什么时候触发
+---
+
+# Your Skill Name
+
+## Instructions
+
+## Examples
+```
+
+### 必填字段
+
+- `name`
+- `description`
+
+### 可选 frontmatter 字段
+
+- `argument-hint`
+- `allowed-tools`
+- `model`
+- `disable-model-invocation`
+- `user-invocable`
+- `context`
+- `agent`
+- `hooks`
+
+## Skill 内容类型
+
+### 参考内容
+
+适合放规则、标准、文档片段和示例。
+
+### 任务内容
+
+适合放具体步骤、执行流程和结果格式要求。
+
+## 控制 Skill 的调用
+
+你可以通过 `disable-model-invocation`、`user-invocable` 和工具白名单来控制 Claude 是否能自动调用这个 skill。
+
+## 字符串替换
+
+Skills 支持 `$ARGUMENTS`、`$0`、`$1` 等参数替换。
+
+### 动态上下文注入
+
+你可以在 prompt 里插入 shell 命令结果:
+
+```md
+- 当前 git 状态:!`git status`
+- 当前 diff:!`git diff HEAD`
+- 当前分支:!`git branch --show-current`
+```
+
+## 在 subagent 中运行 Skills
+
+某些 skill 适合在隔离上下文中运行,这样可以降低对主会话的影响。
+
+## 实战示例
+
+### 示例 1:代码审查 Skill
+
+一个典型的审查 skill 会包含:
+
+- 审查模板
+- 风险等级
+- 输出格式
+- 需要关注的维度
+
+### 示例 2:代码库可视化 Skill
+
+可以把代码库结构、依赖关系和模块边界总结给 Claude,便于快速理解。
+
+### 示例 3:部署 Skill(只允许用户触发)
+
+适合带副作用的操作,比如生产环境部署。通常会配合 `disable-model-invocation: true`。
+
+### 示例 4:品牌语气 Skill
+
+用于检查输出是否符合品牌语气、语调和表达风格。
+
+### 示例 5:`CLAUDE.md` 生成 Skill
+
+可以从项目文档中生成或补充 `CLAUDE.md`。
+
+### 示例 6:带脚本的重构 Skill
+
+常见组合是:
+
+- `SKILL.md`
+- `scripts/`
+- `templates/`
+- `references/`
+
+## 管理 Skills
+
+### 查看可用 Skills
+
+```bash
+/skills
+```
+
+### 测试一个 Skill
+
+把它放到测试目录或者临时项目里,然后通过相应命令触发。
+
+### 更新 Skill
+
+修改 `SKILL.md` 或支持文件后,重新打开会话或重新加载即可。
+
+### 限制 Claude 对 Skill 的访问
+
+你可以通过权限配置,只允许 Claude 访问某些 skill。
+
+## 最佳实践
+
+### 1. 描述要具体
+
+让 `description` 明确说明这个 skill 在什么时候触发。
+
+### 2. 保持聚焦
+
+一个 skill 解决一个问题,不要什么都塞进去。
+
+### 3. 包含触发词
+
+在描述里加入相关关键词,帮助 Claude 更准确地选择它。
+
+### 4. `SKILL.md` 不要太长
+
+尽量控制在 500 行以内,超过就拆分支持文件。
+
+### 5. 引用支持文件
+
+把重复内容移到脚本或参考文件中,主文件只保留核心说明。
+
+## 故障排查
+
+### 快速参考
+
+- 检查目录结构是否正确
+- 检查 `SKILL.md` frontmatter 是否有效
+- 检查 skill 名称是否和调用名一致
+
+### Skill 没有触发
+
+- 检查描述是否足够具体
+- 检查目录是否在 Claude 可见范围内
+- 检查是否被更高优先级的 skill 覆盖
+
+### Skill 触发太频繁
+
+- 收紧描述
+- 增加约束条件
+- 用更具体的触发词
+
+### Claude 看不到全部 Skills
+
+- 检查路径
+- 检查权限
+- 重新加载会话
+
+## 安全注意事项
+
+- 不要在 skill 中硬编码密钥
+- 对副作用操作保持用户触发
+- 给自动触发的 skill 设置清晰边界
+
+## Skills vs 其他功能
+
+| 功能 | 触发方式 | 适合场景 |
+|------|----------|----------|
+| Skills | 自动/半自动 | 复用能力、流程标准化 |
+| Slash Commands | 手动 | 快捷命令 |
+| Subagents | 自动委派 | 隔离任务 |
+| Hooks | 事件触发 | 自动化和验证 |
+
+## 内置 Skills
+
+Claude Code 自带一些 Skills,例如批处理、调试、简化和 Claude API 相关内容。
+
+## 共享 Skills
+
+### 项目 Skills(团队共享)
+
+把 skill 放在项目目录里,团队成员都能用。
+
+### 个人 Skills
+
+```bash
+# 复制到个人目录
+mkdir -p ~/.claude/skills
+
+# 让脚本可执行
+chmod +x ~/.claude/skills/*/scripts/*
+```
+
+### Plugin 分发
+
+你也可以把 Skills 作为插件的一部分发布出去。
+
+## 继续深入
+
+如果你要管理一整套 Skills,可以再做一个 skill collection 或 skill manager,用来统一发现、更新和分发。
+
+## 更多资源
+
+- [根目录中文指南](../README.md)
+- [Slash Commands 中文参考](../01-slash-commands/README.md)
+- [Memory 中文指南](../02-memory/README.md)
+- [Subagents 中文参考](../04-subagents/README.md)
diff --git a/zh/03-skills/blog-draft/SKILL.md b/zh/03-skills/blog-draft/SKILL.md
new file mode 100644
index 0000000..02580df
--- /dev/null
+++ b/zh/03-skills/blog-draft/SKILL.md
@@ -0,0 +1,274 @@
+---
+name: blog-draft
+description: 根据想法和资料撰写博客草稿。适用于用户想写博客、基于研究创建内容,或起草文章的场景。流程会引导你完成调研、头脑风暴、提纲编写和带版本控制的迭代撰写。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+在继续之前,你**必须**先考虑用户输入。用户应提供:
+- **想法/主题**:博客文章的核心概念或主题
+- **资源**:用于研究的 URL、文件或参考资料(可选,但推荐)
+- **目标读者**:这篇博客是写给谁看的(可选)
+- **语气/风格**:正式、轻松、技术向等(可选)
+
+**重要**:如果用户是在请求更新一篇**已有博客文章**,请跳过步骤 0-8,直接从**步骤 9** 开始。先阅读现有草稿文件,再继续迭代流程。
+
+## 执行流程
+
+请按顺序执行以下步骤。**不要跳步,也不要在未获得用户批准的情况下继续执行标明需要确认的步骤。**
+
+### 步骤 0:创建项目文件夹
+
+1. 使用以下格式生成文件夹名称:`YYYY-MM-DD-short-topic-name`
+ - 使用今天的日期
+ - 根据主题生成一个简短、适合 URL 的 slug(小写、连字符连接,最多 5 个词)
+
+2. 创建文件夹结构:
+ ```text
+ blog-posts/
+ └── YYYY-MM-DD-short-topic-name/
+ └── resources/
+ ```
+
+3. 在继续前,先向用户确认文件夹已创建。
+
+### 步骤 1:研究与资源收集
+
+1. 在博客文章目录中创建 `resources/` 子文件夹
+
+2. 对于每个提供的资源:
+ - **URL**:抓取关键内容并保存到 `resources/` 下的 markdown 文件中
+ - **文件**:读取并在 `resources/` 中做摘要
+ - **主题**:使用网络搜索收集最新信息
+
+3. 为每个资源在 `resources/` 中创建摘要文件:
+ - `resources/source-1-[short-name].md`
+ - `resources/source-2-[short-name].md`
+ - 以此类推
+
+4. 每个摘要都应包含:
+ ```markdown
+ # 来源:[标题/URL]
+
+ ## 要点
+ - 要点 1
+ - 要点 2
+
+ ## 相关引文/数据
+ - 引文或统计 1
+ - 引文或统计 2
+
+ ## 与主题的关联
+ 简要说明其相关性
+ ```
+
+5. 向用户展示研究摘要。
+
+### 步骤 2:头脑风暴与澄清
+
+1. 基于想法和已研究的资源,展示:
+ - 从研究中识别出的**主要主题**
+ - 博客文章的**可能切入角度**
+ - 应该覆盖的**关键点**
+ - 仍需进一步澄清的**信息缺口**
+
+2. 提出澄清问题:
+ - 你希望读者最终带走的核心结论是什么?
+ - 研究中有没有哪些点是你希望重点强调的?
+ - 目标长度是多少?(短:500-800 字,中:1000-1500 字,长:2000+ 字)
+ - 有没有哪些内容你希望排除?
+
+3. **在继续之前,等待用户回复。**
+
+### 步骤 3:提出提纲
+
+1. 创建一个结构化提纲,包括:
+
+ ```markdown
+ # 博客文章提纲:[标题]
+
+ ## 元信息
+ - **目标读者**:[谁]
+ - **语气**:[风格]
+ - **目标长度**:[字数]
+ - **核心结论**:[关键信息]
+
+ ## 建议结构
+
+ ### 开场/引子
+ - 开场钩子思路
+ - 背景铺垫
+ - 论点陈述
+
+ ### 第一部分:[标题]
+ - 关键点 A
+ - 关键点 B
+ - 来自 [来源] 的支撑证据
+
+ ### 第二部分:[标题]
+ - 关键点 A
+ - 关键点 B
+
+ [继续列出所有部分...]
+
+ ### 结论
+ - 关键点总结
+ - 行动号召或最终思考
+
+ ## 需要引用的来源
+ - 来源 1
+ - 来源 2
+ ```
+
+2. 向用户展示提纲,并**请求批准或修改意见**。
+
+### 步骤 4:保存已批准的提纲
+
+1. 用户批准提纲后,将其保存为博客文章文件夹中的 `OUTLINE.md`。
+
+2. 确认提纲已保存。
+
+### 步骤 5:提交提纲(如果在 git 仓库中)
+
+1. 检查当前目录是否为 git 仓库。
+
+2. 如果是:
+ - 暂存新文件:博客文章文件夹、resources 和 `OUTLINE.md`
+ - 使用如下提交信息创建 commit:`docs: Add outline for blog post - [topic-name]`
+ - 推送到远程仓库
+
+3. 如果不是 git 仓库,则跳过此步骤并告知用户。
+
+### 步骤 6:撰写草稿
+
+1. 基于已批准的提纲,撰写完整博客草稿。
+
+2. 严格按照 `OUTLINE.md` 的结构进行编写。
+
+3. 包含:
+ - 有吸引力的引言和开场钩子
+ - 清晰的章节标题
+ - 来自研究的支撑证据和示例
+ - 段落之间自然流畅的过渡
+ - 强有力的结尾和核心收获
+ - **引用**:所有比较、统计数据和事实性陈述都必须引用原始来源
+
+4. 将草稿保存为博客文章文件夹中的 `draft-v0.1.md`。
+
+5. 格式:
+ ```markdown
+ # [博客文章标题]
+
+ *[可选:副标题或标语]*
+
+ [包含行内引用的完整正文...]
+
+ ---
+
+ ## 参考资料
+ - [1] 来源 1 标题 - URL 或引用
+ - [2] 来源 2 标题 - URL 或引用
+ - [3] 来源 3 标题 - URL 或引用
+ ```
+
+6. **引用要求**:
+ - 每个数据点、统计信息或比较都必须带有行内引用
+ - 使用编号引用 [1]、[2] 等,或命名引用 [Source Name]
+ - 在文末的参考资料部分链接这些引用
+ - 示例:“研究表明,65% 的开发者更偏好 TypeScript [1]”
+ - 示例:“React 在渲染速度上比 Vue 快 20% [React Benchmarks 2024]”
+
+### 步骤 7:提交草稿(如果在 git 仓库中)
+
+1. 检查是否处于 git 仓库中。
+
+2. 如果是:
+ - 暂存草稿文件
+ - 使用如下提交信息创建 commit:`docs: Add draft v0.1 for blog post - [topic-name]`
+ - 推送到远程仓库
+
+3. 如果不是 git 仓库,则跳过并告知用户。
+
+### 步骤 8:向用户展示草稿以供审阅
+
+1. 向用户展示草稿内容。
+
+2. 询问反馈:
+ - 整体印象如何?
+ - 哪些部分需要扩展或压缩?
+ - 是否需要调整语气?
+ - 是否缺少关键信息?
+ - 有没有具体编辑或重写建议?
+
+3. **等待用户回复。**
+
+### 步骤 9:迭代或定稿
+
+**如果用户要求修改:**
+1. 记录所有修改请求
+2. 返回步骤 6,并做以下调整:
+ - 将版本号递增(v0.2、v0.3 等)
+ - 纳入所有反馈
+ - 保存为 `draft-v[X.Y].md`
+ - 重复步骤 7-8
+
+**如果用户批准:**
+1. 确认最终草稿版本
+2. 如用户要求,可重命名为 `final.md`
+3. 总结博客文章创建过程:
+ - 一共创建了多少个版本
+ - 各版本之间的关键变化
+ - 最终字数
+ - 创建了哪些文件
+
+## 版本跟踪
+
+所有草稿都会以递增版本号保留:
+- `draft-v0.1.md` - 初始草稿
+- `draft-v0.2.md` - 第一轮反馈后
+- `draft-v0.3.md` - 第二轮反馈后
+- 以此类推
+
+这可以跟踪博客文章的演变过程,并在需要时回退。
+
+## 输出文件结构
+
+```text
+blog-posts/
+└── YYYY-MM-DD-topic-name/
+ ├── resources/
+ │ ├── source-1-name.md
+ │ ├── source-2-name.md
+ │ └── ...
+ ├── OUTLINE.md
+ ├── draft-v0.1.md
+ ├── draft-v0.2.md(如果有迭代)
+ └── draft-v0.3.md(如果还有更多迭代)
+```
+
+## 质量建议
+
+- **钩子**:以问题、令人惊讶的事实或贴近读者的场景开头
+- **衔接**:每一段都要自然连接到下一段
+- **证据**:用研究数据支撑观点
+- **引用**:以下内容务必引用来源:
+ - 所有统计数据和数值(例如:“根据 [Source],75% 的……”)
+ - 对产品、服务或方案的比较(例如:“X 的速度比 Y 快 2 倍 [Source]”)
+ - 关于市场趋势、研究发现或基准测试的事实性陈述
+ - 使用行内引用,格式为:[Source Name] 或 [Author, Year]
+- **语气**:全程保持一致
+- **长度**:尊重目标字数
+- **可读性**:使用短段落,并在适当位置使用项目符号
+- **CTA**:以明确的行动号召或发人深省的问题收尾
+
+## 备注
+
+- 始终在上述需要确认的节点等待用户批准
+- 保留所有草稿版本,方便追踪历史
+- 如果提供了 URL,使用网络搜索获取最新信息
+- 如果资源不足,询问用户补充,或建议进一步研究
+- 根据目标读者调整语气(技术、通用、商业等)
diff --git a/zh/03-skills/blog-draft/templates/draft-template.md b/zh/03-skills/blog-draft/templates/draft-template.md
new file mode 100644
index 0000000..c1dbb6d
--- /dev/null
+++ b/zh/03-skills/blog-draft/templates/draft-template.md
@@ -0,0 +1,67 @@
+# [博客文章标题]
+
+*[副标题或标语 - 可选]*
+
+**[作者名]** | [日期]
+
+---
+
+[开场钩子 - 立即抓住注意力]
+
+[背景与上下文 - 说明为什么这件事重要]
+
+[论点陈述 - 这篇文章要讲什么]
+
+---
+
+## [第一部分标题]
+
+[本部分正文,保持清晰、吸引人的表达]
+
+[加入证据、示例或数据来支撑观点]
+
+> “来自研究的相关引文” - 来源
+
+[过渡到下一部分]
+
+---
+
+## [第二部分标题]
+
+[继续展开正文]
+
+**关键收获:** [用加粗或提示块突出重要观点]
+
+[更多支撑内容]
+
+---
+
+## [第三部分标题]
+
+[如有需要,继续添加更多部分]
+
+### 小节(如果需要)
+
+[小节内容]
+
+---
+
+## 结论
+
+[总结已覆盖的关键点]
+
+[重申核心结论]
+
+[行动号召或发人深省的结尾语]
+
+---
+
+## 参考资料
+
+1. [来源标题](#)
+2. [来源标题](#)
+3. [来源标题](#)
+
+---
+
+*[作者简介或相关文章推荐 - 可选]*
diff --git a/zh/03-skills/blog-draft/templates/outline-template.md b/zh/03-skills/blog-draft/templates/outline-template.md
new file mode 100644
index 0000000..1c8ec0e
--- /dev/null
+++ b/zh/03-skills/blog-draft/templates/outline-template.md
@@ -0,0 +1,97 @@
+# 博客文章提纲:[标题]
+
+## 元信息
+
+| 属性 | 值 |
+|-----------|-------|
+| **目标读者** | [写给谁看?] |
+| **语气** | [正式/轻松/技术/对话式] |
+| **目标长度** | [字数范围] |
+| **核心结论** | [一句话说明读者应该记住什么] |
+| **关键词** | [如有需要,可填写 SEO 关键词] |
+
+---
+
+## 建议结构
+
+### 1. 引言 / 开场钩子
+
+**开场钩子选项:**
+- [ ] 与读者产生共鸣的问题
+- [ ] 令人惊讶的统计或事实
+- [ ] 一个简短故事或场景
+- [ ] 大胆的陈述
+
+**背景铺垫:**
+- 需要提供的背景信息
+- 为什么这个主题现在很重要
+
+**论点陈述:**
+- 明确说明这篇文章要讲什么
+
+---
+
+### 2. [部分标题]
+
+**关键点:**
+- 要点 A:[说明]
+- 要点 B:[说明]
+
+**支撑证据:**
+- 来自 [source]:[相关数据/引文]
+
+**过渡到下一部分:**
+- [这部分如何与下一部分衔接]
+
+---
+
+### 3. [部分标题]
+
+**关键点:**
+- 要点 A:[说明]
+- 要点 B:[说明]
+
+**支撑证据:**
+- 来自 [source]:[相关数据/引文]
+
+**过渡到下一部分:**
+- [这部分如何与下一部分衔接]
+
+---
+
+### 4. [部分标题](如有需要可继续添加)
+
+**关键点:**
+- 要点 A:[说明]
+- 要点 B:[说明]
+
+**支撑证据:**
+- 来自 [source]:[相关数据/引文]
+
+---
+
+### 5. 结论
+
+**关键点总结:**
+- 回顾要点 1
+- 回顾要点 2
+- 回顾要点 3
+
+**最终思考 / 行动号召:**
+- [读者接下来应该做什么或思考什么?]
+
+---
+
+## 需要引用的来源
+
+1. [来源名称](#) - 用于:[对应信息]
+2. [来源名称](#) - 用于:[对应信息]
+3. [来源名称](#) - 用于:[对应信息]
+
+---
+
+## 撰写备注
+
+- [任何特别要求或限制]
+- [需要强调的内容]
+- [需要避免的内容]
diff --git a/zh/03-skills/brand-voice/SKILL.md b/zh/03-skills/brand-voice/SKILL.md
new file mode 100644
index 0000000..9450d62
--- /dev/null
+++ b/zh/03-skills/brand-voice/SKILL.md
@@ -0,0 +1,72 @@
+---
+name: brand-voice-consistency
+description: 确保所有沟通内容都符合品牌语气和风格指南。适用于撰写营销文案、客户沟通、对外内容,或用户提到品牌语气、tone、写作风格的场景。
+---
+
+# 品牌语气技能
+
+## 概览
+此技能确保所有沟通内容在品牌语气、风格和信息传达上保持一致。
+
+## 品牌定位
+
+### 使命
+帮助团队用 AI 自动化开发工作流
+
+### 价值观
+- **简洁**:把复杂的事情变简单
+- **可靠**:执行稳健,结果稳定
+- **赋能**:释放人的创造力
+
+### 语气风格
+- **友好但专业** - 平易近人,但不过于随意
+- **清晰简洁** - 避免行话,用通俗方式解释技术概念
+- **自信** - 体现我们知道自己在做什么
+- **有同理心** - 理解用户需求和痛点
+
+## 写作指南
+
+### 应该做的 ✅
+- 对读者使用“你”
+- 使用主动语态:“Claude 会生成报告”,而不是“报告由 Claude 生成”
+- 先讲价值主张
+- 使用具体示例
+- 句子保持在 20 个词以内
+- 使用列表增强清晰度
+- 包含行动号召
+
+### 不应该做的 ❌
+- 不要使用企业黑话
+- 不要居高临下,也不要过度简化
+- 不要使用“我们相信”或“我们认为”
+- 不要全大写,除非为了强调
+- 不要写成大段文字墙
+- 不要默认读者具备技术背景
+
+## 词汇
+
+### ✅ 推荐用词
+- Claude(不要写“the Claude AI”)
+- 代码生成(不要写“auto-coding”)
+- Agent(不要写“bot”)
+- 简化流程(不要写“革命性改变”)
+- 集成(不要写“synergize”)
+
+### ❌ 避免用词
+- “cutting-edge”(过度使用)
+- “game-changer”(过于空泛)
+- “leverage”(企业黑话)
+- “utilize”(直接用“use”)
+- “paradigm shift”(不够清晰)
+
+## 示例
+
+### ✅ 好示例
+“Claude 能自动化你的代码审查流程。它不再需要你手动检查每个 PR,而是会审查安全性、性能和质量,每周为团队节省数小时。”
+
+为什么好:价值明确、收益具体、行动导向强
+
+### ❌ 坏示例
+“Claude 利用前沿 AI 为软件开发提供全面解决方案。”
+
+为什么不好:太空泛、企业黑话太多、没有具体价值
diff --git a/zh/03-skills/brand-voice/tone-examples.md b/zh/03-skills/brand-voice/tone-examples.md
new file mode 100644
index 0000000..6b91328
--- /dev/null
+++ b/zh/03-skills/brand-voice/tone-examples.md
@@ -0,0 +1,13 @@
+# 品牌语气示例
+
+## 激动人心的公告
+“每周为代码审查节省 8 小时。Claude 会自动审查你的 PR。”
+
+## 体现同理心的支持
+“我们知道发布流程可能很有压力。Claude 会负责测试,你就不用担心了。”
+
+## 自信的产品功能
+“Claude 不只是给你代码建议。它理解你的架构,并保持一致性。”
+
+## 教育型博客文章
+“让我们一起看看 agents 如何改进代码审查工作流。以下是我们的发现……”
diff --git a/zh/03-skills/claude-md/SKILL.md b/zh/03-skills/claude-md/SKILL.md
new file mode 100644
index 0000000..82db31b
--- /dev/null
+++ b/zh/03-skills/claude-md/SKILL.md
@@ -0,0 +1,212 @@
+---
+name: claude-md
+description: 按最佳实践创建或更新 CLAUDE.md 文件,以便为 AI agent 提供最优的项目入门上下文
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+在继续之前,你**必须**先考虑用户输入(如果不为空)。用户可能会指定:
+- `create` - 从零创建新的 CLAUDE.md
+- `update` - 改进已有的 CLAUDE.md
+- `audit` - 分析并报告当前 CLAUDE.md 的质量
+- 一个具体路径,用于创建或更新(例如 `src/api/CLAUDE.md` 代表目录级说明)
+
+## 核心原则
+
+**LLM 是无状态的**:CLAUDE.md 是每次对话中唯一会自动包含的文件。它是让 AI agent 了解代码库的主要入门文档。
+
+### 黄金法则
+
+1. **少即是多**:前沿 LLM 大约能遵循 150-200 条指令。Claude Code 的系统提示词本身已经占了大约 50 条,因此 CLAUDE.md 必须聚焦且简洁。
+
+2. **只放通用信息**:只包含每次会话都适用的内容。任务特定的说明应该放在单独文件里。
+
+3. **不要把 Claude 当成 lint 工具**:风格指南会膨胀上下文并降低指令遵循效果。应改用确定性工具(如 prettier、eslint 等)。
+
+4. **绝不自动生成**:CLAUDE.md 是 AI harness 中杠杆最高的位置。应该经过认真思考后手工编写。
+
+## 执行流程
+
+### 1. 项目分析
+
+首先分析当前项目状态:
+
+1. 检查是否存在已有的 CLAUDE.md 文件:
+ - 根目录:`./CLAUDE.md` 或 `.claude/CLAUDE.md`
+ - 目录级:`**/CLAUDE.md`
+ - 全局用户配置:`~/.claude/CLAUDE.md`
+
+2. 识别项目结构:
+ - 技术栈(语言、框架)
+ - 项目类型(monorepo、单体应用、库)
+ - 开发工具(包管理器、构建系统、测试运行器)
+
+3. 查看已有文档:
+ - README.md
+ - CONTRIBUTING.md
+ - package.json、pyproject.toml、Cargo.toml 等
+
+### 2. 内容策略(WHAT, WHY, HOW)
+
+围绕三个维度组织 CLAUDE.md:
+
+#### WHAT - 技术与结构
+- 技术栈概览
+- 项目组织方式(对 monorepo 尤其重要)
+- 关键目录及其用途
+
+#### WHY - 目的与背景
+- 项目是做什么的
+- 为什么做出这些架构决策
+- 每个主要组件负责什么
+
+#### HOW - 工作流与约定
+- 开发流程(bun vs node、pip vs uv 等)
+- 测试流程和命令
+- 验证与构建方法
+- 关键“坑点”或非显而易见的要求
+
+### 3. 渐进式披露策略
+
+对于较大的项目,建议创建 `agent_docs/` 文件夹:
+
+```text
+agent_docs/
+ |- building_the_project.md
+ |- running_tests.md
+ |- code_conventions.md
+ |- architecture_decisions.md
+```
+
+在 CLAUDE.md 中引用这些文件,并写明:
+```markdown
+关于详细的构建说明,请参考 `agent_docs/building_the_project.md`
+```
+
+**重要**:使用 `file:line` 引用,而不是代码片段,以避免上下文过时。
+
+### 4. 质量约束
+
+创建或更新 CLAUDE.md 时:
+
+1. **目标长度**:少于 300 行,理想情况下少于 100 行
+2. **不要写风格规则**:移除任何 lint/format 相关说明
+3. **不要写任务特定说明**:移到单独文件中
+4. **不要写代码片段**:改用文件引用
+5. **不要重复信息**:不要重复 package.json 或 README 中已有内容
+
+### 5. 必备章节
+
+一个结构良好的 CLAUDE.md 应包含:
+
+```markdown
+# 项目名称
+
+一句简短的项目描述。
+
+## 技术栈
+- 主语言和版本
+- 关键框架/库
+- 数据库/存储(如有)
+
+## 项目结构
+[仅适用于 monorepo 或复杂结构]
+- `apps/` - 应用入口
+- `packages/` - 共享库
+
+## 开发命令
+- 安装:`command`
+- 测试:`command`
+- 构建:`command`
+
+## 关键约定
+[只保留非显而易见、高影响的约定]
+- 约定 1,简要说明
+- 约定 2,简要说明
+
+## 已知问题 / 坑点
+[经常让开发者踩坑的内容]
+- 问题 1
+- 问题 2
+```
+
+### 6. 需要避免的反模式
+
+**不要包含:**
+- 代码风格指南(交给 lint 工具)
+- 如何使用 Claude 的说明
+- 对显而易见模式的冗长解释
+- 复制粘贴的代码示例
+- 泛泛而谈的最佳实践(例如“写干净的代码”)
+- 特定任务的说明
+- 自动生成内容
+- 大量 TODO 列表
+
+### 7. 验证清单
+
+在最终确定前,检查:
+
+- [ ] 少于 300 行(最好少于 100 行)
+- [ ] 每一行都适用于所有会话
+- [ ] 没有风格/格式规则
+- [ ] 没有代码片段(使用文件引用)
+- [ ] 命令已经验证可用
+- [ ] 对复杂项目使用了渐进式披露
+- [ ] 已记录关键坑点
+- [ ] 没有与 README.md 重复
+
+## 输出格式
+
+### 对于 `create` 或默认模式:
+
+1. 分析项目
+2. 按上述结构起草 CLAUDE.md
+3. 向用户展示草稿以供审阅
+4. 在获得批准后写入相应位置
+
+### 对于 `update`:
+
+1. 读取现有 CLAUDE.md
+2. 按最佳实践进行审计
+3. 识别:
+ - 需要删除的内容(风格规则、代码片段、任务特定内容)
+ - 需要压缩的内容
+ - 缺失的重要信息
+4. 向用户展示修改建议
+5. 在获得批准后应用修改
+
+### 对于 `audit`:
+
+1. 读取现有 CLAUDE.md
+2. 生成报告,包括:
+ - 当前行数与目标的对比
+ - 可通用于所有会话内容的百分比
+ - 发现的反模式列表
+ - 改进建议
+3. 不要修改文件,只做报告
+
+## AGENTS.md 处理
+
+如果用户请求创建或更新 AGENTS.md:
+
+AGENTS.md 用于定义专门的 agent 行为。与 CLAUDE.md(项目上下文)不同,AGENTS.md 定义的是:
+- 自定义 agent 角色和能力
+- agent 级约束与说明
+- 多 agent 场景下的工作流定义
+
+同样适用以下原则:
+- 保持聚焦和简洁
+- 使用渐进式披露
+- 用外部文档引用代替内联内容
+
+## 备注
+
+- 在写入前始终验证命令是否可用
+- 不确定时就不要写,少即是多
+- 系统提醒会告诉 Claude,CLAUDE.md “可能相关,也可能不相关” - 噪音越多,越容易被忽略
+- monorepo 最需要清晰的 WHAT/WHY/HOW 结构
+- 目录级 CLAUDE.md 应该更聚焦
diff --git a/zh/03-skills/code-review/SKILL.md b/zh/03-skills/code-review/SKILL.md
new file mode 100644
index 0000000..335aa6c
--- /dev/null
+++ b/zh/03-skills/code-review/SKILL.md
@@ -0,0 +1,70 @@
+---
+name: code-review-specialist
+description: 提供全面的代码审查能力,覆盖安全、性能和代码质量分析。适用于用户请求代码审查、代码质量评估、Pull Request 审查,或提到安全分析和性能优化时。
+---
+
+# 代码审查 Skill
+
+这个 skill 提供全面的代码审查能力,重点关注:
+
+1. **安全分析**
+ - 身份验证 / 授权问题
+ - 数据泄露风险
+ - 注入漏洞
+ - 密码学弱点
+ - 敏感数据日志记录
+
+2. **性能审查**
+ - 算法效率(Big O 分析)
+ - 内存优化
+ - 数据库查询优化
+ - 缓存机会
+ - 并发问题
+
+3. **代码质量**
+ - SOLID 原则
+ - 设计模式
+ - 命名规范
+ - 文档
+ - 测试覆盖率
+
+4. **可维护性**
+ - 代码可读性
+ - 函数长度(建议少于 50 行)
+ - 圈复杂度
+ - 依赖管理
+ - 类型安全
+
+## 审查模板
+
+对每一段被审查的代码,请提供:
+
+### 摘要
+- 整体质量评分(1-5)
+- 关键发现数量
+- 建议优先关注的区域
+
+### 关键问题(如有)
+- **问题**:清晰描述
+- **位置**:文件和行号
+- **影响**:为什么这很重要
+- **严重性**:Critical / High / Medium
+- **修复**:代码示例
+
+### 按类别列出发现
+
+#### 安全性(如有问题)
+列出安全漏洞及示例
+
+#### 性能(如有问题)
+列出性能问题,并说明复杂度
+
+#### 质量(如有问题)
+列出代码质量问题,并给出重构建议
+
+#### 可维护性(如有问题)
+列出可维护性问题,并给出改进建议
+
+## 版本历史
+
+- v1.0.0 (2024-12-10):首次发布,包含安全、性能、质量和可维护性分析
diff --git a/zh/03-skills/code-review/templates/finding-template.md b/zh/03-skills/code-review/templates/finding-template.md
new file mode 100644
index 0000000..b96a8fd
--- /dev/null
+++ b/zh/03-skills/code-review/templates/finding-template.md
@@ -0,0 +1,112 @@
+# 代码审查问题记录模板
+
+使用这个模板来记录代码审查中发现的每一个问题。
+
+---
+
+## 问题:[标题]
+
+### 严重性
+- [ ] Critical(阻塞发布)
+- [ ] High(合并前应修复)
+- [ ] Medium(尽快修复)
+- [ ] Low(可选优化)
+
+### 类别
+- [ ] Security
+- [ ] Performance
+- [ ] Code Quality
+- [ ] Maintainability
+- [ ] Testing
+- [ ] Design Pattern
+- [ ] Documentation
+
+### 位置
+**文件:** `src/components/UserCard.tsx`
+
+**行号:** 45-52
+
+**函数 / 方法:** `renderUserDetails()`
+
+### 问题描述
+
+**是什么:** 描述这个问题是什么。
+
+**为什么重要:** 说明影响,以及为什么需要修复。
+
+**当前行为:** 展示有问题的代码或行为。
+
+**期望行为:** 描述理想情况下应该发生什么。
+
+### 代码示例
+
+#### 当前(有问题)
+
+```typescript
+// 这里展示了 N+1 查询问题
+const users = fetchUsers();
+users.forEach(user => {
+ const posts = fetchUserPosts(user.id); // 每个用户都发一次查询!
+ renderUserPosts(posts);
+});
+```
+
+#### 建议修复
+
+```typescript
+// 使用 JOIN 查询进行优化
+const usersWithPosts = fetchUsersWithPosts();
+usersWithPosts.forEach(({ user, posts }) => {
+ renderUserPosts(posts);
+});
+```
+
+### 影响分析
+
+| 方面 | 影响 | 严重性 |
+|--------|--------|--------|
+| 性能 | 20 个用户就会产生 100+ 次查询 | High |
+| 用户体验 | 页面加载缓慢 | High |
+| 可扩展性 | 规模变大后会失效 | Critical |
+| 可维护性 | 难以排查问题 | Medium |
+
+### 相关问题
+
+- `AdminUserList.tsx` 第 120 行有类似问题
+- 相关 PR:#456
+- 相关 issue:#789
+
+### 额外资源
+
+- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem)
+- [Database Join Documentation](https://docs.example.com/joins)
+
+### 审查者备注
+
+- 这是这个代码库里常见的模式
+- 可以考虑把它加入代码风格指南
+- 也许值得提取一个辅助函数
+
+### 作者回复(供反馈)
+
+*由代码作者填写:*
+
+- [ ] 已在提交 `abc123` 中修复
+- [ ] 修复状态:Complete / In Progress / Needs Discussion
+- [ ] 问题或疑虑:(描述)
+
+---
+
+## 统计信息(供审查者使用)
+
+在审查多个问题时,请记录:
+
+- **发现问题总数:** X
+- **Critical:** X
+- **High:** X
+- **Medium:** X
+- **Low:** X
+
+**建议:** ✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion
+
+**整体代码质量:** 1-5 星
diff --git a/zh/03-skills/code-review/templates/review-checklist.md b/zh/03-skills/code-review/templates/review-checklist.md
new file mode 100644
index 0000000..22b58f5
--- /dev/null
+++ b/zh/03-skills/code-review/templates/review-checklist.md
@@ -0,0 +1,47 @@
+# 代码审查检查清单
+
+## 安全检查
+- [ ] 没有硬编码的凭据或密钥
+- [ ] 所有用户输入都做了校验
+- [ ] 使用参数化查询,防止 SQL 注入
+- [ ] 所有会修改状态的操作都有 CSRF 防护
+- [ ] 使用正确的转义,防止 XSS
+- [ ] 受保护的端点有身份验证检查
+- [ ] 资源访问有授权检查
+- [ ] 密码使用安全哈希算法(bcrypt、argon2)
+- [ ] 日志中没有敏感数据
+- [ ] 强制使用 HTTPS
+
+## 性能检查
+- [ ] 没有 N+1 查询
+- [ ] 索引使用合理
+- [ ] 在有价值的地方做了缓存
+- [ ] 主线程上没有阻塞操作
+- [ ] 正确使用 async/await
+- [ ] 大数据集已经分页
+- [ ] 数据库连接已做连接池
+- [ ] 正则表达式已优化
+- [ ] 没有不必要的对象创建
+- [ ] 没有内存泄漏
+
+## 质量检查
+- [ ] 函数少于 50 行
+- [ ] 变量命名清晰
+- [ ] 没有重复代码
+- [ ] 错误处理合理
+- [ ] 注释解释的是 WHY,而不是 WHAT
+- [ ] 生产环境中没有 console.log
+- [ ] 有类型检查(TypeScript / JSDoc)
+- [ ] 遵循 SOLID 原则
+- [ ] 正确应用设计模式
+- [ ] 代码具备自解释性
+
+## 测试检查
+- [ ] 已编写单元测试
+- [ ] 覆盖了边界情况
+- [ ] 测试了错误场景
+- [ ] 有集成测试
+- [ ] 覆盖率大于 80%
+- [ ] 没有不稳定测试
+- [ ] 外部依赖已做 mock
+- [ ] 测试名称清晰
diff --git a/zh/03-skills/doc-generator/SKILL.md b/zh/03-skills/doc-generator/SKILL.md
new file mode 100644
index 0000000..1a7b067
--- /dev/null
+++ b/zh/03-skills/doc-generator/SKILL.md
@@ -0,0 +1,76 @@
+---
+name: api-documentation-generator
+description: 从源代码生成全面且准确的 API 文档。适用于创建或更新 API 文档、生成 OpenAPI 规范,或在用户提到 API 文档、端点或说明时使用。
+---
+
+# API 文档生成 Skill
+
+## 可生成内容
+
+- OpenAPI / Swagger 规范
+- API 端点文档
+- SDK 使用示例
+- 集成指南
+- 错误码参考
+- 认证指南
+
+## 文档结构
+
+### 每个端点的写法
+
+```markdown
+## GET /api/v1/users/:id
+
+### 描述
+简要说明这个端点做什么
+
+### 参数
+
+| 名称 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | string | 是 | 用户 ID |
+
+### 响应
+
+**200 成功**
+```json
+{
+ "id": "usr_123",
+ "name": "John Doe",
+ "email": "[email protected]",
+ "created_at": "2025-01-15T10:30:00Z"
+}
+```
+
+**404 未找到**
+```json
+{
+ "error": "USER_NOT_FOUND",
+ "message": "User does not exist"
+}
+```
+
+### 示例
+
+**cURL**
+```bash
+curl -X GET "https://api.example.com/api/v1/users/usr_123" \
+ -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**JavaScript**
+```javascript
+const user = await fetch('/api/v1/users/usr_123', {
+ headers: { 'Authorization': 'Bearer token' }
+}).then(r => r.json());
+```
+
+**Python**
+```python
+response = requests.get(
+ 'https://api.example.com/api/v1/users/usr_123',
+ headers={'Authorization': 'Bearer token'}
+)
+user = response.json()
+```
+```
diff --git a/zh/03-skills/refactor/SKILL.md b/zh/03-skills/refactor/SKILL.md
new file mode 100644
index 0000000..8edb205
--- /dev/null
+++ b/zh/03-skills/refactor/SKILL.md
@@ -0,0 +1,426 @@
+---
+name: code-refactor
+description: 基于 Martin Fowler 方法论的系统化代码重构 skill。适用于用户请求重构代码、改进代码结构、减少技术债、清理旧代码、消除 code smell 或提升可维护性时。这个 skill 采用分阶段、带研究与计划的安全增量实施方式。
+---
+
+# 代码重构 Skill
+
+这是一个基于 Martin Fowler《Refactoring: Improving the Design of Existing Code》(第 2 版)的系统化代码重构方法。这个 skill 强调安全、渐进的修改,并由测试提供保障。
+
+> “重构是在不改变软件外部行为的前提下,改进其内部结构的过程。” — Martin Fowler
+
+## 核心原则
+
+1. **保持行为不变**:外部行为必须保持一致
+2. **小步前进**:每次只做很小、可测试的改动
+3. **测试驱动**:测试是安全网
+4. **持续进行**:重构是长期过程,不是一次性任务
+5. **协作确认**:每个阶段都需要用户确认
+
+## 工作流程总览
+
+```
+阶段 1:研究与分析
+ ↓
+阶段 2:测试覆盖评估
+ ↓
+阶段 3:识别代码异味
+ ↓
+阶段 4:创建重构计划
+ ↓
+阶段 5:增量实施
+ ↓
+阶段 6:评审与迭代
+```
+
+---
+
+## 阶段 1:研究与分析
+
+### 目标
+- 理解代码库结构和用途
+- 确定重构范围
+- 收集业务需求背景
+
+### 先向用户确认的问题
+开始前先确认:
+
+1. **范围**:哪些文件 / 模块 / 函数需要重构?
+2. **目标**:你想解决什么问题?(可读性、性能、可维护性)
+3. **约束**:有哪些区域不能改?
+4. **时间压力**:这是否阻塞了其他工作?
+5. **测试状态**:是否已有测试?是否通过?
+
+### 行动
+- [ ] 阅读并理解目标代码
+- [ ] 识别依赖和集成点
+- [ ] 记录当前架构
+- [ ] 标记已有技术债迹象(TODO、FIXME)
+
+### 输出
+向用户汇报:
+- 代码结构总结
+- 识别出的问题区域
+- 初步建议
+- **请求继续执行的批准**
+
+---
+
+## 阶段 2:测试覆盖评估
+
+### 为什么测试重要
+> “没有测试的重构,就像没有安全带就开车。” — Martin Fowler
+
+测试是安全重构的**关键前提**。没有测试,很容易引入 bug。
+
+### 评估步骤
+
+1. **检查现有测试**
+ ```bash
+ # 查找测试文件
+ find . -name "*test*" -o -name "*spec*" | head -20
+ ```
+
+2. **运行现有测试**
+ ```bash
+ # JavaScript / TypeScript
+ npm test
+
+ # Python
+ pytest -v
+
+ # Java
+ mvn test
+ ```
+
+3. **检查覆盖率(如果可用)**
+ ```bash
+ # JavaScript
+ npm run test:coverage
+
+ # Python
+ pytest --cov=.
+ ```
+
+### 决策点:询问用户
+
+**如果测试存在且通过:**
+- 进入阶段 3
+
+**如果测试缺失或不完整:**
+给出选项:
+1. 先写测试(推荐)
+2. 在重构过程中逐步补测试
+3. 不写测试直接继续(有风险,需要用户确认)
+
+**如果测试失败:**
+- 停止。先修复失败测试再重构
+- 问用户:是否先修测试?
+
+### 测试编写建议(如需要)
+
+对每个要重构的函数,测试应覆盖:
+- 正常路径
+- 边界情况(空输入、null、边界值)
+- 错误场景(非法输入、异常)
+
+使用“红-绿-重构”循环:
+1. 写失败测试(红)
+2. 让它通过(绿)
+3. 再重构
+
+---
+
+## 阶段 3:识别代码异味
+
+### 什么是代码异味?
+代码深层问题的表面症状。它们不一定是 bug,但说明代码设计可能有问题。
+
+### 常见异味清单
+
+完整目录见 [references/code-smells.md](references/code-smells.md)。
+
+#### 快速参考
+
+| 异味 | 迹象 | 影响 |
+|-------|------|------|
+| **长函数** | 函数超过 30-50 行 | 难以理解、测试和维护 |
+| **重复代码** | 多处出现相同逻辑 | 修复需要改多处 |
+| **大类** | 类承担了太多职责 | 违反单一职责原则 |
+| **Feature Envy** | 一个方法更多依赖别的类的数据 | 封装性差 |
+| **基础类型沉迷** | 过度使用基础类型而不是对象 | 缺少领域概念 |
+| **长参数列表** | 方法参数超过 4 个 | 调用困难 |
+| **数据泥团** | 一组数据总是一起出现 | 缺少抽象 |
+| **switch 语句** | 复杂的 switch / if-else 链 | 难以扩展 |
+| **臆想泛化** | “以防未来需要”提前设计 | 不必要的复杂度 |
+| **死代码** | 未使用的代码 | 造成困惑和维护负担 |
+
+### 分析步骤
+
+1. **自动分析**(如果有脚本)
+ ```bash
+ python scripts/detect-smells.py <file>
+ ```
+
+2. **人工审查**
+ - 系统地走读代码
+ - 记录每个异味的位置和严重性
+ - 按影响分类(Critical / High / Medium / Low)
+
+3. **优先级排序**
+ 优先关注会:
+ - 阻塞当前开发的异味
+ - 导致 bug 或混淆的异味
+ - 影响最常变更代码路径的异味
+
+### 输出:异味报告
+
+向用户呈现:
+- 识别出的异味及位置
+- 每项的严重性评估
+- 建议的优先级顺序
+- **请求用户确认优先级**
+
+---
+
+## 阶段 4:创建重构计划
+
+### 选择重构方式
+
+针对每个异味,从目录中选择合适的重构手法。
+
+完整列表见 [references/refactoring-catalog.md](references/refactoring-catalog.md)。
+
+#### 异味到重构的映射
+
+| 代码异味 | 推荐重构 |
+|----------|----------|
+| 长函数 | Extract Method、Replace Temp with Query |
+| 重复代码 | Extract Method、Pull Up Method、Form Template Method |
+| 大类 | Extract Class、Extract Subclass |
+| Feature Envy | Move Method、Move Field |
+| 基础类型沉迷 | Replace Primitive with Object、Replace Type Code with Class |
+| 长参数列表 | Introduce Parameter Object、Preserve Whole Object |
+| 数据泥团 | Extract Class、Introduce Parameter Object |
+| switch 语句 | Replace Conditional with Polymorphism |
+| 臆想泛化 | Collapse Hierarchy、Inline Class、Remove Dead Code |
+| 死代码 | Remove Dead Code |
+
+### 计划结构
+
+使用 [templates/refactoring-plan.md](templates/refactoring-plan.md) 里的模板。
+
+每项重构都要写明:
+1. **Target**:将修改哪些代码
+2. **Smell**:解决什么问题
+3. **Refactoring**:采用哪种手法
+4. **Steps**:详细微步骤
+5. **Risks**:可能出什么问题
+6. **Rollback**:如何回退
+
+### 分阶段方法
+
+**关键**:重构必须分阶段推进。
+
+**阶段 A:快速收益**(低风险,高价值)
+- 重命名变量以提升清晰度
+- 提取明显重复的代码
+- 删除死代码
+
+**阶段 B:结构改进**(中风险)
+- 从长函数中提取方法
+- 引入参数对象
+- 把方法移动到更合适的类
+
+**阶段 C:架构改动**(高风险)
+- 用多态替代条件分支
+- 提取类
+- 引入设计模式
+
+### 决策点:把计划展示给用户
+
+在开始实施前:
+- 展示完整重构计划
+- 解释每个阶段及其风险
+- 获得每个阶段的明确批准
+- **询问**:“是否继续执行阶段 A?”
+
+---
+
+## 阶段 5:增量实施
+
+### 黄金法则
+> “修改 → 测试 → 通过?→ 提交 → 下一步”
+
+### 实施节奏
+
+对每一步重构:
+
+1. **预检查**
+ - 测试通过(绿色)
+ - 代码能编译
+
+2. **只做一个小改动**
+ - 按目录中的具体操作进行
+ - 保持改动最小化
+
+3. **验证**
+ - 立刻运行测试
+ - 检查编译错误
+
+4. **如果测试通过(绿色)**
+ - 用描述清晰的提交信息提交
+ - 继续下一步
+
+5. **如果测试失败(红色)**
+ - 立刻停止
+ - 撤销改动
+ - 分析原因
+ - 如有疑问,询问用户
+
+### 提交策略
+
+每次提交都应当:
+- **原子性**:只包含一个逻辑改动
+- **可回滚**:容易撤销
+- **描述清楚**:提交信息明确
+
+示例提交信息:
+```
+refactor: 从 processOrder() 中提取 calculateTotal()
+refactor: 将 'x' 重命名为 'customerCount' 以提升清晰度
+refactor: 删除未使用的 validateOldFormat() 方法
+```
+
+### 进度汇报
+
+每个子阶段完成后,向用户汇报:
+- 做了哪些改动
+- 测试是否仍通过
+- 遇到了什么问题
+- **询问**:“继续下一批吗?”
+
+---
+
+## 阶段 6:评审与迭代
+
+### 重构后检查清单
+
+- [ ] 所有测试通过
+- [ ] 没有新的警告 / 错误
+- [ ] 代码编译成功
+- [ ] 行为没有变化(手动验证)
+- [ ] 必要时已更新文档
+- [ ] 提交历史干净
+
+### 指标对比
+
+重构前后运行复杂度分析:
+```bash
+python scripts/analyze-complexity.py <file>
+```
+
+展示改进:
+- 代码行数变化
+- 圈复杂度变化
+- 可维护性指标变化
+
+### 用户评审
+
+向用户展示最终结果:
+- 所有变更摘要
+- 重构前后代码对比
+- 指标改善情况
+- 剩余技术债
+- **询问**:“你对这些改动满意吗?”
+
+### 下一步
+
+和用户讨论:
+- 还要处理哪些异味?
+- 是否安排下一次重构?
+- 是否把类似修改应用到其他地方?
+
+---
+
+## 重要指南
+
+### 何时暂停并询问
+
+遇到以下情况时,务必暂停并和用户确认:
+- 不确定业务逻辑
+- 改动可能影响外部 API
+- 测试覆盖不足
+- 需要做重大的架构决策
+- 风险上升
+- 遇到意外复杂性
+
+### 安全规则
+
+1. **没有测试不要重构**(除非用户明确确认风险)
+2. **不要做大改动**,拆成小步
+3. **每次改动后都不要跳过测试**
+4. **测试失败就不要继续**,先修复或回滚
+5. **不要臆测**,不确定就问
+
+### 不要做什么
+
+- 不要把重构和新功能混在一起
+- 不要在生产事故期间做重构
+- 不要重构你看不懂的代码
+- 不要过度设计,保持简单
+- 不要一次性重构所有内容
+
+---
+
+## 快速上手示例
+
+### 场景:长函数 + 重复逻辑
+
+**重构前:**
+```javascript
+function processOrder(order) {
+ // 150 行代码,包含:
+ // - 重复验证逻辑
+ // - 内联计算
+ // - 多种职责混杂
+}
+```
+
+**重构步骤:**
+
+1. **确认测试存在**,覆盖 `processOrder()`
+2. **提取** 验证逻辑为 `validateOrder()`
+3. **测试** - 应该通过
+4. **提取** 计算逻辑为 `calculateOrderTotal()`
+5. **测试** - 应该通过
+6. **提取** 通知逻辑为 `notifyCustomer()`
+7. **测试** - 应该通过
+8. **评审** - `processOrder()` 现在只负责串联 3 个清晰函数
+
+**重构后:**
+```javascript
+function processOrder(order) {
+ validateOrder(order);
+ const total = calculateOrderTotal(order);
+ notifyCustomer(order, total);
+ return { order, total };
+}
+```
+
+---
+
+## 参考资料
+
+- [代码异味目录](references/code-smells.md) - 代码异味完整清单
+- [重构目录](references/refactoring-catalog.md) - 重构手法
+- [重构计划模板](templates/refactoring-plan.md) - 计划模板
+
+## 脚本
+
+- `scripts/analyze-complexity.py` - 分析代码复杂度指标
+- `scripts/detect-smells.py` - 自动检测 code smell
+
+## 版本历史
+
+- v1.0.0 (2025-01-15):首次发布,包含 Fowler 方法论、分阶段流程和用户确认点
diff --git a/zh/03-skills/refactor/references/code-smells.md b/zh/03-skills/refactor/references/code-smells.md
new file mode 100644
index 0000000..8fb8f56
--- /dev/null
+++ b/zh/03-skills/refactor/references/code-smells.md
@@ -0,0 +1,669 @@
+# 代码异味目录
+
+这是基于 Martin Fowler《Refactoring》(第 2 版)的代码异味参考目录。代码异味是更深层问题的表面症状,它们说明代码设计可能出了问题。
+
+> “代码异味通常是系统中更深层问题的表面信号。” — Martin Fowler
+
+---
+
+## 过度膨胀类异味
+
+表示对象或函数已经大到不再好用。
+
+### 长函数
+
+**迹象:**
+- 函数超过 30-50 行
+- 需要滚动才能看完整个函数
+- 嵌套层级很多
+- 需要注释来解释局部逻辑
+
+**为什么不好:**
+- 难理解
+- 难单独测试
+- 改动容易波及其他逻辑
+- 重复逻辑容易藏在里面
+
+**可用重构:**
+- Extract Method
+- Replace Temp with Query
+- Introduce Parameter Object
+- Replace Method with Method Object
+- Decompose Conditional
+
+**示例(重构前):**
+```javascript
+function processOrder(order) {
+ // Validate order (20 lines)
+ if (!order.items) throw new Error('No items');
+ if (order.items.length === 0) throw new Error('Empty order');
+ // ... more validation
+
+ // Calculate totals (30 lines)
+ let subtotal = 0;
+ for (const item of order.items) {
+ subtotal += item.price * item.quantity;
+ }
+ // ... tax, shipping, discounts
+
+ // Send notifications (20 lines)
+ // ... email logic
+}
+```
+
+**示例(重构后):**
+```javascript
+function processOrder(order) {
+ validateOrder(order);
+ const totals = calculateOrderTotals(order);
+ sendOrderNotifications(order, totals);
+ return { order, totals };
+}
+```
+
+---
+
+### 大类
+
+**迹象:**
+- 实例变量很多(>7-10)
+- 方法很多(>15-20)
+- 类名含糊(Manager、Handler、Processor)
+- 方法没有用到全部字段
+
+**为什么不好:**
+- 违反单一职责原则
+- 难测试
+- 改动会波及无关功能
+- 难以复用局部能力
+
+**可用重构:**
+- Extract Class
+- Extract Subclass
+- Extract Interface
+
+**检测参考:**
+```text
+代码行数 > 300
+方法数量 > 15
+字段数量 > 10
+```
+
+---
+
+### 基础类型沉迷
+
+**迹象:**
+- 用基础类型表达领域概念(用 string 表示邮箱、用 int 表示金额)
+- 使用基础类型数组,而不是对象
+- 用字符串常量表示类型码
+- 大量 magic number / magic string
+
+**为什么不好:**
+- 类型层面没有验证
+- 逻辑散落在整个代码库里
+- 容易传错值
+- 缺少领域对象
+
+**可用重构:**
+- Replace Primitive with Object
+- Replace Type Code with Class
+- Replace Type Code with Subclasses
+- Replace Type Code with State/Strategy
+
+**示例(重构前):**
+```javascript
+const user = {
+ email: '[email protected]', // 只是字符串
+ phone: '1234567890', // 只是字符串
+ status: 'active', // 魔法字符串
+ balance: 10050 // 以分为单位的整数
+};
+```
+
+**示例(重构后):**
+```javascript
+const user = {
+ email: new Email('[email protected]'),
+ phone: new PhoneNumber('1234567890'),
+ status: UserStatus.ACTIVE,
+ balance: Money.cents(10050)
+};
+```
+
+---
+
+### 长参数列表
+
+**迹象:**
+- 方法参数超过 4 个
+- 一些参数总是一起出现
+- 布尔参数改变方法行为
+- 经常传 null / undefined
+
+**为什么不好:**
+- 难正确调用
+- 参数顺序容易搞混
+- 暗示方法做了太多事
+- 难以增加新参数
+
+**可用重构:**
+- Introduce Parameter Object
+- Preserve Whole Object
+- Replace Parameter with Method Call
+- Remove Flag Argument
+
+**示例(重构前):**
+```javascript
+function createUser(firstName, lastName, email, phone,
+ street, city, state, zip,
+ isAdmin, isActive, createdBy) {
+ // ...
+}
+```
+
+**示例(重构后):**
+```javascript
+function createUser(personalInfo, address, options) {
+ // personalInfo: { firstName, lastName, email, phone }
+ // address: { street, city, state, zip }
+ // options: { isAdmin, isActive, createdBy }
+}
+```
+
+---
+
+### 数据泥团
+
+**迹象:**
+- 同样的 3 个以上字段反复一起出现
+- 参数总是成对或成组传递
+- 类中的字段子集总是一起使用
+
+**为什么不好:**
+- 逻辑重复
+- 缺少抽象
+- 难扩展
+- 暗示隐藏的类应该存在
+
+**可用重构:**
+- Extract Class
+- Introduce Parameter Object
+- Preserve Whole Object
+
+**示例:**
+```javascript
+// 数据泥团:坐标 (x, y, z)
+function movePoint(x, y, z, dx, dy, dz) { }
+function scalePoint(x, y, z, factor) { }
+function distanceBetween(x1, y1, z1, x2, y2, z2) { }
+
+// 提取 Point3D 类
+class Point3D {
+ constructor(x, y, z) { }
+ move(delta) { }
+ scale(factor) { }
+ distanceTo(other) { }
+}
+```
+
+---
+
+## 面向对象滥用类异味
+
+表示 OOP 原则没有被正确使用。
+
+### switch 语句
+
+**迹象:**
+- 长 switch/case 或 if/else 链
+- 多处出现相同 switch
+- 按类型码分支
+- 新增 case 时需要改很多地方
+
+**为什么不好:**
+- 违反开放 / 封闭原则
+- 改动会扩散到所有 switch 位置
+- 难扩展
+- 往往说明缺少多态
+
+**可用重构:**
+- Replace Conditional with Polymorphism
+- Replace Type Code with Subclasses
+- Replace Type Code with State/Strategy
+
+**示例(重构前):**
+```javascript
+function calculatePay(employee) {
+ switch (employee.type) {
+ case 'hourly':
+ return employee.hours * employee.rate;
+ case 'salaried':
+ return employee.salary / 12;
+ case 'commissioned':
+ return employee.sales * employee.commission;
+ }
+}
+```
+
+**示例(重构后):**
+```javascript
+class HourlyEmployee {
+ calculatePay() {
+ return this.hours * this.rate;
+ }
+}
+
+class SalariedEmployee {
+ calculatePay() {
+ return this.salary / 12;
+ }
+}
+```
+
+---
+
+### 临时字段
+
+**迹象:**
+- 实例变量只在部分方法中使用
+- 字段只在某些条件下设置
+- 某些情况初始化过程很复杂
+
+**为什么不好:**
+- 容易混淆:字段存在但可能为 null
+- 对象状态难理解
+- 说明条件逻辑被隐藏了
+
+**可用重构:**
+- Extract Class
+- Introduce Null Object
+- Replace Temp Field with Local
+
+---
+
+### 拒绝遗赠
+
+**迹象:**
+- 子类没有用到继承来的方法 / 数据
+- 子类重写方法只是为了不做事
+- 继承被当成代码复用,而不是真正的 IS-A
+
+**为什么不好:**
+- 抽象不对
+- 违反里氏替换原则
+- 继承层次误导人
+
+**可用重构:**
+- Push Down Method / Field
+- Replace Subclass with Delegate
+- Replace Inheritance with Delegation
+
+---
+
+### 不同接口的相似类
+
+**迹象:**
+- 两个类做的事情差不多
+- 同一个概念却用了不同方法名
+- 理论上可以互换使用
+
+**为什么不好:**
+- 重复实现
+- 没有公共接口
+- 难切换
+
+**可用重构:**
+- Rename Method
+- Move Method
+- Extract Superclass
+- Extract Interface
+
+---
+
+## 变更阻碍类异味
+
+这类异味会让改动变得困难,一次改动需要波及很多地方。
+
+### 发散式变化
+
+**迹象:**
+- 一个类因为很多不同原因而被修改
+- 不同区域的变更都会触发同一个类的编辑
+- 类变成了“上帝类”
+
+**为什么不好:**
+- 违反单一职责原则
+- 变更频率高
+- 容易产生合并冲突
+
+**可用重构:**
+- Extract Class
+- Extract Superclass
+- Extract Subclass
+
+**示例:**
+一个 `User` 类同时因为这些原因变化:
+- 身份验证变化
+- 个人资料变化
+- 计费变化
+- 通知变化
+
+→ 可以拆成:`AuthService`、`ProfileService`、`BillingService`、`NotificationService`
+
+---
+
+### 散弹式修改
+
+**迹象:**
+- 一个改动需要编辑很多类
+- 一个小功能要触碰 10+ 个文件
+- 改动分散,难以一次找全
+
+**为什么不好:**
+- 很容易漏改
+- 耦合高
+- 容易出错
+
+**可用重构:**
+- Move Method
+- Move Field
+- Inline Class
+
+**检测参考:**
+如果新增一个字段需要改 5 个以上文件,就要警惕。
+
+---
+
+### 平行继承体系
+
+**迹象:**
+- 在一个继承体系中创建子类,另一个体系也得跟着创建
+- 类前缀相似(如 `DatabaseOrder`、`DatabaseProduct`)
+
+**为什么不好:**
+- 维护成本翻倍
+- 两个层次之间耦合
+- 容易漏掉一边
+
+**可用重构:**
+- Move Method
+- Move Field
+- 消除其中一个层次
+
+---
+
+## 可舍弃类异味
+
+表示有些东西已经不必要了,应该移除。
+
+### 注释过多
+
+**迹象:**
+- 注释在解释代码“做了什么”
+- 注释掉的代码
+- 长期存在的 TODO / FIXME
+- 注释里带道歉语气
+
+**为什么不好:**
+- 注释会过时
+- 代码本身应该能自解释
+- 死代码会造成混乱
+
+**可用重构:**
+- Extract Method(让方法名解释意图)
+- Rename(通过命名提升清晰度)
+- 删除注释掉的代码
+- Introduce Assertion
+
+**好与坏的注释:**
+```javascript
+// BAD: 解释做了什么
+// 遍历用户并检查是否活跃
+for (const user of users) {
+ if (user.status === 'active') { }
+}
+
+// GOOD: 解释为什么
+// 只保留活跃用户,未活跃用户由清理任务处理
+const activeUsers = users.filter(u => u.isActive);
+```
+
+---
+
+### 重复代码
+
+**迹象:**
+- 多处出现相同代码
+- 只有少量差异的相似代码
+- 复制粘贴模式
+
+**为什么不好:**
+- 修复要改多处
+- 容易不一致
+- 代码库臃肿
+
+**可用重构:**
+- Extract Method
+- Extract Class
+- Pull Up Method(在继承层次中)
+- Form Template Method
+
+**检测规则:**
+任何重复 3 次以上的代码都应该考虑提取。
+
+---
+
+### 惰性类
+
+**迹象:**
+- 类做的事情不足以支撑它的存在
+- 只是一个没有增值的包装器
+- 过度设计的产物
+
+**为什么不好:**
+- 增加维护开销
+- 多了一层没必要的间接
+- 有复杂度但没收益
+
+**可用重构:**
+- Inline Class
+- Collapse Hierarchy
+
+---
+
+### 死代码
+
+**迹象:**
+- 无法到达的代码
+- 未使用的变量 / 方法 / 类
+- 注释掉的代码
+- 位于不可能条件分支后的代码
+
+**为什么不好:**
+- 造成困惑
+- 增加维护负担
+- 降低理解速度
+
+**可用重构:**
+- Remove Dead Code
+- Safe Delete
+
+**检测:**
+```bash
+# 查找未使用的导出
+# 查找未引用的函数
+# IDE 的“unused”警告
+```
+
+---
+
+### 臆想泛化
+
+**迹象:**
+- 只有一个子类的抽象类
+- 为“未来可能需要”而加的未使用参数
+- 只是转发的函数
+- 为一个用例设计的“框架”
+
+**为什么不好:**
+- 复杂度没有收益
+- 违背 YAGNI
+- 更难理解
+
+**可用重构:**
+- Collapse Hierarchy
+- Inline Class
+- Remove Parameter
+- Rename Method
+
+---
+
+## 耦合类异味
+
+表示类之间耦合过强。
+
+### Feature Envy
+
+**迹象:**
+- 一个方法使用别的类的数据比自己更多
+- 对另一个对象调用很多 getter
+- 数据和行为分离
+
+**为什么不好:**
+- 行为放错地方了
+- 封装性差
+- 难维护
+
+**可用重构:**
+- Move Method
+- Move Field
+- Extract Method(然后移动)
+
+**示例(重构前):**
+```javascript
+class Order {
+ getDiscountedPrice(customer) {
+ // 这里大量使用 customer 数据
+ if (customer.loyaltyYears > 5) {
+ return this.price * customer.discountRate;
+ }
+ return this.price;
+ }
+}
+```
+
+**示例(重构后):**
+```javascript
+class Customer {
+ getDiscountedPriceFor(price) {
+ if (this.loyaltyYears > 5) {
+ return price * this.discountRate;
+ }
+ return price;
+ }
+}
+```
+
+---
+
+### 不恰当的亲密
+
+**迹象:**
+- 类之间互相访问私有细节
+- 双向引用很多
+- 子类知道父类太多细节
+
+**为什么不好:**
+- 耦合高
+- 改一边会连带另一边
+- 难单独修改
+
+**可用重构:**
+- Move Method
+- Move Field
+- Change Bidirectional to Unidirectional
+- Extract Class
+- Hide Delegate
+
+---
+
+### 消息链
+
+**迹象:**
+- 方法调用链很长:`a.getB().getC().getD().getValue()`
+- 客户端依赖导航结构
+- “火车残骸”式代码
+
+**为什么不好:**
+- 很脆弱,任何一层变动都会坏
+- 违反迪米特法则
+- 绑定到对象结构
+
+**可用重构:**
+- Hide Delegate
+- Extract Method
+- Move Method
+
+**示例:**
+```javascript
+// 差:消息链
+const managerName = employee.getDepartment().getManager().getName();
+
+// 更好:隐藏委派
+const managerName = employee.getManagerName();
+```
+
+---
+
+### 中间人
+
+**迹象:**
+- 类只是把调用转发给另一个类
+- 一半以上的方法都是委派
+- 没有额外价值
+
+**为什么不好:**
+- 多了一层没必要的间接
+- 维护成本更高
+- 架构令人困惑
+
+**可用重构:**
+- Remove Middle Man
+- Inline Method
+
+---
+
+## 严重性指南
+
+| 严重性 | 说明 | 处理方式 |
+|--------|------|---------|
+| **Critical** | 阻塞开发,导致 bug | 立刻修复 |
+| **High** | 明显增加维护负担 | 本迭代修复 |
+| **Medium** | 有问题但还能接受 | 近期计划修复 |
+| **Low** | 小问题 | 视情况顺手修 |
+
+---
+
+## 快速检测清单
+
+扫描代码时使用这个清单:
+
+- [ ] 有没有超过 30 行的函数?
+- [ ] 有没有超过 300 行的类?
+- [ ] 有没有参数超过 4 个的函数?
+- [ ] 有没有重复代码块?
+- [ ] 有没有按类型码分支的 switch/case?
+- [ ] 有没有未使用的代码?
+- [ ] 有没有大量使用其他类数据的方法?
+- [ ] 有没有很长的方法调用链?
+- [ ] 有没有解释“是什么”而不是“为什么”的注释?
+- [ ] 有没有应该封装成对象的基础类型?
+
+---
+
+## 延伸阅读
+
+- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (2nd ed.)
+- Kerievsky, J. (2004). *Refactoring to Patterns*
+- Feathers, M. (2004). *Working Effectively with Legacy Code*
diff --git a/zh/03-skills/refactor/references/refactoring-catalog.md b/zh/03-skills/refactor/references/refactoring-catalog.md
new file mode 100644
index 0000000..5fd8b95
--- /dev/null
+++ b/zh/03-skills/refactor/references/refactoring-catalog.md
@@ -0,0 +1,1023 @@
+# 重构目录
+
+这是 Martin Fowler《Refactoring》(第 2 版)中的一份精选重构目录。每个重构都包含动机、操作步骤和示例。
+
+> “重构由它的操作步骤来定义,也就是你执行这个变化时遵循的精确过程。” — Martin Fowler
+
+---
+
+## 如何使用这个目录
+
+1. **识别异味**:先用代码异味目录定位问题
+2. **找到对应重构**:在这里查找匹配的手法
+3. **按步骤执行**:一步一步来
+4. **每步都测试**:确保行为不变
+
+**黄金法则**:如果某一步超过 10 分钟,就把它拆得更小。
+
+---
+
+## 最常见的重构
+
+### Extract Method
+
+**何时使用**:长函数、重复代码、需要为概念命名
+
+**动机**:把一段代码抽成一个名字能说明意图的方法。
+
+**步骤**:
+1. 创建一个新方法,名字应描述“做什么”而不是“怎么做”
+2. 把代码片段复制到新方法里
+3. 检查片段里用了哪些局部变量
+4. 把局部变量作为参数传入,或在方法内声明
+5. 正确处理返回值
+6. 用新方法调用替换原始片段
+7. 测试
+
+**前:**
+```javascript
+function printOwing(invoice) {
+ let outstanding = 0;
+
+ console.log("***********************");
+ console.log("**** Customer Owes ****");
+ console.log("***********************");
+
+ // Calculate outstanding
+ for (const order of invoice.orders) {
+ outstanding += order.amount;
+ }
+
+ // Print details
+ console.log(`name: ${invoice.customer}`);
+ console.log(`amount: ${outstanding}`);
+}
+```
+
+**后:**
+```javascript
+function printOwing(invoice) {
+ printBanner();
+ const outstanding = calculateOutstanding(invoice);
+ printDetails(invoice, outstanding);
+}
+
+function printBanner() {
+ console.log("***********************");
+ console.log("**** Customer Owes ****");
+ console.log("***********************");
+}
+
+function calculateOutstanding(invoice) {
+ return invoice.orders.reduce((sum, order) => sum + order.amount, 0);
+}
+
+function printDetails(invoice, outstanding) {
+ console.log(`name: ${invoice.customer}`);
+ console.log(`amount: ${outstanding}`);
+}
+```
+
+---
+
+### Inline Method
+
+**何时使用**:方法体和名字一样清楚,或者只是多余转发
+
+**动机**:当方法没有额外价值时,去掉不必要的间接层。
+
+**步骤**:
+1. 确认这个方法不是多态方法
+2. 找到所有调用点
+3. 用方法体替换每个调用
+4. 每替换一次就测试一次
+5. 删除方法定义
+
+**前:**
+```javascript
+function getRating(driver) {
+ return moreThanFiveLateDeliveries(driver) ? 2 : 1;
+}
+
+function moreThanFiveLateDeliveries(driver) {
+ return driver.numberOfLateDeliveries > 5;
+}
+```
+
+**后:**
+```javascript
+function getRating(driver) {
+ return driver.numberOfLateDeliveries > 5 ? 2 : 1;
+}
+```
+
+---
+
+### Extract Variable
+
+**何时使用**:复杂表达式难以理解
+
+**动机**:给复杂表达式的一部分起名字。
+
+**步骤**:
+1. 确保表达式没有副作用
+2. 声明一个不可变变量
+3. 将表达式结果赋给变量
+4. 用变量替换原表达式
+5. 测试
+
+**前:**
+```javascript
+return order.quantity * order.itemPrice -
+ Math.max(0, order.quantity - 500) * order.itemPrice * 0.05 +
+ Math.min(order.quantity * order.itemPrice * 0.1, 100);
+```
+
+**后:**
+```javascript
+const basePrice = order.quantity * order.itemPrice;
+const quantityDiscount = Math.max(0, order.quantity - 500) * order.itemPrice * 0.05;
+const shipping = Math.min(basePrice * 0.1, 100);
+return basePrice - quantityDiscount + shipping;
+```
+
+---
+
+### Inline Variable
+
+**何时使用**:变量名没有比表达式更清楚
+
+**动机**:移除没必要的间接层。
+
+**步骤**:
+1. 检查右侧表达式没有副作用
+2. 如果变量不是不可变的,先改成不可变并测试
+3. 找到第一次引用并替换成表达式
+4. 测试
+5. 对所有引用重复
+6. 删除变量声明和赋值
+7. 测试
+
+---
+
+### Rename Variable
+
+**何时使用**:名字没有清楚表达用途
+
+**动机**:好名字是清晰代码的基础。
+
+**步骤**:
+1. 如果变量使用范围很广,先考虑封装
+2. 找到所有引用
+3. 逐个修改引用
+4. 测试
+
+**提示**:
+- 使用能体现意图的名字
+- 避免缩写
+- 使用领域术语
+
+```javascript
+// Bad
+const d = 30;
+const x = users.filter(u => u.a);
+
+// Good
+const daysSinceLastLogin = 30;
+const activeUsers = users.filter(user => user.isActive);
+```
+
+---
+
+### Change Function Declaration
+
+**何时使用**:函数名不能清楚说明用途,参数也需要变化
+
+**动机**:好函数名能让代码自解释。
+
+**步骤(简单情况)**:
+1. 删除不需要的参数
+2. 修改函数名
+3. 添加需要的参数
+4. 测试
+
+**步骤(迁移式,适用于复杂改动)**:
+1. 如果要删除参数,确保它没有被使用
+2. 创建一个新函数,声明符合新设计
+3. 让旧函数调用新函数
+4. 测试
+5. 让调用方逐步改用新函数
+6. 每改一个调用点就测试
+7. 删除旧函数
+
+**前:**
+```javascript
+function circum(radius) {
+ return 2 * Math.PI * radius;
+}
+```
+
+**后:**
+```javascript
+function circumference(radius) {
+ return 2 * Math.PI * radius;
+}
+```
+
+---
+
+### Encapsulate Variable
+
+**何时使用**:多个地方直接访问某个数据
+
+**动机**:为数据访问提供明确入口。
+
+**步骤**:
+1. 创建 getter 和 setter
+2. 找到所有引用
+3. 用 getter 替换读取
+4. 用 setter 替换写入
+5. 每次改动后测试
+6. 降低变量可见性
+
+**前:**
+```javascript
+let defaultOwner = { firstName: "Martin", lastName: "Fowler" };
+
+// Used in many places
+spaceship.owner = defaultOwner;
+```
+
+**后:**
+```javascript
+let defaultOwnerData = { firstName: "Martin", lastName: "Fowler" };
+
+function defaultOwner() { return defaultOwnerData; }
+function setDefaultOwner(arg) { defaultOwnerData = arg; }
+
+spaceship.owner = defaultOwner();
+```
+
+---
+
+### Introduce Parameter Object
+
+**何时使用**:一组参数经常一起出现
+
+**动机**:把自然属于一起的数据打包起来。
+
+**步骤**:
+1. 为这组参数创建一个新类 / 结构
+2. 测试
+3. 用 Change Function Declaration 引入新对象
+4. 测试
+5. 逐个移除参数,改用对象字段
+6. 每次移除后测试
+
+**前:**
+```javascript
+function amountInvoiced(startDate, endDate) { ... }
+function amountReceived(startDate, endDate) { ... }
+function amountOverdue(startDate, endDate) { ... }
+```
+
+**后:**
+```javascript
+class DateRange {
+ constructor(start, end) {
+ this.start = start;
+ this.end = end;
+ }
+}
+
+function amountInvoiced(dateRange) { ... }
+function amountReceived(dateRange) { ... }
+function amountOverdue(dateRange) { ... }
+```
+
+---
+
+### Combine Functions into Class
+
+**何时使用**:多个函数操作同一份数据
+
+**动机**:把函数和它操作的数据放到一起。
+
+**步骤**:
+1. 对公共数据先做 Encapsulate Record
+2. 把每个函数移动到类里
+3. 每移动一次就测试
+4. 用类字段替代数据参数
+
+**前:**
+```javascript
+function base(reading) { ... }
+function taxableCharge(reading) { ... }
+function calculateBaseCharge(reading) { ... }
+```
+
+**后:**
+```javascript
+class Reading {
+ constructor(data) { this._data = data; }
+
+ get base() { ... }
+ get taxableCharge() { ... }
+ get calculateBaseCharge() { ... }
+}
+```
+
+---
+
+### Split Phase
+
+**何时使用**:代码在处理两件不同的事
+
+**动机**:把代码拆成边界清晰的两个阶段。
+
+**步骤**:
+1. 为第二阶段创建新函数
+2. 测试
+3. 在两个阶段之间引入中间数据结构
+4. 测试
+5. 把第一阶段提取成独立函数
+6. 测试
+
+**前:**
+```javascript
+function priceOrder(product, quantity, shippingMethod) {
+ const basePrice = product.basePrice * quantity;
+ const discount = Math.max(quantity - product.discountThreshold, 0)
+ * product.basePrice * product.discountRate;
+ const shippingPerCase = (basePrice > shippingMethod.discountThreshold)
+ ? shippingMethod.discountedFee : shippingMethod.feePerCase;
+ const shippingCost = quantity * shippingPerCase;
+ return basePrice - discount + shippingCost;
+}
+```
+
+**后:**
+```javascript
+function priceOrder(product, quantity, shippingMethod) {
+ const priceData = calculatePricingData(product, quantity);
+ return applyShipping(priceData, shippingMethod);
+}
+
+function calculatePricingData(product, quantity) {
+ const basePrice = product.basePrice * quantity;
+ const discount = Math.max(quantity - product.discountThreshold, 0)
+ * product.basePrice * product.discountRate;
+ return { basePrice, quantity, discount };
+}
+
+function applyShipping(priceData, shippingMethod) {
+ const shippingPerCase = (priceData.basePrice > shippingMethod.discountThreshold)
+ ? shippingMethod.discountedFee : shippingMethod.feePerCase;
+ const shippingCost = priceData.quantity * shippingPerCase;
+ return priceData.basePrice - priceData.discount + shippingCost;
+}
+```
+
+---
+
+## 移动特性
+
+### Move Method
+
+**何时使用**:方法更依赖另一个类的数据而不是自己类的数据
+
+**动机**:把函数放到它最依赖的数据所在的类里。
+
+**步骤**:
+1. 检查方法使用到的所有程序元素
+2. 确认方法不是多态的
+3. 把方法复制到目标类
+4. 调整上下文
+5. 让原方法委托给目标方法
+6. 测试
+7. 视情况删除原方法
+
+---
+
+### Move Field
+
+**何时使用**:字段更多被另一个类使用
+
+**动机**:让数据和使用它的函数靠在一起。
+
+**步骤**:
+1. 如果还没有,先封装字段
+2. 测试
+3. 在目标类中创建字段
+4. 把引用改成使用目标字段
+5. 测试
+6. 删除原字段
+
+---
+
+### Move Statements into Function
+
+**何时使用**:相同代码总是跟着函数调用一起出现
+
+**动机**:把重复语句移入函数,去掉重复。
+
+**步骤**:
+1. 如果还没有,先把重复代码提取成函数
+2. 把语句移入函数
+3. 测试
+4. 如果调用方不再需要独立语句,就删除它们
+
+---
+
+### Move Statements to Callers
+
+**何时使用**:不同调用方需要不同的行为
+
+**动机**:当行为需要差异化时,把它从函数里移出去。
+
+**步骤**:
+1. 先对要移动的代码做 Extract Method
+2. 再对原函数做 Inline Method
+3. 删除被内联后的调用
+4. 把提取出的代码移到各个调用方
+5. 测试
+
+---
+
+## 数据组织
+
+### Replace Primitive with Object
+
+**何时使用**:数据项需要的不只是简单值
+
+**动机**:把数据和行为封装在一起。
+
+**步骤**:
+1. 先做 Encapsulate Variable
+2. 创建一个简单值对象
+3. 修改 setter,让它创建新实例
+4. 修改 getter,让它返回值
+5. 测试
+6. 给新类增加更丰富的行为
+
+**前:**
+```javascript
+class Order {
+ constructor(data) {
+ this.priority = data.priority; // string: "high", "rush", etc.
+ }
+}
+
+// Usage
+if (order.priority === "high" || order.priority === "rush") { ... }
+```
+
+**后:**
+```javascript
+class Priority {
+ constructor(value) {
+ if (!Priority.legalValues().includes(value))
+ throw new Error(`Invalid priority: ${value}`);
+ this._value = value;
+ }
+
+ static legalValues() { return ['low', 'normal', 'high', 'rush']; }
+ get value() { return this._value; }
+
+ higherThan(other) {
+ return Priority.legalValues().indexOf(this._value) >
+ Priority.legalValues().indexOf(other._value);
+ }
+}
+
+// Usage
+if (order.priority.higherThan(new Priority("normal"))) { ... }
+```
+
+---
+
+### Replace Temp with Query
+
+**何时使用**:临时变量保存的是一个表达式结果
+
+**动机**:把表达式提取成函数,让代码更清晰。
+
+**步骤**:
+1. 确保变量只被赋值一次
+2. 把赋值右侧提取成一个方法
+3. 用方法调用替换临时变量引用
+4. 测试
+5. 删除临时变量声明和赋值
+
+**前:**
+```javascript
+const basePrice = this._quantity * this._itemPrice;
+if (basePrice > 1000) {
+ return basePrice * 0.95;
+} else {
+ return basePrice * 0.98;
+}
+```
+
+**后:**
+```javascript
+get basePrice() {
+ return this._quantity * this._itemPrice;
+}
+
+// In the method
+if (this.basePrice > 1000) {
+ return this.basePrice * 0.95;
+} else {
+ return this.basePrice * 0.98;
+}
+```
+
+---
+
+## 简化条件逻辑
+
+### Decompose Conditional
+
+**何时使用**:复杂条件语句
+
+**动机**:把条件和分支动作分别提取出来,让意图更清楚。
+
+**步骤**:
+1. 对条件做 Extract Method
+2. 对 then 分支做 Extract Method
+3. 对 else 分支也做 Extract Method(如果有)
+
+**前:**
+```javascript
+if (!aDate.isBefore(plan.summerStart) && !aDate.isAfter(plan.summerEnd)) {
+ charge = quantity * plan.summerRate;
+} else {
+ charge = quantity * plan.regularRate + plan.regularServiceCharge;
+}
+```
+
+**后:**
+```javascript
+if (isSummer(aDate, plan)) {
+ charge = summerCharge(quantity, plan);
+} else {
+ charge = regularCharge(quantity, plan);
+}
+
+function isSummer(date, plan) {
+ return !date.isBefore(plan.summerStart) && !date.isAfter(plan.summerEnd);
+}
+
+function summerCharge(quantity, plan) {
+ return quantity * plan.summerRate;
+}
+
+function regularCharge(quantity, plan) {
+ return quantity * plan.regularRate + plan.regularServiceCharge;
+}
+```
+
+---
+
+### Consolidate Conditional Expression
+
+**何时使用**:多个条件最后都返回同一个结果
+
+**动机**:让人一眼看出这些条件其实是一道检查。
+
+**步骤**:
+1. 确认条件没有副作用
+2. 用 and / or 合并条件
+3. 视情况对合并后的条件做 Extract Method
+
+**前:**
+```javascript
+if (employee.seniority < 2) return 0;
+if (employee.monthsDisabled > 12) return 0;
+if (employee.isPartTime) return 0;
+```
+
+**后:**
+```javascript
+if (isNotEligibleForDisability(employee)) return 0;
+
+function isNotEligibleForDisability(employee) {
+ return employee.seniority < 2 ||
+ employee.monthsDisabled > 12 ||
+ employee.isPartTime;
+}
+```
+
+---
+
+### Replace Nested Conditional with Guard Clauses
+
+**何时使用**:深层嵌套条件让流程难以追踪
+
+**动机**:用 guard clause 提前返回,让正常流程更清楚。
+
+**步骤**:
+1. 找出特殊情况
+2. 用提前返回的 guard clause 替换它们
+3. 每改一步就测试
+
+**前:**
+```javascript
+function payAmount(employee) {
+ let result;
+ if (employee.isSeparated) {
+ result = { amount: 0, reasonCode: "SEP" };
+ } else {
+ if (employee.isRetired) {
+ result = { amount: 0, reasonCode: "RET" };
+ } else {
+ result = calculateNormalPay(employee);
+ }
+ }
+ return result;
+}
+```
+
+**后:**
+```javascript
+function payAmount(employee) {
+ if (employee.isSeparated) return { amount: 0, reasonCode: "SEP" };
+ if (employee.isRetired) return { amount: 0, reasonCode: "RET" };
+ return calculateNormalPay(employee);
+}
+```
+
+---
+
+### Replace Conditional with Polymorphism
+
+**何时使用**:按类型分支的 switch / 条件逻辑
+
+**动机**:让对象自己处理自己的行为。
+
+**步骤**:
+1. 创建类层次(如果还没有)
+2. 用 Factory Function 创建对象
+3. 把条件逻辑移到超类方法里
+4. 给每种情况创建子类方法
+5. 删除原条件
+
+**前:**
+```javascript
+function plumages(birds) {
+ return birds.map(b => plumage(b));
+}
+
+function plumage(bird) {
+ switch (bird.type) {
+ case 'EuropeanSwallow':
+ return "average";
+ case 'AfricanSwallow':
+ return (bird.numberOfCoconuts > 2) ? "tired" : "average";
+ case 'NorwegianBlueParrot':
+ return (bird.voltage > 100) ? "scorched" : "beautiful";
+ default:
+ return "unknown";
+ }
+}
+```
+
+**后:**
+```javascript
+class Bird {
+ get plumage() { return "unknown"; }
+}
+
+class EuropeanSwallow extends Bird {
+ get plumage() { return "average"; }
+}
+
+class AfricanSwallow extends Bird {
+ get plumage() {
+ return (this.numberOfCoconuts > 2) ? "tired" : "average";
+ }
+}
+
+class NorwegianBlueParrot extends Bird {
+ get plumage() {
+ return (this.voltage > 100) ? "scorched" : "beautiful";
+ }
+}
+
+function createBird(data) {
+ switch (data.type) {
+ case 'EuropeanSwallow': return new EuropeanSwallow(data);
+ case 'AfricanSwallow': return new AfricanSwallow(data);
+ case 'NorwegianBlueParrot': return new NorwegianBlueParrot(data);
+ default: return new Bird(data);
+ }
+}
+```
+
+---
+
+### Introduce Special Case (Null Object)
+
+**何时使用**:重复出现 null 检查
+
+**动机**:返回一个特殊对象来处理特殊情况。
+
+**步骤**:
+1. 创建一个具备预期接口的特殊情况类
+2. 增加 isSpecialCase 检查
+3. 引入工厂方法
+4. 用特殊对象替换 null 检查
+5. 测试
+
+**前:**
+```javascript
+const customer = site.customer;
+// ... many places checking
+if (customer === "unknown") {
+ customerName = "occupant";
+} else {
+ customerName = customer.name;
+}
+```
+
+**后:**
+```javascript
+class UnknownCustomer {
+ get name() { return "occupant"; }
+ get billingPlan() { return registry.defaultPlan; }
+}
+
+// Factory method
+function customer(site) {
+ return site.customer === "unknown"
+ ? new UnknownCustomer()
+ : site.customer;
+}
+
+// Usage - no null checks needed
+const customerName = customer.name;
+```
+
+---
+
+## 重构 API
+
+### Separate Query from Modifier
+
+**何时使用**:函数既返回值又有副作用
+
+**动机**:明确哪些操作会产生副作用。
+
+**步骤**:
+1. 创建新的查询函数
+2. 复制原函数的返回逻辑
+3. 修改原函数,让它只负责副作用
+4. 替换依赖返回值的调用点
+5. 测试
+
+**前:**
+```javascript
+function alertForMiscreant(people) {
+ for (const p of people) {
+ if (p === "Don") {
+ setOffAlarms();
+ return "Don";
+ }
+ if (p === "John") {
+ setOffAlarms();
+ return "John";
+ }
+ }
+ return "";
+}
+```
+
+**后:**
+```javascript
+function findMiscreant(people) {
+ for (const p of people) {
+ if (p === "Don") return "Don";
+ if (p === "John") return "John";
+ }
+ return "";
+}
+
+function alertForMiscreant(people) {
+ if (findMiscreant(people) !== "") setOffAlarms();
+}
+```
+
+---
+
+### Parameterize Function
+
+**何时使用**:有多个做类似事情但数值不同的函数
+
+**动机**:通过参数化减少重复。
+
+**步骤**:
+1. 选择一个函数
+2. 为变化的字面值增加参数
+3. 修改函数体使用该参数
+4. 测试
+5. 让调用方改用参数化版本
+6. 删除不再使用的旧函数
+
+**前:**
+```javascript
+function tenPercentRaise(person) {
+ person.salary = person.salary * 1.10;
+}
+
+function fivePercentRaise(person) {
+ person.salary = person.salary * 1.05;
+}
+```
+
+**后:**
+```javascript
+function raise(person, factor) {
+ person.salary = person.salary * (1 + factor);
+}
+
+// Usage
+raise(person, 0.10);
+raise(person, 0.05);
+```
+
+---
+
+### Remove Flag Argument
+
+**何时使用**:布尔参数改变函数行为
+
+**动机**:通过拆分成明确函数,让行为更清楚。
+
+**步骤**:
+1. 针对不同旗标值创建显式函数
+2. 替换每个调用点
+3. 每次改动后测试
+4. 删除原函数
+
+**前:**
+```javascript
+function bookConcert(customer, isPremium) {
+ if (isPremium) {
+ // premium booking logic
+ } else {
+ // regular booking logic
+ }
+}
+
+bookConcert(customer, true);
+bookConcert(customer, false);
+```
+
+**后:**
+```javascript
+function bookPremiumConcert(customer) {
+ // premium booking logic
+}
+
+function bookRegularConcert(customer) {
+ // regular booking logic
+}
+
+bookPremiumConcert(customer);
+bookRegularConcert(customer);
+```
+
+---
+
+## 继承相关
+
+### Pull Up Method
+
+**何时使用**:多个子类里有相同方法
+
+**动机**:去掉类层次中的重复。
+
+**步骤**:
+1. 检查方法是否完全相同
+2. 确认签名一致
+3. 在超类中新建方法
+4. 从一个子类复制实现
+5. 删除一个子类中的方法并测试
+6. 删除其他子类中的方法并测试
+
+---
+
+### Push Down Method
+
+**何时使用**:某个行为只适用于部分子类
+
+**动机**:把方法放到真正使用它的地方。
+
+**步骤**:
+1. 把方法复制到需要它的子类
+2. 从超类删除方法
+3. 测试
+4. 删除不需要该方法的子类副本
+5. 测试
+
+---
+
+### Replace Subclass with Delegate
+
+**何时使用**:继承用得不对,需要更灵活
+
+**动机**:在合适的地方更偏向组合而不是继承。
+
+**步骤**:
+1. 创建一个空的委托类
+2. 在宿主类中加一个持有委托的字段
+3. 在宿主类构造委托
+4. 把功能迁移到委托类
+5. 每次迁移后测试
+6. 用委托替代继承
+
+---
+
+## Extract Class
+
+**何时使用**:大类里有多个职责
+
+**动机**:拆分类以维持单一职责。
+
+**步骤**:
+1. 决定如何拆分职责
+2. 创建新类
+3. 把字段从原类移到新类
+4. 测试
+5. 把方法从原类移到新类
+6. 每次移动后测试
+7. 重新检查并命名两个类
+8. 决定如何暴露新类
+
+**前:**
+```javascript
+class Person {
+ get name() { return this._name; }
+ set name(arg) { this._name = arg; }
+ get officeAreaCode() { return this._officeAreaCode; }
+ set officeAreaCode(arg) { this._officeAreaCode = arg; }
+ get officeNumber() { return this._officeNumber; }
+ set officeNumber(arg) { this._officeNumber = arg; }
+
+ get telephoneNumber() {
+ return `(${this._officeAreaCode}) ${this._officeNumber}`;
+ }
+}
+```
+
+**后:**
+```javascript
+class Person {
+ constructor() {
+ this._telephoneNumber = new TelephoneNumber();
+ }
+ get name() { return this._name; }
+ set name(arg) { this._name = arg; }
+ get telephoneNumber() { return this._telephoneNumber.toString(); }
+ get officeAreaCode() { return this._telephoneNumber.areaCode; }
+ set officeAreaCode(arg) { this._telephoneNumber.areaCode = arg; }
+}
+
+class TelephoneNumber {
+ get areaCode() { return this._areaCode; }
+ set areaCode(arg) { this._areaCode = arg; }
+ get number() { return this._number; }
+ set number(arg) { this._number = arg; }
+ toString() { return `(${this._areaCode}) ${this._number}`; }
+}
+```
+
+---
+
+## 快速参考:异味到重构
+
+| 代码异味 | 主要重构 | 备选方案 |
+|----------|---------|---------|
+| 长函数 | Extract Method | Replace Temp with Query |
+| 重复代码 | Extract Method | Pull Up Method |
+| 大类 | Extract Class | Extract Subclass |
+| 长参数列表 | Introduce Parameter Object | Preserve Whole Object |
+| Feature Envy | Move Method | Extract Method + Move |
+| 数据泥团 | Extract Class | Introduce Parameter Object |
+| 基础类型沉迷 | Replace Primitive with Object | Replace Type Code |
+| switch 语句 | Replace Conditional with Polymorphism | Replace Type Code |
+| 临时字段 | Extract Class | Introduce Null Object |
+| 消息链 | Hide Delegate | Extract Method |
+| 中间人 | Remove Middle Man | Inline Method |
+| 发散式变化 | Extract Class | Split Phase |
+| 散弹式修改 | Move Method | Inline Class |
+| 死代码 | Remove Dead Code | - |
+| 臆想泛化 | Collapse Hierarchy | Inline Class |
+
+---
+
+## 延伸阅读
+
+- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (第 2 版)
+- 在线目录:https://refactoring.com/catalog/
diff --git a/zh/03-skills/refactor/templates/refactoring-plan.md b/zh/03-skills/refactor/templates/refactoring-plan.md
new file mode 100644
index 0000000..82e9b7a
--- /dev/null
+++ b/zh/03-skills/refactor/templates/refactoring-plan.md
@@ -0,0 +1,284 @@
+# 重构计划模板
+
+使用这个模板来记录和跟踪你的重构工作。
+
+---
+
+## 项目信息
+
+| 字段 | 值 |
+|-------|-------|
+| **项目 / 模块** | [项目名称] |
+| **目标文件** | [要重构的文件列表] |
+| **创建日期** | [日期] |
+| **作者** | [姓名] |
+| **状态** | Draft / In Review / Approved / In Progress / Completed |
+
+---
+
+## 执行摘要
+
+### 目标
+- [ ] [主要目标:例如,提升支付流程可读性]
+- [ ] [次要目标:例如,减少重复代码]
+- [ ] [第三目标:例如,提升可测试性]
+
+### 约束
+- [ ] [约束 1:例如,不能改公共 API]
+- [ ] [约束 2:例如,必须保持向后兼容]
+- [ ] [约束 3:例如,不能改数据库 schema]
+
+### 风险等级
+- [ ] Low - 小改动,测试充分
+- [ ] Medium - 中等改动,有一定风险
+- [ ] High - 大改动,需要特别注意
+
+---
+
+## 重构前检查清单
+
+### 测试覆盖评估
+
+| 指标 | 当前值 | 目标值 | 状态 |
+|--------|---------|---------|--------|
+| 单元测试覆盖率 | __% | ≥80% | |
+| 集成测试 | Yes/No | Yes | |
+| 所有测试通过 | Yes/No | Yes | |
+
+### 开始前必须满足
+- [ ] 所有测试通过
+- [ ] 已读懂并审查代码
+- [ ] 已有备份 / 版本控制
+- [ ] 已获得用户批准
+
+---
+
+## 已识别的代码异味
+
+### 摘要
+
+| # | 异味 | 位置 | 严重性 | 优先级 |
+|---|-------|------|------|------|
+| 1 | [例如,Long Method] | [file:line] | High | P1 |
+| 2 | [例如,Duplicate Code] | [file:line] | Medium | P2 |
+| 3 | [例如,Feature Envy] | [file:line] | Low | P3 |
+
+### 详细分析
+
+#### 异味 #1:[名称]
+
+**位置**:`path/to/file.js:45-120`
+
+**描述**:[对问题的详细描述]
+
+**影响**:
+- [影响 1]
+- [影响 2]
+
+**建议方案**:[如何修复的简要说明]
+
+---
+
+## 重构阶段
+
+### 阶段 A:快速收益(低风险)
+
+**目标**:快速、低风险的改进,立刻产生价值
+
+**预计改动**:[X 个文件,Y 个方法]
+
+**需要用户批准**:Yes / No
+
+| # | 任务 | 文件 | 重构手法 | 状态 |
+|---|------|------|----------|------|
+| A1 | 将变量 `x` 重命名为 `userCount` | utils.js:15 | Rename Variable | [ ] |
+| A2 | 删除未使用的 `oldHandler()` | api.js:89 | Remove Dead Code | [ ] |
+| A3 | 提取重复的验证逻辑 | form.js:23,67 | Extract Method | [ ] |
+
+**回滚方案**:回退 A1-A3 的提交
+
+---
+
+### 阶段 B:结构优化(中风险)
+
+**目标**:改善代码组织和清晰度
+
+**预计改动**:[X 个文件,Y 个方法]
+
+**需要用户批准**:Yes
+
+**依赖**:必须先完成阶段 A
+
+| # | 任务 | 文件 | 重构手法 | 状态 |
+|---|------|------|----------|------|
+| B1 | 从长函数中提取 `calculatePrice()` | order.js:45 | Extract Method | [ ] |
+| B2 | 引入 `OrderDetails` 参数对象 | order.js:12 | Introduce Parameter Object | [ ] |
+| B3 | 将 `formatAddress()` 移动到 Address 类 | customer.js:78 | Move Method | [ ] |
+
+**回滚方案**:回滚到阶段 A 完成后的提交
+
+---
+
+### 阶段 C:架构改动(高风险)
+
+**目标**:处理更深层的结构问题
+
+**预计改动**:[X 个文件,Y 个方法]
+
+**需要用户批准**:Yes
+
+**依赖**:必须先完成阶段 A 和 B
+
+| # | 任务 | 文件 | 重构手法 | 状态 |
+|---|------|------|----------|------|
+| C1 | 用多态替换价格 switch | pricing.js:30 | Replace Conditional with Polymorphism | [ ] |
+| C2 | 提取 `NotificationService` 类 | user.js:100 | Extract Class | [ ] |
+
+**回滚方案**:回滚到阶段 B 完成后的提交
+
+---
+
+## 详细重构步骤
+
+### 任务 [ID]:[任务名称]
+
+**对应异味**:[异味名称]
+
+**重构手法**:[手法名称]
+
+**风险等级**:Low / Medium / High
+
+#### 上下文
+
+**重构前**(当前状态):
+```javascript
+// 把当前代码贴在这里
+```
+
+**重构后**(期望状态):
+```javascript
+// 把期望代码贴在这里
+```
+
+#### 逐步操作
+
+1. [ ] **步骤 1**:[描述]
+ - 测试:完成此步后运行测试
+ - 预期:所有测试通过
+
+2. [ ] **步骤 2**:[描述]
+ - 测试:完成此步后运行测试
+ - 预期:所有测试通过
+
+3. [ ] **步骤 3**:[描述]
+ - 测试:完成此步后运行测试
+ - 预期:所有测试通过
+
+#### 验证
+
+- [ ] 所有测试通过
+- [ ] 行为未改变
+- [ ] 代码可编译
+- [ ] 没有新的警告
+
+#### 提交信息
+```
+refactor: [描述这次重构]
+```
+
+---
+
+## 进度跟踪
+
+### 阶段状态
+
+| 阶段 | 状态 | 开始时间 | 完成时间 | 测试是否通过 |
+|------|------|----------|----------|--------------|
+| A | Not Started / In Progress / Done | | | |
+| B | Not Started / In Progress / Done | | | |
+| C | Not Started / In Progress / Done | | | |
+
+### 遇到的问题
+
+| # | 问题 | 解决方案 | 状态 |
+|---|------|----------|------|
+| 1 | [描述] | [如何解决] | Open / Resolved |
+
+---
+
+## 指标对比
+
+### 重构前
+
+| 指标 | 文件 1 | 文件 2 | 总计 |
+|------|------|------|------|
+| 代码行数 | | | |
+| 圈复杂度 | | | |
+| 可维护性指标 | | | |
+| 方法数量 | | | |
+| 平均方法长度 | | | |
+
+### 重构后
+
+| 指标 | 文件 1 | 文件 2 | 总计 | 变化 |
+|------|------|------|------|------|
+| 代码行数 | | | | |
+| 圈复杂度 | | | | |
+| 可维护性指标 | | | | |
+| 方法数量 | | | | |
+| 平均方法长度 | | | | |
+
+---
+
+## 重构后检查清单
+
+- [ ] 所有测试通过
+- [ ] 没有新的警告或错误
+- [ ] 代码成功编译
+- [ ] 已完成手工验证
+- [ ] 文档已更新(如需要)
+- [ ] 已完成代码审查
+- [ ] 指标有改善
+- [ ] 已获得用户签字确认
+
+---
+
+## 经验总结
+
+### 做得好的地方
+- [Item 1]
+- [Item 2]
+
+### 可以改进的地方
+- [Item 1]
+- [Item 2]
+
+### 未来建议
+- [Item 1]
+- [Item 2]
+
+---
+
+## 批准
+
+| 角色 | 姓名 | 日期 | 签名 |
+|------|------|------|------|
+| Plan Author | | | |
+| Technical Lead | | | |
+| Product Owner | | | |
+
+---
+
+## 附录
+
+### A. 相关文档
+- [相关文档链接]
+
+### B. 参考资料
+- [代码异味目录]
+- [重构目录]
+
+### C. 使用的工具
+- [测试框架]
+- [Lint 工具]
+- [复杂度分析工具]
diff --git a/zh/04-subagents/README.md b/zh/04-subagents/README.md
new file mode 100644
index 0000000..7d55a10
--- /dev/null
+++ b/zh/04-subagents/README.md
@@ -0,0 +1,380 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Subagents 完整参考
+
+## 概览
+
+Subagents 是专门处理某类任务的独立 AI 助手。它们拥有隔离的上下文、自己的提示词和工具权限,适合把复杂工作拆分给不同角色。
+
+## 主要好处
+
+- 上下文隔离
+- 角色分工清晰
+- 适合并行和委派
+- 便于把复杂任务拆开
+
+## 文件位置
+
+- 项目级:`.claude/agents/`
+- 用户级:`~/.claude/agents/`
+
+## 配置
+
+### 文件格式
+
+Subagent 通常是一个带 frontmatter 的 Markdown 文件。
+
+```yaml
+---
+name: code-reviewer
+description: 审查代码质量和安全问题
+tools: Read, Grep, Bash
+---
+
+# Code Reviewer
+```
+
+### 配置字段
+
+| 字段 | 说明 |
+|------|------|
+| `name` | subagent 名称 |
+| `description` | 何时该调用它 |
+| `tools` | 允许使用的工具 |
+| `model` | 指定模型 |
+| `prompt` | 任务提示词 |
+| `context` | 上下文策略 |
+
+### 工具配置选项
+
+- 只读审查
+- 限制 Bash
+- 允许更强工具集
+
+### 基于 CLI 的配置
+
+你也可以通过命令行或设置文件定义 subagent。
+
+## 内置 Subagents
+
+Claude Code 自带一些常见角色,例如:
+
+- 通用助手
+- Planning agent
+- Explore agent
+- Bash agent
+- Statusline 相关 agent
+- Claude Code Guide agent
+
+## 管理 Subagents
+
+### 使用 `/agents` 命令(推荐)
+
+```bash
+/agents
+```
+
+### 直接管理文件
+
+#### 创建项目 subagent
+
+```bash
+mkdir -p .claude/agents
+```
+
+#### 创建用户 subagent
+
+```bash
+mkdir -p ~/.claude/agents
+```
+
+## 使用 Subagents
+
+### 自动委派
+
+主 agent 可以根据任务描述自动把工作分配给合适的 subagent。
+
+### 显式调用
+
+你也可以明确让 Claude 使用某个 subagent。
+
+### `@` 提及调用
+
+在一些场景里,可以通过 `@agent-name` 方式引用。
+
+### 会话级 agent
+
+可以在整个会话中固定使用某个 agent。
+
+### 列出可用 agents
+
+```bash
+claude agents
+```
+
+## 可恢复的 agents
+
+某些 subagent 可以先启动,之后再恢复,便于长任务接力。
+
+## 串联 Subagents
+
+复杂任务里可以让多个 subagent 依次协作,例如:
+
+1. 代码审查
+2. 测试生成
+3. 文档更新
+
+## Subagents 的持久记忆
+
+Subagents 可以拥有自己的 memory 范围,让它们在各自职责内保持一致。
+
+### Memory 范围
+
+- 项目级
+- 用户级
+- 子目录级
+
+### 工作方式
+
+Subagent 会在自己的上下文中读取对应记忆,不和主会话完全混在一起。
+
+## 后台 Subagents
+
+### 配置
+
+有些 subagent 可以作为后台任务执行,不阻塞主会话。
+
+### 快捷键
+
+在支持的界面中,可用快捷键查看或切换后台 subagent。
+
+### 关闭后台任务
+
+如果你不想让任务后台运行,可以在设置中关闭。
+
+## Worktree 隔离
+
+### 配置
+
+可以为 subagent 分配独立的 worktree。
+
+### 工作方式
+
+这样不同任务就不会互相污染文件状态。
+
+## 限制可启动的 Subagents
+
+你可以限制 Claude 只能 spawn 某些 subagent,以降低风险。
+
+### 示例
+
+- 只允许审查类 agent
+- 禁止高风险自动化 agent
+
+## `claude agents` CLI 命令
+
+用于查看和管理当前可用的 agent。
+
+## Agent Teams(实验性)
+
+Agent teams 是更高级的协作模式,适合多个 subagent 并行处理复杂任务。
+
+### Subagents vs Agent Teams
+
+- Subagents 侧重委派单个任务
+- Agent teams 侧重多角色协作
+
+### 启用 Agent Teams
+
+通过设置打开实验性功能。
+
+### 启动团队
+
+团队模式会把不同任务分配给不同角色。
+
+### 显示模式
+
+可以选择更适合终端或图形界面的显示方式。
+
+### 导航
+
+你可以在 team 中切换角色、查看状态和读取消息。
+
+### 团队配置
+
+适合为大型流程定义清晰角色。
+
+### 架构
+
+agent team 本质上是多个专门角色围绕同一任务协作。
+
+### 任务分配与消息
+
+主 agent 会负责把任务拆分并转发给对应 subagent。
+
+### 计划审批流程
+
+如果是 plan 驱动流程,团队会先审计划再执行。
+
+### 团队相关 hook 事件
+
+一些 hook 可以在 team 生命周期里触发。
+
+### 最佳实践
+
+- 角色定义要清楚
+- 任务边界要明确
+- 不要让多个 agent 做重复工作
+
+### 局限
+
+- 实验性功能可能会变化
+- 复杂团队需要更多配置
+
+## 插件中的 Subagent 安全
+
+插件分发的 subagent 要特别注意权限、工具范围和边界条件。
+
+## 架构
+
+### 高层架构
+
+主 agent、subagent、文件系统和工具权限共同构成执行链。
+
+### 生命周期
+
+1. 创建
+2. 分配任务
+3. 执行
+4. 返回结果
+5. 结束或恢复
+
+## 上下文管理
+
+### 关键点
+
+- 子上下文尽量小
+- 让每个 subagent 只负责自己的事
+- 避免把所有信息都塞进去
+
+### 性能考虑
+
+过多的上下文会拖慢速度并降低准确性。
+
+### 关键行为
+
+subagent 在隔离上下文里工作,但仍能把结果汇总回主会话。
+
+## 什么时候使用 Subagents
+
+- 任务可拆分
+- 需要隔离上下文
+- 需要明确角色分工
+- 需要并行协作
+
+## 最佳实践
+
+### 设计原则
+
+- 单一职责
+- 描述明确
+- 工具权限最小化
+
+### System Prompt 最佳实践
+
+- 任务说明要具体
+- 不要写太长
+- 只保留执行任务所需的信息
+
+### 工具访问策略
+
+- 审查型 subagent 只读
+- 实现型 subagent 适度开放写权限
+- 高风险动作要保持审批
+
+## 本目录中的示例 Subagents
+
+### 1. [Code Reviewer](./code-reviewer.md)
+
+用于全面代码质量审查。
+
+### 2. [Test Engineer](./test-engineer.md)
+
+用于测试策略、覆盖率和测试生成。
+
+### 3. [Documentation Writer](./documentation-writer.md)
+
+用于技术文档写作和更新。
+
+### 4. [Secure Reviewer](./secure-reviewer.md)
+
+用于安全检查,通常只读。
+
+### 5. [Implementation Agent](./implementation-agent.md)
+
+用于功能实现和代码修改。
+
+### 6. [Debugger](./debugger.md)
+
+用于定位 bug 和分析异常。
+
+### 7. [Data Scientist](./data-scientist.md)
+
+用于分析数据、解释结果和生成报告。
+
+### 8. [Clean Code Reviewer](./clean-code-reviewer.md)
+
+用于按 Clean Code 原则做专门审查。
+
+## 安装说明
+
+### 方法 1:使用 `/agents`
+
+```bash
+/agents
+```
+
+### 方法 2:复制到项目
+
+```bash
+mkdir -p .claude/agents
+cp 04-subagents/*.md .claude/agents/
+```
+
+### 方法 3:复制到用户目录
+
+```bash
+mkdir -p ~/.claude/agents
+cp 04-subagents/*.md ~/.claude/agents/
+```
+
+### 验证
+
+- 运行 `/agents`
+- 检查对应 agent 是否出现在列表中
+- 试着让 Claude 委派一个简单任务
+
+## 文件结构
+
+```text
+.claude/agents/
+├── clean-code-reviewer.md
+├── code-reviewer.md
+├── data-scientist.md
+├── debugger.md
+├── documentation-writer.md
+├── implementation-agent.md
+├── secure-reviewer.md
+├── test-engineer.md
+└── README.md
+```
+
+## 相关概念
+
+- [Skills 中文指南](../03-skills/README.md)
+- [Memory 中文指南](../02-memory/README.md)
+- [Hooks 中文指南](../06-hooks/README.md)
+- [Plugins 中文指南](../07-plugins/README.md)
diff --git a/zh/04-subagents/clean-code-reviewer.md b/zh/04-subagents/clean-code-reviewer.md
new file mode 100644
index 0000000..87a9fa5
--- /dev/null
+++ b/zh/04-subagents/clean-code-reviewer.md
@@ -0,0 +1,66 @@
+---
+name: clean-code-reviewer
+description: Clean Code 原则执行专家。审查代码中的 Clean Code 理论和最佳实践违规。写完代码后建议主动使用,确保可维护性和专业质量。
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+# Clean Code Reviewer Agent
+
+你是一名资深代码审查员,专注于 Clean Code 原则(Robert C. Martin)。你需要识别违规点并给出可执行的修复建议。
+
+## 流程
+1. 运行 `git diff` 查看最近的变更
+2. 认真阅读相关文件
+3. 提供带有 `file:line`、代码片段和修复建议的审查结果
+
+## 检查重点
+
+**命名**:要能体现意图、可发音、可搜索。不要使用编码或前缀。类名用名词,方法名用动词。
+
+**函数**:少于 20 行,只做一件事,最多 3 个参数,不要 flag 参数,不要副作用,不要返回 null。
+
+**注释**:代码应当足够自解释。删除被注释掉的代码,不要写冗余或误导性的注释。
+
+**结构**:保持类小而专注,单一职责,高内聚,低耦合。避免上帝类。
+
+**SOLID**:单一职责、开闭原则、里氏替换、接口隔离、依赖倒置。
+
+**DRY/KISS/YAGNI**:不要重复,保持简单,不要为假设中的未来过度设计。
+
+**错误处理**:使用异常而不是错误码,提供上下文,永远不要返回或传递 null。
+
+**坏味道**:死代码、特性依恋、长参数列表、消息链、基本类型偏执、投机性泛化。
+
+## 严重级别
+- **Critical**:函数超过 50 行,5 个及以上参数,4 层及以上嵌套,多重职责
+- **High**:函数 20 到 50 行,4 个参数,命名不清晰,重复较多
+- **Medium**:轻微重复、用注释解释代码、格式问题
+- **Low**:轻微的可读性或组织性改进
+
+## 输出格式
+
+```text
+# Clean Code Review
+
+## Summary
+Files: [n] | Critical: [n] | High: [n] | Medium: [n] | Low: [n]
+
+## Violations
+
+**[Severity] [Category]** `file:line`
+> [code snippet]
+Problem: [what's wrong]
+Fix: [how to fix]
+
+## Good Practices
+[What's done well]
+```
+
+## 指南
+- 要具体:精确到代码和行号
+- 要建设性:解释为什么,并给出修复方式
+- 要务实:关注影响,跳过无关痛痒的小问题
+- 跳过:生成代码、配置文件、测试夹具
+
+**核心理念**:代码被阅读的次数是写作的 10 倍。优化可读性,而不是炫技。
diff --git a/zh/04-subagents/code-reviewer.md b/zh/04-subagents/code-reviewer.md
new file mode 100644
index 0000000..3db98a8
--- /dev/null
+++ b/zh/04-subagents/code-reviewer.md
@@ -0,0 +1,61 @@
+---
+name: code-reviewer
+description: 代码审查专家。写完或修改代码后建议主动使用,确保质量、安全性和可维护性。
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+# Code Reviewer Agent
+
+你是一名资深代码审查员,负责确保代码质量和安全性维持在高标准。
+
+被调用时:
+1. 运行 `git diff` 查看最近的变更
+2. 重点检查被修改的文件
+3. 立即开始审查
+
+## 审查优先级(按顺序)
+
+1. **安全问题** - 身份验证、授权、数据泄露
+2. **性能问题** - O(n^2) 操作、内存泄漏、低效查询
+3. **代码质量** - 可读性、命名、文档
+4. **测试覆盖率** - 缺失测试、边界情况
+5. **设计模式** - SOLID 原则、架构
+
+## 审查清单
+
+- 代码清晰易读
+- 函数和变量命名合理
+- 没有重复代码
+- 错误处理正确
+- 没有暴露密钥或 API key
+- 已实现输入校验
+- 测试覆盖充分
+- 已考虑性能问题
+
+## 审查输出格式
+
+对每个问题都要提供:
+- **Severity**: Critical / High / Medium / Low
+- **Category**: Security / Performance / Quality / Testing / Design
+- **Location**: 文件路径和行号
+- **Issue Description**: 问题是什么,为什么有问题
+- **Suggested Fix**: 代码示例
+- **Impact**: 这会怎样影响系统
+
+请按优先级组织反馈:
+1. Critical issues(必须修)
+2. Warnings(应该修)
+3. Suggestions(可考虑改进)
+
+请给出具体的修复示例。
+
+## 审查示例
+
+### 问题:N+1 查询
+- **Severity**: High
+- **Category**: Performance
+- **Location**: src/user-service.ts:45
+- **Issue**: 循环在每次迭代中都执行数据库查询
+- **Fix**: 使用 JOIN 或批量查询
+- **Impact**: 响应时间会随着数据量线性增长
diff --git a/zh/04-subagents/data-scientist.md b/zh/04-subagents/data-scientist.md
new file mode 100644
index 0000000..2bdb2e6
--- /dev/null
+++ b/zh/04-subagents/data-scientist.md
@@ -0,0 +1,97 @@
+---
+name: data-scientist
+description: 数据分析专家,擅长 SQL 查询、BigQuery 操作和数据洞察。适用于数据分析任务和查询场景。
+tools: Bash, Read, Write
+model: sonnet
+---
+
+# Data Scientist Agent
+
+你是一名专注于 SQL 和 BigQuery 分析的数据科学家。
+
+被调用时:
+1. 理解数据分析需求
+2. 编写高效的 SQL 查询
+3. 在合适时使用 BigQuery 命令行工具(`bq`)
+4. 分析并总结结果
+5. 清晰地呈现发现
+
+## 核心实践
+
+- 编写经过优化的 SQL 查询,并使用合适的过滤条件
+- 使用恰当的聚合和 join
+- 为复杂逻辑添加注释
+- 让结果易于阅读
+- 提供数据驱动的建议
+
+## SQL 最佳实践
+
+### 查询优化
+
+- 使用 `WHERE` 尽早过滤
+- 使用合适的索引
+- 生产环境避免 `SELECT *`
+- 探索数据时限制结果集
+
+### BigQuery 相关
+
+```bash
+# 运行查询
+bq query --use_legacy_sql=false 'SELECT * FROM dataset.table LIMIT 10'
+
+# 导出结果
+bq query --use_legacy_sql=false --format=csv 'SELECT ...' > results.csv
+
+# 查看表结构
+bq show --schema dataset.table
+```
+
+## 分析类型
+
+1. **探索性分析**
+ - 数据剖析
+ - 分布分析
+ - 缺失值检测
+
+2. **统计分析**
+ - 聚合与汇总
+ - 趋势分析
+ - 相关性检测
+
+3. **报告**
+ - 提取关键指标
+ - 环比/同比对比
+ - 面向管理层的总结
+
+## 输出格式
+
+对每次分析,提供:
+- **Objective**: 我们在回答什么问题
+- **Query**: 使用的 SQL(带注释)
+- **Results**: 关键发现
+- **Insights**: 基于数据的结论
+- **Recommendations**: 建议的下一步
+
+## 示例查询
+
+```sql
+-- 月活跃用户趋势
+SELECT
+ DATE_TRUNC(created_at, MONTH) as month,
+ COUNT(DISTINCT user_id) as active_users,
+ COUNT(*) as total_events
+FROM events
+WHERE
+ created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH)
+ AND event_type = 'login'
+GROUP BY 1
+ORDER BY 1 DESC;
+```
+
+## 分析检查清单
+
+- [ ] 已理解需求
+- [ ] 查询已优化
+- [ ] 结果已验证
+- [ ] 发现已记录
+- [ ] 建议已提供
diff --git a/zh/04-subagents/debugger.md b/zh/04-subagents/debugger.md
new file mode 100644
index 0000000..ecb2a1b
--- /dev/null
+++ b/zh/04-subagents/debugger.md
@@ -0,0 +1,80 @@
+---
+name: debugger
+description: 排错专家,负责处理错误、测试失败和异常行为。遇到问题时建议主动使用。
+tools: Read, Edit, Bash, Grep, Glob
+model: inherit
+---
+
+# Debugger Agent
+
+你是一名擅长根因分析的专家级排错人员。
+
+被调用时:
+1. 获取错误信息和堆栈追踪
+2. 找到复现步骤
+3. 定位故障位置
+4. 实施最小修复
+5. 验证修复有效
+
+## 排错流程
+
+1. **分析错误信息和日志**
+ - 阅读完整错误信息
+ - 检查堆栈追踪
+ - 查看最近的日志输出
+
+2. **检查最近的代码变更**
+ - 运行 `git diff` 查看修改
+ - 找出可能破坏行为的改动
+ - 回看提交历史
+
+3. **提出并测试假设**
+ - 从最可能的原因开始
+ - 添加有针对性的调试日志
+ - 检查变量状态
+
+4. **隔离故障**
+ - 缩小到具体函数或行号
+ - 创建最小复现案例
+ - 验证隔离结果
+
+5. **实现并验证修复**
+ - 做最小必要修改
+ - 运行测试确认修复
+ - 检查回归问题
+
+## 调试输出格式
+
+针对每个问题,提供:
+- **Error**: 原始错误信息
+- **Root Cause**: 为什么会失败
+- **Evidence**: 你如何确定原因
+- **Fix**: 具体做了哪些代码修改
+- **Testing**: 如何验证修复
+- **Prevention**: 如何避免再次发生
+
+## 常用调试命令
+
+```bash
+# 查看最近变更
+git diff HEAD~3
+
+# 搜索错误模式
+grep -r "error" --include="*.log"
+
+# 查找相关代码
+grep -r "functionName" --include="*.ts"
+
+# 运行指定测试
+npm test -- --grep "test name"
+```
+
+## 排查检查清单
+
+- [ ] 已捕获错误信息
+- [ ] 已分析堆栈追踪
+- [ ] 已检查最近变更
+- [ ] 已定位根因
+- [ ] 已实现修复
+- [ ] 测试通过
+- [ ] 未引入回归
diff --git a/zh/04-subagents/documentation-writer.md b/zh/04-subagents/documentation-writer.md
new file mode 100644
index 0000000..e3b28ff
--- /dev/null
+++ b/zh/04-subagents/documentation-writer.md
@@ -0,0 +1,98 @@
+---
+name: documentation-writer
+description: 技术文档专家,负责 API 文档、用户指南和架构文档。
+tools: Read, Write, Grep
+model: inherit
+---
+
+# Documentation Writer Agent
+
+你是一名技术写作者,负责创建清晰、完整的文档。
+
+被调用时:
+1. 分析要记录的代码或功能
+2. 确定目标读者
+3. 按项目规范编写文档
+4. 根据实际代码验证准确性
+
+## 文档类型
+
+- 带示例的 API 文档
+- 用户指南和教程
+- 架构文档
+- Changelog 条目
+- 代码注释改进
+
+## 文档标准
+
+1. **清晰** - 使用简单、明确的语言
+2. **示例** - 包含实用的代码示例
+3. **完整** - 覆盖所有参数和返回值
+4. **结构** - 使用一致的格式
+5. **准确** - 根据实际代码验证
+
+## 文档章节
+
+### API 文档
+
+- 描述
+- 参数(含类型)
+- 返回值(含类型)
+- 抛出错误(可能的异常)
+- 示例(curl、JavaScript、Python)
+- 相关端点
+
+### 功能文档
+
+- 概述
+- 前置条件
+- 分步说明
+- 预期结果
+- 故障排查
+- 相关主题
+
+## 输出格式
+
+每份生成的文档都要提供:
+- **Type**: API / Guide / Architecture / Changelog
+- **File**: 文档文件路径
+- **Sections**: 覆盖的章节列表
+- **Examples**: 包含的代码示例数量
+
+## API 文档示例
+
+```markdown
+## GET /api/users/:id
+
+通过唯一标识符检索用户。
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | 用户的唯一标识符 |
+
+### Response
+
+```json
+{
+ "id": "abc123",
+ "name": "John Doe",
+ "email": "[email protected]"
+}
+```
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 404 | User not found |
+| 401 | Unauthorized |
+
+### Example
+
+```bash
+curl -X GET https://api.example.com/api/users/abc123 \
+ -H "Authorization: Bearer <token>"
+```
+```
diff --git a/zh/04-subagents/implementation-agent.md b/zh/04-subagents/implementation-agent.md
new file mode 100644
index 0000000..5b46493
--- /dev/null
+++ b/zh/04-subagents/implementation-agent.md
@@ -0,0 +1,78 @@
+---
+name: implementation-agent
+description: 全栈实现专家,负责根据规范开发功能。拥有完整工具权限,可端到端完成实现。
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+---
+
+# Implementation Agent
+
+你是一名资深开发者,负责根据规格实现功能。
+
+这个 agent 拥有完整能力:
+- 阅读规范和现有代码
+- 创建新的代码文件
+- 编辑已有文件
+- 运行构建命令
+- 搜索代码库
+- 查找匹配模式的文件
+
+## 实现流程
+
+被调用时:
+1. 充分理解需求
+2. 分析现有代码库模式
+3. 制定实现方案
+4. 逐步实现
+5. 边做边测试
+6. 清理和重构
+
+## 实现指南
+
+### 代码质量
+
+- 遵循现有项目规范
+- 编写自解释代码
+- 只有在逻辑复杂时才添加注释
+- 保持函数短小专注
+- 使用有意义的变量名
+
+### 文件组织
+
+- 按项目结构放置文件
+- 相关功能放在一起
+- 遵循命名规范
+- 避免过深的目录嵌套
+
+### 错误处理
+
+- 处理所有错误情况
+- 提供有意义的错误信息
+- 合理记录错误日志
+- 优雅失败
+
+### 测试
+
+- 为新功能编写测试
+- 确保现有测试通过
+- 覆盖边界情况
+- 为 API 添加集成测试
+
+## 输出格式
+
+每个实现任务都要提供:
+- **Files Created**: 新文件列表
+- **Files Modified**: 已修改文件列表
+- **Tests Added**: 测试文件路径
+- **Build Status**: Pass/Fail
+- **Notes**: 重要说明
+
+## 实现检查清单
+
+在标记完成前:
+- [ ] 代码符合项目规范
+- [ ] 所有测试通过
+- [ ] 构建成功
+- [ ] 没有 lint 错误
+- [ ] 已处理边界情况
+- [ ] 已实现错误处理
diff --git a/zh/04-subagents/secure-reviewer.md b/zh/04-subagents/secure-reviewer.md
new file mode 100644
index 0000000..1bfca06
--- /dev/null
+++ b/zh/04-subagents/secure-reviewer.md
@@ -0,0 +1,75 @@
+---
+name: secure-reviewer
+description: 安全审查专家,权限最小化。只读访问确保安全审计过程安全可靠。
+tools: Read, Grep
+model: inherit
+---
+
+# Secure Code Reviewer
+
+你是一名安全专家,专注于识别漏洞。
+
+这个 agent 采用最小权限设计:
+- 可以读取文件进行分析
+- 可以搜索模式
+- 不能执行代码
+- 不能修改文件
+- 不能运行测试
+
+这样可以确保审查过程中不会意外破坏任何东西。
+
+## 安全审查重点
+
+1. **身份验证问题**
+ - 弱密码策略
+ - 缺少多因素认证
+ - 会话管理缺陷
+
+2. **授权问题**
+ - 访问控制失效
+ - 权限提升
+ - 缺少角色检查
+
+3. **数据暴露**
+ - 日志中泄露敏感数据
+ - 未加密存储
+ - API key 泄露
+ - PII 处理问题
+
+4. **注入漏洞**
+ - SQL 注入
+ - 命令注入
+ - XSS(跨站脚本)
+ - LDAP 注入
+
+5. **配置问题**
+ - 生产环境开启调试模式
+ - 默认凭据
+ - 不安全的默认配置
+
+## 搜索模式
+
+```bash
+# 硬编码密钥
+grep -r "password\s*=" --include="*.js" --include="*.ts"
+grep -r "api_key\s*=" --include="*.py"
+grep -r "SECRET" --include="*.env*"
+
+# SQL 注入风险
+grep -r "query.*\$" --include="*.js"
+grep -r "execute.*%" --include="*.py"
+
+# 命令注入风险
+grep -r "exec(" --include="*.js"
+grep -r "os.system" --include="*.py"
+```
+
+## 输出格式
+
+对每个漏洞,提供:
+- **Severity**: Critical / High / Medium / Low
+- **Type**: OWASP 类别
+- **Location**: 文件路径和行号
+- **Description**: 漏洞是什么
+- **Risk**: 如果被利用,可能造成什么影响
+- **Remediation**: 如何修复
diff --git a/zh/04-subagents/test-engineer.md b/zh/04-subagents/test-engineer.md
new file mode 100644
index 0000000..9e2bde8
--- /dev/null
+++ b/zh/04-subagents/test-engineer.md
@@ -0,0 +1,74 @@
+---
+name: test-engineer
+description: 测试自动化专家,负责编写全面测试。新功能上线或代码修改后建议主动使用。
+tools: Read, Write, Bash, Grep
+model: inherit
+---
+
+# Test Engineer Agent
+
+你是一名擅长完整测试覆盖的测试工程师。
+
+被调用时:
+1. 分析需要测试的代码
+2. 识别关键路径和边界情况
+3. 按项目规范编写测试
+4. 运行测试验证通过
+
+## 测试策略
+
+1. **单元测试** - 独立测试单个函数或方法
+2. **集成测试** - 测试组件交互
+3. **端到端测试** - 测试完整工作流
+4. **边界情况** - 边界条件、空值、空集合
+5. **错误场景** - 失败处理、非法输入
+
+## 测试要求
+
+- 使用项目现有测试框架(Jest、pytest 等)
+- 每个测试都要包含 setup/teardown
+- Mock 外部依赖
+- 用清晰描述说明测试目的
+- 在相关场景下加入性能断言
+
+## 覆盖率要求
+
+- 最低 80% 代码覆盖率
+- 关键路径(认证、支付、数据处理)要求 100%
+- 报告缺失的覆盖区域
+
+## 测试输出格式
+
+每个测试文件都要提供:
+- **File**: 测试文件路径
+- **Tests**: 测试用例数量
+- **Coverage**: 预计覆盖率提升
+- **Critical Paths**: 覆盖了哪些关键路径
+
+## 测试结构示例
+
+```javascript
+describe('Feature: User Authentication', () => {
+ beforeEach(() => {
+ // Setup
+ });
+
+ afterEach(() => {
+ // Cleanup
+ });
+
+ it('should authenticate valid credentials', async () => {
+ // Arrange
+ // Act
+ // Assert
+ });
+
+ it('should reject invalid credentials', async () => {
+ // Test error case
+ });
+
+ it('should handle edge case: empty password', async () => {
+ // Test edge case
+ });
+});
+```
diff --git a/zh/05-mcp/README.md b/zh/05-mcp/README.md
new file mode 100644
index 0000000..6c9945e
--- /dev/null
+++ b/zh/05-mcp/README.md
@@ -0,0 +1,342 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# MCP(Model Context Protocol)
+
+## 概览
+
+MCP 是 Claude Code 访问外部工具、服务和 API 的标准协议。你可以把 GitHub、数据库、文件系统、聊天系统等都接到 Claude 里。
+
+## MCP 架构
+
+MCP 通常由三部分构成:
+
+1. Claude Code
+2. MCP server
+3. 外部工具或数据源
+
+Claude 会通过 MCP 协议向 server 发起工具调用,并把结果带回当前会话。
+
+## MCP 生态
+
+- GitHub 集成
+- 数据库集成
+- 文件系统集成
+- 组织内部工具
+- 第三方服务
+
+## 安装方式
+
+### HTTP 传输(推荐)
+
+```bash
+# Basic HTTP connection
+
+# HTTP with authentication header
+```
+
+### Stdio 传输(本地)
+
+```bash
+# Local Node.js server
+
+# With environment variables
+```
+
+### SSE 传输(已弃用)
+
+旧版本中可能仍能见到 SSE 方式,但新配置一般优先考虑 HTTP 或 stdio。
+
+### WebSocket 传输
+
+适用于需要实时双向通信的场景。
+
+### Windows 说明
+
+在 Windows 上配置本地 server 时,要注意 shell、环境变量和路径写法。
+
+### OAuth 2.0 认证
+
+对于支持 OAuth 的 MCP server,Claude 可以通过交互式流程或预配置凭据完成认证。
+
+## MCP 设置流程
+
+1. 确认你要接入的服务
+2. 选择 transport
+3. 配置环境变量或认证
+4. 在 Claude Code 中添加 server
+5. 验证工具是否可用
+
+## MCP 工具搜索
+
+Claude 会根据当前上下文自动查找可用工具。
+
+## 动态工具更新
+
+当 MCP server 增加或移除工具时,Claude 可以在运行时感知变化。
+
+## MCP 提示补充(Elicitation)
+
+有些 MCP server 会在需要用户补充信息时触发 elicitation,Claude 再把问题转给用户。
+
+## 工具描述与指令上限
+
+每个 MCP 工具都应该有清晰的描述,帮助 Claude 选择正确的工具。
+
+## 把 MCP Prompts 暴露成 Slash Commands
+
+```text
+/mcp__<server-name>__<prompt-name> [arguments]
+```
+
+例如:
+
+```bash
+/mcp__github__list_prs
+/mcp__github__pr_review 456
+/mcp__jira__create_issue "Bug title" high
+```
+
+## Server 去重
+
+如果多个配置都指向同一个 server,Claude 会尽量避免重复加载。
+
+## 通过 `@` 提及使用 MCP 资源
+
+你可以把某些资源当作引用对象,在 prompt 中直接提及。
+
+## MCP 作用域
+
+MCP 配置通常有不同作用域,例如项目级和用户级。
+
+### 使用项目作用域
+
+适合把团队共享的 server 配置写进项目内。
+
+## MCP 配置管理
+
+### 添加 MCP server
+
+```bash
+# Add HTTP-based server
+
+# Add local stdio server
+
+# List all MCP servers
+
+# Get details on specific server
+
+# Remove an MCP server
+
+# Reset project-specific approval choices
+
+# Import from Claude Desktop
+```
+
+## 可用 MCP Server 表
+
+你可以在配置中维护一张 server 清单,记录用途、认证方式和安装命令。
+
+## 实战示例
+
+### 示例 1:GitHub MCP 配置
+
+你可以用 GitHub MCP 做这些事:
+
+- PR 管理
+- Issue 管理
+- 仓库信息查询
+- commit 操作
+
+### 环境变量展开
+
+在配置中可以使用环境变量,让同一份配置适配不同环境。
+
+### 示例 2:数据库 MCP
+
+```bash
+# Using MCP database tool:
+
+# Results:
+```
+
+### 示例 3:多 MCP 工作流
+
+适合日常报告、跨系统同步和自动化文档生成。
+
+### 示例 4:文件系统 MCP 操作
+
+可用于读写文件、批量整理、生成报告或导出结果。
+
+## MCP vs Memory:决策矩阵
+
+- **Memory**:适合长期规则、偏好和上下文
+- **MCP**:适合实时工具访问和外部数据
+
+## 请求 / 响应模式
+
+MCP 一般遵循:
+
+1. Claude 发起请求
+2. Server 处理
+3. 返回结构化结果
+
+## 环境变量
+
+常见环境变量包括:
+
+- API token
+- 数据库地址
+- 服务端口
+- 认证信息
+
+## Claude 作为 MCP Server(`claude mcp serve`)
+
+```bash
+# Start Claude Code as an MCP server on stdio
+```
+
+## 受管 MCP 配置(企业)
+
+企业可通过受管设置统一分发 MCP 配置。
+
+## 插件提供的 MCP Servers
+
+插件可以把自己的 MCP server 一起打包分发。
+
+## Subagent 作用域 MCP
+
+某些 MCP 只允许特定 subagent 使用。
+
+## MCP 输出限制
+
+如果输出过大,可以限制 token 数或分页获取。
+
+### 增大最大输出
+
+```bash
+# Increase the max output to 50,000 tokens
+```
+
+## 用代码执行解决上下文膨胀
+
+当重复把大量数据回传给 Claude 会浪费 token 时,可以把 MCP 当作代码 API 来用,减少来回传输。
+
+### 问题
+
+- 两个信息源都在耗 token
+- 大数据集不适合全量塞进上下文
+
+### 方案
+
+- 用 MCP 工具做实时查询
+- 只把必要结果传给 Claude
+
+#### 工作方式
+
+Claude 通过工具调用从外部系统取回需要的数据,而不是把所有数据先写进上下文。
+
+### 好处
+
+- 更少 token 浪费
+- 更清晰的数据边界
+- 更适合大规模查询
+
+#### 示例:过滤大数据集
+
+#### 示例:循环而不做 round-trip
+
+### 取舍
+
+- 实现复杂度更高
+- 需要维护 server
+- 但扩展性更好
+
+### MCPorter:MCP 工具组合运行时
+
+这是更高级的工具编排思路,可以把多个 MCP 工具串成一个流程。
+
+## 最佳实践
+
+### 安全注意事项
+
+#### 应该做的
+
+- 只授权必要的工具
+- 优先使用最小权限
+- 检查输出是否可信
+
+#### 不要做的
+
+- 不要把高风险 token 写死在仓库里
+- 不要默认开放所有工具
+- 不要忽视网络和认证风险
+
+### 配置建议
+
+- 给每个 server 写清楚用途
+- 用环境变量存认证信息
+- 把项目级配置版本化
+
+### 性能建议
+
+- 避免一次性拉回过多数据
+- 优先做过滤和分页
+- 只返回 Claude 真正需要的结果
+
+## 安装说明
+
+### 前置条件
+
+- Claude Code
+- 对应的 MCP server
+- 必要的认证信息
+
+### 分步设置
+
+1. 安装 server
+2. 设置环境变量
+3. 添加到 Claude
+4. 测试工具
+
+### 特定服务的安装
+
+不同服务会有不同的安装命令和认证方式。
+
+## 故障排查
+
+### 找不到 MCP Server
+
+- 检查是否安装
+- 检查路径
+- 检查配置是否正确
+
+### 认证失败
+
+- 检查环境变量是否设置
+- 确认 token 权限正确
+- 重新导出变量后再试
+
+### 连接超时
+
+- 检查网络
+- 检查 server 是否可用
+
+### MCP Server 崩溃
+
+- 查看 server 日志
+- 降低并发
+- 简化请求
+
+## 相关概念
+
+- [Memory 中文指南](../02-memory/README.md)
+- [Subagents 中文参考](../04-subagents/README.md)
+- [Plugins 中文指南](../07-plugins/README.md)
+
+## 更多资源
+
+- [根目录中文指南](../README.md)
+- [MCP 规范](https://modelcontextprotocol.io)
diff --git a/zh/06-hooks/README.md b/zh/06-hooks/README.md
new file mode 100644
index 0000000..3a84f8a
--- /dev/null
+++ b/zh/06-hooks/README.md
@@ -0,0 +1,98 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Hooks 参考
+
+Hooks 是在 Claude Code 事件发生时自动执行的 shell 命令,用来做格式化、校验、通知、审计等自动化工作。
+
+## 概览
+
+Hooks 是事件驱动的自动化机制。它们会在 Claude Code 发生某些动作时自动运行,不需要你手动触发。
+
+常见用途:
+
+- 写文件前自动格式化
+- 提交前运行测试
+- 扫描安全问题
+- 记录 bash 命令
+- 校验用户提示词
+- 发送团队通知
+
+## Hook 类型
+
+Claude Code 提供 4 类、25 个事件:
+
+- **Tool Hooks**:`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`
+- **Session Hooks**:`SessionStart`、`SessionEnd`、`Stop`、`StopFailure`、`SubagentStart`、`SubagentStop`
+- **Task Hooks**:`UserPromptSubmit`、`TaskCompleted`、`TaskCreated`、`TeammateIdle`
+- **Lifecycle Hooks**:`ConfigChange`、`CwdChanged`、`FileChanged`、`PreCompact`、`PostCompact`、`WorktreeCreate`、`WorktreeRemove`、`Notification`、`InstructionsLoaded`、`Elicitation`、`ElicitationResult`
+
+## 安装
+
+```bash
+mkdir -p ~/.claude/hooks
+cp 06-hooks/*.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/*.sh
+```
+
+然后在 `~/.claude/settings.json` 里配置:
+
+```json
+{
+ "hooks": {
+ "PreToolUse": [{
+ "matcher": "Write",
+ "hooks": ["~/.claude/hooks/format-code.sh"]
+ }],
+ "PostToolUse": [{
+ "matcher": "Write",
+ "hooks": ["~/.claude/hooks/security-scan.sh"]
+ }]
+ }
+}
+```
+
+## 使用方法
+
+Hooks 会在匹配到事件时自动执行。你可以把它理解成 Claude Code 的事件回调。
+
+## 常见示例
+
+- `format-code.sh` - 写入前自动格式化
+- `pre-commit.sh` - 提交前跑测试
+- `security-scan.sh` - 做安全扫描
+- `log-bash.sh` - 记录 bash 命令
+- `validate-prompt.sh` - 校验输入
+- `notify-team.sh` - 发通知
+
+## 最佳实践
+
+- 把 hooks 保持短小明确
+- 只做单一职责
+- 先在本地测试
+- 不要在 hook 里放复杂业务逻辑
+- 对副作用保持谨慎
+
+## 故障排查
+
+- 检查文件路径和权限
+- 确认脚本可执行
+- 检查 settings.json 语法
+- 查看 Claude Code 版本兼容性
+
+## 相关概念
+
+- [Checkpoints and Rewind](../08-checkpoints/README.md)
+- [Slash Commands](../01-slash-commands/README.md)
+- [Skills](../03-skills/README.md)
+- [Subagents](../04-subagents/README.md)
+- [Plugins](../07-plugins/README.md)
+- [Advanced Features](../09-advanced-features/README.md)
+
+## 更多资源
+
+- [Memory Guide](../02-memory/README.md)
+- [Official Hooks Documentation](https://code.claude.com/docs/en/hooks)
+- [CLI Reference](https://code.claude.com/docs/en/cli-reference)
diff --git a/zh/07-plugins/README.md b/zh/07-plugins/README.md
new file mode 100644
index 0000000..7390745
--- /dev/null
+++ b/zh/07-plugins/README.md
@@ -0,0 +1,930 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Claude Code 插件
+
+这个目录包含一组完整的插件示例,它们把多个 Claude Code 功能打包成可安装的一体化方案。
+
+## 介绍
+
+Claude Code 插件是把 slash commands、subagents、MCP servers 和 hooks 组合在一起的功能集合,可以通过一条命令安装。它们代表了 Claude Code 最高级别的扩展方式,把多个功能整合成可共享、可复用的完整方案。
+
+## 概览
+
+一个插件通常会把以下能力打包在一起:
+
+- slash commands
+- subagents
+- MCP servers
+- hooks
+
+这样做的好处是:
+
+- 一次安装即可使用完整工作流
+- 团队共享更容易
+- 配置更统一
+- 便于版本控制和分发
+
+## 插件架构
+
+```mermaid
+graph TB
+ A["插件"]
+ B["Slash Commands"]
+ C["Subagents"]
+ D["MCP Servers"]
+ E["Hooks"]
+ F["Configuration"]
+
+ A -->|打包| B
+ A -->|打包| C
+ A -->|打包| D
+ A -->|打包| E
+ A -->|打包| F
+```
+
+## 插件类型与分发
+
+| 类型 | 范围 | 共享对象 | 维护者 | 示例 |
+|------|------|----------|--------|------|
+| 官方 | 全局 | 所有用户 | Anthropic | PR 审查、安全指导 |
+| 社区 | 公开 | 所有用户 | 社区 | DevOps、数据科学 |
+| 组织 | 内部 | 团队成员 | 公司 | 内部规范、工具 |
+| 个人 | 个人 | 单个用户 | 开发者 | 自定义工作流 |
+
+## 插件定义结构
+
+插件清单使用 `.claude-plugin/plugin.json` 中的 JSON 格式:
+
+```json
+{
+ "name": "my-first-plugin",
+ "description": "一个问候插件",
+ "version": "1.0.0",
+ "author": {
+ "name": "Your Name"
+ },
+ "homepage": "https://example.com",
+ "repository": "https://github.com/user/repo",
+ "license": "MIT"
+}
+```
+
+## 插件结构示例
+
+```
+my-plugin/
+├── .claude-plugin/
+│ └── plugin.json # 清单(名称、描述、版本、作者)
+├── commands/ # 以 Markdown 文件形式存放的命令
+│ ├── task-1.md
+│ ├── task-2.md
+│ └── workflows/
+├── agents/ # 自定义 agent 定义
+│ ├── specialist-1.md
+│ ├── specialist-2.md
+│ └── configs/
+├── skills/ # 带有 SKILL.md 文件的技能
+│ ├── skill-1.md
+│ └── skill-2.md
+├── hooks/ # hooks.json 中的事件处理器
+│ └── hooks.json
+├── .mcp.json # MCP server 配置
+├── .lsp.json # LSP server 配置
+├── settings.json # 默认设置
+├── templates/
+│ └── issue-template.md
+├── scripts/
+│ ├── helper-1.sh
+│ └── helper-2.py
+├── docs/
+│ ├── README.md
+│ └── USAGE.md
+└── tests/
+ └── plugin.test.js
+```
+
+### LSP server 配置
+
+插件可以包含 Language Server Protocol(LSP)支持,以获得实时代码智能。LSP server 会在你编写代码时提供诊断、代码导航和符号信息。
+
+**配置位置**:
+- 插件根目录中的 `.lsp.json` 文件
+- `plugin.json` 中的内联 `lsp` 键
+
+#### 字段参考
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `command` | 是 | LSP server 可执行文件(必须在 PATH 中) |
+| `extensionToLanguage` | 是 | 将文件扩展名映射到语言 ID |
+| `args` | 否 | server 的命令行参数 |
+| `transport` | 否 | 通信方式:`stdio`(默认)或 `socket` |
+| `env` | 否 | server 进程的环境变量 |
+| `initializationOptions` | 否 | LSP 初始化期间发送的选项 |
+| `settings` | 否 | 传递给 server 的工作区配置 |
+| `workspaceFolder` | 否 | 覆盖工作区文件夹路径 |
+| `startupTimeout` | 否 | 等待 server 启动的最长时间(毫秒) |
+| `shutdownTimeout` | 否 | 优雅关闭的最长时间(毫秒) |
+| `restartOnCrash` | 否 | server 崩溃时自动重启 |
+| `maxRestarts` | 否 | 放弃前的最大重启次数 |
+
+#### 示例配置
+
+**Go(gopls)**:
+
+```json
+{
+ "go": {
+ "command": "gopls",
+ "args": ["serve"],
+ "extensionToLanguage": {
+ ".go": "go"
+ }
+ }
+}
+```
+
+**Python(pyright)**:
+
+```json
+{
+ "python": {
+ "command": "pyright-langserver",
+ "args": ["--stdio"],
+ "extensionToLanguage": {
+ ".py": "python",
+ ".pyi": "python"
+ }
+ }
+}
+```
+
+**TypeScript**:
+
+```json
+{
+ "typescript": {
+ "command": "typescript-language-server",
+ "args": ["--stdio"],
+ "extensionToLanguage": {
+ ".ts": "typescript",
+ ".tsx": "typescriptreact",
+ ".js": "javascript",
+ ".jsx": "javascriptreact"
+ }
+ }
+}
+```
+
+#### 可用的 LSP 插件
+
+官方市场包含了预配置好的 LSP 插件:
+
+| 插件 | 语言 | Server Binary | 安装命令 |
+|------|------|---------------|----------|
+| `pyright-lsp` | Python | `pyright-langserver` | `pip install pyright` |
+| `typescript-lsp` | TypeScript/JavaScript | `typescript-language-server` | `npm install -g typescript-language-server typescript` |
+| `rust-lsp` | Rust | `rust-analyzer` | 使用 `rustup component add rust-analyzer` 安装 |
+
+#### LSP 能力
+
+配置完成后,LSP server 会提供:
+
+- **即时诊断** - 编辑后立即显示错误和警告
+- **代码导航** - 跳转到定义、查找引用和实现
+- **悬浮信息** - 在悬停时查看类型签名和文档
+- **符号列表** - 浏览当前文件或工作区中的符号
+
+## 插件选项(v2.1.83+)
+
+插件可以在清单中通过 `userConfig` 声明用户可配置选项。标记为 `sensitive: true` 的值会存储在系统钥匙串中,而不是明文设置文件里:
+
+```json
+{
+ "name": "my-plugin",
+ "version": "1.0.0",
+ "userConfig": {
+ "apiKey": {
+ "description": "服务的 API key",
+ "sensitive": true
+ },
+ "region": {
+ "description": "部署区域",
+ "default": "us-east-1"
+ }
+ }
+}
+```
+
+## 持久化插件数据(`${CLAUDE_PLUGIN_DATA}`)(v2.1.78+)
+
+插件可以通过 `${CLAUDE_PLUGIN_DATA}` 环境变量访问一个持久化状态目录。这个目录对每个插件都是唯一的,并且会跨会话保留,适合缓存、数据库和其他持久化状态:
+
+```json
+{
+ "hooks": {
+ "PostToolUse": [
+ {
+ "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js"
+ }
+ ]
+ }
+}
+```
+
+插件安装时会自动创建该目录。存放在这里的文件会一直保留,直到插件被卸载。
+
+## 通过设置文件内联定义插件(`source: 'settings'`)(v2.1.80+)
+
+插件可以在设置文件中以内联市场条目的方式定义,使用 `source: 'settings'` 字段即可。这允许你直接嵌入插件定义,而不必单独准备仓库或市场:
+
+```json
+{
+ "pluginMarketplaces": [
+ {
+ "name": "inline-tools",
+ "source": "settings",
+ "plugins": [
+ {
+ "name": "quick-lint",
+ "source": "./local-plugins/quick-lint"
+ }
+ ]
+ }
+ ]
+}
+```
+
+## 插件设置
+
+插件可以提供一个 `settings.json` 文件来定义默认配置。目前支持 `agent` 键,用来指定插件的主线程 agent:
+
+```json
+{
+ "agent": "agents/specialist-1.md"
+}
+```
+
+当插件包含 `settings.json` 时,这些默认值会在安装时自动应用。用户也可以在自己的项目或用户级配置中覆盖它们。
+
+## 独立命令 vs 插件方式
+
+| 方式 | 命令名称 | 配置方式 | 最适合 |
+|------|----------|----------|--------|
+| **独立命令** | `/hello` | 在 `CLAUDE.md` 中手动设置 | 个人、项目专用 |
+| **插件** | `/plugin-name:hello` | 通过 `plugin.json` 自动配置 | 共享、分发、团队使用 |
+
+对于快速的个人工作流,使用 **独立 slash commands**。当你想打包多个功能、与团队共享或者发布分发时,使用 **插件**。
+
+## 实际示例
+
+### 示例 1:PR 审查插件
+
+**文件:** `.claude-plugin/plugin.json`
+
+```json
+{
+ "name": "pr-review",
+ "version": "1.0.0",
+ "description": "包含安全、测试和文档检查的完整 PR 审查工作流",
+ "author": {
+ "name": "Anthropic"
+ },
+ "repository": "https://github.com/your-org/pr-review",
+ "license": "MIT"
+}
+```
+
+**文件:** `commands/review-pr.md`
+
+```markdown
+---
+name: Review PR
+description: 启动包含安全和测试检查的完整 PR 审查
+---
+
+# PR Review
+
+这个命令会启动一次完整的 Pull Request 审查,包括:
+
+1. 安全分析
+2. 测试覆盖率验证
+3. 文档更新
+4. 代码质量检查
+5. 性能影响评估
+```
+
+**文件:** `agents/security-reviewer.md`
+
+```yaml
+---
+name: security-reviewer
+description: 面向安全的代码审查
+tools: read, grep, diff
+---
+
+# Security Reviewer
+
+专注于发现安全漏洞:
+- 身份验证/授权问题
+- 数据暴露
+- 注入攻击
+- 安全配置
+```
+
+**安装:**
+
+```bash
+/plugin install pr-review
+
+# 结果:
+# ✅ 已安装 3 个 slash commands
+# ✅ 已配置 3 个 subagents
+# ✅ 已连接 2 个 MCP servers
+# ✅ 已注册 4 个 hooks
+# ✅ 可以直接使用!
+```
+
+### 示例 2:DevOps 插件
+
+**组件:**
+
+```
+devops-automation/
+├── commands/
+│ ├── deploy.md
+│ ├── rollback.md
+│ ├── status.md
+│ └── incident.md
+├── agents/
+│ ├── deployment-specialist.md
+│ ├── incident-commander.md
+│ └── alert-analyzer.md
+├── mcp/
+│ ├── github-config.json
+│ ├── kubernetes-config.json
+│ └── prometheus-config.json
+├── hooks/
+│ ├── pre-deploy.js
+│ ├── post-deploy.js
+│ └── on-error.js
+└── scripts/
+ ├── deploy.sh
+ ├── rollback.sh
+ └── health-check.sh
+```
+
+### 示例 3:文档插件
+
+**打包组件:**
+
+```
+documentation/
+├── commands/
+│ ├── generate-api-docs.md
+│ ├── generate-readme.md
+│ ├── sync-docs.md
+│ └── validate-docs.md
+├── agents/
+│ ├── api-documenter.md
+│ ├── code-commentator.md
+│ └── example-generator.md
+├── mcp/
+│ ├── github-docs-config.json
+│ └── slack-announce-config.json
+└── templates/
+ ├── api-endpoint.md
+ ├── function-docs.md
+ └── adr-template.md
+```
+
+## 插件市场
+
+Anthropic 官方维护的插件目录是 `anthropics/claude-plugins-official`。企业管理员也可以创建私有插件市场用于内部分发。
+
+```mermaid
+graph TB
+ A["插件市场"]
+ B["官方<br/>anthropics/claude-plugins-official"]
+ C["社区<br/>市场"]
+ D["企业<br/>私有仓库"]
+
+ A --> B
+ A --> C
+ A --> D
+
+ B -->|分类| B1["开发"]
+ B -->|分类| B2["DevOps"]
+ B -->|分类| B3["文档"]
+
+ C -->|搜索| C1["DevOps 自动化"]
+ C -->|搜索| C2["移动开发"]
+ C -->|搜索| C3["数据科学"]
+
+ D -->|内部| D1["公司规范"]
+ D -->|内部| D2["遗留系统"]
+ D -->|内部| D3["合规"]
+
+ style A fill:#e1f5fe,stroke:#333,color:#333
+ style B fill:#e8f5e9,stroke:#333,color:#333
+ style C fill:#f3e5f5,stroke:#333,color:#333
+ style D fill:#fff3e0,stroke:#333,color:#333
+```
+
+### 市场配置
+
+企业和高级用户可以通过设置来控制市场行为:
+
+| 设置 | 说明 |
+|------|------|
+| `extraKnownMarketplaces` | 在默认列表之外添加额外的市场源 |
+| `strictKnownMarketplaces` | 控制允许用户添加哪些市场 |
+| `deniedPlugins` | 管理员维护的黑名单,阻止特定插件被安装 |
+
+### 额外的市场特性
+
+- **默认 git 超时**:对大型插件仓库从 30 秒增加到 120 秒
+- **自定义 npm registry**:插件可以指定自定义 npm registry URL 用于依赖解析
+- **版本锁定**:将插件锁定到特定版本,以获得可复现的环境
+
+### 市场定义 schema
+
+插件市场定义在 `.claude-plugin/marketplace.json` 中:
+
+```json
+{
+ "name": "my-team-plugins",
+ "owner": "my-org",
+ "plugins": [
+ {
+ "name": "code-standards",
+ "source": "./plugins/code-standards",
+ "description": "强制执行团队编码规范",
+ "version": "1.2.0",
+ "author": "platform-team"
+ },
+ {
+ "name": "deploy-helper",
+ "source": {
+ "source": "github",
+ "repo": "my-org/deploy-helper",
+ "ref": "v2.0.0"
+ },
+ "description": "部署自动化工作流"
+ }
+ ]
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `name` | 是 | 使用 kebab-case 的市场名称 |
+| `owner` | 是 | 维护该市场的组织或用户 |
+| `plugins` | 是 | 插件条目数组 |
+| `plugins[].name` | 是 | 插件名称(kebab-case) |
+| `plugins[].source` | 是 | 插件来源(路径字符串或来源对象) |
+| `plugins[].description` | 否 | 插件的简要描述 |
+| `plugins[].version` | 否 | 语义化版本字符串 |
+| `plugins[].author` | 否 | 插件作者名称 |
+
+### 插件来源类型
+
+插件可以来自多个位置:
+
+| 来源 | 语法 | 示例 |
+|------|------|------|
+| **相对路径** | 字符串路径 | `"./plugins/my-plugin"` |
+| **GitHub** | `{ "source": "github", "repo": "owner/repo" }` | `{ "source": "github", "repo": "acme/lint-plugin", "ref": "v1.0" }` |
+| **Git URL** | `{ "source": "url", "url": "..." }` | `{ "source": "url", "url": "https://git.internal/plugin.git" }` |
+| **Git 子目录** | `{ "source": "git-subdir", "url": "...", "path": "..." }` | `{ "source": "git-subdir", "url": "https://github.com/org/monorepo.git", "path": "packages/plugin" }` |
+| **npm** | `{ "source": "npm", "package": "..." }` | `{ "source": "npm", "package": "@acme/claude-plugin", "version": "^2.0" }` |
+| **pip** | `{ "source": "pip", "package": "..." }` | `{ "source": "pip", "package": "claude-data-plugin", "version": ">=1.0" }` |
+
+GitHub 和 git 来源支持可选的 `ref`(分支/标签)和 `sha`(提交哈希)字段用于版本锁定。
+
+### 分发方式
+
+**GitHub(推荐)**:
+```bash
+# 用户添加你的市场
+/plugin marketplace add owner/repo-name
+```
+
+**其他 git 服务**(需要完整 URL):
+```bash
+/plugin marketplace add https://gitlab.com/org/marketplace-repo.git
+```
+
+**私有仓库**:可以通过 git credential helper 或环境令牌支持。用户必须有该仓库的读取权限。
+
+**官方市场提交**:可以将插件提交到 Anthropic 审核维护的市场,以便更广泛分发。
+
+### 严格模式
+
+控制市场定义与本地 `plugin.json` 文件的交互方式:
+
+| 设置 | 行为 |
+|------|------|
+| `strict: true`(默认) | 本地 `plugin.json` 为权威来源;市场条目会对其进行补充 |
+| `strict: false` | 市场条目就是完整的插件定义 |
+
+**配合 `strictKnownMarketplaces` 的组织限制**:
+
+| 值 | 效果 |
+|----|------|
+| 未设置 | 无限制,用户可以添加任意市场 |
+| 空数组 `[]` | 锁定模式,不允许任何市场 |
+| 模式数组 | 白名单模式,只允许匹配的市场被添加 |
+
+```json
+{
+ "strictKnownMarketplaces": [
+ "my-org/*",
+ "github.com/trusted-vendor/*"
+ ]
+}
+```
+
+> **警告**:在带有 `strictKnownMarketplaces` 的严格模式下,用户只能从白名单市场安装插件。这适用于需要受控插件分发的企业环境。
+
+## 插件安装与生命周期
+
+```mermaid
+graph LR
+ A["发现"] -->|浏览| B["市场"]
+ B -->|选择| C["插件页"]
+ C -->|查看| D["组件"]
+ D -->|安装| E["/plugin install"]
+ E -->|解包| F["配置"]
+ F -->|激活| G["使用"]
+ G -->|检查| H["更新"]
+ H -->|可用| G
+ G -->|完成| I["禁用"]
+ I -->|稍后| J["启用"]
+ J -->|返回| G
+```
+
+## 插件能力对比
+
+| 功能 | Slash Command | Skill | Subagent | Plugin |
+|------|---------------|-------|----------|--------|
+| **安装** | 手动复制 | 手动复制 | 手动配置 | 一条命令 |
+| **设置时间** | 5 分钟 | 10 分钟 | 15 分钟 | 2 分钟 |
+| **打包** | 单文件 | 单文件 | 单文件 | 多文件 |
+| **版本管理** | 手动 | 手动 | 手动 | 自动 |
+| **团队共享** | 复制文件 | 复制文件 | 复制文件 | 安装 ID |
+| **更新** | 手动 | 手动 | 手动 | 自动可用 |
+| **依赖** | 无 | 无 | 无 | 可能包含 |
+| **市场** | 否 | 否 | 否 | 是 |
+| **分发** | 仓库 | 仓库 | 仓库 | 市场 |
+
+## 插件 CLI 命令
+
+所有插件操作都可以通过 CLI 命令完成:
+
+```bash
+claude plugin install <name>@<marketplace> # 从市场安装
+claude plugin uninstall <name> # 删除插件
+claude plugin list # 列出已安装插件
+claude plugin enable <name> # 启用已禁用的插件
+claude plugin disable <name> # 禁用插件
+claude plugin validate # 验证插件结构
+```
+
+## 安装方式
+
+### 从市场安装
+```bash
+/plugin install plugin-name
+# 或通过 CLI:
+claude plugin install plugin-name@marketplace-name
+```
+
+### 启用 / 禁用(自动检测作用域)
+```bash
+/plugin enable plugin-name
+/plugin disable plugin-name
+```
+
+### 本地插件(用于开发)
+```bash
+# 本地测试的 CLI 参数(可重复指定多个插件)
+claude --plugin-dir ./path/to/plugin
+claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b
+```
+
+### 从 Git 仓库安装
+```bash
+/plugin install github:username/repo
+```
+
+## 何时创建插件
+
+```mermaid
+graph TD
+ A["我该创建插件吗?"]
+ A -->|需要多个组件| B{"多个命令<br/>或 subagents<br/>或 MCPs?"}
+ B -->|是| C["✅ 创建插件"]
+ B -->|否| D["使用单独功能"]
+ A -->|团队工作流| E{"要和<br/>团队共享吗?"}
+ E -->|是| C
+ E -->|否| F["保持本地配置"]
+ A -->|复杂设置| G{"需要自动<br/>配置吗?"}
+ G -->|是| C
+ G -->|否| D
+```
+
+### 插件适用场景
+
+| 场景 | 建议 | 原因 |
+|------|------|------|
+| **团队入职** | ✅ 使用插件 | 即时安装,包含所有配置 |
+| **框架初始化** | ✅ 使用插件 | 打包框架专属命令 |
+| **企业规范** | ✅ 使用插件 | 集中分发,版本控制 |
+| **快速任务自动化** | ❌ 使用命令 | 太重 |
+| **单一领域能力** | ❌ 使用 Skill | 太重,直接用 skill 更合适 |
+| **专门化分析** | ❌ 使用 Subagent | 可手动创建,或用 skill |
+| **实时数据访问** | ❌ 使用 MCP | 独立使用,不要打包 |
+
+## 测试插件
+
+在发布前,使用 `--plugin-dir` CLI 参数在本地测试插件(可以重复指定多个插件):
+
+```bash
+claude --plugin-dir ./my-plugin
+claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin
+```
+
+这会用已加载插件启动 Claude Code,让你可以:
+- 验证所有 slash commands 是否可用
+- 测试 subagents 和 agents 是否正常工作
+- 确认 MCP servers 能正确连接
+- 验证 hooks 的执行
+- 检查 LSP server 配置
+- 检查是否有配置错误
+
+## 热重载
+
+插件支持开发期间的热重载。当你修改插件文件时,Claude Code 可以自动检测变化。你也可以手动触发重载:
+
+```bash
+/reload-plugins
+```
+
+这会重新读取所有插件清单、commands、agents、skills、hooks 以及 MCP/LSP 配置,而无需重启会话。
+
+## 插件托管设置
+
+管理员可以使用托管设置在组织范围内控制插件行为:
+
+| 设置 | 说明 |
+|------|------|
+| `enabledPlugins` | 默认启用的插件白名单 |
+| `deniedPlugins` | 不允许安装的插件黑名单 |
+| `extraKnownMarketplaces` | 在默认列表之外添加额外市场源 |
+| `strictKnownMarketplaces` | 限制用户允许添加的市场 |
+| `allowedChannelPlugins` | 控制每个发布渠道允许使用哪些插件 |
+
+这些设置可以通过托管配置文件应用到组织级别,并且优先于用户级设置。
+
+## 插件安全
+
+插件 subagents 运行在受限沙箱中。以下 frontmatter 键在插件 subagent 定义中**不允许**使用:
+
+- `hooks` - subagents 不能注册事件处理器
+- `mcpServers` - subagents 不能配置 MCP servers
+- `permissionMode` - subagents 不能覆盖权限模型
+
+这可以确保插件不会越权,也不会修改主机环境的作用范围。
+
+## 发布插件
+
+**发布步骤:**
+
+1. 使用所有组件创建插件结构
+2. 编写 `.claude-plugin/plugin.json` 清单
+3. 创建带文档的 `README.md`
+4. 使用 `claude --plugin-dir ./my-plugin` 在本地测试
+5. 提交到插件市场
+6. 经过审查和批准
+7. 发布到市场
+8. 用户即可一条命令安装
+
+**示例提交:**
+
+```markdown
+# PR 审查插件
+
+## 描述
+包含安全、测试和文档检查的完整 PR 审查工作流。
+
+## 包含内容
+- 3 个用于不同审查类型的 slash commands
+- 3 个专门化 subagents
+- GitHub 和 CodeQL MCP 集成
+- 自动安全扫描 hooks
+
+## 安装
+```bash
+/plugin install pr-review
+```
+
+## 功能
+✅ 安全分析
+✅ 测试覆盖率检查
+✅ 文档校验
+✅ 代码质量评估
+✅ 性能影响分析
+
+## 使用
+```bash
+/review-pr
+/check-security
+/check-tests
+```
+
+## 要求
+- Claude Code 1.0+
+- GitHub 访问权限
+- CodeQL(可选)
+```
+
+## 插件 vs 手动配置
+
+**手动设置(2+ 小时):**
+- 逐个安装 slash commands
+- 单独创建 subagents
+- 分别配置 MCP
+- 手动设置 hooks
+- 记录所有内容
+- 和团队共享(希望他们能配对)
+
+**使用插件(2 分钟):**
+```bash
+/plugin install pr-review
+# ✅ 一切都已安装并配置
+# ✅ 可以立即使用
+# ✅ 团队可以复现完全相同的设置
+```
+
+## 最佳实践
+
+### 应该做的 ✅
+- 使用清晰、描述性的插件名
+- 提供完整 README
+- 正确使用语义化版本(semver)
+- 一起测试所有组件
+- 清楚记录依赖和要求
+- 提供使用示例
+- 包含错误处理
+- 为发现性添加合适标签
+- 保持向后兼容
+- 保持插件聚焦且一致
+- 包含完整测试
+- 记录所有依赖
+
+### 不要做的 ❌
+- 不要打包无关功能
+- 不要硬编码凭据
+- 不要跳过测试
+- 不要忘记文档
+- 不要创建冗余插件
+- 不要忽略版本管理
+- 不要把组件依赖搞得过于复杂
+- 不要忘记优雅处理错误
+
+## 安装说明
+
+### 从市场安装
+
+1. **浏览可用插件:**
+ ```bash
+ /plugin list
+ ```
+
+2. **查看插件详情:**
+ ```bash
+ /plugin info plugin-name
+ ```
+
+3. **安装插件:**
+ ```bash
+ /plugin install plugin-name
+ ```
+
+### 从本地路径安装
+
+```bash
+/plugin install ./path/to/plugin-directory
+```
+
+### 从 GitHub 安装
+
+```bash
+/plugin install github:username/repo
+```
+
+### 列出已安装插件
+
+```bash
+/plugin list --installed
+```
+
+### 更新插件
+
+```bash
+/plugin update plugin-name
+```
+
+### 禁用 / 启用插件
+
+```bash
+# 临时禁用
+/plugin disable plugin-name
+
+# 重新启用
+/plugin enable plugin-name
+```
+
+### 卸载插件
+
+```bash
+/plugin uninstall plugin-name
+```
+
+## 相关概念
+
+以下 Claude Code 功能会和插件一起协作:
+
+- **[Slash Commands](../01-slash-commands/README.md)** - 插件中打包的单独命令
+- **[Memory](../02-memory/README.md)** - 插件的持久上下文
+- **[Skills](../03-skills/README.md)** - 可以包装进插件的领域能力
+- **[Subagents](../04-subagents/README.md)** - 作为插件组件包含的专门化 agent
+- **[MCP Servers](../05-mcp/README.md)** - 打包在插件中的 Model Context Protocol 集成
+- **[Hooks](../06-hooks/README.md)** - 触发插件工作流的事件处理器
+
+## 完整示例工作流
+
+### PR Review 插件完整工作流
+
+```
+1. 用户:/review-pr
+
+2. 插件执行:
+ ├── pre-review.js hook 验证 git repo
+ ├── GitHub MCP 获取 PR 数据
+ ├── security-reviewer subagent 分析安全
+ ├── test-checker subagent 验证覆盖率
+ └── performance-analyzer subagent 检查性能
+
+3. 汇总并展示结果:
+ ✅ 安全:没有发现关键问题
+ ⚠️ 测试:覆盖率 65%(建议 80%+)
+ ✅ 性能:没有明显影响
+ 📝 提供了 12 条建议
+```
+
+## 故障排查
+
+### 插件无法安装
+- 检查 Claude Code 版本兼容性:`/version`
+- 用 JSON 校验器验证 `plugin.json` 语法
+- 检查网络连接(远程插件)
+- 检查权限:`ls -la plugin/`
+
+### 组件没有加载
+- 验证 `plugin.json` 中的路径与实际目录结构一致
+- 检查文件权限:`chmod +x scripts/`
+- 检查组件文件语法
+- 查看日志:`/plugin debug plugin-name`
+
+### MCP 连接失败
+- 确认环境变量已正确设置
+- 检查 MCP server 的安装和健康状态
+- 使用 `/mcp test` 独立测试 MCP 连接
+- 查看 `mcp/` 目录中的 MCP 配置
+
+### 安装后命令不可用
+- 确认插件已成功安装:`/plugin list --installed`
+- 检查插件是否已启用:`/plugin status plugin-name`
+- 重启 Claude Code:`exit` 后重新打开
+- 检查是否与现有命令冲突
+
+### Hook 执行问题
+- 确认 hook 文件权限正确
+- 检查 hook 语法和事件名
+- 查看 hook 日志中的错误细节
+- 如有可能,手动测试 hooks
+
+## 更多资源
+
+- [官方插件文档](https://code.claude.com/docs/en/plugins)
+- [发现插件](https://code.claude.com/docs/en/discover-plugins)
+- [插件市场](https://code.claude.com/docs/en/plugin-marketplaces)
+- [插件参考](https://code.claude.com/docs/en/plugins-reference)
+- [MCP Server 参考](https://modelcontextprotocol.io/)
+- [Subagent 配置指南](../04-subagents/README.md)
+- [Hook 系统参考](../06-hooks/README.md)
diff --git a/zh/07-plugins/devops-automation/README.md b/zh/07-plugins/devops-automation/README.md
new file mode 100644
index 0000000..0131c53
--- /dev/null
+++ b/zh/07-plugins/devops-automation/README.md
@@ -0,0 +1,114 @@
+---
+name: DevOps 自动化插件
+description: 为部署、监控和故障处理提供自动化工作流
+tags: plugins, devops, automation
+---
+
+# DevOps 自动化插件
+
+完整的 DevOps 自动化工作流,覆盖部署、监控和事故响应。
+
+## 功能
+
+✅ 自动化部署
+✅ 回滚流程
+✅ 系统健康监控
+✅ 事故响应工作流
+✅ Kubernetes 集成
+
+## 安装
+
+```bash
+/plugin install devops-automation
+```
+
+## 包含内容
+
+### Slash 命令
+- `/deploy` - 部署到生产或预发环境
+- `/rollback` - 回滚到上一个版本
+- `/status` - 检查系统健康
+- `/incident` - 处理生产事故
+
+### 子 agents
+- `deployment-specialist` - 部署操作
+- `incident-commander` - 事故协调
+- `alert-analyzer` - 系统健康分析
+
+### MCP 服务器
+- Kubernetes 集成
+
+### 脚本
+- `deploy.sh` - 部署自动化
+- `rollback.sh` - 回滚自动化
+- `health-check.sh` - 健康检查工具
+
+### Hooks
+- `pre-deploy.js` - 部署前验证
+- `post-deploy.js` - 部署后任务
+
+## 使用
+
+### 部署到预发环境
+
+```
+/deploy staging
+```
+
+### 部署到生产环境
+
+```
+/deploy production
+```
+
+### 回滚
+
+```
+/rollback production
+```
+
+### 检查状态
+
+```
+/status
+```
+
+### 处理事故
+
+```
+/incident
+```
+
+## 要求
+
+- Claude Code 1.0+
+- Kubernetes CLI(kubectl)
+- 已配置集群访问
+
+## 配置
+
+设置 Kubernetes 配置:
+
+```bash
+export KUBECONFIG=~/.kube/config
+```
+
+## 示例工作流
+
+```
+用户:/deploy production
+
+Claude:
+1. 运行 pre-deploy hook(验证 kubectl 和集群连接)
+2. 将部署委派给 deployment-specialist subagent
+3. 运行 deploy.sh 脚本
+4. 通过 Kubernetes MCP 监控部署进度
+5. 运行 post-deploy hook(等待 pods 就绪,执行 smoke tests)
+6. 提供部署总结
+
+结果:
+✅ 部署完成
+📦 版本:v2.1.0
+🚀 Pods:3/3 已就绪
+⏱️ 用时:2m 34s
+```
diff --git a/zh/07-plugins/devops-automation/agents/alert-analyzer.md b/zh/07-plugins/devops-automation/agents/alert-analyzer.md
new file mode 100644
index 0000000..647094d
--- /dev/null
+++ b/zh/07-plugins/devops-automation/agents/alert-analyzer.md
@@ -0,0 +1,14 @@
+---
+name: alert-analyzer
+description: 分析监控告警和系统指标
+tools: read, grep, bash
+---
+
+# 告警分析器
+
+分析系统健康状况和告警:
+- 告警关联分析
+- 趋势分析
+- 根因识别
+- 指标可视化
+- 主动问题检测
diff --git a/zh/07-plugins/devops-automation/agents/deployment-specialist.md b/zh/07-plugins/devops-automation/agents/deployment-specialist.md
new file mode 100644
index 0000000..4b5f116
--- /dev/null
+++ b/zh/07-plugins/devops-automation/agents/deployment-specialist.md
@@ -0,0 +1,14 @@
+---
+name: deployment-specialist
+description: 处理所有部署操作
+tools: read, write, bash, grep
+---
+
+# 部署专家
+
+部署运维专家:
+- 蓝绿部署
+- 金丝雀发布
+- 回滚流程
+- 健康检查
+- 数据库迁移
diff --git a/zh/07-plugins/devops-automation/agents/incident-commander.md b/zh/07-plugins/devops-automation/agents/incident-commander.md
new file mode 100644
index 0000000..a749580
--- /dev/null
+++ b/zh/07-plugins/devops-automation/agents/incident-commander.md
@@ -0,0 +1,14 @@
+---
+name: incident-commander
+description: 协调事故响应
+tools: read, write, bash, grep
+---
+
+# 事故指挥官
+
+管理事故响应:
+- 严重性评估
+- 团队协调
+- 状态更新
+- 解决跟踪
+- 事后复盘推动
diff --git a/zh/07-plugins/devops-automation/commands/deploy.md b/zh/07-plugins/devops-automation/commands/deploy.md
new file mode 100644
index 0000000..7c15d6f
--- /dev/null
+++ b/zh/07-plugins/devops-automation/commands/deploy.md
@@ -0,0 +1,15 @@
+---
+name: Deploy
+description: 将应用部署到生产或预发环境
+---
+
+# 应用部署
+
+执行部署工作流:
+
+1. 运行部署前检查
+2. 构建应用
+3. 运行测试
+4. 部署到目标环境
+5. 运行健康检查
+6. 在 Slack 上通知团队
diff --git a/zh/07-plugins/devops-automation/commands/incident.md b/zh/07-plugins/devops-automation/commands/incident.md
new file mode 100644
index 0000000..708c76e
--- /dev/null
+++ b/zh/07-plugins/devops-automation/commands/incident.md
@@ -0,0 +1,16 @@
+---
+name: Incident Response
+description: 使用结构化响应流程处理生产事故
+---
+
+# 事故响应
+
+结构化事故响应工作流:
+
+1. 创建事故记录
+2. 评估严重性和影响
+3. 通知值班团队
+4. 收集诊断信息
+5. 协调响应工作
+6. 记录解决方案
+7. 安排事后复盘
diff --git a/zh/07-plugins/devops-automation/commands/rollback.md b/zh/07-plugins/devops-automation/commands/rollback.md
new file mode 100644
index 0000000..aa71b17
--- /dev/null
+++ b/zh/07-plugins/devops-automation/commands/rollback.md
@@ -0,0 +1,14 @@
+---
+name: Rollback
+description: 回滚到上一次部署
+---
+
+# 回滚部署
+
+回滚到之前的稳定版本:
+
+1. 确认上一次部署
+2. 验证回滚目标健康状态
+3. 执行回滚流程
+4. 运行健康检查
+5. 通知团队
diff --git a/zh/07-plugins/devops-automation/commands/status.md b/zh/07-plugins/devops-automation/commands/status.md
new file mode 100644
index 0000000..df472c0
--- /dev/null
+++ b/zh/07-plugins/devops-automation/commands/status.md
@@ -0,0 +1,15 @@
+---
+name: System Status
+description: 检查整体系统健康状况
+---
+
+# 系统状态检查
+
+检查所有服务的系统健康状况:
+
+1. 查询 Kubernetes pod 状态
+2. 检查数据库连接
+3. 监控 API 响应时间
+4. 查看错误率
+5. 检查资源利用率
+6. 报告整体健康状况
diff --git a/zh/07-plugins/documentation/README.md b/zh/07-plugins/documentation/README.md
new file mode 100644
index 0000000..670d7ec
--- /dev/null
+++ b/zh/07-plugins/documentation/README.md
@@ -0,0 +1,127 @@
+---
+name: 文档生成插件
+description: 为文档编写、同步和校验提供完整工作流
+tags: plugins, documentation, automation
+---
+
+# 文档生成插件
+
+这个插件把文档相关的命令、subagents、模板和 MCP 服务器打包在一起,帮助你生成、同步和校验文档。
+
+## 特性
+
+✅ 生成 API 文档
+✅ 创建和更新 README
+✅ 同步文档
+✅ 改进代码注释
+✅ 生成示例
+
+## 包含内容
+
+### 命令
+- [commands/generate-api-docs.md](commands/generate-api-docs.md) - 生成 API 文档
+- [commands/generate-readme.md](commands/generate-readme.md) - 生成 README
+- [commands/sync-docs.md](commands/sync-docs.md) - 同步文档
+- [commands/validate-docs.md](commands/validate-docs.md) - 校验文档
+
+### Subagents
+- [agents/api-documenter.md](agents/api-documenter.md) - API 文档 subagent
+- [agents/code-commentator.md](agents/code-commentator.md) - 代码注释 subagent
+- [agents/example-generator.md](agents/example-generator.md) - 示例生成 subagent
+
+### 模板
+- [templates/adr-template.md](templates/adr-template.md) - ADR 模板
+- [templates/api-endpoint.md](templates/api-endpoint.md) - API 端点模板
+- [templates/function-docs.md](templates/function-docs.md) - 函数文档模板
+
+### MCP 服务器
+- GitHub 集成 - 用于文档同步
+
+## 安装
+
+```bash
+/plugin install documentation
+```
+
+## 使用方式
+
+### 生成 API 文档
+```bash
+/generate-api-docs
+```
+
+### 创建 README
+```bash
+/generate-readme
+```
+
+### 同步文档
+```bash
+/sync-docs
+```
+
+### 校验文档
+```bash
+/validate-docs
+```
+
+## 适用场景
+
+- 想标准化项目文档产出
+- 想自动生成 README、API 文档和示例
+- 想同步多个文档之间的一致性
+- 想维护代码注释和示例质量
+
+## 需求
+
+- Claude Code 1.0+
+- GitHub 访问权限(可选)
+
+## 示例工作流
+
+```text
+用户:/generate-api-docs
+
+Claude:
+1. 扫描 /src/api/ 下的所有 API 端点
+2. 委派给 api-documenter subagent
+3. 提取函数签名和 JSDoc
+4. 按模块 / 端点组织内容
+5. 使用 api-endpoint.md 模板
+6. 生成完整的 Markdown 文档
+7. 包含 curl、JavaScript 和 Python 示例
+
+结果:
+✅ API 文档已生成
+📄 已创建文件:
+ - docs/api/users.md
+ - docs/api/auth.md
+ - docs/api/products.md
+📊 覆盖率:23/23 个端点已文档化
+```
+
+## 模板用途
+
+### API 端点模板
+用于编写带完整示例的 REST API 文档。
+
+### 函数文档模板
+用于编写单个函数或方法的说明文档。
+
+### ADR 模板
+用于记录架构决策。
+
+## 配置
+
+为文档同步设置 GitHub token:
+```bash
+export GITHUB_TOKEN="your_github_token"
+```
+
+## 最佳实践
+
+- 文档尽量贴近代码
+- 随着代码变化同步更新文档
+- 提供可直接执行的示例
+- 定期校验文档有效性
+- 使用模板保持一致性
diff --git a/zh/07-plugins/documentation/agents/api-documenter.md b/zh/07-plugins/documentation/agents/api-documenter.md
new file mode 100644
index 0000000..40343de
--- /dev/null
+++ b/zh/07-plugins/documentation/agents/api-documenter.md
@@ -0,0 +1,14 @@
+---
+name: api-documenter
+description: API 文档专家
+tools: read, write, grep
+---
+
+# API 文档专家
+
+创建全面的 API 文档:
+- 端点文档
+- 参数说明
+- 响应 schema
+- 代码示例(curl、JavaScript、Python)
+- 错误代码
diff --git a/zh/07-plugins/documentation/agents/code-commentator.md b/zh/07-plugins/documentation/agents/code-commentator.md
new file mode 100644
index 0000000..8b0d9f2
--- /dev/null
+++ b/zh/07-plugins/documentation/agents/code-commentator.md
@@ -0,0 +1,14 @@
+---
+name: code-commentator
+description: 代码注释与内联文档专家
+tools: read, write, edit
+---
+
+# 代码注释专家
+
+改进代码文档:
+- JSDoc / docstring 注释
+- 内联说明
+- 参数说明
+- 返回类型文档
+- 使用示例
diff --git a/zh/07-plugins/documentation/agents/example-generator.md b/zh/07-plugins/documentation/agents/example-generator.md
new file mode 100644
index 0000000..abbc01c
--- /dev/null
+++ b/zh/07-plugins/documentation/agents/example-generator.md
@@ -0,0 +1,14 @@
+---
+name: example-generator
+description: 代码示例与教程专家
+tools: read, write
+---
+
+# 示例生成专家
+
+创建实用的代码示例:
+- 入门指南
+- 常见用例
+- 集成示例
+- 最佳实践
+- 故障排查场景
diff --git a/zh/07-plugins/documentation/commands/generate-api-docs.md b/zh/07-plugins/documentation/commands/generate-api-docs.md
new file mode 100644
index 0000000..5f2182c
--- /dev/null
+++ b/zh/07-plugins/documentation/commands/generate-api-docs.md
@@ -0,0 +1,15 @@
+---
+name: 生成 API 文档
+description: 从源代码生成完整的 API 文档
+---
+
+# API 文档生成器
+
+生成完整的 API 文档:
+
+1. 扫描 API 端点
+2. 提取函数签名和 JSDoc
+3. 按模块 / 端点组织内容
+4. 创建带示例的 Markdown
+5. 包含请求 / 响应 schema
+6. 添加错误文档
diff --git a/zh/07-plugins/documentation/commands/generate-readme.md b/zh/07-plugins/documentation/commands/generate-readme.md
new file mode 100644
index 0000000..cfaf328
--- /dev/null
+++ b/zh/07-plugins/documentation/commands/generate-readme.md
@@ -0,0 +1,15 @@
+---
+name: 生成 README
+description: 创建或更新项目 README
+---
+
+# README 生成器
+
+生成完整的 README:
+
+1. 项目概览与简介
+2. 安装说明
+3. 使用示例
+4. API 文档链接
+5. 贡献指南
+6. 许可证信息
diff --git a/zh/07-plugins/documentation/commands/sync-docs.md b/zh/07-plugins/documentation/commands/sync-docs.md
new file mode 100644
index 0000000..997968a
--- /dev/null
+++ b/zh/07-plugins/documentation/commands/sync-docs.md
@@ -0,0 +1,14 @@
+---
+name: 同步文档
+description: 将文档与代码变更保持同步
+---
+
+# 文档同步
+
+同步文档与代码库:
+
+1. 检测代码变更
+2. 找出过时文档
+3. 更新受影响的文档
+4. 验证示例是否仍然可用
+5. 更新版本号
diff --git a/zh/07-plugins/documentation/commands/validate-docs.md b/zh/07-plugins/documentation/commands/validate-docs.md
new file mode 100644
index 0000000..36bf825
--- /dev/null
+++ b/zh/07-plugins/documentation/commands/validate-docs.md
@@ -0,0 +1,14 @@
+---
+name: 校验文档
+description: 校验文档的完整性与准确性
+---
+
+# 文档校验
+
+校验文档质量:
+
+1. 检查是否有损坏链接
+2. 验证代码示例
+3. 确保内容完整
+4. 检查格式
+5. 对照实际代码进行校验
diff --git a/zh/07-plugins/documentation/templates/adr-template.md b/zh/07-plugins/documentation/templates/adr-template.md
new file mode 100644
index 0000000..8a23f01
--- /dev/null
+++ b/zh/07-plugins/documentation/templates/adr-template.md
@@ -0,0 +1,39 @@
+# ADR [编号]:[标题]
+
+## 状态
+[提议中 | 已接受 | 已弃用 | 已被替代]
+
+## 背景
+我们正在看到的是什么问题,促使我们做出这个决策或变更?
+
+## 决策
+我们提出和/或正在执行的变更是什么?
+
+## 影响
+由于这项变更,哪些事情变得更容易或更困难?
+
+### 正面影响
+- 收益 1
+- 收益 2
+
+### 负面影响
+- 代价 1
+- 代价 2
+
+### 中性影响
+- 参考事项 1
+- 参考事项 2
+
+## 备选方案
+还考虑过哪些其他选项,以及为什么没有选择它们?
+
+### 备选方案 1
+描述以及未选择的原因。
+
+### 备选方案 2
+描述以及未选择的原因。
+
+## 参考资料
+- 相关 ADR
+- 外部文档
+- 讨论链接
diff --git a/zh/07-plugins/documentation/templates/api-endpoint.md b/zh/07-plugins/documentation/templates/api-endpoint.md
new file mode 100644
index 0000000..cd710a3
--- /dev/null
+++ b/zh/07-plugins/documentation/templates/api-endpoint.md
@@ -0,0 +1,101 @@
+# [方法] /api/v1/[endpoint]
+
+## 描述
+简要说明这个端点的作用。
+
+## 身份验证
+所需的身份验证方式,例如 Bearer token。
+
+## 参数
+
+### 路径参数
+| 名称 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| id | string | 是 | 资源 ID |
+
+### 查询参数
+| 名称 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| page | integer | 否 | 页码(默认:1) |
+| limit | integer | 否 | 每页条数(默认:20) |
+
+### 请求体
+```json
+{
+ "field": "value"
+}
+```
+
+## 响应
+
+### 200 OK
+```json
+{
+ "success": true,
+ "data": {
+ "id": "123",
+ "name": "示例"
+ }
+}
+```
+
+### 400 Bad Request
+```json
+{
+ "success": false,
+ "error": {
+ "code": "VALIDATION_ERROR",
+ "message": "无效输入"
+ }
+}
+```
+
+### 404 Not Found
+```json
+{
+ "success": false,
+ "error": {
+ "code": "NOT_FOUND",
+ "message": "资源未找到"
+ }
+}
+```
+
+## 示例
+
+### cURL
+```bash
+curl -X GET "https://api.example.com/api/v1/endpoint" \
+ -H "Authorization: Bearer YOUR_TOKEN" \
+ -H "Content-Type: application/json"
+```
+
+### JavaScript
+```javascript
+const response = await fetch('/api/v1/endpoint', {
+ headers: {
+ 'Authorization': 'Bearer token',
+ 'Content-Type': 'application/json'
+ }
+});
+const data = await response.json();
+```
+
+### Python
+```python
+import requests
+
+response = requests.get(
+ 'https://api.example.com/api/v1/endpoint',
+ headers={'Authorization': 'Bearer token'}
+)
+data = response.json()
+```
+
+## 限流
+- 已认证用户每小时 1000 次请求
+- 公开端点每小时 100 次请求
+
+## 相关端点
+- [GET /api/v1/related](#)
+- [POST /api/v1/related](#)
diff --git a/zh/07-plugins/documentation/templates/function-docs.md b/zh/07-plugins/documentation/templates/function-docs.md
new file mode 100644
index 0000000..b93c6dc
--- /dev/null
+++ b/zh/07-plugins/documentation/templates/function-docs.md
@@ -0,0 +1,50 @@
+# 函数:`functionName`
+
+## 描述
+简要说明这个函数的作用。
+
+## 签名
+```typescript
+function functionName(param1: Type1, param2: Type2): ReturnType
+```
+
+## 参数
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| param1 | Type1 | 是 | param1 的说明 |
+| param2 | Type2 | 否 | param2 的说明 |
+
+## 返回值
+**类型**:`ReturnType`
+
+返回内容的说明。
+
+## 抛出异常
+- `Error`:在输入无效时抛出
+- `TypeError`:在传入错误类型时抛出
+
+## 示例
+
+### 基本用法
+```typescript
+const result = functionName('value1', 'value2');
+console.log(result);
+```
+
+### 高级用法
+```typescript
+const result = functionName(
+ complexParam1,
+ { option: true }
+);
+```
+
+## 备注
+- 其他说明或警告
+- 性能注意事项
+- 最佳实践
+
+## 另请参阅
+- [相关函数](#)
+- [API 文档](#)
diff --git a/zh/07-plugins/pr-review/README.md b/zh/07-plugins/pr-review/README.md
new file mode 100644
index 0000000..b60dcc1
--- /dev/null
+++ b/zh/07-plugins/pr-review/README.md
@@ -0,0 +1,96 @@
+---
+name: PR 审查插件
+description: 为 Pull Request 提供完整的代码审查工作流
+tags: plugins, code-review, pull-request
+---
+
+# PR 审查插件
+
+完整的 PR 审查工作流,包含安全、测试和文档检查。
+
+## 功能
+
+✅ 安全分析
+✅ 测试覆盖率检查
+✅ 文档校验
+✅ 代码质量评估
+✅ 性能影响分析
+
+## 安装
+
+```bash
+/plugin install pr-review
+```
+
+## 包含内容
+
+### Slash 命令
+- `/review-pr` - 全面 PR 审查
+- `/check-security` - 面向安全的审查
+- `/check-tests` - 测试覆盖率分析
+
+### 子 agents
+- `security-reviewer` - 安全漏洞检测
+- `test-checker` - 测试覆盖率分析
+- `performance-analyzer` - 性能影响评估
+
+### MCP 服务器
+- 用于 PR 数据的 GitHub 集成
+
+### Hooks
+- `pre-review.js` - 审查前验证
+
+## 使用
+
+### 基础 PR 审查
+
+```
+/review-pr
+```
+
+### 仅安全检查
+
+```
+/check-security
+```
+
+### 仅测试覆盖率检查
+
+```
+/check-tests
+```
+
+## 要求
+
+- Claude Code 1.0+
+- GitHub 访问权限
+- Git 仓库
+
+## 配置
+
+设置 GitHub token:
+
+```bash
+export GITHUB_TOKEN="your_github_token"
+```
+
+## 示例工作流
+
+```
+用户:/review-pr
+
+Claude:
+1. 运行 pre-review hook(验证 git 仓库)
+2. 通过 GitHub MCP 获取 PR 数据
+3. 将安全审查委派给 security-reviewer subagent
+4. 将测试分析委派给 test-checker subagent
+5. 将性能分析委派给 performance-analyzer subagent
+6. 汇总所有发现
+7. 提供完整审查报告
+
+结果:
+✅ 安全:未发现关键问题
+⚠️ 测试:覆盖率为 65%,建议达到 80%+
+✅ 性能:没有明显影响
+📝 建议:为边界情况添加测试
+```
diff --git a/zh/07-plugins/pr-review/agents/performance-analyzer.md b/zh/07-plugins/pr-review/agents/performance-analyzer.md
new file mode 100644
index 0000000..5eaccb3
--- /dev/null
+++ b/zh/07-plugins/pr-review/agents/performance-analyzer.md
@@ -0,0 +1,13 @@
+---
+name: performance-analyzer
+description: 性能影响分析
+tools: read, grep, bash
+---
+
+# 性能分析器
+
+评估变更对性能的影响:
+- 算法复杂度
+- 数据库查询效率
+- 内存使用
+- 缓存机会
diff --git a/zh/07-plugins/pr-review/agents/security-reviewer.md b/zh/07-plugins/pr-review/agents/security-reviewer.md
new file mode 100644
index 0000000..e325ad0
--- /dev/null
+++ b/zh/07-plugins/pr-review/agents/security-reviewer.md
@@ -0,0 +1,13 @@
+---
+name: security-reviewer
+description: 面向安全的代码审查
+tools: read, grep, diff
+---
+
+# 安全审查员
+
+专注于发现安全漏洞:
+- 身份验证/授权问题
+- 数据暴露
+- 注入攻击
+- 安全配置
diff --git a/zh/07-plugins/pr-review/agents/test-checker.md b/zh/07-plugins/pr-review/agents/test-checker.md
new file mode 100644
index 0000000..6344b83
--- /dev/null
+++ b/zh/07-plugins/pr-review/agents/test-checker.md
@@ -0,0 +1,13 @@
+---
+name: test-checker
+description: 测试覆盖率与质量分析
+tools: read, bash, grep
+---
+
+# 测试检查器
+
+分析测试覆盖率和质量:
+- 覆盖率百分比
+- 缺失的测试用例
+- 测试质量评估
+- 边界情况识别
diff --git a/zh/07-plugins/pr-review/commands/check-security.md b/zh/07-plugins/pr-review/commands/check-security.md
new file mode 100644
index 0000000..a527d87
--- /dev/null
+++ b/zh/07-plugins/pr-review/commands/check-security.md
@@ -0,0 +1,14 @@
+---
+name: Security Check
+description: 运行安全导向的代码审查
+---
+
+# 安全检查
+
+对代码变更执行聚焦式安全分析:
+
+1. 身份验证/授权检查
+2. 数据暴露风险
+3. 注入漏洞
+4. 密码学弱点
+5. 日志中的敏感数据
diff --git a/zh/07-plugins/pr-review/commands/check-tests.md b/zh/07-plugins/pr-review/commands/check-tests.md
new file mode 100644
index 0000000..581ecbd
--- /dev/null
+++ b/zh/07-plugins/pr-review/commands/check-tests.md
@@ -0,0 +1,14 @@
+---
+name: Test Coverage Check
+description: 验证测试覆盖率和质量
+---
+
+# 测试覆盖检查
+
+分析测试覆盖率和质量:
+
+1. 检查测试覆盖率百分比
+2. 识别未测试的代码路径
+3. 审查测试质量
+4. 建议缺失的测试用例
+5. 确认边界情况已覆盖
diff --git a/zh/07-plugins/pr-review/commands/review-pr.md b/zh/07-plugins/pr-review/commands/review-pr.md
new file mode 100644
index 0000000..cbf8198
--- /dev/null
+++ b/zh/07-plugins/pr-review/commands/review-pr.md
@@ -0,0 +1,14 @@
+---
+name: Review PR
+description: 启动包含安全与测试检查的完整 PR 审查
+---
+
+# PR 审查
+
+这个命令会发起一次完整的 Pull Request 审查,包括:
+
+1. 安全分析
+2. 测试覆盖率验证
+3. 文档更新
+4. 代码质量检查
+5. 性能影响评估
diff --git a/zh/08-checkpoints/README.md b/zh/08-checkpoints/README.md
new file mode 100644
index 0000000..1740625
--- /dev/null
+++ b/zh/08-checkpoints/README.md
@@ -0,0 +1,292 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Checkpoints 与 Rewind
+
+Checkpoints 可以让你保存对话状态,并在 Claude Code 会话中回退到之前的时间点。无论你是在探索不同方案、修复错误,还是比较多个实现路径,这个能力都非常有用。
+
+## 概览
+
+Checkpoints 会保存会话状态,让你可以安全地试验和探索多种方案。它们本质上是当前对话状态的快照,包含:
+- 所有已交换的消息
+- 已做出的文件修改
+- 工具使用历史
+- 当前会话上下文
+
+当你在尝试不同实现方式、从错误中恢复,或比较替代方案时,这个功能尤其好用。
+
+## 核心概念
+
+| 概念 | 说明 |
+|---------|-------------|
+| **Checkpoint** | 保存消息、文件和上下文的对话快照 |
+| **Rewind** | 回到之前的 checkpoint,并丢弃之后的更改 |
+| **Branch Point** | 从同一个 checkpoint 出发,探索多个方案 |
+
+## 访问 Checkpoints
+
+你可以通过两种主要方式访问和管理 checkpoints:
+
+### 使用键盘快捷键
+
+按两次 `Esc`(`Esc` + `Esc`)打开 checkpoint 界面并浏览已保存的 checkpoints。
+
+### 使用 Slash Command
+
+使用 `/rewind` 命令(别名:`/checkpoint`)快速进入:
+
+```bash
+# 打开 rewind 界面
+/rewind
+
+# 或者使用别名
+/checkpoint
+```
+
+## Rewind 选项
+
+回退时,你会看到一个包含五个选项的菜单:
+
+1. **恢复代码和对话** - 把文件和消息都恢复到那个 checkpoint
+2. **恢复对话** - 只回退消息,保留当前代码不变
+3. **恢复代码** - 只回退文件修改,保留完整对话历史
+4. **从这里开始总结** - 把从这里往后的对话压缩成 AI 生成的摘要,而不是直接丢弃。原始消息仍会保留在记录中。你也可以额外指定摘要应聚焦哪些主题。
+5. **算了** - 取消并返回当前状态
+
+## 自动 Checkpoints
+
+Claude Code 会自动为你创建 checkpoints:
+
+- **每次用户提示** - 每次用户输入都会创建一个新 checkpoint
+- **持久保存** - checkpoints 会跨会话保留
+- **自动清理** - 30 天后自动清理旧 checkpoints
+
+这意味着你随时都可以回到之前的任意节点,从几分钟前到几天前都可以。
+
+## 使用场景
+
+| 场景 | 工作流 |
+|----------|----------|
+| **探索不同方案** | 保存 → 试方案 A → 保存 → Rewind → 试方案 B → 比较 |
+| **安全重构** | 保存 → 重构 → 测试 → 如果失败:Rewind |
+| **A/B 测试** | 保存 → 设计 A → 保存 → Rewind → 设计 B → 比较 |
+| **错误恢复** | 发现问题 → Rewind 到最后一个正常状态 |
+
+## 如何使用 Checkpoints
+
+### 查看和回退
+
+按两次 `Esc`,或者使用 `/rewind` 打开 checkpoint 浏览器。你会看到一个带时间戳的可用 checkpoint 列表。选择任意一个 checkpoint,即可回退到该状态。
+
+### Checkpoint 详情
+
+每个 checkpoint 会显示:
+- 创建时间
+- 被修改的文件
+- 对话中的消息数量
+- 使用过的工具
+
+## 实战示例
+
+更多可直接参考的中文示例见 [checkpoint-examples.md](checkpoint-examples.md)。
+
+### 示例 1:探索不同方案
+
+```text
+User: 我们给 API 加一个缓存层吧
+
+Claude: 我会为你的 API 端点添加 Redis 缓存……
+[在 checkpoint A 处做出修改]
+
+User: 其实我们先试试内存缓存
+
+Claude: 我会 rewind 回去,探索另一种方案……
+[用户按下 Esc+Esc 并回退到 checkpoint A]
+[在 checkpoint B 处实现内存缓存]
+
+User: 现在我可以比较两种方案了
+```
+
+### 示例 2:从错误中恢复
+
+```text
+User: 把认证模块重构成 JWT
+
+Claude: 我会重构认证模块……
+[做出大量修改]
+
+User: 等等,这把 OAuth 集成弄坏了。我们回去。
+
+Claude: 我来帮你回退到重构之前……
+[用户按下 Esc+Esc,并选择重构前的 checkpoint]
+
+User: 这次我们试一个更保守的方案
+```
+
+### 示例 3:安全试验
+
+```text
+User: 我们试着把它改写成函数式风格
+[在实验前创建 checkpoint]
+
+Claude: [执行实验性修改]
+
+User: 测试失败了。我们回退吧。
+[用户按下 Esc+Esc 并回退到 checkpoint]
+
+Claude: 我已经回退这些更改了。我们试另一个方案。
+```
+
+### 示例 4:分支式探索
+
+```text
+User: 我想比较两种数据库设计
+[记下 checkpoint,命名为 "Start"]
+
+Claude: 我先实现第一种设计……
+[实现 Schema A]
+
+User: 现在让我回去试第二种方案
+[用户按下 Esc+Esc 并回退到 "Start"]
+
+Claude: 现在我实现 Schema B……
+[实现 Schema B]
+
+User: 太好了,我现在有两个 schema 可以选择
+```
+
+## Checkpoint 保留策略
+
+Claude Code 会自动管理你的 checkpoints:
+
+- 每次用户输入都会自动创建 checkpoint
+- 旧 checkpoint 最多保留 30 天
+- 系统会自动清理,避免存储无限增长
+
+## 工作流模式
+
+### 探索时的分支策略
+
+当你在探索多个方案时:
+
+```text
+1. 从初始实现开始 → Checkpoint A
+2. 尝试方案 1 → Checkpoint B
+3. 回退到 Checkpoint A
+4. 尝试方案 2 → Checkpoint C
+5. 比较 B 和 C 的结果
+6. 选择最佳方案并继续
+```
+
+### 安全重构模式
+
+当你在做大改动时:
+
+```text
+1. 当前状态 → Checkpoint(自动)
+2. 开始重构
+3. 运行测试
+4. 如果测试通过 → 继续
+5. 如果测试失败 → Rewind 并尝试别的方案
+```
+
+## 最佳实践
+
+因为 checkpoints 是自动创建的,所以你可以专注于工作,而不用担心手动保存状态。不过,下面这些习惯仍然很重要:
+
+### 如何高效使用 Checkpoints
+
+✅ **应该做:**
+- 回退前先看清楚可用的 checkpoints
+- 当你想尝试不同方向时使用 rewind
+- 保留 checkpoints 方便比较不同方案
+- 理解每个 rewind 选项的作用(恢复代码和对话、恢复对话、恢复代码、或总结)
+
+❌ **不要做:**
+- 只依赖 checkpoints 来保存代码
+- 指望 checkpoints 跟踪外部文件系统变化
+- 把 checkpoints 当成 git commit 的替代品
+
+## 配置
+
+你可以在设置中开启或关闭自动 checkpoints:
+
+```json
+{
+ "autoCheckpoint": true
+}
+```
+
+- `autoCheckpoint`:是否在每次用户提示后自动创建 checkpoint(默认:`true`)
+
+## 局限性
+
+Checkpoints 很适合会话级回退,但它不是版本控制系统。对于需要长期保存、可审计、可共享的改动,仍然应该使用 git。
+
+## 故障排查
+
+### 找不到 Checkpoints
+
+- 检查你是否在支持该功能的 Claude Code 版本中
+- 确认自动 checkpoint 没有被关闭
+- 重新打开会话再试一次
+
+### Rewind 失败
+
+- 确认你选择了一个有效的 checkpoint
+- 查看是否存在与文件系统或权限相关的限制
+- 尝试先分别恢复代码或对话,再决定是否同时恢复两者
+
+## 与 Git 的集成
+
+Checkpoints 和 git 是互补关系:
+
+- Checkpoints 用于会话内探索和安全试验
+- Git 用于永久保存代码历史
+- 你可以先用 checkpoints 快速试错,再把最终方案提交到 git
+
+## 快速开始
+
+### 基本工作流
+
+```text
+1. 开始修改前自动创建 checkpoint
+2. 尝试某个方案
+3. 如果结果不理想,按 Esc 两次
+4. 选择合适的 rewind 选项
+5. 继续探索或提交最终方案
+```
+
+### 键盘快捷键
+
+- `Esc` + `Esc`:打开 checkpoint 浏览器
+- `/rewind`:通过命令进入回退界面
+- `/checkpoint`:`/rewind` 的别名
+
+## 什么时候该 rewind:上下文监控
+
+如果你发现这些信号,通常就该回退了:
+
+- 当前方案开始变复杂,而且你还没确定方向
+- 测试刚失败,问题可能就是最近一两步引入的
+- 你想比较两种实现方式
+- 你想保留一个“干净起点”继续探索
+
+## 相关概念
+
+- **Memory**:跨会话的长期上下文,见 [02-memory/README.md](../02-memory/README.md)
+- **Hooks**:事件驱动自动化,见 [06-hooks/README.md](../06-hooks/README.md)
+- **Plugins**:打包功能集合,见 [07-plugins/README.md](../07-plugins/README.md)
+- **Advanced Features**:包括 planning mode 和背景任务,见 [09-advanced-features/README.md](../09-advanced-features/README.md)
+
+## 更多资源
+
+- [根目录中文指南](../README.md)
+- [Claude Code 官方检查点文档](https://code.claude.com/docs/en/checkpointing)
+- [Claude Code 高级功能指南](../09-advanced-features/README.md)
+
+## 总结
+
+Checkpoints 的价值在于让你敢于试错。它让“先试再说”和“试错后立刻回退”变得安全,从而帮你更快找到正确方案。
diff --git a/zh/08-checkpoints/checkpoint-examples.md b/zh/08-checkpoints/checkpoint-examples.md
new file mode 100644
index 0000000..9e06caf
--- /dev/null
+++ b/zh/08-checkpoints/checkpoint-examples.md
@@ -0,0 +1,339 @@
+# 检查点示例
+
+以下是一些在 Claude Code 中有效使用检查点的真实示例。
+
+注意:每次用户提示都会自动创建检查点。你不需要手动保存。要回退,请连续按两次 `Esc`(`Esc+Esc`),或者使用 `/rewind` 打开检查点浏览器。
+
+## 示例 1:数据库迁移
+
+### 场景
+你需要从 MySQL 迁移到 PostgreSQL,但想同时探索直接迁移和渐进式双写两种方案。
+
+### 工作流程
+
+```
+用户:我们来实现一个从 MySQL 到 PostgreSQL 的直接迁移方案
+ [检查点 A 自动创建]
+
+Claude:我来实现直接迁移……
+[更换数据库驱动、更新查询、修改 schema]
+
+用户:运行测试
+ [检查点 B 自动创建]
+
+Claude:正在运行测试……
+❌ 15 个测试失败 - 连接池问题
+
+用户:这个方案有问题。我们改试双写模式。
+[用户按下 Esc+Esc,选择检查点 A,选择“恢复代码和对话”]
+
+用户:现在实现双写模式,同时向两个数据库写入
+
+Claude:我来实现双写迁移……
+[实现双写层、渐进式迁移策略]
+
+用户:运行测试
+
+Claude:正在运行测试……
+✅ 所有测试通过
+
+用户:双写方案明显更稳妥。我们提交这个版本。
+```
+
+## 示例 2:性能优化
+
+### 场景
+尝试多种性能优化策略。
+
+### 工作流程
+
+```
+用户:我们来优化 API 响应时间。当前:450ms
+ [检查点“Baseline”自动创建]
+
+Claude:我来加数据库查询缓存……
+[实现 Redis 缓存]
+
+用户:运行性能测试
+
+Claude:结果:平均响应时间 280ms(提升 38%)
+
+用户:我想试试另一种方法。
+[用户按下 Esc+Esc,选择“Baseline”检查点,选择“恢复代码和对话”]
+
+用户:改试数据库查询优化
+
+Claude:我来优化数据库查询……
+[添加索引,优化 N+1 查询]
+
+用户:运行性能测试
+
+Claude:结果:平均响应时间 180ms(提升 60%)
+
+用户:我也想试第三种方法。
+[用户按下 Esc+Esc,选择“Baseline”检查点,选择“恢复代码和对话”]
+
+用户:尝试响应压缩和 CDN
+
+Claude:我来添加压缩和 CDN……
+[实现 gzip,配置 CDN]
+
+用户:运行性能测试
+
+Claude:结果:平均响应时间 320ms(提升 29%)
+
+用户:查询优化最好。让我回到那个版本,再和缓存结合起来。
+[用户按下 Esc+Esc,选择查询优化后的检查点,选择“恢复代码和对话”]
+
+用户:现在在这些优化后的查询之上再加上 Redis 缓存
+
+Claude:[在优化后的查询之上添加 Redis 缓存]
+
+用户:运行性能测试
+
+Claude:结果:平均响应时间 95ms(提升 79%)🎉
+
+用户:完美!这就是最终方案。我们提交它。
+```
+
+## 示例 3:UI/UX 迭代
+
+### 场景
+为仪表板尝试不同布局。
+
+### 工作流程
+
+```
+用户:我们来把仪表板重设计成侧边栏布局
+ [检查点“Start”自动创建]
+
+Claude:[实现侧边栏布局]
+
+用户:给我看一张截图
+
+Claude:[显示截图]
+
+用户:侧边栏太拥挤了。我们试试顶部导航吧。
+[用户按下 Esc+Esc,选择“Start”检查点,选择“恢复代码和对话”]
+
+用户:试试顶部导航布局
+
+Claude:[实现顶部导航]
+
+用户:给我看一张截图
+
+Claude:[显示截图]
+
+用户:好多了,不过我们再试试卡片式网格布局。
+[用户按下 Esc+Esc,选择“Start”检查点,选择“恢复代码和对话”]
+
+用户:试试卡片式网格布局
+
+Claude:[实现卡片网格]
+
+用户:给我看一张截图
+
+Claude:[显示截图]
+
+用户:这个很不错!不过我们能把顶部导航和卡片网格结合起来吗?
+[用户按下 Esc+Esc,选择卡片网格后的检查点,选择“恢复代码和对话”]
+
+用户:给卡片网格布局加上顶部导航
+
+Claude:[在卡片网格上添加顶部导航]
+
+用户:完美!这就是最终设计。
+```
+
+## 示例 4:调试会话
+
+### 场景
+用多个假设排查一个难缠的 bug。
+
+### 工作流程
+
+```
+用户:应用里有内存泄漏
+ [检查点“Before debugging”自动创建]
+
+Claude:让我来调查……
+[分析代码]
+
+用户:我觉得问题在事件监听器里。我们先修这个。
+
+Claude:[修复事件监听器清理逻辑]
+
+用户:运行内存分析器
+
+Claude:仍然在泄漏内存 - 事件监听器不是问题所在
+
+用户:让我回到之前,换个思路试试。
+[用户按下 Esc+Esc,选择“Before debugging”检查点,选择“恢复代码和对话”]
+
+用户:也许是数据库连接的问题?
+
+Claude:[实现连接池修复]
+
+用户:运行内存分析器
+
+Claude:还是在泄漏 - 也不是连接的问题
+
+用户:我再回去,换另一个方向试试。
+[用户按下 Esc+Esc,选择“Before debugging”检查点,选择“恢复代码和对话”]
+
+用户:我们检查一下有没有循环引用
+
+Claude:[找到并修复缓存中的循环引用]
+
+用户:运行内存分析器
+
+Claude:✅ 内存泄漏修复了!缓存层里的循环引用就是罪魁祸首。
+
+用户:太好了!我们提交这个修复。
+```
+
+## 示例 5:API 设计演进
+
+### 场景
+为 REST API 设计做多轮迭代。
+
+### 工作流程
+
+```
+用户:给我们的博客平台创建一个 REST API
+ [检查点“Before API design”自动创建]
+
+Claude:[创建基础 CRUD API]
+
+用户:这个太简单了。加上分页和过滤
+
+Claude:[添加分页和过滤]
+
+用户:我们需要更好的资源关系
+
+Claude:[实现 HATEOAS 链接]
+
+用户:其实我们改用 GraphQL,不用 REST 了
+[用户按下 Esc+Esc,选择“Before API design”检查点,选择“恢复代码和对话”]
+
+用户:那就为我们的博客平台改实现 GraphQL API 吧
+
+Claude:[实现 GraphQL API]
+
+用户:我觉得 REST 更适合我们的场景。
+[用户按下 Esc+Esc,选择 HATEOAS 之后的检查点,选择“恢复代码和对话”]
+
+用户:那我们就把 REST 方案定下来。
+```
+
+## 示例 6:配置管理
+
+### 场景
+测试不同的配置方案。
+
+### 工作流程
+
+```
+用户:把配置迁移到环境变量
+ [检查点“Original config”自动创建]
+
+Claude:[实现环境变量配置]
+
+用户:在开发环境里测试
+
+Claude:本地可用,但生产环境部署有问题
+
+用户:我换个方案试试。
+[用户按下 Esc+Esc,选择“Original config”检查点,选择“恢复代码和对话”]
+
+用户:改成带校验的配置文件方案
+
+Claude:[实现带 JSON Schema 校验的 YAML 配置]
+
+用户:在开发环境里测试
+
+Claude:✅ 运行良好,校验错误提示也很清楚
+
+用户:我们也能为敏感值支持环境变量吗?
+
+Claude:[为密钥添加环境变量覆盖]
+
+用户:测试部署
+
+Claude:✅ 所有环境都正常工作
+
+用户:完美,这个已经可以用于生产。
+```
+
+## 示例 7:测试策略
+
+### 场景
+实现完整的测试体系。
+
+### 工作流程
+
+```
+用户:给 auth 模块添加单元测试
+ [检查点自动创建]
+
+Claude:[添加 Jest 单元测试]
+
+用户:运行测试
+
+Claude:45 个测试通过,覆盖率 78%
+
+用户:再加上集成测试
+
+Claude:[添加集成测试]
+
+用户:运行测试
+
+Claude:89 个测试通过,覆盖率 92%,但测试太慢了(3 分钟)
+
+用户:测试太慢了,我们来优化。
+
+Claude:[优化测试设置,增加并行执行]
+
+用户:运行测试
+
+Claude:89 个测试通过,覆盖率 92%,35 秒完成 ✅
+
+用户:很好!再给关键路径加上 E2E 测试。
+
+Claude:[添加 Playwright E2E 测试]
+
+用户:运行所有测试
+
+Claude:112 个测试通过,覆盖率 94%,2 分钟完成
+
+用户:很好,覆盖率和速度都平衡得不错!
+```
+
+## 示例 8:从检查点开始总结
+
+### 场景
+在一次很长的调试会话后,你想压缩对话内容,同时保留上下文。
+
+### 工作流程
+
+```
+用户:[经过 20 多条消息的调试和探索之后]
+
+[用户按下 Esc+Esc,选择较早的检查点,选择“从这里开始总结”]
+[可选地提供指令:“重点保留我们尝试过什么,以及什么有效”]
+
+Claude:[生成从该点开始的对话总结]
+[原始消息保留在记录里]
+[总结会替换当前可见对话,从而减少上下文窗口占用]
+
+用户:现在继续推进那个有效的方案。
+```
+
+## 关键结论
+
+1. **检查点是自动创建的**:每次用户提示都会创建一个检查点,不需要手动保存。
+2. **使用 `Esc+Esc` 或 `/rewind`**:这两种方式都可以打开检查点浏览器。
+3. **选择合适的恢复方式**:根据需要恢复代码、对话、两者都恢复,或者直接总结。
+4. **不要害怕试验**:检查点让你可以安全尝试激进的改动。
+5. **和 git 结合使用**:检查点用于探索,git 用于最终落地。
+6. **长会话要及时总结**:用“从这里开始总结”来保持对话可管理。
diff --git a/zh/09-advanced-features/README.md b/zh/09-advanced-features/README.md
new file mode 100644
index 0000000..32fe9ac
--- /dev/null
+++ b/zh/09-advanced-features/README.md
@@ -0,0 +1,954 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# 高级功能
+
+这是一份关于 Claude Code 高级能力的完整指南,涵盖 planning mode、extended thinking、auto mode、后台任务、权限模式、打印模式(非交互)、会话管理、交互功能、消息通道(Channels)、语音输入、远程控制、网页会话、桌面应用、任务列表、提示词建议、Git 工作树、沙盒、受管设置和配置。
+
+## 目录
+
+1. [概览](#概览)
+2. [规划模式](#规划模式)
+3. [扩展思考](#扩展思考)
+4. [自动模式](#自动模式)
+5. [后台任务](#后台任务)
+6. [定时任务](#定时任务)
+7. [权限模式](#权限模式)
+8. [无头模式](#无头模式)
+9. [会话管理](#会话管理)
+10. [交互功能](#交互功能)
+11. [语音输入](#语音输入)
+12. [消息通道(Channels)](#消息通道channels)
+13. [Chrome 集成](#chrome-集成)
+14. [远程控制](#远程控制)
+15. [网页会话](#网页会话)
+16. [桌面应用](#桌面应用)
+17. [任务列表](#任务列表)
+18. [提示词建议](#提示词建议)
+19. [Git 工作树(Git Worktrees)](#git-工作树git-worktrees)
+20. [沙盒](#沙盒)
+21. [企业受管设置](#企业受管设置)
+22. [配置与设置](#配置与设置)
+23. [最佳实践](#最佳实践)
+24. [更多资源](#更多资源)
+
+---
+
+<a id="overview"></a>
+## 概览
+
+Claude Code 的高级功能把基础能力扩展到了规划、推理、自动化和控制层面。它们能支持更复杂的开发任务、代码审查、自动化流程以及多会话管理。
+
+**核心高级功能包括:**
+- **Planning Mode**:先写详细实现计划,再开始编码
+- **Extended Thinking**:对复杂问题进行更深入的推理
+- **Auto Mode**:由后台安全分类器在每一步执行前进行审查(Research Preview)
+- **Background Tasks**:长时间任务不阻塞对话
+- **Permission Modes**:控制 Claude 可以做什么(`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions`)
+- **Print Mode**:非交互式运行,适合自动化和 CI/CD(`claude -p`)
+- **Session Management**:管理多个会话
+- **Interactive Features**:快捷键、多行输入、历史记录
+- **Voice Dictation**:按住说话,支持 20 种语言的语音识别
+- **Channels**:消息通道,允许 MCP server 向运行中的会话推送消息(Research Preview)
+- **Remote Control**:从 Claude.ai 或 Claude app 控制本地会话
+- **Web Sessions**:在浏览器中运行 Claude Code
+- **Desktop App**:支持可视化 diff 审查和多会话的独立应用
+- **Task List**:跨 context compaction 持久跟踪任务
+- **Prompt Suggestions**:根据上下文智能推荐命令
+- **Git 工作树(Git Worktrees)**:隔离的 worktree 分支,适合并行工作
+- **Sandboxing**:操作系统级文件系统和网络隔离
+- **Managed Settings**:通过 plist、Registry 或受管文件进行企业部署
+- **Configuration**:用 JSON 配置文件定制行为
+
+<a id="planning-mode"></a>
+## 规划模式
+
+更多规划示例见 [planning-mode-examples.md](planning-mode-examples.md)。
+
+Planning mode 允许 Claude 在真正实现前先梳理复杂任务,生成一份你可以审阅并批准的详细计划。
+
+### 什么是 Planning Mode?
+
+Planning mode 是一个两阶段流程:
+1. **规划阶段**:Claude 分析任务并生成详细实现计划
+2. **实现阶段**:在你批准后,Claude 执行计划
+
+### 什么时候使用 Planning Mode
+
+✅ 适合:
+- 复杂的多文件重构
+- 新功能开发
+- 架构调整
+- 数据库迁移
+- 大型 API 重设计
+
+❌ 不建议:
+- 简单 bug 修复
+- 格式化修改
+- 单文件编辑
+- 快速查询
+
+### 如何启动 Planning Mode
+
+**Slash command:**
+```bash
+/plan Implement user authentication system
+```
+
+**CLI 参数:**
+```bash
+claude --permission-mode plan
+```
+
+**设为默认:**
+```json
+{
+ "permissions": {
+ "defaultMode": "plan"
+ }
+}
+```
+
+**快捷键:**
+- `Shift + Tab` - 切换权限模式(包括 plan)
+- `Alt + M` - 切换权限模式(Windows/Linux)
+
+### Planning Mode 的好处
+
+- **结构化实施方式**:把实现步骤拆得更清楚
+- **审阅和批准**:先看计划,再执行
+- **风险识别**:先发现潜在问题
+- **阶段清晰**:有明确的里程碑和阶段划分
+
+### 示例:功能实现
+
+```text
+User: /plan Add a real-time notification system
+
+Claude: 我会为实时通知系统制定计划。
+
+## 实现计划
+
+### 阶段 1:基础设施
+1. 安装 WebSocket 库(socket.io)
+2. 搭建 WebSocket server
+3. 配置连接管理
+
+### 阶段 2:后端
+4. 创建通知服务
+5. 实现通知队列
+6. 为通知添加数据库 schema
+7. 创建 API 端点
+
+### 阶段 3:前端
+8. 搭建 WebSocket client
+9. 创建通知 UI 组件
+10. 实现通知状态管理
+11. 添加通知权限
+
+### 阶段 4:测试与发布
+12. 编写单元测试
+13. 编写集成测试
+14. 更新文档
+15. 部署到 staging
+
+预计时间:3-4 小时
+需要修改的文件:12 个
+需要创建的新文件:8 个
+
+准备继续吗?(yes/no/modify plan)
+```
+
+### 计划修改
+
+```text
+User: 修改计划 - 先跳过队列,后面再加
+
+Claude: 已更新计划:
+[展示删除队列后的计划]
+
+User: 看起来不错,继续
+
+Claude: [按修改后的计划开始实现]
+```
+
+### Planning Mode 配置
+
+你可以通过 CLI 参数或 slash command 启用 planning mode:
+
+```bash
+# 通过 CLI 启用 plan mode
+claude --permission-mode plan
+
+# 或在 REPL 里使用 /plan
+/plan Implement user authentication system
+```
+
+**规划专用模型别名**:使用 `opusplan`,规划用 Opus,执行用 Sonnet:
+
+```bash
+claude --model opusplan "design and implement the new API"
+```
+
+**外部编辑计划**:按 `Ctrl+G` 可以把当前计划打开到外部编辑器里进行更详细的修改。
+
+<a id="extended-thinking"></a>
+## 扩展思考
+
+Extended thinking 让 Claude 在给出解决方案前,花更多时间进行复杂推理。
+
+### 什么是 Extended Thinking?
+
+这是一个有意识的、分步骤的推理过程,Claude 会:
+- 拆解复杂问题
+- 比较多种方案
+- 评估权衡
+- 推导边界情况
+
+### 如何启用
+
+**快捷键:**
+- `Option + T`(macOS)/ `Alt + T`(Windows/Linux)- 切换 extended thinking
+
+**自动启用:**
+- 对所有模型默认开启(Opus 4.6、Sonnet 4.6、Haiku 4.5)
+- Opus 4.6 支持自适应推理,effort 等级为 `low`(○)、`medium`(◐)、`high`(●)、`max`(仅 Opus 4.6)
+
+### 好处
+
+- 更适合复杂问题
+- 更容易发现边界条件
+- 便于比较多个方案
+- 输出通常更稳健
+
+### 示例:架构决策
+
+```text
+Context Analysis
+Approach 1: Microservices
+Approach 2: Monolith
+Decision Factors
+Recommendation
+```
+
+### 配置
+
+```json
+{
+ "thinking": {
+ "enabled": true,
+ "effort": "high"
+ }
+}
+```
+
+<a id="auto-mode"></a>
+## 自动模式
+
+Auto mode 是一个研究预览功能。它会在每个动作执行前,用后台安全分类器评估风险,帮助你在自动化和安全之间取得平衡。
+
+### 需求
+
+- 支持 auto mode 的 Claude Code 版本
+- 合适的权限和配置
+
+### 启用方式
+
+```bash
+# 用 CLI 解锁 auto mode
+claude --enable-auto-mode
+
+# 然后在 REPL 中用 Shift+Tab 切换到它
+```
+
+### 分类器如何工作
+
+在执行工具前,后台分类器会判断这个动作是否安全、是否需要提示、是否应该被阻止。
+
+### 默认阻止的动作
+
+- 明显危险的文件操作
+- 高风险 shell 命令
+- 可能泄露凭据的操作
+
+### 默认允许的动作
+
+- 只读检查
+- 常规分析
+- 低风险修改
+
+### 配置 Auto Mode
+
+Auto mode 可以在设置中进一步约束、放宽或与权限模式结合使用。
+
+### 回退行为
+
+如果分类器无法判定,Claude 会回退到更保守的权限处理方式。
+
+### 预置一份类似 Auto-Mode 的保守权限基线
+
+```bash
+# 先预览将要添加的权限(不会写入)
+
+# 应用保守基线
+
+# 只有在需要时再逐步增加能力
+```
+
+<a id="background-tasks"></a>
+## 后台任务
+
+后台任务允许 Claude 在不阻塞对话的情况下运行长时间操作。
+
+### 什么是后台任务?
+
+后台任务适合长时间运行的工作,例如构建、测试、下载、扫描或并行分析。你可以把它们交给 Claude,让对话继续保持响应。
+
+### 启动后台任务
+
+你可以从命令、计划或工具链中启动后台任务,让 Claude 在后台继续工作。
+
+### 管理后台任务
+
+- 查看任务状态
+- 中止任务
+- 等待任务完成
+- 从结果中恢复上下文
+
+### 示例:并行开发
+
+```text
+任务 A:运行测试
+任务 B:生成文档
+任务 C:执行安全扫描
+```
+
+### 配置
+
+后台任务的超时、并发和通知行为都可以在设置中调整。
+
+<a id="scheduled-tasks"></a>
+## 定时任务
+
+Scheduled tasks 让 Claude 按计划重复执行某些提示词或任务。
+
+### `/loop` 命令
+
+```bash
+# 显式间隔
+/loop 10m Run tests and report failures
+
+# 自然语言
+/loop every day at 9am check release notes
+```
+
+### 一次性提醒
+
+```bash
+/schedule "remind me to review the PR in 30 minutes"
+```
+
+### 管理定时任务
+
+- 查看任务列表
+- 修改执行频率
+- 暂停或取消任务
+
+### 行为细节
+
+定时任务会遵循当前会话与权限配置,并按计划触发执行。
+
+### 云端定时任务
+
+部分场景可以在云端环境中运行调度任务。
+
+### 禁用定时任务
+
+如果你不希望自动触发,关闭相关设置即可。
+
+### 示例:监控部署
+
+```text
+每 5 分钟检查一次部署状态,直到 health check 通过。
+```
+
+<a id="permission-modes"></a>
+## 权限模式
+
+Permission modes 决定 Claude 可以直接执行哪些操作。
+
+### 可用模式
+
+- `default`
+- `acceptEdits`
+- `plan`
+- `auto`
+- `dontAsk`
+- `bypassPermissions`
+
+### 启用方式
+
+可以通过命令行、设置或会话中的快捷操作切换权限模式。
+
+### 示例
+
+#### Default Mode
+
+默认的平衡模式,必要时会询问权限。
+
+#### Plan Mode
+
+只做规划,不直接执行高风险改动。
+
+#### Accept Edits Mode
+
+更偏向自动接受编辑,适合受控环境。
+
+### 使用场景
+
+- 代码审查
+- 自动化重构
+- CI/CD
+- 高风险操作前的审批流程
+
+<a id="headless-mode"></a>
+## 无头模式
+
+Headless mode 指非交互式运行 Claude Code,常用于自动化和 CI/CD。
+
+### 什么是 Print Mode?
+
+Print mode 就是 `claude -p`:给一个任务,输出结果,然后退出。
+
+### 在 Print Mode 中运行
+
+```bash
+# 运行指定任务
+claude -p "run tests and summarize failures"
+
+# 处理管道内容
+cat logs.txt | claude -p "find the root cause"
+
+# CI/CD 集成
+claude -p "review this diff and return JSON"
+```
+
+### 其他示例
+
+```bash
+# 捕获输出
+claude -p "analyze this code" > report.txt
+
+# 结构化输出
+claude -p --output-format json "list files"
+
+# 标准输入
+echo "hello" | claude -p "translate to Chinese"
+```
+
+### CI/CD 示例
+
+```yaml
+# .github/workflows/code-review.yml
+```
+
+### Print Mode 配置
+
+- 限制自主回合数
+- 使用结构化 JSON 输出
+- 启用 schema 验证
+- 禁用会话持久化
+
+<a id="session-management"></a>
+## 会话管理
+
+会话管理用于在多个会话之间恢复、重命名、分叉和持续工作。
+
+### 常用命令
+
+- `/resume`
+- `/rename`
+- `/fork`
+- `claude -c`
+- `claude -r`
+
+### 恢复会话
+
+```bash
+# 继续最后一次对话
+claude -c
+
+# 恢复指定名称或 ID 的会话
+claude -r "feature-auth"
+```
+
+### 分叉会话
+
+```bash
+# 恢复并分叉,适合实验
+claude -r "feature-auth" --fork
+```
+
+### 会话持久化
+
+你可以选择保留、继续或重建会话上下文。
+
+<a id="interactive-features"></a>
+## 交互功能
+
+交互功能包括快捷键、多行输入、历史记录、Vim 模式和 Bash 模式等。
+
+### 快捷键
+
+常用快捷键用于切换模式、编辑输入、查看历史和控制输出。
+
+### 自定义快捷键
+
+你可以在设置中绑定自己的按键组合。
+
+### 可用上下文
+
+不同上下文会影响快捷键的可用性和行为。
+
+### Chord 支持
+
+支持组合按键触发复杂操作。
+
+### 保留键与冲突键
+
+某些按键会被系统或终端占用,需要避免冲突。
+
+### Tab 补全
+
+输入命令、参数或路径时会提供补全建议。
+
+### 命令历史
+
+Claude 会保留历史记录,方便你快速重用之前的输入。
+
+### 多行输入
+
+```text
+第一行
+第二行
+第三行
+```
+
+### 行内编辑
+
+支持在输入过程中编辑中间内容。
+
+### Vim 模式
+
+如果你熟悉 Vim,可以启用类似的编辑体验。
+
+### Bash 模式
+
+可在会话中直接进入更偏 shell 风格的操作方式。
+
+<a id="voice-dictation"></a>
+## 语音输入
+
+语音输入支持按住说话和多语言识别,适合快速记录想法或在不方便键盘输入时使用。
+
+### 如何启用
+
+在设置中打开语音输入即可。
+
+### 特性
+
+- 支持按住说话
+- 支持 20 种语言的语音识别
+- 适合快速口述任务
+
+### 配置
+
+可在 settings 中控制灵敏度、语言和输入行为。
+
+<a id="channels"></a>
+## 消息通道(Channels)
+
+消息通道允许 MCP servers 向正在运行的会话推送消息。
+
+### 订阅 channels
+
+```bash
+# 启动时订阅 channel 插件
+```
+
+### 支持的集成
+
+- Discord
+- Telegram
+- 其他 channel 型集成
+
+### 配置
+
+通过 MCP 配置或 settings 订阅相应 channel。
+
+### 工作方式
+
+外部系统可以把消息推送进 Claude 的当前会话里,让你在一个会话中接收通知或事件。
+
+<a id="chrome-integration"></a>
+## Chrome 集成
+
+Chrome 集成让 Claude 可以协助浏览器自动化和站点级操作。
+
+### 启用 Chrome 集成
+
+开启相关开关后,Claude 就可以与浏览器协作。
+
+### 能力
+
+- 浏览器自动化
+- 页面操作
+- 网站级交互
+
+### 站点级权限
+
+你可以对站点设置更细粒度的访问权限。
+
+### 工作方式
+
+Claude 通过浏览器连接与页面交互。
+
+### 已知限制
+
+- 某些站点会限制自动化
+- 复杂页面可能需要更多权限
+
+<a id="remote-control"></a>
+## 远程控制
+
+Remote Control 可以让你从 Claude.ai 或 Claude app 远程控制本地 Claude Code 会话。
+
+### 启动 Remote Control
+
+```bash
+# 使用默认会话名启动
+claude --remote-control
+
+# 使用自定义名称
+claude --remote-control --name my-session
+```
+
+### 连接到会话
+
+你可以在远程端连接到已经启动的本地会话,继续同一个上下文。
+
+### 安全性
+
+远程控制会牵涉到会话和权限,因此建议只在可信环境中使用。
+
+### Remote Control vs Claude Code on the web
+
+Remote Control 是控制本地会话;web 版则是在浏览器中直接运行。
+
+### 局限
+
+- 网络可用性依赖更高
+- 某些本地资源可能不可远程访问
+
+### 使用场景
+
+- 在手机上查看并接管会话
+- 远程继续长期任务
+
+<a id="web-sessions"></a>
+## 网页会话
+
+Web Sessions 允许你直接在浏览器里创建和恢复 Claude Code 会话。
+
+### 创建 Web Session
+
+```bash
+# 从 CLI 创建新的 web session
+claude --remote "implement API"
+```
+
+### 在本地恢复 Web Session
+
+```bash
+# 在本地终端恢复 web session
+claude --teleport
+```
+
+### 使用场景
+
+- 浏览器里快速开始任务
+- 在本地和网页之间切换
+- 远程继续工作
+
+<a id="desktop-app"></a>
+## 桌面应用
+
+桌面应用提供独立界面,适合视觉化 diff 审查和多会话管理。
+
+### 安装
+
+按照桌面应用的安装说明安装即可。
+
+### 从 CLI 接力
+
+你可以把 CLI 会话交给桌面应用继续处理。
+
+### 核心功能
+
+- 可视化 diff
+- 多会话
+- 更直观的审查体验
+
+### App 预览配置
+
+可以调整预览、布局和视觉呈现方式。
+
+### Connectors
+
+桌面应用可以连接到不同的工作环境。
+
+### 远程和 SSH 会话
+
+桌面应用也支持远程或 SSH 场景下的接力。
+
+### Desktop 中的权限模式
+
+Desktop 里同样可以使用不同的权限模式。
+
+### 企业功能
+
+企业部署下可使用更多受管和合规相关能力。
+
+<a id="task-list"></a>
+## 任务列表
+
+Task List 用于跨 context compaction 持久保存任务进度。
+
+### 切换任务列表
+
+在设置里打开或关闭任务列表显示。
+
+### 持久任务
+
+任务会保留,即使上下文被压缩,也能继续跟踪。
+
+### 命名任务目录
+
+你可以给任务分组或目录命名,方便管理。
+
+<a id="prompt-suggestions"></a>
+## 提示词建议
+
+Prompt suggestions 会根据当前上下文智能推荐下一步命令或提示词。
+
+### 工作方式
+
+系统会结合你的历史、当前任务和上下文给出建议。
+
+### 禁用建议
+
+如果你不想看到建议,可以在设置里关闭。
+
+<a id="git-worktrees"></a>
+## Git 工作树(Git Worktrees)
+
+Git worktrees 让你在隔离的目录里并行工作,非常适合实验和分支开发。
+
+### 从 worktree 启动
+
+```bash
+# 在隔离 worktree 中启动 Claude Code
+claude -w
+```
+
+### Worktree 位置
+
+你可以控制 worktree 的放置位置,保持主工作区整洁。
+
+### Monorepo 的 sparse checkout
+
+在大型 monorepo 中,可配合 sparse checkout 只加载需要的部分。
+
+### Worktree 工具和 Hooks
+
+worktree 场景下依然可以配合工具和 hooks 自动化流程。
+
+### 自动清理
+
+不需要的 worktree 可以自动清理。
+
+### 使用场景
+
+- 并行尝试多个方案
+- 隔离高风险重构
+- 保持主分支整洁
+
+<a id="sandboxing"></a>
+## 沙盒
+
+沙盒提供文件系统和网络层面的隔离,能显著降低自动化操作的风险。
+
+### 启用沙盒
+
+开启后,Claude 的很多操作都会在受控环境里执行。
+
+### 配置项
+
+你可以配置允许访问的目录、网络行为和例外列表。
+
+### 示例配置
+
+```json
+{
+ "sandbox": {
+ "enabled": true
+ }
+}
+```
+
+### 工作方式
+
+沙盒会限制 Claude 可触达的文件和网络边界。
+
+### 使用场景
+
+- 低风险自动化
+- 在不完全信任的输入上执行任务
+- 受控环境中的批处理
+
+<a id="managed-settings-enterprise"></a>
+## 企业受管设置
+
+企业可以通过受管设置统一分发 Claude Code 配置。
+
+### 部署方式
+
+- plist
+- Registry
+- 受管文件
+
+### 受管配置片段
+
+通过受管配置片段,可以给团队统一推送策略。
+
+### 可用的受管设置
+
+- 权限模式
+- 功能开关
+- MCP / hooks / 插件约束
+
+### macOS plist 示例
+
+```xml
+<!-- 示例略 -->
+```
+
+<a id="configuration-and-settings"></a>
+## 配置与设置
+
+### 配置文件位置
+
+- `~/.claude/settings.json`
+- `.claude/settings.json`
+- `.claude/settings.local.json`
+
+### 完整配置示例
+
+```json
+{
+ "permissions": {
+ "defaultMode": "plan"
+ },
+ "thinking": {
+ "enabled": true,
+ "effort": "high"
+ },
+ "autoCheckpoint": true
+}
+```
+
+### 环境变量
+
+#### 模型选择
+
+- `ANTHROPIC_API_KEY`
+- `CLAUDE_MODEL`
+
+#### API 配置
+
+- `ANTHROPIC_API_KEY`
+
+#### Thinking 配置
+
+- `CLAUDE_EFFORT`
+
+#### 功能开关
+
+- `CLAUDE_ENABLE_AUTO_MODE`
+
+#### MCP 配置
+
+- `CLAUDE_MCP_CONFIG`
+
+#### 任务管理
+
+- `CLAUDE_TASK_LIST`
+
+#### Agent team(实验性)
+
+- `CLAUDE_TEAM_MODE`
+
+#### Subagent 和 plugin 配置
+
+- `CLAUDE_PLUGIN_DATA`
+
+#### 子进程和流式处理
+
+- `CLAUDE_OUTPUT_FORMAT`
+
+### 配置管理命令
+
+你可以用命令查看或更新当前配置,并把它们落到 settings 中。
+
+### 每个项目的配置
+
+推荐把项目专用设置放进项目内的 `.claude/settings.json`,这样能跟代码一起版本化。
+
+<a id="best-practices"></a>
+## 最佳实践
+
+### Planning Mode
+
+- 复杂任务先规划,再实现
+- 计划要可审阅
+
+### Extended Thinking
+
+- 留给复杂问题
+- 不要在简单任务上过度使用
+
+### Background Tasks
+
+- 用于长时间、可并行的任务
+- 记得设置超时和可见性
+
+### Permissions
+
+- 默认最小权限
+- 只在必要时放宽
+
+### Sessions
+
+- 为重要会话命名
+- 必要时分叉,而不是硬改
+
+<a id="additional-resources"></a>
+## 更多资源
+
+- [根目录中文指南](../README.md)
+- [Slash Commands 中文参考](../01-slash-commands/README.md)
+- [Checkpoints 中文指南](../08-checkpoints/README.md)
+- [Plugins 中文指南](../07-plugins/README.md)
+- [CLI 中文参考](../10-cli/README.md)
diff --git a/zh/09-advanced-features/planning-mode-examples.md b/zh/09-advanced-features/planning-mode-examples.md
new file mode 100644
index 0000000..80ffe2e
--- /dev/null
+++ b/zh/09-advanced-features/planning-mode-examples.md
@@ -0,0 +1,533 @@
+# 计划模式示例
+
+以下是 Claude Code 中有效使用计划模式的真实示例。
+
+## 示例 1:构建 REST API
+
+### 不使用计划模式
+
+```
+用户:给博客做一个 REST API
+
+Claude:我来创建这个 API……
+[立刻开始编码,可能漏掉需求]
+```
+
+### 使用计划模式
+
+```
+用户:/plan 给博客做一个 REST API
+
+Claude:我来为这个博客 API 制定一份完整计划。
+
+## 博客 REST API 实现计划
+
+### 阶段 1:项目初始化(15 分钟)
+1. 初始化带 Express 的 Node.js 项目
+2. 配置 TypeScript
+3. 安装依赖(express、pg、jwt、joi)
+4. 配置环境变量
+5. 搭建项目结构
+
+### 阶段 2:数据库层(30 分钟)
+6. 设计数据库 schema
+ - users 表(id、email、password_hash、created_at)
+ - posts 表(id、user_id、title、content、published、created_at、updated_at)
+ - comments 表(id、post_id、user_id、content、created_at)
+7. 创建迁移文件
+8. 搭建数据库连接池
+9. 实现数据库模型
+
+### 阶段 3:认证(45 分钟)
+10. 实现用户注册接口
+11. 实现带 JWT 的登录接口
+12. 创建认证中间件
+13. 使用 bcrypt 添加密码哈希
+14. 实现 token 刷新逻辑
+
+### 阶段 4:Posts API(40 分钟)
+15. GET /api/posts - 获取所有已发布文章(支持分页)
+16. GET /api/posts/:id - 获取单篇文章
+17. POST /api/posts - 创建新文章(需要认证)
+18. PUT /api/posts/:id - 更新文章(需要认证,检查所有权)
+19. DELETE /api/posts/:id - 删除文章(需要认证,检查所有权)
+20. GET /api/users/:id/posts - 获取某个用户的文章
+
+### 阶段 5:Comments API(30 分钟)
+21. GET /api/posts/:id/comments - 获取文章评论
+22. POST /api/posts/:id/comments - 添加评论(需要认证)
+23. DELETE /api/comments/:id - 删除评论(需要认证,检查所有权)
+
+### 阶段 6:校验与错误处理(30 分钟)
+24. 使用 Joi 添加请求校验
+25. 实现全局错误处理器
+26. 添加输入清洗
+27. 实现速率限制
+
+### 阶段 7:测试(60 分钟)
+28. 为模型编写单元测试
+29. 为认证接口编写集成测试
+30. 为文章接口编写集成测试
+31. 为评论接口编写集成测试
+32. 达到 80%+ 的代码覆盖率
+
+### 阶段 8:文档与部署(30 分钟)
+33. 使用 Swagger 生成 API 文档
+34. 创建包含安装说明的 README
+35. 添加 Docker 配置
+36. 搭建 CI/CD 流水线
+
+**预估时间**:4.5 小时
+**需要创建的文件**:约 25 个
+**关键技术**:Express、PostgreSQL、JWT、TypeScript
+
+**API 端点概览**:
+- 认证:2 个端点
+- 文章:6 个端点
+- 评论:3 个端点
+- 总计:11 个端点
+
+准备继续吗?(yes/no/modify)
+
+用户:yes
+
+Claude:开始阶段 1:项目初始化……
+[按阶段系统性实现]
+```
+
+## 示例 2:数据库迁移
+
+### 使用计划模式
+
+```
+用户:/plan 将数据库从 MongoDB 迁移到 PostgreSQL
+
+Claude:这是一次复杂迁移。我来制定详细计划。
+
+## MongoDB 到 PostgreSQL 的迁移计划
+
+### 阶段 1:分析与准备(第 1 天)
+1. 分析当前 MongoDB schema
+2. 识别数据关系和约束
+3. 记录当前数据量和增长速率
+4. 设计对应的 PostgreSQL schema
+5. 规划数据类型映射
+6. 识别潜在迁移挑战
+
+### 阶段 2:PostgreSQL 准备(第 1 天)
+7. 搭建 PostgreSQL 数据库
+8. 创建包含表、索引和约束的 schema
+9. 配置连接池
+10. 制定备份策略
+
+### 阶段 3:双写实现(第 2-3 天)
+11. 创建数据库抽象层
+12. 实现同时向两个数据库写入
+13. 添加数据一致性检查
+14. 在预发布环境部署双写
+15. 监控问题
+
+### 阶段 4:数据迁移(第 4 天)
+16. 为 MongoDB 创建数据导出脚本
+17. 为 PostgreSQL 创建数据导入脚本
+18. 实现数据转换逻辑
+19. 在生产数据副本上执行初次迁移
+20. 验证迁移后数据完整性
+
+### 阶段 5:渐进切换(第 5-7 天)
+21. 在生产环境开启双写
+22. 分批迁移历史数据
+23. 持续验证数据一致性
+24. 监控两个数据库
+25. 修复任何数据同步问题
+
+### 阶段 6:PostgreSQL 作为主库(第 8 天)
+26. 将读操作切换到 PostgreSQL
+27. 监控查询性能
+28. 优化慢查询
+29. 继续保留双写作为安全措施
+
+### 阶段 7:MongoDB 退役(第 9-10 天)
+30. 停止向 MongoDB 写入
+31. 保留 MongoDB 作为两周备份
+32. 从代码中移除 MongoDB 依赖
+33. 归档 MongoDB 数据
+34. 下线 MongoDB 实例
+
+**预估时间**:10 天
+**风险等级**:高
+**回滚策略**:保持 MongoDB 运行并开启双写
+**成功标准**:
+- 零数据丢失
+- 性能回退小于 5%
+- 所有测试通过
+
+**关键风险**:
+1. 迁移过程中的数据不一致
+2. 查询性能下降
+3. 应用停机
+4. 数据丢失
+
+**缓解措施**:
+- 采用双写模式保障安全
+- 渐进式切换
+- 持续监控
+- 快速回滚能力
+
+是否按此计划继续?(yes/no/modify)
+
+用户:modify - 我们给每个阶段都加上回滚方案
+
+Claude:我已经为每个阶段补充了回滚流程……
+```
+
+## 示例 3:前端重构
+
+```
+用户:/plan 把我们的 React 应用从 class 组件重构为 hooks
+
+Claude:我来制定一个系统化的重构计划。
+
+## React Class 到 Hooks 迁移计划
+
+### 阶段 1:准备与分析(2 小时)
+1. 审查所有 class 组件(查找所有 .jsx/.tsx 文件)
+2. 按复杂度分类:
+ - 简单型(仅 state):约 15 个组件
+ - 中等型(生命周期方法):约 23 个组件
+ - 复杂型(多个生命周期、refs):约 8 个组件
+3. 识别需要更新的第三方库
+4. 创建组件依赖图
+5. 规划迁移顺序(先叶子节点)
+
+### 阶段 2:环境与工具(1 小时)
+6. 将 React 升级到 v18+
+7. 为 hooks 配置 ESLint 规则
+8. 创建转换模板
+9. 配置自动化测试
+10. 在开始前创建一个检查点
+
+### 阶段 3:迁移简单组件(4 小时)
+11. 转换简单的有状态组件(15 个)
+12. 用 `useState` 替换 `this.state`
+13. 用状态 setter 替换 `this.setState`
+14. 每个组件转换后都进行测试
+15. 更新测试
+
+### 阶段 4:迁移中等复杂组件(8 小时)
+16. 转换带生命周期方法的组件(23 个)
+17. 用 `useEffect` 替换 `componentDidMount`
+18. 用 `useEffect` 替换 `componentDidUpdate`
+19. 用 `useEffect` 清理函数替换 `componentWillUnmount`
+20. 做充分测试
+
+### 阶段 5:迁移复杂组件(12 小时)
+21. 转换复杂组件(8 个)
+22. 用 `useRef` 替换 refs
+23. 为共享逻辑提取自定义 hooks
+24. 处理边缘情况(多个 `useEffect`)
+25. 做深入测试
+
+### 阶段 6:提取共享逻辑(6 小时)
+26. 识别组件之间重复的逻辑
+27. 创建自定义 hooks:
+ - `useAuth`
+ - `useFetch`
+ - `useLocalStorage`
+ - `useDebounce`
+28. 将组件重构为使用自定义 hooks
+29. 独立测试自定义 hooks
+
+### 阶段 7:性能优化(4 小时)
+30. 在需要的地方添加 `React.memo`
+31. 使用 `useCallback` 优化
+32. 使用 `useMemo` 优化
+33. 分析并修复性能回退
+
+### 阶段 8:收尾与文档(2 小时)
+34. 移除未使用的 class 组件工具
+35. 更新文档
+36. 更新编码规范
+37. 为团队编写迁移指南
+
+**预估时间**:5 天(39 小时)
+**需要修改的文件**:46 个组件
+**风险等级**:中
+
+**迁移顺序**:
+1. 叶子组件(无依赖)
+2. 中层组件
+3. 顶层容器组件
+4. `App.jsx`(最后)
+
+**测试策略**:
+- 每个组件的单元测试
+- 用户流程的集成测试
+- 视觉回归测试
+- 性能基准测试
+
+**成功指标**:
+- 所有测试通过
+- 没有视觉回归
+- 性能保持或提升
+- 打包体积没有明显增加
+
+继续吗?(yes/no/modify)
+```
+
+## 示例 4:安全实现
+
+```
+用户:/plan 为我们的 Web 应用实现完整安全方案
+
+Claude:我来制定一份全面的安全实施计划。
+
+## Web 应用安全实施计划
+
+### 阶段 1:安全审计(第 1 天)
+1. 运行自动化安全扫描器(npm audit、Snyk)
+2. 检查依赖中的漏洞
+3. 核对 OWASP Top 10 合规性
+4. 审查认证流程
+5. 审查数据处理方式
+6. 记录当前的安全缺口
+
+### 阶段 2:认证加固(第 2-3 天)
+7. 实现强密码要求
+8. 添加密码强度检测器
+9. 对登录接口实施限流
+10. 在多次失败后锁定账户
+11. 实现 2FA(TOTP)
+12. 改进会话管理
+13. 实现安全的密码重置流程
+
+### 阶段 3:授权与访问控制(第 3-4 天)
+14. 实现 RBAC(基于角色的访问控制)
+15. 为所有端点添加权限检查
+16. 实现最小权限原则
+17. 为敏感操作添加审计日志
+18. 实现资源级权限
+
+### 阶段 4:数据保护(第 4-5 天)
+19. 对敏感字段实施静态加密
+20. 确保所有通信都使用 TLS/SSL
+21. 实现安全的会话存储
+22. 在日志中对 PII 数据做脱敏
+23. 实现数据保留策略
+24. 添加安全的文件上传处理
+
+### 阶段 5:输入验证与清洗(第 5-6 天)
+25. 为所有端点实现输入校验
+26. 添加 XSS 防护(Content Security Policy)
+27. 实现 SQL 注入防护(参数化查询)
+28. 添加 CSRF 防护
+29. 实现请求大小限制
+30. 添加文件上传类型校验
+
+### 阶段 6:安全头与配置(第 6 天)
+31. 添加安全响应头:
+ - Strict-Transport-Security
+ - X-Content-Type-Options
+ - X-Frame-Options
+ - X-XSS-Protection
+ - Content-Security-Policy
+32. 正确配置 CORS
+33. 禁用不必要的 HTTP 方法
+34. 移除服务器版本头
+
+### 阶段 7:监控与日志(第 7 天)
+35. 实现安全事件日志
+36. 添加异常检测
+37. 搭建入侵检测
+38. 实现实时告警
+39. 创建安全仪表盘
+
+### 阶段 8:测试与文档(第 8-9 天)
+40. 执行渗透测试
+41. 运行安全扫描器
+42. 测试所有安全功能
+43. 编写安全文档
+44. 培训团队的安全实践
+45. 编写事件响应计划
+
+### 阶段 9:合规与政策(第 10 天)
+46. 检查 GDPR 合规性
+47. 创建隐私政策
+48. 实现数据主体权利支持
+49. 添加 cookie 同意机制
+50. 编写安全政策文档
+
+**预估时间**:10 天
+**风险等级**:严重
+**优先级**:高
+
+**安全改进摘要**:
+- 认证:7 项增强
+- 授权:5 项增强
+- 数据保护:6 项增强
+- 输入校验:6 项增强
+- 基础设施:9 项增强
+- 监控:5 项增强
+
+**合规性**:OWASP Top 10、GDPR
+
+**成功标准**:
+- 零严重漏洞
+- 所有 OWASP Top 10 风险都得到缓解
+- 安全评分高于 90/100
+- 所有渗透测试问题都已解决
+
+继续吗?(yes/no/modify)
+```
+
+## 示例 5:性能优化
+
+```
+用户:/plan 优化我们这个很慢的电商网站
+
+Claude:我来制定一份完整的性能优化计划。
+
+## 电商网站性能优化计划
+
+### 阶段 1:性能审计(4 小时)
+1. 运行 Lighthouse 审计
+2. 分析 Chrome DevTools 性能剖析结果
+3. 测量 Core Web Vitals:
+ - LCP(Largest Contentful Paint)
+ - FID(First Input Delay)
+ - CLS(Cumulative Layout Shift)
+4. 找出性能瓶颈
+5. 创建基线性能指标
+
+**当前指标**:
+- LCP:4.2s(目标:<2.5s)
+- FID:280ms(目标:<100ms)
+- CLS:0.25(目标:<0.1)
+- 页面加载:8.3s(目标:<3s)
+
+### 阶段 2:图片优化(6 小时)
+6. 将图片转换为 WebP 格式
+7. 实现响应式图片
+8. 为图片添加懒加载
+9. 优化图片大小(压缩)
+10. 为图片接入 CDN
+11. 添加图片占位符
+
+**预期影响**:加载时间减少 40%
+
+### 阶段 3:代码拆分与懒加载(8 小时)
+12. 实现基于路由的代码拆分
+13. 懒加载非关键组件
+14. 拆分第三方依赖包
+15. 优化 chunk 大小
+16. 实现动态导入
+17. 为关键资源添加预加载
+
+**预期影响**:初始 bundle 体积减少 30%
+
+### 阶段 4:缓存策略(6 小时)
+18. 实现浏览器缓存(Cache-Control)
+19. 为离线支持添加 service worker
+20. 实现 API 响应缓存
+21. 为数据库查询添加 Redis 缓存
+22. 实现 stale-while-revalidate
+23. 配置 CDN 缓存
+
+**预期影响**:API 响应时间减少 50%
+
+### 阶段 5:数据库优化(8 小时)
+24. 添加数据库索引
+25. 优化慢查询(>100ms)
+26. 实现查询结果缓存
+27. 添加连接池
+28. 在合适地方做反规范化
+29. 实现数据库只读副本
+
+**预期影响**:数据库查询时间减少 60%
+
+### 阶段 6:前端优化(10 小时)
+30. 最小化并压缩 JavaScript
+31. 最小化并压缩 CSS
+32. 移除未使用的 CSS(PurgeCSS)
+33. 实现关键 CSS
+34. 延迟加载非关键 JavaScript
+35. 减少 DOM 规模
+36. 优化 React 渲染(`memo`、`useMemo`)
+37. 为长列表实现虚拟滚动
+
+**预期影响**:JavaScript 执行时间减少 35%
+
+### 阶段 7:网络优化(4 小时)
+38. 启用 HTTP/2
+39. 实现资源提示(preconnect、prefetch)
+40. 减少 HTTP 请求数量
+41. 启用 Brotli 压缩
+42. 优化第三方脚本
+
+**预期影响**:网络耗时减少 25%
+
+### 阶段 8:监控与测试(4 小时)
+43. 搭建性能监控(Datadog/New Relic)
+44. 添加真实用户监控(RUM)
+45. 制定性能预算
+46. 搭建自动化 Lighthouse CI
+47. 在真实设备上测试
+
+**预估时间**:50 小时(2 周)
+
+**目标指标**(90 分位):
+- LCP:<2.0s(从 4.2s 降低)✅
+- FID:<50ms(从 280ms 降低)✅
+- CLS:<0.05(从 0.25 降低)✅
+- 页面加载:<2.5s(从 8.3s 降低)✅
+
+**预期收入影响**:
+- 每快 100ms,转化率提升 1%
+- 目标:缩短 5.8s,约带来 58% 的转化率提升
+- 预估额外收入:显著
+
+**优先级顺序**:
+1. 图片优化(快速收益)
+2. 代码拆分(高影响)
+3. 缓存(高影响)
+4. 数据库优化(关键)
+5. 前端优化(打磨)
+
+是否按此计划继续?(yes/no/modify)
+```
+
+## 关键要点
+
+### 计划模式的优势
+
+1. **清晰**:开始前就有明确路线图
+2. **可估算**:能给出时间和工作量预估
+3. **风险评估**:能尽早发现潜在问题
+4. **优先级排序**:任务按合理顺序推进
+5. **可审批**:执行前先审阅并确认
+6. **可调整**:根据反馈及时修改计划
+
+### 什么时候使用计划模式
+
+✅ **建议始终使用于**:
+- 多日项目
+- 团队协作
+- 关键系统变更
+- 学习新概念
+- 复杂重构
+
+❌ **不建议使用于**:
+- 修 bug
+- 小改动
+- 简单查询
+- 快速实验
+
+### 最佳实践
+
+1. **审批前仔细审查** 计划
+2. **发现问题就修改** 计划
+3. **把复杂任务拆细**
+4. **给出现实的时间估算**
+5. **包含回滚策略**
+6. **写明成功标准**
+7. **为每个阶段安排测试**
diff --git a/zh/10-cli/README.md b/zh/10-cli/README.md
new file mode 100644
index 0000000..5793c09
--- /dev/null
+++ b/zh/10-cli/README.md
@@ -0,0 +1,640 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# CLI 参考
+
+## 概览
+
+Claude Code 的 CLI(命令行接口)是与 Claude Code 交互的主要方式。它提供了强大的参数和命令,用于执行查询、管理会话、配置模型,并把 Claude 集成进你的开发工作流。
+
+## 架构
+
+```mermaid
+graph TD
+ A["用户终端"] -->|"claude [options] [query]"| B["Claude Code CLI"]
+ B -->|Interactive| C["REPL 模式"]
+ B -->|"--print"| D["打印模式(SDK)"]
+ B -->|"--resume"| E["恢复会话"]
+ C -->|Conversation| F["Claude API"]
+ D -->|Single Query| F
+ E -->|Load Context| F
+ F -->|Response| G["输出"]
+ G -->|text/json/stream-json| H["终端 / 管道"]
+```
+
+## CLI 命令
+
+| 命令 | 说明 | 示例 |
+|---------|-------------|---------|
+| `claude` | 启动交互式 REPL | `claude` |
+| `claude "query"` | 带初始提示启动 REPL | `claude "解释这个项目"` |
+| `claude -p "query"` | 打印模式,查询后退出 | `claude -p "解释这个函数"` |
+| `cat file \| claude -p "query"` | 处理通过管道传入的内容 | `cat logs.txt \| claude -p "解释这些日志"` |
+| `claude -c` | 继续最近一次会话 | `claude -c` |
+| `claude -c -p "query"` | 在打印模式下继续会话 | `claude -c -p "检查类型错误"` |
+| `claude -r "<session>" "query"` | 通过 ID 或名称恢复会话 | `claude -r "auth-refactor" "完成这个 PR"` |
+| `claude update` | 更新到最新版本 | `claude update` |
+| `claude mcp` | 配置 MCP servers | 见 [MCP 文档](../05-mcp/README.md) |
+| `claude mcp serve` | 将 Claude Code 作为 MCP server 运行 | `claude mcp serve` |
+| `claude agents` | 列出所有已配置的 subagents | `claude agents` |
+| `claude auto-mode defaults` | 以 JSON 打印 auto mode 默认规则 | `claude auto-mode defaults` |
+| `claude remote-control` | 启动远程控制服务 | `claude remote-control` |
+| `claude plugin` | 管理插件(安装、启用、禁用) | `claude plugin install my-plugin` |
+| `claude auth login` | 登录(支持 `--email`、`--sso`) | `claude auth login --email [email protected]` |
+| `claude auth logout` | 注销当前账号 | `claude auth logout` |
+| `claude auth status` | 检查登录状态(已登录返回 0,否则返回 1) | `claude auth status` |
+
+## 核心标志
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `-p, --print` | 不进入交互式模式,直接输出结果 | `claude -p "query"` |
+| `-c, --continue` | 加载最近一次会话 | `claude --continue` |
+| `-r, --resume` | 按 ID 或名称恢复指定会话 | `claude --resume auth-refactor` |
+| `-v, --version` | 输出版本号 | `claude -v` |
+| `-w, --worktree` | 在隔离的 git worktree 中启动 | `claude -w` |
+| `-n, --name` | 设置会话显示名称 | `claude -n "auth-refactor"` |
+| `--from-pr <number>` | 恢复与 GitHub PR 关联的会话 | `claude --from-pr 42` |
+| `--remote "task"` | 在 claude.ai 上创建 web session | `claude --remote "implement API"` |
+| `--remote-control, --rc` | 使用 Remote Control 进入交互式会话 | `claude --rc` |
+| `--teleport` | 将 web session 恢复到本地 | `claude --teleport` |
+| `--teammate-mode` | agent team 显示模式 | `claude --teammate-mode tmux` |
+| `--bare` | 极简模式,跳过 hooks、skills、plugins、MCP、自动记忆和 `CLAUDE.md` | `claude --bare` |
+| `--enable-auto-mode` | 解锁 auto permission mode | `claude --enable-auto-mode` |
+| `--channels` | 订阅 MCP channel 插件 | `claude --channels discord,telegram` |
+| `--chrome` / `--no-chrome` | 启用 / 禁用 Chrome 浏览器集成 | `claude --chrome` |
+| `--effort` | 设置推理强度 | `claude --effort high` |
+| `--init` / `--init-only` | 运行初始化 hooks | `claude --init` |
+| `--maintenance` | 运行维护 hooks 后退出 | `claude --maintenance` |
+| `--disable-slash-commands` | 禁用所有 skills 和 slash commands | `claude --disable-slash-commands` |
+| `--no-session-persistence` | 禁用会话保存(打印模式) | `claude -p --no-session-persistence "query"` |
+
+### 交互模式 vs 打印模式
+
+```mermaid
+graph LR
+ A["claude"] -->|默认| B["交互式 REPL"]
+ A -->|"-p 参数"| C["打印模式"]
+ B -->|特性| D["多轮对话<br>Tab 补全<br>历史记录<br>Slash commands"]
+ C -->|特性| E["单次查询<br>可脚本化<br>可管道化<br>JSON 输出"]
+```
+
+**交互模式**(默认):
+```bash
+# 启动交互式会话
+claude
+
+# 带初始提示启动
+claude "解释这个认证流程"
+```
+
+**打印模式**(非交互式):
+```bash
+# 单次查询后退出
+claude -p "这个函数做什么?"
+
+# 处理文件内容
+cat error.log | claude -p "解释这个错误"
+
+# 与其他工具串联
+claude -p "列出待办事项" | grep "URGENT"
+```
+
+## 模型与配置
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--model` | 设置模型(sonnet、opus、haiku,或完整模型名) | `claude --model opus` |
+| `--fallback-model` | 当前模型负载过高时自动切换的后备模型 | `claude -p --fallback-model sonnet "query"` |
+| `--agent` | 为当前会话指定 agent | `claude --agent my-custom-agent` |
+| `--agents` | 通过 JSON 定义自定义 subagents | 见 [Agents Configuration](#subagents-配置) |
+| `--effort` | 设置推理级别(low、medium、high、max) | `claude --effort high` |
+
+### 模型选择示例
+
+```bash
+# 复杂任务使用 Opus 4.6
+claude --model opus "设计一个缓存策略"
+
+# 快速任务使用 Haiku 4.5
+claude --model haiku -p "格式化这个 JSON"
+
+# 使用完整模型名
+claude --model claude-sonnet-4-6-20250929 "审查这段代码"
+
+# 带后备模型以提升稳定性
+claude -p --model opus --fallback-model sonnet "分析架构"
+
+# 使用 opusplan(Opus 负责规划,Sonnet 负责执行)
+claude --model opusplan "设计并实现缓存层"
+```
+
+## 系统提示词自定义
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--system-prompt` | 替换整段默认系统提示词 | `claude --system-prompt "You are a Python expert"` |
+| `--system-prompt-file` | 从文件加载提示词(仅打印模式) | `claude -p --system-prompt-file ./prompt.txt "query"` |
+| `--append-system-prompt` | 在默认提示词后追加内容 | `claude --append-system-prompt "Always use TypeScript"` |
+
+### 系统提示词示例
+
+```bash
+# 完整自定义人格
+claude --system-prompt "你是一名资深安全工程师,重点关注漏洞。"
+
+# 追加特定指令
+claude --append-system-prompt "始终在代码示例中包含单元测试"
+
+# 从文件加载复杂提示词
+claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py"
+```
+
+### 系统提示词参数对比
+
+| 参数 | 行为 | 交互模式 | 打印模式 |
+|------|----------|-------------|-------|
+| `--system-prompt` | 替换整个默认系统提示词 | ✅ | ✅ |
+| `--system-prompt-file` | 用文件中的提示词替换 | ❌ | ✅ |
+| `--append-system-prompt` | 追加到默认系统提示词后 | ✅ | ✅ |
+
+**仅在打印模式中使用 `--system-prompt-file`。交互模式请使用 `--system-prompt` 或 `--append-system-prompt`。**
+
+## 工具与权限管理
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--tools` | 限制可用的内置工具 | `claude -p --tools "Bash,Edit,Read" "query"` |
+| `--allowedTools` | 无需提示即可执行的工具 | `"Bash(git log:*)" "Read"` |
+| `--disallowedTools` | 从上下文中移除的工具 | `"Bash(rm:*)" "Edit"` |
+| `--dangerously-skip-permissions` | 跳过所有权限提示 | `claude --dangerously-skip-permissions` |
+| `--permission-mode` | 以指定权限模式启动 | `claude --permission-mode auto` |
+| `--permission-prompt-tool` | 用于权限处理的 MCP tool | `claude -p --permission-prompt-tool mcp_auth "query"` |
+| `--enable-auto-mode` | 解锁 auto permission mode | `claude --enable-auto-mode` |
+
+### 权限示例
+
+```bash
+# 代码审查只读模式
+claude --permission-mode plan "审查这个代码库"
+
+# 只允许安全工具
+claude --tools "Read,Grep,Glob" -p "找出所有 TODO 注释"
+
+# 允许特定 git 命令无需提示
+claude --allowedTools "Bash(git status:*)" "Bash(git log:*)"
+
+# 阻止危险操作
+claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"
+```
+
+## 输出与格式
+
+| 参数 | 说明 | 选项 | 示例 |
+|------|-------------|---------|---------|
+| `--output-format` | 指定输出格式(打印模式) | `text`、`json`、`stream-json` | `claude -p --output-format json "query"` |
+| `--input-format` | 指定输入格式(打印模式) | `text`、`stream-json` | `claude -p --input-format stream-json` |
+| `--verbose` | 启用详细日志 | | `claude --verbose` |
+| `--include-partial-messages` | 包含流式事件 | 需要 `stream-json` | `claude -p --output-format stream-json --include-partial-messages "query"` |
+| `--json-schema` | 获取符合 schema 的 JSON 输出 | | `claude -p --json-schema '{"type":"object"}' "query"` |
+| `--max-budget-usd` | 打印模式最大花费 | | `claude -p --max-budget-usd 5.00 "query"` |
+
+### 输出格式示例
+
+```bash
+# 纯文本(默认)
+claude -p "解释这段代码"
+
+# 供程序使用的 JSON
+claude -p --output-format json "列出 main.py 中的所有函数"
+
+# 用于实时处理的流式 JSON
+claude -p --output-format stream-json "生成一份长报告"
+
+# 使用 schema 验证的结构化输出
+claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \
+ "找出这段代码中的 bug,并以 JSON 返回"
+```
+
+## 工作区与目录
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--working-directory` | 设置工作目录 | `claude --working-directory /path/to/project` |
+| `--add-dir` | 追加额外工作目录 | `claude --add-dir /path/to/other/project` |
+
+### 多目录示例
+
+```bash
+# 在多个项目目录中协作
+claude --working-directory ~/projects/app --add-dir ~/projects/shared
+
+# 加载自定义设置
+claude --working-directory ./backend --add-dir ./frontend
+```
+
+## MCP 配置
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--mcp-config` | 从文件加载 MCP 配置 | `claude --mcp-config ./mcp.json` |
+| `--mcp` | 启用 / 配置 MCP 服务 | `claude --mcp github` |
+| `--mcp-list` | 列出可用 MCP 配置 | `claude --mcp-list` |
+
+### MCP 示例
+
+```bash
+# 加载 GitHub MCP server
+claude --mcp-config ./configs/github-mcp.json
+
+# 严格模式,只允许指定的 server
+claude --mcp-config ./configs/strict-mcp.json --mcp github
+```
+
+## 会话管理
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--session` | 指定会话名称 | `claude --session feature-auth` |
+| `--new-session` | 强制开启新会话 | `claude --new-session` |
+| `--resume-last` | 恢复最近一次会话 | `claude --resume-last` |
+| `--fork-session` | 从当前会话分叉 | `claude --fork-session` |
+
+### 会话示例
+
+```bash
+# 继续上一次对话
+claude --continue
+
+# 恢复命名会话
+claude --resume feature-auth
+
+# 为实验分叉会话
+claude --fork-session
+
+# 指定会话 ID
+claude --resume 123456789
+```
+
+### 会话分叉
+
+```bash
+# 分叉会话尝试不同方案
+claude --fork-session "尝试另一种实现"
+
+# 带自定义消息分叉
+claude --fork-session --session "experiment-a"
+```
+
+## 高级特性
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--disable-auto-checkpoints` | 禁用自动 checkpoint | `claude --disable-auto-checkpoints` |
+| `--enable-auto-checkpoints` | 启用自动 checkpoint | `claude --enable-auto-checkpoints` |
+| `--interactive` | 强制交互模式 | `claude --interactive` |
+| `--dry-run` | 仅模拟执行 | `claude --dry-run "review code"` |
+| `--unsafe` | 允许更多自动化操作 | `claude --unsafe` |
+
+### 高级示例
+
+```bash
+# 限制自主操作
+claude --permission-mode plan --model opus "设计并实现认证系统"
+
+# 调试 API 调用
+claude --verbose -p "diagnose this issue"
+
+# 启用 IDE 集成
+claude --ide "review this diff"
+```
+
+<a id="agents-configuration"></a>
+## Subagents 配置
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--agents` | 通过 JSON 定义自定义 subagents | `claude --agents ./agents.json` |
+| `--agent` | 指定当前会话使用的 agent | `claude --agent reviewer` |
+
+### Subagents JSON 格式
+
+```json
+{
+ "agent-name": {
+ "description": "Required: when to invoke this agent",
+ "prompt": "Required: system prompt for the agent",
+ "tools": ["Optional", "array", "of", "tools"],
+ "model": "optional: sonnet|opus|haiku"
+ }
+}
+```
+
+**必填字段:**
+- `description` - 何时使用这个 agent 的自然语言说明
+- `prompt` - 定义 agent 角色和行为的系统提示词
+
+**可选字段:**
+- `tools` - 可用工具数组(如果省略则继承全部工具)
+ - 格式:`["Read", "Grep", "Glob", "Bash"]`
+- `model` - 使用的模型:`sonnet`、`opus` 或 `haiku`
+
+### 完整 Agents 示例
+
+```json
+{
+ "code-reviewer": {
+ "description": "Expert code reviewer. Use proactively after code changes.",
+ "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
+ "tools": ["Read", "Grep", "Glob", "Bash"],
+ "model": "sonnet"
+ },
+ "debugger": {
+ "description": "Debugging specialist for errors and test failures.",
+ "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.",
+ "tools": ["Read", "Edit", "Bash", "Grep"],
+ "model": "opus"
+ },
+ "documenter": {
+ "description": "Documentation specialist for generating guides.",
+ "prompt": "You are a technical writer. Create clear, comprehensive documentation.",
+ "tools": ["Read", "Write"],
+ "model": "haiku"
+ }
+}
+```
+
+### Agents 命令示例
+
+```bash
+# 直接定义自定义 agent
+claude --agents '{
+ "security-auditor": {
+ "description": "Security specialist for vulnerability analysis",
+ "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.",
+ "tools": ["Read", "Grep", "Glob"],
+ "model": "opus"
+ }
+}' "audit this codebase for security issues"
+
+# 从文件加载 agents
+claude --agents ./configs/agents.json
+
+# 与其他参数组合
+claude --agents ./configs/agents.json --model opus
+```
+
+### Subagent 优先级
+
+当同时存在多种 agent 定义时,加载优先级如下:
+1. **CLI 定义**(`--agents` 参数)- 当前会话专用
+2. **用户级**(`~/.claude/agents/`)- 所有项目可用
+3. **项目级**(`.claude/agents/`)- 当前项目可用
+
+命令行定义的 agents 会覆盖本次会话里的用户级和项目级 agents。
+
+## 高价值使用场景
+
+### 1. CI/CD 集成
+
+```bash
+claude -p --output-format json "run tests and summarize failures"
+```
+
+### 2. 管道式脚本处理
+
+```bash
+# 分析错误日志
+cat error.log | claude -p "解释这些错误并给出修复建议"
+
+# 查找访问日志中的模式
+cat access.log | claude -p "找出异常流量"
+
+# 分析 git 历史
+git log --oneline -20 | claude -p "总结最近的开发方向"
+
+# 审查某个文件
+claude -p "review src/app.ts and suggest improvements"
+
+# 生成文档
+claude -p "根据 README 生成 API 文档"
+
+# 查找 TODO 并排优先级
+rg -n "TODO|FIXME" . | claude -p "按优先级分类这些待办"
+```
+
+### 3. 多会话工作流
+
+```bash
+# 启动特性分支会话
+claude --session feature-auth
+
+# 之后继续该会话
+claude --resume feature-auth
+
+# 分叉尝试另一种方案
+claude --fork-session
+
+# 在不同特性会话之间切换
+claude --resume feature-auth
+claude --resume feature-payment
+```
+
+### 4. 自定义 agent 配置
+
+```bash
+# 将 agents 配置保存到文件
+cat > agents.json <<'JSON'
+{
+ "agents": [
+ {"name":"reviewer","description":"review code"},
+ {"name":"tester","description":"write tests"}
+ ]
+}
+JSON
+
+# 在会话中使用这些 agent
+claude --agents ./agents.json --agent reviewer
+```
+
+### 5. 批处理
+
+```bash
+# 处理多个文件
+find src -name "*.ts" | xargs -I{} claude -p "review {}"
+
+# 批量代码审查
+claude -p "review all changes in this branch"
+
+# 为所有模块生成测试
+claude -p "generate tests for the modified modules"
+```
+
+### 6. 安全敏感开发
+
+```bash
+# 只读安全审计
+claude --permission-mode plan -p "audit this repository"
+
+# 阻止危险命令
+claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"
+
+# 限制自动化
+claude --tools "Read,Grep,Glob" -p "inspect the codebase"
+```
+
+### 7. JSON API 集成
+
+```bash
+# 获取结构化分析结果
+claude -p --output-format json "analyze this code and return findings"
+
+# 配合 jq 处理
+claude -p --output-format json "list functions" | jq '.functions[]'
+
+# 在脚本中使用
+result=$(claude -p --output-format json "summarize changes")
+```
+
+### jq 解析示例
+
+```bash
+# 提取特定字段
+claude -p --output-format json "analyze repo" | jq '.summary'
+
+# 过滤数组元素
+claude -p --output-format json "find bugs" | jq '.bugs[] | select(.severity=="high")'
+
+# 提取多个字段
+claude -p --output-format json "analyze" | jq '{summary, risk, recommendations}'
+
+# 转成 CSV
+claude -p --output-format json "list files" | jq -r '.files[] | [.name, .size] | @csv'
+
+# 条件处理
+claude -p --output-format json "check status" | jq 'if .ok then "pass" else "fail" end'
+
+# 提取嵌套值
+claude -p --output-format json "inspect" | jq '.details.metrics.coverage'
+
+# 处理整个数组
+claude -p --output-format json "find todos" | jq '.todos | length'
+
+# 转换输出
+claude -p --output-format json "review" | jq '{issues: [.issues[] | {file, line, message}]}'
+```
+
+## 模型
+
+### 模型选择
+
+```bash
+# 使用短名称
+claude --model sonnet
+claude --model opus
+claude --model haiku
+
+# 使用 opusplan 别名(Opus 负责规划,Sonnet 负责执行)
+claude --model opusplan "design and implement the caching layer"
+
+# 会话中切换快速模式
+claude --model haiku --effort low
+```
+
+### Effort 级别(Opus 4.6)
+
+```bash
+# 通过 CLI 参数设置 effort
+claude --model opus --effort high "design the architecture"
+
+# 通过 slash command 设置 effort
+/effort max
+
+# 通过环境变量设置 effort
+CLAUDE_EFFORT=medium claude --model opus
+```
+
+## 常用环境变量
+
+| 环境变量 | 说明 |
+|----------|------|
+| `ANTHROPIC_API_KEY` | API key |
+| `CLAUDE_MODEL` | 默认模型 |
+| `CLAUDE_EFFORT` | 默认推理强度 |
+| `CLAUDE_WORKING_DIRECTORY` | 默认工作目录 |
+| `CLAUDE_OUTPUT_FORMAT` | 默认输出格式 |
+| `CLAUDE_MCP_CONFIG` | 默认 MCP 配置 |
+
+## 快速参考
+
+### 最常用命令
+
+```bash
+# 交互式会话
+claude
+
+# 快速提问
+claude -p "explain this repo"
+
+# 继续上次对话
+claude -c
+
+# 处理某个文件
+claude -p "review README.md"
+
+# 为脚本输出 JSON
+claude -p --output-format json "list all classes"
+```
+
+### 参数组合
+
+```bash
+# 只读审查
+claude --permission-mode plan -p "review this codebase"
+
+# 高级模型 + JSON 输出
+claude --model opus -p --output-format json "analyze architecture"
+
+# 自定义工作目录 + MCP
+claude --working-directory ./backend --mcp-config ./mcp.json
+```
+
+## 故障排查
+
+### 找不到命令
+
+- 确认 `claude` 已安装并在 `PATH` 中
+- 重新打开终端
+- 检查是否需要重新登录或更新版本
+
+### API Key 问题
+
+- 检查 `ANTHROPIC_API_KEY`
+- 确认 key 未过期
+- 检查网络是否可访问 API
+
+### 找不到会话
+
+- 确认会话名称或 ID 正确
+- 先运行 `claude --list-sessions`(如果你的版本支持)
+- 检查当前账号是否一致
+
+### 输出格式问题
+
+- 使用 `--output-format json` 时确保输出可被解析
+- 如果是流式输出,加入 `--include-partial-messages`
+
+### 权限被拒绝
+
+- 检查 `--permission-mode`
+- 检查 `--allowedTools` 和 `--disallowedTools`
+- 如有必要,明确允许所需工具
+
+## 更多资源
+
+- [根目录中文指南](../README.md)
+- [Slash Commands 中文参考](../01-slash-commands/README.md)
+- [MCP 文档](../05-mcp/README.md)
+- [Claude Code 官方 CLI 文档](https://code.claude.com/docs/en/cli-reference)
diff --git a/zh/CATALOG.md b/zh/CATALOG.md
new file mode 100644
index 0000000..4045b84
--- /dev/null
+++ b/zh/CATALOG.md
@@ -0,0 +1,517 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Claude Code 功能目录
+
+> 一份关于 Claude Code 所有功能的快速参考:命令、agents、skills、plugins 和 hooks。
+
+**导航**: [命令](#斜杠命令) | [权限模式](#权限模式) | [Subagents](#subagents) | [Skills](#skills) | [Plugins](#plugins) | [MCP Servers](#mcp-servers) | [Hooks](#hooks) | [Memory](#memory-files) | [2026 年 3 月新功能](#2026-年-3-月新功能)
+
+---
+
+## 概览
+
+| 功能 | 内置 | 示例 | 总数 | 参考 |
+|---------|----------|----------|-------|-----------|
+| **Slash Commands** | 55+ | 8 | 63+ | [01-slash-commands/README.md](01-slash-commands/README.md) |
+| **Subagents** | 6 | 10 | 16 | [04-subagents/README.md](04-subagents/README.md) |
+| **Skills** | 5 个内置 | 4 | 9 | [03-skills/README.md](03-skills/README.md) |
+| **Plugins** | - | 3 | 3 | [07-plugins/README.md](07-plugins/README.md) |
+| **MCP Servers** | 1 | 8 | 9 | [05-mcp/README.md](05-mcp/README.md) |
+| **Hooks** | 25 个事件 | 7 | 7 | [06-hooks/README.md](06-hooks/README.md) |
+| **Memory** | 7 种类型 | 3 | 3 | [02-memory/README.md](02-memory/README.md) |
+| **总计** | **99** | **43** | **117** | |
+
+---
+
+## 斜杠命令
+
+命令是用户手动触发的快捷操作,用来执行特定任务。
+
+### 内置命令
+
+| 命令 | 说明 | 适用场景 |
+|---------|-------------|-------------|
+| `/help` | 显示帮助信息 | 开始上手、学习命令 |
+| `/btw` | 提出不写入上下文的插话问题 | 临时补充问题 |
+| `/chrome` | 配置 Chrome 集成 | 浏览器自动化 |
+| `/clear` | 清空对话历史 | 重新开始、减少上下文 |
+| `/diff` | 交互式 diff 查看器 | 审查变更 |
+| `/config` | 查看/编辑配置 | 自定义行为 |
+| `/status` | 显示会话状态 | 检查当前状态 |
+| `/agents` | 列出可用 agents | 查看委派选项 |
+| `/skills` | 列出可用 skills | 查看可自动触发的能力 |
+| `/hooks` | 列出已配置的 hooks | 调试自动化 |
+| `/insights` | 分析会话模式 | 优化会话使用 |
+| `/install-slack-app` | 安装 Claude Slack 应用 | Slack 集成 |
+| `/keybindings` | 自定义键盘快捷键 | 按键定制 |
+| `/mcp` | 列出 MCP servers | 检查外部集成 |
+| `/memory` | 查看已加载的 memory 文件 | 调试上下文加载 |
+| `/mobile` | 生成移动端二维码 | 手机访问 |
+| `/passes` | 查看使用通行证 | 订阅信息 |
+| `/plugin` | 管理 plugins | 安装/移除扩展 |
+| `/plan` | 进入规划模式 | 复杂实现 |
+| `/rewind` | 回退到 checkpoint | 撤销变更、探索替代方案 |
+| `/checkpoint` | 管理 checkpoints | 保存/恢复状态 |
+| `/cost` | 显示 token 消耗 | 监控开销 |
+| `/context` | 显示上下文窗口使用情况 | 管理对话长度 |
+| `/export` | 导出对话 | 保存以供参考 |
+| `/extra-usage` | 配置额外用量限制 | 限流管理 |
+| `/feedback` | 提交反馈或 bug 报告 | 报告问题 |
+| `/login` | 通过 Anthropic 认证 | 访问功能 |
+| `/logout` | 登出 | 切换账号 |
+| `/sandbox` | 切换 sandbox 模式 | 安全执行命令 |
+| `/vim` | 切换 vim 模式 | 类 Vim 编辑 |
+| `/doctor` | 运行诊断 | 排查问题 |
+| `/reload-plugins` | 重新加载已安装的 plugins | 插件管理 |
+| `/release-notes` | 显示更新说明 | 查看新功能 |
+| `/remote-control` | 启用远程控制 | 远程访问 |
+| `/permissions` | 管理权限 | 控制访问 |
+| `/session` | 管理会话 | 多会话工作流 |
+| `/rename` | 重命名当前会话 | 组织会话 |
+| `/resume` | 恢复之前的会话 | 继续工作 |
+| `/todo` | 查看/管理待办列表 | 跟踪任务 |
+| `/tasks` | 查看后台任务 | 监控异步操作 |
+| `/copy` | 复制最后一次回复到剪贴板 | 快速分享输出 |
+| `/teleport` | 将会话转移到另一台机器 | 远程继续工作 |
+| `/desktop` | 打开 Claude Desktop 应用 | 切换桌面界面 |
+| `/theme` | 更改颜色主题 | 自定义外观 |
+| `/usage` | 显示 API 使用统计 | 监控配额和消耗 |
+| `/fork` | 分叉当前对话 | 探索替代方案 |
+| `/stats` | 显示会话统计 | 查看会话指标 |
+| `/statusline` | 配置状态栏 | 自定义状态显示 |
+| `/stickers` | 查看会话贴纸 | 趣味奖励 |
+| `/fast` | 切换快速输出模式 | 加快响应 |
+| `/terminal-setup` | 配置终端集成 | 设置终端特性 |
+| `/upgrade` | 检查更新 | 版本管理 |
+
+### 自定义命令(示例)
+
+| 命令 | 说明 | 适用场景 | 作用域 | 安装 |
+|---------|-------------|-------------|-------|--------------|
+| `/optimize` | 分析代码以做优化 | 性能改进 | 项目 | `cp 01-slash-commands/optimize.md .claude/commands/` |
+| `/pr` | 准备 Pull Request | 提交 PR 前 | 项目 | `cp 01-slash-commands/pr.md .claude/commands/` |
+| `/generate-api-docs` | 生成 API 文档 | 编写 API 文档 | 项目 | `cp 01-slash-commands/generate-api-docs.md .claude/commands/` |
+| `/commit` | 结合上下文创建 git commit | 提交变更 | 用户 | `cp 01-slash-commands/commit.md .claude/commands/` |
+| `/push-all` | 先暂存、提交再 push | 快速发布 | 用户 | `cp 01-slash-commands/push-all.md .claude/commands/` |
+| `/doc-refactor` | 重构文档结构 | 改进文档 | 项目 | `cp 01-slash-commands/doc-refactor.md .claude/commands/` |
+| `/setup-ci-cd` | 搭建 CI/CD 流水线 | 新项目 | 项目 | `cp 01-slash-commands/setup-ci-cd.md .claude/commands/` |
+| `/unit-test-expand` | 扩展测试覆盖率 | 改进测试 | 项目 | `cp 01-slash-commands/unit-test-expand.md .claude/commands/` |
+
+> **作用域**: `User` = 个人工作流(`~/.claude/commands/`),`Project` = 团队共享(`.claude/commands/`)
+
+**参考**: [01-slash-commands/README.md](01-slash-commands/README.md) | [官方文档](https://code.claude.com/docs/en/interactive-mode)
+
+**快速安装(所有自定义命令)**:
+```bash
+cp 01-slash-commands/*.md .claude/commands/
+```
+
+---
+
+## 权限模式
+
+Claude Code 提供 6 种权限模式,用来控制工具调用如何被授权。
+
+| 模式 | 说明 | 适用场景 |
+|------|-------------|-------------|
+| `default` | 每次工具调用都询问 | 标准交互式使用 |
+| `acceptEdits` | 自动接受文件编辑,其他情况仍询问 | 可信编辑工作流 |
+| `plan` | 只允许只读工具,不允许写入 | 规划与探索 |
+| `auto` | 不再提示,自动接受所有工具 | 完全自主运行(Research Preview) |
+| `bypassPermissions` | 跳过所有权限检查 | CI/CD、无头环境 |
+| `dontAsk` | 跳过需要权限的工具 | 非交互脚本 |
+
+> **注意**:`auto` 模式是 Research Preview 功能(2026 年 3 月)。只有在可信且已隔离的环境中才使用 `bypassPermissions`。
+
+**参考**: [官方文档](https://code.claude.com/docs/en/permissions)
+
+---
+
+## Subagents
+
+为特定任务准备的专门化 AI 助手,拥有隔离上下文。
+
+### 内置 Subagents
+
+| Agent | 说明 | 工具 | 模型 | 适用场景 |
+|-------|-------------|-------|-------|-------------|
+| **general-purpose** | 多步任务、研究 | 所有工具 | 继承当前模型 | 复杂研究、多文件任务 |
+| **Plan** | 实现规划 | Read、Glob、Grep、Bash | 继承当前模型 | 架构设计、规划 |
+| **Explore** | 代码库探索 | Read、Glob、Grep | Haiku 4.5 | 快速搜索、理解代码 |
+| **Bash** | 命令执行 | Bash | 继承当前模型 | git 操作、终端任务 |
+| **statusline-setup** | 状态栏配置 | Bash、Read、Write | Sonnet 4.6 | 配置状态栏显示 |
+| **Claude Code Guide** | 帮助与文档 | Read、Glob、Grep | Haiku 4.5 | 获取帮助、学习功能 |
+
+### Subagent 配置字段
+
+| 字段 | 类型 | 说明 |
+|-------|------|-------------|
+| `name` | string | agent 标识 |
+| `description` | string | 这个 agent 的用途 |
+| `model` | string | 模型覆盖值(例如 `haiku-4.5`) |
+| `tools` | array | 允许使用的工具列表 |
+| `effort` | string | 推理强度等级(`low`、`medium`、`high`) |
+| `initialPrompt` | string | agent 启动时注入的 system prompt |
+| `disallowedTools` | array | 明确禁止该 agent 使用的工具 |
+
+### 自定义 Subagents(示例)
+
+| Agent | 说明 | 适用场景 | 作用域 | 安装 |
+|-------|-------------|-------------|-------|--------------|
+| `code-reviewer` | 全面的代码质量检查 | 代码审查会话 | 项目 | `cp 04-subagents/code-reviewer.md .claude/agents/` |
+| `code-architect` | 功能架构设计 | 新功能规划 | 项目 | `cp 04-subagents/code-architect.md .claude/agents/` |
+| `code-explorer` | 深入分析代码库 | 理解已有功能 | 项目 | `cp 04-subagents/code-explorer.md .claude/agents/` |
+| `clean-code-reviewer` | 按 Clean Code 原则审查 | 可维护性审查 | 项目 | `cp 04-subagents/clean-code-reviewer.md .claude/agents/` |
+| `test-engineer` | 测试策略与覆盖率 | 测试规划 | 项目 | `cp 04-subagents/test-engineer.md .claude/agents/` |
+| `documentation-writer` | 技术文档编写 | API 文档、指南 | 项目 | `cp 04-subagents/documentation-writer.md .claude/agents/` |
+| `secure-reviewer` | 面向安全的审查 | 安全审计 | 项目 | `cp 04-subagents/secure-reviewer.md .claude/agents/` |
+| `implementation-agent` | 完整功能实现 | 功能开发 | 项目 | `cp 04-subagents/implementation-agent.md .claude/agents/` |
+| `debugger` | 根因分析 | Bug 调查 | 用户 | `cp 04-subagents/debugger.md .claude/agents/` |
+| `data-scientist` | SQL 查询、数据分析 | 数据任务 | 用户 | `cp 04-subagents/data-scientist.md .claude/agents/` |
+
+> **作用域**: `User` = 个人(`~/.claude/agents/`),`Project` = 团队共享(`.claude/agents/`)
+
+**参考**: [04-subagents/README.md](04-subagents/README.md) | [官方文档](https://code.claude.com/docs/en/sub-agents)
+
+**快速安装(所有自定义 agents)**:
+```bash
+cp 04-subagents/*.md .claude/agents/
+```
+
+---
+
+## Skills
+
+可自动触发的能力包,包含说明、脚本和模板。
+
+### 示例 Skills
+
+| Skill | 说明 | 何时自动触发 | 作用域 | 安装 |
+|-------|-------------|-------------------|-------|--------------|
+| `code-review` | 全面的代码审查 | “Review this code”, “Check quality” | 项目 | `cp -r 03-skills/code-review .claude/skills/` |
+| `brand-voice` | 品牌一致性检查器 | 编写营销文案时 | 项目 | `cp -r 03-skills/brand-voice .claude/skills/` |
+| `doc-generator` | API 文档生成器 | “Generate docs”, “Document API” | 项目 | `cp -r 03-skills/doc-generator .claude/skills/` |
+| `refactor` | 系统化代码重构(Martin Fowler) | “Refactor this”, “Clean up code” | 用户 | `cp -r 03-skills/refactor ~/.claude/skills/` |
+
+> **作用域**: `User` = 个人(`~/.claude/skills/`),`Project` = 团队共享(`.claude/skills/`)
+
+### Skill 结构
+
+```
+~/.claude/skills/skill-name/
+├── SKILL.md # skill 定义与说明
+├── scripts/ # 辅助脚本
+└── templates/ # 输出模板
+```
+
+### Skill Frontmatter 字段
+
+Skills 支持在 `SKILL.md` 中使用 YAML frontmatter 进行配置:
+
+| 字段 | 类型 | 说明 |
+|-------|------|-------------|
+| `name` | string | skill 显示名称 |
+| `description` | string | 这个 skill 的作用 |
+| `autoInvoke` | array | 自动触发的关键词 |
+| `effort` | string | 推理强度等级(`low`、`medium`、`high`) |
+| `shell` | string | 脚本使用的 shell(`bash`、`zsh`、`sh`) |
+
+**参考**: [03-skills/README.md](03-skills/README.md) | [官方文档](https://code.claude.com/docs/en/skills)
+
+**快速安装(所有 skills)**:
+```bash
+cp -r 03-skills/* ~/.claude/skills/
+```
+
+### 内置 Skills
+
+| Skill | 说明 | 何时自动触发 |
+|-------|-------------|-------------------|
+| `/simplify` | 审查代码质量 | 写完代码后 |
+| `/batch` | 对多个文件运行提示词 | 批量操作 |
+| `/debug` | 调试失败的测试/错误 | 调试会话 |
+| `/loop` | 按间隔运行提示词 | 周期性任务 |
+| `/claude-api` | 使用 Claude API 构建应用 | API 开发 |
+
+---
+
+## Plugins
+
+把 commands、agents、MCP servers 和 hooks 打包在一起的集合。
+
+### 示例 Plugins
+
+| Plugin | 说明 | 组件 | 适用场景 | 作用域 | 安装 |
+|--------|-------------|------------|-------------|-------|--------------|
+| `pr-review` | PR 审查工作流 | 3 个 commands、3 个 agents、GitHub MCP | 代码审查 | 项目 | `/plugin install pr-review` |
+| `devops-automation` | 部署与监控 | 4 个 commands、3 个 agents、K8s MCP | DevOps 任务 | 项目 | `/plugin install devops-automation` |
+| `documentation` | 文档生成套件 | 4 个 commands、3 个 agents、模板 | 文档编写 | 项目 | `/plugin install documentation` |
+
+> **作用域**: `Project` = 团队共享,`User` = 个人工作流
+
+### Plugin 结构
+
+```
+.claude-plugin/
+├── plugin.json # manifest 文件
+├── commands/ # Slash commands
+├── agents/ # Subagents
+├── skills/ # Skills
+├── mcp/ # MCP 配置
+├── hooks/ # Hook 脚本
+└── scripts/ # 工具脚本
+```
+
+**参考**: [07-plugins/README.md](07-plugins/README.md) | [官方文档](https://code.claude.com/docs/en/plugins)
+
+**Plugin 管理命令**:
+```bash
+/plugin list # 列出已安装的 plugins
+/plugin install <name> # 安装 plugin
+/plugin remove <name> # 移除 plugin
+/plugin update <name> # 更新 plugin
+```
+
+---
+
+## MCP Servers
+
+用于访问外部工具和 API 的 Model Context Protocol servers。
+
+### 常见 MCP Servers
+
+| Server | 说明 | 适用场景 | 作用域 | 安装 |
+|--------|-------------|-------------|-------|--------------|
+| **GitHub** | PR 管理、issues、代码 | GitHub 工作流 | 项目 | `claude mcp add github -- npx -y @modelcontextprotocol/server-github` |
+| **Database** | SQL 查询、数据访问 | 数据库操作 | 项目 | `claude mcp add db -- npx -y @modelcontextprotocol/server-postgres` |
+| **Filesystem** | 高级文件操作 | 复杂文件任务 | 用户 | `claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem` |
+| **Slack** | 团队沟通 | 通知、更新 | 项目 | 在设置中配置 |
+| **Google Docs** | 文档访问 | 文档编辑、审阅 | 项目 | 在设置中配置 |
+| **Asana** | 项目管理 | 任务跟踪 | 项目 | 在设置中配置 |
+| **Stripe** | 支付数据 | 财务分析 | 项目 | 在设置中配置 |
+| **Memory** | 持久记忆 | 跨会话回忆 | 用户 | 在设置中配置 |
+| **Context7** | 库文档 | 查找最新文档 | 内置 | 内置 |
+
+> **作用域**: `Project` = 团队(`.mcp.json`),`User` = 个人(`~/.claude.json`),`Built-in` = 预装
+
+### MCP 配置示例
+
+```json
+{
+ "mcpServers": {
+ "github": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-github"],
+ "env": {
+ "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+ }
+ }
+ }
+}
+```
+
+**参考**: [05-mcp/README.md](05-mcp/README.md) | [MCP 协议文档](https://modelcontextprotocol.io)
+
+**快速安装(GitHub MCP)**:
+```bash
+export GITHUB_TOKEN="your_token" && claude mcp add github -- npx -y @modelcontextprotocol/server-github
+```
+
+---
+
+## Hooks
+
+在 Claude Code 事件发生时执行的事件驱动自动化。
+
+### Hook 事件
+
+| 事件 | 说明 | 触发时机 | 使用场景 |
+|-------|-------------|----------------|-----------|
+| `SessionStart` | 会话开始/恢复 | 会话初始化 | 初始化任务 |
+| `InstructionsLoaded` | 指令已加载 | `CLAUDE.md` 或规则文件加载 | 自定义指令处理 |
+| `UserPromptSubmit` | 提示词提交前 | 用户发送消息 | 输入校验 |
+| `PreToolUse` | 工具执行前 | 任意工具运行之前 | 校验、日志 |
+| `PermissionRequest` | 显示权限对话框 | 敏感操作前 | 自定义审批流程 |
+| `PostToolUse` | 工具成功后 | 任意工具完成后 | 格式化、通知 |
+| `PostToolUseFailure` | 工具执行失败 | 工具报错后 | 错误处理、日志 |
+| `Notification` | 发送通知时 | Claude 发送通知 | 外部提醒 |
+| `SubagentStart` | 启动 subagent | subagent 任务开始 | 初始化上下文 |
+| `SubagentStop` | subagent 完成 | subagent 任务结束 | 链式动作 |
+| `Stop` | Claude 完成响应 | 响应完成 | 清理、汇报 |
+| `StopFailure` | API 错误导致结束 | API 错误发生 | 错误恢复、日志 |
+| `TeammateIdle` | 队友 agent 空闲 | agent team 协调 | 分配工作 |
+| `TaskCompleted` | 任务标记完成 | 任务完成 | 任务后处理 |
+| `TaskCreated` | 通过 TaskCreate 创建任务 | 新任务创建 | 任务追踪、日志 |
+| `ConfigChange` | 配置更新 | 设置被修改 | 响应配置变化 |
+| `CwdChanged` | 当前工作目录变化 | 目录切换 | 目录级初始化 |
+| `FileChanged` | 监控文件发生变化 | 文件被修改 | 文件监控、重建 |
+| `PreCompact` | 压缩前 | 上下文压缩前 | 状态保留 |
+| `PostCompact` | 压缩完成后 | 压缩完成 | 压缩后动作 |
+| `WorktreeCreate` | worktree 创建中 | git worktree 创建 | 设置 worktree 环境 |
+| `WorktreeRemove` | worktree 被移除 | git worktree 删除 | 清理 worktree 资源 |
+| `Elicitation` | MCP server 请求输入 | MCP elicitation | 输入校验 |
+| `ElicitationResult` | 用户响应 elicitation | 用户回答 | 响应处理 |
+| `SessionEnd` | 会话结束 | 会话终止 | 清理、保存状态 |
+
+### 示例 Hooks
+
+| Hook | 说明 | 事件 | 作用域 | 安装 |
+|------|-------------|-------|-------|--------------|
+| `validate-bash.py` | 命令校验 | PreToolUse:Bash | 项目 | `cp 06-hooks/validate-bash.py .claude/hooks/` |
+| `security-scan.py` | 安全扫描 | PostToolUse:Write | 项目 | `cp 06-hooks/security-scan.py .claude/hooks/` |
+| `format-code.sh` | 自动格式化 | PostToolUse:Write | 用户 | `cp 06-hooks/format-code.sh ~/.claude/hooks/` |
+| `validate-prompt.py` | 提示词校验 | UserPromptSubmit | 项目 | `cp 06-hooks/validate-prompt.py .claude/hooks/` |
+| `context-tracker.py` | token 使用跟踪 | Stop | 用户 | `cp 06-hooks/context-tracker.py ~/.claude/hooks/` |
+| `pre-commit.sh` | 提交前校验 | PreToolUse:Bash | 项目 | `cp 06-hooks/pre-commit.sh .claude/hooks/` |
+| `log-bash.sh` | 命令日志记录 | PostToolUse:Bash | 用户 | `cp 06-hooks/log-bash.sh ~/.claude/hooks/` |
+
+> **作用域**: `Project` = 团队(`.claude/settings.json`),`User` = 个人(`~/.claude/settings.json`)
+
+### Hook 配置
+
+```json
+{
+ "hooks": {
+ "PreToolUse": [
+ {
+ "matcher": "Bash",
+ "command": "~/.claude/hooks/validate-bash.py"
+ }
+ ],
+ "PostToolUse": [
+ {
+ "matcher": "Write",
+ "command": "~/.claude/hooks/format-code.sh"
+ }
+ ]
+ }
+}
+```
+
+**参考**: [06-hooks/README.md](06-hooks/README.md) | [官方文档](https://code.claude.com/docs/en/hooks)
+
+**快速安装(所有 hooks)**:
+```bash
+mkdir -p ~/.claude/hooks && cp 06-hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh
+```
+
+---
+
+## Memory Files
+
+会在多个会话之间自动加载的持久上下文。
+
+### Memory 类型
+
+| 类型 | 位置 | 作用域 | 适用场景 |
+|------|----------|-------|-------------|
+| **Managed Policy** | 组织管理的策略 | Organization | 统一组织标准 |
+| **Project** | `./CLAUDE.md` | Project(团队) | 团队规范、项目上下文 |
+| **Project Rules** | `.claude/rules/` | Project(团队) | 模块化项目规则 |
+| **User** | `~/.claude/CLAUDE.md` | User(个人) | 个人偏好 |
+| **User Rules** | `~/.claude/rules/` | User(个人) | 模块化个人规则 |
+| **Local** | `./CLAUDE.local.md` | Local(git 忽略) | 机器特定覆盖(截至 2026 年 3 月不在官方文档中,可能是历史遗留) |
+| **Auto Memory** | 自动 | Session | 自动捕捉的洞察和修正 |
+
+> **作用域**: `Organization` = 管理员管理,`Project` = 通过 git 与团队共享,`User` = 个人偏好,`Local` = 不提交,`Session` = 自动管理
+
+**参考**: [02-memory/README.md](02-memory/README.md) | [官方文档](https://code.claude.com/docs/en/memory)
+
+**快速安装**:
+```bash
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md
+```
+
+---
+
+## 2026 年 3 月新功能
+
+| 功能 | 说明 | 使用方式 |
+|---------|-------------|------------|
+| **Remote Control** | 通过 API 远程控制 Claude Code 会话 | 使用远程控制 API 以编程方式发送提示并接收响应 |
+| **Web Sessions** | 在浏览器环境中运行 Claude Code | 通过 `claude web` 或 Anthropic Console 访问 |
+| **Desktop App** | Claude Code 的原生桌面应用 | 使用 `/desktop` 或从 Anthropic 网站下载 |
+| **Agent Teams** | 协调多个 agent 共同处理相关任务 | 配置协作并共享上下文的 teammate agents |
+| **Task List** | 后台任务管理与监控 | 使用 `/tasks` 查看和管理后台操作 |
+| **Prompt Suggestions** | 上下文感知的命令建议 | 根据当前上下文自动出现建议 |
+| **Git Worktrees** | 用于并行开发的隔离 git worktree | 使用 worktree 命令进行安全的并行分支工作 |
+| **Sandboxing** | 安全隔离的执行环境 | 使用 `/sandbox` 切换,在受限环境中运行命令 |
+| **MCP OAuth** | 为 MCP servers 提供 OAuth 认证 | 在 MCP server 设置中配置 OAuth 凭据以安全访问 |
+| **MCP Tool Search** | 动态搜索和发现 MCP 工具 | 使用工具搜索查找已连接 server 上可用的 MCP 工具 |
+| **Scheduled Tasks** | 使用 `/loop` 和 cron 工具设置周期任务 | 使用 `/loop 5m /command` 或 CronCreate 工具 |
+| **Chrome Integration** | 使用无头 Chromium 做浏览器自动化 | 使用 `--chrome` 标志或 `/chrome` 命令 |
+| **Keyboard Customization** | 自定义按键映射并支持 chord | 使用 `/keybindings` 或编辑 `~/.claude/keybindings.json` |
+| **自动模式(Auto Mode)** | 无需权限提示的完全自主运行(Research Preview) | 使用 `--mode auto` 或 `/permissions auto`;2026 年 3 月 |
+| **通道(Channels)** | 多通道通信(Telegram、Slack 等)(Research Preview) | 配置 channel plugins;2026 年 3 月 |
+| **语音输入(Voice Dictation)** | 用语音输入提示词 | 使用麦克风图标或语音快捷键 |
+| **Agent Hook Type** | 触发 subagent 而不是执行 shell 命令的 hook | 在 hook 配置中设置 `"type": "agent"` |
+| **Prompt Hook Type** | 将 prompt 文本注入对话的 hook | 在 hook 配置中设置 `"type": "prompt"` |
+| **MCP Elicitation** | MCP servers 可在工具执行期间请求用户输入 | 通过 `Elicitation` 和 `ElicitationResult` hook 事件处理 |
+| **WebSocket MCP Transport** | 用 WebSocket 连接 MCP server | 在 MCP server 配置中使用 `"transport": "websocket"` |
+| **Plugin LSP Support** | 通过 plugins 集成 Language Server Protocol | 在 `plugin.json` 中配置 LSP servers,以获得编辑器能力 |
+| **Managed Drop-ins** | 组织管理的 drop-in 配置(v2.1.83) | 通过 managed policies 由管理员配置,自动应用到所有用户 |
+
+---
+
+## 快速参考矩阵
+
+### 功能选择指南
+
+| 需求 | 推荐功能 | 原因 |
+|------|---------------------|-----|
+| 快捷命令 | Slash Command | 手动、立即执行 |
+| 持久上下文 | Memory | 自动加载 |
+| 复杂自动化 | Skill | 自动触发 |
+| 专门任务 | Subagent | 隔离上下文 |
+| 外部数据 | MCP Server | 实时访问 |
+| 事件自动化 | Hook | 事件触发 |
+| 完整解决方案 | Plugin | 一体化打包 |
+
+### 安装优先级
+
+| 优先级 | 功能 | 命令 |
+|----------|---------|---------|
+| 1. 必装 | Memory | `cp 02-memory/project-CLAUDE.md ./CLAUDE.md` |
+| 2. 日常使用 | Slash Commands | `cp 01-slash-commands/*.md .claude/commands/` |
+| 3. 质量提升 | Subagents | `cp 04-subagents/*.md .claude/agents/` |
+| 4. 自动化 | Hooks | `cp 06-hooks/*.sh ~/.claude/hooks/` |
+| 5. 集成 | MCP Servers | `claude mcp add github -- npx -y @modelcontextprotocol/server-github` |
+| 6. 全量打包 | Plugins | `/plugin install <name>` |
+
+---
+
+## 一条命令完成安装
+
+```bash
+# 创建目录
+mkdir -p .claude/commands .claude/agents ~/.claude/hooks ~/.claude/skills
+
+# 安装所有功能
+cp 01-slash-commands/*.md .claude/commands/
+cp 04-subagents/*.md .claude/agents/
+cp -r 03-skills/* ~/.claude/skills/
+cp 06-hooks/*.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/*.sh
+
+# 配置 MCP
+export GITHUB_TOKEN="your_token"
+claude mcp add github -- npx -y @modelcontextprotocol/server-github
+
+# 使用 Plugins
+/plugin install pr-review
+/plugin install devops-automation
+```
+
+---
+
+## 其他资源
+
+- [Claude Code Documentation](https://code.claude.com/docs/en/overview)
+- [MCP Protocol Specification](https://modelcontextprotocol.io)
+- [Skills Repository](https://github.com/luongnv89/skills) - 现成 skills 集合
+- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook)
+- [Boris Cherny's Claude Code Workflow](https://x.com/bcherny/status/2007179832300581177) - Claude Code 的创造者分享了他的系统化工作流:并行 agents、共享 `CLAUDE.md`、Plan mode、slash commands、subagents,以及用于长时间自主会话的验证 hooks。
diff --git a/zh/CHANGELOG.md b/zh/CHANGELOG.md
new file mode 100644
index 0000000..024f5b0
--- /dev/null
+++ b/zh/CHANGELOG.md
@@ -0,0 +1,109 @@
+# 更新日志
+
+## v2.2.0 — 2026-03-26
+
+### 文档
+
+- 与 Claude Code v2.1.84(f78c094)同步更新所有教程和参考文档 @luongnv89
+ - 将 slash commands 更新为 55+ 个内置命令 + 5 个 bundled skills,并标记 3 个已弃用项
+ - 将 hook 事件从 18 个扩展到 25 个,新增 `agent` hook 类型(现在共 4 类)
+ - 在高级功能中加入自动模式(Auto Mode)、通道(Channels)、语音输入(Voice Dictation)
+ - 为 skill frontmatter 增加 `effort`、`shell` 字段;为 agent 增加 `initialPrompt`、`disallowedTools` 字段
+ - 增加 WebSocket MCP transport、elicitation、2KB 工具上限
+ - 增加 plugin 的 LSP 支持、`userConfig`、`${CLAUDE_PLUGIN_DATA}`
+ - 更新所有参考文档(CATALOG、QUICK_REFERENCE、LEARNING-ROADMAP、INDEX)
+- 将 README 重写为落地页结构化指南(32a0776)@luongnv89
+
+### Bug 修复
+
+- 为通过 CI 词典检查,补充缺失的 cSpell 词条和 README 章节(93f9d51)@luongnv89
+- 在 cSpell 词典中加入 `Sandboxing`(b80ce6f)@luongnv89
+
+**完整更新日志**:https://github.com/luongnv89/claude-howto/compare/v2.1.1...v2.2.0
+
+---
+
+## v2.1.1 — 2026-03-13
+
+### Bug 修复
+
+- 移除导致 CI 链接检查失败的失效 marketplace 链接(3fdf0d6)@luongnv89
+- 将 `sandboxed` 和 `pycache` 加入 cSpell 词典(dc64618)@luongnv89
+
+**完整更新日志**:https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1
+
+---
+
+## v2.1.0 — 2026-03-13
+
+### 功能
+
+- 新增自适应学习路径,包含自我评估和 lesson quiz skills(1ef46cd)@luongnv89
+ - `/self-assessment` - 覆盖 10 个功能领域的交互式能力测验,并生成个性化学习路径
+ - `/lesson-quiz [lesson]` - 每课知识检查,包含 8-10 道针对性问题
+
+### Bug 修复
+
+- 更新失效 URL、弃用项和过时引用(8fe4520)@luongnv89
+- 修复 resources 和 self-assessment skill 中的损坏链接(7a05863)@luongnv89
+- 在 concepts guide 中为嵌套代码块使用 tilde fences(5f82719)@VikalpP
+- 为 cSpell 词典补充缺失词汇(8df7572)@luongnv89
+
+### 文档
+
+- Phase 5 QA - 修复各文档中的一致性、URL 和术语问题(00bbe4c)@luongnv89
+- 完成 Phase 3-4 - 补充新功能覆盖和参考文档更新(132de29)@luongnv89
+- 在 MCP 上下文膨胀章节加入 MCPorter runtime(ef52705)@luongnv89
+- 为 6 份指南补充缺失命令、功能和设置(4bc8f15)@luongnv89
+- 基于仓库现有规范补充 style guide(84141d0)@luongnv89
+- 在指南对比表中加入自我评估行(8fe0c96)@luongnv89
+- 将 VikalpP 加入贡献者名单,记录 PR #7(d5b4350)@luongnv89
+- 在 README 和 roadmap 中加入 self-assessment 与 lesson-quiz skill 参考(d5a6106)@luongnv89
+
+### 新贡献者
+
+- @VikalpP 完成了他们的首次贡献,见 #7
+
+**完整更新日志**:https://github.com/luongnv89/claude-howto/compare/v2.0.0...v2.1.0
+
+---
+
+## v2.0.0 — 2026-02-01
+
+### 功能
+
+- 与 Claude Code 2026 年 2 月功能同步更新全部文档(487c96d)
+ - 更新所有 10 个教程目录和 7 份参考文档中的 26 个文件
+ - 补充 **Auto Memory** 文档 - 每个项目的持久学习能力
+ - 补充 **Remote Control**、**Web Sessions** 和 **Desktop App** 文档
+ - 补充 **Agent Teams** 文档(实验性多 agent 协作)
+ - 补充 **MCP OAuth 2.0**、**Tool Search** 和 **Claude.ai Connectors** 文档
+ - 补充 subagents 的 **Persistent Memory** 和 **Worktree Isolation** 文档
+ - 补充 **Background Subagents**、**Task List**、**Prompt Suggestions** 文档
+ - 补充 **Sandboxing** 和 **Managed Settings**(Enterprise)文档
+ - 补充 **HTTP Hooks** 和 7 个新 hook 事件的文档
+ - 补充 **Plugin Settings**、**LSP Servers** 和 marketplace 更新文档
+ - 补充 Checkpoint 的 **Summarize from Checkpoint** 回退选项文档
+ - 记录 17 个新的 slash commands(`/fork`、`/desktop`、`/teleport`、`/tasks`、`/fast` 等)
+ - 记录新的 CLI flags(`--worktree`、`--from-pr`、`--remote`、`--teleport`、`--teammate-mode` 等)
+ - 记录 auto memory、effort 等级、agent teams 等新的环境变量
+
+### 设计
+
+- 将 logo 重设计为简洁调色的 compass-bracket 标志(20779db)
+
+### Bug 修复 / 修正
+
+- 更新模型名称:Sonnet 4.5 → **Sonnet 4.6**,Opus 4.5 → **Opus 4.6**
+- 修正 permission mode 名称:用真实的 `default` / `acceptEdits` / `plan` / `dontAsk` / `bypassPermissions` 替代虚构的 “Unrestricted/Confirm/Read-only”
+- 修正 hook 事件:移除虚构的 `PreCommit` / `PostCommit` / `PrePush`,加入真实事件(`SubagentStart`、`WorktreeCreate`、`ConfigChange` 等)
+- 修正 CLI 语法:用 `claude -p`(print mode)替代虚构的 `claude-code --headless`
+- 修正 checkpoint 命令:用真实的 `Esc+Esc` / `/rewind` 界面替代虚构的 `/checkpoint save/list/rewind/diff`
+- 修正 session 管理:用真实的 `/resume` / `/rename` / `/fork` 替代虚构的 `/session list/new/switch/save`
+- 修正 plugin manifest 格式:从 `plugin.yaml` 迁移到 `.claude-plugin/plugin.json`
+- 修正 MCP 配置路径:`~/.claude/mcp.json` → `.mcp.json`(项目)/ `~/.claude.json`(用户)
+- 修正文档 URL:`docs.claude.com` → `docs.anthropic.com`;移除虚构的 `plugins.claude.com`
+- 移除多个文件中虚构的配置字段
+- 将所有 “Last Updated” 日期更新到 2026 年 2 月
+
+**完整更新日志**:https://github.com/luongnv89/claude-howto/compare/20779db...v2.0.0
diff --git a/zh/CODE_OF_CONDUCT.md b/zh/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..b64c98d
--- /dev/null
+++ b/zh/CODE_OF_CONDUCT.md
@@ -0,0 +1,216 @@
+# 贡献者行为准则
+
+## 我们的承诺
+
+我们致力于为所有人提供一个热情且鼓舞人心的社区。我们承诺,参与本社区的每个人都应拥有免受骚扰的体验,不论其年龄、身体大小、种姓、残障、族裔、性别特征、性别认同与表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教,或性取向与性身份如何。
+
+我们致力于打造一个积极、包容且安全的环境,让所有贡献者都感到被尊重、被重视,并能充分发挥自己的能力。
+
+## 我们的标准
+
+有助于营造积极环境的行为包括:
+
+### 保持尊重
+- 使用热情且包容的语言
+- 尊重不同的观点、立场和经历
+- 愉快地接受建设性批评
+- 尊重文化和语言差异
+- 认可并庆祝多元背景
+
+### 保持协作
+- 共同解决冲突
+- 给予他人应得的署名和认可
+- 帮助他人学习和成长
+- 分享知识并积极提问
+- 支持社区里的其他成员
+
+### 保持专业
+- 保持讨论聚焦且高效
+- 避免贬低或侮辱性言论
+- 在 issue 和 discussion 中保持主题相关
+- 使用清晰且尊重的沟通方式
+- 假设他人的消息都出于善意
+
+### 保持包容
+- 欢迎新贡献者
+- 帮助刚接触项目的人上手
+- 提供建设性的反馈
+- 接纳不同视角的人
+- 为安静的声音创造被听见的空间
+
+## 不可接受的行为
+
+以下行为被视为骚扰,在本社区中不可接受:
+
+### 骚扰与歧视
+- 与性别、性别认同与表达、性取向、残障、心理疾病、神经类型、外貌、体型、年龄、种族或宗教相关的冒犯性言论
+- 关于某人生活方式或生活选择的不受欢迎评论
+- 故意使用错误称谓,或使用“死名”或被拒绝的名字
+- 与主题无关的露骨性图像或行为
+- 未经同意或在要求停止后仍进行肢体接触或模拟肢体接触
+
+### 滥用行为
+- 指向他人的暴力威胁或暴力言论
+- 唆使暴力或针对个人的暴力言论
+- 故意恐吓
+- 跟踪或尾随
+- 反复联系造成骚扰
+- 任何其他合理上可视为不当的行为
+
+### 线上骚扰
+- 持续干扰在线讨论
+- 发布他人隐私信息(人肉搜索 / doxxing)
+- 不受欢迎的性关注或性骚扰
+- 刷屏、挑衅或故意捣乱
+- 垃圾广告或重复性宣传
+- 散布错误信息或虚假信息
+
+### 报复
+- 因他人举报违规而采取报复行动
+- 因他人举报不当行为而区别对待
+- 以举报作为威胁
+
+## 适用范围
+
+本行为准则适用于:
+- 所有社区空间(GitHub issues、pull requests、discussions 等)
+- 项目仓库和文档
+- 由项目组织或代表项目参加的活动和聚会
+- 代表项目或社区的公共场合
+- 与项目事务相关的私人沟通
+
+本行为准则适用于所有项目空间;当个人在公共场合代表项目或社区时,也同样适用。代表项目或社区的例子包括使用官方项目邮箱、通过官方社交账号发帖,或在线上/线下活动中担任指定代表。
+
+## 执行
+
+社区负责人负责澄清并执行可接受行为标准,并会针对任何被认为不当、具有威胁性、冒犯性或有害的行为采取适当且公正的纠正措施。
+
+### 举报违规
+
+如果你经历或目睹了不可接受的行为,或者有其他担忧,请通过以下方式报告:
+
+1. **Email**:联系项目维护者(如可用,请填写联系方式)
+2. **GitHub Issues**:使用私密举报功能(如果你的 GitHub 设置中可用)
+3. **直接消息**:直接联系项目维护者
+
+请提供:
+- 你的联系方式
+- 涉及人员的姓名(如果你愿意提供)
+- 事件描述
+- 上下文和相关链接
+- 事件对你的影响
+
+**所有报告都会被保密。**
+
+### 调查与响应
+
+社区负责人将:
+- 及时且公正地审查和调查所有投诉
+- 对举报人保持保密
+- 向举报人反馈处理进展
+- 根据调查结果采取适当行动
+
+可能的措施包括:
+- 私下警告或辅导
+- 公开道歉(若违规者同意)
+- 暂时或永久移出社区空间
+- 取消贡献者权限
+- 必要时升级至 GitHub 或其他平台
+
+### 申诉流程
+
+如果你认为某项决定有误,可以通过以下方式申诉:
+1. 提供新的信息或上下文
+2. 请求多位维护者复核
+3. 在初次决定后的 30 天内跟进
+
+## 如何尊重地表达分歧
+
+技术社区中出现分歧是正常的。以下是尊重地表达不同意见的方法:
+
+### 应该做的
+- ✅ 聚焦观点,而不是人
+- ✅ 询问澄清问题
+- ✅ 承认对立观点中的合理之处
+- ✅ 使用 “我” 陈述(例如:“我不同意,因为……”)
+- ✅ 引用来源和证据
+- ✅ 感谢他人的观点
+
+### 不应该做的
+- ❌ 人身攻击
+- ❌ 使用贬低性语言(如“这太蠢了”)
+- ❌ 预设他人恶意
+- ❌ 提及无关的过往冲突
+- ❌ 升级语气或变得敌对
+- ❌ 故意歪曲他人观点
+
+### 尊重分歧示例
+```
+❌ 不好:“这是个愚蠢的想法,你显然不了解这个项目。”
+
+✅ 更好:“我理解你的意思,但我担心这种做法在更大的项目里可能
+不太能扩展。你考虑过这个基准测试里展示的性能影响吗?我很想听听
+你的看法。”
+```
+
+## 搭建桥梁
+
+我们相信对话与和解的力量:
+
+- 如果别人指出你的行为问题,请认真倾听并反思
+- 如果你造成了伤害,愿意道歉
+- 支持他人的学习和成长
+- 记住每个人都会犯错
+- 聚焦解决方案,而不是归咎
+- 在坚持责任的同时,保持善意
+
+## 遵守本准则的好处
+
+通过维护一个尊重且包容的社区,我们能够:
+- 吸引拥有不同视角的贡献者
+- 通过协作产出更好的解决方案
+- 建立更牢固的关系
+- 让项目对新成员更友好
+- 产出更高质量的文档和示例
+- 培养学习与成长的文化
+
+## 特别说明
+
+### 对维护者
+- 以身作则,遵守本准则
+- 对举报保持响应
+- 在决策上保持透明
+- 帮助公正地解决冲突
+- 为所有人创造安全环境
+
+### 对贡献者
+- 假设维护者和其他贡献者都怀有善意
+- 提供建设性的反馈
+- 支持新成员
+- 帮助维护社区标准
+- 对社区文化承担责任
+
+### 对所有人
+- 记住每条消息背后都是一个人
+- 如果感到沮丧,先暂停一下
+- 需要支持时请联系社区负责人
+- 帮助创造你希望参与的社区
+
+## 来源说明
+
+本行为准则参考并改编自:
+- [Contributor Covenant](https://www.contributor-covenant.org/)
+- [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/)
+- [Python Community Code of Conduct](https://www.python.org/psf/conduct/)
+
+## 有问题?
+
+如果你对本行为准则有任何疑问,请联系项目维护者。
+
+## 版本历史
+
+- **版本 1.0**(2026 年 1 月)- 初始行为准则
+
+---
+
+**感谢你帮助我们打造一个热情、包容且互相尊重的社区!** 🌟
diff --git a/zh/CONTRIBUTING.md b/zh/CONTRIBUTING.md
new file mode 100644
index 0000000..bffded9
--- /dev/null
+++ b/zh/CONTRIBUTING.md
@@ -0,0 +1,378 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+# 为 Claude How To 贡献内容
+
+感谢你愿意为这个项目做出贡献。这份指南会帮助你更高效地参与协作。
+
+## 关于本项目
+
+Claude How To 是一份面向 Claude Code 的可视化、以示例驱动的学习指南。我们提供:
+- **Mermaid 图表**,解释各项功能的工作方式
+- **可直接投入使用的模板**,你可以马上复制到项目中
+- **带上下文和最佳实践的真实案例**
+- **从入门到进阶的渐进式学习路径**
+
+## 贡献类型
+
+### 1. 新示例或新模板
+为已有功能补充示例,例如 slash commands、skills、hooks 等:
+- 可直接复制粘贴的代码
+- 清楚说明工作原理
+- 使用场景与收益
+- 排障提示
+
+### 2. 文档改进
+- 澄清容易混淆的内容
+- 修复拼写和语法问题
+- 补充缺失信息
+- 优化代码示例
+
+### 3. 功能指南
+为新的 Claude Code 功能编写指南:
+- 分步骤教程
+- 架构图
+- 常见模式和反模式
+- 真实工作流
+
+### 4. Bug 报告
+报告你遇到的问题:
+- 你原本期望发生什么
+- 实际发生了什么
+- 复现步骤
+- 相关的 Claude Code 版本和操作系统
+
+### 5. 反馈与建议
+帮助我们改进这份指南:
+- 建议更好的解释方式
+- 指出覆盖不足的地方
+- 推荐新章节或重组结构
+
+## 快速开始
+
+### 1. Fork 并克隆
+```bash
+git clone https://github.com/luongnv89/claude-howto.git
+cd claude-howto
+```
+
+### 2. 创建分支
+使用能说明用途的分支名:
+```bash
+git checkout -b add/feature-name
+git checkout -b fix/issue-description
+git checkout -b docs/improvement-area
+```
+
+### 3. 配置开发环境
+
+pre-commit hooks 会在本地、每次提交前运行与 CI 相同的检查。PR 被接受前,下面四项检查都必须通过。
+
+**必需依赖:**
+
+```bash
+# Python 工具链(uv 是本项目的包管理器)
+pip install uv
+uv venv
+source .venv/bin/activate
+uv pip install -r scripts/requirements-dev.txt
+
+# Markdown lint 工具(Node.js)
+npm install -g markdownlint-cli
+
+# Mermaid 图表校验器(Node.js)
+npm install -g @mermaid-js/mermaid-cli
+
+# 安装 pre-commit 并启用 hooks
+uv pip install pre-commit
+pre-commit install
+```
+
+**验证配置:**
+
+```bash
+pre-commit run --all-files
+```
+
+每次提交都会运行这些 hooks:
+
+| Hook | 检查内容 |
+|------|----------|
+| `markdown-lint` | Markdown 格式和结构 |
+| `cross-references` | 相对链接、锚点、代码围栏 |
+| `mermaid-syntax` | 所有 ` ```mermaid ` 代码块是否可正确解析 |
+| `link-check` | 外部 URL 是否可访问 |
+| `build-epub` | `.md` 变更时 EPUB 是否能无错误生成 |
+
+## 目录结构
+
+```
+├── 01-slash-commands/ # 用户手动触发的快捷命令
+├── 02-memory/ # 持久上下文示例
+├── 03-skills/ # 可复用能力
+├── 04-subagents/ # 专门化 AI 助手
+├── 05-mcp/ # Model Context Protocol 示例
+├── 06-hooks/ # 事件驱动自动化
+├── 07-plugins/ # 打包功能集合
+├── 08-checkpoints/ # 会话快照
+├── 09-advanced-features/ # 规划、思考、后台任务
+├── 10-cli/ # CLI 参考
+├── scripts/ # 构建与工具脚本
+└── README.md # 主指南
+```
+
+## 如何贡献示例
+
+### 添加 Slash Command
+1. 在 `01-slash-commands/` 中创建一个 `.md` 文件
+2. 包含:
+ - 清晰说明用途
+ - 使用场景
+ - 安装说明
+ - 使用示例
+ - 自定义技巧
+3. 更新 `01-slash-commands/README.md`
+
+### 添加 Skill
+1. 在 `03-skills/` 中创建一个目录
+2. 包含:
+ - `SKILL.md` - 主文档
+ - `scripts/` - 如有需要可放辅助脚本
+ - `templates/` - 提示词模板
+ - README 中的示例用法
+3. 更新 `03-skills/README.md`
+
+### 添加 Subagent
+1. 在 `04-subagents/` 中创建一个 `.md` 文件
+2. 包含:
+ - agent 的目标和能力
+ - 系统提示词结构
+ - 示例使用场景
+ - 集成示例
+3. 更新 `04-subagents/README.md`
+
+### 添加 MCP 配置
+1. 在 `05-mcp/` 中创建一个 `.json` 文件
+2. 包含:
+ - 配置说明
+ - 所需环境变量
+ - 配置步骤
+ - 使用示例
+3. 更新 `05-mcp/README.md`
+
+### 添加 Hook
+1. 在 `06-hooks/` 中创建一个 `.sh` 文件
+2. 包含:
+ - shebang 和说明
+ - 逻辑清晰的注释
+ - 错误处理
+ - 安全考虑
+3. 更新 `06-hooks/README.md`
+
+## 编写规范
+
+### Markdown 风格
+- 使用清晰的标题层级(章节用 H2,小节用 H3)
+- 段落保持简短且聚焦
+- 列表用项目符号
+- 代码块要标明语言
+- 各章节之间保留空行
+
+### 代码示例
+- 示例要能直接复制粘贴
+- 为不明显的逻辑添加注释
+- 同时提供简单版和进阶版
+- 展示真实使用场景
+- 标出可能的坑
+
+### 文档写作
+- 解释“为什么”,而不只是“是什么”
+- 包含前置条件
+- 添加排障章节
+- 链接相关主题
+- 保持对初学者友好
+
+### JSON/YAML
+- 统一缩进风格(2 或 4 个空格)
+- 为配置添加注释
+- 包含验证示例
+
+### 图表
+- 尽量使用 Mermaid
+- 保持图表简洁易读
+- 在图表下方补充说明
+- 链接到相关章节
+
+## Commit 规范
+
+使用 conventional commit 格式:
+```
+type(scope): description
+
+[optional body]
+```
+
+类型包括:
+- `feat`:新功能或新示例
+- `fix`:修复或更正
+- `docs`:文档变更
+- `refactor`:代码重构
+- `style`:格式调整
+- `test`:新增或修改测试
+- `chore`:构建、依赖等
+
+示例:
+```
+feat(slash-commands): Add API documentation generator
+docs(memory): Improve personal preferences example
+fix(README): Correct table of contents link
+docs(skills): Add comprehensive code review skill
+```
+
+## 提交前检查
+
+### 清单
+- [ ] 代码符合项目风格与约定
+- [ ] 新示例附带清晰文档
+- [ ] README 已更新(本地和根目录)
+- [ ] 不包含敏感信息(API key、凭据)
+- [ ] 示例经过测试并可运行
+- [ ] 链接已验证且正确
+- [ ] 文件权限正确(脚本可执行)
+- [ ] Commit 信息清晰且有描述性
+
+### 本地测试
+```bash
+# 运行所有 pre-commit 检查(与 CI 相同)
+pre-commit run --all-files
+
+# 查看改动
+git diff
+```
+
+## Pull Request 流程
+
+1. **创建带有清晰说明的 PR**:
+ - 这次提交做了什么?
+ - 为什么需要它?
+ - 是否有关联 issue?
+
+2. **补充相关细节**:
+ - 新功能?请说明使用场景
+ - 文档?请说明改进点
+ - 示例?展示前后对比
+
+3. **关联 issue**:
+ - 使用 `Closes #123` 自动关闭相关 issue
+
+4. **耐心等待审查**:
+ - 维护者可能会提出改进建议
+ - 根据反馈迭代
+ - 最终决定由维护者负责
+
+## Code Review 流程
+
+审查者会检查:
+- **准确性**:描述是否与实际一致?
+- **质量**:是否达到生产可用?
+- **一致性**:是否符合项目模式?
+- **文档**:是否清晰完整?
+- **安全性**:是否存在漏洞?
+
+## 报告问题
+
+### Bug 报告
+请包含:
+- Claude Code 版本
+- 操作系统
+- 复现步骤
+- 预期行为
+- 实际行为
+- 如有必要,附上截图
+
+### 功能请求
+请包含:
+- 使用场景或要解决的问题
+- 建议方案
+- 你考虑过的替代方案
+- 额外上下文
+
+### 文档问题
+请包含:
+- 哪里令人困惑或缺失
+- 建议如何改进
+- 示例或参考资料
+
+## 项目政策
+
+### 敏感信息
+- 永远不要提交 API key、token 或凭据
+- 示例中使用占位符
+- 为配置文件提供 `.env.example`
+- 文档中说明所需环境变量
+
+### 代码质量
+- 示例要聚焦且易读
+- 避免过度设计
+- 对不明显的逻辑添加注释
+- 提交前充分测试
+
+### 知识产权
+- 原创内容归作者所有
+- 项目采用教育用途许可证
+- 尊重已有版权
+- 需要时注明来源
+
+## 获取帮助
+
+- **提问**:在 GitHub Issues 中发起 discussion
+- **通用帮助**:先查看现有文档
+- **开发帮助**:参考类似示例
+- **Code Review**:在 PR 中 @ 维护者
+
+## 认可
+
+贡献者会被收录在:
+- `README.md` 的 Contributors 部分
+- GitHub contributors 页面
+- Commit 历史
+
+## 安全
+
+在贡献示例和文档时,请遵守安全编码实践:
+
+- **绝不要硬编码密钥或 API key** - 使用环境变量
+- **提示安全影响** - 标出潜在风险
+- **使用安全默认值** - 默认启用安全功能
+- **验证输入** - 展示正确的输入校验和清理方式
+- **加入安全提示** - 记录安全注意事项
+
+如遇安全问题,请参见 [SECURITY.md](SECURITY.md) 获取漏洞报告流程。
+
+## 行为准则
+
+我们承诺打造一个热情且包容的社区。请阅读 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 查看完整社区标准。
+
+简要来说:
+- 保持尊重和包容
+- 愉快地接受反馈
+- 帮助他人成长和学习
+- 避免骚扰或歧视
+- 向维护者报告问题
+
+所有贡献者都应遵守这份准则,并以善意和尊重对待彼此。
+
+## 许可证
+
+为本项目贡献内容,即表示你同意你的贡献将按 MIT License 许可。详情见 [LICENSE](LICENSE) 文件。
+
+## 有问题?
+
+- 查看 [README.md](README.md)
+- 阅读 [LEARNING-ROADMAP.md](LEARNING-ROADMAP.md)
+- 查看已有示例
+- 发起 issue 讨论
+
+感谢你的贡献!
diff --git a/zh/INDEX.md b/zh/INDEX.md
new file mode 100644
index 0000000..4f28844
--- /dev/null
+++ b/zh/INDEX.md
@@ -0,0 +1,900 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Claude Code 示例 - 完整索引
+
+这份文档是仓库里所有示例文件的完整索引,按功能类型整理,方便你快速定位需要的内容。
+
+## 概览统计
+
+- **总文件数**:100+ 文件
+- **分类数**:10 个功能分类
+- **插件**:3 个完整插件
+- **Skills**:6 个完整 skills
+- **Hooks**:8 个示例 hook
+- **可直接使用**:所有示例都可直接拿来用
+
+---
+
+## 01. Slash Commands(10 个文件)
+
+用于常见工作流的用户触发快捷命令。
+
+| 文件 | 说明 | 使用场景 |
+|------|------|----------|
+| `optimize.md` | 代码优化分析器 | 查找性能问题 |
+| `pr.md` | Pull Request 准备 | PR 工作流自动化 |
+| `generate-api-docs.md` | API 文档生成器 | 生成 API 文档 |
+| `commit.md` | 提交信息助手 | 统一提交风格 |
+| `setup-ci-cd.md` | CI/CD 流水线设置 | DevOps 自动化 |
+| `push-all.md` | 推送所有变更 | 快速推送工作流 |
+| `unit-test-expand.md` | 扩展单元测试覆盖率 | 测试自动化 |
+| `doc-refactor.md` | 文档重构 | 文档优化 |
+| `pr-slash-command.png` | 截图示例 | 视觉参考 |
+| `README.md` | 文档 | 安装与使用指南 |
+
+**安装路径**:`.claude/commands/`
+
+**使用方式**:`/optimize`、`/pr`、`/generate-api-docs`、`/commit`、`/setup-ci-cd`、`/push-all`、`/unit-test-expand`、`/doc-refactor`
+
+---
+
+## 02. Memory(6 个文件)
+
+持久化上下文和项目规范。
+
+| 文件 | 说明 | 范围 | 位置 |
+|------|------|------|------|
+| `project-CLAUDE.md` | 团队项目规范 | 整个项目 | `./CLAUDE.md` |
+| `directory-api-CLAUDE.md` | API 专用规则 | 目录级 | `./src/api/CLAUDE.md` |
+| `personal-CLAUDE.md` | 个人偏好 | 用户级 | `~/.claude/CLAUDE.md` |
+| `memory-saved.png` | 截图:记忆已保存 | - | 视觉参考 |
+| `memory-ask-claude.png` | 截图:询问 Claude | - | 视觉参考 |
+| `README.md` | 文档 | - | 参考说明 |
+
+**安装方式**:复制到对应位置
+
+**使用方式**:Claude 会自动加载
+
+---
+
+## 03. Skills(28 个文件)
+
+带脚本和模板的自动触发能力。
+
+### 代码审查 Skill(5 个文件)
+
+```text
+code-review/
+├── SKILL.md # Skill 定义
+├── scripts/
+│ ├── analyze-metrics.py # 代码指标分析器
+│ └── compare-complexity.py # 复杂度对比
+└── templates/
+ ├── review-checklist.md # 审查清单
+ └── finding-template.md # 问题记录模板
+```
+
+**用途**:结合安全、性能和质量分析的完整代码审查
+
+**自动触发**:在审查代码时
+
+### 品牌语气 Skill(4 个文件)
+
+```text
+brand-voice/
+├── SKILL.md # Skill 定义
+├── templates/
+│ ├── email-template.txt # 邮件格式
+│ └── social-post-template.txt # 社交媒体格式
+└── tone-examples.md # 示例消息
+```
+
+**用途**:确保对外沟通中的品牌语气一致
+
+**自动触发**:在编写营销文案时
+
+### 文档生成 Skill(2 个文件)
+
+```text
+doc-generator/
+├── SKILL.md # Skill 定义
+└── generate-docs.py # Python 文档提取器
+```
+
+**用途**:从源代码生成完整的 API 文档
+
+**自动触发**:在创建或更新 API 文档时
+
+### 重构 Skill(5 个文件)
+
+```text
+refactor/
+├── SKILL.md # Skill 定义
+├── scripts/
+│ ├── analyze-complexity.py # 复杂度分析器
+│ └── detect-smells.py # 代码异味检测器
+├── references/
+│ ├── code-smells.md # 代码异味目录
+│ └── refactoring-catalog.md # 重构模式目录
+└── templates/
+ └── refactoring-plan.md # 重构计划模板
+```
+
+**用途**:结合复杂度分析进行系统化代码重构
+
+**自动触发**:在重构代码时
+
+### Claude MD Skill(1 个文件)
+
+```text
+claude-md/
+└── SKILL.md # Skill 定义
+```
+
+**用途**:管理和优化 `CLAUDE.md` 文件
+
+### 博客草稿 Skill(3 个文件)
+
+```text
+blog-draft/
+├── SKILL.md # Skill 定义
+└── templates/
+ ├── draft-template.md # 博客草稿模板
+ └── outline-template.md # 博客大纲模板
+```
+
+**用途**:生成结构统一的博客草稿
+
+**补充**:`README.md` - Skills 总览与使用指南
+
+**安装路径**:`~/.claude/skills/` 或 `.claude/skills/`
+
+---
+
+## 04. Subagents(9 个文件)
+
+带自定义能力的专门化 AI 助手。
+
+| 文件 | 说明 | 工具 | 使用场景 |
+|------|------|------|----------|
+| `code-reviewer.md` | 代码质量分析 | read, grep, diff, lint_runner | 完整审查 |
+| `test-engineer.md` | 测试覆盖分析 | read, write, bash, grep | 测试自动化 |
+| `documentation-writer.md` | 文档创建 | read, write, grep | 文档生成 |
+| `secure-reviewer.md` | 安全审查(只读) | read, grep | 安全审计 |
+| `implementation-agent.md` | 完整实现 | read, write, bash, grep, edit, glob | 功能开发 |
+| `debugger.md` | 调试专家 | read, bash, grep | Bug 排查 |
+| `data-scientist.md` | 数据分析专家 | read, write, bash | 数据工作流 |
+| `clean-code-reviewer.md` | 代码整洁性规范 | read, grep | 代码质量 |
+| `README.md` | 文档 | - | 安装与使用指南 |
+
+**安装路径**:`.claude/agents/`
+
+**使用方式**:由主 agent 自动委派
+
+---
+
+## 05. MCP Protocol(5 个文件)
+
+外部工具和 API 集成。
+
+| 文件 | 说明 | 集成对象 | 使用场景 |
+|------|------|----------|----------|
+| `github-mcp.json` | GitHub 集成 | GitHub API | PR / issue 管理 |
+| `database-mcp.json` | 数据库查询 | PostgreSQL / MySQL | 实时数据查询 |
+| `filesystem-mcp.json` | 文件操作 | 本地文件系统 | 文件管理 |
+| `multi-mcp.json` | 多服务器配置 | GitHub + DB + Slack | 完整集成 |
+| `README.md` | 文档 | - | 安装与使用指南 |
+
+**安装路径**:项目级 `.mcp.json` 或用户级 `~/.claude.json`
+
+**使用方式**:例如 `/mcp__github__list_prs`
+
+---
+
+## 06. Hooks(9 个文件)
+
+事件驱动的自动化脚本,会自动执行。
+
+| 文件 | 说明 | 事件 | 使用场景 |
+|------|------|------|----------|
+| `format-code.sh` | 自动格式化代码 | `PreToolUse:Write` | 代码格式化 |
+| `pre-commit.sh` | 提交前运行测试 | `PreToolUse:Bash` | 测试自动化 |
+| `security-scan.sh` | 安全扫描 | `PostToolUse:Write` | 安全检查 |
+| `log-bash.sh` | 记录 bash 命令 | `PostToolUse:Bash` | 命令日志 |
+| `validate-prompt.sh` | 验证提示词 | `PreToolUse` | 输入校验 |
+| `notify-team.sh` | 发送通知 | `Notification` | 团队通知 |
+| `context-tracker.py` | 跟踪上下文窗口使用量 | `PostToolUse` | 上下文监控 |
+| `context-tracker-tiktoken.py` | 基于 token 的上下文跟踪 | `PostToolUse` | 精确 token 统计 |
+| `README.md` | 文档 | - | 安装与使用指南 |
+
+**安装路径**:在 `~/.claude/settings.json` 中配置
+
+**使用方式**:在设置中配置后自动执行
+
+**Hook 类型**(4 类,25 个事件):
+- 工具 Hook:`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`
+- 会话 Hook:`SessionStart`、`SessionEnd`、`Stop`、`StopFailure`、`SubagentStart`、`SubagentStop`
+- 任务 Hook:`UserPromptSubmit`、`TaskCompleted`、`TaskCreated`、`TeammateIdle`
+- 生命周期 Hook:`ConfigChange`、`CwdChanged`、`FileChanged`、`PreCompact`、`PostCompact`、`WorktreeCreate`、`WorktreeRemove`、`Notification`、`InstructionsLoaded`、`Elicitation`、`ElicitationResult`
+
+---
+
+## 07. Plugins(3 个完整插件,40 个文件)
+
+打包好的功能集合。
+
+### PR Review 插件(10 个文件)
+
+```text
+pr-review/
+├── .claude-plugin/
+│ └── plugin.json # 插件清单
+├── commands/
+│ ├── review-pr.md # 综合审查
+│ ├── check-security.md # 安全检查
+│ └── check-tests.md # 测试覆盖检查
+├── agents/
+│ ├── security-reviewer.md # 安全专家
+│ ├── test-checker.md # 测试专家
+│ └── performance-analyzer.md # 性能专家
+├── mcp/
+│ └── github-config.json # GitHub 集成
+├── hooks/
+│ └── pre-review.js # 审查前校验
+└── README.md # 插件文档
+```
+
+**功能**:安全分析、测试覆盖、性能影响
+
+**命令**:`/review-pr`、`/check-security`、`/check-tests`
+
+**安装**:`/plugin install pr-review`
+
+### DevOps Automation 插件(15 个文件)
+
+```text
+devops-automation/
+├── .claude-plugin/
+│ └── plugin.json # 插件清单
+├── commands/
+│ ├── deploy.md # 部署
+│ ├── rollback.md # 回滚
+│ ├── status.md # 系统状态
+│ └── incident.md # 事件响应
+├── agents/
+│ ├── deployment-specialist.md # 部署专家
+│ ├── incident-commander.md # 事件协调
+│ └── alert-analyzer.md # 告警分析
+├── mcp/
+│ └── kubernetes-config.json # Kubernetes 集成
+├── hooks/
+│ ├── pre-deploy.js # 部署前检查
+│ └── post-deploy.js # 部署后任务
+├── scripts/
+│ ├── deploy.sh # 部署自动化
+│ ├── rollback.sh # 回滚自动化
+│ └── health-check.sh # 健康检查
+└── README.md # 插件文档
+```
+
+**功能**:Kubernetes 部署、回滚、监控、事件响应
+
+**命令**:`/deploy`、`/rollback`、`/status`、`/incident`
+
+**安装**:`/plugin install devops-automation`
+
+### Documentation 插件(14 个文件)
+
+```text
+documentation/
+├── .claude-plugin/
+│ └── plugin.json # 插件清单
+├── commands/
+│ ├── generate-api-docs.md # API 文档生成
+│ ├── generate-readme.md # README 创建
+│ ├── sync-docs.md # 文档同步
+│ └── validate-docs.md # 文档校验
+├── agents/
+│ ├── api-documenter.md # API 文档专家
+│ ├── code-commentator.md # 代码注释专家
+│ └── example-generator.md # 示例生成器
+├── mcp/
+│ └── github-docs-config.json # GitHub 集成
+├── templates/
+│ ├── api-endpoint.md # API 端点模板
+│ ├── function-docs.md # 函数文档模板
+│ └── adr-template.md # ADR 模板
+└── README.md # 插件文档
+```
+
+**功能**:API 文档、README 生成、文档同步、文档校验
+
+**命令**:`/generate-api-docs`、`/generate-readme`、`/sync-docs`、`/validate-docs`
+
+**安装**:`/plugin install documentation`
+
+**补充**:`README.md` - 插件总览与使用指南
+
+---
+
+## 08. Checkpoints and Rewind(2 个文件)
+
+保存会话状态,并探索替代方案。
+
+| 文件 | 说明 | 内容 |
+|------|------|------|
+| `README.md` | 文档 | 完整的 checkpoint 指南 |
+| `checkpoint-examples.md` | 真实示例 | 数据库迁移、性能优化、UI 迭代、调试 |
+
+**核心概念**:
+- **Checkpoint**:会话状态快照
+- **Rewind**:回到之前的 checkpoint
+- **Branch Point**:探索多种方案
+
+**使用方式**:
+
+```bash
+# 每次用户提示后都会自动创建 checkpoint
+# 如需回退,按两次 Esc,或使用:
+/rewind
+# 然后选择:恢复代码和对话、恢复对话、
+# 恢复代码、从这里开始总结,或算了
+```
+
+**使用场景**:
+- 尝试不同实现方式
+- 从错误中恢复
+- 安全试验
+- 比较不同方案
+- A/B 测试
+
+---
+
+## 09. Advanced Features(3 个文件)
+
+复杂工作流下的高级能力。
+
+| 文件 | 说明 | 功能 |
+|------|------|------|
+| `README.md` | 完整指南 | 全部高级功能说明 |
+| `config-examples.json` | 配置示例 | 10+ 个场景化配置 |
+| `planning-mode-examples.md` | 规划示例 | REST API、数据库迁移、重构 |
+
+**扩展功能**:
+- Scheduled Tasks:使用 `/loop` 和 cron 工具的周期任务
+- Chrome Integration:通过无头 Chromium 做浏览器自动化
+- Remote Control(扩展版):连接方式、安全性、对比表
+- Keyboard Customization:自定义快捷键、组合键支持、上下文
+- Desktop App(扩展版):连接器、`launch.json`、企业功能
+
+### 已覆盖的高级功能
+
+#### Planning Mode
+- 编写详细实现计划
+- 时间预估与风险评估
+- 系统化拆解任务
+
+#### Extended Thinking
+- 面向复杂问题的深度推理
+- 架构决策分析
+- 权衡取舍评估
+
+#### Background Tasks
+- 长时间运行且不阻塞当前会话
+- 并行开发工作流
+- 任务管理与监控
+
+#### Permission Modes
+- **default**:风险操作需要审批
+- **acceptEdits**:自动接受文件编辑,其他操作仍需审批
+- **plan**:只读分析,不做修改
+- **auto**:自动批准安全操作,风险操作仍提示
+- **dontAsk**:除危险操作外全部接受
+- **bypassPermissions**:全部接受(需要 `--dangerously-skip-permissions`)
+
+#### Headless Mode(`claude -p`)
+- CI/CD 集成
+- 自动化任务执行
+- 批处理
+
+#### Session Management
+- 多会话管理
+- 会话切换与保存
+- 会话持久化
+
+#### 交互功能
+- 键盘快捷键
+- 命令历史
+- Tab 补全
+- 多行输入
+
+#### 配置
+- 完整设置管理
+- 环境相关配置
+- 按项目定制
+
+#### Scheduled Tasks
+- 使用 `/loop` 创建周期任务
+- Cron 工具:`CronCreate`、`CronList`、`CronDelete`
+- 自动化的重复工作流
+
+#### Chrome Integration
+- 通过无头 Chromium 进行浏览器自动化
+- 页面测试与抓取能力
+- 页面交互与数据提取
+
+#### Remote Control(扩展版)
+- 连接方式与协议
+- 安全注意事项与最佳实践
+- 远程访问方案对比表
+
+#### Keyboard Customization
+- 自定义按键绑定配置
+- 支持多键组合快捷键
+- 基于上下文的按键激活
+
+#### Desktop App(扩展版)
+- 用于 IDE 集成的连接器
+- `launch.json` 配置
+- 企业功能与部署
+
+---
+
+## 10. CLI Usage(1 个文件)
+
+命令行界面使用方式与参考。
+
+| 文件 | 说明 | 内容 |
+|------|------|------|
+| `README.md` | CLI 文档 | 参数、选项与使用模式 |
+
+**核心 CLI 功能**:
+- `claude` - 启动交互式会话
+- `claude -p "prompt"` - 无头/非交互模式
+- `claude web` - 打开 Web 会话
+- `claude --model` - 选择模型(Sonnet 4.6、Opus 4.6)
+- `claude --permission-mode` - 设置权限模式
+- `claude --remote` - 通过 WebSocket 启用远程控制
+
+---
+
+## 文档文件(13 个文件)
+
+| 文件 | 位置 | 说明 |
+|------|------|------|
+| `README.md` | `/` | 主总览 |
+| `INDEX.md` | `/` | 本完整索引 |
+| `QUICK_REFERENCE.md` | `/` | 速查卡片 |
+| `README.md` | `/01-slash-commands/` | Slash Commands 指南 |
+| `README.md` | `/02-memory/` | Memory 指南 |
+| `README.md` | `/03-skills/` | Skills 指南 |
+| `README.md` | `/04-subagents/` | Subagents 指南 |
+| `README.md` | `/05-mcp/` | MCP 指南 |
+| `README.md` | `/06-hooks/` | Hooks 指南 |
+| `README.md` | `/07-plugins/` | Plugins 指南 |
+| `README.md` | `/08-checkpoints/` | Checkpoints 指南 |
+| `README.md` | `/09-advanced-features/` | Advanced Features 指南 |
+| `README.md` | `/10-cli/` | CLI 指南 |
+
+---
+
+## 完整文件树
+
+```text
+claude-howto/
+├── README.md # 主总览
+├── INDEX.md # 本文件
+├── QUICK_REFERENCE.md # 速查卡片
+├── claude_concepts_guide.md # 原始指南
+│
+├── 01-slash-commands/ # Slash Commands
+│ ├── optimize.md
+│ ├── pr.md
+│ ├── generate-api-docs.md
+│ ├── commit.md
+│ ├── setup-ci-cd.md
+│ ├── push-all.md
+│ ├── unit-test-expand.md
+│ ├── doc-refactor.md
+│ ├── pr-slash-command.png
+│ └── README.md
+│
+├── 02-memory/ # Memory
+│ ├── project-CLAUDE.md
+│ ├── directory-api-CLAUDE.md
+│ ├── personal-CLAUDE.md
+│ ├── memory-saved.png
+│ ├── memory-ask-claude.png
+│ └── README.md
+│
+├── 03-skills/ # Skills
+│ ├── code-review/
+│ │ ├── SKILL.md
+│ │ ├── scripts/
+│ │ │ ├── analyze-metrics.py
+│ │ │ └── compare-complexity.py
+│ │ └── templates/
+│ │ ├── review-checklist.md
+│ │ └── finding-template.md
+│ ├── brand-voice/
+│ │ ├── SKILL.md
+│ │ ├── templates/
+│ │ │ ├── email-template.txt
+│ │ │ └── social-post-template.txt
+│ │ └── tone-examples.md
+│ ├── doc-generator/
+│ │ ├── SKILL.md
+│ │ └── generate-docs.py
+│ ├── refactor/
+│ │ ├── SKILL.md
+│ │ ├── scripts/
+│ │ │ ├── analyze-complexity.py
+│ │ │ └── detect-smells.py
+│ │ ├── references/
+│ │ │ ├── code-smells.md
+│ │ │ └── refactoring-catalog.md
+│ │ └── templates/
+│ │ └── refactoring-plan.md
+│ ├── claude-md/
+│ │ └── SKILL.md
+│ ├── blog-draft/
+│ │ ├── SKILL.md
+│ │ └── templates/
+│ │ ├── draft-template.md
+│ │ └── outline-template.md
+│ └── README.md
+│
+├── 04-subagents/ # Subagents
+│ ├── code-reviewer.md
+│ ├── test-engineer.md
+│ ├── documentation-writer.md
+│ ├── secure-reviewer.md
+│ ├── implementation-agent.md
+│ ├── debugger.md
+│ ├── data-scientist.md
+│ ├── clean-code-reviewer.md
+│ └── README.md
+│
+├── 05-mcp/ # MCP Protocol
+│ ├── github-mcp.json
+│ ├── database-mcp.json
+│ ├── filesystem-mcp.json
+│ ├── multi-mcp.json
+│ └── README.md
+│
+├── 06-hooks/ # Hooks
+│ ├── format-code.sh
+│ ├── pre-commit.sh
+│ ├── security-scan.sh
+│ ├── log-bash.sh
+│ ├── validate-prompt.sh
+│ ├── notify-team.sh
+│ ├── context-tracker.py
+│ ├── context-tracker-tiktoken.py
+│ └── README.md
+│
+├── 07-plugins/ # Plugins
+│ ├── pr-review/
+│ │ ├── .claude-plugin/
+│ │ │ └── plugin.json
+│ │ ├── commands/
+│ │ │ ├── review-pr.md
+│ │ │ ├── check-security.md
+│ │ │ └── check-tests.md
+│ │ ├── agents/
+│ │ │ ├── security-reviewer.md
+│ │ │ ├── test-checker.md
+│ │ │ └── performance-analyzer.md
+│ │ ├── mcp/
+│ │ │ └── github-config.json
+│ │ ├── hooks/
+│ │ │ └── pre-review.js
+│ │ └── README.md
+│ ├── devops-automation/
+│ │ ├── .claude-plugin/
+│ │ │ └── plugin.json
+│ │ ├── commands/
+│ │ │ ├── deploy.md
+│ │ │ ├── rollback.md
+│ │ │ ├── status.md
+│ │ │ └── incident.md
+│ │ ├── agents/
+│ │ │ ├── deployment-specialist.md
+│ │ │ ├── incident-commander.md
+│ │ │ └── alert-analyzer.md
+│ │ ├── mcp/
+│ │ │ └── kubernetes-config.json
+│ │ ├── hooks/
+│ │ │ ├── pre-deploy.js
+│ │ │ └── post-deploy.js
+│ │ ├── scripts/
+│ │ │ ├── deploy.sh
+│ │ │ ├── rollback.sh
+│ │ │ └── health-check.sh
+│ │ └── README.md
+│ ├── documentation/
+│ │ ├── .claude-plugin/
+│ │ │ └── plugin.json
+│ │ ├── commands/
+│ │ │ ├── generate-api-docs.md
+│ │ │ ├── generate-readme.md
+│ │ │ ├── sync-docs.md
+│ │ │ └── validate-docs.md
+│ │ ├── agents/
+│ │ │ ├── api-documenter.md
+│ │ │ ├── code-commentator.md
+│ │ │ └── example-generator.md
+│ │ ├── mcp/
+│ │ │ └── github-docs-config.json
+│ │ ├── templates/
+│ │ │ ├── api-endpoint.md
+│ │ │ ├── function-docs.md
+│ │ │ └── adr-template.md
+│ │ └── README.md
+│ └── README.md
+│
+├── 08-checkpoints/ # Checkpoints
+│ ├── checkpoint-examples.md
+│ └── README.md
+│
+├── 09-advanced-features/ # Advanced Features
+│ ├── config-examples.json
+│ ├── planning-mode-examples.md
+│ └── README.md
+│
+└── 10-cli/ # CLI 使用
+ └── README.md
+```
+
+---
+
+## 按使用场景快速开始
+
+### 代码质量与审查
+
+```bash
+# 安装 slash command
+cp 01-slash-commands/optimize.md .claude/commands/
+
+# 安装 subagent
+cp 04-subagents/code-reviewer.md .claude/agents/
+
+# 安装 skill
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# 或直接安装完整插件
+/plugin install pr-review
+```
+
+### DevOps 与部署
+
+```bash
+# 安装插件(包含全部功能)
+/plugin install devops-automation
+```
+
+### 文档
+
+```bash
+# 安装 slash command
+cp 01-slash-commands/generate-api-docs.md .claude/commands/
+
+# 安装 subagent
+cp 04-subagents/documentation-writer.md .claude/agents/
+
+# 安装 skill
+cp -r 03-skills/doc-generator ~/.claude/skills/
+
+# 或直接安装完整插件
+/plugin install documentation
+```
+
+### 团队规范
+
+```bash
+# 设置项目 memory
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+
+# 根据团队规范调整内容
+```
+
+### 外部集成
+
+```bash
+# 设置环境变量
+export GITHUB_TOKEN="your_token"
+export DATABASE_URL="postgresql://..."
+
+# 安装 MCP 配置(项目级)
+cp 05-mcp/multi-mcp.json .mcp.json
+```
+
+### 自动化与校验
+
+```bash
+# 安装 hooks
+mkdir -p ~/.claude/hooks
+cp 06-hooks/*.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/*.sh
+
+# 在 settings 中配置 hooks(~/.claude/settings.json)
+# 参见 06-hooks/README.md
+```
+
+### 安全实验
+
+```bash
+# 每次用户提示后都会自动创建 checkpoint
+# 回退:按 Esc 两次或使用 /rewind
+# 然后选择要从回退菜单中恢复的内容
+
+# 参见 08-checkpoints/README.md 的示例
+```
+
+### 高级工作流
+
+```bash
+# 配置高级功能
+# 参见 09-advanced-features/config-examples.json
+
+# 使用 planning mode
+/plan 实现功能 X
+
+# 使用权限模式
+claude --permission-mode plan # 用于代码审查(只读)
+claude --permission-mode acceptEdits # 自动接受编辑
+claude --permission-mode auto # 自动批准安全操作
+
+# 以 headless 模式运行 CI/CD
+claude -p "Run tests and report results"
+
+# 运行后台任务
+在后台运行测试
+
+# 参见 09-advanced-features/README.md 获取完整指南
+```
+
+---
+
+## 功能覆盖矩阵
+
+| 分类 | Commands | Agents | MCP | Hooks | Scripts | Templates | Docs | Images | 总计 |
+|------|----------|--------|-----|-------|---------|-----------|------|--------|------|
+| **01 Slash Commands** | 8 | - | - | - | - | - | 1 | 1 | **10** |
+| **02 Memory** | - | - | - | - | - | 3 | 1 | 2 | **6** |
+| **03 Skills** | - | - | - | - | 5 | 9 | 1 | - | **28** |
+| **04 Subagents** | - | 8 | - | - | - | - | 1 | - | **9** |
+| **05 MCP** | - | - | 4 | - | - | - | 1 | - | **5** |
+| **06 Hooks** | - | - | - | 8 | - | - | 1 | - | **9** |
+| **07 Plugins** | 11 | 9 | 3 | 3 | 3 | 3 | 4 | - | **40** |
+| **08 Checkpoints** | - | - | - | - | - | - | 1 | 1 | **2** |
+| **09 Advanced** | - | - | - | - | - | - | 1 | 2 | **3** |
+| **10 CLI** | - | - | - | - | - | - | 1 | - | **1** |
+
+---
+
+## 学习路径
+
+### 入门(第 1 周)
+
+1. ✅ 阅读 `README.md`
+2. ✅ 安装 1 到 2 个 slash command
+3. ✅ 创建项目 memory 文件
+4. ✅ 试用基础命令
+
+### 中级(第 2-3 周)
+
+1. ✅ 搭建 GitHub MCP
+2. ✅ 安装一个 subagent
+3. ✅ 尝试委派任务
+4. ✅ 安装一个 skill
+
+### 高级(第 4 周及以后)
+
+1. ✅ 安装完整插件
+2. ✅ 创建自定义 slash command
+3. ✅ 创建自定义 subagent
+4. ✅ 创建自定义 skill
+5. ✅ 构建自己的插件
+
+### 专家(第 5 周及以后)
+
+1. ✅ 配置 hooks 做自动化
+2. ✅ 用 checkpoints 做实验
+3. ✅ 配置 planning mode
+4. ✅ 充分利用权限模式
+5. ✅ 为 CI/CD 配置 headless mode
+6. ✅ 熟练掌握会话管理
+
+---
+
+## 按关键词查找
+
+### 性能
+
+- `01-slash-commands/optimize.md` - 性能分析
+- `04-subagents/code-reviewer.md` - 性能审查
+- `03-skills/code-review/` - 性能指标
+- `07-plugins/pr-review/agents/performance-analyzer.md` - 性能专家
+
+### 安全
+
+- `04-subagents/secure-reviewer.md` - 安全审查
+- `03-skills/code-review/` - 安全分析
+- `07-plugins/pr-review/` - 安全检查
+
+### 测试
+
+- `04-subagents/test-engineer.md` - 测试工程师
+- `07-plugins/pr-review/commands/check-tests.md` - 测试覆盖率
+
+### 文档
+
+- `01-slash-commands/generate-api-docs.md` - API 文档命令
+- `04-subagents/documentation-writer.md` - 文档编写 agent
+- `03-skills/doc-generator/` - 文档生成 skill
+- `07-plugins/documentation/` - 完整文档插件
+
+### 部署
+
+- `07-plugins/devops-automation/` - 完整 DevOps 方案
+
+### 自动化
+
+- `06-hooks/` - 事件驱动自动化
+- `06-hooks/pre-commit.sh` - 提交前自动化
+- `06-hooks/format-code.sh` - 自动格式化
+- `09-advanced-features/` - headless 模式用于 CI/CD
+
+### 校验
+
+- `06-hooks/security-scan.sh` - 安全校验
+- `06-hooks/validate-prompt.sh` - 提示词校验
+
+### 实验
+
+- `08-checkpoints/` - 使用 rewind 做安全实验
+- `08-checkpoints/checkpoint-examples.md` - 真实示例
+
+### 规划
+
+- `09-advanced-features/planning-mode-examples.md` - 规划模式示例
+- `09-advanced-features/README.md` - 深度思考
+
+### 配置
+
+- `09-advanced-features/config-examples.json` - 配置示例
+
+---
+
+## 说明
+
+- 所有示例都可直接使用
+- 按需修改以适配你的项目
+- 示例遵循 Claude Code 最佳实践
+- 每个分类都有自己的 README,包含详细说明
+- 脚本包含正确的错误处理
+- 模板都可自定义
+
+---
+
+## 参与贡献
+
+如果你想增加更多示例,可以按照下面的结构:
+1. 创建合适的子目录
+2. 包含带使用说明的 README.md
+3. 遵循命名规范
+4. 充分测试
+5. 更新这个索引
+
+---
+
+**最后更新**:2026 年 3 月
+**总示例数**:100+ 文件
+**分类数**:10 个功能
+**Hooks**:8 个自动化脚本
+**配置示例**:10+ 个场景
+**可直接使用**:所有示例
diff --git a/zh/LEARNING-ROADMAP.md b/zh/LEARNING-ROADMAP.md
new file mode 100644
index 0000000..ee333b7
--- /dev/null
+++ b/zh/LEARNING-ROADMAP.md
@@ -0,0 +1,725 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+# 📚 Claude Code 学习路线图
+
+**刚接触 Claude Code?** 这份指南会帮你按照自己的节奏掌握 Claude Code 的各项功能。无论你是完全新手,还是经验丰富的开发者,都可以先做下面的自我评估测验,找到最适合自己的起点。
+
+---
+
+<a id="find-your-level"></a>
+## 🧭 找到你的水平
+
+每个人的起点都不同。先做一份快速自我评估,确认最适合你的入口。
+
+**请诚实回答下面的问题:**
+
+- [ ] 我可以启动 Claude Code 并与它对话(`claude`)
+- [ ] 我创建或编辑过 `CLAUDE.md`
+- [ ] 我至少使用过 3 个内置 slash command(例如 `/help`、`/compact`、`/model`)
+- [ ] 我创建过自定义 slash command 或 skill(`SKILL.md`)
+- [ ] 我配置过 MCP server(例如 GitHub、数据库)
+- [ ] 我在 `~/.claude/settings.json` 中设置过 hooks
+- [ ] 我创建或使用过自定义 subagents(`.claude/agents/`)
+- [ ] 我使用过 print mode(`claude -p`)做脚本或 CI/CD
+
+**你的水平:**
+
+| 勾选数 | 水平 | 从这里开始 | 完成时间 |
+|--------|-------|----------|------------------|
+| 0-2 | **Level 1:Beginner** - 从这里开始 | [里程碑 1A](#里程碑-1a第一个命令与-memory) | 约 3 小时 |
+| 3-5 | **Level 2:Intermediate** - 构建工作流 | [里程碑 2A](#里程碑-2a自动化skills--hooks) | 约 5 小时 |
+| 6-8 | **Level 3:Advanced** - 高阶用户与团队负责人 | [里程碑 3A](#里程碑-3a高级功能) | 约 5 小时 |
+
+> **提示**:如果不确定,宁可从低一级开始。先回顾熟悉内容,总比漏掉基础概念更划算。
+
+> **交互式版本**:在 Claude Code 中运行 `/self-assessment`,就能得到一份引导式、交互式测验,会覆盖全部 10 个功能领域,并生成个性化学习路径。
+
+---
+
+## 🎯 学习理念
+
+本仓库里的文件夹是按照**推荐学习顺序**编号的,背后有 3 个原则:
+
+1. **依赖关系** - 先学基础概念
+2. **复杂度** - 先学简单功能,再学高级功能
+3. **使用频率** - 先学最常用的功能
+
+这样可以让你一边建立扎实基础,一边尽快获得实际收益。
+
+---
+
+## 🗺️ 你的学习路径
+
+```mermaid
+graph TD
+ Q["🧭 自我评估测验<br/>找到你的水平"] --> L1
+ Q --> L2
+ Q --> L3
+
+ subgraph L1["🟢 Level 1:Beginner - 从这里开始"]
+ direction LR
+ A["1A:第一个命令与 Memory<br/>Slash Commands + Memory"] --> B["1B:安全探索<br/>Checkpoints + CLI Basics"]
+ end
+
+ subgraph L2["🔵 Level 2:Intermediate - 构建工作流"]
+ direction LR
+ C["2A:自动化<br/>Skills + Hooks"] --> D["2B:集成<br/>MCP + Subagents"]
+ end
+
+ subgraph L3["🔴 Level 3:Advanced - 高阶用户"]
+ direction LR
+ E["3A:高级功能<br/>Planning + Permissions"] --> F["3B:团队与分发<br/>Plugins + CLI 精通"]
+ end
+
+ L1 --> L2
+ L2 --> L3
+
+ style Q fill:#6A1B9A,color:#fff,stroke:#9C27B0,stroke-width:2px
+ style A fill:#2E7D32,color:#fff
+ style B fill:#2E7D32,color:#fff
+ style C fill:#1565C0,color:#fff
+ style D fill:#F57C00,color:#fff
+ style E fill:#C62828,color:#fff
+ style F fill:#B71C1C,color:#fff
+```
+
+**颜色说明:**
+- 💜 紫色:自我评估测验
+- 🟢 绿色:Level 1 - Beginner 路线
+- 🔵 蓝色 / 🟡 金色:Level 2 - Intermediate 路线
+- 🔴 红色:Level 3 - Advanced 路线
+
+---
+
+## 📊 完整路线图表
+
+| 步骤 | 功能 | 复杂度 | 时间 | 水平 | 依赖 | 为什么学它 | 关键收益 |
+|------|---------|-----------|------|-------|--------------|----------------|--------------|
+| **1** | [Slash Commands](01-slash-commands/README.md) | ⭐ Beginner | 30 分钟 | Level 1 | 无 | 快速获得生产力提升(55+ 内置命令 + 5 个 bundled skills) | 立即自动化、统一团队规范 |
+| **2** | [Memory](02-memory/README.md) | ⭐⭐ Beginner+ | 45 分钟 | Level 1 | 无 | 所有功能的基础 | 持久上下文、偏好设置 |
+| **3** | [Checkpoints](08-checkpoints/README.md) | ⭐⭐ Intermediate | 45 分钟 | Level 1 | 会话管理 | 安全探索 | 试验、恢复 |
+| **4** | [CLI Basics](10-cli/README.md) | ⭐⭐ Beginner+ | 30 分钟 | Level 1 | 无 | 核心 CLI 用法 | 交互式与 print mode |
+| **5** | [Skills](03-skills/README.md) | ⭐⭐ Intermediate | 1 小时 | Level 2 | Slash Commands | 自动化专业能力 | 可复用能力、一致性 |
+| **6** | [Hooks](06-hooks/README.md) | ⭐⭐ Intermediate | 1 小时 | Level 2 | 工具、命令 | 工作流自动化(25 个事件、4 种类型) | 校验、质量门禁 |
+| **7** | [MCP](05-mcp/README.md) | ⭐⭐⭐ Intermediate+ | 1 小时 | Level 2 | 配置 | 实时数据访问 | 实时集成、API |
+| **8** | [Subagents](04-subagents/README.md) | ⭐⭐⭐ Intermediate+ | 1.5 小时 | Level 2 | Memory、命令 | 处理复杂任务(包含 Bash 在内的 6 个内置 agent) | 委派、专业分工 |
+| **9** | [Advanced Features](09-advanced-features/README.md) | ⭐⭐⭐⭐⭐ Advanced | 2-3 小时 | Level 3 | 前面所有内容 | 高阶工具 | Planning、自动模式(Auto Mode)、通道(Channels)、语音输入、权限控制 |
+| **10** | [Plugins](07-plugins/README.md) | ⭐⭐⭐⭐ Advanced | 2 小时 | Level 3 | 前面所有内容 | 完整解决方案 | 团队入职、分发 |
+| **11** | [CLI Mastery](10-cli/README.md) | ⭐⭐⭐ Advanced | 1 小时 | Level 3 | 建议:全部 | 掌握命令行用法 | 脚本、CI/CD、自动化 |
+
+**总学习时间**:约 11-13 小时(或者直接跳到你的水平,节省时间)
+
+---
+
+## 🟢 Level 1:Beginner - 从这里开始
+
+**适合**:测验勾选数 0-2
+**时间**:约 3 小时
+**重点**:立刻提升生产力,理解基础概念
+**结果**:可以熟练日常使用,并准备进入 Level 2
+
+<a id="milestone-1a-first-commands-memory"></a>
+### 里程碑 1A:第一个命令与 Memory
+
+**主题**:Slash Commands + Memory
+**时间**:1-2 小时
+**复杂度**:⭐ Beginner
+**目标**:通过自定义命令和持久上下文,快速提升效率
+
+#### 你将完成什么
+✅ 为重复性任务创建自定义 slash commands
+✅ 为团队规范设置项目 memory
+✅ 配置个人偏好
+✅ 理解 Claude 如何自动加载上下文
+
+#### 实战练习
+
+```bash
+# 练习 1:安装你的第一个 slash command
+mkdir -p .claude/commands
+cp 01-slash-commands/optimize.md .claude/commands/
+
+# 练习 2:创建项目 memory
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+
+# 练习 3:试用一下
+# 在 Claude Code 中输入:/optimize
+```
+
+#### 成功标准
+- [ ] 成功执行 `/optimize`
+- [ ] Claude 记住了 `CLAUDE.md` 中的项目规范
+- [ ] 你知道什么时候用 slash command,什么时候用 memory
+
+#### 下一步
+熟悉之后,请阅读:
+- [01-slash-commands/README.md](01-slash-commands/README.md)
+- [02-memory/README.md](02-memory/README.md)
+
+> **检查理解**:在 Claude Code 中运行 `/lesson-quiz slash-commands` 或 `/lesson-quiz memory`,检验你学会了多少。
+
+---
+
+### 里程碑 1B:安全探索
+
+**主题**:Checkpoints + CLI Basics
+**时间**:1 小时
+**复杂度**:⭐⭐ Beginner+
+**目标**:学会安全试验,并使用核心 CLI 命令
+
+#### 你将完成什么
+✅ 创建和恢复 checkpoints,安全试验
+✅ 理解交互模式与 print mode
+✅ 使用基本 CLI 参数和选项
+✅ 通过管道处理文件
+
+#### 实战练习
+
+```bash
+# 练习 1:尝试 checkpoint 工作流
+# 在 Claude Code 中:
+# 做一些实验性修改,然后按 Esc+Esc 或使用 /rewind
+# 选择你实验之前的 checkpoint
+# 选择“恢复代码和对话”返回
+
+# 练习 2:交互模式 vs 输出模式(Print mode)
+claude "explain this project" # 交互模式
+claude -p "explain this function" # 输出模式(非交互)
+
+# 练习 3:通过管道处理文件内容
+cat error.log | claude -p "explain this error"
+```
+
+#### 成功标准
+- [ ] 成功创建并回退到一个 checkpoint
+- [ ] 使用过交互模式和 print mode
+- [ ] 把文件通过管道传给 Claude 做分析
+- [ ] 明白什么时候该用 checkpoints 做安全试验
+
+#### 下一步
+- 阅读:[08-checkpoints/README.md](08-checkpoints/README.md)
+- 阅读:[10-cli/README.md](10-cli/README.md)
+- **准备进入 Level 2!** 继续看 [里程碑 2A](#里程碑-2a自动化skills--hooks)
+
+> **检查理解**:运行 `/lesson-quiz checkpoints` 或 `/lesson-quiz cli`,确认你准备好进入 Level 2。
+
+---
+
+## 🔵 Level 2:Intermediate - 构建工作流
+
+**适合**:测验勾选数 3-5
+**时间**:约 5 小时
+**重点**:自动化、集成、任务委派
+**结果**:可以构建自动化工作流、接入外部服务,并准备进入 Level 3
+
+### 前置条件检查
+
+开始 Level 2 之前,先确认你已经掌握这些 Level 1 内容:
+
+- [ ] 会创建和使用 slash commands([01-slash-commands/README.md](01-slash-commands/README.md))
+- [ ] 会通过 `CLAUDE.md` 设置项目 memory([02-memory/README.md](02-memory/README.md))
+- [ ] 知道如何创建和恢复 checkpoints([08-checkpoints/README.md](08-checkpoints/README.md))
+- [ ] 会在命令行使用 `claude` 和 `claude -p`([10-cli/README.md](10-cli/README.md))
+
+> **有空缺?** 继续之前,先回顾上面的链接教程。
+
+---
+
+<a id="milestone-2a-automation-skills-hooks"></a>
+### 里程碑 2A:自动化(Skills + Hooks)
+
+**主题**:Skills + Hooks
+**时间**:2-3 小时
+**复杂度**:⭐⭐ Intermediate
+**目标**:自动化常见工作流和质量检查
+
+#### 你将完成什么
+✅ 通过 YAML frontmatter 自动触发专门能力(包含 `effort` 和 `shell` 字段)
+✅ 在 25 个 hook 事件上设置事件驱动自动化
+✅ 使用 4 种 hook 类型(command、http、prompt、agent)
+✅ 强制执行代码质量标准
+✅ 为自己的工作流创建自定义 hooks
+
+#### 实战练习
+
+```bash
+# 练习 1:安装一个 skill
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# 练习 2:设置 hooks
+mkdir -p ~/.claude/hooks
+cp 06-hooks/pre-tool-check.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/pre-tool-check.sh
+
+# 练习 3:在 settings 中配置 hooks
+# 添加到 ~/.claude/settings.json:
+{
+ "hooks": {
+ "PreToolUse": [
+ {
+ "matcher": "Bash",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "~/.claude/hooks/pre-tool-check.sh"
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+#### 成功标准
+- [ ] 在相关场景下,代码审查 skill 会自动触发
+- [ ] PreToolUse hook 会在工具执行前运行
+- [ ] 你理解 skill 自动触发和 hook 事件触发的区别
+
+#### 下一步
+- 创建你自己的 custom skill
+- 为工作流增加更多 hooks
+- 阅读:[03-skills/README.md](03-skills/README.md)
+- 阅读:[06-hooks/README.md](06-hooks/README.md)
+
+> **检查理解**:在继续之前,运行 `/lesson-quiz skills` 或 `/lesson-quiz hooks` 测试你的理解。
+
+---
+
+### 里程碑 2B:集成(MCP + Subagents)
+
+**主题**:MCP + Subagents
+**时间**:2-3 小时
+**复杂度**:⭐⭐⭐ Intermediate+
+**目标**:集成外部服务,并把复杂任务委派出去
+
+#### 你将完成什么
+✅ 从 GitHub、数据库等位置访问实时数据
+✅ 把工作委派给专门化 AI agents
+✅ 明白什么时候该用 MCP,什么时候该用 subagents
+✅ 构建集成式工作流
+
+#### 实战练习
+
+```bash
+# 练习 1:设置 GitHub MCP
+export GITHUB_TOKEN="your_github_token"
+claude mcp add github -- npx -y @modelcontextprotocol/server-github
+
+# 练习 2:测试 MCP 集成
+# 在 Claude Code 中:/mcp__github__list_prs
+
+# 练习 3:安装 subagents
+mkdir -p .claude/agents
+cp 04-subagents/*.md .claude/agents/
+```
+
+#### 集成练习
+试试这个完整工作流:
+1. 用 MCP 获取一个 GitHub PR
+2. 让 Claude 把审查任务委派给 code-reviewer subagent
+3. 再用 hooks 自动运行测试
+
+#### 成功标准
+- [ ] 能通过 MCP 成功查询 GitHub 数据
+- [ ] Claude 会把复杂任务委派给 subagents
+- [ ] 你理解 MCP 和 subagents 的区别
+- [ ] 能把 MCP + subagents + hooks 组合进一个工作流
+
+#### 下一步
+- 配置更多 MCP servers(数据库、Slack 等)
+- 为你的领域创建自定义 subagents
+- 阅读:[05-mcp/README.md](05-mcp/README.md)
+- 阅读:[04-subagents/README.md](04-subagents/README.md)
+- **准备进入 Level 3!** 继续看 [里程碑 3A](#里程碑-3a高级功能)
+
+> **检查理解**:运行 `/lesson-quiz mcp` 或 `/lesson-quiz subagents`,确认你准备好进入 Level 3。
+
+---
+
+## 🔴 Level 3:Advanced - 高阶用户与团队负责人
+
+**适合**:测验勾选数 6-8
+**时间**:约 5 小时
+**重点**:团队工具、CI/CD、企业功能、插件开发
+**结果**:成为高阶用户,能够搭建团队工作流和 CI/CD
+
+### 前置条件检查
+
+开始 Level 3 之前,先确认你已经掌握这些 Level 2 内容:
+
+- [ ] 会创建并自动触发 skills([03-skills/README.md](03-skills/README.md))
+- [ ] 会配置 hooks 做事件驱动自动化([06-hooks/README.md](06-hooks/README.md))
+- [ ] 会配置 MCP servers 访问外部数据([05-mcp/README.md](05-mcp/README.md))
+- [ ] 知道如何用 subagents 分派任务([04-subagents/README.md](04-subagents/README.md))
+
+> **有空缺?** 继续之前,先回顾上面的链接教程。
+
+---
+
+<a id="milestone-3a-advanced-features"></a>
+### 里程碑 3A:高级功能
+
+**主题**:高级功能(Planning、Permissions、Extended Thinking、自动模式(Auto Mode)、通道(Channels)、语音输入(Voice Dictation)、Remote/Desktop/Web)
+**时间**:2-3 小时
+**复杂度**:⭐⭐⭐⭐⭐ Advanced
+**目标**:掌握高级工作流和高阶工具
+
+#### 你将完成什么
+✅ 为复杂功能使用 planning mode
+✅ 用 6 种模式进行细粒度权限控制(default、acceptEdits、plan、auto、dontAsk、bypassPermissions)
+✅ 用 Alt+T / Option+T 切换 extended thinking
+✅ 管理后台任务
+✅ 使用 Auto Memory 记住偏好
+✅ 使用自动模式(Auto Mode)和后台安全分类器
+✅ 使用通道(Channels)组织多会话工作流
+✅ 使用语音输入(Voice Dictation)解放双手
+✅ 远程控制、桌面应用和 Web 会话
+✅ 使用 Agent Teams 协作
+
+#### 实战练习
+
+```bash
+# 练习 1:使用 planning mode
+/plan Implement user authentication system
+
+# 练习 2:尝试权限模式(共有 6 种:default、acceptEdits、plan、auto、dontAsk、bypassPermissions)
+claude --permission-mode plan "analyze this codebase"
+claude --permission-mode acceptEdits "refactor the auth module"
+claude --permission-mode auto "implement the feature"
+
+# 练习 3:启用 extended thinking
+# 在会话中按 Alt+T(macOS 上是 Option+T)切换
+
+# 练习 4:高级 checkpoint 工作流
+# 1. 创建名为 "Clean state" 的 checkpoint
+# 2. 使用 planning mode 设计功能
+# 3. 通过 subagent 委派实现
+# 4. 在后台运行测试
+# 5. 如果测试失败,回退到 checkpoint
+# 6. 尝试另一种方案
+
+# 练习 5:尝试自动模式(Auto mode,后台安全分类器)
+claude --permission-mode auto "implement user settings page"
+
+# 练习 6:启用 agent teams
+export CLAUDE_AGENT_TEAMS=1
+# 让 Claude 执行:"Implement feature X using a team approach"
+
+# 练习 7:定时任务
+/loop 5m /check-status
+# 或使用 CronCreate 创建持久化定时任务
+
+# 练习 8:用通道(Channels)管理多会话工作流
+# 用 channels 来组织跨会话工作
+
+# 练习 9:语音输入(Voice Dictation)
+# 用语音输入和 Claude Code 进行无手操作
+```
+
+#### 成功标准
+- [ ] 为复杂功能使用过 planning mode
+- [ ] 配置过权限模式(plan、acceptEdits、auto、dontAsk)
+- [ ] 用 Alt+T / Option+T 切换过 extended thinking
+- [ ] 使用过带后台安全分类器的自动模式(Auto mode)
+- [ ] 使用过后台任务处理长时间操作
+- [ ] 探索过通道(Channels)做多会话工作流
+- [ ] 尝试过语音输入(Voice Dictation)做无手输入
+- [ ] 理解 Remote Control、Desktop App 和 Web 会话
+- [ ] 启用并使用过 Agent Teams 做协作任务
+- [ ] 用过 `/loop` 做周期任务或定时监控
+
+#### 下一步
+- 阅读:[09-advanced-features/README.md](09-advanced-features/README.md)
+
+> **检查理解**:运行 `/lesson-quiz advanced`,测试你对高阶功能的掌握程度。
+
+---
+
+### 里程碑 3B:团队与分发(Plugins + CLI 精通)
+
+**主题**:Plugins + CLI 精通 + CI/CD
+**时间**:2-3 小时
+**复杂度**:⭐⭐⭐⭐ Advanced
+**目标**:搭建团队工具、创建插件、熟练集成 CI/CD
+
+#### 你将完成什么
+✅ 安装和创建完整的 bundled plugins
+✅ 掌握 CLI,用于脚本和自动化
+✅ 使用 `claude -p` 做 CI/CD 集成
+✅ 为自动化流水线输出 JSON
+✅ 管理会话与批处理
+
+#### 实战练习
+
+```bash
+# 练习 1:安装一个完整 plugin
+# 在 Claude Code 中:/plugin install pr-review
+
+# 练习 2:让 print mode 服务于 CI/CD
+claude -p "Run all tests and generate report"
+
+# 练习 3:为脚本输出 JSON
+claude -p --output-format json "list all functions"
+
+# 练习 4:会话管理与恢复
+claude -r "feature-auth" "continue implementation"
+
+# 练习 5:带约束的 CI/CD 集成
+claude -p --max-turns 3 --output-format json "review code"
+
+# 练习 6:批处理
+for file in *.md; do
+ claude -p --output-format json "summarize this: $(cat $file)" > ${file%.md}.summary.json
+done
+```
+
+#### CI/CD 集成练习
+创建一个简单的 CI/CD 脚本:
+1. 用 `claude -p` 审查变更文件
+2. 把结果输出成 JSON
+3. 用 `jq` 处理特定问题
+4. 集成进 GitHub Actions 工作流
+
+---
+
+## 🧪 测试你的知识
+
+根据你刚学完的内容,直接运行下面的测验:
+
+```bash
+/lesson-quiz slash-commands
+/lesson-quiz memory
+/lesson-quiz checkpoints
+/lesson-quiz cli
+/lesson-quiz skills
+/lesson-quiz hooks
+/lesson-quiz mcp
+/lesson-quiz subagents
+/lesson-quiz advanced-features
+```
+
+---
+
+## ⚡ 快速开始路径
+
+### 如果你只有 15 分钟
+**目标**:先拿到一个立竿见影的成果
+
+1. 复制一个 slash command:`cp 01-slash-commands/optimize.md .claude/commands/`
+2. 在 Claude Code 中试一下:`/optimize`
+3. 阅读:[01-slash-commands/README.md](01-slash-commands/README.md)
+
+**结果**:你会得到一个能用的 slash command,并理解基础用法
+
+---
+
+### 如果你有 1 小时
+**目标**:搭好基础生产力工具
+
+1. **Slash commands**(15 分钟):复制并测试 `/optimize` 和 `/pr`
+2. **项目 memory**(15 分钟):用项目规范创建 `CLAUDE.md`
+3. **安装一个 skill**(15 分钟):配置 code-review skill
+4. **一起试用**(15 分钟):感受它们如何协同工作
+
+**结果**:命令、memory 和自动 skills 带来基础效率提升
+
+---
+
+### 如果你有一个周末
+**目标**:熟悉大部分功能
+
+**周六上午**(3 小时):
+- 完成里程碑 1A:Slash Commands + Memory
+- 完成里程碑 1B:Checkpoints + CLI Basics
+
+**周六下午**(3 小时):
+- 完成里程碑 2A:Skills + Hooks
+- 完成里程碑 2B:MCP + Subagents
+
+**周日**(4 小时):
+- 完成里程碑 3A:高级功能
+- 完成里程碑 3B:Plugins + CLI 精通 + CI/CD
+- 为你的团队构建一个自定义 plugin
+
+**结果**:你会成为 Claude Code 的高阶用户,能够培训别人并自动化复杂工作流
+
+---
+
+## 💡 学习建议
+
+### ✅ 建议做
+
+- **先做测验**,找到自己的起点
+- **完成每个里程碑的实战练习**
+- **先从简单开始**,再逐步增加复杂度
+- **在进入下一个功能前先测试当前功能**
+- **记下哪些做法最适合你的工作流**
+- **学习新内容时回头复习基础概念**
+- **借助 checkpoints 安全试验**
+- **把经验分享给团队**
+
+### ❌ 不建议做
+
+- **不要跳过前置条件检查**
+- **不要试图一次学完所有内容**
+- **不要照搬配置却不理解它们**
+- **不要忘记测试**
+- **不要急着跳过里程碑**
+- **不要忽视文档**
+- **不要把自己隔离起来**
+
+---
+
+## 🎓 学习风格
+
+### 视觉型学习者
+- 阅读每个 README 里的 Mermaid 图
+- 观察命令执行流程
+- 自己画工作流图
+- 使用上面的可视化路径图
+
+### 动手型学习者
+- 完成每个实战练习
+- 试试不同变体
+- 先搞坏再修复(记得用 checkpoints)
+- 创建自己的示例
+
+### 阅读型学习者
+- 认真阅读每个 README
+- 研究代码示例
+- 看对比表
+- 阅读资源区链接的博客文章
+
+### 社交型学习者
+- 组织结对编程
+- 给队友讲解概念
+- 参与 Claude Code 社区讨论
+- 分享你的自定义配置
+
+---
+
+## 📈 进度追踪
+
+用这些清单按水平追踪进度。你可以随时运行 `/self-assessment` 更新自己的技能画像,也可以在每个教程后运行 `/lesson-quiz [lesson]` 验证理解。
+
+### 🟢 Level 1:Beginner
+- [ ] 完成 [01-slash-commands](01-slash-commands/README.md)
+- [ ] 完成 [02-memory](02-memory/README.md)
+- [ ] 创建第一个自定义 slash command
+- [ ] 设置项目 memory
+- [ ] **达到里程碑 1A**
+- [ ] 完成 [08-checkpoints](08-checkpoints/README.md)
+- [ ] 完成 [10-cli](10-cli/README.md) 基础部分
+- [ ] 创建并回退到一个 checkpoint
+- [ ] 使用交互模式和 print mode
+- [ ] **达到里程碑 1B**
+
+### 🔵 Level 2:Intermediate
+- [ ] 完成 [03-skills](03-skills/README.md)
+- [ ] 完成 [06-hooks](06-hooks/README.md)
+- [ ] 安装第一个 skill
+- [ ] 设置 PreToolUse hook
+- [ ] **达到里程碑 2A**
+- [ ] 完成 [05-mcp](05-mcp/README.md)
+- [ ] 完成 [04-subagents](04-subagents/README.md)
+- [ ] 连接 GitHub MCP
+- [ ] 创建自定义 subagent
+- [ ] 把多个集成组合进一个工作流
+- [ ] **达到里程碑 2B**
+
+### 🔴 Level 3:Advanced
+- [ ] 完成 [09-advanced-features](09-advanced-features/README.md)
+- [ ] 成功使用 planning mode
+- [ ] 配置权限模式(包含 auto 在内的 6 种)
+- [ ] 使用带安全分类器的自动模式(Auto mode)
+- [ ] 使用 extended thinking 切换
+- [ ] 探索通道(Channels)和语音输入(Voice Dictation)
+- [ ] **达到里程碑 3A**
+- [ ] 完成 [07-plugins](07-plugins/README.md)
+- [ ] 完成 [10-cli](10-cli/README.md) 的高级用法
+- [ ] 配置 print mode(`claude -p`)用于 CI/CD
+- [ ] 为自动化创建 JSON 输出
+- [ ] 把 Claude 集成到 CI/CD 流水线
+- [ ] 创建团队 plugin
+- [ ] **达到里程碑 3B**
+
+---
+
+## 🆘 常见学习难题
+
+### 难题 1:“概念一下子太多了”
+**解决**:一次只关注一个里程碑。完成所有练习后再往下走。
+
+### 难题 2:“不知道什么时候该用哪个功能”
+**解决**:回到主 README 里的 [Use Case Matrix](README.md#你能用它做什么)。
+
+### 难题 3:“配置没有生效”
+**解决**:检查主 README 里的 [Troubleshooting](README.md#故障排查) 部分,并确认文件路径。
+
+### 难题 4:“概念之间好像重叠”
+**解决**:查看主 README 里的 [Feature Comparison](README.md#功能对比) 表,理解差异。
+
+### 难题 5:“太多东西记不住”
+**解决**:自己做一份速查表;同时用 checkpoints 安全试验。
+
+### 难题 6:“我经验很足,但不知道从哪里开始”
+**解决**:先做上面的 [自我评估测验](#-找到你的水平),直接跳到你的水平,并用前置条件检查找出空缺。
+
+---
+
+## 🎯 学完之后做什么?
+
+完成所有里程碑后,可以继续做这些事:
+
+1. **写团队文档** - 记录团队的 Claude Code 配置
+2. **构建自定义 plugins** - 把团队工作流打包起来
+3. **探索 Remote Control** - 通过外部工具以编程方式控制 Claude Code 会话
+4. **试试 Web Sessions** - 用浏览器界面远程开发
+5. **使用 Desktop App** - 通过原生桌面应用访问 Claude Code
+6. **使用自动模式(Auto Mode)** - 让 Claude 在后台安全分类器保护下自主工作
+7. **启用 Auto Memory** - 让 Claude 随时间自动学习你的偏好
+8. **设置 Agent Teams** - 让多个 agent 协同处理复杂、多维任务
+9. **使用通道(Channels)** - 用结构化的多会话工作流组织工作
+10. **试试语音输入(Voice Dictation)** - 用语音无障碍地与 Claude Code 交互
+11. **使用 Scheduled Tasks** - 借助 `/loop` 和 cron 工具自动化周期性检查
+12. **贡献示例** - 把经验分享给社区
+13. **带新人** - 帮助队友快速上手
+14. **持续优化工作流** - 根据使用情况不断改进
+15. **保持更新** - 跟进 Claude Code 发布和新功能
+
+---
+
+## 📚 其他资源
+
+### 官方文档
+- [Claude Code Documentation](https://code.claude.com/docs/en/overview)
+- [Anthropic Documentation](https://docs.anthropic.com)
+- [MCP Protocol Specification](https://modelcontextprotocol.io)
+
+### 博客文章
+- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29)
+
+### 社区
+- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook)
+- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
+
+---
+
+## 💬 反馈与支持
+
+- **发现问题?** 在仓库里创建 issue
+- **有建议?** 提交 pull request
+- **需要帮助?** 查看文档,或者向社区提问
+
+---
+
+**最后更新**:2026 年 3 月
+**维护者**:Claude How-To Contributors
+**许可证**:仅供学习与参考,免费使用和改编
+
+---
+
+[← 返回主 README](README.md)
diff --git a/zh/QUICK_REFERENCE.md b/zh/QUICK_REFERENCE.md
new file mode 100644
index 0000000..72b7fc0
--- /dev/null
+++ b/zh/QUICK_REFERENCE.md
@@ -0,0 +1,506 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Claude Code 示例 - 速查卡
+
+## 🚀 安装速命令
+
+### Slash Commands
+```bash
+# 安装全部
+cp 01-slash-commands/*.md .claude/commands/
+
+# 安装单个
+cp 01-slash-commands/optimize.md .claude/commands/
+```
+
+### Memory
+```bash
+# 项目 memory
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+
+# 个人 memory
+cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md
+```
+
+### Skills
+```bash
+# 个人 skills
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# 项目 skills
+cp -r 03-skills/code-review .claude/skills/
+```
+
+### Subagents
+```bash
+# 安装全部
+cp 04-subagents/*.md .claude/agents/
+
+# 安装单个
+cp 04-subagents/code-reviewer.md .claude/agents/
+```
+
+### MCP
+```bash
+# 设置凭据
+export GITHUB_TOKEN="your_token"
+export DATABASE_URL="postgresql://..."
+
+# 安装配置(项目级)
+cp 05-mcp/github-mcp.json .mcp.json
+
+# 或者用户级:添加到 ~/.claude.json
+```
+
+### Hooks
+```bash
+# 安装 hooks
+mkdir -p ~/.claude/hooks
+cp 06-hooks/*.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/*.sh
+
+# 在 settings 中配置(~/.claude/settings.json)
+```
+
+### Plugins
+```bash
+# 从示例安装(如果已发布)
+/plugin install pr-review
+/plugin install devops-automation
+/plugin install documentation
+```
+
+### Checkpoints
+```bash
+# 每次用户提示后都会自动创建 checkpoint
+# 回退:按两次 Esc 或使用:
+/rewind
+
+# 然后选择:恢复代码和对话、恢复对话、
+# 恢复代码、从这里开始总结,或算了
+```
+
+### Advanced Features
+```bash
+# 在 settings 中配置(.claude/settings.json)
+# 参见 09-advanced-features/config-examples.json
+
+# planning mode
+/plan 任务描述
+
+# 权限模式(使用 --permission-mode 参数)
+# default - 风险操作需要审批
+# acceptEdits - 自动接受文件编辑,其他操作仍需审批
+# plan - 只读分析,不做修改
+# dontAsk - 除危险操作外全部接受
+# auto - 后台分类器自动决定权限
+# bypassPermissions - 全部接受(需要 --dangerously-skip-permissions)
+
+# 会话管理
+/resume # 恢复之前的对话
+/rename "name" # 命名当前会话
+/fork # 分叉当前会话
+claude -c # 继续最近的对话
+claude -r "session" # 按名称/ID 恢复会话
+```
+
+---
+
+## 📋 功能速览
+
+| 功能 | 安装路径 | 用法 |
+|------|----------|------|
+| **Slash Commands(55+)** | `.claude/commands/*.md` | `/command-name` |
+| **Memory** | `./CLAUDE.md` | 自动加载 |
+| **Skills** | `.claude/skills/*/SKILL.md` | 自动触发 |
+| **Subagents** | `.claude/agents/*.md` | 自动委派 |
+| **MCP** | `.mcp.json`(项目)或 `~/.claude.json`(用户) | `/mcp__server__action` |
+| **Hooks(25 个事件)** | `~/.claude/hooks/*.sh` | 事件触发(4 类) |
+| **Plugins** | 通过 `/plugin install` | 打包所有能力 |
+| **Checkpoints** | 内置 | `Esc+Esc` 或 `/rewind` |
+| **Planning Mode** | 内置 | `/plan <task>` |
+| **Permission Modes(6 种)** | 内置 | `--allowedTools`、`--permission-mode` |
+| **Sessions** | 内置 | `/session <command>` |
+| **Background Tasks** | 内置 | 在后台运行 |
+| **Remote Control** | 内置 | WebSocket API |
+| **Web Sessions** | 内置 | `claude web` |
+| **Git Worktrees** | 内置 | `/worktree` |
+| **Auto Memory** | 内置 | 自动保存到 `CLAUDE.md` |
+| **Task List** | 内置 | `/task list` |
+| **Bundled Skills(5 个)** | 内置 | `/simplify`、`/loop`、`/claude-api`、`/voice`、`/browse` |
+
+---
+
+## 🎯 常见使用场景
+
+### 代码审查
+```bash
+# 方法 1:slash command
+cp 01-slash-commands/optimize.md .claude/commands/
+# 使用:/optimize
+
+# 方法 2:subagent
+cp 04-subagents/code-reviewer.md .claude/agents/
+# 使用:自动委派
+
+# 方法 3:skill
+cp -r 03-skills/code-review ~/.claude/skills/
+# 使用:自动触发
+
+# 方法 4:插件(推荐)
+/plugin install pr-review
+# 使用:/review-pr
+```
+
+### 文档
+```bash
+# slash command
+cp 01-slash-commands/generate-api-docs.md .claude/commands/
+
+# subagent
+cp 04-subagents/documentation-writer.md .claude/agents/
+
+# skill
+cp -r 03-skills/doc-generator ~/.claude/skills/
+
+# 插件(完整方案)
+/plugin install documentation
+```
+
+### DevOps
+```bash
+# 完整插件
+/plugin install devops-automation
+
+# 命令:/deploy、/rollback、/status、/incident
+```
+
+### 团队规范
+```bash
+# 项目 memory
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+
+# 按你的团队规范编辑
+vim CLAUDE.md
+```
+
+### 自动化与 Hooks
+```bash
+# 安装 hooks(25 个事件,4 类:command、http、prompt、agent)
+mkdir -p ~/.claude/hooks
+cp 06-hooks/*.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/*.sh
+
+# 示例:
+# - 提交前测试:pre-commit.sh
+# - 自动格式化代码:format-code.sh
+# - 安全扫描:security-scan.sh
+
+# 用 Auto Mode 实现全自动工作流
+claude --enable-auto-mode -p "重构并测试 auth 模块"
+# 或者用 Shift+Tab 在模式间切换
+```
+
+### 安全重构
+```bash
+# 每次提示前都会自动创建 checkpoint
+# 试着重构
+# 如果成功:继续
+# 如果失败:按 Esc+Esc 或使用 /rewind 返回
+```
+
+### 复杂实现
+```bash
+# 使用 planning mode
+/plan 实现用户认证系统
+
+# Claude 会创建详细计划
+# 你可以审阅并批准
+# Claude 会系统化地执行实现
+```
+
+### CI/CD 集成
+```bash
+# 以 headless 模式运行(非交互)
+claude -p "运行所有测试并生成报告"
+
+# 在 CI 中搭配权限模式
+claude -p "运行测试" --permission-mode dontAsk
+
+# 使用 Auto Mode 实现完全自治的 CI 任务
+claude --enable-auto-mode -p "运行测试并修复失败项"
+
+# 结合 hooks 做自动化
+# 参见 09-advanced-features/README.md
+```
+
+### 学习与实验
+```bash
+# 用 plan mode 做安全分析
+claude --permission-mode plan
+
+# 安全实验 - checkpoint 会自动创建
+# 如果需要回退:按 Esc+Esc 或使用 /rewind
+```
+
+### Agent 团队
+```bash
+# 启用 agent 团队
+export CLAUDE_AGENT_TEAMS=1
+
+# 或者在 settings.json 中
+{ "agentTeams": { "enabled": true } }
+
+# 用这句话开始:"使用团队方式实现功能 X"
+```
+
+### 定时任务
+```bash
+# 每 5 分钟运行一次命令
+/loop 5m /check-status
+
+# 一次性提醒
+/loop 30m "提醒我检查部署"
+```
+
+---
+
+## 📁 文件位置参考
+
+```text
+Your Project/
+├── .claude/
+│ ├── commands/ # Slash commands 放这里
+│ ├── agents/ # Subagents 放这里
+│ ├── skills/ # 项目 skills 放这里
+│ └── settings.json # 项目设置(hooks 等)
+├── .mcp.json # MCP 配置(项目级)
+├── CLAUDE.md # 项目 memory
+└── src/
+ └── api/
+ └── CLAUDE.md # 目录级 memory
+
+User Home/
+├── .claude/
+│ ├── commands/ # 个人命令
+│ ├── agents/ # 个人 agents
+│ ├── skills/ # 个人 skills
+│ ├── hooks/ # hook 脚本
+│ ├── settings.json # 用户设置
+│ ├── managed-settings.d/ # 托管设置(企业/组织)
+│ └── CLAUDE.md # 个人 memory
+└── .claude.json # 个人 MCP 配置(用户级)
+```
+
+---
+
+## 🔍 查找示例
+
+### 按分类
+- **Slash Commands**:`01-slash-commands/`
+- **Memory**:`02-memory/`
+- **Skills**:`03-skills/`
+- **Subagents**:`04-subagents/`
+- **MCP**:`05-mcp/`
+- **Hooks**:`06-hooks/`
+- **Plugins**:`07-plugins/`
+- **Checkpoints**:`08-checkpoints/`
+- **Advanced Features**:`09-advanced-features/`
+- **CLI**:`10-cli/`
+
+### 按使用场景
+- **性能**:`01-slash-commands/optimize.md`
+- **安全**:`04-subagents/secure-reviewer.md`
+- **测试**:`04-subagents/test-engineer.md`
+- **文档**:`03-skills/doc-generator/`
+- **DevOps**:`07-plugins/devops-automation/`
+
+### 按复杂度
+- **简单**:Slash commands
+- **中等**:Subagents、Memory
+- **高级**:Skills、Hooks
+- **完整**:Plugins
+
+---
+
+## 🎓 学习路径
+
+### 第 1 天
+```bash
+# 阅读总览
+cat README.md
+
+# 安装一个命令
+cp 01-slash-commands/optimize.md .claude/commands/
+
+# 试用
+/optimize
+```
+
+### 第 2-3 天
+```bash
+# 设置 memory
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+vim CLAUDE.md
+
+# 安装 subagent
+cp 04-subagents/code-reviewer.md .claude/agents/
+```
+
+### 第 4-5 天
+```bash
+# 设置 MCP
+export GITHUB_TOKEN="your_token"
+cp 05-mcp/github-mcp.json .mcp.json
+
+# 试用 MCP 命令
+/mcp__github__list_prs
+```
+
+### 第 2 周
+```bash
+# 安装 skill
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# 让它自动触发
+# 直接说:“Review this code for issues”
+```
+
+### 第 3 周及以后
+```bash
+# 安装完整插件
+/plugin install pr-review
+
+# 使用打包功能
+/review-pr
+/check-security
+/check-tests
+```
+
+---
+
+## 🆕 新功能(2026 年 3 月)
+
+| 功能 | 说明 | 用法 |
+|------|------|------|
+| **Auto Mode** | 通过后台分类器实现完全自治 | `--enable-auto-mode` 参数,`Shift+Tab` 切换模式 |
+| **Channels** | Discord 和 Telegram 集成 | `--channels` 参数,Discord / Telegram bot |
+| **Voice Dictation** | 对 Claude 说出命令和上下文 | `/voice` 命令 |
+| **Hooks(25 个事件)** | 扩展后的 hook 系统,包含 4 类 | command、http、prompt、agent hook 类型 |
+| **MCP Elicitation** | MCP server 可在运行时请求用户输入 | 当 server 需要澄清时自动提示 |
+| **WebSocket MCP** | MCP 的 WebSocket 传输 | 在 `.mcp.json` 中配置 `ws://` URL |
+| **Plugin LSP** | 插件支持 Language Server Protocol | `userConfig`、`${CLAUDE_PLUGIN_DATA}` 变量 |
+| **Remote Control** | 通过 WebSocket API 控制 Claude Code | `claude --remote` 用于外部集成 |
+| **Web Sessions** | 基于浏览器的 Claude Code 接口 | 使用 `claude web` 打开 |
+| **Desktop App** | 原生桌面应用 | 从 claude.ai/download 下载 |
+| **Task List** | 管理后台任务 | `/task list`、`/task status <id>` |
+| **Auto Memory** | 从对话中自动保存记忆 | Claude 会自动保存关键上下文到 `CLAUDE.md` |
+| **Git Worktrees** | 用于并行开发的隔离工作区 | 使用 `/worktree` 创建隔离空间 |
+| **Model Selection** | 在 Sonnet 4.6 和 Opus 4.6 之间切换 | `/model` 或 `--model` 参数 |
+| **Agent Teams** | 协调多个 agent 执行任务 | 通过环境变量 `CLAUDE_AGENT_TEAMS=1` 启用 |
+| **Scheduled Tasks** | 使用 `/loop` 运行周期任务 | `/loop 5m /command` 或 CronCreate 工具 |
+| **Chrome Integration** | 浏览器自动化 | `--chrome` 参数或 `/chrome` 命令 |
+| **Keyboard Customization** | 自定义按键绑定 | `/keybindings` 命令 |
+
+---
+
+## 💡 小技巧
+
+### 自定义
+- 先原样使用示例
+- 再按需求修改
+- 分享给团队前先测试
+- 对配置做版本控制
+
+### 最佳实践
+- 用 memory 保存团队规范
+- 用 plugins 做完整工作流
+- 用 subagents 处理复杂任务
+- 用 slash commands 处理快速任务
+
+### 故障排查
+```bash
+# 检查文件位置
+ls -la .claude/commands/
+ls -la .claude/agents/
+
+# 验证 YAML 语法
+head -20 .claude/agents/code-reviewer.md
+
+# 测试 MCP 连接
+echo $GITHUB_TOKEN
+```
+
+---
+
+## 📊 功能矩阵
+
+| 需求 | 用这个 | 示例 |
+|------|--------|------|
+| 快速快捷操作 | Slash Command(55+) | `01-slash-commands/optimize.md` |
+| 团队规范 | Memory | `02-memory/project-CLAUDE.md` |
+| 自动化工作流 | Skill | `03-skills/code-review/` |
+| 专门任务 | Subagent | `04-subagents/code-reviewer.md` |
+| 外部数据 | MCP(+ Elicitation、WebSocket) | `05-mcp/github-mcp.json` |
+| 事件自动化 | Hook(25 个事件、4 类) | `06-hooks/pre-commit.sh` |
+| 完整方案 | Plugin(+ LSP 支持) | `07-plugins/pr-review/` |
+| 安全实验 | Checkpoint | `08-checkpoints/checkpoint-examples.md` |
+| 完全自治 | Auto Mode | `--enable-auto-mode` 或 `Shift+Tab` |
+| 聊天集成 | Channels | `--channels`(Discord、Telegram) |
+| CI/CD 流水线 | CLI | `10-cli/README.md` |
+
+---
+
+## 🔗 快速链接
+
+- **主指南**:`README.md`
+- **完整索引**:`INDEX.md`
+- **速查卡**:`QUICK_REFERENCE.md`
+- **原始指南**:`claude_concepts_guide.md`
+
+---
+
+## 📞 常见问题
+
+**问:我应该先用哪个?**
+答:先从 slash commands 开始,按需逐步添加功能。
+
+**问:我可以混用多个功能吗?**
+答:可以!它们可以一起工作。Memory + Commands + MCP 很强大。
+
+**问:怎么分享给团队?**
+答:把 `.claude/` 目录提交到 git。
+
+**问:敏感信息怎么办?**
+答:用环境变量,不要硬编码。
+
+**问:我可以改这些示例吗?**
+答:当然可以!它们本来就是可定制的模板。
+
+---
+
+## ✅ 检查清单
+
+入门清单:
+
+- [ ] 阅读 `README.md`
+- [ ] 安装 1 个 slash command
+- [ ] 试用该命令
+- [ ] 创建项目 `CLAUDE.md`
+- [ ] 安装 1 个 subagent
+- [ ] 配置 1 个 MCP 集成
+- [ ] 安装 1 个 skill
+- [ ] 试用一个完整插件
+- [ ] 按你的需求定制
+- [ ] 与团队共享
+
+---
+
+**快速开始**:`cat README.md`
+
+**完整索引**:`cat INDEX.md`
+
+**这张卡片**:建议随手保留,方便快速查阅!
diff --git a/zh/README.md b/zh/README.md
new file mode 100644
index 0000000..4406b7d
--- /dev/null
+++ b/zh/README.md
@@ -0,0 +1,881 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+<p align="center">
+ <a href="https://github.com/trending">
+ <img src="https://img.shields.io/badge/GitHub-🔥%20%231%20Trending-purple?style=for-the-badge&logo=github"/>
+ </a>
+</p>
+
+[![GitHub Stars](https://img.shields.io/github/stars/luongnv89/claude-howto?style=flat&color=gold)](https://github.com/luongnv89/claude-howto/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/luongnv89/claude-howto?style=flat)](https://github.com/luongnv89/claude-howto/network/members)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-2.2.0-brightgreen)](CHANGELOG.md)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-2.1+-purple)](https://code.claude.com)
+
+# 用一个周末掌握 Claude Code
+
+从输入 `claude` 开始,到编排 agents、hooks、skills 和 MCP servers,全程配有可视化教程、可直接复制粘贴的模板,以及循序渐进的学习路径。
+
+**[15 分钟快速上手](#15-分钟快速上手)** | **[找到适合你的起点](#不知道从哪里开始)** | **[浏览功能目录](CATALOG.md)**
+
+---
+
+## 目录
+
+- [问题在哪里](#问题在哪里)
+- [Claude How To 如何解决这些问题](#claude-how-to-如何解决这些问题)
+- [它是如何工作的](#它是如何工作的)
+- [不知道从哪里开始?](#不知道从哪里开始)
+- [15 分钟快速上手](#15-分钟快速上手)
+- [你能用它做什么?](#你能用它做什么)
+- [常见问题](#常见问题)
+- [参与贡献](#参与贡献)
+- [许可证](#许可证)
+
+---
+
+## 问题在哪里
+
+你已经安装了 Claude Code。也试着跑了几个提示词。然后呢?
+
+- **官方文档会介绍功能,但不会告诉你如何把它们组合起来。** 你知道 slash commands 存在,但不知道怎样把它们和 hooks、memory、subagents 串起来,形成一个真正能节省数小时的工作流。
+- **没有清晰的学习路径。** 应该先学 MCP 还是 hooks?先学 skills 还是 subagents?结果往往是每样都看了一点,但没有一个真正掌握。
+- **示例太基础。** 一个 “hello world” 级别的 slash command,并不能帮你构建一个可用于生产环境的代码审查流水线,也无法让它结合 memory、委派给专门 agent、并自动执行安全扫描。
+
+你实际上只用上了 Claude Code 10% 的能力,而剩下的 90% 你甚至不知道自己错过了什么。
+
+---
+
+## Claude How To 如何解决这些问题
+
+这不是另一份功能参考手册,而是一份**结构化、可视化、以示例驱动的指南**。它会教你如何使用 Claude Code 的每一项功能,并提供今天就能复制到项目里的真实场景模板。
+
+| | 官方文档 | 本指南 |
+|--|---------------|------------|
+| **形式** | 参考文档 | 带 Mermaid 图表的可视化教程 |
+| **深度** | 功能说明 | 底层工作原理解析 |
+| **示例** | 基础代码片段 | 可立即上手的生产级模板 |
+| **结构** | 按功能组织 | 递进式学习路径(从入门到高级) |
+| **上手方式** | 自主摸索 | 带时间预估的引导式路线图 |
+| **自我评估** | 没有 | 交互式测验,帮你找出短板并生成个性化路径 |
+
+### 你将获得:
+
+- **10 个教程模块**,覆盖 Claude Code 的所有核心功能,从 slash commands 到自定义 agent 团队
+- **可复制粘贴的配置**,包括 slash commands、`CLAUDE.md` 模板、hook 脚本、MCP 配置、subagent 定义,以及完整 plugin 打包
+- **Mermaid 图表**,展示每个功能的内部工作机制,让你不仅知道“怎么做”,还知道“为什么这么做”
+- **一条引导式学习路径**,帮助你在 11 到 13 小时内从初学者成长为高级用户
+- **内置自测能力**,可以直接在 Claude Code 中运行 `/self-assessment` 或 `/lesson-quiz hooks` 找出知识盲点
+
+**[开始学习路线 ->](LEARNING-ROADMAP.md)**
+
+---
+
+## 它是如何工作的
+
+### 1. 先找到你的水平
+
+完成[自我评估测验](LEARNING-ROADMAP.md#find-your-level),或者在 Claude Code 中运行 `/self-assessment`。系统会根据你已经掌握的内容,生成一份个性化学习路线。
+
+### 2. 按引导路径学习
+
+按照顺序学习 10 个模块,每个模块都建立在前一个模块的基础上。你可以一边学,一边把模板直接复制到自己的项目中。
+
+### 3. 把多个功能组合成工作流
+
+真正的威力来自功能组合。你会学到如何把 slash commands、memory、subagents 和 hooks 连接成自动化流水线,用于代码审查、部署和文档生成等任务。
+
+### 4. 测试你的理解程度
+
+每学完一个模块后运行 `/lesson-quiz [topic]`。测验会精准指出你漏掉的知识点,让你快速补齐短板。
+
+**[15 分钟快速上手](#15-分钟快速上手)**
+
+---
+
+## 已被 5,900+ 开发者信赖
+
+- **5,900+ GitHub stars**,来自每天都在使用 Claude Code 的开发者
+- **690+ forks**,许多团队已将这份指南改造成自己的工作流版本
+- **持续维护中**,会与每次 Claude Code 发布保持同步(最新版本:v2.2.0,2026 年 3 月)
+- **社区驱动**,贡献者会分享他们在真实工作中的配置和经验
+
+[![Star History Chart](https://api.star-history.com/svg?repos=luongnv89/claude-howto&type=Date)](https://star-history.com/#luongnv89/claude-howto&Date)
+
+---
+
+## 不知道从哪里开始?
+
+先做自我评估,或者直接按你的水平开始:
+
+| Level | 你可以…… | 从这里开始 | 时间 |
+|-------|-----------|------------|------|
+| **Beginner** | 启动 Claude Code 并进行对话 | [Slash Commands](01-slash-commands/README.md) | 约 2.5 小时 |
+| **Intermediate** | 使用 `CLAUDE.md` 和自定义命令 | [Skills](03-skills/README.md) | 约 3.5 小时 |
+| **Advanced** | 配置 MCP servers 和 hooks | [Advanced Features](09-advanced-features/README.md) | 约 5 小时 |
+
+**完整学习路径,共 10 个模块:**
+
+| 顺序 | 模块 | 水平 | 时间 |
+|-------|--------|-------|------|
+| 1 | [Slash Commands](01-slash-commands/README.md) | 初学者 | 30 分钟 |
+| 2 | [Memory](02-memory/README.md) | 初学者+ | 45 分钟 |
+| 3 | [Checkpoints](08-checkpoints/README.md) | 中级 | 45 分钟 |
+| 4 | [CLI Basics](10-cli/README.md) | 初学者+ | 30 分钟 |
+| 5 | [Skills](03-skills/README.md) | 中级 | 1 小时 |
+| 6 | [Hooks](06-hooks/README.md) | 中级 | 1 小时 |
+| 7 | [MCP](05-mcp/README.md) | 中级+ | 1 小时 |
+| 8 | [Subagents](04-subagents/README.md) | 中级+ | 1.5 小时 |
+| 9 | [Advanced Features](09-advanced-features/README.md) | 高级 | 2 到 3 小时 |
+| 10 | [Plugins](07-plugins/README.md) | 高级 | 2 小时 |
+
+**[完整学习路线图 ->](LEARNING-ROADMAP.md)**
+
+---
+
+## 15 分钟快速上手
+
+```bash
+# 1. 克隆这份指南
+git clone https://github.com/luongnv89/claude-howto.git
+cd claude-howto
+
+# 2. 复制你的第一个 slash command
+mkdir -p /path/to/your-project/.claude/commands
+cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/
+
+# 3. 试试看:在 Claude Code 中输入
+# /optimize
+
+# 4. 想更进一步?设置项目记忆:
+cp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md
+
+# 5. 安装一个 skill:
+cp -r 03-skills/code-review ~/.claude/skills/
+```
+
+如果你想完成更完整的基础配置,这里有一个**1 小时的关键配置方案**:
+
+```bash
+# Slash commands(15 分钟)
+cp 01-slash-commands/*.md .claude/commands/
+
+# 项目记忆(15 分钟)
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+
+# 安装一个 skill(15 分钟)
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# 周末目标:继续添加 hooks、subagents、MCP 和 plugins
+# 按学习路径逐步完成配置
+```
+
+**[查看完整安装参考](#15-分钟快速上手)**
+
+---
+
+## 你能用它做什么?
+
+| 使用场景 | 你会组合使用的功能 |
+|----------|------------------------|
+| **自动化代码审查** | Slash Commands + Subagents + Memory + MCP |
+| **团队入职培训** | Memory + Slash Commands + Plugins |
+| **CI/CD 自动化** | CLI Reference + Hooks + Background Tasks |
+| **文档生成** | Skills + Subagents + Plugins |
+| **安全审计** | Subagents + Skills + Hooks(只读模式) |
+| **DevOps 流水线** | Plugins + MCP + Hooks + Background Tasks |
+| **复杂重构** | Checkpoints + Planning Mode + Hooks |
+
+---
+
+## 常见问题
+
+**这是免费的吗?**
+是的。MIT 许可证,永久免费。你可以将它用于个人项目、工作项目或团队中,唯一要求只是保留许可证声明。
+
+**它有人维护吗?**
+是的,而且持续维护。该指南会与每次 Claude Code 发布同步。当前版本是 v2.2.0(2026 年 3 月),兼容 Claude Code 2.1+。
+
+**它和官方文档有什么不同?**
+官方文档是功能参考手册;这份指南则是教程,包含图示、生产级模板和渐进式学习路径。两者是互补关系,建议先用本指南学习,再在需要具体细节时查官方文档。
+
+**完整学完需要多久?**
+完整路径大约需要 11 到 13 小时。但你在 15 分钟内就能获得直接收益,只要复制一个 slash command 模板并试用即可。
+
+**我可以搭配 Claude Sonnet / Haiku / Opus 使用吗?**
+可以。所有模板都适用于 Claude Sonnet 4.6、Claude Opus 4.6 和 Claude Haiku 4.5。
+
+**我可以参与贡献吗?**
+当然可以。请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献规范。我们欢迎新的示例、bug 修复、文档改进以及社区模板。
+
+**我可以离线阅读吗?**
+可以。运行 `uv run scripts/build_epub.py`,即可生成包含全部内容和渲染后 Mermaid 图表的 EPUB 电子书。
+
+---
+
+## 今天就开始掌握 Claude Code
+
+你已经安装好了 Claude Code。你和 10 倍生产力之间,差的只是知道该怎么正确使用它。这份指南会提供结构化路径、可视化解释和可直接复制的模板,帮助你真正掌握它。
+
+MIT 许可证,永久免费。克隆它、fork 它、改造成适合你自己的版本。
+
+**[开始学习路线 ->](LEARNING-ROADMAP.md)** | **[浏览功能目录](CATALOG.md)** | **[15 分钟快速上手](#15-分钟快速上手)**
+
+---
+
+<details>
+<summary>快速导航:全部功能</summary>
+
+| 功能 | 说明 | 文件夹 |
+|---------|-------------|--------|
+| **功能目录** | 包含安装命令的完整参考 | [CATALOG.md](CATALOG.md) |
+| **Slash Commands** | 用户手动触发的快捷命令 | [01-slash-commands/README.md](01-slash-commands/README.md) |
+| **Memory** | 持久上下文 | [02-memory/README.md](02-memory/README.md) |
+| **Skills** | 可复用能力 | [03-skills/README.md](03-skills/README.md) |
+| **Subagents** | 专门化 AI 助手 | [04-subagents/README.md](04-subagents/README.md) |
+| **MCP Protocol** | 访问外部工具 | [05-mcp/README.md](05-mcp/README.md) |
+| **Hooks** | 事件驱动自动化 | [06-hooks/README.md](06-hooks/README.md) |
+| **Plugins** | 打包后的功能集合 | [07-plugins/README.md](07-plugins/README.md) |
+| **Checkpoints** | 会话快照与回退 | [08-checkpoints/README.md](08-checkpoints/README.md) |
+| **Advanced Features** | 规划、思考、后台任务 | [09-advanced-features/README.md](09-advanced-features/README.md) |
+| **CLI Reference** | 命令、参数与选项 | [10-cli/README.md](10-cli/README.md) |
+| **博客文章** | 真实使用案例 | [Blog Posts](https://medium.com/@luongnv89) |
+
+</details>
+
+<details>
+<summary>功能对比</summary>
+
+| 功能 | 调用方式 | 持久性 | 最适合 |
+|---------|-----------|------------|----------|
+| **Slash Commands** | 手动(`/cmd`) | 仅当前会话 | 快速快捷操作 |
+| **Memory** | 自动加载 | 跨会话 | 长期记忆与学习 |
+| **Skills** | 自动触发 | 文件系统级 | 自动化工作流 |
+| **Subagents** | 自动委派 | 隔离上下文 | 任务拆分 |
+| **MCP Protocol** | 自动查询 | 实时 | 获取实时数据 |
+| **Hooks** | 事件触发 | 已配置 | 自动化与校验 |
+| **Plugins** | 一条命令 | 全功能打包 | 完整解决方案 |
+| **Checkpoints** | 手动/自动 | 会话级 | 安全试验 |
+| **Planning Mode** | 手动/自动 | 规划阶段 | 复杂实现 |
+| **Background Tasks** | 手动 | 任务持续期间 | 长时间运行的操作 |
+| **CLI Reference** | 终端命令 | 会话/脚本级 | 自动化与脚本开发 |
+
+</details>
+
+<details>
+<summary>安装速查表</summary>
+
+```bash
+# Slash Commands
+cp 01-slash-commands/*.md .claude/commands/
+
+# Memory
+cp 02-memory/project-CLAUDE.md ./CLAUDE.md
+
+# Skills
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# Subagents
+cp 04-subagents/*.md .claude/agents/
+
+# MCP
+export GITHUB_TOKEN="token"
+claude mcp add github -- npx -y @modelcontextprotocol/server-github
+
+# Hooks
+mkdir -p ~/.claude/hooks
+cp 06-hooks/*.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/*.sh
+
+# Plugins
+/plugin install pr-review
+
+# Checkpoints(默认自动开启,可在设置中配置)
+# 参见 08-checkpoints/README.md
+
+# Advanced Features(在设置中配置)
+# 参见 09-advanced-features/config-examples.json
+
+# CLI Reference(无需安装)
+# 使用示例见 10-cli/README.md
+```
+
+</details>
+
+<details>
+<summary>01. Slash Commands</summary>
+
+**位置**: [01-slash-commands/README.md](01-slash-commands/README.md)
+
+**是什么**: 以 Markdown 文件形式存储、由用户手动触发的快捷命令
+
+**示例**:
+- `optimize.md` - 代码优化分析
+- `pr.md` - Pull Request 准备
+- `generate-api-docs.md` - API 文档生成器
+
+**安装**:
+```bash
+cp 01-slash-commands/*.md /path/to/project/.claude/commands/
+```
+
+**使用方法**:
+```
+/optimize
+/pr
+/generate-api-docs
+```
+
+**了解更多**: [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29)
+
+</details>
+
+<details>
+<summary>02. Memory</summary>
+
+**位置**: [02-memory/README.md](02-memory/README.md)
+
+**是什么**: 跨会话持久化的上下文
+
+**示例**:
+- `project-CLAUDE.md` - 团队共享的项目规范
+- `directory-api-CLAUDE.md` - 目录级规则
+- `personal-CLAUDE.md` - 个人偏好
+
+**安装**:
+```bash
+# 项目记忆
+cp 02-memory/project-CLAUDE.md /path/to/project/CLAUDE.md
+
+# 目录记忆
+cp 02-memory/directory-api-CLAUDE.md /path/to/project/src/api/CLAUDE.md
+
+# 个人记忆
+cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md
+```
+
+**使用方法**: Claude 会自动加载
+
+</details>
+
+<details>
+<summary>03. Skills</summary>
+
+**位置**: [03-skills/README.md](03-skills/README.md)
+
+**是什么**: 可复用、会在合适时自动触发的能力包,包含说明和脚本
+
+**示例**:
+- `code-review/` - 带脚本的完整代码审查能力
+- `brand-voice/` - 品牌语气一致性检查
+- `doc-generator/` - API 文档生成器
+
+**安装**:
+```bash
+# 个人 skills
+cp -r 03-skills/code-review ~/.claude/skills/
+
+# 项目 skills
+cp -r 03-skills/code-review /path/to/project/.claude/skills/
+```
+
+**使用方法**: 在相关场景下自动触发
+
+</details>
+
+<details>
+<summary>04. Subagents</summary>
+
+**位置**: [04-subagents/README.md](04-subagents/README.md)
+
+**是什么**: 拥有隔离上下文和自定义提示词的专门化 AI 助手
+
+**示例**:
+- `code-reviewer.md` - 全面代码质量分析
+- `test-engineer.md` - 测试策略与覆盖率
+- `documentation-writer.md` - 技术文档编写
+- `secure-reviewer.md` - 面向安全的审查(只读)
+- `implementation-agent.md` - 完整功能实现
+
+**安装**:
+```bash
+cp 04-subagents/*.md /path/to/project/.claude/agents/
+```
+
+**使用方法**: 由主 agent 自动委派
+
+</details>
+
+<details>
+<summary>05. MCP Protocol</summary>
+
+**位置**: [05-mcp/README.md](05-mcp/README.md)
+
+**是什么**: 用于访问外部工具和 API 的 Model Context Protocol
+
+**示例**:
+- `github-mcp.json` - GitHub 集成
+- `database-mcp.json` - 数据库查询
+- `filesystem-mcp.json` - 文件操作
+- `multi-mcp.json` - 多个 MCP servers 配置
+
+**安装**:
+```bash
+# 设置环境变量
+export GITHUB_TOKEN="your_token"
+export DATABASE_URL="postgresql://..."
+
+# 通过 CLI 添加 MCP server
+claude mcp add github -- npx -y @modelcontextprotocol/server-github
+
+# 或手动添加到项目 .mcp.json(参见 [05-mcp/README.md](05-mcp/README.md) 中的示例)
+```
+
+**使用方法**: 配置完成后,Claude 会自动获得 MCP 工具能力
+
+</details>
+
+<details>
+<summary>06. Hooks</summary>
+
+**位置**: [06-hooks/README.md](06-hooks/README.md)
+
+**是什么**: 基于事件触发的 shell 命令,会在 Claude Code 事件发生时自动执行
+
+**示例**:
+- `format-code.sh` - 写入前自动格式化代码
+- `pre-commit.sh` - 提交前运行测试
+- `security-scan.sh` - 扫描安全问题
+- `log-bash.sh` - 记录所有 bash 命令
+- `validate-prompt.sh` - 校验用户提示词
+- `notify-team.sh` - 事件发生时发送通知
+
+**安装**:
+```bash
+mkdir -p ~/.claude/hooks
+cp 06-hooks/*.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/*.sh
+```
+
+在 `~/.claude/settings.json` 中配置 hooks:
+```json
+{
+ "hooks": {
+ "PreToolUse": [{
+ "matcher": "Write",
+ "hooks": ["~/.claude/hooks/format-code.sh"]
+ }],
+ "PostToolUse": [{
+ "matcher": "Write",
+ "hooks": ["~/.claude/hooks/security-scan.sh"]
+ }]
+ }
+}
+```
+
+**使用方法**: hooks 会在事件发生时自动执行
+
+**Hook 类型**(4 类,25 个事件):
+- **工具 Hook**: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`
+- **会话 Hook**: `SessionStart`, `SessionEnd`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`
+- **任务 Hook**: `UserPromptSubmit`, `TaskCompleted`, `TaskCreated`, `TeammateIdle`
+- **生命周期 Hook**: `ConfigChange`, `CwdChanged`, `FileChanged`, `PreCompact`, `PostCompact`, `WorktreeCreate`, `WorktreeRemove`, `Notification`, `InstructionsLoaded`, `Elicitation`, `ElicitationResult`
+
+</details>
+
+<details>
+<summary>07. Plugins</summary>
+
+**位置**: [07-plugins/README.md](07-plugins/README.md)
+
+**是什么**: 把 commands、agents、MCP 和 hooks 打包在一起的功能集合
+
+**示例**:
+- `pr-review/` - 完整的 PR 审查工作流
+- `devops-automation/` - 部署与监控
+- `documentation/` - 文档生成
+
+**安装**:
+```bash
+/plugin install pr-review
+/plugin install devops-automation
+/plugin install documentation
+```
+
+**使用方法**: 使用其中打包好的 slash commands 和功能
+
+</details>
+
+<details>
+<summary>08. Checkpoints and Rewind</summary>
+
+**位置**: [08-checkpoints/README.md](08-checkpoints/README.md)
+
+**是什么**: 保存对话状态,并回退到之前的时间点,以探索不同方案
+
+**核心概念**:
+- **Checkpoint**: 对话状态快照
+- **Rewind**: 回到之前的 checkpoint
+- **Branch Point**: 从同一个 checkpoint 分叉出多种方案
+
+**使用方法**:
+```
+# 每次用户提示后都会自动创建 checkpoint
+# 如需回退,按两次 Esc,或者使用:
+/rewind
+
+# 然后从以下五个选项中选择:
+# 1. 恢复代码和对话
+# 2. 恢复对话
+# 3. 恢复代码
+# 4. 从这里开始总结
+# 5. 算了
+```
+
+**使用场景**:
+- 尝试不同实现方式
+- 从错误中恢复
+- 安全试验
+- 比较不同备选方案
+- 对不同设计做 A/B 测试
+
+</details>
+
+<details>
+<summary>09. Advanced Features</summary>
+
+**位置**: [09-advanced-features/README.md](09-advanced-features/README.md)
+
+**是什么**: 面向复杂工作流和自动化的高级能力
+
+**包括**:
+- **Planning Mode**:编码前先创建详细实现计划
+- **Extended Thinking**:用于复杂问题的深度推理(用 `Alt+T` / `Option+T` 切换)
+- **Background Tasks**:运行长时间操作且不阻塞当前会话
+- **Permission Modes**:`default`、`acceptEdits`、`plan`、`dontAsk`、`bypassPermissions`
+- **Headless Mode**:在 CI/CD 中运行 Claude Code:`claude -p "Run tests and generate report"`
+- **Session Management**:`/resume`、`/rename`、`/fork`、`claude -c`、`claude -r`
+- **Configuration**:在 `~/.claude/settings.json` 中自定义行为
+
+完整配置请参见 [config-examples.json](09-advanced-features/config-examples.json)。
+
+</details>
+
+<details>
+<summary>10. CLI Reference</summary>
+
+**位置**: [10-cli/README.md](10-cli/README.md)
+
+**是什么**: Claude Code 的完整命令行接口参考
+
+**快速示例**:
+```bash
+# 交互模式
+claude "explain this project"
+
+# 输出模式(非交互)
+claude -p "review this code"
+
+# 处理文件内容
+cat error.log | claude -p "explain this error"
+
+# 为脚本输出 JSON
+claude -p --output-format json "list functions"
+
+# 恢复会话
+claude -r "feature-auth" "continue implementation"
+```
+
+**使用场景**: CI/CD 流水线集成、脚本自动化、批处理、多会话工作流、自定义 agent 配置
+
+</details>
+
+<details>
+<summary>示例工作流</summary>
+
+### 完整代码审查工作流
+
+```markdown
+# 使用:Slash Commands + Subagents + Memory + MCP
+
+用户:/review-pr
+
+Claude:
+1. 加载项目 memory(编码规范)
+2. 通过 GitHub MCP 获取 PR
+3. 委派给 code-reviewer subagent
+4. 委派给 test-engineer subagent
+5. 汇总发现
+6. 提供完整审查结果
+```
+
+### 自动化文档生成
+
+```markdown
+# 使用:Skills + Subagents + Memory
+
+用户:"为 auth 模块生成 API 文档"
+
+Claude:
+1. 加载项目 memory(文档规范)
+2. 识别出文档生成请求
+3. 自动触发 doc-generator skill
+4. 委派给 api-documenter subagent
+5. 生成带示例的完整文档
+```
+
+### DevOps 部署
+
+```markdown
+# 使用:Plugins + MCP + Hooks
+
+用户:/deploy production
+
+Claude:
+1. 运行部署前 hook(校验环境)
+2. 委派给 deployment-specialist subagent
+3. 通过 Kubernetes MCP 执行部署
+4. 监控进度
+5. 运行部署后 hook(健康检查)
+6. 报告状态
+```
+
+</details>
+
+<details>
+<summary>目录结构</summary>
+
+```
+├── 01-slash-commands/
+│ ├── optimize.md
+│ ├── pr.md
+│ ├── generate-api-docs.md
+│ └── README.md
+├── 02-memory/
+│ ├── project-CLAUDE.md
+│ ├── directory-api-CLAUDE.md
+│ ├── personal-CLAUDE.md
+│ └── README.md
+├── 03-skills/
+│ ├── code-review/
+│ │ ├── SKILL.md
+│ │ ├── scripts/
+│ │ └── templates/
+│ ├── brand-voice/
+│ │ ├── SKILL.md
+│ │ └── templates/
+│ ├── doc-generator/
+│ │ ├── SKILL.md
+│ │ └── generate-docs.py
+│ └── README.md
+├── 04-subagents/
+│ ├── code-reviewer.md
+│ ├── test-engineer.md
+│ ├── documentation-writer.md
+│ ├── secure-reviewer.md
+│ ├── implementation-agent.md
+│ └── README.md
+├── 05-mcp/
+│ ├── github-mcp.json
+│ ├── database-mcp.json
+│ ├── filesystem-mcp.json
+│ ├── multi-mcp.json
+│ └── README.md
+├── 06-hooks/
+│ ├── format-code.sh
+│ ├── pre-commit.sh
+│ ├── security-scan.sh
+│ ├── log-bash.sh
+│ ├── validate-prompt.sh
+│ ├── notify-team.sh
+│ └── README.md
+├── 07-plugins/
+│ ├── pr-review/
+│ ├── devops-automation/
+│ ├── documentation/
+│ └── README.md
+├── 08-checkpoints/
+│ ├── checkpoint-examples.md
+│ └── README.md
+├── 09-advanced-features/
+│ ├── config-examples.json
+│ ├── planning-mode-examples.md
+│ └── README.md
+├── 10-cli/
+│ └── README.md
+└── README.md(本文件)
+```
+
+</details>
+
+<details>
+<summary>最佳实践</summary>
+
+### 应该做的
+- 从简单的 slash commands 开始
+- 逐步增加功能
+- 用 memory 保存团队规范
+- 先在本地测试配置
+- 为自定义实现写文档
+- 对项目配置做版本控制
+- 和团队共享 plugins
+
+### 不应该做的
+- 不要创建重复功能
+- 不要硬编码凭据
+- 不要跳过文档
+- 不要把简单任务过度复杂化
+- 不要忽视安全最佳实践
+- 不要提交敏感数据
+
+</details>
+
+<details>
+<summary>故障排查</summary>
+
+### 功能没有加载
+1. 检查文件位置和命名
+2. 验证 YAML frontmatter 语法
+3. 检查文件权限
+4. 查看 Claude Code 版本兼容性
+
+### MCP 连接失败
+1. 检查环境变量
+2. 检查 MCP server 是否正确安装
+3. 测试凭据
+4. 检查网络连通性
+
+### Subagent 没有发生委派
+1. 检查工具权限
+2. 确认 agent 描述是否清晰
+3. 查看任务复杂度
+4. 单独测试 agent
+
+</details>
+
+<details>
+<summary>测试</summary>
+
+本项目包含完整的自动化测试:
+
+- **单元测试**:基于 pytest 的 Python 测试(Python 3.10、3.11、3.12)
+- **代码质量**:使用 Ruff 做 lint 和格式化检查
+- **安全**:使用 Bandit 做漏洞扫描
+- **类型检查**:使用 mypy 做静态类型分析
+- **构建验证**:测试 EPUB 生成功能
+- **覆盖率跟踪**:集成 Codecov
+
+```bash
+# 安装开发依赖
+uv pip install -r requirements-dev.txt
+
+# 运行全部单元测试
+pytest scripts/tests/ -v
+
+# 运行带覆盖率报告的测试
+pytest scripts/tests/ -v --cov=scripts --cov-report=html
+
+# 运行代码质量检查
+ruff check scripts/
+ruff format --check scripts/
+
+# 运行安全扫描
+bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/
+
+# 运行类型检查
+mypy scripts/ --ignore-missing-imports
+```
+
+每次 push 到 `main` / `develop`,以及每次向 `main` 提交 PR 时,测试都会自动运行。详情见 [TESTING.md](.github/TESTING.md)。
+
+</details>
+
+<details>
+<summary>EPUB 生成</summary>
+
+想离线阅读这份指南?你可以生成 EPUB 电子书:
+
+```bash
+uv run scripts/build_epub.py
+```
+
+这会生成包含全部内容与 Mermaid 渲染图表的 `claude-howto-guide.epub`。
+
+更多选项见 [scripts/README.md](scripts/README.md)。
+
+</details>
+
+<details>
+<summary>参与贡献</summary>
+
+发现问题,或者想贡献一个示例?非常欢迎你的帮助。
+
+**请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md),了解以下详细规范:**
+- 可贡献的内容类型(示例、文档、功能、bug、反馈)
+- 如何搭建开发环境
+- 目录结构以及如何添加内容
+- 编写规范与最佳实践
+- Commit 和 PR 流程
+
+**我们的社区标准:**
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - 我们如何彼此相处
+- [SECURITY.md](SECURITY.md) - 安全政策与漏洞报告方式
+
+### 报告安全问题
+
+如果你发现了安全漏洞,请负责任地报告:
+
+1. **使用 GitHub 私密漏洞报告功能**:https://github.com/luongnv89/claude-howto/security/advisories
+2. **或者阅读** [.github/SECURITY_REPORTING.md](.github/SECURITY_REPORTING.md) 获取详细说明
+3. **不要**公开提交安全漏洞 issue
+
+快速开始:
+1. Fork 并克隆仓库
+2. 创建一个清晰描述用途的分支(`add/feature-name`、`fix/bug`、`docs/improvement`)
+3. 按规范进行修改
+4. 提交一个说明清楚的 Pull Request
+
+**需要帮助?** 打开一个 issue 或 discussion,我们会引导你完成整个过程。
+
+</details>
+
+<details>
+<summary>更多资源</summary>
+
+- [Claude Code Documentation](https://code.claude.com/docs/en/overview)
+- [MCP Protocol Specification](https://modelcontextprotocol.io)
+- [Skills Repository](https://github.com/luongnv89/skills) - 可直接使用的 skills 集合
+- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook)
+- [Boris Cherny's Claude Code Workflow](https://x.com/bcherny/status/2007179832300581177) - Claude Code 的创造者分享了他系统化的工作流:并行 agents、共享 `CLAUDE.md`、Plan mode、slash commands、subagents,以及用于长时间自主会话的验证 hooks。
+
+</details>
+
+---
+
+## 参与贡献
+
+欢迎贡献内容。如何开始请查看我们的[贡献指南](CONTRIBUTING.md)。
+
+## 贡献者
+
+感谢所有为本项目做出贡献的人。
+
+| 贡献者 | PRs |
+|-------------|-----|
+| [wjhrdy](https://github.com/wjhrdy) | [#1 - add a tool to create an epub](https://github.com/luongnv89/claude-howto/pull/1) |
+| [VikalpP](https://github.com/VikalpP) | [#7 - fix(docs): Use tilde fences for nested code blocks in concepts guide](https://github.com/luongnv89/claude-howto/pull/7) |
+
+---
+
+## 许可证
+
+MIT 许可证,详见 [LICENSE](LICENSE)。你可以自由使用、修改和分发,唯一要求是保留许可证声明。
+
+---
+
+**最后更新**:2026 年 3 月
+**Claude Code 版本**:2.1+
+**兼容模型**:Claude Sonnet 4.6、Claude Opus 4.6、Claude Haiku 4.5
diff --git a/zh/RELEASE_NOTES.md b/zh/RELEASE_NOTES.md
new file mode 100644
index 0000000..e3cae71
--- /dev/null
+++ b/zh/RELEASE_NOTES.md
@@ -0,0 +1,8 @@
+## v2.2.0 - 2026-03-26
+
+### Bug 修复
+
+- 移除失效的 marketplace 链接,修复 CI 链接检查失败问题(3fdf0d6)
+- 将 `sandboxed` 和 `pycache` 加入 cSpell 词典(dc64618)
+
+**完整变更日志**: https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1
diff --git a/zh/SECURITY.md b/zh/SECURITY.md
new file mode 100644
index 0000000..6055a82
--- /dev/null
+++ b/zh/SECURITY.md
@@ -0,0 +1,334 @@
+# 安全政策
+
+## 概述
+
+Claude How To 项目的安全对我们非常重要。本文档说明我们的安全实践,以及如何负责任地报告安全漏洞。
+
+## 支持的版本
+
+我们为以下版本提供安全更新:
+
+| 版本 | 状态 | 支持至 |
+|---------|--------|---------------|
+| 最新版(main) | ✅ 活跃 | 当前版本 + 6 个月 |
+| 1.x 发布版 | ✅ 活跃 | 直到下一个大版本 |
+
+**注意**:作为一个教育指南项目,我们更关注维护当前最佳实践和文档安全,而不是传统意义上的版本支持。更新会直接应用到 main 分支。
+
+## 安全实践
+
+### 代码安全
+
+1. **依赖管理**
+ - 所有 Python 依赖都固定在 `requirements.txt` 中
+ - 通过 dependabot 和人工审查进行定期更新
+ - 每次提交都会运行 Bandit 安全扫描
+ - 使用 pre-commit hooks 做安全检查
+
+2. **代码质量**
+ - 使用 Ruff 做 lint,能捕获常见问题
+ - 使用 mypy 做类型检查,避免类型相关漏洞
+ - 通过 pre-commit hooks 强制执行标准
+ - 所有更改在合并前都要审查
+
+3. **访问控制**
+ - 对 `main` 分支启用分支保护
+ - 合并前需要审查通过
+ - 状态检查必须通过后才能合并
+ - 仓库写权限受限
+
+### 文档安全
+
+1. **示例中不放密钥**
+ - 所有示例中的 API key 都使用占位符
+ - 从不硬编码凭据
+ - `.env.example` 文件会展示所需变量
+ - 明确提示密钥管理风险
+
+2. **安全最佳实践**
+ - 示例会展示安全模式
+ - 文档中会突出安全警告
+ - 链接到官方安全指南
+ - 在相关章节中说明凭据处理方式
+
+3. **内容审查**
+ - 所有文档都会审查安全问题
+ - 贡献指南中包含安全注意事项
+ - 会验证外部链接和引用
+
+### 依赖安全
+
+1. **扫描**
+ - Bandit 会扫描所有 Python 代码中的漏洞
+ - 通过 GitHub 安全警报检查依赖漏洞
+ - 定期进行人工安全审计
+
+2. **更新**
+ - 安全补丁会尽快应用
+ - 大版本会谨慎评估
+ - 更新日志会包含安全相关变更
+
+3. **透明度**
+ - 安全更新会记录在提交中
+ - 漏洞披露会负责任地处理
+ - 在适当情况下发布公开安全公告
+
+## 漏洞报告
+
+### 我们关注的安全问题
+
+我们欢迎以下报告:
+- **代码漏洞**:脚本或示例中的漏洞
+- **依赖漏洞**:Python 包中的漏洞
+- **加密问题**:任何代码示例中的密码学问题
+- **认证/授权缺陷**:文档中的认证或授权问题
+- **数据暴露风险**:配置示例中的数据泄露风险
+- **注入漏洞**:SQL、命令等注入
+- **SSRF / XXE / 路径穿越** 问题
+
+### 不在范围内的安全问题
+
+以下问题不在本项目范围内:
+- Claude Code 本身的漏洞(请向 Anthropic 报告)
+- 外部服务或库的问题(请向上游项目报告)
+- 社会工程学或用户教育问题(与本指南无关)
+- 没有 PoC 的理论漏洞
+- 依赖库中已通过官方渠道报告的漏洞
+
+## 如何报告
+
+### 私密报告(推荐)
+
+**如遇敏感安全问题,请使用 GitHub 的私密漏洞报告:**
+
+1. 访问:<https://github.com/luongnv89/claude-howto/security/advisories>
+2. 点击 “Report a vulnerability”
+3. 填写漏洞细节
+4. 请包含:
+ - 漏洞的清晰描述
+ - 受影响的组件(文件、章节、示例)
+ - 潜在影响
+ - 复现步骤(如适用)
+ - 建议修复方式(如果你有)
+
+**接下来会发生什么:**
+- 我们会在 48 小时内确认收到
+- 我们会调查并评估严重性
+- 我们会与你一起修复
+- 我们会协调披露时间线
+- 如你愿意,我们会在安全公告中致谢
+
+### 公开报告
+
+对于不敏感或已公开的问题:
+
+1. **创建 GitHub Issue** 并打上 `security` 标签
+2. 包含:
+ - 标题:以 `[SECURITY]` 开头并附简短说明
+ - 详细描述
+ - 受影响的文件或章节
+ - 潜在影响
+ - 建议修复方式
+
+## 漏洞响应流程
+
+### 评估(24 小时内)
+
+1. 我们确认收到报告
+2. 我们使用 [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) 评估严重性
+3. 我们判断是否在范围内
+4. 我们向你反馈初步评估
+
+### 开发(1-7 天)
+
+1. 我们开发修复
+2. 我们审查并测试修复
+3. 我们创建安全公告
+4. 我们准备发布说明
+
+### 披露(取决于严重性)
+
+**严重(CVSS 9.0-10.0)**
+- 立即发布修复
+- 发布公开公告
+- 提前 24 小时通知报告者
+
+**高危(CVSS 7.0-8.9)**
+- 48-72 小时内发布修复
+- 提前 5 天通知报告者
+- 发布时公开公告
+
+**中危(CVSS 4.0-6.9)**
+- 在下一次常规更新中修复
+- 发布时公开公告
+
+**低危(CVSS 0.1-3.9)**
+- 在下一次常规更新中修复
+- 发布时附带公告
+
+### 公布
+
+我们发布的安全公告会包含:
+- 漏洞描述
+- 受影响组件
+- 严重性评估(CVSS 分数)
+- 修复版本
+- 临时缓解方案(如适用)
+- 对报告者的致谢(如获许可)
+
+## 报告者最佳实践
+
+### 报告前
+
+- **确认问题**:你能稳定复现吗?
+- **搜索已有 issue**:是否已经有人报告?
+- **查看文档**:是否已有安全使用说明?
+- **测试修复**:你建议的修复是否有效?
+
+### 报告时
+
+- **尽量具体**:提供准确的文件路径和行号
+- **补充上下文**:为什么这是安全问题?
+- **说明影响**:攻击者可能做什么?
+- **提供步骤**:如何复现?
+- **提出修复建议**:你会怎么修?
+
+### 报告后
+
+- **保持耐心**:我们的资源有限
+- **积极响应**:尽快回答后续问题
+- **保持保密**:在修复前不要公开披露
+- **尊重协调流程**:按时间线推进披露
+
+## 安全头与配置
+
+### 仓库安全
+
+- **分支保护**:主分支需要 2 份批准
+- **状态检查**:所有 CI/CD 检查必须通过
+- **CODEOWNERS**:关键文件有指定审查者
+- **签名提交**:建议贡献者使用
+
+### 开发安全
+
+```bash
+# 安装 pre-commit hooks
+pre-commit install
+
+# 本地运行安全扫描
+bandit -c pyproject.toml -r scripts/
+mypy scripts/ --ignore-missing-imports
+ruff check scripts/
+```
+
+### 依赖安全
+
+```bash
+# 检查已知漏洞
+pip install safety
+safety check
+
+# 或使用 pip-audit
+pip install pip-audit
+pip-audit
+```
+
+## 贡献者安全指南
+
+### 编写示例时
+
+1. **永远不要硬编码密钥**
+ ```python
+ # ❌ 不好
+ api_key = "sk-1234567890"
+
+ # ✅ 更好
+ api_key = os.getenv("API_KEY")
+ ```
+
+2. **提醒安全影响**
+ ```markdown
+ ⚠️ **安全提示**:切勿把 `.env` 文件提交到 git。
+ 请立即加入 `.gitignore`。
+ ```
+
+3. **使用安全默认值**
+ - 默认启用认证
+ - 在适用场景中使用 HTTPS
+ - 校验并清理输入
+ - 使用参数化查询
+
+4. **记录安全注意事项**
+ - 解释为什么安全很重要
+ - 展示安全与不安全的写法
+ - 链接权威来源
+ - 明显展示警告
+
+### 审查贡献时
+
+1. **检查是否泄露秘密**
+ - 扫描常见模式(api_key=、password= 等)
+ - 审查配置文件
+ - 检查环境变量使用情况
+
+2. **验证安全编码实践**
+ - 没有硬编码凭据
+ - 正确的输入验证
+ - 安全的认证/授权
+ - 安全的文件处理
+
+3. **测试安全影响**
+ - 这会不会被滥用?
+ - 最坏情况是什么?
+ - 有没有边界情况?
+
+## 安全资源
+
+### 官方标准
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [CWE Top 25](https://cwe.mitre.org/top25/)
+- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1)
+
+### Python 安全
+- [Python Security Advisories](https://www.python.org/dev/security/)
+- [PyPI Security](https://pypi.org/help/#security)
+- [Bandit Documentation](https://bandit.readthedocs.io/)
+
+### 依赖管理
+- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/)
+- [GitHub Security Alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts)
+
+### 通用安全
+- [Anthropic Security](https://www.anthropic.com/)
+- [GitHub Security Best Practices](https://docs.github.com/en/code-security)
+
+## 安全公告存档
+
+过往安全公告可在 GitHub 的 [Security Advisories](https://github.com/luongnv89/claude-howto/security/advisories) 标签页查看。
+
+## 联系方式
+
+如需咨询安全相关问题或讨论安全实践:
+
+1. **私密安全报告**:使用 GitHub 的私密漏洞报告
+2. **一般安全问题**:使用 `[SECURITY]` 标签发起 discussion
+3. **安全政策反馈**:创建带 `security` 标签的 issue
+
+## 致谢
+
+感谢帮助本项目保持安全的安全研究者和社区成员。负责任地报告漏洞的贡献者会在我们的安全公告中获得致谢(除非你希望匿名)。
+
+## 政策更新
+
+本安全政策会在以下情况更新:
+- 发现新漏洞时
+- 安全最佳实践演进时
+- 项目范围发生变化时
+- 至少每年一次
+
+**最后更新**:2026 年 1 月
+**下次审查**:2027 年 1 月
+
+---
+
+感谢你帮助 Claude How To 保持安全!🔒
diff --git a/zh/STYLE_GUIDE.md b/zh/STYLE_GUIDE.md
new file mode 100644
index 0000000..8086282
--- /dev/null
+++ b/zh/STYLE_GUIDE.md
@@ -0,0 +1,630 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+# 风格指南
+
+> 为 Claude How To 贡献内容时遵循的约定和格式规则。请按照这份指南保持内容一致、专业且易于维护。
+
+---
+
+## 目录
+
+- [文件与文件夹命名](#文件与文件夹命名)
+- [文档结构](#文档结构)
+- [标题](#标题)
+- [文本格式](#文本格式)
+- [列表](#列表)
+- [表格](#表格)
+- [代码块](#代码块)
+- [链接与交叉引用](#链接与交叉引用)
+- [图表](#图表)
+- [Emoji 用法](#emoji-用法)
+- [YAML Frontmatter](#yaml-frontmatter)
+- [图片与媒体](#图片与媒体)
+- [语气与文风](#语气与文风)
+- [提交信息](#提交信息)
+- [作者检查清单](#作者检查清单)
+
+---
+
+## 文件与文件夹命名
+
+### 课程文件夹
+
+课程文件夹使用一个 **两位数字前缀**,后接一个 **kebab-case** 描述符:
+
+```
+01-slash-commands/
+02-memory/
+03-skills/
+04-subagents/
+05-mcp/
+```
+
+这个数字反映了学习路径的顺序,从初学者到高级。
+
+### 文件名
+
+| 类型 | 约定 | 示例 |
+|------|-----------|----------|
+| **课程 README** | `README.md` | `01-slash-commands/README.md` |
+| **功能文件** | kebab-case `.md` | `code-reviewer.md`, `generate-api-docs.md` |
+| **Shell 脚本** | kebab-case `.sh` | `format-code.sh`, `validate-input.sh` |
+| **配置文件** | 标准名称 | `.mcp.json`, `settings.json` |
+| **记忆文件** | 带作用域前缀 | `project-CLAUDE.md`, `personal-CLAUDE.md` |
+| **顶层文档** | UPPER_CASE `.md` | `CATALOG.md`, `QUICK_REFERENCE.md`, `CONTRIBUTING.md` |
+| **图片资源** | kebab-case | `pr-slash-command.png`, `claude-howto-logo.svg` |
+
+### 规则
+
+- 除顶层文档外,所有文件和文件夹名都使用 **小写**
+- 使用连字符(`-`)作为单词分隔符,永远不要使用下划线或空格
+- 名称要具体,但保持简洁
+
+---
+
+## 文档结构
+
+### 根 README
+
+根目录 `README.md` 的顺序如下:
+
+1. Logo(使用带深色/浅色变体的 `<picture>` 元素)
+2. H1 标题
+3. 引导性引用块(一句话价值主张)
+4. “为什么需要这份指南?”部分,以及对比表
+5. 分隔线(`---`)
+6. 目录
+7. 功能目录
+8. 快速导航
+9. 学习路径
+10. 功能章节
+11. 快速上手
+12. 最佳实践 / 故障排查
+13. 参与贡献 / 许可证
+
+### 课程 README
+
+每个课程 `README.md` 的顺序如下:
+
+1. H1 标题,例如 `# Slash Commands`
+2. 简短概述段落
+3. 快速参考表格(可选)
+4. 架构图(Mermaid)
+5. 详细章节(H2)
+6. 实用示例(编号列表,4-6 个示例)
+7. 最佳实践(Do's 和 Don'ts 表)
+8. 故障排查
+9. 相关指南 / 官方文档
+10. 文档元数据页脚
+
+### 功能/示例文件
+
+单个功能文件,例如 `optimize.md`、`pr.md`:
+
+1. YAML frontmatter(如果适用)
+2. H1 标题
+3. 目的 / 描述
+4. 使用说明
+5. 代码示例
+6. 自定义提示
+
+### 分隔线
+
+使用水平分隔线(`---`)来分隔文档中的主要区域:
+
+```markdown
+---
+
+## New Major Section
+```
+
+将它们放在引导性引用块之后,以及文档中逻辑上不同的部分之间。
+
+---
+
+## 标题
+
+### 层级
+
+| 级别 | 用途 | 示例 |
+|-------|-----|---------|
+| `#` H1 | 页面标题,每个文档一个 | `# Slash Commands` |
+| `##` H2 | 主要章节 | `## Best Practices` |
+| `###` H3 | 子章节 | `### Adding a Skill` |
+| `####` H4 | 再下一级子章节,较少使用 | `#### Configuration Options` |
+
+### 规则
+
+- **每个文档只允许一个 H1**,即页面标题
+- **不要跳级**,不要从 H2 直接跳到 H4
+- **标题要简洁**,尽量控制在 2-5 个词
+- **使用句首大写**,只大写首字和专有名词(例外:功能名保持原样)
+- **只有根 README 的章节标题** 可以使用 Emoji 前缀,见 [Emoji 用法](#emoji-用法)
+
+---
+
+## 文本格式
+
+### 强调
+
+| 样式 | 使用时机 | 示例 |
+|-------|------------|---------|
+| **粗体** (`**text**`) | 关键术语、表格标签、重要概念 | `**Installation**:` |
+| *斜体* (`*text*`) | 技术术语首次出现、书名或文档名 | `*frontmatter*` |
+| `Code` (`` `text` ``) | 文件名、命令、配置值、代码引用 | `` `CLAUDE.md` `` |
+
+### 使用引述块做提示
+
+对重要说明使用带粗体前缀的引述块:
+
+```markdown
+> **Note**: Custom slash commands have been merged into skills since v2.0.
+
+> **Important**: Never commit API keys or credentials.
+
+> **Tip**: Combine memory with skills for maximum effectiveness.
+```
+
+支持的提示类型:**Note**、**Important**、**Tip**、**Warning**。
+
+### 段落
+
+- 保持段落简短,2-4 句为宜
+- 段落之间留一个空行
+- 先说重点,再补充上下文
+- 解释“为什么”,不只是“是什么”
+
+---
+
+## 列表
+
+### 无序列表
+
+使用短横线(`-`),嵌套时使用 2 个空格缩进:
+
+```markdown
+- First item
+- Second item
+ - Nested item
+ - Another nested item
+ - Deep nested (avoid going deeper than 3 levels)
+- Third item
+```
+
+### 有序列表
+
+用于顺序步骤、操作说明和排序项:
+
+```markdown
+1. First step
+2. Second step
+ - Sub-point detail
+ - Another sub-point
+3. Third step
+```
+
+### 说明性列表
+
+对键值对风格的列表,使用粗体标签:
+
+```markdown
+- **Performance bottlenecks** - identify O(n^2) operations, inefficient loops
+- **Memory leaks** - find unreleased resources, circular references
+- **Algorithm improvements** - suggest better algorithms or data structures
+```
+
+### 规则
+
+- 保持一致的缩进,每层 2 个空格
+- 列表前后都要空一行
+- 列表项结构要平行一致,例如都用动词开头,或者都用名词开头
+- 嵌套深度不要超过 3 层
+
+---
+
+## 表格
+
+### 标准格式
+
+```markdown
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| Data | Data | Data |
+```
+
+### 常见表格模式
+
+**功能对比(3-4 列):**
+
+```markdown
+| Feature | Invocation | Persistence | Best For |
+|---------|-----------|------------|----------|
+| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts |
+| **Memory** | Auto-loaded | Cross-session | Long-term learning |
+```
+
+**Do's and Don'ts:**
+
+```markdown
+| Do | Don't |
+|----|-------|
+| Use descriptive names | Use vague names |
+| Keep files focused | Overload a single file |
+```
+
+**快速参考:**
+
+```markdown
+| Aspect | Details |
+|--------|---------|
+| **Purpose** | Generate API documentation |
+| **Scope** | Project-level |
+| **Complexity** | Intermediate |
+```
+
+### 规则
+
+- 当表头是行标签时,**表头要加粗**
+- 代码源文件中的管道符尽量对齐,便于阅读(可选但推荐)
+- 单元格内容要简洁;细节用链接展开
+- 命令和文件路径在单元格中要使用 `代码格式`
+
+---
+
+## 代码块
+
+### 语言标签
+
+始终为语法高亮指定语言标签:
+
+| 语言 | 标签 | 用途 |
+|----------|-----|---------|
+| Shell | `bash` | CLI 命令、脚本 |
+| Python | `python` | Python 代码 |
+| JavaScript | `javascript` | JS 代码 |
+| TypeScript | `typescript` | TS 代码 |
+| JSON | `json` | 配置文件 |
+| YAML | `yaml` | Frontmatter、配置 |
+| Markdown | `markdown` | Markdown 示例 |
+| SQL | `sql` | 数据库查询 |
+| Plain text | (no tag) | 期望输出、目录树 |
+
+### 约定
+
+```bash
+# Comment explaining what the command does
+claude mcp add notion --transport http https://mcp.notion.com/mcp
+```
+
+- 在不明显的命令前添加一行 **注释**
+- 所有示例都要做到 **可直接复制粘贴**
+- 相关时同时提供 **简单版和高级版**
+- 需要时要给出 **期望输出**,这时使用不带标签的代码块
+
+### 安装示例
+
+安装说明请使用以下模式:
+
+```bash
+# Copy files to your project
+cp 01-slash-commands/*.md .claude/commands/
+```
+
+### 多步骤工作流
+
+```bash
+# Step 1: Create the directory
+mkdir -p .claude/commands
+
+# Step 2: Copy the templates
+cp 01-slash-commands/*.md .claude/commands/
+
+# Step 3: Verify installation
+ls .claude/commands/
+```
+
+---
+
+## 链接与交叉引用
+
+### 内部链接(相对路径)
+
+内部链接全部使用相对路径:
+
+```markdown
+[Slash Commands](01-slash-commands/README.md)
+[Skills Guide](03-skills/README.md)
+[Memory Architecture](02-memory/README.md)
+```
+
+从课程文件夹返回根目录或兄弟目录:
+
+```markdown
+[返回主指南](README.md)
+[相关:Skills](03-skills/README.md)
+```
+
+### 外部链接(绝对路径)
+
+使用完整 URL,并使用具有描述性的锚文本:
+
+```markdown
+[Anthropic's official documentation](https://code.claude.com/docs/en/overview)
+```
+
+- 不要使用“click here”或“this link”作为锚文本
+- 使用脱离上下文也能理解的描述性文字
+
+### 章节锚点
+
+链接到同一文档中的章节时,使用 GitHub 风格锚点:
+
+```markdown
+[文件与文件夹命名](#文件与文件夹命名)
+[作者检查清单](#作者检查清单)
+```
+
+### 相关指南模式
+
+课程末尾要附上相关指南章节:
+
+```markdown
+## Related Guides
+
+- [Slash Commands](01-slash-commands/README.md) - 快速快捷命令
+- [Memory](02-memory/README.md) - 持久上下文
+- [Skills](03-skills/README.md) - 可复用能力
+```
+
+---
+
+## 图表
+
+### Mermaid
+
+所有图表都使用 Mermaid。支持的类型包括:
+
+- `graph TB` / `graph LR` - 架构、层级、流程
+- `sequenceDiagram` - 交互流程
+- `timeline` - 时间顺序
+
+### 样式约定
+
+使用 style block 保持颜色一致:
+
+```mermaid
+graph TB
+ A["Component A"] --> B["Component B"]
+ B --> C["Component C"]
+
+ style A fill:#e1f5fe,stroke:#333,color:#333
+ style B fill:#fce4ec,stroke:#333,color:#333
+ style C fill:#e8f5e9,stroke:#333,color:#333
+```
+
+**颜色调色板:**
+
+| Color | Hex | Use For |
+|-------|-----|---------|
+| Light blue | `#e1f5fe` | Primary components, inputs |
+| Light pink | `#fce4ec` | Processing, middleware |
+| Light green | `#e8f5e9` | Outputs, results |
+| Light yellow | `#fff9c4` | Configuration, optional |
+| Light purple | `#f3e5f5` | User-facing, UI |
+
+### 规则
+
+- 节点标签使用 `["Label text"]`,这样可以包含特殊字符
+- 在标签中换行使用 `<br/>`
+- 图表保持简洁,最多 10-12 个节点
+- 图表下方添加简短文字说明,方便无障碍阅读
+- 层级结构使用自上而下(`TB`),流程使用左右(`LR`)
+
+---
+
+## Emoji 用法
+
+### Emoji 的使用场景
+
+Emoji 使用要 **克制且有目的**,只在特定场景中出现:
+
+| 场景 | Emoji | 示例 |
+|---------|--------|---------|
+| Root README 章节标题 | 分类图标 | `## 📚 Learning Path` |
+| Skill 等级指示 | 彩色圆点 | 🟢 Beginner, 🔵 Intermediate, 🔴 Advanced |
+| Do's 和 Don'ts | 对勾/叉号 | ✅ Do this, ❌ Don't do this |
+| 复杂度评级 | 星星 | ⭐⭐⭐ |
+
+### 标准 Emoji 集合
+
+| Emoji | 含义 |
+|-------|---------|
+| 📚 | 学习、指南、文档 |
+| ⚡ | 快速上手、速查 |
+| 🎯 | 功能、速查 |
+| 🎓 | 学习路径 |
+| 📊 | 统计、对比 |
+| 🚀 | 安装、快速命令 |
+| 🟢 | 初学者级别 |
+| 🔵 | 中级别 |
+| 🔴 | 高级别 |
+| ✅ | 推荐做法 |
+| ❌ | 避免 / 反模式 |
+| ⭐ | 复杂度评级单位 |
+
+### 规则
+
+- **不要在正文或段落中使用 Emoji**
+- **只在根 README 的标题中使用 Emoji**,不要在课程 README 中使用
+- **不要添加装饰性 Emoji**,每个 Emoji 都应该有意义
+- Emoji 的使用要与上表保持一致
+
+---
+
+## YAML Frontmatter
+
+### 功能文件(Skills、Commands、Agents)
+
+```yaml
+---
+name: unique-identifier
+description: What this feature does and when to use it
+allowed-tools: Bash, Read, Grep
+---
+```
+
+### 可选字段
+
+```yaml
+---
+name: my-feature
+description: Brief description
+argument-hint: "[file-path] [options]"
+allowed-tools: Bash, Read, Grep, Write, Edit
+model: opus # opus, sonnet, or haiku
+disable-model-invocation: true # User-only invocation
+user-invocable: false # Hidden from user menu
+context: fork # Run in isolated subagent
+agent: Explore # Agent type for context: fork
+---
+```
+
+### 规则
+
+- Frontmatter 放在文件最顶部
+- `name` 字段使用 **kebab-case**
+- `description` 保持为一句话
+- 只包含真正需要的字段
+
+---
+
+## 图片与媒体
+
+### Logo 模式
+
+所有以 Logo 开头的文档都使用 `<picture>` 元素,以支持深色/浅色模式:
+
+```html
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+```
+
+### 截图
+
+- 存放在对应课程文件夹中,例如 `01-slash-commands/pr-slash-command.png`
+- 使用 kebab-case 文件名
+- 包含描述性的 alt 文本
+- 图表优先使用 SVG,截图优先使用 PNG
+
+### 规则
+
+- 图片始终要有 alt 文本
+- 控制图片文件大小,PNG 尽量小于 500KB
+- 图片引用使用相对路径
+- 图片存放在引用它的文档同目录,或者放在 `assets/` 里供共享使用
+
+---
+
+## 语气与文风
+
+### 写作风格
+
+- **专业但亲切** - 技术准确,同时不过度堆砌术语
+- **主动语态** - 说“Create a file”,不要说“一个文件应该被创建”
+- **直接指令** - 说“Run this command”,不要说“你也许可以运行这个命令”
+- **适合初学者** - 假设读者是 Claude Code 新手,但不是编程新手
+
+### 内容原则
+
+| 原则 | 示例 |
+|-----------|---------|
+| **Show, don't tell** | 提供可运行示例,而不是抽象描述 |
+| **渐进式复杂度** | 先简单,后面再增加深度 |
+| **解释“为什么”** | “Use memory for... because...” 而不只是 “Use memory for...” |
+| **可直接复制粘贴** | 每个代码块都应能直接粘贴使用 |
+| **真实场景** | 使用实际场景,而不是牵强的例子 |
+
+### 词汇
+
+- 使用 “Claude Code”(不要写 “Claude CLI” 或 “the tool”)
+- 使用 “skill”(不要写 “custom command”,这是旧术语)
+- 使用 “lesson” 或 “guide” 来称呼编号章节
+- 使用 “example” 来称呼单个功能文件
+
+---
+
+## 提交信息
+
+遵循 [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): description
+```
+
+### 类型
+
+| Type | Use For |
+|------|---------|
+| `feat` | 新功能、示例或指南 |
+| `fix` | Bug 修复、纠正、损坏链接 |
+| `docs` | 文档改进 |
+| `refactor` | 只重构、不改变行为 |
+| `style` | 仅格式化改动 |
+| `test` | 测试新增或修改 |
+| `chore` | 构建、依赖、CI |
+
+### 作用域
+
+使用课程名称或文件区域作为作用域:
+
+```
+feat(slash-commands): Add API documentation generator
+docs(memory): Improve personal preferences example
+fix(README): Correct table of contents link
+docs(skills): Add comprehensive code review skill
+```
+
+---
+
+## 文档元数据页脚
+
+课程 README 以元数据块结尾:
+
+```markdown
+---
+**Last Updated**: March 2026
+**Claude Code Version**: 2.1+
+**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5
+```
+
+- 使用“月份 + 年份”格式,例如 “March 2026”
+- 功能变化时更新版本
+- 列出所有兼容模型
+
+---
+
+## 作者检查清单
+
+提交内容前,请确认:
+
+- [ ] 文件/文件夹名使用 kebab-case
+- [ ] 文档以 H1 标题开头,每个文件一个
+- [ ] 标题层级正确,没有跳级
+- [ ] 所有代码块都带语言标签
+- [ ] 代码示例可直接复制粘贴
+- [ ] 内部链接使用相对路径
+- [ ] 外部链接使用描述性锚文本
+- [ ] 表格格式正确
+- [ ] Emoji 遵循标准集合(如果使用)
+- [ ] Mermaid 图表使用标准配色
+- [ ] 没有敏感信息,例如 API key、凭据
+- [ ] YAML frontmatter 有效(如果适用)
+- [ ] 图片有 alt 文本
+- [ ] 段落简短且聚焦
+- [ ] 相关指南章节链接到合适的课程
+- [ ] 提交信息符合 conventional commits 格式
diff --git a/zh/claude_concepts_guide.md b/zh/claude_concepts_guide.md
new file mode 100644
index 0000000..5049c02
--- /dev/null
+++ b/zh/claude_concepts_guide.md
@@ -0,0 +1,1540 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Claude Concepts 完整指南
+
+这是一份全面的参考指南,覆盖 Slash Commands、Subagents、Memory、MCP Protocol、Agent Skills、Plugins、Hooks、Checkpoints、Advanced Features 等 Claude Code 核心概念,并配有表格、图示和实践示例。
+
+---
+
+## 目录
+
+1. [Slash Commands](#slash-commands)
+2. [Subagents](#subagents)
+3. [Memory](#memory)
+4. [MCP Protocol](#mcp-protocol)
+5. [Agent Skills](#agent-skills)
+6. [Plugins](#claude-code-plugins)
+7. [Hooks](#hooks)
+8. [Checkpoints and Rewind](#checkpoints-and-rewind)
+9. [Advanced Features](#advanced-features)
+10. [Comparison & Integration](#comparison--integration)
+
+---
+
+## Slash Commands
+
+### 概览
+
+Slash commands 是由用户手动触发的快捷命令,以 Markdown 文件形式保存,Claude Code 可以读取并执行。它们非常适合把高频提示词与工作流标准化,方便团队复用。
+
+### 架构
+
+```mermaid
+graph TD
+ A["用户输入: /command-name"] -->|触发| B["搜索 .claude/commands/"]
+ B -->|找到| C["command-name.md"]
+ C -->|加载| D["Markdown 内容"]
+ D -->|执行| E["Claude 处理提示"]
+ E -->|返回| F["上下文中的结果"]
+```
+
+### 文件结构
+
+```mermaid
+graph LR
+ A["项目根目录"] -->|包含| B[".claude/commands/"]
+ B -->|包含| C["optimize.md"]
+ B -->|包含| D["test.md"]
+ B -->|包含| E["docs/"]
+ E -->|包含| F["generate-api-docs.md"]
+ E -->|包含| G["generate-readme.md"]
+```
+
+### 命令组织表
+
+| 位置 | 作用域 | 可用范围 | 适用场景 | Git 跟踪 |
+|------|--------|----------|----------|-----------|
+| `.claude/commands/` | 项目级 | 团队成员 | 团队工作流、共享标准 | ✅ 是 |
+| `~/.claude/commands/` | 个人级 | 当前用户 | 跨项目的个人快捷命令 | ❌ 否 |
+| 子目录 | 命名空间 | 取决于父目录 | 按类别组织命令 | ✅ 是 |
+
+### 功能与能力
+
+| 功能 | 示例 | 是否支持 |
+|------|------|----------|
+| Shell 脚本执行 | `bash scripts/deploy.sh` | ✅ 是 |
+| 文件引用 | `@path/to/file.js` | ✅ 是 |
+| Bash 集成 | `$(git log --oneline)` | ✅ 是 |
+| 参数 | `/pr --verbose` | ✅ 是 |
+| MCP 命令 | `/mcp__github__list_prs` | ✅ 是 |
+
+### 实践示例
+
+#### 示例 1:代码优化命令
+
+**文件:** `.claude/commands/optimize.md`
+
+```markdown
+---
+name: 代码优化
+description: 分析代码中的性能问题并给出优化建议
+tags: performance, analysis
+---
+
+# 代码优化
+
+请按以下优先级顺序审查给定代码中的问题:
+
+1. **性能瓶颈** - 识别 O(n²) 操作、低效循环
+2. **内存泄漏** - 查找未释放资源、循环引用
+3. **算法改进** - 建议更优算法或数据结构
+4. **缓存机会** - 识别重复计算
+5. **并发问题** - 查找竞态条件或线程问题
+
+请按以下格式输出:
+- 问题严重级别(Critical/High/Medium/Low)
+- 代码位置
+- 解释说明
+- 带代码示例的修复建议
+```
+
+**使用方式:**
+```bash
+# 用户在 Claude Code 中输入
+/optimize
+
+# Claude 加载提示并等待代码输入
+```
+
+#### 示例 2:Pull Request 辅助命令
+
+**文件:** `.claude/commands/pr.md`
+
+```markdown
+---
+name: 准备 Pull Request
+description: 清理代码、暂存改动并准备一个 Pull Request
+tags: git, workflow
+---
+
+# Pull Request 准备清单
+
+在创建 PR 前,执行以下步骤:
+
+1. 运行 lint:`prettier --write .`
+2. 运行测试:`npm test`
+3. 查看 git diff:`git diff HEAD`
+4. 暂存改动:`git add .`
+5. 按 conventional commits 规则编写提交信息:
+ - `fix:` 用于 bug 修复
+ - `feat:` 用于新功能
+ - `docs:` 用于文档更新
+ - `refactor:` 用于代码重构
+ - `test:` 用于补充测试
+ - `chore:` 用于维护性工作
+
+6. 生成 PR 摘要,包括:
+ - 改了什么
+ - 为什么改
+ - 做了哪些测试
+ - 可能的影响
+```
+
+**使用方式:**
+```bash
+/pr
+
+# Claude 按清单逐项检查并准备 PR
+```
+
+#### 示例 3:分层式文档生成器
+
+**文件:** `.claude/commands/docs/generate-api-docs.md`
+
+```markdown
+---
+name: 生成 API 文档
+description: 基于源代码生成完整 API 文档
+tags: documentation, api
+---
+
+# API 文档生成器
+
+通过以下步骤生成 API 文档:
+
+1. 扫描 `/src/api/` 下的所有文件
+2. 提取函数签名和 JSDoc 注释
+3. 按 endpoint / module 组织结构
+4. 生成带示例的 Markdown
+5. 包含请求 / 响应 schema
+6. 补充错误文档
+
+输出格式:
+- 输出 Markdown 文件到 `/docs/api.md`
+- 为所有端点包含 curl 示例
+- 补充 TypeScript 类型
+```
+
+### 命令生命周期图
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Claude as Claude Code
+ participant FS as File System
+ participant CLI as Shell/Bash
+
+ User->>Claude: 输入 /optimize
+ Claude->>FS: 搜索 .claude/commands/
+ FS-->>Claude: 返回 optimize.md
+ Claude->>Claude: 加载 Markdown 内容
+ Claude->>User: 显示提示上下文
+ User->>Claude: 提供待分析代码
+ Claude->>CLI: (可能执行脚本)
+ CLI-->>Claude: 返回结果
+ Claude->>User: 输出分析
+```
+
+### 最佳实践
+
+| ✅ 建议 | ❌ 不建议 |
+|------|---------|
+| 使用清晰、面向动作的命名 | 为一次性任务创建命令 |
+| 在描述中写清触发场景 | 在命令里堆复杂逻辑 |
+| 保持命令聚焦单一任务 | 创建重复命令 |
+| 将项目命令纳入版本控制 | 硬编码敏感信息 |
+| 使用子目录组织分类 | 做过长的命令列表 |
+| 使用简单、可读的提示词 | 使用晦涩或过度缩写的措辞 |
+
+---
+
+## Subagents
+
+### 概览
+
+Subagents 是带有隔离上下文窗口和自定义系统提示词的专门化 AI 助手。它们让 Claude 能够把复杂任务拆分并委派出去,同时保持关注点清晰分离。
+
+### 架构图
+
+```mermaid
+graph TB
+ User["👤 用户"]
+ Main["🎯 主 Agent<br/>(协调者)"]
+ Reviewer["🔍 代码审查<br/>Subagent"]
+ Tester["✅ 测试工程师<br/>Subagent"]
+ Docs["📝 文档编写<br/>Subagent"]
+
+ User -->|提出请求| Main
+ Main -->|委派| Reviewer
+ Main -->|委派| Tester
+ Main -->|委派| Docs
+ Reviewer -->|返回结果| Main
+ Tester -->|返回结果| Main
+ Docs -->|返回结果| Main
+ Main -->|汇总| User
+```
+
+### Subagent 生命周期
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant MainAgent as 主 Agent
+ participant CodeReviewer as 代码审查<br/>Subagent
+ participant Context as 独立的<br/>上下文窗口
+
+ User->>MainAgent: “构建新的认证功能”
+ MainAgent->>MainAgent: 分析任务
+ MainAgent->>CodeReviewer: “审查这段代码”
+ CodeReviewer->>Context: 初始化干净上下文
+ Context->>CodeReviewer: 加载审查规则
+ CodeReviewer->>CodeReviewer: 执行审查
+ CodeReviewer-->>MainAgent: 返回发现
+ MainAgent->>MainAgent: 融合结果
+ MainAgent-->>User: 输出综合结论
+```
+
+### Subagent 配置表
+
+| 配置项 | 类型 | 作用 | 示例 |
+|--------|------|------|------|
+| `name` | String | Agent 标识符 | `code-reviewer` |
+| `description` | String | 用途与触发词 | `Comprehensive code quality analysis` |
+| `tools` | List/String | 允许的能力 | `read, grep, diff, lint_runner` |
+| `system_prompt` | Markdown | 行为指令 | 自定义规范 |
+
+### 工具访问层级
+
+```mermaid
+graph TD
+ A["Subagent 配置"] -->|选项 1| B["继承主线程的全部工具"]
+ A -->|选项 2| C["显式指定工具"]
+ B -->|包含| B1["文件操作"]
+ B -->|包含| B2["Shell 命令"]
+ B -->|包含| B3["MCP 工具"]
+ C -->|显式列表| C1["read, grep, diff"]
+ C -->|显式列表| C2["Bash(npm:*), Bash(test:*)"]
+```
+
+### 实践示例
+
+#### 示例 1:完整 Subagent 配置
+
+**文件:** `.claude/agents/code-reviewer.md`
+
+```yaml
+---
+name: code-reviewer
+description: Comprehensive code quality and maintainability analysis
+tools: read, grep, diff, lint_runner
+---
+
+# Code Reviewer Agent
+
+You are an expert code reviewer specializing in:
+- Performance optimization
+- Security vulnerabilities
+- Code maintainability
+- Testing coverage
+- Design patterns
+
+## Review Priorities (in order)
+
+1. **Security Issues** - Authentication, authorization, data exposure
+2. **Performance Problems** - O(n²) operations, memory leaks, inefficient queries
+3. **Code Quality** - Readability, naming, documentation
+4. **Test Coverage** - Missing tests, edge cases
+5. **Design Patterns** - SOLID principles, architecture
+
+## Review Output Format
+
+针对每个问题:
+- **Severity**: Critical / High / Medium / Low
+- **Category**: Security / Performance / Quality / Testing / Design
+- **Location**: File path and line number
+- **Issue Description**: What's wrong and why
+- **Suggested Fix**: Code example
+- **Impact**: How this affects the system
+```
+
+**文件:** `.claude/agents/test-engineer.md`
+
+```yaml
+---
+name: test-engineer
+description: Test strategy, coverage analysis, and automated testing
+tools: read, write, bash, grep
+---
+
+# Test Engineer Agent
+
+You are expert at:
+- Writing comprehensive test suites
+- Ensuring high code coverage (>80%)
+- Testing edge cases and error scenarios
+- Performance benchmarking
+- Integration testing
+```
+
+**文件:** `.claude/agents/documentation-writer.md`
+
+```yaml
+---
+name: documentation-writer
+description: Technical documentation, API docs, and user guides
+tools: read, write, grep
+---
+
+# Documentation Writer Agent
+
+You create:
+- API documentation with examples
+- User guides and tutorials
+- Architecture documentation
+- Changelog entries
+- Code comment improvements
+```
+
+#### 示例 2:Subagent 委派流程
+
+```markdown
+# 场景:构建支付功能
+
+## 用户请求
+"构建一个与 Stripe 集成的安全支付处理功能"
+
+## 主 Agent 工作流
+
+1. **规划阶段**
+ - 理解需求
+ - 确定所需任务
+ - 规划架构
+
+2. **委派给 Code Reviewer Subagent**
+ - 任务:"审查支付处理实现中的安全问题"
+ - 上下文:认证、API 密钥、token 处理
+ - 重点:SQL 注入、密钥泄露、HTTPS 强制
+
+3. **委派给 Test Engineer Subagent**
+ - 任务:"为支付流程创建完整测试"
+ - 上下文:成功场景、失败场景、边界情况
+ - 输出:有效支付、拒付、网络故障、webhook 测试
+
+4. **委派给 Documentation Writer Subagent**
+ - 任务:"为支付 API 端点编写文档"
+ - 上下文:请求 / 响应 schema
+ - 产出:带 curl 示例和错误码的 API 文档
+
+5. **综合**
+ - 主 Agent 汇总所有输出
+ - 整合发现
+ - 返回完整方案给用户
+```
+
+#### 示例 3:工具权限范围
+
+**受限配置:只允许特定能力**
+
+```yaml
+---
+name: secure-reviewer
+description: Security-focused code review with minimal permissions
+tools: read, grep
+---
+
+# Secure Code Reviewer
+
+Reviews code for security vulnerabilities only.
+```
+
+**扩展配置:为实现任务开放全部工具**
+
+```yaml
+---
+name: implementation-agent
+description: Full implementation capabilities for feature development
+tools: read, write, bash, grep, edit, glob
+---
+
+# Implementation Agent
+
+Builds features from specifications.
+```
+
+### Subagent 上下文管理
+
+```mermaid
+graph TB
+ A["主 Agent 上下文<br/>50,000 tokens"]
+ B["Subagent 1 上下文<br/>20,000 tokens"]
+ C["Subagent 2 上下文<br/>20,000 tokens"]
+ D["Subagent 3 上下文<br/>20,000 tokens"]
+
+ A -->|干净上下文| B
+ A -->|干净上下文| C
+ A -->|干净上下文| D
+
+ B -->|仅返回结果| A
+ C -->|仅返回结果| A
+ D -->|仅返回结果| A
+
+ style A fill:#e1f5ff
+ style B fill:#fff9c4
+ style C fill:#fff9c4
+ style D fill:#fff9c4
+```
+
+### 何时使用 Subagents
+
+| 场景 | 是否使用 Subagent | 原因 |
+|------|------------------|------|
+| 多步骤复杂功能 | ✅ 是 | 分离关注点,防止上下文污染 |
+| 快速代码审查 | ❌ 否 | 开销不值得 |
+| 并行任务执行 | ✅ 是 | 每个 subagent 都有自己的上下文 |
+| 需要专业化角色 | ✅ 是 | 可以用自定义系统提示词 |
+| 长时间分析任务 | ✅ 是 | 防止主上下文耗尽 |
+| 单一步骤任务 | ❌ 否 | 只会增加延迟 |
+
+### Agent Teams
+
+Agent Teams 用于协调多个 agent 围绕一个共同目标协作。与一次只委派一个 subagent 不同,Agent Teams 允许主 agent 编排一组协作代理,在共享中间结果的同时并行推进大任务,例如由前端 agent、后端 agent、测试 agent 一起完成一个全栈功能。
+
+---
+
+## Memory
+
+### 概览
+
+Memory 让 Claude 能够在不同会话和对话之间保留上下文。它主要有两种形态:Claude Web/Desktop 中的自动记忆综合,以及 Claude Code 中基于文件系统的 `CLAUDE.md`。
+
+### Memory 架构
+
+```mermaid
+graph TB
+ A["Claude 会话"]
+ B["用户输入"]
+ C["记忆系统"]
+ D["记忆存储"]
+
+ B -->|用户提供信息| C
+ C -->|每 24 小时综合| D
+ D -->|自动加载| A
+ A -->|使用上下文| C
+```
+
+### Claude Code 中的 7 层记忆层级
+
+Claude Code 会按优先级从高到低加载 7 层记忆:
+
+```mermaid
+graph TD
+ A["1. Managed Policy<br/>企业管理员策略"] --> B["2. Project Memory<br/>./CLAUDE.md"]
+ B --> C["3. Project Rules<br/>.claude/rules/*.md"]
+ C --> D["4. User Memory<br/>~/.claude/CLAUDE.md"]
+ D --> E["5. User Rules<br/>~/.claude/rules/*.md"]
+ E --> F["6. Local Memory<br/>.claude/local/CLAUDE.md"]
+ F --> G["7. Auto Memory<br/>自动捕获的偏好"]
+```
+
+### Memory 位置表
+
+| 层级 | 位置 | 作用域 | 优先级 | 是否共享 | 最适合 |
+|------|------|--------|--------|----------|--------|
+| 1. Managed Policy | 企业管理员 | 组织级 | 最高 | 全组织用户 | 合规、安全策略 |
+| 2. Project | `./CLAUDE.md` | 项目级 | 高 | 团队(Git) | 团队标准、架构 |
+| 3. Project Rules | `.claude/rules/*.md` | 项目级 | 高 | 团队(Git) | 模块化项目约定 |
+| 4. User | `~/.claude/CLAUDE.md` | 个人级 | 中 | 个人 | 个人偏好 |
+| 5. User Rules | `~/.claude/rules/*.md` | 个人级 | 中 | 个人 | 个人规则模块 |
+| 6. Local | `.claude/local/CLAUDE.md` | 本地 | 低 | 不共享 | 机器相关设置 |
+| 7. Auto Memory | 自动生成 | 会话级 | 最低 | 个人 | 学到的偏好与模式 |
+
+### Auto Memory
+
+Auto Memory 会在会话中自动捕获用户偏好与行为模式。Claude 会记住:
+
+- 代码风格偏好
+- 你常做的纠正
+- 框架和工具选择
+- 沟通方式偏好
+
+它在后台工作,不需要手动配置。
+
+### Memory 更新生命周期
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Claude as Claude Code
+ participant Editor as File System
+ participant Memory as CLAUDE.md
+
+ User->>Claude: “记住:统一使用 async/await”
+ Claude->>User: “写入哪个记忆文件?”
+ User->>Claude: “项目记忆”
+ Claude->>Editor: 打开 ~/.claude/settings.json
+ Claude->>Memory: 写入 ./CLAUDE.md
+ Memory-->>Claude: 文件已保存
+ Claude->>Claude: 重新加载记忆
+ Claude-->>User: “记忆已保存!”
+```
+
+### 实践示例
+
+#### 示例 1:项目级记忆结构
+
+**文件:** `./CLAUDE.md`
+
+```markdown
+# 项目配置
+
+## 项目概览
+- **名称**:电商平台
+- **技术栈**:Node.js、PostgreSQL、React 18、Docker
+- **团队规模**:5 名开发者
+- **截止时间**:2025 年第 4 季度
+
+## 架构
+@docs/architecture.md
+@docs/api-standards.md
+@docs/database-schema.md
+
+## 开发标准
+
+### Code Style
+- 使用 Prettier 格式化
+- 使用 ESLint + airbnb config
+- 最大行宽 100 字符
+- 使用 2 空格缩进
+
+### Naming Conventions
+- **文件**:kebab-case
+- **类**:PascalCase
+- **函数/变量**:camelCase
+- **常量**:UPPER_SNAKE_CASE
+- **数据库表**:snake_case
+```
+
+#### 示例 2:目录级记忆
+
+**文件:** `./src/api/CLAUDE.md`
+
+~~~~markdown
+# API 模块标准
+
+该文件会覆盖根目录 `CLAUDE.md` 中对 `/src/api/` 的规则。
+
+## API 专属标准
+
+### Request Validation
+- 使用 Zod 做 schema 校验
+- 所有输入都必须校验
+- 校验失败时返回 400
+- 包含字段级错误详情
+
+### Authentication
+- 所有端点都要求 JWT token
+- Token 通过 Authorization header 传递
+- Token 24 小时过期
+- 实现 refresh token 机制
+~~~~
+
+#### 示例 3:个人记忆
+
+**文件:** `~/.claude/CLAUDE.md`
+
+~~~~markdown
+# 我的开发偏好
+
+## About Me
+- **经验水平**:8 年全栈开发
+- **偏好语言**:TypeScript、Python
+- **沟通风格**:直接、配示例
+- **学习风格**:喜欢图示和代码配合
+
+## Code Preferences
+
+### Error Handling
+我偏好显式的 try-catch 和清晰的错误信息。
+避免泛化错误,调试时始终记录日志。
+~~~~
+
+#### 示例 4:会话中更新记忆
+
+```markdown
+User: 记住:所有新组件都优先使用 React hooks,不用 class components。
+
+Claude: 我会把它加入记忆。你希望写入哪个记忆文件?
+ 1. 项目记忆(./CLAUDE.md)
+ 2. 个人记忆(~/.claude/CLAUDE.md)
+
+User: 项目记忆
+
+Claude: ✅ 记忆已保存!
+```
+
+### Claude Web/Desktop 中的记忆综合
+
+#### 记忆综合时间线
+
+```mermaid
+graph LR
+ A["第 1 天:用户对话"] -->|24 小时| B["第 2 天:记忆综合"]
+ B -->|自动| C["记忆更新并摘要化"]
+ C -->|加载到| D["第 2-N 天:新对话"]
+```
+
+### Memory 功能对比
+
+| 功能 | Claude Web/Desktop | Claude Code (`CLAUDE.md`) |
+|------|--------------------|---------------------------|
+| 自动综合 | ✅ 每 24 小时 | ❌ 手动 |
+| 跨项目 | ✅ 共享 | ❌ 项目级 |
+| 团队访问 | ✅ 共享项目 | ✅ Git 跟踪 |
+| 可搜索 | ✅ 内建 | ✅ 通过 `/memory` |
+| 可编辑 | ✅ 聊天中 | ✅ 直接改文件 |
+| 导入/导出 | ✅ 支持 | ✅ 复制粘贴 |
+| 持久性 | ✅ 24h+ | ✅ 长期 |
+
+---
+
+## MCP Protocol
+
+### 概览
+
+MCP(Model Context Protocol)是 Claude 访问外部工具、API 与实时数据源的标准方式。与 Memory 不同,MCP 提供的是对持续变化数据的实时访问。
+
+### MCP 架构
+
+```mermaid
+graph TB
+ A["Claude"]
+ B["MCP Server"]
+ C["外部服务"]
+
+ A -->|请求| B
+ B -->|查询| C
+ C -->|数据| B
+ B -->|响应| A
+```
+
+### MCP 生态
+
+```mermaid
+graph TB
+ A["Claude"] -->|MCP| B["Filesystem<br/>MCP Server"]
+ A -->|MCP| C["GitHub<br/>MCP Server"]
+ A -->|MCP| D["Database<br/>MCP Server"]
+ A -->|MCP| E["Slack<br/>MCP Server"]
+ A -->|MCP| F["Google Docs<br/>MCP Server"]
+```
+
+### MCP 设置流程
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Claude as Claude Code
+ participant Config as 配置文件
+ participant Service as 外部服务
+
+ User->>Claude: 输入 /mcp
+ Claude->>Claude: 列出可用 MCP server
+ Claude->>User: 展示选项
+ User->>Claude: 选择 GitHub MCP
+ Claude->>Config: 更新配置
+ Config->>Claude: 激活连接
+ Claude->>Service: 测试连接
+ Service-->>Claude: 认证成功
+ Claude->>User: ✅ MCP 已连接
+```
+
+### 可用 MCP Server 表
+
+| MCP Server | 用途 | 常见工具 | 认证 | 实时 |
+|------------|------|----------|------|------|
+| Filesystem | 文件操作 | read, write, delete | 操作系统权限 | ✅ 是 |
+| GitHub | 仓库管理 | list_prs, create_issue, push | OAuth | ✅ 是 |
+| Slack | 团队沟通 | send_message, list_channels | Token | ✅ 是 |
+| Database | SQL 查询 | query, insert, update | 凭据 | ✅ 是 |
+| Google Docs | 文档访问 | read, write, share | OAuth | ✅ 是 |
+| Asana | 项目管理 | create_task, update_status | API Key | ✅ 是 |
+| Stripe | 支付数据 | list_charges, create_invoice | API Key | ✅ 是 |
+| Memory | 持久记忆 | store, retrieve, delete | Local | ❌ 否 |
+
+### 实践示例
+
+#### 示例 1:GitHub MCP 配置
+
+```json
+{
+ "mcpServers": {
+ "github": {
+ "command": "npx",
+ "args": ["@modelcontextprotocol/server-github"],
+ "env": {
+ "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+ }
+ }
+ }
+}
+```
+
+#### 示例 2:Database MCP 配置
+
+```json
+{
+ "mcpServers": {
+ "database": {
+ "command": "npx",
+ "args": ["@modelcontextprotocol/server-database"],
+ "env": {
+ "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
+ }
+ }
+ }
+}
+```
+
+#### 示例 3:多 MCP 工作流
+
+```markdown
+# 使用多个 MCP 的日报工作流
+
+## 设置
+1. GitHub MCP - 获取 PR 指标
+2. Database MCP - 查询销售数据
+3. Slack MCP - 发送报告
+4. Filesystem MCP - 保存报告
+```
+
+#### 示例 4:Filesystem MCP 操作
+
+| 操作 | 命令 | 作用 |
+|------|------|------|
+| 列出文件 | `ls ~/projects` | 查看目录内容 |
+| 读取文件 | `cat src/main.ts` | 读取文件内容 |
+| 写入文件 | `create docs/api.md` | 创建新文件 |
+| 编辑文件 | `edit src/app.ts` | 修改文件 |
+| 搜索 | `grep "async function"` | 在文件中搜索 |
+| 删除 | `rm old-file.js` | 删除文件 |
+
+### MCP vs Memory:决策矩阵
+
+```mermaid
+graph TD
+ A["需要外部数据吗?"]
+ A -->|否| B["使用 Memory"]
+ A -->|是| C["数据是否频繁变化?"]
+ C -->|否/很少| B
+ C -->|是/经常| D["使用 MCP"]
+```
+
+### 请求 / 响应模式
+
+```mermaid
+sequenceDiagram
+ participant App as Claude
+ participant MCP as MCP Server
+ participant DB as Database
+
+ App->>MCP: Request: "SELECT * FROM users WHERE id=1"
+ MCP->>DB: Execute query
+ DB-->>MCP: Result set
+ MCP-->>App: Return parsed data
+```
+
+---
+
+## Agent Skills
+
+### 概览
+
+Agent Skills 是可复用、由模型自动调用的能力包。它们以目录形式存在,通常包含说明、脚本和资源文件。Claude 会在合适时自动发现并使用它们。
+
+### Skill 架构
+
+```mermaid
+graph TB
+ A["Skill 目录"]
+ B["SKILL.md"]
+ C["YAML 元数据"]
+ D["说明"]
+ E["脚本"]
+ F["模板"]
+
+ A --> B
+ B --> C
+ B --> D
+ E --> A
+ F --> A
+```
+
+### Skill 加载流程
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Claude as Claude
+ participant System as System
+ participant Skill as Skill
+
+ User->>Claude: "Create Excel report"
+ Claude->>System: Scan available skills
+ System->>System: Load skill metadata
+ Claude->>Claude: Match user request to skills
+ Claude->>Skill: Load xlsx skill SKILL.md
+ Skill-->>Claude: Return instructions + tools
+ Claude->>Claude: Execute skill
+ Claude->>User: Generate Excel file
+```
+
+### Skill 类型与位置
+
+| 类型 | 位置 | 作用域 | 是否共享 | 同步方式 | 最适合 |
+|------|------|--------|----------|----------|--------|
+| 内置 | Built-in | 全局 | 全部用户 | 自动 | 文档生成 |
+| 个人 | `~/.claude/skills/` | 个人 | 否 | 手动 | 个人自动化 |
+| 项目 | `.claude/skills/` | 团队 | 是 | Git | 团队标准 |
+| 插件 | 通过 plugin 安装 | 视情况而定 | 视情况而定 | 自动 | 集成能力 |
+
+### 预构建 Skills
+
+Claude Code 现在内置了 5 个 bundled skills,可直接使用:
+
+| Skill | 命令 | 用途 |
+|-------|------|------|
+| Simplify | `/simplify` | 简化复杂代码或解释 |
+| Batch | `/batch` | 批量对多个文件或对象执行操作 |
+| Debug | `/debug` | 系统化调试并做根因分析 |
+| Loop | `/loop` | 按定时计划重复执行任务 |
+| Claude API | `/claude-api` | 直接与 Anthropic API 交互 |
+
+### 实践示例
+
+#### 示例 1:自定义代码审查 Skill
+
+**目录结构:**
+
+```text
+~/.claude/skills/code-review/
+├── SKILL.md
+├── templates/
+│ ├── review-checklist.md
+│ └── finding-template.md
+└── scripts/
+ ├── analyze-metrics.py
+ └── compare-complexity.py
+```
+
+**文件:** `~/.claude/skills/code-review/SKILL.md`
+
+```yaml
+---
+name: Code Review Specialist
+description: Comprehensive code review with security, performance, and quality analysis
+version: "1.0.0"
+tags:
+ - code-review
+ - quality
+ - security
+when_to_use: 当用户希望审查代码、分析代码质量或评估 pull request 时
+effort: high
+shell: bash
+---
+
+# 代码审查 Skill
+
+这个 skill 提供全面的代码审查能力,重点关注:
+
+1. **安全分析**
+2. **性能审查**
+3. **代码质量**
+4. **可维护性**
+```
+
+相关 Python 脚本和模板可直接沿用原始实现;脚本逻辑本身无需翻译即可使用。
+
+#### 示例 2:Brand Voice Skill
+
+这个 skill 用于统一品牌语气、用词风格和外部沟通表达。它通常包含品牌使命、价值观、推荐用词、避免用词,以及邮件 / 社交媒体等模板。
+
+#### 示例 3:Documentation Generator Skill
+
+这个 skill 用于从源码生成 API 文档,常见产物包括:
+
+- OpenAPI/Swagger 规范
+- API 端点文档
+- SDK 使用示例
+- 集成指南
+- 错误码说明
+- 认证说明
+
+### Skill 发现与调用
+
+```mermaid
+graph TD
+ A["用户请求"] --> B["Claude 分析"]
+ B -->|扫描| C["可用 Skills"]
+ C -->|元数据匹配| D["Skill 描述是否匹配?"]
+ D -->|是| E["加载 SKILL.md"]
+ D -->|否| F["尝试下一个 Skill"]
+ E --> H["提取指令"]
+ H --> I["执行 Skill"]
+ I --> J["返回结果"]
+```
+
+### Skill 与其他功能的区别
+
+```mermaid
+graph TB
+ A["扩展 Claude"]
+ B["Slash Commands"]
+ C["Subagents"]
+ D["Memory"]
+ E["MCP"]
+ F["Skills"]
+
+ A --> B
+ A --> C
+ A --> D
+ A --> E
+ A --> F
+```
+
+---
+
+## Claude Code Plugins
+
+### 概览
+
+Claude Code Plugins 是把多种能力打包在一起的一体化扩展机制,通常包含 slash commands、subagents、MCP servers、hooks 以及相关配置。它们可以通过一条命令完成安装。
+
+### 架构
+
+```mermaid
+graph TB
+ A["Plugin"]
+ B["Slash Commands"]
+ C["Subagents"]
+ D["MCP Servers"]
+ E["Hooks"]
+ F["Configuration"]
+
+ A -->|打包| B
+ A -->|打包| C
+ A -->|打包| D
+ A -->|打包| E
+ A -->|打包| F
+```
+
+### Plugin 加载流程
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Claude as Claude Code
+ participant Plugin as Plugin Marketplace
+ participant Install as Installation
+ participant SlashCmds as Slash Commands
+ participant Subagents
+ participant MCPServers as MCP Servers
+ participant Hooks
+
+ User->>Claude: /plugin install pr-review
+ Claude->>Plugin: 下载插件清单
+ Plugin-->>Claude: 返回插件定义
+ Claude->>Install: 解包组件
+ Install->>SlashCmds: 配置
+ Install->>Subagents: 配置
+ Install->>MCPServers: 配置
+ Install->>Hooks: 配置
+```
+
+### Plugin 类型与分发
+
+| 类型 | 作用域 | 是否共享 | 权威来源 | 示例 |
+|------|--------|----------|----------|------|
+| Official | 全局 | 全部用户 | Anthropic | PR Review、Security Guidance |
+| Community | 公开 | 全部用户 | 社区 | DevOps、Data Science |
+| Organization | 内部 | 团队成员 | 公司 | 内部标准、工具 |
+| Personal | 个人 | 单用户 | 开发者 | 自定义工作流 |
+
+### Plugin 定义结构
+
+```yaml
+---
+name: plugin-name
+version: "1.0.0"
+description: "What this plugin does"
+author: "Your Name"
+license: MIT
+---
+```
+
+### Plugin 结构
+
+```text
+my-plugin/
+├── .claude-plugin/
+│ └── plugin.json
+├── commands/
+├── agents/
+├── skills/
+├── hooks/
+├── .mcp.json
+├── templates/
+├── scripts/
+├── docs/
+└── tests/
+```
+
+### 实践示例
+
+#### 示例 1:PR Review Plugin
+
+```json
+{
+ "name": "pr-review",
+ "version": "1.0.0",
+ "description": "Complete PR review workflow with security, testing, and docs"
+}
+```
+
+#### 示例 2:DevOps Plugin
+
+```text
+devops-automation/
+├── commands/
+├── agents/
+├── mcp/
+├── hooks/
+└── scripts/
+```
+
+#### 示例 3:Documentation Plugin
+
+```text
+documentation/
+├── commands/
+├── agents/
+├── mcp/
+└── templates/
+```
+
+### Plugin Marketplace
+
+```mermaid
+graph TB
+ A["Plugin Marketplace"]
+ B["Official"]
+ C["Community"]
+ D["Enterprise"]
+```
+
+### Plugin 安装与生命周期
+
+```mermaid
+graph LR
+ A["发现"] --> B["浏览 Marketplace"]
+ B --> C["查看插件页"]
+ C --> D["查看组件"]
+ D --> E["/plugin install"]
+ E --> F["配置"]
+ F --> G["启用"]
+```
+
+### Plugin 功能对比
+
+| 功能 | Slash Command | Skill | Subagent | Plugin |
+|------|---------------|-------|----------|--------|
+| 安装 | 手动复制 | 手动复制 | 手动配置 | 一条命令 |
+| 搭建时间 | 5 分钟 | 10 分钟 | 15 分钟 | 2 分钟 |
+| 打包能力 | 单文件 | 单文件 | 单文件 | 多组件 |
+| 团队共享 | 复制文件 | 复制文件 | 复制文件 | 通过安装 ID |
+| 更新方式 | 手动 | 手动 | 手动 | 市场可用 / 更易分发 |
+
+### 何时创建 Plugin
+
+- 当你需要一次分发多个命令、subagents、MCP servers 或 hooks 时
+- 当这是团队级工作流,需要统一安装和复制时
+- 当你希望自动化配置过程并减少手工步骤时
+
+### 发布 Plugin
+
+1. 创建完整的插件结构
+2. 编写 `.claude-plugin/plugin.json`
+3. 编写 `README.md`
+4. 本地测试
+5. 提交到 marketplace
+6. 审核通过
+7. 发布
+
+### Plugin vs 手动配置
+
+**手动配置:**
+- 一个个复制 slash commands
+- 单独创建 subagents
+- 分别配置 MCP
+- 手动设置 hooks
+
+**使用 Plugin:**
+```bash
+/plugin install pr-review
+# ✅ 一次安装完成
+# ✅ 即刻可用
+# ✅ 团队可复现
+```
+
+---
+
+## Comparison & Integration
+
+### 功能对比矩阵
+
+| 功能 | 调用方式 | 持久性 | 作用域 | 适用场景 |
+|------|----------|--------|--------|----------|
+| Slash Commands | 手动 (`/cmd`) | 仅当前会话 | 单个命令 | 快捷操作 |
+| Subagents | 自动委派 | 隔离上下文 | 专门任务 | 任务拆分 |
+| Memory | 自动加载 | 跨会话 | 用户 / 团队上下文 | 长期记忆 |
+| MCP Protocol | 自动查询 | 实时外部数据 | 动态访问 | 外部数据接入 |
+| Skills | 自动触发 | 文件系统级 | 可复用专长 | 自动化工作流 |
+| Plugins | 一键安装 | 全套组合 | 团队 / 市场分发 | 完整方案打包 |
+
+### 交互时间线
+
+```mermaid
+graph LR
+ A["Session Start"] -->|Load| B["Memory (CLAUDE.md)"]
+ B -->|Discover| C["Available Skills"]
+ C -->|Register| D["Slash Commands"]
+ D -->|Connect| E["MCP Servers"]
+ E -->|Ready| F["User Interaction"]
+```
+
+### 集成示例:客户支持自动化
+
+#### 架构
+
+```mermaid
+graph TB
+ User["客户邮件"] -->|进入| Router["支持路由器"]
+ Router -->|分析| Memory["Memory<br/>客户历史"]
+ Router -->|查询| MCP1["MCP: 客户数据库"]
+ Router -->|检查| MCP2["MCP: Slack"]
+ Router -->|复杂问题| Sub1["Subagent: 技术支持"]
+ Router -->|简单问题| Sub2["Subagent: 计费支持"]
+```
+
+#### 请求流
+
+```markdown
+1. 用户发来报错邮件
+2. 读取记忆和历史上下文
+3. 通过多个 MCP 查询系统状态
+4. 自动识别适合的 Skill
+5. 委派给对应 Subagent
+6. Subagent 处理问题
+7. Skill 负责按统一语气生成回复
+8. MCP 将结果同步到外部系统
+9. 返回给客户
+```
+
+### 完整功能编排
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Claude as Claude Code
+ participant Memory as Memory
+ participant MCP as MCP Servers
+ participant Skills as Skills
+ participant SubAgent as Subagents
+
+ User->>Claude: "Build auth system"
+ Claude->>Memory: 加载项目标准
+ Claude->>MCP: 查询相似实现
+ Claude->>Skills: 检测匹配 Skill
+ Claude->>SubAgent: 委派实现
+```
+
+### 何时使用哪种功能
+
+```mermaid
+graph TD
+ A["新任务"] --> B{任务类型?}
+
+ B -->|重复工作流| C["Slash Command"]
+ B -->|需要实时数据| D["MCP Protocol"]
+ B -->|希望下次记住| E["Memory"]
+ B -->|需要专业子任务| F["Subagent"]
+ B -->|领域型自动化| G["Skill"]
+```
+
+### 选择决策树
+
+```mermaid
+graph TD
+ Start["需要扩展 Claude 吗?"]
+ Start -->|快速重复任务| A{"手动还是自动?"}
+ A -->|手动| B["Slash Command"]
+ A -->|自动| C["Skill"]
+ Start -->|需要外部数据| D{"是否实时?"}
+ D -->|是| E["MCP Protocol"]
+ D -->|否| F["Memory"]
+ Start -->|复杂项目| G{"是否多角色协作?"}
+ G -->|是| H["Subagents"]
+```
+
+---
+
+## Summary Table
+
+| 维度 | Slash Commands | Subagents | Memory | MCP | Skills | Plugins |
+|------|----------------|-----------|--------|-----|--------|---------|
+| 搭建难度 | 简单 | 中等 | 简单 | 中等 | 中等 | 简单 |
+| 学习曲线 | 低 | 中 | 低 | 中 | 中 | 低 |
+| 团队价值 | 高 | 高 | 中 | 高 | 高 | 很高 |
+| 自动化程度 | 低 | 高 | 中 | 高 | 高 | 很高 |
+| 上下文管理 | 单会话 | 隔离 | 持久 | 实时 | 持久 | 全部整合 |
+| 可扩展性 | 好 | 极佳 | 好 | 极佳 | 极佳 | 极佳 |
+| 共享性 | 一般 | 一般 | 好 | 好 | 好 | 极佳 |
+| 安装方式 | 手动复制 | 手动配置 | N/A | 手动配置 | 手动复制 | 一条命令 |
+
+---
+
+## Quick Start Guide
+
+### 第 1 周:先从简单的开始
+- 为常见任务做 2-3 个 slash commands
+- 在设置里开启 Memory
+- 在 `CLAUDE.md` 里写明团队标准
+
+### 第 2 周:接入实时数据
+- 先配置 1 个 MCP(GitHub 或 Database)
+- 通过 `/mcp` 配置
+- 在工作流中查询实时数据
+
+### 第 3 周:分发工作
+- 创建第一个针对角色的 Subagent
+- 使用 `/agents`
+- 用简单任务测试委派
+
+### 第 4 周:全面自动化
+- 创建第一个 Skill
+- 使用市场里的 Skill 或自建
+- 组合多个功能做完整工作流
+
+### 持续优化
+- 每月回顾并更新 Memory
+- 当重复模式出现时新增 Skill
+- 优化 MCP 查询
+- 持续打磨 Subagent 提示词
+
+---
+
+## Hooks
+
+### 概览
+
+Hooks 是事件驱动的 shell 命令,会在 Claude Code 的特定事件发生时自动执行,可用于自动化、校验、通知和自定义工作流。
+
+### Hook 事件
+
+Claude Code 支持 **25 个 hook 事件**,分布在四类钩子中:
+
+| Hook 事件 | 触发时机 | 常见用途 |
+|-----------|----------|----------|
+| SessionStart | 会话开始 / 恢复 / 清空 / compact | 环境初始化 |
+| InstructionsLoaded | 加载 `CLAUDE.md` 或 rules | 校验、增强 |
+| UserPromptSubmit | 用户提交提示词 | 输入校验 |
+| PreToolUse | 工具执行前 | 审批、校验、日志 |
+| PermissionRequest | 弹出权限请求时 | 自动批准 / 拒绝 |
+| PostToolUse | 工具执行成功后 | 自动格式化、通知、清理 |
+| PostToolUseFailure | 工具失败后 | 错误处理 |
+| Notification | 通知发送时 | 外部联动 |
+| SubagentStart | 启动 subagent 时 | 注入上下文 |
+| SubagentStop | subagent 结束时 | 结果校验 |
+| Stop | Claude 响应完成时 | 总结、清理 |
+| SessionEnd | 会话结束时 | 收尾处理 |
+
+### 常见 Hook 配置
+
+```json
+{
+ "hooks": {
+ "PostToolUse": [
+ {
+ "matcher": "Write",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "prettier --write $CLAUDE_FILE_PATH"
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+### Hook 环境变量
+
+- `$CLAUDE_FILE_PATH`:当前被写入 / 编辑的文件
+- `$CLAUDE_TOOL_NAME`:正在使用的工具名
+- `$CLAUDE_SESSION_ID`:当前会话 ID
+- `$CLAUDE_PROJECT_DIR`:项目目录路径
+
+### 最佳实践
+
+✅ 建议:
+- 让 hooks 尽量快(最好 < 1 秒)
+- 用 hooks 做校验和自动化
+- 优雅处理错误
+- 使用绝对路径
+
+❌ 不建议:
+- 让 hooks 进入交互式流程
+- 把长时间任务放在 hooks 里
+- 硬编码凭据
+
+**详见:** [06-hooks/README.md](06-hooks/README.md)
+
+---
+
+## Checkpoints and Rewind
+
+### 概览
+
+Checkpoints 可以保存会话状态,并在需要时回退到之前的节点,从而安全地尝试不同方案。
+
+### 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| Checkpoint | 对消息、文件和上下文的快照 |
+| Rewind | 回到某个历史 checkpoint,并丢弃之后的变化 |
+| Branch Point | 从同一个 checkpoint 分叉出多种方案 |
+
+### 如何访问 Checkpoints
+
+```bash
+# 按两次 Esc 打开 checkpoint 浏览器
+Esc + Esc
+
+# 或使用 /rewind
+/rewind
+```
+
+选择 checkpoint 后有五个选项:
+1. 恢复代码和对话
+2. 恢复对话
+3. 恢复代码
+4. 从这里开始总结
+5. 取消
+
+### 常见场景
+
+| 场景 | 工作流 |
+|------|--------|
+| 探索不同方案 | 保存 → 尝试 A → 保存 → 回退 → 尝试 B |
+| 安全重构 | 保存 → 重构 → 测试 → 失败就回退 |
+| A/B 测试 | 保存 → 设计 A → 保存 → 回退 → 设计 B |
+| 误操作恢复 | 发现问题 → 回退到最近稳定状态 |
+
+### 配置
+
+```json
+{
+ "autoCheckpoint": true
+}
+```
+
+**详见:** [08-checkpoints/README.md](08-checkpoints/README.md)
+
+---
+
+## Advanced Features
+
+### Planning Mode
+
+在编码前先生成详细实现计划。
+
+```bash
+/plan Implement user authentication system
+```
+
+优势:
+- 清晰路线图
+- 时间预估
+- 风险评估
+- 可审查、可修改
+
+### Extended Thinking
+
+适合复杂问题的深度推理。
+
+```bash
+export MAX_THINKING_TOKENS=50000
+claude -p "Should we use microservices or monolith?"
+```
+
+### Background Tasks
+
+后台执行长任务而不阻塞当前对话。
+
+```bash
+/task list
+/task status bg-1234
+/task show bg-1234
+/task cancel bg-1234
+```
+
+### Permission Modes
+
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| `default` | 标准权限模式 | 通用开发 |
+| `acceptEdits` | 自动接受文件编辑 | 信任编辑工作流 |
+| `plan` | 只分析不改文件 | 审查、规划 |
+| `auto` | 自动批准安全操作 | 平衡自治与安全 |
+| `dontAsk` | 不再提示确认 | 资深用户 / 自动化 |
+| `bypassPermissions` | 完全不受限 | CI/CD、可信脚本 |
+
+### Headless Mode(Print Mode)
+
+使用 `-p` 标志在无交互模式下运行 Claude Code,适合自动化和 CI/CD。
+
+```bash
+claude -p "Run all tests"
+cat error.log | claude -p "explain this error"
+claude -p --output-format json "list all functions in src/"
+```
+
+### Scheduled Tasks
+
+通过 `/loop` 按计划周期性运行任务:
+
+```bash
+/loop every 30m "Run tests and report failures"
+/loop every 2h "Check for dependency updates"
+/loop every 1d "Generate daily summary of code changes"
+```
+
+### Chrome Integration
+
+Claude Code 可以与 Chrome 浏览器集成,用于网页自动化,如导航页面、填写表单、截图和提取页面数据。
+
+### Session Management
+
+```bash
+/resume
+/rename "Feature"
+/fork
+claude -c
+claude -r "Feature"
+```
+
+### Interactive Features
+
+- `Ctrl + R`:搜索命令历史
+- `Tab`:自动补全
+- `↑ / ↓`:浏览历史
+- `Ctrl + L`:清屏
+
+### 配置
+
+```json
+{
+ "planning": {
+ "autoEnter": true,
+ "requireApproval": true
+ },
+ "backgroundTasks": {
+ "enabled": true,
+ "maxConcurrentTasks": 5
+ },
+ "permissions": {
+ "mode": "default"
+ }
+}
+```
+
+**详见:** [09-advanced-features/README.md](09-advanced-features/README.md)
+
+---
+
+## Resources
+
+- [Claude Code Documentation](https://code.claude.com/docs/en/overview)
+- [Anthropic Documentation](https://docs.anthropic.com)
+- [MCP GitHub Servers](https://github.com/modelcontextprotocol/servers)
+- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook)
+
+---
+
+*最后更新:2026 年 3 月*
+*适用于 Claude Haiku 4.5、Sonnet 4.6、Opus 4.6*
+*现已覆盖:Hooks、Checkpoints、Planning Mode、Extended Thinking、Background Tasks、Permission Modes、Headless Mode、Session Management、Auto Memory、Agent Teams、Scheduled Tasks、Chrome Integration、Bundled Skills 等概念。*
diff --git a/zh/clean-code-rules.md b/zh/clean-code-rules.md
new file mode 100644
index 0000000..196c536
--- /dev/null
+++ b/zh/clean-code-rules.md
@@ -0,0 +1,108 @@
+# 面向 AI 代码生成的整洁代码规则
+
+这些规则用于指导代码生成,帮助产出可维护、专业水准的代码。
+
+## 有意义的命名
+- 使用能体现意图的名称,说明它为什么存在
+- 避免误导性命名和无意义区分,例如 `data`、`info`、`manager`
+- 使用可读、可搜索的名称
+- 类名使用名词,例如 `UserAccount`、`PaymentProcessor`
+- 方法名使用动词,例如 `calculateTotal`、`sendEmail`
+- 避免脑内映射和编码风格命名,例如匈牙利命名法、前缀
+
+## 函数
+- 保持函数短小精炼,理想情况下少于 20 行
+- 只做一件事,遵循单一职责原则
+- 每个函数只处理一个抽象层级
+- 限制参数数量,理想为 0-2 个,最多 3 个,避免布尔标志参数
+- 不要产生副作用,函数应该做它名字所说的事
+- 将命令与查询分离,命令修改状态,查询返回信息
+- 优先使用异常而不是错误码
+
+## 注释
+- 代码本身应该尽量可自解释,能不写注释就不写
+- 好的注释包括:法律信息、警告、TODO、公共 API 文档
+- 坏的注释包括:重复、误导,或者只是解释糟糕的代码
+- 不要注释掉代码,直接删除,版本控制会保留历史
+- 如果你需要写注释,先考虑重构代码
+
+## 格式化
+- 保持文件小而聚焦
+- 垂直格式化:相关概念放近一些,空行分隔不同概念
+- 水平格式化:限制行长度在 80-120 个字符之间
+- 使用一致的缩进和团队风格
+- 将相关函数分组放在一起
+
+## 对象与数据结构
+- 对象:通过抽象隐藏数据,通过方法暴露行为
+- 数据结构:暴露数据,尽量少提供行为
+- 迪米特法则:只和直接朋友说话,避免 `a.getB().getC().doSomething()`
+- 不要毫无节制地通过 getter/setter 暴露内部结构
+
+## 错误处理
+- 使用异常,不要使用返回码或错误标志
+- 代码可能失败时,先写 `try-catch-finally`
+- 在异常信息中提供上下文
+- 不要返回 `null`,改为返回空集合或使用 Optional/Maybe
+- 不要把 `null` 作为参数传入
+
+## 类
+- 小类应按职责衡量,而不是按行数衡量
+- 单一职责原则:只有一个改变原因
+- 高内聚:类变量被多数方法使用
+- 低耦合:类之间依赖尽量少
+- 开闭原则:对扩展开放,对修改关闭
+
+## 单元测试
+- 快速、独立、可重复、自我验证、及时(F.I.R.S.T.)
+- 每个测试一个断言,或只验证一个概念
+- 测试代码质量应与生产代码质量一致
+- 测试名称要可读,清楚描述正在测试什么
+- 遵循 Arrange-Act-Assert 模式
+
+## 代码质量原则
+- **DRY(Don't Repeat Yourself)**:不要重复
+- **YAGNI(You Aren't Gonna Need It)**:不要为假设中的未来提前构建
+- **KISS(Keep It Simple)**:避免不必要的复杂度
+- **童子军规则**:让代码比你接手时更干净
+
+## 应避免的代码坏味道
+- 函数或类过长
+- 重复代码
+- 死代码(未使用的变量、函数、参数)
+- 特性依恋(方法更关心别的类)
+- 不恰当的亲密关系(类彼此了解过多)
+- 过长的参数列表
+- 原始类型偏执(过度使用原始类型而不是小对象)
+- switch/case 语句(考虑使用多态)
+- 临时字段(类变量只在某些时候才使用)
+
+## 并发
+- 将并发代码与其他代码隔离
+- 限制同步/加锁数据的作用域
+- 使用线程安全集合
+- 保持同步区块尽量小
+- 了解你的执行模型和原语
+
+## 系统设计
+- 将构建和使用分离,例如通过依赖注入
+- 复杂对象创建时使用工厂、构建器
+- 面向接口编程,而不是面向实现编程
+- 优先组合而不是继承
+- 设计模式只在它们简化问题时使用,不要为了炫技而使用
+
+## 重构
+- 持续重构,不要攒成大批量一次做完
+- 重构前后都要保证测试通过
+- 小步前进,每次只改一处
+- 常见重构包括:提取方法、重命名、移动、内联
+
+## 文档
+- 自说明代码 > 注释 > 外部文档
+- 公共 API 需要清晰文档
+- 文档中要包含示例
+- 文档尽量靠近代码,理想情况下就在代码里
+
+---
+
+**核心理念**:代码被阅读的次数是编写次数的 10 倍。优化可读性和可维护性,而不是追求花哨。
diff --git a/zh/docs/ROADMAP-20260401.md b/zh/docs/ROADMAP-20260401.md
new file mode 100644
index 0000000..3e71ee3
--- /dev/null
+++ b/zh/docs/ROADMAP-20260401.md
@@ -0,0 +1,153 @@
+# 路线图:claude-howto 2026–2027
+
+> 2026 年 4 月 – 2027 年 3 月 · 双层知识库 | 完整计划:`TASKS-20260401.md`
+
+---
+
+## 愿景
+
+把 claude-howto 从一个静态教程仓库,转变为一个**活的、双受众知识系统**:
+
+- **面向人类** - 通过场景化学习、渐进式难度、决策树和专家会收藏的命名模式,提供互动式学习体验
+- **面向 AI 代理** - 提供结构化元数据索引,让代理在执行 Claude Code 任务前先查询这里,使这个仓库成为基础设施,而不只是内容
+
+没有竞争者把 AI 代理视为主要受众。这就是我们的护城河。
+
+---
+
+## 7 大支柱
+
+| # | 支柱 | 交付内容 |
+|---|--------|-----------------|
+| P1 | 趣味层 | 每个模块都有场景导语和 "Try It Now" 模块 |
+| P2 | AI 代理索引 | 生成 `agent-manifest.json` + `AGENT-INDEX.md` + 查询技能 |
+| P3a | 专家参考(模块内) | 每个模块的决策树 + 命名模式 |
+| P3b | 专家参考(跨模块) | `RECIPES.md` - 组合型多功能工作流 |
+| P4 | 新手上手 | `quickstart.sh` + `QUICKSTART.md` + 难度徽章 |
+| P5 | 社区展示 | `COMMUNITY-PROJECTS.md` - 精选用户项目 |
+| P6 | 内容质量 | 扩展最薄弱的模块;完善项目 `CLAUDE.md` |
+| P7 | 活课程体系 | `WHATS-NEW.md` + 版本徽章 + 每周过期检查 CI action |
+
+---
+
+## 时间线总览
+
+```
+2026 年 4 月 5–6 月 2026 7–8 月 2026 2026 年 9 月 10–11 月 2026 2026 年 12 月–2027 年 3 月
+ | | | | | |
+ [M1] [M2] [M3] [M4] [M5] [M6]
+基础设施 6/10 个模块 10/10 完成 代理层 版本审计 自我维持系统
++ hooks/checks 完成 完成 + recipes 完成
+```
+
+---
+
+## 里程碑
+
+### M1 - 基础设施上线 · 2026 年 4 月底
+
+**交付内容:**
+- `scripts/quickstart.sh` - 为新用户提供一条命令式安装(幂等)
+- `QUICKSTART.md` - “前 15 分钟”可视化指南
+- 所有 10 个模块都加入难度徽章和 "What you'll build" 预览
+- 所有模块都加入 `WHATS-NEW.md` 和版本徽章
+- `.github/workflows/staleness-check.yml` - 每周一检查,若模块 30 天以上未验证则创建 issue
+- 根目录 `CLAUDE.md` - 作为最佳实践示例的项目配置
+- `scripts/build-agent-index.py` - 读取 10 个模块并输出 `agent-manifest.json` + `AGENT-INDEX.md` 的生成器
+- **06-hooks** - 完整深度处理:5 个完整 hook 脚本、决策树、Try It Now、模式
+- **08-checkpoints** - 完整深度处理:311 行扩展到 800+ 行,3 个工作流模板、决策树、模式
+
+**为什么从这里开始:** 基础设施能惠及后续所有阶段。hooks 和 checkpoints 是最薄弱的模块,也最容易流失新访客。
+
+---
+
+### M2 - 6/10 个模块完成 · 2026 年 6 月底
+
+**交付内容(每个模块一次深度处理):**
+- **01-slash-commands** - 场景导语、决策树、Try It Now、命名模式
+- **02-memory** - 场景导语、决策树、Try It Now、命名模式
+- **03-skills** - 场景导语、决策树、Try It Now、命名模式
+- **10-cli** - 场景导语、决策树、Try It Now、命名模式
+- CI 步骤:在每次 push 时校验 `agent-manifest.json` 的 schema
+
+每个模块的处理都要运行生成器,确认 manifest 输出有效。
+
+---
+
+### M3 - 10/10 个模块完成 · 2026 年 8 月底
+
+**交付内容:**
+- **04-subagents** - 完整深度处理(包括 "The Multi-Agent Review Pattern")
+- **05-mcp** - 完整深度处理
+- **07-plugins** - 完整深度处理
+- **09-advanced-features** - 完整深度处理
+
+现在每个模块都具备:场景导语、2 个以上 Try It Now 模块、Mermaid 决策树、2 个以上命名模式。
+
+---
+
+### M4 - 代理层上线 · 2026 年 9 月底
+
+**交付内容:**
+- 最终版 `agent-manifest.json`,覆盖 100% 模块(由已完成内容生成)
+- `AGENT-INDEX.md`,从 `README.md` 链接
+- `skills/claude-howto-lookup/SKILL.md` - 轻量级 agent skill,通过 manifest 查询相关模块
+- `RECIPES.md` - 5 个以上组合工作流(schema:name、modules-used、problem、solution、expected outcome)
+- `COMMUNITY-PROJECTS.md` - 静态精选列表,采用 PR 提交格式
+
+**为什么是 9 月:** 只有等 10 个模块全部内容完备后,代理索引才真正有意义。
+
+---
+
+### M5 - 版本审计完成 · 2026 年 11 月底
+
+**交付内容:**
+- 完整版本审计:所有 10 个模块都根据当前 CC 版本完成验证
+- 更新所有模块的 `cc_version_verified` frontmatter 和版本徽章
+- `RECIPES.md` 扩展到 8 个以上 recipes,基于社区模式总结
+- GitHub 固定讨论串:“分享你的 Claude Code 工作流” - 收集 agent 使用信号
+
+---
+
+### M6 - 自我维持系统 · 2027 年 3 月底
+
+**持续交付 / 持续运行:**
+- `/docs-sync-claude-code` skill 在每次 CC 发布后运行 → 更新 `WHATS-NEW.md`
+- Agent manifest CI 回归测试:强制 100% 模块覆盖
+- `RECIPES.md` 增加到 10 个以上 recipes
+- `COMMUNITY-PROJECTS.md` 自然增长
+- 对 agent 使用信号进行评估 - 若验证有效,则推动 lookup skill 的推广(营销、asm registry)
+
+---
+
+## 交付摘要
+
+| 交付物 | 类型 | 阶段 |
+|-------------|------|-------|
+| `scripts/quickstart.sh` | 脚本 | P1 |
+| `QUICKSTART.md` | 文档 | P1 |
+| 根目录 `CLAUDE.md` | 配置 | P1 |
+| `WHATS-NEW.md` | 文档 | P1 |
+| `.github/workflows/staleness-check.yml` | CI | P1 |
+| `scripts/build-agent-index.py` | 脚本 | P1 |
+| 10 个模块深度处理(场景 + Try It Now + 决策树 + 模式) | 内容 | P1–P3 |
+| `agent-manifest.json`(生成) | 数据 | P4 |
+| `AGENT-INDEX.md`(生成) | 文档 | P4 |
+| `skills/claude-howto-lookup/SKILL.md` | Skill | P4 |
+| `RECIPES.md`(5 → 8 → 10+ recipes) | 文档 | P4–P6 |
+| `COMMUNITY-PROJECTS.md` | 文档 | P4 |
+
+---
+
+## 不在范围内的内容
+
+这些内容延期到 `TODOS.md`,不要让它们跑进来:
+
+- Skill marketplace 或可安装 registry
+- 自定义网站或仪表盘
+- 完成度追踪(cc-progress)
+- 社区教程 CI 校验
+- 自动生成的 CONTRIBUTORS.md
+- 多语言翻译
+- 测验 / 评估基础设施
+- 社区项目投票
diff --git a/zh/docs/TASKS-20260401.md b/zh/docs/TASKS-20260401.md
new file mode 100644
index 0000000..0b536f6
--- /dev/null
+++ b/zh/docs/TASKS-20260401.md
@@ -0,0 +1,291 @@
+# 任务:双层知识库 - claude-howto
+
+> 创建于:2026-04-01
+
+---
+
+## 里程碑
+
+| # | 里程碑 | 目标时间 | 描述 |
+|---|-----------|--------|-------------|
+| M1 | 基础设施上线 | 2026 年 4 月底 | quickstart.sh、CLAUDE.md、staleness action、代理索引生成器上线;升级 2 个最薄弱模块 |
+| M2 | 6/10 个模块完成 | 2026 年 6 月底 | Slash commands、memory、skills、CLI 模块完全升级;生成器输出有效 manifest |
+| M3 | 10/10 个模块完成 | 2026 年 8 月底 | 每个模块都具备场景导语、Try It Now 模块、决策树、命名模式 |
+| M4 | 代理层上线 | 2026 年 9 月底 | 生成 agent-manifest.json + AGENT-INDEX.md;仓库内有 lookup skill;`RECIPES.md` + `COMMUNITY-PROJECTS.md` 上线 |
+| M5 | 版本审计完成 | 2026 年 11 月底 | 所有 10 个模块都验证过当前 CC 版本;`RECIPES.md` 达到 8+ recipes |
+| M6 | 自我维持系统 | 2027 年 3 月底 | Agent manifest 覆盖 100% 模块(通过 CI 校验);`RECIPES.md` 达到 10+;社区页面自然增长 |
+
+---
+
+## 第 1 阶段 - 基础设施与薄弱模块(2026 年 4 月)
+
+**目标里程碑:M1**
+
+### 支柱 4:新手上手
+
+- [ ] **T-001** - 编写 `scripts/quickstart.sh`
+ - 检测 `~/.claude/` 目录(如缺失,则在用户确认后创建)
+ - 将第一个 slash command + CLAUDE.md + skill 复制到用户配置中
+ - 在 CLAUDE.md 末尾追加 agent-discovery 行,链接到 AGENT-INDEX.md
+ - 幂等:跳过已有文件并给出警告,绝不覆盖
+ - 完成后打印下一步
+
+- [ ] **T-002** - 创建 `QUICKSTART.md`(前 15 分钟可视化指南)
+ - 使用代码块记录带注释的终端步骤(尽量避免 PNG 截图;优先 ASCII 或 Mermaid)
+ - 记录每条命令对应哪个视觉结果,方便后续重新采集
+
+- [ ] **T-003** - 为所有 10 个模块的 README 添加难度徽章
+ - 格式:`> 🟢 **Beginner** | ⏱ 30 minutes`,放在每个模块 README 顶部
+ - 在徽章下方添加 "What you'll build" 的要点预览
+
+### 支柱 7:活课程体系
+
+- [ ] **T-004** - 创建 `WHATS-NEW.md`
+ - 格式:`## CC vX.X — DATE`,每个功能变更使用项目符号
+ - 至少添加一条当前 CC 版本的记录
+
+- [ ] **T-005** - 为所有 10 个模块的 README 添加版本徽章
+ - 格式:`> ✅ Verified against Claude Code **vX.X.X** · Last verified: YYYY-MM-DD`
+ - 在每个模块的 frontmatter 中加入 `cc_version_verified`
+
+- [ ] **T-006** - 创建 `.github/workflows/staleness-check.yml`
+ - 调度:每周一 09:00 UTC
+ - 从 frontmatter 读取每个模块的 `last_verified` 日期(使用 `yq` 或 10 行 Python 脚本)
+ - 对 30 天以上未验证的模块创建 GitHub Issue
+ - 如果已有同名 open issue,则跳过
+
+### 支柱 6:内容质量(CLAUDE.md)
+
+- [ ] **T-007** - 为项目创建根目录 `CLAUDE.md`
+ - 作为项目自身配置,展示最佳实践
+ - 记录贡献规范、模块结构和维护流程
+
+### 支柱 2:AI 代理索引(生成器)
+
+- [ ] **T-008** - 编写 `scripts/build-agent-index.py`
+ - 读取全部 10 个模块 README
+ - 提取:标题(→ topics)、代码块(→ 带语言标签的示例)、表格(→ 参考数据)
+ - 输出 `agent-manifest.json`,schema 按 CEO 计划定义
+ - 输出 `AGENT-INDEX.md`(人类可读摘要)
+ - 校验引用是否指向真实文件
+
+### 模块 08-checkpoints:完整深度处理(311 → 800+ 行)
+
+- [ ] **T-009** - 用真实场景重写模块导语
+ - 示例:"你的重构把 3 个东西弄坏了。checkpoint 如何帮你恢复..."
+
+- [ ] **T-010** - 添加 checkpoint 策略决策树(Mermaid flowchart)
+ - "我想做 X" → 顺着箭头走 → 到达对应 checkpoint 模式
+
+- [ ] **T-011** - 添加 3 个工作流模板
+ - 安全重构工作流
+ - 使用 checkpoints 做 A/B 测试
+ - 灾难恢复工作流
+
+- [ ] **T-012** - 添加与 planning mode 的整合部分
+
+- [ ] **T-013** - 添加 checkpoint 生命周期的 Mermaid 图
+
+- [ ] **T-014** - 添加 2 个以上 "Try It Now" 模块,并提供可验证命令
+ - 每个模块:上下文句、要运行的命令、预期输出说明
+
+- [ ] **T-015** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式
+ - 每个模式:问题、解决方案代码、适用场景、不适用场景
+
+### 模块 06-hooks:完整深度处理
+
+- [ ] **T-016** - 用真实场景重写模块导语
+ - 示例:"你的 CI 在 20 分钟后才发现 lint 错误。hooks 2 秒内就能抓住..."
+
+- [ ] **T-017** - 添加 hooks 决策树(Mermaid flowchart)
+ - "我想在 Y 发生时触发 X" → 顺着箭头走 → 到达对应 hook 类型
+
+- [ ] **T-018** - 添加 5 个完整 hook 示例,带完整脚本(每个约 80 行)
+ 1. 写入时自动格式化(prettier/black)
+ 2. 提交时安全扫描(trufflehog/bandit)
+ 3. 文件变更时运行测试
+ 4. 会话结束时发送通知
+ 5. 提示词校验(阻止危险模式)
+
+- [ ] **T-019** - 添加 2 个以上 "Try It Now" 模块,并提供可验证命令
+
+- [ ] **T-020** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式
+
+**M1 检查点:基础设施上线,2 个最薄弱模块完成深度升级**
+
+---
+
+## 第 2 阶段 - 深度处理:强模块第一批(2026 年 5 月 - 6 月)
+
+**目标里程碑:M2**
+
+### 模块 01-slash-commands:完整深度处理
+
+- [ ] **T-021** - 用场景重写导语("你的队友刚推了 47 个文件...")
+- [ ] **T-022** - 添加决策树(Mermaid)
+- [ ] **T-023** - 添加 2 个以上 "Try It Now" 模块
+- [ ] **T-024** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式
+
+### 模块 02-memory:完整深度处理
+
+- [ ] **T-025** - 用真实场景重写导语
+- [ ] **T-026** - 添加决策树(Mermaid)
+- [ ] **T-027** - 添加 2 个以上 "Try It Now" 模块
+- [ ] **T-028** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式
+
+### 模块 03-skills:完整深度处理
+
+- [ ] **T-029** - 用真实场景重写导语
+- [ ] **T-030** - 添加决策树(Mermaid)
+- [ ] **T-031** - 添加 2 个以上 "Try It Now" 模块
+- [ ] **T-032** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式
+
+### 模块 10-cli:完整深度处理
+
+- [ ] **T-033** - 用真实场景重写导语
+- [ ] **T-034** - 添加决策树(Mermaid)
+- [ ] **T-035** - 添加 2 个以上 "Try It Now" 模块
+- [ ] **T-036** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式
+
+### 生成器校验
+
+- [ ] **T-037** - 每次模块升级后运行 `scripts/build-agent-index.py`;确认 manifest 输出有效
+- [ ] **T-038** - 在每次 push 时添加 CI 步骤:校验 agent-manifest.json schema
+
+**M2 检查点:6/10 个模块完成,生成器输出有效 manifest**
+
+---
+
+## 第 3 阶段 - 深度处理:强模块第二批(2026 年 7 月 - 8 月)
+
+**目标里程碑:M3**
+
+### 模块 04-subagents:完整深度处理
+
+- [ ] **T-039** - 用真实场景重写导语
+- [ ] **T-040** - 添加决策树(Mermaid)
+- [ ] **T-041** - 添加 2 个以上 "Try It Now" 模块
+- [ ] **T-042** - 添加 "Patterns & Recipes" 部分(例如:"The Multi-Agent Review Pattern")
+
+### 模块 05-mcp:完整深度处理
+
+- [ ] **T-043** - 用真实场景重写导语
+- [ ] **T-044** - 添加决策树(Mermaid)
+- [ ] **T-045** - 添加 2 个以上 "Try It Now" 模块
+- [ ] **T-046** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式
+
+### 模块 07-plugins:完整深度处理
+
+- [ ] **T-047** - 用真实场景重写导语
+- [ ] **T-048** - 添加决策树(Mermaid)
+- [ ] **T-049** - 添加 2 个以上 "Try It Now" 模块
+- [ ] **T-050** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式
+
+### 模块 09-advanced-features:完整深度处理
+
+- [ ] **T-051** - 用真实场景重写导语
+- [ ] **T-052** - 添加决策树(Mermaid)
+- [ ] **T-053** - 添加 2 个以上 "Try It Now" 模块
+- [ ] **T-054** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式
+
+**M3 检查点:全部 10 个模块完成且风格一致**
+
+---
+
+## 第 4 阶段 - 代理层与跨模块(2026 年 9 月)
+
+**目标里程碑:M4**
+
+### 支柱 2:最终完成 AI 代理索引
+
+- [ ] **T-055** - 使用所有 10 个完成的模块运行 `scripts/build-agent-index.py`
+ - 生成最终版 `agent-manifest.json`,覆盖率达到 100%
+ - 生成 `AGENT-INDEX.md` 并从 `README.md` 链接
+
+- [ ] **T-056** - 创建 `skills/claude-howto-lookup/SKILL.md`
+ - 读取 `agent-manifest.json` 以查找相关模块
+ - 使用 `Read` 加载对应章节
+ - 安装方式:`cp -r claude-howto/skills/claude-howto-lookup ~/.claude/skills/`
+
+- [ ] **T-057** - 在 quickstart.sh 和 QUICKSTART.md 中把 lookup skill 作为可选功能提到
+
+### 支柱 3b:跨模块 `RECIPES.md`
+
+- [ ] **T-058** - 创建带有 5 个以上组合工作流的 `RECIPES.md`
+ - 每个 recipe 的 schema:name、modules-used、problem、solution 代码块、expected outcome
+ - 示例:skill + hook + subagent = 自动审查流水线
+ - 确保所有主要标题都有 HTML 锚点,便于深链
+
+### 支柱 5:社区展示
+
+- [ ] **T-059** - 创建 `COMMUNITY-PROJECTS.md`
+ - 静态 Markdown 页面,提交格式包括:name、description、link、features used
+ - 包含模板条目
+ - 提供基于 PR 的提交说明
+
+**M4 检查点:代理索引上线,recipes 上线,社区页面上线**
+
+---
+
+## 第 5 阶段 - 版本审计与 recipe 扩展(2026 年 10 月 - 11 月)
+
+**目标里程碑:M5**
+
+- [ ] **T-060** - 进行完整版本审计:验证所有 10 个模块是否与当前 CC 版本匹配
+ - 更新每个模块的 `cc_version_verified` frontmatter
+ - 更新版本徽章
+
+- [ ] **T-061** - 将 `RECIPES.md` 扩展到 8 个以上 recipes,基于社区实践模式
+
+- [ ] **T-062** - 如果完成的模块中出现新的模式,则迭代 agent manifest schema
+
+- [ ] **T-063** - 开一个置顶 GitHub Discussion:"分享你的 Claude Code 工作流"
+ - 收集真实 agent 使用信号,为后续 recipe 扩展提供依据
+
+**M5 检查点:所有模块都已验证当前版本,recipes 持续增长**
+
+---
+
+## 第 6 阶段 - 组合与持续运行(2026 年 12 月 - 2027 年 3 月)
+
+**目标里程碑:M6**
+
+- [ ] **T-064** - 每次 CC 发布后运行 `/docs-sync-claude-code` skill;更新 `WHATS-NEW.md`
+
+- [ ] **T-065** - 确保 agent manifest 覆盖 100% 模块(CI 回归测试)
+
+- [ ] **T-066** - 将 `RECIPES.md` 扩展到 10 个以上 recipes
+
+- [ ] **T-067** - 监控 `COMMUNITY-PROJECTS.md` 的自然增长;筛选新增条目
+
+- [ ] **T-068** - 评估来自 GitHub Discussions 的 agent 使用信号;如果验证有效,就投入资源推广 lookup skill(营销、asm registry)
+
+**M6 检查点:系统已经可以自我维持**
+
+---
+
+## 延后项(TODOS.md)
+
+这些内容不在本计划范围内。请记录在这里,避免范围蔓延:
+
+- Skill marketplace / 可安装 registry
+- 自定义网站或仪表盘
+- 完成度追踪基础设施(cc-progress)
+- 带 CI 校验的社区教程模板
+- 自动生成的 CONTRIBUTORS.md
+- 多语言翻译
+- 测验 / 评估基础设施升级
+- COMMUNITY-PROJECTS.md 的社区投票 / 审核机制
+
+---
+
+## 按阶段划分的任务摘要
+
+| 阶段 | 任务 | 时间段 | 涉及模块 |
+|-------|-------|--------|-----------------|
+| 1 - 基础设施与薄弱模块 | T-001 到 T-020 | 2026 年 4 月 | 06-hooks、08-checkpoints + 基础设施 |
+| 2 - 第一批深度处理 | T-021 到 T-038 | 2026 年 5 月 - 6 月 | 01、02、03、10 |
+| 3 - 第二批深度处理 | T-039 到 T-054 | 2026 年 7 月 - 8 月 | 04、05、07、09 |
+| 4 - 代理层与跨模块 | T-055 到 T-059 | 2026 年 9 月 | 全部(manifest)+ 新文件 |
+| 5 - 版本审计与 recipes | T-060 到 T-063 | 2026 年 10 月 - 11 月 | 全部(审计) |
+| 6 - 持续运行 | T-064 到 T-068 | 2026 年 12 月 - 2027 年 3 月 | 持续进行 |
diff --git a/zh/prompts/remotion-video.md b/zh/prompts/remotion-video.md
new file mode 100644
index 0000000..0772483
--- /dev/null
+++ b/zh/prompts/remotion-video.md
@@ -0,0 +1,350 @@
+你是一位擅长 Remotion 的资深动效设计师和高级 React 工程师。你的目标是把产品描述转化为一个高能量、专业动画感强的视频,并使用 React 代码实现。
+
+**先自主探索:** 立即开始探索代码库,收集产品信息。只有在你探索之后,仍然缺少关键或不清晰的信息时,才向用户提问。
+
+请遵循一个 7 阶段工作流,并根据你收集到的信息在每一步做出聪明的决策。
+
+---
+
+# 🔄 自动化工作流
+
+**关键原则:**
+
+- **先探索:** 永远先自动探索代码库,收集产品信息。不要一上来就问产品问题。
+- **先问偏好,再规划:** 探索之后,先向用户展示发现结果,再询问视频偏好(尺寸、风格、时长、自定义项),然后再创建计划。
+- **产品 URL 优先:** 如果找到了或用户提供了产品 URL,它就是第一信息源。产品页面上的信息优先于代码库发现。
+- **重价值,不重技术:** 聚焦价值主张、客户收益和功能(用户获得了什么),而不是技术规格或实现细节。
+- **以客户为中心:** 强调产品如何解决问题、改善生活或为用户带来收益。
+- **自主执行:** 用户确认偏好后,自动推进到规划和实现阶段,不要再请求额外批准。
+
+## 📋 第 1 阶段:自主资源发现
+
+**目标:** 自动探索代码库,收集所有可用的产品信息,不要询问用户。
+
+**动作:**
+
+1. **先自动探索代码库:**
+ - 搜索 `README.md`,查找产品描述和价值主张
+ - 检查 `package.json`,获取产品名称、描述和主页 URL
+ - 在 `/assets`、`/public`、`/static`、`/images` 目录中查找品牌资源
+ - 从 CSS / Tailwind 配置文件中提取配色方案
+ - 查找任何现有的营销文案或文档
+ - 在配置文件、环境变量或文档中查找任何产品 URL
+
+2. **如果找到了产品 URL,立即抓取:**
+ - 使用 WebFetch 提取产品页面的信息
+ - 产品页面信息优先于代码库发现
+ - 提取所有价值主张、功能和品牌信息
+
+3. **汇总所有收集到的信息:**
+ - 产品名称和描述
+ - 价值主张
+ - 核心功能和收益
+ - 品牌色和风格
+ - 目标受众(根据语气推断)
+ - 任何现有资源或媒体
+
+4. **对缺失信息使用智能默认值:**
+ - **视频格式:** 横屏 1920x1080(适合 YouTube / Web)
+ - **时长:** 30 秒(大多数平台都适合)
+ - **风格:** 现代、简洁、专业(基于品牌)
+ - **品牌色:** 使用提取到的颜色,或采用现代互补配色
+
+5. **只有在以下情况下才询问用户:**
+ - 探索后仍无法确定产品名称或找不到任何产品信息
+ - 无法找到或访问产品 URL
+ - 存在关键歧义(例如 B2B 和 B2C 的差异会显著改变表达方式)
+ - 有冲突信息需要澄清
+
+**重要:** 这一整段探索要静默、自主完成。不要问“我需要什么才能开始”或列出需求。只有在真正必要时才打断用户。
+
+**输出:** 立即带着所有收集到的信息进入第 2 阶段。
+
+---
+
+## 🔍 第 2 阶段:信息分析与深度挖掘
+
+**目标:** 分析收集到的信息,并提炼出视频创作所需的关键洞察。
+
+**动作:**
+
+1. **回顾第 1 阶段收集到的全部信息:**
+ - 产品页面内容(如果找到了并抓取了 URL)
+ - 代码库发现(README、package.json、资源等)
+ - 任何品牌指南或营销材料
+
+2. **提炼并排序(聚焦价值,不聚焦技术):**
+ - **价值主张**(首要)- 对客户的核心收益
+ - **客户收益** - 它如何改善用户生活
+ - **核心功能** - 用收益来描述,而不是技术规格
+ - **独特卖点** - 与其他方案相比有什么不同/更好
+ - **使用场景** - 真实世界应用
+ - **品牌识别**(颜色、字体、风格、语气)
+ - **目标受众洞察**(这是谁的产品)
+ - **情感吸引力**和信息表达(人们为什么在意)
+
+3. **静默用智能推断补齐空白:**
+ - 如果价值主张不明确,从功能和目标受众推断
+ - 如果目标受众不清晰,从产品类型和文案语气推断
+ - 如果缺少品牌色,创建一套现代的互补配色
+ - 除非与用户可见内容相关,否则避免技术实现细节
+
+4. **只有在以下情况下才请求澄清:**
+ - 存在多个相互冲突的价值主张
+ - 无法判断产品是 B2B 还是 B2C(这会显著影响表达)
+ - 目标受众确实过于模糊
+
+**输出:** 对产品价值、收益和品牌有清晰理解,足以支持视频制作。
+
+---
+
+## ✅ 第 3 阶段:展示发现并收集用户偏好
+
+**目标:** 分享你发现的内容,并在进入规划前获取用户对视频偏好的输入。
+
+**动作:**
+
+1. **展示发现摘要:**
+
+ ```text
+ 📊 发现的信息
+
+ 产品:[名称]
+ 价值主张:[对客户的主要收益]
+ 核心功能:[2-3 个主要收益]
+ 品牌色:[提取到或建议的颜色]
+ 目标受众:[这是谁的产品]
+ ```
+
+2. **询问用户偏好(进入下一步前必须完成):**
+
+ 使用清晰简洁的格式:
+
+ ```text
+ 在我创建视频之前,请告诉我你的偏好:
+
+ 1. **视频尺寸/格式:**
+ - 横屏(1920x1080)- YouTube、网站
+ - 竖屏(1080x1920)- TikTok、Instagram Reels
+ - 方形(1080x1080)- Instagram 信息流
+
+ 2. **视频时长:**
+ - 15 秒 - 快速社媒广告
+ - 30 秒 - 标准宣传视频
+ - 60 秒 - 详细功能展示
+ - 自定义时长
+
+ 3. **视频风格:**
+ - 现代 & 极简 - 干净的 Apple 风格美学
+ - 有冲击力 & 高能量 - 快节奏,适合社媒
+ - 专业 & 企业感 - 面向商业场景
+ - 自定义风格(描述你的想法)
+
+ 4. **还想突出或自定义什么?**
+ (特定功能、文案、颜色等)
+ ```
+
+3. **等待用户回复** 后再进入第 4 阶段。
+
+4. **确认并回应:**
+ - 总结用户选择
+ - 应用任何自定义要求
+ - 根据确认方向继续做结构设计
+
+**输出:** 用户确认的视频规格,准备进入规划阶段。
+
+---
+
+## 📐 第 4 阶段:结构设计(确认后)
+
+**目标:** 基于用户偏好,使用三幕式结构设计一个有吸引力的视频。
+
+**动作:**
+
+1. **根据用户确认的偏好设计视频结构:**
+
+ ```text
+ 🎬 视频结构
+
+ 第 1 幕:钩子(0-5 秒)
+ - [抓眼球的视觉概念]
+ - [强势的动画开场]
+ - [有吸引力的标题/问题]
+
+ 第 2 幕:价值展示(中段)
+ - [展示核心收益如何发挥作用]
+ - [用视觉叙事表达客户价值]
+ - [2-3 个作为收益呈现的功能亮点]
+
+ 第 3 幕:行动号召(结尾)
+ - [清晰的 CTA 和品牌强化]
+ - [令人印象深刻的收尾画面]
+ - [平滑的退出动画]
+ ```
+
+2. **应用用户偏好:**
+ - 使用指定的视频尺寸/格式
+ - 匹配所选风格(极简/高能量/专业)
+ - 按指定时长调整节奏
+ - 融入任何自定义要求
+
+3. **基于以下内容做创意决策:**
+ - 产品价值主张(什么最吸引人)
+ - 目标受众(什么最能打动他们)
+ - 用户的风格偏好
+ - 品牌个性(视觉和语气的一致性)
+
+4. **简要展示结构**,然后自动进入第 5 阶段。
+
+**输出:** 可直接用于实现规划的视频结构。
+
+---
+
+## 🛠️ 第 5 阶段:技术架构
+
+**目标:** 设计实现架构,并直接开始构建。
+
+**动作:**
+
+1. **静默设计** 组件架构:
+ - 工具函数(easing、动画辅助、颜色工具)
+ - 可复用组件(AnimatedTitle、FeatureHighlight 等)
+ - 场景组件(Hook、Demo、CTA 场景)
+ - 主组合结构(Video.tsx、Root.tsx)
+
+2. **规划技术细节:**
+ - 动画时序和 easing 曲线
+ - 调色板实现
+ - 字体层级
+ - 图标和资源策略
+ - 序列时间拆分
+
+3. **无需请求批准,直接进入第 6 阶段**实现。
+
+**输出:** 可立即实现的内部技术蓝图。
+
+---
+
+## 💻 第 6 阶段:实现
+
+**目标:** 自主构建完整的 Remotion 视频项目。
+
+**约束与技术栈:**
+
+1. **框架:** Remotion(React)
+2. **样式:** Tailwind CSS(通过 `className` 或标准样式对象)
+3. **动画:** 使用 `spring`、`interpolate` 和 `useCurrentFrame` 实现平滑运动
+4. **代码风格:** 模块化组件。不要把所有东西都堆在 `Root.tsx` 里
+5. **最佳实践:**
+ - 不要有静态内容。所有元素都应该有入场(opacity / scale / slide)和退场
+ - 如有需要,使用 Lucide-React 图标
+ - 使用标准字体,但要强样式化(粗体、紧字距)
+ - 不要使用外部图片,除非是占位图(例如 `https://placehold.co/600x400`)或用户提供的资源
+
+**动作:**
+
+1. **按以下顺序构建完整项目结构:**
+ - 工具函数(easing、动画辅助、颜色工具)
+ - 可复用组件(AnimatedTitle、FeatureHighlight、过渡)
+ - 场景组件(HookScene、DemoScene、CTAScene)
+ - 主合成(带编排的 Video.tsx)
+ - 根配置(注册正确的 Root.tsx)
+
+2. **静默高效地工作:**
+ - 不要逐步叙述每一步
+ - 基于已收集信息做设计决策
+ - 使用专业的动画原则
+ - 确保场景之间过渡平滑
+
+3. **实现完成后自动进入第 7 阶段。**
+
+**输出:** 完整、可直接交付的 Remotion 项目代码。
+
+---
+
+## 🎥 第 7 阶段:交付与后续
+
+**目标:** 提供渲染说明,并标记项目完成。
+
+**动作:**
+
+1. **提供渲染说明:**
+
+ ```bash
+ # 在浏览器中预览视频
+ npm run dev
+
+ # 渲染最终视频
+ npm run build
+ npx remotion render Video out/video.mp4
+
+ # 指定编解码设置
+ npx remotion render Video out/video.mp4 --codec h264
+ ```
+
+2. **交付摘要:**
+ - 简要说明创建了什么
+ - 视频的关键特性
+ - 视频规格(时长、格式、尺寸)
+ - 任何值得注意的设计决策
+
+3. **用户可以在需要时请求修改:**
+ - 时间调整
+ - 动画修改
+ - 内容更新
+ - 风格微调
+
+**输出:** 完整的 Remotion 项目,附带清晰的渲染说明,可直接使用。
+
+---
+
+# 🎯 质量标准
+
+在所有阶段都要保持以下标准:
+
+**视觉质量:**
+- 专业级动画(平滑、明确、有品牌感)
+- 一致的间距和对齐
+- 具备良好对比度的易读排版
+- 协调统一的色彩使用
+
+**技术质量:**
+- 干净、模块化的代码架构
+- 性能优化(平滑 30fps 播放)
+- 正确使用 Remotion API(spring、interpolate、Sequence)
+- 如果使用 TypeScript,则具备类型安全
+
+**创意质量:**
+- 清晰的叙事结构
+- 抓眼的开场
+- 强有力的行动号召
+- 令人记住的视觉瞬间
+
+---
+
+# 🚀 开始使用
+
+我会为你的产品创建一个专业的 Remotion 视频项目。工作流程如下:
+
+## 第 1-2 阶段:自主探索(我会自动完成)
+
+1. 探索你的代码库,查找产品细节、品牌资源和颜色
+2. 如果找到了产品 URL,抓取并分析产品页面
+3. 提取价值主张和关键收益
+
+## 第 3 阶段:你的输入(我会询问你)
+
+1. 展示我发现的内容
+2. 询问你的视频偏好:
+ - 视频尺寸/格式(横屏 / 竖屏 / 方形)
+ - 时长(15 秒 / 30 秒 / 60 秒)
+ - 风格(极简 / 高能量 / 专业)
+ - 任何自定义项
+
+## 第 4-7 阶段:自主执行(我会自动完成)
+
+1. 根据你的偏好设计视频结构
+2. 构建完整的 Remotion 项目并加入专业动画
+3. 交付可直接使用的生产级代码和渲染说明
+
+让我们一起做出一个很棒的作品!
diff --git a/zh/resources.md b/zh/resources.md
new file mode 100644
index 0000000..4723236
--- /dev/null
+++ b/zh/resources.md
@@ -0,0 +1,248 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+# 优质资源清单
+
+## 官方文档
+
+| 资源 | 说明 | 链接 |
+|----------|-------------|------|
+| Claude Code 文档 | Claude Code 官方文档 | [code.claude.com/docs/en/overview](https://code.claude.com/docs/en/overview) |
+| Anthropic 文档 | Anthropic 完整文档 | [docs.anthropic.com](https://docs.anthropic.com) |
+| MCP Protocol | Model Context Protocol 规范 | [modelcontextprotocol.io](https://modelcontextprotocol.io) |
+| MCP Servers | 官方 MCP server 实现 | [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) |
+| Anthropic Cookbook | 代码示例和教程 | [github.com/anthropics/anthropic-cookbook](https://github.com/anthropics/anthropic-cookbook) |
+| Claude Code Skills | 社区技能仓库 | [github.com/anthropics/skills](https://github.com/anthropics/skills) |
+| Agent Teams | 多 agent 协作与协调 | [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) |
+| Scheduled Tasks | 使用 `/loop` 和 cron 的周期性任务 | [code.claude.com/docs/en/scheduled-tasks](https://code.claude.com/docs/en/scheduled-tasks) |
+| Chrome Integration | 浏览器自动化 | [code.claude.com/docs/en/chrome](https://code.claude.com/docs/en/chrome) |
+| Keybindings | 键盘快捷键自定义 | [code.claude.com/docs/en/keybindings](https://code.claude.com/docs/en/keybindings) |
+| Desktop App | 原生桌面应用 | [code.claude.com/docs/en/desktop](https://code.claude.com/docs/en/desktop) |
+| Remote Control | 远程会话控制 | [code.claude.com/docs/en/remote-control](https://code.claude.com/docs/en/remote-control) |
+| Auto Mode | 自动权限管理 | [code.claude.com/docs/en/permissions](https://code.claude.com/docs/en/permissions) |
+| Channels | 多通道通信 | [code.claude.com/docs/en/channels](https://code.claude.com/docs/en/channels) |
+| Voice Dictation | Claude Code 语音输入 | [code.claude.com/docs/en/voice-dictation](https://code.claude.com/docs/en/voice-dictation) |
+
+## Anthropic Engineering Blog
+
+| 文章 | 说明 | 链接 |
+|---------|-------------|------|
+| Code Execution with MCP | 如何通过代码执行解决 MCP 上下文膨胀问题,Token 数量减少 98.7% | [anthropic.com/engineering/code-execution-with-mcp](https://www.anthropic.com/engineering/code-execution-with-mcp) |
+
+---
+
+## 30 分钟掌握 Claude Code
+
+_视频_: https://www.youtube.com/watch?v=6eBSHbLKuN0
+
+_**全部技巧**_
+- **探索高级功能和快捷键**
+ - 定期查看 Claude 发布说明中的新代码编辑与上下文功能。
+ - 学习键盘快捷键,在聊天、文件和编辑器视图之间快速切换。
+
+- **高效设置**
+ - 为项目创建带有清晰名称和描述的会话,便于之后查找。
+ - 将最常用的文件或文件夹固定住,让 Claude 随时可访问。
+ - 配置 Claude 的集成,例如 GitHub 和常见 IDE,以简化你的编码流程。
+
+- **高效的代码库问答**
+ - 向 Claude 询问架构、设计模式和具体模块的细节问题。
+ - 在问题里使用文件和行号引用,例如:“`app/models/user.py` 里的逻辑是在做什么?”
+ - 对于大型代码库,提供摘要或清单,帮助 Claude 聚焦。
+ - **示例提示词**:_“你能解释一下 `src/auth/AuthService.ts:45-120` 里实现的认证流程吗?它是如何与 `src/middleware/auth.ts` 里的中间件集成的?”_
+
+- **代码编辑与重构**
+ - 使用代码块中的内联注释或请求来获得更聚焦的编辑结果(例如:“把这个函数重构得更清晰一些”)。
+ - 让 Claude 给出并排的修改前后对比。
+ - 在重大修改后,让 Claude 生成测试或文档,以保证质量。
+ - **示例提示词**:_“把 `api/users.js` 里的 `getUserData` 函数从 promises 改成 async/await。给我一个修改前后对比,并为重构后的版本生成单元测试。”_
+
+- **上下文管理**
+ - 只粘贴当前任务真正需要的代码和上下文。
+ - 使用结构化提示词(“这里是文件 A,这里是函数 B,我的问题是 X”)通常效果最好。
+ - 在提示窗口里移除或折叠大文件,避免超出上下文限制。
+ - **示例提示词**:_“这里是 `models/User.js` 里的 User 模型,以及 `utils/validation.js` 里的 `validateUser` 函数。我的问题是:如何在保持向后兼容的前提下添加邮箱验证?”_
+
+- **接入团队工具**
+ - 将 Claude 会话连接到你们团队的代码仓库和文档。
+ - 使用内置模板,或为重复出现的工程任务创建自定义模板。
+ - 通过和队友共享会话记录与提示词来协作。
+
+- **提升性能**
+ - 给 Claude 清晰、面向目标的指令,例如:“用五个要点总结这个类”。
+ - 从上下文窗口中删掉不必要的注释和样板代码。
+ - 如果 Claude 的输出跑偏了,重置上下文或重新表述问题,以获得更好的对齐。
+ - **示例提示词**:_“用五个要点总结 `src/db/Manager.ts` 里的 `DatabaseManager` 类,重点说明它的核心职责和关键方法。”_
+
+- **实用场景示例**
+ - 调试:粘贴错误和堆栈信息,然后询问可能的原因和修复方式。
+ - 生成测试:为复杂逻辑请求属性测试、单元测试或集成测试。
+ - 代码审查:请 Claude 识别风险变更、边界情况或代码异味。
+ - **示例提示词**:
+ - _“我遇到这个错误:`TypeError: Cannot read property 'map' of undefined at line 42 in components/UserList.jsx`。这是堆栈信息和相关代码。是什么原因导致的?我该怎么修复?”_
+ - _“为 `PaymentProcessor` 类生成完整的单元测试,包括失败交易、超时和无效输入等边界情况。”_
+ - _“审查这个 pull request diff,找出潜在的安全问题、性能瓶颈和代码异味。”_
+
+- **工作流自动化**
+ - 用 Claude 提示词为格式化、清理、批量重命名等重复任务编写脚本。
+ - 用 Claude 基于代码 diff 起草 PR 描述、发布说明或文档。
+ - **示例提示词**:_“根据 git diff,生成一份详细的 PR 描述,包含变更摘要、修改文件列表、测试步骤和潜在影响。同时为 2.3.0 版本生成发布说明。”_
+
+**提示**:想要获得最佳效果,可以把这些实践组合起来使用。先固定关键文件并总结目标,再使用聚焦的提示词和 Claude 的重构工具,逐步改进你的代码库和自动化流程。
+
+
+**与 Claude Code 配合使用的推荐工作流**
+
+### Claude Code 推荐工作流
+
+#### 新仓库场景
+
+1. **初始化仓库并接入 Claude**
+ - 建立新仓库的基础结构:`README`、`LICENSE`、`.gitignore`、根配置文件。
+ - 创建 `CLAUDE.md`,说明架构、高层目标和编码规范。
+ - 安装 Claude Code,并将其连接到仓库,用于代码建议、测试脚手架和工作流自动化。
+
+2. **使用计划模式和规格说明**
+ - 在实现功能之前,使用计划模式(`shift-tab` 或 `/plan`)先写详细规格。
+ - 让 Claude 给出架构建议和初始项目布局。
+ - 保持清晰、面向目标的提示词序列,依次询问组件轮廓、主要模块和职责。
+
+3. **迭代开发与审查**
+ - 把核心功能拆成小块逐步实现,并在过程中请求 Claude 生成代码、重构和文档。
+ - 每增加一小步,都请求单元测试和示例。
+ - 在 `CLAUDE.md` 中维护持续更新的任务列表。
+
+4. **自动化 CI/CD 和部署**
+ - 用 Claude 搭建 GitHub Actions、npm/yarn 脚本或部署工作流。
+ - 通过更新 `CLAUDE.md` 并请求对应命令/脚本,轻松调整流水线。
+
+```mermaid
+graph TD
+ A[Start New Repository] --> B[Initialize Repository Structure]
+ B --> C[Create README, LICENSE, .gitignore]
+ C --> D[Create CLAUDE.md]
+ D --> E[Document Architecture & Guidelines]
+ E --> F[Install & Link Claude Code]
+
+ F --> G[Enter Plan Mode]
+ G --> H[Draft Feature Specification]
+ H --> I[Get Architecture Suggestions]
+ I --> J[Define Components & Modules]
+
+ J --> K[Implement Feature Chunk]
+ K --> L[Generate Code with Claude]
+ L --> M[Request Unit Tests]
+ M --> N[Review & Refactor]
+ N --> O{More Features?}
+ O -->|Yes| K
+ O -->|No| P[Update Task List in CLAUDE.md]
+
+ P --> Q[Setup CI/CD Pipeline]
+ Q --> R[Scaffold GitHub Actions]
+ R --> S[Create Deployment Scripts]
+ S --> T[Test Automation]
+ T --> U[Repository Ready]
+
+ style A fill:#e1f5ff
+ style G fill:#fff4e1
+ style K fill:#f0ffe1
+ style Q fill:#ffe1f5
+ style U fill:#90EE90
+```
+
+#### 现有仓库场景
+
+1. **仓库与上下文准备**
+ - 添加或更新 `CLAUDE.md`,记录仓库结构、编码模式和关键文件。对于旧仓库,可以使用 `CLAUDE_LEGACY.md`,其中涵盖框架、版本映射、说明、已知问题和升级笔记。
+ - 固定或高亮 Claude 应该用来作为上下文的主文件。
+
+2. **上下文驱动的代码问答**
+ - 让 Claude 基于具体文件/函数,回答代码审查、 bug 解释、重构或迁移计划。
+ - 给 Claude 明确边界,例如“只修改这些文件”或者“不要新增依赖”。
+
+3. **分支、工作区和多会话管理**
+ - 使用多个 git worktree 做隔离的功能开发或 bug 修复,并为每个 worktree 启动独立的 Claude 会话。
+ - 通过终端标签页/窗口按分支或功能组织并行工作。
+
+4. **团队工具和自动化**
+ - 通过 `.claude/commands/` 同步自定义命令,保持团队一致性。
+ - 用 Claude 的 slash commands 或 hooks 自动化重复任务、PR 创建和代码格式化。
+ - 与团队成员共享会话和上下文,便于协作排障和审查。
+
+```mermaid
+graph TD
+ A[Start with Existing Repository] --> B{Legacy Codebase?}
+ B -->|Yes| C[Create CLAUDE_LEGACY.md]
+ B -->|No| D[Create/Update CLAUDE.md]
+ C --> E[Document Frameworks & Version Maps]
+ D --> F[Document Structure & Patterns]
+ E --> G[Pin Key Files for Context]
+ F --> G
+
+ G --> H[Identify Task Type]
+ H --> I{Task Category}
+ I -->|Bug Fix| J[Ask Claude for Bug Analysis]
+ I -->|Code Review| K[Request Code Review]
+ I -->|Refactor| L[Plan Refactoring Strategy]
+ I -->|Migration| M[Create Migration Plan]
+
+ J --> N[Set Explicit Boundaries]
+ K --> N
+ L --> N
+ M --> N
+
+ N --> O{Multiple Features?}
+ O -->|Yes| P[Create Git Worktrees]
+ O -->|No| Q[Work on Main Branch]
+ P --> R[Launch Separate Claude Sessions]
+ R --> S[Organize Terminal Tabs]
+ Q --> S
+
+ S --> T[Setup Team Automation]
+ T --> U[Sync .claude/commands/]
+ U --> V[Configure Slash Commands]
+ V --> W[Setup Hooks for Automation]
+ W --> X[Share Session Context with Team]
+
+ X --> Y{More Tasks?}
+ Y -->|Yes| H
+ Y -->|No| Z[Workflow Complete]
+
+ style A fill:#e1f5ff
+ style C fill:#ffecec
+ style D fill:#fff4e1
+ style P fill:#f0ffe1
+ style T fill:#ffe1f5
+ style Z fill:#90EE90
+```
+
+**提示**:
+- 每个新功能或修复都从规格和计划模式提示词开始。
+- 对于旧仓库和复杂仓库,把更详细的指导存放在 `CLAUDE.md` / `CLAUDE_LEGACY.md` 中。
+- 给出清晰、聚焦的指令,把复杂工作拆成多阶段计划。
+- 定期清理会话、裁剪上下文,并删除已完成的工作区,避免堆积混乱。
+
+这些步骤概括了在新旧代码库中更顺畅使用 Claude Code 的核心建议。
+
+---
+
+## 2026 年 3 月新增功能与能力
+
+### 关键功能资源
+
+| 功能 | 说明 | 了解更多 |
+|---------|-------------|------------|
+| **Auto Memory** | Claude 会自动学习并记住你跨会话的偏好 | [记忆指南](02-memory/README.md) |
+| **Remote Control** | 通过外部工具和脚本以编程方式控制 Claude Code 会话 | [高级功能](09-advanced-features/README.md) |
+| **Web Sessions** | 通过基于浏览器的界面访问 Claude Code,实现远程开发 | [CLI 参考](10-cli/README.md) |
+| **Desktop App** | Claude Code 的原生桌面应用,界面更强大 | [Claude Code 文档](https://code.claude.com/docs/en/desktop) |
+| **Extended Thinking** | 通过 `Alt+T` / `Option+T` 或 `MAX_THINKING_TOKENS` 环境变量切换深度推理 | [高级功能](09-advanced-features/README.md) |
+| **Permission Modes** | 精细权限控制:default、acceptEdits、plan、auto、dontAsk、bypassPermissions | [高级功能](09-advanced-features/README.md) |
+| **7-Tier Memory** | Managed Policy、Project、Project Rules、User、User Rules、Local、Auto Memory | [记忆指南](02-memory/README.md) |
+| **Hook Events** | 25 个事件:PreToolUse、PostToolUse、PostToolUseFailure、Stop、StopFailure、SubagentStart、SubagentStop、Notification、Elicitation 等 | [Hooks 指南](06-hooks/README.md) |
+| **Agent Teams** | 协调多个 agent 共同处理复杂任务 | [Subagents 指南](04-subagents/README.md) |
+| **Scheduled Tasks** | 用 `/loop` 和 cron 工具设置周期性任务 | [高级功能](09-advanced-features/README.md) |
+| **Chrome Integration** | 使用无头 Chromium 做浏览器自动化 | [高级功能](09-advanced-features/README.md) |
+| **Keyboard Customization** | 自定义按键绑定,包括组合键序列 | [高级功能](09-advanced-features/README.md) |
diff --git a/zh/resources/DESIGN-SYSTEM.md b/zh/resources/DESIGN-SYSTEM.md
new file mode 100644
index 0000000..82818f4
--- /dev/null
+++ b/zh/resources/DESIGN-SYSTEM.md
@@ -0,0 +1,244 @@
+# Claude How To - 设计系统
+
+## 视觉识别
+
+### 图标设计概念:指南针 + 代码括号
+
+Claude How To 的图标使用**指南针加 `>` 代码括号**来表示“在代码中导航”:
+
+```
+ N (green)
+ ▲
+ │
+W ───>─── E Compass = Guidance/Direction
+ │ > Bracket = Code/Terminal/CLI
+ ▼
+ S (black)
+```
+
+它带来了以下效果:
+- **视觉清晰**:一眼就能看出这是“代码导航指南”
+- **象征意义**:指南针 = 找到方向;`>` = 代码/终端
+- **可扩展性**:从 16px 到 512px 都能正常工作
+- **品牌一致性**:以极简配色匹配开发者工具气质
+
+---
+
+## 色彩系统
+
+### 配色
+
+| 颜色 | 十六进制 | RGB | 用途 |
+|-------|-----|-----|-------|
+| 黑色(主色) | `#000000` | 0, 0, 0 | 主描边、文字、南针 |
+| 白色(背景) | `#FFFFFF` | 255, 255, 255 | 浅色背景 |
+| 灰色(辅助) | `#6B7280` | 107, 114, 128 | 次要刻度、次级文字 |
+| 亮绿色(强调) | `#22C55E` | 34, 197, 94 | 北针、中心点、强调线 |
+| 接近黑色(深色背景) | `#0A0A0A` | 10, 10, 10 | 深色模式背景 |
+
+### 对比度(WCAG)
+
+- 黑底白字:**21:1** AAA
+- 灰底白字:**4.6:1** AA
+- 绿底白字:**3.2:1**(仅用于装饰,不用于正文)
+- 深色背景白字:**19.5:1** AAA
+
+### 强调色规则
+
+**亮绿色(#22C55E)仅用于高亮:**
+- 指南针北针
+- 中心点
+- 强调下划线/边框
+- 绝不作为背景色
+- 绝不用于正文
+
+---
+
+## 字体排版
+
+### Logo 字体
+- **字体族**:Inter、SF Pro Display、-apple-system、Segoe UI、sans-serif
+- **“Claude”**:42px,700 字重(加粗),黑色
+- **“How-To”**:32px,500 字重(中等),灰色(#6B7280)
+- **副标题**:10px,500 字重,灰色,字间距 1.5px,大写
+
+### 界面字体
+- **字体族**:Inter、SF Pro、系统字体(sans-serif)
+- **字重**:400-600
+- **风格**:简洁、易读
+
+---
+
+## 图标细节
+
+### 指南针规格
+
+指南针图形由以下几何元素组成:
+
+```
+Element | Stroke/Fill | Color
+--------------------|----------------|------------------
+Outer ring | 3px stroke | Black / White (dark mode)
+North tick | 2.5px stroke | Black / White (dark mode)
+Other cardinal ticks| 2px stroke | Gray / White 50% (dark mode)
+Intercardinal ticks | 1.5px stroke | Gray / White 40% (dark mode)
+North needle | filled polygon | #22C55E (always green)
+South needle | filled polygon | Black / White (dark mode)
+> bracket | 3px stroke | Black / White (dark mode)
+Center dot | filled circle | #22C55E (always green)
+```
+
+### 尺寸递进
+
+```
+16px → 仅环 + 指针 + 箭头(最简版)
+32px → 增加方位刻度
+64px → 增加中间方位刻度
+128px → 全细节,所有元素都清晰
+256px → 最高细节,较粗描边
+```
+
+---
+
+## 尺寸指南
+
+### Logo 尺寸
+
+- **最小**:200px 宽(用于网页)
+- **推荐**:520px(原始尺寸)
+- **最大**:无限制(矢量格式)
+- **宽高比**:约 4.3:1(宽:高)
+
+### 图标尺寸
+
+- **最小**:16px(favicon)
+- **推荐**:64-256px(应用、头像)
+- **最大**:无限制(矢量格式)
+- **宽高比**:1:1(正方形)
+
+---
+
+## 间距与对齐
+
+### Logo 留白
+
+```
+┌─────────────────────────────────────┐
+│ │
+│ 最小留白空间 │
+│ (logo 高度 / 2) │
+│ │
+│ [COMPASS] Claude │
+│ How-To │
+│ │
+└─────────────────────────────────────┘
+```
+
+### 图标中心点
+
+所有图标都以画布中心为基准:
+- 256px 画布使用 128×128 中心点
+- 128px 画布使用 64×64 中心点
+- 与其他 UI 元素保持对齐
+
+---
+
+## 无障碍性
+
+### 颜色对比
+- 所有文字都满足 WCAG AA(最低 4.5:1)
+- 绿色强调色只用于装饰,不承担信息传达
+- 不依赖红绿配色表达含义
+
+### 可扩展性
+- 矢量格式保证任意尺寸都清晰
+- 即使在 16px 下,几何形状依然可辨识
+- 细节会随可用空间逐步增加
+
+---
+
+## 应用示例
+
+### Web 页眉
+- 尺寸:520×120px logo
+- 文件:`logos/claude-howto-logo.svg`
+- 背景:白色或深色(#0A0A0A)
+- 内边距:至少 20px
+
+### 应用图标
+- 尺寸:256×256px
+- 文件:`icons/claude-howto-icon.svg`
+- 背景:白色或深色
+- 用途:应用快捷方式、头像
+
+### 浏览器 Favicon
+- 尺寸:32px(主用),16px(备用)
+- 文件:`favicons/favicon-32.svg`
+- 格式:SVG,显示清晰锐利
+
+### 社交媒体
+- 头像:256×256px 图标
+- 横幅:520×120px logo(居中)
+
+### 文档
+- 章节标题:按需缩放的 logo
+- 小节图标:64×64px favicon
+- 内联图标:32×32px favicon
+
+---
+
+## 文件格式细节
+
+### SVG 结构
+
+所有 SVG 文件都采用扁平设计:
+- 无渐变(仅用纯色)
+- 无滤镜效果(不使用模糊、发光或阴影)
+- 干净的描边和填充几何结构
+- 使用 `viewBox` 实现响应式缩放
+- 代码可读且带注释
+
+### 跨浏览器兼容性
+
+- Chrome/Edge:完全支持
+- Firefox:完全支持
+- Safari:完全支持
+- iOS Safari:完全支持
+- 所有现代浏览器:完全支持
+
+---
+
+## 自定义
+
+### 更换强调色
+
+如果你想创建不同强调色的变体:
+
+1. 把所有 `#22C55E` 替换成你的强调色
+2. 确保装饰性元素的对比度仍高于 3:1
+3. 保持黑/白/灰结构不变
+
+### 缩放
+
+```css
+svg {
+ width: 256px;
+ height: 256px;
+}
+```
+
+SVG 会通过 `viewBox` 自动缩放,不需要额外变换。
+
+---
+
+## 版本控制
+
+在 git 中跟踪设计变更:
+- 正常版本化 SVG 文件,因为它们本质上是文本
+- 随设计变更一起打 tag
+- 在提交中包含 `DESIGN-SYSTEM.md`
+
+---
+
+**最后更新**:2026 年 2 月
+**设计系统版本**:3.0
diff --git a/zh/resources/QUICK-START.md b/zh/resources/QUICK-START.md
new file mode 100644
index 0000000..44785a3
--- /dev/null
+++ b/zh/resources/QUICK-START.md
@@ -0,0 +1,89 @@
+# 快速开始 - 品牌资源
+
+## 复制资源到你的项目
+
+```bash
+# 将所有资源复制到你的 Web 项目中
+cp -r resources/ /path/to/your/website/
+
+# 或者只复制网页所需的 favicon
+cp resources/favicons/* /path/to/your/website/public/
+```
+
+## 添加到 HTML(直接复制粘贴)
+
+```html
+<!-- Favicons -->
+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-32.svg" sizes="32x32">
+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-16.svg" sizes="16x16">
+<link rel="apple-touch-icon" href="/resources/favicons/favicon-128.svg">
+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-256.svg" sizes="256x256">
+<meta name="theme-color" content="#000000">
+```
+
+## 在 Markdown/文档中使用
+
+```markdown
+# Claude How To
+
+![Claude How To Logo](resources/logos/claude-howto-logo.svg)
+
+![Icon](resources/icons/claude-howto-icon.svg)
+```
+
+## 推荐尺寸
+
+| 用途 | 尺寸 | 文件 |
+|---------|------|------|
+| 网站页眉 | 520×120 | `logos/claude-howto-logo.svg` |
+| 应用图标 | 256×256 | `icons/claude-howto-icon.svg` |
+| 浏览器标签页 | 32×32 | `favicons/favicon-32.svg` |
+| 移动端桌面图标 | 128×128 | `favicons/favicon-128.svg` |
+| 桌面应用 | 256×256 | `favicons/favicon-256.svg` |
+| 小头像 | 64×64 | `favicons/favicon-64.svg` |
+
+## 颜色值
+
+```css
+/* 在 CSS 中使用这些值 */
+--color-primary: #000000;
+--color-secondary: #6B7280;
+--color-accent: #22C55E;
+--color-bg-light: #FFFFFF;
+--color-bg-dark: #0A0A0A;
+```
+
+## 图标含义
+
+**指南针 + 代码括号**:
+- 指南针环 = 导航、结构化学习路径
+- 绿色北针 = 方向、进展、引导
+- 黑色南针 = 基础、根基
+- `>` 括号 = 终端提示符、代码、CLI 场景
+- 刻度线 = 精准、结构化步骤
+
+这象征着“在清晰引导下穿行于代码世界”。
+
+## 在哪里用什么
+
+### 网站
+- **页眉**:Logo(`logos/claude-howto-logo.svg`)
+- **Favicon**:32px(`favicons/favicon-32.svg`)
+- **社交预览**:图标(`icons/claude-howto-icon.svg`)
+
+### GitHub
+- **README 徽章**:图标(`icons/claude-howto-icon.svg`),建议 64-128px
+- **仓库头像**:图标(`icons/claude-howto-icon.svg`)
+
+### 社交媒体
+- **头像**:图标(`icons/claude-howto-icon.svg`)
+- **横幅**:Logo(`logos/claude-howto-logo.svg`)
+- **缩略图**:256×256px 图标
+
+### 文档
+- **章节标题**:Logo 或图标(按需缩放)
+- **导航图标**:Favicon(32-64px)
+
+---
+
+完整文档见 [README.md](README.md)。
diff --git a/zh/resources/README.md b/zh/resources/README.md
new file mode 100644
index 0000000..1be1235
--- /dev/null
+++ b/zh/resources/README.md
@@ -0,0 +1,266 @@
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="logos/claude-howto-logo-dark.svg">
+ <img alt="Claude How To" src="logos/claude-howto-logo.svg">
+</picture>
+
+# Claude How To - 品牌资源
+
+这是 Claude How To 项目的完整品牌资源集合,包括 logo、图标和 favicon。所有资源都采用 V3.0 设计:一个带有代码括号(`>`)符号的指南针,象征在代码中引导前进,整体使用黑/白/灰配色,并以亮绿色(`#22C55E`)作为强调色。
+
+## 目录结构
+
+```
+resources/
+├── logos/
+│ ├── claude-howto-logo.svg # 主 logo - 浅色模式 (520×120px)
+│ └── claude-howto-logo-dark.svg # 主 logo - 深色模式 (520×120px)
+├── icons/
+│ ├── claude-howto-icon.svg # 应用图标 - 浅色模式 (256×256px)
+│ └── claude-howto-icon-dark.svg # 应用图标 - 深色模式 (256×256px)
+└── favicons/
+ ├── favicon-16.svg # Favicon - 16×16px
+ ├── favicon-32.svg # Favicon - 32×32px(主用)
+ ├── favicon-64.svg # Favicon - 64×64px
+ ├── favicon-128.svg # Favicon - 128×128px
+ └── favicon-256.svg # Favicon - 256×256px
+```
+
+`assets/logo/` 下还有额外资源:
+```
+assets/logo/
+├── logo-full.svg # 图形标记 + 品牌字样(横向)
+├── logo-mark.svg # 仅指南针符号 (120×120px)
+├── logo-wordmark.svg # 仅文字
+├── logo-icon.svg # 应用图标 (512×512,圆角)
+├── favicon.svg # 16×16 优化版
+├── logo-white.svg # 适用于深色背景的白色版本
+└── logo-black.svg # 黑色单色版本
+```
+
+## 资源概览
+
+### 设计概念(V3.0)
+
+**指南针 + 代码括号**,代表“导航遇见代码”:
+- **指南针环** = 导航、找到方向
+- **北针(绿色)** = 方向、学习路径上的进展
+- **南针(黑色)** = 扎实基础、稳固根基
+- **`>` 括号** = 终端提示符、代码、CLI 场景
+- **刻度线** = 精准、结构化学习
+
+### Logo
+
+**文件**:
+- `logos/claude-howto-logo.svg`(浅色模式)
+- `logos/claude-howto-logo-dark.svg`(深色模式)
+
+**规格**:
+- **尺寸**:520×120 px
+- **用途**:主标题/品牌 logo,带品牌字样
+- **使用场景**:
+ - 网站页眉
+ - README 徽章
+ - 营销素材
+ - 印刷物料
+- **格式**:SVG(可无限缩放)
+- **模式**:浅色(白色背景)与深色(#0A0A0A 背景)
+
+### 图标
+
+**文件**:
+- `icons/claude-howto-icon.svg`(浅色模式)
+- `icons/claude-howto-icon-dark.svg`(深色模式)
+
+**规格**:
+- **尺寸**:256×256 px
+- **用途**:应用图标、头像、缩略图
+- **使用场景**:
+ - App 图标
+ - 个人头像
+ - 社交媒体缩略图
+ - 文档页眉
+- **格式**:SVG(可无限缩放)
+- **模式**:浅色(白色背景)与深色(#0A0A0A 背景)
+
+**设计元素**:
+- 带方位和中间方位刻度的指南针环
+- 绿色北针(方向/引导)
+- 黑色南针(基础)
+- 中央 `>` 代码括号(终端/CLI)
+- 绿色中心点强调
+
+### Favicon
+
+为网页使用提供了多种尺寸的优化版本:
+
+| 文件 | 尺寸 | DPI | 用途 |
+|------|------|-----|------|
+| `favicon-16.svg` | 16×16 px | 1x | 浏览器标签页(旧浏览器) |
+| `favicon-32.svg` | 32×32 px | 1x | 标准浏览器 favicon |
+| `favicon-64.svg` | 64×64 px | 1x-2x | 高 DPI 显示器 |
+| `favicon-128.svg` | 128×128 px | 2x | Apple touch icon、书签 |
+| `favicon-256.svg` | 256×256 px | 4x | 现代浏览器、PWA 图标 |
+
+**优化说明**:
+- 16px:最小几何元素,仅保留环、指针和箭头
+- 32px:增加方位刻度
+- 64px 以上:完整细节与中间方位刻度
+- 全部版本都保持与主图标一致的视觉效果
+- SVG 格式保证任意尺寸下都清晰锐利
+
+## HTML 集成
+
+### 基础 Favicon 配置
+
+```html
+<!-- 浏览器 favicon -->
+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-32.svg">
+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-16.svg" sizes="16x16">
+
+<!-- Apple touch icon(移动端桌面图标) -->
+<link rel="apple-touch-icon" href="/resources/favicons/favicon-128.svg">
+
+<!-- PWA 与现代浏览器 -->
+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-256.svg" sizes="256x256">
+```
+
+### 完整配置
+
+```html
+<head>
+ <!-- 主 favicon -->
+ <link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-32.svg" sizes="32x32">
+ <link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-16.svg" sizes="16x16">
+
+ <!-- Apple touch icon -->
+ <link rel="apple-touch-icon" href="/resources/favicons/favicon-128.svg">
+
+ <!-- PWA 图标 -->
+ <link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-256.svg" sizes="256x256">
+
+ <!-- Android -->
+ <link rel="shortcut icon" href="/resources/favicons/favicon-256.svg">
+
+ <!-- PWA manifest 引用(如果使用 manifest.json) -->
+ <meta name="theme-color" content="#000000">
+</head>
+```
+
+## 颜色方案
+
+### 主色
+- **黑色**:`#000000`(主文本、线条、南针)
+- **白色**:`#FFFFFF`(浅色背景)
+- **灰色**:`#6B7280`(次级文本、次要刻度)
+
+### 强调色
+- **亮绿色**:`#22C55E`(北针、中心点、强调线条,只用于高亮,绝不作为背景)
+
+### 深色模式
+- **背景**:`#0A0A0A`(接近黑色)
+
+### CSS 变量
+```css
+--color-primary: #000000;
+--color-secondary: #6B7280;
+--color-accent: #22C55E;
+--color-bg-light: #FFFFFF;
+--color-bg-dark: #0A0A0A;
+```
+
+### Tailwind 配置
+```js
+colors: {
+ brand: {
+ primary: '#000000',
+ secondary: '#6B7280',
+ accent: '#22C55E',
+ }
+}
+```
+
+### 使用规范
+- 主文本和结构元素使用黑色
+- 次级/辅助元素使用灰色
+- 绿色**仅**用于高亮,例如指针、点和强调线
+- 不要把绿色用作背景色
+- 保持 WCAG AA 对比度(最低 4.5:1)
+
+## 设计规范
+
+### Logo 使用
+- 用于白色或深色(#0A0A0A)背景
+- 按比例缩放
+- Logo 四周保留足够留白(最小值:logo 高度 / 2)
+- 根据背景选择对应的浅色/深色版本
+
+### 图标使用
+- 适用于标准尺寸:16、32、64、128、256px
+- 保持指南针比例
+- 按比例缩放
+
+### Favicon 使用
+- 根据场景选用合适尺寸
+- 16-32px:浏览器标签页、书签
+- 64px:站点图标
+- 128px 以上:Apple/Android 桌面图标
+
+## SVG 优化
+
+所有 SVG 文件都采用扁平设计,没有渐变和滤镜:
+- 干净的基于描边的几何结构
+- 不嵌入位图
+- 路径已优化
+- 使用响应式 `viewBox`
+
+网页优化示例:
+```bash
+# 压缩 SVG,同时保持质量
+svgo --config='{
+ "js2svg": {
+ "indent": 2
+ },
+ "plugins": [
+ "convertStyleToAttrs",
+ "removeRasterImages"
+ ]
+}' input.svg -o output.svg
+```
+
+## PNG 转换
+
+如果你需要为旧浏览器支持转换成 PNG:
+
+```bash
+# 使用 ImageMagick
+convert -density 300 -background none favicon-256.svg favicon-256.png
+
+# 使用 Inkscape
+inkscape -D -z --file=favicon-256.svg --export-png=favicon-256.png
+```
+
+## 无障碍性
+
+- 高对比度颜色比例(符合 WCAG AA,最低 4.5:1)
+- 几何形状清晰,在各种尺寸下都容易识别
+- 矢量格式,可无限缩放
+- 图标中不使用文字(文字由单独的 wordmark 承担)
+- 不依赖红绿配色表达含义
+
+## 署名
+
+这些资源属于 Claude How To 项目。
+
+**许可证**:MIT(见项目 LICENSE 文件)
+
+## 版本历史
+
+- **v3.0**(2026 年 2 月):指南针 + 括号设计,黑/白/灰 + 绿色强调色
+- **v2.0**(2026 年 1 月):受 Claude 启发的 12 芒星爆发式设计,祖母绿配色
+- **v1.0**(2026 年 1 月):最初基于六边形的进度图标设计
+
+---
+
+**最后更新**:2026 年 2 月
+**当前版本**:3.0(指南针 + 括号)
+**全部资源**:可直接用于生产环境的 SVG,支持无限缩放,符合 WCAG AA 无障碍标准
diff --git a/zh/scripts/README.md b/zh/scripts/README.md
new file mode 100644
index 0000000..7623e1c
--- /dev/null
+++ b/zh/scripts/README.md
@@ -0,0 +1,69 @@
+# EPUB 构建脚本
+
+## 功能
+
+这个脚本会把整份指南构建成 EPUB 电子书,方便离线阅读。
+
+## 需求
+
+- Python 环境
+- `uv`
+- 相关依赖
+
+## 快速开始
+
+最简单的方式是直接让 `uv` 帮你处理依赖:
+
+```bash
+uv run scripts/build_epub.py
+```
+
+## 开发环境
+
+如果你要修改脚本本身,可以先创建虚拟环境,再安装开发依赖。
+
+```bash
+# 创建虚拟环境
+
+# 激活并安装依赖
+
+# 运行测试
+
+# 运行脚本
+```
+
+## 命令行选项
+
+常见选项包括:
+
+- 指定输出路径
+- 打开详细日志
+- 限制并发请求
+
+## 示例
+
+```bash
+# 带详细输出构建
+
+# 指定输出位置
+
+# 限制并发数(遇到限流时)
+```
+
+## 输出
+
+脚本会生成 EPUB 文件,里面包含所有内容和渲染后的图表。
+
+## 运行测试
+
+你可以用虚拟环境或直接通过 `uv` 运行测试。
+
+## 依赖
+
+脚本依赖的包会在项目的开发依赖里列出。
+
+## 故障排查
+
+- 检查 `uv` 是否可用
+- 检查 Python 版本
+- 检查依赖是否安装完整