A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
feat(zh): add Chinese translations in zh/ directory
Luong NGUYEN89e89d4aa38c
diff --git a/scripts/check_cross_references.py b/scripts/check_cross_references.pyindex 0d9539c..7dd28c3 100644--- a/scripts/check_cross_references.py+++ b/scripts/check_cross_references.py@@ -3,6 +3,7 @@import reimport sys+import unicodedatafrom pathlib import PathIGNORE_DIRS = {@@ -63,7 +64,7 @@ def main() -> int:errors = []for file_path in iter_md_files():- content = file_path.read_text()+ content = file_path.read_text(encoding="utf-8")# Strip code blocks before scanning for links/anchors to avoid false positives# from documentation examples inside code fences.scannable = strip_code_blocks(content)diff --git a/zh/.github/ISSUE_TEMPLATE/bug_report.md b/zh/.github/ISSUE_TEMPLATE/bug_report.mdnew file mode 100644index 0000000..bda438d--- /dev/null+++ b/zh/.github/ISSUE_TEMPLATE/bug_report.md@@ -0,0 +1,43 @@+---+name: Bug Report+about: 报告示例、指南或文档中的问题+title: "[BUG] "+labels: bug+assignees: ''++---++## 问题描述+简要说明问题。++## 复现步骤+1. 第 1 步+2. 第 2 步+3. 第 3 步++## 预期行为+应该发生什么?++## 实际行为+实际发生了什么?++## 环境+- **Claude Code 版本**:(例如 1.0.5)+- **操作系统**:(例如 macOS 14.1、Ubuntu 22.04、Windows 11)+- **Python 版本**:(如有相关,例如 3.11)+- **受影响的组件**:(例如 01-slash-commands、03-skills 等)++## 示例代码+如果适用,请提供无法正常工作的示例代码:+```+[在这里插入代码]+```++## 截图+如果适用,请附上显示问题的截图。++## 其他上下文+还有哪些信息可能有助于我们理解这个问题?++## 可能的解决方案+如果你有修复建议,也可以写在这里。diff --git a/zh/.github/ISSUE_TEMPLATE/documentation.md b/zh/.github/ISSUE_TEMPLATE/documentation.mdnew file mode 100644index 0000000..b53cec1--- /dev/null+++ b/zh/.github/ISSUE_TEMPLATE/documentation.md@@ -0,0 +1,44 @@+---+name: Documentation Issue+about: 报告文档中的不清晰、错别字或缺失信息+title: "[DOCS] "+labels: documentation+assignees: ''++---++## 问题类型+- [ ] 拼写或语法错误+- [ ] 解释不清+- [ ] 缺少信息+- [ ] 链接或引用损坏+- [ ] 内容过时+- [ ] 需要更好的示例++## 位置+哪一部分有问题?+- **文件**:(例如 README.md、03-skills/README.md)+- **章节**:(例如 "Installation Quick Reference")+- **行号/区域**:(如有具体位置)++## 当前内容+当前写的是什么?+```+[在这里粘贴当前文本]+```++## 问题说明+哪里有问题?++## 建议改进+应该如何改进或澄清?+```+[在这里提供改进后的文本或建议]+```++## 这样做的重要性+这个问题会怎样影响用户?++## 相关文档+相关章节链接:+- 相关指南:<!-- 在这里添加链接 -->diff --git a/zh/.github/ISSUE_TEMPLATE/feature_request.md b/zh/.github/ISSUE_TEMPLATE/feature_request.mdnew file mode 100644index 0000000..7a328d7--- /dev/null+++ b/zh/.github/ISSUE_TEMPLATE/feature_request.md@@ -0,0 +1,46 @@+---+name: Feature Request+about: 建议新增示例、指南或改进+title: "[FEATURE] "+labels: enhancement+assignees: ''++---++## 描述+描述你希望看到的功能或改进。++## 它解决了什么问题+它解决了什么问题或缺口?++示例:+- 没有 X 功能的示例+- Y 功能的现有文档不清楚+- 我们需要 Z 场景的指南+- 结构可以通过以下方式改进……++## 使用场景+这个功能会在什么时候、怎样使用?请包含真实场景。++## 建议方案+应该如何实现或记录?++## 示例+如果适用,请提供你设想的示例:+```+[在这里插入示例]+```++## 相关示例+链接任何已有的相关示例或指南:+- 现有指南:<!-- 在这里添加链接 -->+- 功能:(例如 Skills、Hooks、Subagents)++## 其他上下文+还有哪些可能有帮助的信息?++## 验收标准+怎样才算这个功能完成?+- [ ] 标准 1+- [ ] 标准 2+- [ ] 标准 3diff --git a/zh/.github/ISSUE_TEMPLATE/question.md b/zh/.github/ISSUE_TEMPLATE/question.mdnew file mode 100644index 0000000..954585c--- /dev/null+++ b/zh/.github/ISSUE_TEMPLATE/question.md@@ -0,0 +1,40 @@+---+name: Question+about: 提出关于 Claude Code 或本指南的问题+title: "[QUESTION] "+labels: question+assignees: ''++---++## 问题+你想了解什么?++## 背景+请提供一些背景或上下文:+- 你想做什么?+- 你已经尝试过什么?+- 你看过哪些示例或指南?++## 相关主题+这个问题属于哪个主题?+- [ ] Slash Commands+- [ ] Memory+- [ ] Skills+- [ ] Subagents+- [ ] MCP Protocol+- [ ] Hooks+- [ ] Plugins+- [ ] Checkpoints+- [ ] Advanced Features+- [ ] CLI Reference+- [ ] 其他++## 你尝试过什么+你已经尝试了什么?结果如何?++## 期望结果+什么样的结果能帮助你解决问题?++## 其他资源+还有哪些可能相关的链接或资源?diff --git a/zh/.github/SECURITY_REPORTING.md b/zh/.github/SECURITY_REPORTING.mdnew file mode 100644index 0000000..3b8b84a--- /dev/null+++ b/zh/.github/SECURITY_REPORTING.md@@ -0,0 +1,309 @@+# 安全漏洞报告++本文说明如何向 Claude How To 项目报告安全漏洞。++## 快速链接++- **私密报告**:<https://github.com/luongnv89/claude-howto/security/advisories>+- **安全政策**:[SECURITY.md](../SECURITY.md)+- **报告模板**:见下文++## 报告漏洞++### 选项 1:GitHub 私密漏洞报告(推荐)++这是报告安全漏洞的首选方式。++**步骤:**+1. 访问:<https://github.com/luongnv89/claude-howto/security/advisories>+2. 点击 “Report a vulnerability”+3. 填写详情(可使用下方模板)+4. 提交++**优点:**+- 在修复发布前保持漏洞私密+- 自动通知维护者+- 内置协作功能+- 与 GitHub 安全工具集成++### 选项 2:GitHub 安全警报(依赖漏洞)++如果你在依赖中发现漏洞:++1. 访问:<https://github.com/luongnv89/claude-howto/security/advisories>+2. 查看警报+3. 提交包含修复的 pull request+4. 加上 `security` 标签++### 选项 3:私密邮箱(GitHub 不可用时)++如果你无法使用 GitHub 的报告系统:++**即将提供**:这里会补充安全联系邮箱++目前请优先使用上面的 GitHub 私密漏洞报告。++## 漏洞报告模板++报告漏洞时可使用以下模板:++```+**标题**:[漏洞简述]++**严重性**:[Critical/High/Medium/Low]+Estimated CVSS Score: [0-10]++**类型**:[代码/文档/依赖/配置]++**受影响组件**:+- File: [path/to/file.py]+- Section: [文档章节名,如适用]+- Version: [latest/具体版本]++**描述**:+[对漏洞的清晰说明]++**潜在影响**:+[攻击者可以利用该漏洞做什么?]+[可能影响哪些人?]++**复现步骤**:+1. [第一步]+2. [第二步]+3. [第三步]+[预期结果与实际结果]++**PoC**(如有):+[用于演示漏洞的代码或步骤]++**建议修复**:+[你的建议方案,如有]++**附加上下文**:+[任何其他相关信息]++**你的信息**:+- Name: [你的名字或匿名]+- Email: [你的邮箱]+- Credit: [你希望如何署名,如有]+```++## 提交后会发生什么++### 时间线++1. **立刻(< 1 小时)**+ - 自动通知会发送给项目维护者++2. **24 小时内**+ - 对报告进行初步评估+ - 确认已收到+ - 初步严重性评估++3. **48 小时内**+ - 安全团队给出详细回复+ - 如需更多信息会继续询问+ - 如果确认漏洞存在,会给出修复时间线++4. **1-7 天内**(取决于严重性)+ - 完成修复并测试+ - 准备安全公告+ - 发布修复并公开公告++### 沟通方式++我们会通过以下方式与你保持沟通:+- GitHub 私密漏洞讨论+- 邮件(如果你提供了)+- 讨论线程中的更新++你可以:+- 提出澄清问题+- 补充更多信息+- 建议改进修复方案+- 请求调整时间线++### 披露时间线++**严重问题(CVSS 9.0-10.0)**+- 修复:立即发布(24 小时内)+- 披露:当天发布公开公告+- 通知:提前 24 小时通知报告者++**高危问题(CVSS 7.0-8.9)**+- 修复:48-72 小时内发布+- 披露:发布时公开公告+- 通知:提前 5 天通知报告者++**中危问题(CVSS 4.0-6.9)**+- 修复:纳入下一次常规更新+- 披露:发布时公开公告+- 通知:协调时间线++**低危问题(CVSS 0.1-3.9)**+- 修复:纳入下一次常规更新+- 披露:发布时公告+- 通知:与发布同日++## 安全漏洞标准++### 范围内++我们接受以下类型的报告:++- **代码漏洞**+ - 注入攻击(命令、SQL 等)+ - 示例中的跨站脚本(XSS)+ - 认证/授权缺陷+ - 路径穿越漏洞+ - 密码学问题++- **文档安全**+ - 暴露的秘密或凭据+ - 不安全代码模式+ - 安全反模式+ - 误导性的安全声明++- **依赖漏洞**+ - 依赖中的已知 CVE+ - 供应链攻击+ - 恶意依赖++- **配置问题**+ - 不安全默认值+ - 缺失安全头+ - 示例中的凭据暴露++### 范围外++以下内容不接受报告:++- Claude Code 本身的漏洞(请联系 Anthropic)+- 外部服务中的漏洞+- 没有证明的理论漏洞+- 已向上游项目报告的问题+- 社会工程学或钓鱼+- 用户教育 / 培训问题++## 负责任披露指南++### 应该做的 ✅++- **先私下报告**,再公开披露+- **尽量具体**,提供文件路径和行号+- **提供证明**,说明漏洞确实存在+- **给我们时间**修复(协调披露)+- **补充更新**,如果你发现了更多细节+- **保持专业**,在所有沟通中都如此+- **尊重保密性**,直到我们公开发布++### 不应该做的 ❌++- **不要在修复前公开披露**+- **不要超出测试所需范围去利用漏洞**+- **不要修改**其他用户的数据+- **不要索要**报酬或好处+- **不要把漏洞**分享给其他人+- **不要用于**任何有害用途+- **不要用**非安全相关 issue 刷屏++## 协调披露++我们遵循负责任披露流程:++1. **私密报告**:你先私下告诉我们+2. **我们评估**:判断并评估严重性+3. **开发修复**:我们开发并测试修复+4. **提前通知**:在公开披露前提前通知你+5. **公开发布**:我们同时发布修复和公告+6. **你的署名**:如你愿意,会在公告中致谢++**具体时间会根据严重性变化**(见上文)++## 修复发布后++### 公开公告++公开安全公告通常包含:+- 漏洞描述+- 受影响版本+- 严重性(CVSS 分数)+- 修复步骤+- 修复链接+- 对报告者的致谢(如获许可)++### 你的署名++如果你希望被致谢:+- 公告中会写上你的名字/昵称+- 可附上你的个人资料或网站链接+- 在发布说明中致谢+- 如果未来建立名人堂,也可能加入++### 不提供金钱补偿++请注意:+- 这是一个志愿者维护的开源项目+- 我们无法提供金钱奖励+- 但会提供认可和署名+- 你的贡献会帮助整个社区++## 安全研究++如果你在做安全研究:++1. **先取得许可**:先联系维护者+2. **明确范围**:约定你会测试什么+3. **报告发现**:使用本流程+4. **尊重时间线**:给我们时间修复+5. **负责任地发布**:与我们协调++## 有问题?++如果你对这个流程有疑问:++1. 查看 [SECURITY.md](../SECURITY.md) 的完整政策+2. 查看下方的 [FAQ](#faq)+3. 使用 `[SECURITY]` 标签发起 discussion+4. 对敏感问题使用私密漏洞报告++## FAQ++**Q: 我的报告会保密吗?**+A: 会,直到修复发布。我们只会与参与修复的人共享细节。++**Q: 我需要等多久才能公开披露?**+A: 我们会按照严重性遵循负责任披露时间线(24 小时到 7 天)。如有需要,你可以同意延长。++**Q: 我会获得署名吗?**+A: 会,会出现在安全公告和发布说明中(除非你希望匿名)。++**Q: 如果漏洞很小怎么办?**+A: 所有真实的安全问题都会被认真对待,即使很小也会被记录和致谢。++**Q: 我可以只报告文档里的漏洞吗?**+A: 可以。文档安全同样重要。不安全示例也在范围内。++**Q: 如果我不确定这是不是安全问题呢?**+A: 先报告即可!如果不是安全问题,我们会告诉你。误报没关系。++**Q: 报告后我可以公开讨论吗?**+A: 不可以,请在我们公开公告前保持私密。过早披露可能让用户面临风险。++**Q: 我怎么知道你收到了我的报告?**+A: GitHub 会发送自动通知,我们会在 24 小时内跟进。++**Q: 如果我一直没收到回复怎么办?**+A: 检查 GitHub security advisories 页面。如果仍看不到回复,可以在私密报告里继续留言跟进。++## 资源++- [SECURITY.md](../SECURITY.md) - 完整安全政策+- [CONTRIBUTING.md](../CONTRIBUTING.md) - 贡献指南+- [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) - 社区标准+- [OWASP Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html) - 负责任披露最佳实践+- [Coordinated Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerable_Dependency_Management_Cheat_Sheet.html)++---++感谢你帮助维护项目安全!🔒diff --git a/zh/.github/TESTING.md b/zh/.github/TESTING.mdnew file mode 100644index 0000000..22612a6--- /dev/null+++ b/zh/.github/TESTING.md@@ -0,0 +1,341 @@+# 测试指南++本文档说明 Claude How To 的测试基础设施。++## 概览++项目使用 GitHub Actions 在每次 push 和 pull request 时自动运行测试。测试覆盖:++- **单元测试**:使用 pytest 的 Python 测试+- **代码质量**:使用 Ruff 做 lint 和格式化+- **安全**:使用 Bandit 做漏洞扫描+- **类型检查**:使用 mypy 做静态类型分析+- **构建验证**:EPUB 生成测试++## 在本地运行测试++### 前置条件++```bash+# 安装 uv(快速 Python 包管理器)+pip install uv++# 或者在 macOS 上使用 Homebrew+brew install uv+```++### 配置环境++```bash+# 克隆仓库+git clone https://github.com/luongnv89/claude-howto.git+cd claude-howto++# 创建虚拟环境+uv venv++# 激活虚拟环境+source .venv/bin/activate # macOS/Linux+# 或者+.venv\Scripts\activate # Windows++# 安装开发依赖+uv pip install -r requirements-dev.txt+```++### 运行测试++```bash+# 运行所有单元测试+pytest scripts/tests/ -v++# 运行带覆盖率的测试+pytest scripts/tests/ -v --cov=scripts --cov-report=html++# 运行指定测试文件+pytest scripts/tests/test_build_epub.py -v++# 运行指定测试函数+pytest scripts/tests/test_build_epub.py::test_function_name -v++# 以 watch 模式运行测试(需要 pytest-watch)+ptw scripts/tests/+```++### 运行 lint++```bash+# 检查代码格式+ruff format --check scripts/++# 自动修复格式问题+ruff format scripts/++# 运行 lint+ruff check scripts/++# 自动修复 lint 问题+ruff check --fix scripts/+```++### 运行安全扫描++```bash+# 运行 Bandit 安全扫描+bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/++# 生成 JSON 报告+bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ -f json -o bandit-report.json+```++### 运行类型检查++```bash+# 使用 mypy 检查类型+mypy scripts/ --ignore-missing-imports --no-implicit-optional+```++## GitHub Actions 工作流++### 触发条件++- 推送到 `main` 或 `develop` 分支(当 `scripts` 有变更时)+- 向 `main` 提交 Pull Request(当 `scripts` 有变更时)+- 手动触发 workflow++### 作业++#### 1. 单元测试(pytest)++- **运行环境**:Ubuntu latest+- **Python 版本**:3.10、3.11、3.12+- **执行内容**:+ - 从 `requirements-dev.txt` 安装依赖+ - 运行 pytest 并生成覆盖率报告+ - 将覆盖率上传到 Codecov+ - 归档测试结果和 HTML 覆盖率报告++**结果**:如果任何测试失败,工作流失败(关键)++#### 2. 代码质量(Ruff)++- **运行环境**:Ubuntu latest+- **Python 版本**:3.11+- **执行内容**:+ - 使用 `ruff format` 检查格式+ - 使用 `ruff check` 运行 lint+ - 报告问题,但不会让整个工作流失败++**结果**:非阻塞(仅警告)++#### 3. 安全扫描(Bandit)++- **运行环境**:Ubuntu latest+- **Python 版本**:3.11+- **执行内容**:+ - 扫描安全漏洞+ - 生成 JSON 报告+ - 将报告作为 artifact 上传++**结果**:非阻塞(仅警告)++#### 4. 类型检查(mypy)++- **运行环境**:Ubuntu latest+- **Python 版本**:3.11+- **执行内容**:+ - 执行静态类型分析+ - 报告类型不匹配+ - 帮助尽早发现 bug++**结果**:非阻塞(仅警告)++#### 5. 构建 EPUB++- **运行环境**:Ubuntu latest+- **依赖**:pytest、lint、安全扫描(都必须通过)+- **执行内容**:+ - 使用 `scripts/build_epub.py` 构建 EPUB+ - 验证 EPUB 是否成功生成+ - 将 EPUB 作为 artifact 上传++**结果**:如果构建失败,工作流失败(关键)++#### 6. 总结++- **运行环境**:Ubuntu latest+- **依赖**:所有其他作业+- **执行内容**:+ - 生成工作流总结+ - 列出所有 artifacts+ - 汇总总体状态++## 编写测试++### 测试结构++测试应放在 `scripts/tests/` 中,文件名形如 `test_*.py`:++```python+# scripts/tests/test_example.py+import pytest+from scripts.example_module import some_function++def test_basic_functionality():+ """测试 some_function 是否正常工作。"""+ result = some_function("input")+ assert result == "expected_output"++def test_error_handling():+ """测试 some_function 是否能优雅处理错误。"""+ with pytest.raises(ValueError):+ some_function("invalid_input")++async def test_async_function():+ """测试异步函数。"""+ result = await async_function()+ assert result is not None+```++### 测试最佳实践++- **使用有描述性的名称**:例如 `test_function_returns_correct_value()`+- **尽量每个测试只做一个断言**:更容易排查失败原因+- **使用 fixture** 复用初始化逻辑:见 `scripts/tests/conftest.py`+- **Mock 外部服务**:使用 `unittest.mock` 或 `pytest-mock`+- **测试边界情况**:空输入、None 值、错误情况+- **保持测试快速**:避免 `sleep()` 和外部 I/O+- **使用 pytest 标记**:例如 `@pytest.mark.slow` 标记慢测试++### Fixtures++常用 fixture 定义在 `scripts/tests/conftest.py`:++```python+# 在测试中使用 fixture+def test_something(tmp_path):+ """tmp_path fixture 提供临时目录。"""+ test_file = tmp_path / "test.txt"+ test_file.write_text("content")+ assert test_file.read_text() == "content"+```++## 覆盖率报告++### 本地覆盖率++```bash+# 生成覆盖率报告+pytest scripts/tests/ --cov=scripts --cov-report=html++# 在浏览器中打开覆盖率报告+open htmlcov/index.html+```++### 覆盖率目标++- **最低覆盖率**:80%+- **分支覆盖率**:启用+- **重点区域**:核心功能和错误路径++## Pre-commit Hooks++项目使用 pre-commit hooks 在每次提交前自动运行检查:++```bash+# 安装 pre-commit hooks+pre-commit install++# 手动运行 hooks+pre-commit run --all-files++# 跳过某次提交的 hooks(不推荐)+git commit --no-verify+```++在 `.pre-commit-config.yaml` 中配置的 hooks:+- Ruff formatter+- Ruff linter+- Bandit security scanner+- YAML validation+- 文件大小检查+- 合并冲突检测++## 排障++### 本地测试通过,但 CI 失败++常见原因:+1. **Python 版本差异**:CI 使用 3.10、3.11、3.12+2. **依赖缺失**:更新 `requirements-dev.txt`+3. **平台差异**:路径分隔符、环境变量+4. **测试不稳定**:依赖时序或执行顺序的测试++解决方案:+```bash+# 使用相同的 Python 版本测试+uv python install 3.10 3.11 3.12++# 使用干净环境测试+rm -rf .venv+uv venv+uv pip install -r requirements-dev.txt+pytest scripts/tests/+```++### Bandit 报告误报++某些安全警告可能是误报。可在 `pyproject.toml` 中配置:++```toml+[tool.bandit]+exclude_dirs = ["scripts/tests"]+skips = ["B101"] # 跳过 assert_used 警告+```++### 类型检查太严格++对特定文件放宽类型检查:++```python+# 放在文件顶部+# type: ignore++# 或者针对特定行+some_dynamic_code() # type: ignore+```++## 持续集成最佳实践++1. **保持测试快速**:每个测试最好在 1 秒内完成+2. **不要测试外部 API**:用 mock 替代外部服务+3. **测试要隔离**:每个测试都应独立+4. **断言要清晰**:写 `assert x == 5`,不要写 `assert x`+5. **处理异步测试**:使用 `@pytest.mark.asyncio`+6. **生成报告**:覆盖率、安全扫描、类型检查++## 资源++- [pytest Documentation](https://docs.pytest.org/)+- [Ruff Documentation](https://docs.astral.sh/ruff/)+- [Bandit Documentation](https://bandit.readthedocs.io/)+- [mypy Documentation](https://mypy.readthedocs.io/)+- [GitHub Actions Documentation](https://docs.github.com/en/actions)++## 贡献测试++提交 PR 时:++1. **为新功能编写测试**+2. **本地运行测试**:`pytest scripts/tests/ -v`+3. **检查覆盖率**:`pytest scripts/tests/ --cov=scripts`+4. **运行 lint**:`ruff check scripts/`+5. **安全扫描**:`bandit -r scripts/ --exclude scripts/tests/`+6. **如果测试变化,更新文档**++所有 PR 都必须包含测试!🧪++---++如果你对测试有问题或疑问,请在 GitHub 上创建 issue 或 discussion。diff --git a/zh/.github/pull_request_template.md b/zh/.github/pull_request_template.mdnew file mode 100644index 0000000..03bf75f--- /dev/null+++ b/zh/.github/pull_request_template.md@@ -0,0 +1,57 @@+## 描述+简要说明这个 PR 做了什么。++## 变更类型+- [ ] 新增示例或模板+- [ ] 文档改进+- [ ] Bug 修复+- [ ] 功能指南+- [ ] 其他(请说明)++## 相关 Issues+Closes #(issue number)++## 已做的修改+- 修改 1+- 修改 2+- 修改 3++## 需要重点查看的内容+审阅者应该重点关注什么?++## 变更文件+- `path/to/file1.md`+- `path/to/file2.md`++## 测试+你如何测试的?+- [ ] 已在 Claude Code 本地测试+- [ ] 已验证示例可用+- [ ] 已检查链接和引用+- [ ] 已检查拼写和清晰度++## 检查清单+- [ ] 符合项目结构和规范+- [ ] 包含清晰的文档 / 示例+- [ ] 代码 / 示例可直接复制使用+- [ ] 所有链接都已验证且可用+- [ ] 没有包含敏感信息(密钥、token、凭证)+- [ ] 已更新相关 README 文件+- [ ] Commit 信息符合 conventional commit 格式+- [ ] 没有添加大文件(>1MB)++## 截图或示例+如有必要,展示这个 PR 增加的内容:+```+[示例代码或前后对比]+```++## 破坏性变更+这个变更是否影响现有内容或行为?+- [ ] 没有破坏性变更+- [ ] 是,并已在下方说明++如果有,请描述:++## 其他说明+还有哪些信息需要审阅者了解?diff --git a/zh/01-slash-commands/README.md b/zh/01-slash-commands/README.mdnew file mode 100644index 0000000..29f4523--- /dev/null+++ b/zh/01-slash-commands/README.md@@ -0,0 +1,551 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# Slash Commands 参考指南++## 概览++Slash command 是你在 Claude 的交互式会话中用来控制行为的快捷方式,主要分为几类:++- **内置命令**:Claude Code 自带,例如 `/help`、`/clear`、`/model`+- **Skills**:你自己定义的命令,基于 `SKILL.md` 文件,例如 `/optimize`、`/pr`+- **插件命令**:来自已安装插件的命令,例如 `/frontend-design:frontend-design`+- **MCP prompts**:来自 MCP server 的命令,例如 `/mcp__github__list_prs`++> **注意**:自定义 slash command 已经合并进 Skills。`.claude/commands/` 仍然可用,但现在更推荐使用 `.claude/skills/`。两者都会创建 `/command-name` 形式的快捷命令。完整参考请见 [Skills 指南](../03-skills/README.md)。++## 内置命令速查++Claude Code 目前提供 55+ 个内置命令和 5 个内置 Skills。你可以在 Claude Code 中输入 `/` 查看全部,也可以输入 `/` 后继续键入字母进行筛选。++| 命令 | 作用 |+|---------|---------|+| `/add-dir <path>` | 添加工作目录 |+| `/agents` | 管理 agent 配置 |+| `/branch [name]` | 将当前对话分支到新会话(别名:`/fork`。注意:`/fork` 在 v2.1.77 中更名为 `/branch`) |+| `/btw <question>` | 额外问题,不写入历史 |+| `/chrome` | 配置 Chrome 浏览器集成 |+| `/clear` | 清空对话(别名:`/reset`、`/new`) |+| `/color [color|default]` | 设置提示栏颜色 |+| `/compact [instructions]` | 压缩对话,可附带聚焦指令 |+| `/config` | 打开设置(别名:`/settings`) |+| `/context` | 用彩色网格可视化上下文占用 |+| `/copy [N]` | 将 assistant 回复复制到剪贴板;`w` 会写入文件 |+| `/cost` | 查看 token 使用统计 |+| `/desktop` | 继续在桌面应用中处理(别名:`/app`) |+| `/diff` | 查看未提交更改的交互式 diff |+| `/doctor` | 检查安装健康状态 |+| `/effort [low|medium|high|max|auto]` | 设置推理强度;`max` 需要 Opus 4.6 |+| `/exit` | 退出 REPL(别名:`/quit`) |+| `/export [filename]` | 将当前对话导出为文件或剪贴板内容 |+| `/extra-usage` | 配置额外用量以应对速率限制 |+| `/fast [on|off]` | 切换快速模式 |+| `/feedback` | 提交反馈(别名:`/bug`) |+| `/help` | 显示帮助 |+| `/hooks` | 查看 hook 配置 |+| `/ide` | 管理 IDE 集成 |+| `/init` | 初始化 `CLAUDE.md`,可设置 `CLAUDE_CODE_NEW_INIT=true` 启用交互式流程 |+| `/insights` | 生成会话分析报告 |+| `/install-github-app` | 配置 GitHub Actions app |+| `/install-slack-app` | 安装 Slack app |+| `/keybindings` | 打开快捷键配置 |+| `/login` | 切换 Anthropic 账号 |+| `/logout` | 退出当前 Anthropic 账号 |+| `/mcp` | 管理 MCP servers 和 OAuth |+| `/memory` | 编辑 `CLAUDE.md`,切换自动记忆 |+| `/mobile` | 生成移动端扫码二维码(别名:`/ios`、`/android`) |+| `/model [model]` | 选择模型,并可用左右箭头调整 effort |+| `/passes` | 分享一周免费 Claude Code 使用权 |+| `/permissions` | 查看或更新权限(别名:`/allowed-tools`) |+| `/plan [description]` | 进入规划模式 |+| `/plugin` | 管理插件 |+| `/pr-comments [PR]` | 获取 GitHub PR 评论 |+| `/privacy-settings` | 隐私设置(仅 Pro/Max) |+| `/release-notes` | 查看更新日志 |+| `/reload-plugins` | 重新加载当前插件 |+| `/remote-control` | 从 claude.ai 进行远程控制(别名:`/rc`) |+| `/remote-env` | 配置默认远程环境 |+| `/rename [name]` | 重命名会话 |+| `/resume [session]` | 恢复对话(别名:`/continue`) |+| `/review` | **已弃用**,请改用 `code-review` 插件 |+| `/rewind` | 回退对话和/或代码(别名:`/checkpoint`) |+| `/sandbox` | 切换沙盒模式 |+| `/schedule [description]` | 创建/管理定时任务 |+| `/security-review` | 分析分支中的安全漏洞 |+| `/skills` | 列出可用 Skills |+| `/stats` | 可视化每日使用量、会话和连续天数 |+| `/status` | 显示版本、模型、账号 |+| `/statusline` | 配置状态栏 |+| `/tasks` | 列出/管理后台任务 |+| `/terminal-setup` | 配置终端快捷键 |+| `/theme` | 更改颜色主题 |+| `/vim` | 切换 Vim/Normal 模式 |+| `/voice` | 切换按住说话语音输入 |++### 内置 Skills++以下 Skills 随 Claude Code 一起提供,调用方式和 slash command 一样:++| Skill | 作用 |+|-------|---------|+| `/batch <instruction>` | 使用 worktree 编排大规模并行修改 |+| `/claude-api` | 加载 Claude API 参考,便于为项目所用语言编写代码 |+| `/debug [description]` | 启用调试日志 |+| `/loop [interval] <prompt>` | 按固定间隔重复运行提示词 |+| `/simplify [focus]` | 审查改动文件的代码质量 |++### 已弃用命令++| 命令 | 状态 |+|---------|--------|+| `/review` | 已弃用,已被 `code-review` 插件替代 |+| `/output-style` | 自 v2.1.73 起弃用 |+| `/fork` | 已重命名为 `/branch`(别名仍可用,v2.1.77) |++### 最近变化++- `/fork` 已更名为 `/branch`,但保留 `/fork` 作为别名(v2.1.77)+- `/output-style` 已弃用(v2.1.73)+- `/review` 已弃用,推荐改用 `code-review` 插件+- 新增 `/effort`,其中 `max` 级别需要 Opus 4.6+- 新增 `/voice`,用于按住说话语音输入+- 新增 `/schedule`,用于创建和管理定时任务+- 新增 `/color`,用于自定义提示栏颜色+- `/model` 选择器现在显示人类可读标签,例如 “Sonnet 4.6”+- `/resume` 支持 `/continue` 别名+- MCP prompts 可作为 `/mcp__<server>__<prompt>` 命令使用,见 [MCP Prompts as Commands](#mcp-prompts-作为命令)++## 自定义命令(现已归入 Skills)++自定义 slash command 已经**合并到 Skills**。两种方式都可以通过 `/command-name` 调用:++| 方式 | 位置 | 状态 |+|----------|----------|--------|+| **Skills(推荐)** | `.claude/skills/<name>/SKILL.md` | 当前标准 |+| **旧式命令** | `.claude/commands/<name>.md` | 仍可使用 |++如果 skill 和 command 同名,**skill 优先**。例如同时存在 `.claude/commands/review.md` 和 `.claude/skills/review/SKILL.md` 时,会使用 skill 版本。++### 迁移路径++你现有的 `.claude/commands/` 文件可以继续直接使用。若要迁移到 Skills:++**迁移前(Command):**+```text+.claude/commands/optimize.md+```++**迁移后(Skill):**+```text+.claude/skills/optimize/SKILL.md+```++### 为什么用 Skills++- **目录结构**:可以把脚本、模板、参考文件打包在一起+- **自动触发**:相关场景下 Claude 可以自动调用+- **调用控制**:可以决定由用户、Claude 或两者共同调用+- **子 agent 执行**:可在隔离上下文中运行 skill+- **渐进披露**:只在需要时加载额外文件++### 把自定义命令做成 Skill++创建一个包含 `SKILL.md` 的目录:++```bash+mkdir -p .claude/skills/my-command+```++**文件:** `.claude/skills/my-command/SKILL.md`++```yaml+---+name: my-command+description: 这个命令的作用,以及何时使用它+---++# 我的命令++当该命令被触发时,Claude 需要遵循的说明。++1. 第一步+2. 第二步+3. 第三步+```++### Frontmatter 参考++| 字段 | 作用 | 默认值 |+|-------|---------|---------|+| `name` | 命令名(会变成 `/name`) | 目录名 |+| `description` | 简短说明,帮助 Claude 判断何时使用 | 第一段 |+| `argument-hint` | 自动补全时显示的参数提示 | 无 |+| `allowed-tools` | 命令可无权限使用的工具 | 继承 |+| `model` | 指定要使用的模型 | 继承 |+| `disable-model-invocation` | 若为 `true`,只有用户能调用,Claude 不能自动调用 | `false` |+| `user-invocable` | 若为 `false`,不会出现在 `/` 菜单中 | `true` |+| `context` | 设为 `fork` 时,在隔离 subagent 中运行 | 无 |+| `agent` | `context: fork` 时使用的 agent 类型 | `general-purpose` |+| `hooks` | Skill 范围内的 hooks(PreToolUse、PostToolUse、Stop) | 无 |++### 参数++命令可以接收参数:++**使用 `$ARGUMENTS` 接收全部参数:**++```yaml+---+name: fix-issue+description: 根据编号修复 GitHub issue+---++按团队编码规范修复 #$ARGUMENTS+```++调用 `/fix-issue 123` 时,`$ARGUMENTS` 会变成 `123`。++**使用 `$0`、`$1` 等接收单个参数:**++```yaml+---+name: review-pr+description: 按优先级审查 PR+---++审查 #$0,优先级为 $1+```++调用 `/review-pr 456 high` 时,`$0="456"`,`$1="high"`。++### 用 Shell 命令注入动态上下文++在 prompt 发送前,可用 `!` 命令先执行 shell 命令:++```yaml+---+name: commit+description: 使用上下文创建 git commit+allowed-tools: Bash(git *)+---++## 上下文++- 当前 git 状态:!`git status`+- 当前 diff:!`git diff HEAD`+- 当前分支:!`git branch --show-current`+- 最近提交:!`git log --oneline -5`++## 你的任务++根据以上变更,创建一个 git commit。+```++### 文件引用++使用 `@` 引用文件内容:++```markdown+审查 @src/utils/helpers.js 中的实现+比较 @src/old-version.js 和 @src/new-version.js+```++## 插件命令++插件可以提供自定义命令:++```text+/plugin-name:command-name+```++如果没有命名冲突,也可以直接使用 `/command-name`。++**示例:**+```bash+/frontend-design:frontend-design+/commit-commands:commit+```++## MCP Prompts 作为命令++MCP servers 可以把 prompt 暴露成 slash command:++```text+/mcp__<server-name>__<prompt-name> [arguments]+```++**示例:**+```bash+/mcp__github__list_prs+/mcp__github__pr_review 456+/mcp__jira__create_issue "Bug title" high+```++### MCP 权限语法++在权限中控制 MCP server 访问:++- `mcp__github` - 访问整个 GitHub MCP server+- `mcp__github__*` - 通配符访问全部工具+- `mcp__github__get_issue` - 访问某个特定工具++## 命令架构++```mermaid+graph TD+ A["用户输入:/command-name"] --> B{"命令类型?"}+ B -->|内置| C["执行内置命令"]+ B -->|Skill| D["加载 SKILL.md"]+ B -->|插件| E["加载插件命令"]+ B -->|MCP| F["执行 MCP Prompt"]++ D --> G["解析 Frontmatter"]+ G --> H["替换变量"]+ H --> I["执行 Shell 命令"]+ I --> J["发送给 Claude"]+ J --> K["返回结果"]+```++## 命令生命周期++```mermaid+sequenceDiagram+ participant User+ participant Claude as Claude Code+ participant FS as File System+ participant CLI as Shell/Bash++ User->>Claude: 输入 /optimize+ Claude->>FS: 搜索 .claude/skills/ 和 .claude/commands/+ FS-->>Claude: 返回 optimize/SKILL.md+ Claude->>Claude: 解析 frontmatter+ Claude->>CLI: 执行 !`command` 替换+ CLI-->>Claude: 命令输出+ Claude->>Claude: 替换 $ARGUMENTS+ Claude->>User: 处理 prompt+ Claude->>User: 返回结果+```++## 本文件中的可用命令++这些示例命令可以作为 skill 或旧式命令安装。++### 1. `/optimize` - 代码优化++分析性能问题、内存泄漏和优化机会。++**用法:**+```text+/optimize+[粘贴你的代码]+```++**文件:** [optimize.md](optimize.md)++### 2. `/pr` - Pull Request 准备++引导你完成 PR 准备清单,包括 lint、测试和提交格式整理。++**用法:**+```text+/pr+```++**文件:** [pr.md](pr.md)++**截图:**+++### 3. `/generate-api-docs` - API 文档生成器++从源码生成完整的 API 文档。++**用法:**+```text+/generate-api-docs+```++**文件:** [generate-api-docs.md](generate-api-docs.md)++### 4. `/commit` - 带上下文的 Git Commit++基于仓库中的动态上下文创建 git commit。++**用法:**+```text+/commit [可选说明]+```++**文件:** [commit.md](commit.md)++### 5. `/push-all` - 暂存、提交并推送++会先暂存所有改动,再提交,并带安全检查地推送到远端。++**用法:**+```text+/push-all+```++**文件:** [push-all.md](push-all.md)++**安全检查:**+- 密钥文件:`.env*`、`*.key`、`*.pem`、`credentials.json`+- API Keys:识别真实 key 与占位符+- 大文件:未使用 Git LFS 且大于 10MB+- 构建产物:`node_modules/`、`dist/`、`__pycache__/`++### 6. `/doc-refactor` - 文档重构++重组项目文档,让结构更清晰、可访问性更好。++**文件:** [doc-refactor.md](doc-refactor.md)++### 7. `/setup-ci-cd` - CI/CD 流水线配置++实现 pre-commit hooks 和 GitHub Actions 质量保障流程。++**文件:** [setup-ci-cd.md](setup-ci-cd.md)++### 8. `/unit-test-expand` - 测试覆盖率扩展++针对未测试分支和边界情况,提升测试覆盖率。++**文件:** [unit-test-expand.md](unit-test-expand.md)++## 安装++### 作为 Skills(推荐)++复制到你的 skills 目录:++```bash+# 创建 skills 目录+mkdir -p .claude/skills++# 对每个命令文件,创建一个 skill 目录+for cmd in optimize pr commit; do+ mkdir -p .claude/skills/$cmd+ cp 01-slash-commands/$cmd.md .claude/skills/$cmd/SKILL.md+done+```++### 作为旧式命令++复制到 commands 目录:++```bash+# 项目范围(团队)+mkdir -p .claude/commands+cp 01-slash-commands/*.md .claude/commands/++# 个人使用+mkdir -p ~/.claude/commands+cp 01-slash-commands/*.md ~/.claude/commands/+```++## 创建你自己的命令++### Skill 模板(推荐)++创建 `.claude/skills/my-command/SKILL.md`:++```yaml+---+name: my-command+description: 这个命令做什么。用于 [触发条件]。+argument-hint: [可选参数]+allowed-tools: Bash(npm *), Read, Grep+---++# Command Title++## 上下文++- 当前分支:!`git branch --show-current`+- 相关文件:@package.json++## 指令++1. 第一步+2. 第二步,参数:$ARGUMENTS+3. 第三步++## 输出格式++- 如何格式化回复+- 需要包含什么+```++### 仅用户可调用的命令(无自动触发)++对于带副作用、Claude 不应自动触发的命令:++```yaml+---+name: deploy+description: 部署到生产环境+disable-model-invocation: true+allowed-tools: Bash(npm *), Bash(git *)+---++将应用部署到生产环境:++1. 运行测试+2. 构建应用+3. 推送到部署目标+4. 验证部署+```++## 最佳实践++| 应该做 | 不要做 |+|------|---------|+| 使用清晰、以动作导向的命名 | 为一次性任务创建命令 |+| 在 `description` 中写清触发条件 | 在命令里写太复杂的逻辑 |+| 保持命令聚焦于单一任务 | 硬编码敏感信息 |+| 有副作用时使用 `disable-model-invocation` | 跳过 description 字段 |+| 用 `!` 前缀注入动态上下文 | 假设 Claude 知道当前状态 |+| 把相关文件组织进 skill 目录 | 所有内容都塞进一个文件 |++## 故障排查++### 找不到命令++**解决办法:**+- 检查文件是否位于 `.claude/skills/<name>/SKILL.md` 或 `.claude/commands/<name>.md`+- 确认 frontmatter 中的 `name` 与预期命令名一致+- 重启 Claude Code 会话+- 运行 `/help` 查看可用命令++### 命令没有按预期执行++**解决办法:**+- 补充更具体的指令+- 在 skill 文件中加入示例+- 如果使用 bash 命令,检查 `allowed-tools`+- 先用简单输入测试++### Skill 与 Command 冲突++如果同名同时存在,**skill 优先**。删除其中一个或重命名即可。++## 相关指南++- **[Skills](../03-skills/README.md)** - 完整的 Skills 参考+- **[Memory](../02-memory/README.md)** - 带 `CLAUDE.md` 的持久上下文+- **[Subagents](../04-subagents/README.md)** - 委派式 AI agents+- **[Plugins](../07-plugins/README.md)** - 打包好的命令集合+- **[Hooks](../06-hooks/README.md)** - 事件驱动自动化++## 其他资源++- [官方交互模式文档](https://code.claude.com/docs/en/interactive-mode) - 内置命令参考+- [官方 Skills 文档](https://code.claude.com/docs/en/skills) - 完整 Skills 参考+- [CLI Reference](https://code.claude.com/docs/en/cli-reference) - 命令行选项++---++*Claude How To 指南系列的一部分*diff --git a/zh/01-slash-commands/commit.md b/zh/01-slash-commands/commit.mdnew file mode 100644index 0000000..99d6fa2--- /dev/null+++ b/zh/01-slash-commands/commit.md@@ -0,0 +1,26 @@+---+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*)+argument-hint: [message]+description: 创建带上下文的 Git 提交+---++## 上下文++- 当前 git 状态: !`git status`+- 当前 git diff: !`git diff HEAD`+- 当前分支: !`git branch --show-current`+- 最近的提交: !`git log --oneline -10`++## 你的任务++根据上面的变更创建一个单独的 Git 提交。++如果通过参数传入了 message,就直接使用它:$ARGUMENTS++否则,分析这些变更,并按照 conventional commits 格式生成合适的提交信息:+- `feat:` 新功能+- `fix:` 修复 bug+- `docs:` 文档变更+- `refactor:` 代码重构+- `test:` 新增测试+- `chore:` 维护任务diff --git a/zh/01-slash-commands/doc-refactor.md b/zh/01-slash-commands/doc-refactor.mdnew file mode 100644index 0000000..4569912--- /dev/null+++ b/zh/01-slash-commands/doc-refactor.md@@ -0,0 +1,24 @@+---+name: 文档重构+description: 为项目重新组织文档结构,以提升清晰度和可访问性+tags: documentation, refactoring, organization+---++# 文档重构++根据项目类型重构项目文档结构:++1. **分析项目**:识别类型(库/API/Web 应用/CLI/微服务)、架构和用户角色+2. **集中管理文档**:将技术文档迁移到 `docs/`,并保留正确的交叉引用+3. **整理根目录 README.md**:将其精简为入口页,包含概览、快速开始、模块/组件摘要、许可证和联系方式+4. **为组件补充文档**:添加模块/包/服务级别的 README 文件,包含安装和测试说明+5. **按主题组织 `docs/`**:+ - 架构、API Reference、数据库、设计、故障排查、部署、贡献(根据项目需要调整)+6. **创建指南**(按需选择):+ - 用户指南:面向应用最终用户的文档+ - API 文档:API 的端点、认证和示例+ - 开发指南:环境搭建、测试、贡献流程+ - 部署指南:服务/应用的生产部署+7. **所有图表都使用 Mermaid**(架构图、流程图、Schema 图)++保持文档简洁、易扫读,并与项目类型保持上下文一致。diff --git a/zh/01-slash-commands/generate-api-docs.md b/zh/01-slash-commands/generate-api-docs.mdnew file mode 100644index 0000000..8075f67--- /dev/null+++ b/zh/01-slash-commands/generate-api-docs.md@@ -0,0 +1,19 @@+---+description: 根据源代码生成完整的 API 文档+---++# API 文档生成器++按以下步骤生成 API 文档:++1. 扫描 `/src/api/` 下的所有文件+2. 提取函数签名和 JSDoc 注释+3. 按端点/模块进行组织+4. 生成带示例的 Markdown+5. 包含请求/响应 Schema+6. 添加错误文档++输出格式:+- 输出为 `/docs/api.md` 中的 Markdown 文件+- 为所有端点加入 curl 示例+- 添加 TypeScript 类型diff --git a/zh/01-slash-commands/optimize.md b/zh/01-slash-commands/optimize.mdnew file mode 100644index 0000000..e8ebe08--- /dev/null+++ b/zh/01-slash-commands/optimize.md@@ -0,0 +1,19 @@+---+description: 分析代码中的性能问题并提出优化建议+---++# 代码优化++按优先级审查提供的代码,重点关注以下问题:++1. **性能瓶颈** - 识别 O(n²) 操作和低效循环+2. **内存泄漏** - 查找未释放的资源、循环引用+3. **算法改进** - 建议更好的算法或数据结构+4. **缓存机会** - 识别重复计算+5. **并发问题** - 查找竞态条件或线程问题++请按以下格式输出:+- 问题严重性(Critical/High/Medium/Low)+- 代码位置+- 解释+- 推荐修复方案,附代码示例diff --git a/zh/01-slash-commands/pr.md b/zh/01-slash-commands/pr.mdnew file mode 100644index 0000000..81dfdec--- /dev/null+++ b/zh/01-slash-commands/pr.md@@ -0,0 +1,26 @@+---+description: 清理代码、暂存变更并准备 Pull Request+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(npm test:*), Bash(npm run lint:*)+---++# Pull Request 准备清单++在创建 PR 之前,请执行以下步骤:++1. 运行格式化:`prettier --write .`+2. 运行测试:`npm test`+3. 查看 git diff:`git diff HEAD`+4. 暂存变更:`git add .`+5. 按 conventional commits 创建提交信息:+ - `fix:` bug 修复+ - `feat:` 新功能+ - `docs:` 文档+ - `refactor:` 代码重构+ - `test:` 测试新增+ - `chore:` 维护++6. 生成 PR 摘要,包含:+ - 变更了什么+ - 为什么变更+ - 做了哪些测试+ - 可能的影响diff --git a/zh/01-slash-commands/push-all.md b/zh/01-slash-commands/push-all.mdnew file mode 100644index 0000000..6974c32--- /dev/null+++ b/zh/01-slash-commands/push-all.md@@ -0,0 +1,152 @@+---+description: 暂存所有变更,创建提交并推送到远程(请谨慎使用)+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git push:*), Bash(git diff:*), Bash(git log:*), Bash(git pull:*)+---++# 提交并推送全部内容++⚠️ **注意**:将所有变更都暂存、提交并推送到远程。只有在你确认所有改动都应该放在一起时才使用。++## 工作流++### 1. 分析变更+并行运行:+- `git status` - 显示已修改/已添加/已删除/未跟踪文件+- `git diff --stat` - 显示变更统计+- `git log -1 --oneline` - 查看最近一次提交,便于统一提交信息风格++### 2. 安全检查++**❌ 如果发现以下内容,立即停止并警告:**+- Secrets:`.env*`、`*.key`、`*.pem`、`credentials.json`、`secrets.yaml`、`id_rsa`、`*.p12`、`*.pfx`、`*.cer`+- API Keys:任何 `*_API_KEY`、`*_SECRET`、`*_TOKEN` 变量包含真实值,而不是占位符,如 `your-api-key`、`xxx`、`placeholder`+- 大文件:`>10MB` 且未使用 Git LFS+- 构建产物:`node_modules/`、`dist/`、`build/`、`__pycache__/`、`*.pyc`、`.venv/`+- 临时文件:`.DS_Store`、`thumbs.db`、`*.swp`、`*.tmp`++**API Key 校验:**+检查修改文件中是否存在以下模式:+```bash+OPENAI_API_KEY=sk-proj-xxxxx # ❌ 检测到真实密钥!+AWS_SECRET_KEY=AKIA... # ❌ 检测到真实密钥!+STRIPE_API_KEY=sk_live_... # ❌ 检测到真实密钥!++# ✅ 可接受的占位符:+API_KEY=your-api-key-here+SECRET_KEY=placeholder+TOKEN=xxx+API_KEY=<your-key>+SECRET=${YOUR_SECRET}+```++**✅ 确认:**+- `.gitignore` 配置正确+- 没有合并冲突+- 分支正确(如果是 `main`/`master` 要提醒)+- API key 只是占位符++### 3. 请求确认++展示摘要:+```+📊 变更摘要:+- X 个文件已修改,Y 个文件已新增,Z 个文件已删除+- 总计:+AAA 行新增,-BBB 行删除++🔒 安全性:✅ 无 secrets | ✅ 无大文件 | ⚠️ [警告]+🌿 分支: [name] → origin/[name]++我将执行:git add . → commit → push++请输入 'yes' 继续,或输入 'no' 取消。+```++**在收到明确的 "yes" 之前不要继续。**++### 4. 执行(确认后)++按顺序运行:+```bash+git add .+git status # 验证暂存状态+```++### 5. 生成提交信息++分析变更并创建 conventional commit:++**格式:**+```+[type]: 简要摘要(最多 72 个字符)++- 关键改动 1+- 关键改动 2+- 关键改动 3+```++**类型:** `feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`、`perf`、`build`、`ci`++**示例:**+```+docs: 更新概念文档,补充完整说明++- 添加架构图和表格+- 补充实用示例+- 扩展最佳实践部分+```++### 6. 提交并推送++```bash+git commit -m "$(cat <<'EOF'+[生成的提交信息]+EOF+)"+git push # 如果失败:git pull --rebase && git push+git log -1 --oneline --decorate # 验证+```++### 7. 确认成功++```+✅ 已成功推送到远程!++Commit: [hash] [message]+Branch: [branch] → origin/[branch]+Files changed: X (+insertions, -deletions)+```++## 错误处理++- `git add` 失败:检查权限、锁定文件,确认仓库已初始化+- `git commit` 失败:修复 pre-commit hooks,检查 git 配置(user.name/email)+- `git push` 失败:+ - 非快进:`git pull --rebase && git push`+ - 没有远程分支:`git push -u origin [branch]`+ - 受保护分支:改用 PR 工作流++## 适用场景++✅ **适合:**+- 多文件文档更新+- 同时包含测试和文档的功能+- 跨多个文件的 bug 修复+- 项目级格式化/重构+- 配置变更++❌ **避免:**+- 不确定要提交哪些内容+- 包含 secrets/敏感数据+- 受保护分支且未经过审核+- 存在合并冲突+- 想保留更细粒度的提交历史+- pre-commit hooks 失败++## 替代方案++如果用户想保留控制权,可以建议:+1. **选择性暂存**:查看并暂存特定文件+2. **交互式暂存**:使用 `git add -p` 逐块选择+3. **PR 工作流**:创建分支 → 推送 → 发起 PR(使用 `/pr` 命令)++**⚠️ 记住**:在推送前始终先检查变更。拿不准时,使用单独的 git 命令会更可控。diff --git a/zh/01-slash-commands/setup-ci-cd.md b/zh/01-slash-commands/setup-ci-cd.mdnew file mode 100644index 0000000..7e21df8--- /dev/null+++ b/zh/01-slash-commands/setup-ci-cd.md@@ -0,0 +1,25 @@+---+name: 设置 CI/CD 流水线+description: 实现 pre-commit hooks 和 GitHub Actions 质量保障+tags: ci-cd, devops, automation+---++# 设置 CI/CD 流水线++根据项目类型实现完整的 DevOps 质量门禁:++1. **分析项目**:检测语言、框架、构建系统和现有工具链+2. **配置 pre-commit hooks**,使用与语言匹配的工具:+ - 格式化:Prettier/Black/gofmt/rustfmt 等+ - 代码检查:ESLint/Ruff/golangci-lint/Clippy 等+ - 安全:Bandit/gosec/cargo-audit/npm audit 等+ - 类型检查:TypeScript/mypy/flow(如适用)+ - 测试:运行相关测试套件+3. **创建 GitHub Actions 工作流**(`.github/workflows/`):+ - 在 push/PR 时镜像 pre-commit 检查+ - 多版本/多平台矩阵(如适用)+ - 构建和测试验证+ - 部署步骤(如需要)+4. **验证流水线**:本地测试、创建测试 PR,确认所有检查都通过++使用免费/开源工具。尊重已有配置。保持执行快速。diff --git a/zh/01-slash-commands/unit-test-expand.md b/zh/01-slash-commands/unit-test-expand.mdnew file mode 100644index 0000000..9867ec0--- /dev/null+++ b/zh/01-slash-commands/unit-test-expand.md@@ -0,0 +1,25 @@+---+name: 扩充单元测试+description: 通过覆盖未测试分支和边界情况来提高测试覆盖率+tags: testing, coverage, unit-tests+---++# 扩充单元测试++根据项目的测试框架,扩充现有单元测试:++1. **分析覆盖率**:运行覆盖率报告,找出未测试分支、边界情况和低覆盖区域+2. **识别缺口**:审查代码中的逻辑分支、错误路径、边界条件、空值/空输入+3. **编写测试**,使用项目现有框架:+ - Jest/Vitest/Mocha(JavaScript/TypeScript)+ - pytest/unittest(Python)+ - Go testing/testify(Go)+ - Rust test framework(Rust)+4. **针对具体场景**:+ - 错误处理和异常+ - 边界值(最小/最大、空值、空输入)+ - 边缘情况和极端情况+ - 状态转换和副作用+5. **验证提升**:再次运行覆盖率,确认有可衡量的提升++只展示新增的测试代码块。遵循现有测试模式和命名约定。diff --git a/zh/02-memory/README.md b/zh/02-memory/README.mdnew file mode 100644index 0000000..5bc1734--- /dev/null+++ b/zh/02-memory/README.md@@ -0,0 +1,305 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# Memory 指南++## 概览++Memory 让 Claude Code 在不同会话之间保留上下文。你可以把团队规范、项目规则、个人偏好和目录级约束写进 `CLAUDE.md`,让 Claude 在合适的时候自动加载。++## Memory 命令速查++| 命令 | 作用 |+|------|------|+| `/init` | 初始化项目级 `CLAUDE.md` |+| `/memory` | 打开并编辑记忆文件 |+| `#` | 快速把当前规则写入 memory |++## 快速上手:初始化 Memory++### 使用 `/init`++在项目目录中运行:++```bash+/init+```++Claude 会根据当前项目生成一个 `CLAUDE.md`,通常包含类似如下结构:++```md+# 项目配置+## 项目概览+## 开发规范+```++### 使用 `#` 快速更新记忆++当你想把一句规则写入 memory 时,可以直接在输入前加 `#`:++```text+# 这个项目始终使用 TypeScript 严格模式+# 优先使用 async/await,而不是 promise 链+# 每次提交前都运行 npm test+# 文件名统一使用 kebab-case+```++这会把规则加入当前会话能感知到的记忆中。++### 使用 `/memory`++`/memory` 会打开记忆编辑器,让你在不同范围之间切换:++1. 受管策略记忆+2. 项目记忆(`./CLAUDE.md`)+3. 用户记忆(`~/.claude/CLAUDE.md`)+4. 本地项目记忆++适合你把长期规则、项目规范和个人偏好分层管理。++## Memory 架构++Claude Code 的记忆系统通常有以下层级:++| 层级 | 作用范围 | 典型内容 |+|------|----------|----------|+| 受管策略 | 组织级 | 合规、安全、统一流程 |+| 项目记忆 | 单个项目 | 架构、编码标准、工作流 |+| 目录记忆 | 子目录 | 模块约束、局部规范 |+| 用户记忆 | 单个用户 | 个人偏好、默认设置 |++## 记忆层级++Claude 会按更接近当前上下文的规则优先使用更具体的 memory。一般来说:++- 组织级规则优先于普通偏好+- 项目规则优先于个人偏好+- 目录级规则优先于项目级通用规则++## 排除规则++如果某些 `CLAUDE.md` 不应该被自动加载,可以通过 `claudeMdExcludes` 之类的设置排除。++## 配置文件层级++项目设置、用户设置和企业托管设置会共同影响 memory 的加载方式。你可以把它理解为:++1. 组织策略+2. 项目设置+3. 本地设置+4. 临时会话输入++## 模块化规则系统++Memory 不一定要写成一个巨大文件。你可以把规则拆成多个目录文件,再按路径组织。++### 通过 YAML frontmatter 设置路径规则++```md+---+description: API development rules+---++# API Development Rules+```++### 子目录与符号链接++你可以用子目录和 symlink 把局部规则复用到多个项目区域。++## Memory 位置表++常见位置包括:++- 项目根目录的 `CLAUDE.md`+- 用户目录的 `~/.claude/CLAUDE.md`+- 子目录的 `CLAUDE.md`++## Memory 更新生命周期++一般流程是:++1. 创建或编辑 `CLAUDE.md`+2. Claude 重新加载+3. 新规则在后续会话中生效++## Auto Memory++Auto memory 让 Claude 根据当前目录自动寻找并加载合适的记忆文件。++### 工作方式++Claude 会根据当前工作目录、父目录和已配置路径,逐层查找相关 memory。++### 目录结构++```text+project/+├── CLAUDE.md+├── src/+│ ├── CLAUDE.md+│ └── api/+│ └── CLAUDE.md+```++### 版本要求++某些 auto memory 行为依赖较新的 Claude Code 版本。++### 自定义 auto memory 目录++如果默认目录不适合你的项目,可以在设置中指定新的 memory 路径。++### worktree 和仓库共享++在 worktree、monorepo 或多人协作场景中,auto memory 可以帮助保持规则一致。++### Subagent 记忆++Subagents 也可以拥有自己的记忆范围,用于在各自职责内保持一致性。++### 控制 auto memory++```bash+# 当前会话禁用 auto memory++# 显式开启 auto memory+```++## 通过 `--add-dir` 添加额外目录++你可以用 `--add-dir` 把额外目录也加入 Claude 的可见范围,适合多目录协作。++## 实战示例++### 示例 1:项目记忆结构++```md+# 项目配置+## 项目概览+## 架构+## 开发规范+### 代码风格+### 命名约定+### Git 工作流+### 测试要求+### API 规范+### 数据库+### 部署+## 常用命令+## 团队联系人+## 已知问题与解决办法+## 相关项目+```++### 示例 2:目录级记忆++```md+# API 模块规范+## API 专属规范+### 请求校验+### 身份验证+### 响应格式+### 分页+### 限流+### 缓存+```++### 示例 3:个人记忆++```md+# 我的开发偏好+## 关于我+## 代码偏好+### 错误处理+### 注释+### 测试+### 架构+## 调试偏好+## 沟通方式+## 项目组织+## 工具链+```++### 示例 4:会话中更新记忆++两种常见方式:++1. 直接提要求,让 Claude 把规则写进 memory+2. 使用 `# new rule into memory` 这种模式追加规则++## 最佳实践++### 应该做的++- 用项目记忆保存团队标准+- 用目录记忆保存局部差异+- 先写简洁规则,再逐步补充+- 把可重复内容写进 `CLAUDE.md`++### 不应该做的++- 不要把 README 整份复制进 `CLAUDE.md`+- 不要把明显属于代码的实现细节硬塞进 memory+- 不要让 memory 变成垃圾桶++### 记忆管理建议++- 优先引用已有文档,而不是重复粘贴+- 只保留真正影响 Claude 行为的信息+- 定期整理过期或冲突的规则++## 安装说明++### 设置项目记忆++#### 方法 1:使用 `/init`(推荐)++```bash+/init+```++#### 方法 2:手动创建++```bash+cp project-CLAUDE.md CLAUDE.md+```++#### 方法 3:快速更新++```text+# Use semantic versioning for all releases+# Always run tests before committing+# Prefer composition over inheritance+```++### 设置个人记忆++```bash+cp personal-CLAUDE.md ~/.claude/CLAUDE.md+```++### 设置目录记忆++```bash+cp directory-api-CLAUDE.md src/api/CLAUDE.md+```++### 验证安装++- 重新打开 Claude Code 会话+- 检查 `CLAUDE.md` 是否被自动加载+- 用一条明显会受 memory 影响的提示词测试++## 官方文档++如果你想看更详细的行为定义、兼容性和最新限制,建议参考 Claude Code 官方 memory 文档。++## 相关概念++- [Slash Commands 中文参考](../01-slash-commands/README.md)+- [Skills 中文指南](../03-skills/README.md)+- [Subagents 中文参考](../04-subagents/README.md)+- [Advanced Features 中文指南](../09-advanced-features/README.md)diff --git a/zh/02-memory/directory-api-CLAUDE.md b/zh/02-memory/directory-api-CLAUDE.mdnew file mode 100644index 0000000..200187d--- /dev/null+++ b/zh/02-memory/directory-api-CLAUDE.md@@ -0,0 +1,62 @@+# API 模块规范++本文件会覆盖 `/src/api/` 下所有内容对应的根目录 `CLAUDE.md`。++## API 专属规范++### 请求校验+- 使用 Zod 做 schema 校验+- 始终校验输入+- 校验失败时返回 400+- 提供字段级别的错误详情++### 认证+- 所有端点都需要 JWT token+- token 放在 `Authorization` header 中+- token 24 小时后过期+- 实现 refresh token 机制++### 响应格式++所有响应都必须遵循下面的结构:++```json+{+ "success": true,+ "data": { /* 实际数据 */ },+ "timestamp": "2025-11-06T10:30:00Z",+ "version": "1.0"+}+```++错误响应:++```json+{+ "success": false,+ "error": {+ "code": "VALIDATION_ERROR",+ "message": "用户可读消息",+ "details": { /* 字段错误 */ }+ },+ "timestamp": "2025-11-06T10:30:00Z"+}+```++### 分页+- 使用基于 cursor 的分页,而不是 offset+- 包含 `hasMore` 布尔值+- 单页最大数量限制为 100+- 默认页大小:20++### 限流+- 已认证用户每小时 1000 次请求+- 公开端点每小时 100 次请求+- 超出时返回 429+- 包含 `retry-after` header++### 缓存+- 使用 Redis 做会话缓存+- 缓存时长默认 5 分钟+- 写操作时失效缓存+- 用资源类型给缓存键打标签diff --git a/zh/02-memory/personal-CLAUDE.md b/zh/02-memory/personal-CLAUDE.mdnew file mode 100644index 0000000..9a5c612--- /dev/null+++ b/zh/02-memory/personal-CLAUDE.md@@ -0,0 +1,61 @@+# 我的开发偏好++## 关于我+- **经验水平**:8 年全栈开发经验+- **偏好语言**:TypeScript、Python+- **沟通风格**:直接,最好带例子+- **学习风格**:配合代码的可视化图示++## 代码偏好++### 错误处理+我偏好显式的错误处理,使用 `try-catch` 和有意义的错误消息。+避免使用泛化错误。为了便于调试,始终记录错误日志。++### 注释+注释应解释“为什么”,而不是“是什么”。代码本身应该尽量能自解释。+注释应该说明业务逻辑或者不明显的设计决策。++### 测试+我偏好 TDD(测试驱动开发)。+先写测试,再写实现。+重点关注行为,而不是实现细节。++### 架构+我偏好模块化、低耦合的设计。+使用依赖注入提升可测试性。+拆分关注点,例如 Controllers、Services、Repositories。++## 调试偏好+- 使用带前缀的 `console.log`:`[DEBUG]`+- 包含上下文:函数名、相关变量+- 如果有堆栈信息,优先使用+- 日志里始终带时间戳++## 沟通方式+- 用图示解释复杂概念+- 先给具体例子,再讲理论+- 提供修改前 / 修改后的代码片段+- 在结尾总结关键点++## 项目组织+我通常会这样组织项目:++```text+project/+ ├── src/+ │ ├── api/+ │ ├── services/+ │ ├── models/+ │ └── utils/+ ├── tests/+ ├── docs/+ └── docker/+```++## 工具链+- **IDE**:VS Code,带 vim 键位+- **终端**:Zsh + Oh-My-Zsh+- **格式化**:Prettier,行宽 100 字符+- **Linter**:ESLint,airbnb 配置+- **测试框架**:Jest + React Testing Librarydiff --git a/zh/02-memory/project-CLAUDE.md b/zh/02-memory/project-CLAUDE.mdnew file mode 100644index 0000000..57114e0--- /dev/null+++ b/zh/02-memory/project-CLAUDE.md@@ -0,0 +1,88 @@+# 项目配置++## 项目概览+- **名称**:电商平台+- **技术栈**:Node.js、PostgreSQL、React 18、Docker+- **团队规模**:5 名开发者+- **截止时间**:2025 年第 4 季度++## 架构+@docs/architecture.md+@docs/api-standards.md+@docs/database-schema.md++## 开发规范++### 代码风格+- 使用 Prettier 格式化+- 使用带 airbnb 配置的 ESLint+- 最大行长度:100 字符+- 使用 2 空格缩进++### 命名规范+- **文件**:kebab-case(`user-controller.js`)+- **类**:PascalCase(`UserService`)+- **函数 / 变量**:camelCase(`getUserById`)+- **常量**:UPPER_SNAKE_CASE(`API_BASE_URL`)+- **数据库表**:snake_case(`user_accounts`)++### Git 工作流+- 分支命名:`feature/description` 或 `fix/description`+- 提交信息:遵循 conventional commits+- 合并前必须有 PR+- 所有 CI/CD 检查都必须通过+- 至少需要 1 个 approval++### 测试要求+- 最低 80% 代码覆盖率+- 所有关键路径都必须有测试+- 单元测试使用 Jest+- E2E 测试使用 Cypress+- 测试文件名:`*.test.ts` 或 `*.spec.ts`++### API 规范+- 只允许 RESTful 端点+- 请求 / 响应都使用 JSON+- 正确使用 HTTP 状态码+- API 版本路径:`/api/v1/`+- 所有端点都要带示例文档++### 数据库+- schema 变更使用 migrations+- 绝不硬编码凭据+- 使用连接池+- 开发环境启用查询日志+- 需要定期备份++### 部署+- 基于 Docker 的部署+- 使用 Kubernetes 编排+- 蓝绿部署策略+- 失败时自动回滚+- 部署前先执行数据库迁移++## 常用命令++| 命令 | 作用 |+|---------|---------|+| `npm run dev` | 启动开发服务器 |+| `npm test` | 运行测试套件 |+| `npm run lint` | 检查代码风格 |+| `npm run build` | 构建生产版本 |+| `npm run migrate` | 执行数据库迁移 |++## 团队联系人+- 技术负责人:Sarah Chen(@sarah.chen)+- 产品经理:Mike Johnson(@mike.j)+- 运维:Alex Kim(@alex.k)++## 已知问题与解决方案+- PostgreSQL 连接池在高峰期限制为 20+- 解决方法:实现查询排队+- Safari 14 对 async generator 的兼容性有问题+- 解决方法:使用 Babel 转译器++## 关联项目+- 分析仪表盘:`/projects/analytics`+- 移动端 App:`/projects/mobile`+- 管理后台:`/projects/admin`diff --git a/zh/03-skills/README.md b/zh/03-skills/README.mdnew file mode 100644index 0000000..00bf0d1--- /dev/null+++ b/zh/03-skills/README.md@@ -0,0 +1,271 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# Agent Skills 指南++## 概览++Skills 是可以复用、可自动触发的能力包。一个 skill 通常包含 `SKILL.md`、参考文件、脚本和模板。Claude 在合适的场景下会自动加载它。++### 主要好处++- 可复用+- 可渐进加载+- 可以把脚本、模板、说明放在一起+- 适合标准化流程++## Skills 的工作方式:渐进式披露++Skills 不会一次性把所有内容都塞进上下文,而是按需加载。++### 三层加载++1. **只看描述**:先判断这个 skill 是否相关+2. **加载 `SKILL.md`**:读取核心说明+3. **按需加载支持文件**:脚本、模板、参考资料++## Skill 加载流程++1. Claude 扫描技能目录+2. 根据描述判断是否匹配当前任务+3. 读取 `SKILL.md`+4. 如有需要,再加载脚本和辅助文件++## Skill 类型与位置++Skills 可以放在:++- 项目目录下的 `.claude/skills/`+- 用户目录下的 `~/.claude/skills/`++### 自动发现++只要目录结构正确,Claude 就会自动发现这些 Skills。++## 创建自定义 Skills++### 基本目录结构++```text+my-skill/+└── SKILL.md+```++### `SKILL.md` 格式++```yaml+---+name: my-skill+description: 这个 skill 的用途,以及什么时候触发+---++# Your Skill Name++## Instructions++## Examples+```++### 必填字段++- `name`+- `description`++### 可选 frontmatter 字段++- `argument-hint`+- `allowed-tools`+- `model`+- `disable-model-invocation`+- `user-invocable`+- `context`+- `agent`+- `hooks`++## Skill 内容类型++### 参考内容++适合放规则、标准、文档片段和示例。++### 任务内容++适合放具体步骤、执行流程和结果格式要求。++## 控制 Skill 的调用++你可以通过 `disable-model-invocation`、`user-invocable` 和工具白名单来控制 Claude 是否能自动调用这个 skill。++## 字符串替换++Skills 支持 `$ARGUMENTS`、`$0`、`$1` 等参数替换。++### 动态上下文注入++你可以在 prompt 里插入 shell 命令结果:++```md+- 当前 git 状态:!`git status`+- 当前 diff:!`git diff HEAD`+- 当前分支:!`git branch --show-current`+```++## 在 subagent 中运行 Skills++某些 skill 适合在隔离上下文中运行,这样可以降低对主会话的影响。++## 实战示例++### 示例 1:代码审查 Skill++一个典型的审查 skill 会包含:++- 审查模板+- 风险等级+- 输出格式+- 需要关注的维度++### 示例 2:代码库可视化 Skill++可以把代码库结构、依赖关系和模块边界总结给 Claude,便于快速理解。++### 示例 3:部署 Skill(只允许用户触发)++适合带副作用的操作,比如生产环境部署。通常会配合 `disable-model-invocation: true`。++### 示例 4:品牌语气 Skill++用于检查输出是否符合品牌语气、语调和表达风格。++### 示例 5:`CLAUDE.md` 生成 Skill++可以从项目文档中生成或补充 `CLAUDE.md`。++### 示例 6:带脚本的重构 Skill++常见组合是:++- `SKILL.md`+- `scripts/`+- `templates/`+- `references/`++## 管理 Skills++### 查看可用 Skills++```bash+/skills+```++### 测试一个 Skill++把它放到测试目录或者临时项目里,然后通过相应命令触发。++### 更新 Skill++修改 `SKILL.md` 或支持文件后,重新打开会话或重新加载即可。++### 限制 Claude 对 Skill 的访问++你可以通过权限配置,只允许 Claude 访问某些 skill。++## 最佳实践++### 1. 描述要具体++让 `description` 明确说明这个 skill 在什么时候触发。++### 2. 保持聚焦++一个 skill 解决一个问题,不要什么都塞进去。++### 3. 包含触发词++在描述里加入相关关键词,帮助 Claude 更准确地选择它。++### 4. `SKILL.md` 不要太长++尽量控制在 500 行以内,超过就拆分支持文件。++### 5. 引用支持文件++把重复内容移到脚本或参考文件中,主文件只保留核心说明。++## 故障排查++### 快速参考++- 检查目录结构是否正确+- 检查 `SKILL.md` frontmatter 是否有效+- 检查 skill 名称是否和调用名一致++### Skill 没有触发++- 检查描述是否足够具体+- 检查目录是否在 Claude 可见范围内+- 检查是否被更高优先级的 skill 覆盖++### Skill 触发太频繁++- 收紧描述+- 增加约束条件+- 用更具体的触发词++### Claude 看不到全部 Skills++- 检查路径+- 检查权限+- 重新加载会话++## 安全注意事项++- 不要在 skill 中硬编码密钥+- 对副作用操作保持用户触发+- 给自动触发的 skill 设置清晰边界++## Skills vs 其他功能++| 功能 | 触发方式 | 适合场景 |+|------|----------|----------|+| Skills | 自动/半自动 | 复用能力、流程标准化 |+| Slash Commands | 手动 | 快捷命令 |+| Subagents | 自动委派 | 隔离任务 |+| Hooks | 事件触发 | 自动化和验证 |++## 内置 Skills++Claude Code 自带一些 Skills,例如批处理、调试、简化和 Claude API 相关内容。++## 共享 Skills++### 项目 Skills(团队共享)++把 skill 放在项目目录里,团队成员都能用。++### 个人 Skills++```bash+# 复制到个人目录+mkdir -p ~/.claude/skills++# 让脚本可执行+chmod +x ~/.claude/skills/*/scripts/*+```++### Plugin 分发++你也可以把 Skills 作为插件的一部分发布出去。++## 继续深入++如果你要管理一整套 Skills,可以再做一个 skill collection 或 skill manager,用来统一发现、更新和分发。++## 更多资源++- [根目录中文指南](../README.md)+- [Slash Commands 中文参考](../01-slash-commands/README.md)+- [Memory 中文指南](../02-memory/README.md)+- [Subagents 中文参考](../04-subagents/README.md)diff --git a/zh/03-skills/blog-draft/SKILL.md b/zh/03-skills/blog-draft/SKILL.mdnew file mode 100644index 0000000..02580df--- /dev/null+++ b/zh/03-skills/blog-draft/SKILL.md@@ -0,0 +1,274 @@+---+name: blog-draft+description: 根据想法和资料撰写博客草稿。适用于用户想写博客、基于研究创建内容,或起草文章的场景。流程会引导你完成调研、头脑风暴、提纲编写和带版本控制的迭代撰写。+---++## 用户输入++```text+$ARGUMENTS+```++在继续之前,你**必须**先考虑用户输入。用户应提供:+- **想法/主题**:博客文章的核心概念或主题+- **资源**:用于研究的 URL、文件或参考资料(可选,但推荐)+- **目标读者**:这篇博客是写给谁看的(可选)+- **语气/风格**:正式、轻松、技术向等(可选)++**重要**:如果用户是在请求更新一篇**已有博客文章**,请跳过步骤 0-8,直接从**步骤 9** 开始。先阅读现有草稿文件,再继续迭代流程。++## 执行流程++请按顺序执行以下步骤。**不要跳步,也不要在未获得用户批准的情况下继续执行标明需要确认的步骤。**++### 步骤 0:创建项目文件夹++1. 使用以下格式生成文件夹名称:`YYYY-MM-DD-short-topic-name`+ - 使用今天的日期+ - 根据主题生成一个简短、适合 URL 的 slug(小写、连字符连接,最多 5 个词)++2. 创建文件夹结构:+ ```text+ blog-posts/+ └── YYYY-MM-DD-short-topic-name/+ └── resources/+ ```++3. 在继续前,先向用户确认文件夹已创建。++### 步骤 1:研究与资源收集++1. 在博客文章目录中创建 `resources/` 子文件夹++2. 对于每个提供的资源:+ - **URL**:抓取关键内容并保存到 `resources/` 下的 markdown 文件中+ - **文件**:读取并在 `resources/` 中做摘要+ - **主题**:使用网络搜索收集最新信息++3. 为每个资源在 `resources/` 中创建摘要文件:+ - `resources/source-1-[short-name].md`+ - `resources/source-2-[short-name].md`+ - 以此类推++4. 每个摘要都应包含:+ ```markdown+ # 来源:[标题/URL]++ ## 要点+ - 要点 1+ - 要点 2++ ## 相关引文/数据+ - 引文或统计 1+ - 引文或统计 2++ ## 与主题的关联+ 简要说明其相关性+ ```++5. 向用户展示研究摘要。++### 步骤 2:头脑风暴与澄清++1. 基于想法和已研究的资源,展示:+ - 从研究中识别出的**主要主题**+ - 博客文章的**可能切入角度**+ - 应该覆盖的**关键点**+ - 仍需进一步澄清的**信息缺口**++2. 提出澄清问题:+ - 你希望读者最终带走的核心结论是什么?+ - 研究中有没有哪些点是你希望重点强调的?+ - 目标长度是多少?(短:500-800 字,中:1000-1500 字,长:2000+ 字)+ - 有没有哪些内容你希望排除?++3. **在继续之前,等待用户回复。**++### 步骤 3:提出提纲++1. 创建一个结构化提纲,包括:++ ```markdown+ # 博客文章提纲:[标题]++ ## 元信息+ - **目标读者**:[谁]+ - **语气**:[风格]+ - **目标长度**:[字数]+ - **核心结论**:[关键信息]++ ## 建议结构++ ### 开场/引子+ - 开场钩子思路+ - 背景铺垫+ - 论点陈述++ ### 第一部分:[标题]+ - 关键点 A+ - 关键点 B+ - 来自 [来源] 的支撑证据++ ### 第二部分:[标题]+ - 关键点 A+ - 关键点 B++ [继续列出所有部分...]++ ### 结论+ - 关键点总结+ - 行动号召或最终思考++ ## 需要引用的来源+ - 来源 1+ - 来源 2+ ```++2. 向用户展示提纲,并**请求批准或修改意见**。++### 步骤 4:保存已批准的提纲++1. 用户批准提纲后,将其保存为博客文章文件夹中的 `OUTLINE.md`。++2. 确认提纲已保存。++### 步骤 5:提交提纲(如果在 git 仓库中)++1. 检查当前目录是否为 git 仓库。++2. 如果是:+ - 暂存新文件:博客文章文件夹、resources 和 `OUTLINE.md`+ - 使用如下提交信息创建 commit:`docs: Add outline for blog post - [topic-name]`+ - 推送到远程仓库++3. 如果不是 git 仓库,则跳过此步骤并告知用户。++### 步骤 6:撰写草稿++1. 基于已批准的提纲,撰写完整博客草稿。++2. 严格按照 `OUTLINE.md` 的结构进行编写。++3. 包含:+ - 有吸引力的引言和开场钩子+ - 清晰的章节标题+ - 来自研究的支撑证据和示例+ - 段落之间自然流畅的过渡+ - 强有力的结尾和核心收获+ - **引用**:所有比较、统计数据和事实性陈述都必须引用原始来源++4. 将草稿保存为博客文章文件夹中的 `draft-v0.1.md`。++5. 格式:+ ```markdown+ # [博客文章标题]++ *[可选:副标题或标语]*++ [包含行内引用的完整正文...]++ ---++ ## 参考资料+ - [1] 来源 1 标题 - URL 或引用+ - [2] 来源 2 标题 - URL 或引用+ - [3] 来源 3 标题 - URL 或引用+ ```++6. **引用要求**:+ - 每个数据点、统计信息或比较都必须带有行内引用+ - 使用编号引用 [1]、[2] 等,或命名引用 [Source Name]+ - 在文末的参考资料部分链接这些引用+ - 示例:“研究表明,65% 的开发者更偏好 TypeScript [1]”+ - 示例:“React 在渲染速度上比 Vue 快 20% [React Benchmarks 2024]”++### 步骤 7:提交草稿(如果在 git 仓库中)++1. 检查是否处于 git 仓库中。++2. 如果是:+ - 暂存草稿文件+ - 使用如下提交信息创建 commit:`docs: Add draft v0.1 for blog post - [topic-name]`+ - 推送到远程仓库++3. 如果不是 git 仓库,则跳过并告知用户。++### 步骤 8:向用户展示草稿以供审阅++1. 向用户展示草稿内容。++2. 询问反馈:+ - 整体印象如何?+ - 哪些部分需要扩展或压缩?+ - 是否需要调整语气?+ - 是否缺少关键信息?+ - 有没有具体编辑或重写建议?++3. **等待用户回复。**++### 步骤 9:迭代或定稿++**如果用户要求修改:**+1. 记录所有修改请求+2. 返回步骤 6,并做以下调整:+ - 将版本号递增(v0.2、v0.3 等)+ - 纳入所有反馈+ - 保存为 `draft-v[X.Y].md`+ - 重复步骤 7-8++**如果用户批准:**+1. 确认最终草稿版本+2. 如用户要求,可重命名为 `final.md`+3. 总结博客文章创建过程:+ - 一共创建了多少个版本+ - 各版本之间的关键变化+ - 最终字数+ - 创建了哪些文件++## 版本跟踪++所有草稿都会以递增版本号保留:+- `draft-v0.1.md` - 初始草稿+- `draft-v0.2.md` - 第一轮反馈后+- `draft-v0.3.md` - 第二轮反馈后+- 以此类推++这可以跟踪博客文章的演变过程,并在需要时回退。++## 输出文件结构++```text+blog-posts/+└── YYYY-MM-DD-topic-name/+ ├── resources/+ │ ├── source-1-name.md+ │ ├── source-2-name.md+ │ └── ...+ ├── OUTLINE.md+ ├── draft-v0.1.md+ ├── draft-v0.2.md(如果有迭代)+ └── draft-v0.3.md(如果还有更多迭代)+```++## 质量建议++- **钩子**:以问题、令人惊讶的事实或贴近读者的场景开头+- **衔接**:每一段都要自然连接到下一段+- **证据**:用研究数据支撑观点+- **引用**:以下内容务必引用来源:+ - 所有统计数据和数值(例如:“根据 [Source],75% 的……”)+ - 对产品、服务或方案的比较(例如:“X 的速度比 Y 快 2 倍 [Source]”)+ - 关于市场趋势、研究发现或基准测试的事实性陈述+ - 使用行内引用,格式为:[Source Name] 或 [Author, Year]+- **语气**:全程保持一致+- **长度**:尊重目标字数+- **可读性**:使用短段落,并在适当位置使用项目符号+- **CTA**:以明确的行动号召或发人深省的问题收尾++## 备注++- 始终在上述需要确认的节点等待用户批准+- 保留所有草稿版本,方便追踪历史+- 如果提供了 URL,使用网络搜索获取最新信息+- 如果资源不足,询问用户补充,或建议进一步研究+- 根据目标读者调整语气(技术、通用、商业等)diff --git a/zh/03-skills/blog-draft/templates/draft-template.md b/zh/03-skills/blog-draft/templates/draft-template.mdnew file mode 100644index 0000000..c1dbb6d--- /dev/null+++ b/zh/03-skills/blog-draft/templates/draft-template.md@@ -0,0 +1,67 @@+# [博客文章标题]++*[副标题或标语 - 可选]*++**[作者名]** | [日期]++---++[开场钩子 - 立即抓住注意力]++[背景与上下文 - 说明为什么这件事重要]++[论点陈述 - 这篇文章要讲什么]++---++## [第一部分标题]++[本部分正文,保持清晰、吸引人的表达]++[加入证据、示例或数据来支撑观点]++> “来自研究的相关引文” - 来源++[过渡到下一部分]++---++## [第二部分标题]++[继续展开正文]++**关键收获:** [用加粗或提示块突出重要观点]++[更多支撑内容]++---++## [第三部分标题]++[如有需要,继续添加更多部分]++### 小节(如果需要)++[小节内容]++---++## 结论++[总结已覆盖的关键点]++[重申核心结论]++[行动号召或发人深省的结尾语]++---++## 参考资料++1. [来源标题](#)+2. [来源标题](#)+3. [来源标题](#)++---++*[作者简介或相关文章推荐 - 可选]*diff --git a/zh/03-skills/blog-draft/templates/outline-template.md b/zh/03-skills/blog-draft/templates/outline-template.mdnew file mode 100644index 0000000..1c8ec0e--- /dev/null+++ b/zh/03-skills/blog-draft/templates/outline-template.md@@ -0,0 +1,97 @@+# 博客文章提纲:[标题]++## 元信息++| 属性 | 值 |+|-----------|-------|+| **目标读者** | [写给谁看?] |+| **语气** | [正式/轻松/技术/对话式] |+| **目标长度** | [字数范围] |+| **核心结论** | [一句话说明读者应该记住什么] |+| **关键词** | [如有需要,可填写 SEO 关键词] |++---++## 建议结构++### 1. 引言 / 开场钩子++**开场钩子选项:**+- [ ] 与读者产生共鸣的问题+- [ ] 令人惊讶的统计或事实+- [ ] 一个简短故事或场景+- [ ] 大胆的陈述++**背景铺垫:**+- 需要提供的背景信息+- 为什么这个主题现在很重要++**论点陈述:**+- 明确说明这篇文章要讲什么++---++### 2. [部分标题]++**关键点:**+- 要点 A:[说明]+- 要点 B:[说明]++**支撑证据:**+- 来自 [source]:[相关数据/引文]++**过渡到下一部分:**+- [这部分如何与下一部分衔接]++---++### 3. [部分标题]++**关键点:**+- 要点 A:[说明]+- 要点 B:[说明]++**支撑证据:**+- 来自 [source]:[相关数据/引文]++**过渡到下一部分:**+- [这部分如何与下一部分衔接]++---++### 4. [部分标题](如有需要可继续添加)++**关键点:**+- 要点 A:[说明]+- 要点 B:[说明]++**支撑证据:**+- 来自 [source]:[相关数据/引文]++---++### 5. 结论++**关键点总结:**+- 回顾要点 1+- 回顾要点 2+- 回顾要点 3++**最终思考 / 行动号召:**+- [读者接下来应该做什么或思考什么?]++---++## 需要引用的来源++1. [来源名称](#) - 用于:[对应信息]+2. [来源名称](#) - 用于:[对应信息]+3. [来源名称](#) - 用于:[对应信息]++---++## 撰写备注++- [任何特别要求或限制]+- [需要强调的内容]+- [需要避免的内容]diff --git a/zh/03-skills/brand-voice/SKILL.md b/zh/03-skills/brand-voice/SKILL.mdnew file mode 100644index 0000000..9450d62--- /dev/null+++ b/zh/03-skills/brand-voice/SKILL.md@@ -0,0 +1,72 @@+---+name: brand-voice-consistency+description: 确保所有沟通内容都符合品牌语气和风格指南。适用于撰写营销文案、客户沟通、对外内容,或用户提到品牌语气、tone、写作风格的场景。+---++# 品牌语气技能++## 概览+此技能确保所有沟通内容在品牌语气、风格和信息传达上保持一致。++## 品牌定位++### 使命+帮助团队用 AI 自动化开发工作流++### 价值观+- **简洁**:把复杂的事情变简单+- **可靠**:执行稳健,结果稳定+- **赋能**:释放人的创造力++### 语气风格+- **友好但专业** - 平易近人,但不过于随意+- **清晰简洁** - 避免行话,用通俗方式解释技术概念+- **自信** - 体现我们知道自己在做什么+- **有同理心** - 理解用户需求和痛点++## 写作指南++### 应该做的 ✅+- 对读者使用“你”+- 使用主动语态:“Claude 会生成报告”,而不是“报告由 Claude 生成”+- 先讲价值主张+- 使用具体示例+- 句子保持在 20 个词以内+- 使用列表增强清晰度+- 包含行动号召++### 不应该做的 ❌+- 不要使用企业黑话+- 不要居高临下,也不要过度简化+- 不要使用“我们相信”或“我们认为”+- 不要全大写,除非为了强调+- 不要写成大段文字墙+- 不要默认读者具备技术背景++## 词汇++### ✅ 推荐用词+- Claude(不要写“the Claude AI”)+- 代码生成(不要写“auto-coding”)+- Agent(不要写“bot”)+- 简化流程(不要写“革命性改变”)+- 集成(不要写“synergize”)++### ❌ 避免用词+- “cutting-edge”(过度使用)+- “game-changer”(过于空泛)+- “leverage”(企业黑话)+- “utilize”(直接用“use”)+- “paradigm shift”(不够清晰)++## 示例++### ✅ 好示例+“Claude 能自动化你的代码审查流程。它不再需要你手动检查每个 PR,而是会审查安全性、性能和质量,每周为团队节省数小时。”++为什么好:价值明确、收益具体、行动导向强++### ❌ 坏示例+“Claude 利用前沿 AI 为软件开发提供全面解决方案。”++为什么不好:太空泛、企业黑话太多、没有具体价值diff --git a/zh/03-skills/brand-voice/tone-examples.md b/zh/03-skills/brand-voice/tone-examples.mdnew file mode 100644index 0000000..6b91328--- /dev/null+++ b/zh/03-skills/brand-voice/tone-examples.md@@ -0,0 +1,13 @@+# 品牌语气示例++## 激动人心的公告+“每周为代码审查节省 8 小时。Claude 会自动审查你的 PR。”++## 体现同理心的支持+“我们知道发布流程可能很有压力。Claude 会负责测试,你就不用担心了。”++## 自信的产品功能+“Claude 不只是给你代码建议。它理解你的架构,并保持一致性。”++## 教育型博客文章+“让我们一起看看 agents 如何改进代码审查工作流。以下是我们的发现……”diff --git a/zh/03-skills/claude-md/SKILL.md b/zh/03-skills/claude-md/SKILL.mdnew file mode 100644index 0000000..82db31b--- /dev/null+++ b/zh/03-skills/claude-md/SKILL.md@@ -0,0 +1,212 @@+---+name: claude-md+description: 按最佳实践创建或更新 CLAUDE.md 文件,以便为 AI agent 提供最优的项目入门上下文+---++## 用户输入++```text+$ARGUMENTS+```++在继续之前,你**必须**先考虑用户输入(如果不为空)。用户可能会指定:+- `create` - 从零创建新的 CLAUDE.md+- `update` - 改进已有的 CLAUDE.md+- `audit` - 分析并报告当前 CLAUDE.md 的质量+- 一个具体路径,用于创建或更新(例如 `src/api/CLAUDE.md` 代表目录级说明)++## 核心原则++**LLM 是无状态的**:CLAUDE.md 是每次对话中唯一会自动包含的文件。它是让 AI agent 了解代码库的主要入门文档。++### 黄金法则++1. **少即是多**:前沿 LLM 大约能遵循 150-200 条指令。Claude Code 的系统提示词本身已经占了大约 50 条,因此 CLAUDE.md 必须聚焦且简洁。++2. **只放通用信息**:只包含每次会话都适用的内容。任务特定的说明应该放在单独文件里。++3. **不要把 Claude 当成 lint 工具**:风格指南会膨胀上下文并降低指令遵循效果。应改用确定性工具(如 prettier、eslint 等)。++4. **绝不自动生成**:CLAUDE.md 是 AI harness 中杠杆最高的位置。应该经过认真思考后手工编写。++## 执行流程++### 1. 项目分析++首先分析当前项目状态:++1. 检查是否存在已有的 CLAUDE.md 文件:+ - 根目录:`./CLAUDE.md` 或 `.claude/CLAUDE.md`+ - 目录级:`**/CLAUDE.md`+ - 全局用户配置:`~/.claude/CLAUDE.md`++2. 识别项目结构:+ - 技术栈(语言、框架)+ - 项目类型(monorepo、单体应用、库)+ - 开发工具(包管理器、构建系统、测试运行器)++3. 查看已有文档:+ - README.md+ - CONTRIBUTING.md+ - package.json、pyproject.toml、Cargo.toml 等++### 2. 内容策略(WHAT, WHY, HOW)++围绕三个维度组织 CLAUDE.md:++#### WHAT - 技术与结构+- 技术栈概览+- 项目组织方式(对 monorepo 尤其重要)+- 关键目录及其用途++#### WHY - 目的与背景+- 项目是做什么的+- 为什么做出这些架构决策+- 每个主要组件负责什么++#### HOW - 工作流与约定+- 开发流程(bun vs node、pip vs uv 等)+- 测试流程和命令+- 验证与构建方法+- 关键“坑点”或非显而易见的要求++### 3. 渐进式披露策略++对于较大的项目,建议创建 `agent_docs/` 文件夹:++```text+agent_docs/+ |- building_the_project.md+ |- running_tests.md+ |- code_conventions.md+ |- architecture_decisions.md+```++在 CLAUDE.md 中引用这些文件,并写明:+```markdown+关于详细的构建说明,请参考 `agent_docs/building_the_project.md`+```++**重要**:使用 `file:line` 引用,而不是代码片段,以避免上下文过时。++### 4. 质量约束++创建或更新 CLAUDE.md 时:++1. **目标长度**:少于 300 行,理想情况下少于 100 行+2. **不要写风格规则**:移除任何 lint/format 相关说明+3. **不要写任务特定说明**:移到单独文件中+4. **不要写代码片段**:改用文件引用+5. **不要重复信息**:不要重复 package.json 或 README 中已有内容++### 5. 必备章节++一个结构良好的 CLAUDE.md 应包含:++```markdown+# 项目名称++一句简短的项目描述。++## 技术栈+- 主语言和版本+- 关键框架/库+- 数据库/存储(如有)++## 项目结构+[仅适用于 monorepo 或复杂结构]+- `apps/` - 应用入口+- `packages/` - 共享库++## 开发命令+- 安装:`command`+- 测试:`command`+- 构建:`command`++## 关键约定+[只保留非显而易见、高影响的约定]+- 约定 1,简要说明+- 约定 2,简要说明++## 已知问题 / 坑点+[经常让开发者踩坑的内容]+- 问题 1+- 问题 2+```++### 6. 需要避免的反模式++**不要包含:**+- 代码风格指南(交给 lint 工具)+- 如何使用 Claude 的说明+- 对显而易见模式的冗长解释+- 复制粘贴的代码示例+- 泛泛而谈的最佳实践(例如“写干净的代码”)+- 特定任务的说明+- 自动生成内容+- 大量 TODO 列表++### 7. 验证清单++在最终确定前,检查:++- [ ] 少于 300 行(最好少于 100 行)+- [ ] 每一行都适用于所有会话+- [ ] 没有风格/格式规则+- [ ] 没有代码片段(使用文件引用)+- [ ] 命令已经验证可用+- [ ] 对复杂项目使用了渐进式披露+- [ ] 已记录关键坑点+- [ ] 没有与 README.md 重复++## 输出格式++### 对于 `create` 或默认模式:++1. 分析项目+2. 按上述结构起草 CLAUDE.md+3. 向用户展示草稿以供审阅+4. 在获得批准后写入相应位置++### 对于 `update`:++1. 读取现有 CLAUDE.md+2. 按最佳实践进行审计+3. 识别:+ - 需要删除的内容(风格规则、代码片段、任务特定内容)+ - 需要压缩的内容+ - 缺失的重要信息+4. 向用户展示修改建议+5. 在获得批准后应用修改++### 对于 `audit`:++1. 读取现有 CLAUDE.md+2. 生成报告,包括:+ - 当前行数与目标的对比+ - 可通用于所有会话内容的百分比+ - 发现的反模式列表+ - 改进建议+3. 不要修改文件,只做报告++## AGENTS.md 处理++如果用户请求创建或更新 AGENTS.md:++AGENTS.md 用于定义专门的 agent 行为。与 CLAUDE.md(项目上下文)不同,AGENTS.md 定义的是:+- 自定义 agent 角色和能力+- agent 级约束与说明+- 多 agent 场景下的工作流定义++同样适用以下原则:+- 保持聚焦和简洁+- 使用渐进式披露+- 用外部文档引用代替内联内容++## 备注++- 在写入前始终验证命令是否可用+- 不确定时就不要写,少即是多+- 系统提醒会告诉 Claude,CLAUDE.md “可能相关,也可能不相关” - 噪音越多,越容易被忽略+- monorepo 最需要清晰的 WHAT/WHY/HOW 结构+- 目录级 CLAUDE.md 应该更聚焦diff --git a/zh/03-skills/code-review/SKILL.md b/zh/03-skills/code-review/SKILL.mdnew file mode 100644index 0000000..335aa6c--- /dev/null+++ b/zh/03-skills/code-review/SKILL.md@@ -0,0 +1,70 @@+---+name: code-review-specialist+description: 提供全面的代码审查能力,覆盖安全、性能和代码质量分析。适用于用户请求代码审查、代码质量评估、Pull Request 审查,或提到安全分析和性能优化时。+---++# 代码审查 Skill++这个 skill 提供全面的代码审查能力,重点关注:++1. **安全分析**+ - 身份验证 / 授权问题+ - 数据泄露风险+ - 注入漏洞+ - 密码学弱点+ - 敏感数据日志记录++2. **性能审查**+ - 算法效率(Big O 分析)+ - 内存优化+ - 数据库查询优化+ - 缓存机会+ - 并发问题++3. **代码质量**+ - SOLID 原则+ - 设计模式+ - 命名规范+ - 文档+ - 测试覆盖率++4. **可维护性**+ - 代码可读性+ - 函数长度(建议少于 50 行)+ - 圈复杂度+ - 依赖管理+ - 类型安全++## 审查模板++对每一段被审查的代码,请提供:++### 摘要+- 整体质量评分(1-5)+- 关键发现数量+- 建议优先关注的区域++### 关键问题(如有)+- **问题**:清晰描述+- **位置**:文件和行号+- **影响**:为什么这很重要+- **严重性**:Critical / High / Medium+- **修复**:代码示例++### 按类别列出发现++#### 安全性(如有问题)+列出安全漏洞及示例++#### 性能(如有问题)+列出性能问题,并说明复杂度++#### 质量(如有问题)+列出代码质量问题,并给出重构建议++#### 可维护性(如有问题)+列出可维护性问题,并给出改进建议++## 版本历史++- v1.0.0 (2024-12-10):首次发布,包含安全、性能、质量和可维护性分析diff --git a/zh/03-skills/code-review/templates/finding-template.md b/zh/03-skills/code-review/templates/finding-template.mdnew file mode 100644index 0000000..b96a8fd--- /dev/null+++ b/zh/03-skills/code-review/templates/finding-template.md@@ -0,0 +1,112 @@+# 代码审查问题记录模板++使用这个模板来记录代码审查中发现的每一个问题。++---++## 问题:[标题]++### 严重性+- [ ] Critical(阻塞发布)+- [ ] High(合并前应修复)+- [ ] Medium(尽快修复)+- [ ] Low(可选优化)++### 类别+- [ ] Security+- [ ] Performance+- [ ] Code Quality+- [ ] Maintainability+- [ ] Testing+- [ ] Design Pattern+- [ ] Documentation++### 位置+**文件:** `src/components/UserCard.tsx`++**行号:** 45-52++**函数 / 方法:** `renderUserDetails()`++### 问题描述++**是什么:** 描述这个问题是什么。++**为什么重要:** 说明影响,以及为什么需要修复。++**当前行为:** 展示有问题的代码或行为。++**期望行为:** 描述理想情况下应该发生什么。++### 代码示例++#### 当前(有问题)++```typescript+// 这里展示了 N+1 查询问题+const users = fetchUsers();+users.forEach(user => {+ const posts = fetchUserPosts(user.id); // 每个用户都发一次查询!+ renderUserPosts(posts);+});+```++#### 建议修复++```typescript+// 使用 JOIN 查询进行优化+const usersWithPosts = fetchUsersWithPosts();+usersWithPosts.forEach(({ user, posts }) => {+ renderUserPosts(posts);+});+```++### 影响分析++| 方面 | 影响 | 严重性 |+|--------|--------|--------|+| 性能 | 20 个用户就会产生 100+ 次查询 | High |+| 用户体验 | 页面加载缓慢 | High |+| 可扩展性 | 规模变大后会失效 | Critical |+| 可维护性 | 难以排查问题 | Medium |++### 相关问题++- `AdminUserList.tsx` 第 120 行有类似问题+- 相关 PR:#456+- 相关 issue:#789++### 额外资源++- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem)+- [Database Join Documentation](https://docs.example.com/joins)++### 审查者备注++- 这是这个代码库里常见的模式+- 可以考虑把它加入代码风格指南+- 也许值得提取一个辅助函数++### 作者回复(供反馈)++*由代码作者填写:*++- [ ] 已在提交 `abc123` 中修复+- [ ] 修复状态:Complete / In Progress / Needs Discussion+- [ ] 问题或疑虑:(描述)++---++## 统计信息(供审查者使用)++在审查多个问题时,请记录:++- **发现问题总数:** X+- **Critical:** X+- **High:** X+- **Medium:** X+- **Low:** X++**建议:** ✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion++**整体代码质量:** 1-5 星diff --git a/zh/03-skills/code-review/templates/review-checklist.md b/zh/03-skills/code-review/templates/review-checklist.mdnew file mode 100644index 0000000..22b58f5--- /dev/null+++ b/zh/03-skills/code-review/templates/review-checklist.md@@ -0,0 +1,47 @@+# 代码审查检查清单++## 安全检查+- [ ] 没有硬编码的凭据或密钥+- [ ] 所有用户输入都做了校验+- [ ] 使用参数化查询,防止 SQL 注入+- [ ] 所有会修改状态的操作都有 CSRF 防护+- [ ] 使用正确的转义,防止 XSS+- [ ] 受保护的端点有身份验证检查+- [ ] 资源访问有授权检查+- [ ] 密码使用安全哈希算法(bcrypt、argon2)+- [ ] 日志中没有敏感数据+- [ ] 强制使用 HTTPS++## 性能检查+- [ ] 没有 N+1 查询+- [ ] 索引使用合理+- [ ] 在有价值的地方做了缓存+- [ ] 主线程上没有阻塞操作+- [ ] 正确使用 async/await+- [ ] 大数据集已经分页+- [ ] 数据库连接已做连接池+- [ ] 正则表达式已优化+- [ ] 没有不必要的对象创建+- [ ] 没有内存泄漏++## 质量检查+- [ ] 函数少于 50 行+- [ ] 变量命名清晰+- [ ] 没有重复代码+- [ ] 错误处理合理+- [ ] 注释解释的是 WHY,而不是 WHAT+- [ ] 生产环境中没有 console.log+- [ ] 有类型检查(TypeScript / JSDoc)+- [ ] 遵循 SOLID 原则+- [ ] 正确应用设计模式+- [ ] 代码具备自解释性++## 测试检查+- [ ] 已编写单元测试+- [ ] 覆盖了边界情况+- [ ] 测试了错误场景+- [ ] 有集成测试+- [ ] 覆盖率大于 80%+- [ ] 没有不稳定测试+- [ ] 外部依赖已做 mock+- [ ] 测试名称清晰diff --git a/zh/03-skills/doc-generator/SKILL.md b/zh/03-skills/doc-generator/SKILL.mdnew file mode 100644index 0000000..1a7b067--- /dev/null+++ b/zh/03-skills/doc-generator/SKILL.md@@ -0,0 +1,76 @@+---+name: api-documentation-generator+description: 从源代码生成全面且准确的 API 文档。适用于创建或更新 API 文档、生成 OpenAPI 规范,或在用户提到 API 文档、端点或说明时使用。+---++# API 文档生成 Skill++## 可生成内容++- OpenAPI / Swagger 规范+- API 端点文档+- SDK 使用示例+- 集成指南+- 错误码参考+- 认证指南++## 文档结构++### 每个端点的写法++```markdown+## GET /api/v1/users/:id++### 描述+简要说明这个端点做什么++### 参数++| 名称 | 类型 | 必填 | 说明 |+|------|------|------|------|+| id | string | 是 | 用户 ID |++### 响应++**200 成功**+```json+{+ "id": "usr_123",+ "name": "John Doe",+ "email": "[email protected]",+ "created_at": "2025-01-15T10:30:00Z"+}+```++**404 未找到**+```json+{+ "error": "USER_NOT_FOUND",+ "message": "User does not exist"+}+```++### 示例++**cURL**+```bash+curl -X GET "https://api.example.com/api/v1/users/usr_123" \+ -H "Authorization: Bearer YOUR_TOKEN"+```++**JavaScript**+```javascript+const user = await fetch('/api/v1/users/usr_123', {+ headers: { 'Authorization': 'Bearer token' }+}).then(r => r.json());+```++**Python**+```python+response = requests.get(+ 'https://api.example.com/api/v1/users/usr_123',+ headers={'Authorization': 'Bearer token'}+)+user = response.json()+```+```diff --git a/zh/03-skills/refactor/SKILL.md b/zh/03-skills/refactor/SKILL.mdnew file mode 100644index 0000000..8edb205--- /dev/null+++ b/zh/03-skills/refactor/SKILL.md@@ -0,0 +1,426 @@+---+name: code-refactor+description: 基于 Martin Fowler 方法论的系统化代码重构 skill。适用于用户请求重构代码、改进代码结构、减少技术债、清理旧代码、消除 code smell 或提升可维护性时。这个 skill 采用分阶段、带研究与计划的安全增量实施方式。+---++# 代码重构 Skill++这是一个基于 Martin Fowler《Refactoring: Improving the Design of Existing Code》(第 2 版)的系统化代码重构方法。这个 skill 强调安全、渐进的修改,并由测试提供保障。++> “重构是在不改变软件外部行为的前提下,改进其内部结构的过程。” — Martin Fowler++## 核心原则++1. **保持行为不变**:外部行为必须保持一致+2. **小步前进**:每次只做很小、可测试的改动+3. **测试驱动**:测试是安全网+4. **持续进行**:重构是长期过程,不是一次性任务+5. **协作确认**:每个阶段都需要用户确认++## 工作流程总览++```+阶段 1:研究与分析+ ↓+阶段 2:测试覆盖评估+ ↓+阶段 3:识别代码异味+ ↓+阶段 4:创建重构计划+ ↓+阶段 5:增量实施+ ↓+阶段 6:评审与迭代+```++---++## 阶段 1:研究与分析++### 目标+- 理解代码库结构和用途+- 确定重构范围+- 收集业务需求背景++### 先向用户确认的问题+开始前先确认:++1. **范围**:哪些文件 / 模块 / 函数需要重构?+2. **目标**:你想解决什么问题?(可读性、性能、可维护性)+3. **约束**:有哪些区域不能改?+4. **时间压力**:这是否阻塞了其他工作?+5. **测试状态**:是否已有测试?是否通过?++### 行动+- [ ] 阅读并理解目标代码+- [ ] 识别依赖和集成点+- [ ] 记录当前架构+- [ ] 标记已有技术债迹象(TODO、FIXME)++### 输出+向用户汇报:+- 代码结构总结+- 识别出的问题区域+- 初步建议+- **请求继续执行的批准**++---++## 阶段 2:测试覆盖评估++### 为什么测试重要+> “没有测试的重构,就像没有安全带就开车。” — Martin Fowler++测试是安全重构的**关键前提**。没有测试,很容易引入 bug。++### 评估步骤++1. **检查现有测试**+ ```bash+ # 查找测试文件+ find . -name "*test*" -o -name "*spec*" | head -20+ ```++2. **运行现有测试**+ ```bash+ # JavaScript / TypeScript+ npm test++ # Python+ pytest -v++ # Java+ mvn test+ ```++3. **检查覆盖率(如果可用)**+ ```bash+ # JavaScript+ npm run test:coverage++ # Python+ pytest --cov=.+ ```++### 决策点:询问用户++**如果测试存在且通过:**+- 进入阶段 3++**如果测试缺失或不完整:**+给出选项:+1. 先写测试(推荐)+2. 在重构过程中逐步补测试+3. 不写测试直接继续(有风险,需要用户确认)++**如果测试失败:**+- 停止。先修复失败测试再重构+- 问用户:是否先修测试?++### 测试编写建议(如需要)++对每个要重构的函数,测试应覆盖:+- 正常路径+- 边界情况(空输入、null、边界值)+- 错误场景(非法输入、异常)++使用“红-绿-重构”循环:+1. 写失败测试(红)+2. 让它通过(绿)+3. 再重构++---++## 阶段 3:识别代码异味++### 什么是代码异味?+代码深层问题的表面症状。它们不一定是 bug,但说明代码设计可能有问题。++### 常见异味清单++完整目录见 [references/code-smells.md](references/code-smells.md)。++#### 快速参考++| 异味 | 迹象 | 影响 |+|-------|------|------|+| **长函数** | 函数超过 30-50 行 | 难以理解、测试和维护 |+| **重复代码** | 多处出现相同逻辑 | 修复需要改多处 |+| **大类** | 类承担了太多职责 | 违反单一职责原则 |+| **Feature Envy** | 一个方法更多依赖别的类的数据 | 封装性差 |+| **基础类型沉迷** | 过度使用基础类型而不是对象 | 缺少领域概念 |+| **长参数列表** | 方法参数超过 4 个 | 调用困难 |+| **数据泥团** | 一组数据总是一起出现 | 缺少抽象 |+| **switch 语句** | 复杂的 switch / if-else 链 | 难以扩展 |+| **臆想泛化** | “以防未来需要”提前设计 | 不必要的复杂度 |+| **死代码** | 未使用的代码 | 造成困惑和维护负担 |++### 分析步骤++1. **自动分析**(如果有脚本)+ ```bash+ python scripts/detect-smells.py <file>+ ```++2. **人工审查**+ - 系统地走读代码+ - 记录每个异味的位置和严重性+ - 按影响分类(Critical / High / Medium / Low)++3. **优先级排序**+ 优先关注会:+ - 阻塞当前开发的异味+ - 导致 bug 或混淆的异味+ - 影响最常变更代码路径的异味++### 输出:异味报告++向用户呈现:+- 识别出的异味及位置+- 每项的严重性评估+- 建议的优先级顺序+- **请求用户确认优先级**++---++## 阶段 4:创建重构计划++### 选择重构方式++针对每个异味,从目录中选择合适的重构手法。++完整列表见 [references/refactoring-catalog.md](references/refactoring-catalog.md)。++#### 异味到重构的映射++| 代码异味 | 推荐重构 |+|----------|----------|+| 长函数 | Extract Method、Replace Temp with Query |+| 重复代码 | Extract Method、Pull Up Method、Form Template Method |+| 大类 | Extract Class、Extract Subclass |+| Feature Envy | Move Method、Move Field |+| 基础类型沉迷 | Replace Primitive with Object、Replace Type Code with Class |+| 长参数列表 | Introduce Parameter Object、Preserve Whole Object |+| 数据泥团 | Extract Class、Introduce Parameter Object |+| switch 语句 | Replace Conditional with Polymorphism |+| 臆想泛化 | Collapse Hierarchy、Inline Class、Remove Dead Code |+| 死代码 | Remove Dead Code |++### 计划结构++使用 [templates/refactoring-plan.md](templates/refactoring-plan.md) 里的模板。++每项重构都要写明:+1. **Target**:将修改哪些代码+2. **Smell**:解决什么问题+3. **Refactoring**:采用哪种手法+4. **Steps**:详细微步骤+5. **Risks**:可能出什么问题+6. **Rollback**:如何回退++### 分阶段方法++**关键**:重构必须分阶段推进。++**阶段 A:快速收益**(低风险,高价值)+- 重命名变量以提升清晰度+- 提取明显重复的代码+- 删除死代码++**阶段 B:结构改进**(中风险)+- 从长函数中提取方法+- 引入参数对象+- 把方法移动到更合适的类++**阶段 C:架构改动**(高风险)+- 用多态替代条件分支+- 提取类+- 引入设计模式++### 决策点:把计划展示给用户++在开始实施前:+- 展示完整重构计划+- 解释每个阶段及其风险+- 获得每个阶段的明确批准+- **询问**:“是否继续执行阶段 A?”++---++## 阶段 5:增量实施++### 黄金法则+> “修改 → 测试 → 通过?→ 提交 → 下一步”++### 实施节奏++对每一步重构:++1. **预检查**+ - 测试通过(绿色)+ - 代码能编译++2. **只做一个小改动**+ - 按目录中的具体操作进行+ - 保持改动最小化++3. **验证**+ - 立刻运行测试+ - 检查编译错误++4. **如果测试通过(绿色)**+ - 用描述清晰的提交信息提交+ - 继续下一步++5. **如果测试失败(红色)**+ - 立刻停止+ - 撤销改动+ - 分析原因+ - 如有疑问,询问用户++### 提交策略++每次提交都应当:+- **原子性**:只包含一个逻辑改动+- **可回滚**:容易撤销+- **描述清楚**:提交信息明确++示例提交信息:+```+refactor: 从 processOrder() 中提取 calculateTotal()+refactor: 将 'x' 重命名为 'customerCount' 以提升清晰度+refactor: 删除未使用的 validateOldFormat() 方法+```++### 进度汇报++每个子阶段完成后,向用户汇报:+- 做了哪些改动+- 测试是否仍通过+- 遇到了什么问题+- **询问**:“继续下一批吗?”++---++## 阶段 6:评审与迭代++### 重构后检查清单++- [ ] 所有测试通过+- [ ] 没有新的警告 / 错误+- [ ] 代码编译成功+- [ ] 行为没有变化(手动验证)+- [ ] 必要时已更新文档+- [ ] 提交历史干净++### 指标对比++重构前后运行复杂度分析:+```bash+python scripts/analyze-complexity.py <file>+```++展示改进:+- 代码行数变化+- 圈复杂度变化+- 可维护性指标变化++### 用户评审++向用户展示最终结果:+- 所有变更摘要+- 重构前后代码对比+- 指标改善情况+- 剩余技术债+- **询问**:“你对这些改动满意吗?”++### 下一步++和用户讨论:+- 还要处理哪些异味?+- 是否安排下一次重构?+- 是否把类似修改应用到其他地方?++---++## 重要指南++### 何时暂停并询问++遇到以下情况时,务必暂停并和用户确认:+- 不确定业务逻辑+- 改动可能影响外部 API+- 测试覆盖不足+- 需要做重大的架构决策+- 风险上升+- 遇到意外复杂性++### 安全规则++1. **没有测试不要重构**(除非用户明确确认风险)+2. **不要做大改动**,拆成小步+3. **每次改动后都不要跳过测试**+4. **测试失败就不要继续**,先修复或回滚+5. **不要臆测**,不确定就问++### 不要做什么++- 不要把重构和新功能混在一起+- 不要在生产事故期间做重构+- 不要重构你看不懂的代码+- 不要过度设计,保持简单+- 不要一次性重构所有内容++---++## 快速上手示例++### 场景:长函数 + 重复逻辑++**重构前:**+```javascript+function processOrder(order) {+ // 150 行代码,包含:+ // - 重复验证逻辑+ // - 内联计算+ // - 多种职责混杂+}+```++**重构步骤:**++1. **确认测试存在**,覆盖 `processOrder()`+2. **提取** 验证逻辑为 `validateOrder()`+3. **测试** - 应该通过+4. **提取** 计算逻辑为 `calculateOrderTotal()`+5. **测试** - 应该通过+6. **提取** 通知逻辑为 `notifyCustomer()`+7. **测试** - 应该通过+8. **评审** - `processOrder()` 现在只负责串联 3 个清晰函数++**重构后:**+```javascript+function processOrder(order) {+ validateOrder(order);+ const total = calculateOrderTotal(order);+ notifyCustomer(order, total);+ return { order, total };+}+```++---++## 参考资料++- [代码异味目录](references/code-smells.md) - 代码异味完整清单+- [重构目录](references/refactoring-catalog.md) - 重构手法+- [重构计划模板](templates/refactoring-plan.md) - 计划模板++## 脚本++- `scripts/analyze-complexity.py` - 分析代码复杂度指标+- `scripts/detect-smells.py` - 自动检测 code smell++## 版本历史++- v1.0.0 (2025-01-15):首次发布,包含 Fowler 方法论、分阶段流程和用户确认点diff --git a/zh/03-skills/refactor/references/code-smells.md b/zh/03-skills/refactor/references/code-smells.mdnew file mode 100644index 0000000..8fb8f56--- /dev/null+++ b/zh/03-skills/refactor/references/code-smells.md@@ -0,0 +1,669 @@+# 代码异味目录++这是基于 Martin Fowler《Refactoring》(第 2 版)的代码异味参考目录。代码异味是更深层问题的表面症状,它们说明代码设计可能出了问题。++> “代码异味通常是系统中更深层问题的表面信号。” — Martin Fowler++---++## 过度膨胀类异味++表示对象或函数已经大到不再好用。++### 长函数++**迹象:**+- 函数超过 30-50 行+- 需要滚动才能看完整个函数+- 嵌套层级很多+- 需要注释来解释局部逻辑++**为什么不好:**+- 难理解+- 难单独测试+- 改动容易波及其他逻辑+- 重复逻辑容易藏在里面++**可用重构:**+- Extract Method+- Replace Temp with Query+- Introduce Parameter Object+- Replace Method with Method Object+- Decompose Conditional++**示例(重构前):**+```javascript+function processOrder(order) {+ // Validate order (20 lines)+ if (!order.items) throw new Error('No items');+ if (order.items.length === 0) throw new Error('Empty order');+ // ... more validation++ // Calculate totals (30 lines)+ let subtotal = 0;+ for (const item of order.items) {+ subtotal += item.price * item.quantity;+ }+ // ... tax, shipping, discounts++ // Send notifications (20 lines)+ // ... email logic+}+```++**示例(重构后):**+```javascript+function processOrder(order) {+ validateOrder(order);+ const totals = calculateOrderTotals(order);+ sendOrderNotifications(order, totals);+ return { order, totals };+}+```++---++### 大类++**迹象:**+- 实例变量很多(>7-10)+- 方法很多(>15-20)+- 类名含糊(Manager、Handler、Processor)+- 方法没有用到全部字段++**为什么不好:**+- 违反单一职责原则+- 难测试+- 改动会波及无关功能+- 难以复用局部能力++**可用重构:**+- Extract Class+- Extract Subclass+- Extract Interface++**检测参考:**+```text+代码行数 > 300+方法数量 > 15+字段数量 > 10+```++---++### 基础类型沉迷++**迹象:**+- 用基础类型表达领域概念(用 string 表示邮箱、用 int 表示金额)+- 使用基础类型数组,而不是对象+- 用字符串常量表示类型码+- 大量 magic number / magic string++**为什么不好:**+- 类型层面没有验证+- 逻辑散落在整个代码库里+- 容易传错值+- 缺少领域对象++**可用重构:**+- Replace Primitive with Object+- Replace Type Code with Class+- Replace Type Code with Subclasses+- Replace Type Code with State/Strategy++**示例(重构前):**+```javascript+const user = {+ email: '[email protected]', // 只是字符串+ phone: '1234567890', // 只是字符串+ status: 'active', // 魔法字符串+ balance: 10050 // 以分为单位的整数+};+```++**示例(重构后):**+```javascript+const user = {+ email: new Email('[email protected]'),+ phone: new PhoneNumber('1234567890'),+ status: UserStatus.ACTIVE,+ balance: Money.cents(10050)+};+```++---++### 长参数列表++**迹象:**+- 方法参数超过 4 个+- 一些参数总是一起出现+- 布尔参数改变方法行为+- 经常传 null / undefined++**为什么不好:**+- 难正确调用+- 参数顺序容易搞混+- 暗示方法做了太多事+- 难以增加新参数++**可用重构:**+- Introduce Parameter Object+- Preserve Whole Object+- Replace Parameter with Method Call+- Remove Flag Argument++**示例(重构前):**+```javascript+function createUser(firstName, lastName, email, phone,+ street, city, state, zip,+ isAdmin, isActive, createdBy) {+ // ...+}+```++**示例(重构后):**+```javascript+function createUser(personalInfo, address, options) {+ // personalInfo: { firstName, lastName, email, phone }+ // address: { street, city, state, zip }+ // options: { isAdmin, isActive, createdBy }+}+```++---++### 数据泥团++**迹象:**+- 同样的 3 个以上字段反复一起出现+- 参数总是成对或成组传递+- 类中的字段子集总是一起使用++**为什么不好:**+- 逻辑重复+- 缺少抽象+- 难扩展+- 暗示隐藏的类应该存在++**可用重构:**+- Extract Class+- Introduce Parameter Object+- Preserve Whole Object++**示例:**+```javascript+// 数据泥团:坐标 (x, y, z)+function movePoint(x, y, z, dx, dy, dz) { }+function scalePoint(x, y, z, factor) { }+function distanceBetween(x1, y1, z1, x2, y2, z2) { }++// 提取 Point3D 类+class Point3D {+ constructor(x, y, z) { }+ move(delta) { }+ scale(factor) { }+ distanceTo(other) { }+}+```++---++## 面向对象滥用类异味++表示 OOP 原则没有被正确使用。++### switch 语句++**迹象:**+- 长 switch/case 或 if/else 链+- 多处出现相同 switch+- 按类型码分支+- 新增 case 时需要改很多地方++**为什么不好:**+- 违反开放 / 封闭原则+- 改动会扩散到所有 switch 位置+- 难扩展+- 往往说明缺少多态++**可用重构:**+- Replace Conditional with Polymorphism+- Replace Type Code with Subclasses+- Replace Type Code with State/Strategy++**示例(重构前):**+```javascript+function calculatePay(employee) {+ switch (employee.type) {+ case 'hourly':+ return employee.hours * employee.rate;+ case 'salaried':+ return employee.salary / 12;+ case 'commissioned':+ return employee.sales * employee.commission;+ }+}+```++**示例(重构后):**+```javascript+class HourlyEmployee {+ calculatePay() {+ return this.hours * this.rate;+ }+}++class SalariedEmployee {+ calculatePay() {+ return this.salary / 12;+ }+}+```++---++### 临时字段++**迹象:**+- 实例变量只在部分方法中使用+- 字段只在某些条件下设置+- 某些情况初始化过程很复杂++**为什么不好:**+- 容易混淆:字段存在但可能为 null+- 对象状态难理解+- 说明条件逻辑被隐藏了++**可用重构:**+- Extract Class+- Introduce Null Object+- Replace Temp Field with Local++---++### 拒绝遗赠++**迹象:**+- 子类没有用到继承来的方法 / 数据+- 子类重写方法只是为了不做事+- 继承被当成代码复用,而不是真正的 IS-A++**为什么不好:**+- 抽象不对+- 违反里氏替换原则+- 继承层次误导人++**可用重构:**+- Push Down Method / Field+- Replace Subclass with Delegate+- Replace Inheritance with Delegation++---++### 不同接口的相似类++**迹象:**+- 两个类做的事情差不多+- 同一个概念却用了不同方法名+- 理论上可以互换使用++**为什么不好:**+- 重复实现+- 没有公共接口+- 难切换++**可用重构:**+- Rename Method+- Move Method+- Extract Superclass+- Extract Interface++---++## 变更阻碍类异味++这类异味会让改动变得困难,一次改动需要波及很多地方。++### 发散式变化++**迹象:**+- 一个类因为很多不同原因而被修改+- 不同区域的变更都会触发同一个类的编辑+- 类变成了“上帝类”++**为什么不好:**+- 违反单一职责原则+- 变更频率高+- 容易产生合并冲突++**可用重构:**+- Extract Class+- Extract Superclass+- Extract Subclass++**示例:**+一个 `User` 类同时因为这些原因变化:+- 身份验证变化+- 个人资料变化+- 计费变化+- 通知变化++→ 可以拆成:`AuthService`、`ProfileService`、`BillingService`、`NotificationService`++---++### 散弹式修改++**迹象:**+- 一个改动需要编辑很多类+- 一个小功能要触碰 10+ 个文件+- 改动分散,难以一次找全++**为什么不好:**+- 很容易漏改+- 耦合高+- 容易出错++**可用重构:**+- Move Method+- Move Field+- Inline Class++**检测参考:**+如果新增一个字段需要改 5 个以上文件,就要警惕。++---++### 平行继承体系++**迹象:**+- 在一个继承体系中创建子类,另一个体系也得跟着创建+- 类前缀相似(如 `DatabaseOrder`、`DatabaseProduct`)++**为什么不好:**+- 维护成本翻倍+- 两个层次之间耦合+- 容易漏掉一边++**可用重构:**+- Move Method+- Move Field+- 消除其中一个层次++---++## 可舍弃类异味++表示有些东西已经不必要了,应该移除。++### 注释过多++**迹象:**+- 注释在解释代码“做了什么”+- 注释掉的代码+- 长期存在的 TODO / FIXME+- 注释里带道歉语气++**为什么不好:**+- 注释会过时+- 代码本身应该能自解释+- 死代码会造成混乱++**可用重构:**+- Extract Method(让方法名解释意图)+- Rename(通过命名提升清晰度)+- 删除注释掉的代码+- Introduce Assertion++**好与坏的注释:**+```javascript+// BAD: 解释做了什么+// 遍历用户并检查是否活跃+for (const user of users) {+ if (user.status === 'active') { }+}++// GOOD: 解释为什么+// 只保留活跃用户,未活跃用户由清理任务处理+const activeUsers = users.filter(u => u.isActive);+```++---++### 重复代码++**迹象:**+- 多处出现相同代码+- 只有少量差异的相似代码+- 复制粘贴模式++**为什么不好:**+- 修复要改多处+- 容易不一致+- 代码库臃肿++**可用重构:**+- Extract Method+- Extract Class+- Pull Up Method(在继承层次中)+- Form Template Method++**检测规则:**+任何重复 3 次以上的代码都应该考虑提取。++---++### 惰性类++**迹象:**+- 类做的事情不足以支撑它的存在+- 只是一个没有增值的包装器+- 过度设计的产物++**为什么不好:**+- 增加维护开销+- 多了一层没必要的间接+- 有复杂度但没收益++**可用重构:**+- Inline Class+- Collapse Hierarchy++---++### 死代码++**迹象:**+- 无法到达的代码+- 未使用的变量 / 方法 / 类+- 注释掉的代码+- 位于不可能条件分支后的代码++**为什么不好:**+- 造成困惑+- 增加维护负担+- 降低理解速度++**可用重构:**+- Remove Dead Code+- Safe Delete++**检测:**+```bash+# 查找未使用的导出+# 查找未引用的函数+# IDE 的“unused”警告+```++---++### 臆想泛化++**迹象:**+- 只有一个子类的抽象类+- 为“未来可能需要”而加的未使用参数+- 只是转发的函数+- 为一个用例设计的“框架”++**为什么不好:**+- 复杂度没有收益+- 违背 YAGNI+- 更难理解++**可用重构:**+- Collapse Hierarchy+- Inline Class+- Remove Parameter+- Rename Method++---++## 耦合类异味++表示类之间耦合过强。++### Feature Envy++**迹象:**+- 一个方法使用别的类的数据比自己更多+- 对另一个对象调用很多 getter+- 数据和行为分离++**为什么不好:**+- 行为放错地方了+- 封装性差+- 难维护++**可用重构:**+- Move Method+- Move Field+- Extract Method(然后移动)++**示例(重构前):**+```javascript+class Order {+ getDiscountedPrice(customer) {+ // 这里大量使用 customer 数据+ if (customer.loyaltyYears > 5) {+ return this.price * customer.discountRate;+ }+ return this.price;+ }+}+```++**示例(重构后):**+```javascript+class Customer {+ getDiscountedPriceFor(price) {+ if (this.loyaltyYears > 5) {+ return price * this.discountRate;+ }+ return price;+ }+}+```++---++### 不恰当的亲密++**迹象:**+- 类之间互相访问私有细节+- 双向引用很多+- 子类知道父类太多细节++**为什么不好:**+- 耦合高+- 改一边会连带另一边+- 难单独修改++**可用重构:**+- Move Method+- Move Field+- Change Bidirectional to Unidirectional+- Extract Class+- Hide Delegate++---++### 消息链++**迹象:**+- 方法调用链很长:`a.getB().getC().getD().getValue()`+- 客户端依赖导航结构+- “火车残骸”式代码++**为什么不好:**+- 很脆弱,任何一层变动都会坏+- 违反迪米特法则+- 绑定到对象结构++**可用重构:**+- Hide Delegate+- Extract Method+- Move Method++**示例:**+```javascript+// 差:消息链+const managerName = employee.getDepartment().getManager().getName();++// 更好:隐藏委派+const managerName = employee.getManagerName();+```++---++### 中间人++**迹象:**+- 类只是把调用转发给另一个类+- 一半以上的方法都是委派+- 没有额外价值++**为什么不好:**+- 多了一层没必要的间接+- 维护成本更高+- 架构令人困惑++**可用重构:**+- Remove Middle Man+- Inline Method++---++## 严重性指南++| 严重性 | 说明 | 处理方式 |+|--------|------|---------|+| **Critical** | 阻塞开发,导致 bug | 立刻修复 |+| **High** | 明显增加维护负担 | 本迭代修复 |+| **Medium** | 有问题但还能接受 | 近期计划修复 |+| **Low** | 小问题 | 视情况顺手修 |++---++## 快速检测清单++扫描代码时使用这个清单:++- [ ] 有没有超过 30 行的函数?+- [ ] 有没有超过 300 行的类?+- [ ] 有没有参数超过 4 个的函数?+- [ ] 有没有重复代码块?+- [ ] 有没有按类型码分支的 switch/case?+- [ ] 有没有未使用的代码?+- [ ] 有没有大量使用其他类数据的方法?+- [ ] 有没有很长的方法调用链?+- [ ] 有没有解释“是什么”而不是“为什么”的注释?+- [ ] 有没有应该封装成对象的基础类型?++---++## 延伸阅读++- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (2nd ed.)+- Kerievsky, J. (2004). *Refactoring to Patterns*+- Feathers, M. (2004). *Working Effectively with Legacy Code*diff --git a/zh/03-skills/refactor/references/refactoring-catalog.md b/zh/03-skills/refactor/references/refactoring-catalog.mdnew file mode 100644index 0000000..5fd8b95--- /dev/null+++ b/zh/03-skills/refactor/references/refactoring-catalog.md@@ -0,0 +1,1023 @@+# 重构目录++这是 Martin Fowler《Refactoring》(第 2 版)中的一份精选重构目录。每个重构都包含动机、操作步骤和示例。++> “重构由它的操作步骤来定义,也就是你执行这个变化时遵循的精确过程。” — Martin Fowler++---++## 如何使用这个目录++1. **识别异味**:先用代码异味目录定位问题+2. **找到对应重构**:在这里查找匹配的手法+3. **按步骤执行**:一步一步来+4. **每步都测试**:确保行为不变++**黄金法则**:如果某一步超过 10 分钟,就把它拆得更小。++---++## 最常见的重构++### Extract Method++**何时使用**:长函数、重复代码、需要为概念命名++**动机**:把一段代码抽成一个名字能说明意图的方法。++**步骤**:+1. 创建一个新方法,名字应描述“做什么”而不是“怎么做”+2. 把代码片段复制到新方法里+3. 检查片段里用了哪些局部变量+4. 把局部变量作为参数传入,或在方法内声明+5. 正确处理返回值+6. 用新方法调用替换原始片段+7. 测试++**前:**+```javascript+function printOwing(invoice) {+ let outstanding = 0;++ console.log("***********************");+ console.log("**** Customer Owes ****");+ console.log("***********************");++ // Calculate outstanding+ for (const order of invoice.orders) {+ outstanding += order.amount;+ }++ // Print details+ console.log(`name: ${invoice.customer}`);+ console.log(`amount: ${outstanding}`);+}+```++**后:**+```javascript+function printOwing(invoice) {+ printBanner();+ const outstanding = calculateOutstanding(invoice);+ printDetails(invoice, outstanding);+}++function printBanner() {+ console.log("***********************");+ console.log("**** Customer Owes ****");+ console.log("***********************");+}++function calculateOutstanding(invoice) {+ return invoice.orders.reduce((sum, order) => sum + order.amount, 0);+}++function printDetails(invoice, outstanding) {+ console.log(`name: ${invoice.customer}`);+ console.log(`amount: ${outstanding}`);+}+```++---++### Inline Method++**何时使用**:方法体和名字一样清楚,或者只是多余转发++**动机**:当方法没有额外价值时,去掉不必要的间接层。++**步骤**:+1. 确认这个方法不是多态方法+2. 找到所有调用点+3. 用方法体替换每个调用+4. 每替换一次就测试一次+5. 删除方法定义++**前:**+```javascript+function getRating(driver) {+ return moreThanFiveLateDeliveries(driver) ? 2 : 1;+}++function moreThanFiveLateDeliveries(driver) {+ return driver.numberOfLateDeliveries > 5;+}+```++**后:**+```javascript+function getRating(driver) {+ return driver.numberOfLateDeliveries > 5 ? 2 : 1;+}+```++---++### Extract Variable++**何时使用**:复杂表达式难以理解++**动机**:给复杂表达式的一部分起名字。++**步骤**:+1. 确保表达式没有副作用+2. 声明一个不可变变量+3. 将表达式结果赋给变量+4. 用变量替换原表达式+5. 测试++**前:**+```javascript+return order.quantity * order.itemPrice -+ Math.max(0, order.quantity - 500) * order.itemPrice * 0.05 ++ Math.min(order.quantity * order.itemPrice * 0.1, 100);+```++**后:**+```javascript+const basePrice = order.quantity * order.itemPrice;+const quantityDiscount = Math.max(0, order.quantity - 500) * order.itemPrice * 0.05;+const shipping = Math.min(basePrice * 0.1, 100);+return basePrice - quantityDiscount + shipping;+```++---++### Inline Variable++**何时使用**:变量名没有比表达式更清楚++**动机**:移除没必要的间接层。++**步骤**:+1. 检查右侧表达式没有副作用+2. 如果变量不是不可变的,先改成不可变并测试+3. 找到第一次引用并替换成表达式+4. 测试+5. 对所有引用重复+6. 删除变量声明和赋值+7. 测试++---++### Rename Variable++**何时使用**:名字没有清楚表达用途++**动机**:好名字是清晰代码的基础。++**步骤**:+1. 如果变量使用范围很广,先考虑封装+2. 找到所有引用+3. 逐个修改引用+4. 测试++**提示**:+- 使用能体现意图的名字+- 避免缩写+- 使用领域术语++```javascript+// Bad+const d = 30;+const x = users.filter(u => u.a);++// Good+const daysSinceLastLogin = 30;+const activeUsers = users.filter(user => user.isActive);+```++---++### Change Function Declaration++**何时使用**:函数名不能清楚说明用途,参数也需要变化++**动机**:好函数名能让代码自解释。++**步骤(简单情况)**:+1. 删除不需要的参数+2. 修改函数名+3. 添加需要的参数+4. 测试++**步骤(迁移式,适用于复杂改动)**:+1. 如果要删除参数,确保它没有被使用+2. 创建一个新函数,声明符合新设计+3. 让旧函数调用新函数+4. 测试+5. 让调用方逐步改用新函数+6. 每改一个调用点就测试+7. 删除旧函数++**前:**+```javascript+function circum(radius) {+ return 2 * Math.PI * radius;+}+```++**后:**+```javascript+function circumference(radius) {+ return 2 * Math.PI * radius;+}+```++---++### Encapsulate Variable++**何时使用**:多个地方直接访问某个数据++**动机**:为数据访问提供明确入口。++**步骤**:+1. 创建 getter 和 setter+2. 找到所有引用+3. 用 getter 替换读取+4. 用 setter 替换写入+5. 每次改动后测试+6. 降低变量可见性++**前:**+```javascript+let defaultOwner = { firstName: "Martin", lastName: "Fowler" };++// Used in many places+spaceship.owner = defaultOwner;+```++**后:**+```javascript+let defaultOwnerData = { firstName: "Martin", lastName: "Fowler" };++function defaultOwner() { return defaultOwnerData; }+function setDefaultOwner(arg) { defaultOwnerData = arg; }++spaceship.owner = defaultOwner();+```++---++### Introduce Parameter Object++**何时使用**:一组参数经常一起出现++**动机**:把自然属于一起的数据打包起来。++**步骤**:+1. 为这组参数创建一个新类 / 结构+2. 测试+3. 用 Change Function Declaration 引入新对象+4. 测试+5. 逐个移除参数,改用对象字段+6. 每次移除后测试++**前:**+```javascript+function amountInvoiced(startDate, endDate) { ... }+function amountReceived(startDate, endDate) { ... }+function amountOverdue(startDate, endDate) { ... }+```++**后:**+```javascript+class DateRange {+ constructor(start, end) {+ this.start = start;+ this.end = end;+ }+}++function amountInvoiced(dateRange) { ... }+function amountReceived(dateRange) { ... }+function amountOverdue(dateRange) { ... }+```++---++### Combine Functions into Class++**何时使用**:多个函数操作同一份数据++**动机**:把函数和它操作的数据放到一起。++**步骤**:+1. 对公共数据先做 Encapsulate Record+2. 把每个函数移动到类里+3. 每移动一次就测试+4. 用类字段替代数据参数++**前:**+```javascript+function base(reading) { ... }+function taxableCharge(reading) { ... }+function calculateBaseCharge(reading) { ... }+```++**后:**+```javascript+class Reading {+ constructor(data) { this._data = data; }++ get base() { ... }+ get taxableCharge() { ... }+ get calculateBaseCharge() { ... }+}+```++---++### Split Phase++**何时使用**:代码在处理两件不同的事++**动机**:把代码拆成边界清晰的两个阶段。++**步骤**:+1. 为第二阶段创建新函数+2. 测试+3. 在两个阶段之间引入中间数据结构+4. 测试+5. 把第一阶段提取成独立函数+6. 测试++**前:**+```javascript+function priceOrder(product, quantity, shippingMethod) {+ const basePrice = product.basePrice * quantity;+ const discount = Math.max(quantity - product.discountThreshold, 0)+ * product.basePrice * product.discountRate;+ const shippingPerCase = (basePrice > shippingMethod.discountThreshold)+ ? shippingMethod.discountedFee : shippingMethod.feePerCase;+ const shippingCost = quantity * shippingPerCase;+ return basePrice - discount + shippingCost;+}+```++**后:**+```javascript+function priceOrder(product, quantity, shippingMethod) {+ const priceData = calculatePricingData(product, quantity);+ return applyShipping(priceData, shippingMethod);+}++function calculatePricingData(product, quantity) {+ const basePrice = product.basePrice * quantity;+ const discount = Math.max(quantity - product.discountThreshold, 0)+ * product.basePrice * product.discountRate;+ return { basePrice, quantity, discount };+}++function applyShipping(priceData, shippingMethod) {+ const shippingPerCase = (priceData.basePrice > shippingMethod.discountThreshold)+ ? shippingMethod.discountedFee : shippingMethod.feePerCase;+ const shippingCost = priceData.quantity * shippingPerCase;+ return priceData.basePrice - priceData.discount + shippingCost;+}+```++---++## 移动特性++### Move Method++**何时使用**:方法更依赖另一个类的数据而不是自己类的数据++**动机**:把函数放到它最依赖的数据所在的类里。++**步骤**:+1. 检查方法使用到的所有程序元素+2. 确认方法不是多态的+3. 把方法复制到目标类+4. 调整上下文+5. 让原方法委托给目标方法+6. 测试+7. 视情况删除原方法++---++### Move Field++**何时使用**:字段更多被另一个类使用++**动机**:让数据和使用它的函数靠在一起。++**步骤**:+1. 如果还没有,先封装字段+2. 测试+3. 在目标类中创建字段+4. 把引用改成使用目标字段+5. 测试+6. 删除原字段++---++### Move Statements into Function++**何时使用**:相同代码总是跟着函数调用一起出现++**动机**:把重复语句移入函数,去掉重复。++**步骤**:+1. 如果还没有,先把重复代码提取成函数+2. 把语句移入函数+3. 测试+4. 如果调用方不再需要独立语句,就删除它们++---++### Move Statements to Callers++**何时使用**:不同调用方需要不同的行为++**动机**:当行为需要差异化时,把它从函数里移出去。++**步骤**:+1. 先对要移动的代码做 Extract Method+2. 再对原函数做 Inline Method+3. 删除被内联后的调用+4. 把提取出的代码移到各个调用方+5. 测试++---++## 数据组织++### Replace Primitive with Object++**何时使用**:数据项需要的不只是简单值++**动机**:把数据和行为封装在一起。++**步骤**:+1. 先做 Encapsulate Variable+2. 创建一个简单值对象+3. 修改 setter,让它创建新实例+4. 修改 getter,让它返回值+5. 测试+6. 给新类增加更丰富的行为++**前:**+```javascript+class Order {+ constructor(data) {+ this.priority = data.priority; // string: "high", "rush", etc.+ }+}++// Usage+if (order.priority === "high" || order.priority === "rush") { ... }+```++**后:**+```javascript+class Priority {+ constructor(value) {+ if (!Priority.legalValues().includes(value))+ throw new Error(`Invalid priority: ${value}`);+ this._value = value;+ }++ static legalValues() { return ['low', 'normal', 'high', 'rush']; }+ get value() { return this._value; }++ higherThan(other) {+ return Priority.legalValues().indexOf(this._value) >+ Priority.legalValues().indexOf(other._value);+ }+}++// Usage+if (order.priority.higherThan(new Priority("normal"))) { ... }+```++---++### Replace Temp with Query++**何时使用**:临时变量保存的是一个表达式结果++**动机**:把表达式提取成函数,让代码更清晰。++**步骤**:+1. 确保变量只被赋值一次+2. 把赋值右侧提取成一个方法+3. 用方法调用替换临时变量引用+4. 测试+5. 删除临时变量声明和赋值++**前:**+```javascript+const basePrice = this._quantity * this._itemPrice;+if (basePrice > 1000) {+ return basePrice * 0.95;+} else {+ return basePrice * 0.98;+}+```++**后:**+```javascript+get basePrice() {+ return this._quantity * this._itemPrice;+}++// In the method+if (this.basePrice > 1000) {+ return this.basePrice * 0.95;+} else {+ return this.basePrice * 0.98;+}+```++---++## 简化条件逻辑++### Decompose Conditional++**何时使用**:复杂条件语句++**动机**:把条件和分支动作分别提取出来,让意图更清楚。++**步骤**:+1. 对条件做 Extract Method+2. 对 then 分支做 Extract Method+3. 对 else 分支也做 Extract Method(如果有)++**前:**+```javascript+if (!aDate.isBefore(plan.summerStart) && !aDate.isAfter(plan.summerEnd)) {+ charge = quantity * plan.summerRate;+} else {+ charge = quantity * plan.regularRate + plan.regularServiceCharge;+}+```++**后:**+```javascript+if (isSummer(aDate, plan)) {+ charge = summerCharge(quantity, plan);+} else {+ charge = regularCharge(quantity, plan);+}++function isSummer(date, plan) {+ return !date.isBefore(plan.summerStart) && !date.isAfter(plan.summerEnd);+}++function summerCharge(quantity, plan) {+ return quantity * plan.summerRate;+}++function regularCharge(quantity, plan) {+ return quantity * plan.regularRate + plan.regularServiceCharge;+}+```++---++### Consolidate Conditional Expression++**何时使用**:多个条件最后都返回同一个结果++**动机**:让人一眼看出这些条件其实是一道检查。++**步骤**:+1. 确认条件没有副作用+2. 用 and / or 合并条件+3. 视情况对合并后的条件做 Extract Method++**前:**+```javascript+if (employee.seniority < 2) return 0;+if (employee.monthsDisabled > 12) return 0;+if (employee.isPartTime) return 0;+```++**后:**+```javascript+if (isNotEligibleForDisability(employee)) return 0;++function isNotEligibleForDisability(employee) {+ return employee.seniority < 2 ||+ employee.monthsDisabled > 12 ||+ employee.isPartTime;+}+```++---++### Replace Nested Conditional with Guard Clauses++**何时使用**:深层嵌套条件让流程难以追踪++**动机**:用 guard clause 提前返回,让正常流程更清楚。++**步骤**:+1. 找出特殊情况+2. 用提前返回的 guard clause 替换它们+3. 每改一步就测试++**前:**+```javascript+function payAmount(employee) {+ let result;+ if (employee.isSeparated) {+ result = { amount: 0, reasonCode: "SEP" };+ } else {+ if (employee.isRetired) {+ result = { amount: 0, reasonCode: "RET" };+ } else {+ result = calculateNormalPay(employee);+ }+ }+ return result;+}+```++**后:**+```javascript+function payAmount(employee) {+ if (employee.isSeparated) return { amount: 0, reasonCode: "SEP" };+ if (employee.isRetired) return { amount: 0, reasonCode: "RET" };+ return calculateNormalPay(employee);+}+```++---++### Replace Conditional with Polymorphism++**何时使用**:按类型分支的 switch / 条件逻辑++**动机**:让对象自己处理自己的行为。++**步骤**:+1. 创建类层次(如果还没有)+2. 用 Factory Function 创建对象+3. 把条件逻辑移到超类方法里+4. 给每种情况创建子类方法+5. 删除原条件++**前:**+```javascript+function plumages(birds) {+ return birds.map(b => plumage(b));+}++function plumage(bird) {+ switch (bird.type) {+ case 'EuropeanSwallow':+ return "average";+ case 'AfricanSwallow':+ return (bird.numberOfCoconuts > 2) ? "tired" : "average";+ case 'NorwegianBlueParrot':+ return (bird.voltage > 100) ? "scorched" : "beautiful";+ default:+ return "unknown";+ }+}+```++**后:**+```javascript+class Bird {+ get plumage() { return "unknown"; }+}++class EuropeanSwallow extends Bird {+ get plumage() { return "average"; }+}++class AfricanSwallow extends Bird {+ get plumage() {+ return (this.numberOfCoconuts > 2) ? "tired" : "average";+ }+}++class NorwegianBlueParrot extends Bird {+ get plumage() {+ return (this.voltage > 100) ? "scorched" : "beautiful";+ }+}++function createBird(data) {+ switch (data.type) {+ case 'EuropeanSwallow': return new EuropeanSwallow(data);+ case 'AfricanSwallow': return new AfricanSwallow(data);+ case 'NorwegianBlueParrot': return new NorwegianBlueParrot(data);+ default: return new Bird(data);+ }+}+```++---++### Introduce Special Case (Null Object)++**何时使用**:重复出现 null 检查++**动机**:返回一个特殊对象来处理特殊情况。++**步骤**:+1. 创建一个具备预期接口的特殊情况类+2. 增加 isSpecialCase 检查+3. 引入工厂方法+4. 用特殊对象替换 null 检查+5. 测试++**前:**+```javascript+const customer = site.customer;+// ... many places checking+if (customer === "unknown") {+ customerName = "occupant";+} else {+ customerName = customer.name;+}+```++**后:**+```javascript+class UnknownCustomer {+ get name() { return "occupant"; }+ get billingPlan() { return registry.defaultPlan; }+}++// Factory method+function customer(site) {+ return site.customer === "unknown"+ ? new UnknownCustomer()+ : site.customer;+}++// Usage - no null checks needed+const customerName = customer.name;+```++---++## 重构 API++### Separate Query from Modifier++**何时使用**:函数既返回值又有副作用++**动机**:明确哪些操作会产生副作用。++**步骤**:+1. 创建新的查询函数+2. 复制原函数的返回逻辑+3. 修改原函数,让它只负责副作用+4. 替换依赖返回值的调用点+5. 测试++**前:**+```javascript+function alertForMiscreant(people) {+ for (const p of people) {+ if (p === "Don") {+ setOffAlarms();+ return "Don";+ }+ if (p === "John") {+ setOffAlarms();+ return "John";+ }+ }+ return "";+}+```++**后:**+```javascript+function findMiscreant(people) {+ for (const p of people) {+ if (p === "Don") return "Don";+ if (p === "John") return "John";+ }+ return "";+}++function alertForMiscreant(people) {+ if (findMiscreant(people) !== "") setOffAlarms();+}+```++---++### Parameterize Function++**何时使用**:有多个做类似事情但数值不同的函数++**动机**:通过参数化减少重复。++**步骤**:+1. 选择一个函数+2. 为变化的字面值增加参数+3. 修改函数体使用该参数+4. 测试+5. 让调用方改用参数化版本+6. 删除不再使用的旧函数++**前:**+```javascript+function tenPercentRaise(person) {+ person.salary = person.salary * 1.10;+}++function fivePercentRaise(person) {+ person.salary = person.salary * 1.05;+}+```++**后:**+```javascript+function raise(person, factor) {+ person.salary = person.salary * (1 + factor);+}++// Usage+raise(person, 0.10);+raise(person, 0.05);+```++---++### Remove Flag Argument++**何时使用**:布尔参数改变函数行为++**动机**:通过拆分成明确函数,让行为更清楚。++**步骤**:+1. 针对不同旗标值创建显式函数+2. 替换每个调用点+3. 每次改动后测试+4. 删除原函数++**前:**+```javascript+function bookConcert(customer, isPremium) {+ if (isPremium) {+ // premium booking logic+ } else {+ // regular booking logic+ }+}++bookConcert(customer, true);+bookConcert(customer, false);+```++**后:**+```javascript+function bookPremiumConcert(customer) {+ // premium booking logic+}++function bookRegularConcert(customer) {+ // regular booking logic+}++bookPremiumConcert(customer);+bookRegularConcert(customer);+```++---++## 继承相关++### Pull Up Method++**何时使用**:多个子类里有相同方法++**动机**:去掉类层次中的重复。++**步骤**:+1. 检查方法是否完全相同+2. 确认签名一致+3. 在超类中新建方法+4. 从一个子类复制实现+5. 删除一个子类中的方法并测试+6. 删除其他子类中的方法并测试++---++### Push Down Method++**何时使用**:某个行为只适用于部分子类++**动机**:把方法放到真正使用它的地方。++**步骤**:+1. 把方法复制到需要它的子类+2. 从超类删除方法+3. 测试+4. 删除不需要该方法的子类副本+5. 测试++---++### Replace Subclass with Delegate++**何时使用**:继承用得不对,需要更灵活++**动机**:在合适的地方更偏向组合而不是继承。++**步骤**:+1. 创建一个空的委托类+2. 在宿主类中加一个持有委托的字段+3. 在宿主类构造委托+4. 把功能迁移到委托类+5. 每次迁移后测试+6. 用委托替代继承++---++## Extract Class++**何时使用**:大类里有多个职责++**动机**:拆分类以维持单一职责。++**步骤**:+1. 决定如何拆分职责+2. 创建新类+3. 把字段从原类移到新类+4. 测试+5. 把方法从原类移到新类+6. 每次移动后测试+7. 重新检查并命名两个类+8. 决定如何暴露新类++**前:**+```javascript+class Person {+ get name() { return this._name; }+ set name(arg) { this._name = arg; }+ get officeAreaCode() { return this._officeAreaCode; }+ set officeAreaCode(arg) { this._officeAreaCode = arg; }+ get officeNumber() { return this._officeNumber; }+ set officeNumber(arg) { this._officeNumber = arg; }++ get telephoneNumber() {+ return `(${this._officeAreaCode}) ${this._officeNumber}`;+ }+}+```++**后:**+```javascript+class Person {+ constructor() {+ this._telephoneNumber = new TelephoneNumber();+ }+ get name() { return this._name; }+ set name(arg) { this._name = arg; }+ get telephoneNumber() { return this._telephoneNumber.toString(); }+ get officeAreaCode() { return this._telephoneNumber.areaCode; }+ set officeAreaCode(arg) { this._telephoneNumber.areaCode = arg; }+}++class TelephoneNumber {+ get areaCode() { return this._areaCode; }+ set areaCode(arg) { this._areaCode = arg; }+ get number() { return this._number; }+ set number(arg) { this._number = arg; }+ toString() { return `(${this._areaCode}) ${this._number}`; }+}+```++---++## 快速参考:异味到重构++| 代码异味 | 主要重构 | 备选方案 |+|----------|---------|---------|+| 长函数 | Extract Method | Replace Temp with Query |+| 重复代码 | Extract Method | Pull Up Method |+| 大类 | Extract Class | Extract Subclass |+| 长参数列表 | Introduce Parameter Object | Preserve Whole Object |+| Feature Envy | Move Method | Extract Method + Move |+| 数据泥团 | Extract Class | Introduce Parameter Object |+| 基础类型沉迷 | Replace Primitive with Object | Replace Type Code |+| switch 语句 | Replace Conditional with Polymorphism | Replace Type Code |+| 临时字段 | Extract Class | Introduce Null Object |+| 消息链 | Hide Delegate | Extract Method |+| 中间人 | Remove Middle Man | Inline Method |+| 发散式变化 | Extract Class | Split Phase |+| 散弹式修改 | Move Method | Inline Class |+| 死代码 | Remove Dead Code | - |+| 臆想泛化 | Collapse Hierarchy | Inline Class |++---++## 延伸阅读++- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (第 2 版)+- 在线目录:https://refactoring.com/catalog/diff --git a/zh/03-skills/refactor/templates/refactoring-plan.md b/zh/03-skills/refactor/templates/refactoring-plan.mdnew file mode 100644index 0000000..82e9b7a--- /dev/null+++ b/zh/03-skills/refactor/templates/refactoring-plan.md@@ -0,0 +1,284 @@+# 重构计划模板++使用这个模板来记录和跟踪你的重构工作。++---++## 项目信息++| 字段 | 值 |+|-------|-------|+| **项目 / 模块** | [项目名称] |+| **目标文件** | [要重构的文件列表] |+| **创建日期** | [日期] |+| **作者** | [姓名] |+| **状态** | Draft / In Review / Approved / In Progress / Completed |++---++## 执行摘要++### 目标+- [ ] [主要目标:例如,提升支付流程可读性]+- [ ] [次要目标:例如,减少重复代码]+- [ ] [第三目标:例如,提升可测试性]++### 约束+- [ ] [约束 1:例如,不能改公共 API]+- [ ] [约束 2:例如,必须保持向后兼容]+- [ ] [约束 3:例如,不能改数据库 schema]++### 风险等级+- [ ] Low - 小改动,测试充分+- [ ] Medium - 中等改动,有一定风险+- [ ] High - 大改动,需要特别注意++---++## 重构前检查清单++### 测试覆盖评估++| 指标 | 当前值 | 目标值 | 状态 |+|--------|---------|---------|--------|+| 单元测试覆盖率 | __% | ≥80% | |+| 集成测试 | Yes/No | Yes | |+| 所有测试通过 | Yes/No | Yes | |++### 开始前必须满足+- [ ] 所有测试通过+- [ ] 已读懂并审查代码+- [ ] 已有备份 / 版本控制+- [ ] 已获得用户批准++---++## 已识别的代码异味++### 摘要++| # | 异味 | 位置 | 严重性 | 优先级 |+|---|-------|------|------|------|+| 1 | [例如,Long Method] | [file:line] | High | P1 |+| 2 | [例如,Duplicate Code] | [file:line] | Medium | P2 |+| 3 | [例如,Feature Envy] | [file:line] | Low | P3 |++### 详细分析++#### 异味 #1:[名称]++**位置**:`path/to/file.js:45-120`++**描述**:[对问题的详细描述]++**影响**:+- [影响 1]+- [影响 2]++**建议方案**:[如何修复的简要说明]++---++## 重构阶段++### 阶段 A:快速收益(低风险)++**目标**:快速、低风险的改进,立刻产生价值++**预计改动**:[X 个文件,Y 个方法]++**需要用户批准**:Yes / No++| # | 任务 | 文件 | 重构手法 | 状态 |+|---|------|------|----------|------|+| A1 | 将变量 `x` 重命名为 `userCount` | utils.js:15 | Rename Variable | [ ] |+| A2 | 删除未使用的 `oldHandler()` | api.js:89 | Remove Dead Code | [ ] |+| A3 | 提取重复的验证逻辑 | form.js:23,67 | Extract Method | [ ] |++**回滚方案**:回退 A1-A3 的提交++---++### 阶段 B:结构优化(中风险)++**目标**:改善代码组织和清晰度++**预计改动**:[X 个文件,Y 个方法]++**需要用户批准**:Yes++**依赖**:必须先完成阶段 A++| # | 任务 | 文件 | 重构手法 | 状态 |+|---|------|------|----------|------|+| B1 | 从长函数中提取 `calculatePrice()` | order.js:45 | Extract Method | [ ] |+| B2 | 引入 `OrderDetails` 参数对象 | order.js:12 | Introduce Parameter Object | [ ] |+| B3 | 将 `formatAddress()` 移动到 Address 类 | customer.js:78 | Move Method | [ ] |++**回滚方案**:回滚到阶段 A 完成后的提交++---++### 阶段 C:架构改动(高风险)++**目标**:处理更深层的结构问题++**预计改动**:[X 个文件,Y 个方法]++**需要用户批准**:Yes++**依赖**:必须先完成阶段 A 和 B++| # | 任务 | 文件 | 重构手法 | 状态 |+|---|------|------|----------|------|+| C1 | 用多态替换价格 switch | pricing.js:30 | Replace Conditional with Polymorphism | [ ] |+| C2 | 提取 `NotificationService` 类 | user.js:100 | Extract Class | [ ] |++**回滚方案**:回滚到阶段 B 完成后的提交++---++## 详细重构步骤++### 任务 [ID]:[任务名称]++**对应异味**:[异味名称]++**重构手法**:[手法名称]++**风险等级**:Low / Medium / High++#### 上下文++**重构前**(当前状态):+```javascript+// 把当前代码贴在这里+```++**重构后**(期望状态):+```javascript+// 把期望代码贴在这里+```++#### 逐步操作++1. [ ] **步骤 1**:[描述]+ - 测试:完成此步后运行测试+ - 预期:所有测试通过++2. [ ] **步骤 2**:[描述]+ - 测试:完成此步后运行测试+ - 预期:所有测试通过++3. [ ] **步骤 3**:[描述]+ - 测试:完成此步后运行测试+ - 预期:所有测试通过++#### 验证++- [ ] 所有测试通过+- [ ] 行为未改变+- [ ] 代码可编译+- [ ] 没有新的警告++#### 提交信息+```+refactor: [描述这次重构]+```++---++## 进度跟踪++### 阶段状态++| 阶段 | 状态 | 开始时间 | 完成时间 | 测试是否通过 |+|------|------|----------|----------|--------------|+| A | Not Started / In Progress / Done | | | |+| B | Not Started / In Progress / Done | | | |+| C | Not Started / In Progress / Done | | | |++### 遇到的问题++| # | 问题 | 解决方案 | 状态 |+|---|------|----------|------|+| 1 | [描述] | [如何解决] | Open / Resolved |++---++## 指标对比++### 重构前++| 指标 | 文件 1 | 文件 2 | 总计 |+|------|------|------|------|+| 代码行数 | | | |+| 圈复杂度 | | | |+| 可维护性指标 | | | |+| 方法数量 | | | |+| 平均方法长度 | | | |++### 重构后++| 指标 | 文件 1 | 文件 2 | 总计 | 变化 |+|------|------|------|------|------|+| 代码行数 | | | | |+| 圈复杂度 | | | | |+| 可维护性指标 | | | | |+| 方法数量 | | | | |+| 平均方法长度 | | | | |++---++## 重构后检查清单++- [ ] 所有测试通过+- [ ] 没有新的警告或错误+- [ ] 代码成功编译+- [ ] 已完成手工验证+- [ ] 文档已更新(如需要)+- [ ] 已完成代码审查+- [ ] 指标有改善+- [ ] 已获得用户签字确认++---++## 经验总结++### 做得好的地方+- [Item 1]+- [Item 2]++### 可以改进的地方+- [Item 1]+- [Item 2]++### 未来建议+- [Item 1]+- [Item 2]++---++## 批准++| 角色 | 姓名 | 日期 | 签名 |+|------|------|------|------|+| Plan Author | | | |+| Technical Lead | | | |+| Product Owner | | | |++---++## 附录++### A. 相关文档+- [相关文档链接]++### B. 参考资料+- [代码异味目录]+- [重构目录]++### C. 使用的工具+- [测试框架]+- [Lint 工具]+- [复杂度分析工具]diff --git a/zh/04-subagents/README.md b/zh/04-subagents/README.mdnew file mode 100644index 0000000..7d55a10--- /dev/null+++ b/zh/04-subagents/README.md@@ -0,0 +1,380 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# Subagents 完整参考++## 概览++Subagents 是专门处理某类任务的独立 AI 助手。它们拥有隔离的上下文、自己的提示词和工具权限,适合把复杂工作拆分给不同角色。++## 主要好处++- 上下文隔离+- 角色分工清晰+- 适合并行和委派+- 便于把复杂任务拆开++## 文件位置++- 项目级:`.claude/agents/`+- 用户级:`~/.claude/agents/`++## 配置++### 文件格式++Subagent 通常是一个带 frontmatter 的 Markdown 文件。++```yaml+---+name: code-reviewer+description: 审查代码质量和安全问题+tools: Read, Grep, Bash+---++# Code Reviewer+```++### 配置字段++| 字段 | 说明 |+|------|------|+| `name` | subagent 名称 |+| `description` | 何时该调用它 |+| `tools` | 允许使用的工具 |+| `model` | 指定模型 |+| `prompt` | 任务提示词 |+| `context` | 上下文策略 |++### 工具配置选项++- 只读审查+- 限制 Bash+- 允许更强工具集++### 基于 CLI 的配置++你也可以通过命令行或设置文件定义 subagent。++## 内置 Subagents++Claude Code 自带一些常见角色,例如:++- 通用助手+- Planning agent+- Explore agent+- Bash agent+- Statusline 相关 agent+- Claude Code Guide agent++## 管理 Subagents++### 使用 `/agents` 命令(推荐)++```bash+/agents+```++### 直接管理文件++#### 创建项目 subagent++```bash+mkdir -p .claude/agents+```++#### 创建用户 subagent++```bash+mkdir -p ~/.claude/agents+```++## 使用 Subagents++### 自动委派++主 agent 可以根据任务描述自动把工作分配给合适的 subagent。++### 显式调用++你也可以明确让 Claude 使用某个 subagent。++### `@` 提及调用++在一些场景里,可以通过 `@agent-name` 方式引用。++### 会话级 agent++可以在整个会话中固定使用某个 agent。++### 列出可用 agents++```bash+claude agents+```++## 可恢复的 agents++某些 subagent 可以先启动,之后再恢复,便于长任务接力。++## 串联 Subagents++复杂任务里可以让多个 subagent 依次协作,例如:++1. 代码审查+2. 测试生成+3. 文档更新++## Subagents 的持久记忆++Subagents 可以拥有自己的 memory 范围,让它们在各自职责内保持一致。++### Memory 范围++- 项目级+- 用户级+- 子目录级++### 工作方式++Subagent 会在自己的上下文中读取对应记忆,不和主会话完全混在一起。++## 后台 Subagents++### 配置++有些 subagent 可以作为后台任务执行,不阻塞主会话。++### 快捷键++在支持的界面中,可用快捷键查看或切换后台 subagent。++### 关闭后台任务++如果你不想让任务后台运行,可以在设置中关闭。++## Worktree 隔离++### 配置++可以为 subagent 分配独立的 worktree。++### 工作方式++这样不同任务就不会互相污染文件状态。++## 限制可启动的 Subagents++你可以限制 Claude 只能 spawn 某些 subagent,以降低风险。++### 示例++- 只允许审查类 agent+- 禁止高风险自动化 agent++## `claude agents` CLI 命令++用于查看和管理当前可用的 agent。++## Agent Teams(实验性)++Agent teams 是更高级的协作模式,适合多个 subagent 并行处理复杂任务。++### Subagents vs Agent Teams++- Subagents 侧重委派单个任务+- Agent teams 侧重多角色协作++### 启用 Agent Teams++通过设置打开实验性功能。++### 启动团队++团队模式会把不同任务分配给不同角色。++### 显示模式++可以选择更适合终端或图形界面的显示方式。++### 导航++你可以在 team 中切换角色、查看状态和读取消息。++### 团队配置++适合为大型流程定义清晰角色。++### 架构++agent team 本质上是多个专门角色围绕同一任务协作。++### 任务分配与消息++主 agent 会负责把任务拆分并转发给对应 subagent。++### 计划审批流程++如果是 plan 驱动流程,团队会先审计划再执行。++### 团队相关 hook 事件++一些 hook 可以在 team 生命周期里触发。++### 最佳实践++- 角色定义要清楚+- 任务边界要明确+- 不要让多个 agent 做重复工作++### 局限++- 实验性功能可能会变化+- 复杂团队需要更多配置++## 插件中的 Subagent 安全++插件分发的 subagent 要特别注意权限、工具范围和边界条件。++## 架构++### 高层架构++主 agent、subagent、文件系统和工具权限共同构成执行链。++### 生命周期++1. 创建+2. 分配任务+3. 执行+4. 返回结果+5. 结束或恢复++## 上下文管理++### 关键点++- 子上下文尽量小+- 让每个 subagent 只负责自己的事+- 避免把所有信息都塞进去++### 性能考虑++过多的上下文会拖慢速度并降低准确性。++### 关键行为++subagent 在隔离上下文里工作,但仍能把结果汇总回主会话。++## 什么时候使用 Subagents++- 任务可拆分+- 需要隔离上下文+- 需要明确角色分工+- 需要并行协作++## 最佳实践++### 设计原则++- 单一职责+- 描述明确+- 工具权限最小化++### System Prompt 最佳实践++- 任务说明要具体+- 不要写太长+- 只保留执行任务所需的信息++### 工具访问策略++- 审查型 subagent 只读+- 实现型 subagent 适度开放写权限+- 高风险动作要保持审批++## 本目录中的示例 Subagents++### 1. [Code Reviewer](./code-reviewer.md)++用于全面代码质量审查。++### 2. [Test Engineer](./test-engineer.md)++用于测试策略、覆盖率和测试生成。++### 3. [Documentation Writer](./documentation-writer.md)++用于技术文档写作和更新。++### 4. [Secure Reviewer](./secure-reviewer.md)++用于安全检查,通常只读。++### 5. [Implementation Agent](./implementation-agent.md)++用于功能实现和代码修改。++### 6. [Debugger](./debugger.md)++用于定位 bug 和分析异常。++### 7. [Data Scientist](./data-scientist.md)++用于分析数据、解释结果和生成报告。++### 8. [Clean Code Reviewer](./clean-code-reviewer.md)++用于按 Clean Code 原则做专门审查。++## 安装说明++### 方法 1:使用 `/agents`++```bash+/agents+```++### 方法 2:复制到项目++```bash+mkdir -p .claude/agents+cp 04-subagents/*.md .claude/agents/+```++### 方法 3:复制到用户目录++```bash+mkdir -p ~/.claude/agents+cp 04-subagents/*.md ~/.claude/agents/+```++### 验证++- 运行 `/agents`+- 检查对应 agent 是否出现在列表中+- 试着让 Claude 委派一个简单任务++## 文件结构++```text+.claude/agents/+├── clean-code-reviewer.md+├── code-reviewer.md+├── data-scientist.md+├── debugger.md+├── documentation-writer.md+├── implementation-agent.md+├── secure-reviewer.md+├── test-engineer.md+└── README.md+```++## 相关概念++- [Skills 中文指南](../03-skills/README.md)+- [Memory 中文指南](../02-memory/README.md)+- [Hooks 中文指南](../06-hooks/README.md)+- [Plugins 中文指南](../07-plugins/README.md)diff --git a/zh/04-subagents/clean-code-reviewer.md b/zh/04-subagents/clean-code-reviewer.mdnew file mode 100644index 0000000..87a9fa5--- /dev/null+++ b/zh/04-subagents/clean-code-reviewer.md@@ -0,0 +1,66 @@+---+name: clean-code-reviewer+description: Clean Code 原则执行专家。审查代码中的 Clean Code 理论和最佳实践违规。写完代码后建议主动使用,确保可维护性和专业质量。+tools: Read, Grep, Glob, Bash+model: inherit+---++# Clean Code Reviewer Agent++你是一名资深代码审查员,专注于 Clean Code 原则(Robert C. Martin)。你需要识别违规点并给出可执行的修复建议。++## 流程+1. 运行 `git diff` 查看最近的变更+2. 认真阅读相关文件+3. 提供带有 `file:line`、代码片段和修复建议的审查结果++## 检查重点++**命名**:要能体现意图、可发音、可搜索。不要使用编码或前缀。类名用名词,方法名用动词。++**函数**:少于 20 行,只做一件事,最多 3 个参数,不要 flag 参数,不要副作用,不要返回 null。++**注释**:代码应当足够自解释。删除被注释掉的代码,不要写冗余或误导性的注释。++**结构**:保持类小而专注,单一职责,高内聚,低耦合。避免上帝类。++**SOLID**:单一职责、开闭原则、里氏替换、接口隔离、依赖倒置。++**DRY/KISS/YAGNI**:不要重复,保持简单,不要为假设中的未来过度设计。++**错误处理**:使用异常而不是错误码,提供上下文,永远不要返回或传递 null。++**坏味道**:死代码、特性依恋、长参数列表、消息链、基本类型偏执、投机性泛化。++## 严重级别+- **Critical**:函数超过 50 行,5 个及以上参数,4 层及以上嵌套,多重职责+- **High**:函数 20 到 50 行,4 个参数,命名不清晰,重复较多+- **Medium**:轻微重复、用注释解释代码、格式问题+- **Low**:轻微的可读性或组织性改进++## 输出格式++```text+# Clean Code Review++## Summary+Files: [n] | Critical: [n] | High: [n] | Medium: [n] | Low: [n]++## Violations++**[Severity] [Category]** `file:line`+> [code snippet]+Problem: [what's wrong]+Fix: [how to fix]++## Good Practices+[What's done well]+```++## 指南+- 要具体:精确到代码和行号+- 要建设性:解释为什么,并给出修复方式+- 要务实:关注影响,跳过无关痛痒的小问题+- 跳过:生成代码、配置文件、测试夹具++**核心理念**:代码被阅读的次数是写作的 10 倍。优化可读性,而不是炫技。diff --git a/zh/04-subagents/code-reviewer.md b/zh/04-subagents/code-reviewer.mdnew file mode 100644index 0000000..3db98a8--- /dev/null+++ b/zh/04-subagents/code-reviewer.md@@ -0,0 +1,61 @@+---+name: code-reviewer+description: 代码审查专家。写完或修改代码后建议主动使用,确保质量、安全性和可维护性。+tools: Read, Grep, Glob, Bash+model: inherit+---++# Code Reviewer Agent++你是一名资深代码审查员,负责确保代码质量和安全性维持在高标准。++被调用时:+1. 运行 `git diff` 查看最近的变更+2. 重点检查被修改的文件+3. 立即开始审查++## 审查优先级(按顺序)++1. **安全问题** - 身份验证、授权、数据泄露+2. **性能问题** - O(n^2) 操作、内存泄漏、低效查询+3. **代码质量** - 可读性、命名、文档+4. **测试覆盖率** - 缺失测试、边界情况+5. **设计模式** - SOLID 原则、架构++## 审查清单++- 代码清晰易读+- 函数和变量命名合理+- 没有重复代码+- 错误处理正确+- 没有暴露密钥或 API key+- 已实现输入校验+- 测试覆盖充分+- 已考虑性能问题++## 审查输出格式++对每个问题都要提供:+- **Severity**: Critical / High / Medium / Low+- **Category**: Security / Performance / Quality / Testing / Design+- **Location**: 文件路径和行号+- **Issue Description**: 问题是什么,为什么有问题+- **Suggested Fix**: 代码示例+- **Impact**: 这会怎样影响系统++请按优先级组织反馈:+1. Critical issues(必须修)+2. Warnings(应该修)+3. Suggestions(可考虑改进)++请给出具体的修复示例。++## 审查示例++### 问题:N+1 查询+- **Severity**: High+- **Category**: Performance+- **Location**: src/user-service.ts:45+- **Issue**: 循环在每次迭代中都执行数据库查询+- **Fix**: 使用 JOIN 或批量查询+- **Impact**: 响应时间会随着数据量线性增长diff --git a/zh/04-subagents/data-scientist.md b/zh/04-subagents/data-scientist.mdnew file mode 100644index 0000000..2bdb2e6--- /dev/null+++ b/zh/04-subagents/data-scientist.md@@ -0,0 +1,97 @@+---+name: data-scientist+description: 数据分析专家,擅长 SQL 查询、BigQuery 操作和数据洞察。适用于数据分析任务和查询场景。+tools: Bash, Read, Write+model: sonnet+---++# Data Scientist Agent++你是一名专注于 SQL 和 BigQuery 分析的数据科学家。++被调用时:+1. 理解数据分析需求+2. 编写高效的 SQL 查询+3. 在合适时使用 BigQuery 命令行工具(`bq`)+4. 分析并总结结果+5. 清晰地呈现发现++## 核心实践++- 编写经过优化的 SQL 查询,并使用合适的过滤条件+- 使用恰当的聚合和 join+- 为复杂逻辑添加注释+- 让结果易于阅读+- 提供数据驱动的建议++## SQL 最佳实践++### 查询优化++- 使用 `WHERE` 尽早过滤+- 使用合适的索引+- 生产环境避免 `SELECT *`+- 探索数据时限制结果集++### BigQuery 相关++```bash+# 运行查询+bq query --use_legacy_sql=false 'SELECT * FROM dataset.table LIMIT 10'++# 导出结果+bq query --use_legacy_sql=false --format=csv 'SELECT ...' > results.csv++# 查看表结构+bq show --schema dataset.table+```++## 分析类型++1. **探索性分析**+ - 数据剖析+ - 分布分析+ - 缺失值检测++2. **统计分析**+ - 聚合与汇总+ - 趋势分析+ - 相关性检测++3. **报告**+ - 提取关键指标+ - 环比/同比对比+ - 面向管理层的总结++## 输出格式++对每次分析,提供:+- **Objective**: 我们在回答什么问题+- **Query**: 使用的 SQL(带注释)+- **Results**: 关键发现+- **Insights**: 基于数据的结论+- **Recommendations**: 建议的下一步++## 示例查询++```sql+-- 月活跃用户趋势+SELECT+ DATE_TRUNC(created_at, MONTH) as month,+ COUNT(DISTINCT user_id) as active_users,+ COUNT(*) as total_events+FROM events+WHERE+ created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH)+ AND event_type = 'login'+GROUP BY 1+ORDER BY 1 DESC;+```++## 分析检查清单++- [ ] 已理解需求+- [ ] 查询已优化+- [ ] 结果已验证+- [ ] 发现已记录+- [ ] 建议已提供diff --git a/zh/04-subagents/debugger.md b/zh/04-subagents/debugger.mdnew file mode 100644index 0000000..ecb2a1b--- /dev/null+++ b/zh/04-subagents/debugger.md@@ -0,0 +1,80 @@+---+name: debugger+description: 排错专家,负责处理错误、测试失败和异常行为。遇到问题时建议主动使用。+tools: Read, Edit, Bash, Grep, Glob+model: inherit+---++# Debugger Agent++你是一名擅长根因分析的专家级排错人员。++被调用时:+1. 获取错误信息和堆栈追踪+2. 找到复现步骤+3. 定位故障位置+4. 实施最小修复+5. 验证修复有效++## 排错流程++1. **分析错误信息和日志**+ - 阅读完整错误信息+ - 检查堆栈追踪+ - 查看最近的日志输出++2. **检查最近的代码变更**+ - 运行 `git diff` 查看修改+ - 找出可能破坏行为的改动+ - 回看提交历史++3. **提出并测试假设**+ - 从最可能的原因开始+ - 添加有针对性的调试日志+ - 检查变量状态++4. **隔离故障**+ - 缩小到具体函数或行号+ - 创建最小复现案例+ - 验证隔离结果++5. **实现并验证修复**+ - 做最小必要修改+ - 运行测试确认修复+ - 检查回归问题++## 调试输出格式++针对每个问题,提供:+- **Error**: 原始错误信息+- **Root Cause**: 为什么会失败+- **Evidence**: 你如何确定原因+- **Fix**: 具体做了哪些代码修改+- **Testing**: 如何验证修复+- **Prevention**: 如何避免再次发生++## 常用调试命令++```bash+# 查看最近变更+git diff HEAD~3++# 搜索错误模式+grep -r "error" --include="*.log"++# 查找相关代码+grep -r "functionName" --include="*.ts"++# 运行指定测试+npm test -- --grep "test name"+```++## 排查检查清单++- [ ] 已捕获错误信息+- [ ] 已分析堆栈追踪+- [ ] 已检查最近变更+- [ ] 已定位根因+- [ ] 已实现修复+- [ ] 测试通过+- [ ] 未引入回归diff --git a/zh/04-subagents/documentation-writer.md b/zh/04-subagents/documentation-writer.mdnew file mode 100644index 0000000..e3b28ff--- /dev/null+++ b/zh/04-subagents/documentation-writer.md@@ -0,0 +1,98 @@+---+name: documentation-writer+description: 技术文档专家,负责 API 文档、用户指南和架构文档。+tools: Read, Write, Grep+model: inherit+---++# Documentation Writer Agent++你是一名技术写作者,负责创建清晰、完整的文档。++被调用时:+1. 分析要记录的代码或功能+2. 确定目标读者+3. 按项目规范编写文档+4. 根据实际代码验证准确性++## 文档类型++- 带示例的 API 文档+- 用户指南和教程+- 架构文档+- Changelog 条目+- 代码注释改进++## 文档标准++1. **清晰** - 使用简单、明确的语言+2. **示例** - 包含实用的代码示例+3. **完整** - 覆盖所有参数和返回值+4. **结构** - 使用一致的格式+5. **准确** - 根据实际代码验证++## 文档章节++### API 文档++- 描述+- 参数(含类型)+- 返回值(含类型)+- 抛出错误(可能的异常)+- 示例(curl、JavaScript、Python)+- 相关端点++### 功能文档++- 概述+- 前置条件+- 分步说明+- 预期结果+- 故障排查+- 相关主题++## 输出格式++每份生成的文档都要提供:+- **Type**: API / Guide / Architecture / Changelog+- **File**: 文档文件路径+- **Sections**: 覆盖的章节列表+- **Examples**: 包含的代码示例数量++## API 文档示例++```markdown+## GET /api/users/:id++通过唯一标识符检索用户。++### Parameters++| Name | Type | Required | Description |+|------|------|----------|-------------|+| id | string | Yes | 用户的唯一标识符 |++### Response++```json+{+ "id": "abc123",+ "name": "John Doe",+ "email": "[email protected]"+}+```++### Errors++| Code | Description |+|------|-------------|+| 404 | User not found |+| 401 | Unauthorized |++### Example++```bash+curl -X GET https://api.example.com/api/users/abc123 \+ -H "Authorization: Bearer <token>"+```+```diff --git a/zh/04-subagents/implementation-agent.md b/zh/04-subagents/implementation-agent.mdnew file mode 100644index 0000000..5b46493--- /dev/null+++ b/zh/04-subagents/implementation-agent.md@@ -0,0 +1,78 @@+---+name: implementation-agent+description: 全栈实现专家,负责根据规范开发功能。拥有完整工具权限,可端到端完成实现。+tools: Read, Write, Edit, Bash, Grep, Glob+model: inherit+---++# Implementation Agent++你是一名资深开发者,负责根据规格实现功能。++这个 agent 拥有完整能力:+- 阅读规范和现有代码+- 创建新的代码文件+- 编辑已有文件+- 运行构建命令+- 搜索代码库+- 查找匹配模式的文件++## 实现流程++被调用时:+1. 充分理解需求+2. 分析现有代码库模式+3. 制定实现方案+4. 逐步实现+5. 边做边测试+6. 清理和重构++## 实现指南++### 代码质量++- 遵循现有项目规范+- 编写自解释代码+- 只有在逻辑复杂时才添加注释+- 保持函数短小专注+- 使用有意义的变量名++### 文件组织++- 按项目结构放置文件+- 相关功能放在一起+- 遵循命名规范+- 避免过深的目录嵌套++### 错误处理++- 处理所有错误情况+- 提供有意义的错误信息+- 合理记录错误日志+- 优雅失败++### 测试++- 为新功能编写测试+- 确保现有测试通过+- 覆盖边界情况+- 为 API 添加集成测试++## 输出格式++每个实现任务都要提供:+- **Files Created**: 新文件列表+- **Files Modified**: 已修改文件列表+- **Tests Added**: 测试文件路径+- **Build Status**: Pass/Fail+- **Notes**: 重要说明++## 实现检查清单++在标记完成前:+- [ ] 代码符合项目规范+- [ ] 所有测试通过+- [ ] 构建成功+- [ ] 没有 lint 错误+- [ ] 已处理边界情况+- [ ] 已实现错误处理diff --git a/zh/04-subagents/secure-reviewer.md b/zh/04-subagents/secure-reviewer.mdnew file mode 100644index 0000000..1bfca06--- /dev/null+++ b/zh/04-subagents/secure-reviewer.md@@ -0,0 +1,75 @@+---+name: secure-reviewer+description: 安全审查专家,权限最小化。只读访问确保安全审计过程安全可靠。+tools: Read, Grep+model: inherit+---++# Secure Code Reviewer++你是一名安全专家,专注于识别漏洞。++这个 agent 采用最小权限设计:+- 可以读取文件进行分析+- 可以搜索模式+- 不能执行代码+- 不能修改文件+- 不能运行测试++这样可以确保审查过程中不会意外破坏任何东西。++## 安全审查重点++1. **身份验证问题**+ - 弱密码策略+ - 缺少多因素认证+ - 会话管理缺陷++2. **授权问题**+ - 访问控制失效+ - 权限提升+ - 缺少角色检查++3. **数据暴露**+ - 日志中泄露敏感数据+ - 未加密存储+ - API key 泄露+ - PII 处理问题++4. **注入漏洞**+ - SQL 注入+ - 命令注入+ - XSS(跨站脚本)+ - LDAP 注入++5. **配置问题**+ - 生产环境开启调试模式+ - 默认凭据+ - 不安全的默认配置++## 搜索模式++```bash+# 硬编码密钥+grep -r "password\s*=" --include="*.js" --include="*.ts"+grep -r "api_key\s*=" --include="*.py"+grep -r "SECRET" --include="*.env*"++# SQL 注入风险+grep -r "query.*\$" --include="*.js"+grep -r "execute.*%" --include="*.py"++# 命令注入风险+grep -r "exec(" --include="*.js"+grep -r "os.system" --include="*.py"+```++## 输出格式++对每个漏洞,提供:+- **Severity**: Critical / High / Medium / Low+- **Type**: OWASP 类别+- **Location**: 文件路径和行号+- **Description**: 漏洞是什么+- **Risk**: 如果被利用,可能造成什么影响+- **Remediation**: 如何修复diff --git a/zh/04-subagents/test-engineer.md b/zh/04-subagents/test-engineer.mdnew file mode 100644index 0000000..9e2bde8--- /dev/null+++ b/zh/04-subagents/test-engineer.md@@ -0,0 +1,74 @@+---+name: test-engineer+description: 测试自动化专家,负责编写全面测试。新功能上线或代码修改后建议主动使用。+tools: Read, Write, Bash, Grep+model: inherit+---++# Test Engineer Agent++你是一名擅长完整测试覆盖的测试工程师。++被调用时:+1. 分析需要测试的代码+2. 识别关键路径和边界情况+3. 按项目规范编写测试+4. 运行测试验证通过++## 测试策略++1. **单元测试** - 独立测试单个函数或方法+2. **集成测试** - 测试组件交互+3. **端到端测试** - 测试完整工作流+4. **边界情况** - 边界条件、空值、空集合+5. **错误场景** - 失败处理、非法输入++## 测试要求++- 使用项目现有测试框架(Jest、pytest 等)+- 每个测试都要包含 setup/teardown+- Mock 外部依赖+- 用清晰描述说明测试目的+- 在相关场景下加入性能断言++## 覆盖率要求++- 最低 80% 代码覆盖率+- 关键路径(认证、支付、数据处理)要求 100%+- 报告缺失的覆盖区域++## 测试输出格式++每个测试文件都要提供:+- **File**: 测试文件路径+- **Tests**: 测试用例数量+- **Coverage**: 预计覆盖率提升+- **Critical Paths**: 覆盖了哪些关键路径++## 测试结构示例++```javascript+describe('Feature: User Authentication', () => {+ beforeEach(() => {+ // Setup+ });++ afterEach(() => {+ // Cleanup+ });++ it('should authenticate valid credentials', async () => {+ // Arrange+ // Act+ // Assert+ });++ it('should reject invalid credentials', async () => {+ // Test error case+ });++ it('should handle edge case: empty password', async () => {+ // Test edge case+ });+});+```diff --git a/zh/05-mcp/README.md b/zh/05-mcp/README.mdnew file mode 100644index 0000000..6c9945e--- /dev/null+++ b/zh/05-mcp/README.md@@ -0,0 +1,342 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# MCP(Model Context Protocol)++## 概览++MCP 是 Claude Code 访问外部工具、服务和 API 的标准协议。你可以把 GitHub、数据库、文件系统、聊天系统等都接到 Claude 里。++## MCP 架构++MCP 通常由三部分构成:++1. Claude Code+2. MCP server+3. 外部工具或数据源++Claude 会通过 MCP 协议向 server 发起工具调用,并把结果带回当前会话。++## MCP 生态++- GitHub 集成+- 数据库集成+- 文件系统集成+- 组织内部工具+- 第三方服务++## 安装方式++### HTTP 传输(推荐)++```bash+# Basic HTTP connection++# HTTP with authentication header+```++### Stdio 传输(本地)++```bash+# Local Node.js server++# With environment variables+```++### SSE 传输(已弃用)++旧版本中可能仍能见到 SSE 方式,但新配置一般优先考虑 HTTP 或 stdio。++### WebSocket 传输++适用于需要实时双向通信的场景。++### Windows 说明++在 Windows 上配置本地 server 时,要注意 shell、环境变量和路径写法。++### OAuth 2.0 认证++对于支持 OAuth 的 MCP server,Claude 可以通过交互式流程或预配置凭据完成认证。++## MCP 设置流程++1. 确认你要接入的服务+2. 选择 transport+3. 配置环境变量或认证+4. 在 Claude Code 中添加 server+5. 验证工具是否可用++## MCP 工具搜索++Claude 会根据当前上下文自动查找可用工具。++## 动态工具更新++当 MCP server 增加或移除工具时,Claude 可以在运行时感知变化。++## MCP 提示补充(Elicitation)++有些 MCP server 会在需要用户补充信息时触发 elicitation,Claude 再把问题转给用户。++## 工具描述与指令上限++每个 MCP 工具都应该有清晰的描述,帮助 Claude 选择正确的工具。++## 把 MCP Prompts 暴露成 Slash Commands++```text+/mcp__<server-name>__<prompt-name> [arguments]+```++例如:++```bash+/mcp__github__list_prs+/mcp__github__pr_review 456+/mcp__jira__create_issue "Bug title" high+```++## Server 去重++如果多个配置都指向同一个 server,Claude 会尽量避免重复加载。++## 通过 `@` 提及使用 MCP 资源++你可以把某些资源当作引用对象,在 prompt 中直接提及。++## MCP 作用域++MCP 配置通常有不同作用域,例如项目级和用户级。++### 使用项目作用域++适合把团队共享的 server 配置写进项目内。++## MCP 配置管理++### 添加 MCP server++```bash+# Add HTTP-based server++# Add local stdio server++# List all MCP servers++# Get details on specific server++# Remove an MCP server++# Reset project-specific approval choices++# Import from Claude Desktop+```++## 可用 MCP Server 表++你可以在配置中维护一张 server 清单,记录用途、认证方式和安装命令。++## 实战示例++### 示例 1:GitHub MCP 配置++你可以用 GitHub MCP 做这些事:++- PR 管理+- Issue 管理+- 仓库信息查询+- commit 操作++### 环境变量展开++在配置中可以使用环境变量,让同一份配置适配不同环境。++### 示例 2:数据库 MCP++```bash+# Using MCP database tool:++# Results:+```++### 示例 3:多 MCP 工作流++适合日常报告、跨系统同步和自动化文档生成。++### 示例 4:文件系统 MCP 操作++可用于读写文件、批量整理、生成报告或导出结果。++## MCP vs Memory:决策矩阵++- **Memory**:适合长期规则、偏好和上下文+- **MCP**:适合实时工具访问和外部数据++## 请求 / 响应模式++MCP 一般遵循:++1. Claude 发起请求+2. Server 处理+3. 返回结构化结果++## 环境变量++常见环境变量包括:++- API token+- 数据库地址+- 服务端口+- 认证信息++## Claude 作为 MCP Server(`claude mcp serve`)++```bash+# Start Claude Code as an MCP server on stdio+```++## 受管 MCP 配置(企业)++企业可通过受管设置统一分发 MCP 配置。++## 插件提供的 MCP Servers++插件可以把自己的 MCP server 一起打包分发。++## Subagent 作用域 MCP++某些 MCP 只允许特定 subagent 使用。++## MCP 输出限制++如果输出过大,可以限制 token 数或分页获取。++### 增大最大输出++```bash+# Increase the max output to 50,000 tokens+```++## 用代码执行解决上下文膨胀++当重复把大量数据回传给 Claude 会浪费 token 时,可以把 MCP 当作代码 API 来用,减少来回传输。++### 问题++- 两个信息源都在耗 token+- 大数据集不适合全量塞进上下文++### 方案++- 用 MCP 工具做实时查询+- 只把必要结果传给 Claude++#### 工作方式++Claude 通过工具调用从外部系统取回需要的数据,而不是把所有数据先写进上下文。++### 好处++- 更少 token 浪费+- 更清晰的数据边界+- 更适合大规模查询++#### 示例:过滤大数据集++#### 示例:循环而不做 round-trip++### 取舍++- 实现复杂度更高+- 需要维护 server+- 但扩展性更好++### MCPorter:MCP 工具组合运行时++这是更高级的工具编排思路,可以把多个 MCP 工具串成一个流程。++## 最佳实践++### 安全注意事项++#### 应该做的++- 只授权必要的工具+- 优先使用最小权限+- 检查输出是否可信++#### 不要做的++- 不要把高风险 token 写死在仓库里+- 不要默认开放所有工具+- 不要忽视网络和认证风险++### 配置建议++- 给每个 server 写清楚用途+- 用环境变量存认证信息+- 把项目级配置版本化++### 性能建议++- 避免一次性拉回过多数据+- 优先做过滤和分页+- 只返回 Claude 真正需要的结果++## 安装说明++### 前置条件++- Claude Code+- 对应的 MCP server+- 必要的认证信息++### 分步设置++1. 安装 server+2. 设置环境变量+3. 添加到 Claude+4. 测试工具++### 特定服务的安装++不同服务会有不同的安装命令和认证方式。++## 故障排查++### 找不到 MCP Server++- 检查是否安装+- 检查路径+- 检查配置是否正确++### 认证失败++- 检查环境变量是否设置+- 确认 token 权限正确+- 重新导出变量后再试++### 连接超时++- 检查网络+- 检查 server 是否可用++### MCP Server 崩溃++- 查看 server 日志+- 降低并发+- 简化请求++## 相关概念++- [Memory 中文指南](../02-memory/README.md)+- [Subagents 中文参考](../04-subagents/README.md)+- [Plugins 中文指南](../07-plugins/README.md)++## 更多资源++- [根目录中文指南](../README.md)+- [MCP 规范](https://modelcontextprotocol.io)diff --git a/zh/06-hooks/README.md b/zh/06-hooks/README.mdnew file mode 100644index 0000000..3a84f8a--- /dev/null+++ b/zh/06-hooks/README.md@@ -0,0 +1,98 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# Hooks 参考++Hooks 是在 Claude Code 事件发生时自动执行的 shell 命令,用来做格式化、校验、通知、审计等自动化工作。++## 概览++Hooks 是事件驱动的自动化机制。它们会在 Claude Code 发生某些动作时自动运行,不需要你手动触发。++常见用途:++- 写文件前自动格式化+- 提交前运行测试+- 扫描安全问题+- 记录 bash 命令+- 校验用户提示词+- 发送团队通知++## Hook 类型++Claude Code 提供 4 类、25 个事件:++- **Tool Hooks**:`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`+- **Session Hooks**:`SessionStart`、`SessionEnd`、`Stop`、`StopFailure`、`SubagentStart`、`SubagentStop`+- **Task Hooks**:`UserPromptSubmit`、`TaskCompleted`、`TaskCreated`、`TeammateIdle`+- **Lifecycle Hooks**:`ConfigChange`、`CwdChanged`、`FileChanged`、`PreCompact`、`PostCompact`、`WorktreeCreate`、`WorktreeRemove`、`Notification`、`InstructionsLoaded`、`Elicitation`、`ElicitationResult`++## 安装++```bash+mkdir -p ~/.claude/hooks+cp 06-hooks/*.sh ~/.claude/hooks/+chmod +x ~/.claude/hooks/*.sh+```++然后在 `~/.claude/settings.json` 里配置:++```json+{+ "hooks": {+ "PreToolUse": [{+ "matcher": "Write",+ "hooks": ["~/.claude/hooks/format-code.sh"]+ }],+ "PostToolUse": [{+ "matcher": "Write",+ "hooks": ["~/.claude/hooks/security-scan.sh"]+ }]+ }+}+```++## 使用方法++Hooks 会在匹配到事件时自动执行。你可以把它理解成 Claude Code 的事件回调。++## 常见示例++- `format-code.sh` - 写入前自动格式化+- `pre-commit.sh` - 提交前跑测试+- `security-scan.sh` - 做安全扫描+- `log-bash.sh` - 记录 bash 命令+- `validate-prompt.sh` - 校验输入+- `notify-team.sh` - 发通知++## 最佳实践++- 把 hooks 保持短小明确+- 只做单一职责+- 先在本地测试+- 不要在 hook 里放复杂业务逻辑+- 对副作用保持谨慎++## 故障排查++- 检查文件路径和权限+- 确认脚本可执行+- 检查 settings.json 语法+- 查看 Claude Code 版本兼容性++## 相关概念++- [Checkpoints and Rewind](../08-checkpoints/README.md)+- [Slash Commands](../01-slash-commands/README.md)+- [Skills](../03-skills/README.md)+- [Subagents](../04-subagents/README.md)+- [Plugins](../07-plugins/README.md)+- [Advanced Features](../09-advanced-features/README.md)++## 更多资源++- [Memory Guide](../02-memory/README.md)+- [Official Hooks Documentation](https://code.claude.com/docs/en/hooks)+- [CLI Reference](https://code.claude.com/docs/en/cli-reference)diff --git a/zh/07-plugins/README.md b/zh/07-plugins/README.mdnew file mode 100644index 0000000..7390745--- /dev/null+++ b/zh/07-plugins/README.md@@ -0,0 +1,930 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# Claude Code 插件++这个目录包含一组完整的插件示例,它们把多个 Claude Code 功能打包成可安装的一体化方案。++## 介绍++Claude Code 插件是把 slash commands、subagents、MCP servers 和 hooks 组合在一起的功能集合,可以通过一条命令安装。它们代表了 Claude Code 最高级别的扩展方式,把多个功能整合成可共享、可复用的完整方案。++## 概览++一个插件通常会把以下能力打包在一起:++- slash commands+- subagents+- MCP servers+- hooks++这样做的好处是:++- 一次安装即可使用完整工作流+- 团队共享更容易+- 配置更统一+- 便于版本控制和分发++## 插件架构++```mermaid+graph TB+ A["插件"]+ B["Slash Commands"]+ C["Subagents"]+ D["MCP Servers"]+ E["Hooks"]+ F["Configuration"]++ A -->|打包| B+ A -->|打包| C+ A -->|打包| D+ A -->|打包| E+ A -->|打包| F+```++## 插件类型与分发++| 类型 | 范围 | 共享对象 | 维护者 | 示例 |+|------|------|----------|--------|------|+| 官方 | 全局 | 所有用户 | Anthropic | PR 审查、安全指导 |+| 社区 | 公开 | 所有用户 | 社区 | DevOps、数据科学 |+| 组织 | 内部 | 团队成员 | 公司 | 内部规范、工具 |+| 个人 | 个人 | 单个用户 | 开发者 | 自定义工作流 |++## 插件定义结构++插件清单使用 `.claude-plugin/plugin.json` 中的 JSON 格式:++```json+{+ "name": "my-first-plugin",+ "description": "一个问候插件",+ "version": "1.0.0",+ "author": {+ "name": "Your Name"+ },+ "homepage": "https://example.com",+ "repository": "https://github.com/user/repo",+ "license": "MIT"+}+```++## 插件结构示例++```+my-plugin/+├── .claude-plugin/+│ └── plugin.json # 清单(名称、描述、版本、作者)+├── commands/ # 以 Markdown 文件形式存放的命令+│ ├── task-1.md+│ ├── task-2.md+│ └── workflows/+├── agents/ # 自定义 agent 定义+│ ├── specialist-1.md+│ ├── specialist-2.md+│ └── configs/+├── skills/ # 带有 SKILL.md 文件的技能+│ ├── skill-1.md+│ └── skill-2.md+├── hooks/ # hooks.json 中的事件处理器+│ └── hooks.json+├── .mcp.json # MCP server 配置+├── .lsp.json # LSP server 配置+├── settings.json # 默认设置+├── templates/+│ └── issue-template.md+├── scripts/+│ ├── helper-1.sh+│ └── helper-2.py+├── docs/+│ ├── README.md+│ └── USAGE.md+└── tests/+ └── plugin.test.js+```++### LSP server 配置++插件可以包含 Language Server Protocol(LSP)支持,以获得实时代码智能。LSP server 会在你编写代码时提供诊断、代码导航和符号信息。++**配置位置**:+- 插件根目录中的 `.lsp.json` 文件+- `plugin.json` 中的内联 `lsp` 键++#### 字段参考++| 字段 | 必填 | 说明 |+|------|------|------|+| `command` | 是 | LSP server 可执行文件(必须在 PATH 中) |+| `extensionToLanguage` | 是 | 将文件扩展名映射到语言 ID |+| `args` | 否 | server 的命令行参数 |+| `transport` | 否 | 通信方式:`stdio`(默认)或 `socket` |+| `env` | 否 | server 进程的环境变量 |+| `initializationOptions` | 否 | LSP 初始化期间发送的选项 |+| `settings` | 否 | 传递给 server 的工作区配置 |+| `workspaceFolder` | 否 | 覆盖工作区文件夹路径 |+| `startupTimeout` | 否 | 等待 server 启动的最长时间(毫秒) |+| `shutdownTimeout` | 否 | 优雅关闭的最长时间(毫秒) |+| `restartOnCrash` | 否 | server 崩溃时自动重启 |+| `maxRestarts` | 否 | 放弃前的最大重启次数 |++#### 示例配置++**Go(gopls)**:++```json+{+ "go": {+ "command": "gopls",+ "args": ["serve"],+ "extensionToLanguage": {+ ".go": "go"+ }+ }+}+```++**Python(pyright)**:++```json+{+ "python": {+ "command": "pyright-langserver",+ "args": ["--stdio"],+ "extensionToLanguage": {+ ".py": "python",+ ".pyi": "python"+ }+ }+}+```++**TypeScript**:++```json+{+ "typescript": {+ "command": "typescript-language-server",+ "args": ["--stdio"],+ "extensionToLanguage": {+ ".ts": "typescript",+ ".tsx": "typescriptreact",+ ".js": "javascript",+ ".jsx": "javascriptreact"+ }+ }+}+```++#### 可用的 LSP 插件++官方市场包含了预配置好的 LSP 插件:++| 插件 | 语言 | Server Binary | 安装命令 |+|------|------|---------------|----------|+| `pyright-lsp` | Python | `pyright-langserver` | `pip install pyright` |+| `typescript-lsp` | TypeScript/JavaScript | `typescript-language-server` | `npm install -g typescript-language-server typescript` |+| `rust-lsp` | Rust | `rust-analyzer` | 使用 `rustup component add rust-analyzer` 安装 |++#### LSP 能力++配置完成后,LSP server 会提供:++- **即时诊断** - 编辑后立即显示错误和警告+- **代码导航** - 跳转到定义、查找引用和实现+- **悬浮信息** - 在悬停时查看类型签名和文档+- **符号列表** - 浏览当前文件或工作区中的符号++## 插件选项(v2.1.83+)++插件可以在清单中通过 `userConfig` 声明用户可配置选项。标记为 `sensitive: true` 的值会存储在系统钥匙串中,而不是明文设置文件里:++```json+{+ "name": "my-plugin",+ "version": "1.0.0",+ "userConfig": {+ "apiKey": {+ "description": "服务的 API key",+ "sensitive": true+ },+ "region": {+ "description": "部署区域",+ "default": "us-east-1"+ }+ }+}+```++## 持久化插件数据(`${CLAUDE_PLUGIN_DATA}`)(v2.1.78+)++插件可以通过 `${CLAUDE_PLUGIN_DATA}` 环境变量访问一个持久化状态目录。这个目录对每个插件都是唯一的,并且会跨会话保留,适合缓存、数据库和其他持久化状态:++```json+{+ "hooks": {+ "PostToolUse": [+ {+ "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js"+ }+ ]+ }+}+```++插件安装时会自动创建该目录。存放在这里的文件会一直保留,直到插件被卸载。++## 通过设置文件内联定义插件(`source: 'settings'`)(v2.1.80+)++插件可以在设置文件中以内联市场条目的方式定义,使用 `source: 'settings'` 字段即可。这允许你直接嵌入插件定义,而不必单独准备仓库或市场:++```json+{+ "pluginMarketplaces": [+ {+ "name": "inline-tools",+ "source": "settings",+ "plugins": [+ {+ "name": "quick-lint",+ "source": "./local-plugins/quick-lint"+ }+ ]+ }+ ]+}+```++## 插件设置++插件可以提供一个 `settings.json` 文件来定义默认配置。目前支持 `agent` 键,用来指定插件的主线程 agent:++```json+{+ "agent": "agents/specialist-1.md"+}+```++当插件包含 `settings.json` 时,这些默认值会在安装时自动应用。用户也可以在自己的项目或用户级配置中覆盖它们。++## 独立命令 vs 插件方式++| 方式 | 命令名称 | 配置方式 | 最适合 |+|------|----------|----------|--------|+| **独立命令** | `/hello` | 在 `CLAUDE.md` 中手动设置 | 个人、项目专用 |+| **插件** | `/plugin-name:hello` | 通过 `plugin.json` 自动配置 | 共享、分发、团队使用 |++对于快速的个人工作流,使用 **独立 slash commands**。当你想打包多个功能、与团队共享或者发布分发时,使用 **插件**。++## 实际示例++### 示例 1:PR 审查插件++**文件:** `.claude-plugin/plugin.json`++```json+{+ "name": "pr-review",+ "version": "1.0.0",+ "description": "包含安全、测试和文档检查的完整 PR 审查工作流",+ "author": {+ "name": "Anthropic"+ },+ "repository": "https://github.com/your-org/pr-review",+ "license": "MIT"+}+```++**文件:** `commands/review-pr.md`++```markdown+---+name: Review PR+description: 启动包含安全和测试检查的完整 PR 审查+---++# PR Review++这个命令会启动一次完整的 Pull Request 审查,包括:++1. 安全分析+2. 测试覆盖率验证+3. 文档更新+4. 代码质量检查+5. 性能影响评估+```++**文件:** `agents/security-reviewer.md`++```yaml+---+name: security-reviewer+description: 面向安全的代码审查+tools: read, grep, diff+---++# Security Reviewer++专注于发现安全漏洞:+- 身份验证/授权问题+- 数据暴露+- 注入攻击+- 安全配置+```++**安装:**++```bash+/plugin install pr-review++# 结果:+# ✅ 已安装 3 个 slash commands+# ✅ 已配置 3 个 subagents+# ✅ 已连接 2 个 MCP servers+# ✅ 已注册 4 个 hooks+# ✅ 可以直接使用!+```++### 示例 2:DevOps 插件++**组件:**++```+devops-automation/+├── commands/+│ ├── deploy.md+│ ├── rollback.md+│ ├── status.md+│ └── incident.md+├── agents/+│ ├── deployment-specialist.md+│ ├── incident-commander.md+│ └── alert-analyzer.md+├── mcp/+│ ├── github-config.json+│ ├── kubernetes-config.json+│ └── prometheus-config.json+├── hooks/+│ ├── pre-deploy.js+│ ├── post-deploy.js+│ └── on-error.js+└── scripts/+ ├── deploy.sh+ ├── rollback.sh+ └── health-check.sh+```++### 示例 3:文档插件++**打包组件:**++```+documentation/+├── commands/+│ ├── generate-api-docs.md+│ ├── generate-readme.md+│ ├── sync-docs.md+│ └── validate-docs.md+├── agents/+│ ├── api-documenter.md+│ ├── code-commentator.md+│ └── example-generator.md+├── mcp/+│ ├── github-docs-config.json+│ └── slack-announce-config.json+└── templates/+ ├── api-endpoint.md+ ├── function-docs.md+ └── adr-template.md+```++## 插件市场++Anthropic 官方维护的插件目录是 `anthropics/claude-plugins-official`。企业管理员也可以创建私有插件市场用于内部分发。++```mermaid+graph TB+ A["插件市场"]+ B["官方<br/>anthropics/claude-plugins-official"]+ C["社区<br/>市场"]+ D["企业<br/>私有仓库"]++ A --> B+ A --> C+ A --> D++ B -->|分类| B1["开发"]+ B -->|分类| B2["DevOps"]+ B -->|分类| B3["文档"]++ C -->|搜索| C1["DevOps 自动化"]+ C -->|搜索| C2["移动开发"]+ C -->|搜索| C3["数据科学"]++ D -->|内部| D1["公司规范"]+ D -->|内部| D2["遗留系统"]+ D -->|内部| D3["合规"]++ style A fill:#e1f5fe,stroke:#333,color:#333+ style B fill:#e8f5e9,stroke:#333,color:#333+ style C fill:#f3e5f5,stroke:#333,color:#333+ style D fill:#fff3e0,stroke:#333,color:#333+```++### 市场配置++企业和高级用户可以通过设置来控制市场行为:++| 设置 | 说明 |+|------|------|+| `extraKnownMarketplaces` | 在默认列表之外添加额外的市场源 |+| `strictKnownMarketplaces` | 控制允许用户添加哪些市场 |+| `deniedPlugins` | 管理员维护的黑名单,阻止特定插件被安装 |++### 额外的市场特性++- **默认 git 超时**:对大型插件仓库从 30 秒增加到 120 秒+- **自定义 npm registry**:插件可以指定自定义 npm registry URL 用于依赖解析+- **版本锁定**:将插件锁定到特定版本,以获得可复现的环境++### 市场定义 schema++插件市场定义在 `.claude-plugin/marketplace.json` 中:++```json+{+ "name": "my-team-plugins",+ "owner": "my-org",+ "plugins": [+ {+ "name": "code-standards",+ "source": "./plugins/code-standards",+ "description": "强制执行团队编码规范",+ "version": "1.2.0",+ "author": "platform-team"+ },+ {+ "name": "deploy-helper",+ "source": {+ "source": "github",+ "repo": "my-org/deploy-helper",+ "ref": "v2.0.0"+ },+ "description": "部署自动化工作流"+ }+ ]+}+```++| 字段 | 必填 | 说明 |+|------|------|------|+| `name` | 是 | 使用 kebab-case 的市场名称 |+| `owner` | 是 | 维护该市场的组织或用户 |+| `plugins` | 是 | 插件条目数组 |+| `plugins[].name` | 是 | 插件名称(kebab-case) |+| `plugins[].source` | 是 | 插件来源(路径字符串或来源对象) |+| `plugins[].description` | 否 | 插件的简要描述 |+| `plugins[].version` | 否 | 语义化版本字符串 |+| `plugins[].author` | 否 | 插件作者名称 |++### 插件来源类型++插件可以来自多个位置:++| 来源 | 语法 | 示例 |+|------|------|------|+| **相对路径** | 字符串路径 | `"./plugins/my-plugin"` |+| **GitHub** | `{ "source": "github", "repo": "owner/repo" }` | `{ "source": "github", "repo": "acme/lint-plugin", "ref": "v1.0" }` |+| **Git URL** | `{ "source": "url", "url": "..." }` | `{ "source": "url", "url": "https://git.internal/plugin.git" }` |+| **Git 子目录** | `{ "source": "git-subdir", "url": "...", "path": "..." }` | `{ "source": "git-subdir", "url": "https://github.com/org/monorepo.git", "path": "packages/plugin" }` |+| **npm** | `{ "source": "npm", "package": "..." }` | `{ "source": "npm", "package": "@acme/claude-plugin", "version": "^2.0" }` |+| **pip** | `{ "source": "pip", "package": "..." }` | `{ "source": "pip", "package": "claude-data-plugin", "version": ">=1.0" }` |++GitHub 和 git 来源支持可选的 `ref`(分支/标签)和 `sha`(提交哈希)字段用于版本锁定。++### 分发方式++**GitHub(推荐)**:+```bash+# 用户添加你的市场+/plugin marketplace add owner/repo-name+```++**其他 git 服务**(需要完整 URL):+```bash+/plugin marketplace add https://gitlab.com/org/marketplace-repo.git+```++**私有仓库**:可以通过 git credential helper 或环境令牌支持。用户必须有该仓库的读取权限。++**官方市场提交**:可以将插件提交到 Anthropic 审核维护的市场,以便更广泛分发。++### 严格模式++控制市场定义与本地 `plugin.json` 文件的交互方式:++| 设置 | 行为 |+|------|------|+| `strict: true`(默认) | 本地 `plugin.json` 为权威来源;市场条目会对其进行补充 |+| `strict: false` | 市场条目就是完整的插件定义 |++**配合 `strictKnownMarketplaces` 的组织限制**:++| 值 | 效果 |+|----|------|+| 未设置 | 无限制,用户可以添加任意市场 |+| 空数组 `[]` | 锁定模式,不允许任何市场 |+| 模式数组 | 白名单模式,只允许匹配的市场被添加 |++```json+{+ "strictKnownMarketplaces": [+ "my-org/*",+ "github.com/trusted-vendor/*"+ ]+}+```++> **警告**:在带有 `strictKnownMarketplaces` 的严格模式下,用户只能从白名单市场安装插件。这适用于需要受控插件分发的企业环境。++## 插件安装与生命周期++```mermaid+graph LR+ A["发现"] -->|浏览| B["市场"]+ B -->|选择| C["插件页"]+ C -->|查看| D["组件"]+ D -->|安装| E["/plugin install"]+ E -->|解包| F["配置"]+ F -->|激活| G["使用"]+ G -->|检查| H["更新"]+ H -->|可用| G+ G -->|完成| I["禁用"]+ I -->|稍后| J["启用"]+ J -->|返回| G+```++## 插件能力对比++| 功能 | Slash Command | Skill | Subagent | Plugin |+|------|---------------|-------|----------|--------|+| **安装** | 手动复制 | 手动复制 | 手动配置 | 一条命令 |+| **设置时间** | 5 分钟 | 10 分钟 | 15 分钟 | 2 分钟 |+| **打包** | 单文件 | 单文件 | 单文件 | 多文件 |+| **版本管理** | 手动 | 手动 | 手动 | 自动 |+| **团队共享** | 复制文件 | 复制文件 | 复制文件 | 安装 ID |+| **更新** | 手动 | 手动 | 手动 | 自动可用 |+| **依赖** | 无 | 无 | 无 | 可能包含 |+| **市场** | 否 | 否 | 否 | 是 |+| **分发** | 仓库 | 仓库 | 仓库 | 市场 |++## 插件 CLI 命令++所有插件操作都可以通过 CLI 命令完成:++```bash+claude plugin install <name>@<marketplace> # 从市场安装+claude plugin uninstall <name> # 删除插件+claude plugin list # 列出已安装插件+claude plugin enable <name> # 启用已禁用的插件+claude plugin disable <name> # 禁用插件+claude plugin validate # 验证插件结构+```++## 安装方式++### 从市场安装+```bash+/plugin install plugin-name+# 或通过 CLI:+claude plugin install plugin-name@marketplace-name+```++### 启用 / 禁用(自动检测作用域)+```bash+/plugin enable plugin-name+/plugin disable plugin-name+```++### 本地插件(用于开发)+```bash+# 本地测试的 CLI 参数(可重复指定多个插件)+claude --plugin-dir ./path/to/plugin+claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b+```++### 从 Git 仓库安装+```bash+/plugin install github:username/repo+```++## 何时创建插件++```mermaid+graph TD+ A["我该创建插件吗?"]+ A -->|需要多个组件| B{"多个命令<br/>或 subagents<br/>或 MCPs?"}+ B -->|是| C["✅ 创建插件"]+ B -->|否| D["使用单独功能"]+ A -->|团队工作流| E{"要和<br/>团队共享吗?"}+ E -->|是| C+ E -->|否| F["保持本地配置"]+ A -->|复杂设置| G{"需要自动<br/>配置吗?"}+ G -->|是| C+ G -->|否| D+```++### 插件适用场景++| 场景 | 建议 | 原因 |+|------|------|------|+| **团队入职** | ✅ 使用插件 | 即时安装,包含所有配置 |+| **框架初始化** | ✅ 使用插件 | 打包框架专属命令 |+| **企业规范** | ✅ 使用插件 | 集中分发,版本控制 |+| **快速任务自动化** | ❌ 使用命令 | 太重 |+| **单一领域能力** | ❌ 使用 Skill | 太重,直接用 skill 更合适 |+| **专门化分析** | ❌ 使用 Subagent | 可手动创建,或用 skill |+| **实时数据访问** | ❌ 使用 MCP | 独立使用,不要打包 |++## 测试插件++在发布前,使用 `--plugin-dir` CLI 参数在本地测试插件(可以重复指定多个插件):++```bash+claude --plugin-dir ./my-plugin+claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin+```++这会用已加载插件启动 Claude Code,让你可以:+- 验证所有 slash commands 是否可用+- 测试 subagents 和 agents 是否正常工作+- 确认 MCP servers 能正确连接+- 验证 hooks 的执行+- 检查 LSP server 配置+- 检查是否有配置错误++## 热重载++插件支持开发期间的热重载。当你修改插件文件时,Claude Code 可以自动检测变化。你也可以手动触发重载:++```bash+/reload-plugins+```++这会重新读取所有插件清单、commands、agents、skills、hooks 以及 MCP/LSP 配置,而无需重启会话。++## 插件托管设置++管理员可以使用托管设置在组织范围内控制插件行为:++| 设置 | 说明 |+|------|------|+| `enabledPlugins` | 默认启用的插件白名单 |+| `deniedPlugins` | 不允许安装的插件黑名单 |+| `extraKnownMarketplaces` | 在默认列表之外添加额外市场源 |+| `strictKnownMarketplaces` | 限制用户允许添加的市场 |+| `allowedChannelPlugins` | 控制每个发布渠道允许使用哪些插件 |++这些设置可以通过托管配置文件应用到组织级别,并且优先于用户级设置。++## 插件安全++插件 subagents 运行在受限沙箱中。以下 frontmatter 键在插件 subagent 定义中**不允许**使用:++- `hooks` - subagents 不能注册事件处理器+- `mcpServers` - subagents 不能配置 MCP servers+- `permissionMode` - subagents 不能覆盖权限模型++这可以确保插件不会越权,也不会修改主机环境的作用范围。++## 发布插件++**发布步骤:**++1. 使用所有组件创建插件结构+2. 编写 `.claude-plugin/plugin.json` 清单+3. 创建带文档的 `README.md`+4. 使用 `claude --plugin-dir ./my-plugin` 在本地测试+5. 提交到插件市场+6. 经过审查和批准+7. 发布到市场+8. 用户即可一条命令安装++**示例提交:**++```markdown+# PR 审查插件++## 描述+包含安全、测试和文档检查的完整 PR 审查工作流。++## 包含内容+- 3 个用于不同审查类型的 slash commands+- 3 个专门化 subagents+- GitHub 和 CodeQL MCP 集成+- 自动安全扫描 hooks++## 安装+```bash+/plugin install pr-review+```++## 功能+✅ 安全分析+✅ 测试覆盖率检查+✅ 文档校验+✅ 代码质量评估+✅ 性能影响分析++## 使用+```bash+/review-pr+/check-security+/check-tests+```++## 要求+- Claude Code 1.0++- GitHub 访问权限+- CodeQL(可选)+```++## 插件 vs 手动配置++**手动设置(2+ 小时):**+- 逐个安装 slash commands+- 单独创建 subagents+- 分别配置 MCP+- 手动设置 hooks+- 记录所有内容+- 和团队共享(希望他们能配对)++**使用插件(2 分钟):**+```bash+/plugin install pr-review+# ✅ 一切都已安装并配置+# ✅ 可以立即使用+# ✅ 团队可以复现完全相同的设置+```++## 最佳实践++### 应该做的 ✅+- 使用清晰、描述性的插件名+- 提供完整 README+- 正确使用语义化版本(semver)+- 一起测试所有组件+- 清楚记录依赖和要求+- 提供使用示例+- 包含错误处理+- 为发现性添加合适标签+- 保持向后兼容+- 保持插件聚焦且一致+- 包含完整测试+- 记录所有依赖++### 不要做的 ❌+- 不要打包无关功能+- 不要硬编码凭据+- 不要跳过测试+- 不要忘记文档+- 不要创建冗余插件+- 不要忽略版本管理+- 不要把组件依赖搞得过于复杂+- 不要忘记优雅处理错误++## 安装说明++### 从市场安装++1. **浏览可用插件:**+ ```bash+ /plugin list+ ```++2. **查看插件详情:**+ ```bash+ /plugin info plugin-name+ ```++3. **安装插件:**+ ```bash+ /plugin install plugin-name+ ```++### 从本地路径安装++```bash+/plugin install ./path/to/plugin-directory+```++### 从 GitHub 安装++```bash+/plugin install github:username/repo+```++### 列出已安装插件++```bash+/plugin list --installed+```++### 更新插件++```bash+/plugin update plugin-name+```++### 禁用 / 启用插件++```bash+# 临时禁用+/plugin disable plugin-name++# 重新启用+/plugin enable plugin-name+```++### 卸载插件++```bash+/plugin uninstall plugin-name+```++## 相关概念++以下 Claude Code 功能会和插件一起协作:++- **[Slash Commands](../01-slash-commands/README.md)** - 插件中打包的单独命令+- **[Memory](../02-memory/README.md)** - 插件的持久上下文+- **[Skills](../03-skills/README.md)** - 可以包装进插件的领域能力+- **[Subagents](../04-subagents/README.md)** - 作为插件组件包含的专门化 agent+- **[MCP Servers](../05-mcp/README.md)** - 打包在插件中的 Model Context Protocol 集成+- **[Hooks](../06-hooks/README.md)** - 触发插件工作流的事件处理器++## 完整示例工作流++### PR Review 插件完整工作流++```+1. 用户:/review-pr++2. 插件执行:+ ├── pre-review.js hook 验证 git repo+ ├── GitHub MCP 获取 PR 数据+ ├── security-reviewer subagent 分析安全+ ├── test-checker subagent 验证覆盖率+ └── performance-analyzer subagent 检查性能++3. 汇总并展示结果:+ ✅ 安全:没有发现关键问题+ ⚠️ 测试:覆盖率 65%(建议 80%+)+ ✅ 性能:没有明显影响+ 📝 提供了 12 条建议+```++## 故障排查++### 插件无法安装+- 检查 Claude Code 版本兼容性:`/version`+- 用 JSON 校验器验证 `plugin.json` 语法+- 检查网络连接(远程插件)+- 检查权限:`ls -la plugin/`++### 组件没有加载+- 验证 `plugin.json` 中的路径与实际目录结构一致+- 检查文件权限:`chmod +x scripts/`+- 检查组件文件语法+- 查看日志:`/plugin debug plugin-name`++### MCP 连接失败+- 确认环境变量已正确设置+- 检查 MCP server 的安装和健康状态+- 使用 `/mcp test` 独立测试 MCP 连接+- 查看 `mcp/` 目录中的 MCP 配置++### 安装后命令不可用+- 确认插件已成功安装:`/plugin list --installed`+- 检查插件是否已启用:`/plugin status plugin-name`+- 重启 Claude Code:`exit` 后重新打开+- 检查是否与现有命令冲突++### Hook 执行问题+- 确认 hook 文件权限正确+- 检查 hook 语法和事件名+- 查看 hook 日志中的错误细节+- 如有可能,手动测试 hooks++## 更多资源++- [官方插件文档](https://code.claude.com/docs/en/plugins)+- [发现插件](https://code.claude.com/docs/en/discover-plugins)+- [插件市场](https://code.claude.com/docs/en/plugin-marketplaces)+- [插件参考](https://code.claude.com/docs/en/plugins-reference)+- [MCP Server 参考](https://modelcontextprotocol.io/)+- [Subagent 配置指南](../04-subagents/README.md)+- [Hook 系统参考](../06-hooks/README.md)diff --git a/zh/07-plugins/devops-automation/README.md b/zh/07-plugins/devops-automation/README.mdnew file mode 100644index 0000000..0131c53--- /dev/null+++ b/zh/07-plugins/devops-automation/README.md@@ -0,0 +1,114 @@+---+name: DevOps 自动化插件+description: 为部署、监控和故障处理提供自动化工作流+tags: plugins, devops, automation+---++# DevOps 自动化插件++完整的 DevOps 自动化工作流,覆盖部署、监控和事故响应。++## 功能++✅ 自动化部署+✅ 回滚流程+✅ 系统健康监控+✅ 事故响应工作流+✅ Kubernetes 集成++## 安装++```bash+/plugin install devops-automation+```++## 包含内容++### Slash 命令+- `/deploy` - 部署到生产或预发环境+- `/rollback` - 回滚到上一个版本+- `/status` - 检查系统健康+- `/incident` - 处理生产事故++### 子 agents+- `deployment-specialist` - 部署操作+- `incident-commander` - 事故协调+- `alert-analyzer` - 系统健康分析++### MCP 服务器+- Kubernetes 集成++### 脚本+- `deploy.sh` - 部署自动化+- `rollback.sh` - 回滚自动化+- `health-check.sh` - 健康检查工具++### Hooks+- `pre-deploy.js` - 部署前验证+- `post-deploy.js` - 部署后任务++## 使用++### 部署到预发环境++```+/deploy staging+```++### 部署到生产环境++```+/deploy production+```++### 回滚++```+/rollback production+```++### 检查状态++```+/status+```++### 处理事故++```+/incident+```++## 要求++- Claude Code 1.0++- Kubernetes CLI(kubectl)+- 已配置集群访问++## 配置++设置 Kubernetes 配置:++```bash+export KUBECONFIG=~/.kube/config+```++## 示例工作流++```+用户:/deploy production++Claude:+1. 运行 pre-deploy hook(验证 kubectl 和集群连接)+2. 将部署委派给 deployment-specialist subagent+3. 运行 deploy.sh 脚本+4. 通过 Kubernetes MCP 监控部署进度+5. 运行 post-deploy hook(等待 pods 就绪,执行 smoke tests)+6. 提供部署总结++结果:+✅ 部署完成+📦 版本:v2.1.0+🚀 Pods:3/3 已就绪+⏱️ 用时:2m 34s+```diff --git a/zh/07-plugins/devops-automation/agents/alert-analyzer.md b/zh/07-plugins/devops-automation/agents/alert-analyzer.mdnew file mode 100644index 0000000..647094d--- /dev/null+++ b/zh/07-plugins/devops-automation/agents/alert-analyzer.md@@ -0,0 +1,14 @@+---+name: alert-analyzer+description: 分析监控告警和系统指标+tools: read, grep, bash+---++# 告警分析器++分析系统健康状况和告警:+- 告警关联分析+- 趋势分析+- 根因识别+- 指标可视化+- 主动问题检测diff --git a/zh/07-plugins/devops-automation/agents/deployment-specialist.md b/zh/07-plugins/devops-automation/agents/deployment-specialist.mdnew file mode 100644index 0000000..4b5f116--- /dev/null+++ b/zh/07-plugins/devops-automation/agents/deployment-specialist.md@@ -0,0 +1,14 @@+---+name: deployment-specialist+description: 处理所有部署操作+tools: read, write, bash, grep+---++# 部署专家++部署运维专家:+- 蓝绿部署+- 金丝雀发布+- 回滚流程+- 健康检查+- 数据库迁移diff --git a/zh/07-plugins/devops-automation/agents/incident-commander.md b/zh/07-plugins/devops-automation/agents/incident-commander.mdnew file mode 100644index 0000000..a749580--- /dev/null+++ b/zh/07-plugins/devops-automation/agents/incident-commander.md@@ -0,0 +1,14 @@+---+name: incident-commander+description: 协调事故响应+tools: read, write, bash, grep+---++# 事故指挥官++管理事故响应:+- 严重性评估+- 团队协调+- 状态更新+- 解决跟踪+- 事后复盘推动diff --git a/zh/07-plugins/devops-automation/commands/deploy.md b/zh/07-plugins/devops-automation/commands/deploy.mdnew file mode 100644index 0000000..7c15d6f--- /dev/null+++ b/zh/07-plugins/devops-automation/commands/deploy.md@@ -0,0 +1,15 @@+---+name: Deploy+description: 将应用部署到生产或预发环境+---++# 应用部署++执行部署工作流:++1. 运行部署前检查+2. 构建应用+3. 运行测试+4. 部署到目标环境+5. 运行健康检查+6. 在 Slack 上通知团队diff --git a/zh/07-plugins/devops-automation/commands/incident.md b/zh/07-plugins/devops-automation/commands/incident.mdnew file mode 100644index 0000000..708c76e--- /dev/null+++ b/zh/07-plugins/devops-automation/commands/incident.md@@ -0,0 +1,16 @@+---+name: Incident Response+description: 使用结构化响应流程处理生产事故+---++# 事故响应++结构化事故响应工作流:++1. 创建事故记录+2. 评估严重性和影响+3. 通知值班团队+4. 收集诊断信息+5. 协调响应工作+6. 记录解决方案+7. 安排事后复盘diff --git a/zh/07-plugins/devops-automation/commands/rollback.md b/zh/07-plugins/devops-automation/commands/rollback.mdnew file mode 100644index 0000000..aa71b17--- /dev/null+++ b/zh/07-plugins/devops-automation/commands/rollback.md@@ -0,0 +1,14 @@+---+name: Rollback+description: 回滚到上一次部署+---++# 回滚部署++回滚到之前的稳定版本:++1. 确认上一次部署+2. 验证回滚目标健康状态+3. 执行回滚流程+4. 运行健康检查+5. 通知团队diff --git a/zh/07-plugins/devops-automation/commands/status.md b/zh/07-plugins/devops-automation/commands/status.mdnew file mode 100644index 0000000..df472c0--- /dev/null+++ b/zh/07-plugins/devops-automation/commands/status.md@@ -0,0 +1,15 @@+---+name: System Status+description: 检查整体系统健康状况+---++# 系统状态检查++检查所有服务的系统健康状况:++1. 查询 Kubernetes pod 状态+2. 检查数据库连接+3. 监控 API 响应时间+4. 查看错误率+5. 检查资源利用率+6. 报告整体健康状况diff --git a/zh/07-plugins/documentation/README.md b/zh/07-plugins/documentation/README.mdnew file mode 100644index 0000000..670d7ec--- /dev/null+++ b/zh/07-plugins/documentation/README.md@@ -0,0 +1,127 @@+---+name: 文档生成插件+description: 为文档编写、同步和校验提供完整工作流+tags: plugins, documentation, automation+---++# 文档生成插件++这个插件把文档相关的命令、subagents、模板和 MCP 服务器打包在一起,帮助你生成、同步和校验文档。++## 特性++✅ 生成 API 文档+✅ 创建和更新 README+✅ 同步文档+✅ 改进代码注释+✅ 生成示例++## 包含内容++### 命令+- [commands/generate-api-docs.md](commands/generate-api-docs.md) - 生成 API 文档+- [commands/generate-readme.md](commands/generate-readme.md) - 生成 README+- [commands/sync-docs.md](commands/sync-docs.md) - 同步文档+- [commands/validate-docs.md](commands/validate-docs.md) - 校验文档++### Subagents+- [agents/api-documenter.md](agents/api-documenter.md) - API 文档 subagent+- [agents/code-commentator.md](agents/code-commentator.md) - 代码注释 subagent+- [agents/example-generator.md](agents/example-generator.md) - 示例生成 subagent++### 模板+- [templates/adr-template.md](templates/adr-template.md) - ADR 模板+- [templates/api-endpoint.md](templates/api-endpoint.md) - API 端点模板+- [templates/function-docs.md](templates/function-docs.md) - 函数文档模板++### MCP 服务器+- GitHub 集成 - 用于文档同步++## 安装++```bash+/plugin install documentation+```++## 使用方式++### 生成 API 文档+```bash+/generate-api-docs+```++### 创建 README+```bash+/generate-readme+```++### 同步文档+```bash+/sync-docs+```++### 校验文档+```bash+/validate-docs+```++## 适用场景++- 想标准化项目文档产出+- 想自动生成 README、API 文档和示例+- 想同步多个文档之间的一致性+- 想维护代码注释和示例质量++## 需求++- Claude Code 1.0++- GitHub 访问权限(可选)++## 示例工作流++```text+用户:/generate-api-docs++Claude:+1. 扫描 /src/api/ 下的所有 API 端点+2. 委派给 api-documenter subagent+3. 提取函数签名和 JSDoc+4. 按模块 / 端点组织内容+5. 使用 api-endpoint.md 模板+6. 生成完整的 Markdown 文档+7. 包含 curl、JavaScript 和 Python 示例++结果:+✅ API 文档已生成+📄 已创建文件:+ - docs/api/users.md+ - docs/api/auth.md+ - docs/api/products.md+📊 覆盖率:23/23 个端点已文档化+```++## 模板用途++### API 端点模板+用于编写带完整示例的 REST API 文档。++### 函数文档模板+用于编写单个函数或方法的说明文档。++### ADR 模板+用于记录架构决策。++## 配置++为文档同步设置 GitHub token:+```bash+export GITHUB_TOKEN="your_github_token"+```++## 最佳实践++- 文档尽量贴近代码+- 随着代码变化同步更新文档+- 提供可直接执行的示例+- 定期校验文档有效性+- 使用模板保持一致性diff --git a/zh/07-plugins/documentation/agents/api-documenter.md b/zh/07-plugins/documentation/agents/api-documenter.mdnew file mode 100644index 0000000..40343de--- /dev/null+++ b/zh/07-plugins/documentation/agents/api-documenter.md@@ -0,0 +1,14 @@+---+name: api-documenter+description: API 文档专家+tools: read, write, grep+---++# API 文档专家++创建全面的 API 文档:+- 端点文档+- 参数说明+- 响应 schema+- 代码示例(curl、JavaScript、Python)+- 错误代码diff --git a/zh/07-plugins/documentation/agents/code-commentator.md b/zh/07-plugins/documentation/agents/code-commentator.mdnew file mode 100644index 0000000..8b0d9f2--- /dev/null+++ b/zh/07-plugins/documentation/agents/code-commentator.md@@ -0,0 +1,14 @@+---+name: code-commentator+description: 代码注释与内联文档专家+tools: read, write, edit+---++# 代码注释专家++改进代码文档:+- JSDoc / docstring 注释+- 内联说明+- 参数说明+- 返回类型文档+- 使用示例diff --git a/zh/07-plugins/documentation/agents/example-generator.md b/zh/07-plugins/documentation/agents/example-generator.mdnew file mode 100644index 0000000..abbc01c--- /dev/null+++ b/zh/07-plugins/documentation/agents/example-generator.md@@ -0,0 +1,14 @@+---+name: example-generator+description: 代码示例与教程专家+tools: read, write+---++# 示例生成专家++创建实用的代码示例:+- 入门指南+- 常见用例+- 集成示例+- 最佳实践+- 故障排查场景diff --git a/zh/07-plugins/documentation/commands/generate-api-docs.md b/zh/07-plugins/documentation/commands/generate-api-docs.mdnew file mode 100644index 0000000..5f2182c--- /dev/null+++ b/zh/07-plugins/documentation/commands/generate-api-docs.md@@ -0,0 +1,15 @@+---+name: 生成 API 文档+description: 从源代码生成完整的 API 文档+---++# API 文档生成器++生成完整的 API 文档:++1. 扫描 API 端点+2. 提取函数签名和 JSDoc+3. 按模块 / 端点组织内容+4. 创建带示例的 Markdown+5. 包含请求 / 响应 schema+6. 添加错误文档diff --git a/zh/07-plugins/documentation/commands/generate-readme.md b/zh/07-plugins/documentation/commands/generate-readme.mdnew file mode 100644index 0000000..cfaf328--- /dev/null+++ b/zh/07-plugins/documentation/commands/generate-readme.md@@ -0,0 +1,15 @@+---+name: 生成 README+description: 创建或更新项目 README+---++# README 生成器++生成完整的 README:++1. 项目概览与简介+2. 安装说明+3. 使用示例+4. API 文档链接+5. 贡献指南+6. 许可证信息diff --git a/zh/07-plugins/documentation/commands/sync-docs.md b/zh/07-plugins/documentation/commands/sync-docs.mdnew file mode 100644index 0000000..997968a--- /dev/null+++ b/zh/07-plugins/documentation/commands/sync-docs.md@@ -0,0 +1,14 @@+---+name: 同步文档+description: 将文档与代码变更保持同步+---++# 文档同步++同步文档与代码库:++1. 检测代码变更+2. 找出过时文档+3. 更新受影响的文档+4. 验证示例是否仍然可用+5. 更新版本号diff --git a/zh/07-plugins/documentation/commands/validate-docs.md b/zh/07-plugins/documentation/commands/validate-docs.mdnew file mode 100644index 0000000..36bf825--- /dev/null+++ b/zh/07-plugins/documentation/commands/validate-docs.md@@ -0,0 +1,14 @@+---+name: 校验文档+description: 校验文档的完整性与准确性+---++# 文档校验++校验文档质量:++1. 检查是否有损坏链接+2. 验证代码示例+3. 确保内容完整+4. 检查格式+5. 对照实际代码进行校验diff --git a/zh/07-plugins/documentation/templates/adr-template.md b/zh/07-plugins/documentation/templates/adr-template.mdnew file mode 100644index 0000000..8a23f01--- /dev/null+++ b/zh/07-plugins/documentation/templates/adr-template.md@@ -0,0 +1,39 @@+# ADR [编号]:[标题]++## 状态+[提议中 | 已接受 | 已弃用 | 已被替代]++## 背景+我们正在看到的是什么问题,促使我们做出这个决策或变更?++## 决策+我们提出和/或正在执行的变更是什么?++## 影响+由于这项变更,哪些事情变得更容易或更困难?++### 正面影响+- 收益 1+- 收益 2++### 负面影响+- 代价 1+- 代价 2++### 中性影响+- 参考事项 1+- 参考事项 2++## 备选方案+还考虑过哪些其他选项,以及为什么没有选择它们?++### 备选方案 1+描述以及未选择的原因。++### 备选方案 2+描述以及未选择的原因。++## 参考资料+- 相关 ADR+- 外部文档+- 讨论链接diff --git a/zh/07-plugins/documentation/templates/api-endpoint.md b/zh/07-plugins/documentation/templates/api-endpoint.mdnew file mode 100644index 0000000..cd710a3--- /dev/null+++ b/zh/07-plugins/documentation/templates/api-endpoint.md@@ -0,0 +1,101 @@+# [方法] /api/v1/[endpoint]++## 描述+简要说明这个端点的作用。++## 身份验证+所需的身份验证方式,例如 Bearer token。++## 参数++### 路径参数+| 名称 | 类型 | 必填 | 描述 |+|------|------|------|------|+| id | string | 是 | 资源 ID |++### 查询参数+| 名称 | 类型 | 必填 | 描述 |+|------|------|------|------|+| page | integer | 否 | 页码(默认:1) |+| limit | integer | 否 | 每页条数(默认:20) |++### 请求体+```json+{+ "field": "value"+}+```++## 响应++### 200 OK+```json+{+ "success": true,+ "data": {+ "id": "123",+ "name": "示例"+ }+}+```++### 400 Bad Request+```json+{+ "success": false,+ "error": {+ "code": "VALIDATION_ERROR",+ "message": "无效输入"+ }+}+```++### 404 Not Found+```json+{+ "success": false,+ "error": {+ "code": "NOT_FOUND",+ "message": "资源未找到"+ }+}+```++## 示例++### cURL+```bash+curl -X GET "https://api.example.com/api/v1/endpoint" \+ -H "Authorization: Bearer YOUR_TOKEN" \+ -H "Content-Type: application/json"+```++### JavaScript+```javascript+const response = await fetch('/api/v1/endpoint', {+ headers: {+ 'Authorization': 'Bearer token',+ 'Content-Type': 'application/json'+ }+});+const data = await response.json();+```++### Python+```python+import requests++response = requests.get(+ 'https://api.example.com/api/v1/endpoint',+ headers={'Authorization': 'Bearer token'}+)+data = response.json()+```++## 限流+- 已认证用户每小时 1000 次请求+- 公开端点每小时 100 次请求++## 相关端点+- [GET /api/v1/related](#)+- [POST /api/v1/related](#)diff --git a/zh/07-plugins/documentation/templates/function-docs.md b/zh/07-plugins/documentation/templates/function-docs.mdnew file mode 100644index 0000000..b93c6dc--- /dev/null+++ b/zh/07-plugins/documentation/templates/function-docs.md@@ -0,0 +1,50 @@+# 函数:`functionName`++## 描述+简要说明这个函数的作用。++## 签名+```typescript+function functionName(param1: Type1, param2: Type2): ReturnType+```++## 参数++| 参数 | 类型 | 必填 | 描述 |+|------|------|------|------|+| param1 | Type1 | 是 | param1 的说明 |+| param2 | Type2 | 否 | param2 的说明 |++## 返回值+**类型**:`ReturnType`++返回内容的说明。++## 抛出异常+- `Error`:在输入无效时抛出+- `TypeError`:在传入错误类型时抛出++## 示例++### 基本用法+```typescript+const result = functionName('value1', 'value2');+console.log(result);+```++### 高级用法+```typescript+const result = functionName(+ complexParam1,+ { option: true }+);+```++## 备注+- 其他说明或警告+- 性能注意事项+- 最佳实践++## 另请参阅+- [相关函数](#)+- [API 文档](#)diff --git a/zh/07-plugins/pr-review/README.md b/zh/07-plugins/pr-review/README.mdnew file mode 100644index 0000000..b60dcc1--- /dev/null+++ b/zh/07-plugins/pr-review/README.md@@ -0,0 +1,96 @@+---+name: PR 审查插件+description: 为 Pull Request 提供完整的代码审查工作流+tags: plugins, code-review, pull-request+---++# PR 审查插件++完整的 PR 审查工作流,包含安全、测试和文档检查。++## 功能++✅ 安全分析+✅ 测试覆盖率检查+✅ 文档校验+✅ 代码质量评估+✅ 性能影响分析++## 安装++```bash+/plugin install pr-review+```++## 包含内容++### Slash 命令+- `/review-pr` - 全面 PR 审查+- `/check-security` - 面向安全的审查+- `/check-tests` - 测试覆盖率分析++### 子 agents+- `security-reviewer` - 安全漏洞检测+- `test-checker` - 测试覆盖率分析+- `performance-analyzer` - 性能影响评估++### MCP 服务器+- 用于 PR 数据的 GitHub 集成++### Hooks+- `pre-review.js` - 审查前验证++## 使用++### 基础 PR 审查++```+/review-pr+```++### 仅安全检查++```+/check-security+```++### 仅测试覆盖率检查++```+/check-tests+```++## 要求++- Claude Code 1.0++- GitHub 访问权限+- Git 仓库++## 配置++设置 GitHub token:++```bash+export GITHUB_TOKEN="your_github_token"+```++## 示例工作流++```+用户:/review-pr++Claude:+1. 运行 pre-review hook(验证 git 仓库)+2. 通过 GitHub MCP 获取 PR 数据+3. 将安全审查委派给 security-reviewer subagent+4. 将测试分析委派给 test-checker subagent+5. 将性能分析委派给 performance-analyzer subagent+6. 汇总所有发现+7. 提供完整审查报告++结果:+✅ 安全:未发现关键问题+⚠️ 测试:覆盖率为 65%,建议达到 80%++✅ 性能:没有明显影响+📝 建议:为边界情况添加测试+```diff --git a/zh/07-plugins/pr-review/agents/performance-analyzer.md b/zh/07-plugins/pr-review/agents/performance-analyzer.mdnew file mode 100644index 0000000..5eaccb3--- /dev/null+++ b/zh/07-plugins/pr-review/agents/performance-analyzer.md@@ -0,0 +1,13 @@+---+name: performance-analyzer+description: 性能影响分析+tools: read, grep, bash+---++# 性能分析器++评估变更对性能的影响:+- 算法复杂度+- 数据库查询效率+- 内存使用+- 缓存机会diff --git a/zh/07-plugins/pr-review/agents/security-reviewer.md b/zh/07-plugins/pr-review/agents/security-reviewer.mdnew file mode 100644index 0000000..e325ad0--- /dev/null+++ b/zh/07-plugins/pr-review/agents/security-reviewer.md@@ -0,0 +1,13 @@+---+name: security-reviewer+description: 面向安全的代码审查+tools: read, grep, diff+---++# 安全审查员++专注于发现安全漏洞:+- 身份验证/授权问题+- 数据暴露+- 注入攻击+- 安全配置diff --git a/zh/07-plugins/pr-review/agents/test-checker.md b/zh/07-plugins/pr-review/agents/test-checker.mdnew file mode 100644index 0000000..6344b83--- /dev/null+++ b/zh/07-plugins/pr-review/agents/test-checker.md@@ -0,0 +1,13 @@+---+name: test-checker+description: 测试覆盖率与质量分析+tools: read, bash, grep+---++# 测试检查器++分析测试覆盖率和质量:+- 覆盖率百分比+- 缺失的测试用例+- 测试质量评估+- 边界情况识别diff --git a/zh/07-plugins/pr-review/commands/check-security.md b/zh/07-plugins/pr-review/commands/check-security.mdnew file mode 100644index 0000000..a527d87--- /dev/null+++ b/zh/07-plugins/pr-review/commands/check-security.md@@ -0,0 +1,14 @@+---+name: Security Check+description: 运行安全导向的代码审查+---++# 安全检查++对代码变更执行聚焦式安全分析:++1. 身份验证/授权检查+2. 数据暴露风险+3. 注入漏洞+4. 密码学弱点+5. 日志中的敏感数据diff --git a/zh/07-plugins/pr-review/commands/check-tests.md b/zh/07-plugins/pr-review/commands/check-tests.mdnew file mode 100644index 0000000..581ecbd--- /dev/null+++ b/zh/07-plugins/pr-review/commands/check-tests.md@@ -0,0 +1,14 @@+---+name: Test Coverage Check+description: 验证测试覆盖率和质量+---++# 测试覆盖检查++分析测试覆盖率和质量:++1. 检查测试覆盖率百分比+2. 识别未测试的代码路径+3. 审查测试质量+4. 建议缺失的测试用例+5. 确认边界情况已覆盖diff --git a/zh/07-plugins/pr-review/commands/review-pr.md b/zh/07-plugins/pr-review/commands/review-pr.mdnew file mode 100644index 0000000..cbf8198--- /dev/null+++ b/zh/07-plugins/pr-review/commands/review-pr.md@@ -0,0 +1,14 @@+---+name: Review PR+description: 启动包含安全与测试检查的完整 PR 审查+---++# PR 审查++这个命令会发起一次完整的 Pull Request 审查,包括:++1. 安全分析+2. 测试覆盖率验证+3. 文档更新+4. 代码质量检查+5. 性能影响评估diff --git a/zh/08-checkpoints/README.md b/zh/08-checkpoints/README.mdnew file mode 100644index 0000000..1740625--- /dev/null+++ b/zh/08-checkpoints/README.md@@ -0,0 +1,292 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# Checkpoints 与 Rewind++Checkpoints 可以让你保存对话状态,并在 Claude Code 会话中回退到之前的时间点。无论你是在探索不同方案、修复错误,还是比较多个实现路径,这个能力都非常有用。++## 概览++Checkpoints 会保存会话状态,让你可以安全地试验和探索多种方案。它们本质上是当前对话状态的快照,包含:+- 所有已交换的消息+- 已做出的文件修改+- 工具使用历史+- 当前会话上下文++当你在尝试不同实现方式、从错误中恢复,或比较替代方案时,这个功能尤其好用。++## 核心概念++| 概念 | 说明 |+|---------|-------------|+| **Checkpoint** | 保存消息、文件和上下文的对话快照 |+| **Rewind** | 回到之前的 checkpoint,并丢弃之后的更改 |+| **Branch Point** | 从同一个 checkpoint 出发,探索多个方案 |++## 访问 Checkpoints++你可以通过两种主要方式访问和管理 checkpoints:++### 使用键盘快捷键++按两次 `Esc`(`Esc` + `Esc`)打开 checkpoint 界面并浏览已保存的 checkpoints。++### 使用 Slash Command++使用 `/rewind` 命令(别名:`/checkpoint`)快速进入:++```bash+# 打开 rewind 界面+/rewind++# 或者使用别名+/checkpoint+```++## Rewind 选项++回退时,你会看到一个包含五个选项的菜单:++1. **恢复代码和对话** - 把文件和消息都恢复到那个 checkpoint+2. **恢复对话** - 只回退消息,保留当前代码不变+3. **恢复代码** - 只回退文件修改,保留完整对话历史+4. **从这里开始总结** - 把从这里往后的对话压缩成 AI 生成的摘要,而不是直接丢弃。原始消息仍会保留在记录中。你也可以额外指定摘要应聚焦哪些主题。+5. **算了** - 取消并返回当前状态++## 自动 Checkpoints++Claude Code 会自动为你创建 checkpoints:++- **每次用户提示** - 每次用户输入都会创建一个新 checkpoint+- **持久保存** - checkpoints 会跨会话保留+- **自动清理** - 30 天后自动清理旧 checkpoints++这意味着你随时都可以回到之前的任意节点,从几分钟前到几天前都可以。++## 使用场景++| 场景 | 工作流 |+|----------|----------|+| **探索不同方案** | 保存 → 试方案 A → 保存 → Rewind → 试方案 B → 比较 |+| **安全重构** | 保存 → 重构 → 测试 → 如果失败:Rewind |+| **A/B 测试** | 保存 → 设计 A → 保存 → Rewind → 设计 B → 比较 |+| **错误恢复** | 发现问题 → Rewind 到最后一个正常状态 |++## 如何使用 Checkpoints++### 查看和回退++按两次 `Esc`,或者使用 `/rewind` 打开 checkpoint 浏览器。你会看到一个带时间戳的可用 checkpoint 列表。选择任意一个 checkpoint,即可回退到该状态。++### Checkpoint 详情++每个 checkpoint 会显示:+- 创建时间+- 被修改的文件+- 对话中的消息数量+- 使用过的工具++## 实战示例++更多可直接参考的中文示例见 [checkpoint-examples.md](checkpoint-examples.md)。++### 示例 1:探索不同方案++```text+User: 我们给 API 加一个缓存层吧++Claude: 我会为你的 API 端点添加 Redis 缓存……+[在 checkpoint A 处做出修改]++User: 其实我们先试试内存缓存++Claude: 我会 rewind 回去,探索另一种方案……+[用户按下 Esc+Esc 并回退到 checkpoint A]+[在 checkpoint B 处实现内存缓存]++User: 现在我可以比较两种方案了+```++### 示例 2:从错误中恢复++```text+User: 把认证模块重构成 JWT++Claude: 我会重构认证模块……+[做出大量修改]++User: 等等,这把 OAuth 集成弄坏了。我们回去。++Claude: 我来帮你回退到重构之前……+[用户按下 Esc+Esc,并选择重构前的 checkpoint]++User: 这次我们试一个更保守的方案+```++### 示例 3:安全试验++```text+User: 我们试着把它改写成函数式风格+[在实验前创建 checkpoint]++Claude: [执行实验性修改]++User: 测试失败了。我们回退吧。+[用户按下 Esc+Esc 并回退到 checkpoint]++Claude: 我已经回退这些更改了。我们试另一个方案。+```++### 示例 4:分支式探索++```text+User: 我想比较两种数据库设计+[记下 checkpoint,命名为 "Start"]++Claude: 我先实现第一种设计……+[实现 Schema A]++User: 现在让我回去试第二种方案+[用户按下 Esc+Esc 并回退到 "Start"]++Claude: 现在我实现 Schema B……+[实现 Schema B]++User: 太好了,我现在有两个 schema 可以选择+```++## Checkpoint 保留策略++Claude Code 会自动管理你的 checkpoints:++- 每次用户输入都会自动创建 checkpoint+- 旧 checkpoint 最多保留 30 天+- 系统会自动清理,避免存储无限增长++## 工作流模式++### 探索时的分支策略++当你在探索多个方案时:++```text+1. 从初始实现开始 → Checkpoint A+2. 尝试方案 1 → Checkpoint B+3. 回退到 Checkpoint A+4. 尝试方案 2 → Checkpoint C+5. 比较 B 和 C 的结果+6. 选择最佳方案并继续+```++### 安全重构模式++当你在做大改动时:++```text+1. 当前状态 → Checkpoint(自动)+2. 开始重构+3. 运行测试+4. 如果测试通过 → 继续+5. 如果测试失败 → Rewind 并尝试别的方案+```++## 最佳实践++因为 checkpoints 是自动创建的,所以你可以专注于工作,而不用担心手动保存状态。不过,下面这些习惯仍然很重要:++### 如何高效使用 Checkpoints++✅ **应该做:**+- 回退前先看清楚可用的 checkpoints+- 当你想尝试不同方向时使用 rewind+- 保留 checkpoints 方便比较不同方案+- 理解每个 rewind 选项的作用(恢复代码和对话、恢复对话、恢复代码、或总结)++❌ **不要做:**+- 只依赖 checkpoints 来保存代码+- 指望 checkpoints 跟踪外部文件系统变化+- 把 checkpoints 当成 git commit 的替代品++## 配置++你可以在设置中开启或关闭自动 checkpoints:++```json+{+ "autoCheckpoint": true+}+```++- `autoCheckpoint`:是否在每次用户提示后自动创建 checkpoint(默认:`true`)++## 局限性++Checkpoints 很适合会话级回退,但它不是版本控制系统。对于需要长期保存、可审计、可共享的改动,仍然应该使用 git。++## 故障排查++### 找不到 Checkpoints++- 检查你是否在支持该功能的 Claude Code 版本中+- 确认自动 checkpoint 没有被关闭+- 重新打开会话再试一次++### Rewind 失败++- 确认你选择了一个有效的 checkpoint+- 查看是否存在与文件系统或权限相关的限制+- 尝试先分别恢复代码或对话,再决定是否同时恢复两者++## 与 Git 的集成++Checkpoints 和 git 是互补关系:++- Checkpoints 用于会话内探索和安全试验+- Git 用于永久保存代码历史+- 你可以先用 checkpoints 快速试错,再把最终方案提交到 git++## 快速开始++### 基本工作流++```text+1. 开始修改前自动创建 checkpoint+2. 尝试某个方案+3. 如果结果不理想,按 Esc 两次+4. 选择合适的 rewind 选项+5. 继续探索或提交最终方案+```++### 键盘快捷键++- `Esc` + `Esc`:打开 checkpoint 浏览器+- `/rewind`:通过命令进入回退界面+- `/checkpoint`:`/rewind` 的别名++## 什么时候该 rewind:上下文监控++如果你发现这些信号,通常就该回退了:++- 当前方案开始变复杂,而且你还没确定方向+- 测试刚失败,问题可能就是最近一两步引入的+- 你想比较两种实现方式+- 你想保留一个“干净起点”继续探索++## 相关概念++- **Memory**:跨会话的长期上下文,见 [02-memory/README.md](../02-memory/README.md)+- **Hooks**:事件驱动自动化,见 [06-hooks/README.md](../06-hooks/README.md)+- **Plugins**:打包功能集合,见 [07-plugins/README.md](../07-plugins/README.md)+- **Advanced Features**:包括 planning mode 和背景任务,见 [09-advanced-features/README.md](../09-advanced-features/README.md)++## 更多资源++- [根目录中文指南](../README.md)+- [Claude Code 官方检查点文档](https://code.claude.com/docs/en/checkpointing)+- [Claude Code 高级功能指南](../09-advanced-features/README.md)++## 总结++Checkpoints 的价值在于让你敢于试错。它让“先试再说”和“试错后立刻回退”变得安全,从而帮你更快找到正确方案。diff --git a/zh/08-checkpoints/checkpoint-examples.md b/zh/08-checkpoints/checkpoint-examples.mdnew file mode 100644index 0000000..9e06caf--- /dev/null+++ b/zh/08-checkpoints/checkpoint-examples.md@@ -0,0 +1,339 @@+# 检查点示例++以下是一些在 Claude Code 中有效使用检查点的真实示例。++注意:每次用户提示都会自动创建检查点。你不需要手动保存。要回退,请连续按两次 `Esc`(`Esc+Esc`),或者使用 `/rewind` 打开检查点浏览器。++## 示例 1:数据库迁移++### 场景+你需要从 MySQL 迁移到 PostgreSQL,但想同时探索直接迁移和渐进式双写两种方案。++### 工作流程++```+用户:我们来实现一个从 MySQL 到 PostgreSQL 的直接迁移方案+ [检查点 A 自动创建]++Claude:我来实现直接迁移……+[更换数据库驱动、更新查询、修改 schema]++用户:运行测试+ [检查点 B 自动创建]++Claude:正在运行测试……+❌ 15 个测试失败 - 连接池问题++用户:这个方案有问题。我们改试双写模式。+[用户按下 Esc+Esc,选择检查点 A,选择“恢复代码和对话”]++用户:现在实现双写模式,同时向两个数据库写入++Claude:我来实现双写迁移……+[实现双写层、渐进式迁移策略]++用户:运行测试++Claude:正在运行测试……+✅ 所有测试通过++用户:双写方案明显更稳妥。我们提交这个版本。+```++## 示例 2:性能优化++### 场景+尝试多种性能优化策略。++### 工作流程++```+用户:我们来优化 API 响应时间。当前:450ms+ [检查点“Baseline”自动创建]++Claude:我来加数据库查询缓存……+[实现 Redis 缓存]++用户:运行性能测试++Claude:结果:平均响应时间 280ms(提升 38%)++用户:我想试试另一种方法。+[用户按下 Esc+Esc,选择“Baseline”检查点,选择“恢复代码和对话”]++用户:改试数据库查询优化++Claude:我来优化数据库查询……+[添加索引,优化 N+1 查询]++用户:运行性能测试++Claude:结果:平均响应时间 180ms(提升 60%)++用户:我也想试第三种方法。+[用户按下 Esc+Esc,选择“Baseline”检查点,选择“恢复代码和对话”]++用户:尝试响应压缩和 CDN++Claude:我来添加压缩和 CDN……+[实现 gzip,配置 CDN]++用户:运行性能测试++Claude:结果:平均响应时间 320ms(提升 29%)++用户:查询优化最好。让我回到那个版本,再和缓存结合起来。+[用户按下 Esc+Esc,选择查询优化后的检查点,选择“恢复代码和对话”]++用户:现在在这些优化后的查询之上再加上 Redis 缓存++Claude:[在优化后的查询之上添加 Redis 缓存]++用户:运行性能测试++Claude:结果:平均响应时间 95ms(提升 79%)🎉++用户:完美!这就是最终方案。我们提交它。+```++## 示例 3:UI/UX 迭代++### 场景+为仪表板尝试不同布局。++### 工作流程++```+用户:我们来把仪表板重设计成侧边栏布局+ [检查点“Start”自动创建]++Claude:[实现侧边栏布局]++用户:给我看一张截图++Claude:[显示截图]++用户:侧边栏太拥挤了。我们试试顶部导航吧。+[用户按下 Esc+Esc,选择“Start”检查点,选择“恢复代码和对话”]++用户:试试顶部导航布局++Claude:[实现顶部导航]++用户:给我看一张截图++Claude:[显示截图]++用户:好多了,不过我们再试试卡片式网格布局。+[用户按下 Esc+Esc,选择“Start”检查点,选择“恢复代码和对话”]++用户:试试卡片式网格布局++Claude:[实现卡片网格]++用户:给我看一张截图++Claude:[显示截图]++用户:这个很不错!不过我们能把顶部导航和卡片网格结合起来吗?+[用户按下 Esc+Esc,选择卡片网格后的检查点,选择“恢复代码和对话”]++用户:给卡片网格布局加上顶部导航++Claude:[在卡片网格上添加顶部导航]++用户:完美!这就是最终设计。+```++## 示例 4:调试会话++### 场景+用多个假设排查一个难缠的 bug。++### 工作流程++```+用户:应用里有内存泄漏+ [检查点“Before debugging”自动创建]++Claude:让我来调查……+[分析代码]++用户:我觉得问题在事件监听器里。我们先修这个。++Claude:[修复事件监听器清理逻辑]++用户:运行内存分析器++Claude:仍然在泄漏内存 - 事件监听器不是问题所在++用户:让我回到之前,换个思路试试。+[用户按下 Esc+Esc,选择“Before debugging”检查点,选择“恢复代码和对话”]++用户:也许是数据库连接的问题?++Claude:[实现连接池修复]++用户:运行内存分析器++Claude:还是在泄漏 - 也不是连接的问题++用户:我再回去,换另一个方向试试。+[用户按下 Esc+Esc,选择“Before debugging”检查点,选择“恢复代码和对话”]++用户:我们检查一下有没有循环引用++Claude:[找到并修复缓存中的循环引用]++用户:运行内存分析器++Claude:✅ 内存泄漏修复了!缓存层里的循环引用就是罪魁祸首。++用户:太好了!我们提交这个修复。+```++## 示例 5:API 设计演进++### 场景+为 REST API 设计做多轮迭代。++### 工作流程++```+用户:给我们的博客平台创建一个 REST API+ [检查点“Before API design”自动创建]++Claude:[创建基础 CRUD API]++用户:这个太简单了。加上分页和过滤++Claude:[添加分页和过滤]++用户:我们需要更好的资源关系++Claude:[实现 HATEOAS 链接]++用户:其实我们改用 GraphQL,不用 REST 了+[用户按下 Esc+Esc,选择“Before API design”检查点,选择“恢复代码和对话”]++用户:那就为我们的博客平台改实现 GraphQL API 吧++Claude:[实现 GraphQL API]++用户:我觉得 REST 更适合我们的场景。+[用户按下 Esc+Esc,选择 HATEOAS 之后的检查点,选择“恢复代码和对话”]++用户:那我们就把 REST 方案定下来。+```++## 示例 6:配置管理++### 场景+测试不同的配置方案。++### 工作流程++```+用户:把配置迁移到环境变量+ [检查点“Original config”自动创建]++Claude:[实现环境变量配置]++用户:在开发环境里测试++Claude:本地可用,但生产环境部署有问题++用户:我换个方案试试。+[用户按下 Esc+Esc,选择“Original config”检查点,选择“恢复代码和对话”]++用户:改成带校验的配置文件方案++Claude:[实现带 JSON Schema 校验的 YAML 配置]++用户:在开发环境里测试++Claude:✅ 运行良好,校验错误提示也很清楚++用户:我们也能为敏感值支持环境变量吗?++Claude:[为密钥添加环境变量覆盖]++用户:测试部署++Claude:✅ 所有环境都正常工作++用户:完美,这个已经可以用于生产。+```++## 示例 7:测试策略++### 场景+实现完整的测试体系。++### 工作流程++```+用户:给 auth 模块添加单元测试+ [检查点自动创建]++Claude:[添加 Jest 单元测试]++用户:运行测试++Claude:45 个测试通过,覆盖率 78%++用户:再加上集成测试++Claude:[添加集成测试]++用户:运行测试++Claude:89 个测试通过,覆盖率 92%,但测试太慢了(3 分钟)++用户:测试太慢了,我们来优化。++Claude:[优化测试设置,增加并行执行]++用户:运行测试++Claude:89 个测试通过,覆盖率 92%,35 秒完成 ✅++用户:很好!再给关键路径加上 E2E 测试。++Claude:[添加 Playwright E2E 测试]++用户:运行所有测试++Claude:112 个测试通过,覆盖率 94%,2 分钟完成++用户:很好,覆盖率和速度都平衡得不错!+```++## 示例 8:从检查点开始总结++### 场景+在一次很长的调试会话后,你想压缩对话内容,同时保留上下文。++### 工作流程++```+用户:[经过 20 多条消息的调试和探索之后]++[用户按下 Esc+Esc,选择较早的检查点,选择“从这里开始总结”]+[可选地提供指令:“重点保留我们尝试过什么,以及什么有效”]++Claude:[生成从该点开始的对话总结]+[原始消息保留在记录里]+[总结会替换当前可见对话,从而减少上下文窗口占用]++用户:现在继续推进那个有效的方案。+```++## 关键结论++1. **检查点是自动创建的**:每次用户提示都会创建一个检查点,不需要手动保存。+2. **使用 `Esc+Esc` 或 `/rewind`**:这两种方式都可以打开检查点浏览器。+3. **选择合适的恢复方式**:根据需要恢复代码、对话、两者都恢复,或者直接总结。+4. **不要害怕试验**:检查点让你可以安全尝试激进的改动。+5. **和 git 结合使用**:检查点用于探索,git 用于最终落地。+6. **长会话要及时总结**:用“从这里开始总结”来保持对话可管理。diff --git a/zh/09-advanced-features/README.md b/zh/09-advanced-features/README.mdnew file mode 100644index 0000000..32fe9ac--- /dev/null+++ b/zh/09-advanced-features/README.md@@ -0,0 +1,954 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# 高级功能++这是一份关于 Claude Code 高级能力的完整指南,涵盖 planning mode、extended thinking、auto mode、后台任务、权限模式、打印模式(非交互)、会话管理、交互功能、消息通道(Channels)、语音输入、远程控制、网页会话、桌面应用、任务列表、提示词建议、Git 工作树、沙盒、受管设置和配置。++## 目录++1. [概览](#概览)+2. [规划模式](#规划模式)+3. [扩展思考](#扩展思考)+4. [自动模式](#自动模式)+5. [后台任务](#后台任务)+6. [定时任务](#定时任务)+7. [权限模式](#权限模式)+8. [无头模式](#无头模式)+9. [会话管理](#会话管理)+10. [交互功能](#交互功能)+11. [语音输入](#语音输入)+12. [消息通道(Channels)](#消息通道channels)+13. [Chrome 集成](#chrome-集成)+14. [远程控制](#远程控制)+15. [网页会话](#网页会话)+16. [桌面应用](#桌面应用)+17. [任务列表](#任务列表)+18. [提示词建议](#提示词建议)+19. [Git 工作树(Git Worktrees)](#git-工作树git-worktrees)+20. [沙盒](#沙盒)+21. [企业受管设置](#企业受管设置)+22. [配置与设置](#配置与设置)+23. [最佳实践](#最佳实践)+24. [更多资源](#更多资源)++---++<a id="overview"></a>+## 概览++Claude Code 的高级功能把基础能力扩展到了规划、推理、自动化和控制层面。它们能支持更复杂的开发任务、代码审查、自动化流程以及多会话管理。++**核心高级功能包括:**+- **Planning Mode**:先写详细实现计划,再开始编码+- **Extended Thinking**:对复杂问题进行更深入的推理+- **Auto Mode**:由后台安全分类器在每一步执行前进行审查(Research Preview)+- **Background Tasks**:长时间任务不阻塞对话+- **Permission Modes**:控制 Claude 可以做什么(`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions`)+- **Print Mode**:非交互式运行,适合自动化和 CI/CD(`claude -p`)+- **Session Management**:管理多个会话+- **Interactive Features**:快捷键、多行输入、历史记录+- **Voice Dictation**:按住说话,支持 20 种语言的语音识别+- **Channels**:消息通道,允许 MCP server 向运行中的会话推送消息(Research Preview)+- **Remote Control**:从 Claude.ai 或 Claude app 控制本地会话+- **Web Sessions**:在浏览器中运行 Claude Code+- **Desktop App**:支持可视化 diff 审查和多会话的独立应用+- **Task List**:跨 context compaction 持久跟踪任务+- **Prompt Suggestions**:根据上下文智能推荐命令+- **Git 工作树(Git Worktrees)**:隔离的 worktree 分支,适合并行工作+- **Sandboxing**:操作系统级文件系统和网络隔离+- **Managed Settings**:通过 plist、Registry 或受管文件进行企业部署+- **Configuration**:用 JSON 配置文件定制行为++<a id="planning-mode"></a>+## 规划模式++更多规划示例见 [planning-mode-examples.md](planning-mode-examples.md)。++Planning mode 允许 Claude 在真正实现前先梳理复杂任务,生成一份你可以审阅并批准的详细计划。++### 什么是 Planning Mode?++Planning mode 是一个两阶段流程:+1. **规划阶段**:Claude 分析任务并生成详细实现计划+2. **实现阶段**:在你批准后,Claude 执行计划++### 什么时候使用 Planning Mode++✅ 适合:+- 复杂的多文件重构+- 新功能开发+- 架构调整+- 数据库迁移+- 大型 API 重设计++❌ 不建议:+- 简单 bug 修复+- 格式化修改+- 单文件编辑+- 快速查询++### 如何启动 Planning Mode++**Slash command:**+```bash+/plan Implement user authentication system+```++**CLI 参数:**+```bash+claude --permission-mode plan+```++**设为默认:**+```json+{+ "permissions": {+ "defaultMode": "plan"+ }+}+```++**快捷键:**+- `Shift + Tab` - 切换权限模式(包括 plan)+- `Alt + M` - 切换权限模式(Windows/Linux)++### Planning Mode 的好处++- **结构化实施方式**:把实现步骤拆得更清楚+- **审阅和批准**:先看计划,再执行+- **风险识别**:先发现潜在问题+- **阶段清晰**:有明确的里程碑和阶段划分++### 示例:功能实现++```text+User: /plan Add a real-time notification system++Claude: 我会为实时通知系统制定计划。++## 实现计划++### 阶段 1:基础设施+1. 安装 WebSocket 库(socket.io)+2. 搭建 WebSocket server+3. 配置连接管理++### 阶段 2:后端+4. 创建通知服务+5. 实现通知队列+6. 为通知添加数据库 schema+7. 创建 API 端点++### 阶段 3:前端+8. 搭建 WebSocket client+9. 创建通知 UI 组件+10. 实现通知状态管理+11. 添加通知权限++### 阶段 4:测试与发布+12. 编写单元测试+13. 编写集成测试+14. 更新文档+15. 部署到 staging++预计时间:3-4 小时+需要修改的文件:12 个+需要创建的新文件:8 个++准备继续吗?(yes/no/modify plan)+```++### 计划修改++```text+User: 修改计划 - 先跳过队列,后面再加++Claude: 已更新计划:+[展示删除队列后的计划]++User: 看起来不错,继续++Claude: [按修改后的计划开始实现]+```++### Planning Mode 配置++你可以通过 CLI 参数或 slash command 启用 planning mode:++```bash+# 通过 CLI 启用 plan mode+claude --permission-mode plan++# 或在 REPL 里使用 /plan+/plan Implement user authentication system+```++**规划专用模型别名**:使用 `opusplan`,规划用 Opus,执行用 Sonnet:++```bash+claude --model opusplan "design and implement the new API"+```++**外部编辑计划**:按 `Ctrl+G` 可以把当前计划打开到外部编辑器里进行更详细的修改。++<a id="extended-thinking"></a>+## 扩展思考++Extended thinking 让 Claude 在给出解决方案前,花更多时间进行复杂推理。++### 什么是 Extended Thinking?++这是一个有意识的、分步骤的推理过程,Claude 会:+- 拆解复杂问题+- 比较多种方案+- 评估权衡+- 推导边界情况++### 如何启用++**快捷键:**+- `Option + T`(macOS)/ `Alt + T`(Windows/Linux)- 切换 extended thinking++**自动启用:**+- 对所有模型默认开启(Opus 4.6、Sonnet 4.6、Haiku 4.5)+- Opus 4.6 支持自适应推理,effort 等级为 `low`(○)、`medium`(◐)、`high`(●)、`max`(仅 Opus 4.6)++### 好处++- 更适合复杂问题+- 更容易发现边界条件+- 便于比较多个方案+- 输出通常更稳健++### 示例:架构决策++```text+Context Analysis+Approach 1: Microservices+Approach 2: Monolith+Decision Factors+Recommendation+```++### 配置++```json+{+ "thinking": {+ "enabled": true,+ "effort": "high"+ }+}+```++<a id="auto-mode"></a>+## 自动模式++Auto mode 是一个研究预览功能。它会在每个动作执行前,用后台安全分类器评估风险,帮助你在自动化和安全之间取得平衡。++### 需求++- 支持 auto mode 的 Claude Code 版本+- 合适的权限和配置++### 启用方式++```bash+# 用 CLI 解锁 auto mode+claude --enable-auto-mode++# 然后在 REPL 中用 Shift+Tab 切换到它+```++### 分类器如何工作++在执行工具前,后台分类器会判断这个动作是否安全、是否需要提示、是否应该被阻止。++### 默认阻止的动作++- 明显危险的文件操作+- 高风险 shell 命令+- 可能泄露凭据的操作++### 默认允许的动作++- 只读检查+- 常规分析+- 低风险修改++### 配置 Auto Mode++Auto mode 可以在设置中进一步约束、放宽或与权限模式结合使用。++### 回退行为++如果分类器无法判定,Claude 会回退到更保守的权限处理方式。++### 预置一份类似 Auto-Mode 的保守权限基线++```bash+# 先预览将要添加的权限(不会写入)++# 应用保守基线++# 只有在需要时再逐步增加能力+```++<a id="background-tasks"></a>+## 后台任务++后台任务允许 Claude 在不阻塞对话的情况下运行长时间操作。++### 什么是后台任务?++后台任务适合长时间运行的工作,例如构建、测试、下载、扫描或并行分析。你可以把它们交给 Claude,让对话继续保持响应。++### 启动后台任务++你可以从命令、计划或工具链中启动后台任务,让 Claude 在后台继续工作。++### 管理后台任务++- 查看任务状态+- 中止任务+- 等待任务完成+- 从结果中恢复上下文++### 示例:并行开发++```text+任务 A:运行测试+任务 B:生成文档+任务 C:执行安全扫描+```++### 配置++后台任务的超时、并发和通知行为都可以在设置中调整。++<a id="scheduled-tasks"></a>+## 定时任务++Scheduled tasks 让 Claude 按计划重复执行某些提示词或任务。++### `/loop` 命令++```bash+# 显式间隔+/loop 10m Run tests and report failures++# 自然语言+/loop every day at 9am check release notes+```++### 一次性提醒++```bash+/schedule "remind me to review the PR in 30 minutes"+```++### 管理定时任务++- 查看任务列表+- 修改执行频率+- 暂停或取消任务++### 行为细节++定时任务会遵循当前会话与权限配置,并按计划触发执行。++### 云端定时任务++部分场景可以在云端环境中运行调度任务。++### 禁用定时任务++如果你不希望自动触发,关闭相关设置即可。++### 示例:监控部署++```text+每 5 分钟检查一次部署状态,直到 health check 通过。+```++<a id="permission-modes"></a>+## 权限模式++Permission modes 决定 Claude 可以直接执行哪些操作。++### 可用模式++- `default`+- `acceptEdits`+- `plan`+- `auto`+- `dontAsk`+- `bypassPermissions`++### 启用方式++可以通过命令行、设置或会话中的快捷操作切换权限模式。++### 示例++#### Default Mode++默认的平衡模式,必要时会询问权限。++#### Plan Mode++只做规划,不直接执行高风险改动。++#### Accept Edits Mode++更偏向自动接受编辑,适合受控环境。++### 使用场景++- 代码审查+- 自动化重构+- CI/CD+- 高风险操作前的审批流程++<a id="headless-mode"></a>+## 无头模式++Headless mode 指非交互式运行 Claude Code,常用于自动化和 CI/CD。++### 什么是 Print Mode?++Print mode 就是 `claude -p`:给一个任务,输出结果,然后退出。++### 在 Print Mode 中运行++```bash+# 运行指定任务+claude -p "run tests and summarize failures"++# 处理管道内容+cat logs.txt | claude -p "find the root cause"++# CI/CD 集成+claude -p "review this diff and return JSON"+```++### 其他示例++```bash+# 捕获输出+claude -p "analyze this code" > report.txt++# 结构化输出+claude -p --output-format json "list files"++# 标准输入+echo "hello" | claude -p "translate to Chinese"+```++### CI/CD 示例++```yaml+# .github/workflows/code-review.yml+```++### Print Mode 配置++- 限制自主回合数+- 使用结构化 JSON 输出+- 启用 schema 验证+- 禁用会话持久化++<a id="session-management"></a>+## 会话管理++会话管理用于在多个会话之间恢复、重命名、分叉和持续工作。++### 常用命令++- `/resume`+- `/rename`+- `/fork`+- `claude -c`+- `claude -r`++### 恢复会话++```bash+# 继续最后一次对话+claude -c++# 恢复指定名称或 ID 的会话+claude -r "feature-auth"+```++### 分叉会话++```bash+# 恢复并分叉,适合实验+claude -r "feature-auth" --fork+```++### 会话持久化++你可以选择保留、继续或重建会话上下文。++<a id="interactive-features"></a>+## 交互功能++交互功能包括快捷键、多行输入、历史记录、Vim 模式和 Bash 模式等。++### 快捷键++常用快捷键用于切换模式、编辑输入、查看历史和控制输出。++### 自定义快捷键++你可以在设置中绑定自己的按键组合。++### 可用上下文++不同上下文会影响快捷键的可用性和行为。++### Chord 支持++支持组合按键触发复杂操作。++### 保留键与冲突键++某些按键会被系统或终端占用,需要避免冲突。++### Tab 补全++输入命令、参数或路径时会提供补全建议。++### 命令历史++Claude 会保留历史记录,方便你快速重用之前的输入。++### 多行输入++```text+第一行+第二行+第三行+```++### 行内编辑++支持在输入过程中编辑中间内容。++### Vim 模式++如果你熟悉 Vim,可以启用类似的编辑体验。++### Bash 模式++可在会话中直接进入更偏 shell 风格的操作方式。++<a id="voice-dictation"></a>+## 语音输入++语音输入支持按住说话和多语言识别,适合快速记录想法或在不方便键盘输入时使用。++### 如何启用++在设置中打开语音输入即可。++### 特性++- 支持按住说话+- 支持 20 种语言的语音识别+- 适合快速口述任务++### 配置++可在 settings 中控制灵敏度、语言和输入行为。++<a id="channels"></a>+## 消息通道(Channels)++消息通道允许 MCP servers 向正在运行的会话推送消息。++### 订阅 channels++```bash+# 启动时订阅 channel 插件+```++### 支持的集成++- Discord+- Telegram+- 其他 channel 型集成++### 配置++通过 MCP 配置或 settings 订阅相应 channel。++### 工作方式++外部系统可以把消息推送进 Claude 的当前会话里,让你在一个会话中接收通知或事件。++<a id="chrome-integration"></a>+## Chrome 集成++Chrome 集成让 Claude 可以协助浏览器自动化和站点级操作。++### 启用 Chrome 集成++开启相关开关后,Claude 就可以与浏览器协作。++### 能力++- 浏览器自动化+- 页面操作+- 网站级交互++### 站点级权限++你可以对站点设置更细粒度的访问权限。++### 工作方式++Claude 通过浏览器连接与页面交互。++### 已知限制++- 某些站点会限制自动化+- 复杂页面可能需要更多权限++<a id="remote-control"></a>+## 远程控制++Remote Control 可以让你从 Claude.ai 或 Claude app 远程控制本地 Claude Code 会话。++### 启动 Remote Control++```bash+# 使用默认会话名启动+claude --remote-control++# 使用自定义名称+claude --remote-control --name my-session+```++### 连接到会话++你可以在远程端连接到已经启动的本地会话,继续同一个上下文。++### 安全性++远程控制会牵涉到会话和权限,因此建议只在可信环境中使用。++### Remote Control vs Claude Code on the web++Remote Control 是控制本地会话;web 版则是在浏览器中直接运行。++### 局限++- 网络可用性依赖更高+- 某些本地资源可能不可远程访问++### 使用场景++- 在手机上查看并接管会话+- 远程继续长期任务++<a id="web-sessions"></a>+## 网页会话++Web Sessions 允许你直接在浏览器里创建和恢复 Claude Code 会话。++### 创建 Web Session++```bash+# 从 CLI 创建新的 web session+claude --remote "implement API"+```++### 在本地恢复 Web Session++```bash+# 在本地终端恢复 web session+claude --teleport+```++### 使用场景++- 浏览器里快速开始任务+- 在本地和网页之间切换+- 远程继续工作++<a id="desktop-app"></a>+## 桌面应用++桌面应用提供独立界面,适合视觉化 diff 审查和多会话管理。++### 安装++按照桌面应用的安装说明安装即可。++### 从 CLI 接力++你可以把 CLI 会话交给桌面应用继续处理。++### 核心功能++- 可视化 diff+- 多会话+- 更直观的审查体验++### App 预览配置++可以调整预览、布局和视觉呈现方式。++### Connectors++桌面应用可以连接到不同的工作环境。++### 远程和 SSH 会话++桌面应用也支持远程或 SSH 场景下的接力。++### Desktop 中的权限模式++Desktop 里同样可以使用不同的权限模式。++### 企业功能++企业部署下可使用更多受管和合规相关能力。++<a id="task-list"></a>+## 任务列表++Task List 用于跨 context compaction 持久保存任务进度。++### 切换任务列表++在设置里打开或关闭任务列表显示。++### 持久任务++任务会保留,即使上下文被压缩,也能继续跟踪。++### 命名任务目录++你可以给任务分组或目录命名,方便管理。++<a id="prompt-suggestions"></a>+## 提示词建议++Prompt suggestions 会根据当前上下文智能推荐下一步命令或提示词。++### 工作方式++系统会结合你的历史、当前任务和上下文给出建议。++### 禁用建议++如果你不想看到建议,可以在设置里关闭。++<a id="git-worktrees"></a>+## Git 工作树(Git Worktrees)++Git worktrees 让你在隔离的目录里并行工作,非常适合实验和分支开发。++### 从 worktree 启动++```bash+# 在隔离 worktree 中启动 Claude Code+claude -w+```++### Worktree 位置++你可以控制 worktree 的放置位置,保持主工作区整洁。++### Monorepo 的 sparse checkout++在大型 monorepo 中,可配合 sparse checkout 只加载需要的部分。++### Worktree 工具和 Hooks++worktree 场景下依然可以配合工具和 hooks 自动化流程。++### 自动清理++不需要的 worktree 可以自动清理。++### 使用场景++- 并行尝试多个方案+- 隔离高风险重构+- 保持主分支整洁++<a id="sandboxing"></a>+## 沙盒++沙盒提供文件系统和网络层面的隔离,能显著降低自动化操作的风险。++### 启用沙盒++开启后,Claude 的很多操作都会在受控环境里执行。++### 配置项++你可以配置允许访问的目录、网络行为和例外列表。++### 示例配置++```json+{+ "sandbox": {+ "enabled": true+ }+}+```++### 工作方式++沙盒会限制 Claude 可触达的文件和网络边界。++### 使用场景++- 低风险自动化+- 在不完全信任的输入上执行任务+- 受控环境中的批处理++<a id="managed-settings-enterprise"></a>+## 企业受管设置++企业可以通过受管设置统一分发 Claude Code 配置。++### 部署方式++- plist+- Registry+- 受管文件++### 受管配置片段++通过受管配置片段,可以给团队统一推送策略。++### 可用的受管设置++- 权限模式+- 功能开关+- MCP / hooks / 插件约束++### macOS plist 示例++```xml+<!-- 示例略 -->+```++<a id="configuration-and-settings"></a>+## 配置与设置++### 配置文件位置++- `~/.claude/settings.json`+- `.claude/settings.json`+- `.claude/settings.local.json`++### 完整配置示例++```json+{+ "permissions": {+ "defaultMode": "plan"+ },+ "thinking": {+ "enabled": true,+ "effort": "high"+ },+ "autoCheckpoint": true+}+```++### 环境变量++#### 模型选择++- `ANTHROPIC_API_KEY`+- `CLAUDE_MODEL`++#### API 配置++- `ANTHROPIC_API_KEY`++#### Thinking 配置++- `CLAUDE_EFFORT`++#### 功能开关++- `CLAUDE_ENABLE_AUTO_MODE`++#### MCP 配置++- `CLAUDE_MCP_CONFIG`++#### 任务管理++- `CLAUDE_TASK_LIST`++#### Agent team(实验性)++- `CLAUDE_TEAM_MODE`++#### Subagent 和 plugin 配置++- `CLAUDE_PLUGIN_DATA`++#### 子进程和流式处理++- `CLAUDE_OUTPUT_FORMAT`++### 配置管理命令++你可以用命令查看或更新当前配置,并把它们落到 settings 中。++### 每个项目的配置++推荐把项目专用设置放进项目内的 `.claude/settings.json`,这样能跟代码一起版本化。++<a id="best-practices"></a>+## 最佳实践++### Planning Mode++- 复杂任务先规划,再实现+- 计划要可审阅++### Extended Thinking++- 留给复杂问题+- 不要在简单任务上过度使用++### Background Tasks++- 用于长时间、可并行的任务+- 记得设置超时和可见性++### Permissions++- 默认最小权限+- 只在必要时放宽++### Sessions++- 为重要会话命名+- 必要时分叉,而不是硬改++<a id="additional-resources"></a>+## 更多资源++- [根目录中文指南](../README.md)+- [Slash Commands 中文参考](../01-slash-commands/README.md)+- [Checkpoints 中文指南](../08-checkpoints/README.md)+- [Plugins 中文指南](../07-plugins/README.md)+- [CLI 中文参考](../10-cli/README.md)diff --git a/zh/09-advanced-features/planning-mode-examples.md b/zh/09-advanced-features/planning-mode-examples.mdnew file mode 100644index 0000000..80ffe2e--- /dev/null+++ b/zh/09-advanced-features/planning-mode-examples.md@@ -0,0 +1,533 @@+# 计划模式示例++以下是 Claude Code 中有效使用计划模式的真实示例。++## 示例 1:构建 REST API++### 不使用计划模式++```+用户:给博客做一个 REST API++Claude:我来创建这个 API……+[立刻开始编码,可能漏掉需求]+```++### 使用计划模式++```+用户:/plan 给博客做一个 REST API++Claude:我来为这个博客 API 制定一份完整计划。++## 博客 REST API 实现计划++### 阶段 1:项目初始化(15 分钟)+1. 初始化带 Express 的 Node.js 项目+2. 配置 TypeScript+3. 安装依赖(express、pg、jwt、joi)+4. 配置环境变量+5. 搭建项目结构++### 阶段 2:数据库层(30 分钟)+6. 设计数据库 schema+ - users 表(id、email、password_hash、created_at)+ - posts 表(id、user_id、title、content、published、created_at、updated_at)+ - comments 表(id、post_id、user_id、content、created_at)+7. 创建迁移文件+8. 搭建数据库连接池+9. 实现数据库模型++### 阶段 3:认证(45 分钟)+10. 实现用户注册接口+11. 实现带 JWT 的登录接口+12. 创建认证中间件+13. 使用 bcrypt 添加密码哈希+14. 实现 token 刷新逻辑++### 阶段 4:Posts API(40 分钟)+15. GET /api/posts - 获取所有已发布文章(支持分页)+16. GET /api/posts/:id - 获取单篇文章+17. POST /api/posts - 创建新文章(需要认证)+18. PUT /api/posts/:id - 更新文章(需要认证,检查所有权)+19. DELETE /api/posts/:id - 删除文章(需要认证,检查所有权)+20. GET /api/users/:id/posts - 获取某个用户的文章++### 阶段 5:Comments API(30 分钟)+21. GET /api/posts/:id/comments - 获取文章评论+22. POST /api/posts/:id/comments - 添加评论(需要认证)+23. DELETE /api/comments/:id - 删除评论(需要认证,检查所有权)++### 阶段 6:校验与错误处理(30 分钟)+24. 使用 Joi 添加请求校验+25. 实现全局错误处理器+26. 添加输入清洗+27. 实现速率限制++### 阶段 7:测试(60 分钟)+28. 为模型编写单元测试+29. 为认证接口编写集成测试+30. 为文章接口编写集成测试+31. 为评论接口编写集成测试+32. 达到 80%+ 的代码覆盖率++### 阶段 8:文档与部署(30 分钟)+33. 使用 Swagger 生成 API 文档+34. 创建包含安装说明的 README+35. 添加 Docker 配置+36. 搭建 CI/CD 流水线++**预估时间**:4.5 小时+**需要创建的文件**:约 25 个+**关键技术**:Express、PostgreSQL、JWT、TypeScript++**API 端点概览**:+- 认证:2 个端点+- 文章:6 个端点+- 评论:3 个端点+- 总计:11 个端点++准备继续吗?(yes/no/modify)++用户:yes++Claude:开始阶段 1:项目初始化……+[按阶段系统性实现]+```++## 示例 2:数据库迁移++### 使用计划模式++```+用户:/plan 将数据库从 MongoDB 迁移到 PostgreSQL++Claude:这是一次复杂迁移。我来制定详细计划。++## MongoDB 到 PostgreSQL 的迁移计划++### 阶段 1:分析与准备(第 1 天)+1. 分析当前 MongoDB schema+2. 识别数据关系和约束+3. 记录当前数据量和增长速率+4. 设计对应的 PostgreSQL schema+5. 规划数据类型映射+6. 识别潜在迁移挑战++### 阶段 2:PostgreSQL 准备(第 1 天)+7. 搭建 PostgreSQL 数据库+8. 创建包含表、索引和约束的 schema+9. 配置连接池+10. 制定备份策略++### 阶段 3:双写实现(第 2-3 天)+11. 创建数据库抽象层+12. 实现同时向两个数据库写入+13. 添加数据一致性检查+14. 在预发布环境部署双写+15. 监控问题++### 阶段 4:数据迁移(第 4 天)+16. 为 MongoDB 创建数据导出脚本+17. 为 PostgreSQL 创建数据导入脚本+18. 实现数据转换逻辑+19. 在生产数据副本上执行初次迁移+20. 验证迁移后数据完整性++### 阶段 5:渐进切换(第 5-7 天)+21. 在生产环境开启双写+22. 分批迁移历史数据+23. 持续验证数据一致性+24. 监控两个数据库+25. 修复任何数据同步问题++### 阶段 6:PostgreSQL 作为主库(第 8 天)+26. 将读操作切换到 PostgreSQL+27. 监控查询性能+28. 优化慢查询+29. 继续保留双写作为安全措施++### 阶段 7:MongoDB 退役(第 9-10 天)+30. 停止向 MongoDB 写入+31. 保留 MongoDB 作为两周备份+32. 从代码中移除 MongoDB 依赖+33. 归档 MongoDB 数据+34. 下线 MongoDB 实例++**预估时间**:10 天+**风险等级**:高+**回滚策略**:保持 MongoDB 运行并开启双写+**成功标准**:+- 零数据丢失+- 性能回退小于 5%+- 所有测试通过++**关键风险**:+1. 迁移过程中的数据不一致+2. 查询性能下降+3. 应用停机+4. 数据丢失++**缓解措施**:+- 采用双写模式保障安全+- 渐进式切换+- 持续监控+- 快速回滚能力++是否按此计划继续?(yes/no/modify)++用户:modify - 我们给每个阶段都加上回滚方案++Claude:我已经为每个阶段补充了回滚流程……+```++## 示例 3:前端重构++```+用户:/plan 把我们的 React 应用从 class 组件重构为 hooks++Claude:我来制定一个系统化的重构计划。++## React Class 到 Hooks 迁移计划++### 阶段 1:准备与分析(2 小时)+1. 审查所有 class 组件(查找所有 .jsx/.tsx 文件)+2. 按复杂度分类:+ - 简单型(仅 state):约 15 个组件+ - 中等型(生命周期方法):约 23 个组件+ - 复杂型(多个生命周期、refs):约 8 个组件+3. 识别需要更新的第三方库+4. 创建组件依赖图+5. 规划迁移顺序(先叶子节点)++### 阶段 2:环境与工具(1 小时)+6. 将 React 升级到 v18++7. 为 hooks 配置 ESLint 规则+8. 创建转换模板+9. 配置自动化测试+10. 在开始前创建一个检查点++### 阶段 3:迁移简单组件(4 小时)+11. 转换简单的有状态组件(15 个)+12. 用 `useState` 替换 `this.state`+13. 用状态 setter 替换 `this.setState`+14. 每个组件转换后都进行测试+15. 更新测试++### 阶段 4:迁移中等复杂组件(8 小时)+16. 转换带生命周期方法的组件(23 个)+17. 用 `useEffect` 替换 `componentDidMount`+18. 用 `useEffect` 替换 `componentDidUpdate`+19. 用 `useEffect` 清理函数替换 `componentWillUnmount`+20. 做充分测试++### 阶段 5:迁移复杂组件(12 小时)+21. 转换复杂组件(8 个)+22. 用 `useRef` 替换 refs+23. 为共享逻辑提取自定义 hooks+24. 处理边缘情况(多个 `useEffect`)+25. 做深入测试++### 阶段 6:提取共享逻辑(6 小时)+26. 识别组件之间重复的逻辑+27. 创建自定义 hooks:+ - `useAuth`+ - `useFetch`+ - `useLocalStorage`+ - `useDebounce`+28. 将组件重构为使用自定义 hooks+29. 独立测试自定义 hooks++### 阶段 7:性能优化(4 小时)+30. 在需要的地方添加 `React.memo`+31. 使用 `useCallback` 优化+32. 使用 `useMemo` 优化+33. 分析并修复性能回退++### 阶段 8:收尾与文档(2 小时)+34. 移除未使用的 class 组件工具+35. 更新文档+36. 更新编码规范+37. 为团队编写迁移指南++**预估时间**:5 天(39 小时)+**需要修改的文件**:46 个组件+**风险等级**:中++**迁移顺序**:+1. 叶子组件(无依赖)+2. 中层组件+3. 顶层容器组件+4. `App.jsx`(最后)++**测试策略**:+- 每个组件的单元测试+- 用户流程的集成测试+- 视觉回归测试+- 性能基准测试++**成功指标**:+- 所有测试通过+- 没有视觉回归+- 性能保持或提升+- 打包体积没有明显增加++继续吗?(yes/no/modify)+```++## 示例 4:安全实现++```+用户:/plan 为我们的 Web 应用实现完整安全方案++Claude:我来制定一份全面的安全实施计划。++## Web 应用安全实施计划++### 阶段 1:安全审计(第 1 天)+1. 运行自动化安全扫描器(npm audit、Snyk)+2. 检查依赖中的漏洞+3. 核对 OWASP Top 10 合规性+4. 审查认证流程+5. 审查数据处理方式+6. 记录当前的安全缺口++### 阶段 2:认证加固(第 2-3 天)+7. 实现强密码要求+8. 添加密码强度检测器+9. 对登录接口实施限流+10. 在多次失败后锁定账户+11. 实现 2FA(TOTP)+12. 改进会话管理+13. 实现安全的密码重置流程++### 阶段 3:授权与访问控制(第 3-4 天)+14. 实现 RBAC(基于角色的访问控制)+15. 为所有端点添加权限检查+16. 实现最小权限原则+17. 为敏感操作添加审计日志+18. 实现资源级权限++### 阶段 4:数据保护(第 4-5 天)+19. 对敏感字段实施静态加密+20. 确保所有通信都使用 TLS/SSL+21. 实现安全的会话存储+22. 在日志中对 PII 数据做脱敏+23. 实现数据保留策略+24. 添加安全的文件上传处理++### 阶段 5:输入验证与清洗(第 5-6 天)+25. 为所有端点实现输入校验+26. 添加 XSS 防护(Content Security Policy)+27. 实现 SQL 注入防护(参数化查询)+28. 添加 CSRF 防护+29. 实现请求大小限制+30. 添加文件上传类型校验++### 阶段 6:安全头与配置(第 6 天)+31. 添加安全响应头:+ - Strict-Transport-Security+ - X-Content-Type-Options+ - X-Frame-Options+ - X-XSS-Protection+ - Content-Security-Policy+32. 正确配置 CORS+33. 禁用不必要的 HTTP 方法+34. 移除服务器版本头++### 阶段 7:监控与日志(第 7 天)+35. 实现安全事件日志+36. 添加异常检测+37. 搭建入侵检测+38. 实现实时告警+39. 创建安全仪表盘++### 阶段 8:测试与文档(第 8-9 天)+40. 执行渗透测试+41. 运行安全扫描器+42. 测试所有安全功能+43. 编写安全文档+44. 培训团队的安全实践+45. 编写事件响应计划++### 阶段 9:合规与政策(第 10 天)+46. 检查 GDPR 合规性+47. 创建隐私政策+48. 实现数据主体权利支持+49. 添加 cookie 同意机制+50. 编写安全政策文档++**预估时间**:10 天+**风险等级**:严重+**优先级**:高++**安全改进摘要**:+- 认证:7 项增强+- 授权:5 项增强+- 数据保护:6 项增强+- 输入校验:6 项增强+- 基础设施:9 项增强+- 监控:5 项增强++**合规性**:OWASP Top 10、GDPR++**成功标准**:+- 零严重漏洞+- 所有 OWASP Top 10 风险都得到缓解+- 安全评分高于 90/100+- 所有渗透测试问题都已解决++继续吗?(yes/no/modify)+```++## 示例 5:性能优化++```+用户:/plan 优化我们这个很慢的电商网站++Claude:我来制定一份完整的性能优化计划。++## 电商网站性能优化计划++### 阶段 1:性能审计(4 小时)+1. 运行 Lighthouse 审计+2. 分析 Chrome DevTools 性能剖析结果+3. 测量 Core Web Vitals:+ - LCP(Largest Contentful Paint)+ - FID(First Input Delay)+ - CLS(Cumulative Layout Shift)+4. 找出性能瓶颈+5. 创建基线性能指标++**当前指标**:+- LCP:4.2s(目标:<2.5s)+- FID:280ms(目标:<100ms)+- CLS:0.25(目标:<0.1)+- 页面加载:8.3s(目标:<3s)++### 阶段 2:图片优化(6 小时)+6. 将图片转换为 WebP 格式+7. 实现响应式图片+8. 为图片添加懒加载+9. 优化图片大小(压缩)+10. 为图片接入 CDN+11. 添加图片占位符++**预期影响**:加载时间减少 40%++### 阶段 3:代码拆分与懒加载(8 小时)+12. 实现基于路由的代码拆分+13. 懒加载非关键组件+14. 拆分第三方依赖包+15. 优化 chunk 大小+16. 实现动态导入+17. 为关键资源添加预加载++**预期影响**:初始 bundle 体积减少 30%++### 阶段 4:缓存策略(6 小时)+18. 实现浏览器缓存(Cache-Control)+19. 为离线支持添加 service worker+20. 实现 API 响应缓存+21. 为数据库查询添加 Redis 缓存+22. 实现 stale-while-revalidate+23. 配置 CDN 缓存++**预期影响**:API 响应时间减少 50%++### 阶段 5:数据库优化(8 小时)+24. 添加数据库索引+25. 优化慢查询(>100ms)+26. 实现查询结果缓存+27. 添加连接池+28. 在合适地方做反规范化+29. 实现数据库只读副本++**预期影响**:数据库查询时间减少 60%++### 阶段 6:前端优化(10 小时)+30. 最小化并压缩 JavaScript+31. 最小化并压缩 CSS+32. 移除未使用的 CSS(PurgeCSS)+33. 实现关键 CSS+34. 延迟加载非关键 JavaScript+35. 减少 DOM 规模+36. 优化 React 渲染(`memo`、`useMemo`)+37. 为长列表实现虚拟滚动++**预期影响**:JavaScript 执行时间减少 35%++### 阶段 7:网络优化(4 小时)+38. 启用 HTTP/2+39. 实现资源提示(preconnect、prefetch)+40. 减少 HTTP 请求数量+41. 启用 Brotli 压缩+42. 优化第三方脚本++**预期影响**:网络耗时减少 25%++### 阶段 8:监控与测试(4 小时)+43. 搭建性能监控(Datadog/New Relic)+44. 添加真实用户监控(RUM)+45. 制定性能预算+46. 搭建自动化 Lighthouse CI+47. 在真实设备上测试++**预估时间**:50 小时(2 周)++**目标指标**(90 分位):+- LCP:<2.0s(从 4.2s 降低)✅+- FID:<50ms(从 280ms 降低)✅+- CLS:<0.05(从 0.25 降低)✅+- 页面加载:<2.5s(从 8.3s 降低)✅++**预期收入影响**:+- 每快 100ms,转化率提升 1%+- 目标:缩短 5.8s,约带来 58% 的转化率提升+- 预估额外收入:显著++**优先级顺序**:+1. 图片优化(快速收益)+2. 代码拆分(高影响)+3. 缓存(高影响)+4. 数据库优化(关键)+5. 前端优化(打磨)++是否按此计划继续?(yes/no/modify)+```++## 关键要点++### 计划模式的优势++1. **清晰**:开始前就有明确路线图+2. **可估算**:能给出时间和工作量预估+3. **风险评估**:能尽早发现潜在问题+4. **优先级排序**:任务按合理顺序推进+5. **可审批**:执行前先审阅并确认+6. **可调整**:根据反馈及时修改计划++### 什么时候使用计划模式++✅ **建议始终使用于**:+- 多日项目+- 团队协作+- 关键系统变更+- 学习新概念+- 复杂重构++❌ **不建议使用于**:+- 修 bug+- 小改动+- 简单查询+- 快速实验++### 最佳实践++1. **审批前仔细审查** 计划+2. **发现问题就修改** 计划+3. **把复杂任务拆细**+4. **给出现实的时间估算**+5. **包含回滚策略**+6. **写明成功标准**+7. **为每个阶段安排测试**diff --git a/zh/10-cli/README.md b/zh/10-cli/README.mdnew file mode 100644index 0000000..5793c09--- /dev/null+++ b/zh/10-cli/README.md@@ -0,0 +1,640 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# CLI 参考++## 概览++Claude Code 的 CLI(命令行接口)是与 Claude Code 交互的主要方式。它提供了强大的参数和命令,用于执行查询、管理会话、配置模型,并把 Claude 集成进你的开发工作流。++## 架构++```mermaid+graph TD+ A["用户终端"] -->|"claude [options] [query]"| B["Claude Code CLI"]+ B -->|Interactive| C["REPL 模式"]+ B -->|"--print"| D["打印模式(SDK)"]+ B -->|"--resume"| E["恢复会话"]+ C -->|Conversation| F["Claude API"]+ D -->|Single Query| F+ E -->|Load Context| F+ F -->|Response| G["输出"]+ G -->|text/json/stream-json| H["终端 / 管道"]+```++## CLI 命令++| 命令 | 说明 | 示例 |+|---------|-------------|---------|+| `claude` | 启动交互式 REPL | `claude` |+| `claude "query"` | 带初始提示启动 REPL | `claude "解释这个项目"` |+| `claude -p "query"` | 打印模式,查询后退出 | `claude -p "解释这个函数"` |+| `cat file \| claude -p "query"` | 处理通过管道传入的内容 | `cat logs.txt \| claude -p "解释这些日志"` |+| `claude -c` | 继续最近一次会话 | `claude -c` |+| `claude -c -p "query"` | 在打印模式下继续会话 | `claude -c -p "检查类型错误"` |+| `claude -r "<session>" "query"` | 通过 ID 或名称恢复会话 | `claude -r "auth-refactor" "完成这个 PR"` |+| `claude update` | 更新到最新版本 | `claude update` |+| `claude mcp` | 配置 MCP servers | 见 [MCP 文档](../05-mcp/README.md) |+| `claude mcp serve` | 将 Claude Code 作为 MCP server 运行 | `claude mcp serve` |+| `claude agents` | 列出所有已配置的 subagents | `claude agents` |+| `claude auto-mode defaults` | 以 JSON 打印 auto mode 默认规则 | `claude auto-mode defaults` |+| `claude remote-control` | 启动远程控制服务 | `claude remote-control` |+| `claude plugin` | 管理插件(安装、启用、禁用) | `claude plugin install my-plugin` |+| `claude auth login` | 登录(支持 `--email`、`--sso`) | `claude auth login --email [email protected]` |+| `claude auth logout` | 注销当前账号 | `claude auth logout` |+| `claude auth status` | 检查登录状态(已登录返回 0,否则返回 1) | `claude auth status` |++## 核心标志++| 参数 | 说明 | 示例 |+|------|-------------|---------|+| `-p, --print` | 不进入交互式模式,直接输出结果 | `claude -p "query"` |+| `-c, --continue` | 加载最近一次会话 | `claude --continue` |+| `-r, --resume` | 按 ID 或名称恢复指定会话 | `claude --resume auth-refactor` |+| `-v, --version` | 输出版本号 | `claude -v` |+| `-w, --worktree` | 在隔离的 git worktree 中启动 | `claude -w` |+| `-n, --name` | 设置会话显示名称 | `claude -n "auth-refactor"` |+| `--from-pr <number>` | 恢复与 GitHub PR 关联的会话 | `claude --from-pr 42` |+| `--remote "task"` | 在 claude.ai 上创建 web session | `claude --remote "implement API"` |+| `--remote-control, --rc` | 使用 Remote Control 进入交互式会话 | `claude --rc` |+| `--teleport` | 将 web session 恢复到本地 | `claude --teleport` |+| `--teammate-mode` | agent team 显示模式 | `claude --teammate-mode tmux` |+| `--bare` | 极简模式,跳过 hooks、skills、plugins、MCP、自动记忆和 `CLAUDE.md` | `claude --bare` |+| `--enable-auto-mode` | 解锁 auto permission mode | `claude --enable-auto-mode` |+| `--channels` | 订阅 MCP channel 插件 | `claude --channels discord,telegram` |+| `--chrome` / `--no-chrome` | 启用 / 禁用 Chrome 浏览器集成 | `claude --chrome` |+| `--effort` | 设置推理强度 | `claude --effort high` |+| `--init` / `--init-only` | 运行初始化 hooks | `claude --init` |+| `--maintenance` | 运行维护 hooks 后退出 | `claude --maintenance` |+| `--disable-slash-commands` | 禁用所有 skills 和 slash commands | `claude --disable-slash-commands` |+| `--no-session-persistence` | 禁用会话保存(打印模式) | `claude -p --no-session-persistence "query"` |++### 交互模式 vs 打印模式++```mermaid+graph LR+ A["claude"] -->|默认| B["交互式 REPL"]+ A -->|"-p 参数"| C["打印模式"]+ B -->|特性| D["多轮对话<br>Tab 补全<br>历史记录<br>Slash commands"]+ C -->|特性| E["单次查询<br>可脚本化<br>可管道化<br>JSON 输出"]+```++**交互模式**(默认):+```bash+# 启动交互式会话+claude++# 带初始提示启动+claude "解释这个认证流程"+```++**打印模式**(非交互式):+```bash+# 单次查询后退出+claude -p "这个函数做什么?"++# 处理文件内容+cat error.log | claude -p "解释这个错误"++# 与其他工具串联+claude -p "列出待办事项" | grep "URGENT"+```++## 模型与配置++| 参数 | 说明 | 示例 |+|------|-------------|---------|+| `--model` | 设置模型(sonnet、opus、haiku,或完整模型名) | `claude --model opus` |+| `--fallback-model` | 当前模型负载过高时自动切换的后备模型 | `claude -p --fallback-model sonnet "query"` |+| `--agent` | 为当前会话指定 agent | `claude --agent my-custom-agent` |+| `--agents` | 通过 JSON 定义自定义 subagents | 见 [Agents Configuration](#subagents-配置) |+| `--effort` | 设置推理级别(low、medium、high、max) | `claude --effort high` |++### 模型选择示例++```bash+# 复杂任务使用 Opus 4.6+claude --model opus "设计一个缓存策略"++# 快速任务使用 Haiku 4.5+claude --model haiku -p "格式化这个 JSON"++# 使用完整模型名+claude --model claude-sonnet-4-6-20250929 "审查这段代码"++# 带后备模型以提升稳定性+claude -p --model opus --fallback-model sonnet "分析架构"++# 使用 opusplan(Opus 负责规划,Sonnet 负责执行)+claude --model opusplan "设计并实现缓存层"+```++## 系统提示词自定义++| 参数 | 说明 | 示例 |+|------|-------------|---------|+| `--system-prompt` | 替换整段默认系统提示词 | `claude --system-prompt "You are a Python expert"` |+| `--system-prompt-file` | 从文件加载提示词(仅打印模式) | `claude -p --system-prompt-file ./prompt.txt "query"` |+| `--append-system-prompt` | 在默认提示词后追加内容 | `claude --append-system-prompt "Always use TypeScript"` |++### 系统提示词示例++```bash+# 完整自定义人格+claude --system-prompt "你是一名资深安全工程师,重点关注漏洞。"++# 追加特定指令+claude --append-system-prompt "始终在代码示例中包含单元测试"++# 从文件加载复杂提示词+claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py"+```++### 系统提示词参数对比++| 参数 | 行为 | 交互模式 | 打印模式 |+|------|----------|-------------|-------|+| `--system-prompt` | 替换整个默认系统提示词 | ✅ | ✅ |+| `--system-prompt-file` | 用文件中的提示词替换 | ❌ | ✅ |+| `--append-system-prompt` | 追加到默认系统提示词后 | ✅ | ✅ |++**仅在打印模式中使用 `--system-prompt-file`。交互模式请使用 `--system-prompt` 或 `--append-system-prompt`。**++## 工具与权限管理++| 参数 | 说明 | 示例 |+|------|-------------|---------|+| `--tools` | 限制可用的内置工具 | `claude -p --tools "Bash,Edit,Read" "query"` |+| `--allowedTools` | 无需提示即可执行的工具 | `"Bash(git log:*)" "Read"` |+| `--disallowedTools` | 从上下文中移除的工具 | `"Bash(rm:*)" "Edit"` |+| `--dangerously-skip-permissions` | 跳过所有权限提示 | `claude --dangerously-skip-permissions` |+| `--permission-mode` | 以指定权限模式启动 | `claude --permission-mode auto` |+| `--permission-prompt-tool` | 用于权限处理的 MCP tool | `claude -p --permission-prompt-tool mcp_auth "query"` |+| `--enable-auto-mode` | 解锁 auto permission mode | `claude --enable-auto-mode` |++### 权限示例++```bash+# 代码审查只读模式+claude --permission-mode plan "审查这个代码库"++# 只允许安全工具+claude --tools "Read,Grep,Glob" -p "找出所有 TODO 注释"++# 允许特定 git 命令无需提示+claude --allowedTools "Bash(git status:*)" "Bash(git log:*)"++# 阻止危险操作+claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"+```++## 输出与格式++| 参数 | 说明 | 选项 | 示例 |+|------|-------------|---------|---------|+| `--output-format` | 指定输出格式(打印模式) | `text`、`json`、`stream-json` | `claude -p --output-format json "query"` |+| `--input-format` | 指定输入格式(打印模式) | `text`、`stream-json` | `claude -p --input-format stream-json` |+| `--verbose` | 启用详细日志 | | `claude --verbose` |+| `--include-partial-messages` | 包含流式事件 | 需要 `stream-json` | `claude -p --output-format stream-json --include-partial-messages "query"` |+| `--json-schema` | 获取符合 schema 的 JSON 输出 | | `claude -p --json-schema '{"type":"object"}' "query"` |+| `--max-budget-usd` | 打印模式最大花费 | | `claude -p --max-budget-usd 5.00 "query"` |++### 输出格式示例++```bash+# 纯文本(默认)+claude -p "解释这段代码"++# 供程序使用的 JSON+claude -p --output-format json "列出 main.py 中的所有函数"++# 用于实时处理的流式 JSON+claude -p --output-format stream-json "生成一份长报告"++# 使用 schema 验证的结构化输出+claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \+ "找出这段代码中的 bug,并以 JSON 返回"+```++## 工作区与目录++| 参数 | 说明 | 示例 |+|------|-------------|---------|+| `--working-directory` | 设置工作目录 | `claude --working-directory /path/to/project` |+| `--add-dir` | 追加额外工作目录 | `claude --add-dir /path/to/other/project` |++### 多目录示例++```bash+# 在多个项目目录中协作+claude --working-directory ~/projects/app --add-dir ~/projects/shared++# 加载自定义设置+claude --working-directory ./backend --add-dir ./frontend+```++## MCP 配置++| 参数 | 说明 | 示例 |+|------|-------------|---------|+| `--mcp-config` | 从文件加载 MCP 配置 | `claude --mcp-config ./mcp.json` |+| `--mcp` | 启用 / 配置 MCP 服务 | `claude --mcp github` |+| `--mcp-list` | 列出可用 MCP 配置 | `claude --mcp-list` |++### MCP 示例++```bash+# 加载 GitHub MCP server+claude --mcp-config ./configs/github-mcp.json++# 严格模式,只允许指定的 server+claude --mcp-config ./configs/strict-mcp.json --mcp github+```++## 会话管理++| 参数 | 说明 | 示例 |+|------|-------------|---------|+| `--session` | 指定会话名称 | `claude --session feature-auth` |+| `--new-session` | 强制开启新会话 | `claude --new-session` |+| `--resume-last` | 恢复最近一次会话 | `claude --resume-last` |+| `--fork-session` | 从当前会话分叉 | `claude --fork-session` |++### 会话示例++```bash+# 继续上一次对话+claude --continue++# 恢复命名会话+claude --resume feature-auth++# 为实验分叉会话+claude --fork-session++# 指定会话 ID+claude --resume 123456789+```++### 会话分叉++```bash+# 分叉会话尝试不同方案+claude --fork-session "尝试另一种实现"++# 带自定义消息分叉+claude --fork-session --session "experiment-a"+```++## 高级特性++| 参数 | 说明 | 示例 |+|------|-------------|---------|+| `--disable-auto-checkpoints` | 禁用自动 checkpoint | `claude --disable-auto-checkpoints` |+| `--enable-auto-checkpoints` | 启用自动 checkpoint | `claude --enable-auto-checkpoints` |+| `--interactive` | 强制交互模式 | `claude --interactive` |+| `--dry-run` | 仅模拟执行 | `claude --dry-run "review code"` |+| `--unsafe` | 允许更多自动化操作 | `claude --unsafe` |++### 高级示例++```bash+# 限制自主操作+claude --permission-mode plan --model opus "设计并实现认证系统"++# 调试 API 调用+claude --verbose -p "diagnose this issue"++# 启用 IDE 集成+claude --ide "review this diff"+```++<a id="agents-configuration"></a>+## Subagents 配置++| 参数 | 说明 | 示例 |+|------|-------------|---------|+| `--agents` | 通过 JSON 定义自定义 subagents | `claude --agents ./agents.json` |+| `--agent` | 指定当前会话使用的 agent | `claude --agent reviewer` |++### Subagents JSON 格式++```json+{+ "agent-name": {+ "description": "Required: when to invoke this agent",+ "prompt": "Required: system prompt for the agent",+ "tools": ["Optional", "array", "of", "tools"],+ "model": "optional: sonnet|opus|haiku"+ }+}+```++**必填字段:**+- `description` - 何时使用这个 agent 的自然语言说明+- `prompt` - 定义 agent 角色和行为的系统提示词++**可选字段:**+- `tools` - 可用工具数组(如果省略则继承全部工具)+ - 格式:`["Read", "Grep", "Glob", "Bash"]`+- `model` - 使用的模型:`sonnet`、`opus` 或 `haiku`++### 完整 Agents 示例++```json+{+ "code-reviewer": {+ "description": "Expert code reviewer. Use proactively after code changes.",+ "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",+ "tools": ["Read", "Grep", "Glob", "Bash"],+ "model": "sonnet"+ },+ "debugger": {+ "description": "Debugging specialist for errors and test failures.",+ "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.",+ "tools": ["Read", "Edit", "Bash", "Grep"],+ "model": "opus"+ },+ "documenter": {+ "description": "Documentation specialist for generating guides.",+ "prompt": "You are a technical writer. Create clear, comprehensive documentation.",+ "tools": ["Read", "Write"],+ "model": "haiku"+ }+}+```++### Agents 命令示例++```bash+# 直接定义自定义 agent+claude --agents '{+ "security-auditor": {+ "description": "Security specialist for vulnerability analysis",+ "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.",+ "tools": ["Read", "Grep", "Glob"],+ "model": "opus"+ }+}' "audit this codebase for security issues"++# 从文件加载 agents+claude --agents ./configs/agents.json++# 与其他参数组合+claude --agents ./configs/agents.json --model opus+```++### Subagent 优先级++当同时存在多种 agent 定义时,加载优先级如下:+1. **CLI 定义**(`--agents` 参数)- 当前会话专用+2. **用户级**(`~/.claude/agents/`)- 所有项目可用+3. **项目级**(`.claude/agents/`)- 当前项目可用++命令行定义的 agents 会覆盖本次会话里的用户级和项目级 agents。++## 高价值使用场景++### 1. CI/CD 集成++```bash+claude -p --output-format json "run tests and summarize failures"+```++### 2. 管道式脚本处理++```bash+# 分析错误日志+cat error.log | claude -p "解释这些错误并给出修复建议"++# 查找访问日志中的模式+cat access.log | claude -p "找出异常流量"++# 分析 git 历史+git log --oneline -20 | claude -p "总结最近的开发方向"++# 审查某个文件+claude -p "review src/app.ts and suggest improvements"++# 生成文档+claude -p "根据 README 生成 API 文档"++# 查找 TODO 并排优先级+rg -n "TODO|FIXME" . | claude -p "按优先级分类这些待办"+```++### 3. 多会话工作流++```bash+# 启动特性分支会话+claude --session feature-auth++# 之后继续该会话+claude --resume feature-auth++# 分叉尝试另一种方案+claude --fork-session++# 在不同特性会话之间切换+claude --resume feature-auth+claude --resume feature-payment+```++### 4. 自定义 agent 配置++```bash+# 将 agents 配置保存到文件+cat > agents.json <<'JSON'+{+ "agents": [+ {"name":"reviewer","description":"review code"},+ {"name":"tester","description":"write tests"}+ ]+}+JSON++# 在会话中使用这些 agent+claude --agents ./agents.json --agent reviewer+```++### 5. 批处理++```bash+# 处理多个文件+find src -name "*.ts" | xargs -I{} claude -p "review {}"++# 批量代码审查+claude -p "review all changes in this branch"++# 为所有模块生成测试+claude -p "generate tests for the modified modules"+```++### 6. 安全敏感开发++```bash+# 只读安全审计+claude --permission-mode plan -p "audit this repository"++# 阻止危险命令+claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"++# 限制自动化+claude --tools "Read,Grep,Glob" -p "inspect the codebase"+```++### 7. JSON API 集成++```bash+# 获取结构化分析结果+claude -p --output-format json "analyze this code and return findings"++# 配合 jq 处理+claude -p --output-format json "list functions" | jq '.functions[]'++# 在脚本中使用+result=$(claude -p --output-format json "summarize changes")+```++### jq 解析示例++```bash+# 提取特定字段+claude -p --output-format json "analyze repo" | jq '.summary'++# 过滤数组元素+claude -p --output-format json "find bugs" | jq '.bugs[] | select(.severity=="high")'++# 提取多个字段+claude -p --output-format json "analyze" | jq '{summary, risk, recommendations}'++# 转成 CSV+claude -p --output-format json "list files" | jq -r '.files[] | [.name, .size] | @csv'++# 条件处理+claude -p --output-format json "check status" | jq 'if .ok then "pass" else "fail" end'++# 提取嵌套值+claude -p --output-format json "inspect" | jq '.details.metrics.coverage'++# 处理整个数组+claude -p --output-format json "find todos" | jq '.todos | length'++# 转换输出+claude -p --output-format json "review" | jq '{issues: [.issues[] | {file, line, message}]}'+```++## 模型++### 模型选择++```bash+# 使用短名称+claude --model sonnet+claude --model opus+claude --model haiku++# 使用 opusplan 别名(Opus 负责规划,Sonnet 负责执行)+claude --model opusplan "design and implement the caching layer"++# 会话中切换快速模式+claude --model haiku --effort low+```++### Effort 级别(Opus 4.6)++```bash+# 通过 CLI 参数设置 effort+claude --model opus --effort high "design the architecture"++# 通过 slash command 设置 effort+/effort max++# 通过环境变量设置 effort+CLAUDE_EFFORT=medium claude --model opus+```++## 常用环境变量++| 环境变量 | 说明 |+|----------|------|+| `ANTHROPIC_API_KEY` | API key |+| `CLAUDE_MODEL` | 默认模型 |+| `CLAUDE_EFFORT` | 默认推理强度 |+| `CLAUDE_WORKING_DIRECTORY` | 默认工作目录 |+| `CLAUDE_OUTPUT_FORMAT` | 默认输出格式 |+| `CLAUDE_MCP_CONFIG` | 默认 MCP 配置 |++## 快速参考++### 最常用命令++```bash+# 交互式会话+claude++# 快速提问+claude -p "explain this repo"++# 继续上次对话+claude -c++# 处理某个文件+claude -p "review README.md"++# 为脚本输出 JSON+claude -p --output-format json "list all classes"+```++### 参数组合++```bash+# 只读审查+claude --permission-mode plan -p "review this codebase"++# 高级模型 + JSON 输出+claude --model opus -p --output-format json "analyze architecture"++# 自定义工作目录 + MCP+claude --working-directory ./backend --mcp-config ./mcp.json+```++## 故障排查++### 找不到命令++- 确认 `claude` 已安装并在 `PATH` 中+- 重新打开终端+- 检查是否需要重新登录或更新版本++### API Key 问题++- 检查 `ANTHROPIC_API_KEY`+- 确认 key 未过期+- 检查网络是否可访问 API++### 找不到会话++- 确认会话名称或 ID 正确+- 先运行 `claude --list-sessions`(如果你的版本支持)+- 检查当前账号是否一致++### 输出格式问题++- 使用 `--output-format json` 时确保输出可被解析+- 如果是流式输出,加入 `--include-partial-messages`++### 权限被拒绝++- 检查 `--permission-mode`+- 检查 `--allowedTools` 和 `--disallowedTools`+- 如有必要,明确允许所需工具++## 更多资源++- [根目录中文指南](../README.md)+- [Slash Commands 中文参考](../01-slash-commands/README.md)+- [MCP 文档](../05-mcp/README.md)+- [Claude Code 官方 CLI 文档](https://code.claude.com/docs/en/cli-reference)diff --git a/zh/CATALOG.md b/zh/CATALOG.mdnew file mode 100644index 0000000..4045b84--- /dev/null+++ b/zh/CATALOG.md@@ -0,0 +1,517 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">+</picture>++# Claude Code 功能目录++> 一份关于 Claude Code 所有功能的快速参考:命令、agents、skills、plugins 和 hooks。++**导航**: [命令](#斜杠命令) | [权限模式](#权限模式) | [Subagents](#subagents) | [Skills](#skills) | [Plugins](#plugins) | [MCP Servers](#mcp-servers) | [Hooks](#hooks) | [Memory](#memory-files) | [2026 年 3 月新功能](#2026-年-3-月新功能)++---++## 概览++| 功能 | 内置 | 示例 | 总数 | 参考 |+|---------|----------|----------|-------|-----------|+| **Slash Commands** | 55+ | 8 | 63+ | [01-slash-commands/README.md](01-slash-commands/README.md) |+| **Subagents** | 6 | 10 | 16 | [04-subagents/README.md](04-subagents/README.md) |+| **Skills** | 5 个内置 | 4 | 9 | [03-skills/README.md](03-skills/README.md) |+| **Plugins** | - | 3 | 3 | [07-plugins/README.md](07-plugins/README.md) |+| **MCP Servers** | 1 | 8 | 9 | [05-mcp/README.md](05-mcp/README.md) |+| **Hooks** | 25 个事件 | 7 | 7 | [06-hooks/README.md](06-hooks/README.md) |+| **Memory** | 7 种类型 | 3 | 3 | [02-memory/README.md](02-memory/README.md) |+| **总计** | **99** | **43** | **117** | |++---++## 斜杠命令++命令是用户手动触发的快捷操作,用来执行特定任务。++### 内置命令++| 命令 | 说明 | 适用场景 |+|---------|-------------|-------------|+| `/help` | 显示帮助信息 | 开始上手、学习命令 |+| `/btw` | 提出不写入上下文的插话问题 | 临时补充问题 |+| `/chrome` | 配置 Chrome 集成 | 浏览器自动化 |+| `/clear` | 清空对话历史 | 重新开始、减少上下文 |+| `/diff` | 交互式 diff 查看器 | 审查变更 |+| `/config` | 查看/编辑配置 | 自定义行为 |+| `/status` | 显示会话状态 | 检查当前状态 |+| `/agents` | 列出可用 agents | 查看委派选项 |+| `/skills` | 列出可用 skills | 查看可自动触发的能力 |+| `/hooks` | 列出已配置的 hooks | 调试自动化 |+| `/insights` | 分析会话模式 | 优化会话使用 |+| `/install-slack-app` | 安装 Claude Slack 应用 | Slack 集成 |+| `/keybindings` | 自定义键盘快捷键 | 按键定制 |+| `/mcp` | 列出 MCP servers | 检查外部集成 |+| `/memory` | 查看已加载的 memory 文件 | 调试上下文加载 |+| `/mobile` | 生成移动端二维码 | 手机访问 |+| `/passes` | 查看使用通行证 | 订阅信息 |+| `/plugin` | 管理 plugins | 安装/移除扩展 |+| `/plan` | 进入规划模式 | 复杂实现 |+| `/rewind` | 回退到 checkpoint | 撤销变更、探索替代方案 |+| `/checkpoint` | 管理 checkpoints | 保存/恢复状态 |+| `/cost` | 显示 token 消耗 | 监控开销 |+| `/context` | 显示上下文窗口使用情况 | 管理对话长度 |+| `/export` | 导出对话 | 保存以供参考 |+| `/extra-usage` | 配置额外用量限制 | 限流管理 |+| `/feedback` | 提交反馈或 bug 报告 | 报告问题 |+| `/login` | 通过 Anthropic 认证 | 访问功能 |+| `/logout` | 登出 | 切换账号 |+| `/sandbox` | 切换 sandbox 模式 | 安全执行命令 |+| `/vim` | 切换 vim 模式 | 类 Vim 编辑 |+| `/doctor` | 运行诊断 | 排查问题 |+| `/reload-plugins` | 重新加载已安装的 plugins | 插件管理 |+| `/release-notes` | 显示更新说明 | 查看新功能 |+| `/remote-control` | 启用远程控制 | 远程访问 |+| `/permissions` | 管理权限 | 控制访问 |+| `/session` | 管理会话 | 多会话工作流 |+| `/rename` | 重命名当前会话 | 组织会话 |+| `/resume` | 恢复之前的会话 | 继续工作 |+| `/todo` | 查看/管理待办列表 | 跟踪任务 |+| `/tasks` | 查看后台任务 | 监控异步操作 |+| `/copy` | 复制最后一次回复到剪贴板 | 快速分享输出 |+| `/teleport` | 将会话转移到另一台机器 | 远程继续工作 |+| `/desktop` | 打开 Claude Desktop 应用 | 切换桌面界面 |+| `/theme` | 更改颜色主题 | 自定义外观 |+| `/usage` | 显示 API 使用统计 | 监控配额和消耗 |+| `/fork` | 分叉当前对话 | 探索替代方案 |+| `/stats` | 显示会话统计 | 查看会话指标 |+| `/statusline` | 配置状态栏 | 自定义状态显示 |+| `/stickers` | 查看会话贴纸 | 趣味奖励 |+| `/fast` | 切换快速输出模式 | 加快响应 |+| `/terminal-setup` | 配置终端集成 | 设置终端特性 |+| `/upgrade` | 检查更新 | 版本管理 |++### 自定义命令(示例)++| 命令 | 说明 | 适用场景 | 作用域 | 安装 |+|---------|-------------|-------------|-------|--------------|+| `/optimize` | 分析代码以做优化 | 性能改进 | 项目 | `cp 01-slash-commands/optimize.md .claude/commands/` |+| `/pr` | 准备 Pull Request | 提交 PR 前 | 项目 | `cp 01-slash-commands/pr.md .claude/commands/` |+| `/generate-api-docs` | 生成 API 文档 | 编写 API 文档 | 项目 | `cp 01-slash-commands/generate-api-docs.md .claude/commands/` |+| `/commit` | 结合上下文创建 git commit | 提交变更 | 用户 | `cp 01-slash-commands/commit.md .claude/commands/` |+| `/push-all` | 先暂存、提交再 push | 快速发布 | 用户 | `cp 01-slash-commands/push-all.md .claude/commands/` |+| `/doc-refactor` | 重构文档结构 | 改进文档 | 项目 | `cp 01-slash-commands/doc-refactor.md .claude/commands/` |+| `/setup-ci-cd` | 搭建 CI/CD 流水线 | 新项目 | 项目 | `cp 01-slash-commands/setup-ci-cd.md .claude/commands/` |+| `/unit-test-expand` | 扩展测试覆盖率 | 改进测试 | 项目 | `cp 01-slash-commands/unit-test-expand.md .claude/commands/` |++> **作用域**: `User` = 个人工作流(`~/.claude/commands/`),`Project` = 团队共享(`.claude/commands/`)++**参考**: [01-slash-commands/README.md](01-slash-commands/README.md) | [官方文档](https://code.claude.com/docs/en/interactive-mode)++**快速安装(所有自定义命令)**:+```bash+cp 01-slash-commands/*.md .claude/commands/+```++---++## 权限模式++Claude Code 提供 6 种权限模式,用来控制工具调用如何被授权。++| 模式 | 说明 | 适用场景 |+|------|-------------|-------------|+| `default` | 每次工具调用都询问 | 标准交互式使用 |+| `acceptEdits` | 自动接受文件编辑,其他情况仍询问 | 可信编辑工作流 |+| `plan` | 只允许只读工具,不允许写入 | 规划与探索 |+| `auto` | 不再提示,自动接受所有工具 | 完全自主运行(Research Preview) |+| `bypassPermissions` | 跳过所有权限检查 | CI/CD、无头环境 |+| `dontAsk` | 跳过需要权限的工具 | 非交互脚本 |++> **注意**:`auto` 模式是 Research Preview 功能(2026 年 3 月)。只有在可信且已隔离的环境中才使用 `bypassPermissions`。++**参考**: [官方文档](https://code.claude.com/docs/en/permissions)++---++## Subagents++为特定任务准备的专门化 AI 助手,拥有隔离上下文。++### 内置 Subagents++| Agent | 说明 | 工具 | 模型 | 适用场景 |+|-------|-------------|-------|-------|-------------|+| **general-purpose** | 多步任务、研究 | 所有工具 | 继承当前模型 | 复杂研究、多文件任务 |+| **Plan** | 实现规划 | Read、Glob、Grep、Bash | 继承当前模型 | 架构设计、规划 |+| **Explore** | 代码库探索 | Read、Glob、Grep | Haiku 4.5 | 快速搜索、理解代码 |+| **Bash** | 命令执行 | Bash | 继承当前模型 | git 操作、终端任务 |+| **statusline-setup** | 状态栏配置 | Bash、Read、Write | Sonnet 4.6 | 配置状态栏显示 |+| **Claude Code Guide** | 帮助与文档 | Read、Glob、Grep | Haiku 4.5 | 获取帮助、学习功能 |++### Subagent 配置字段++| 字段 | 类型 | 说明 |+|-------|------|-------------|+| `name` | string | agent 标识 |+| `description` | string | 这个 agent 的用途 |+| `model` | string | 模型覆盖值(例如 `haiku-4.5`) |+| `tools` | array | 允许使用的工具列表 |+| `effort` | string | 推理强度等级(`low`、`medium`、`high`) |+| `initialPrompt` | string | agent 启动时注入的 system prompt |+| `disallowedTools` | array | 明确禁止该 agent 使用的工具 |++### 自定义 Subagents(示例)++| Agent | 说明 | 适用场景 | 作用域 | 安装 |+|-------|-------------|-------------|-------|--------------|+| `code-reviewer` | 全面的代码质量检查 | 代码审查会话 | 项目 | `cp 04-subagents/code-reviewer.md .claude/agents/` |+| `code-architect` | 功能架构设计 | 新功能规划 | 项目 | `cp 04-subagents/code-architect.md .claude/agents/` |+| `code-explorer` | 深入分析代码库 | 理解已有功能 | 项目 | `cp 04-subagents/code-explorer.md .claude/agents/` |+| `clean-code-reviewer` | 按 Clean Code 原则审查 | 可维护性审查 | 项目 | `cp 04-subagents/clean-code-reviewer.md .claude/agents/` |+| `test-engineer` | 测试策略与覆盖率 | 测试规划 | 项目 | `cp 04-subagents/test-engineer.md .claude/agents/` |+| `documentation-writer` | 技术文档编写 | API 文档、指南 | 项目 | `cp 04-subagents/documentation-writer.md .claude/agents/` |+| `secure-reviewer` | 面向安全的审查 | 安全审计 | 项目 | `cp 04-subagents/secure-reviewer.md .claude/agents/` |+| `implementation-agent` | 完整功能实现 | 功能开发 | 项目 | `cp 04-subagents/implementation-agent.md .claude/agents/` |+| `debugger` | 根因分析 | Bug 调查 | 用户 | `cp 04-subagents/debugger.md .claude/agents/` |+| `data-scientist` | SQL 查询、数据分析 | 数据任务 | 用户 | `cp 04-subagents/data-scientist.md .claude/agents/` |++> **作用域**: `User` = 个人(`~/.claude/agents/`),`Project` = 团队共享(`.claude/agents/`)++**参考**: [04-subagents/README.md](04-subagents/README.md) | [官方文档](https://code.claude.com/docs/en/sub-agents)++**快速安装(所有自定义 agents)**:+```bash+cp 04-subagents/*.md .claude/agents/+```++---++## Skills++可自动触发的能力包,包含说明、脚本和模板。++### 示例 Skills++| Skill | 说明 | 何时自动触发 | 作用域 | 安装 |+|-------|-------------|-------------------|-------|--------------|+| `code-review` | 全面的代码审查 | “Review this code”, “Check quality” | 项目 | `cp -r 03-skills/code-review .claude/skills/` |+| `brand-voice` | 品牌一致性检查器 | 编写营销文案时 | 项目 | `cp -r 03-skills/brand-voice .claude/skills/` |+| `doc-generator` | API 文档生成器 | “Generate docs”, “Document API” | 项目 | `cp -r 03-skills/doc-generator .claude/skills/` |+| `refactor` | 系统化代码重构(Martin Fowler) | “Refactor this”, “Clean up code” | 用户 | `cp -r 03-skills/refactor ~/.claude/skills/` |++> **作用域**: `User` = 个人(`~/.claude/skills/`),`Project` = 团队共享(`.claude/skills/`)++### Skill 结构++```+~/.claude/skills/skill-name/+├── SKILL.md # skill 定义与说明+├── scripts/ # 辅助脚本+└── templates/ # 输出模板+```++### Skill Frontmatter 字段++Skills 支持在 `SKILL.md` 中使用 YAML frontmatter 进行配置:++| 字段 | 类型 | 说明 |+|-------|------|-------------|+| `name` | string | skill 显示名称 |+| `description` | string | 这个 skill 的作用 |+| `autoInvoke` | array | 自动触发的关键词 |+| `effort` | string | 推理强度等级(`low`、`medium`、`high`) |+| `shell` | string | 脚本使用的 shell(`bash`、`zsh`、`sh`) |++**参考**: [03-skills/README.md](03-skills/README.md) | [官方文档](https://code.claude.com/docs/en/skills)++**快速安装(所有 skills)**:+```bash+cp -r 03-skills/* ~/.claude/skills/+```++### 内置 Skills++| Skill | 说明 | 何时自动触发 |+|-------|-------------|-------------------|+| `/simplify` | 审查代码质量 | 写完代码后 |+| `/batch` | 对多个文件运行提示词 | 批量操作 |+| `/debug` | 调试失败的测试/错误 | 调试会话 |+| `/loop` | 按间隔运行提示词 | 周期性任务 |+| `/claude-api` | 使用 Claude API 构建应用 | API 开发 |++---++## Plugins++把 commands、agents、MCP servers 和 hooks 打包在一起的集合。++### 示例 Plugins++| Plugin | 说明 | 组件 | 适用场景 | 作用域 | 安装 |+|--------|-------------|------------|-------------|-------|--------------|+| `pr-review` | PR 审查工作流 | 3 个 commands、3 个 agents、GitHub MCP | 代码审查 | 项目 | `/plugin install pr-review` |+| `devops-automation` | 部署与监控 | 4 个 commands、3 个 agents、K8s MCP | DevOps 任务 | 项目 | `/plugin install devops-automation` |+| `documentation` | 文档生成套件 | 4 个 commands、3 个 agents、模板 | 文档编写 | 项目 | `/plugin install documentation` |++> **作用域**: `Project` = 团队共享,`User` = 个人工作流++### Plugin 结构++```+.claude-plugin/+├── plugin.json # manifest 文件+├── commands/ # Slash commands+├── agents/ # Subagents+├── skills/ # Skills+├── mcp/ # MCP 配置+├── hooks/ # Hook 脚本+└── scripts/ # 工具脚本+```++**参考**: [07-plugins/README.md](07-plugins/README.md) | [官方文档](https://code.claude.com/docs/en/plugins)++**Plugin 管理命令**:+```bash+/plugin list # 列出已安装的 plugins+/plugin install <name> # 安装 plugin+/plugin remove <name> # 移除 plugin+/plugin update <name> # 更新 plugin+```++---++## MCP Servers++用于访问外部工具和 API 的 Model Context Protocol servers。++### 常见 MCP Servers++| Server | 说明 | 适用场景 | 作用域 | 安装 |+|--------|-------------|-------------|-------|--------------|+| **GitHub** | PR 管理、issues、代码 | GitHub 工作流 | 项目 | `claude mcp add github -- npx -y @modelcontextprotocol/server-github` |+| **Database** | SQL 查询、数据访问 | 数据库操作 | 项目 | `claude mcp add db -- npx -y @modelcontextprotocol/server-postgres` |+| **Filesystem** | 高级文件操作 | 复杂文件任务 | 用户 | `claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem` |+| **Slack** | 团队沟通 | 通知、更新 | 项目 | 在设置中配置 |+| **Google Docs** | 文档访问 | 文档编辑、审阅 | 项目 | 在设置中配置 |+| **Asana** | 项目管理 | 任务跟踪 | 项目 | 在设置中配置 |+| **Stripe** | 支付数据 | 财务分析 | 项目 | 在设置中配置 |+| **Memory** | 持久记忆 | 跨会话回忆 | 用户 | 在设置中配置 |+| **Context7** | 库文档 | 查找最新文档 | 内置 | 内置 |++> **作用域**: `Project` = 团队(`.mcp.json`),`User` = 个人(`~/.claude.json`),`Built-in` = 预装++### MCP 配置示例++```json+{+ "mcpServers": {+ "github": {+ "command": "npx",+ "args": ["-y", "@modelcontextprotocol/server-github"],+ "env": {+ "GITHUB_TOKEN": "${GITHUB_TOKEN}"+ }+ }+ }+}+```++**参考**: [05-mcp/README.md](05-mcp/README.md) | [MCP 协议文档](https://modelcontextprotocol.io)++**快速安装(GitHub MCP)**:+```bash+export GITHUB_TOKEN="your_token" && claude mcp add github -- npx -y @modelcontextprotocol/server-github+```++---++## Hooks++在 Claude Code 事件发生时执行的事件驱动自动化。++### Hook 事件++| 事件 | 说明 | 触发时机 | 使用场景 |+|-------|-------------|----------------|-----------|+| `SessionStart` | 会话开始/恢复 | 会话初始化 | 初始化任务 |+| `InstructionsLoaded` | 指令已加载 | `CLAUDE.md` 或规则文件加载 | 自定义指令处理 |+| `UserPromptSubmit` | 提示词提交前 | 用户发送消息 | 输入校验 |+| `PreToolUse` | 工具执行前 | 任意工具运行之前 | 校验、日志 |+| `PermissionRequest` | 显示权限对话框 | 敏感操作前 | 自定义审批流程 |+| `PostToolUse` | 工具成功后 | 任意工具完成后 | 格式化、通知 |+| `PostToolUseFailure` | 工具执行失败 | 工具报错后 | 错误处理、日志 |+| `Notification` | 发送通知时 | Claude 发送通知 | 外部提醒 |+| `SubagentStart` | 启动 subagent | subagent 任务开始 | 初始化上下文 |+| `SubagentStop` | subagent 完成 | subagent 任务结束 | 链式动作 |+| `Stop` | Claude 完成响应 | 响应完成 | 清理、汇报 |+| `StopFailure` | API 错误导致结束 | API 错误发生 | 错误恢复、日志 |+| `TeammateIdle` | 队友 agent 空闲 | agent team 协调 | 分配工作 |+| `TaskCompleted` | 任务标记完成 | 任务完成 | 任务后处理 |+| `TaskCreated` | 通过 TaskCreate 创建任务 | 新任务创建 | 任务追踪、日志 |+| `ConfigChange` | 配置更新 | 设置被修改 | 响应配置变化 |+| `CwdChanged` | 当前工作目录变化 | 目录切换 | 目录级初始化 |+| `FileChanged` | 监控文件发生变化 | 文件被修改 | 文件监控、重建 |+| `PreCompact` | 压缩前 | 上下文压缩前 | 状态保留 |+| `PostCompact` | 压缩完成后 | 压缩完成 | 压缩后动作 |+| `WorktreeCreate` | worktree 创建中 | git worktree 创建 | 设置 worktree 环境 |+| `WorktreeRemove` | worktree 被移除 | git worktree 删除 | 清理 worktree 资源 |+| `Elicitation` | MCP server 请求输入 | MCP elicitation | 输入校验 |+| `ElicitationResult` | 用户响应 elicitation | 用户回答 | 响应处理 |+| `SessionEnd` | 会话结束 | 会话终止 | 清理、保存状态 |++### 示例 Hooks++| Hook | 说明 | 事件 | 作用域 | 安装 |+|------|-------------|-------|-------|--------------|+| `validate-bash.py` | 命令校验 | PreToolUse:Bash | 项目 | `cp 06-hooks/validate-bash.py .claude/hooks/` |+| `security-scan.py` | 安全扫描 | PostToolUse:Write | 项目 | `cp 06-hooks/security-scan.py .claude/hooks/` |+| `format-code.sh` | 自动格式化 | PostToolUse:Write | 用户 | `cp 06-hooks/format-code.sh ~/.claude/hooks/` |+| `validate-prompt.py` | 提示词校验 | UserPromptSubmit | 项目 | `cp 06-hooks/validate-prompt.py .claude/hooks/` |+| `context-tracker.py` | token 使用跟踪 | Stop | 用户 | `cp 06-hooks/context-tracker.py ~/.claude/hooks/` |+| `pre-commit.sh` | 提交前校验 | PreToolUse:Bash | 项目 | `cp 06-hooks/pre-commit.sh .claude/hooks/` |+| `log-bash.sh` | 命令日志记录 | PostToolUse:Bash | 用户 | `cp 06-hooks/log-bash.sh ~/.claude/hooks/` |++> **作用域**: `Project` = 团队(`.claude/settings.json`),`User` = 个人(`~/.claude/settings.json`)++### Hook 配置++```json+{+ "hooks": {+ "PreToolUse": [+ {+ "matcher": "Bash",+ "command": "~/.claude/hooks/validate-bash.py"+ }+ ],+ "PostToolUse": [+ {+ "matcher": "Write",+ "command": "~/.claude/hooks/format-code.sh"+ }+ ]+ }+}+```++**参考**: [06-hooks/README.md](06-hooks/README.md) | [官方文档](https://code.claude.com/docs/en/hooks)++**快速安装(所有 hooks)**:+```bash+mkdir -p ~/.claude/hooks && cp 06-hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh+```++---++## Memory Files++会在多个会话之间自动加载的持久上下文。++### Memory 类型++| 类型 | 位置 | 作用域 | 适用场景 |+|------|----------|-------|-------------|+| **Managed Policy** | 组织管理的策略 | Organization | 统一组织标准 |+| **Project** | `./CLAUDE.md` | Project(团队) | 团队规范、项目上下文 |+| **Project Rules** | `.claude/rules/` | Project(团队) | 模块化项目规则 |+| **User** | `~/.claude/CLAUDE.md` | User(个人) | 个人偏好 |+| **User Rules** | `~/.claude/rules/` | User(个人) | 模块化个人规则 |+| **Local** | `./CLAUDE.local.md` | Local(git 忽略) | 机器特定覆盖(截至 2026 年 3 月不在官方文档中,可能是历史遗留) |+| **Auto Memory** | 自动 | Session | 自动捕捉的洞察和修正 |++> **作用域**: `Organization` = 管理员管理,`Project` = 通过 git 与团队共享,`User` = 个人偏好,`Local` = 不提交,`Session` = 自动管理++**参考**: [02-memory/README.md](02-memory/README.md) | [官方文档](https://code.claude.com/docs/en/memory)++**快速安装**:+```bash+cp 02-memory/project-CLAUDE.md ./CLAUDE.md+cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md+```++---++## 2026 年 3 月新功能++| 功能 | 说明 | 使用方式 |+|---------|-------------|------------|+| **Remote Control** | 通过 API 远程控制 Claude Code 会话 | 使用远程控制 API 以编程方式发送提示并接收响应 |+| **Web Sessions** | 在浏览器环境中运行 Claude Code | 通过 `claude web` 或 Anthropic Console 访问 |+| **Desktop App** | Claude Code 的原生桌面应用 | 使用 `/desktop` 或从 Anthropic 网站下载 |+| **Agent Teams** | 协调多个 agent 共同处理相关任务 | 配置协作并共享上下文的 teammate agents |+| **Task List** | 后台任务管理与监控 | 使用 `/tasks` 查看和管理后台操作 |+| **Prompt Suggestions** | 上下文感知的命令建议 | 根据当前上下文自动出现建议 |+| **Git Worktrees** | 用于并行开发的隔离 git worktree | 使用 worktree 命令进行安全的并行分支工作 |+| **Sandboxing** | 安全隔离的执行环境 | 使用 `/sandbox` 切换,在受限环境中运行命令 |+| **MCP OAuth** | 为 MCP servers 提供 OAuth 认证 | 在 MCP server 设置中配置 OAuth 凭据以安全访问 |+| **MCP Tool Search** | 动态搜索和发现 MCP 工具 | 使用工具搜索查找已连接 server 上可用的 MCP 工具 |+| **Scheduled Tasks** | 使用 `/loop` 和 cron 工具设置周期任务 | 使用 `/loop 5m /command` 或 CronCreate 工具 |+| **Chrome Integration** | 使用无头 Chromium 做浏览器自动化 | 使用 `--chrome` 标志或 `/chrome` 命令 |+| **Keyboard Customization** | 自定义按键映射并支持 chord | 使用 `/keybindings` 或编辑 `~/.claude/keybindings.json` |+| **自动模式(Auto Mode)** | 无需权限提示的完全自主运行(Research Preview) | 使用 `--mode auto` 或 `/permissions auto`;2026 年 3 月 |+| **通道(Channels)** | 多通道通信(Telegram、Slack 等)(Research Preview) | 配置 channel plugins;2026 年 3 月 |+| **语音输入(Voice Dictation)** | 用语音输入提示词 | 使用麦克风图标或语音快捷键 |+| **Agent Hook Type** | 触发 subagent 而不是执行 shell 命令的 hook | 在 hook 配置中设置 `"type": "agent"` |+| **Prompt Hook Type** | 将 prompt 文本注入对话的 hook | 在 hook 配置中设置 `"type": "prompt"` |+| **MCP Elicitation** | MCP servers 可在工具执行期间请求用户输入 | 通过 `Elicitation` 和 `ElicitationResult` hook 事件处理 |+| **WebSocket MCP Transport** | 用 WebSocket 连接 MCP server | 在 MCP server 配置中使用 `"transport": "websocket"` |+| **Plugin LSP Support** | 通过 plugins 集成 Language Server Protocol | 在 `plugin.json` 中配置 LSP servers,以获得编辑器能力 |+| **Managed Drop-ins** | 组织管理的 drop-in 配置(v2.1.83) | 通过 managed policies 由管理员配置,自动应用到所有用户 |++---++## 快速参考矩阵++### 功能选择指南++| 需求 | 推荐功能 | 原因 |+|------|---------------------|-----|+| 快捷命令 | Slash Command | 手动、立即执行 |+| 持久上下文 | Memory | 自动加载 |+| 复杂自动化 | Skill | 自动触发 |+| 专门任务 | Subagent | 隔离上下文 |+| 外部数据 | MCP Server | 实时访问 |+| 事件自动化 | Hook | 事件触发 |+| 完整解决方案 | Plugin | 一体化打包 |++### 安装优先级++| 优先级 | 功能 | 命令 |+|----------|---------|---------|+| 1. 必装 | Memory | `cp 02-memory/project-CLAUDE.md ./CLAUDE.md` |+| 2. 日常使用 | Slash Commands | `cp 01-slash-commands/*.md .claude/commands/` |+| 3. 质量提升 | Subagents | `cp 04-subagents/*.md .claude/agents/` |+| 4. 自动化 | Hooks | `cp 06-hooks/*.sh ~/.claude/hooks/` |+| 5. 集成 | MCP Servers | `claude mcp add github -- npx -y @modelcontextprotocol/server-github` |+| 6. 全量打包 | Plugins | `/plugin install <name>` |++---++## 一条命令完成安装++```bash+# 创建目录+mkdir -p .claude/commands .claude/agents ~/.claude/hooks ~/.claude/skills++# 安装所有功能+cp 01-slash-commands/*.md .claude/commands/+cp 04-subagents/*.md .claude/agents/+cp -r 03-skills/* ~/.claude/skills/+cp 06-hooks/*.sh ~/.claude/hooks/+chmod +x ~/.claude/hooks/*.sh++# 配置 MCP+export GITHUB_TOKEN="your_token"+claude mcp add github -- npx -y @modelcontextprotocol/server-github++# 使用 Plugins+/plugin install pr-review+/plugin install devops-automation+```++---++## 其他资源++- [Claude Code Documentation](https://code.claude.com/docs/en/overview)+- [MCP Protocol Specification](https://modelcontextprotocol.io)+- [Skills Repository](https://github.com/luongnv89/skills) - 现成 skills 集合+- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook)+- [Boris Cherny's Claude Code Workflow](https://x.com/bcherny/status/2007179832300581177) - Claude Code 的创造者分享了他的系统化工作流:并行 agents、共享 `CLAUDE.md`、Plan mode、slash commands、subagents,以及用于长时间自主会话的验证 hooks。diff --git a/zh/CHANGELOG.md b/zh/CHANGELOG.mdnew file mode 100644index 0000000..024f5b0--- /dev/null+++ b/zh/CHANGELOG.md@@ -0,0 +1,109 @@+# 更新日志++## v2.2.0 — 2026-03-26++### 文档++- 与 Claude Code v2.1.84(f78c094)同步更新所有教程和参考文档 @luongnv89+ - 将 slash commands 更新为 55+ 个内置命令 + 5 个 bundled skills,并标记 3 个已弃用项+ - 将 hook 事件从 18 个扩展到 25 个,新增 `agent` hook 类型(现在共 4 类)+ - 在高级功能中加入自动模式(Auto Mode)、通道(Channels)、语音输入(Voice Dictation)+ - 为 skill frontmatter 增加 `effort`、`shell` 字段;为 agent 增加 `initialPrompt`、`disallowedTools` 字段+ - 增加 WebSocket MCP transport、elicitation、2KB 工具上限+ - 增加 plugin 的 LSP 支持、`userConfig`、`${CLAUDE_PLUGIN_DATA}`+ - 更新所有参考文档(CATALOG、QUICK_REFERENCE、LEARNING-ROADMAP、INDEX)+- 将 README 重写为落地页结构化指南(32a0776)@luongnv89++### Bug 修复++- 为通过 CI 词典检查,补充缺失的 cSpell 词条和 README 章节(93f9d51)@luongnv89+- 在 cSpell 词典中加入 `Sandboxing`(b80ce6f)@luongnv89++**完整更新日志**:https://github.com/luongnv89/claude-howto/compare/v2.1.1...v2.2.0++---++## v2.1.1 — 2026-03-13++### Bug 修复++- 移除导致 CI 链接检查失败的失效 marketplace 链接(3fdf0d6)@luongnv89+- 将 `sandboxed` 和 `pycache` 加入 cSpell 词典(dc64618)@luongnv89++**完整更新日志**:https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1++---++## v2.1.0 — 2026-03-13++### 功能++- 新增自适应学习路径,包含自我评估和 lesson quiz skills(1ef46cd)@luongnv89+ - `/self-assessment` - 覆盖 10 个功能领域的交互式能力测验,并生成个性化学习路径+ - `/lesson-quiz [lesson]` - 每课知识检查,包含 8-10 道针对性问题++### Bug 修复++- 更新失效 URL、弃用项和过时引用(8fe4520)@luongnv89+- 修复 resources 和 self-assessment skill 中的损坏链接(7a05863)@luongnv89+- 在 concepts guide 中为嵌套代码块使用 tilde fences(5f82719)@VikalpP+- 为 cSpell 词典补充缺失词汇(8df7572)@luongnv89++### 文档++- Phase 5 QA - 修复各文档中的一致性、URL 和术语问题(00bbe4c)@luongnv89+- 完成 Phase 3-4 - 补充新功能覆盖和参考文档更新(132de29)@luongnv89+- 在 MCP 上下文膨胀章节加入 MCPorter runtime(ef52705)@luongnv89+- 为 6 份指南补充缺失命令、功能和设置(4bc8f15)@luongnv89+- 基于仓库现有规范补充 style guide(84141d0)@luongnv89+- 在指南对比表中加入自我评估行(8fe0c96)@luongnv89+- 将 VikalpP 加入贡献者名单,记录 PR #7(d5b4350)@luongnv89+- 在 README 和 roadmap 中加入 self-assessment 与 lesson-quiz skill 参考(d5a6106)@luongnv89++### 新贡献者++- @VikalpP 完成了他们的首次贡献,见 #7++**完整更新日志**:https://github.com/luongnv89/claude-howto/compare/v2.0.0...v2.1.0++---++## v2.0.0 — 2026-02-01++### 功能++- 与 Claude Code 2026 年 2 月功能同步更新全部文档(487c96d)+ - 更新所有 10 个教程目录和 7 份参考文档中的 26 个文件+ - 补充 **Auto Memory** 文档 - 每个项目的持久学习能力+ - 补充 **Remote Control**、**Web Sessions** 和 **Desktop App** 文档+ - 补充 **Agent Teams** 文档(实验性多 agent 协作)+ - 补充 **MCP OAuth 2.0**、**Tool Search** 和 **Claude.ai Connectors** 文档+ - 补充 subagents 的 **Persistent Memory** 和 **Worktree Isolation** 文档+ - 补充 **Background Subagents**、**Task List**、**Prompt Suggestions** 文档+ - 补充 **Sandboxing** 和 **Managed Settings**(Enterprise)文档+ - 补充 **HTTP Hooks** 和 7 个新 hook 事件的文档+ - 补充 **Plugin Settings**、**LSP Servers** 和 marketplace 更新文档+ - 补充 Checkpoint 的 **Summarize from Checkpoint** 回退选项文档+ - 记录 17 个新的 slash commands(`/fork`、`/desktop`、`/teleport`、`/tasks`、`/fast` 等)+ - 记录新的 CLI flags(`--worktree`、`--from-pr`、`--remote`、`--teleport`、`--teammate-mode` 等)+ - 记录 auto memory、effort 等级、agent teams 等新的环境变量++### 设计++- 将 logo 重设计为简洁调色的 compass-bracket 标志(20779db)++### Bug 修复 / 修正++- 更新模型名称:Sonnet 4.5 → **Sonnet 4.6**,Opus 4.5 → **Opus 4.6**+- 修正 permission mode 名称:用真实的 `default` / `acceptEdits` / `plan` / `dontAsk` / `bypassPermissions` 替代虚构的 “Unrestricted/Confirm/Read-only”+- 修正 hook 事件:移除虚构的 `PreCommit` / `PostCommit` / `PrePush`,加入真实事件(`SubagentStart`、`WorktreeCreate`、`ConfigChange` 等)+- 修正 CLI 语法:用 `claude -p`(print mode)替代虚构的 `claude-code --headless`+- 修正 checkpoint 命令:用真实的 `Esc+Esc` / `/rewind` 界面替代虚构的 `/checkpoint save/list/rewind/diff`+- 修正 session 管理:用真实的 `/resume` / `/rename` / `/fork` 替代虚构的 `/session list/new/switch/save`+- 修正 plugin manifest 格式:从 `plugin.yaml` 迁移到 `.claude-plugin/plugin.json`+- 修正 MCP 配置路径:`~/.claude/mcp.json` → `.mcp.json`(项目)/ `~/.claude.json`(用户)+- 修正文档 URL:`docs.claude.com` → `docs.anthropic.com`;移除虚构的 `plugins.claude.com`+- 移除多个文件中虚构的配置字段+- 将所有 “Last Updated” 日期更新到 2026 年 2 月++**完整更新日志**:https://github.com/luongnv89/claude-howto/compare/20779db...v2.0.0diff --git a/zh/CODE_OF_CONDUCT.md b/zh/CODE_OF_CONDUCT.mdnew file mode 100644index 0000000..b64c98d--- /dev/null+++ b/zh/CODE_OF_CONDUCT.md@@ -0,0 +1,216 @@+# 贡献者行为准则++## 我们的承诺++我们致力于为所有人提供一个热情且鼓舞人心的社区。我们承诺,参与本社区的每个人都应拥有免受骚扰的体验,不论其年龄、身体大小、种姓、残障、族裔、性别特征、性别认同与表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教,或性取向与性身份如何。++我们致力于打造一个积极、包容且安全的环境,让所有贡献者都感到被尊重、被重视,并能充分发挥自己的能力。++## 我们的标准++有助于营造积极环境的行为包括:++### 保持尊重+- 使用热情且包容的语言+- 尊重不同的观点、立场和经历+- 愉快地接受建设性批评+- 尊重文化和语言差异+- 认可并庆祝多元背景++### 保持协作+- 共同解决冲突+- 给予他人应得的署名和认可+- 帮助他人学习和成长+- 分享知识并积极提问+- 支持社区里的其他成员++### 保持专业+- 保持讨论聚焦且高效+- 避免贬低或侮辱性言论+- 在 issue 和 discussion 中保持主题相关+- 使用清晰且尊重的沟通方式+- 假设他人的消息都出于善意++### 保持包容+- 欢迎新贡献者+- 帮助刚接触项目的人上手+- 提供建设性的反馈+- 接纳不同视角的人+- 为安静的声音创造被听见的空间++## 不可接受的行为++以下行为被视为骚扰,在本社区中不可接受:++### 骚扰与歧视+- 与性别、性别认同与表达、性取向、残障、心理疾病、神经类型、外貌、体型、年龄、种族或宗教相关的冒犯性言论+- 关于某人生活方式或生活选择的不受欢迎评论+- 故意使用错误称谓,或使用“死名”或被拒绝的名字+- 与主题无关的露骨性图像或行为+- 未经同意或在要求停止后仍进行肢体接触或模拟肢体接触++### 滥用行为+- 指向他人的暴力威胁或暴力言论+- 唆使暴力或针对个人的暴力言论+- 故意恐吓+- 跟踪或尾随+- 反复联系造成骚扰+- 任何其他合理上可视为不当的行为++### 线上骚扰+- 持续干扰在线讨论+- 发布他人隐私信息(人肉搜索 / doxxing)+- 不受欢迎的性关注或性骚扰+- 刷屏、挑衅或故意捣乱+- 垃圾广告或重复性宣传+- 散布错误信息或虚假信息++### 报复+- 因他人举报违规而采取报复行动+- 因他人举报不当行为而区别对待+- 以举报作为威胁++## 适用范围++本行为准则适用于:+- 所有社区空间(GitHub issues、pull requests、discussions 等)+- 项目仓库和文档+- 由项目组织或代表项目参加的活动和聚会+- 代表项目或社区的公共场合+- 与项目事务相关的私人沟通++本行为准则适用于所有项目空间;当个人在公共场合代表项目或社区时,也同样适用。代表项目或社区的例子包括使用官方项目邮箱、通过官方社交账号发帖,或在线上/线下活动中担任指定代表。++## 执行++社区负责人负责澄清并执行可接受行为标准,并会针对任何被认为不当、具有威胁性、冒犯性或有害的行为采取适当且公正的纠正措施。++### 举报违规++如果你经历或目睹了不可接受的行为,或者有其他担忧,请通过以下方式报告:++1. **Email**:联系项目维护者(如可用,请填写联系方式)+2. **GitHub Issues**:使用私密举报功能(如果你的 GitHub 设置中可用)+3. **直接消息**:直接联系项目维护者++请提供:+- 你的联系方式+- 涉及人员的姓名(如果你愿意提供)+- 事件描述+- 上下文和相关链接+- 事件对你的影响++**所有报告都会被保密。**++### 调查与响应++社区负责人将:+- 及时且公正地审查和调查所有投诉+- 对举报人保持保密+- 向举报人反馈处理进展+- 根据调查结果采取适当行动++可能的措施包括:+- 私下警告或辅导+- 公开道歉(若违规者同意)+- 暂时或永久移出社区空间+- 取消贡献者权限+- 必要时升级至 GitHub 或其他平台++### 申诉流程++如果你认为某项决定有误,可以通过以下方式申诉:+1. 提供新的信息或上下文+2. 请求多位维护者复核+3. 在初次决定后的 30 天内跟进++## 如何尊重地表达分歧++技术社区中出现分歧是正常的。以下是尊重地表达不同意见的方法:++### 应该做的+- ✅ 聚焦观点,而不是人+- ✅ 询问澄清问题+- ✅ 承认对立观点中的合理之处+- ✅ 使用 “我” 陈述(例如:“我不同意,因为……”)+- ✅ 引用来源和证据+- ✅ 感谢他人的观点++### 不应该做的+- ❌ 人身攻击+- ❌ 使用贬低性语言(如“这太蠢了”)+- ❌ 预设他人恶意+- ❌ 提及无关的过往冲突+- ❌ 升级语气或变得敌对+- ❌ 故意歪曲他人观点++### 尊重分歧示例+```+❌ 不好:“这是个愚蠢的想法,你显然不了解这个项目。”++✅ 更好:“我理解你的意思,但我担心这种做法在更大的项目里可能+不太能扩展。你考虑过这个基准测试里展示的性能影响吗?我很想听听+你的看法。”+```++## 搭建桥梁++我们相信对话与和解的力量:++- 如果别人指出你的行为问题,请认真倾听并反思+- 如果你造成了伤害,愿意道歉+- 支持他人的学习和成长+- 记住每个人都会犯错+- 聚焦解决方案,而不是归咎+- 在坚持责任的同时,保持善意++## 遵守本准则的好处++通过维护一个尊重且包容的社区,我们能够:+- 吸引拥有不同视角的贡献者+- 通过协作产出更好的解决方案+- 建立更牢固的关系+- 让项目对新成员更友好+- 产出更高质量的文档和示例+- 培养学习与成长的文化++## 特别说明++### 对维护者+- 以身作则,遵守本准则+- 对举报保持响应+- 在决策上保持透明+- 帮助公正地解决冲突+- 为所有人创造安全环境++### 对贡献者+- 假设维护者和其他贡献者都怀有善意+- 提供建设性的反馈+- 支持新成员+- 帮助维护社区标准+- 对社区文化承担责任++### 对所有人+- 记住每条消息背后都是一个人+- 如果感到沮丧,先暂停一下+- 需要支持时请联系社区负责人+- 帮助创造你希望参与的社区++## 来源说明++本行为准则参考并改编自:+- [Contributor Covenant](https://www.contributor-covenant.org/)+- [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/)+- [Python Community Code of Conduct](https://www.python.org/psf/conduct/)++## 有问题?++如果你对本行为准则有任何疑问,请联系项目维护者。++## 版本历史++- **版本 1.0**(2026 年 1 月)- 初始行为准则++---++**感谢你帮助我们打造一个热情、包容且互相尊重的社区!** 🌟diff --git a/zh/CONTRIBUTING.md b/zh/CONTRIBUTING.mdnew file mode 100644index 0000000..bffded9--- /dev/null+++ b/zh/CONTRIBUTING.md@@ -0,0 +1,378 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">+</picture>++# 为 Claude How To 贡献内容++感谢你愿意为这个项目做出贡献。这份指南会帮助你更高效地参与协作。++## 关于本项目++Claude How To 是一份面向 Claude Code 的可视化、以示例驱动的学习指南。我们提供:+- **Mermaid 图表**,解释各项功能的工作方式+- **可直接投入使用的模板**,你可以马上复制到项目中+- **带上下文和最佳实践的真实案例**+- **从入门到进阶的渐进式学习路径**++## 贡献类型++### 1. 新示例或新模板+为已有功能补充示例,例如 slash commands、skills、hooks 等:+- 可直接复制粘贴的代码+- 清楚说明工作原理+- 使用场景与收益+- 排障提示++### 2. 文档改进+- 澄清容易混淆的内容+- 修复拼写和语法问题+- 补充缺失信息+- 优化代码示例++### 3. 功能指南+为新的 Claude Code 功能编写指南:+- 分步骤教程+- 架构图+- 常见模式和反模式+- 真实工作流++### 4. Bug 报告+报告你遇到的问题:+- 你原本期望发生什么+- 实际发生了什么+- 复现步骤+- 相关的 Claude Code 版本和操作系统++### 5. 反馈与建议+帮助我们改进这份指南:+- 建议更好的解释方式+- 指出覆盖不足的地方+- 推荐新章节或重组结构++## 快速开始++### 1. Fork 并克隆+```bash+git clone https://github.com/luongnv89/claude-howto.git+cd claude-howto+```++### 2. 创建分支+使用能说明用途的分支名:+```bash+git checkout -b add/feature-name+git checkout -b fix/issue-description+git checkout -b docs/improvement-area+```++### 3. 配置开发环境++pre-commit hooks 会在本地、每次提交前运行与 CI 相同的检查。PR 被接受前,下面四项检查都必须通过。++**必需依赖:**++```bash+# Python 工具链(uv 是本项目的包管理器)+pip install uv+uv venv+source .venv/bin/activate+uv pip install -r scripts/requirements-dev.txt++# Markdown lint 工具(Node.js)+npm install -g markdownlint-cli++# Mermaid 图表校验器(Node.js)+npm install -g @mermaid-js/mermaid-cli++# 安装 pre-commit 并启用 hooks+uv pip install pre-commit+pre-commit install+```++**验证配置:**++```bash+pre-commit run --all-files+```++每次提交都会运行这些 hooks:++| Hook | 检查内容 |+|------|----------|+| `markdown-lint` | Markdown 格式和结构 |+| `cross-references` | 相对链接、锚点、代码围栏 |+| `mermaid-syntax` | 所有 ` ```mermaid ` 代码块是否可正确解析 |+| `link-check` | 外部 URL 是否可访问 |+| `build-epub` | `.md` 变更时 EPUB 是否能无错误生成 |++## 目录结构++```+├── 01-slash-commands/ # 用户手动触发的快捷命令+├── 02-memory/ # 持久上下文示例+├── 03-skills/ # 可复用能力+├── 04-subagents/ # 专门化 AI 助手+├── 05-mcp/ # Model Context Protocol 示例+├── 06-hooks/ # 事件驱动自动化+├── 07-plugins/ # 打包功能集合+├── 08-checkpoints/ # 会话快照+├── 09-advanced-features/ # 规划、思考、后台任务+├── 10-cli/ # CLI 参考+├── scripts/ # 构建与工具脚本+└── README.md # 主指南+```++## 如何贡献示例++### 添加 Slash Command+1. 在 `01-slash-commands/` 中创建一个 `.md` 文件+2. 包含:+ - 清晰说明用途+ - 使用场景+ - 安装说明+ - 使用示例+ - 自定义技巧+3. 更新 `01-slash-commands/README.md`++### 添加 Skill+1. 在 `03-skills/` 中创建一个目录+2. 包含:+ - `SKILL.md` - 主文档+ - `scripts/` - 如有需要可放辅助脚本+ - `templates/` - 提示词模板+ - README 中的示例用法+3. 更新 `03-skills/README.md`++### 添加 Subagent+1. 在 `04-subagents/` 中创建一个 `.md` 文件+2. 包含:+ - agent 的目标和能力+ - 系统提示词结构+ - 示例使用场景+ - 集成示例+3. 更新 `04-subagents/README.md`++### 添加 MCP 配置+1. 在 `05-mcp/` 中创建一个 `.json` 文件+2. 包含:+ - 配置说明+ - 所需环境变量+ - 配置步骤+ - 使用示例+3. 更新 `05-mcp/README.md`++### 添加 Hook+1. 在 `06-hooks/` 中创建一个 `.sh` 文件+2. 包含:+ - shebang 和说明+ - 逻辑清晰的注释+ - 错误处理+ - 安全考虑+3. 更新 `06-hooks/README.md`++## 编写规范++### Markdown 风格+- 使用清晰的标题层级(章节用 H2,小节用 H3)+- 段落保持简短且聚焦+- 列表用项目符号+- 代码块要标明语言+- 各章节之间保留空行++### 代码示例+- 示例要能直接复制粘贴+- 为不明显的逻辑添加注释+- 同时提供简单版和进阶版+- 展示真实使用场景+- 标出可能的坑++### 文档写作+- 解释“为什么”,而不只是“是什么”+- 包含前置条件+- 添加排障章节+- 链接相关主题+- 保持对初学者友好++### JSON/YAML+- 统一缩进风格(2 或 4 个空格)+- 为配置添加注释+- 包含验证示例++### 图表+- 尽量使用 Mermaid+- 保持图表简洁易读+- 在图表下方补充说明+- 链接到相关章节++## Commit 规范++使用 conventional commit 格式:+```+type(scope): description++[optional body]+```++类型包括:+- `feat`:新功能或新示例+- `fix`:修复或更正+- `docs`:文档变更+- `refactor`:代码重构+- `style`:格式调整+- `test`:新增或修改测试+- `chore`:构建、依赖等++示例:+```+feat(slash-commands): Add API documentation generator+docs(memory): Improve personal preferences example+fix(README): Correct table of contents link+docs(skills): Add comprehensive code review skill+```++## 提交前检查++### 清单+- [ ] 代码符合项目风格与约定+- [ ] 新示例附带清晰文档+- [ ] README 已更新(本地和根目录)+- [ ] 不包含敏感信息(API key、凭据)+- [ ] 示例经过测试并可运行+- [ ] 链接已验证且正确+- [ ] 文件权限正确(脚本可执行)+- [ ] Commit 信息清晰且有描述性++### 本地测试+```bash+# 运行所有 pre-commit 检查(与 CI 相同)+pre-commit run --all-files++# 查看改动+git diff+```++## Pull Request 流程++1. **创建带有清晰说明的 PR**:+ - 这次提交做了什么?+ - 为什么需要它?+ - 是否有关联 issue?++2. **补充相关细节**:+ - 新功能?请说明使用场景+ - 文档?请说明改进点+ - 示例?展示前后对比++3. **关联 issue**:+ - 使用 `Closes #123` 自动关闭相关 issue++4. **耐心等待审查**:+ - 维护者可能会提出改进建议+ - 根据反馈迭代+ - 最终决定由维护者负责++## Code Review 流程++审查者会检查:+- **准确性**:描述是否与实际一致?+- **质量**:是否达到生产可用?+- **一致性**:是否符合项目模式?+- **文档**:是否清晰完整?+- **安全性**:是否存在漏洞?++## 报告问题++### Bug 报告+请包含:+- Claude Code 版本+- 操作系统+- 复现步骤+- 预期行为+- 实际行为+- 如有必要,附上截图++### 功能请求+请包含:+- 使用场景或要解决的问题+- 建议方案+- 你考虑过的替代方案+- 额外上下文++### 文档问题+请包含:+- 哪里令人困惑或缺失+- 建议如何改进+- 示例或参考资料++## 项目政策++### 敏感信息+- 永远不要提交 API key、token 或凭据+- 示例中使用占位符+- 为配置文件提供 `.env.example`+- 文档中说明所需环境变量++### 代码质量+- 示例要聚焦且易读+- 避免过度设计+- 对不明显的逻辑添加注释+- 提交前充分测试++### 知识产权+- 原创内容归作者所有+- 项目采用教育用途许可证+- 尊重已有版权+- 需要时注明来源++## 获取帮助++- **提问**:在 GitHub Issues 中发起 discussion+- **通用帮助**:先查看现有文档+- **开发帮助**:参考类似示例+- **Code Review**:在 PR 中 @ 维护者++## 认可++贡献者会被收录在:+- `README.md` 的 Contributors 部分+- GitHub contributors 页面+- Commit 历史++## 安全++在贡献示例和文档时,请遵守安全编码实践:++- **绝不要硬编码密钥或 API key** - 使用环境变量+- **提示安全影响** - 标出潜在风险+- **使用安全默认值** - 默认启用安全功能+- **验证输入** - 展示正确的输入校验和清理方式+- **加入安全提示** - 记录安全注意事项++如遇安全问题,请参见 [SECURITY.md](SECURITY.md) 获取漏洞报告流程。++## 行为准则++我们承诺打造一个热情且包容的社区。请阅读 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 查看完整社区标准。++简要来说:+- 保持尊重和包容+- 愉快地接受反馈+- 帮助他人成长和学习+- 避免骚扰或歧视+- 向维护者报告问题++所有贡献者都应遵守这份准则,并以善意和尊重对待彼此。++## 许可证++为本项目贡献内容,即表示你同意你的贡献将按 MIT License 许可。详情见 [LICENSE](LICENSE) 文件。++## 有问题?++- 查看 [README.md](README.md)+- 阅读 [LEARNING-ROADMAP.md](LEARNING-ROADMAP.md)+- 查看已有示例+- 发起 issue 讨论++感谢你的贡献!diff --git a/zh/INDEX.md b/zh/INDEX.mdnew file mode 100644index 0000000..4f28844--- /dev/null+++ b/zh/INDEX.md@@ -0,0 +1,900 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">+</picture>++# Claude Code 示例 - 完整索引++这份文档是仓库里所有示例文件的完整索引,按功能类型整理,方便你快速定位需要的内容。++## 概览统计++- **总文件数**:100+ 文件+- **分类数**:10 个功能分类+- **插件**:3 个完整插件+- **Skills**:6 个完整 skills+- **Hooks**:8 个示例 hook+- **可直接使用**:所有示例都可直接拿来用++---++## 01. Slash Commands(10 个文件)++用于常见工作流的用户触发快捷命令。++| 文件 | 说明 | 使用场景 |+|------|------|----------|+| `optimize.md` | 代码优化分析器 | 查找性能问题 |+| `pr.md` | Pull Request 准备 | PR 工作流自动化 |+| `generate-api-docs.md` | API 文档生成器 | 生成 API 文档 |+| `commit.md` | 提交信息助手 | 统一提交风格 |+| `setup-ci-cd.md` | CI/CD 流水线设置 | DevOps 自动化 |+| `push-all.md` | 推送所有变更 | 快速推送工作流 |+| `unit-test-expand.md` | 扩展单元测试覆盖率 | 测试自动化 |+| `doc-refactor.md` | 文档重构 | 文档优化 |+| `pr-slash-command.png` | 截图示例 | 视觉参考 |+| `README.md` | 文档 | 安装与使用指南 |++**安装路径**:`.claude/commands/`++**使用方式**:`/optimize`、`/pr`、`/generate-api-docs`、`/commit`、`/setup-ci-cd`、`/push-all`、`/unit-test-expand`、`/doc-refactor`++---++## 02. Memory(6 个文件)++持久化上下文和项目规范。++| 文件 | 说明 | 范围 | 位置 |+|------|------|------|------|+| `project-CLAUDE.md` | 团队项目规范 | 整个项目 | `./CLAUDE.md` |+| `directory-api-CLAUDE.md` | API 专用规则 | 目录级 | `./src/api/CLAUDE.md` |+| `personal-CLAUDE.md` | 个人偏好 | 用户级 | `~/.claude/CLAUDE.md` |+| `memory-saved.png` | 截图:记忆已保存 | - | 视觉参考 |+| `memory-ask-claude.png` | 截图:询问 Claude | - | 视觉参考 |+| `README.md` | 文档 | - | 参考说明 |++**安装方式**:复制到对应位置++**使用方式**:Claude 会自动加载++---++## 03. Skills(28 个文件)++带脚本和模板的自动触发能力。++### 代码审查 Skill(5 个文件)++```text+code-review/+├── SKILL.md # Skill 定义+├── scripts/+│ ├── analyze-metrics.py # 代码指标分析器+│ └── compare-complexity.py # 复杂度对比+└── templates/+ ├── review-checklist.md # 审查清单+ └── finding-template.md # 问题记录模板+```++**用途**:结合安全、性能和质量分析的完整代码审查++**自动触发**:在审查代码时++### 品牌语气 Skill(4 个文件)++```text+brand-voice/+├── SKILL.md # Skill 定义+├── templates/+│ ├── email-template.txt # 邮件格式+│ └── social-post-template.txt # 社交媒体格式+└── tone-examples.md # 示例消息+```++**用途**:确保对外沟通中的品牌语气一致++**自动触发**:在编写营销文案时++### 文档生成 Skill(2 个文件)++```text+doc-generator/+├── SKILL.md # Skill 定义+└── generate-docs.py # Python 文档提取器+```++**用途**:从源代码生成完整的 API 文档++**自动触发**:在创建或更新 API 文档时++### 重构 Skill(5 个文件)++```text+refactor/+├── SKILL.md # Skill 定义+├── scripts/+│ ├── analyze-complexity.py # 复杂度分析器+│ └── detect-smells.py # 代码异味检测器+├── references/+│ ├── code-smells.md # 代码异味目录+│ └── refactoring-catalog.md # 重构模式目录+└── templates/+ └── refactoring-plan.md # 重构计划模板+```++**用途**:结合复杂度分析进行系统化代码重构++**自动触发**:在重构代码时++### Claude MD Skill(1 个文件)++```text+claude-md/+└── SKILL.md # Skill 定义+```++**用途**:管理和优化 `CLAUDE.md` 文件++### 博客草稿 Skill(3 个文件)++```text+blog-draft/+├── SKILL.md # Skill 定义+└── templates/+ ├── draft-template.md # 博客草稿模板+ └── outline-template.md # 博客大纲模板+```++**用途**:生成结构统一的博客草稿++**补充**:`README.md` - Skills 总览与使用指南++**安装路径**:`~/.claude/skills/` 或 `.claude/skills/`++---++## 04. Subagents(9 个文件)++带自定义能力的专门化 AI 助手。++| 文件 | 说明 | 工具 | 使用场景 |+|------|------|------|----------|+| `code-reviewer.md` | 代码质量分析 | read, grep, diff, lint_runner | 完整审查 |+| `test-engineer.md` | 测试覆盖分析 | read, write, bash, grep | 测试自动化 |+| `documentation-writer.md` | 文档创建 | read, write, grep | 文档生成 |+| `secure-reviewer.md` | 安全审查(只读) | read, grep | 安全审计 |+| `implementation-agent.md` | 完整实现 | read, write, bash, grep, edit, glob | 功能开发 |+| `debugger.md` | 调试专家 | read, bash, grep | Bug 排查 |+| `data-scientist.md` | 数据分析专家 | read, write, bash | 数据工作流 |+| `clean-code-reviewer.md` | 代码整洁性规范 | read, grep | 代码质量 |+| `README.md` | 文档 | - | 安装与使用指南 |++**安装路径**:`.claude/agents/`++**使用方式**:由主 agent 自动委派++---++## 05. MCP Protocol(5 个文件)++外部工具和 API 集成。++| 文件 | 说明 | 集成对象 | 使用场景 |+|------|------|----------|----------|+| `github-mcp.json` | GitHub 集成 | GitHub API | PR / issue 管理 |+| `database-mcp.json` | 数据库查询 | PostgreSQL / MySQL | 实时数据查询 |+| `filesystem-mcp.json` | 文件操作 | 本地文件系统 | 文件管理 |+| `multi-mcp.json` | 多服务器配置 | GitHub + DB + Slack | 完整集成 |+| `README.md` | 文档 | - | 安装与使用指南 |++**安装路径**:项目级 `.mcp.json` 或用户级 `~/.claude.json`++**使用方式**:例如 `/mcp__github__list_prs`++---++## 06. Hooks(9 个文件)++事件驱动的自动化脚本,会自动执行。++| 文件 | 说明 | 事件 | 使用场景 |+|------|------|------|----------|+| `format-code.sh` | 自动格式化代码 | `PreToolUse:Write` | 代码格式化 |+| `pre-commit.sh` | 提交前运行测试 | `PreToolUse:Bash` | 测试自动化 |+| `security-scan.sh` | 安全扫描 | `PostToolUse:Write` | 安全检查 |+| `log-bash.sh` | 记录 bash 命令 | `PostToolUse:Bash` | 命令日志 |+| `validate-prompt.sh` | 验证提示词 | `PreToolUse` | 输入校验 |+| `notify-team.sh` | 发送通知 | `Notification` | 团队通知 |+| `context-tracker.py` | 跟踪上下文窗口使用量 | `PostToolUse` | 上下文监控 |+| `context-tracker-tiktoken.py` | 基于 token 的上下文跟踪 | `PostToolUse` | 精确 token 统计 |+| `README.md` | 文档 | - | 安装与使用指南 |++**安装路径**:在 `~/.claude/settings.json` 中配置++**使用方式**:在设置中配置后自动执行++**Hook 类型**(4 类,25 个事件):+- 工具 Hook:`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`+- 会话 Hook:`SessionStart`、`SessionEnd`、`Stop`、`StopFailure`、`SubagentStart`、`SubagentStop`+- 任务 Hook:`UserPromptSubmit`、`TaskCompleted`、`TaskCreated`、`TeammateIdle`+- 生命周期 Hook:`ConfigChange`、`CwdChanged`、`FileChanged`、`PreCompact`、`PostCompact`、`WorktreeCreate`、`WorktreeRemove`、`Notification`、`InstructionsLoaded`、`Elicitation`、`ElicitationResult`++---++## 07. Plugins(3 个完整插件,40 个文件)++打包好的功能集合。++### PR Review 插件(10 个文件)++```text+pr-review/+├── .claude-plugin/+│ └── plugin.json # 插件清单+├── commands/+│ ├── review-pr.md # 综合审查+│ ├── check-security.md # 安全检查+│ └── check-tests.md # 测试覆盖检查+├── agents/+│ ├── security-reviewer.md # 安全专家+│ ├── test-checker.md # 测试专家+│ └── performance-analyzer.md # 性能专家+├── mcp/+│ └── github-config.json # GitHub 集成+├── hooks/+│ └── pre-review.js # 审查前校验+└── README.md # 插件文档+```++**功能**:安全分析、测试覆盖、性能影响++**命令**:`/review-pr`、`/check-security`、`/check-tests`++**安装**:`/plugin install pr-review`++### DevOps Automation 插件(15 个文件)++```text+devops-automation/+├── .claude-plugin/+│ └── plugin.json # 插件清单+├── commands/+│ ├── deploy.md # 部署+│ ├── rollback.md # 回滚+│ ├── status.md # 系统状态+│ └── incident.md # 事件响应+├── agents/+│ ├── deployment-specialist.md # 部署专家+│ ├── incident-commander.md # 事件协调+│ └── alert-analyzer.md # 告警分析+├── mcp/+│ └── kubernetes-config.json # Kubernetes 集成+├── hooks/+│ ├── pre-deploy.js # 部署前检查+│ └── post-deploy.js # 部署后任务+├── scripts/+│ ├── deploy.sh # 部署自动化+│ ├── rollback.sh # 回滚自动化+│ └── health-check.sh # 健康检查+└── README.md # 插件文档+```++**功能**:Kubernetes 部署、回滚、监控、事件响应++**命令**:`/deploy`、`/rollback`、`/status`、`/incident`++**安装**:`/plugin install devops-automation`++### Documentation 插件(14 个文件)++```text+documentation/+├── .claude-plugin/+│ └── plugin.json # 插件清单+├── commands/+│ ├── generate-api-docs.md # API 文档生成+│ ├── generate-readme.md # README 创建+│ ├── sync-docs.md # 文档同步+│ └── validate-docs.md # 文档校验+├── agents/+│ ├── api-documenter.md # API 文档专家+│ ├── code-commentator.md # 代码注释专家+│ └── example-generator.md # 示例生成器+├── mcp/+│ └── github-docs-config.json # GitHub 集成+├── templates/+│ ├── api-endpoint.md # API 端点模板+│ ├── function-docs.md # 函数文档模板+│ └── adr-template.md # ADR 模板+└── README.md # 插件文档+```++**功能**:API 文档、README 生成、文档同步、文档校验++**命令**:`/generate-api-docs`、`/generate-readme`、`/sync-docs`、`/validate-docs`++**安装**:`/plugin install documentation`++**补充**:`README.md` - 插件总览与使用指南++---++## 08. Checkpoints and Rewind(2 个文件)++保存会话状态,并探索替代方案。++| 文件 | 说明 | 内容 |+|------|------|------|+| `README.md` | 文档 | 完整的 checkpoint 指南 |+| `checkpoint-examples.md` | 真实示例 | 数据库迁移、性能优化、UI 迭代、调试 |++**核心概念**:+- **Checkpoint**:会话状态快照+- **Rewind**:回到之前的 checkpoint+- **Branch Point**:探索多种方案++**使用方式**:++```bash+# 每次用户提示后都会自动创建 checkpoint+# 如需回退,按两次 Esc,或使用:+/rewind+# 然后选择:恢复代码和对话、恢复对话、+# 恢复代码、从这里开始总结,或算了+```++**使用场景**:+- 尝试不同实现方式+- 从错误中恢复+- 安全试验+- 比较不同方案+- A/B 测试++---++## 09. Advanced Features(3 个文件)++复杂工作流下的高级能力。++| 文件 | 说明 | 功能 |+|------|------|------|+| `README.md` | 完整指南 | 全部高级功能说明 |+| `config-examples.json` | 配置示例 | 10+ 个场景化配置 |+| `planning-mode-examples.md` | 规划示例 | REST API、数据库迁移、重构 |++**扩展功能**:+- Scheduled Tasks:使用 `/loop` 和 cron 工具的周期任务+- Chrome Integration:通过无头 Chromium 做浏览器自动化+- Remote Control(扩展版):连接方式、安全性、对比表+- Keyboard Customization:自定义快捷键、组合键支持、上下文+- Desktop App(扩展版):连接器、`launch.json`、企业功能++### 已覆盖的高级功能++#### Planning Mode+- 编写详细实现计划+- 时间预估与风险评估+- 系统化拆解任务++#### Extended Thinking+- 面向复杂问题的深度推理+- 架构决策分析+- 权衡取舍评估++#### Background Tasks+- 长时间运行且不阻塞当前会话+- 并行开发工作流+- 任务管理与监控++#### Permission Modes+- **default**:风险操作需要审批+- **acceptEdits**:自动接受文件编辑,其他操作仍需审批+- **plan**:只读分析,不做修改+- **auto**:自动批准安全操作,风险操作仍提示+- **dontAsk**:除危险操作外全部接受+- **bypassPermissions**:全部接受(需要 `--dangerously-skip-permissions`)++#### Headless Mode(`claude -p`)+- CI/CD 集成+- 自动化任务执行+- 批处理++#### Session Management+- 多会话管理+- 会话切换与保存+- 会话持久化++#### 交互功能+- 键盘快捷键+- 命令历史+- Tab 补全+- 多行输入++#### 配置+- 完整设置管理+- 环境相关配置+- 按项目定制++#### Scheduled Tasks+- 使用 `/loop` 创建周期任务+- Cron 工具:`CronCreate`、`CronList`、`CronDelete`+- 自动化的重复工作流++#### Chrome Integration+- 通过无头 Chromium 进行浏览器自动化+- 页面测试与抓取能力+- 页面交互与数据提取++#### Remote Control(扩展版)+- 连接方式与协议+- 安全注意事项与最佳实践+- 远程访问方案对比表++#### Keyboard Customization+- 自定义按键绑定配置+- 支持多键组合快捷键+- 基于上下文的按键激活++#### Desktop App(扩展版)+- 用于 IDE 集成的连接器+- `launch.json` 配置+- 企业功能与部署++---++## 10. CLI Usage(1 个文件)++命令行界面使用方式与参考。++| 文件 | 说明 | 内容 |+|------|------|------|+| `README.md` | CLI 文档 | 参数、选项与使用模式 |++**核心 CLI 功能**:+- `claude` - 启动交互式会话+- `claude -p "prompt"` - 无头/非交互模式+- `claude web` - 打开 Web 会话+- `claude --model` - 选择模型(Sonnet 4.6、Opus 4.6)+- `claude --permission-mode` - 设置权限模式+- `claude --remote` - 通过 WebSocket 启用远程控制++---++## 文档文件(13 个文件)++| 文件 | 位置 | 说明 |+|------|------|------|+| `README.md` | `/` | 主总览 |+| `INDEX.md` | `/` | 本完整索引 |+| `QUICK_REFERENCE.md` | `/` | 速查卡片 |+| `README.md` | `/01-slash-commands/` | Slash Commands 指南 |+| `README.md` | `/02-memory/` | Memory 指南 |+| `README.md` | `/03-skills/` | Skills 指南 |+| `README.md` | `/04-subagents/` | Subagents 指南 |+| `README.md` | `/05-mcp/` | MCP 指南 |+| `README.md` | `/06-hooks/` | Hooks 指南 |+| `README.md` | `/07-plugins/` | Plugins 指南 |+| `README.md` | `/08-checkpoints/` | Checkpoints 指南 |+| `README.md` | `/09-advanced-features/` | Advanced Features 指南 |+| `README.md` | `/10-cli/` | CLI 指南 |++---++## 完整文件树++```text+claude-howto/+├── README.md # 主总览+├── INDEX.md # 本文件+├── QUICK_REFERENCE.md # 速查卡片+├── claude_concepts_guide.md # 原始指南+│+├── 01-slash-commands/ # Slash Commands+│ ├── optimize.md+│ ├── pr.md+│ ├── generate-api-docs.md+│ ├── commit.md+│ ├── setup-ci-cd.md+│ ├── push-all.md+│ ├── unit-test-expand.md+│ ├── doc-refactor.md+│ ├── pr-slash-command.png+│ └── README.md+│+├── 02-memory/ # Memory+│ ├── project-CLAUDE.md+│ ├── directory-api-CLAUDE.md+│ ├── personal-CLAUDE.md+│ ├── memory-saved.png+│ ├── memory-ask-claude.png+│ └── README.md+│+├── 03-skills/ # Skills+│ ├── code-review/+│ │ ├── SKILL.md+│ │ ├── scripts/+│ │ │ ├── analyze-metrics.py+│ │ │ └── compare-complexity.py+│ │ └── templates/+│ │ ├── review-checklist.md+│ │ └── finding-template.md+│ ├── brand-voice/+│ │ ├── SKILL.md+│ │ ├── templates/+│ │ │ ├── email-template.txt+│ │ │ └── social-post-template.txt+│ │ └── tone-examples.md+│ ├── doc-generator/+│ │ ├── SKILL.md+│ │ └── generate-docs.py+│ ├── refactor/+│ │ ├── SKILL.md+│ │ ├── scripts/+│ │ │ ├── analyze-complexity.py+│ │ │ └── detect-smells.py+│ │ ├── references/+│ │ │ ├── code-smells.md+│ │ │ └── refactoring-catalog.md+│ │ └── templates/+│ │ └── refactoring-plan.md+│ ├── claude-md/+│ │ └── SKILL.md+│ ├── blog-draft/+│ │ ├── SKILL.md+│ │ └── templates/+│ │ ├── draft-template.md+│ │ └── outline-template.md+│ └── README.md+│+├── 04-subagents/ # Subagents+│ ├── code-reviewer.md+│ ├── test-engineer.md+│ ├── documentation-writer.md+│ ├── secure-reviewer.md+│ ├── implementation-agent.md+│ ├── debugger.md+│ ├── data-scientist.md+│ ├── clean-code-reviewer.md+│ └── README.md+│+├── 05-mcp/ # MCP Protocol+│ ├── github-mcp.json+│ ├── database-mcp.json+│ ├── filesystem-mcp.json+│ ├── multi-mcp.json+│ └── README.md+│+├── 06-hooks/ # Hooks+│ ├── format-code.sh+│ ├── pre-commit.sh+│ ├── security-scan.sh+│ ├── log-bash.sh+│ ├── validate-prompt.sh+│ ├── notify-team.sh+│ ├── context-tracker.py+│ ├── context-tracker-tiktoken.py+│ └── README.md+│+├── 07-plugins/ # Plugins+│ ├── pr-review/+│ │ ├── .claude-plugin/+│ │ │ └── plugin.json+│ │ ├── commands/+│ │ │ ├── review-pr.md+│ │ │ ├── check-security.md+│ │ │ └── check-tests.md+│ │ ├── agents/+│ │ │ ├── security-reviewer.md+│ │ │ ├── test-checker.md+│ │ │ └── performance-analyzer.md+│ │ ├── mcp/+│ │ │ └── github-config.json+│ │ ├── hooks/+│ │ │ └── pre-review.js+│ │ └── README.md+│ ├── devops-automation/+│ │ ├── .claude-plugin/+│ │ │ └── plugin.json+│ │ ├── commands/+│ │ │ ├── deploy.md+│ │ │ ├── rollback.md+│ │ │ ├── status.md+│ │ │ └── incident.md+│ │ ├── agents/+│ │ │ ├── deployment-specialist.md+│ │ │ ├── incident-commander.md+│ │ │ └── alert-analyzer.md+│ │ ├── mcp/+│ │ │ └── kubernetes-config.json+│ │ ├── hooks/+│ │ │ ├── pre-deploy.js+│ │ │ └── post-deploy.js+│ │ ├── scripts/+│ │ │ ├── deploy.sh+│ │ │ ├── rollback.sh+│ │ │ └── health-check.sh+│ │ └── README.md+│ ├── documentation/+│ │ ├── .claude-plugin/+│ │ │ └── plugin.json+│ │ ├── commands/+│ │ │ ├── generate-api-docs.md+│ │ │ ├── generate-readme.md+│ │ │ ├── sync-docs.md+│ │ │ └── validate-docs.md+│ │ ├── agents/+│ │ │ ├── api-documenter.md+│ │ │ ├── code-commentator.md+│ │ │ └── example-generator.md+│ │ ├── mcp/+│ │ │ └── github-docs-config.json+│ │ ├── templates/+│ │ │ ├── api-endpoint.md+│ │ │ ├── function-docs.md+│ │ │ └── adr-template.md+│ │ └── README.md+│ └── README.md+│+├── 08-checkpoints/ # Checkpoints+│ ├── checkpoint-examples.md+│ └── README.md+│+├── 09-advanced-features/ # Advanced Features+│ ├── config-examples.json+│ ├── planning-mode-examples.md+│ └── README.md+│+└── 10-cli/ # CLI 使用+ └── README.md+```++---++## 按使用场景快速开始++### 代码质量与审查++```bash+# 安装 slash command+cp 01-slash-commands/optimize.md .claude/commands/++# 安装 subagent+cp 04-subagents/code-reviewer.md .claude/agents/++# 安装 skill+cp -r 03-skills/code-review ~/.claude/skills/++# 或直接安装完整插件+/plugin install pr-review+```++### DevOps 与部署++```bash+# 安装插件(包含全部功能)+/plugin install devops-automation+```++### 文档++```bash+# 安装 slash command+cp 01-slash-commands/generate-api-docs.md .claude/commands/++# 安装 subagent+cp 04-subagents/documentation-writer.md .claude/agents/++# 安装 skill+cp -r 03-skills/doc-generator ~/.claude/skills/++# 或直接安装完整插件+/plugin install documentation+```++### 团队规范++```bash+# 设置项目 memory+cp 02-memory/project-CLAUDE.md ./CLAUDE.md++# 根据团队规范调整内容+```++### 外部集成++```bash+# 设置环境变量+export GITHUB_TOKEN="your_token"+export DATABASE_URL="postgresql://..."++# 安装 MCP 配置(项目级)+cp 05-mcp/multi-mcp.json .mcp.json+```++### 自动化与校验++```bash+# 安装 hooks+mkdir -p ~/.claude/hooks+cp 06-hooks/*.sh ~/.claude/hooks/+chmod +x ~/.claude/hooks/*.sh++# 在 settings 中配置 hooks(~/.claude/settings.json)+# 参见 06-hooks/README.md+```++### 安全实验++```bash+# 每次用户提示后都会自动创建 checkpoint+# 回退:按 Esc 两次或使用 /rewind+# 然后选择要从回退菜单中恢复的内容++# 参见 08-checkpoints/README.md 的示例+```++### 高级工作流++```bash+# 配置高级功能+# 参见 09-advanced-features/config-examples.json++# 使用 planning mode+/plan 实现功能 X++# 使用权限模式+claude --permission-mode plan # 用于代码审查(只读)+claude --permission-mode acceptEdits # 自动接受编辑+claude --permission-mode auto # 自动批准安全操作++# 以 headless 模式运行 CI/CD+claude -p "Run tests and report results"++# 运行后台任务+在后台运行测试++# 参见 09-advanced-features/README.md 获取完整指南+```++---++## 功能覆盖矩阵++| 分类 | Commands | Agents | MCP | Hooks | Scripts | Templates | Docs | Images | 总计 |+|------|----------|--------|-----|-------|---------|-----------|------|--------|------|+| **01 Slash Commands** | 8 | - | - | - | - | - | 1 | 1 | **10** |+| **02 Memory** | - | - | - | - | - | 3 | 1 | 2 | **6** |+| **03 Skills** | - | - | - | - | 5 | 9 | 1 | - | **28** |+| **04 Subagents** | - | 8 | - | - | - | - | 1 | - | **9** |+| **05 MCP** | - | - | 4 | - | - | - | 1 | - | **5** |+| **06 Hooks** | - | - | - | 8 | - | - | 1 | - | **9** |+| **07 Plugins** | 11 | 9 | 3 | 3 | 3 | 3 | 4 | - | **40** |+| **08 Checkpoints** | - | - | - | - | - | - | 1 | 1 | **2** |+| **09 Advanced** | - | - | - | - | - | - | 1 | 2 | **3** |+| **10 CLI** | - | - | - | - | - | - | 1 | - | **1** |++---++## 学习路径++### 入门(第 1 周)++1. ✅ 阅读 `README.md`+2. ✅ 安装 1 到 2 个 slash command+3. ✅ 创建项目 memory 文件+4. ✅ 试用基础命令++### 中级(第 2-3 周)++1. ✅ 搭建 GitHub MCP+2. ✅ 安装一个 subagent+3. ✅ 尝试委派任务+4. ✅ 安装一个 skill++### 高级(第 4 周及以后)++1. ✅ 安装完整插件+2. ✅ 创建自定义 slash command+3. ✅ 创建自定义 subagent+4. ✅ 创建自定义 skill+5. ✅ 构建自己的插件++### 专家(第 5 周及以后)++1. ✅ 配置 hooks 做自动化+2. ✅ 用 checkpoints 做实验+3. ✅ 配置 planning mode+4. ✅ 充分利用权限模式+5. ✅ 为 CI/CD 配置 headless mode+6. ✅ 熟练掌握会话管理++---++## 按关键词查找++### 性能++- `01-slash-commands/optimize.md` - 性能分析+- `04-subagents/code-reviewer.md` - 性能审查+- `03-skills/code-review/` - 性能指标+- `07-plugins/pr-review/agents/performance-analyzer.md` - 性能专家++### 安全++- `04-subagents/secure-reviewer.md` - 安全审查+- `03-skills/code-review/` - 安全分析+- `07-plugins/pr-review/` - 安全检查++### 测试++- `04-subagents/test-engineer.md` - 测试工程师+- `07-plugins/pr-review/commands/check-tests.md` - 测试覆盖率++### 文档++- `01-slash-commands/generate-api-docs.md` - API 文档命令+- `04-subagents/documentation-writer.md` - 文档编写 agent+- `03-skills/doc-generator/` - 文档生成 skill+- `07-plugins/documentation/` - 完整文档插件++### 部署++- `07-plugins/devops-automation/` - 完整 DevOps 方案++### 自动化++- `06-hooks/` - 事件驱动自动化+- `06-hooks/pre-commit.sh` - 提交前自动化+- `06-hooks/format-code.sh` - 自动格式化+- `09-advanced-features/` - headless 模式用于 CI/CD++### 校验++- `06-hooks/security-scan.sh` - 安全校验+- `06-hooks/validate-prompt.sh` - 提示词校验++### 实验++- `08-checkpoints/` - 使用 rewind 做安全实验+- `08-checkpoints/checkpoint-examples.md` - 真实示例++### 规划++- `09-advanced-features/planning-mode-examples.md` - 规划模式示例+- `09-advanced-features/README.md` - 深度思考++### 配置++- `09-advanced-features/config-examples.json` - 配置示例++---++## 说明++- 所有示例都可直接使用+- 按需修改以适配你的项目+- 示例遵循 Claude Code 最佳实践+- 每个分类都有自己的 README,包含详细说明+- 脚本包含正确的错误处理+- 模板都可自定义++---++## 参与贡献++如果你想增加更多示例,可以按照下面的结构:+1. 创建合适的子目录+2. 包含带使用说明的 README.md+3. 遵循命名规范+4. 充分测试+5. 更新这个索引++---++**最后更新**:2026 年 3 月+**总示例数**:100+ 文件+**分类数**:10 个功能+**Hooks**:8 个自动化脚本+**配置示例**:10+ 个场景+**可直接使用**:所有示例diff --git a/zh/LEARNING-ROADMAP.md b/zh/LEARNING-ROADMAP.mdnew file mode 100644index 0000000..ee333b7--- /dev/null+++ b/zh/LEARNING-ROADMAP.md@@ -0,0 +1,725 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">+</picture>++# 📚 Claude Code 学习路线图++**刚接触 Claude Code?** 这份指南会帮你按照自己的节奏掌握 Claude Code 的各项功能。无论你是完全新手,还是经验丰富的开发者,都可以先做下面的自我评估测验,找到最适合自己的起点。++---++<a id="find-your-level"></a>+## 🧭 找到你的水平++每个人的起点都不同。先做一份快速自我评估,确认最适合你的入口。++**请诚实回答下面的问题:**++- [ ] 我可以启动 Claude Code 并与它对话(`claude`)+- [ ] 我创建或编辑过 `CLAUDE.md`+- [ ] 我至少使用过 3 个内置 slash command(例如 `/help`、`/compact`、`/model`)+- [ ] 我创建过自定义 slash command 或 skill(`SKILL.md`)+- [ ] 我配置过 MCP server(例如 GitHub、数据库)+- [ ] 我在 `~/.claude/settings.json` 中设置过 hooks+- [ ] 我创建或使用过自定义 subagents(`.claude/agents/`)+- [ ] 我使用过 print mode(`claude -p`)做脚本或 CI/CD++**你的水平:**++| 勾选数 | 水平 | 从这里开始 | 完成时间 |+|--------|-------|----------|------------------|+| 0-2 | **Level 1:Beginner** - 从这里开始 | [里程碑 1A](#里程碑-1a第一个命令与-memory) | 约 3 小时 |+| 3-5 | **Level 2:Intermediate** - 构建工作流 | [里程碑 2A](#里程碑-2a自动化skills--hooks) | 约 5 小时 |+| 6-8 | **Level 3:Advanced** - 高阶用户与团队负责人 | [里程碑 3A](#里程碑-3a高级功能) | 约 5 小时 |++> **提示**:如果不确定,宁可从低一级开始。先回顾熟悉内容,总比漏掉基础概念更划算。++> **交互式版本**:在 Claude Code 中运行 `/self-assessment`,就能得到一份引导式、交互式测验,会覆盖全部 10 个功能领域,并生成个性化学习路径。++---++## 🎯 学习理念++本仓库里的文件夹是按照**推荐学习顺序**编号的,背后有 3 个原则:++1. **依赖关系** - 先学基础概念+2. **复杂度** - 先学简单功能,再学高级功能+3. **使用频率** - 先学最常用的功能++这样可以让你一边建立扎实基础,一边尽快获得实际收益。++---++## 🗺️ 你的学习路径++```mermaid+graph TD+ Q["🧭 自我评估测验<br/>找到你的水平"] --> L1+ Q --> L2+ Q --> L3++ subgraph L1["🟢 Level 1:Beginner - 从这里开始"]+ direction LR+ A["1A:第一个命令与 Memory<br/>Slash Commands + Memory"] --> B["1B:安全探索<br/>Checkpoints + CLI Basics"]+ end++ subgraph L2["🔵 Level 2:Intermediate - 构建工作流"]+ direction LR+ C["2A:自动化<br/>Skills + Hooks"] --> D["2B:集成<br/>MCP + Subagents"]+ end++ subgraph L3["🔴 Level 3:Advanced - 高阶用户"]+ direction LR+ E["3A:高级功能<br/>Planning + Permissions"] --> F["3B:团队与分发<br/>Plugins + CLI 精通"]+ end++ L1 --> L2+ L2 --> L3++ style Q fill:#6A1B9A,color:#fff,stroke:#9C27B0,stroke-width:2px+ style A fill:#2E7D32,color:#fff+ style B fill:#2E7D32,color:#fff+ style C fill:#1565C0,color:#fff+ style D fill:#F57C00,color:#fff+ style E fill:#C62828,color:#fff+ style F fill:#B71C1C,color:#fff+```++**颜色说明:**+- 💜 紫色:自我评估测验+- 🟢 绿色:Level 1 - Beginner 路线+- 🔵 蓝色 / 🟡 金色:Level 2 - Intermediate 路线+- 🔴 红色:Level 3 - Advanced 路线++---++## 📊 完整路线图表++| 步骤 | 功能 | 复杂度 | 时间 | 水平 | 依赖 | 为什么学它 | 关键收益 |+|------|---------|-----------|------|-------|--------------|----------------|--------------|+| **1** | [Slash Commands](01-slash-commands/README.md) | ⭐ Beginner | 30 分钟 | Level 1 | 无 | 快速获得生产力提升(55+ 内置命令 + 5 个 bundled skills) | 立即自动化、统一团队规范 |+| **2** | [Memory](02-memory/README.md) | ⭐⭐ Beginner+ | 45 分钟 | Level 1 | 无 | 所有功能的基础 | 持久上下文、偏好设置 |+| **3** | [Checkpoints](08-checkpoints/README.md) | ⭐⭐ Intermediate | 45 分钟 | Level 1 | 会话管理 | 安全探索 | 试验、恢复 |+| **4** | [CLI Basics](10-cli/README.md) | ⭐⭐ Beginner+ | 30 分钟 | Level 1 | 无 | 核心 CLI 用法 | 交互式与 print mode |+| **5** | [Skills](03-skills/README.md) | ⭐⭐ Intermediate | 1 小时 | Level 2 | Slash Commands | 自动化专业能力 | 可复用能力、一致性 |+| **6** | [Hooks](06-hooks/README.md) | ⭐⭐ Intermediate | 1 小时 | Level 2 | 工具、命令 | 工作流自动化(25 个事件、4 种类型) | 校验、质量门禁 |+| **7** | [MCP](05-mcp/README.md) | ⭐⭐⭐ Intermediate+ | 1 小时 | Level 2 | 配置 | 实时数据访问 | 实时集成、API |+| **8** | [Subagents](04-subagents/README.md) | ⭐⭐⭐ Intermediate+ | 1.5 小时 | Level 2 | Memory、命令 | 处理复杂任务(包含 Bash 在内的 6 个内置 agent) | 委派、专业分工 |+| **9** | [Advanced Features](09-advanced-features/README.md) | ⭐⭐⭐⭐⭐ Advanced | 2-3 小时 | Level 3 | 前面所有内容 | 高阶工具 | Planning、自动模式(Auto Mode)、通道(Channels)、语音输入、权限控制 |+| **10** | [Plugins](07-plugins/README.md) | ⭐⭐⭐⭐ Advanced | 2 小时 | Level 3 | 前面所有内容 | 完整解决方案 | 团队入职、分发 |+| **11** | [CLI Mastery](10-cli/README.md) | ⭐⭐⭐ Advanced | 1 小时 | Level 3 | 建议:全部 | 掌握命令行用法 | 脚本、CI/CD、自动化 |++**总学习时间**:约 11-13 小时(或者直接跳到你的水平,节省时间)++---++## 🟢 Level 1:Beginner - 从这里开始++**适合**:测验勾选数 0-2+**时间**:约 3 小时+**重点**:立刻提升生产力,理解基础概念+**结果**:可以熟练日常使用,并准备进入 Level 2++<a id="milestone-1a-first-commands-memory"></a>+### 里程碑 1A:第一个命令与 Memory++**主题**:Slash Commands + Memory+**时间**:1-2 小时+**复杂度**:⭐ Beginner+**目标**:通过自定义命令和持久上下文,快速提升效率++#### 你将完成什么+✅ 为重复性任务创建自定义 slash commands+✅ 为团队规范设置项目 memory+✅ 配置个人偏好+✅ 理解 Claude 如何自动加载上下文++#### 实战练习++```bash+# 练习 1:安装你的第一个 slash command+mkdir -p .claude/commands+cp 01-slash-commands/optimize.md .claude/commands/++# 练习 2:创建项目 memory+cp 02-memory/project-CLAUDE.md ./CLAUDE.md++# 练习 3:试用一下+# 在 Claude Code 中输入:/optimize+```++#### 成功标准+- [ ] 成功执行 `/optimize`+- [ ] Claude 记住了 `CLAUDE.md` 中的项目规范+- [ ] 你知道什么时候用 slash command,什么时候用 memory++#### 下一步+熟悉之后,请阅读:+- [01-slash-commands/README.md](01-slash-commands/README.md)+- [02-memory/README.md](02-memory/README.md)++> **检查理解**:在 Claude Code 中运行 `/lesson-quiz slash-commands` 或 `/lesson-quiz memory`,检验你学会了多少。++---++### 里程碑 1B:安全探索++**主题**:Checkpoints + CLI Basics+**时间**:1 小时+**复杂度**:⭐⭐ Beginner++**目标**:学会安全试验,并使用核心 CLI 命令++#### 你将完成什么+✅ 创建和恢复 checkpoints,安全试验+✅ 理解交互模式与 print mode+✅ 使用基本 CLI 参数和选项+✅ 通过管道处理文件++#### 实战练习++```bash+# 练习 1:尝试 checkpoint 工作流+# 在 Claude Code 中:+# 做一些实验性修改,然后按 Esc+Esc 或使用 /rewind+# 选择你实验之前的 checkpoint+# 选择“恢复代码和对话”返回++# 练习 2:交互模式 vs 输出模式(Print mode)+claude "explain this project" # 交互模式+claude -p "explain this function" # 输出模式(非交互)++# 练习 3:通过管道处理文件内容+cat error.log | claude -p "explain this error"+```++#### 成功标准+- [ ] 成功创建并回退到一个 checkpoint+- [ ] 使用过交互模式和 print mode+- [ ] 把文件通过管道传给 Claude 做分析+- [ ] 明白什么时候该用 checkpoints 做安全试验++#### 下一步+- 阅读:[08-checkpoints/README.md](08-checkpoints/README.md)+- 阅读:[10-cli/README.md](10-cli/README.md)+- **准备进入 Level 2!** 继续看 [里程碑 2A](#里程碑-2a自动化skills--hooks)++> **检查理解**:运行 `/lesson-quiz checkpoints` 或 `/lesson-quiz cli`,确认你准备好进入 Level 2。++---++## 🔵 Level 2:Intermediate - 构建工作流++**适合**:测验勾选数 3-5+**时间**:约 5 小时+**重点**:自动化、集成、任务委派+**结果**:可以构建自动化工作流、接入外部服务,并准备进入 Level 3++### 前置条件检查++开始 Level 2 之前,先确认你已经掌握这些 Level 1 内容:++- [ ] 会创建和使用 slash commands([01-slash-commands/README.md](01-slash-commands/README.md))+- [ ] 会通过 `CLAUDE.md` 设置项目 memory([02-memory/README.md](02-memory/README.md))+- [ ] 知道如何创建和恢复 checkpoints([08-checkpoints/README.md](08-checkpoints/README.md))+- [ ] 会在命令行使用 `claude` 和 `claude -p`([10-cli/README.md](10-cli/README.md))++> **有空缺?** 继续之前,先回顾上面的链接教程。++---++<a id="milestone-2a-automation-skills-hooks"></a>+### 里程碑 2A:自动化(Skills + Hooks)++**主题**:Skills + Hooks+**时间**:2-3 小时+**复杂度**:⭐⭐ Intermediate+**目标**:自动化常见工作流和质量检查++#### 你将完成什么+✅ 通过 YAML frontmatter 自动触发专门能力(包含 `effort` 和 `shell` 字段)+✅ 在 25 个 hook 事件上设置事件驱动自动化+✅ 使用 4 种 hook 类型(command、http、prompt、agent)+✅ 强制执行代码质量标准+✅ 为自己的工作流创建自定义 hooks++#### 实战练习++```bash+# 练习 1:安装一个 skill+cp -r 03-skills/code-review ~/.claude/skills/++# 练习 2:设置 hooks+mkdir -p ~/.claude/hooks+cp 06-hooks/pre-tool-check.sh ~/.claude/hooks/+chmod +x ~/.claude/hooks/pre-tool-check.sh++# 练习 3:在 settings 中配置 hooks+# 添加到 ~/.claude/settings.json:+{+ "hooks": {+ "PreToolUse": [+ {+ "matcher": "Bash",+ "hooks": [+ {+ "type": "command",+ "command": "~/.claude/hooks/pre-tool-check.sh"+ }+ ]+ }+ ]+ }+}+```++#### 成功标准+- [ ] 在相关场景下,代码审查 skill 会自动触发+- [ ] PreToolUse hook 会在工具执行前运行+- [ ] 你理解 skill 自动触发和 hook 事件触发的区别++#### 下一步+- 创建你自己的 custom skill+- 为工作流增加更多 hooks+- 阅读:[03-skills/README.md](03-skills/README.md)+- 阅读:[06-hooks/README.md](06-hooks/README.md)++> **检查理解**:在继续之前,运行 `/lesson-quiz skills` 或 `/lesson-quiz hooks` 测试你的理解。++---++### 里程碑 2B:集成(MCP + Subagents)++**主题**:MCP + Subagents+**时间**:2-3 小时+**复杂度**:⭐⭐⭐ Intermediate++**目标**:集成外部服务,并把复杂任务委派出去++#### 你将完成什么+✅ 从 GitHub、数据库等位置访问实时数据+✅ 把工作委派给专门化 AI agents+✅ 明白什么时候该用 MCP,什么时候该用 subagents+✅ 构建集成式工作流++#### 实战练习++```bash+# 练习 1:设置 GitHub MCP+export GITHUB_TOKEN="your_github_token"+claude mcp add github -- npx -y @modelcontextprotocol/server-github++# 练习 2:测试 MCP 集成+# 在 Claude Code 中:/mcp__github__list_prs++# 练习 3:安装 subagents+mkdir -p .claude/agents+cp 04-subagents/*.md .claude/agents/+```++#### 集成练习+试试这个完整工作流:+1. 用 MCP 获取一个 GitHub PR+2. 让 Claude 把审查任务委派给 code-reviewer subagent+3. 再用 hooks 自动运行测试++#### 成功标准+- [ ] 能通过 MCP 成功查询 GitHub 数据+- [ ] Claude 会把复杂任务委派给 subagents+- [ ] 你理解 MCP 和 subagents 的区别+- [ ] 能把 MCP + subagents + hooks 组合进一个工作流++#### 下一步+- 配置更多 MCP servers(数据库、Slack 等)+- 为你的领域创建自定义 subagents+- 阅读:[05-mcp/README.md](05-mcp/README.md)+- 阅读:[04-subagents/README.md](04-subagents/README.md)+- **准备进入 Level 3!** 继续看 [里程碑 3A](#里程碑-3a高级功能)++> **检查理解**:运行 `/lesson-quiz mcp` 或 `/lesson-quiz subagents`,确认你准备好进入 Level 3。++---++## 🔴 Level 3:Advanced - 高阶用户与团队负责人++**适合**:测验勾选数 6-8+**时间**:约 5 小时+**重点**:团队工具、CI/CD、企业功能、插件开发+**结果**:成为高阶用户,能够搭建团队工作流和 CI/CD++### 前置条件检查++开始 Level 3 之前,先确认你已经掌握这些 Level 2 内容:++- [ ] 会创建并自动触发 skills([03-skills/README.md](03-skills/README.md))+- [ ] 会配置 hooks 做事件驱动自动化([06-hooks/README.md](06-hooks/README.md))+- [ ] 会配置 MCP servers 访问外部数据([05-mcp/README.md](05-mcp/README.md))+- [ ] 知道如何用 subagents 分派任务([04-subagents/README.md](04-subagents/README.md))++> **有空缺?** 继续之前,先回顾上面的链接教程。++---++<a id="milestone-3a-advanced-features"></a>+### 里程碑 3A:高级功能++**主题**:高级功能(Planning、Permissions、Extended Thinking、自动模式(Auto Mode)、通道(Channels)、语音输入(Voice Dictation)、Remote/Desktop/Web)+**时间**:2-3 小时+**复杂度**:⭐⭐⭐⭐⭐ Advanced+**目标**:掌握高级工作流和高阶工具++#### 你将完成什么+✅ 为复杂功能使用 planning mode+✅ 用 6 种模式进行细粒度权限控制(default、acceptEdits、plan、auto、dontAsk、bypassPermissions)+✅ 用 Alt+T / Option+T 切换 extended thinking+✅ 管理后台任务+✅ 使用 Auto Memory 记住偏好+✅ 使用自动模式(Auto Mode)和后台安全分类器+✅ 使用通道(Channels)组织多会话工作流+✅ 使用语音输入(Voice Dictation)解放双手+✅ 远程控制、桌面应用和 Web 会话+✅ 使用 Agent Teams 协作++#### 实战练习++```bash+# 练习 1:使用 planning mode+/plan Implement user authentication system++# 练习 2:尝试权限模式(共有 6 种:default、acceptEdits、plan、auto、dontAsk、bypassPermissions)+claude --permission-mode plan "analyze this codebase"+claude --permission-mode acceptEdits "refactor the auth module"+claude --permission-mode auto "implement the feature"++# 练习 3:启用 extended thinking+# 在会话中按 Alt+T(macOS 上是 Option+T)切换++# 练习 4:高级 checkpoint 工作流+# 1. 创建名为 "Clean state" 的 checkpoint+# 2. 使用 planning mode 设计功能+# 3. 通过 subagent 委派实现+# 4. 在后台运行测试+# 5. 如果测试失败,回退到 checkpoint+# 6. 尝试另一种方案++# 练习 5:尝试自动模式(Auto mode,后台安全分类器)+claude --permission-mode auto "implement user settings page"++# 练习 6:启用 agent teams+export CLAUDE_AGENT_TEAMS=1+# 让 Claude 执行:"Implement feature X using a team approach"++# 练习 7:定时任务+/loop 5m /check-status+# 或使用 CronCreate 创建持久化定时任务++# 练习 8:用通道(Channels)管理多会话工作流+# 用 channels 来组织跨会话工作++# 练习 9:语音输入(Voice Dictation)+# 用语音输入和 Claude Code 进行无手操作+```++#### 成功标准+- [ ] 为复杂功能使用过 planning mode+- [ ] 配置过权限模式(plan、acceptEdits、auto、dontAsk)+- [ ] 用 Alt+T / Option+T 切换过 extended thinking+- [ ] 使用过带后台安全分类器的自动模式(Auto mode)+- [ ] 使用过后台任务处理长时间操作+- [ ] 探索过通道(Channels)做多会话工作流+- [ ] 尝试过语音输入(Voice Dictation)做无手输入+- [ ] 理解 Remote Control、Desktop App 和 Web 会话+- [ ] 启用并使用过 Agent Teams 做协作任务+- [ ] 用过 `/loop` 做周期任务或定时监控++#### 下一步+- 阅读:[09-advanced-features/README.md](09-advanced-features/README.md)++> **检查理解**:运行 `/lesson-quiz advanced`,测试你对高阶功能的掌握程度。++---++### 里程碑 3B:团队与分发(Plugins + CLI 精通)++**主题**:Plugins + CLI 精通 + CI/CD+**时间**:2-3 小时+**复杂度**:⭐⭐⭐⭐ Advanced+**目标**:搭建团队工具、创建插件、熟练集成 CI/CD++#### 你将完成什么+✅ 安装和创建完整的 bundled plugins+✅ 掌握 CLI,用于脚本和自动化+✅ 使用 `claude -p` 做 CI/CD 集成+✅ 为自动化流水线输出 JSON+✅ 管理会话与批处理++#### 实战练习++```bash+# 练习 1:安装一个完整 plugin+# 在 Claude Code 中:/plugin install pr-review++# 练习 2:让 print mode 服务于 CI/CD+claude -p "Run all tests and generate report"++# 练习 3:为脚本输出 JSON+claude -p --output-format json "list all functions"++# 练习 4:会话管理与恢复+claude -r "feature-auth" "continue implementation"++# 练习 5:带约束的 CI/CD 集成+claude -p --max-turns 3 --output-format json "review code"++# 练习 6:批处理+for file in *.md; do+ claude -p --output-format json "summarize this: $(cat $file)" > ${file%.md}.summary.json+done+```++#### CI/CD 集成练习+创建一个简单的 CI/CD 脚本:+1. 用 `claude -p` 审查变更文件+2. 把结果输出成 JSON+3. 用 `jq` 处理特定问题+4. 集成进 GitHub Actions 工作流++---++## 🧪 测试你的知识++根据你刚学完的内容,直接运行下面的测验:++```bash+/lesson-quiz slash-commands+/lesson-quiz memory+/lesson-quiz checkpoints+/lesson-quiz cli+/lesson-quiz skills+/lesson-quiz hooks+/lesson-quiz mcp+/lesson-quiz subagents+/lesson-quiz advanced-features+```++---++## ⚡ 快速开始路径++### 如果你只有 15 分钟+**目标**:先拿到一个立竿见影的成果++1. 复制一个 slash command:`cp 01-slash-commands/optimize.md .claude/commands/`+2. 在 Claude Code 中试一下:`/optimize`+3. 阅读:[01-slash-commands/README.md](01-slash-commands/README.md)++**结果**:你会得到一个能用的 slash command,并理解基础用法++---++### 如果你有 1 小时+**目标**:搭好基础生产力工具++1. **Slash commands**(15 分钟):复制并测试 `/optimize` 和 `/pr`+2. **项目 memory**(15 分钟):用项目规范创建 `CLAUDE.md`+3. **安装一个 skill**(15 分钟):配置 code-review skill+4. **一起试用**(15 分钟):感受它们如何协同工作++**结果**:命令、memory 和自动 skills 带来基础效率提升++---++### 如果你有一个周末+**目标**:熟悉大部分功能++**周六上午**(3 小时):+- 完成里程碑 1A:Slash Commands + Memory+- 完成里程碑 1B:Checkpoints + CLI Basics++**周六下午**(3 小时):+- 完成里程碑 2A:Skills + Hooks+- 完成里程碑 2B:MCP + Subagents++**周日**(4 小时):+- 完成里程碑 3A:高级功能+- 完成里程碑 3B:Plugins + CLI 精通 + CI/CD+- 为你的团队构建一个自定义 plugin++**结果**:你会成为 Claude Code 的高阶用户,能够培训别人并自动化复杂工作流++---++## 💡 学习建议++### ✅ 建议做++- **先做测验**,找到自己的起点+- **完成每个里程碑的实战练习**+- **先从简单开始**,再逐步增加复杂度+- **在进入下一个功能前先测试当前功能**+- **记下哪些做法最适合你的工作流**+- **学习新内容时回头复习基础概念**+- **借助 checkpoints 安全试验**+- **把经验分享给团队**++### ❌ 不建议做++- **不要跳过前置条件检查**+- **不要试图一次学完所有内容**+- **不要照搬配置却不理解它们**+- **不要忘记测试**+- **不要急着跳过里程碑**+- **不要忽视文档**+- **不要把自己隔离起来**++---++## 🎓 学习风格++### 视觉型学习者+- 阅读每个 README 里的 Mermaid 图+- 观察命令执行流程+- 自己画工作流图+- 使用上面的可视化路径图++### 动手型学习者+- 完成每个实战练习+- 试试不同变体+- 先搞坏再修复(记得用 checkpoints)+- 创建自己的示例++### 阅读型学习者+- 认真阅读每个 README+- 研究代码示例+- 看对比表+- 阅读资源区链接的博客文章++### 社交型学习者+- 组织结对编程+- 给队友讲解概念+- 参与 Claude Code 社区讨论+- 分享你的自定义配置++---++## 📈 进度追踪++用这些清单按水平追踪进度。你可以随时运行 `/self-assessment` 更新自己的技能画像,也可以在每个教程后运行 `/lesson-quiz [lesson]` 验证理解。++### 🟢 Level 1:Beginner+- [ ] 完成 [01-slash-commands](01-slash-commands/README.md)+- [ ] 完成 [02-memory](02-memory/README.md)+- [ ] 创建第一个自定义 slash command+- [ ] 设置项目 memory+- [ ] **达到里程碑 1A**+- [ ] 完成 [08-checkpoints](08-checkpoints/README.md)+- [ ] 完成 [10-cli](10-cli/README.md) 基础部分+- [ ] 创建并回退到一个 checkpoint+- [ ] 使用交互模式和 print mode+- [ ] **达到里程碑 1B**++### 🔵 Level 2:Intermediate+- [ ] 完成 [03-skills](03-skills/README.md)+- [ ] 完成 [06-hooks](06-hooks/README.md)+- [ ] 安装第一个 skill+- [ ] 设置 PreToolUse hook+- [ ] **达到里程碑 2A**+- [ ] 完成 [05-mcp](05-mcp/README.md)+- [ ] 完成 [04-subagents](04-subagents/README.md)+- [ ] 连接 GitHub MCP+- [ ] 创建自定义 subagent+- [ ] 把多个集成组合进一个工作流+- [ ] **达到里程碑 2B**++### 🔴 Level 3:Advanced+- [ ] 完成 [09-advanced-features](09-advanced-features/README.md)+- [ ] 成功使用 planning mode+- [ ] 配置权限模式(包含 auto 在内的 6 种)+- [ ] 使用带安全分类器的自动模式(Auto mode)+- [ ] 使用 extended thinking 切换+- [ ] 探索通道(Channels)和语音输入(Voice Dictation)+- [ ] **达到里程碑 3A**+- [ ] 完成 [07-plugins](07-plugins/README.md)+- [ ] 完成 [10-cli](10-cli/README.md) 的高级用法+- [ ] 配置 print mode(`claude -p`)用于 CI/CD+- [ ] 为自动化创建 JSON 输出+- [ ] 把 Claude 集成到 CI/CD 流水线+- [ ] 创建团队 plugin+- [ ] **达到里程碑 3B**++---++## 🆘 常见学习难题++### 难题 1:“概念一下子太多了”+**解决**:一次只关注一个里程碑。完成所有练习后再往下走。++### 难题 2:“不知道什么时候该用哪个功能”+**解决**:回到主 README 里的 [Use Case Matrix](README.md#你能用它做什么)。++### 难题 3:“配置没有生效”+**解决**:检查主 README 里的 [Troubleshooting](README.md#故障排查) 部分,并确认文件路径。++### 难题 4:“概念之间好像重叠”+**解决**:查看主 README 里的 [Feature Comparison](README.md#功能对比) 表,理解差异。++### 难题 5:“太多东西记不住”+**解决**:自己做一份速查表;同时用 checkpoints 安全试验。++### 难题 6:“我经验很足,但不知道从哪里开始”+**解决**:先做上面的 [自我评估测验](#-找到你的水平),直接跳到你的水平,并用前置条件检查找出空缺。++---++## 🎯 学完之后做什么?++完成所有里程碑后,可以继续做这些事:++1. **写团队文档** - 记录团队的 Claude Code 配置+2. **构建自定义 plugins** - 把团队工作流打包起来+3. **探索 Remote Control** - 通过外部工具以编程方式控制 Claude Code 会话+4. **试试 Web Sessions** - 用浏览器界面远程开发+5. **使用 Desktop App** - 通过原生桌面应用访问 Claude Code+6. **使用自动模式(Auto Mode)** - 让 Claude 在后台安全分类器保护下自主工作+7. **启用 Auto Memory** - 让 Claude 随时间自动学习你的偏好+8. **设置 Agent Teams** - 让多个 agent 协同处理复杂、多维任务+9. **使用通道(Channels)** - 用结构化的多会话工作流组织工作+10. **试试语音输入(Voice Dictation)** - 用语音无障碍地与 Claude Code 交互+11. **使用 Scheduled Tasks** - 借助 `/loop` 和 cron 工具自动化周期性检查+12. **贡献示例** - 把经验分享给社区+13. **带新人** - 帮助队友快速上手+14. **持续优化工作流** - 根据使用情况不断改进+15. **保持更新** - 跟进 Claude Code 发布和新功能++---++## 📚 其他资源++### 官方文档+- [Claude Code Documentation](https://code.claude.com/docs/en/overview)+- [Anthropic Documentation](https://docs.anthropic.com)+- [MCP Protocol Specification](https://modelcontextprotocol.io)++### 博客文章+- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29)++### 社区+- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook)+- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)++---++## 💬 反馈与支持++- **发现问题?** 在仓库里创建 issue+- **有建议?** 提交 pull request+- **需要帮助?** 查看文档,或者向社区提问++---++**最后更新**:2026 年 3 月+**维护者**:Claude How-To Contributors+**许可证**:仅供学习与参考,免费使用和改编++---++[← 返回主 README](README.md)diff --git a/zh/QUICK_REFERENCE.md b/zh/QUICK_REFERENCE.mdnew file mode 100644index 0000000..72b7fc0--- /dev/null+++ b/zh/QUICK_REFERENCE.md@@ -0,0 +1,506 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">+</picture>++# Claude Code 示例 - 速查卡++## 🚀 安装速命令++### Slash Commands+```bash+# 安装全部+cp 01-slash-commands/*.md .claude/commands/++# 安装单个+cp 01-slash-commands/optimize.md .claude/commands/+```++### Memory+```bash+# 项目 memory+cp 02-memory/project-CLAUDE.md ./CLAUDE.md++# 个人 memory+cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md+```++### Skills+```bash+# 个人 skills+cp -r 03-skills/code-review ~/.claude/skills/++# 项目 skills+cp -r 03-skills/code-review .claude/skills/+```++### Subagents+```bash+# 安装全部+cp 04-subagents/*.md .claude/agents/++# 安装单个+cp 04-subagents/code-reviewer.md .claude/agents/+```++### MCP+```bash+# 设置凭据+export GITHUB_TOKEN="your_token"+export DATABASE_URL="postgresql://..."++# 安装配置(项目级)+cp 05-mcp/github-mcp.json .mcp.json++# 或者用户级:添加到 ~/.claude.json+```++### Hooks+```bash+# 安装 hooks+mkdir -p ~/.claude/hooks+cp 06-hooks/*.sh ~/.claude/hooks/+chmod +x ~/.claude/hooks/*.sh++# 在 settings 中配置(~/.claude/settings.json)+```++### Plugins+```bash+# 从示例安装(如果已发布)+/plugin install pr-review+/plugin install devops-automation+/plugin install documentation+```++### Checkpoints+```bash+# 每次用户提示后都会自动创建 checkpoint+# 回退:按两次 Esc 或使用:+/rewind++# 然后选择:恢复代码和对话、恢复对话、+# 恢复代码、从这里开始总结,或算了+```++### Advanced Features+```bash+# 在 settings 中配置(.claude/settings.json)+# 参见 09-advanced-features/config-examples.json++# planning mode+/plan 任务描述++# 权限模式(使用 --permission-mode 参数)+# default - 风险操作需要审批+# acceptEdits - 自动接受文件编辑,其他操作仍需审批+# plan - 只读分析,不做修改+# dontAsk - 除危险操作外全部接受+# auto - 后台分类器自动决定权限+# bypassPermissions - 全部接受(需要 --dangerously-skip-permissions)++# 会话管理+/resume # 恢复之前的对话+/rename "name" # 命名当前会话+/fork # 分叉当前会话+claude -c # 继续最近的对话+claude -r "session" # 按名称/ID 恢复会话+```++---++## 📋 功能速览++| 功能 | 安装路径 | 用法 |+|------|----------|------|+| **Slash Commands(55+)** | `.claude/commands/*.md` | `/command-name` |+| **Memory** | `./CLAUDE.md` | 自动加载 |+| **Skills** | `.claude/skills/*/SKILL.md` | 自动触发 |+| **Subagents** | `.claude/agents/*.md` | 自动委派 |+| **MCP** | `.mcp.json`(项目)或 `~/.claude.json`(用户) | `/mcp__server__action` |+| **Hooks(25 个事件)** | `~/.claude/hooks/*.sh` | 事件触发(4 类) |+| **Plugins** | 通过 `/plugin install` | 打包所有能力 |+| **Checkpoints** | 内置 | `Esc+Esc` 或 `/rewind` |+| **Planning Mode** | 内置 | `/plan <task>` |+| **Permission Modes(6 种)** | 内置 | `--allowedTools`、`--permission-mode` |+| **Sessions** | 内置 | `/session <command>` |+| **Background Tasks** | 内置 | 在后台运行 |+| **Remote Control** | 内置 | WebSocket API |+| **Web Sessions** | 内置 | `claude web` |+| **Git Worktrees** | 内置 | `/worktree` |+| **Auto Memory** | 内置 | 自动保存到 `CLAUDE.md` |+| **Task List** | 内置 | `/task list` |+| **Bundled Skills(5 个)** | 内置 | `/simplify`、`/loop`、`/claude-api`、`/voice`、`/browse` |++---++## 🎯 常见使用场景++### 代码审查+```bash+# 方法 1:slash command+cp 01-slash-commands/optimize.md .claude/commands/+# 使用:/optimize++# 方法 2:subagent+cp 04-subagents/code-reviewer.md .claude/agents/+# 使用:自动委派++# 方法 3:skill+cp -r 03-skills/code-review ~/.claude/skills/+# 使用:自动触发++# 方法 4:插件(推荐)+/plugin install pr-review+# 使用:/review-pr+```++### 文档+```bash+# slash command+cp 01-slash-commands/generate-api-docs.md .claude/commands/++# subagent+cp 04-subagents/documentation-writer.md .claude/agents/++# skill+cp -r 03-skills/doc-generator ~/.claude/skills/++# 插件(完整方案)+/plugin install documentation+```++### DevOps+```bash+# 完整插件+/plugin install devops-automation++# 命令:/deploy、/rollback、/status、/incident+```++### 团队规范+```bash+# 项目 memory+cp 02-memory/project-CLAUDE.md ./CLAUDE.md++# 按你的团队规范编辑+vim CLAUDE.md+```++### 自动化与 Hooks+```bash+# 安装 hooks(25 个事件,4 类:command、http、prompt、agent)+mkdir -p ~/.claude/hooks+cp 06-hooks/*.sh ~/.claude/hooks/+chmod +x ~/.claude/hooks/*.sh++# 示例:+# - 提交前测试:pre-commit.sh+# - 自动格式化代码:format-code.sh+# - 安全扫描:security-scan.sh++# 用 Auto Mode 实现全自动工作流+claude --enable-auto-mode -p "重构并测试 auth 模块"+# 或者用 Shift+Tab 在模式间切换+```++### 安全重构+```bash+# 每次提示前都会自动创建 checkpoint+# 试着重构+# 如果成功:继续+# 如果失败:按 Esc+Esc 或使用 /rewind 返回+```++### 复杂实现+```bash+# 使用 planning mode+/plan 实现用户认证系统++# Claude 会创建详细计划+# 你可以审阅并批准+# Claude 会系统化地执行实现+```++### CI/CD 集成+```bash+# 以 headless 模式运行(非交互)+claude -p "运行所有测试并生成报告"++# 在 CI 中搭配权限模式+claude -p "运行测试" --permission-mode dontAsk++# 使用 Auto Mode 实现完全自治的 CI 任务+claude --enable-auto-mode -p "运行测试并修复失败项"++# 结合 hooks 做自动化+# 参见 09-advanced-features/README.md+```++### 学习与实验+```bash+# 用 plan mode 做安全分析+claude --permission-mode plan++# 安全实验 - checkpoint 会自动创建+# 如果需要回退:按 Esc+Esc 或使用 /rewind+```++### Agent 团队+```bash+# 启用 agent 团队+export CLAUDE_AGENT_TEAMS=1++# 或者在 settings.json 中+{ "agentTeams": { "enabled": true } }++# 用这句话开始:"使用团队方式实现功能 X"+```++### 定时任务+```bash+# 每 5 分钟运行一次命令+/loop 5m /check-status++# 一次性提醒+/loop 30m "提醒我检查部署"+```++---++## 📁 文件位置参考++```text+Your Project/+├── .claude/+│ ├── commands/ # Slash commands 放这里+│ ├── agents/ # Subagents 放这里+│ ├── skills/ # 项目 skills 放这里+│ └── settings.json # 项目设置(hooks 等)+├── .mcp.json # MCP 配置(项目级)+├── CLAUDE.md # 项目 memory+└── src/+ └── api/+ └── CLAUDE.md # 目录级 memory++User Home/+├── .claude/+│ ├── commands/ # 个人命令+│ ├── agents/ # 个人 agents+│ ├── skills/ # 个人 skills+│ ├── hooks/ # hook 脚本+│ ├── settings.json # 用户设置+│ ├── managed-settings.d/ # 托管设置(企业/组织)+│ └── CLAUDE.md # 个人 memory+└── .claude.json # 个人 MCP 配置(用户级)+```++---++## 🔍 查找示例++### 按分类+- **Slash Commands**:`01-slash-commands/`+- **Memory**:`02-memory/`+- **Skills**:`03-skills/`+- **Subagents**:`04-subagents/`+- **MCP**:`05-mcp/`+- **Hooks**:`06-hooks/`+- **Plugins**:`07-plugins/`+- **Checkpoints**:`08-checkpoints/`+- **Advanced Features**:`09-advanced-features/`+- **CLI**:`10-cli/`++### 按使用场景+- **性能**:`01-slash-commands/optimize.md`+- **安全**:`04-subagents/secure-reviewer.md`+- **测试**:`04-subagents/test-engineer.md`+- **文档**:`03-skills/doc-generator/`+- **DevOps**:`07-plugins/devops-automation/`++### 按复杂度+- **简单**:Slash commands+- **中等**:Subagents、Memory+- **高级**:Skills、Hooks+- **完整**:Plugins++---++## 🎓 学习路径++### 第 1 天+```bash+# 阅读总览+cat README.md++# 安装一个命令+cp 01-slash-commands/optimize.md .claude/commands/++# 试用+/optimize+```++### 第 2-3 天+```bash+# 设置 memory+cp 02-memory/project-CLAUDE.md ./CLAUDE.md+vim CLAUDE.md++# 安装 subagent+cp 04-subagents/code-reviewer.md .claude/agents/+```++### 第 4-5 天+```bash+# 设置 MCP+export GITHUB_TOKEN="your_token"+cp 05-mcp/github-mcp.json .mcp.json++# 试用 MCP 命令+/mcp__github__list_prs+```++### 第 2 周+```bash+# 安装 skill+cp -r 03-skills/code-review ~/.claude/skills/++# 让它自动触发+# 直接说:“Review this code for issues”+```++### 第 3 周及以后+```bash+# 安装完整插件+/plugin install pr-review++# 使用打包功能+/review-pr+/check-security+/check-tests+```++---++## 🆕 新功能(2026 年 3 月)++| 功能 | 说明 | 用法 |+|------|------|------|+| **Auto Mode** | 通过后台分类器实现完全自治 | `--enable-auto-mode` 参数,`Shift+Tab` 切换模式 |+| **Channels** | Discord 和 Telegram 集成 | `--channels` 参数,Discord / Telegram bot |+| **Voice Dictation** | 对 Claude 说出命令和上下文 | `/voice` 命令 |+| **Hooks(25 个事件)** | 扩展后的 hook 系统,包含 4 类 | command、http、prompt、agent hook 类型 |+| **MCP Elicitation** | MCP server 可在运行时请求用户输入 | 当 server 需要澄清时自动提示 |+| **WebSocket MCP** | MCP 的 WebSocket 传输 | 在 `.mcp.json` 中配置 `ws://` URL |+| **Plugin LSP** | 插件支持 Language Server Protocol | `userConfig`、`${CLAUDE_PLUGIN_DATA}` 变量 |+| **Remote Control** | 通过 WebSocket API 控制 Claude Code | `claude --remote` 用于外部集成 |+| **Web Sessions** | 基于浏览器的 Claude Code 接口 | 使用 `claude web` 打开 |+| **Desktop App** | 原生桌面应用 | 从 claude.ai/download 下载 |+| **Task List** | 管理后台任务 | `/task list`、`/task status <id>` |+| **Auto Memory** | 从对话中自动保存记忆 | Claude 会自动保存关键上下文到 `CLAUDE.md` |+| **Git Worktrees** | 用于并行开发的隔离工作区 | 使用 `/worktree` 创建隔离空间 |+| **Model Selection** | 在 Sonnet 4.6 和 Opus 4.6 之间切换 | `/model` 或 `--model` 参数 |+| **Agent Teams** | 协调多个 agent 执行任务 | 通过环境变量 `CLAUDE_AGENT_TEAMS=1` 启用 |+| **Scheduled Tasks** | 使用 `/loop` 运行周期任务 | `/loop 5m /command` 或 CronCreate 工具 |+| **Chrome Integration** | 浏览器自动化 | `--chrome` 参数或 `/chrome` 命令 |+| **Keyboard Customization** | 自定义按键绑定 | `/keybindings` 命令 |++---++## 💡 小技巧++### 自定义+- 先原样使用示例+- 再按需求修改+- 分享给团队前先测试+- 对配置做版本控制++### 最佳实践+- 用 memory 保存团队规范+- 用 plugins 做完整工作流+- 用 subagents 处理复杂任务+- 用 slash commands 处理快速任务++### 故障排查+```bash+# 检查文件位置+ls -la .claude/commands/+ls -la .claude/agents/++# 验证 YAML 语法+head -20 .claude/agents/code-reviewer.md++# 测试 MCP 连接+echo $GITHUB_TOKEN+```++---++## 📊 功能矩阵++| 需求 | 用这个 | 示例 |+|------|--------|------|+| 快速快捷操作 | Slash Command(55+) | `01-slash-commands/optimize.md` |+| 团队规范 | Memory | `02-memory/project-CLAUDE.md` |+| 自动化工作流 | Skill | `03-skills/code-review/` |+| 专门任务 | Subagent | `04-subagents/code-reviewer.md` |+| 外部数据 | MCP(+ Elicitation、WebSocket) | `05-mcp/github-mcp.json` |+| 事件自动化 | Hook(25 个事件、4 类) | `06-hooks/pre-commit.sh` |+| 完整方案 | Plugin(+ LSP 支持) | `07-plugins/pr-review/` |+| 安全实验 | Checkpoint | `08-checkpoints/checkpoint-examples.md` |+| 完全自治 | Auto Mode | `--enable-auto-mode` 或 `Shift+Tab` |+| 聊天集成 | Channels | `--channels`(Discord、Telegram) |+| CI/CD 流水线 | CLI | `10-cli/README.md` |++---++## 🔗 快速链接++- **主指南**:`README.md`+- **完整索引**:`INDEX.md`+- **速查卡**:`QUICK_REFERENCE.md`+- **原始指南**:`claude_concepts_guide.md`++---++## 📞 常见问题++**问:我应该先用哪个?**+答:先从 slash commands 开始,按需逐步添加功能。++**问:我可以混用多个功能吗?**+答:可以!它们可以一起工作。Memory + Commands + MCP 很强大。++**问:怎么分享给团队?**+答:把 `.claude/` 目录提交到 git。++**问:敏感信息怎么办?**+答:用环境变量,不要硬编码。++**问:我可以改这些示例吗?**+答:当然可以!它们本来就是可定制的模板。++---++## ✅ 检查清单++入门清单:++- [ ] 阅读 `README.md`+- [ ] 安装 1 个 slash command+- [ ] 试用该命令+- [ ] 创建项目 `CLAUDE.md`+- [ ] 安装 1 个 subagent+- [ ] 配置 1 个 MCP 集成+- [ ] 安装 1 个 skill+- [ ] 试用一个完整插件+- [ ] 按你的需求定制+- [ ] 与团队共享++---++**快速开始**:`cat README.md`++**完整索引**:`cat INDEX.md`++**这张卡片**:建议随手保留,方便快速查阅!diff --git a/zh/README.md b/zh/README.mdnew file mode 100644index 0000000..4406b7d--- /dev/null+++ b/zh/README.md@@ -0,0 +1,881 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">+</picture>++<p align="center">+ <a href="https://github.com/trending">+ <img src="https://img.shields.io/badge/GitHub-🔥%20%231%20Trending-purple?style=for-the-badge&logo=github"/>+ </a>+</p>++[](https://github.com/luongnv89/claude-howto/stargazers)+[](https://github.com/luongnv89/claude-howto/network/members)+[](LICENSE)+[](CHANGELOG.md)+[](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 月)+- **社区驱动**,贡献者会分享他们在真实工作中的配置和经验++[](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.5diff --git a/zh/RELEASE_NOTES.md b/zh/RELEASE_NOTES.mdnew file mode 100644index 0000000..e3cae71--- /dev/null+++ b/zh/RELEASE_NOTES.md@@ -0,0 +1,8 @@+## v2.2.0 - 2026-03-26++### Bug 修复++- 移除失效的 marketplace 链接,修复 CI 链接检查失败问题(3fdf0d6)+- 将 `sandboxed` 和 `pycache` 加入 cSpell 词典(dc64618)++**完整变更日志**: https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1diff --git a/zh/SECURITY.md b/zh/SECURITY.mdnew file mode 100644index 0000000..6055a82--- /dev/null+++ b/zh/SECURITY.md@@ -0,0 +1,334 @@+# 安全政策++## 概述++Claude How To 项目的安全对我们非常重要。本文档说明我们的安全实践,以及如何负责任地报告安全漏洞。++## 支持的版本++我们为以下版本提供安全更新:++| 版本 | 状态 | 支持至 |+|---------|--------|---------------|+| 最新版(main) | ✅ 活跃 | 当前版本 + 6 个月 |+| 1.x 发布版 | ✅ 活跃 | 直到下一个大版本 |++**注意**:作为一个教育指南项目,我们更关注维护当前最佳实践和文档安全,而不是传统意义上的版本支持。更新会直接应用到 main 分支。++## 安全实践++### 代码安全++1. **依赖管理**+ - 所有 Python 依赖都固定在 `requirements.txt` 中+ - 通过 dependabot 和人工审查进行定期更新+ - 每次提交都会运行 Bandit 安全扫描+ - 使用 pre-commit hooks 做安全检查++2. **代码质量**+ - 使用 Ruff 做 lint,能捕获常见问题+ - 使用 mypy 做类型检查,避免类型相关漏洞+ - 通过 pre-commit hooks 强制执行标准+ - 所有更改在合并前都要审查++3. **访问控制**+ - 对 `main` 分支启用分支保护+ - 合并前需要审查通过+ - 状态检查必须通过后才能合并+ - 仓库写权限受限++### 文档安全++1. **示例中不放密钥**+ - 所有示例中的 API key 都使用占位符+ - 从不硬编码凭据+ - `.env.example` 文件会展示所需变量+ - 明确提示密钥管理风险++2. **安全最佳实践**+ - 示例会展示安全模式+ - 文档中会突出安全警告+ - 链接到官方安全指南+ - 在相关章节中说明凭据处理方式++3. **内容审查**+ - 所有文档都会审查安全问题+ - 贡献指南中包含安全注意事项+ - 会验证外部链接和引用++### 依赖安全++1. **扫描**+ - Bandit 会扫描所有 Python 代码中的漏洞+ - 通过 GitHub 安全警报检查依赖漏洞+ - 定期进行人工安全审计++2. **更新**+ - 安全补丁会尽快应用+ - 大版本会谨慎评估+ - 更新日志会包含安全相关变更++3. **透明度**+ - 安全更新会记录在提交中+ - 漏洞披露会负责任地处理+ - 在适当情况下发布公开安全公告++## 漏洞报告++### 我们关注的安全问题++我们欢迎以下报告:+- **代码漏洞**:脚本或示例中的漏洞+- **依赖漏洞**:Python 包中的漏洞+- **加密问题**:任何代码示例中的密码学问题+- **认证/授权缺陷**:文档中的认证或授权问题+- **数据暴露风险**:配置示例中的数据泄露风险+- **注入漏洞**:SQL、命令等注入+- **SSRF / XXE / 路径穿越** 问题++### 不在范围内的安全问题++以下问题不在本项目范围内:+- Claude Code 本身的漏洞(请向 Anthropic 报告)+- 外部服务或库的问题(请向上游项目报告)+- 社会工程学或用户教育问题(与本指南无关)+- 没有 PoC 的理论漏洞+- 依赖库中已通过官方渠道报告的漏洞++## 如何报告++### 私密报告(推荐)++**如遇敏感安全问题,请使用 GitHub 的私密漏洞报告:**++1. 访问:<https://github.com/luongnv89/claude-howto/security/advisories>+2. 点击 “Report a vulnerability”+3. 填写漏洞细节+4. 请包含:+ - 漏洞的清晰描述+ - 受影响的组件(文件、章节、示例)+ - 潜在影响+ - 复现步骤(如适用)+ - 建议修复方式(如果你有)++**接下来会发生什么:**+- 我们会在 48 小时内确认收到+- 我们会调查并评估严重性+- 我们会与你一起修复+- 我们会协调披露时间线+- 如你愿意,我们会在安全公告中致谢++### 公开报告++对于不敏感或已公开的问题:++1. **创建 GitHub Issue** 并打上 `security` 标签+2. 包含:+ - 标题:以 `[SECURITY]` 开头并附简短说明+ - 详细描述+ - 受影响的文件或章节+ - 潜在影响+ - 建议修复方式++## 漏洞响应流程++### 评估(24 小时内)++1. 我们确认收到报告+2. 我们使用 [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) 评估严重性+3. 我们判断是否在范围内+4. 我们向你反馈初步评估++### 开发(1-7 天)++1. 我们开发修复+2. 我们审查并测试修复+3. 我们创建安全公告+4. 我们准备发布说明++### 披露(取决于严重性)++**严重(CVSS 9.0-10.0)**+- 立即发布修复+- 发布公开公告+- 提前 24 小时通知报告者++**高危(CVSS 7.0-8.9)**+- 48-72 小时内发布修复+- 提前 5 天通知报告者+- 发布时公开公告++**中危(CVSS 4.0-6.9)**+- 在下一次常规更新中修复+- 发布时公开公告++**低危(CVSS 0.1-3.9)**+- 在下一次常规更新中修复+- 发布时附带公告++### 公布++我们发布的安全公告会包含:+- 漏洞描述+- 受影响组件+- 严重性评估(CVSS 分数)+- 修复版本+- 临时缓解方案(如适用)+- 对报告者的致谢(如获许可)++## 报告者最佳实践++### 报告前++- **确认问题**:你能稳定复现吗?+- **搜索已有 issue**:是否已经有人报告?+- **查看文档**:是否已有安全使用说明?+- **测试修复**:你建议的修复是否有效?++### 报告时++- **尽量具体**:提供准确的文件路径和行号+- **补充上下文**:为什么这是安全问题?+- **说明影响**:攻击者可能做什么?+- **提供步骤**:如何复现?+- **提出修复建议**:你会怎么修?++### 报告后++- **保持耐心**:我们的资源有限+- **积极响应**:尽快回答后续问题+- **保持保密**:在修复前不要公开披露+- **尊重协调流程**:按时间线推进披露++## 安全头与配置++### 仓库安全++- **分支保护**:主分支需要 2 份批准+- **状态检查**:所有 CI/CD 检查必须通过+- **CODEOWNERS**:关键文件有指定审查者+- **签名提交**:建议贡献者使用++### 开发安全++```bash+# 安装 pre-commit hooks+pre-commit install++# 本地运行安全扫描+bandit -c pyproject.toml -r scripts/+mypy scripts/ --ignore-missing-imports+ruff check scripts/+```++### 依赖安全++```bash+# 检查已知漏洞+pip install safety+safety check++# 或使用 pip-audit+pip install pip-audit+pip-audit+```++## 贡献者安全指南++### 编写示例时++1. **永远不要硬编码密钥**+ ```python+ # ❌ 不好+ api_key = "sk-1234567890"++ # ✅ 更好+ api_key = os.getenv("API_KEY")+ ```++2. **提醒安全影响**+ ```markdown+ ⚠️ **安全提示**:切勿把 `.env` 文件提交到 git。+ 请立即加入 `.gitignore`。+ ```++3. **使用安全默认值**+ - 默认启用认证+ - 在适用场景中使用 HTTPS+ - 校验并清理输入+ - 使用参数化查询++4. **记录安全注意事项**+ - 解释为什么安全很重要+ - 展示安全与不安全的写法+ - 链接权威来源+ - 明显展示警告++### 审查贡献时++1. **检查是否泄露秘密**+ - 扫描常见模式(api_key=、password= 等)+ - 审查配置文件+ - 检查环境变量使用情况++2. **验证安全编码实践**+ - 没有硬编码凭据+ - 正确的输入验证+ - 安全的认证/授权+ - 安全的文件处理++3. **测试安全影响**+ - 这会不会被滥用?+ - 最坏情况是什么?+ - 有没有边界情况?++## 安全资源++### 官方标准+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)+- [CWE Top 25](https://cwe.mitre.org/top25/)+- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1)++### Python 安全+- [Python Security Advisories](https://www.python.org/dev/security/)+- [PyPI Security](https://pypi.org/help/#security)+- [Bandit Documentation](https://bandit.readthedocs.io/)++### 依赖管理+- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/)+- [GitHub Security Alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts)++### 通用安全+- [Anthropic Security](https://www.anthropic.com/)+- [GitHub Security Best Practices](https://docs.github.com/en/code-security)++## 安全公告存档++过往安全公告可在 GitHub 的 [Security Advisories](https://github.com/luongnv89/claude-howto/security/advisories) 标签页查看。++## 联系方式++如需咨询安全相关问题或讨论安全实践:++1. **私密安全报告**:使用 GitHub 的私密漏洞报告+2. **一般安全问题**:使用 `[SECURITY]` 标签发起 discussion+3. **安全政策反馈**:创建带 `security` 标签的 issue++## 致谢++感谢帮助本项目保持安全的安全研究者和社区成员。负责任地报告漏洞的贡献者会在我们的安全公告中获得致谢(除非你希望匿名)。++## 政策更新++本安全政策会在以下情况更新:+- 发现新漏洞时+- 安全最佳实践演进时+- 项目范围发生变化时+- 至少每年一次++**最后更新**:2026 年 1 月+**下次审查**:2027 年 1 月++---++感谢你帮助 Claude How To 保持安全!🔒diff --git a/zh/STYLE_GUIDE.md b/zh/STYLE_GUIDE.mdnew file mode 100644index 0000000..8086282--- /dev/null+++ b/zh/STYLE_GUIDE.md@@ -0,0 +1,630 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">+</picture>++# 风格指南++> 为 Claude How To 贡献内容时遵循的约定和格式规则。请按照这份指南保持内容一致、专业且易于维护。++---++## 目录++- [文件与文件夹命名](#文件与文件夹命名)+- [文档结构](#文档结构)+- [标题](#标题)+- [文本格式](#文本格式)+- [列表](#列表)+- [表格](#表格)+- [代码块](#代码块)+- [链接与交叉引用](#链接与交叉引用)+- [图表](#图表)+- [Emoji 用法](#emoji-用法)+- [YAML Frontmatter](#yaml-frontmatter)+- [图片与媒体](#图片与媒体)+- [语气与文风](#语气与文风)+- [提交信息](#提交信息)+- [作者检查清单](#作者检查清单)++---++## 文件与文件夹命名++### 课程文件夹++课程文件夹使用一个 **两位数字前缀**,后接一个 **kebab-case** 描述符:++```+01-slash-commands/+02-memory/+03-skills/+04-subagents/+05-mcp/+```++这个数字反映了学习路径的顺序,从初学者到高级。++### 文件名++| 类型 | 约定 | 示例 |+|------|-----------|----------|+| **课程 README** | `README.md` | `01-slash-commands/README.md` |+| **功能文件** | kebab-case `.md` | `code-reviewer.md`, `generate-api-docs.md` |+| **Shell 脚本** | kebab-case `.sh` | `format-code.sh`, `validate-input.sh` |+| **配置文件** | 标准名称 | `.mcp.json`, `settings.json` |+| **记忆文件** | 带作用域前缀 | `project-CLAUDE.md`, `personal-CLAUDE.md` |+| **顶层文档** | UPPER_CASE `.md` | `CATALOG.md`, `QUICK_REFERENCE.md`, `CONTRIBUTING.md` |+| **图片资源** | kebab-case | `pr-slash-command.png`, `claude-howto-logo.svg` |++### 规则++- 除顶层文档外,所有文件和文件夹名都使用 **小写**+- 使用连字符(`-`)作为单词分隔符,永远不要使用下划线或空格+- 名称要具体,但保持简洁++---++## 文档结构++### 根 README++根目录 `README.md` 的顺序如下:++1. Logo(使用带深色/浅色变体的 `<picture>` 元素)+2. H1 标题+3. 引导性引用块(一句话价值主张)+4. “为什么需要这份指南?”部分,以及对比表+5. 分隔线(`---`)+6. 目录+7. 功能目录+8. 快速导航+9. 学习路径+10. 功能章节+11. 快速上手+12. 最佳实践 / 故障排查+13. 参与贡献 / 许可证++### 课程 README++每个课程 `README.md` 的顺序如下:++1. H1 标题,例如 `# Slash Commands`+2. 简短概述段落+3. 快速参考表格(可选)+4. 架构图(Mermaid)+5. 详细章节(H2)+6. 实用示例(编号列表,4-6 个示例)+7. 最佳实践(Do's 和 Don'ts 表)+8. 故障排查+9. 相关指南 / 官方文档+10. 文档元数据页脚++### 功能/示例文件++单个功能文件,例如 `optimize.md`、`pr.md`:++1. YAML frontmatter(如果适用)+2. H1 标题+3. 目的 / 描述+4. 使用说明+5. 代码示例+6. 自定义提示++### 分隔线++使用水平分隔线(`---`)来分隔文档中的主要区域:++```markdown+---++## New Major Section+```++将它们放在引导性引用块之后,以及文档中逻辑上不同的部分之间。++---++## 标题++### 层级++| 级别 | 用途 | 示例 |+|-------|-----|---------|+| `#` H1 | 页面标题,每个文档一个 | `# Slash Commands` |+| `##` H2 | 主要章节 | `## Best Practices` |+| `###` H3 | 子章节 | `### Adding a Skill` |+| `####` H4 | 再下一级子章节,较少使用 | `#### Configuration Options` |++### 规则++- **每个文档只允许一个 H1**,即页面标题+- **不要跳级**,不要从 H2 直接跳到 H4+- **标题要简洁**,尽量控制在 2-5 个词+- **使用句首大写**,只大写首字和专有名词(例外:功能名保持原样)+- **只有根 README 的章节标题** 可以使用 Emoji 前缀,见 [Emoji 用法](#emoji-用法)++---++## 文本格式++### 强调++| 样式 | 使用时机 | 示例 |+|-------|------------|---------|+| **粗体** (`**text**`) | 关键术语、表格标签、重要概念 | `**Installation**:` |+| *斜体* (`*text*`) | 技术术语首次出现、书名或文档名 | `*frontmatter*` |+| `Code` (`` `text` ``) | 文件名、命令、配置值、代码引用 | `` `CLAUDE.md` `` |++### 使用引述块做提示++对重要说明使用带粗体前缀的引述块:++```markdown+> **Note**: Custom slash commands have been merged into skills since v2.0.++> **Important**: Never commit API keys or credentials.++> **Tip**: Combine memory with skills for maximum effectiveness.+```++支持的提示类型:**Note**、**Important**、**Tip**、**Warning**。++### 段落++- 保持段落简短,2-4 句为宜+- 段落之间留一个空行+- 先说重点,再补充上下文+- 解释“为什么”,不只是“是什么”++---++## 列表++### 无序列表++使用短横线(`-`),嵌套时使用 2 个空格缩进:++```markdown+- First item+- Second item+ - Nested item+ - Another nested item+ - Deep nested (avoid going deeper than 3 levels)+- Third item+```++### 有序列表++用于顺序步骤、操作说明和排序项:++```markdown+1. First step+2. Second step+ - Sub-point detail+ - Another sub-point+3. Third step+```++### 说明性列表++对键值对风格的列表,使用粗体标签:++```markdown+- **Performance bottlenecks** - identify O(n^2) operations, inefficient loops+- **Memory leaks** - find unreleased resources, circular references+- **Algorithm improvements** - suggest better algorithms or data structures+```++### 规则++- 保持一致的缩进,每层 2 个空格+- 列表前后都要空一行+- 列表项结构要平行一致,例如都用动词开头,或者都用名词开头+- 嵌套深度不要超过 3 层++---++## 表格++### 标准格式++```markdown+| Column 1 | Column 2 | Column 3 |+|----------|----------|----------|+| Data | Data | Data |+```++### 常见表格模式++**功能对比(3-4 列):**++```markdown+| Feature | Invocation | Persistence | Best For |+|---------|-----------|------------|----------|+| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts |+| **Memory** | Auto-loaded | Cross-session | Long-term learning |+```++**Do's and Don'ts:**++```markdown+| Do | Don't |+|----|-------|+| Use descriptive names | Use vague names |+| Keep files focused | Overload a single file |+```++**快速参考:**++```markdown+| Aspect | Details |+|--------|---------|+| **Purpose** | Generate API documentation |+| **Scope** | Project-level |+| **Complexity** | Intermediate |+```++### 规则++- 当表头是行标签时,**表头要加粗**+- 代码源文件中的管道符尽量对齐,便于阅读(可选但推荐)+- 单元格内容要简洁;细节用链接展开+- 命令和文件路径在单元格中要使用 `代码格式`++---++## 代码块++### 语言标签++始终为语法高亮指定语言标签:++| 语言 | 标签 | 用途 |+|----------|-----|---------|+| Shell | `bash` | CLI 命令、脚本 |+| Python | `python` | Python 代码 |+| JavaScript | `javascript` | JS 代码 |+| TypeScript | `typescript` | TS 代码 |+| JSON | `json` | 配置文件 |+| YAML | `yaml` | Frontmatter、配置 |+| Markdown | `markdown` | Markdown 示例 |+| SQL | `sql` | 数据库查询 |+| Plain text | (no tag) | 期望输出、目录树 |++### 约定++```bash+# Comment explaining what the command does+claude mcp add notion --transport http https://mcp.notion.com/mcp+```++- 在不明显的命令前添加一行 **注释**+- 所有示例都要做到 **可直接复制粘贴**+- 相关时同时提供 **简单版和高级版**+- 需要时要给出 **期望输出**,这时使用不带标签的代码块++### 安装示例++安装说明请使用以下模式:++```bash+# Copy files to your project+cp 01-slash-commands/*.md .claude/commands/+```++### 多步骤工作流++```bash+# Step 1: Create the directory+mkdir -p .claude/commands++# Step 2: Copy the templates+cp 01-slash-commands/*.md .claude/commands/++# Step 3: Verify installation+ls .claude/commands/+```++---++## 链接与交叉引用++### 内部链接(相对路径)++内部链接全部使用相对路径:++```markdown+[Slash Commands](01-slash-commands/README.md)+[Skills Guide](03-skills/README.md)+[Memory Architecture](02-memory/README.md)+```++从课程文件夹返回根目录或兄弟目录:++```markdown+[返回主指南](README.md)+[相关:Skills](03-skills/README.md)+```++### 外部链接(绝对路径)++使用完整 URL,并使用具有描述性的锚文本:++```markdown+[Anthropic's official documentation](https://code.claude.com/docs/en/overview)+```++- 不要使用“click here”或“this link”作为锚文本+- 使用脱离上下文也能理解的描述性文字++### 章节锚点++链接到同一文档中的章节时,使用 GitHub 风格锚点:++```markdown+[文件与文件夹命名](#文件与文件夹命名)+[作者检查清单](#作者检查清单)+```++### 相关指南模式++课程末尾要附上相关指南章节:++```markdown+## Related Guides++- [Slash Commands](01-slash-commands/README.md) - 快速快捷命令+- [Memory](02-memory/README.md) - 持久上下文+- [Skills](03-skills/README.md) - 可复用能力+```++---++## 图表++### Mermaid++所有图表都使用 Mermaid。支持的类型包括:++- `graph TB` / `graph LR` - 架构、层级、流程+- `sequenceDiagram` - 交互流程+- `timeline` - 时间顺序++### 样式约定++使用 style block 保持颜色一致:++```mermaid+graph TB+ A["Component A"] --> B["Component B"]+ B --> C["Component C"]++ style A fill:#e1f5fe,stroke:#333,color:#333+ style B fill:#fce4ec,stroke:#333,color:#333+ style C fill:#e8f5e9,stroke:#333,color:#333+```++**颜色调色板:**++| Color | Hex | Use For |+|-------|-----|---------|+| Light blue | `#e1f5fe` | Primary components, inputs |+| Light pink | `#fce4ec` | Processing, middleware |+| Light green | `#e8f5e9` | Outputs, results |+| Light yellow | `#fff9c4` | Configuration, optional |+| Light purple | `#f3e5f5` | User-facing, UI |++### 规则++- 节点标签使用 `["Label text"]`,这样可以包含特殊字符+- 在标签中换行使用 `<br/>`+- 图表保持简洁,最多 10-12 个节点+- 图表下方添加简短文字说明,方便无障碍阅读+- 层级结构使用自上而下(`TB`),流程使用左右(`LR`)++---++## Emoji 用法++### Emoji 的使用场景++Emoji 使用要 **克制且有目的**,只在特定场景中出现:++| 场景 | Emoji | 示例 |+|---------|--------|---------|+| Root README 章节标题 | 分类图标 | `## 📚 Learning Path` |+| Skill 等级指示 | 彩色圆点 | 🟢 Beginner, 🔵 Intermediate, 🔴 Advanced |+| Do's 和 Don'ts | 对勾/叉号 | ✅ Do this, ❌ Don't do this |+| 复杂度评级 | 星星 | ⭐⭐⭐ |++### 标准 Emoji 集合++| Emoji | 含义 |+|-------|---------|+| 📚 | 学习、指南、文档 |+| ⚡ | 快速上手、速查 |+| 🎯 | 功能、速查 |+| 🎓 | 学习路径 |+| 📊 | 统计、对比 |+| 🚀 | 安装、快速命令 |+| 🟢 | 初学者级别 |+| 🔵 | 中级别 |+| 🔴 | 高级别 |+| ✅ | 推荐做法 |+| ❌ | 避免 / 反模式 |+| ⭐ | 复杂度评级单位 |++### 规则++- **不要在正文或段落中使用 Emoji**+- **只在根 README 的标题中使用 Emoji**,不要在课程 README 中使用+- **不要添加装饰性 Emoji**,每个 Emoji 都应该有意义+- Emoji 的使用要与上表保持一致++---++## YAML Frontmatter++### 功能文件(Skills、Commands、Agents)++```yaml+---+name: unique-identifier+description: What this feature does and when to use it+allowed-tools: Bash, Read, Grep+---+```++### 可选字段++```yaml+---+name: my-feature+description: Brief description+argument-hint: "[file-path] [options]"+allowed-tools: Bash, Read, Grep, Write, Edit+model: opus # opus, sonnet, or haiku+disable-model-invocation: true # User-only invocation+user-invocable: false # Hidden from user menu+context: fork # Run in isolated subagent+agent: Explore # Agent type for context: fork+---+```++### 规则++- Frontmatter 放在文件最顶部+- `name` 字段使用 **kebab-case**+- `description` 保持为一句话+- 只包含真正需要的字段++---++## 图片与媒体++### Logo 模式++所有以 Logo 开头的文档都使用 `<picture>` 元素,以支持深色/浅色模式:++```html+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">+</picture>+```++### 截图++- 存放在对应课程文件夹中,例如 `01-slash-commands/pr-slash-command.png`+- 使用 kebab-case 文件名+- 包含描述性的 alt 文本+- 图表优先使用 SVG,截图优先使用 PNG++### 规则++- 图片始终要有 alt 文本+- 控制图片文件大小,PNG 尽量小于 500KB+- 图片引用使用相对路径+- 图片存放在引用它的文档同目录,或者放在 `assets/` 里供共享使用++---++## 语气与文风++### 写作风格++- **专业但亲切** - 技术准确,同时不过度堆砌术语+- **主动语态** - 说“Create a file”,不要说“一个文件应该被创建”+- **直接指令** - 说“Run this command”,不要说“你也许可以运行这个命令”+- **适合初学者** - 假设读者是 Claude Code 新手,但不是编程新手++### 内容原则++| 原则 | 示例 |+|-----------|---------|+| **Show, don't tell** | 提供可运行示例,而不是抽象描述 |+| **渐进式复杂度** | 先简单,后面再增加深度 |+| **解释“为什么”** | “Use memory for... because...” 而不只是 “Use memory for...” |+| **可直接复制粘贴** | 每个代码块都应能直接粘贴使用 |+| **真实场景** | 使用实际场景,而不是牵强的例子 |++### 词汇++- 使用 “Claude Code”(不要写 “Claude CLI” 或 “the tool”)+- 使用 “skill”(不要写 “custom command”,这是旧术语)+- 使用 “lesson” 或 “guide” 来称呼编号章节+- 使用 “example” 来称呼单个功能文件++---++## 提交信息++遵循 [Conventional Commits](https://www.conventionalcommits.org/):++```+type(scope): description+```++### 类型++| Type | Use For |+|------|---------|+| `feat` | 新功能、示例或指南 |+| `fix` | Bug 修复、纠正、损坏链接 |+| `docs` | 文档改进 |+| `refactor` | 只重构、不改变行为 |+| `style` | 仅格式化改动 |+| `test` | 测试新增或修改 |+| `chore` | 构建、依赖、CI |++### 作用域++使用课程名称或文件区域作为作用域:++```+feat(slash-commands): Add API documentation generator+docs(memory): Improve personal preferences example+fix(README): Correct table of contents link+docs(skills): Add comprehensive code review skill+```++---++## 文档元数据页脚++课程 README 以元数据块结尾:++```markdown+---+**Last Updated**: March 2026+**Claude Code Version**: 2.1++**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5+```++- 使用“月份 + 年份”格式,例如 “March 2026”+- 功能变化时更新版本+- 列出所有兼容模型++---++## 作者检查清单++提交内容前,请确认:++- [ ] 文件/文件夹名使用 kebab-case+- [ ] 文档以 H1 标题开头,每个文件一个+- [ ] 标题层级正确,没有跳级+- [ ] 所有代码块都带语言标签+- [ ] 代码示例可直接复制粘贴+- [ ] 内部链接使用相对路径+- [ ] 外部链接使用描述性锚文本+- [ ] 表格格式正确+- [ ] Emoji 遵循标准集合(如果使用)+- [ ] Mermaid 图表使用标准配色+- [ ] 没有敏感信息,例如 API key、凭据+- [ ] YAML frontmatter 有效(如果适用)+- [ ] 图片有 alt 文本+- [ ] 段落简短且聚焦+- [ ] 相关指南章节链接到合适的课程+- [ ] 提交信息符合 conventional commits 格式diff --git a/zh/claude_concepts_guide.md b/zh/claude_concepts_guide.mdnew file mode 100644index 0000000..5049c02--- /dev/null+++ b/zh/claude_concepts_guide.md@@ -0,0 +1,1540 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">+</picture>++# Claude Concepts 完整指南++这是一份全面的参考指南,覆盖 Slash Commands、Subagents、Memory、MCP Protocol、Agent Skills、Plugins、Hooks、Checkpoints、Advanced Features 等 Claude Code 核心概念,并配有表格、图示和实践示例。++---++## 目录++1. [Slash Commands](#slash-commands)+2. [Subagents](#subagents)+3. [Memory](#memory)+4. [MCP Protocol](#mcp-protocol)+5. [Agent Skills](#agent-skills)+6. [Plugins](#claude-code-plugins)+7. [Hooks](#hooks)+8. [Checkpoints and Rewind](#checkpoints-and-rewind)+9. [Advanced Features](#advanced-features)+10. [Comparison & Integration](#comparison--integration)++---++## Slash Commands++### 概览++Slash commands 是由用户手动触发的快捷命令,以 Markdown 文件形式保存,Claude Code 可以读取并执行。它们非常适合把高频提示词与工作流标准化,方便团队复用。++### 架构++```mermaid+graph TD+ A["用户输入: /command-name"] -->|触发| B["搜索 .claude/commands/"]+ B -->|找到| C["command-name.md"]+ C -->|加载| D["Markdown 内容"]+ D -->|执行| E["Claude 处理提示"]+ E -->|返回| F["上下文中的结果"]+```++### 文件结构++```mermaid+graph LR+ A["项目根目录"] -->|包含| B[".claude/commands/"]+ B -->|包含| C["optimize.md"]+ B -->|包含| D["test.md"]+ B -->|包含| E["docs/"]+ E -->|包含| F["generate-api-docs.md"]+ E -->|包含| G["generate-readme.md"]+```++### 命令组织表++| 位置 | 作用域 | 可用范围 | 适用场景 | Git 跟踪 |+|------|--------|----------|----------|-----------|+| `.claude/commands/` | 项目级 | 团队成员 | 团队工作流、共享标准 | ✅ 是 |+| `~/.claude/commands/` | 个人级 | 当前用户 | 跨项目的个人快捷命令 | ❌ 否 |+| 子目录 | 命名空间 | 取决于父目录 | 按类别组织命令 | ✅ 是 |++### 功能与能力++| 功能 | 示例 | 是否支持 |+|------|------|----------|+| Shell 脚本执行 | `bash scripts/deploy.sh` | ✅ 是 |+| 文件引用 | `@path/to/file.js` | ✅ 是 |+| Bash 集成 | `$(git log --oneline)` | ✅ 是 |+| 参数 | `/pr --verbose` | ✅ 是 |+| MCP 命令 | `/mcp__github__list_prs` | ✅ 是 |++### 实践示例++#### 示例 1:代码优化命令++**文件:** `.claude/commands/optimize.md`++```markdown+---+name: 代码优化+description: 分析代码中的性能问题并给出优化建议+tags: performance, analysis+---++# 代码优化++请按以下优先级顺序审查给定代码中的问题:++1. **性能瓶颈** - 识别 O(n²) 操作、低效循环+2. **内存泄漏** - 查找未释放资源、循环引用+3. **算法改进** - 建议更优算法或数据结构+4. **缓存机会** - 识别重复计算+5. **并发问题** - 查找竞态条件或线程问题++请按以下格式输出:+- 问题严重级别(Critical/High/Medium/Low)+- 代码位置+- 解释说明+- 带代码示例的修复建议+```++**使用方式:**+```bash+# 用户在 Claude Code 中输入+/optimize++# Claude 加载提示并等待代码输入+```++#### 示例 2:Pull Request 辅助命令++**文件:** `.claude/commands/pr.md`++```markdown+---+name: 准备 Pull Request+description: 清理代码、暂存改动并准备一个 Pull Request+tags: git, workflow+---++# Pull Request 准备清单++在创建 PR 前,执行以下步骤:++1. 运行 lint:`prettier --write .`+2. 运行测试:`npm test`+3. 查看 git diff:`git diff HEAD`+4. 暂存改动:`git add .`+5. 按 conventional commits 规则编写提交信息:+ - `fix:` 用于 bug 修复+ - `feat:` 用于新功能+ - `docs:` 用于文档更新+ - `refactor:` 用于代码重构+ - `test:` 用于补充测试+ - `chore:` 用于维护性工作++6. 生成 PR 摘要,包括:+ - 改了什么+ - 为什么改+ - 做了哪些测试+ - 可能的影响+```++**使用方式:**+```bash+/pr++# Claude 按清单逐项检查并准备 PR+```++#### 示例 3:分层式文档生成器++**文件:** `.claude/commands/docs/generate-api-docs.md`++```markdown+---+name: 生成 API 文档+description: 基于源代码生成完整 API 文档+tags: documentation, api+---++# API 文档生成器++通过以下步骤生成 API 文档:++1. 扫描 `/src/api/` 下的所有文件+2. 提取函数签名和 JSDoc 注释+3. 按 endpoint / module 组织结构+4. 生成带示例的 Markdown+5. 包含请求 / 响应 schema+6. 补充错误文档++输出格式:+- 输出 Markdown 文件到 `/docs/api.md`+- 为所有端点包含 curl 示例+- 补充 TypeScript 类型+```++### 命令生命周期图++```mermaid+sequenceDiagram+ participant User+ participant Claude as Claude Code+ participant FS as File System+ participant CLI as Shell/Bash++ User->>Claude: 输入 /optimize+ Claude->>FS: 搜索 .claude/commands/+ FS-->>Claude: 返回 optimize.md+ Claude->>Claude: 加载 Markdown 内容+ Claude->>User: 显示提示上下文+ User->>Claude: 提供待分析代码+ Claude->>CLI: (可能执行脚本)+ CLI-->>Claude: 返回结果+ Claude->>User: 输出分析+```++### 最佳实践++| ✅ 建议 | ❌ 不建议 |+|------|---------|+| 使用清晰、面向动作的命名 | 为一次性任务创建命令 |+| 在描述中写清触发场景 | 在命令里堆复杂逻辑 |+| 保持命令聚焦单一任务 | 创建重复命令 |+| 将项目命令纳入版本控制 | 硬编码敏感信息 |+| 使用子目录组织分类 | 做过长的命令列表 |+| 使用简单、可读的提示词 | 使用晦涩或过度缩写的措辞 |++---++## Subagents++### 概览++Subagents 是带有隔离上下文窗口和自定义系统提示词的专门化 AI 助手。它们让 Claude 能够把复杂任务拆分并委派出去,同时保持关注点清晰分离。++### 架构图++```mermaid+graph TB+ User["👤 用户"]+ Main["🎯 主 Agent<br/>(协调者)"]+ Reviewer["🔍 代码审查<br/>Subagent"]+ Tester["✅ 测试工程师<br/>Subagent"]+ Docs["📝 文档编写<br/>Subagent"]++ User -->|提出请求| Main+ Main -->|委派| Reviewer+ Main -->|委派| Tester+ Main -->|委派| Docs+ Reviewer -->|返回结果| Main+ Tester -->|返回结果| Main+ Docs -->|返回结果| Main+ Main -->|汇总| User+```++### Subagent 生命周期++```mermaid+sequenceDiagram+ participant User+ participant MainAgent as 主 Agent+ participant CodeReviewer as 代码审查<br/>Subagent+ participant Context as 独立的<br/>上下文窗口++ User->>MainAgent: “构建新的认证功能”+ MainAgent->>MainAgent: 分析任务+ MainAgent->>CodeReviewer: “审查这段代码”+ CodeReviewer->>Context: 初始化干净上下文+ Context->>CodeReviewer: 加载审查规则+ CodeReviewer->>CodeReviewer: 执行审查+ CodeReviewer-->>MainAgent: 返回发现+ MainAgent->>MainAgent: 融合结果+ MainAgent-->>User: 输出综合结论+```++### Subagent 配置表++| 配置项 | 类型 | 作用 | 示例 |+|--------|------|------|------|+| `name` | String | Agent 标识符 | `code-reviewer` |+| `description` | String | 用途与触发词 | `Comprehensive code quality analysis` |+| `tools` | List/String | 允许的能力 | `read, grep, diff, lint_runner` |+| `system_prompt` | Markdown | 行为指令 | 自定义规范 |++### 工具访问层级++```mermaid+graph TD+ A["Subagent 配置"] -->|选项 1| B["继承主线程的全部工具"]+ A -->|选项 2| C["显式指定工具"]+ B -->|包含| B1["文件操作"]+ B -->|包含| B2["Shell 命令"]+ B -->|包含| B3["MCP 工具"]+ C -->|显式列表| C1["read, grep, diff"]+ C -->|显式列表| C2["Bash(npm:*), Bash(test:*)"]+```++### 实践示例++#### 示例 1:完整 Subagent 配置++**文件:** `.claude/agents/code-reviewer.md`++```yaml+---+name: code-reviewer+description: Comprehensive code quality and maintainability analysis+tools: read, grep, diff, lint_runner+---++# Code Reviewer Agent++You are an expert code reviewer specializing in:+- Performance optimization+- Security vulnerabilities+- Code maintainability+- Testing coverage+- Design patterns++## Review Priorities (in order)++1. **Security Issues** - Authentication, authorization, data exposure+2. **Performance Problems** - O(n²) operations, memory leaks, inefficient queries+3. **Code Quality** - Readability, naming, documentation+4. **Test Coverage** - Missing tests, edge cases+5. **Design Patterns** - SOLID principles, architecture++## Review Output Format++针对每个问题:+- **Severity**: Critical / High / Medium / Low+- **Category**: Security / Performance / Quality / Testing / Design+- **Location**: File path and line number+- **Issue Description**: What's wrong and why+- **Suggested Fix**: Code example+- **Impact**: How this affects the system+```++**文件:** `.claude/agents/test-engineer.md`++```yaml+---+name: test-engineer+description: Test strategy, coverage analysis, and automated testing+tools: read, write, bash, grep+---++# Test Engineer Agent++You are expert at:+- Writing comprehensive test suites+- Ensuring high code coverage (>80%)+- Testing edge cases and error scenarios+- Performance benchmarking+- Integration testing+```++**文件:** `.claude/agents/documentation-writer.md`++```yaml+---+name: documentation-writer+description: Technical documentation, API docs, and user guides+tools: read, write, grep+---++# Documentation Writer Agent++You create:+- API documentation with examples+- User guides and tutorials+- Architecture documentation+- Changelog entries+- Code comment improvements+```++#### 示例 2:Subagent 委派流程++```markdown+# 场景:构建支付功能++## 用户请求+"构建一个与 Stripe 集成的安全支付处理功能"++## 主 Agent 工作流++1. **规划阶段**+ - 理解需求+ - 确定所需任务+ - 规划架构++2. **委派给 Code Reviewer Subagent**+ - 任务:"审查支付处理实现中的安全问题"+ - 上下文:认证、API 密钥、token 处理+ - 重点:SQL 注入、密钥泄露、HTTPS 强制++3. **委派给 Test Engineer Subagent**+ - 任务:"为支付流程创建完整测试"+ - 上下文:成功场景、失败场景、边界情况+ - 输出:有效支付、拒付、网络故障、webhook 测试++4. **委派给 Documentation Writer Subagent**+ - 任务:"为支付 API 端点编写文档"+ - 上下文:请求 / 响应 schema+ - 产出:带 curl 示例和错误码的 API 文档++5. **综合**+ - 主 Agent 汇总所有输出+ - 整合发现+ - 返回完整方案给用户+```++#### 示例 3:工具权限范围++**受限配置:只允许特定能力**++```yaml+---+name: secure-reviewer+description: Security-focused code review with minimal permissions+tools: read, grep+---++# Secure Code Reviewer++Reviews code for security vulnerabilities only.+```++**扩展配置:为实现任务开放全部工具**++```yaml+---+name: implementation-agent+description: Full implementation capabilities for feature development+tools: read, write, bash, grep, edit, glob+---++# Implementation Agent++Builds features from specifications.+```++### Subagent 上下文管理++```mermaid+graph TB+ A["主 Agent 上下文<br/>50,000 tokens"]+ B["Subagent 1 上下文<br/>20,000 tokens"]+ C["Subagent 2 上下文<br/>20,000 tokens"]+ D["Subagent 3 上下文<br/>20,000 tokens"]++ A -->|干净上下文| B+ A -->|干净上下文| C+ A -->|干净上下文| D++ B -->|仅返回结果| A+ C -->|仅返回结果| A+ D -->|仅返回结果| A++ style A fill:#e1f5ff+ style B fill:#fff9c4+ style C fill:#fff9c4+ style D fill:#fff9c4+```++### 何时使用 Subagents++| 场景 | 是否使用 Subagent | 原因 |+|------|------------------|------|+| 多步骤复杂功能 | ✅ 是 | 分离关注点,防止上下文污染 |+| 快速代码审查 | ❌ 否 | 开销不值得 |+| 并行任务执行 | ✅ 是 | 每个 subagent 都有自己的上下文 |+| 需要专业化角色 | ✅ 是 | 可以用自定义系统提示词 |+| 长时间分析任务 | ✅ 是 | 防止主上下文耗尽 |+| 单一步骤任务 | ❌ 否 | 只会增加延迟 |++### Agent Teams++Agent Teams 用于协调多个 agent 围绕一个共同目标协作。与一次只委派一个 subagent 不同,Agent Teams 允许主 agent 编排一组协作代理,在共享中间结果的同时并行推进大任务,例如由前端 agent、后端 agent、测试 agent 一起完成一个全栈功能。++---++## Memory++### 概览++Memory 让 Claude 能够在不同会话和对话之间保留上下文。它主要有两种形态:Claude Web/Desktop 中的自动记忆综合,以及 Claude Code 中基于文件系统的 `CLAUDE.md`。++### Memory 架构++```mermaid+graph TB+ A["Claude 会话"]+ B["用户输入"]+ C["记忆系统"]+ D["记忆存储"]++ B -->|用户提供信息| C+ C -->|每 24 小时综合| D+ D -->|自动加载| A+ A -->|使用上下文| C+```++### Claude Code 中的 7 层记忆层级++Claude Code 会按优先级从高到低加载 7 层记忆:++```mermaid+graph TD+ A["1. Managed Policy<br/>企业管理员策略"] --> B["2. Project Memory<br/>./CLAUDE.md"]+ B --> C["3. Project Rules<br/>.claude/rules/*.md"]+ C --> D["4. User Memory<br/>~/.claude/CLAUDE.md"]+ D --> E["5. User Rules<br/>~/.claude/rules/*.md"]+ E --> F["6. Local Memory<br/>.claude/local/CLAUDE.md"]+ F --> G["7. Auto Memory<br/>自动捕获的偏好"]+```++### Memory 位置表++| 层级 | 位置 | 作用域 | 优先级 | 是否共享 | 最适合 |+|------|------|--------|--------|----------|--------|+| 1. Managed Policy | 企业管理员 | 组织级 | 最高 | 全组织用户 | 合规、安全策略 |+| 2. Project | `./CLAUDE.md` | 项目级 | 高 | 团队(Git) | 团队标准、架构 |+| 3. Project Rules | `.claude/rules/*.md` | 项目级 | 高 | 团队(Git) | 模块化项目约定 |+| 4. User | `~/.claude/CLAUDE.md` | 个人级 | 中 | 个人 | 个人偏好 |+| 5. User Rules | `~/.claude/rules/*.md` | 个人级 | 中 | 个人 | 个人规则模块 |+| 6. Local | `.claude/local/CLAUDE.md` | 本地 | 低 | 不共享 | 机器相关设置 |+| 7. Auto Memory | 自动生成 | 会话级 | 最低 | 个人 | 学到的偏好与模式 |++### Auto Memory++Auto Memory 会在会话中自动捕获用户偏好与行为模式。Claude 会记住:++- 代码风格偏好+- 你常做的纠正+- 框架和工具选择+- 沟通方式偏好++它在后台工作,不需要手动配置。++### Memory 更新生命周期++```mermaid+sequenceDiagram+ participant User+ participant Claude as Claude Code+ participant Editor as File System+ participant Memory as CLAUDE.md++ User->>Claude: “记住:统一使用 async/await”+ Claude->>User: “写入哪个记忆文件?”+ User->>Claude: “项目记忆”+ Claude->>Editor: 打开 ~/.claude/settings.json+ Claude->>Memory: 写入 ./CLAUDE.md+ Memory-->>Claude: 文件已保存+ Claude->>Claude: 重新加载记忆+ Claude-->>User: “记忆已保存!”+```++### 实践示例++#### 示例 1:项目级记忆结构++**文件:** `./CLAUDE.md`++```markdown+# 项目配置++## 项目概览+- **名称**:电商平台+- **技术栈**:Node.js、PostgreSQL、React 18、Docker+- **团队规模**:5 名开发者+- **截止时间**:2025 年第 4 季度++## 架构+@docs/architecture.md+@docs/api-standards.md+@docs/database-schema.md++## 开发标准++### Code Style+- 使用 Prettier 格式化+- 使用 ESLint + airbnb config+- 最大行宽 100 字符+- 使用 2 空格缩进++### Naming Conventions+- **文件**:kebab-case+- **类**:PascalCase+- **函数/变量**:camelCase+- **常量**:UPPER_SNAKE_CASE+- **数据库表**:snake_case+```++#### 示例 2:目录级记忆++**文件:** `./src/api/CLAUDE.md`++~~~~markdown+# API 模块标准++该文件会覆盖根目录 `CLAUDE.md` 中对 `/src/api/` 的规则。++## API 专属标准++### Request Validation+- 使用 Zod 做 schema 校验+- 所有输入都必须校验+- 校验失败时返回 400+- 包含字段级错误详情++### Authentication+- 所有端点都要求 JWT token+- Token 通过 Authorization header 传递+- Token 24 小时过期+- 实现 refresh token 机制+~~~~++#### 示例 3:个人记忆++**文件:** `~/.claude/CLAUDE.md`++~~~~markdown+# 我的开发偏好++## About Me+- **经验水平**:8 年全栈开发+- **偏好语言**:TypeScript、Python+- **沟通风格**:直接、配示例+- **学习风格**:喜欢图示和代码配合++## Code Preferences++### Error Handling+我偏好显式的 try-catch 和清晰的错误信息。+避免泛化错误,调试时始终记录日志。+~~~~++#### 示例 4:会话中更新记忆++```markdown+User: 记住:所有新组件都优先使用 React hooks,不用 class components。++Claude: 我会把它加入记忆。你希望写入哪个记忆文件?+ 1. 项目记忆(./CLAUDE.md)+ 2. 个人记忆(~/.claude/CLAUDE.md)++User: 项目记忆++Claude: ✅ 记忆已保存!+```++### Claude Web/Desktop 中的记忆综合++#### 记忆综合时间线++```mermaid+graph LR+ A["第 1 天:用户对话"] -->|24 小时| B["第 2 天:记忆综合"]+ B -->|自动| C["记忆更新并摘要化"]+ C -->|加载到| D["第 2-N 天:新对话"]+```++### Memory 功能对比++| 功能 | Claude Web/Desktop | Claude Code (`CLAUDE.md`) |+|------|--------------------|---------------------------|+| 自动综合 | ✅ 每 24 小时 | ❌ 手动 |+| 跨项目 | ✅ 共享 | ❌ 项目级 |+| 团队访问 | ✅ 共享项目 | ✅ Git 跟踪 |+| 可搜索 | ✅ 内建 | ✅ 通过 `/memory` |+| 可编辑 | ✅ 聊天中 | ✅ 直接改文件 |+| 导入/导出 | ✅ 支持 | ✅ 复制粘贴 |+| 持久性 | ✅ 24h+ | ✅ 长期 |++---++## MCP Protocol++### 概览++MCP(Model Context Protocol)是 Claude 访问外部工具、API 与实时数据源的标准方式。与 Memory 不同,MCP 提供的是对持续变化数据的实时访问。++### MCP 架构++```mermaid+graph TB+ A["Claude"]+ B["MCP Server"]+ C["外部服务"]++ A -->|请求| B+ B -->|查询| C+ C -->|数据| B+ B -->|响应| A+```++### MCP 生态++```mermaid+graph TB+ A["Claude"] -->|MCP| B["Filesystem<br/>MCP Server"]+ A -->|MCP| C["GitHub<br/>MCP Server"]+ A -->|MCP| D["Database<br/>MCP Server"]+ A -->|MCP| E["Slack<br/>MCP Server"]+ A -->|MCP| F["Google Docs<br/>MCP Server"]+```++### MCP 设置流程++```mermaid+sequenceDiagram+ participant User+ participant Claude as Claude Code+ participant Config as 配置文件+ participant Service as 外部服务++ User->>Claude: 输入 /mcp+ Claude->>Claude: 列出可用 MCP server+ Claude->>User: 展示选项+ User->>Claude: 选择 GitHub MCP+ Claude->>Config: 更新配置+ Config->>Claude: 激活连接+ Claude->>Service: 测试连接+ Service-->>Claude: 认证成功+ Claude->>User: ✅ MCP 已连接+```++### 可用 MCP Server 表++| MCP Server | 用途 | 常见工具 | 认证 | 实时 |+|------------|------|----------|------|------|+| Filesystem | 文件操作 | read, write, delete | 操作系统权限 | ✅ 是 |+| GitHub | 仓库管理 | list_prs, create_issue, push | OAuth | ✅ 是 |+| Slack | 团队沟通 | send_message, list_channels | Token | ✅ 是 |+| Database | SQL 查询 | query, insert, update | 凭据 | ✅ 是 |+| Google Docs | 文档访问 | read, write, share | OAuth | ✅ 是 |+| Asana | 项目管理 | create_task, update_status | API Key | ✅ 是 |+| Stripe | 支付数据 | list_charges, create_invoice | API Key | ✅ 是 |+| Memory | 持久记忆 | store, retrieve, delete | Local | ❌ 否 |++### 实践示例++#### 示例 1:GitHub MCP 配置++```json+{+ "mcpServers": {+ "github": {+ "command": "npx",+ "args": ["@modelcontextprotocol/server-github"],+ "env": {+ "GITHUB_TOKEN": "${GITHUB_TOKEN}"+ }+ }+ }+}+```++#### 示例 2:Database MCP 配置++```json+{+ "mcpServers": {+ "database": {+ "command": "npx",+ "args": ["@modelcontextprotocol/server-database"],+ "env": {+ "DATABASE_URL": "postgresql://user:pass@localhost/mydb"+ }+ }+ }+}+```++#### 示例 3:多 MCP 工作流++```markdown+# 使用多个 MCP 的日报工作流++## 设置+1. GitHub MCP - 获取 PR 指标+2. Database MCP - 查询销售数据+3. Slack MCP - 发送报告+4. Filesystem MCP - 保存报告+```++#### 示例 4:Filesystem MCP 操作++| 操作 | 命令 | 作用 |+|------|------|------|+| 列出文件 | `ls ~/projects` | 查看目录内容 |+| 读取文件 | `cat src/main.ts` | 读取文件内容 |+| 写入文件 | `create docs/api.md` | 创建新文件 |+| 编辑文件 | `edit src/app.ts` | 修改文件 |+| 搜索 | `grep "async function"` | 在文件中搜索 |+| 删除 | `rm old-file.js` | 删除文件 |++### MCP vs Memory:决策矩阵++```mermaid+graph TD+ A["需要外部数据吗?"]+ A -->|否| B["使用 Memory"]+ A -->|是| C["数据是否频繁变化?"]+ C -->|否/很少| B+ C -->|是/经常| D["使用 MCP"]+```++### 请求 / 响应模式++```mermaid+sequenceDiagram+ participant App as Claude+ participant MCP as MCP Server+ participant DB as Database++ App->>MCP: Request: "SELECT * FROM users WHERE id=1"+ MCP->>DB: Execute query+ DB-->>MCP: Result set+ MCP-->>App: Return parsed data+```++---++## Agent Skills++### 概览++Agent Skills 是可复用、由模型自动调用的能力包。它们以目录形式存在,通常包含说明、脚本和资源文件。Claude 会在合适时自动发现并使用它们。++### Skill 架构++```mermaid+graph TB+ A["Skill 目录"]+ B["SKILL.md"]+ C["YAML 元数据"]+ D["说明"]+ E["脚本"]+ F["模板"]++ A --> B+ B --> C+ B --> D+ E --> A+ F --> A+```++### Skill 加载流程++```mermaid+sequenceDiagram+ participant User+ participant Claude as Claude+ participant System as System+ participant Skill as Skill++ User->>Claude: "Create Excel report"+ Claude->>System: Scan available skills+ System->>System: Load skill metadata+ Claude->>Claude: Match user request to skills+ Claude->>Skill: Load xlsx skill SKILL.md+ Skill-->>Claude: Return instructions + tools+ Claude->>Claude: Execute skill+ Claude->>User: Generate Excel file+```++### Skill 类型与位置++| 类型 | 位置 | 作用域 | 是否共享 | 同步方式 | 最适合 |+|------|------|--------|----------|----------|--------|+| 内置 | Built-in | 全局 | 全部用户 | 自动 | 文档生成 |+| 个人 | `~/.claude/skills/` | 个人 | 否 | 手动 | 个人自动化 |+| 项目 | `.claude/skills/` | 团队 | 是 | Git | 团队标准 |+| 插件 | 通过 plugin 安装 | 视情况而定 | 视情况而定 | 自动 | 集成能力 |++### 预构建 Skills++Claude Code 现在内置了 5 个 bundled skills,可直接使用:++| Skill | 命令 | 用途 |+|-------|------|------|+| Simplify | `/simplify` | 简化复杂代码或解释 |+| Batch | `/batch` | 批量对多个文件或对象执行操作 |+| Debug | `/debug` | 系统化调试并做根因分析 |+| Loop | `/loop` | 按定时计划重复执行任务 |+| Claude API | `/claude-api` | 直接与 Anthropic API 交互 |++### 实践示例++#### 示例 1:自定义代码审查 Skill++**目录结构:**++```text+~/.claude/skills/code-review/+├── SKILL.md+├── templates/+│ ├── review-checklist.md+│ └── finding-template.md+└── scripts/+ ├── analyze-metrics.py+ └── compare-complexity.py+```++**文件:** `~/.claude/skills/code-review/SKILL.md`++```yaml+---+name: Code Review Specialist+description: Comprehensive code review with security, performance, and quality analysis+version: "1.0.0"+tags:+ - code-review+ - quality+ - security+when_to_use: 当用户希望审查代码、分析代码质量或评估 pull request 时+effort: high+shell: bash+---++# 代码审查 Skill++这个 skill 提供全面的代码审查能力,重点关注:++1. **安全分析**+2. **性能审查**+3. **代码质量**+4. **可维护性**+```++相关 Python 脚本和模板可直接沿用原始实现;脚本逻辑本身无需翻译即可使用。++#### 示例 2:Brand Voice Skill++这个 skill 用于统一品牌语气、用词风格和外部沟通表达。它通常包含品牌使命、价值观、推荐用词、避免用词,以及邮件 / 社交媒体等模板。++#### 示例 3:Documentation Generator Skill++这个 skill 用于从源码生成 API 文档,常见产物包括:++- OpenAPI/Swagger 规范+- API 端点文档+- SDK 使用示例+- 集成指南+- 错误码说明+- 认证说明++### Skill 发现与调用++```mermaid+graph TD+ A["用户请求"] --> B["Claude 分析"]+ B -->|扫描| C["可用 Skills"]+ C -->|元数据匹配| D["Skill 描述是否匹配?"]+ D -->|是| E["加载 SKILL.md"]+ D -->|否| F["尝试下一个 Skill"]+ E --> H["提取指令"]+ H --> I["执行 Skill"]+ I --> J["返回结果"]+```++### Skill 与其他功能的区别++```mermaid+graph TB+ A["扩展 Claude"]+ B["Slash Commands"]+ C["Subagents"]+ D["Memory"]+ E["MCP"]+ F["Skills"]++ A --> B+ A --> C+ A --> D+ A --> E+ A --> F+```++---++## Claude Code Plugins++### 概览++Claude Code Plugins 是把多种能力打包在一起的一体化扩展机制,通常包含 slash commands、subagents、MCP servers、hooks 以及相关配置。它们可以通过一条命令完成安装。++### 架构++```mermaid+graph TB+ A["Plugin"]+ B["Slash Commands"]+ C["Subagents"]+ D["MCP Servers"]+ E["Hooks"]+ F["Configuration"]++ A -->|打包| B+ A -->|打包| C+ A -->|打包| D+ A -->|打包| E+ A -->|打包| F+```++### Plugin 加载流程++```mermaid+sequenceDiagram+ participant User+ participant Claude as Claude Code+ participant Plugin as Plugin Marketplace+ participant Install as Installation+ participant SlashCmds as Slash Commands+ participant Subagents+ participant MCPServers as MCP Servers+ participant Hooks++ User->>Claude: /plugin install pr-review+ Claude->>Plugin: 下载插件清单+ Plugin-->>Claude: 返回插件定义+ Claude->>Install: 解包组件+ Install->>SlashCmds: 配置+ Install->>Subagents: 配置+ Install->>MCPServers: 配置+ Install->>Hooks: 配置+```++### Plugin 类型与分发++| 类型 | 作用域 | 是否共享 | 权威来源 | 示例 |+|------|--------|----------|----------|------|+| Official | 全局 | 全部用户 | Anthropic | PR Review、Security Guidance |+| Community | 公开 | 全部用户 | 社区 | DevOps、Data Science |+| Organization | 内部 | 团队成员 | 公司 | 内部标准、工具 |+| Personal | 个人 | 单用户 | 开发者 | 自定义工作流 |++### Plugin 定义结构++```yaml+---+name: plugin-name+version: "1.0.0"+description: "What this plugin does"+author: "Your Name"+license: MIT+---+```++### Plugin 结构++```text+my-plugin/+├── .claude-plugin/+│ └── plugin.json+├── commands/+├── agents/+├── skills/+├── hooks/+├── .mcp.json+├── templates/+├── scripts/+├── docs/+└── tests/+```++### 实践示例++#### 示例 1:PR Review Plugin++```json+{+ "name": "pr-review",+ "version": "1.0.0",+ "description": "Complete PR review workflow with security, testing, and docs"+}+```++#### 示例 2:DevOps Plugin++```text+devops-automation/+├── commands/+├── agents/+├── mcp/+├── hooks/+└── scripts/+```++#### 示例 3:Documentation Plugin++```text+documentation/+├── commands/+├── agents/+├── mcp/+└── templates/+```++### Plugin Marketplace++```mermaid+graph TB+ A["Plugin Marketplace"]+ B["Official"]+ C["Community"]+ D["Enterprise"]+```++### Plugin 安装与生命周期++```mermaid+graph LR+ A["发现"] --> B["浏览 Marketplace"]+ B --> C["查看插件页"]+ C --> D["查看组件"]+ D --> E["/plugin install"]+ E --> F["配置"]+ F --> G["启用"]+```++### Plugin 功能对比++| 功能 | Slash Command | Skill | Subagent | Plugin |+|------|---------------|-------|----------|--------|+| 安装 | 手动复制 | 手动复制 | 手动配置 | 一条命令 |+| 搭建时间 | 5 分钟 | 10 分钟 | 15 分钟 | 2 分钟 |+| 打包能力 | 单文件 | 单文件 | 单文件 | 多组件 |+| 团队共享 | 复制文件 | 复制文件 | 复制文件 | 通过安装 ID |+| 更新方式 | 手动 | 手动 | 手动 | 市场可用 / 更易分发 |++### 何时创建 Plugin++- 当你需要一次分发多个命令、subagents、MCP servers 或 hooks 时+- 当这是团队级工作流,需要统一安装和复制时+- 当你希望自动化配置过程并减少手工步骤时++### 发布 Plugin++1. 创建完整的插件结构+2. 编写 `.claude-plugin/plugin.json`+3. 编写 `README.md`+4. 本地测试+5. 提交到 marketplace+6. 审核通过+7. 发布++### Plugin vs 手动配置++**手动配置:**+- 一个个复制 slash commands+- 单独创建 subagents+- 分别配置 MCP+- 手动设置 hooks++**使用 Plugin:**+```bash+/plugin install pr-review+# ✅ 一次安装完成+# ✅ 即刻可用+# ✅ 团队可复现+```++---++## Comparison & Integration++### 功能对比矩阵++| 功能 | 调用方式 | 持久性 | 作用域 | 适用场景 |+|------|----------|--------|--------|----------|+| Slash Commands | 手动 (`/cmd`) | 仅当前会话 | 单个命令 | 快捷操作 |+| Subagents | 自动委派 | 隔离上下文 | 专门任务 | 任务拆分 |+| Memory | 自动加载 | 跨会话 | 用户 / 团队上下文 | 长期记忆 |+| MCP Protocol | 自动查询 | 实时外部数据 | 动态访问 | 外部数据接入 |+| Skills | 自动触发 | 文件系统级 | 可复用专长 | 自动化工作流 |+| Plugins | 一键安装 | 全套组合 | 团队 / 市场分发 | 完整方案打包 |++### 交互时间线++```mermaid+graph LR+ A["Session Start"] -->|Load| B["Memory (CLAUDE.md)"]+ B -->|Discover| C["Available Skills"]+ C -->|Register| D["Slash Commands"]+ D -->|Connect| E["MCP Servers"]+ E -->|Ready| F["User Interaction"]+```++### 集成示例:客户支持自动化++#### 架构++```mermaid+graph TB+ User["客户邮件"] -->|进入| Router["支持路由器"]+ Router -->|分析| Memory["Memory<br/>客户历史"]+ Router -->|查询| MCP1["MCP: 客户数据库"]+ Router -->|检查| MCP2["MCP: Slack"]+ Router -->|复杂问题| Sub1["Subagent: 技术支持"]+ Router -->|简单问题| Sub2["Subagent: 计费支持"]+```++#### 请求流++```markdown+1. 用户发来报错邮件+2. 读取记忆和历史上下文+3. 通过多个 MCP 查询系统状态+4. 自动识别适合的 Skill+5. 委派给对应 Subagent+6. Subagent 处理问题+7. Skill 负责按统一语气生成回复+8. MCP 将结果同步到外部系统+9. 返回给客户+```++### 完整功能编排++```mermaid+sequenceDiagram+ participant User+ participant Claude as Claude Code+ participant Memory as Memory+ participant MCP as MCP Servers+ participant Skills as Skills+ participant SubAgent as Subagents++ User->>Claude: "Build auth system"+ Claude->>Memory: 加载项目标准+ Claude->>MCP: 查询相似实现+ Claude->>Skills: 检测匹配 Skill+ Claude->>SubAgent: 委派实现+```++### 何时使用哪种功能++```mermaid+graph TD+ A["新任务"] --> B{任务类型?}++ B -->|重复工作流| C["Slash Command"]+ B -->|需要实时数据| D["MCP Protocol"]+ B -->|希望下次记住| E["Memory"]+ B -->|需要专业子任务| F["Subagent"]+ B -->|领域型自动化| G["Skill"]+```++### 选择决策树++```mermaid+graph TD+ Start["需要扩展 Claude 吗?"]+ Start -->|快速重复任务| A{"手动还是自动?"}+ A -->|手动| B["Slash Command"]+ A -->|自动| C["Skill"]+ Start -->|需要外部数据| D{"是否实时?"}+ D -->|是| E["MCP Protocol"]+ D -->|否| F["Memory"]+ Start -->|复杂项目| G{"是否多角色协作?"}+ G -->|是| H["Subagents"]+```++---++## Summary Table++| 维度 | Slash Commands | Subagents | Memory | MCP | Skills | Plugins |+|------|----------------|-----------|--------|-----|--------|---------|+| 搭建难度 | 简单 | 中等 | 简单 | 中等 | 中等 | 简单 |+| 学习曲线 | 低 | 中 | 低 | 中 | 中 | 低 |+| 团队价值 | 高 | 高 | 中 | 高 | 高 | 很高 |+| 自动化程度 | 低 | 高 | 中 | 高 | 高 | 很高 |+| 上下文管理 | 单会话 | 隔离 | 持久 | 实时 | 持久 | 全部整合 |+| 可扩展性 | 好 | 极佳 | 好 | 极佳 | 极佳 | 极佳 |+| 共享性 | 一般 | 一般 | 好 | 好 | 好 | 极佳 |+| 安装方式 | 手动复制 | 手动配置 | N/A | 手动配置 | 手动复制 | 一条命令 |++---++## Quick Start Guide++### 第 1 周:先从简单的开始+- 为常见任务做 2-3 个 slash commands+- 在设置里开启 Memory+- 在 `CLAUDE.md` 里写明团队标准++### 第 2 周:接入实时数据+- 先配置 1 个 MCP(GitHub 或 Database)+- 通过 `/mcp` 配置+- 在工作流中查询实时数据++### 第 3 周:分发工作+- 创建第一个针对角色的 Subagent+- 使用 `/agents`+- 用简单任务测试委派++### 第 4 周:全面自动化+- 创建第一个 Skill+- 使用市场里的 Skill 或自建+- 组合多个功能做完整工作流++### 持续优化+- 每月回顾并更新 Memory+- 当重复模式出现时新增 Skill+- 优化 MCP 查询+- 持续打磨 Subagent 提示词++---++## Hooks++### 概览++Hooks 是事件驱动的 shell 命令,会在 Claude Code 的特定事件发生时自动执行,可用于自动化、校验、通知和自定义工作流。++### Hook 事件++Claude Code 支持 **25 个 hook 事件**,分布在四类钩子中:++| Hook 事件 | 触发时机 | 常见用途 |+|-----------|----------|----------|+| SessionStart | 会话开始 / 恢复 / 清空 / compact | 环境初始化 |+| InstructionsLoaded | 加载 `CLAUDE.md` 或 rules | 校验、增强 |+| UserPromptSubmit | 用户提交提示词 | 输入校验 |+| PreToolUse | 工具执行前 | 审批、校验、日志 |+| PermissionRequest | 弹出权限请求时 | 自动批准 / 拒绝 |+| PostToolUse | 工具执行成功后 | 自动格式化、通知、清理 |+| PostToolUseFailure | 工具失败后 | 错误处理 |+| Notification | 通知发送时 | 外部联动 |+| SubagentStart | 启动 subagent 时 | 注入上下文 |+| SubagentStop | subagent 结束时 | 结果校验 |+| Stop | Claude 响应完成时 | 总结、清理 |+| SessionEnd | 会话结束时 | 收尾处理 |++### 常见 Hook 配置++```json+{+ "hooks": {+ "PostToolUse": [+ {+ "matcher": "Write",+ "hooks": [+ {+ "type": "command",+ "command": "prettier --write $CLAUDE_FILE_PATH"+ }+ ]+ }+ ]+ }+}+```++### Hook 环境变量++- `$CLAUDE_FILE_PATH`:当前被写入 / 编辑的文件+- `$CLAUDE_TOOL_NAME`:正在使用的工具名+- `$CLAUDE_SESSION_ID`:当前会话 ID+- `$CLAUDE_PROJECT_DIR`:项目目录路径++### 最佳实践++✅ 建议:+- 让 hooks 尽量快(最好 < 1 秒)+- 用 hooks 做校验和自动化+- 优雅处理错误+- 使用绝对路径++❌ 不建议:+- 让 hooks 进入交互式流程+- 把长时间任务放在 hooks 里+- 硬编码凭据++**详见:** [06-hooks/README.md](06-hooks/README.md)++---++## Checkpoints and Rewind++### 概览++Checkpoints 可以保存会话状态,并在需要时回退到之前的节点,从而安全地尝试不同方案。++### 核心概念++| 概念 | 说明 |+|------|------|+| Checkpoint | 对消息、文件和上下文的快照 |+| Rewind | 回到某个历史 checkpoint,并丢弃之后的变化 |+| Branch Point | 从同一个 checkpoint 分叉出多种方案 |++### 如何访问 Checkpoints++```bash+# 按两次 Esc 打开 checkpoint 浏览器+Esc + Esc++# 或使用 /rewind+/rewind+```++选择 checkpoint 后有五个选项:+1. 恢复代码和对话+2. 恢复对话+3. 恢复代码+4. 从这里开始总结+5. 取消++### 常见场景++| 场景 | 工作流 |+|------|--------|+| 探索不同方案 | 保存 → 尝试 A → 保存 → 回退 → 尝试 B |+| 安全重构 | 保存 → 重构 → 测试 → 失败就回退 |+| A/B 测试 | 保存 → 设计 A → 保存 → 回退 → 设计 B |+| 误操作恢复 | 发现问题 → 回退到最近稳定状态 |++### 配置++```json+{+ "autoCheckpoint": true+}+```++**详见:** [08-checkpoints/README.md](08-checkpoints/README.md)++---++## Advanced Features++### Planning Mode++在编码前先生成详细实现计划。++```bash+/plan Implement user authentication system+```++优势:+- 清晰路线图+- 时间预估+- 风险评估+- 可审查、可修改++### Extended Thinking++适合复杂问题的深度推理。++```bash+export MAX_THINKING_TOKENS=50000+claude -p "Should we use microservices or monolith?"+```++### Background Tasks++后台执行长任务而不阻塞当前对话。++```bash+/task list+/task status bg-1234+/task show bg-1234+/task cancel bg-1234+```++### Permission Modes++| 模式 | 说明 | 适用场景 |+|------|------|----------|+| `default` | 标准权限模式 | 通用开发 |+| `acceptEdits` | 自动接受文件编辑 | 信任编辑工作流 |+| `plan` | 只分析不改文件 | 审查、规划 |+| `auto` | 自动批准安全操作 | 平衡自治与安全 |+| `dontAsk` | 不再提示确认 | 资深用户 / 自动化 |+| `bypassPermissions` | 完全不受限 | CI/CD、可信脚本 |++### Headless Mode(Print Mode)++使用 `-p` 标志在无交互模式下运行 Claude Code,适合自动化和 CI/CD。++```bash+claude -p "Run all tests"+cat error.log | claude -p "explain this error"+claude -p --output-format json "list all functions in src/"+```++### Scheduled Tasks++通过 `/loop` 按计划周期性运行任务:++```bash+/loop every 30m "Run tests and report failures"+/loop every 2h "Check for dependency updates"+/loop every 1d "Generate daily summary of code changes"+```++### Chrome Integration++Claude Code 可以与 Chrome 浏览器集成,用于网页自动化,如导航页面、填写表单、截图和提取页面数据。++### Session Management++```bash+/resume+/rename "Feature"+/fork+claude -c+claude -r "Feature"+```++### Interactive Features++- `Ctrl + R`:搜索命令历史+- `Tab`:自动补全+- `↑ / ↓`:浏览历史+- `Ctrl + L`:清屏++### 配置++```json+{+ "planning": {+ "autoEnter": true,+ "requireApproval": true+ },+ "backgroundTasks": {+ "enabled": true,+ "maxConcurrentTasks": 5+ },+ "permissions": {+ "mode": "default"+ }+}+```++**详见:** [09-advanced-features/README.md](09-advanced-features/README.md)++---++## Resources++- [Claude Code Documentation](https://code.claude.com/docs/en/overview)+- [Anthropic Documentation](https://docs.anthropic.com)+- [MCP GitHub Servers](https://github.com/modelcontextprotocol/servers)+- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook)++---++*最后更新:2026 年 3 月*+*适用于 Claude Haiku 4.5、Sonnet 4.6、Opus 4.6*+*现已覆盖:Hooks、Checkpoints、Planning Mode、Extended Thinking、Background Tasks、Permission Modes、Headless Mode、Session Management、Auto Memory、Agent Teams、Scheduled Tasks、Chrome Integration、Bundled Skills 等概念。*diff --git a/zh/clean-code-rules.md b/zh/clean-code-rules.mdnew file mode 100644index 0000000..196c536--- /dev/null+++ b/zh/clean-code-rules.md@@ -0,0 +1,108 @@+# 面向 AI 代码生成的整洁代码规则++这些规则用于指导代码生成,帮助产出可维护、专业水准的代码。++## 有意义的命名+- 使用能体现意图的名称,说明它为什么存在+- 避免误导性命名和无意义区分,例如 `data`、`info`、`manager`+- 使用可读、可搜索的名称+- 类名使用名词,例如 `UserAccount`、`PaymentProcessor`+- 方法名使用动词,例如 `calculateTotal`、`sendEmail`+- 避免脑内映射和编码风格命名,例如匈牙利命名法、前缀++## 函数+- 保持函数短小精炼,理想情况下少于 20 行+- 只做一件事,遵循单一职责原则+- 每个函数只处理一个抽象层级+- 限制参数数量,理想为 0-2 个,最多 3 个,避免布尔标志参数+- 不要产生副作用,函数应该做它名字所说的事+- 将命令与查询分离,命令修改状态,查询返回信息+- 优先使用异常而不是错误码++## 注释+- 代码本身应该尽量可自解释,能不写注释就不写+- 好的注释包括:法律信息、警告、TODO、公共 API 文档+- 坏的注释包括:重复、误导,或者只是解释糟糕的代码+- 不要注释掉代码,直接删除,版本控制会保留历史+- 如果你需要写注释,先考虑重构代码++## 格式化+- 保持文件小而聚焦+- 垂直格式化:相关概念放近一些,空行分隔不同概念+- 水平格式化:限制行长度在 80-120 个字符之间+- 使用一致的缩进和团队风格+- 将相关函数分组放在一起++## 对象与数据结构+- 对象:通过抽象隐藏数据,通过方法暴露行为+- 数据结构:暴露数据,尽量少提供行为+- 迪米特法则:只和直接朋友说话,避免 `a.getB().getC().doSomething()`+- 不要毫无节制地通过 getter/setter 暴露内部结构++## 错误处理+- 使用异常,不要使用返回码或错误标志+- 代码可能失败时,先写 `try-catch-finally`+- 在异常信息中提供上下文+- 不要返回 `null`,改为返回空集合或使用 Optional/Maybe+- 不要把 `null` 作为参数传入++## 类+- 小类应按职责衡量,而不是按行数衡量+- 单一职责原则:只有一个改变原因+- 高内聚:类变量被多数方法使用+- 低耦合:类之间依赖尽量少+- 开闭原则:对扩展开放,对修改关闭++## 单元测试+- 快速、独立、可重复、自我验证、及时(F.I.R.S.T.)+- 每个测试一个断言,或只验证一个概念+- 测试代码质量应与生产代码质量一致+- 测试名称要可读,清楚描述正在测试什么+- 遵循 Arrange-Act-Assert 模式++## 代码质量原则+- **DRY(Don't Repeat Yourself)**:不要重复+- **YAGNI(You Aren't Gonna Need It)**:不要为假设中的未来提前构建+- **KISS(Keep It Simple)**:避免不必要的复杂度+- **童子军规则**:让代码比你接手时更干净++## 应避免的代码坏味道+- 函数或类过长+- 重复代码+- 死代码(未使用的变量、函数、参数)+- 特性依恋(方法更关心别的类)+- 不恰当的亲密关系(类彼此了解过多)+- 过长的参数列表+- 原始类型偏执(过度使用原始类型而不是小对象)+- switch/case 语句(考虑使用多态)+- 临时字段(类变量只在某些时候才使用)++## 并发+- 将并发代码与其他代码隔离+- 限制同步/加锁数据的作用域+- 使用线程安全集合+- 保持同步区块尽量小+- 了解你的执行模型和原语++## 系统设计+- 将构建和使用分离,例如通过依赖注入+- 复杂对象创建时使用工厂、构建器+- 面向接口编程,而不是面向实现编程+- 优先组合而不是继承+- 设计模式只在它们简化问题时使用,不要为了炫技而使用++## 重构+- 持续重构,不要攒成大批量一次做完+- 重构前后都要保证测试通过+- 小步前进,每次只改一处+- 常见重构包括:提取方法、重命名、移动、内联++## 文档+- 自说明代码 > 注释 > 外部文档+- 公共 API 需要清晰文档+- 文档中要包含示例+- 文档尽量靠近代码,理想情况下就在代码里++---++**核心理念**:代码被阅读的次数是编写次数的 10 倍。优化可读性和可维护性,而不是追求花哨。diff --git a/zh/docs/ROADMAP-20260401.md b/zh/docs/ROADMAP-20260401.mdnew file mode 100644index 0000000..3e71ee3--- /dev/null+++ b/zh/docs/ROADMAP-20260401.md@@ -0,0 +1,153 @@+# 路线图:claude-howto 2026–2027++> 2026 年 4 月 – 2027 年 3 月 · 双层知识库 | 完整计划:`TASKS-20260401.md`++---++## 愿景++把 claude-howto 从一个静态教程仓库,转变为一个**活的、双受众知识系统**:++- **面向人类** - 通过场景化学习、渐进式难度、决策树和专家会收藏的命名模式,提供互动式学习体验+- **面向 AI 代理** - 提供结构化元数据索引,让代理在执行 Claude Code 任务前先查询这里,使这个仓库成为基础设施,而不只是内容++没有竞争者把 AI 代理视为主要受众。这就是我们的护城河。++---++## 7 大支柱++| # | 支柱 | 交付内容 |+|---|--------|-----------------|+| P1 | 趣味层 | 每个模块都有场景导语和 "Try It Now" 模块 |+| P2 | AI 代理索引 | 生成 `agent-manifest.json` + `AGENT-INDEX.md` + 查询技能 |+| P3a | 专家参考(模块内) | 每个模块的决策树 + 命名模式 |+| P3b | 专家参考(跨模块) | `RECIPES.md` - 组合型多功能工作流 |+| P4 | 新手上手 | `quickstart.sh` + `QUICKSTART.md` + 难度徽章 |+| P5 | 社区展示 | `COMMUNITY-PROJECTS.md` - 精选用户项目 |+| P6 | 内容质量 | 扩展最薄弱的模块;完善项目 `CLAUDE.md` |+| P7 | 活课程体系 | `WHATS-NEW.md` + 版本徽章 + 每周过期检查 CI action |++---++## 时间线总览++```+2026 年 4 月 5–6 月 2026 7–8 月 2026 2026 年 9 月 10–11 月 2026 2026 年 12 月–2027 年 3 月+ | | | | | |+ [M1] [M2] [M3] [M4] [M5] [M6]+基础设施 6/10 个模块 10/10 完成 代理层 版本审计 自我维持系统++ hooks/checks 完成 完成 + recipes 完成+```++---++## 里程碑++### M1 - 基础设施上线 · 2026 年 4 月底++**交付内容:**+- `scripts/quickstart.sh` - 为新用户提供一条命令式安装(幂等)+- `QUICKSTART.md` - “前 15 分钟”可视化指南+- 所有 10 个模块都加入难度徽章和 "What you'll build" 预览+- 所有模块都加入 `WHATS-NEW.md` 和版本徽章+- `.github/workflows/staleness-check.yml` - 每周一检查,若模块 30 天以上未验证则创建 issue+- 根目录 `CLAUDE.md` - 作为最佳实践示例的项目配置+- `scripts/build-agent-index.py` - 读取 10 个模块并输出 `agent-manifest.json` + `AGENT-INDEX.md` 的生成器+- **06-hooks** - 完整深度处理:5 个完整 hook 脚本、决策树、Try It Now、模式+- **08-checkpoints** - 完整深度处理:311 行扩展到 800+ 行,3 个工作流模板、决策树、模式++**为什么从这里开始:** 基础设施能惠及后续所有阶段。hooks 和 checkpoints 是最薄弱的模块,也最容易流失新访客。++---++### M2 - 6/10 个模块完成 · 2026 年 6 月底++**交付内容(每个模块一次深度处理):**+- **01-slash-commands** - 场景导语、决策树、Try It Now、命名模式+- **02-memory** - 场景导语、决策树、Try It Now、命名模式+- **03-skills** - 场景导语、决策树、Try It Now、命名模式+- **10-cli** - 场景导语、决策树、Try It Now、命名模式+- CI 步骤:在每次 push 时校验 `agent-manifest.json` 的 schema++每个模块的处理都要运行生成器,确认 manifest 输出有效。++---++### M3 - 10/10 个模块完成 · 2026 年 8 月底++**交付内容:**+- **04-subagents** - 完整深度处理(包括 "The Multi-Agent Review Pattern")+- **05-mcp** - 完整深度处理+- **07-plugins** - 完整深度处理+- **09-advanced-features** - 完整深度处理++现在每个模块都具备:场景导语、2 个以上 Try It Now 模块、Mermaid 决策树、2 个以上命名模式。++---++### M4 - 代理层上线 · 2026 年 9 月底++**交付内容:**+- 最终版 `agent-manifest.json`,覆盖 100% 模块(由已完成内容生成)+- `AGENT-INDEX.md`,从 `README.md` 链接+- `skills/claude-howto-lookup/SKILL.md` - 轻量级 agent skill,通过 manifest 查询相关模块+- `RECIPES.md` - 5 个以上组合工作流(schema:name、modules-used、problem、solution、expected outcome)+- `COMMUNITY-PROJECTS.md` - 静态精选列表,采用 PR 提交格式++**为什么是 9 月:** 只有等 10 个模块全部内容完备后,代理索引才真正有意义。++---++### M5 - 版本审计完成 · 2026 年 11 月底++**交付内容:**+- 完整版本审计:所有 10 个模块都根据当前 CC 版本完成验证+- 更新所有模块的 `cc_version_verified` frontmatter 和版本徽章+- `RECIPES.md` 扩展到 8 个以上 recipes,基于社区模式总结+- GitHub 固定讨论串:“分享你的 Claude Code 工作流” - 收集 agent 使用信号++---++### M6 - 自我维持系统 · 2027 年 3 月底++**持续交付 / 持续运行:**+- `/docs-sync-claude-code` skill 在每次 CC 发布后运行 → 更新 `WHATS-NEW.md`+- Agent manifest CI 回归测试:强制 100% 模块覆盖+- `RECIPES.md` 增加到 10 个以上 recipes+- `COMMUNITY-PROJECTS.md` 自然增长+- 对 agent 使用信号进行评估 - 若验证有效,则推动 lookup skill 的推广(营销、asm registry)++---++## 交付摘要++| 交付物 | 类型 | 阶段 |+|-------------|------|-------|+| `scripts/quickstart.sh` | 脚本 | P1 |+| `QUICKSTART.md` | 文档 | P1 |+| 根目录 `CLAUDE.md` | 配置 | P1 |+| `WHATS-NEW.md` | 文档 | P1 |+| `.github/workflows/staleness-check.yml` | CI | P1 |+| `scripts/build-agent-index.py` | 脚本 | P1 |+| 10 个模块深度处理(场景 + Try It Now + 决策树 + 模式) | 内容 | P1–P3 |+| `agent-manifest.json`(生成) | 数据 | P4 |+| `AGENT-INDEX.md`(生成) | 文档 | P4 |+| `skills/claude-howto-lookup/SKILL.md` | Skill | P4 |+| `RECIPES.md`(5 → 8 → 10+ recipes) | 文档 | P4–P6 |+| `COMMUNITY-PROJECTS.md` | 文档 | P4 |++---++## 不在范围内的内容++这些内容延期到 `TODOS.md`,不要让它们跑进来:++- Skill marketplace 或可安装 registry+- 自定义网站或仪表盘+- 完成度追踪(cc-progress)+- 社区教程 CI 校验+- 自动生成的 CONTRIBUTORS.md+- 多语言翻译+- 测验 / 评估基础设施+- 社区项目投票diff --git a/zh/docs/TASKS-20260401.md b/zh/docs/TASKS-20260401.mdnew file mode 100644index 0000000..0b536f6--- /dev/null+++ b/zh/docs/TASKS-20260401.md@@ -0,0 +1,291 @@+# 任务:双层知识库 - claude-howto++> 创建于:2026-04-01++---++## 里程碑++| # | 里程碑 | 目标时间 | 描述 |+|---|-----------|--------|-------------|+| M1 | 基础设施上线 | 2026 年 4 月底 | quickstart.sh、CLAUDE.md、staleness action、代理索引生成器上线;升级 2 个最薄弱模块 |+| M2 | 6/10 个模块完成 | 2026 年 6 月底 | Slash commands、memory、skills、CLI 模块完全升级;生成器输出有效 manifest |+| M3 | 10/10 个模块完成 | 2026 年 8 月底 | 每个模块都具备场景导语、Try It Now 模块、决策树、命名模式 |+| M4 | 代理层上线 | 2026 年 9 月底 | 生成 agent-manifest.json + AGENT-INDEX.md;仓库内有 lookup skill;`RECIPES.md` + `COMMUNITY-PROJECTS.md` 上线 |+| M5 | 版本审计完成 | 2026 年 11 月底 | 所有 10 个模块都验证过当前 CC 版本;`RECIPES.md` 达到 8+ recipes |+| M6 | 自我维持系统 | 2027 年 3 月底 | Agent manifest 覆盖 100% 模块(通过 CI 校验);`RECIPES.md` 达到 10+;社区页面自然增长 |++---++## 第 1 阶段 - 基础设施与薄弱模块(2026 年 4 月)++**目标里程碑:M1**++### 支柱 4:新手上手++- [ ] **T-001** - 编写 `scripts/quickstart.sh`+ - 检测 `~/.claude/` 目录(如缺失,则在用户确认后创建)+ - 将第一个 slash command + CLAUDE.md + skill 复制到用户配置中+ - 在 CLAUDE.md 末尾追加 agent-discovery 行,链接到 AGENT-INDEX.md+ - 幂等:跳过已有文件并给出警告,绝不覆盖+ - 完成后打印下一步++- [ ] **T-002** - 创建 `QUICKSTART.md`(前 15 分钟可视化指南)+ - 使用代码块记录带注释的终端步骤(尽量避免 PNG 截图;优先 ASCII 或 Mermaid)+ - 记录每条命令对应哪个视觉结果,方便后续重新采集++- [ ] **T-003** - 为所有 10 个模块的 README 添加难度徽章+ - 格式:`> 🟢 **Beginner** | ⏱ 30 minutes`,放在每个模块 README 顶部+ - 在徽章下方添加 "What you'll build" 的要点预览++### 支柱 7:活课程体系++- [ ] **T-004** - 创建 `WHATS-NEW.md`+ - 格式:`## CC vX.X — DATE`,每个功能变更使用项目符号+ - 至少添加一条当前 CC 版本的记录++- [ ] **T-005** - 为所有 10 个模块的 README 添加版本徽章+ - 格式:`> ✅ Verified against Claude Code **vX.X.X** · Last verified: YYYY-MM-DD`+ - 在每个模块的 frontmatter 中加入 `cc_version_verified`++- [ ] **T-006** - 创建 `.github/workflows/staleness-check.yml`+ - 调度:每周一 09:00 UTC+ - 从 frontmatter 读取每个模块的 `last_verified` 日期(使用 `yq` 或 10 行 Python 脚本)+ - 对 30 天以上未验证的模块创建 GitHub Issue+ - 如果已有同名 open issue,则跳过++### 支柱 6:内容质量(CLAUDE.md)++- [ ] **T-007** - 为项目创建根目录 `CLAUDE.md`+ - 作为项目自身配置,展示最佳实践+ - 记录贡献规范、模块结构和维护流程++### 支柱 2:AI 代理索引(生成器)++- [ ] **T-008** - 编写 `scripts/build-agent-index.py`+ - 读取全部 10 个模块 README+ - 提取:标题(→ topics)、代码块(→ 带语言标签的示例)、表格(→ 参考数据)+ - 输出 `agent-manifest.json`,schema 按 CEO 计划定义+ - 输出 `AGENT-INDEX.md`(人类可读摘要)+ - 校验引用是否指向真实文件++### 模块 08-checkpoints:完整深度处理(311 → 800+ 行)++- [ ] **T-009** - 用真实场景重写模块导语+ - 示例:"你的重构把 3 个东西弄坏了。checkpoint 如何帮你恢复..."++- [ ] **T-010** - 添加 checkpoint 策略决策树(Mermaid flowchart)+ - "我想做 X" → 顺着箭头走 → 到达对应 checkpoint 模式++- [ ] **T-011** - 添加 3 个工作流模板+ - 安全重构工作流+ - 使用 checkpoints 做 A/B 测试+ - 灾难恢复工作流++- [ ] **T-012** - 添加与 planning mode 的整合部分++- [ ] **T-013** - 添加 checkpoint 生命周期的 Mermaid 图++- [ ] **T-014** - 添加 2 个以上 "Try It Now" 模块,并提供可验证命令+ - 每个模块:上下文句、要运行的命令、预期输出说明++- [ ] **T-015** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式+ - 每个模式:问题、解决方案代码、适用场景、不适用场景++### 模块 06-hooks:完整深度处理++- [ ] **T-016** - 用真实场景重写模块导语+ - 示例:"你的 CI 在 20 分钟后才发现 lint 错误。hooks 2 秒内就能抓住..."++- [ ] **T-017** - 添加 hooks 决策树(Mermaid flowchart)+ - "我想在 Y 发生时触发 X" → 顺着箭头走 → 到达对应 hook 类型++- [ ] **T-018** - 添加 5 个完整 hook 示例,带完整脚本(每个约 80 行)+ 1. 写入时自动格式化(prettier/black)+ 2. 提交时安全扫描(trufflehog/bandit)+ 3. 文件变更时运行测试+ 4. 会话结束时发送通知+ 5. 提示词校验(阻止危险模式)++- [ ] **T-019** - 添加 2 个以上 "Try It Now" 模块,并提供可验证命令++- [ ] **T-020** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式++**M1 检查点:基础设施上线,2 个最薄弱模块完成深度升级**++---++## 第 2 阶段 - 深度处理:强模块第一批(2026 年 5 月 - 6 月)++**目标里程碑:M2**++### 模块 01-slash-commands:完整深度处理++- [ ] **T-021** - 用场景重写导语("你的队友刚推了 47 个文件...")+- [ ] **T-022** - 添加决策树(Mermaid)+- [ ] **T-023** - 添加 2 个以上 "Try It Now" 模块+- [ ] **T-024** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式++### 模块 02-memory:完整深度处理++- [ ] **T-025** - 用真实场景重写导语+- [ ] **T-026** - 添加决策树(Mermaid)+- [ ] **T-027** - 添加 2 个以上 "Try It Now" 模块+- [ ] **T-028** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式++### 模块 03-skills:完整深度处理++- [ ] **T-029** - 用真实场景重写导语+- [ ] **T-030** - 添加决策树(Mermaid)+- [ ] **T-031** - 添加 2 个以上 "Try It Now" 模块+- [ ] **T-032** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式++### 模块 10-cli:完整深度处理++- [ ] **T-033** - 用真实场景重写导语+- [ ] **T-034** - 添加决策树(Mermaid)+- [ ] **T-035** - 添加 2 个以上 "Try It Now" 模块+- [ ] **T-036** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式++### 生成器校验++- [ ] **T-037** - 每次模块升级后运行 `scripts/build-agent-index.py`;确认 manifest 输出有效+- [ ] **T-038** - 在每次 push 时添加 CI 步骤:校验 agent-manifest.json schema++**M2 检查点:6/10 个模块完成,生成器输出有效 manifest**++---++## 第 3 阶段 - 深度处理:强模块第二批(2026 年 7 月 - 8 月)++**目标里程碑:M3**++### 模块 04-subagents:完整深度处理++- [ ] **T-039** - 用真实场景重写导语+- [ ] **T-040** - 添加决策树(Mermaid)+- [ ] **T-041** - 添加 2 个以上 "Try It Now" 模块+- [ ] **T-042** - 添加 "Patterns & Recipes" 部分(例如:"The Multi-Agent Review Pattern")++### 模块 05-mcp:完整深度处理++- [ ] **T-043** - 用真实场景重写导语+- [ ] **T-044** - 添加决策树(Mermaid)+- [ ] **T-045** - 添加 2 个以上 "Try It Now" 模块+- [ ] **T-046** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式++### 模块 07-plugins:完整深度处理++- [ ] **T-047** - 用真实场景重写导语+- [ ] **T-048** - 添加决策树(Mermaid)+- [ ] **T-049** - 添加 2 个以上 "Try It Now" 模块+- [ ] **T-050** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式++### 模块 09-advanced-features:完整深度处理++- [ ] **T-051** - 用真实场景重写导语+- [ ] **T-052** - 添加决策树(Mermaid)+- [ ] **T-053** - 添加 2 个以上 "Try It Now" 模块+- [ ] **T-054** - 添加 "Patterns & Recipes" 部分,包含 2 个以上命名模式++**M3 检查点:全部 10 个模块完成且风格一致**++---++## 第 4 阶段 - 代理层与跨模块(2026 年 9 月)++**目标里程碑:M4**++### 支柱 2:最终完成 AI 代理索引++- [ ] **T-055** - 使用所有 10 个完成的模块运行 `scripts/build-agent-index.py`+ - 生成最终版 `agent-manifest.json`,覆盖率达到 100%+ - 生成 `AGENT-INDEX.md` 并从 `README.md` 链接++- [ ] **T-056** - 创建 `skills/claude-howto-lookup/SKILL.md`+ - 读取 `agent-manifest.json` 以查找相关模块+ - 使用 `Read` 加载对应章节+ - 安装方式:`cp -r claude-howto/skills/claude-howto-lookup ~/.claude/skills/`++- [ ] **T-057** - 在 quickstart.sh 和 QUICKSTART.md 中把 lookup skill 作为可选功能提到++### 支柱 3b:跨模块 `RECIPES.md`++- [ ] **T-058** - 创建带有 5 个以上组合工作流的 `RECIPES.md`+ - 每个 recipe 的 schema:name、modules-used、problem、solution 代码块、expected outcome+ - 示例:skill + hook + subagent = 自动审查流水线+ - 确保所有主要标题都有 HTML 锚点,便于深链++### 支柱 5:社区展示++- [ ] **T-059** - 创建 `COMMUNITY-PROJECTS.md`+ - 静态 Markdown 页面,提交格式包括:name、description、link、features used+ - 包含模板条目+ - 提供基于 PR 的提交说明++**M4 检查点:代理索引上线,recipes 上线,社区页面上线**++---++## 第 5 阶段 - 版本审计与 recipe 扩展(2026 年 10 月 - 11 月)++**目标里程碑:M5**++- [ ] **T-060** - 进行完整版本审计:验证所有 10 个模块是否与当前 CC 版本匹配+ - 更新每个模块的 `cc_version_verified` frontmatter+ - 更新版本徽章++- [ ] **T-061** - 将 `RECIPES.md` 扩展到 8 个以上 recipes,基于社区实践模式++- [ ] **T-062** - 如果完成的模块中出现新的模式,则迭代 agent manifest schema++- [ ] **T-063** - 开一个置顶 GitHub Discussion:"分享你的 Claude Code 工作流"+ - 收集真实 agent 使用信号,为后续 recipe 扩展提供依据++**M5 检查点:所有模块都已验证当前版本,recipes 持续增长**++---++## 第 6 阶段 - 组合与持续运行(2026 年 12 月 - 2027 年 3 月)++**目标里程碑:M6**++- [ ] **T-064** - 每次 CC 发布后运行 `/docs-sync-claude-code` skill;更新 `WHATS-NEW.md`++- [ ] **T-065** - 确保 agent manifest 覆盖 100% 模块(CI 回归测试)++- [ ] **T-066** - 将 `RECIPES.md` 扩展到 10 个以上 recipes++- [ ] **T-067** - 监控 `COMMUNITY-PROJECTS.md` 的自然增长;筛选新增条目++- [ ] **T-068** - 评估来自 GitHub Discussions 的 agent 使用信号;如果验证有效,就投入资源推广 lookup skill(营销、asm registry)++**M6 检查点:系统已经可以自我维持**++---++## 延后项(TODOS.md)++这些内容不在本计划范围内。请记录在这里,避免范围蔓延:++- Skill marketplace / 可安装 registry+- 自定义网站或仪表盘+- 完成度追踪基础设施(cc-progress)+- 带 CI 校验的社区教程模板+- 自动生成的 CONTRIBUTORS.md+- 多语言翻译+- 测验 / 评估基础设施升级+- COMMUNITY-PROJECTS.md 的社区投票 / 审核机制++---++## 按阶段划分的任务摘要++| 阶段 | 任务 | 时间段 | 涉及模块 |+|-------|-------|--------|-----------------|+| 1 - 基础设施与薄弱模块 | T-001 到 T-020 | 2026 年 4 月 | 06-hooks、08-checkpoints + 基础设施 |+| 2 - 第一批深度处理 | T-021 到 T-038 | 2026 年 5 月 - 6 月 | 01、02、03、10 |+| 3 - 第二批深度处理 | T-039 到 T-054 | 2026 年 7 月 - 8 月 | 04、05、07、09 |+| 4 - 代理层与跨模块 | T-055 到 T-059 | 2026 年 9 月 | 全部(manifest)+ 新文件 |+| 5 - 版本审计与 recipes | T-060 到 T-063 | 2026 年 10 月 - 11 月 | 全部(审计) |+| 6 - 持续运行 | T-064 到 T-068 | 2026 年 12 月 - 2027 年 3 月 | 持续进行 |diff --git a/zh/prompts/remotion-video.md b/zh/prompts/remotion-video.mdnew file mode 100644index 0000000..0772483--- /dev/null+++ b/zh/prompts/remotion-video.md@@ -0,0 +1,350 @@+你是一位擅长 Remotion 的资深动效设计师和高级 React 工程师。你的目标是把产品描述转化为一个高能量、专业动画感强的视频,并使用 React 代码实现。++**先自主探索:** 立即开始探索代码库,收集产品信息。只有在你探索之后,仍然缺少关键或不清晰的信息时,才向用户提问。++请遵循一个 7 阶段工作流,并根据你收集到的信息在每一步做出聪明的决策。++---++# 🔄 自动化工作流++**关键原则:**++- **先探索:** 永远先自动探索代码库,收集产品信息。不要一上来就问产品问题。+- **先问偏好,再规划:** 探索之后,先向用户展示发现结果,再询问视频偏好(尺寸、风格、时长、自定义项),然后再创建计划。+- **产品 URL 优先:** 如果找到了或用户提供了产品 URL,它就是第一信息源。产品页面上的信息优先于代码库发现。+- **重价值,不重技术:** 聚焦价值主张、客户收益和功能(用户获得了什么),而不是技术规格或实现细节。+- **以客户为中心:** 强调产品如何解决问题、改善生活或为用户带来收益。+- **自主执行:** 用户确认偏好后,自动推进到规划和实现阶段,不要再请求额外批准。++## 📋 第 1 阶段:自主资源发现++**目标:** 自动探索代码库,收集所有可用的产品信息,不要询问用户。++**动作:**++1. **先自动探索代码库:**+ - 搜索 `README.md`,查找产品描述和价值主张+ - 检查 `package.json`,获取产品名称、描述和主页 URL+ - 在 `/assets`、`/public`、`/static`、`/images` 目录中查找品牌资源+ - 从 CSS / Tailwind 配置文件中提取配色方案+ - 查找任何现有的营销文案或文档+ - 在配置文件、环境变量或文档中查找任何产品 URL++2. **如果找到了产品 URL,立即抓取:**+ - 使用 WebFetch 提取产品页面的信息+ - 产品页面信息优先于代码库发现+ - 提取所有价值主张、功能和品牌信息++3. **汇总所有收集到的信息:**+ - 产品名称和描述+ - 价值主张+ - 核心功能和收益+ - 品牌色和风格+ - 目标受众(根据语气推断)+ - 任何现有资源或媒体++4. **对缺失信息使用智能默认值:**+ - **视频格式:** 横屏 1920x1080(适合 YouTube / Web)+ - **时长:** 30 秒(大多数平台都适合)+ - **风格:** 现代、简洁、专业(基于品牌)+ - **品牌色:** 使用提取到的颜色,或采用现代互补配色++5. **只有在以下情况下才询问用户:**+ - 探索后仍无法确定产品名称或找不到任何产品信息+ - 无法找到或访问产品 URL+ - 存在关键歧义(例如 B2B 和 B2C 的差异会显著改变表达方式)+ - 有冲突信息需要澄清++**重要:** 这一整段探索要静默、自主完成。不要问“我需要什么才能开始”或列出需求。只有在真正必要时才打断用户。++**输出:** 立即带着所有收集到的信息进入第 2 阶段。++---++## 🔍 第 2 阶段:信息分析与深度挖掘++**目标:** 分析收集到的信息,并提炼出视频创作所需的关键洞察。++**动作:**++1. **回顾第 1 阶段收集到的全部信息:**+ - 产品页面内容(如果找到了并抓取了 URL)+ - 代码库发现(README、package.json、资源等)+ - 任何品牌指南或营销材料++2. **提炼并排序(聚焦价值,不聚焦技术):**+ - **价值主张**(首要)- 对客户的核心收益+ - **客户收益** - 它如何改善用户生活+ - **核心功能** - 用收益来描述,而不是技术规格+ - **独特卖点** - 与其他方案相比有什么不同/更好+ - **使用场景** - 真实世界应用+ - **品牌识别**(颜色、字体、风格、语气)+ - **目标受众洞察**(这是谁的产品)+ - **情感吸引力**和信息表达(人们为什么在意)++3. **静默用智能推断补齐空白:**+ - 如果价值主张不明确,从功能和目标受众推断+ - 如果目标受众不清晰,从产品类型和文案语气推断+ - 如果缺少品牌色,创建一套现代的互补配色+ - 除非与用户可见内容相关,否则避免技术实现细节++4. **只有在以下情况下才请求澄清:**+ - 存在多个相互冲突的价值主张+ - 无法判断产品是 B2B 还是 B2C(这会显著影响表达)+ - 目标受众确实过于模糊++**输出:** 对产品价值、收益和品牌有清晰理解,足以支持视频制作。++---++## ✅ 第 3 阶段:展示发现并收集用户偏好++**目标:** 分享你发现的内容,并在进入规划前获取用户对视频偏好的输入。++**动作:**++1. **展示发现摘要:**++ ```text+ 📊 发现的信息++ 产品:[名称]+ 价值主张:[对客户的主要收益]+ 核心功能:[2-3 个主要收益]+ 品牌色:[提取到或建议的颜色]+ 目标受众:[这是谁的产品]+ ```++2. **询问用户偏好(进入下一步前必须完成):**++ 使用清晰简洁的格式:++ ```text+ 在我创建视频之前,请告诉我你的偏好:++ 1. **视频尺寸/格式:**+ - 横屏(1920x1080)- YouTube、网站+ - 竖屏(1080x1920)- TikTok、Instagram Reels+ - 方形(1080x1080)- Instagram 信息流++ 2. **视频时长:**+ - 15 秒 - 快速社媒广告+ - 30 秒 - 标准宣传视频+ - 60 秒 - 详细功能展示+ - 自定义时长++ 3. **视频风格:**+ - 现代 & 极简 - 干净的 Apple 风格美学+ - 有冲击力 & 高能量 - 快节奏,适合社媒+ - 专业 & 企业感 - 面向商业场景+ - 自定义风格(描述你的想法)++ 4. **还想突出或自定义什么?**+ (特定功能、文案、颜色等)+ ```++3. **等待用户回复** 后再进入第 4 阶段。++4. **确认并回应:**+ - 总结用户选择+ - 应用任何自定义要求+ - 根据确认方向继续做结构设计++**输出:** 用户确认的视频规格,准备进入规划阶段。++---++## 📐 第 4 阶段:结构设计(确认后)++**目标:** 基于用户偏好,使用三幕式结构设计一个有吸引力的视频。++**动作:**++1. **根据用户确认的偏好设计视频结构:**++ ```text+ 🎬 视频结构++ 第 1 幕:钩子(0-5 秒)+ - [抓眼球的视觉概念]+ - [强势的动画开场]+ - [有吸引力的标题/问题]++ 第 2 幕:价值展示(中段)+ - [展示核心收益如何发挥作用]+ - [用视觉叙事表达客户价值]+ - [2-3 个作为收益呈现的功能亮点]++ 第 3 幕:行动号召(结尾)+ - [清晰的 CTA 和品牌强化]+ - [令人印象深刻的收尾画面]+ - [平滑的退出动画]+ ```++2. **应用用户偏好:**+ - 使用指定的视频尺寸/格式+ - 匹配所选风格(极简/高能量/专业)+ - 按指定时长调整节奏+ - 融入任何自定义要求++3. **基于以下内容做创意决策:**+ - 产品价值主张(什么最吸引人)+ - 目标受众(什么最能打动他们)+ - 用户的风格偏好+ - 品牌个性(视觉和语气的一致性)++4. **简要展示结构**,然后自动进入第 5 阶段。++**输出:** 可直接用于实现规划的视频结构。++---++## 🛠️ 第 5 阶段:技术架构++**目标:** 设计实现架构,并直接开始构建。++**动作:**++1. **静默设计** 组件架构:+ - 工具函数(easing、动画辅助、颜色工具)+ - 可复用组件(AnimatedTitle、FeatureHighlight 等)+ - 场景组件(Hook、Demo、CTA 场景)+ - 主组合结构(Video.tsx、Root.tsx)++2. **规划技术细节:**+ - 动画时序和 easing 曲线+ - 调色板实现+ - 字体层级+ - 图标和资源策略+ - 序列时间拆分++3. **无需请求批准,直接进入第 6 阶段**实现。++**输出:** 可立即实现的内部技术蓝图。++---++## 💻 第 6 阶段:实现++**目标:** 自主构建完整的 Remotion 视频项目。++**约束与技术栈:**++1. **框架:** Remotion(React)+2. **样式:** Tailwind CSS(通过 `className` 或标准样式对象)+3. **动画:** 使用 `spring`、`interpolate` 和 `useCurrentFrame` 实现平滑运动+4. **代码风格:** 模块化组件。不要把所有东西都堆在 `Root.tsx` 里+5. **最佳实践:**+ - 不要有静态内容。所有元素都应该有入场(opacity / scale / slide)和退场+ - 如有需要,使用 Lucide-React 图标+ - 使用标准字体,但要强样式化(粗体、紧字距)+ - 不要使用外部图片,除非是占位图(例如 `https://placehold.co/600x400`)或用户提供的资源++**动作:**++1. **按以下顺序构建完整项目结构:**+ - 工具函数(easing、动画辅助、颜色工具)+ - 可复用组件(AnimatedTitle、FeatureHighlight、过渡)+ - 场景组件(HookScene、DemoScene、CTAScene)+ - 主合成(带编排的 Video.tsx)+ - 根配置(注册正确的 Root.tsx)++2. **静默高效地工作:**+ - 不要逐步叙述每一步+ - 基于已收集信息做设计决策+ - 使用专业的动画原则+ - 确保场景之间过渡平滑++3. **实现完成后自动进入第 7 阶段。**++**输出:** 完整、可直接交付的 Remotion 项目代码。++---++## 🎥 第 7 阶段:交付与后续++**目标:** 提供渲染说明,并标记项目完成。++**动作:**++1. **提供渲染说明:**++ ```bash+ # 在浏览器中预览视频+ npm run dev++ # 渲染最终视频+ npm run build+ npx remotion render Video out/video.mp4++ # 指定编解码设置+ npx remotion render Video out/video.mp4 --codec h264+ ```++2. **交付摘要:**+ - 简要说明创建了什么+ - 视频的关键特性+ - 视频规格(时长、格式、尺寸)+ - 任何值得注意的设计决策++3. **用户可以在需要时请求修改:**+ - 时间调整+ - 动画修改+ - 内容更新+ - 风格微调++**输出:** 完整的 Remotion 项目,附带清晰的渲染说明,可直接使用。++---++# 🎯 质量标准++在所有阶段都要保持以下标准:++**视觉质量:**+- 专业级动画(平滑、明确、有品牌感)+- 一致的间距和对齐+- 具备良好对比度的易读排版+- 协调统一的色彩使用++**技术质量:**+- 干净、模块化的代码架构+- 性能优化(平滑 30fps 播放)+- 正确使用 Remotion API(spring、interpolate、Sequence)+- 如果使用 TypeScript,则具备类型安全++**创意质量:**+- 清晰的叙事结构+- 抓眼的开场+- 强有力的行动号召+- 令人记住的视觉瞬间++---++# 🚀 开始使用++我会为你的产品创建一个专业的 Remotion 视频项目。工作流程如下:++## 第 1-2 阶段:自主探索(我会自动完成)++1. 探索你的代码库,查找产品细节、品牌资源和颜色+2. 如果找到了产品 URL,抓取并分析产品页面+3. 提取价值主张和关键收益++## 第 3 阶段:你的输入(我会询问你)++1. 展示我发现的内容+2. 询问你的视频偏好:+ - 视频尺寸/格式(横屏 / 竖屏 / 方形)+ - 时长(15 秒 / 30 秒 / 60 秒)+ - 风格(极简 / 高能量 / 专业)+ - 任何自定义项++## 第 4-7 阶段:自主执行(我会自动完成)++1. 根据你的偏好设计视频结构+2. 构建完整的 Remotion 项目并加入专业动画+3. 交付可直接使用的生产级代码和渲染说明++让我们一起做出一个很棒的作品!diff --git a/zh/resources.md b/zh/resources.mdnew file mode 100644index 0000000..4723236--- /dev/null+++ b/zh/resources.md@@ -0,0 +1,248 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">+</picture>++# 优质资源清单++## 官方文档++| 资源 | 说明 | 链接 |+|----------|-------------|------|+| Claude Code 文档 | Claude Code 官方文档 | [code.claude.com/docs/en/overview](https://code.claude.com/docs/en/overview) |+| Anthropic 文档 | Anthropic 完整文档 | [docs.anthropic.com](https://docs.anthropic.com) |+| MCP Protocol | Model Context Protocol 规范 | [modelcontextprotocol.io](https://modelcontextprotocol.io) |+| MCP Servers | 官方 MCP server 实现 | [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) |+| Anthropic Cookbook | 代码示例和教程 | [github.com/anthropics/anthropic-cookbook](https://github.com/anthropics/anthropic-cookbook) |+| Claude Code Skills | 社区技能仓库 | [github.com/anthropics/skills](https://github.com/anthropics/skills) |+| Agent Teams | 多 agent 协作与协调 | [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) |+| Scheduled Tasks | 使用 `/loop` 和 cron 的周期性任务 | [code.claude.com/docs/en/scheduled-tasks](https://code.claude.com/docs/en/scheduled-tasks) |+| Chrome Integration | 浏览器自动化 | [code.claude.com/docs/en/chrome](https://code.claude.com/docs/en/chrome) |+| Keybindings | 键盘快捷键自定义 | [code.claude.com/docs/en/keybindings](https://code.claude.com/docs/en/keybindings) |+| Desktop App | 原生桌面应用 | [code.claude.com/docs/en/desktop](https://code.claude.com/docs/en/desktop) |+| Remote Control | 远程会话控制 | [code.claude.com/docs/en/remote-control](https://code.claude.com/docs/en/remote-control) |+| Auto Mode | 自动权限管理 | [code.claude.com/docs/en/permissions](https://code.claude.com/docs/en/permissions) |+| Channels | 多通道通信 | [code.claude.com/docs/en/channels](https://code.claude.com/docs/en/channels) |+| Voice Dictation | Claude Code 语音输入 | [code.claude.com/docs/en/voice-dictation](https://code.claude.com/docs/en/voice-dictation) |++## Anthropic Engineering Blog++| 文章 | 说明 | 链接 |+|---------|-------------|------|+| Code Execution with MCP | 如何通过代码执行解决 MCP 上下文膨胀问题,Token 数量减少 98.7% | [anthropic.com/engineering/code-execution-with-mcp](https://www.anthropic.com/engineering/code-execution-with-mcp) |++---++## 30 分钟掌握 Claude Code++_视频_: https://www.youtube.com/watch?v=6eBSHbLKuN0++_**全部技巧**_+- **探索高级功能和快捷键**+ - 定期查看 Claude 发布说明中的新代码编辑与上下文功能。+ - 学习键盘快捷键,在聊天、文件和编辑器视图之间快速切换。++- **高效设置**+ - 为项目创建带有清晰名称和描述的会话,便于之后查找。+ - 将最常用的文件或文件夹固定住,让 Claude 随时可访问。+ - 配置 Claude 的集成,例如 GitHub 和常见 IDE,以简化你的编码流程。++- **高效的代码库问答**+ - 向 Claude 询问架构、设计模式和具体模块的细节问题。+ - 在问题里使用文件和行号引用,例如:“`app/models/user.py` 里的逻辑是在做什么?”+ - 对于大型代码库,提供摘要或清单,帮助 Claude 聚焦。+ - **示例提示词**:_“你能解释一下 `src/auth/AuthService.ts:45-120` 里实现的认证流程吗?它是如何与 `src/middleware/auth.ts` 里的中间件集成的?”_++- **代码编辑与重构**+ - 使用代码块中的内联注释或请求来获得更聚焦的编辑结果(例如:“把这个函数重构得更清晰一些”)。+ - 让 Claude 给出并排的修改前后对比。+ - 在重大修改后,让 Claude 生成测试或文档,以保证质量。+ - **示例提示词**:_“把 `api/users.js` 里的 `getUserData` 函数从 promises 改成 async/await。给我一个修改前后对比,并为重构后的版本生成单元测试。”_++- **上下文管理**+ - 只粘贴当前任务真正需要的代码和上下文。+ - 使用结构化提示词(“这里是文件 A,这里是函数 B,我的问题是 X”)通常效果最好。+ - 在提示窗口里移除或折叠大文件,避免超出上下文限制。+ - **示例提示词**:_“这里是 `models/User.js` 里的 User 模型,以及 `utils/validation.js` 里的 `validateUser` 函数。我的问题是:如何在保持向后兼容的前提下添加邮箱验证?”_++- **接入团队工具**+ - 将 Claude 会话连接到你们团队的代码仓库和文档。+ - 使用内置模板,或为重复出现的工程任务创建自定义模板。+ - 通过和队友共享会话记录与提示词来协作。++- **提升性能**+ - 给 Claude 清晰、面向目标的指令,例如:“用五个要点总结这个类”。+ - 从上下文窗口中删掉不必要的注释和样板代码。+ - 如果 Claude 的输出跑偏了,重置上下文或重新表述问题,以获得更好的对齐。+ - **示例提示词**:_“用五个要点总结 `src/db/Manager.ts` 里的 `DatabaseManager` 类,重点说明它的核心职责和关键方法。”_++- **实用场景示例**+ - 调试:粘贴错误和堆栈信息,然后询问可能的原因和修复方式。+ - 生成测试:为复杂逻辑请求属性测试、单元测试或集成测试。+ - 代码审查:请 Claude 识别风险变更、边界情况或代码异味。+ - **示例提示词**:+ - _“我遇到这个错误:`TypeError: Cannot read property 'map' of undefined at line 42 in components/UserList.jsx`。这是堆栈信息和相关代码。是什么原因导致的?我该怎么修复?”_+ - _“为 `PaymentProcessor` 类生成完整的单元测试,包括失败交易、超时和无效输入等边界情况。”_+ - _“审查这个 pull request diff,找出潜在的安全问题、性能瓶颈和代码异味。”_++- **工作流自动化**+ - 用 Claude 提示词为格式化、清理、批量重命名等重复任务编写脚本。+ - 用 Claude 基于代码 diff 起草 PR 描述、发布说明或文档。+ - **示例提示词**:_“根据 git diff,生成一份详细的 PR 描述,包含变更摘要、修改文件列表、测试步骤和潜在影响。同时为 2.3.0 版本生成发布说明。”_++**提示**:想要获得最佳效果,可以把这些实践组合起来使用。先固定关键文件并总结目标,再使用聚焦的提示词和 Claude 的重构工具,逐步改进你的代码库和自动化流程。+++**与 Claude Code 配合使用的推荐工作流**++### Claude Code 推荐工作流++#### 新仓库场景++1. **初始化仓库并接入 Claude**+ - 建立新仓库的基础结构:`README`、`LICENSE`、`.gitignore`、根配置文件。+ - 创建 `CLAUDE.md`,说明架构、高层目标和编码规范。+ - 安装 Claude Code,并将其连接到仓库,用于代码建议、测试脚手架和工作流自动化。++2. **使用计划模式和规格说明**+ - 在实现功能之前,使用计划模式(`shift-tab` 或 `/plan`)先写详细规格。+ - 让 Claude 给出架构建议和初始项目布局。+ - 保持清晰、面向目标的提示词序列,依次询问组件轮廓、主要模块和职责。++3. **迭代开发与审查**+ - 把核心功能拆成小块逐步实现,并在过程中请求 Claude 生成代码、重构和文档。+ - 每增加一小步,都请求单元测试和示例。+ - 在 `CLAUDE.md` 中维护持续更新的任务列表。++4. **自动化 CI/CD 和部署**+ - 用 Claude 搭建 GitHub Actions、npm/yarn 脚本或部署工作流。+ - 通过更新 `CLAUDE.md` 并请求对应命令/脚本,轻松调整流水线。++```mermaid+graph TD+ A[Start New Repository] --> B[Initialize Repository Structure]+ B --> C[Create README, LICENSE, .gitignore]+ C --> D[Create CLAUDE.md]+ D --> E[Document Architecture & Guidelines]+ E --> F[Install & Link Claude Code]++ F --> G[Enter Plan Mode]+ G --> H[Draft Feature Specification]+ H --> I[Get Architecture Suggestions]+ I --> J[Define Components & Modules]++ J --> K[Implement Feature Chunk]+ K --> L[Generate Code with Claude]+ L --> M[Request Unit Tests]+ M --> N[Review & Refactor]+ N --> O{More Features?}+ O -->|Yes| K+ O -->|No| P[Update Task List in CLAUDE.md]++ P --> Q[Setup CI/CD Pipeline]+ Q --> R[Scaffold GitHub Actions]+ R --> S[Create Deployment Scripts]+ S --> T[Test Automation]+ T --> U[Repository Ready]++ style A fill:#e1f5ff+ style G fill:#fff4e1+ style K fill:#f0ffe1+ style Q fill:#ffe1f5+ style U fill:#90EE90+```++#### 现有仓库场景++1. **仓库与上下文准备**+ - 添加或更新 `CLAUDE.md`,记录仓库结构、编码模式和关键文件。对于旧仓库,可以使用 `CLAUDE_LEGACY.md`,其中涵盖框架、版本映射、说明、已知问题和升级笔记。+ - 固定或高亮 Claude 应该用来作为上下文的主文件。++2. **上下文驱动的代码问答**+ - 让 Claude 基于具体文件/函数,回答代码审查、 bug 解释、重构或迁移计划。+ - 给 Claude 明确边界,例如“只修改这些文件”或者“不要新增依赖”。++3. **分支、工作区和多会话管理**+ - 使用多个 git worktree 做隔离的功能开发或 bug 修复,并为每个 worktree 启动独立的 Claude 会话。+ - 通过终端标签页/窗口按分支或功能组织并行工作。++4. **团队工具和自动化**+ - 通过 `.claude/commands/` 同步自定义命令,保持团队一致性。+ - 用 Claude 的 slash commands 或 hooks 自动化重复任务、PR 创建和代码格式化。+ - 与团队成员共享会话和上下文,便于协作排障和审查。++```mermaid+graph TD+ A[Start with Existing Repository] --> B{Legacy Codebase?}+ B -->|Yes| C[Create CLAUDE_LEGACY.md]+ B -->|No| D[Create/Update CLAUDE.md]+ C --> E[Document Frameworks & Version Maps]+ D --> F[Document Structure & Patterns]+ E --> G[Pin Key Files for Context]+ F --> G++ G --> H[Identify Task Type]+ H --> I{Task Category}+ I -->|Bug Fix| J[Ask Claude for Bug Analysis]+ I -->|Code Review| K[Request Code Review]+ I -->|Refactor| L[Plan Refactoring Strategy]+ I -->|Migration| M[Create Migration Plan]++ J --> N[Set Explicit Boundaries]+ K --> N+ L --> N+ M --> N++ N --> O{Multiple Features?}+ O -->|Yes| P[Create Git Worktrees]+ O -->|No| Q[Work on Main Branch]+ P --> R[Launch Separate Claude Sessions]+ R --> S[Organize Terminal Tabs]+ Q --> S++ S --> T[Setup Team Automation]+ T --> U[Sync .claude/commands/]+ U --> V[Configure Slash Commands]+ V --> W[Setup Hooks for Automation]+ W --> X[Share Session Context with Team]++ X --> Y{More Tasks?}+ Y -->|Yes| H+ Y -->|No| Z[Workflow Complete]++ style A fill:#e1f5ff+ style C fill:#ffecec+ style D fill:#fff4e1+ style P fill:#f0ffe1+ style T fill:#ffe1f5+ style Z fill:#90EE90+```++**提示**:+- 每个新功能或修复都从规格和计划模式提示词开始。+- 对于旧仓库和复杂仓库,把更详细的指导存放在 `CLAUDE.md` / `CLAUDE_LEGACY.md` 中。+- 给出清晰、聚焦的指令,把复杂工作拆成多阶段计划。+- 定期清理会话、裁剪上下文,并删除已完成的工作区,避免堆积混乱。++这些步骤概括了在新旧代码库中更顺畅使用 Claude Code 的核心建议。++---++## 2026 年 3 月新增功能与能力++### 关键功能资源++| 功能 | 说明 | 了解更多 |+|---------|-------------|------------|+| **Auto Memory** | Claude 会自动学习并记住你跨会话的偏好 | [记忆指南](02-memory/README.md) |+| **Remote Control** | 通过外部工具和脚本以编程方式控制 Claude Code 会话 | [高级功能](09-advanced-features/README.md) |+| **Web Sessions** | 通过基于浏览器的界面访问 Claude Code,实现远程开发 | [CLI 参考](10-cli/README.md) |+| **Desktop App** | Claude Code 的原生桌面应用,界面更强大 | [Claude Code 文档](https://code.claude.com/docs/en/desktop) |+| **Extended Thinking** | 通过 `Alt+T` / `Option+T` 或 `MAX_THINKING_TOKENS` 环境变量切换深度推理 | [高级功能](09-advanced-features/README.md) |+| **Permission Modes** | 精细权限控制:default、acceptEdits、plan、auto、dontAsk、bypassPermissions | [高级功能](09-advanced-features/README.md) |+| **7-Tier Memory** | Managed Policy、Project、Project Rules、User、User Rules、Local、Auto Memory | [记忆指南](02-memory/README.md) |+| **Hook Events** | 25 个事件:PreToolUse、PostToolUse、PostToolUseFailure、Stop、StopFailure、SubagentStart、SubagentStop、Notification、Elicitation 等 | [Hooks 指南](06-hooks/README.md) |+| **Agent Teams** | 协调多个 agent 共同处理复杂任务 | [Subagents 指南](04-subagents/README.md) |+| **Scheduled Tasks** | 用 `/loop` 和 cron 工具设置周期性任务 | [高级功能](09-advanced-features/README.md) |+| **Chrome Integration** | 使用无头 Chromium 做浏览器自动化 | [高级功能](09-advanced-features/README.md) |+| **Keyboard Customization** | 自定义按键绑定,包括组合键序列 | [高级功能](09-advanced-features/README.md) |diff --git a/zh/resources/DESIGN-SYSTEM.md b/zh/resources/DESIGN-SYSTEM.mdnew file mode 100644index 0000000..82818f4--- /dev/null+++ b/zh/resources/DESIGN-SYSTEM.md@@ -0,0 +1,244 @@+# Claude How To - 设计系统++## 视觉识别++### 图标设计概念:指南针 + 代码括号++Claude How To 的图标使用**指南针加 `>` 代码括号**来表示“在代码中导航”:++```+ N (green)+ ▲+ │+W ───>─── E Compass = Guidance/Direction+ │ > Bracket = Code/Terminal/CLI+ ▼+ S (black)+```++它带来了以下效果:+- **视觉清晰**:一眼就能看出这是“代码导航指南”+- **象征意义**:指南针 = 找到方向;`>` = 代码/终端+- **可扩展性**:从 16px 到 512px 都能正常工作+- **品牌一致性**:以极简配色匹配开发者工具气质++---++## 色彩系统++### 配色++| 颜色 | 十六进制 | RGB | 用途 |+|-------|-----|-----|-------|+| 黑色(主色) | `#000000` | 0, 0, 0 | 主描边、文字、南针 |+| 白色(背景) | `#FFFFFF` | 255, 255, 255 | 浅色背景 |+| 灰色(辅助) | `#6B7280` | 107, 114, 128 | 次要刻度、次级文字 |+| 亮绿色(强调) | `#22C55E` | 34, 197, 94 | 北针、中心点、强调线 |+| 接近黑色(深色背景) | `#0A0A0A` | 10, 10, 10 | 深色模式背景 |++### 对比度(WCAG)++- 黑底白字:**21:1** AAA+- 灰底白字:**4.6:1** AA+- 绿底白字:**3.2:1**(仅用于装饰,不用于正文)+- 深色背景白字:**19.5:1** AAA++### 强调色规则++**亮绿色(#22C55E)仅用于高亮:**+- 指南针北针+- 中心点+- 强调下划线/边框+- 绝不作为背景色+- 绝不用于正文++---++## 字体排版++### Logo 字体+- **字体族**:Inter、SF Pro Display、-apple-system、Segoe UI、sans-serif+- **“Claude”**:42px,700 字重(加粗),黑色+- **“How-To”**:32px,500 字重(中等),灰色(#6B7280)+- **副标题**:10px,500 字重,灰色,字间距 1.5px,大写++### 界面字体+- **字体族**:Inter、SF Pro、系统字体(sans-serif)+- **字重**:400-600+- **风格**:简洁、易读++---++## 图标细节++### 指南针规格++指南针图形由以下几何元素组成:++```+Element | Stroke/Fill | Color+--------------------|----------------|------------------+Outer ring | 3px stroke | Black / White (dark mode)+North tick | 2.5px stroke | Black / White (dark mode)+Other cardinal ticks| 2px stroke | Gray / White 50% (dark mode)+Intercardinal ticks | 1.5px stroke | Gray / White 40% (dark mode)+North needle | filled polygon | #22C55E (always green)+South needle | filled polygon | Black / White (dark mode)+> bracket | 3px stroke | Black / White (dark mode)+Center dot | filled circle | #22C55E (always green)+```++### 尺寸递进++```+16px → 仅环 + 指针 + 箭头(最简版)+32px → 增加方位刻度+64px → 增加中间方位刻度+128px → 全细节,所有元素都清晰+256px → 最高细节,较粗描边+```++---++## 尺寸指南++### Logo 尺寸++- **最小**:200px 宽(用于网页)+- **推荐**:520px(原始尺寸)+- **最大**:无限制(矢量格式)+- **宽高比**:约 4.3:1(宽:高)++### 图标尺寸++- **最小**:16px(favicon)+- **推荐**:64-256px(应用、头像)+- **最大**:无限制(矢量格式)+- **宽高比**:1:1(正方形)++---++## 间距与对齐++### Logo 留白++```+┌─────────────────────────────────────┐+│ │+│ 最小留白空间 │+│ (logo 高度 / 2) │+│ │+│ [COMPASS] Claude │+│ How-To │+│ │+└─────────────────────────────────────┘+```++### 图标中心点++所有图标都以画布中心为基准:+- 256px 画布使用 128×128 中心点+- 128px 画布使用 64×64 中心点+- 与其他 UI 元素保持对齐++---++## 无障碍性++### 颜色对比+- 所有文字都满足 WCAG AA(最低 4.5:1)+- 绿色强调色只用于装饰,不承担信息传达+- 不依赖红绿配色表达含义++### 可扩展性+- 矢量格式保证任意尺寸都清晰+- 即使在 16px 下,几何形状依然可辨识+- 细节会随可用空间逐步增加++---++## 应用示例++### Web 页眉+- 尺寸:520×120px logo+- 文件:`logos/claude-howto-logo.svg`+- 背景:白色或深色(#0A0A0A)+- 内边距:至少 20px++### 应用图标+- 尺寸:256×256px+- 文件:`icons/claude-howto-icon.svg`+- 背景:白色或深色+- 用途:应用快捷方式、头像++### 浏览器 Favicon+- 尺寸:32px(主用),16px(备用)+- 文件:`favicons/favicon-32.svg`+- 格式:SVG,显示清晰锐利++### 社交媒体+- 头像:256×256px 图标+- 横幅:520×120px logo(居中)++### 文档+- 章节标题:按需缩放的 logo+- 小节图标:64×64px favicon+- 内联图标:32×32px favicon++---++## 文件格式细节++### SVG 结构++所有 SVG 文件都采用扁平设计:+- 无渐变(仅用纯色)+- 无滤镜效果(不使用模糊、发光或阴影)+- 干净的描边和填充几何结构+- 使用 `viewBox` 实现响应式缩放+- 代码可读且带注释++### 跨浏览器兼容性++- Chrome/Edge:完全支持+- Firefox:完全支持+- Safari:完全支持+- iOS Safari:完全支持+- 所有现代浏览器:完全支持++---++## 自定义++### 更换强调色++如果你想创建不同强调色的变体:++1. 把所有 `#22C55E` 替换成你的强调色+2. 确保装饰性元素的对比度仍高于 3:1+3. 保持黑/白/灰结构不变++### 缩放++```css+svg {+ width: 256px;+ height: 256px;+}+```++SVG 会通过 `viewBox` 自动缩放,不需要额外变换。++---++## 版本控制++在 git 中跟踪设计变更:+- 正常版本化 SVG 文件,因为它们本质上是文本+- 随设计变更一起打 tag+- 在提交中包含 `DESIGN-SYSTEM.md`++---++**最后更新**:2026 年 2 月+**设计系统版本**:3.0diff --git a/zh/resources/QUICK-START.md b/zh/resources/QUICK-START.mdnew file mode 100644index 0000000..44785a3--- /dev/null+++ b/zh/resources/QUICK-START.md@@ -0,0 +1,89 @@+# 快速开始 - 品牌资源++## 复制资源到你的项目++```bash+# 将所有资源复制到你的 Web 项目中+cp -r resources/ /path/to/your/website/++# 或者只复制网页所需的 favicon+cp resources/favicons/* /path/to/your/website/public/+```++## 添加到 HTML(直接复制粘贴)++```html+<!-- Favicons -->+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-32.svg" sizes="32x32">+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-16.svg" sizes="16x16">+<link rel="apple-touch-icon" href="/resources/favicons/favicon-128.svg">+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-256.svg" sizes="256x256">+<meta name="theme-color" content="#000000">+```++## 在 Markdown/文档中使用++```markdown+# Claude How To+++++```++## 推荐尺寸++| 用途 | 尺寸 | 文件 |+|---------|------|------|+| 网站页眉 | 520×120 | `logos/claude-howto-logo.svg` |+| 应用图标 | 256×256 | `icons/claude-howto-icon.svg` |+| 浏览器标签页 | 32×32 | `favicons/favicon-32.svg` |+| 移动端桌面图标 | 128×128 | `favicons/favicon-128.svg` |+| 桌面应用 | 256×256 | `favicons/favicon-256.svg` |+| 小头像 | 64×64 | `favicons/favicon-64.svg` |++## 颜色值++```css+/* 在 CSS 中使用这些值 */+--color-primary: #000000;+--color-secondary: #6B7280;+--color-accent: #22C55E;+--color-bg-light: #FFFFFF;+--color-bg-dark: #0A0A0A;+```++## 图标含义++**指南针 + 代码括号**:+- 指南针环 = 导航、结构化学习路径+- 绿色北针 = 方向、进展、引导+- 黑色南针 = 基础、根基+- `>` 括号 = 终端提示符、代码、CLI 场景+- 刻度线 = 精准、结构化步骤++这象征着“在清晰引导下穿行于代码世界”。++## 在哪里用什么++### 网站+- **页眉**:Logo(`logos/claude-howto-logo.svg`)+- **Favicon**:32px(`favicons/favicon-32.svg`)+- **社交预览**:图标(`icons/claude-howto-icon.svg`)++### GitHub+- **README 徽章**:图标(`icons/claude-howto-icon.svg`),建议 64-128px+- **仓库头像**:图标(`icons/claude-howto-icon.svg`)++### 社交媒体+- **头像**:图标(`icons/claude-howto-icon.svg`)+- **横幅**:Logo(`logos/claude-howto-logo.svg`)+- **缩略图**:256×256px 图标++### 文档+- **章节标题**:Logo 或图标(按需缩放)+- **导航图标**:Favicon(32-64px)++---++完整文档见 [README.md](README.md)。diff --git a/zh/resources/README.md b/zh/resources/README.mdnew file mode 100644index 0000000..1be1235--- /dev/null+++ b/zh/resources/README.md@@ -0,0 +1,266 @@+<picture>+ <source media="(prefers-color-scheme: dark)" srcset="logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="logos/claude-howto-logo.svg">+</picture>++# Claude How To - 品牌资源++这是 Claude How To 项目的完整品牌资源集合,包括 logo、图标和 favicon。所有资源都采用 V3.0 设计:一个带有代码括号(`>`)符号的指南针,象征在代码中引导前进,整体使用黑/白/灰配色,并以亮绿色(`#22C55E`)作为强调色。++## 目录结构++```+resources/+├── logos/+│ ├── claude-howto-logo.svg # 主 logo - 浅色模式 (520×120px)+│ └── claude-howto-logo-dark.svg # 主 logo - 深色模式 (520×120px)+├── icons/+│ ├── claude-howto-icon.svg # 应用图标 - 浅色模式 (256×256px)+│ └── claude-howto-icon-dark.svg # 应用图标 - 深色模式 (256×256px)+└── favicons/+ ├── favicon-16.svg # Favicon - 16×16px+ ├── favicon-32.svg # Favicon - 32×32px(主用)+ ├── favicon-64.svg # Favicon - 64×64px+ ├── favicon-128.svg # Favicon - 128×128px+ └── favicon-256.svg # Favicon - 256×256px+```++`assets/logo/` 下还有额外资源:+```+assets/logo/+├── logo-full.svg # 图形标记 + 品牌字样(横向)+├── logo-mark.svg # 仅指南针符号 (120×120px)+├── logo-wordmark.svg # 仅文字+├── logo-icon.svg # 应用图标 (512×512,圆角)+├── favicon.svg # 16×16 优化版+├── logo-white.svg # 适用于深色背景的白色版本+└── logo-black.svg # 黑色单色版本+```++## 资源概览++### 设计概念(V3.0)++**指南针 + 代码括号**,代表“导航遇见代码”:+- **指南针环** = 导航、找到方向+- **北针(绿色)** = 方向、学习路径上的进展+- **南针(黑色)** = 扎实基础、稳固根基+- **`>` 括号** = 终端提示符、代码、CLI 场景+- **刻度线** = 精准、结构化学习++### Logo++**文件**:+- `logos/claude-howto-logo.svg`(浅色模式)+- `logos/claude-howto-logo-dark.svg`(深色模式)++**规格**:+- **尺寸**:520×120 px+- **用途**:主标题/品牌 logo,带品牌字样+- **使用场景**:+ - 网站页眉+ - README 徽章+ - 营销素材+ - 印刷物料+- **格式**:SVG(可无限缩放)+- **模式**:浅色(白色背景)与深色(#0A0A0A 背景)++### 图标++**文件**:+- `icons/claude-howto-icon.svg`(浅色模式)+- `icons/claude-howto-icon-dark.svg`(深色模式)++**规格**:+- **尺寸**:256×256 px+- **用途**:应用图标、头像、缩略图+- **使用场景**:+ - App 图标+ - 个人头像+ - 社交媒体缩略图+ - 文档页眉+- **格式**:SVG(可无限缩放)+- **模式**:浅色(白色背景)与深色(#0A0A0A 背景)++**设计元素**:+- 带方位和中间方位刻度的指南针环+- 绿色北针(方向/引导)+- 黑色南针(基础)+- 中央 `>` 代码括号(终端/CLI)+- 绿色中心点强调++### Favicon++为网页使用提供了多种尺寸的优化版本:++| 文件 | 尺寸 | DPI | 用途 |+|------|------|-----|------|+| `favicon-16.svg` | 16×16 px | 1x | 浏览器标签页(旧浏览器) |+| `favicon-32.svg` | 32×32 px | 1x | 标准浏览器 favicon |+| `favicon-64.svg` | 64×64 px | 1x-2x | 高 DPI 显示器 |+| `favicon-128.svg` | 128×128 px | 2x | Apple touch icon、书签 |+| `favicon-256.svg` | 256×256 px | 4x | 现代浏览器、PWA 图标 |++**优化说明**:+- 16px:最小几何元素,仅保留环、指针和箭头+- 32px:增加方位刻度+- 64px 以上:完整细节与中间方位刻度+- 全部版本都保持与主图标一致的视觉效果+- SVG 格式保证任意尺寸下都清晰锐利++## HTML 集成++### 基础 Favicon 配置++```html+<!-- 浏览器 favicon -->+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-32.svg">+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-16.svg" sizes="16x16">++<!-- Apple touch icon(移动端桌面图标) -->+<link rel="apple-touch-icon" href="/resources/favicons/favicon-128.svg">++<!-- PWA 与现代浏览器 -->+<link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-256.svg" sizes="256x256">+```++### 完整配置++```html+<head>+ <!-- 主 favicon -->+ <link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-32.svg" sizes="32x32">+ <link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-16.svg" sizes="16x16">++ <!-- Apple touch icon -->+ <link rel="apple-touch-icon" href="/resources/favicons/favicon-128.svg">++ <!-- PWA 图标 -->+ <link rel="icon" type="image/svg+xml" href="/resources/favicons/favicon-256.svg" sizes="256x256">++ <!-- Android -->+ <link rel="shortcut icon" href="/resources/favicons/favicon-256.svg">++ <!-- PWA manifest 引用(如果使用 manifest.json) -->+ <meta name="theme-color" content="#000000">+</head>+```++## 颜色方案++### 主色+- **黑色**:`#000000`(主文本、线条、南针)+- **白色**:`#FFFFFF`(浅色背景)+- **灰色**:`#6B7280`(次级文本、次要刻度)++### 强调色+- **亮绿色**:`#22C55E`(北针、中心点、强调线条,只用于高亮,绝不作为背景)++### 深色模式+- **背景**:`#0A0A0A`(接近黑色)++### CSS 变量+```css+--color-primary: #000000;+--color-secondary: #6B7280;+--color-accent: #22C55E;+--color-bg-light: #FFFFFF;+--color-bg-dark: #0A0A0A;+```++### Tailwind 配置+```js+colors: {+ brand: {+ primary: '#000000',+ secondary: '#6B7280',+ accent: '#22C55E',+ }+}+```++### 使用规范+- 主文本和结构元素使用黑色+- 次级/辅助元素使用灰色+- 绿色**仅**用于高亮,例如指针、点和强调线+- 不要把绿色用作背景色+- 保持 WCAG AA 对比度(最低 4.5:1)++## 设计规范++### Logo 使用+- 用于白色或深色(#0A0A0A)背景+- 按比例缩放+- Logo 四周保留足够留白(最小值:logo 高度 / 2)+- 根据背景选择对应的浅色/深色版本++### 图标使用+- 适用于标准尺寸:16、32、64、128、256px+- 保持指南针比例+- 按比例缩放++### Favicon 使用+- 根据场景选用合适尺寸+- 16-32px:浏览器标签页、书签+- 64px:站点图标+- 128px 以上:Apple/Android 桌面图标++## SVG 优化++所有 SVG 文件都采用扁平设计,没有渐变和滤镜:+- 干净的基于描边的几何结构+- 不嵌入位图+- 路径已优化+- 使用响应式 `viewBox`++网页优化示例:+```bash+# 压缩 SVG,同时保持质量+svgo --config='{+ "js2svg": {+ "indent": 2+ },+ "plugins": [+ "convertStyleToAttrs",+ "removeRasterImages"+ ]+}' input.svg -o output.svg+```++## PNG 转换++如果你需要为旧浏览器支持转换成 PNG:++```bash+# 使用 ImageMagick+convert -density 300 -background none favicon-256.svg favicon-256.png++# 使用 Inkscape+inkscape -D -z --file=favicon-256.svg --export-png=favicon-256.png+```++## 无障碍性++- 高对比度颜色比例(符合 WCAG AA,最低 4.5:1)+- 几何形状清晰,在各种尺寸下都容易识别+- 矢量格式,可无限缩放+- 图标中不使用文字(文字由单独的 wordmark 承担)+- 不依赖红绿配色表达含义++## 署名++这些资源属于 Claude How To 项目。++**许可证**:MIT(见项目 LICENSE 文件)++## 版本历史++- **v3.0**(2026 年 2 月):指南针 + 括号设计,黑/白/灰 + 绿色强调色+- **v2.0**(2026 年 1 月):受 Claude 启发的 12 芒星爆发式设计,祖母绿配色+- **v1.0**(2026 年 1 月):最初基于六边形的进度图标设计++---++**最后更新**:2026 年 2 月+**当前版本**:3.0(指南针 + 括号)+**全部资源**:可直接用于生产环境的 SVG,支持无限缩放,符合 WCAG AA 无障碍标准diff --git a/zh/scripts/README.md b/zh/scripts/README.mdnew file mode 100644index 0000000..7623e1c--- /dev/null+++ b/zh/scripts/README.md@@ -0,0 +1,69 @@+# EPUB 构建脚本++## 功能++这个脚本会把整份指南构建成 EPUB 电子书,方便离线阅读。++## 需求++- Python 环境+- `uv`+- 相关依赖++## 快速开始++最简单的方式是直接让 `uv` 帮你处理依赖:++```bash+uv run scripts/build_epub.py+```++## 开发环境++如果你要修改脚本本身,可以先创建虚拟环境,再安装开发依赖。++```bash+# 创建虚拟环境++# 激活并安装依赖++# 运行测试++# 运行脚本+```++## 命令行选项++常见选项包括:++- 指定输出路径+- 打开详细日志+- 限制并发请求++## 示例++```bash+# 带详细输出构建++# 指定输出位置++# 限制并发数(遇到限流时)+```++## 输出++脚本会生成 EPUB 文件,里面包含所有内容和渲染后的图表。++## 运行测试++你可以用虚拟环境或直接通过 `uv` 运行测试。++## 依赖++脚本依赖的包会在项目的开发依赖里列出。++## 故障排查++- 检查 `uv` 是否可用+- 检查 Python 版本+- 检查依赖是否安装完整