CalvinBackup/claude-howto
1
0
Fork 0
mirror of https://github.com/luongnv89/claude-howto.git synced 2026-06-05 22:36:34 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Add Chinese (Simplified) translations for all documentation, organized
under a dedicated zh/ directory that mirrors the English folder structure.

Co-authored-by: tanqingkuang <tanqingkuang@users.noreply.github.com>

Translations originally contributed by @tanqingkuang in #45.
Restructured from *-CN.md suffix pattern into zh/ directory to prevent
the EPUB builder (scripts/build_epub.py collect_folder_files) from
picking up Chinese files via glob("*.md") inside module folders.
This commit is contained in:
Luong NGUYEN
2026-04-06 23:08:54 +02:00
committed by GitHub
parent 100c45eef2
commit 89e89d4aa3
100 changed files with 20487 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/check_cross_references.py
+2 -1
View File
@@ -3,6 +3,7 @@
import re import re
import sys import sys
import unicodedata
from pathlib import Path from pathlib import Path
IGNORE_DIRS = { IGNORE_DIRS = {
@@ -63,7 +64,7 @@ def main() -> int:
errors = [] errors = []
for file_path in iter_md_files(): 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 # Strip code blocks before scanning for links/anchors to avoid false positives
# from documentation examples inside code fences. # from documentation examples inside code fences.
scannable = strip_code_blocks(content) scannable = strip_code_blocks(content)
zh/.github/ISSUE_TEMPLATE/bug_report.md
Vendored
+43
View File
@@ -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 等）
## 示例代码
如果适用，请提供无法正常工作的示例代码：
```
[在这里插入代码]
```
## 截图
如果适用，请附上显示问题的截图。
## 其他上下文
还有哪些信息可能有助于我们理解这个问题？
## 可能的解决方案
如果你有修复建议，也可以写在这里。
zh/.github/ISSUE_TEMPLATE/documentation.md
Vendored
+44
View File
@@ -0,0 +1,44 @@
---
name: Documentation Issue
about: 报告文档中的不清晰、错别字或缺失信息
title: "[DOCS] "
labels: documentation
assignees: ''
---
## 问题类型
- [ ] 拼写或语法错误
- [ ] 解释不清
- [ ] 缺少信息
- [ ] 链接或引用损坏
- [ ] 内容过时
- [ ] 需要更好的示例
## 位置
哪一部分有问题？
- **文件**：（例如 README.md、03-skills/README.md）
- **章节**：（例如 "Installation Quick Reference"）
- **行号/区域**：（如有具体位置）
## 当前内容
当前写的是什么？
```
[在这里粘贴当前文本]
```
## 问题说明
哪里有问题？
## 建议改进
应该如何改进或澄清？
```
[在这里提供改进后的文本或建议]
```
## 这样做的重要性
这个问题会怎样影响用户？
## 相关文档
相关章节链接：
- 相关指南：<!-- 在这里添加链接 -->
zh/.github/ISSUE_TEMPLATE/feature_request.md
Vendored
+46
View File
@@ -0,0 +1,46 @@
---
name: Feature Request
about: 建议新增示例、指南或改进
title: "[FEATURE] "
labels: enhancement
assignees: ''
---
## 描述
描述你希望看到的功能或改进。
## 它解决了什么问题
它解决了什么问题或缺口？
示例：
- 没有 X 功能的示例
- Y 功能的现有文档不清楚
- 我们需要 Z 场景的指南
- 结构可以通过以下方式改进……
## 使用场景
这个功能会在什么时候、怎样使用？请包含真实场景。
## 建议方案
应该如何实现或记录？
## 示例
如果适用，请提供你设想的示例：
```
[在这里插入示例]
```
## 相关示例
链接任何已有的相关示例或指南：
- 现有指南：<!-- 在这里添加链接 -->
- 功能：（例如 Skills、Hooks、Subagents）
## 其他上下文
还有哪些可能有帮助的信息？
## 验收标准
怎样才算这个功能完成？
- [ ] 标准 1
- [ ] 标准 2
- [ ] 标准 3
zh/.github/ISSUE_TEMPLATE/question.md
Vendored
+40
View File
@@ -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
- [ ] 其他
## 你尝试过什么
你已经尝试了什么？结果如何？
## 期望结果
什么样的结果能帮助你解决问题？
## 其他资源
还有哪些可能相关的链接或资源？
zh/.github/SECURITY_REPORTING.md
Vendored
+309
View File
@@ -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)
---
感谢你帮助维护项目安全！🔒
zh/.github/TESTING.md
Vendored
+341
View File
@@ -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")
@pytest.mark.asyncio
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。
zh/.github/pull_request_template.md
Vendored
+57
View File
@@ -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 增加的内容：
```
[示例代码或前后对比]
```
## 破坏性变更
这个变更是否影响现有内容或行为？
- [ ] 没有破坏性变更
- [ ] 是，并已在下方说明
如果有，请描述：
## 其他说明
还有哪些信息需要审阅者了解？
zh/01-slash-commands/README.md
+551
View File
@@ -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 指南系列的一部分*
zh/01-slash-commands/commit.md
+26
View File
@@ -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:` 维护任务
zh/01-slash-commands/doc-refactor.md
+24
View File
@@ -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 图）
保持文档简洁、易扫读，并与项目类型保持上下文一致。
zh/01-slash-commands/generate-api-docs.md
+19
View File
@@ -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 类型
zh/01-slash-commands/optimize.md
+19
View File
@@ -0,0 +1,19 @@
---
description: 分析代码中的性能问题并提出优化建议
---
# 代码优化
按优先级审查提供的代码，重点关注以下问题：
1. **性能瓶颈** - 识别 O(n²) 操作和低效循环
2. **内存泄漏** - 查找未释放的资源、循环引用
3. **算法改进** - 建议更好的算法或数据结构
4. **缓存机会** - 识别重复计算
5. **并发问题** - 查找竞态条件或线程问题
请按以下格式输出：
- 问题严重性（Critical/High/Medium/Low）
- 代码位置
- 解释
- 推荐修复方案，附代码示例
zh/01-slash-commands/pr.md
+26
View File
@@ -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 摘要，包含：
- 变更了什么
- 为什么变更
- 做了哪些测试
- 可能的影响
zh/01-slash-commands/push-all.md
+152
View File
@@ -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 命令会更可控。
zh/01-slash-commands/setup-ci-cd.md
+25
View File
@@ -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，确认所有检查都通过
使用免费/开源工具。尊重已有配置。保持执行快速。
zh/01-slash-commands/unit-test-expand.md
+25
View File
@@ -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. **验证提升**：再次运行覆盖率，确认有可衡量的提升
只展示新增的测试代码块。遵循现有测试模式和命名约定。
zh/02-memory/README.md
+305
View File
@@ -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)
zh/02-memory/directory-api-CLAUDE.md
+62
View File
@@ -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 分钟
- 写操作时失效缓存
- 用资源类型给缓存键打标签
zh/02-memory/personal-CLAUDE.md
+61
View File
@@ -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
zh/02-memory/project-CLAUDE.md
+88
View File
@@ -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`
zh/03-skills/README.md
+271
View File
@@ -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)
zh/03-skills/blog-draft/SKILL.md
+274
View File
@@ -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，使用网络搜索获取最新信息
- 如果资源不足，询问用户补充，或建议进一步研究
- 根据目标读者调整语气（技术、通用、商业等）
zh/03-skills/blog-draft/templates/draft-template.md
+67
View File
@@ -0,0 +1,67 @@
# [博客文章标题]
*[副标题或标语 - 可选]*
**[作者名]** | [日期]
---
[开场钩子 - 立即抓住注意力]
[背景与上下文 - 说明为什么这件事重要]
[论点陈述 - 这篇文章要讲什么]
---
## [第一部分标题]
[本部分正文，保持清晰、吸引人的表达]
[加入证据、示例或数据来支撑观点]
> “来自研究的相关引文” - 来源
[过渡到下一部分]
---
## [第二部分标题]
[继续展开正文]
**关键收获：** [用加粗或提示块突出重要观点]
[更多支撑内容]
---
## [第三部分标题]
[如有需要，继续添加更多部分]
### 小节（如果需要）
[小节内容]
---
## 结论
[总结已覆盖的关键点]
[重申核心结论]
[行动号召或发人深省的结尾语]
---
## 参考资料
1. [来源标题](#)
2. [来源标题](#)
3. [来源标题](#)
---
*[作者简介或相关文章推荐 - 可选]*
zh/03-skills/blog-draft/templates/outline-template.md
+97
View File
@@ -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. [来源名称](#) - 用于：[对应信息]
---
## 撰写备注
- [任何特别要求或限制]
- [需要强调的内容]
- [需要避免的内容]
zh/03-skills/brand-voice/SKILL.md
+72
View File
@@ -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 为软件开发提供全面解决方案。”
为什么不好：太空泛、企业黑话太多、没有具体价值
zh/03-skills/brand-voice/tone-examples.md
+13
View File
@@ -0,0 +1,13 @@
# 品牌语气示例
## 激动人心的公告
“每周为代码审查节省 8 小时。Claude 会自动审查你的 PR。”
## 体现同理心的支持
“我们知道发布流程可能很有压力。Claude 会负责测试，你就不用担心了。”
## 自信的产品功能
“Claude 不只是给你代码建议。它理解你的架构，并保持一致性。”
## 教育型博客文章
“让我们一起看看 agents 如何改进代码审查工作流。以下是我们的发现……”
zh/03-skills/claude-md/SKILL.md
+212
View File
@@ -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 应该更聚焦
zh/03-skills/code-review/SKILL.md
+70
View File
@@ -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)：首次发布，包含安全、性能、质量和可维护性分析
zh/03-skills/code-review/templates/finding-template.md
+112
View File
@@ -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 星
zh/03-skills/code-review/templates/review-checklist.md
+47
View File
@@ -0,0 +1,47 @@
# 代码审查检查清单
## 安全检查
- [ ] 没有硬编码的凭据或密钥
- [ ] 所有用户输入都做了校验
- [ ] 使用参数化查询，防止 SQL 注入
- [ ] 所有会修改状态的操作都有 CSRF 防护
- [ ] 使用正确的转义，防止 XSS
- [ ] 受保护的端点有身份验证检查
- [ ] 资源访问有授权检查
- [ ] 密码使用安全哈希算法（bcrypt、argon2）
- [ ] 日志中没有敏感数据
- [ ] 强制使用 HTTPS
## 性能检查
- [ ] 没有 N+1 查询
- [ ] 索引使用合理
- [ ] 在有价值的地方做了缓存
- [ ] 主线程上没有阻塞操作
- [ ] 正确使用 async/await
- [ ] 大数据集已经分页
- [ ] 数据库连接已做连接池
- [ ] 正则表达式已优化
- [ ] 没有不必要的对象创建
- [ ] 没有内存泄漏
## 质量检查
- [ ] 函数少于 50 行
- [ ] 变量命名清晰
- [ ] 没有重复代码
- [ ] 错误处理合理
- [ ] 注释解释的是 WHY，而不是 WHAT
- [ ] 生产环境中没有 console.log
- [ ] 有类型检查（TypeScript / JSDoc）
- [ ] 遵循 SOLID 原则
- [ ] 正确应用设计模式
- [ ] 代码具备自解释性
## 测试检查
- [ ] 已编写单元测试
- [ ] 覆盖了边界情况
- [ ] 测试了错误场景
- [ ] 有集成测试
- [ ] 覆盖率大于 80%
- [ ] 没有不稳定测试
- [ ] 外部依赖已做 mock
- [ ] 测试名称清晰
zh/03-skills/doc-generator/SKILL.md
+76
View File
@@ -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": "john@example.com",
"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()
```
```
zh/03-skills/refactor/SKILL.md
+426
View File
@@ -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 方法论、分阶段流程和用户确认点
zh/03-skills/refactor/references/code-smells.md
+669
View File
@@ -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: 'john@example.com', // 只是字符串
phone: '1234567890', // 只是字符串
status: 'active', // 魔法字符串
balance: 10050 // 以分为单位的整数
};
```
**示例（重构后）：**
```javascript
const user = {
email: new Email('john@example.com'),
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*
zh/03-skills/refactor/references/refactoring-catalog.md
+1023
View File
File diff suppressed because it is too large Load Diff
zh/03-skills/refactor/templates/refactoring-plan.md
+284
View File
@@ -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 工具]
- [复杂度分析工具]
zh/04-subagents/README.md
+380
View File
@@ -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)
zh/04-subagents/clean-code-reviewer.md
+66
View File
@@ -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 倍。优化可读性，而不是炫技。
zh/04-subagents/code-reviewer.md
+61
View File
@@ -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**: 响应时间会随着数据量线性增长
zh/04-subagents/data-scientist.md
+97
View File
@@ -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;
```
## 分析检查清单
- [ ] 已理解需求
- [ ] 查询已优化
- [ ] 结果已验证
- [ ] 发现已记录
- [ ] 建议已提供
zh/04-subagents/debugger.md
+80
View File
@@ -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"
```
## 排查检查清单
- [ ] 已捕获错误信息
- [ ] 已分析堆栈追踪
- [ ] 已检查最近变更
- [ ] 已定位根因
- [ ] 已实现修复
- [ ] 测试通过
- [ ] 未引入回归
zh/04-subagents/documentation-writer.md
+98
View File
@@ -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": "john@example.com"
}
```
### 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>"
```
```
zh/04-subagents/implementation-agent.md
+78
View File
@@ -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 错误
- [ ] 已处理边界情况
- [ ] 已实现错误处理
zh/04-subagents/secure-reviewer.md
+75
View File
@@ -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**: 如何修复
zh/04-subagents/test-engineer.md
+74
View File
@@ -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
});
});
```
zh/05-mcp/README.md
+342
View File
@@ -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)
zh/06-hooks/README.md
+98
View File
@@ -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)
zh/07-plugins/README.md
+930
View File
@@ -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)
zh/07-plugins/devops-automation/README.md
+114
View File
@@ -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
```
zh/07-plugins/devops-automation/agents/alert-analyzer.md
+14
View File
@@ -0,0 +1,14 @@
---
name: alert-analyzer
description: 分析监控告警和系统指标
tools: read, grep, bash
---
# 告警分析器
分析系统健康状况和告警：
- 告警关联分析
- 趋势分析
- 根因识别
- 指标可视化
- 主动问题检测
zh/07-plugins/devops-automation/agents/deployment-specialist.md
+14
View File
@@ -0,0 +1,14 @@
---
name: deployment-specialist
description: 处理所有部署操作
tools: read, write, bash, grep
---
# 部署专家
部署运维专家：
- 蓝绿部署
- 金丝雀发布
- 回滚流程
- 健康检查
- 数据库迁移
zh/07-plugins/devops-automation/agents/incident-commander.md
+14
View File
@@ -0,0 +1,14 @@
---
name: incident-commander
description: 协调事故响应
tools: read, write, bash, grep
---
# 事故指挥官
管理事故响应：
- 严重性评估
- 团队协调
- 状态更新
- 解决跟踪
- 事后复盘推动
zh/07-plugins/devops-automation/commands/deploy.md
+15
View File
@@ -0,0 +1,15 @@
---
name: Deploy
description: 将应用部署到生产或预发环境
---
# 应用部署
执行部署工作流：
1. 运行部署前检查
2. 构建应用
3. 运行测试
4. 部署到目标环境
5. 运行健康检查
6. 在 Slack 上通知团队
zh/07-plugins/devops-automation/commands/incident.md
+16
View File
@@ -0,0 +1,16 @@
---
name: Incident Response
description: 使用结构化响应流程处理生产事故
---
# 事故响应
结构化事故响应工作流：
1. 创建事故记录
2. 评估严重性和影响
3. 通知值班团队
4. 收集诊断信息
5. 协调响应工作
6. 记录解决方案
7. 安排事后复盘
zh/07-plugins/devops-automation/commands/rollback.md
+14
View File
@@ -0,0 +1,14 @@
---
name: Rollback
description: 回滚到上一次部署
---
# 回滚部署
回滚到之前的稳定版本：
1. 确认上一次部署
2. 验证回滚目标健康状态
3. 执行回滚流程
4. 运行健康检查
5. 通知团队
zh/07-plugins/devops-automation/commands/status.md
+15
View File
@@ -0,0 +1,15 @@
---
name: System Status
description: 检查整体系统健康状况
---
# 系统状态检查
检查所有服务的系统健康状况：
1. 查询 Kubernetes pod 状态
2. 检查数据库连接
3. 监控 API 响应时间
4. 查看错误率
5. 检查资源利用率
6. 报告整体健康状况
zh/07-plugins/documentation/README.md
+127
View File
@@ -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"
```
## 最佳实践
- 文档尽量贴近代码
- 随着代码变化同步更新文档
- 提供可直接执行的示例
- 定期校验文档有效性
- 使用模板保持一致性
zh/07-plugins/documentation/agents/api-documenter.md
+14
View File
@@ -0,0 +1,14 @@
---
name: api-documenter
description: API 文档专家
tools: read, write, grep
---
# API 文档专家
创建全面的 API 文档：
- 端点文档
- 参数说明
- 响应 schema
- 代码示例（curl、JavaScript、Python）
- 错误代码
zh/07-plugins/documentation/agents/code-commentator.md
+14
View File
@@ -0,0 +1,14 @@
---
name: code-commentator
description: 代码注释与内联文档专家
tools: read, write, edit
---
# 代码注释专家
改进代码文档：
- JSDoc / docstring 注释
- 内联说明
- 参数说明
- 返回类型文档
- 使用示例
zh/07-plugins/documentation/agents/example-generator.md
+14
View File
@@ -0,0 +1,14 @@
---
name: example-generator
description: 代码示例与教程专家
tools: read, write
---
# 示例生成专家
创建实用的代码示例：
- 入门指南
- 常见用例
- 集成示例
- 最佳实践
- 故障排查场景
zh/07-plugins/documentation/commands/generate-api-docs.md
+15
View File
@@ -0,0 +1,15 @@
---
name: 生成 API 文档
description: 从源代码生成完整的 API 文档
---
# API 文档生成器
生成完整的 API 文档：
1. 扫描 API 端点
2. 提取函数签名和 JSDoc
3. 按模块 / 端点组织内容
4. 创建带示例的 Markdown
5. 包含请求 / 响应 schema
6. 添加错误文档
zh/07-plugins/documentation/commands/generate-readme.md
+15
View File
@@ -0,0 +1,15 @@
---
name: 生成 README
description: 创建或更新项目 README
---
# README 生成器
生成完整的 README：
1. 项目概览与简介
2. 安装说明
3. 使用示例
4. API 文档链接
5. 贡献指南
6. 许可证信息
zh/07-plugins/documentation/commands/sync-docs.md
+14
View File
@@ -0,0 +1,14 @@
---
name: 同步文档
description: 将文档与代码变更保持同步
---
# 文档同步
同步文档与代码库：
1. 检测代码变更
2. 找出过时文档
3. 更新受影响的文档
4. 验证示例是否仍然可用
5. 更新版本号
zh/07-plugins/documentation/commands/validate-docs.md
+14
View File
@@ -0,0 +1,14 @@
---
name: 校验文档
description: 校验文档的完整性与准确性
---
# 文档校验
校验文档质量：
1. 检查是否有损坏链接
2. 验证代码示例
3. 确保内容完整
4. 检查格式
5. 对照实际代码进行校验
zh/07-plugins/documentation/templates/adr-template.md
+39
View File
@@ -0,0 +1,39 @@
# ADR [编号]：[标题]
## 状态
[提议中 | 已接受 | 已弃用 | 已被替代]
## 背景
我们正在看到的是什么问题，促使我们做出这个决策或变更？
## 决策
我们提出和/或正在执行的变更是什么？
## 影响
由于这项变更，哪些事情变得更容易或更困难？
### 正面影响
- 收益 1
- 收益 2
### 负面影响
- 代价 1
- 代价 2
### 中性影响
- 参考事项 1
- 参考事项 2
## 备选方案
还考虑过哪些其他选项，以及为什么没有选择它们？
### 备选方案 1
描述以及未选择的原因。
### 备选方案 2
描述以及未选择的原因。
## 参考资料
- 相关 ADR
- 外部文档
- 讨论链接
zh/07-plugins/documentation/templates/api-endpoint.md
+101
View File
@@ -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](#)
zh/07-plugins/documentation/templates/function-docs.md
+50
View File
@@ -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 文档](#)
zh/07-plugins/pr-review/README.md
+96
View File
@@ -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%+
✅ 性能：没有明显影响
📝 建议：为边界情况添加测试
```
zh/07-plugins/pr-review/agents/performance-analyzer.md
+13
View File
@@ -0,0 +1,13 @@
---
name: performance-analyzer
description: 性能影响分析
tools: read, grep, bash
---
# 性能分析器
评估变更对性能的影响：
- 算法复杂度
- 数据库查询效率
- 内存使用
- 缓存机会
zh/07-plugins/pr-review/agents/security-reviewer.md
+13
View File
@@ -0,0 +1,13 @@
---
name: security-reviewer
description: 面向安全的代码审查
tools: read, grep, diff
---
# 安全审查员
专注于发现安全漏洞：
- 身份验证/授权问题
- 数据暴露
- 注入攻击
- 安全配置
zh/07-plugins/pr-review/agents/test-checker.md
+13
View File
@@ -0,0 +1,13 @@
---
name: test-checker
description: 测试覆盖率与质量分析
tools: read, bash, grep
---
# 测试检查器
分析测试覆盖率和质量：
- 覆盖率百分比
- 缺失的测试用例
- 测试质量评估
- 边界情况识别
zh/07-plugins/pr-review/commands/check-security.md
+14
View File
@@ -0,0 +1,14 @@
---
name: Security Check
description: 运行安全导向的代码审查
---
# 安全检查
对代码变更执行聚焦式安全分析：
1. 身份验证/授权检查
2. 数据暴露风险
3. 注入漏洞
4. 密码学弱点
5. 日志中的敏感数据
zh/07-plugins/pr-review/commands/check-tests.md
+14
View File
@@ -0,0 +1,14 @@
---
name: Test Coverage Check
description: 验证测试覆盖率和质量
---
# 测试覆盖检查
分析测试覆盖率和质量：
1. 检查测试覆盖率百分比
2. 识别未测试的代码路径
3. 审查测试质量
4. 建议缺失的测试用例
5. 确认边界情况已覆盖
zh/07-plugins/pr-review/commands/review-pr.md
+14
View File
@@ -0,0 +1,14 @@
---
name: Review PR
description: 启动包含安全与测试检查的完整 PR 审查
---
# PR 审查
这个命令会发起一次完整的 Pull Request 审查，包括：
1. 安全分析
2. 测试覆盖率验证
3. 文档更新
4. 代码质量检查
5. 性能影响评估
zh/08-checkpoints/README.md
+292
View File
@@ -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 的价值在于让你敢于试错。它让“先试再说”和“试错后立刻回退”变得安全，从而帮你更快找到正确方案。
zh/08-checkpoints/checkpoint-examples.md
+339
View File
@@ -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. **长会话要及时总结**：用“从这里开始总结”来保持对话可管理。
zh/09-advanced-features/README.md
+954
View File
@@ -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)
zh/09-advanced-features/planning-mode-examples.md
+533
View File
@@ -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. **为每个阶段安排测试**
zh/10-cli/README.md
+640
View File
@@ -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 user@example.com` |
| `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)
zh/CATALOG.md
+517
View File
@@ -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。
zh/CHANGELOG.md
+109
View File
@@ -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
zh/CODE_OF_CONDUCT.md
+216
View File
@@ -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 月）- 初始行为准则
---
**感谢你帮助我们打造一个热情、包容且互相尊重的社区！** 🌟
zh/CONTRIBUTING.md
+378
View File
@@ -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 讨论
感谢你的贡献！
zh/INDEX.md
+900
View File
@@ -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+ 个场景
**可直接使用**：所有示例
zh/LEARNING-ROADMAP.md
+725
View File
@@ -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)
zh/QUICK_REFERENCE.md
+506
View File
@@ -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`
**这张卡片**：建议随手保留，方便快速查阅！
zh/README.md
+881
View File
@@ -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
zh/RELEASE_NOTES.md
+8
View File
@@ -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
zh/SECURITY.md
+334
View File
@@ -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 保持安全！🔒
zh/STYLE_GUIDE.md
+630
View File
@@ -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 格式
zh/claude_concepts_guide.md
+1540
View File
File diff suppressed because it is too large Load Diff
zh/clean-code-rules.md
+108
View File
@@ -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 倍。优化可读性和可维护性，而不是追求花哨。
zh/docs/ROADMAP-20260401.md
+153
View File
@@ -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
- 多语言翻译
- 测验 / 评估基础设施
- 社区项目投票
zh/docs/TASKS-20260401.md
+291
View File
@@ -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 月 | 持续进行 |
zh/prompts/remotion-video.md
+350
View File
@@ -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. 交付可直接使用的生产级代码和渲染说明
让我们一起做出一个很棒的作品！
zh/resources.md
+248
View File
@@ -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) |
zh/resources/DESIGN-SYSTEM.md
+244
View File
@@ -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
zh/resources/QUICK-START.md
+89
View File
@@ -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)。
zh/resources/README.md
+266
View File
@@ -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 无障碍标准
zh/scripts/README.md
+69
View File
@@ -0,0 +1,69 @@
# EPUB 构建脚本
## 功能
这个脚本会把整份指南构建成 EPUB 电子书，方便离线阅读。
## 需求
- Python 环境
- `uv`
- 相关依赖
## 快速开始
最简单的方式是直接让 `uv` 帮你处理依赖：
```bash
uv run scripts/build_epub.py
```
## 开发环境
如果你要修改脚本本身，可以先创建虚拟环境，再安装开发依赖。
```bash
# 创建虚拟环境
# 激活并安装依赖
# 运行测试
# 运行脚本
```
## 命令行选项
常见选项包括：
- 指定输出路径
- 打开详细日志
- 限制并发请求
## 示例
```bash
# 带详细输出构建
# 指定输出位置
# 限制并发数（遇到限流时）
```
## 输出
脚本会生成 EPUB 文件，里面包含所有内容和渲染后的图表。
## 运行测试
你可以用虚拟环境或直接通过 `uv` 运行测试。
## 依赖
脚本依赖的包会在项目的开发依赖里列出。
## 故障排查
- 检查 `uv` 是否可用
- 检查 Python 版本
- 检查依赖是否安装完整