From 89e89d4aa38cb57d872844adecd618a49e19331f Mon Sep 17 00:00:00 2001 From: Luong NGUYEN Date: Mon, 6 Apr 2026 23:08:54 +0200 Subject: [PATCH] feat(zh): add Chinese translations in zh/ directory Add Chinese (Simplified) translations for all documentation, organized under a dedicated zh/ directory that mirrors the English folder structure. Co-authored-by: tanqingkuang Translations originally contributed by @tanqingkuang in #45. Restructured from *-CN.md suffix pattern into zh/ directory to prevent the EPUB builder (scripts/build_epub.py collect_folder_files) from picking up Chinese files via glob("*.md") inside module folders. --- scripts/check_cross_references.py | 3 +- zh/.github/ISSUE_TEMPLATE/bug_report.md | 43 + zh/.github/ISSUE_TEMPLATE/documentation.md | 44 + zh/.github/ISSUE_TEMPLATE/feature_request.md | 46 + zh/.github/ISSUE_TEMPLATE/question.md | 40 + zh/.github/SECURITY_REPORTING.md | 309 ++++ zh/.github/TESTING.md | 341 ++++ zh/.github/pull_request_template.md | 57 + zh/01-slash-commands/README.md | 551 ++++++ zh/01-slash-commands/commit.md | 26 + zh/01-slash-commands/doc-refactor.md | 24 + zh/01-slash-commands/generate-api-docs.md | 19 + zh/01-slash-commands/optimize.md | 19 + zh/01-slash-commands/pr.md | 26 + zh/01-slash-commands/push-all.md | 152 ++ zh/01-slash-commands/setup-ci-cd.md | 25 + zh/01-slash-commands/unit-test-expand.md | 25 + zh/02-memory/README.md | 305 ++++ zh/02-memory/directory-api-CLAUDE.md | 62 + zh/02-memory/personal-CLAUDE.md | 61 + zh/02-memory/project-CLAUDE.md | 88 + zh/03-skills/README.md | 271 +++ zh/03-skills/blog-draft/SKILL.md | 274 +++ .../blog-draft/templates/draft-template.md | 67 + .../blog-draft/templates/outline-template.md | 97 ++ zh/03-skills/brand-voice/SKILL.md | 72 + zh/03-skills/brand-voice/tone-examples.md | 13 + zh/03-skills/claude-md/SKILL.md | 212 +++ zh/03-skills/code-review/SKILL.md | 70 + .../code-review/templates/finding-template.md | 112 ++ .../code-review/templates/review-checklist.md | 47 + zh/03-skills/doc-generator/SKILL.md | 76 + zh/03-skills/refactor/SKILL.md | 426 +++++ .../refactor/references/code-smells.md | 669 +++++++ .../references/refactoring-catalog.md | 1023 +++++++++++ .../refactor/templates/refactoring-plan.md | 284 +++ zh/04-subagents/README.md | 380 ++++ zh/04-subagents/clean-code-reviewer.md | 66 + zh/04-subagents/code-reviewer.md | 61 + zh/04-subagents/data-scientist.md | 97 ++ zh/04-subagents/debugger.md | 80 + zh/04-subagents/documentation-writer.md | 98 ++ zh/04-subagents/implementation-agent.md | 78 + zh/04-subagents/secure-reviewer.md | 75 + zh/04-subagents/test-engineer.md | 74 + zh/05-mcp/README.md | 342 ++++ zh/06-hooks/README.md | 98 ++ zh/07-plugins/README.md | 930 ++++++++++ zh/07-plugins/devops-automation/README.md | 114 ++ .../agents/alert-analyzer.md | 14 + .../agents/deployment-specialist.md | 14 + .../agents/incident-commander.md | 14 + .../devops-automation/commands/deploy.md | 15 + .../devops-automation/commands/incident.md | 16 + .../devops-automation/commands/rollback.md | 14 + .../devops-automation/commands/status.md | 15 + zh/07-plugins/documentation/README.md | 127 ++ .../documentation/agents/api-documenter.md | 14 + .../documentation/agents/code-commentator.md | 14 + .../documentation/agents/example-generator.md | 14 + .../commands/generate-api-docs.md | 15 + .../documentation/commands/generate-readme.md | 15 + .../documentation/commands/sync-docs.md | 14 + .../documentation/commands/validate-docs.md | 14 + .../documentation/templates/adr-template.md | 39 + .../documentation/templates/api-endpoint.md | 101 ++ .../documentation/templates/function-docs.md | 50 + zh/07-plugins/pr-review/README.md | 96 + .../pr-review/agents/performance-analyzer.md | 13 + .../pr-review/agents/security-reviewer.md | 13 + .../pr-review/agents/test-checker.md | 13 + .../pr-review/commands/check-security.md | 14 + .../pr-review/commands/check-tests.md | 14 + zh/07-plugins/pr-review/commands/review-pr.md | 14 + zh/08-checkpoints/README.md | 292 ++++ zh/08-checkpoints/checkpoint-examples.md | 339 ++++ zh/09-advanced-features/README.md | 954 ++++++++++ .../planning-mode-examples.md | 533 ++++++ zh/10-cli/README.md | 640 +++++++ zh/CATALOG.md | 517 ++++++ zh/CHANGELOG.md | 109 ++ zh/CODE_OF_CONDUCT.md | 216 +++ zh/CONTRIBUTING.md | 378 ++++ zh/INDEX.md | 900 ++++++++++ zh/LEARNING-ROADMAP.md | 725 ++++++++ zh/QUICK_REFERENCE.md | 506 ++++++ zh/README.md | 881 ++++++++++ zh/RELEASE_NOTES.md | 8 + zh/SECURITY.md | 334 ++++ zh/STYLE_GUIDE.md | 630 +++++++ zh/claude_concepts_guide.md | 1540 +++++++++++++++++ zh/clean-code-rules.md | 108 ++ zh/docs/ROADMAP-20260401.md | 153 ++ zh/docs/TASKS-20260401.md | 291 ++++ zh/prompts/remotion-video.md | 350 ++++ zh/resources.md | 248 +++ zh/resources/DESIGN-SYSTEM.md | 244 +++ zh/resources/QUICK-START.md | 89 + zh/resources/README.md | 266 +++ zh/scripts/README.md | 69 + 100 files changed, 20487 insertions(+), 1 deletion(-) create mode 100644 zh/.github/ISSUE_TEMPLATE/bug_report.md create mode 100644 zh/.github/ISSUE_TEMPLATE/documentation.md create mode 100644 zh/.github/ISSUE_TEMPLATE/feature_request.md create mode 100644 zh/.github/ISSUE_TEMPLATE/question.md create mode 100644 zh/.github/SECURITY_REPORTING.md create mode 100644 zh/.github/TESTING.md create mode 100644 zh/.github/pull_request_template.md create mode 100644 zh/01-slash-commands/README.md create mode 100644 zh/01-slash-commands/commit.md create mode 100644 zh/01-slash-commands/doc-refactor.md create mode 100644 zh/01-slash-commands/generate-api-docs.md create mode 100644 zh/01-slash-commands/optimize.md create mode 100644 zh/01-slash-commands/pr.md create mode 100644 zh/01-slash-commands/push-all.md create mode 100644 zh/01-slash-commands/setup-ci-cd.md create mode 100644 zh/01-slash-commands/unit-test-expand.md create mode 100644 zh/02-memory/README.md create mode 100644 zh/02-memory/directory-api-CLAUDE.md create mode 100644 zh/02-memory/personal-CLAUDE.md create mode 100644 zh/02-memory/project-CLAUDE.md create mode 100644 zh/03-skills/README.md create mode 100644 zh/03-skills/blog-draft/SKILL.md create mode 100644 zh/03-skills/blog-draft/templates/draft-template.md create mode 100644 zh/03-skills/blog-draft/templates/outline-template.md create mode 100644 zh/03-skills/brand-voice/SKILL.md create mode 100644 zh/03-skills/brand-voice/tone-examples.md create mode 100644 zh/03-skills/claude-md/SKILL.md create mode 100644 zh/03-skills/code-review/SKILL.md create mode 100644 zh/03-skills/code-review/templates/finding-template.md create mode 100644 zh/03-skills/code-review/templates/review-checklist.md create mode 100644 zh/03-skills/doc-generator/SKILL.md create mode 100644 zh/03-skills/refactor/SKILL.md create mode 100644 zh/03-skills/refactor/references/code-smells.md create mode 100644 zh/03-skills/refactor/references/refactoring-catalog.md create mode 100644 zh/03-skills/refactor/templates/refactoring-plan.md create mode 100644 zh/04-subagents/README.md create mode 100644 zh/04-subagents/clean-code-reviewer.md create mode 100644 zh/04-subagents/code-reviewer.md create mode 100644 zh/04-subagents/data-scientist.md create mode 100644 zh/04-subagents/debugger.md create mode 100644 zh/04-subagents/documentation-writer.md create mode 100644 zh/04-subagents/implementation-agent.md create mode 100644 zh/04-subagents/secure-reviewer.md create mode 100644 zh/04-subagents/test-engineer.md create mode 100644 zh/05-mcp/README.md create mode 100644 zh/06-hooks/README.md create mode 100644 zh/07-plugins/README.md create mode 100644 zh/07-plugins/devops-automation/README.md create mode 100644 zh/07-plugins/devops-automation/agents/alert-analyzer.md create mode 100644 zh/07-plugins/devops-automation/agents/deployment-specialist.md create mode 100644 zh/07-plugins/devops-automation/agents/incident-commander.md create mode 100644 zh/07-plugins/devops-automation/commands/deploy.md create mode 100644 zh/07-plugins/devops-automation/commands/incident.md create mode 100644 zh/07-plugins/devops-automation/commands/rollback.md create mode 100644 zh/07-plugins/devops-automation/commands/status.md create mode 100644 zh/07-plugins/documentation/README.md create mode 100644 zh/07-plugins/documentation/agents/api-documenter.md create mode 100644 zh/07-plugins/documentation/agents/code-commentator.md create mode 100644 zh/07-plugins/documentation/agents/example-generator.md create mode 100644 zh/07-plugins/documentation/commands/generate-api-docs.md create mode 100644 zh/07-plugins/documentation/commands/generate-readme.md create mode 100644 zh/07-plugins/documentation/commands/sync-docs.md create mode 100644 zh/07-plugins/documentation/commands/validate-docs.md create mode 100644 zh/07-plugins/documentation/templates/adr-template.md create mode 100644 zh/07-plugins/documentation/templates/api-endpoint.md create mode 100644 zh/07-plugins/documentation/templates/function-docs.md create mode 100644 zh/07-plugins/pr-review/README.md create mode 100644 zh/07-plugins/pr-review/agents/performance-analyzer.md create mode 100644 zh/07-plugins/pr-review/agents/security-reviewer.md create mode 100644 zh/07-plugins/pr-review/agents/test-checker.md create mode 100644 zh/07-plugins/pr-review/commands/check-security.md create mode 100644 zh/07-plugins/pr-review/commands/check-tests.md create mode 100644 zh/07-plugins/pr-review/commands/review-pr.md create mode 100644 zh/08-checkpoints/README.md create mode 100644 zh/08-checkpoints/checkpoint-examples.md create mode 100644 zh/09-advanced-features/README.md create mode 100644 zh/09-advanced-features/planning-mode-examples.md create mode 100644 zh/10-cli/README.md create mode 100644 zh/CATALOG.md create mode 100644 zh/CHANGELOG.md create mode 100644 zh/CODE_OF_CONDUCT.md create mode 100644 zh/CONTRIBUTING.md create mode 100644 zh/INDEX.md create mode 100644 zh/LEARNING-ROADMAP.md create mode 100644 zh/QUICK_REFERENCE.md create mode 100644 zh/README.md create mode 100644 zh/RELEASE_NOTES.md create mode 100644 zh/SECURITY.md create mode 100644 zh/STYLE_GUIDE.md create mode 100644 zh/claude_concepts_guide.md create mode 100644 zh/clean-code-rules.md create mode 100644 zh/docs/ROADMAP-20260401.md create mode 100644 zh/docs/TASKS-20260401.md create mode 100644 zh/prompts/remotion-video.md create mode 100644 zh/resources.md create mode 100644 zh/resources/DESIGN-SYSTEM.md create mode 100644 zh/resources/QUICK-START.md create mode 100644 zh/resources/README.md create mode 100644 zh/scripts/README.md diff --git a/scripts/check_cross_references.py b/scripts/check_cross_references.py index 0d9539c..7dd28c3 100644 --- a/scripts/check_cross_references.py +++ b/scripts/check_cross_references.py @@ -3,6 +3,7 @@ import re import sys +import unicodedata from pathlib import Path IGNORE_DIRS = { @@ -63,7 +64,7 @@ def main() -> int: errors = [] for file_path in iter_md_files(): - content = file_path.read_text() + content = file_path.read_text(encoding="utf-8") # Strip code blocks before scanning for links/anchors to avoid false positives # from documentation examples inside code fences. scannable = strip_code_blocks(content) diff --git a/zh/.github/ISSUE_TEMPLATE/bug_report.md b/zh/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..bda438d --- /dev/null +++ b/zh/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,43 @@ +--- +name: Bug Report +about: 报告示例、指南或文档中的问题 +title: "[BUG] " +labels: bug +assignees: '' + +--- + +## 问题描述 +简要说明问题。 + +## 复现步骤 +1. 第 1 步 +2. 第 2 步 +3. 第 3 步 + +## 预期行为 +应该发生什么？ + +## 实际行为 +实际发生了什么？ + +## 环境 +- **Claude Code 版本**：（例如 1.0.5） +- **操作系统**：（例如 macOS 14.1、Ubuntu 22.04、Windows 11） +- **Python 版本**：（如有相关，例如 3.11） +- **受影响的组件**：（例如 01-slash-commands、03-skills 等） + +## 示例代码 +如果适用，请提供无法正常工作的示例代码： +``` +[在这里插入代码] +``` + +## 截图 +如果适用，请附上显示问题的截图。 + +## 其他上下文 +还有哪些信息可能有助于我们理解这个问题？ + +## 可能的解决方案 +如果你有修复建议，也可以写在这里。 diff --git a/zh/.github/ISSUE_TEMPLATE/documentation.md b/zh/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 0000000..b53cec1 --- /dev/null +++ b/zh/.github/ISSUE_TEMPLATE/documentation.md @@ -0,0 +1,44 @@ +--- +name: Documentation Issue +about: 报告文档中的不清晰、错别字或缺失信息 +title: "[DOCS] " +labels: documentation +assignees: '' + +--- + +## 问题类型 +- [ ] 拼写或语法错误 +- [ ] 解释不清 +- [ ] 缺少信息 +- [ ] 链接或引用损坏 +- [ ] 内容过时 +- [ ] 需要更好的示例 + +## 位置 +哪一部分有问题？ +- **文件**：（例如 README.md、03-skills/README.md） +- **章节**：（例如 "Installation Quick Reference"） +- **行号/区域**：（如有具体位置） + +## 当前内容 +当前写的是什么？ +``` +[在这里粘贴当前文本] +``` + +## 问题说明 +哪里有问题？ + +## 建议改进 +应该如何改进或澄清？ +``` +[在这里提供改进后的文本或建议] +``` + +## 这样做的重要性 +这个问题会怎样影响用户？ + +## 相关文档 +相关章节链接： +- 相关指南： diff --git a/zh/.github/ISSUE_TEMPLATE/feature_request.md b/zh/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..7a328d7 --- /dev/null +++ b/zh/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,46 @@ +--- +name: Feature Request +about: 建议新增示例、指南或改进 +title: "[FEATURE] " +labels: enhancement +assignees: '' + +--- + +## 描述 +描述你希望看到的功能或改进。 + +## 它解决了什么问题 +它解决了什么问题或缺口？ + +示例： +- 没有 X 功能的示例 +- Y 功能的现有文档不清楚 +- 我们需要 Z 场景的指南 +- 结构可以通过以下方式改进…… + +## 使用场景 +这个功能会在什么时候、怎样使用？请包含真实场景。 + +## 建议方案 +应该如何实现或记录？ + +## 示例 +如果适用，请提供你设想的示例： +``` +[在这里插入示例] +``` + +## 相关示例 +链接任何已有的相关示例或指南： +- 现有指南： +- 功能：（例如 Skills、Hooks、Subagents） + +## 其他上下文 +还有哪些可能有帮助的信息？ + +## 验收标准 +怎样才算这个功能完成？ +- [ ] 标准 1 +- [ ] 标准 2 +- [ ] 标准 3 diff --git a/zh/.github/ISSUE_TEMPLATE/question.md b/zh/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 0000000..954585c --- /dev/null +++ b/zh/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,40 @@ +--- +name: Question +about: 提出关于 Claude Code 或本指南的问题 +title: "[QUESTION] " +labels: question +assignees: '' + +--- + +## 问题 +你想了解什么？ + +## 背景 +请提供一些背景或上下文： +- 你想做什么？ +- 你已经尝试过什么？ +- 你看过哪些示例或指南？ + +## 相关主题 +这个问题属于哪个主题？ +- [ ] Slash Commands +- [ ] Memory +- [ ] Skills +- [ ] Subagents +- [ ] MCP Protocol +- [ ] Hooks +- [ ] Plugins +- [ ] Checkpoints +- [ ] Advanced Features +- [ ] CLI Reference +- [ ] 其他 + +## 你尝试过什么 +你已经尝试了什么？结果如何？ + +## 期望结果 +什么样的结果能帮助你解决问题？ + +## 其他资源 +还有哪些可能相关的链接或资源？ diff --git a/zh/.github/SECURITY_REPORTING.md b/zh/.github/SECURITY_REPORTING.md new file mode 100644 index 0000000..3b8b84a --- /dev/null +++ b/zh/.github/SECURITY_REPORTING.md @@ -0,0 +1,309 @@ +# 安全漏洞报告 + +本文说明如何向 Claude How To 项目报告安全漏洞。 + +## 快速链接 + +- **私密报告**： +- **安全政策**：[SECURITY.md](../SECURITY.md) +- **报告模板**：见下文 + +## 报告漏洞 + +### 选项 1：GitHub 私密漏洞报告（推荐） + +这是报告安全漏洞的首选方式。 + +**步骤：** +1. 访问： +2. 点击 “Report a vulnerability” +3. 填写详情（可使用下方模板） +4. 提交 + +**优点：** +- 在修复发布前保持漏洞私密 +- 自动通知维护者 +- 内置协作功能 +- 与 GitHub 安全工具集成 + +### 选项 2：GitHub 安全警报（依赖漏洞） + +如果你在依赖中发现漏洞： + +1. 访问： +2. 查看警报 +3. 提交包含修复的 pull request +4. 加上 `security` 标签 + +### 选项 3：私密邮箱（GitHub 不可用时） + +如果你无法使用 GitHub 的报告系统： + +**即将提供**：这里会补充安全联系邮箱 + +目前请优先使用上面的 GitHub 私密漏洞报告。 + +## 漏洞报告模板 + +报告漏洞时可使用以下模板： + +``` +**标题**：[漏洞简述] + +**严重性**：[Critical/High/Medium/Low] +Estimated CVSS Score: [0-10] + +**类型**：[代码/文档/依赖/配置] + +**受影响组件**： +- File: [path/to/file.py] +- Section: [文档章节名，如适用] +- Version: [latest/具体版本] + +**描述**： +[对漏洞的清晰说明] + +**潜在影响**： +[攻击者可以利用该漏洞做什么？] +[可能影响哪些人？] + +**复现步骤**： +1. [第一步] +2. [第二步] +3. [第三步] +[预期结果与实际结果] + +**PoC**（如有）： +[用于演示漏洞的代码或步骤] + +**建议修复**： +[你的建议方案，如有] + +**附加上下文**： +[任何其他相关信息] + +**你的信息**： +- Name: [你的名字或匿名] +- Email: [你的邮箱] +- Credit: [你希望如何署名，如有] +``` + +## 提交后会发生什么 + +### 时间线 + +1. **立刻（< 1 小时）** + - 自动通知会发送给项目维护者 + +2. **24 小时内** + - 对报告进行初步评估 + - 确认已收到 + - 初步严重性评估 + +3. **48 小时内** + - 安全团队给出详细回复 + - 如需更多信息会继续询问 + - 如果确认漏洞存在，会给出修复时间线 + +4. **1-7 天内**（取决于严重性） + - 完成修复并测试 + - 准备安全公告 + - 发布修复并公开公告 + +### 沟通方式 + +我们会通过以下方式与你保持沟通： +- GitHub 私密漏洞讨论 +- 邮件（如果你提供了） +- 讨论线程中的更新 + +你可以： +- 提出澄清问题 +- 补充更多信息 +- 建议改进修复方案 +- 请求调整时间线 + +### 披露时间线 + +**严重问题（CVSS 9.0-10.0）** +- 修复：立即发布（24 小时内） +- 披露：当天发布公开公告 +- 通知：提前 24 小时通知报告者 + +**高危问题（CVSS 7.0-8.9）** +- 修复：48-72 小时内发布 +- 披露：发布时公开公告 +- 通知：提前 5 天通知报告者 + +**中危问题（CVSS 4.0-6.9）** +- 修复：纳入下一次常规更新 +- 披露：发布时公开公告 +- 通知：协调时间线 + +**低危问题（CVSS 0.1-3.9）** +- 修复：纳入下一次常规更新 +- 披露：发布时公告 +- 通知：与发布同日 + +## 安全漏洞标准 + +### 范围内 + +我们接受以下类型的报告： + +- **代码漏洞** + - 注入攻击（命令、SQL 等） + - 示例中的跨站脚本（XSS） + - 认证/授权缺陷 + - 路径穿越漏洞 + - 密码学问题 + +- **文档安全** + - 暴露的秘密或凭据 + - 不安全代码模式 + - 安全反模式 + - 误导性的安全声明 + +- **依赖漏洞** + - 依赖中的已知 CVE + - 供应链攻击 + - 恶意依赖 + +- **配置问题** + - 不安全默认值 + - 缺失安全头 + - 示例中的凭据暴露 + +### 范围外 + +以下内容不接受报告： + +- Claude Code 本身的漏洞（请联系 Anthropic） +- 外部服务中的漏洞 +- 没有证明的理论漏洞 +- 已向上游项目报告的问题 +- 社会工程学或钓鱼 +- 用户教育 / 培训问题 + +## 负责任披露指南 + +### 应该做的 ✅ + +- **先私下报告**，再公开披露 +- **尽量具体**，提供文件路径和行号 +- **提供证明**，说明漏洞确实存在 +- **给我们时间**修复（协调披露） +- **补充更新**，如果你发现了更多细节 +- **保持专业**，在所有沟通中都如此 +- **尊重保密性**，直到我们公开发布 + +### 不应该做的 ❌ + +- **不要在修复前公开披露** +- **不要超出测试所需范围去利用漏洞** +- **不要修改**其他用户的数据 +- **不要索要**报酬或好处 +- **不要把漏洞**分享给其他人 +- **不要用于**任何有害用途 +- **不要用**非安全相关 issue 刷屏 + +## 协调披露 + +我们遵循负责任披露流程： + +1. **私密报告**：你先私下告诉我们 +2. **我们评估**：判断并评估严重性 +3. **开发修复**：我们开发并测试修复 +4. **提前通知**：在公开披露前提前通知你 +5. **公开发布**：我们同时发布修复和公告 +6. **你的署名**：如你愿意，会在公告中致谢 + +**具体时间会根据严重性变化**（见上文） + +## 修复发布后 + +### 公开公告 + +公开安全公告通常包含： +- 漏洞描述 +- 受影响版本 +- 严重性（CVSS 分数） +- 修复步骤 +- 修复链接 +- 对报告者的致谢（如获许可） + +### 你的署名 + +如果你希望被致谢： +- 公告中会写上你的名字/昵称 +- 可附上你的个人资料或网站链接 +- 在发布说明中致谢 +- 如果未来建立名人堂，也可能加入 + +### 不提供金钱补偿 + +请注意： +- 这是一个志愿者维护的开源项目 +- 我们无法提供金钱奖励 +- 但会提供认可和署名 +- 你的贡献会帮助整个社区 + +## 安全研究 + +如果你在做安全研究： + +1. **先取得许可**：先联系维护者 +2. **明确范围**：约定你会测试什么 +3. **报告发现**：使用本流程 +4. **尊重时间线**：给我们时间修复 +5. **负责任地发布**：与我们协调 + +## 有问题？ + +如果你对这个流程有疑问： + +1. 查看 [SECURITY.md](../SECURITY.md) 的完整政策 +2. 查看下方的 [FAQ](#faq) +3. 使用 `[SECURITY]` 标签发起 discussion +4. 对敏感问题使用私密漏洞报告 + +## FAQ + +**Q: 我的报告会保密吗？** +A: 会，直到修复发布。我们只会与参与修复的人共享细节。 + +**Q: 我需要等多久才能公开披露？** +A: 我们会按照严重性遵循负责任披露时间线（24 小时到 7 天）。如有需要，你可以同意延长。 + +**Q: 我会获得署名吗？** +A: 会，会出现在安全公告和发布说明中（除非你希望匿名）。 + +**Q: 如果漏洞很小怎么办？** +A: 所有真实的安全问题都会被认真对待，即使很小也会被记录和致谢。 + +**Q: 我可以只报告文档里的漏洞吗？** +A: 可以。文档安全同样重要。不安全示例也在范围内。 + +**Q: 如果我不确定这是不是安全问题呢？** +A: 先报告即可！如果不是安全问题，我们会告诉你。误报没关系。 + +**Q: 报告后我可以公开讨论吗？** +A: 不可以，请在我们公开公告前保持私密。过早披露可能让用户面临风险。 + +**Q: 我怎么知道你收到了我的报告？** +A: GitHub 会发送自动通知，我们会在 24 小时内跟进。 + +**Q: 如果我一直没收到回复怎么办？** +A: 检查 GitHub security advisories 页面。如果仍看不到回复，可以在私密报告里继续留言跟进。 + +## 资源 + +- [SECURITY.md](../SECURITY.md) - 完整安全政策 +- [CONTRIBUTING.md](../CONTRIBUTING.md) - 贡献指南 +- [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) - 社区标准 +- [OWASP Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html) - 负责任披露最佳实践 +- [Coordinated Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerable_Dependency_Management_Cheat_Sheet.html) + +--- + +感谢你帮助维护项目安全！🔒 diff --git a/zh/.github/TESTING.md b/zh/.github/TESTING.md new file mode 100644 index 0000000..22612a6 --- /dev/null +++ b/zh/.github/TESTING.md @@ -0,0 +1,341 @@ +# 测试指南 + +本文档说明 Claude How To 的测试基础设施。 + +## 概览 + +项目使用 GitHub Actions 在每次 push 和 pull request 时自动运行测试。测试覆盖： + +- **单元测试**：使用 pytest 的 Python 测试 +- **代码质量**：使用 Ruff 做 lint 和格式化 +- **安全**：使用 Bandit 做漏洞扫描 +- **类型检查**：使用 mypy 做静态类型分析 +- **构建验证**：EPUB 生成测试 + +## 在本地运行测试 + +### 前置条件 + +```bash +# 安装 uv（快速 Python 包管理器） +pip install uv + +# 或者在 macOS 上使用 Homebrew +brew install uv +``` + +### 配置环境 + +```bash +# 克隆仓库 +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto + +# 创建虚拟环境 +uv venv + +# 激活虚拟环境 +source .venv/bin/activate # macOS/Linux +# 或者 +.venv\Scripts\activate # Windows + +# 安装开发依赖 +uv pip install -r requirements-dev.txt +``` + +### 运行测试 + +```bash +# 运行所有单元测试 +pytest scripts/tests/ -v + +# 运行带覆盖率的测试 +pytest scripts/tests/ -v --cov=scripts --cov-report=html + +# 运行指定测试文件 +pytest scripts/tests/test_build_epub.py -v + +# 运行指定测试函数 +pytest scripts/tests/test_build_epub.py::test_function_name -v + +# 以 watch 模式运行测试（需要 pytest-watch） +ptw scripts/tests/ +``` + +### 运行 lint + +```bash +# 检查代码格式 +ruff format --check scripts/ + +# 自动修复格式问题 +ruff format scripts/ + +# 运行 lint +ruff check scripts/ + +# 自动修复 lint 问题 +ruff check --fix scripts/ +``` + +### 运行安全扫描 + +```bash +# 运行 Bandit 安全扫描 +bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ + +# 生成 JSON 报告 +bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ -f json -o bandit-report.json +``` + +### 运行类型检查 + +```bash +# 使用 mypy 检查类型 +mypy scripts/ --ignore-missing-imports --no-implicit-optional +``` + +## GitHub Actions 工作流 + +### 触发条件 + +- 推送到 `main` 或 `develop` 分支（当 `scripts` 有变更时） +- 向 `main` 提交 Pull Request（当 `scripts` 有变更时） +- 手动触发 workflow + +### 作业 + +#### 1. 单元测试（pytest） + +- **运行环境**：Ubuntu latest +- **Python 版本**：3.10、3.11、3.12 +- **执行内容**： + - 从 `requirements-dev.txt` 安装依赖 + - 运行 pytest 并生成覆盖率报告 + - 将覆盖率上传到 Codecov + - 归档测试结果和 HTML 覆盖率报告 + +**结果**：如果任何测试失败，工作流失败（关键） + +#### 2. 代码质量（Ruff） + +- **运行环境**：Ubuntu latest +- **Python 版本**：3.11 +- **执行内容**： + - 使用 `ruff format` 检查格式 + - 使用 `ruff check` 运行 lint + - 报告问题，但不会让整个工作流失败 + +**结果**：非阻塞（仅警告） + +#### 3. 安全扫描（Bandit） + +- **运行环境**：Ubuntu latest +- **Python 版本**：3.11 +- **执行内容**： + - 扫描安全漏洞 + - 生成 JSON 报告 + - 将报告作为 artifact 上传 + +**结果**：非阻塞（仅警告） + +#### 4. 类型检查（mypy） + +- **运行环境**：Ubuntu latest +- **Python 版本**：3.11 +- **执行内容**： + - 执行静态类型分析 + - 报告类型不匹配 + - 帮助尽早发现 bug + +**结果**：非阻塞（仅警告） + +#### 5. 构建 EPUB + +- **运行环境**：Ubuntu latest +- **依赖**：pytest、lint、安全扫描（都必须通过） +- **执行内容**： + - 使用 `scripts/build_epub.py` 构建 EPUB + - 验证 EPUB 是否成功生成 + - 将 EPUB 作为 artifact 上传 + +**结果**：如果构建失败，工作流失败（关键） + +#### 6. 总结 + +- **运行环境**：Ubuntu latest +- **依赖**：所有其他作业 +- **执行内容**： + - 生成工作流总结 + - 列出所有 artifacts + - 汇总总体状态 + +## 编写测试 + +### 测试结构 + +测试应放在 `scripts/tests/` 中，文件名形如 `test_*.py`： + +```python +# scripts/tests/test_example.py +import pytest +from scripts.example_module import some_function + +def test_basic_functionality(): + """测试 some_function 是否正常工作。""" + result = some_function("input") + assert result == "expected_output" + +def test_error_handling(): + """测试 some_function 是否能优雅处理错误。""" + with pytest.raises(ValueError): + some_function("invalid_input") + +@pytest.mark.asyncio +async def test_async_function(): + """测试异步函数。""" + result = await async_function() + assert result is not None +``` + +### 测试最佳实践 + +- **使用有描述性的名称**：例如 `test_function_returns_correct_value()` +- **尽量每个测试只做一个断言**：更容易排查失败原因 +- **使用 fixture** 复用初始化逻辑：见 `scripts/tests/conftest.py` +- **Mock 外部服务**：使用 `unittest.mock` 或 `pytest-mock` +- **测试边界情况**：空输入、None 值、错误情况 +- **保持测试快速**：避免 `sleep()` 和外部 I/O +- **使用 pytest 标记**：例如 `@pytest.mark.slow` 标记慢测试 + +### Fixtures + +常用 fixture 定义在 `scripts/tests/conftest.py`： + +```python +# 在测试中使用 fixture +def test_something(tmp_path): + """tmp_path fixture 提供临时目录。""" + test_file = tmp_path / "test.txt" + test_file.write_text("content") + assert test_file.read_text() == "content" +``` + +## 覆盖率报告 + +### 本地覆盖率 + +```bash +# 生成覆盖率报告 +pytest scripts/tests/ --cov=scripts --cov-report=html + +# 在浏览器中打开覆盖率报告 +open htmlcov/index.html +``` + +### 覆盖率目标 + +- **最低覆盖率**：80% +- **分支覆盖率**：启用 +- **重点区域**：核心功能和错误路径 + +## Pre-commit Hooks + +项目使用 pre-commit hooks 在每次提交前自动运行检查： + +```bash +# 安装 pre-commit hooks +pre-commit install + +# 手动运行 hooks +pre-commit run --all-files + +# 跳过某次提交的 hooks（不推荐） +git commit --no-verify +``` + +在 `.pre-commit-config.yaml` 中配置的 hooks： +- Ruff formatter +- Ruff linter +- Bandit security scanner +- YAML validation +- 文件大小检查 +- 合并冲突检测 + +## 排障 + +### 本地测试通过，但 CI 失败 + +常见原因： +1. **Python 版本差异**：CI 使用 3.10、3.11、3.12 +2. **依赖缺失**：更新 `requirements-dev.txt` +3. **平台差异**：路径分隔符、环境变量 +4. **测试不稳定**：依赖时序或执行顺序的测试 + +解决方案： +```bash +# 使用相同的 Python 版本测试 +uv python install 3.10 3.11 3.12 + +# 使用干净环境测试 +rm -rf .venv +uv venv +uv pip install -r requirements-dev.txt +pytest scripts/tests/ +``` + +### Bandit 报告误报 + +某些安全警告可能是误报。可在 `pyproject.toml` 中配置： + +```toml +[tool.bandit] +exclude_dirs = ["scripts/tests"] +skips = ["B101"] # 跳过 assert_used 警告 +``` + +### 类型检查太严格 + +对特定文件放宽类型检查： + +```python +# 放在文件顶部 +# type: ignore + +# 或者针对特定行 +some_dynamic_code() # type: ignore +``` + +## 持续集成最佳实践 + +1. **保持测试快速**：每个测试最好在 1 秒内完成 +2. **不要测试外部 API**：用 mock 替代外部服务 +3. **测试要隔离**：每个测试都应独立 +4. **断言要清晰**：写 `assert x == 5`，不要写 `assert x` +5. **处理异步测试**：使用 `@pytest.mark.asyncio` +6. **生成报告**：覆盖率、安全扫描、类型检查 + +## 资源 + +- [pytest Documentation](https://docs.pytest.org/) +- [Ruff Documentation](https://docs.astral.sh/ruff/) +- [Bandit Documentation](https://bandit.readthedocs.io/) +- [mypy Documentation](https://mypy.readthedocs.io/) +- [GitHub Actions Documentation](https://docs.github.com/en/actions) + +## 贡献测试 + +提交 PR 时： + +1. **为新功能编写测试** +2. **本地运行测试**：`pytest scripts/tests/ -v` +3. **检查覆盖率**：`pytest scripts/tests/ --cov=scripts` +4. **运行 lint**：`ruff check scripts/` +5. **安全扫描**：`bandit -r scripts/ --exclude scripts/tests/` +6. **如果测试变化，更新文档** + +所有 PR 都必须包含测试！🧪 + +--- + +如果你对测试有问题或疑问，请在 GitHub 上创建 issue 或 discussion。 diff --git a/zh/.github/pull_request_template.md b/zh/.github/pull_request_template.md new file mode 100644 index 0000000..03bf75f --- /dev/null +++ b/zh/.github/pull_request_template.md @@ -0,0 +1,57 @@ +## 描述 +简要说明这个 PR 做了什么。 + +## 变更类型 +- [ ] 新增示例或模板 +- [ ] 文档改进 +- [ ] Bug 修复 +- [ ] 功能指南 +- [ ] 其他（请说明） + +## 相关 Issues +Closes #(issue number) + +## 已做的修改 +- 修改 1 +- 修改 2 +- 修改 3 + +## 需要重点查看的内容 +审阅者应该重点关注什么？ + +## 变更文件 +- `path/to/file1.md` +- `path/to/file2.md` + +## 测试 +你如何测试的？ +- [ ] 已在 Claude Code 本地测试 +- [ ] 已验证示例可用 +- [ ] 已检查链接和引用 +- [ ] 已检查拼写和清晰度 + +## 检查清单 +- [ ] 符合项目结构和规范 +- [ ] 包含清晰的文档 / 示例 +- [ ] 代码 / 示例可直接复制使用 +- [ ] 所有链接都已验证且可用 +- [ ] 没有包含敏感信息（密钥、token、凭证） +- [ ] 已更新相关 README 文件 +- [ ] Commit 信息符合 conventional commit 格式 +- [ ] 没有添加大文件（>1MB） + +## 截图或示例 +如有必要，展示这个 PR 增加的内容： +``` +[示例代码或前后对比] +``` + +## 破坏性变更 +这个变更是否影响现有内容或行为？ +- [ ] 没有破坏性变更 +- [ ] 是，并已在下方说明 + +如果有，请描述： + +## 其他说明 +还有哪些信息需要审阅者了解？ diff --git a/zh/01-slash-commands/README.md b/zh/01-slash-commands/README.md new file mode 100644 index 0000000..29f4523 --- /dev/null +++ b/zh/01-slash-commands/README.md @@ -0,0 +1,551 @@ + + + Claude How To + + +# 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 ` | 添加工作目录 | +| `/agents` | 管理 agent 配置 | +| `/branch [name]` | 将当前对话分支到新会话（别名：`/fork`。注意：`/fork` 在 v2.1.77 中更名为 `/branch`） | +| `/btw ` | 额外问题，不写入历史 | +| `/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 ` | 使用 worktree 编排大规模并行修改 | +| `/claude-api` | 加载 Claude API 参考，便于为项目所用语言编写代码 | +| `/debug [description]` | 启用调试日志 | +| `/loop [interval] ` | 按固定间隔重复运行提示词 | +| `/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____` 命令使用，见 [MCP Prompts as Commands](#mcp-prompts-作为命令) + +## 自定义命令（现已归入 Skills） + +自定义 slash command 已经**合并到 Skills**。两种方式都可以通过 `/command-name` 调用： + +| 方式 | 位置 | 状态 | +|----------|----------|--------| +| **Skills（推荐）** | `.claude/skills//SKILL.md` | 当前标准 | +| **旧式命令** | `.claude/commands/.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____ [arguments] +``` + +**示例：** +```bash +/mcp__github__list_prs +/mcp__github__pr_review 456 +/mcp__jira__create_issue "Bug title" high +``` + +### MCP 权限语法 + +在权限中控制 MCP server 访问： + +- `mcp__github` - 访问整个 GitHub MCP server +- `mcp__github__*` - 通配符访问全部工具 +- `mcp__github__get_issue` - 访问某个特定工具 + +## 命令架构 + +```mermaid +graph TD + A["用户输入：/command-name"] --> B{"命令类型？"} + B -->|内置| C["执行内置命令"] + B -->|Skill| D["加载 SKILL.md"] + B -->|插件| E["加载插件命令"] + B -->|MCP| F["执行 MCP Prompt"] + + D --> G["解析 Frontmatter"] + G --> H["替换变量"] + H --> I["执行 Shell 命令"] + I --> J["发送给 Claude"] + J --> K["返回结果"] +``` + +## 命令生命周期 + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant FS as File System + participant CLI as Shell/Bash + + User->>Claude: 输入 /optimize + Claude->>FS: 搜索 .claude/skills/ 和 .claude/commands/ + FS-->>Claude: 返回 optimize/SKILL.md + Claude->>Claude: 解析 frontmatter + Claude->>CLI: 执行 !`command` 替换 + CLI-->>Claude: 命令输出 + Claude->>Claude: 替换 $ARGUMENTS + Claude->>User: 处理 prompt + Claude->>User: 返回结果 +``` + +## 本文件中的可用命令 + +这些示例命令可以作为 skill 或旧式命令安装。 + +### 1. `/optimize` - 代码优化 + +分析性能问题、内存泄漏和优化机会。 + +**用法：** +```text +/optimize +[粘贴你的代码] +``` + +**文件：** [optimize.md](optimize.md) + +### 2. `/pr` - Pull Request 准备 + +引导你完成 PR 准备清单，包括 lint、测试和提交格式整理。 + +**用法：** +```text +/pr +``` + +**文件：** [pr.md](pr.md) + +**截图：** +![/pr](pr-slash-command.png) + +### 3. `/generate-api-docs` - API 文档生成器 + +从源码生成完整的 API 文档。 + +**用法：** +```text +/generate-api-docs +``` + +**文件：** [generate-api-docs.md](generate-api-docs.md) + +### 4. `/commit` - 带上下文的 Git Commit + +基于仓库中的动态上下文创建 git commit。 + +**用法：** +```text +/commit [可选说明] +``` + +**文件：** [commit.md](commit.md) + +### 5. `/push-all` - 暂存、提交并推送 + +会先暂存所有改动，再提交，并带安全检查地推送到远端。 + +**用法：** +```text +/push-all +``` + +**文件：** [push-all.md](push-all.md) + +**安全检查：** +- 密钥文件：`.env*`、`*.key`、`*.pem`、`credentials.json` +- API Keys：识别真实 key 与占位符 +- 大文件：未使用 Git LFS 且大于 10MB +- 构建产物：`node_modules/`、`dist/`、`__pycache__/` + +### 6. `/doc-refactor` - 文档重构 + +重组项目文档，让结构更清晰、可访问性更好。 + +**文件：** [doc-refactor.md](doc-refactor.md) + +### 7. `/setup-ci-cd` - CI/CD 流水线配置 + +实现 pre-commit hooks 和 GitHub Actions 质量保障流程。 + +**文件：** [setup-ci-cd.md](setup-ci-cd.md) + +### 8. `/unit-test-expand` - 测试覆盖率扩展 + +针对未测试分支和边界情况，提升测试覆盖率。 + +**文件：** [unit-test-expand.md](unit-test-expand.md) + +## 安装 + +### 作为 Skills（推荐） + +复制到你的 skills 目录： + +```bash +# 创建 skills 目录 +mkdir -p .claude/skills + +# 对每个命令文件，创建一个 skill 目录 +for cmd in optimize pr commit; do + mkdir -p .claude/skills/$cmd + cp 01-slash-commands/$cmd.md .claude/skills/$cmd/SKILL.md +done +``` + +### 作为旧式命令 + +复制到 commands 目录： + +```bash +# 项目范围（团队） +mkdir -p .claude/commands +cp 01-slash-commands/*.md .claude/commands/ + +# 个人使用 +mkdir -p ~/.claude/commands +cp 01-slash-commands/*.md ~/.claude/commands/ +``` + +## 创建你自己的命令 + +### Skill 模板（推荐） + +创建 `.claude/skills/my-command/SKILL.md`： + +```yaml +--- +name: my-command +description: 这个命令做什么。用于 [触发条件]。 +argument-hint: [可选参数] +allowed-tools: Bash(npm *), Read, Grep +--- + +# Command Title + +## 上下文 + +- 当前分支：!`git branch --show-current` +- 相关文件：@package.json + +## 指令 + +1. 第一步 +2. 第二步，参数：$ARGUMENTS +3. 第三步 + +## 输出格式 + +- 如何格式化回复 +- 需要包含什么 +``` + +### 仅用户可调用的命令（无自动触发） + +对于带副作用、Claude 不应自动触发的命令： + +```yaml +--- +name: deploy +description: 部署到生产环境 +disable-model-invocation: true +allowed-tools: Bash(npm *), Bash(git *) +--- + +将应用部署到生产环境： + +1. 运行测试 +2. 构建应用 +3. 推送到部署目标 +4. 验证部署 +``` + +## 最佳实践 + +| 应该做 | 不要做 | +|------|---------| +| 使用清晰、以动作导向的命名 | 为一次性任务创建命令 | +| 在 `description` 中写清触发条件 | 在命令里写太复杂的逻辑 | +| 保持命令聚焦于单一任务 | 硬编码敏感信息 | +| 有副作用时使用 `disable-model-invocation` | 跳过 description 字段 | +| 用 `!` 前缀注入动态上下文 | 假设 Claude 知道当前状态 | +| 把相关文件组织进 skill 目录 | 所有内容都塞进一个文件 | + +## 故障排查 + +### 找不到命令 + +**解决办法：** +- 检查文件是否位于 `.claude/skills//SKILL.md` 或 `.claude/commands/.md` +- 确认 frontmatter 中的 `name` 与预期命令名一致 +- 重启 Claude Code 会话 +- 运行 `/help` 查看可用命令 + +### 命令没有按预期执行 + +**解决办法：** +- 补充更具体的指令 +- 在 skill 文件中加入示例 +- 如果使用 bash 命令，检查 `allowed-tools` +- 先用简单输入测试 + +### Skill 与 Command 冲突 + +如果同名同时存在，**skill 优先**。删除其中一个或重命名即可。 + +## 相关指南 + +- **[Skills](../03-skills/README.md)** - 完整的 Skills 参考 +- **[Memory](../02-memory/README.md)** - 带 `CLAUDE.md` 的持久上下文 +- **[Subagents](../04-subagents/README.md)** - 委派式 AI agents +- **[Plugins](../07-plugins/README.md)** - 打包好的命令集合 +- **[Hooks](../06-hooks/README.md)** - 事件驱动自动化 + +## 其他资源 + +- [官方交互模式文档](https://code.claude.com/docs/en/interactive-mode) - 内置命令参考 +- [官方 Skills 文档](https://code.claude.com/docs/en/skills) - 完整 Skills 参考 +- [CLI Reference](https://code.claude.com/docs/en/cli-reference) - 命令行选项 + +--- + +*Claude How To 指南系列的一部分* diff --git a/zh/01-slash-commands/commit.md b/zh/01-slash-commands/commit.md new file mode 100644 index 0000000..99d6fa2 --- /dev/null +++ b/zh/01-slash-commands/commit.md @@ -0,0 +1,26 @@ +--- +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*) +argument-hint: [message] +description: 创建带上下文的 Git 提交 +--- + +## 上下文 + +- 当前 git 状态: !`git status` +- 当前 git diff: !`git diff HEAD` +- 当前分支: !`git branch --show-current` +- 最近的提交: !`git log --oneline -10` + +## 你的任务 + +根据上面的变更创建一个单独的 Git 提交。 + +如果通过参数传入了 message，就直接使用它：$ARGUMENTS + +否则，分析这些变更，并按照 conventional commits 格式生成合适的提交信息： +- `feat:` 新功能 +- `fix:` 修复 bug +- `docs:` 文档变更 +- `refactor:` 代码重构 +- `test:` 新增测试 +- `chore:` 维护任务 diff --git a/zh/01-slash-commands/doc-refactor.md b/zh/01-slash-commands/doc-refactor.md new file mode 100644 index 0000000..4569912 --- /dev/null +++ b/zh/01-slash-commands/doc-refactor.md @@ -0,0 +1,24 @@ +--- +name: 文档重构 +description: 为项目重新组织文档结构，以提升清晰度和可访问性 +tags: documentation, refactoring, organization +--- + +# 文档重构 + +根据项目类型重构项目文档结构： + +1. **分析项目**：识别类型（库/API/Web 应用/CLI/微服务）、架构和用户角色 +2. **集中管理文档**：将技术文档迁移到 `docs/`，并保留正确的交叉引用 +3. **整理根目录 README.md**：将其精简为入口页，包含概览、快速开始、模块/组件摘要、许可证和联系方式 +4. **为组件补充文档**：添加模块/包/服务级别的 README 文件，包含安装和测试说明 +5. **按主题组织 `docs/`**： + - 架构、API Reference、数据库、设计、故障排查、部署、贡献（根据项目需要调整） +6. **创建指南**（按需选择）： + - 用户指南：面向应用最终用户的文档 + - API 文档：API 的端点、认证和示例 + - 开发指南：环境搭建、测试、贡献流程 + - 部署指南：服务/应用的生产部署 +7. **所有图表都使用 Mermaid**（架构图、流程图、Schema 图） + +保持文档简洁、易扫读，并与项目类型保持上下文一致。 diff --git a/zh/01-slash-commands/generate-api-docs.md b/zh/01-slash-commands/generate-api-docs.md new file mode 100644 index 0000000..8075f67 --- /dev/null +++ b/zh/01-slash-commands/generate-api-docs.md @@ -0,0 +1,19 @@ +--- +description: 根据源代码生成完整的 API 文档 +--- + +# API 文档生成器 + +按以下步骤生成 API 文档： + +1. 扫描 `/src/api/` 下的所有文件 +2. 提取函数签名和 JSDoc 注释 +3. 按端点/模块进行组织 +4. 生成带示例的 Markdown +5. 包含请求/响应 Schema +6. 添加错误文档 + +输出格式： +- 输出为 `/docs/api.md` 中的 Markdown 文件 +- 为所有端点加入 curl 示例 +- 添加 TypeScript 类型 diff --git a/zh/01-slash-commands/optimize.md b/zh/01-slash-commands/optimize.md new file mode 100644 index 0000000..e8ebe08 --- /dev/null +++ b/zh/01-slash-commands/optimize.md @@ -0,0 +1,19 @@ +--- +description: 分析代码中的性能问题并提出优化建议 +--- + +# 代码优化 + +按优先级审查提供的代码，重点关注以下问题： + +1. **性能瓶颈** - 识别 O(n²) 操作和低效循环 +2. **内存泄漏** - 查找未释放的资源、循环引用 +3. **算法改进** - 建议更好的算法或数据结构 +4. **缓存机会** - 识别重复计算 +5. **并发问题** - 查找竞态条件或线程问题 + +请按以下格式输出： +- 问题严重性（Critical/High/Medium/Low） +- 代码位置 +- 解释 +- 推荐修复方案，附代码示例 diff --git a/zh/01-slash-commands/pr.md b/zh/01-slash-commands/pr.md new file mode 100644 index 0000000..81dfdec --- /dev/null +++ b/zh/01-slash-commands/pr.md @@ -0,0 +1,26 @@ +--- +description: 清理代码、暂存变更并准备 Pull Request +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(npm test:*), Bash(npm run lint:*) +--- + +# Pull Request 准备清单 + +在创建 PR 之前，请执行以下步骤： + +1. 运行格式化：`prettier --write .` +2. 运行测试：`npm test` +3. 查看 git diff：`git diff HEAD` +4. 暂存变更：`git add .` +5. 按 conventional commits 创建提交信息： + - `fix:` bug 修复 + - `feat:` 新功能 + - `docs:` 文档 + - `refactor:` 代码重构 + - `test:` 测试新增 + - `chore:` 维护 + +6. 生成 PR 摘要，包含： + - 变更了什么 + - 为什么变更 + - 做了哪些测试 + - 可能的影响 diff --git a/zh/01-slash-commands/push-all.md b/zh/01-slash-commands/push-all.md new file mode 100644 index 0000000..6974c32 --- /dev/null +++ b/zh/01-slash-commands/push-all.md @@ -0,0 +1,152 @@ +--- +description: 暂存所有变更，创建提交并推送到远程（请谨慎使用） +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git push:*), Bash(git diff:*), Bash(git log:*), Bash(git pull:*) +--- + +# 提交并推送全部内容 + +⚠️ **注意**：将所有变更都暂存、提交并推送到远程。只有在你确认所有改动都应该放在一起时才使用。 + +## 工作流 + +### 1. 分析变更 +并行运行： +- `git status` - 显示已修改/已添加/已删除/未跟踪文件 +- `git diff --stat` - 显示变更统计 +- `git log -1 --oneline` - 查看最近一次提交，便于统一提交信息风格 + +### 2. 安全检查 + +**❌ 如果发现以下内容，立即停止并警告：** +- Secrets：`.env*`、`*.key`、`*.pem`、`credentials.json`、`secrets.yaml`、`id_rsa`、`*.p12`、`*.pfx`、`*.cer` +- API Keys：任何 `*_API_KEY`、`*_SECRET`、`*_TOKEN` 变量包含真实值，而不是占位符，如 `your-api-key`、`xxx`、`placeholder` +- 大文件：`>10MB` 且未使用 Git LFS +- 构建产物：`node_modules/`、`dist/`、`build/`、`__pycache__/`、`*.pyc`、`.venv/` +- 临时文件：`.DS_Store`、`thumbs.db`、`*.swp`、`*.tmp` + +**API Key 校验：** +检查修改文件中是否存在以下模式： +```bash +OPENAI_API_KEY=sk-proj-xxxxx # ❌ 检测到真实密钥！ +AWS_SECRET_KEY=AKIA... # ❌ 检测到真实密钥！ +STRIPE_API_KEY=sk_live_... # ❌ 检测到真实密钥！ + +# ✅ 可接受的占位符： +API_KEY=your-api-key-here +SECRET_KEY=placeholder +TOKEN=xxx +API_KEY= +SECRET=${YOUR_SECRET} +``` + +**✅ 确认：** +- `.gitignore` 配置正确 +- 没有合并冲突 +- 分支正确（如果是 `main`/`master` 要提醒） +- API key 只是占位符 + +### 3. 请求确认 + +展示摘要： +``` +📊 变更摘要： +- X 个文件已修改，Y 个文件已新增，Z 个文件已删除 +- 总计：+AAA 行新增，-BBB 行删除 + +🔒 安全性：✅ 无 secrets | ✅ 无大文件 | ⚠️ [警告] +🌿 分支： [name] → origin/[name] + +我将执行：git add . → commit → push + +请输入 'yes' 继续，或输入 'no' 取消。 +``` + +**在收到明确的 "yes" 之前不要继续。** + +### 4. 执行（确认后） + +按顺序运行： +```bash +git add . +git status # 验证暂存状态 +``` + +### 5. 生成提交信息 + +分析变更并创建 conventional commit： + +**格式：** +``` +[type]: 简要摘要（最多 72 个字符） + +- 关键改动 1 +- 关键改动 2 +- 关键改动 3 +``` + +**类型：** `feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`、`perf`、`build`、`ci` + +**示例：** +``` +docs: 更新概念文档，补充完整说明 + +- 添加架构图和表格 +- 补充实用示例 +- 扩展最佳实践部分 +``` + +### 6. 提交并推送 + +```bash +git commit -m "$(cat <<'EOF' +[生成的提交信息] +EOF +)" +git push # 如果失败：git pull --rebase && git push +git log -1 --oneline --decorate # 验证 +``` + +### 7. 确认成功 + +``` +✅ 已成功推送到远程！ + +Commit: [hash] [message] +Branch: [branch] → origin/[branch] +Files changed: X (+insertions, -deletions) +``` + +## 错误处理 + +- `git add` 失败：检查权限、锁定文件，确认仓库已初始化 +- `git commit` 失败：修复 pre-commit hooks，检查 git 配置（user.name/email） +- `git push` 失败： + - 非快进：`git pull --rebase && git push` + - 没有远程分支：`git push -u origin [branch]` + - 受保护分支：改用 PR 工作流 + +## 适用场景 + +✅ **适合：** +- 多文件文档更新 +- 同时包含测试和文档的功能 +- 跨多个文件的 bug 修复 +- 项目级格式化/重构 +- 配置变更 + +❌ **避免：** +- 不确定要提交哪些内容 +- 包含 secrets/敏感数据 +- 受保护分支且未经过审核 +- 存在合并冲突 +- 想保留更细粒度的提交历史 +- pre-commit hooks 失败 + +## 替代方案 + +如果用户想保留控制权，可以建议： +1. **选择性暂存**：查看并暂存特定文件 +2. **交互式暂存**：使用 `git add -p` 逐块选择 +3. **PR 工作流**：创建分支 → 推送 → 发起 PR（使用 `/pr` 命令） + +**⚠️ 记住**：在推送前始终先检查变更。拿不准时，使用单独的 git 命令会更可控。 diff --git a/zh/01-slash-commands/setup-ci-cd.md b/zh/01-slash-commands/setup-ci-cd.md new file mode 100644 index 0000000..7e21df8 --- /dev/null +++ b/zh/01-slash-commands/setup-ci-cd.md @@ -0,0 +1,25 @@ +--- +name: 设置 CI/CD 流水线 +description: 实现 pre-commit hooks 和 GitHub Actions 质量保障 +tags: ci-cd, devops, automation +--- + +# 设置 CI/CD 流水线 + +根据项目类型实现完整的 DevOps 质量门禁： + +1. **分析项目**：检测语言、框架、构建系统和现有工具链 +2. **配置 pre-commit hooks**，使用与语言匹配的工具： + - 格式化：Prettier/Black/gofmt/rustfmt 等 + - 代码检查：ESLint/Ruff/golangci-lint/Clippy 等 + - 安全：Bandit/gosec/cargo-audit/npm audit 等 + - 类型检查：TypeScript/mypy/flow（如适用） + - 测试：运行相关测试套件 +3. **创建 GitHub Actions 工作流**（`.github/workflows/`）： + - 在 push/PR 时镜像 pre-commit 检查 + - 多版本/多平台矩阵（如适用） + - 构建和测试验证 + - 部署步骤（如需要） +4. **验证流水线**：本地测试、创建测试 PR，确认所有检查都通过 + +使用免费/开源工具。尊重已有配置。保持执行快速。 diff --git a/zh/01-slash-commands/unit-test-expand.md b/zh/01-slash-commands/unit-test-expand.md new file mode 100644 index 0000000..9867ec0 --- /dev/null +++ b/zh/01-slash-commands/unit-test-expand.md @@ -0,0 +1,25 @@ +--- +name: 扩充单元测试 +description: 通过覆盖未测试分支和边界情况来提高测试覆盖率 +tags: testing, coverage, unit-tests +--- + +# 扩充单元测试 + +根据项目的测试框架，扩充现有单元测试： + +1. **分析覆盖率**：运行覆盖率报告，找出未测试分支、边界情况和低覆盖区域 +2. **识别缺口**：审查代码中的逻辑分支、错误路径、边界条件、空值/空输入 +3. **编写测试**，使用项目现有框架： + - Jest/Vitest/Mocha（JavaScript/TypeScript） + - pytest/unittest（Python） + - Go testing/testify（Go） + - Rust test framework（Rust） +4. **针对具体场景**： + - 错误处理和异常 + - 边界值（最小/最大、空值、空输入） + - 边缘情况和极端情况 + - 状态转换和副作用 +5. **验证提升**：再次运行覆盖率，确认有可衡量的提升 + +只展示新增的测试代码块。遵循现有测试模式和命名约定。 diff --git a/zh/02-memory/README.md b/zh/02-memory/README.md new file mode 100644 index 0000000..5bc1734 --- /dev/null +++ b/zh/02-memory/README.md @@ -0,0 +1,305 @@ + + + Claude How To + + +# Memory 指南 + +## 概览 + +Memory 让 Claude Code 在不同会话之间保留上下文。你可以把团队规范、项目规则、个人偏好和目录级约束写进 `CLAUDE.md`，让 Claude 在合适的时候自动加载。 + +## Memory 命令速查 + +| 命令 | 作用 | +|------|------| +| `/init` | 初始化项目级 `CLAUDE.md` | +| `/memory` | 打开并编辑记忆文件 | +| `#` | 快速把当前规则写入 memory | + +## 快速上手：初始化 Memory + +### 使用 `/init` + +在项目目录中运行： + +```bash +/init +``` + +Claude 会根据当前项目生成一个 `CLAUDE.md`，通常包含类似如下结构： + +```md +# 项目配置 +## 项目概览 +## 开发规范 +``` + +### 使用 `#` 快速更新记忆 + +当你想把一句规则写入 memory 时，可以直接在输入前加 `#`： + +```text +# 这个项目始终使用 TypeScript 严格模式 +# 优先使用 async/await，而不是 promise 链 +# 每次提交前都运行 npm test +# 文件名统一使用 kebab-case +``` + +这会把规则加入当前会话能感知到的记忆中。 + +### 使用 `/memory` + +`/memory` 会打开记忆编辑器，让你在不同范围之间切换： + +1. 受管策略记忆 +2. 项目记忆（`./CLAUDE.md`） +3. 用户记忆（`~/.claude/CLAUDE.md`） +4. 本地项目记忆 + +适合你把长期规则、项目规范和个人偏好分层管理。 + +## Memory 架构 + +Claude Code 的记忆系统通常有以下层级： + +| 层级 | 作用范围 | 典型内容 | +|------|----------|----------| +| 受管策略 | 组织级 | 合规、安全、统一流程 | +| 项目记忆 | 单个项目 | 架构、编码标准、工作流 | +| 目录记忆 | 子目录 | 模块约束、局部规范 | +| 用户记忆 | 单个用户 | 个人偏好、默认设置 | + +## 记忆层级 + +Claude 会按更接近当前上下文的规则优先使用更具体的 memory。一般来说： + +- 组织级规则优先于普通偏好 +- 项目规则优先于个人偏好 +- 目录级规则优先于项目级通用规则 + +## 排除规则 + +如果某些 `CLAUDE.md` 不应该被自动加载，可以通过 `claudeMdExcludes` 之类的设置排除。 + +## 配置文件层级 + +项目设置、用户设置和企业托管设置会共同影响 memory 的加载方式。你可以把它理解为： + +1. 组织策略 +2. 项目设置 +3. 本地设置 +4. 临时会话输入 + +## 模块化规则系统 + +Memory 不一定要写成一个巨大文件。你可以把规则拆成多个目录文件，再按路径组织。 + +### 通过 YAML frontmatter 设置路径规则 + +```md +--- +description: API development rules +--- + +# API Development Rules +``` + +### 子目录与符号链接 + +你可以用子目录和 symlink 把局部规则复用到多个项目区域。 + +## Memory 位置表 + +常见位置包括： + +- 项目根目录的 `CLAUDE.md` +- 用户目录的 `~/.claude/CLAUDE.md` +- 子目录的 `CLAUDE.md` + +## Memory 更新生命周期 + +一般流程是： + +1. 创建或编辑 `CLAUDE.md` +2. Claude 重新加载 +3. 新规则在后续会话中生效 + +## Auto Memory + +Auto memory 让 Claude 根据当前目录自动寻找并加载合适的记忆文件。 + +### 工作方式 + +Claude 会根据当前工作目录、父目录和已配置路径，逐层查找相关 memory。 + +### 目录结构 + +```text +project/ +├── CLAUDE.md +├── src/ +│ ├── CLAUDE.md +│ └── api/ +│ └── CLAUDE.md +``` + +### 版本要求 + +某些 auto memory 行为依赖较新的 Claude Code 版本。 + +### 自定义 auto memory 目录 + +如果默认目录不适合你的项目，可以在设置中指定新的 memory 路径。 + +### worktree 和仓库共享 + +在 worktree、monorepo 或多人协作场景中，auto memory 可以帮助保持规则一致。 + +### Subagent 记忆 + +Subagents 也可以拥有自己的记忆范围，用于在各自职责内保持一致性。 + +### 控制 auto memory + +```bash +# 当前会话禁用 auto memory + +# 显式开启 auto memory +``` + +## 通过 `--add-dir` 添加额外目录 + +你可以用 `--add-dir` 把额外目录也加入 Claude 的可见范围，适合多目录协作。 + +## 实战示例 + +### 示例 1：项目记忆结构 + +```md +# 项目配置 +## 项目概览 +## 架构 +## 开发规范 +### 代码风格 +### 命名约定 +### Git 工作流 +### 测试要求 +### API 规范 +### 数据库 +### 部署 +## 常用命令 +## 团队联系人 +## 已知问题与解决办法 +## 相关项目 +``` + +### 示例 2：目录级记忆 + +```md +# API 模块规范 +## API 专属规范 +### 请求校验 +### 身份验证 +### 响应格式 +### 分页 +### 限流 +### 缓存 +``` + +### 示例 3：个人记忆 + +```md +# 我的开发偏好 +## 关于我 +## 代码偏好 +### 错误处理 +### 注释 +### 测试 +### 架构 +## 调试偏好 +## 沟通方式 +## 项目组织 +## 工具链 +``` + +### 示例 4：会话中更新记忆 + +两种常见方式： + +1. 直接提要求，让 Claude 把规则写进 memory +2. 使用 `# new rule into memory` 这种模式追加规则 + +## 最佳实践 + +### 应该做的 + +- 用项目记忆保存团队标准 +- 用目录记忆保存局部差异 +- 先写简洁规则，再逐步补充 +- 把可重复内容写进 `CLAUDE.md` + +### 不应该做的 + +- 不要把 README 整份复制进 `CLAUDE.md` +- 不要把明显属于代码的实现细节硬塞进 memory +- 不要让 memory 变成垃圾桶 + +### 记忆管理建议 + +- 优先引用已有文档，而不是重复粘贴 +- 只保留真正影响 Claude 行为的信息 +- 定期整理过期或冲突的规则 + +## 安装说明 + +### 设置项目记忆 + +#### 方法 1：使用 `/init`（推荐） + +```bash +/init +``` + +#### 方法 2：手动创建 + +```bash +cp project-CLAUDE.md CLAUDE.md +``` + +#### 方法 3：快速更新 + +```text +# Use semantic versioning for all releases +# Always run tests before committing +# Prefer composition over inheritance +``` + +### 设置个人记忆 + +```bash +cp personal-CLAUDE.md ~/.claude/CLAUDE.md +``` + +### 设置目录记忆 + +```bash +cp directory-api-CLAUDE.md src/api/CLAUDE.md +``` + +### 验证安装 + +- 重新打开 Claude Code 会话 +- 检查 `CLAUDE.md` 是否被自动加载 +- 用一条明显会受 memory 影响的提示词测试 + +## 官方文档 + +如果你想看更详细的行为定义、兼容性和最新限制，建议参考 Claude Code 官方 memory 文档。 + +## 相关概念 + +- [Slash Commands 中文参考](../01-slash-commands/README.md) +- [Skills 中文指南](../03-skills/README.md) +- [Subagents 中文参考](../04-subagents/README.md) +- [Advanced Features 中文指南](../09-advanced-features/README.md) diff --git a/zh/02-memory/directory-api-CLAUDE.md b/zh/02-memory/directory-api-CLAUDE.md new file mode 100644 index 0000000..200187d --- /dev/null +++ b/zh/02-memory/directory-api-CLAUDE.md @@ -0,0 +1,62 @@ +# API 模块规范 + +本文件会覆盖 `/src/api/` 下所有内容对应的根目录 `CLAUDE.md`。 + +## API 专属规范 + +### 请求校验 +- 使用 Zod 做 schema 校验 +- 始终校验输入 +- 校验失败时返回 400 +- 提供字段级别的错误详情 + +### 认证 +- 所有端点都需要 JWT token +- token 放在 `Authorization` header 中 +- token 24 小时后过期 +- 实现 refresh token 机制 + +### 响应格式 + +所有响应都必须遵循下面的结构： + +```json +{ + "success": true, + "data": { /* 实际数据 */ }, + "timestamp": "2025-11-06T10:30:00Z", + "version": "1.0" +} +``` + +错误响应： + +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "用户可读消息", + "details": { /* 字段错误 */ } + }, + "timestamp": "2025-11-06T10:30:00Z" +} +``` + +### 分页 +- 使用基于 cursor 的分页，而不是 offset +- 包含 `hasMore` 布尔值 +- 单页最大数量限制为 100 +- 默认页大小：20 + +### 限流 +- 已认证用户每小时 1000 次请求 +- 公开端点每小时 100 次请求 +- 超出时返回 429 +- 包含 `retry-after` header + +### 缓存 +- 使用 Redis 做会话缓存 +- 缓存时长默认 5 分钟 +- 写操作时失效缓存 +- 用资源类型给缓存键打标签 diff --git a/zh/02-memory/personal-CLAUDE.md b/zh/02-memory/personal-CLAUDE.md new file mode 100644 index 0000000..9a5c612 --- /dev/null +++ b/zh/02-memory/personal-CLAUDE.md @@ -0,0 +1,61 @@ +# 我的开发偏好 + +## 关于我 +- **经验水平**：8 年全栈开发经验 +- **偏好语言**：TypeScript、Python +- **沟通风格**：直接，最好带例子 +- **学习风格**：配合代码的可视化图示 + +## 代码偏好 + +### 错误处理 +我偏好显式的错误处理，使用 `try-catch` 和有意义的错误消息。 +避免使用泛化错误。为了便于调试，始终记录错误日志。 + +### 注释 +注释应解释“为什么”，而不是“是什么”。代码本身应该尽量能自解释。 +注释应该说明业务逻辑或者不明显的设计决策。 + +### 测试 +我偏好 TDD（测试驱动开发）。 +先写测试，再写实现。 +重点关注行为，而不是实现细节。 + +### 架构 +我偏好模块化、低耦合的设计。 +使用依赖注入提升可测试性。 +拆分关注点，例如 Controllers、Services、Repositories。 + +## 调试偏好 +- 使用带前缀的 `console.log`：`[DEBUG]` +- 包含上下文：函数名、相关变量 +- 如果有堆栈信息，优先使用 +- 日志里始终带时间戳 + +## 沟通方式 +- 用图示解释复杂概念 +- 先给具体例子，再讲理论 +- 提供修改前 / 修改后的代码片段 +- 在结尾总结关键点 + +## 项目组织 +我通常会这样组织项目： + +```text +project/ + ├── src/ + │ ├── api/ + │ ├── services/ + │ ├── models/ + │ └── utils/ + ├── tests/ + ├── docs/ + └── docker/ +``` + +## 工具链 +- **IDE**：VS Code，带 vim 键位 +- **终端**：Zsh + Oh-My-Zsh +- **格式化**：Prettier，行宽 100 字符 +- **Linter**：ESLint，airbnb 配置 +- **测试框架**：Jest + React Testing Library diff --git a/zh/02-memory/project-CLAUDE.md b/zh/02-memory/project-CLAUDE.md new file mode 100644 index 0000000..57114e0 --- /dev/null +++ b/zh/02-memory/project-CLAUDE.md @@ -0,0 +1,88 @@ +# 项目配置 + +## 项目概览 +- **名称**：电商平台 +- **技术栈**：Node.js、PostgreSQL、React 18、Docker +- **团队规模**：5 名开发者 +- **截止时间**：2025 年第 4 季度 + +## 架构 +@docs/architecture.md +@docs/api-standards.md +@docs/database-schema.md + +## 开发规范 + +### 代码风格 +- 使用 Prettier 格式化 +- 使用带 airbnb 配置的 ESLint +- 最大行长度：100 字符 +- 使用 2 空格缩进 + +### 命名规范 +- **文件**：kebab-case（`user-controller.js`） +- **类**：PascalCase（`UserService`） +- **函数 / 变量**：camelCase（`getUserById`） +- **常量**：UPPER_SNAKE_CASE（`API_BASE_URL`） +- **数据库表**：snake_case（`user_accounts`） + +### Git 工作流 +- 分支命名：`feature/description` 或 `fix/description` +- 提交信息：遵循 conventional commits +- 合并前必须有 PR +- 所有 CI/CD 检查都必须通过 +- 至少需要 1 个 approval + +### 测试要求 +- 最低 80% 代码覆盖率 +- 所有关键路径都必须有测试 +- 单元测试使用 Jest +- E2E 测试使用 Cypress +- 测试文件名：`*.test.ts` 或 `*.spec.ts` + +### API 规范 +- 只允许 RESTful 端点 +- 请求 / 响应都使用 JSON +- 正确使用 HTTP 状态码 +- API 版本路径：`/api/v1/` +- 所有端点都要带示例文档 + +### 数据库 +- schema 变更使用 migrations +- 绝不硬编码凭据 +- 使用连接池 +- 开发环境启用查询日志 +- 需要定期备份 + +### 部署 +- 基于 Docker 的部署 +- 使用 Kubernetes 编排 +- 蓝绿部署策略 +- 失败时自动回滚 +- 部署前先执行数据库迁移 + +## 常用命令 + +| 命令 | 作用 | +|---------|---------| +| `npm run dev` | 启动开发服务器 | +| `npm test` | 运行测试套件 | +| `npm run lint` | 检查代码风格 | +| `npm run build` | 构建生产版本 | +| `npm run migrate` | 执行数据库迁移 | + +## 团队联系人 +- 技术负责人：Sarah Chen（@sarah.chen） +- 产品经理：Mike Johnson（@mike.j） +- 运维：Alex Kim（@alex.k） + +## 已知问题与解决方案 +- PostgreSQL 连接池在高峰期限制为 20 +- 解决方法：实现查询排队 +- Safari 14 对 async generator 的兼容性有问题 +- 解决方法：使用 Babel 转译器 + +## 关联项目 +- 分析仪表盘：`/projects/analytics` +- 移动端 App：`/projects/mobile` +- 管理后台：`/projects/admin` diff --git a/zh/03-skills/README.md b/zh/03-skills/README.md new file mode 100644 index 0000000..00bf0d1 --- /dev/null +++ b/zh/03-skills/README.md @@ -0,0 +1,271 @@ + + + Claude How To + + +# Agent Skills 指南 + +## 概览 + +Skills 是可以复用、可自动触发的能力包。一个 skill 通常包含 `SKILL.md`、参考文件、脚本和模板。Claude 在合适的场景下会自动加载它。 + +### 主要好处 + +- 可复用 +- 可渐进加载 +- 可以把脚本、模板、说明放在一起 +- 适合标准化流程 + +## Skills 的工作方式：渐进式披露 + +Skills 不会一次性把所有内容都塞进上下文，而是按需加载。 + +### 三层加载 + +1. **只看描述**：先判断这个 skill 是否相关 +2. **加载 `SKILL.md`**：读取核心说明 +3. **按需加载支持文件**：脚本、模板、参考资料 + +## Skill 加载流程 + +1. Claude 扫描技能目录 +2. 根据描述判断是否匹配当前任务 +3. 读取 `SKILL.md` +4. 如有需要，再加载脚本和辅助文件 + +## Skill 类型与位置 + +Skills 可以放在： + +- 项目目录下的 `.claude/skills/` +- 用户目录下的 `~/.claude/skills/` + +### 自动发现 + +只要目录结构正确，Claude 就会自动发现这些 Skills。 + +## 创建自定义 Skills + +### 基本目录结构 + +```text +my-skill/ +└── SKILL.md +``` + +### `SKILL.md` 格式 + +```yaml +--- +name: my-skill +description: 这个 skill 的用途，以及什么时候触发 +--- + +# Your Skill Name + +## Instructions + +## Examples +``` + +### 必填字段 + +- `name` +- `description` + +### 可选 frontmatter 字段 + +- `argument-hint` +- `allowed-tools` +- `model` +- `disable-model-invocation` +- `user-invocable` +- `context` +- `agent` +- `hooks` + +## Skill 内容类型 + +### 参考内容 + +适合放规则、标准、文档片段和示例。 + +### 任务内容 + +适合放具体步骤、执行流程和结果格式要求。 + +## 控制 Skill 的调用 + +你可以通过 `disable-model-invocation`、`user-invocable` 和工具白名单来控制 Claude 是否能自动调用这个 skill。 + +## 字符串替换 + +Skills 支持 `$ARGUMENTS`、`$0`、`$1` 等参数替换。 + +### 动态上下文注入 + +你可以在 prompt 里插入 shell 命令结果： + +```md +- 当前 git 状态：!`git status` +- 当前 diff：!`git diff HEAD` +- 当前分支：!`git branch --show-current` +``` + +## 在 subagent 中运行 Skills + +某些 skill 适合在隔离上下文中运行，这样可以降低对主会话的影响。 + +## 实战示例 + +### 示例 1：代码审查 Skill + +一个典型的审查 skill 会包含： + +- 审查模板 +- 风险等级 +- 输出格式 +- 需要关注的维度 + +### 示例 2：代码库可视化 Skill + +可以把代码库结构、依赖关系和模块边界总结给 Claude，便于快速理解。 + +### 示例 3：部署 Skill（只允许用户触发） + +适合带副作用的操作，比如生产环境部署。通常会配合 `disable-model-invocation: true`。 + +### 示例 4：品牌语气 Skill + +用于检查输出是否符合品牌语气、语调和表达风格。 + +### 示例 5：`CLAUDE.md` 生成 Skill + +可以从项目文档中生成或补充 `CLAUDE.md`。 + +### 示例 6：带脚本的重构 Skill + +常见组合是： + +- `SKILL.md` +- `scripts/` +- `templates/` +- `references/` + +## 管理 Skills + +### 查看可用 Skills + +```bash +/skills +``` + +### 测试一个 Skill + +把它放到测试目录或者临时项目里，然后通过相应命令触发。 + +### 更新 Skill + +修改 `SKILL.md` 或支持文件后，重新打开会话或重新加载即可。 + +### 限制 Claude 对 Skill 的访问 + +你可以通过权限配置，只允许 Claude 访问某些 skill。 + +## 最佳实践 + +### 1. 描述要具体 + +让 `description` 明确说明这个 skill 在什么时候触发。 + +### 2. 保持聚焦 + +一个 skill 解决一个问题，不要什么都塞进去。 + +### 3. 包含触发词 + +在描述里加入相关关键词，帮助 Claude 更准确地选择它。 + +### 4. `SKILL.md` 不要太长 + +尽量控制在 500 行以内，超过就拆分支持文件。 + +### 5. 引用支持文件 + +把重复内容移到脚本或参考文件中，主文件只保留核心说明。 + +## 故障排查 + +### 快速参考 + +- 检查目录结构是否正确 +- 检查 `SKILL.md` frontmatter 是否有效 +- 检查 skill 名称是否和调用名一致 + +### Skill 没有触发 + +- 检查描述是否足够具体 +- 检查目录是否在 Claude 可见范围内 +- 检查是否被更高优先级的 skill 覆盖 + +### Skill 触发太频繁 + +- 收紧描述 +- 增加约束条件 +- 用更具体的触发词 + +### Claude 看不到全部 Skills + +- 检查路径 +- 检查权限 +- 重新加载会话 + +## 安全注意事项 + +- 不要在 skill 中硬编码密钥 +- 对副作用操作保持用户触发 +- 给自动触发的 skill 设置清晰边界 + +## Skills vs 其他功能 + +| 功能 | 触发方式 | 适合场景 | +|------|----------|----------| +| Skills | 自动/半自动 | 复用能力、流程标准化 | +| Slash Commands | 手动 | 快捷命令 | +| Subagents | 自动委派 | 隔离任务 | +| Hooks | 事件触发 | 自动化和验证 | + +## 内置 Skills + +Claude Code 自带一些 Skills，例如批处理、调试、简化和 Claude API 相关内容。 + +## 共享 Skills + +### 项目 Skills（团队共享） + +把 skill 放在项目目录里，团队成员都能用。 + +### 个人 Skills + +```bash +# 复制到个人目录 +mkdir -p ~/.claude/skills + +# 让脚本可执行 +chmod +x ~/.claude/skills/*/scripts/* +``` + +### Plugin 分发 + +你也可以把 Skills 作为插件的一部分发布出去。 + +## 继续深入 + +如果你要管理一整套 Skills，可以再做一个 skill collection 或 skill manager，用来统一发现、更新和分发。 + +## 更多资源 + +- [根目录中文指南](../README.md) +- [Slash Commands 中文参考](../01-slash-commands/README.md) +- [Memory 中文指南](../02-memory/README.md) +- [Subagents 中文参考](../04-subagents/README.md) diff --git a/zh/03-skills/blog-draft/SKILL.md b/zh/03-skills/blog-draft/SKILL.md new file mode 100644 index 0000000..02580df --- /dev/null +++ b/zh/03-skills/blog-draft/SKILL.md @@ -0,0 +1,274 @@ +--- +name: blog-draft +description: 根据想法和资料撰写博客草稿。适用于用户想写博客、基于研究创建内容，或起草文章的场景。流程会引导你完成调研、头脑风暴、提纲编写和带版本控制的迭代撰写。 +--- + +## 用户输入 + +```text +$ARGUMENTS +``` + +在继续之前，你**必须**先考虑用户输入。用户应提供： +- **想法/主题**：博客文章的核心概念或主题 +- **资源**：用于研究的 URL、文件或参考资料（可选，但推荐） +- **目标读者**：这篇博客是写给谁看的（可选） +- **语气/风格**：正式、轻松、技术向等（可选） + +**重要**：如果用户是在请求更新一篇**已有博客文章**，请跳过步骤 0-8，直接从**步骤 9** 开始。先阅读现有草稿文件，再继续迭代流程。 + +## 执行流程 + +请按顺序执行以下步骤。**不要跳步，也不要在未获得用户批准的情况下继续执行标明需要确认的步骤。** + +### 步骤 0：创建项目文件夹 + +1. 使用以下格式生成文件夹名称：`YYYY-MM-DD-short-topic-name` + - 使用今天的日期 + - 根据主题生成一个简短、适合 URL 的 slug（小写、连字符连接，最多 5 个词） + +2. 创建文件夹结构： + ```text + blog-posts/ + └── YYYY-MM-DD-short-topic-name/ + └── resources/ + ``` + +3. 在继续前，先向用户确认文件夹已创建。 + +### 步骤 1：研究与资源收集 + +1. 在博客文章目录中创建 `resources/` 子文件夹 + +2. 对于每个提供的资源： + - **URL**：抓取关键内容并保存到 `resources/` 下的 markdown 文件中 + - **文件**：读取并在 `resources/` 中做摘要 + - **主题**：使用网络搜索收集最新信息 + +3. 为每个资源在 `resources/` 中创建摘要文件： + - `resources/source-1-[short-name].md` + - `resources/source-2-[short-name].md` + - 以此类推 + +4. 每个摘要都应包含： + ```markdown + # 来源：[标题/URL] + + ## 要点 + - 要点 1 + - 要点 2 + + ## 相关引文/数据 + - 引文或统计 1 + - 引文或统计 2 + + ## 与主题的关联 + 简要说明其相关性 + ``` + +5. 向用户展示研究摘要。 + +### 步骤 2：头脑风暴与澄清 + +1. 基于想法和已研究的资源，展示： + - 从研究中识别出的**主要主题** + - 博客文章的**可能切入角度** + - 应该覆盖的**关键点** + - 仍需进一步澄清的**信息缺口** + +2. 提出澄清问题： + - 你希望读者最终带走的核心结论是什么？ + - 研究中有没有哪些点是你希望重点强调的？ + - 目标长度是多少？（短：500-800 字，中：1000-1500 字，长：2000+ 字） + - 有没有哪些内容你希望排除？ + +3. **在继续之前，等待用户回复。** + +### 步骤 3：提出提纲 + +1. 创建一个结构化提纲，包括： + + ```markdown + # 博客文章提纲：[标题] + + ## 元信息 + - **目标读者**：[谁] + - **语气**：[风格] + - **目标长度**：[字数] + - **核心结论**：[关键信息] + + ## 建议结构 + + ### 开场/引子 + - 开场钩子思路 + - 背景铺垫 + - 论点陈述 + + ### 第一部分：[标题] + - 关键点 A + - 关键点 B + - 来自 [来源] 的支撑证据 + + ### 第二部分：[标题] + - 关键点 A + - 关键点 B + + [继续列出所有部分...] + + ### 结论 + - 关键点总结 + - 行动号召或最终思考 + + ## 需要引用的来源 + - 来源 1 + - 来源 2 + ``` + +2. 向用户展示提纲，并**请求批准或修改意见**。 + +### 步骤 4：保存已批准的提纲 + +1. 用户批准提纲后，将其保存为博客文章文件夹中的 `OUTLINE.md`。 + +2. 确认提纲已保存。 + +### 步骤 5：提交提纲（如果在 git 仓库中） + +1. 检查当前目录是否为 git 仓库。 + +2. 如果是： + - 暂存新文件：博客文章文件夹、resources 和 `OUTLINE.md` + - 使用如下提交信息创建 commit：`docs: Add outline for blog post - [topic-name]` + - 推送到远程仓库 + +3. 如果不是 git 仓库，则跳过此步骤并告知用户。 + +### 步骤 6：撰写草稿 + +1. 基于已批准的提纲，撰写完整博客草稿。 + +2. 严格按照 `OUTLINE.md` 的结构进行编写。 + +3. 包含： + - 有吸引力的引言和开场钩子 + - 清晰的章节标题 + - 来自研究的支撑证据和示例 + - 段落之间自然流畅的过渡 + - 强有力的结尾和核心收获 + - **引用**：所有比较、统计数据和事实性陈述都必须引用原始来源 + +4. 将草稿保存为博客文章文件夹中的 `draft-v0.1.md`。 + +5. 格式： + ```markdown + # [博客文章标题] + + *[可选：副标题或标语]* + + [包含行内引用的完整正文...] + + --- + + ## 参考资料 + - [1] 来源 1 标题 - URL 或引用 + - [2] 来源 2 标题 - URL 或引用 + - [3] 来源 3 标题 - URL 或引用 + ``` + +6. **引用要求**： + - 每个数据点、统计信息或比较都必须带有行内引用 + - 使用编号引用 [1]、[2] 等，或命名引用 [Source Name] + - 在文末的参考资料部分链接这些引用 + - 示例：“研究表明，65% 的开发者更偏好 TypeScript [1]” + - 示例：“React 在渲染速度上比 Vue 快 20% [React Benchmarks 2024]” + +### 步骤 7：提交草稿（如果在 git 仓库中） + +1. 检查是否处于 git 仓库中。 + +2. 如果是： + - 暂存草稿文件 + - 使用如下提交信息创建 commit：`docs: Add draft v0.1 for blog post - [topic-name]` + - 推送到远程仓库 + +3. 如果不是 git 仓库，则跳过并告知用户。 + +### 步骤 8：向用户展示草稿以供审阅 + +1. 向用户展示草稿内容。 + +2. 询问反馈： + - 整体印象如何？ + - 哪些部分需要扩展或压缩？ + - 是否需要调整语气？ + - 是否缺少关键信息？ + - 有没有具体编辑或重写建议？ + +3. **等待用户回复。** + +### 步骤 9：迭代或定稿 + +**如果用户要求修改：** +1. 记录所有修改请求 +2. 返回步骤 6，并做以下调整： + - 将版本号递增（v0.2、v0.3 等） + - 纳入所有反馈 + - 保存为 `draft-v[X.Y].md` + - 重复步骤 7-8 + +**如果用户批准：** +1. 确认最终草稿版本 +2. 如用户要求，可重命名为 `final.md` +3. 总结博客文章创建过程： + - 一共创建了多少个版本 + - 各版本之间的关键变化 + - 最终字数 + - 创建了哪些文件 + +## 版本跟踪 + +所有草稿都会以递增版本号保留： +- `draft-v0.1.md` - 初始草稿 +- `draft-v0.2.md` - 第一轮反馈后 +- `draft-v0.3.md` - 第二轮反馈后 +- 以此类推 + +这可以跟踪博客文章的演变过程，并在需要时回退。 + +## 输出文件结构 + +```text +blog-posts/ +└── YYYY-MM-DD-topic-name/ + ├── resources/ + │ ├── source-1-name.md + │ ├── source-2-name.md + │ └── ... + ├── OUTLINE.md + ├── draft-v0.1.md + ├── draft-v0.2.md（如果有迭代） + └── draft-v0.3.md（如果还有更多迭代） +``` + +## 质量建议 + +- **钩子**：以问题、令人惊讶的事实或贴近读者的场景开头 +- **衔接**：每一段都要自然连接到下一段 +- **证据**：用研究数据支撑观点 +- **引用**：以下内容务必引用来源： + - 所有统计数据和数值（例如：“根据 [Source]，75% 的……”） + - 对产品、服务或方案的比较（例如：“X 的速度比 Y 快 2 倍 [Source]”） + - 关于市场趋势、研究发现或基准测试的事实性陈述 + - 使用行内引用，格式为：[Source Name] 或 [Author, Year] +- **语气**：全程保持一致 +- **长度**：尊重目标字数 +- **可读性**：使用短段落，并在适当位置使用项目符号 +- **CTA**：以明确的行动号召或发人深省的问题收尾 + +## 备注 + +- 始终在上述需要确认的节点等待用户批准 +- 保留所有草稿版本，方便追踪历史 +- 如果提供了 URL，使用网络搜索获取最新信息 +- 如果资源不足，询问用户补充，或建议进一步研究 +- 根据目标读者调整语气（技术、通用、商业等） diff --git a/zh/03-skills/blog-draft/templates/draft-template.md b/zh/03-skills/blog-draft/templates/draft-template.md new file mode 100644 index 0000000..c1dbb6d --- /dev/null +++ b/zh/03-skills/blog-draft/templates/draft-template.md @@ -0,0 +1,67 @@ +# [博客文章标题] + +*[副标题或标语 - 可选]* + +**[作者名]** | [日期] + +--- + +[开场钩子 - 立即抓住注意力] + +[背景与上下文 - 说明为什么这件事重要] + +[论点陈述 - 这篇文章要讲什么] + +--- + +## [第一部分标题] + +[本部分正文，保持清晰、吸引人的表达] + +[加入证据、示例或数据来支撑观点] + +> “来自研究的相关引文” - 来源 + +[过渡到下一部分] + +--- + +## [第二部分标题] + +[继续展开正文] + +**关键收获：** [用加粗或提示块突出重要观点] + +[更多支撑内容] + +--- + +## [第三部分标题] + +[如有需要，继续添加更多部分] + +### 小节（如果需要） + +[小节内容] + +--- + +## 结论 + +[总结已覆盖的关键点] + +[重申核心结论] + +[行动号召或发人深省的结尾语] + +--- + +## 参考资料 + +1. [来源标题](#) +2. [来源标题](#) +3. [来源标题](#) + +--- + +*[作者简介或相关文章推荐 - 可选]* diff --git a/zh/03-skills/blog-draft/templates/outline-template.md b/zh/03-skills/blog-draft/templates/outline-template.md new file mode 100644 index 0000000..1c8ec0e --- /dev/null +++ b/zh/03-skills/blog-draft/templates/outline-template.md @@ -0,0 +1,97 @@ +# 博客文章提纲：[标题] + +## 元信息 + +| 属性 | 值 | +|-----------|-------| +| **目标读者** | [写给谁看？] | +| **语气** | [正式/轻松/技术/对话式] | +| **目标长度** | [字数范围] | +| **核心结论** | [一句话说明读者应该记住什么] | +| **关键词** | [如有需要，可填写 SEO 关键词] | + +--- + +## 建议结构 + +### 1. 引言 / 开场钩子 + +**开场钩子选项：** +- [ ] 与读者产生共鸣的问题 +- [ ] 令人惊讶的统计或事实 +- [ ] 一个简短故事或场景 +- [ ] 大胆的陈述 + +**背景铺垫：** +- 需要提供的背景信息 +- 为什么这个主题现在很重要 + +**论点陈述：** +- 明确说明这篇文章要讲什么 + +--- + +### 2. [部分标题] + +**关键点：** +- 要点 A：[说明] +- 要点 B：[说明] + +**支撑证据：** +- 来自 [source]：[相关数据/引文] + +**过渡到下一部分：** +- [这部分如何与下一部分衔接] + +--- + +### 3. [部分标题] + +**关键点：** +- 要点 A：[说明] +- 要点 B：[说明] + +**支撑证据：** +- 来自 [source]：[相关数据/引文] + +**过渡到下一部分：** +- [这部分如何与下一部分衔接] + +--- + +### 4. [部分标题]（如有需要可继续添加） + +**关键点：** +- 要点 A：[说明] +- 要点 B：[说明] + +**支撑证据：** +- 来自 [source]：[相关数据/引文] + +--- + +### 5. 结论 + +**关键点总结：** +- 回顾要点 1 +- 回顾要点 2 +- 回顾要点 3 + +**最终思考 / 行动号召：** +- [读者接下来应该做什么或思考什么？] + +--- + +## 需要引用的来源 + +1. [来源名称](#) - 用于：[对应信息] +2. [来源名称](#) - 用于：[对应信息] +3. [来源名称](#) - 用于：[对应信息] + +--- + +## 撰写备注 + +- [任何特别要求或限制] +- [需要强调的内容] +- [需要避免的内容] diff --git a/zh/03-skills/brand-voice/SKILL.md b/zh/03-skills/brand-voice/SKILL.md new file mode 100644 index 0000000..9450d62 --- /dev/null +++ b/zh/03-skills/brand-voice/SKILL.md @@ -0,0 +1,72 @@ +--- +name: brand-voice-consistency +description: 确保所有沟通内容都符合品牌语气和风格指南。适用于撰写营销文案、客户沟通、对外内容，或用户提到品牌语气、tone、写作风格的场景。 +--- + +# 品牌语气技能 + +## 概览 +此技能确保所有沟通内容在品牌语气、风格和信息传达上保持一致。 + +## 品牌定位 + +### 使命 +帮助团队用 AI 自动化开发工作流 + +### 价值观 +- **简洁**：把复杂的事情变简单 +- **可靠**：执行稳健，结果稳定 +- **赋能**：释放人的创造力 + +### 语气风格 +- **友好但专业** - 平易近人，但不过于随意 +- **清晰简洁** - 避免行话，用通俗方式解释技术概念 +- **自信** - 体现我们知道自己在做什么 +- **有同理心** - 理解用户需求和痛点 + +## 写作指南 + +### 应该做的 ✅ +- 对读者使用“你” +- 使用主动语态：“Claude 会生成报告”，而不是“报告由 Claude 生成” +- 先讲价值主张 +- 使用具体示例 +- 句子保持在 20 个词以内 +- 使用列表增强清晰度 +- 包含行动号召 + +### 不应该做的 ❌ +- 不要使用企业黑话 +- 不要居高临下，也不要过度简化 +- 不要使用“我们相信”或“我们认为” +- 不要全大写，除非为了强调 +- 不要写成大段文字墙 +- 不要默认读者具备技术背景 + +## 词汇 + +### ✅ 推荐用词 +- Claude（不要写“the Claude AI”） +- 代码生成（不要写“auto-coding”） +- Agent（不要写“bot”） +- 简化流程（不要写“革命性改变”） +- 集成（不要写“synergize”） + +### ❌ 避免用词 +- “cutting-edge”（过度使用） +- “game-changer”（过于空泛） +- “leverage”（企业黑话） +- “utilize”（直接用“use”） +- “paradigm shift”（不够清晰） + +## 示例 + +### ✅ 好示例 +“Claude 能自动化你的代码审查流程。它不再需要你手动检查每个 PR，而是会审查安全性、性能和质量，每周为团队节省数小时。” + +为什么好：价值明确、收益具体、行动导向强 + +### ❌ 坏示例 +“Claude 利用前沿 AI 为软件开发提供全面解决方案。” + +为什么不好：太空泛、企业黑话太多、没有具体价值 diff --git a/zh/03-skills/brand-voice/tone-examples.md b/zh/03-skills/brand-voice/tone-examples.md new file mode 100644 index 0000000..6b91328 --- /dev/null +++ b/zh/03-skills/brand-voice/tone-examples.md @@ -0,0 +1,13 @@ +# 品牌语气示例 + +## 激动人心的公告 +“每周为代码审查节省 8 小时。Claude 会自动审查你的 PR。” + +## 体现同理心的支持 +“我们知道发布流程可能很有压力。Claude 会负责测试，你就不用担心了。” + +## 自信的产品功能 +“Claude 不只是给你代码建议。它理解你的架构，并保持一致性。” + +## 教育型博客文章 +“让我们一起看看 agents 如何改进代码审查工作流。以下是我们的发现……” diff --git a/zh/03-skills/claude-md/SKILL.md b/zh/03-skills/claude-md/SKILL.md new file mode 100644 index 0000000..82db31b --- /dev/null +++ b/zh/03-skills/claude-md/SKILL.md @@ -0,0 +1,212 @@ +--- +name: claude-md +description: 按最佳实践创建或更新 CLAUDE.md 文件，以便为 AI agent 提供最优的项目入门上下文 +--- + +## 用户输入 + +```text +$ARGUMENTS +``` + +在继续之前，你**必须**先考虑用户输入（如果不为空）。用户可能会指定： +- `create` - 从零创建新的 CLAUDE.md +- `update` - 改进已有的 CLAUDE.md +- `audit` - 分析并报告当前 CLAUDE.md 的质量 +- 一个具体路径，用于创建或更新（例如 `src/api/CLAUDE.md` 代表目录级说明） + +## 核心原则 + +**LLM 是无状态的**：CLAUDE.md 是每次对话中唯一会自动包含的文件。它是让 AI agent 了解代码库的主要入门文档。 + +### 黄金法则 + +1. **少即是多**：前沿 LLM 大约能遵循 150-200 条指令。Claude Code 的系统提示词本身已经占了大约 50 条，因此 CLAUDE.md 必须聚焦且简洁。 + +2. **只放通用信息**：只包含每次会话都适用的内容。任务特定的说明应该放在单独文件里。 + +3. **不要把 Claude 当成 lint 工具**：风格指南会膨胀上下文并降低指令遵循效果。应改用确定性工具（如 prettier、eslint 等）。 + +4. **绝不自动生成**：CLAUDE.md 是 AI harness 中杠杆最高的位置。应该经过认真思考后手工编写。 + +## 执行流程 + +### 1. 项目分析 + +首先分析当前项目状态： + +1. 检查是否存在已有的 CLAUDE.md 文件： + - 根目录：`./CLAUDE.md` 或 `.claude/CLAUDE.md` + - 目录级：`**/CLAUDE.md` + - 全局用户配置：`~/.claude/CLAUDE.md` + +2. 识别项目结构： + - 技术栈（语言、框架） + - 项目类型（monorepo、单体应用、库） + - 开发工具（包管理器、构建系统、测试运行器） + +3. 查看已有文档： + - README.md + - CONTRIBUTING.md + - package.json、pyproject.toml、Cargo.toml 等 + +### 2. 内容策略（WHAT, WHY, HOW） + +围绕三个维度组织 CLAUDE.md： + +#### WHAT - 技术与结构 +- 技术栈概览 +- 项目组织方式（对 monorepo 尤其重要） +- 关键目录及其用途 + +#### WHY - 目的与背景 +- 项目是做什么的 +- 为什么做出这些架构决策 +- 每个主要组件负责什么 + +#### HOW - 工作流与约定 +- 开发流程（bun vs node、pip vs uv 等） +- 测试流程和命令 +- 验证与构建方法 +- 关键“坑点”或非显而易见的要求 + +### 3. 渐进式披露策略 + +对于较大的项目，建议创建 `agent_docs/` 文件夹： + +```text +agent_docs/ + |- building_the_project.md + |- running_tests.md + |- code_conventions.md + |- architecture_decisions.md +``` + +在 CLAUDE.md 中引用这些文件，并写明： +```markdown +关于详细的构建说明，请参考 `agent_docs/building_the_project.md` +``` + +**重要**：使用 `file:line` 引用，而不是代码片段，以避免上下文过时。 + +### 4. 质量约束 + +创建或更新 CLAUDE.md 时： + +1. **目标长度**：少于 300 行，理想情况下少于 100 行 +2. **不要写风格规则**：移除任何 lint/format 相关说明 +3. **不要写任务特定说明**：移到单独文件中 +4. **不要写代码片段**：改用文件引用 +5. **不要重复信息**：不要重复 package.json 或 README 中已有内容 + +### 5. 必备章节 + +一个结构良好的 CLAUDE.md 应包含： + +```markdown +# 项目名称 + +一句简短的项目描述。 + +## 技术栈 +- 主语言和版本 +- 关键框架/库 +- 数据库/存储（如有） + +## 项目结构 +[仅适用于 monorepo 或复杂结构] +- `apps/` - 应用入口 +- `packages/` - 共享库 + +## 开发命令 +- 安装：`command` +- 测试：`command` +- 构建：`command` + +## 关键约定 +[只保留非显而易见、高影响的约定] +- 约定 1，简要说明 +- 约定 2，简要说明 + +## 已知问题 / 坑点 +[经常让开发者踩坑的内容] +- 问题 1 +- 问题 2 +``` + +### 6. 需要避免的反模式 + +**不要包含：** +- 代码风格指南（交给 lint 工具） +- 如何使用 Claude 的说明 +- 对显而易见模式的冗长解释 +- 复制粘贴的代码示例 +- 泛泛而谈的最佳实践（例如“写干净的代码”） +- 特定任务的说明 +- 自动生成内容 +- 大量 TODO 列表 + +### 7. 验证清单 + +在最终确定前，检查： + +- [ ] 少于 300 行（最好少于 100 行） +- [ ] 每一行都适用于所有会话 +- [ ] 没有风格/格式规则 +- [ ] 没有代码片段（使用文件引用） +- [ ] 命令已经验证可用 +- [ ] 对复杂项目使用了渐进式披露 +- [ ] 已记录关键坑点 +- [ ] 没有与 README.md 重复 + +## 输出格式 + +### 对于 `create` 或默认模式： + +1. 分析项目 +2. 按上述结构起草 CLAUDE.md +3. 向用户展示草稿以供审阅 +4. 在获得批准后写入相应位置 + +### 对于 `update`： + +1. 读取现有 CLAUDE.md +2. 按最佳实践进行审计 +3. 识别： + - 需要删除的内容（风格规则、代码片段、任务特定内容） + - 需要压缩的内容 + - 缺失的重要信息 +4. 向用户展示修改建议 +5. 在获得批准后应用修改 + +### 对于 `audit`： + +1. 读取现有 CLAUDE.md +2. 生成报告，包括： + - 当前行数与目标的对比 + - 可通用于所有会话内容的百分比 + - 发现的反模式列表 + - 改进建议 +3. 不要修改文件，只做报告 + +## AGENTS.md 处理 + +如果用户请求创建或更新 AGENTS.md： + +AGENTS.md 用于定义专门的 agent 行为。与 CLAUDE.md（项目上下文）不同，AGENTS.md 定义的是： +- 自定义 agent 角色和能力 +- agent 级约束与说明 +- 多 agent 场景下的工作流定义 + +同样适用以下原则： +- 保持聚焦和简洁 +- 使用渐进式披露 +- 用外部文档引用代替内联内容 + +## 备注 + +- 在写入前始终验证命令是否可用 +- 不确定时就不要写，少即是多 +- 系统提醒会告诉 Claude，CLAUDE.md “可能相关，也可能不相关” - 噪音越多，越容易被忽略 +- monorepo 最需要清晰的 WHAT/WHY/HOW 结构 +- 目录级 CLAUDE.md 应该更聚焦 diff --git a/zh/03-skills/code-review/SKILL.md b/zh/03-skills/code-review/SKILL.md new file mode 100644 index 0000000..335aa6c --- /dev/null +++ b/zh/03-skills/code-review/SKILL.md @@ -0,0 +1,70 @@ +--- +name: code-review-specialist +description: 提供全面的代码审查能力，覆盖安全、性能和代码质量分析。适用于用户请求代码审查、代码质量评估、Pull Request 审查，或提到安全分析和性能优化时。 +--- + +# 代码审查 Skill + +这个 skill 提供全面的代码审查能力，重点关注： + +1. **安全分析** + - 身份验证 / 授权问题 + - 数据泄露风险 + - 注入漏洞 + - 密码学弱点 + - 敏感数据日志记录 + +2. **性能审查** + - 算法效率（Big O 分析） + - 内存优化 + - 数据库查询优化 + - 缓存机会 + - 并发问题 + +3. **代码质量** + - SOLID 原则 + - 设计模式 + - 命名规范 + - 文档 + - 测试覆盖率 + +4. **可维护性** + - 代码可读性 + - 函数长度（建议少于 50 行） + - 圈复杂度 + - 依赖管理 + - 类型安全 + +## 审查模板 + +对每一段被审查的代码，请提供： + +### 摘要 +- 整体质量评分（1-5） +- 关键发现数量 +- 建议优先关注的区域 + +### 关键问题（如有） +- **问题**：清晰描述 +- **位置**：文件和行号 +- **影响**：为什么这很重要 +- **严重性**：Critical / High / Medium +- **修复**：代码示例 + +### 按类别列出发现 + +#### 安全性（如有问题） +列出安全漏洞及示例 + +#### 性能（如有问题） +列出性能问题，并说明复杂度 + +#### 质量（如有问题） +列出代码质量问题，并给出重构建议 + +#### 可维护性（如有问题） +列出可维护性问题，并给出改进建议 + +## 版本历史 + +- v1.0.0 (2024-12-10)：首次发布，包含安全、性能、质量和可维护性分析 diff --git a/zh/03-skills/code-review/templates/finding-template.md b/zh/03-skills/code-review/templates/finding-template.md new file mode 100644 index 0000000..b96a8fd --- /dev/null +++ b/zh/03-skills/code-review/templates/finding-template.md @@ -0,0 +1,112 @@ +# 代码审查问题记录模板 + +使用这个模板来记录代码审查中发现的每一个问题。 + +--- + +## 问题：[标题] + +### 严重性 +- [ ] Critical（阻塞发布） +- [ ] High（合并前应修复） +- [ ] Medium（尽快修复） +- [ ] Low（可选优化） + +### 类别 +- [ ] Security +- [ ] Performance +- [ ] Code Quality +- [ ] Maintainability +- [ ] Testing +- [ ] Design Pattern +- [ ] Documentation + +### 位置 +**文件：** `src/components/UserCard.tsx` + +**行号：** 45-52 + +**函数 / 方法：** `renderUserDetails()` + +### 问题描述 + +**是什么：** 描述这个问题是什么。 + +**为什么重要：** 说明影响，以及为什么需要修复。 + +**当前行为：** 展示有问题的代码或行为。 + +**期望行为：** 描述理想情况下应该发生什么。 + +### 代码示例 + +#### 当前（有问题） + +```typescript +// 这里展示了 N+1 查询问题 +const users = fetchUsers(); +users.forEach(user => { + const posts = fetchUserPosts(user.id); // 每个用户都发一次查询！ + renderUserPosts(posts); +}); +``` + +#### 建议修复 + +```typescript +// 使用 JOIN 查询进行优化 +const usersWithPosts = fetchUsersWithPosts(); +usersWithPosts.forEach(({ user, posts }) => { + renderUserPosts(posts); +}); +``` + +### 影响分析 + +| 方面 | 影响 | 严重性 | +|--------|--------|--------| +| 性能 | 20 个用户就会产生 100+ 次查询 | High | +| 用户体验 | 页面加载缓慢 | High | +| 可扩展性 | 规模变大后会失效 | Critical | +| 可维护性 | 难以排查问题 | Medium | + +### 相关问题 + +- `AdminUserList.tsx` 第 120 行有类似问题 +- 相关 PR：#456 +- 相关 issue：#789 + +### 额外资源 + +- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem) +- [Database Join Documentation](https://docs.example.com/joins) + +### 审查者备注 + +- 这是这个代码库里常见的模式 +- 可以考虑把它加入代码风格指南 +- 也许值得提取一个辅助函数 + +### 作者回复（供反馈） + +*由代码作者填写：* + +- [ ] 已在提交 `abc123` 中修复 +- [ ] 修复状态：Complete / In Progress / Needs Discussion +- [ ] 问题或疑虑：（描述） + +--- + +## 统计信息（供审查者使用） + +在审查多个问题时，请记录： + +- **发现问题总数：** X +- **Critical：** X +- **High：** X +- **Medium：** X +- **Low：** X + +**建议：** ✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion + +**整体代码质量：** 1-5 星 diff --git a/zh/03-skills/code-review/templates/review-checklist.md b/zh/03-skills/code-review/templates/review-checklist.md new file mode 100644 index 0000000..22b58f5 --- /dev/null +++ b/zh/03-skills/code-review/templates/review-checklist.md @@ -0,0 +1,47 @@ +# 代码审查检查清单 + +## 安全检查 +- [ ] 没有硬编码的凭据或密钥 +- [ ] 所有用户输入都做了校验 +- [ ] 使用参数化查询，防止 SQL 注入 +- [ ] 所有会修改状态的操作都有 CSRF 防护 +- [ ] 使用正确的转义，防止 XSS +- [ ] 受保护的端点有身份验证检查 +- [ ] 资源访问有授权检查 +- [ ] 密码使用安全哈希算法（bcrypt、argon2） +- [ ] 日志中没有敏感数据 +- [ ] 强制使用 HTTPS + +## 性能检查 +- [ ] 没有 N+1 查询 +- [ ] 索引使用合理 +- [ ] 在有价值的地方做了缓存 +- [ ] 主线程上没有阻塞操作 +- [ ] 正确使用 async/await +- [ ] 大数据集已经分页 +- [ ] 数据库连接已做连接池 +- [ ] 正则表达式已优化 +- [ ] 没有不必要的对象创建 +- [ ] 没有内存泄漏 + +## 质量检查 +- [ ] 函数少于 50 行 +- [ ] 变量命名清晰 +- [ ] 没有重复代码 +- [ ] 错误处理合理 +- [ ] 注释解释的是 WHY，而不是 WHAT +- [ ] 生产环境中没有 console.log +- [ ] 有类型检查（TypeScript / JSDoc） +- [ ] 遵循 SOLID 原则 +- [ ] 正确应用设计模式 +- [ ] 代码具备自解释性 + +## 测试检查 +- [ ] 已编写单元测试 +- [ ] 覆盖了边界情况 +- [ ] 测试了错误场景 +- [ ] 有集成测试 +- [ ] 覆盖率大于 80% +- [ ] 没有不稳定测试 +- [ ] 外部依赖已做 mock +- [ ] 测试名称清晰 diff --git a/zh/03-skills/doc-generator/SKILL.md b/zh/03-skills/doc-generator/SKILL.md new file mode 100644 index 0000000..1a7b067 --- /dev/null +++ b/zh/03-skills/doc-generator/SKILL.md @@ -0,0 +1,76 @@ +--- +name: api-documentation-generator +description: 从源代码生成全面且准确的 API 文档。适用于创建或更新 API 文档、生成 OpenAPI 规范，或在用户提到 API 文档、端点或说明时使用。 +--- + +# API 文档生成 Skill + +## 可生成内容 + +- OpenAPI / Swagger 规范 +- API 端点文档 +- SDK 使用示例 +- 集成指南 +- 错误码参考 +- 认证指南 + +## 文档结构 + +### 每个端点的写法 + +```markdown +## GET /api/v1/users/:id + +### 描述 +简要说明这个端点做什么 + +### 参数 + +| 名称 | 类型 | 必填 | 说明 | +|------|------|------|------| +| id | string | 是 | 用户 ID | + +### 响应 + +**200 成功** +```json +{ + "id": "usr_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2025-01-15T10:30:00Z" +} +``` + +**404 未找到** +```json +{ + "error": "USER_NOT_FOUND", + "message": "User does not exist" +} +``` + +### 示例 + +**cURL** +```bash +curl -X GET "https://api.example.com/api/v1/users/usr_123" \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +**JavaScript** +```javascript +const user = await fetch('/api/v1/users/usr_123', { + headers: { 'Authorization': 'Bearer token' } +}).then(r => r.json()); +``` + +**Python** +```python +response = requests.get( + 'https://api.example.com/api/v1/users/usr_123', + headers={'Authorization': 'Bearer token'} +) +user = response.json() +``` +``` diff --git a/zh/03-skills/refactor/SKILL.md b/zh/03-skills/refactor/SKILL.md new file mode 100644 index 0000000..8edb205 --- /dev/null +++ b/zh/03-skills/refactor/SKILL.md @@ -0,0 +1,426 @@ +--- +name: code-refactor +description: 基于 Martin Fowler 方法论的系统化代码重构 skill。适用于用户请求重构代码、改进代码结构、减少技术债、清理旧代码、消除 code smell 或提升可维护性时。这个 skill 采用分阶段、带研究与计划的安全增量实施方式。 +--- + +# 代码重构 Skill + +这是一个基于 Martin Fowler《Refactoring: Improving the Design of Existing Code》（第 2 版）的系统化代码重构方法。这个 skill 强调安全、渐进的修改，并由测试提供保障。 + +> “重构是在不改变软件外部行为的前提下，改进其内部结构的过程。” — Martin Fowler + +## 核心原则 + +1. **保持行为不变**：外部行为必须保持一致 +2. **小步前进**：每次只做很小、可测试的改动 +3. **测试驱动**：测试是安全网 +4. **持续进行**：重构是长期过程，不是一次性任务 +5. **协作确认**：每个阶段都需要用户确认 + +## 工作流程总览 + +``` +阶段 1：研究与分析 + ↓ +阶段 2：测试覆盖评估 + ↓ +阶段 3：识别代码异味 + ↓ +阶段 4：创建重构计划 + ↓ +阶段 5：增量实施 + ↓ +阶段 6：评审与迭代 +``` + +--- + +## 阶段 1：研究与分析 + +### 目标 +- 理解代码库结构和用途 +- 确定重构范围 +- 收集业务需求背景 + +### 先向用户确认的问题 +开始前先确认： + +1. **范围**：哪些文件 / 模块 / 函数需要重构？ +2. **目标**：你想解决什么问题？（可读性、性能、可维护性） +3. **约束**：有哪些区域不能改？ +4. **时间压力**：这是否阻塞了其他工作？ +5. **测试状态**：是否已有测试？是否通过？ + +### 行动 +- [ ] 阅读并理解目标代码 +- [ ] 识别依赖和集成点 +- [ ] 记录当前架构 +- [ ] 标记已有技术债迹象（TODO、FIXME） + +### 输出 +向用户汇报： +- 代码结构总结 +- 识别出的问题区域 +- 初步建议 +- **请求继续执行的批准** + +--- + +## 阶段 2：测试覆盖评估 + +### 为什么测试重要 +> “没有测试的重构，就像没有安全带就开车。” — Martin Fowler + +测试是安全重构的**关键前提**。没有测试，很容易引入 bug。 + +### 评估步骤 + +1. **检查现有测试** + ```bash + # 查找测试文件 + find . -name "*test*" -o -name "*spec*" | head -20 + ``` + +2. **运行现有测试** + ```bash + # JavaScript / TypeScript + npm test + + # Python + pytest -v + + # Java + mvn test + ``` + +3. **检查覆盖率（如果可用）** + ```bash + # JavaScript + npm run test:coverage + + # Python + pytest --cov=. + ``` + +### 决策点：询问用户 + +**如果测试存在且通过：** +- 进入阶段 3 + +**如果测试缺失或不完整：** +给出选项： +1. 先写测试（推荐） +2. 在重构过程中逐步补测试 +3. 不写测试直接继续（有风险，需要用户确认） + +**如果测试失败：** +- 停止。先修复失败测试再重构 +- 问用户：是否先修测试？ + +### 测试编写建议（如需要） + +对每个要重构的函数，测试应覆盖： +- 正常路径 +- 边界情况（空输入、null、边界值） +- 错误场景（非法输入、异常） + +使用“红-绿-重构”循环： +1. 写失败测试（红） +2. 让它通过（绿） +3. 再重构 + +--- + +## 阶段 3：识别代码异味 + +### 什么是代码异味？ +代码深层问题的表面症状。它们不一定是 bug，但说明代码设计可能有问题。 + +### 常见异味清单 + +完整目录见 [references/code-smells.md](references/code-smells.md)。 + +#### 快速参考 + +| 异味 | 迹象 | 影响 | +|-------|------|------| +| **长函数** | 函数超过 30-50 行 | 难以理解、测试和维护 | +| **重复代码** | 多处出现相同逻辑 | 修复需要改多处 | +| **大类** | 类承担了太多职责 | 违反单一职责原则 | +| **Feature Envy** | 一个方法更多依赖别的类的数据 | 封装性差 | +| **基础类型沉迷** | 过度使用基础类型而不是对象 | 缺少领域概念 | +| **长参数列表** | 方法参数超过 4 个 | 调用困难 | +| **数据泥团** | 一组数据总是一起出现 | 缺少抽象 | +| **switch 语句** | 复杂的 switch / if-else 链 | 难以扩展 | +| **臆想泛化** | “以防未来需要”提前设计 | 不必要的复杂度 | +| **死代码** | 未使用的代码 | 造成困惑和维护负担 | + +### 分析步骤 + +1. **自动分析**（如果有脚本） + ```bash + python scripts/detect-smells.py + ``` + +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 +``` + +展示改进： +- 代码行数变化 +- 圈复杂度变化 +- 可维护性指标变化 + +### 用户评审 + +向用户展示最终结果： +- 所有变更摘要 +- 重构前后代码对比 +- 指标改善情况 +- 剩余技术债 +- **询问**：“你对这些改动满意吗？” + +### 下一步 + +和用户讨论： +- 还要处理哪些异味？ +- 是否安排下一次重构？ +- 是否把类似修改应用到其他地方？ + +--- + +## 重要指南 + +### 何时暂停并询问 + +遇到以下情况时，务必暂停并和用户确认： +- 不确定业务逻辑 +- 改动可能影响外部 API +- 测试覆盖不足 +- 需要做重大的架构决策 +- 风险上升 +- 遇到意外复杂性 + +### 安全规则 + +1. **没有测试不要重构**（除非用户明确确认风险） +2. **不要做大改动**，拆成小步 +3. **每次改动后都不要跳过测试** +4. **测试失败就不要继续**，先修复或回滚 +5. **不要臆测**，不确定就问 + +### 不要做什么 + +- 不要把重构和新功能混在一起 +- 不要在生产事故期间做重构 +- 不要重构你看不懂的代码 +- 不要过度设计，保持简单 +- 不要一次性重构所有内容 + +--- + +## 快速上手示例 + +### 场景：长函数 + 重复逻辑 + +**重构前：** +```javascript +function processOrder(order) { + // 150 行代码，包含： + // - 重复验证逻辑 + // - 内联计算 + // - 多种职责混杂 +} +``` + +**重构步骤：** + +1. **确认测试存在**，覆盖 `processOrder()` +2. **提取** 验证逻辑为 `validateOrder()` +3. **测试** - 应该通过 +4. **提取** 计算逻辑为 `calculateOrderTotal()` +5. **测试** - 应该通过 +6. **提取** 通知逻辑为 `notifyCustomer()` +7. **测试** - 应该通过 +8. **评审** - `processOrder()` 现在只负责串联 3 个清晰函数 + +**重构后：** +```javascript +function processOrder(order) { + validateOrder(order); + const total = calculateOrderTotal(order); + notifyCustomer(order, total); + return { order, total }; +} +``` + +--- + +## 参考资料 + +- [代码异味目录](references/code-smells.md) - 代码异味完整清单 +- [重构目录](references/refactoring-catalog.md) - 重构手法 +- [重构计划模板](templates/refactoring-plan.md) - 计划模板 + +## 脚本 + +- `scripts/analyze-complexity.py` - 分析代码复杂度指标 +- `scripts/detect-smells.py` - 自动检测 code smell + +## 版本历史 + +- v1.0.0 (2025-01-15)：首次发布，包含 Fowler 方法论、分阶段流程和用户确认点 diff --git a/zh/03-skills/refactor/references/code-smells.md b/zh/03-skills/refactor/references/code-smells.md new file mode 100644 index 0000000..8fb8f56 --- /dev/null +++ b/zh/03-skills/refactor/references/code-smells.md @@ -0,0 +1,669 @@ +# 代码异味目录 + +这是基于 Martin Fowler《Refactoring》（第 2 版）的代码异味参考目录。代码异味是更深层问题的表面症状，它们说明代码设计可能出了问题。 + +> “代码异味通常是系统中更深层问题的表面信号。” — Martin Fowler + +--- + +## 过度膨胀类异味 + +表示对象或函数已经大到不再好用。 + +### 长函数 + +**迹象：** +- 函数超过 30-50 行 +- 需要滚动才能看完整个函数 +- 嵌套层级很多 +- 需要注释来解释局部逻辑 + +**为什么不好：** +- 难理解 +- 难单独测试 +- 改动容易波及其他逻辑 +- 重复逻辑容易藏在里面 + +**可用重构：** +- Extract Method +- Replace Temp with Query +- Introduce Parameter Object +- Replace Method with Method Object +- Decompose Conditional + +**示例（重构前）：** +```javascript +function processOrder(order) { + // Validate order (20 lines) + if (!order.items) throw new Error('No items'); + if (order.items.length === 0) throw new Error('Empty order'); + // ... more validation + + // Calculate totals (30 lines) + let subtotal = 0; + for (const item of order.items) { + subtotal += item.price * item.quantity; + } + // ... tax, shipping, discounts + + // Send notifications (20 lines) + // ... email logic +} +``` + +**示例（重构后）：** +```javascript +function processOrder(order) { + validateOrder(order); + const totals = calculateOrderTotals(order); + sendOrderNotifications(order, totals); + return { order, totals }; +} +``` + +--- + +### 大类 + +**迹象：** +- 实例变量很多（>7-10） +- 方法很多（>15-20） +- 类名含糊（Manager、Handler、Processor） +- 方法没有用到全部字段 + +**为什么不好：** +- 违反单一职责原则 +- 难测试 +- 改动会波及无关功能 +- 难以复用局部能力 + +**可用重构：** +- Extract Class +- Extract Subclass +- Extract Interface + +**检测参考：** +```text +代码行数 > 300 +方法数量 > 15 +字段数量 > 10 +``` + +--- + +### 基础类型沉迷 + +**迹象：** +- 用基础类型表达领域概念（用 string 表示邮箱、用 int 表示金额） +- 使用基础类型数组，而不是对象 +- 用字符串常量表示类型码 +- 大量 magic number / magic string + +**为什么不好：** +- 类型层面没有验证 +- 逻辑散落在整个代码库里 +- 容易传错值 +- 缺少领域对象 + +**可用重构：** +- Replace Primitive with Object +- Replace Type Code with Class +- Replace Type Code with Subclasses +- Replace Type Code with State/Strategy + +**示例（重构前）：** +```javascript +const user = { + email: 'john@example.com', // 只是字符串 + phone: '1234567890', // 只是字符串 + status: 'active', // 魔法字符串 + balance: 10050 // 以分为单位的整数 +}; +``` + +**示例（重构后）：** +```javascript +const user = { + email: new Email('john@example.com'), + phone: new PhoneNumber('1234567890'), + status: UserStatus.ACTIVE, + balance: Money.cents(10050) +}; +``` + +--- + +### 长参数列表 + +**迹象：** +- 方法参数超过 4 个 +- 一些参数总是一起出现 +- 布尔参数改变方法行为 +- 经常传 null / undefined + +**为什么不好：** +- 难正确调用 +- 参数顺序容易搞混 +- 暗示方法做了太多事 +- 难以增加新参数 + +**可用重构：** +- Introduce Parameter Object +- Preserve Whole Object +- Replace Parameter with Method Call +- Remove Flag Argument + +**示例（重构前）：** +```javascript +function createUser(firstName, lastName, email, phone, + street, city, state, zip, + isAdmin, isActive, createdBy) { + // ... +} +``` + +**示例（重构后）：** +```javascript +function createUser(personalInfo, address, options) { + // personalInfo: { firstName, lastName, email, phone } + // address: { street, city, state, zip } + // options: { isAdmin, isActive, createdBy } +} +``` + +--- + +### 数据泥团 + +**迹象：** +- 同样的 3 个以上字段反复一起出现 +- 参数总是成对或成组传递 +- 类中的字段子集总是一起使用 + +**为什么不好：** +- 逻辑重复 +- 缺少抽象 +- 难扩展 +- 暗示隐藏的类应该存在 + +**可用重构：** +- Extract Class +- Introduce Parameter Object +- Preserve Whole Object + +**示例：** +```javascript +// 数据泥团：坐标 (x, y, z) +function movePoint(x, y, z, dx, dy, dz) { } +function scalePoint(x, y, z, factor) { } +function distanceBetween(x1, y1, z1, x2, y2, z2) { } + +// 提取 Point3D 类 +class Point3D { + constructor(x, y, z) { } + move(delta) { } + scale(factor) { } + distanceTo(other) { } +} +``` + +--- + +## 面向对象滥用类异味 + +表示 OOP 原则没有被正确使用。 + +### switch 语句 + +**迹象：** +- 长 switch/case 或 if/else 链 +- 多处出现相同 switch +- 按类型码分支 +- 新增 case 时需要改很多地方 + +**为什么不好：** +- 违反开放 / 封闭原则 +- 改动会扩散到所有 switch 位置 +- 难扩展 +- 往往说明缺少多态 + +**可用重构：** +- Replace Conditional with Polymorphism +- Replace Type Code with Subclasses +- Replace Type Code with State/Strategy + +**示例（重构前）：** +```javascript +function calculatePay(employee) { + switch (employee.type) { + case 'hourly': + return employee.hours * employee.rate; + case 'salaried': + return employee.salary / 12; + case 'commissioned': + return employee.sales * employee.commission; + } +} +``` + +**示例（重构后）：** +```javascript +class HourlyEmployee { + calculatePay() { + return this.hours * this.rate; + } +} + +class SalariedEmployee { + calculatePay() { + return this.salary / 12; + } +} +``` + +--- + +### 临时字段 + +**迹象：** +- 实例变量只在部分方法中使用 +- 字段只在某些条件下设置 +- 某些情况初始化过程很复杂 + +**为什么不好：** +- 容易混淆：字段存在但可能为 null +- 对象状态难理解 +- 说明条件逻辑被隐藏了 + +**可用重构：** +- Extract Class +- Introduce Null Object +- Replace Temp Field with Local + +--- + +### 拒绝遗赠 + +**迹象：** +- 子类没有用到继承来的方法 / 数据 +- 子类重写方法只是为了不做事 +- 继承被当成代码复用，而不是真正的 IS-A + +**为什么不好：** +- 抽象不对 +- 违反里氏替换原则 +- 继承层次误导人 + +**可用重构：** +- Push Down Method / Field +- Replace Subclass with Delegate +- Replace Inheritance with Delegation + +--- + +### 不同接口的相似类 + +**迹象：** +- 两个类做的事情差不多 +- 同一个概念却用了不同方法名 +- 理论上可以互换使用 + +**为什么不好：** +- 重复实现 +- 没有公共接口 +- 难切换 + +**可用重构：** +- Rename Method +- Move Method +- Extract Superclass +- Extract Interface + +--- + +## 变更阻碍类异味 + +这类异味会让改动变得困难，一次改动需要波及很多地方。 + +### 发散式变化 + +**迹象：** +- 一个类因为很多不同原因而被修改 +- 不同区域的变更都会触发同一个类的编辑 +- 类变成了“上帝类” + +**为什么不好：** +- 违反单一职责原则 +- 变更频率高 +- 容易产生合并冲突 + +**可用重构：** +- Extract Class +- Extract Superclass +- Extract Subclass + +**示例：** +一个 `User` 类同时因为这些原因变化： +- 身份验证变化 +- 个人资料变化 +- 计费变化 +- 通知变化 + +→ 可以拆成：`AuthService`、`ProfileService`、`BillingService`、`NotificationService` + +--- + +### 散弹式修改 + +**迹象：** +- 一个改动需要编辑很多类 +- 一个小功能要触碰 10+ 个文件 +- 改动分散，难以一次找全 + +**为什么不好：** +- 很容易漏改 +- 耦合高 +- 容易出错 + +**可用重构：** +- Move Method +- Move Field +- Inline Class + +**检测参考：** +如果新增一个字段需要改 5 个以上文件，就要警惕。 + +--- + +### 平行继承体系 + +**迹象：** +- 在一个继承体系中创建子类，另一个体系也得跟着创建 +- 类前缀相似（如 `DatabaseOrder`、`DatabaseProduct`） + +**为什么不好：** +- 维护成本翻倍 +- 两个层次之间耦合 +- 容易漏掉一边 + +**可用重构：** +- Move Method +- Move Field +- 消除其中一个层次 + +--- + +## 可舍弃类异味 + +表示有些东西已经不必要了，应该移除。 + +### 注释过多 + +**迹象：** +- 注释在解释代码“做了什么” +- 注释掉的代码 +- 长期存在的 TODO / FIXME +- 注释里带道歉语气 + +**为什么不好：** +- 注释会过时 +- 代码本身应该能自解释 +- 死代码会造成混乱 + +**可用重构：** +- Extract Method（让方法名解释意图） +- Rename（通过命名提升清晰度） +- 删除注释掉的代码 +- Introduce Assertion + +**好与坏的注释：** +```javascript +// BAD: 解释做了什么 +// 遍历用户并检查是否活跃 +for (const user of users) { + if (user.status === 'active') { } +} + +// GOOD: 解释为什么 +// 只保留活跃用户，未活跃用户由清理任务处理 +const activeUsers = users.filter(u => u.isActive); +``` + +--- + +### 重复代码 + +**迹象：** +- 多处出现相同代码 +- 只有少量差异的相似代码 +- 复制粘贴模式 + +**为什么不好：** +- 修复要改多处 +- 容易不一致 +- 代码库臃肿 + +**可用重构：** +- Extract Method +- Extract Class +- Pull Up Method（在继承层次中） +- Form Template Method + +**检测规则：** +任何重复 3 次以上的代码都应该考虑提取。 + +--- + +### 惰性类 + +**迹象：** +- 类做的事情不足以支撑它的存在 +- 只是一个没有增值的包装器 +- 过度设计的产物 + +**为什么不好：** +- 增加维护开销 +- 多了一层没必要的间接 +- 有复杂度但没收益 + +**可用重构：** +- Inline Class +- Collapse Hierarchy + +--- + +### 死代码 + +**迹象：** +- 无法到达的代码 +- 未使用的变量 / 方法 / 类 +- 注释掉的代码 +- 位于不可能条件分支后的代码 + +**为什么不好：** +- 造成困惑 +- 增加维护负担 +- 降低理解速度 + +**可用重构：** +- Remove Dead Code +- Safe Delete + +**检测：** +```bash +# 查找未使用的导出 +# 查找未引用的函数 +# IDE 的“unused”警告 +``` + +--- + +### 臆想泛化 + +**迹象：** +- 只有一个子类的抽象类 +- 为“未来可能需要”而加的未使用参数 +- 只是转发的函数 +- 为一个用例设计的“框架” + +**为什么不好：** +- 复杂度没有收益 +- 违背 YAGNI +- 更难理解 + +**可用重构：** +- Collapse Hierarchy +- Inline Class +- Remove Parameter +- Rename Method + +--- + +## 耦合类异味 + +表示类之间耦合过强。 + +### Feature Envy + +**迹象：** +- 一个方法使用别的类的数据比自己更多 +- 对另一个对象调用很多 getter +- 数据和行为分离 + +**为什么不好：** +- 行为放错地方了 +- 封装性差 +- 难维护 + +**可用重构：** +- Move Method +- Move Field +- Extract Method（然后移动） + +**示例（重构前）：** +```javascript +class Order { + getDiscountedPrice(customer) { + // 这里大量使用 customer 数据 + if (customer.loyaltyYears > 5) { + return this.price * customer.discountRate; + } + return this.price; + } +} +``` + +**示例（重构后）：** +```javascript +class Customer { + getDiscountedPriceFor(price) { + if (this.loyaltyYears > 5) { + return price * this.discountRate; + } + return price; + } +} +``` + +--- + +### 不恰当的亲密 + +**迹象：** +- 类之间互相访问私有细节 +- 双向引用很多 +- 子类知道父类太多细节 + +**为什么不好：** +- 耦合高 +- 改一边会连带另一边 +- 难单独修改 + +**可用重构：** +- Move Method +- Move Field +- Change Bidirectional to Unidirectional +- Extract Class +- Hide Delegate + +--- + +### 消息链 + +**迹象：** +- 方法调用链很长：`a.getB().getC().getD().getValue()` +- 客户端依赖导航结构 +- “火车残骸”式代码 + +**为什么不好：** +- 很脆弱，任何一层变动都会坏 +- 违反迪米特法则 +- 绑定到对象结构 + +**可用重构：** +- Hide Delegate +- Extract Method +- Move Method + +**示例：** +```javascript +// 差：消息链 +const managerName = employee.getDepartment().getManager().getName(); + +// 更好：隐藏委派 +const managerName = employee.getManagerName(); +``` + +--- + +### 中间人 + +**迹象：** +- 类只是把调用转发给另一个类 +- 一半以上的方法都是委派 +- 没有额外价值 + +**为什么不好：** +- 多了一层没必要的间接 +- 维护成本更高 +- 架构令人困惑 + +**可用重构：** +- Remove Middle Man +- Inline Method + +--- + +## 严重性指南 + +| 严重性 | 说明 | 处理方式 | +|--------|------|---------| +| **Critical** | 阻塞开发，导致 bug | 立刻修复 | +| **High** | 明显增加维护负担 | 本迭代修复 | +| **Medium** | 有问题但还能接受 | 近期计划修复 | +| **Low** | 小问题 | 视情况顺手修 | + +--- + +## 快速检测清单 + +扫描代码时使用这个清单： + +- [ ] 有没有超过 30 行的函数？ +- [ ] 有没有超过 300 行的类？ +- [ ] 有没有参数超过 4 个的函数？ +- [ ] 有没有重复代码块？ +- [ ] 有没有按类型码分支的 switch/case？ +- [ ] 有没有未使用的代码？ +- [ ] 有没有大量使用其他类数据的方法？ +- [ ] 有没有很长的方法调用链？ +- [ ] 有没有解释“是什么”而不是“为什么”的注释？ +- [ ] 有没有应该封装成对象的基础类型？ + +--- + +## 延伸阅读 + +- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (2nd ed.) +- Kerievsky, J. (2004). *Refactoring to Patterns* +- Feathers, M. (2004). *Working Effectively with Legacy Code* diff --git a/zh/03-skills/refactor/references/refactoring-catalog.md b/zh/03-skills/refactor/references/refactoring-catalog.md new file mode 100644 index 0000000..5fd8b95 --- /dev/null +++ b/zh/03-skills/refactor/references/refactoring-catalog.md @@ -0,0 +1,1023 @@ +# 重构目录 + +这是 Martin Fowler《Refactoring》（第 2 版）中的一份精选重构目录。每个重构都包含动机、操作步骤和示例。 + +> “重构由它的操作步骤来定义，也就是你执行这个变化时遵循的精确过程。” — Martin Fowler + +--- + +## 如何使用这个目录 + +1. **识别异味**：先用代码异味目录定位问题 +2. **找到对应重构**：在这里查找匹配的手法 +3. **按步骤执行**：一步一步来 +4. **每步都测试**：确保行为不变 + +**黄金法则**：如果某一步超过 10 分钟，就把它拆得更小。 + +--- + +## 最常见的重构 + +### Extract Method + +**何时使用**：长函数、重复代码、需要为概念命名 + +**动机**：把一段代码抽成一个名字能说明意图的方法。 + +**步骤**： +1. 创建一个新方法，名字应描述“做什么”而不是“怎么做” +2. 把代码片段复制到新方法里 +3. 检查片段里用了哪些局部变量 +4. 把局部变量作为参数传入，或在方法内声明 +5. 正确处理返回值 +6. 用新方法调用替换原始片段 +7. 测试 + +**前：** +```javascript +function printOwing(invoice) { + let outstanding = 0; + + console.log("***********************"); + console.log("**** Customer Owes ****"); + console.log("***********************"); + + // Calculate outstanding + for (const order of invoice.orders) { + outstanding += order.amount; + } + + // Print details + console.log(`name: ${invoice.customer}`); + console.log(`amount: ${outstanding}`); +} +``` + +**后：** +```javascript +function printOwing(invoice) { + printBanner(); + const outstanding = calculateOutstanding(invoice); + printDetails(invoice, outstanding); +} + +function printBanner() { + console.log("***********************"); + console.log("**** Customer Owes ****"); + console.log("***********************"); +} + +function calculateOutstanding(invoice) { + return invoice.orders.reduce((sum, order) => sum + order.amount, 0); +} + +function printDetails(invoice, outstanding) { + console.log(`name: ${invoice.customer}`); + console.log(`amount: ${outstanding}`); +} +``` + +--- + +### Inline Method + +**何时使用**：方法体和名字一样清楚，或者只是多余转发 + +**动机**：当方法没有额外价值时，去掉不必要的间接层。 + +**步骤**： +1. 确认这个方法不是多态方法 +2. 找到所有调用点 +3. 用方法体替换每个调用 +4. 每替换一次就测试一次 +5. 删除方法定义 + +**前：** +```javascript +function getRating(driver) { + return moreThanFiveLateDeliveries(driver) ? 2 : 1; +} + +function moreThanFiveLateDeliveries(driver) { + return driver.numberOfLateDeliveries > 5; +} +``` + +**后：** +```javascript +function getRating(driver) { + return driver.numberOfLateDeliveries > 5 ? 2 : 1; +} +``` + +--- + +### Extract Variable + +**何时使用**：复杂表达式难以理解 + +**动机**：给复杂表达式的一部分起名字。 + +**步骤**： +1. 确保表达式没有副作用 +2. 声明一个不可变变量 +3. 将表达式结果赋给变量 +4. 用变量替换原表达式 +5. 测试 + +**前：** +```javascript +return order.quantity * order.itemPrice - + Math.max(0, order.quantity - 500) * order.itemPrice * 0.05 + + Math.min(order.quantity * order.itemPrice * 0.1, 100); +``` + +**后：** +```javascript +const basePrice = order.quantity * order.itemPrice; +const quantityDiscount = Math.max(0, order.quantity - 500) * order.itemPrice * 0.05; +const shipping = Math.min(basePrice * 0.1, 100); +return basePrice - quantityDiscount + shipping; +``` + +--- + +### Inline Variable + +**何时使用**：变量名没有比表达式更清楚 + +**动机**：移除没必要的间接层。 + +**步骤**： +1. 检查右侧表达式没有副作用 +2. 如果变量不是不可变的，先改成不可变并测试 +3. 找到第一次引用并替换成表达式 +4. 测试 +5. 对所有引用重复 +6. 删除变量声明和赋值 +7. 测试 + +--- + +### Rename Variable + +**何时使用**：名字没有清楚表达用途 + +**动机**：好名字是清晰代码的基础。 + +**步骤**： +1. 如果变量使用范围很广，先考虑封装 +2. 找到所有引用 +3. 逐个修改引用 +4. 测试 + +**提示**： +- 使用能体现意图的名字 +- 避免缩写 +- 使用领域术语 + +```javascript +// Bad +const d = 30; +const x = users.filter(u => u.a); + +// Good +const daysSinceLastLogin = 30; +const activeUsers = users.filter(user => user.isActive); +``` + +--- + +### Change Function Declaration + +**何时使用**：函数名不能清楚说明用途，参数也需要变化 + +**动机**：好函数名能让代码自解释。 + +**步骤（简单情况）**： +1. 删除不需要的参数 +2. 修改函数名 +3. 添加需要的参数 +4. 测试 + +**步骤（迁移式，适用于复杂改动）**： +1. 如果要删除参数，确保它没有被使用 +2. 创建一个新函数，声明符合新设计 +3. 让旧函数调用新函数 +4. 测试 +5. 让调用方逐步改用新函数 +6. 每改一个调用点就测试 +7. 删除旧函数 + +**前：** +```javascript +function circum(radius) { + return 2 * Math.PI * radius; +} +``` + +**后：** +```javascript +function circumference(radius) { + return 2 * Math.PI * radius; +} +``` + +--- + +### Encapsulate Variable + +**何时使用**：多个地方直接访问某个数据 + +**动机**：为数据访问提供明确入口。 + +**步骤**： +1. 创建 getter 和 setter +2. 找到所有引用 +3. 用 getter 替换读取 +4. 用 setter 替换写入 +5. 每次改动后测试 +6. 降低变量可见性 + +**前：** +```javascript +let defaultOwner = { firstName: "Martin", lastName: "Fowler" }; + +// Used in many places +spaceship.owner = defaultOwner; +``` + +**后：** +```javascript +let defaultOwnerData = { firstName: "Martin", lastName: "Fowler" }; + +function defaultOwner() { return defaultOwnerData; } +function setDefaultOwner(arg) { defaultOwnerData = arg; } + +spaceship.owner = defaultOwner(); +``` + +--- + +### Introduce Parameter Object + +**何时使用**：一组参数经常一起出现 + +**动机**：把自然属于一起的数据打包起来。 + +**步骤**： +1. 为这组参数创建一个新类 / 结构 +2. 测试 +3. 用 Change Function Declaration 引入新对象 +4. 测试 +5. 逐个移除参数，改用对象字段 +6. 每次移除后测试 + +**前：** +```javascript +function amountInvoiced(startDate, endDate) { ... } +function amountReceived(startDate, endDate) { ... } +function amountOverdue(startDate, endDate) { ... } +``` + +**后：** +```javascript +class DateRange { + constructor(start, end) { + this.start = start; + this.end = end; + } +} + +function amountInvoiced(dateRange) { ... } +function amountReceived(dateRange) { ... } +function amountOverdue(dateRange) { ... } +``` + +--- + +### Combine Functions into Class + +**何时使用**：多个函数操作同一份数据 + +**动机**：把函数和它操作的数据放到一起。 + +**步骤**： +1. 对公共数据先做 Encapsulate Record +2. 把每个函数移动到类里 +3. 每移动一次就测试 +4. 用类字段替代数据参数 + +**前：** +```javascript +function base(reading) { ... } +function taxableCharge(reading) { ... } +function calculateBaseCharge(reading) { ... } +``` + +**后：** +```javascript +class Reading { + constructor(data) { this._data = data; } + + get base() { ... } + get taxableCharge() { ... } + get calculateBaseCharge() { ... } +} +``` + +--- + +### Split Phase + +**何时使用**：代码在处理两件不同的事 + +**动机**：把代码拆成边界清晰的两个阶段。 + +**步骤**： +1. 为第二阶段创建新函数 +2. 测试 +3. 在两个阶段之间引入中间数据结构 +4. 测试 +5. 把第一阶段提取成独立函数 +6. 测试 + +**前：** +```javascript +function priceOrder(product, quantity, shippingMethod) { + const basePrice = product.basePrice * quantity; + const discount = Math.max(quantity - product.discountThreshold, 0) + * product.basePrice * product.discountRate; + const shippingPerCase = (basePrice > shippingMethod.discountThreshold) + ? shippingMethod.discountedFee : shippingMethod.feePerCase; + const shippingCost = quantity * shippingPerCase; + return basePrice - discount + shippingCost; +} +``` + +**后：** +```javascript +function priceOrder(product, quantity, shippingMethod) { + const priceData = calculatePricingData(product, quantity); + return applyShipping(priceData, shippingMethod); +} + +function calculatePricingData(product, quantity) { + const basePrice = product.basePrice * quantity; + const discount = Math.max(quantity - product.discountThreshold, 0) + * product.basePrice * product.discountRate; + return { basePrice, quantity, discount }; +} + +function applyShipping(priceData, shippingMethod) { + const shippingPerCase = (priceData.basePrice > shippingMethod.discountThreshold) + ? shippingMethod.discountedFee : shippingMethod.feePerCase; + const shippingCost = priceData.quantity * shippingPerCase; + return priceData.basePrice - priceData.discount + shippingCost; +} +``` + +--- + +## 移动特性 + +### Move Method + +**何时使用**：方法更依赖另一个类的数据而不是自己类的数据 + +**动机**：把函数放到它最依赖的数据所在的类里。 + +**步骤**： +1. 检查方法使用到的所有程序元素 +2. 确认方法不是多态的 +3. 把方法复制到目标类 +4. 调整上下文 +5. 让原方法委托给目标方法 +6. 测试 +7. 视情况删除原方法 + +--- + +### Move Field + +**何时使用**：字段更多被另一个类使用 + +**动机**：让数据和使用它的函数靠在一起。 + +**步骤**： +1. 如果还没有，先封装字段 +2. 测试 +3. 在目标类中创建字段 +4. 把引用改成使用目标字段 +5. 测试 +6. 删除原字段 + +--- + +### Move Statements into Function + +**何时使用**：相同代码总是跟着函数调用一起出现 + +**动机**：把重复语句移入函数，去掉重复。 + +**步骤**： +1. 如果还没有，先把重复代码提取成函数 +2. 把语句移入函数 +3. 测试 +4. 如果调用方不再需要独立语句，就删除它们 + +--- + +### Move Statements to Callers + +**何时使用**：不同调用方需要不同的行为 + +**动机**：当行为需要差异化时，把它从函数里移出去。 + +**步骤**： +1. 先对要移动的代码做 Extract Method +2. 再对原函数做 Inline Method +3. 删除被内联后的调用 +4. 把提取出的代码移到各个调用方 +5. 测试 + +--- + +## 数据组织 + +### Replace Primitive with Object + +**何时使用**：数据项需要的不只是简单值 + +**动机**：把数据和行为封装在一起。 + +**步骤**： +1. 先做 Encapsulate Variable +2. 创建一个简单值对象 +3. 修改 setter，让它创建新实例 +4. 修改 getter，让它返回值 +5. 测试 +6. 给新类增加更丰富的行为 + +**前：** +```javascript +class Order { + constructor(data) { + this.priority = data.priority; // string: "high", "rush", etc. + } +} + +// Usage +if (order.priority === "high" || order.priority === "rush") { ... } +``` + +**后：** +```javascript +class Priority { + constructor(value) { + if (!Priority.legalValues().includes(value)) + throw new Error(`Invalid priority: ${value}`); + this._value = value; + } + + static legalValues() { return ['low', 'normal', 'high', 'rush']; } + get value() { return this._value; } + + higherThan(other) { + return Priority.legalValues().indexOf(this._value) > + Priority.legalValues().indexOf(other._value); + } +} + +// Usage +if (order.priority.higherThan(new Priority("normal"))) { ... } +``` + +--- + +### Replace Temp with Query + +**何时使用**：临时变量保存的是一个表达式结果 + +**动机**：把表达式提取成函数，让代码更清晰。 + +**步骤**： +1. 确保变量只被赋值一次 +2. 把赋值右侧提取成一个方法 +3. 用方法调用替换临时变量引用 +4. 测试 +5. 删除临时变量声明和赋值 + +**前：** +```javascript +const basePrice = this._quantity * this._itemPrice; +if (basePrice > 1000) { + return basePrice * 0.95; +} else { + return basePrice * 0.98; +} +``` + +**后：** +```javascript +get basePrice() { + return this._quantity * this._itemPrice; +} + +// In the method +if (this.basePrice > 1000) { + return this.basePrice * 0.95; +} else { + return this.basePrice * 0.98; +} +``` + +--- + +## 简化条件逻辑 + +### Decompose Conditional + +**何时使用**：复杂条件语句 + +**动机**：把条件和分支动作分别提取出来，让意图更清楚。 + +**步骤**： +1. 对条件做 Extract Method +2. 对 then 分支做 Extract Method +3. 对 else 分支也做 Extract Method（如果有） + +**前：** +```javascript +if (!aDate.isBefore(plan.summerStart) && !aDate.isAfter(plan.summerEnd)) { + charge = quantity * plan.summerRate; +} else { + charge = quantity * plan.regularRate + plan.regularServiceCharge; +} +``` + +**后：** +```javascript +if (isSummer(aDate, plan)) { + charge = summerCharge(quantity, plan); +} else { + charge = regularCharge(quantity, plan); +} + +function isSummer(date, plan) { + return !date.isBefore(plan.summerStart) && !date.isAfter(plan.summerEnd); +} + +function summerCharge(quantity, plan) { + return quantity * plan.summerRate; +} + +function regularCharge(quantity, plan) { + return quantity * plan.regularRate + plan.regularServiceCharge; +} +``` + +--- + +### Consolidate Conditional Expression + +**何时使用**：多个条件最后都返回同一个结果 + +**动机**：让人一眼看出这些条件其实是一道检查。 + +**步骤**： +1. 确认条件没有副作用 +2. 用 and / or 合并条件 +3. 视情况对合并后的条件做 Extract Method + +**前：** +```javascript +if (employee.seniority < 2) return 0; +if (employee.monthsDisabled > 12) return 0; +if (employee.isPartTime) return 0; +``` + +**后：** +```javascript +if (isNotEligibleForDisability(employee)) return 0; + +function isNotEligibleForDisability(employee) { + return employee.seniority < 2 || + employee.monthsDisabled > 12 || + employee.isPartTime; +} +``` + +--- + +### Replace Nested Conditional with Guard Clauses + +**何时使用**：深层嵌套条件让流程难以追踪 + +**动机**：用 guard clause 提前返回，让正常流程更清楚。 + +**步骤**： +1. 找出特殊情况 +2. 用提前返回的 guard clause 替换它们 +3. 每改一步就测试 + +**前：** +```javascript +function payAmount(employee) { + let result; + if (employee.isSeparated) { + result = { amount: 0, reasonCode: "SEP" }; + } else { + if (employee.isRetired) { + result = { amount: 0, reasonCode: "RET" }; + } else { + result = calculateNormalPay(employee); + } + } + return result; +} +``` + +**后：** +```javascript +function payAmount(employee) { + if (employee.isSeparated) return { amount: 0, reasonCode: "SEP" }; + if (employee.isRetired) return { amount: 0, reasonCode: "RET" }; + return calculateNormalPay(employee); +} +``` + +--- + +### Replace Conditional with Polymorphism + +**何时使用**：按类型分支的 switch / 条件逻辑 + +**动机**：让对象自己处理自己的行为。 + +**步骤**： +1. 创建类层次（如果还没有） +2. 用 Factory Function 创建对象 +3. 把条件逻辑移到超类方法里 +4. 给每种情况创建子类方法 +5. 删除原条件 + +**前：** +```javascript +function plumages(birds) { + return birds.map(b => plumage(b)); +} + +function plumage(bird) { + switch (bird.type) { + case 'EuropeanSwallow': + return "average"; + case 'AfricanSwallow': + return (bird.numberOfCoconuts > 2) ? "tired" : "average"; + case 'NorwegianBlueParrot': + return (bird.voltage > 100) ? "scorched" : "beautiful"; + default: + return "unknown"; + } +} +``` + +**后：** +```javascript +class Bird { + get plumage() { return "unknown"; } +} + +class EuropeanSwallow extends Bird { + get plumage() { return "average"; } +} + +class AfricanSwallow extends Bird { + get plumage() { + return (this.numberOfCoconuts > 2) ? "tired" : "average"; + } +} + +class NorwegianBlueParrot extends Bird { + get plumage() { + return (this.voltage > 100) ? "scorched" : "beautiful"; + } +} + +function createBird(data) { + switch (data.type) { + case 'EuropeanSwallow': return new EuropeanSwallow(data); + case 'AfricanSwallow': return new AfricanSwallow(data); + case 'NorwegianBlueParrot': return new NorwegianBlueParrot(data); + default: return new Bird(data); + } +} +``` + +--- + +### Introduce Special Case (Null Object) + +**何时使用**：重复出现 null 检查 + +**动机**：返回一个特殊对象来处理特殊情况。 + +**步骤**： +1. 创建一个具备预期接口的特殊情况类 +2. 增加 isSpecialCase 检查 +3. 引入工厂方法 +4. 用特殊对象替换 null 检查 +5. 测试 + +**前：** +```javascript +const customer = site.customer; +// ... many places checking +if (customer === "unknown") { + customerName = "occupant"; +} else { + customerName = customer.name; +} +``` + +**后：** +```javascript +class UnknownCustomer { + get name() { return "occupant"; } + get billingPlan() { return registry.defaultPlan; } +} + +// Factory method +function customer(site) { + return site.customer === "unknown" + ? new UnknownCustomer() + : site.customer; +} + +// Usage - no null checks needed +const customerName = customer.name; +``` + +--- + +## 重构 API + +### Separate Query from Modifier + +**何时使用**：函数既返回值又有副作用 + +**动机**：明确哪些操作会产生副作用。 + +**步骤**： +1. 创建新的查询函数 +2. 复制原函数的返回逻辑 +3. 修改原函数，让它只负责副作用 +4. 替换依赖返回值的调用点 +5. 测试 + +**前：** +```javascript +function alertForMiscreant(people) { + for (const p of people) { + if (p === "Don") { + setOffAlarms(); + return "Don"; + } + if (p === "John") { + setOffAlarms(); + return "John"; + } + } + return ""; +} +``` + +**后：** +```javascript +function findMiscreant(people) { + for (const p of people) { + if (p === "Don") return "Don"; + if (p === "John") return "John"; + } + return ""; +} + +function alertForMiscreant(people) { + if (findMiscreant(people) !== "") setOffAlarms(); +} +``` + +--- + +### Parameterize Function + +**何时使用**：有多个做类似事情但数值不同的函数 + +**动机**：通过参数化减少重复。 + +**步骤**： +1. 选择一个函数 +2. 为变化的字面值增加参数 +3. 修改函数体使用该参数 +4. 测试 +5. 让调用方改用参数化版本 +6. 删除不再使用的旧函数 + +**前：** +```javascript +function tenPercentRaise(person) { + person.salary = person.salary * 1.10; +} + +function fivePercentRaise(person) { + person.salary = person.salary * 1.05; +} +``` + +**后：** +```javascript +function raise(person, factor) { + person.salary = person.salary * (1 + factor); +} + +// Usage +raise(person, 0.10); +raise(person, 0.05); +``` + +--- + +### Remove Flag Argument + +**何时使用**：布尔参数改变函数行为 + +**动机**：通过拆分成明确函数，让行为更清楚。 + +**步骤**： +1. 针对不同旗标值创建显式函数 +2. 替换每个调用点 +3. 每次改动后测试 +4. 删除原函数 + +**前：** +```javascript +function bookConcert(customer, isPremium) { + if (isPremium) { + // premium booking logic + } else { + // regular booking logic + } +} + +bookConcert(customer, true); +bookConcert(customer, false); +``` + +**后：** +```javascript +function bookPremiumConcert(customer) { + // premium booking logic +} + +function bookRegularConcert(customer) { + // regular booking logic +} + +bookPremiumConcert(customer); +bookRegularConcert(customer); +``` + +--- + +## 继承相关 + +### Pull Up Method + +**何时使用**：多个子类里有相同方法 + +**动机**：去掉类层次中的重复。 + +**步骤**： +1. 检查方法是否完全相同 +2. 确认签名一致 +3. 在超类中新建方法 +4. 从一个子类复制实现 +5. 删除一个子类中的方法并测试 +6. 删除其他子类中的方法并测试 + +--- + +### Push Down Method + +**何时使用**：某个行为只适用于部分子类 + +**动机**：把方法放到真正使用它的地方。 + +**步骤**： +1. 把方法复制到需要它的子类 +2. 从超类删除方法 +3. 测试 +4. 删除不需要该方法的子类副本 +5. 测试 + +--- + +### Replace Subclass with Delegate + +**何时使用**：继承用得不对，需要更灵活 + +**动机**：在合适的地方更偏向组合而不是继承。 + +**步骤**： +1. 创建一个空的委托类 +2. 在宿主类中加一个持有委托的字段 +3. 在宿主类构造委托 +4. 把功能迁移到委托类 +5. 每次迁移后测试 +6. 用委托替代继承 + +--- + +## Extract Class + +**何时使用**：大类里有多个职责 + +**动机**：拆分类以维持单一职责。 + +**步骤**： +1. 决定如何拆分职责 +2. 创建新类 +3. 把字段从原类移到新类 +4. 测试 +5. 把方法从原类移到新类 +6. 每次移动后测试 +7. 重新检查并命名两个类 +8. 决定如何暴露新类 + +**前：** +```javascript +class Person { + get name() { return this._name; } + set name(arg) { this._name = arg; } + get officeAreaCode() { return this._officeAreaCode; } + set officeAreaCode(arg) { this._officeAreaCode = arg; } + get officeNumber() { return this._officeNumber; } + set officeNumber(arg) { this._officeNumber = arg; } + + get telephoneNumber() { + return `(${this._officeAreaCode}) ${this._officeNumber}`; + } +} +``` + +**后：** +```javascript +class Person { + constructor() { + this._telephoneNumber = new TelephoneNumber(); + } + get name() { return this._name; } + set name(arg) { this._name = arg; } + get telephoneNumber() { return this._telephoneNumber.toString(); } + get officeAreaCode() { return this._telephoneNumber.areaCode; } + set officeAreaCode(arg) { this._telephoneNumber.areaCode = arg; } +} + +class TelephoneNumber { + get areaCode() { return this._areaCode; } + set areaCode(arg) { this._areaCode = arg; } + get number() { return this._number; } + set number(arg) { this._number = arg; } + toString() { return `(${this._areaCode}) ${this._number}`; } +} +``` + +--- + +## 快速参考：异味到重构 + +| 代码异味 | 主要重构 | 备选方案 | +|----------|---------|---------| +| 长函数 | Extract Method | Replace Temp with Query | +| 重复代码 | Extract Method | Pull Up Method | +| 大类 | Extract Class | Extract Subclass | +| 长参数列表 | Introduce Parameter Object | Preserve Whole Object | +| Feature Envy | Move Method | Extract Method + Move | +| 数据泥团 | Extract Class | Introduce Parameter Object | +| 基础类型沉迷 | Replace Primitive with Object | Replace Type Code | +| switch 语句 | Replace Conditional with Polymorphism | Replace Type Code | +| 临时字段 | Extract Class | Introduce Null Object | +| 消息链 | Hide Delegate | Extract Method | +| 中间人 | Remove Middle Man | Inline Method | +| 发散式变化 | Extract Class | Split Phase | +| 散弹式修改 | Move Method | Inline Class | +| 死代码 | Remove Dead Code | - | +| 臆想泛化 | Collapse Hierarchy | Inline Class | + +--- + +## 延伸阅读 + +- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (第 2 版) +- 在线目录：https://refactoring.com/catalog/ diff --git a/zh/03-skills/refactor/templates/refactoring-plan.md b/zh/03-skills/refactor/templates/refactoring-plan.md new file mode 100644 index 0000000..82e9b7a --- /dev/null +++ b/zh/03-skills/refactor/templates/refactoring-plan.md @@ -0,0 +1,284 @@ +# 重构计划模板 + +使用这个模板来记录和跟踪你的重构工作。 + +--- + +## 项目信息 + +| 字段 | 值 | +|-------|-------| +| **项目 / 模块** | [项目名称] | +| **目标文件** | [要重构的文件列表] | +| **创建日期** | [日期] | +| **作者** | [姓名] | +| **状态** | Draft / In Review / Approved / In Progress / Completed | + +--- + +## 执行摘要 + +### 目标 +- [ ] [主要目标：例如，提升支付流程可读性] +- [ ] [次要目标：例如，减少重复代码] +- [ ] [第三目标：例如，提升可测试性] + +### 约束 +- [ ] [约束 1：例如，不能改公共 API] +- [ ] [约束 2：例如，必须保持向后兼容] +- [ ] [约束 3：例如，不能改数据库 schema] + +### 风险等级 +- [ ] Low - 小改动，测试充分 +- [ ] Medium - 中等改动，有一定风险 +- [ ] High - 大改动，需要特别注意 + +--- + +## 重构前检查清单 + +### 测试覆盖评估 + +| 指标 | 当前值 | 目标值 | 状态 | +|--------|---------|---------|--------| +| 单元测试覆盖率 | __% | ≥80% | | +| 集成测试 | Yes/No | Yes | | +| 所有测试通过 | Yes/No | Yes | | + +### 开始前必须满足 +- [ ] 所有测试通过 +- [ ] 已读懂并审查代码 +- [ ] 已有备份 / 版本控制 +- [ ] 已获得用户批准 + +--- + +## 已识别的代码异味 + +### 摘要 + +| # | 异味 | 位置 | 严重性 | 优先级 | +|---|-------|------|------|------| +| 1 | [例如，Long Method] | [file:line] | High | P1 | +| 2 | [例如，Duplicate Code] | [file:line] | Medium | P2 | +| 3 | [例如，Feature Envy] | [file:line] | Low | P3 | + +### 详细分析 + +#### 异味 #1：[名称] + +**位置**：`path/to/file.js:45-120` + +**描述**：[对问题的详细描述] + +**影响**： +- [影响 1] +- [影响 2] + +**建议方案**：[如何修复的简要说明] + +--- + +## 重构阶段 + +### 阶段 A：快速收益（低风险） + +**目标**：快速、低风险的改进，立刻产生价值 + +**预计改动**：[X 个文件，Y 个方法] + +**需要用户批准**：Yes / No + +| # | 任务 | 文件 | 重构手法 | 状态 | +|---|------|------|----------|------| +| A1 | 将变量 `x` 重命名为 `userCount` | utils.js:15 | Rename Variable | [ ] | +| A2 | 删除未使用的 `oldHandler()` | api.js:89 | Remove Dead Code | [ ] | +| A3 | 提取重复的验证逻辑 | form.js:23,67 | Extract Method | [ ] | + +**回滚方案**：回退 A1-A3 的提交 + +--- + +### 阶段 B：结构优化（中风险） + +**目标**：改善代码组织和清晰度 + +**预计改动**：[X 个文件，Y 个方法] + +**需要用户批准**：Yes + +**依赖**：必须先完成阶段 A + +| # | 任务 | 文件 | 重构手法 | 状态 | +|---|------|------|----------|------| +| B1 | 从长函数中提取 `calculatePrice()` | order.js:45 | Extract Method | [ ] | +| B2 | 引入 `OrderDetails` 参数对象 | order.js:12 | Introduce Parameter Object | [ ] | +| B3 | 将 `formatAddress()` 移动到 Address 类 | customer.js:78 | Move Method | [ ] | + +**回滚方案**：回滚到阶段 A 完成后的提交 + +--- + +### 阶段 C：架构改动（高风险） + +**目标**：处理更深层的结构问题 + +**预计改动**：[X 个文件，Y 个方法] + +**需要用户批准**：Yes + +**依赖**：必须先完成阶段 A 和 B + +| # | 任务 | 文件 | 重构手法 | 状态 | +|---|------|------|----------|------| +| C1 | 用多态替换价格 switch | pricing.js:30 | Replace Conditional with Polymorphism | [ ] | +| C2 | 提取 `NotificationService` 类 | user.js:100 | Extract Class | [ ] | + +**回滚方案**：回滚到阶段 B 完成后的提交 + +--- + +## 详细重构步骤 + +### 任务 [ID]：[任务名称] + +**对应异味**：[异味名称] + +**重构手法**：[手法名称] + +**风险等级**：Low / Medium / High + +#### 上下文 + +**重构前**（当前状态）： +```javascript +// 把当前代码贴在这里 +``` + +**重构后**（期望状态）： +```javascript +// 把期望代码贴在这里 +``` + +#### 逐步操作 + +1. [ ] **步骤 1**：[描述] + - 测试：完成此步后运行测试 + - 预期：所有测试通过 + +2. [ ] **步骤 2**：[描述] + - 测试：完成此步后运行测试 + - 预期：所有测试通过 + +3. [ ] **步骤 3**：[描述] + - 测试：完成此步后运行测试 + - 预期：所有测试通过 + +#### 验证 + +- [ ] 所有测试通过 +- [ ] 行为未改变 +- [ ] 代码可编译 +- [ ] 没有新的警告 + +#### 提交信息 +``` +refactor: [描述这次重构] +``` + +--- + +## 进度跟踪 + +### 阶段状态 + +| 阶段 | 状态 | 开始时间 | 完成时间 | 测试是否通过 | +|------|------|----------|----------|--------------| +| A | Not Started / In Progress / Done | | | | +| B | Not Started / In Progress / Done | | | | +| C | Not Started / In Progress / Done | | | | + +### 遇到的问题 + +| # | 问题 | 解决方案 | 状态 | +|---|------|----------|------| +| 1 | [描述] | [如何解决] | Open / Resolved | + +--- + +## 指标对比 + +### 重构前 + +| 指标 | 文件 1 | 文件 2 | 总计 | +|------|------|------|------| +| 代码行数 | | | | +| 圈复杂度 | | | | +| 可维护性指标 | | | | +| 方法数量 | | | | +| 平均方法长度 | | | | + +### 重构后 + +| 指标 | 文件 1 | 文件 2 | 总计 | 变化 | +|------|------|------|------|------| +| 代码行数 | | | | | +| 圈复杂度 | | | | | +| 可维护性指标 | | | | | +| 方法数量 | | | | | +| 平均方法长度 | | | | | + +--- + +## 重构后检查清单 + +- [ ] 所有测试通过 +- [ ] 没有新的警告或错误 +- [ ] 代码成功编译 +- [ ] 已完成手工验证 +- [ ] 文档已更新（如需要） +- [ ] 已完成代码审查 +- [ ] 指标有改善 +- [ ] 已获得用户签字确认 + +--- + +## 经验总结 + +### 做得好的地方 +- [Item 1] +- [Item 2] + +### 可以改进的地方 +- [Item 1] +- [Item 2] + +### 未来建议 +- [Item 1] +- [Item 2] + +--- + +## 批准 + +| 角色 | 姓名 | 日期 | 签名 | +|------|------|------|------| +| Plan Author | | | | +| Technical Lead | | | | +| Product Owner | | | | + +--- + +## 附录 + +### A. 相关文档 +- [相关文档链接] + +### B. 参考资料 +- [代码异味目录] +- [重构目录] + +### C. 使用的工具 +- [测试框架] +- [Lint 工具] +- [复杂度分析工具] diff --git a/zh/04-subagents/README.md b/zh/04-subagents/README.md new file mode 100644 index 0000000..7d55a10 --- /dev/null +++ b/zh/04-subagents/README.md @@ -0,0 +1,380 @@ + + + Claude How To + + +# Subagents 完整参考 + +## 概览 + +Subagents 是专门处理某类任务的独立 AI 助手。它们拥有隔离的上下文、自己的提示词和工具权限，适合把复杂工作拆分给不同角色。 + +## 主要好处 + +- 上下文隔离 +- 角色分工清晰 +- 适合并行和委派 +- 便于把复杂任务拆开 + +## 文件位置 + +- 项目级：`.claude/agents/` +- 用户级：`~/.claude/agents/` + +## 配置 + +### 文件格式 + +Subagent 通常是一个带 frontmatter 的 Markdown 文件。 + +```yaml +--- +name: code-reviewer +description: 审查代码质量和安全问题 +tools: Read, Grep, Bash +--- + +# Code Reviewer +``` + +### 配置字段 + +| 字段 | 说明 | +|------|------| +| `name` | subagent 名称 | +| `description` | 何时该调用它 | +| `tools` | 允许使用的工具 | +| `model` | 指定模型 | +| `prompt` | 任务提示词 | +| `context` | 上下文策略 | + +### 工具配置选项 + +- 只读审查 +- 限制 Bash +- 允许更强工具集 + +### 基于 CLI 的配置 + +你也可以通过命令行或设置文件定义 subagent。 + +## 内置 Subagents + +Claude Code 自带一些常见角色，例如： + +- 通用助手 +- Planning agent +- Explore agent +- Bash agent +- Statusline 相关 agent +- Claude Code Guide agent + +## 管理 Subagents + +### 使用 `/agents` 命令（推荐） + +```bash +/agents +``` + +### 直接管理文件 + +#### 创建项目 subagent + +```bash +mkdir -p .claude/agents +``` + +#### 创建用户 subagent + +```bash +mkdir -p ~/.claude/agents +``` + +## 使用 Subagents + +### 自动委派 + +主 agent 可以根据任务描述自动把工作分配给合适的 subagent。 + +### 显式调用 + +你也可以明确让 Claude 使用某个 subagent。 + +### `@` 提及调用 + +在一些场景里，可以通过 `@agent-name` 方式引用。 + +### 会话级 agent + +可以在整个会话中固定使用某个 agent。 + +### 列出可用 agents + +```bash +claude agents +``` + +## 可恢复的 agents + +某些 subagent 可以先启动，之后再恢复，便于长任务接力。 + +## 串联 Subagents + +复杂任务里可以让多个 subagent 依次协作，例如： + +1. 代码审查 +2. 测试生成 +3. 文档更新 + +## Subagents 的持久记忆 + +Subagents 可以拥有自己的 memory 范围，让它们在各自职责内保持一致。 + +### Memory 范围 + +- 项目级 +- 用户级 +- 子目录级 + +### 工作方式 + +Subagent 会在自己的上下文中读取对应记忆，不和主会话完全混在一起。 + +## 后台 Subagents + +### 配置 + +有些 subagent 可以作为后台任务执行，不阻塞主会话。 + +### 快捷键 + +在支持的界面中，可用快捷键查看或切换后台 subagent。 + +### 关闭后台任务 + +如果你不想让任务后台运行，可以在设置中关闭。 + +## Worktree 隔离 + +### 配置 + +可以为 subagent 分配独立的 worktree。 + +### 工作方式 + +这样不同任务就不会互相污染文件状态。 + +## 限制可启动的 Subagents + +你可以限制 Claude 只能 spawn 某些 subagent，以降低风险。 + +### 示例 + +- 只允许审查类 agent +- 禁止高风险自动化 agent + +## `claude agents` CLI 命令 + +用于查看和管理当前可用的 agent。 + +## Agent Teams（实验性） + +Agent teams 是更高级的协作模式，适合多个 subagent 并行处理复杂任务。 + +### Subagents vs Agent Teams + +- Subagents 侧重委派单个任务 +- Agent teams 侧重多角色协作 + +### 启用 Agent Teams + +通过设置打开实验性功能。 + +### 启动团队 + +团队模式会把不同任务分配给不同角色。 + +### 显示模式 + +可以选择更适合终端或图形界面的显示方式。 + +### 导航 + +你可以在 team 中切换角色、查看状态和读取消息。 + +### 团队配置 + +适合为大型流程定义清晰角色。 + +### 架构 + +agent team 本质上是多个专门角色围绕同一任务协作。 + +### 任务分配与消息 + +主 agent 会负责把任务拆分并转发给对应 subagent。 + +### 计划审批流程 + +如果是 plan 驱动流程，团队会先审计划再执行。 + +### 团队相关 hook 事件 + +一些 hook 可以在 team 生命周期里触发。 + +### 最佳实践 + +- 角色定义要清楚 +- 任务边界要明确 +- 不要让多个 agent 做重复工作 + +### 局限 + +- 实验性功能可能会变化 +- 复杂团队需要更多配置 + +## 插件中的 Subagent 安全 + +插件分发的 subagent 要特别注意权限、工具范围和边界条件。 + +## 架构 + +### 高层架构 + +主 agent、subagent、文件系统和工具权限共同构成执行链。 + +### 生命周期 + +1. 创建 +2. 分配任务 +3. 执行 +4. 返回结果 +5. 结束或恢复 + +## 上下文管理 + +### 关键点 + +- 子上下文尽量小 +- 让每个 subagent 只负责自己的事 +- 避免把所有信息都塞进去 + +### 性能考虑 + +过多的上下文会拖慢速度并降低准确性。 + +### 关键行为 + +subagent 在隔离上下文里工作，但仍能把结果汇总回主会话。 + +## 什么时候使用 Subagents + +- 任务可拆分 +- 需要隔离上下文 +- 需要明确角色分工 +- 需要并行协作 + +## 最佳实践 + +### 设计原则 + +- 单一职责 +- 描述明确 +- 工具权限最小化 + +### System Prompt 最佳实践 + +- 任务说明要具体 +- 不要写太长 +- 只保留执行任务所需的信息 + +### 工具访问策略 + +- 审查型 subagent 只读 +- 实现型 subagent 适度开放写权限 +- 高风险动作要保持审批 + +## 本目录中的示例 Subagents + +### 1. [Code Reviewer](./code-reviewer.md) + +用于全面代码质量审查。 + +### 2. [Test Engineer](./test-engineer.md) + +用于测试策略、覆盖率和测试生成。 + +### 3. [Documentation Writer](./documentation-writer.md) + +用于技术文档写作和更新。 + +### 4. [Secure Reviewer](./secure-reviewer.md) + +用于安全检查，通常只读。 + +### 5. [Implementation Agent](./implementation-agent.md) + +用于功能实现和代码修改。 + +### 6. [Debugger](./debugger.md) + +用于定位 bug 和分析异常。 + +### 7. [Data Scientist](./data-scientist.md) + +用于分析数据、解释结果和生成报告。 + +### 8. [Clean Code Reviewer](./clean-code-reviewer.md) + +用于按 Clean Code 原则做专门审查。 + +## 安装说明 + +### 方法 1：使用 `/agents` + +```bash +/agents +``` + +### 方法 2：复制到项目 + +```bash +mkdir -p .claude/agents +cp 04-subagents/*.md .claude/agents/ +``` + +### 方法 3：复制到用户目录 + +```bash +mkdir -p ~/.claude/agents +cp 04-subagents/*.md ~/.claude/agents/ +``` + +### 验证 + +- 运行 `/agents` +- 检查对应 agent 是否出现在列表中 +- 试着让 Claude 委派一个简单任务 + +## 文件结构 + +```text +.claude/agents/ +├── clean-code-reviewer.md +├── code-reviewer.md +├── data-scientist.md +├── debugger.md +├── documentation-writer.md +├── implementation-agent.md +├── secure-reviewer.md +├── test-engineer.md +└── README.md +``` + +## 相关概念 + +- [Skills 中文指南](../03-skills/README.md) +- [Memory 中文指南](../02-memory/README.md) +- [Hooks 中文指南](../06-hooks/README.md) +- [Plugins 中文指南](../07-plugins/README.md) diff --git a/zh/04-subagents/clean-code-reviewer.md b/zh/04-subagents/clean-code-reviewer.md new file mode 100644 index 0000000..87a9fa5 --- /dev/null +++ b/zh/04-subagents/clean-code-reviewer.md @@ -0,0 +1,66 @@ +--- +name: clean-code-reviewer +description: Clean Code 原则执行专家。审查代码中的 Clean Code 理论和最佳实践违规。写完代码后建议主动使用，确保可维护性和专业质量。 +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# Clean Code Reviewer Agent + +你是一名资深代码审查员，专注于 Clean Code 原则（Robert C. Martin）。你需要识别违规点并给出可执行的修复建议。 + +## 流程 +1. 运行 `git diff` 查看最近的变更 +2. 认真阅读相关文件 +3. 提供带有 `file:line`、代码片段和修复建议的审查结果 + +## 检查重点 + +**命名**：要能体现意图、可发音、可搜索。不要使用编码或前缀。类名用名词，方法名用动词。 + +**函数**：少于 20 行，只做一件事，最多 3 个参数，不要 flag 参数，不要副作用，不要返回 null。 + +**注释**：代码应当足够自解释。删除被注释掉的代码，不要写冗余或误导性的注释。 + +**结构**：保持类小而专注，单一职责，高内聚，低耦合。避免上帝类。 + +**SOLID**：单一职责、开闭原则、里氏替换、接口隔离、依赖倒置。 + +**DRY/KISS/YAGNI**：不要重复，保持简单，不要为假设中的未来过度设计。 + +**错误处理**：使用异常而不是错误码，提供上下文，永远不要返回或传递 null。 + +**坏味道**：死代码、特性依恋、长参数列表、消息链、基本类型偏执、投机性泛化。 + +## 严重级别 +- **Critical**：函数超过 50 行，5 个及以上参数，4 层及以上嵌套，多重职责 +- **High**：函数 20 到 50 行，4 个参数，命名不清晰，重复较多 +- **Medium**：轻微重复、用注释解释代码、格式问题 +- **Low**：轻微的可读性或组织性改进 + +## 输出格式 + +```text +# Clean Code Review + +## Summary +Files: [n] | Critical: [n] | High: [n] | Medium: [n] | Low: [n] + +## Violations + +**[Severity] [Category]** `file:line` +> [code snippet] +Problem: [what's wrong] +Fix: [how to fix] + +## Good Practices +[What's done well] +``` + +## 指南 +- 要具体：精确到代码和行号 +- 要建设性：解释为什么，并给出修复方式 +- 要务实：关注影响，跳过无关痛痒的小问题 +- 跳过：生成代码、配置文件、测试夹具 + +**核心理念**：代码被阅读的次数是写作的 10 倍。优化可读性，而不是炫技。 diff --git a/zh/04-subagents/code-reviewer.md b/zh/04-subagents/code-reviewer.md new file mode 100644 index 0000000..3db98a8 --- /dev/null +++ b/zh/04-subagents/code-reviewer.md @@ -0,0 +1,61 @@ +--- +name: code-reviewer +description: 代码审查专家。写完或修改代码后建议主动使用，确保质量、安全性和可维护性。 +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# Code Reviewer Agent + +你是一名资深代码审查员，负责确保代码质量和安全性维持在高标准。 + +被调用时： +1. 运行 `git diff` 查看最近的变更 +2. 重点检查被修改的文件 +3. 立即开始审查 + +## 审查优先级（按顺序） + +1. **安全问题** - 身份验证、授权、数据泄露 +2. **性能问题** - O(n^2) 操作、内存泄漏、低效查询 +3. **代码质量** - 可读性、命名、文档 +4. **测试覆盖率** - 缺失测试、边界情况 +5. **设计模式** - SOLID 原则、架构 + +## 审查清单 + +- 代码清晰易读 +- 函数和变量命名合理 +- 没有重复代码 +- 错误处理正确 +- 没有暴露密钥或 API key +- 已实现输入校验 +- 测试覆盖充分 +- 已考虑性能问题 + +## 审查输出格式 + +对每个问题都要提供： +- **Severity**: Critical / High / Medium / Low +- **Category**: Security / Performance / Quality / Testing / Design +- **Location**: 文件路径和行号 +- **Issue Description**: 问题是什么，为什么有问题 +- **Suggested Fix**: 代码示例 +- **Impact**: 这会怎样影响系统 + +请按优先级组织反馈： +1. Critical issues（必须修） +2. Warnings（应该修） +3. Suggestions（可考虑改进） + +请给出具体的修复示例。 + +## 审查示例 + +### 问题：N+1 查询 +- **Severity**: High +- **Category**: Performance +- **Location**: src/user-service.ts:45 +- **Issue**: 循环在每次迭代中都执行数据库查询 +- **Fix**: 使用 JOIN 或批量查询 +- **Impact**: 响应时间会随着数据量线性增长 diff --git a/zh/04-subagents/data-scientist.md b/zh/04-subagents/data-scientist.md new file mode 100644 index 0000000..2bdb2e6 --- /dev/null +++ b/zh/04-subagents/data-scientist.md @@ -0,0 +1,97 @@ +--- +name: data-scientist +description: 数据分析专家，擅长 SQL 查询、BigQuery 操作和数据洞察。适用于数据分析任务和查询场景。 +tools: Bash, Read, Write +model: sonnet +--- + +# Data Scientist Agent + +你是一名专注于 SQL 和 BigQuery 分析的数据科学家。 + +被调用时： +1. 理解数据分析需求 +2. 编写高效的 SQL 查询 +3. 在合适时使用 BigQuery 命令行工具（`bq`） +4. 分析并总结结果 +5. 清晰地呈现发现 + +## 核心实践 + +- 编写经过优化的 SQL 查询，并使用合适的过滤条件 +- 使用恰当的聚合和 join +- 为复杂逻辑添加注释 +- 让结果易于阅读 +- 提供数据驱动的建议 + +## SQL 最佳实践 + +### 查询优化 + +- 使用 `WHERE` 尽早过滤 +- 使用合适的索引 +- 生产环境避免 `SELECT *` +- 探索数据时限制结果集 + +### BigQuery 相关 + +```bash +# 运行查询 +bq query --use_legacy_sql=false 'SELECT * FROM dataset.table LIMIT 10' + +# 导出结果 +bq query --use_legacy_sql=false --format=csv 'SELECT ...' > results.csv + +# 查看表结构 +bq show --schema dataset.table +``` + +## 分析类型 + +1. **探索性分析** + - 数据剖析 + - 分布分析 + - 缺失值检测 + +2. **统计分析** + - 聚合与汇总 + - 趋势分析 + - 相关性检测 + +3. **报告** + - 提取关键指标 + - 环比/同比对比 + - 面向管理层的总结 + +## 输出格式 + +对每次分析，提供： +- **Objective**: 我们在回答什么问题 +- **Query**: 使用的 SQL（带注释） +- **Results**: 关键发现 +- **Insights**: 基于数据的结论 +- **Recommendations**: 建议的下一步 + +## 示例查询 + +```sql +-- 月活跃用户趋势 +SELECT + DATE_TRUNC(created_at, MONTH) as month, + COUNT(DISTINCT user_id) as active_users, + COUNT(*) as total_events +FROM events +WHERE + created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH) + AND event_type = 'login' +GROUP BY 1 +ORDER BY 1 DESC; +``` + +## 分析检查清单 + +- [ ] 已理解需求 +- [ ] 查询已优化 +- [ ] 结果已验证 +- [ ] 发现已记录 +- [ ] 建议已提供 diff --git a/zh/04-subagents/debugger.md b/zh/04-subagents/debugger.md new file mode 100644 index 0000000..ecb2a1b --- /dev/null +++ b/zh/04-subagents/debugger.md @@ -0,0 +1,80 @@ +--- +name: debugger +description: 排错专家，负责处理错误、测试失败和异常行为。遇到问题时建议主动使用。 +tools: Read, Edit, Bash, Grep, Glob +model: inherit +--- + +# Debugger Agent + +你是一名擅长根因分析的专家级排错人员。 + +被调用时： +1. 获取错误信息和堆栈追踪 +2. 找到复现步骤 +3. 定位故障位置 +4. 实施最小修复 +5. 验证修复有效 + +## 排错流程 + +1. **分析错误信息和日志** + - 阅读完整错误信息 + - 检查堆栈追踪 + - 查看最近的日志输出 + +2. **检查最近的代码变更** + - 运行 `git diff` 查看修改 + - 找出可能破坏行为的改动 + - 回看提交历史 + +3. **提出并测试假设** + - 从最可能的原因开始 + - 添加有针对性的调试日志 + - 检查变量状态 + +4. **隔离故障** + - 缩小到具体函数或行号 + - 创建最小复现案例 + - 验证隔离结果 + +5. **实现并验证修复** + - 做最小必要修改 + - 运行测试确认修复 + - 检查回归问题 + +## 调试输出格式 + +针对每个问题，提供： +- **Error**: 原始错误信息 +- **Root Cause**: 为什么会失败 +- **Evidence**: 你如何确定原因 +- **Fix**: 具体做了哪些代码修改 +- **Testing**: 如何验证修复 +- **Prevention**: 如何避免再次发生 + +## 常用调试命令 + +```bash +# 查看最近变更 +git diff HEAD~3 + +# 搜索错误模式 +grep -r "error" --include="*.log" + +# 查找相关代码 +grep -r "functionName" --include="*.ts" + +# 运行指定测试 +npm test -- --grep "test name" +``` + +## 排查检查清单 + +- [ ] 已捕获错误信息 +- [ ] 已分析堆栈追踪 +- [ ] 已检查最近变更 +- [ ] 已定位根因 +- [ ] 已实现修复 +- [ ] 测试通过 +- [ ] 未引入回归 diff --git a/zh/04-subagents/documentation-writer.md b/zh/04-subagents/documentation-writer.md new file mode 100644 index 0000000..e3b28ff --- /dev/null +++ b/zh/04-subagents/documentation-writer.md @@ -0,0 +1,98 @@ +--- +name: documentation-writer +description: 技术文档专家，负责 API 文档、用户指南和架构文档。 +tools: Read, Write, Grep +model: inherit +--- + +# Documentation Writer Agent + +你是一名技术写作者，负责创建清晰、完整的文档。 + +被调用时： +1. 分析要记录的代码或功能 +2. 确定目标读者 +3. 按项目规范编写文档 +4. 根据实际代码验证准确性 + +## 文档类型 + +- 带示例的 API 文档 +- 用户指南和教程 +- 架构文档 +- Changelog 条目 +- 代码注释改进 + +## 文档标准 + +1. **清晰** - 使用简单、明确的语言 +2. **示例** - 包含实用的代码示例 +3. **完整** - 覆盖所有参数和返回值 +4. **结构** - 使用一致的格式 +5. **准确** - 根据实际代码验证 + +## 文档章节 + +### API 文档 + +- 描述 +- 参数（含类型） +- 返回值（含类型） +- 抛出错误（可能的异常） +- 示例（curl、JavaScript、Python） +- 相关端点 + +### 功能文档 + +- 概述 +- 前置条件 +- 分步说明 +- 预期结果 +- 故障排查 +- 相关主题 + +## 输出格式 + +每份生成的文档都要提供： +- **Type**: API / Guide / Architecture / Changelog +- **File**: 文档文件路径 +- **Sections**: 覆盖的章节列表 +- **Examples**: 包含的代码示例数量 + +## API 文档示例 + +```markdown +## GET /api/users/:id + +通过唯一标识符检索用户。 + +### Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| id | string | Yes | 用户的唯一标识符 | + +### Response + +```json +{ + "id": "abc123", + "name": "John Doe", + "email": "john@example.com" +} +``` + +### Errors + +| Code | Description | +|------|-------------| +| 404 | User not found | +| 401 | Unauthorized | + +### Example + +```bash +curl -X GET https://api.example.com/api/users/abc123 \ + -H "Authorization: Bearer " +``` +``` diff --git a/zh/04-subagents/implementation-agent.md b/zh/04-subagents/implementation-agent.md new file mode 100644 index 0000000..5b46493 --- /dev/null +++ b/zh/04-subagents/implementation-agent.md @@ -0,0 +1,78 @@ +--- +name: implementation-agent +description: 全栈实现专家，负责根据规范开发功能。拥有完整工具权限，可端到端完成实现。 +tools: Read, Write, Edit, Bash, Grep, Glob +model: inherit +--- + +# Implementation Agent + +你是一名资深开发者，负责根据规格实现功能。 + +这个 agent 拥有完整能力： +- 阅读规范和现有代码 +- 创建新的代码文件 +- 编辑已有文件 +- 运行构建命令 +- 搜索代码库 +- 查找匹配模式的文件 + +## 实现流程 + +被调用时： +1. 充分理解需求 +2. 分析现有代码库模式 +3. 制定实现方案 +4. 逐步实现 +5. 边做边测试 +6. 清理和重构 + +## 实现指南 + +### 代码质量 + +- 遵循现有项目规范 +- 编写自解释代码 +- 只有在逻辑复杂时才添加注释 +- 保持函数短小专注 +- 使用有意义的变量名 + +### 文件组织 + +- 按项目结构放置文件 +- 相关功能放在一起 +- 遵循命名规范 +- 避免过深的目录嵌套 + +### 错误处理 + +- 处理所有错误情况 +- 提供有意义的错误信息 +- 合理记录错误日志 +- 优雅失败 + +### 测试 + +- 为新功能编写测试 +- 确保现有测试通过 +- 覆盖边界情况 +- 为 API 添加集成测试 + +## 输出格式 + +每个实现任务都要提供： +- **Files Created**: 新文件列表 +- **Files Modified**: 已修改文件列表 +- **Tests Added**: 测试文件路径 +- **Build Status**: Pass/Fail +- **Notes**: 重要说明 + +## 实现检查清单 + +在标记完成前： +- [ ] 代码符合项目规范 +- [ ] 所有测试通过 +- [ ] 构建成功 +- [ ] 没有 lint 错误 +- [ ] 已处理边界情况 +- [ ] 已实现错误处理 diff --git a/zh/04-subagents/secure-reviewer.md b/zh/04-subagents/secure-reviewer.md new file mode 100644 index 0000000..1bfca06 --- /dev/null +++ b/zh/04-subagents/secure-reviewer.md @@ -0,0 +1,75 @@ +--- +name: secure-reviewer +description: 安全审查专家，权限最小化。只读访问确保安全审计过程安全可靠。 +tools: Read, Grep +model: inherit +--- + +# Secure Code Reviewer + +你是一名安全专家，专注于识别漏洞。 + +这个 agent 采用最小权限设计： +- 可以读取文件进行分析 +- 可以搜索模式 +- 不能执行代码 +- 不能修改文件 +- 不能运行测试 + +这样可以确保审查过程中不会意外破坏任何东西。 + +## 安全审查重点 + +1. **身份验证问题** + - 弱密码策略 + - 缺少多因素认证 + - 会话管理缺陷 + +2. **授权问题** + - 访问控制失效 + - 权限提升 + - 缺少角色检查 + +3. **数据暴露** + - 日志中泄露敏感数据 + - 未加密存储 + - API key 泄露 + - PII 处理问题 + +4. **注入漏洞** + - SQL 注入 + - 命令注入 + - XSS（跨站脚本） + - LDAP 注入 + +5. **配置问题** + - 生产环境开启调试模式 + - 默认凭据 + - 不安全的默认配置 + +## 搜索模式 + +```bash +# 硬编码密钥 +grep -r "password\s*=" --include="*.js" --include="*.ts" +grep -r "api_key\s*=" --include="*.py" +grep -r "SECRET" --include="*.env*" + +# SQL 注入风险 +grep -r "query.*\$" --include="*.js" +grep -r "execute.*%" --include="*.py" + +# 命令注入风险 +grep -r "exec(" --include="*.js" +grep -r "os.system" --include="*.py" +``` + +## 输出格式 + +对每个漏洞，提供： +- **Severity**: Critical / High / Medium / Low +- **Type**: OWASP 类别 +- **Location**: 文件路径和行号 +- **Description**: 漏洞是什么 +- **Risk**: 如果被利用，可能造成什么影响 +- **Remediation**: 如何修复 diff --git a/zh/04-subagents/test-engineer.md b/zh/04-subagents/test-engineer.md new file mode 100644 index 0000000..9e2bde8 --- /dev/null +++ b/zh/04-subagents/test-engineer.md @@ -0,0 +1,74 @@ +--- +name: test-engineer +description: 测试自动化专家，负责编写全面测试。新功能上线或代码修改后建议主动使用。 +tools: Read, Write, Bash, Grep +model: inherit +--- + +# Test Engineer Agent + +你是一名擅长完整测试覆盖的测试工程师。 + +被调用时： +1. 分析需要测试的代码 +2. 识别关键路径和边界情况 +3. 按项目规范编写测试 +4. 运行测试验证通过 + +## 测试策略 + +1. **单元测试** - 独立测试单个函数或方法 +2. **集成测试** - 测试组件交互 +3. **端到端测试** - 测试完整工作流 +4. **边界情况** - 边界条件、空值、空集合 +5. **错误场景** - 失败处理、非法输入 + +## 测试要求 + +- 使用项目现有测试框架（Jest、pytest 等） +- 每个测试都要包含 setup/teardown +- Mock 外部依赖 +- 用清晰描述说明测试目的 +- 在相关场景下加入性能断言 + +## 覆盖率要求 + +- 最低 80% 代码覆盖率 +- 关键路径（认证、支付、数据处理）要求 100% +- 报告缺失的覆盖区域 + +## 测试输出格式 + +每个测试文件都要提供： +- **File**: 测试文件路径 +- **Tests**: 测试用例数量 +- **Coverage**: 预计覆盖率提升 +- **Critical Paths**: 覆盖了哪些关键路径 + +## 测试结构示例 + +```javascript +describe('Feature: User Authentication', () => { + beforeEach(() => { + // Setup + }); + + afterEach(() => { + // Cleanup + }); + + it('should authenticate valid credentials', async () => { + // Arrange + // Act + // Assert + }); + + it('should reject invalid credentials', async () => { + // Test error case + }); + + it('should handle edge case: empty password', async () => { + // Test edge case + }); +}); +``` diff --git a/zh/05-mcp/README.md b/zh/05-mcp/README.md new file mode 100644 index 0000000..6c9945e --- /dev/null +++ b/zh/05-mcp/README.md @@ -0,0 +1,342 @@ + + + Claude How To + + +# 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____ [arguments] +``` + +例如： + +```bash +/mcp__github__list_prs +/mcp__github__pr_review 456 +/mcp__jira__create_issue "Bug title" high +``` + +## Server 去重 + +如果多个配置都指向同一个 server，Claude 会尽量避免重复加载。 + +## 通过 `@` 提及使用 MCP 资源 + +你可以把某些资源当作引用对象，在 prompt 中直接提及。 + +## MCP 作用域 + +MCP 配置通常有不同作用域，例如项目级和用户级。 + +### 使用项目作用域 + +适合把团队共享的 server 配置写进项目内。 + +## MCP 配置管理 + +### 添加 MCP server + +```bash +# Add HTTP-based server + +# Add local stdio server + +# List all MCP servers + +# Get details on specific server + +# Remove an MCP server + +# Reset project-specific approval choices + +# Import from Claude Desktop +``` + +## 可用 MCP Server 表 + +你可以在配置中维护一张 server 清单，记录用途、认证方式和安装命令。 + +## 实战示例 + +### 示例 1：GitHub MCP 配置 + +你可以用 GitHub MCP 做这些事： + +- PR 管理 +- Issue 管理 +- 仓库信息查询 +- commit 操作 + +### 环境变量展开 + +在配置中可以使用环境变量，让同一份配置适配不同环境。 + +### 示例 2：数据库 MCP + +```bash +# Using MCP database tool: + +# Results: +``` + +### 示例 3：多 MCP 工作流 + +适合日常报告、跨系统同步和自动化文档生成。 + +### 示例 4：文件系统 MCP 操作 + +可用于读写文件、批量整理、生成报告或导出结果。 + +## MCP vs Memory：决策矩阵 + +- **Memory**：适合长期规则、偏好和上下文 +- **MCP**：适合实时工具访问和外部数据 + +## 请求 / 响应模式 + +MCP 一般遵循： + +1. Claude 发起请求 +2. Server 处理 +3. 返回结构化结果 + +## 环境变量 + +常见环境变量包括： + +- API token +- 数据库地址 +- 服务端口 +- 认证信息 + +## Claude 作为 MCP Server（`claude mcp serve`） + +```bash +# Start Claude Code as an MCP server on stdio +``` + +## 受管 MCP 配置（企业） + +企业可通过受管设置统一分发 MCP 配置。 + +## 插件提供的 MCP Servers + +插件可以把自己的 MCP server 一起打包分发。 + +## Subagent 作用域 MCP + +某些 MCP 只允许特定 subagent 使用。 + +## MCP 输出限制 + +如果输出过大，可以限制 token 数或分页获取。 + +### 增大最大输出 + +```bash +# Increase the max output to 50,000 tokens +``` + +## 用代码执行解决上下文膨胀 + +当重复把大量数据回传给 Claude 会浪费 token 时，可以把 MCP 当作代码 API 来用，减少来回传输。 + +### 问题 + +- 两个信息源都在耗 token +- 大数据集不适合全量塞进上下文 + +### 方案 + +- 用 MCP 工具做实时查询 +- 只把必要结果传给 Claude + +#### 工作方式 + +Claude 通过工具调用从外部系统取回需要的数据，而不是把所有数据先写进上下文。 + +### 好处 + +- 更少 token 浪费 +- 更清晰的数据边界 +- 更适合大规模查询 + +#### 示例：过滤大数据集 + +#### 示例：循环而不做 round-trip + +### 取舍 + +- 实现复杂度更高 +- 需要维护 server +- 但扩展性更好 + +### MCPorter：MCP 工具组合运行时 + +这是更高级的工具编排思路，可以把多个 MCP 工具串成一个流程。 + +## 最佳实践 + +### 安全注意事项 + +#### 应该做的 + +- 只授权必要的工具 +- 优先使用最小权限 +- 检查输出是否可信 + +#### 不要做的 + +- 不要把高风险 token 写死在仓库里 +- 不要默认开放所有工具 +- 不要忽视网络和认证风险 + +### 配置建议 + +- 给每个 server 写清楚用途 +- 用环境变量存认证信息 +- 把项目级配置版本化 + +### 性能建议 + +- 避免一次性拉回过多数据 +- 优先做过滤和分页 +- 只返回 Claude 真正需要的结果 + +## 安装说明 + +### 前置条件 + +- Claude Code +- 对应的 MCP server +- 必要的认证信息 + +### 分步设置 + +1. 安装 server +2. 设置环境变量 +3. 添加到 Claude +4. 测试工具 + +### 特定服务的安装 + +不同服务会有不同的安装命令和认证方式。 + +## 故障排查 + +### 找不到 MCP Server + +- 检查是否安装 +- 检查路径 +- 检查配置是否正确 + +### 认证失败 + +- 检查环境变量是否设置 +- 确认 token 权限正确 +- 重新导出变量后再试 + +### 连接超时 + +- 检查网络 +- 检查 server 是否可用 + +### MCP Server 崩溃 + +- 查看 server 日志 +- 降低并发 +- 简化请求 + +## 相关概念 + +- [Memory 中文指南](../02-memory/README.md) +- [Subagents 中文参考](../04-subagents/README.md) +- [Plugins 中文指南](../07-plugins/README.md) + +## 更多资源 + +- [根目录中文指南](../README.md) +- [MCP 规范](https://modelcontextprotocol.io) diff --git a/zh/06-hooks/README.md b/zh/06-hooks/README.md new file mode 100644 index 0000000..3a84f8a --- /dev/null +++ b/zh/06-hooks/README.md @@ -0,0 +1,98 @@ + + + Claude How To + + +# Hooks 参考 + +Hooks 是在 Claude Code 事件发生时自动执行的 shell 命令，用来做格式化、校验、通知、审计等自动化工作。 + +## 概览 + +Hooks 是事件驱动的自动化机制。它们会在 Claude Code 发生某些动作时自动运行，不需要你手动触发。 + +常见用途： + +- 写文件前自动格式化 +- 提交前运行测试 +- 扫描安全问题 +- 记录 bash 命令 +- 校验用户提示词 +- 发送团队通知 + +## Hook 类型 + +Claude Code 提供 4 类、25 个事件： + +- **Tool Hooks**：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` +- **Session Hooks**：`SessionStart`、`SessionEnd`、`Stop`、`StopFailure`、`SubagentStart`、`SubagentStop` +- **Task Hooks**：`UserPromptSubmit`、`TaskCompleted`、`TaskCreated`、`TeammateIdle` +- **Lifecycle Hooks**：`ConfigChange`、`CwdChanged`、`FileChanged`、`PreCompact`、`PostCompact`、`WorktreeCreate`、`WorktreeRemove`、`Notification`、`InstructionsLoaded`、`Elicitation`、`ElicitationResult` + +## 安装 + +```bash +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh +``` + +然后在 `~/.claude/settings.json` 里配置： + +```json +{ + "hooks": { + "PreToolUse": [{ + "matcher": "Write", + "hooks": ["~/.claude/hooks/format-code.sh"] + }], + "PostToolUse": [{ + "matcher": "Write", + "hooks": ["~/.claude/hooks/security-scan.sh"] + }] + } +} +``` + +## 使用方法 + +Hooks 会在匹配到事件时自动执行。你可以把它理解成 Claude Code 的事件回调。 + +## 常见示例 + +- `format-code.sh` - 写入前自动格式化 +- `pre-commit.sh` - 提交前跑测试 +- `security-scan.sh` - 做安全扫描 +- `log-bash.sh` - 记录 bash 命令 +- `validate-prompt.sh` - 校验输入 +- `notify-team.sh` - 发通知 + +## 最佳实践 + +- 把 hooks 保持短小明确 +- 只做单一职责 +- 先在本地测试 +- 不要在 hook 里放复杂业务逻辑 +- 对副作用保持谨慎 + +## 故障排查 + +- 检查文件路径和权限 +- 确认脚本可执行 +- 检查 settings.json 语法 +- 查看 Claude Code 版本兼容性 + +## 相关概念 + +- [Checkpoints and Rewind](../08-checkpoints/README.md) +- [Slash Commands](../01-slash-commands/README.md) +- [Skills](../03-skills/README.md) +- [Subagents](../04-subagents/README.md) +- [Plugins](../07-plugins/README.md) +- [Advanced Features](../09-advanced-features/README.md) + +## 更多资源 + +- [Memory Guide](../02-memory/README.md) +- [Official Hooks Documentation](https://code.claude.com/docs/en/hooks) +- [CLI Reference](https://code.claude.com/docs/en/cli-reference) diff --git a/zh/07-plugins/README.md b/zh/07-plugins/README.md new file mode 100644 index 0000000..7390745 --- /dev/null +++ b/zh/07-plugins/README.md @@ -0,0 +1,930 @@ + + + Claude How To + + +# 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["官方
anthropics/claude-plugins-official"] + C["社区
市场"] + D["企业
私有仓库"] + + 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 @ # 从市场安装 +claude plugin uninstall # 删除插件 +claude plugin list # 列出已安装插件 +claude plugin enable # 启用已禁用的插件 +claude plugin disable # 禁用插件 +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{"多个命令
或 subagents
或 MCPs?"} + B -->|是| C["✅ 创建插件"] + B -->|否| D["使用单独功能"] + A -->|团队工作流| E{"要和
团队共享吗？"} + E -->|是| C + E -->|否| F["保持本地配置"] + A -->|复杂设置| G{"需要自动
配置吗？"} + G -->|是| C + G -->|否| D +``` + +### 插件适用场景 + +| 场景 | 建议 | 原因 | +|------|------|------| +| **团队入职** | ✅ 使用插件 | 即时安装，包含所有配置 | +| **框架初始化** | ✅ 使用插件 | 打包框架专属命令 | +| **企业规范** | ✅ 使用插件 | 集中分发，版本控制 | +| **快速任务自动化** | ❌ 使用命令 | 太重 | +| **单一领域能力** | ❌ 使用 Skill | 太重，直接用 skill 更合适 | +| **专门化分析** | ❌ 使用 Subagent | 可手动创建，或用 skill | +| **实时数据访问** | ❌ 使用 MCP | 独立使用，不要打包 | + +## 测试插件 + +在发布前，使用 `--plugin-dir` CLI 参数在本地测试插件（可以重复指定多个插件）： + +```bash +claude --plugin-dir ./my-plugin +claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin +``` + +这会用已加载插件启动 Claude Code，让你可以： +- 验证所有 slash commands 是否可用 +- 测试 subagents 和 agents 是否正常工作 +- 确认 MCP servers 能正确连接 +- 验证 hooks 的执行 +- 检查 LSP server 配置 +- 检查是否有配置错误 + +## 热重载 + +插件支持开发期间的热重载。当你修改插件文件时，Claude Code 可以自动检测变化。你也可以手动触发重载： + +```bash +/reload-plugins +``` + +这会重新读取所有插件清单、commands、agents、skills、hooks 以及 MCP/LSP 配置，而无需重启会话。 + +## 插件托管设置 + +管理员可以使用托管设置在组织范围内控制插件行为： + +| 设置 | 说明 | +|------|------| +| `enabledPlugins` | 默认启用的插件白名单 | +| `deniedPlugins` | 不允许安装的插件黑名单 | +| `extraKnownMarketplaces` | 在默认列表之外添加额外市场源 | +| `strictKnownMarketplaces` | 限制用户允许添加的市场 | +| `allowedChannelPlugins` | 控制每个发布渠道允许使用哪些插件 | + +这些设置可以通过托管配置文件应用到组织级别，并且优先于用户级设置。 + +## 插件安全 + +插件 subagents 运行在受限沙箱中。以下 frontmatter 键在插件 subagent 定义中**不允许**使用： + +- `hooks` - subagents 不能注册事件处理器 +- `mcpServers` - subagents 不能配置 MCP servers +- `permissionMode` - subagents 不能覆盖权限模型 + +这可以确保插件不会越权，也不会修改主机环境的作用范围。 + +## 发布插件 + +**发布步骤：** + +1. 使用所有组件创建插件结构 +2. 编写 `.claude-plugin/plugin.json` 清单 +3. 创建带文档的 `README.md` +4. 使用 `claude --plugin-dir ./my-plugin` 在本地测试 +5. 提交到插件市场 +6. 经过审查和批准 +7. 发布到市场 +8. 用户即可一条命令安装 + +**示例提交：** + +```markdown +# PR 审查插件 + +## 描述 +包含安全、测试和文档检查的完整 PR 审查工作流。 + +## 包含内容 +- 3 个用于不同审查类型的 slash commands +- 3 个专门化 subagents +- GitHub 和 CodeQL MCP 集成 +- 自动安全扫描 hooks + +## 安装 +```bash +/plugin install pr-review +``` + +## 功能 +✅ 安全分析 +✅ 测试覆盖率检查 +✅ 文档校验 +✅ 代码质量评估 +✅ 性能影响分析 + +## 使用 +```bash +/review-pr +/check-security +/check-tests +``` + +## 要求 +- Claude Code 1.0+ +- GitHub 访问权限 +- CodeQL（可选） +``` + +## 插件 vs 手动配置 + +**手动设置（2+ 小时）：** +- 逐个安装 slash commands +- 单独创建 subagents +- 分别配置 MCP +- 手动设置 hooks +- 记录所有内容 +- 和团队共享（希望他们能配对） + +**使用插件（2 分钟）：** +```bash +/plugin install pr-review +# ✅ 一切都已安装并配置 +# ✅ 可以立即使用 +# ✅ 团队可以复现完全相同的设置 +``` + +## 最佳实践 + +### 应该做的 ✅ +- 使用清晰、描述性的插件名 +- 提供完整 README +- 正确使用语义化版本（semver） +- 一起测试所有组件 +- 清楚记录依赖和要求 +- 提供使用示例 +- 包含错误处理 +- 为发现性添加合适标签 +- 保持向后兼容 +- 保持插件聚焦且一致 +- 包含完整测试 +- 记录所有依赖 + +### 不要做的 ❌ +- 不要打包无关功能 +- 不要硬编码凭据 +- 不要跳过测试 +- 不要忘记文档 +- 不要创建冗余插件 +- 不要忽略版本管理 +- 不要把组件依赖搞得过于复杂 +- 不要忘记优雅处理错误 + +## 安装说明 + +### 从市场安装 + +1. **浏览可用插件：** + ```bash + /plugin list + ``` + +2. **查看插件详情：** + ```bash + /plugin info plugin-name + ``` + +3. **安装插件：** + ```bash + /plugin install plugin-name + ``` + +### 从本地路径安装 + +```bash +/plugin install ./path/to/plugin-directory +``` + +### 从 GitHub 安装 + +```bash +/plugin install github:username/repo +``` + +### 列出已安装插件 + +```bash +/plugin list --installed +``` + +### 更新插件 + +```bash +/plugin update plugin-name +``` + +### 禁用 / 启用插件 + +```bash +# 临时禁用 +/plugin disable plugin-name + +# 重新启用 +/plugin enable plugin-name +``` + +### 卸载插件 + +```bash +/plugin uninstall plugin-name +``` + +## 相关概念 + +以下 Claude Code 功能会和插件一起协作： + +- **[Slash Commands](../01-slash-commands/README.md)** - 插件中打包的单独命令 +- **[Memory](../02-memory/README.md)** - 插件的持久上下文 +- **[Skills](../03-skills/README.md)** - 可以包装进插件的领域能力 +- **[Subagents](../04-subagents/README.md)** - 作为插件组件包含的专门化 agent +- **[MCP Servers](../05-mcp/README.md)** - 打包在插件中的 Model Context Protocol 集成 +- **[Hooks](../06-hooks/README.md)** - 触发插件工作流的事件处理器 + +## 完整示例工作流 + +### PR Review 插件完整工作流 + +``` +1. 用户：/review-pr + +2. 插件执行： + ├── pre-review.js hook 验证 git repo + ├── GitHub MCP 获取 PR 数据 + ├── security-reviewer subagent 分析安全 + ├── test-checker subagent 验证覆盖率 + └── performance-analyzer subagent 检查性能 + +3. 汇总并展示结果： + ✅ 安全：没有发现关键问题 + ⚠️ 测试：覆盖率 65%（建议 80%+） + ✅ 性能：没有明显影响 + 📝 提供了 12 条建议 +``` + +## 故障排查 + +### 插件无法安装 +- 检查 Claude Code 版本兼容性：`/version` +- 用 JSON 校验器验证 `plugin.json` 语法 +- 检查网络连接（远程插件） +- 检查权限：`ls -la plugin/` + +### 组件没有加载 +- 验证 `plugin.json` 中的路径与实际目录结构一致 +- 检查文件权限：`chmod +x scripts/` +- 检查组件文件语法 +- 查看日志：`/plugin debug plugin-name` + +### MCP 连接失败 +- 确认环境变量已正确设置 +- 检查 MCP server 的安装和健康状态 +- 使用 `/mcp test` 独立测试 MCP 连接 +- 查看 `mcp/` 目录中的 MCP 配置 + +### 安装后命令不可用 +- 确认插件已成功安装：`/plugin list --installed` +- 检查插件是否已启用：`/plugin status plugin-name` +- 重启 Claude Code：`exit` 后重新打开 +- 检查是否与现有命令冲突 + +### Hook 执行问题 +- 确认 hook 文件权限正确 +- 检查 hook 语法和事件名 +- 查看 hook 日志中的错误细节 +- 如有可能，手动测试 hooks + +## 更多资源 + +- [官方插件文档](https://code.claude.com/docs/en/plugins) +- [发现插件](https://code.claude.com/docs/en/discover-plugins) +- [插件市场](https://code.claude.com/docs/en/plugin-marketplaces) +- [插件参考](https://code.claude.com/docs/en/plugins-reference) +- [MCP Server 参考](https://modelcontextprotocol.io/) +- [Subagent 配置指南](../04-subagents/README.md) +- [Hook 系统参考](../06-hooks/README.md) diff --git a/zh/07-plugins/devops-automation/README.md b/zh/07-plugins/devops-automation/README.md new file mode 100644 index 0000000..0131c53 --- /dev/null +++ b/zh/07-plugins/devops-automation/README.md @@ -0,0 +1,114 @@ +--- +name: DevOps 自动化插件 +description: 为部署、监控和故障处理提供自动化工作流 +tags: plugins, devops, automation +--- + +# DevOps 自动化插件 + +完整的 DevOps 自动化工作流，覆盖部署、监控和事故响应。 + +## 功能 + +✅ 自动化部署 +✅ 回滚流程 +✅ 系统健康监控 +✅ 事故响应工作流 +✅ Kubernetes 集成 + +## 安装 + +```bash +/plugin install devops-automation +``` + +## 包含内容 + +### Slash 命令 +- `/deploy` - 部署到生产或预发环境 +- `/rollback` - 回滚到上一个版本 +- `/status` - 检查系统健康 +- `/incident` - 处理生产事故 + +### 子 agents +- `deployment-specialist` - 部署操作 +- `incident-commander` - 事故协调 +- `alert-analyzer` - 系统健康分析 + +### MCP 服务器 +- Kubernetes 集成 + +### 脚本 +- `deploy.sh` - 部署自动化 +- `rollback.sh` - 回滚自动化 +- `health-check.sh` - 健康检查工具 + +### Hooks +- `pre-deploy.js` - 部署前验证 +- `post-deploy.js` - 部署后任务 + +## 使用 + +### 部署到预发环境 + +``` +/deploy staging +``` + +### 部署到生产环境 + +``` +/deploy production +``` + +### 回滚 + +``` +/rollback production +``` + +### 检查状态 + +``` +/status +``` + +### 处理事故 + +``` +/incident +``` + +## 要求 + +- Claude Code 1.0+ +- Kubernetes CLI（kubectl） +- 已配置集群访问 + +## 配置 + +设置 Kubernetes 配置： + +```bash +export KUBECONFIG=~/.kube/config +``` + +## 示例工作流 + +``` +用户：/deploy production + +Claude: +1. 运行 pre-deploy hook（验证 kubectl 和集群连接） +2. 将部署委派给 deployment-specialist subagent +3. 运行 deploy.sh 脚本 +4. 通过 Kubernetes MCP 监控部署进度 +5. 运行 post-deploy hook（等待 pods 就绪，执行 smoke tests） +6. 提供部署总结 + +结果： +✅ 部署完成 +📦 版本：v2.1.0 +🚀 Pods：3/3 已就绪 +⏱️ 用时：2m 34s +``` diff --git a/zh/07-plugins/devops-automation/agents/alert-analyzer.md b/zh/07-plugins/devops-automation/agents/alert-analyzer.md new file mode 100644 index 0000000..647094d --- /dev/null +++ b/zh/07-plugins/devops-automation/agents/alert-analyzer.md @@ -0,0 +1,14 @@ +--- +name: alert-analyzer +description: 分析监控告警和系统指标 +tools: read, grep, bash +--- + +# 告警分析器 + +分析系统健康状况和告警： +- 告警关联分析 +- 趋势分析 +- 根因识别 +- 指标可视化 +- 主动问题检测 diff --git a/zh/07-plugins/devops-automation/agents/deployment-specialist.md b/zh/07-plugins/devops-automation/agents/deployment-specialist.md new file mode 100644 index 0000000..4b5f116 --- /dev/null +++ b/zh/07-plugins/devops-automation/agents/deployment-specialist.md @@ -0,0 +1,14 @@ +--- +name: deployment-specialist +description: 处理所有部署操作 +tools: read, write, bash, grep +--- + +# 部署专家 + +部署运维专家： +- 蓝绿部署 +- 金丝雀发布 +- 回滚流程 +- 健康检查 +- 数据库迁移 diff --git a/zh/07-plugins/devops-automation/agents/incident-commander.md b/zh/07-plugins/devops-automation/agents/incident-commander.md new file mode 100644 index 0000000..a749580 --- /dev/null +++ b/zh/07-plugins/devops-automation/agents/incident-commander.md @@ -0,0 +1,14 @@ +--- +name: incident-commander +description: 协调事故响应 +tools: read, write, bash, grep +--- + +# 事故指挥官 + +管理事故响应： +- 严重性评估 +- 团队协调 +- 状态更新 +- 解决跟踪 +- 事后复盘推动 diff --git a/zh/07-plugins/devops-automation/commands/deploy.md b/zh/07-plugins/devops-automation/commands/deploy.md new file mode 100644 index 0000000..7c15d6f --- /dev/null +++ b/zh/07-plugins/devops-automation/commands/deploy.md @@ -0,0 +1,15 @@ +--- +name: Deploy +description: 将应用部署到生产或预发环境 +--- + +# 应用部署 + +执行部署工作流： + +1. 运行部署前检查 +2. 构建应用 +3. 运行测试 +4. 部署到目标环境 +5. 运行健康检查 +6. 在 Slack 上通知团队 diff --git a/zh/07-plugins/devops-automation/commands/incident.md b/zh/07-plugins/devops-automation/commands/incident.md new file mode 100644 index 0000000..708c76e --- /dev/null +++ b/zh/07-plugins/devops-automation/commands/incident.md @@ -0,0 +1,16 @@ +--- +name: Incident Response +description: 使用结构化响应流程处理生产事故 +--- + +# 事故响应 + +结构化事故响应工作流： + +1. 创建事故记录 +2. 评估严重性和影响 +3. 通知值班团队 +4. 收集诊断信息 +5. 协调响应工作 +6. 记录解决方案 +7. 安排事后复盘 diff --git a/zh/07-plugins/devops-automation/commands/rollback.md b/zh/07-plugins/devops-automation/commands/rollback.md new file mode 100644 index 0000000..aa71b17 --- /dev/null +++ b/zh/07-plugins/devops-automation/commands/rollback.md @@ -0,0 +1,14 @@ +--- +name: Rollback +description: 回滚到上一次部署 +--- + +# 回滚部署 + +回滚到之前的稳定版本： + +1. 确认上一次部署 +2. 验证回滚目标健康状态 +3. 执行回滚流程 +4. 运行健康检查 +5. 通知团队 diff --git a/zh/07-plugins/devops-automation/commands/status.md b/zh/07-plugins/devops-automation/commands/status.md new file mode 100644 index 0000000..df472c0 --- /dev/null +++ b/zh/07-plugins/devops-automation/commands/status.md @@ -0,0 +1,15 @@ +--- +name: System Status +description: 检查整体系统健康状况 +--- + +# 系统状态检查 + +检查所有服务的系统健康状况： + +1. 查询 Kubernetes pod 状态 +2. 检查数据库连接 +3. 监控 API 响应时间 +4. 查看错误率 +5. 检查资源利用率 +6. 报告整体健康状况 diff --git a/zh/07-plugins/documentation/README.md b/zh/07-plugins/documentation/README.md new file mode 100644 index 0000000..670d7ec --- /dev/null +++ b/zh/07-plugins/documentation/README.md @@ -0,0 +1,127 @@ +--- +name: 文档生成插件 +description: 为文档编写、同步和校验提供完整工作流 +tags: plugins, documentation, automation +--- + +# 文档生成插件 + +这个插件把文档相关的命令、subagents、模板和 MCP 服务器打包在一起，帮助你生成、同步和校验文档。 + +## 特性 + +✅ 生成 API 文档 +✅ 创建和更新 README +✅ 同步文档 +✅ 改进代码注释 +✅ 生成示例 + +## 包含内容 + +### 命令 +- [commands/generate-api-docs.md](commands/generate-api-docs.md) - 生成 API 文档 +- [commands/generate-readme.md](commands/generate-readme.md) - 生成 README +- [commands/sync-docs.md](commands/sync-docs.md) - 同步文档 +- [commands/validate-docs.md](commands/validate-docs.md) - 校验文档 + +### Subagents +- [agents/api-documenter.md](agents/api-documenter.md) - API 文档 subagent +- [agents/code-commentator.md](agents/code-commentator.md) - 代码注释 subagent +- [agents/example-generator.md](agents/example-generator.md) - 示例生成 subagent + +### 模板 +- [templates/adr-template.md](templates/adr-template.md) - ADR 模板 +- [templates/api-endpoint.md](templates/api-endpoint.md) - API 端点模板 +- [templates/function-docs.md](templates/function-docs.md) - 函数文档模板 + +### MCP 服务器 +- GitHub 集成 - 用于文档同步 + +## 安装 + +```bash +/plugin install documentation +``` + +## 使用方式 + +### 生成 API 文档 +```bash +/generate-api-docs +``` + +### 创建 README +```bash +/generate-readme +``` + +### 同步文档 +```bash +/sync-docs +``` + +### 校验文档 +```bash +/validate-docs +``` + +## 适用场景 + +- 想标准化项目文档产出 +- 想自动生成 README、API 文档和示例 +- 想同步多个文档之间的一致性 +- 想维护代码注释和示例质量 + +## 需求 + +- Claude Code 1.0+ +- GitHub 访问权限（可选） + +## 示例工作流 + +```text +用户：/generate-api-docs + +Claude： +1. 扫描 /src/api/ 下的所有 API 端点 +2. 委派给 api-documenter subagent +3. 提取函数签名和 JSDoc +4. 按模块 / 端点组织内容 +5. 使用 api-endpoint.md 模板 +6. 生成完整的 Markdown 文档 +7. 包含 curl、JavaScript 和 Python 示例 + +结果： +✅ API 文档已生成 +📄 已创建文件： + - docs/api/users.md + - docs/api/auth.md + - docs/api/products.md +📊 覆盖率：23/23 个端点已文档化 +``` + +## 模板用途 + +### API 端点模板 +用于编写带完整示例的 REST API 文档。 + +### 函数文档模板 +用于编写单个函数或方法的说明文档。 + +### ADR 模板 +用于记录架构决策。 + +## 配置 + +为文档同步设置 GitHub token： +```bash +export GITHUB_TOKEN="your_github_token" +``` + +## 最佳实践 + +- 文档尽量贴近代码 +- 随着代码变化同步更新文档 +- 提供可直接执行的示例 +- 定期校验文档有效性 +- 使用模板保持一致性 diff --git a/zh/07-plugins/documentation/agents/api-documenter.md b/zh/07-plugins/documentation/agents/api-documenter.md new file mode 100644 index 0000000..40343de --- /dev/null +++ b/zh/07-plugins/documentation/agents/api-documenter.md @@ -0,0 +1,14 @@ +--- +name: api-documenter +description: API 文档专家 +tools: read, write, grep +--- + +# API 文档专家 + +创建全面的 API 文档： +- 端点文档 +- 参数说明 +- 响应 schema +- 代码示例（curl、JavaScript、Python） +- 错误代码 diff --git a/zh/07-plugins/documentation/agents/code-commentator.md b/zh/07-plugins/documentation/agents/code-commentator.md new file mode 100644 index 0000000..8b0d9f2 --- /dev/null +++ b/zh/07-plugins/documentation/agents/code-commentator.md @@ -0,0 +1,14 @@ +--- +name: code-commentator +description: 代码注释与内联文档专家 +tools: read, write, edit +--- + +# 代码注释专家 + +改进代码文档： +- JSDoc / docstring 注释 +- 内联说明 +- 参数说明 +- 返回类型文档 +- 使用示例 diff --git a/zh/07-plugins/documentation/agents/example-generator.md b/zh/07-plugins/documentation/agents/example-generator.md new file mode 100644 index 0000000..abbc01c --- /dev/null +++ b/zh/07-plugins/documentation/agents/example-generator.md @@ -0,0 +1,14 @@ +--- +name: example-generator +description: 代码示例与教程专家 +tools: read, write +--- + +# 示例生成专家 + +创建实用的代码示例： +- 入门指南 +- 常见用例 +- 集成示例 +- 最佳实践 +- 故障排查场景 diff --git a/zh/07-plugins/documentation/commands/generate-api-docs.md b/zh/07-plugins/documentation/commands/generate-api-docs.md new file mode 100644 index 0000000..5f2182c --- /dev/null +++ b/zh/07-plugins/documentation/commands/generate-api-docs.md @@ -0,0 +1,15 @@ +--- +name: 生成 API 文档 +description: 从源代码生成完整的 API 文档 +--- + +# API 文档生成器 + +生成完整的 API 文档： + +1. 扫描 API 端点 +2. 提取函数签名和 JSDoc +3. 按模块 / 端点组织内容 +4. 创建带示例的 Markdown +5. 包含请求 / 响应 schema +6. 添加错误文档 diff --git a/zh/07-plugins/documentation/commands/generate-readme.md b/zh/07-plugins/documentation/commands/generate-readme.md new file mode 100644 index 0000000..cfaf328 --- /dev/null +++ b/zh/07-plugins/documentation/commands/generate-readme.md @@ -0,0 +1,15 @@ +--- +name: 生成 README +description: 创建或更新项目 README +--- + +# README 生成器 + +生成完整的 README： + +1. 项目概览与简介 +2. 安装说明 +3. 使用示例 +4. API 文档链接 +5. 贡献指南 +6. 许可证信息 diff --git a/zh/07-plugins/documentation/commands/sync-docs.md b/zh/07-plugins/documentation/commands/sync-docs.md new file mode 100644 index 0000000..997968a --- /dev/null +++ b/zh/07-plugins/documentation/commands/sync-docs.md @@ -0,0 +1,14 @@ +--- +name: 同步文档 +description: 将文档与代码变更保持同步 +--- + +# 文档同步 + +同步文档与代码库： + +1. 检测代码变更 +2. 找出过时文档 +3. 更新受影响的文档 +4. 验证示例是否仍然可用 +5. 更新版本号 diff --git a/zh/07-plugins/documentation/commands/validate-docs.md b/zh/07-plugins/documentation/commands/validate-docs.md new file mode 100644 index 0000000..36bf825 --- /dev/null +++ b/zh/07-plugins/documentation/commands/validate-docs.md @@ -0,0 +1,14 @@ +--- +name: 校验文档 +description: 校验文档的完整性与准确性 +--- + +# 文档校验 + +校验文档质量： + +1. 检查是否有损坏链接 +2. 验证代码示例 +3. 确保内容完整 +4. 检查格式 +5. 对照实际代码进行校验 diff --git a/zh/07-plugins/documentation/templates/adr-template.md b/zh/07-plugins/documentation/templates/adr-template.md new file mode 100644 index 0000000..8a23f01 --- /dev/null +++ b/zh/07-plugins/documentation/templates/adr-template.md @@ -0,0 +1,39 @@ +# ADR [编号]：[标题] + +## 状态 +[提议中 | 已接受 | 已弃用 | 已被替代] + +## 背景 +我们正在看到的是什么问题，促使我们做出这个决策或变更？ + +## 决策 +我们提出和/或正在执行的变更是什么？ + +## 影响 +由于这项变更，哪些事情变得更容易或更困难？ + +### 正面影响 +- 收益 1 +- 收益 2 + +### 负面影响 +- 代价 1 +- 代价 2 + +### 中性影响 +- 参考事项 1 +- 参考事项 2 + +## 备选方案 +还考虑过哪些其他选项，以及为什么没有选择它们？ + +### 备选方案 1 +描述以及未选择的原因。 + +### 备选方案 2 +描述以及未选择的原因。 + +## 参考资料 +- 相关 ADR +- 外部文档 +- 讨论链接 diff --git a/zh/07-plugins/documentation/templates/api-endpoint.md b/zh/07-plugins/documentation/templates/api-endpoint.md new file mode 100644 index 0000000..cd710a3 --- /dev/null +++ b/zh/07-plugins/documentation/templates/api-endpoint.md @@ -0,0 +1,101 @@ +# [方法] /api/v1/[endpoint] + +## 描述 +简要说明这个端点的作用。 + +## 身份验证 +所需的身份验证方式，例如 Bearer token。 + +## 参数 + +### 路径参数 +| 名称 | 类型 | 必填 | 描述 | +|------|------|------|------| +| id | string | 是 | 资源 ID | + +### 查询参数 +| 名称 | 类型 | 必填 | 描述 | +|------|------|------|------| +| page | integer | 否 | 页码（默认：1） | +| limit | integer | 否 | 每页条数（默认：20） | + +### 请求体 +```json +{ + "field": "value" +} +``` + +## 响应 + +### 200 OK +```json +{ + "success": true, + "data": { + "id": "123", + "name": "示例" + } +} +``` + +### 400 Bad Request +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "无效输入" + } +} +``` + +### 404 Not Found +```json +{ + "success": false, + "error": { + "code": "NOT_FOUND", + "message": "资源未找到" + } +} +``` + +## 示例 + +### cURL +```bash +curl -X GET "https://api.example.com/api/v1/endpoint" \ + -H "Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" +``` + +### JavaScript +```javascript +const response = await fetch('/api/v1/endpoint', { + headers: { + 'Authorization': 'Bearer token', + 'Content-Type': 'application/json' + } +}); +const data = await response.json(); +``` + +### Python +```python +import requests + +response = requests.get( + 'https://api.example.com/api/v1/endpoint', + headers={'Authorization': 'Bearer token'} +) +data = response.json() +``` + +## 限流 +- 已认证用户每小时 1000 次请求 +- 公开端点每小时 100 次请求 + +## 相关端点 +- [GET /api/v1/related](#) +- [POST /api/v1/related](#) diff --git a/zh/07-plugins/documentation/templates/function-docs.md b/zh/07-plugins/documentation/templates/function-docs.md new file mode 100644 index 0000000..b93c6dc --- /dev/null +++ b/zh/07-plugins/documentation/templates/function-docs.md @@ -0,0 +1,50 @@ +# 函数：`functionName` + +## 描述 +简要说明这个函数的作用。 + +## 签名 +```typescript +function functionName(param1: Type1, param2: Type2): ReturnType +``` + +## 参数 + +| 参数 | 类型 | 必填 | 描述 | +|------|------|------|------| +| param1 | Type1 | 是 | param1 的说明 | +| param2 | Type2 | 否 | param2 的说明 | + +## 返回值 +**类型**：`ReturnType` + +返回内容的说明。 + +## 抛出异常 +- `Error`：在输入无效时抛出 +- `TypeError`：在传入错误类型时抛出 + +## 示例 + +### 基本用法 +```typescript +const result = functionName('value1', 'value2'); +console.log(result); +``` + +### 高级用法 +```typescript +const result = functionName( + complexParam1, + { option: true } +); +``` + +## 备注 +- 其他说明或警告 +- 性能注意事项 +- 最佳实践 + +## 另请参阅 +- [相关函数](#) +- [API 文档](#) diff --git a/zh/07-plugins/pr-review/README.md b/zh/07-plugins/pr-review/README.md new file mode 100644 index 0000000..b60dcc1 --- /dev/null +++ b/zh/07-plugins/pr-review/README.md @@ -0,0 +1,96 @@ +--- +name: PR 审查插件 +description: 为 Pull Request 提供完整的代码审查工作流 +tags: plugins, code-review, pull-request +--- + +# PR 审查插件 + +完整的 PR 审查工作流，包含安全、测试和文档检查。 + +## 功能 + +✅ 安全分析 +✅ 测试覆盖率检查 +✅ 文档校验 +✅ 代码质量评估 +✅ 性能影响分析 + +## 安装 + +```bash +/plugin install pr-review +``` + +## 包含内容 + +### Slash 命令 +- `/review-pr` - 全面 PR 审查 +- `/check-security` - 面向安全的审查 +- `/check-tests` - 测试覆盖率分析 + +### 子 agents +- `security-reviewer` - 安全漏洞检测 +- `test-checker` - 测试覆盖率分析 +- `performance-analyzer` - 性能影响评估 + +### MCP 服务器 +- 用于 PR 数据的 GitHub 集成 + +### Hooks +- `pre-review.js` - 审查前验证 + +## 使用 + +### 基础 PR 审查 + +``` +/review-pr +``` + +### 仅安全检查 + +``` +/check-security +``` + +### 仅测试覆盖率检查 + +``` +/check-tests +``` + +## 要求 + +- Claude Code 1.0+ +- GitHub 访问权限 +- Git 仓库 + +## 配置 + +设置 GitHub token： + +```bash +export GITHUB_TOKEN="your_github_token" +``` + +## 示例工作流 + +``` +用户：/review-pr + +Claude: +1. 运行 pre-review hook（验证 git 仓库） +2. 通过 GitHub MCP 获取 PR 数据 +3. 将安全审查委派给 security-reviewer subagent +4. 将测试分析委派给 test-checker subagent +5. 将性能分析委派给 performance-analyzer subagent +6. 汇总所有发现 +7. 提供完整审查报告 + +结果： +✅ 安全：未发现关键问题 +⚠️ 测试：覆盖率为 65%，建议达到 80%+ +✅ 性能：没有明显影响 +📝 建议：为边界情况添加测试 +``` diff --git a/zh/07-plugins/pr-review/agents/performance-analyzer.md b/zh/07-plugins/pr-review/agents/performance-analyzer.md new file mode 100644 index 0000000..5eaccb3 --- /dev/null +++ b/zh/07-plugins/pr-review/agents/performance-analyzer.md @@ -0,0 +1,13 @@ +--- +name: performance-analyzer +description: 性能影响分析 +tools: read, grep, bash +--- + +# 性能分析器 + +评估变更对性能的影响： +- 算法复杂度 +- 数据库查询效率 +- 内存使用 +- 缓存机会 diff --git a/zh/07-plugins/pr-review/agents/security-reviewer.md b/zh/07-plugins/pr-review/agents/security-reviewer.md new file mode 100644 index 0000000..e325ad0 --- /dev/null +++ b/zh/07-plugins/pr-review/agents/security-reviewer.md @@ -0,0 +1,13 @@ +--- +name: security-reviewer +description: 面向安全的代码审查 +tools: read, grep, diff +--- + +# 安全审查员 + +专注于发现安全漏洞： +- 身份验证/授权问题 +- 数据暴露 +- 注入攻击 +- 安全配置 diff --git a/zh/07-plugins/pr-review/agents/test-checker.md b/zh/07-plugins/pr-review/agents/test-checker.md new file mode 100644 index 0000000..6344b83 --- /dev/null +++ b/zh/07-plugins/pr-review/agents/test-checker.md @@ -0,0 +1,13 @@ +--- +name: test-checker +description: 测试覆盖率与质量分析 +tools: read, bash, grep +--- + +# 测试检查器 + +分析测试覆盖率和质量： +- 覆盖率百分比 +- 缺失的测试用例 +- 测试质量评估 +- 边界情况识别 diff --git a/zh/07-plugins/pr-review/commands/check-security.md b/zh/07-plugins/pr-review/commands/check-security.md new file mode 100644 index 0000000..a527d87 --- /dev/null +++ b/zh/07-plugins/pr-review/commands/check-security.md @@ -0,0 +1,14 @@ +--- +name: Security Check +description: 运行安全导向的代码审查 +--- + +# 安全检查 + +对代码变更执行聚焦式安全分析： + +1. 身份验证/授权检查 +2. 数据暴露风险 +3. 注入漏洞 +4. 密码学弱点 +5. 日志中的敏感数据 diff --git a/zh/07-plugins/pr-review/commands/check-tests.md b/zh/07-plugins/pr-review/commands/check-tests.md new file mode 100644 index 0000000..581ecbd --- /dev/null +++ b/zh/07-plugins/pr-review/commands/check-tests.md @@ -0,0 +1,14 @@ +--- +name: Test Coverage Check +description: 验证测试覆盖率和质量 +--- + +# 测试覆盖检查 + +分析测试覆盖率和质量： + +1. 检查测试覆盖率百分比 +2. 识别未测试的代码路径 +3. 审查测试质量 +4. 建议缺失的测试用例 +5. 确认边界情况已覆盖 diff --git a/zh/07-plugins/pr-review/commands/review-pr.md b/zh/07-plugins/pr-review/commands/review-pr.md new file mode 100644 index 0000000..cbf8198 --- /dev/null +++ b/zh/07-plugins/pr-review/commands/review-pr.md @@ -0,0 +1,14 @@ +--- +name: Review PR +description: 启动包含安全与测试检查的完整 PR 审查 +--- + +# PR 审查 + +这个命令会发起一次完整的 Pull Request 审查，包括： + +1. 安全分析 +2. 测试覆盖率验证 +3. 文档更新 +4. 代码质量检查 +5. 性能影响评估 diff --git a/zh/08-checkpoints/README.md b/zh/08-checkpoints/README.md new file mode 100644 index 0000000..1740625 --- /dev/null +++ b/zh/08-checkpoints/README.md @@ -0,0 +1,292 @@ + + + Claude How To + + +# Checkpoints 与 Rewind + +Checkpoints 可以让你保存对话状态，并在 Claude Code 会话中回退到之前的时间点。无论你是在探索不同方案、修复错误，还是比较多个实现路径，这个能力都非常有用。 + +## 概览 + +Checkpoints 会保存会话状态，让你可以安全地试验和探索多种方案。它们本质上是当前对话状态的快照，包含： +- 所有已交换的消息 +- 已做出的文件修改 +- 工具使用历史 +- 当前会话上下文 + +当你在尝试不同实现方式、从错误中恢复，或比较替代方案时，这个功能尤其好用。 + +## 核心概念 + +| 概念 | 说明 | +|---------|-------------| +| **Checkpoint** | 保存消息、文件和上下文的对话快照 | +| **Rewind** | 回到之前的 checkpoint，并丢弃之后的更改 | +| **Branch Point** | 从同一个 checkpoint 出发，探索多个方案 | + +## 访问 Checkpoints + +你可以通过两种主要方式访问和管理 checkpoints： + +### 使用键盘快捷键 + +按两次 `Esc`（`Esc` + `Esc`）打开 checkpoint 界面并浏览已保存的 checkpoints。 + +### 使用 Slash Command + +使用 `/rewind` 命令（别名：`/checkpoint`）快速进入： + +```bash +# 打开 rewind 界面 +/rewind + +# 或者使用别名 +/checkpoint +``` + +## Rewind 选项 + +回退时，你会看到一个包含五个选项的菜单： + +1. **恢复代码和对话** - 把文件和消息都恢复到那个 checkpoint +2. **恢复对话** - 只回退消息，保留当前代码不变 +3. **恢复代码** - 只回退文件修改，保留完整对话历史 +4. **从这里开始总结** - 把从这里往后的对话压缩成 AI 生成的摘要，而不是直接丢弃。原始消息仍会保留在记录中。你也可以额外指定摘要应聚焦哪些主题。 +5. **算了** - 取消并返回当前状态 + +## 自动 Checkpoints + +Claude Code 会自动为你创建 checkpoints： + +- **每次用户提示** - 每次用户输入都会创建一个新 checkpoint +- **持久保存** - checkpoints 会跨会话保留 +- **自动清理** - 30 天后自动清理旧 checkpoints + +这意味着你随时都可以回到之前的任意节点，从几分钟前到几天前都可以。 + +## 使用场景 + +| 场景 | 工作流 | +|----------|----------| +| **探索不同方案** | 保存 → 试方案 A → 保存 → Rewind → 试方案 B → 比较 | +| **安全重构** | 保存 → 重构 → 测试 → 如果失败：Rewind | +| **A/B 测试** | 保存 → 设计 A → 保存 → Rewind → 设计 B → 比较 | +| **错误恢复** | 发现问题 → Rewind 到最后一个正常状态 | + +## 如何使用 Checkpoints + +### 查看和回退 + +按两次 `Esc`，或者使用 `/rewind` 打开 checkpoint 浏览器。你会看到一个带时间戳的可用 checkpoint 列表。选择任意一个 checkpoint，即可回退到该状态。 + +### Checkpoint 详情 + +每个 checkpoint 会显示： +- 创建时间 +- 被修改的文件 +- 对话中的消息数量 +- 使用过的工具 + +## 实战示例 + +更多可直接参考的中文示例见 [checkpoint-examples.md](checkpoint-examples.md)。 + +### 示例 1：探索不同方案 + +```text +User: 我们给 API 加一个缓存层吧 + +Claude: 我会为你的 API 端点添加 Redis 缓存…… +[在 checkpoint A 处做出修改] + +User: 其实我们先试试内存缓存 + +Claude: 我会 rewind 回去，探索另一种方案…… +[用户按下 Esc+Esc 并回退到 checkpoint A] +[在 checkpoint B 处实现内存缓存] + +User: 现在我可以比较两种方案了 +``` + +### 示例 2：从错误中恢复 + +```text +User: 把认证模块重构成 JWT + +Claude: 我会重构认证模块…… +[做出大量修改] + +User: 等等，这把 OAuth 集成弄坏了。我们回去。 + +Claude: 我来帮你回退到重构之前…… +[用户按下 Esc+Esc，并选择重构前的 checkpoint] + +User: 这次我们试一个更保守的方案 +``` + +### 示例 3：安全试验 + +```text +User: 我们试着把它改写成函数式风格 +[在实验前创建 checkpoint] + +Claude: [执行实验性修改] + +User: 测试失败了。我们回退吧。 +[用户按下 Esc+Esc 并回退到 checkpoint] + +Claude: 我已经回退这些更改了。我们试另一个方案。 +``` + +### 示例 4：分支式探索 + +```text +User: 我想比较两种数据库设计 +[记下 checkpoint，命名为 "Start"] + +Claude: 我先实现第一种设计…… +[实现 Schema A] + +User: 现在让我回去试第二种方案 +[用户按下 Esc+Esc 并回退到 "Start"] + +Claude: 现在我实现 Schema B…… +[实现 Schema B] + +User: 太好了，我现在有两个 schema 可以选择 +``` + +## Checkpoint 保留策略 + +Claude Code 会自动管理你的 checkpoints： + +- 每次用户输入都会自动创建 checkpoint +- 旧 checkpoint 最多保留 30 天 +- 系统会自动清理，避免存储无限增长 + +## 工作流模式 + +### 探索时的分支策略 + +当你在探索多个方案时： + +```text +1. 从初始实现开始 → Checkpoint A +2. 尝试方案 1 → Checkpoint B +3. 回退到 Checkpoint A +4. 尝试方案 2 → Checkpoint C +5. 比较 B 和 C 的结果 +6. 选择最佳方案并继续 +``` + +### 安全重构模式 + +当你在做大改动时： + +```text +1. 当前状态 → Checkpoint（自动） +2. 开始重构 +3. 运行测试 +4. 如果测试通过 → 继续 +5. 如果测试失败 → Rewind 并尝试别的方案 +``` + +## 最佳实践 + +因为 checkpoints 是自动创建的，所以你可以专注于工作，而不用担心手动保存状态。不过，下面这些习惯仍然很重要： + +### 如何高效使用 Checkpoints + +✅ **应该做：** +- 回退前先看清楚可用的 checkpoints +- 当你想尝试不同方向时使用 rewind +- 保留 checkpoints 方便比较不同方案 +- 理解每个 rewind 选项的作用（恢复代码和对话、恢复对话、恢复代码、或总结） + +❌ **不要做：** +- 只依赖 checkpoints 来保存代码 +- 指望 checkpoints 跟踪外部文件系统变化 +- 把 checkpoints 当成 git commit 的替代品 + +## 配置 + +你可以在设置中开启或关闭自动 checkpoints： + +```json +{ + "autoCheckpoint": true +} +``` + +- `autoCheckpoint`：是否在每次用户提示后自动创建 checkpoint（默认：`true`） + +## 局限性 + +Checkpoints 很适合会话级回退，但它不是版本控制系统。对于需要长期保存、可审计、可共享的改动，仍然应该使用 git。 + +## 故障排查 + +### 找不到 Checkpoints + +- 检查你是否在支持该功能的 Claude Code 版本中 +- 确认自动 checkpoint 没有被关闭 +- 重新打开会话再试一次 + +### Rewind 失败 + +- 确认你选择了一个有效的 checkpoint +- 查看是否存在与文件系统或权限相关的限制 +- 尝试先分别恢复代码或对话，再决定是否同时恢复两者 + +## 与 Git 的集成 + +Checkpoints 和 git 是互补关系： + +- Checkpoints 用于会话内探索和安全试验 +- Git 用于永久保存代码历史 +- 你可以先用 checkpoints 快速试错，再把最终方案提交到 git + +## 快速开始 + +### 基本工作流 + +```text +1. 开始修改前自动创建 checkpoint +2. 尝试某个方案 +3. 如果结果不理想，按 Esc 两次 +4. 选择合适的 rewind 选项 +5. 继续探索或提交最终方案 +``` + +### 键盘快捷键 + +- `Esc` + `Esc`：打开 checkpoint 浏览器 +- `/rewind`：通过命令进入回退界面 +- `/checkpoint`：`/rewind` 的别名 + +## 什么时候该 rewind：上下文监控 + +如果你发现这些信号，通常就该回退了： + +- 当前方案开始变复杂，而且你还没确定方向 +- 测试刚失败，问题可能就是最近一两步引入的 +- 你想比较两种实现方式 +- 你想保留一个“干净起点”继续探索 + +## 相关概念 + +- **Memory**：跨会话的长期上下文，见 [02-memory/README.md](../02-memory/README.md) +- **Hooks**：事件驱动自动化，见 [06-hooks/README.md](../06-hooks/README.md) +- **Plugins**：打包功能集合，见 [07-plugins/README.md](../07-plugins/README.md) +- **Advanced Features**：包括 planning mode 和背景任务，见 [09-advanced-features/README.md](../09-advanced-features/README.md) + +## 更多资源 + +- [根目录中文指南](../README.md) +- [Claude Code 官方检查点文档](https://code.claude.com/docs/en/checkpointing) +- [Claude Code 高级功能指南](../09-advanced-features/README.md) + +## 总结 + +Checkpoints 的价值在于让你敢于试错。它让“先试再说”和“试错后立刻回退”变得安全，从而帮你更快找到正确方案。 diff --git a/zh/08-checkpoints/checkpoint-examples.md b/zh/08-checkpoints/checkpoint-examples.md new file mode 100644 index 0000000..9e06caf --- /dev/null +++ b/zh/08-checkpoints/checkpoint-examples.md @@ -0,0 +1,339 @@ +# 检查点示例 + +以下是一些在 Claude Code 中有效使用检查点的真实示例。 + +注意：每次用户提示都会自动创建检查点。你不需要手动保存。要回退，请连续按两次 `Esc`（`Esc+Esc`），或者使用 `/rewind` 打开检查点浏览器。 + +## 示例 1：数据库迁移 + +### 场景 +你需要从 MySQL 迁移到 PostgreSQL，但想同时探索直接迁移和渐进式双写两种方案。 + +### 工作流程 + +``` +用户：我们来实现一个从 MySQL 到 PostgreSQL 的直接迁移方案 + [检查点 A 自动创建] + +Claude：我来实现直接迁移…… +[更换数据库驱动、更新查询、修改 schema] + +用户：运行测试 + [检查点 B 自动创建] + +Claude：正在运行测试…… +❌ 15 个测试失败 - 连接池问题 + +用户：这个方案有问题。我们改试双写模式。 +[用户按下 Esc+Esc，选择检查点 A，选择“恢复代码和对话”] + +用户：现在实现双写模式，同时向两个数据库写入 + +Claude：我来实现双写迁移…… +[实现双写层、渐进式迁移策略] + +用户：运行测试 + +Claude：正在运行测试…… +✅ 所有测试通过 + +用户：双写方案明显更稳妥。我们提交这个版本。 +``` + +## 示例 2：性能优化 + +### 场景 +尝试多种性能优化策略。 + +### 工作流程 + +``` +用户：我们来优化 API 响应时间。当前：450ms + [检查点“Baseline”自动创建] + +Claude：我来加数据库查询缓存…… +[实现 Redis 缓存] + +用户：运行性能测试 + +Claude：结果：平均响应时间 280ms（提升 38%） + +用户：我想试试另一种方法。 +[用户按下 Esc+Esc，选择“Baseline”检查点，选择“恢复代码和对话”] + +用户：改试数据库查询优化 + +Claude：我来优化数据库查询…… +[添加索引，优化 N+1 查询] + +用户：运行性能测试 + +Claude：结果：平均响应时间 180ms（提升 60%） + +用户：我也想试第三种方法。 +[用户按下 Esc+Esc，选择“Baseline”检查点，选择“恢复代码和对话”] + +用户：尝试响应压缩和 CDN + +Claude：我来添加压缩和 CDN…… +[实现 gzip，配置 CDN] + +用户：运行性能测试 + +Claude：结果：平均响应时间 320ms（提升 29%） + +用户：查询优化最好。让我回到那个版本，再和缓存结合起来。 +[用户按下 Esc+Esc，选择查询优化后的检查点，选择“恢复代码和对话”] + +用户：现在在这些优化后的查询之上再加上 Redis 缓存 + +Claude：[在优化后的查询之上添加 Redis 缓存] + +用户：运行性能测试 + +Claude：结果：平均响应时间 95ms（提升 79%）🎉 + +用户：完美！这就是最终方案。我们提交它。 +``` + +## 示例 3：UI/UX 迭代 + +### 场景 +为仪表板尝试不同布局。 + +### 工作流程 + +``` +用户：我们来把仪表板重设计成侧边栏布局 + [检查点“Start”自动创建] + +Claude：[实现侧边栏布局] + +用户：给我看一张截图 + +Claude：[显示截图] + +用户：侧边栏太拥挤了。我们试试顶部导航吧。 +[用户按下 Esc+Esc，选择“Start”检查点，选择“恢复代码和对话”] + +用户：试试顶部导航布局 + +Claude：[实现顶部导航] + +用户：给我看一张截图 + +Claude：[显示截图] + +用户：好多了，不过我们再试试卡片式网格布局。 +[用户按下 Esc+Esc，选择“Start”检查点，选择“恢复代码和对话”] + +用户：试试卡片式网格布局 + +Claude：[实现卡片网格] + +用户：给我看一张截图 + +Claude：[显示截图] + +用户：这个很不错！不过我们能把顶部导航和卡片网格结合起来吗？ +[用户按下 Esc+Esc，选择卡片网格后的检查点，选择“恢复代码和对话”] + +用户：给卡片网格布局加上顶部导航 + +Claude：[在卡片网格上添加顶部导航] + +用户：完美！这就是最终设计。 +``` + +## 示例 4：调试会话 + +### 场景 +用多个假设排查一个难缠的 bug。 + +### 工作流程 + +``` +用户：应用里有内存泄漏 + [检查点“Before debugging”自动创建] + +Claude：让我来调查…… +[分析代码] + +用户：我觉得问题在事件监听器里。我们先修这个。 + +Claude：[修复事件监听器清理逻辑] + +用户：运行内存分析器 + +Claude：仍然在泄漏内存 - 事件监听器不是问题所在 + +用户：让我回到之前，换个思路试试。 +[用户按下 Esc+Esc，选择“Before debugging”检查点，选择“恢复代码和对话”] + +用户：也许是数据库连接的问题？ + +Claude：[实现连接池修复] + +用户：运行内存分析器 + +Claude：还是在泄漏 - 也不是连接的问题 + +用户：我再回去，换另一个方向试试。 +[用户按下 Esc+Esc，选择“Before debugging”检查点，选择“恢复代码和对话”] + +用户：我们检查一下有没有循环引用 + +Claude：[找到并修复缓存中的循环引用] + +用户：运行内存分析器 + +Claude：✅ 内存泄漏修复了！缓存层里的循环引用就是罪魁祸首。 + +用户：太好了！我们提交这个修复。 +``` + +## 示例 5：API 设计演进 + +### 场景 +为 REST API 设计做多轮迭代。 + +### 工作流程 + +``` +用户：给我们的博客平台创建一个 REST API + [检查点“Before API design”自动创建] + +Claude：[创建基础 CRUD API] + +用户：这个太简单了。加上分页和过滤 + +Claude：[添加分页和过滤] + +用户：我们需要更好的资源关系 + +Claude：[实现 HATEOAS 链接] + +用户：其实我们改用 GraphQL，不用 REST 了 +[用户按下 Esc+Esc，选择“Before API design”检查点，选择“恢复代码和对话”] + +用户：那就为我们的博客平台改实现 GraphQL API 吧 + +Claude：[实现 GraphQL API] + +用户：我觉得 REST 更适合我们的场景。 +[用户按下 Esc+Esc，选择 HATEOAS 之后的检查点，选择“恢复代码和对话”] + +用户：那我们就把 REST 方案定下来。 +``` + +## 示例 6：配置管理 + +### 场景 +测试不同的配置方案。 + +### 工作流程 + +``` +用户：把配置迁移到环境变量 + [检查点“Original config”自动创建] + +Claude：[实现环境变量配置] + +用户：在开发环境里测试 + +Claude：本地可用，但生产环境部署有问题 + +用户：我换个方案试试。 +[用户按下 Esc+Esc，选择“Original config”检查点，选择“恢复代码和对话”] + +用户：改成带校验的配置文件方案 + +Claude：[实现带 JSON Schema 校验的 YAML 配置] + +用户：在开发环境里测试 + +Claude：✅ 运行良好，校验错误提示也很清楚 + +用户：我们也能为敏感值支持环境变量吗？ + +Claude：[为密钥添加环境变量覆盖] + +用户：测试部署 + +Claude：✅ 所有环境都正常工作 + +用户：完美，这个已经可以用于生产。 +``` + +## 示例 7：测试策略 + +### 场景 +实现完整的测试体系。 + +### 工作流程 + +``` +用户：给 auth 模块添加单元测试 + [检查点自动创建] + +Claude：[添加 Jest 单元测试] + +用户：运行测试 + +Claude：45 个测试通过，覆盖率 78% + +用户：再加上集成测试 + +Claude：[添加集成测试] + +用户：运行测试 + +Claude：89 个测试通过，覆盖率 92%，但测试太慢了（3 分钟） + +用户：测试太慢了，我们来优化。 + +Claude：[优化测试设置，增加并行执行] + +用户：运行测试 + +Claude：89 个测试通过，覆盖率 92%，35 秒完成 ✅ + +用户：很好！再给关键路径加上 E2E 测试。 + +Claude：[添加 Playwright E2E 测试] + +用户：运行所有测试 + +Claude：112 个测试通过，覆盖率 94%，2 分钟完成 + +用户：很好，覆盖率和速度都平衡得不错！ +``` + +## 示例 8：从检查点开始总结 + +### 场景 +在一次很长的调试会话后，你想压缩对话内容，同时保留上下文。 + +### 工作流程 + +``` +用户：[经过 20 多条消息的调试和探索之后] + +[用户按下 Esc+Esc，选择较早的检查点，选择“从这里开始总结”] +[可选地提供指令：“重点保留我们尝试过什么，以及什么有效”] + +Claude：[生成从该点开始的对话总结] +[原始消息保留在记录里] +[总结会替换当前可见对话，从而减少上下文窗口占用] + +用户：现在继续推进那个有效的方案。 +``` + +## 关键结论 + +1. **检查点是自动创建的**：每次用户提示都会创建一个检查点，不需要手动保存。 +2. **使用 `Esc+Esc` 或 `/rewind`**：这两种方式都可以打开检查点浏览器。 +3. **选择合适的恢复方式**：根据需要恢复代码、对话、两者都恢复，或者直接总结。 +4. **不要害怕试验**：检查点让你可以安全尝试激进的改动。 +5. **和 git 结合使用**：检查点用于探索，git 用于最终落地。 +6. **长会话要及时总结**：用“从这里开始总结”来保持对话可管理。 diff --git a/zh/09-advanced-features/README.md b/zh/09-advanced-features/README.md new file mode 100644 index 0000000..32fe9ac --- /dev/null +++ b/zh/09-advanced-features/README.md @@ -0,0 +1,954 @@ + + + Claude How To + + +# 高级功能 + +这是一份关于 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. [更多资源](#更多资源) + +--- + + +## 概览 + +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 配置文件定制行为 + + +## 规划模式 + +更多规划示例见 [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` 可以把当前计划打开到外部编辑器里进行更详细的修改。 + + +## 扩展思考 + +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" + } +} +``` + + +## 自动模式 + +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 +# 先预览将要添加的权限（不会写入） + +# 应用保守基线 + +# 只有在需要时再逐步增加能力 +``` + + +## 后台任务 + +后台任务允许 Claude 在不阻塞对话的情况下运行长时间操作。 + +### 什么是后台任务？ + +后台任务适合长时间运行的工作，例如构建、测试、下载、扫描或并行分析。你可以把它们交给 Claude，让对话继续保持响应。 + +### 启动后台任务 + +你可以从命令、计划或工具链中启动后台任务，让 Claude 在后台继续工作。 + +### 管理后台任务 + +- 查看任务状态 +- 中止任务 +- 等待任务完成 +- 从结果中恢复上下文 + +### 示例：并行开发 + +```text +任务 A：运行测试 +任务 B：生成文档 +任务 C：执行安全扫描 +``` + +### 配置 + +后台任务的超时、并发和通知行为都可以在设置中调整。 + + +## 定时任务 + +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 通过。 +``` + + +## 权限模式 + +Permission modes 决定 Claude 可以直接执行哪些操作。 + +### 可用模式 + +- `default` +- `acceptEdits` +- `plan` +- `auto` +- `dontAsk` +- `bypassPermissions` + +### 启用方式 + +可以通过命令行、设置或会话中的快捷操作切换权限模式。 + +### 示例 + +#### Default Mode + +默认的平衡模式，必要时会询问权限。 + +#### Plan Mode + +只做规划，不直接执行高风险改动。 + +#### Accept Edits Mode + +更偏向自动接受编辑，适合受控环境。 + +### 使用场景 + +- 代码审查 +- 自动化重构 +- CI/CD +- 高风险操作前的审批流程 + + +## 无头模式 + +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 验证 +- 禁用会话持久化 + + +## 会话管理 + +会话管理用于在多个会话之间恢复、重命名、分叉和持续工作。 + +### 常用命令 + +- `/resume` +- `/rename` +- `/fork` +- `claude -c` +- `claude -r` + +### 恢复会话 + +```bash +# 继续最后一次对话 +claude -c + +# 恢复指定名称或 ID 的会话 +claude -r "feature-auth" +``` + +### 分叉会话 + +```bash +# 恢复并分叉，适合实验 +claude -r "feature-auth" --fork +``` + +### 会话持久化 + +你可以选择保留、继续或重建会话上下文。 + + +## 交互功能 + +交互功能包括快捷键、多行输入、历史记录、Vim 模式和 Bash 模式等。 + +### 快捷键 + +常用快捷键用于切换模式、编辑输入、查看历史和控制输出。 + +### 自定义快捷键 + +你可以在设置中绑定自己的按键组合。 + +### 可用上下文 + +不同上下文会影响快捷键的可用性和行为。 + +### Chord 支持 + +支持组合按键触发复杂操作。 + +### 保留键与冲突键 + +某些按键会被系统或终端占用，需要避免冲突。 + +### Tab 补全 + +输入命令、参数或路径时会提供补全建议。 + +### 命令历史 + +Claude 会保留历史记录，方便你快速重用之前的输入。 + +### 多行输入 + +```text +第一行 +第二行 +第三行 +``` + +### 行内编辑 + +支持在输入过程中编辑中间内容。 + +### Vim 模式 + +如果你熟悉 Vim，可以启用类似的编辑体验。 + +### Bash 模式 + +可在会话中直接进入更偏 shell 风格的操作方式。 + + +## 语音输入 + +语音输入支持按住说话和多语言识别，适合快速记录想法或在不方便键盘输入时使用。 + +### 如何启用 + +在设置中打开语音输入即可。 + +### 特性 + +- 支持按住说话 +- 支持 20 种语言的语音识别 +- 适合快速口述任务 + +### 配置 + +可在 settings 中控制灵敏度、语言和输入行为。 + + +## 消息通道（Channels） + +消息通道允许 MCP servers 向正在运行的会话推送消息。 + +### 订阅 channels + +```bash +# 启动时订阅 channel 插件 +``` + +### 支持的集成 + +- Discord +- Telegram +- 其他 channel 型集成 + +### 配置 + +通过 MCP 配置或 settings 订阅相应 channel。 + +### 工作方式 + +外部系统可以把消息推送进 Claude 的当前会话里，让你在一个会话中接收通知或事件。 + + +## Chrome 集成 + +Chrome 集成让 Claude 可以协助浏览器自动化和站点级操作。 + +### 启用 Chrome 集成 + +开启相关开关后，Claude 就可以与浏览器协作。 + +### 能力 + +- 浏览器自动化 +- 页面操作 +- 网站级交互 + +### 站点级权限 + +你可以对站点设置更细粒度的访问权限。 + +### 工作方式 + +Claude 通过浏览器连接与页面交互。 + +### 已知限制 + +- 某些站点会限制自动化 +- 复杂页面可能需要更多权限 + + +## 远程控制 + +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 版则是在浏览器中直接运行。 + +### 局限 + +- 网络可用性依赖更高 +- 某些本地资源可能不可远程访问 + +### 使用场景 + +- 在手机上查看并接管会话 +- 远程继续长期任务 + + +## 网页会话 + +Web Sessions 允许你直接在浏览器里创建和恢复 Claude Code 会话。 + +### 创建 Web Session + +```bash +# 从 CLI 创建新的 web session +claude --remote "implement API" +``` + +### 在本地恢复 Web Session + +```bash +# 在本地终端恢复 web session +claude --teleport +``` + +### 使用场景 + +- 浏览器里快速开始任务 +- 在本地和网页之间切换 +- 远程继续工作 + + +## 桌面应用 + +桌面应用提供独立界面，适合视觉化 diff 审查和多会话管理。 + +### 安装 + +按照桌面应用的安装说明安装即可。 + +### 从 CLI 接力 + +你可以把 CLI 会话交给桌面应用继续处理。 + +### 核心功能 + +- 可视化 diff +- 多会话 +- 更直观的审查体验 + +### App 预览配置 + +可以调整预览、布局和视觉呈现方式。 + +### Connectors + +桌面应用可以连接到不同的工作环境。 + +### 远程和 SSH 会话 + +桌面应用也支持远程或 SSH 场景下的接力。 + +### Desktop 中的权限模式 + +Desktop 里同样可以使用不同的权限模式。 + +### 企业功能 + +企业部署下可使用更多受管和合规相关能力。 + + +## 任务列表 + +Task List 用于跨 context compaction 持久保存任务进度。 + +### 切换任务列表 + +在设置里打开或关闭任务列表显示。 + +### 持久任务 + +任务会保留，即使上下文被压缩，也能继续跟踪。 + +### 命名任务目录 + +你可以给任务分组或目录命名，方便管理。 + + +## 提示词建议 + +Prompt suggestions 会根据当前上下文智能推荐下一步命令或提示词。 + +### 工作方式 + +系统会结合你的历史、当前任务和上下文给出建议。 + +### 禁用建议 + +如果你不想看到建议，可以在设置里关闭。 + + +## 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 可以自动清理。 + +### 使用场景 + +- 并行尝试多个方案 +- 隔离高风险重构 +- 保持主分支整洁 + + +## 沙盒 + +沙盒提供文件系统和网络层面的隔离，能显著降低自动化操作的风险。 + +### 启用沙盒 + +开启后，Claude 的很多操作都会在受控环境里执行。 + +### 配置项 + +你可以配置允许访问的目录、网络行为和例外列表。 + +### 示例配置 + +```json +{ + "sandbox": { + "enabled": true + } +} +``` + +### 工作方式 + +沙盒会限制 Claude 可触达的文件和网络边界。 + +### 使用场景 + +- 低风险自动化 +- 在不完全信任的输入上执行任务 +- 受控环境中的批处理 + + +## 企业受管设置 + +企业可以通过受管设置统一分发 Claude Code 配置。 + +### 部署方式 + +- plist +- Registry +- 受管文件 + +### 受管配置片段 + +通过受管配置片段，可以给团队统一推送策略。 + +### 可用的受管设置 + +- 权限模式 +- 功能开关 +- MCP / hooks / 插件约束 + +### macOS plist 示例 + +```xml + +``` + + +## 配置与设置 + +### 配置文件位置 + +- `~/.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`，这样能跟代码一起版本化。 + + +## 最佳实践 + +### Planning Mode + +- 复杂任务先规划，再实现 +- 计划要可审阅 + +### Extended Thinking + +- 留给复杂问题 +- 不要在简单任务上过度使用 + +### Background Tasks + +- 用于长时间、可并行的任务 +- 记得设置超时和可见性 + +### Permissions + +- 默认最小权限 +- 只在必要时放宽 + +### Sessions + +- 为重要会话命名 +- 必要时分叉，而不是硬改 + + +## 更多资源 + +- [根目录中文指南](../README.md) +- [Slash Commands 中文参考](../01-slash-commands/README.md) +- [Checkpoints 中文指南](../08-checkpoints/README.md) +- [Plugins 中文指南](../07-plugins/README.md) +- [CLI 中文参考](../10-cli/README.md) diff --git a/zh/09-advanced-features/planning-mode-examples.md b/zh/09-advanced-features/planning-mode-examples.md new file mode 100644 index 0000000..80ffe2e --- /dev/null +++ b/zh/09-advanced-features/planning-mode-examples.md @@ -0,0 +1,533 @@ +# 计划模式示例 + +以下是 Claude Code 中有效使用计划模式的真实示例。 + +## 示例 1：构建 REST API + +### 不使用计划模式 + +``` +用户：给博客做一个 REST API + +Claude：我来创建这个 API…… +[立刻开始编码，可能漏掉需求] +``` + +### 使用计划模式 + +``` +用户：/plan 给博客做一个 REST API + +Claude：我来为这个博客 API 制定一份完整计划。 + +## 博客 REST API 实现计划 + +### 阶段 1：项目初始化（15 分钟） +1. 初始化带 Express 的 Node.js 项目 +2. 配置 TypeScript +3. 安装依赖（express、pg、jwt、joi） +4. 配置环境变量 +5. 搭建项目结构 + +### 阶段 2：数据库层（30 分钟） +6. 设计数据库 schema + - users 表（id、email、password_hash、created_at） + - posts 表（id、user_id、title、content、published、created_at、updated_at） + - comments 表（id、post_id、user_id、content、created_at） +7. 创建迁移文件 +8. 搭建数据库连接池 +9. 实现数据库模型 + +### 阶段 3：认证（45 分钟） +10. 实现用户注册接口 +11. 实现带 JWT 的登录接口 +12. 创建认证中间件 +13. 使用 bcrypt 添加密码哈希 +14. 实现 token 刷新逻辑 + +### 阶段 4：Posts API（40 分钟） +15. GET /api/posts - 获取所有已发布文章（支持分页） +16. GET /api/posts/:id - 获取单篇文章 +17. POST /api/posts - 创建新文章（需要认证） +18. PUT /api/posts/:id - 更新文章（需要认证，检查所有权） +19. DELETE /api/posts/:id - 删除文章（需要认证，检查所有权） +20. GET /api/users/:id/posts - 获取某个用户的文章 + +### 阶段 5：Comments API（30 分钟） +21. GET /api/posts/:id/comments - 获取文章评论 +22. POST /api/posts/:id/comments - 添加评论（需要认证） +23. DELETE /api/comments/:id - 删除评论（需要认证，检查所有权） + +### 阶段 6：校验与错误处理（30 分钟） +24. 使用 Joi 添加请求校验 +25. 实现全局错误处理器 +26. 添加输入清洗 +27. 实现速率限制 + +### 阶段 7：测试（60 分钟） +28. 为模型编写单元测试 +29. 为认证接口编写集成测试 +30. 为文章接口编写集成测试 +31. 为评论接口编写集成测试 +32. 达到 80%+ 的代码覆盖率 + +### 阶段 8：文档与部署（30 分钟） +33. 使用 Swagger 生成 API 文档 +34. 创建包含安装说明的 README +35. 添加 Docker 配置 +36. 搭建 CI/CD 流水线 + +**预估时间**：4.5 小时 +**需要创建的文件**：约 25 个 +**关键技术**：Express、PostgreSQL、JWT、TypeScript + +**API 端点概览**： +- 认证：2 个端点 +- 文章：6 个端点 +- 评论：3 个端点 +- 总计：11 个端点 + +准备继续吗？（yes/no/modify） + +用户：yes + +Claude：开始阶段 1：项目初始化…… +[按阶段系统性实现] +``` + +## 示例 2：数据库迁移 + +### 使用计划模式 + +``` +用户：/plan 将数据库从 MongoDB 迁移到 PostgreSQL + +Claude：这是一次复杂迁移。我来制定详细计划。 + +## MongoDB 到 PostgreSQL 的迁移计划 + +### 阶段 1：分析与准备（第 1 天） +1. 分析当前 MongoDB schema +2. 识别数据关系和约束 +3. 记录当前数据量和增长速率 +4. 设计对应的 PostgreSQL schema +5. 规划数据类型映射 +6. 识别潜在迁移挑战 + +### 阶段 2：PostgreSQL 准备（第 1 天） +7. 搭建 PostgreSQL 数据库 +8. 创建包含表、索引和约束的 schema +9. 配置连接池 +10. 制定备份策略 + +### 阶段 3：双写实现（第 2-3 天） +11. 创建数据库抽象层 +12. 实现同时向两个数据库写入 +13. 添加数据一致性检查 +14. 在预发布环境部署双写 +15. 监控问题 + +### 阶段 4：数据迁移（第 4 天） +16. 为 MongoDB 创建数据导出脚本 +17. 为 PostgreSQL 创建数据导入脚本 +18. 实现数据转换逻辑 +19. 在生产数据副本上执行初次迁移 +20. 验证迁移后数据完整性 + +### 阶段 5：渐进切换（第 5-7 天） +21. 在生产环境开启双写 +22. 分批迁移历史数据 +23. 持续验证数据一致性 +24. 监控两个数据库 +25. 修复任何数据同步问题 + +### 阶段 6：PostgreSQL 作为主库（第 8 天） +26. 将读操作切换到 PostgreSQL +27. 监控查询性能 +28. 优化慢查询 +29. 继续保留双写作为安全措施 + +### 阶段 7：MongoDB 退役（第 9-10 天） +30. 停止向 MongoDB 写入 +31. 保留 MongoDB 作为两周备份 +32. 从代码中移除 MongoDB 依赖 +33. 归档 MongoDB 数据 +34. 下线 MongoDB 实例 + +**预估时间**：10 天 +**风险等级**：高 +**回滚策略**：保持 MongoDB 运行并开启双写 +**成功标准**： +- 零数据丢失 +- 性能回退小于 5% +- 所有测试通过 + +**关键风险**： +1. 迁移过程中的数据不一致 +2. 查询性能下降 +3. 应用停机 +4. 数据丢失 + +**缓解措施**： +- 采用双写模式保障安全 +- 渐进式切换 +- 持续监控 +- 快速回滚能力 + +是否按此计划继续？（yes/no/modify） + +用户：modify - 我们给每个阶段都加上回滚方案 + +Claude：我已经为每个阶段补充了回滚流程…… +``` + +## 示例 3：前端重构 + +``` +用户：/plan 把我们的 React 应用从 class 组件重构为 hooks + +Claude：我来制定一个系统化的重构计划。 + +## React Class 到 Hooks 迁移计划 + +### 阶段 1：准备与分析（2 小时） +1. 审查所有 class 组件（查找所有 .jsx/.tsx 文件） +2. 按复杂度分类： + - 简单型（仅 state）：约 15 个组件 + - 中等型（生命周期方法）：约 23 个组件 + - 复杂型（多个生命周期、refs）：约 8 个组件 +3. 识别需要更新的第三方库 +4. 创建组件依赖图 +5. 规划迁移顺序（先叶子节点） + +### 阶段 2：环境与工具（1 小时） +6. 将 React 升级到 v18+ +7. 为 hooks 配置 ESLint 规则 +8. 创建转换模板 +9. 配置自动化测试 +10. 在开始前创建一个检查点 + +### 阶段 3：迁移简单组件（4 小时） +11. 转换简单的有状态组件（15 个） +12. 用 `useState` 替换 `this.state` +13. 用状态 setter 替换 `this.setState` +14. 每个组件转换后都进行测试 +15. 更新测试 + +### 阶段 4：迁移中等复杂组件（8 小时） +16. 转换带生命周期方法的组件（23 个） +17. 用 `useEffect` 替换 `componentDidMount` +18. 用 `useEffect` 替换 `componentDidUpdate` +19. 用 `useEffect` 清理函数替换 `componentWillUnmount` +20. 做充分测试 + +### 阶段 5：迁移复杂组件（12 小时） +21. 转换复杂组件（8 个） +22. 用 `useRef` 替换 refs +23. 为共享逻辑提取自定义 hooks +24. 处理边缘情况（多个 `useEffect`） +25. 做深入测试 + +### 阶段 6：提取共享逻辑（6 小时） +26. 识别组件之间重复的逻辑 +27. 创建自定义 hooks： + - `useAuth` + - `useFetch` + - `useLocalStorage` + - `useDebounce` +28. 将组件重构为使用自定义 hooks +29. 独立测试自定义 hooks + +### 阶段 7：性能优化（4 小时） +30. 在需要的地方添加 `React.memo` +31. 使用 `useCallback` 优化 +32. 使用 `useMemo` 优化 +33. 分析并修复性能回退 + +### 阶段 8：收尾与文档（2 小时） +34. 移除未使用的 class 组件工具 +35. 更新文档 +36. 更新编码规范 +37. 为团队编写迁移指南 + +**预估时间**：5 天（39 小时） +**需要修改的文件**：46 个组件 +**风险等级**：中 + +**迁移顺序**： +1. 叶子组件（无依赖） +2. 中层组件 +3. 顶层容器组件 +4. `App.jsx`（最后） + +**测试策略**： +- 每个组件的单元测试 +- 用户流程的集成测试 +- 视觉回归测试 +- 性能基准测试 + +**成功指标**： +- 所有测试通过 +- 没有视觉回归 +- 性能保持或提升 +- 打包体积没有明显增加 + +继续吗？（yes/no/modify） +``` + +## 示例 4：安全实现 + +``` +用户：/plan 为我们的 Web 应用实现完整安全方案 + +Claude：我来制定一份全面的安全实施计划。 + +## Web 应用安全实施计划 + +### 阶段 1：安全审计（第 1 天） +1. 运行自动化安全扫描器（npm audit、Snyk） +2. 检查依赖中的漏洞 +3. 核对 OWASP Top 10 合规性 +4. 审查认证流程 +5. 审查数据处理方式 +6. 记录当前的安全缺口 + +### 阶段 2：认证加固（第 2-3 天） +7. 实现强密码要求 +8. 添加密码强度检测器 +9. 对登录接口实施限流 +10. 在多次失败后锁定账户 +11. 实现 2FA（TOTP） +12. 改进会话管理 +13. 实现安全的密码重置流程 + +### 阶段 3：授权与访问控制（第 3-4 天） +14. 实现 RBAC（基于角色的访问控制） +15. 为所有端点添加权限检查 +16. 实现最小权限原则 +17. 为敏感操作添加审计日志 +18. 实现资源级权限 + +### 阶段 4：数据保护（第 4-5 天） +19. 对敏感字段实施静态加密 +20. 确保所有通信都使用 TLS/SSL +21. 实现安全的会话存储 +22. 在日志中对 PII 数据做脱敏 +23. 实现数据保留策略 +24. 添加安全的文件上传处理 + +### 阶段 5：输入验证与清洗（第 5-6 天） +25. 为所有端点实现输入校验 +26. 添加 XSS 防护（Content Security Policy） +27. 实现 SQL 注入防护（参数化查询） +28. 添加 CSRF 防护 +29. 实现请求大小限制 +30. 添加文件上传类型校验 + +### 阶段 6：安全头与配置（第 6 天） +31. 添加安全响应头： + - Strict-Transport-Security + - X-Content-Type-Options + - X-Frame-Options + - X-XSS-Protection + - Content-Security-Policy +32. 正确配置 CORS +33. 禁用不必要的 HTTP 方法 +34. 移除服务器版本头 + +### 阶段 7：监控与日志（第 7 天） +35. 实现安全事件日志 +36. 添加异常检测 +37. 搭建入侵检测 +38. 实现实时告警 +39. 创建安全仪表盘 + +### 阶段 8：测试与文档（第 8-9 天） +40. 执行渗透测试 +41. 运行安全扫描器 +42. 测试所有安全功能 +43. 编写安全文档 +44. 培训团队的安全实践 +45. 编写事件响应计划 + +### 阶段 9：合规与政策（第 10 天） +46. 检查 GDPR 合规性 +47. 创建隐私政策 +48. 实现数据主体权利支持 +49. 添加 cookie 同意机制 +50. 编写安全政策文档 + +**预估时间**：10 天 +**风险等级**：严重 +**优先级**：高 + +**安全改进摘要**： +- 认证：7 项增强 +- 授权：5 项增强 +- 数据保护：6 项增强 +- 输入校验：6 项增强 +- 基础设施：9 项增强 +- 监控：5 项增强 + +**合规性**：OWASP Top 10、GDPR + +**成功标准**： +- 零严重漏洞 +- 所有 OWASP Top 10 风险都得到缓解 +- 安全评分高于 90/100 +- 所有渗透测试问题都已解决 + +继续吗？（yes/no/modify） +``` + +## 示例 5：性能优化 + +``` +用户：/plan 优化我们这个很慢的电商网站 + +Claude：我来制定一份完整的性能优化计划。 + +## 电商网站性能优化计划 + +### 阶段 1：性能审计（4 小时） +1. 运行 Lighthouse 审计 +2. 分析 Chrome DevTools 性能剖析结果 +3. 测量 Core Web Vitals： + - LCP（Largest Contentful Paint） + - FID（First Input Delay） + - CLS（Cumulative Layout Shift） +4. 找出性能瓶颈 +5. 创建基线性能指标 + +**当前指标**： +- LCP：4.2s（目标：<2.5s） +- FID：280ms（目标：<100ms） +- CLS：0.25（目标：<0.1） +- 页面加载：8.3s（目标：<3s） + +### 阶段 2：图片优化（6 小时） +6. 将图片转换为 WebP 格式 +7. 实现响应式图片 +8. 为图片添加懒加载 +9. 优化图片大小（压缩） +10. 为图片接入 CDN +11. 添加图片占位符 + +**预期影响**：加载时间减少 40% + +### 阶段 3：代码拆分与懒加载（8 小时） +12. 实现基于路由的代码拆分 +13. 懒加载非关键组件 +14. 拆分第三方依赖包 +15. 优化 chunk 大小 +16. 实现动态导入 +17. 为关键资源添加预加载 + +**预期影响**：初始 bundle 体积减少 30% + +### 阶段 4：缓存策略（6 小时） +18. 实现浏览器缓存（Cache-Control） +19. 为离线支持添加 service worker +20. 实现 API 响应缓存 +21. 为数据库查询添加 Redis 缓存 +22. 实现 stale-while-revalidate +23. 配置 CDN 缓存 + +**预期影响**：API 响应时间减少 50% + +### 阶段 5：数据库优化（8 小时） +24. 添加数据库索引 +25. 优化慢查询（>100ms） +26. 实现查询结果缓存 +27. 添加连接池 +28. 在合适地方做反规范化 +29. 实现数据库只读副本 + +**预期影响**：数据库查询时间减少 60% + +### 阶段 6：前端优化（10 小时） +30. 最小化并压缩 JavaScript +31. 最小化并压缩 CSS +32. 移除未使用的 CSS（PurgeCSS） +33. 实现关键 CSS +34. 延迟加载非关键 JavaScript +35. 减少 DOM 规模 +36. 优化 React 渲染（`memo`、`useMemo`） +37. 为长列表实现虚拟滚动 + +**预期影响**：JavaScript 执行时间减少 35% + +### 阶段 7：网络优化（4 小时） +38. 启用 HTTP/2 +39. 实现资源提示（preconnect、prefetch） +40. 减少 HTTP 请求数量 +41. 启用 Brotli 压缩 +42. 优化第三方脚本 + +**预期影响**：网络耗时减少 25% + +### 阶段 8：监控与测试（4 小时） +43. 搭建性能监控（Datadog/New Relic） +44. 添加真实用户监控（RUM） +45. 制定性能预算 +46. 搭建自动化 Lighthouse CI +47. 在真实设备上测试 + +**预估时间**：50 小时（2 周） + +**目标指标**（90 分位）： +- LCP：<2.0s（从 4.2s 降低）✅ +- FID：<50ms（从 280ms 降低）✅ +- CLS：<0.05（从 0.25 降低）✅ +- 页面加载：<2.5s（从 8.3s 降低）✅ + +**预期收入影响**： +- 每快 100ms，转化率提升 1% +- 目标：缩短 5.8s，约带来 58% 的转化率提升 +- 预估额外收入：显著 + +**优先级顺序**： +1. 图片优化（快速收益） +2. 代码拆分（高影响） +3. 缓存（高影响） +4. 数据库优化（关键） +5. 前端优化（打磨） + +是否按此计划继续？（yes/no/modify） +``` + +## 关键要点 + +### 计划模式的优势 + +1. **清晰**：开始前就有明确路线图 +2. **可估算**：能给出时间和工作量预估 +3. **风险评估**：能尽早发现潜在问题 +4. **优先级排序**：任务按合理顺序推进 +5. **可审批**：执行前先审阅并确认 +6. **可调整**：根据反馈及时修改计划 + +### 什么时候使用计划模式 + +✅ **建议始终使用于**： +- 多日项目 +- 团队协作 +- 关键系统变更 +- 学习新概念 +- 复杂重构 + +❌ **不建议使用于**： +- 修 bug +- 小改动 +- 简单查询 +- 快速实验 + +### 最佳实践 + +1. **审批前仔细审查** 计划 +2. **发现问题就修改** 计划 +3. **把复杂任务拆细** +4. **给出现实的时间估算** +5. **包含回滚策略** +6. **写明成功标准** +7. **为每个阶段安排测试** diff --git a/zh/10-cli/README.md b/zh/10-cli/README.md new file mode 100644 index 0000000..5793c09 --- /dev/null +++ b/zh/10-cli/README.md @@ -0,0 +1,640 @@ + + + Claude How To + + +# 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 "" "query"` | 通过 ID 或名称恢复会话 | `claude -r "auth-refactor" "完成这个 PR"` | +| `claude update` | 更新到最新版本 | `claude update` | +| `claude mcp` | 配置 MCP servers | 见 [MCP 文档](../05-mcp/README.md) | +| `claude mcp serve` | 将 Claude Code 作为 MCP server 运行 | `claude mcp serve` | +| `claude agents` | 列出所有已配置的 subagents | `claude agents` | +| `claude auto-mode defaults` | 以 JSON 打印 auto mode 默认规则 | `claude auto-mode defaults` | +| `claude remote-control` | 启动远程控制服务 | `claude remote-control` | +| `claude plugin` | 管理插件（安装、启用、禁用） | `claude plugin install my-plugin` | +| `claude auth login` | 登录（支持 `--email`、`--sso`） | `claude auth login --email user@example.com` | +| `claude auth logout` | 注销当前账号 | `claude auth logout` | +| `claude auth status` | 检查登录状态（已登录返回 0，否则返回 1） | `claude auth status` | + +## 核心标志 + +| 参数 | 说明 | 示例 | +|------|-------------|---------| +| `-p, --print` | 不进入交互式模式，直接输出结果 | `claude -p "query"` | +| `-c, --continue` | 加载最近一次会话 | `claude --continue` | +| `-r, --resume` | 按 ID 或名称恢复指定会话 | `claude --resume auth-refactor` | +| `-v, --version` | 输出版本号 | `claude -v` | +| `-w, --worktree` | 在隔离的 git worktree 中启动 | `claude -w` | +| `-n, --name` | 设置会话显示名称 | `claude -n "auth-refactor"` | +| `--from-pr ` | 恢复与 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["多轮对话
Tab 补全
历史记录
Slash commands"] + C -->|特性| E["单次查询
可脚本化
可管道化
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" +``` + + +## Subagents 配置 + +| 参数 | 说明 | 示例 | +|------|-------------|---------| +| `--agents` | 通过 JSON 定义自定义 subagents | `claude --agents ./agents.json` | +| `--agent` | 指定当前会话使用的 agent | `claude --agent reviewer` | + +### Subagents JSON 格式 + +```json +{ + "agent-name": { + "description": "Required: when to invoke this agent", + "prompt": "Required: system prompt for the agent", + "tools": ["Optional", "array", "of", "tools"], + "model": "optional: sonnet|opus|haiku" + } +} +``` + +**必填字段：** +- `description` - 何时使用这个 agent 的自然语言说明 +- `prompt` - 定义 agent 角色和行为的系统提示词 + +**可选字段：** +- `tools` - 可用工具数组（如果省略则继承全部工具） + - 格式：`["Read", "Grep", "Glob", "Bash"]` +- `model` - 使用的模型：`sonnet`、`opus` 或 `haiku` + +### 完整 Agents 示例 + +```json +{ + "code-reviewer": { + "description": "Expert code reviewer. Use proactively after code changes.", + "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", + "tools": ["Read", "Grep", "Glob", "Bash"], + "model": "sonnet" + }, + "debugger": { + "description": "Debugging specialist for errors and test failures.", + "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.", + "tools": ["Read", "Edit", "Bash", "Grep"], + "model": "opus" + }, + "documenter": { + "description": "Documentation specialist for generating guides.", + "prompt": "You are a technical writer. Create clear, comprehensive documentation.", + "tools": ["Read", "Write"], + "model": "haiku" + } +} +``` + +### Agents 命令示例 + +```bash +# 直接定义自定义 agent +claude --agents '{ + "security-auditor": { + "description": "Security specialist for vulnerability analysis", + "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.", + "tools": ["Read", "Grep", "Glob"], + "model": "opus" + } +}' "audit this codebase for security issues" + +# 从文件加载 agents +claude --agents ./configs/agents.json + +# 与其他参数组合 +claude --agents ./configs/agents.json --model opus +``` + +### Subagent 优先级 + +当同时存在多种 agent 定义时，加载优先级如下： +1. **CLI 定义**（`--agents` 参数）- 当前会话专用 +2. **用户级**（`~/.claude/agents/`）- 所有项目可用 +3. **项目级**（`.claude/agents/`）- 当前项目可用 + +命令行定义的 agents 会覆盖本次会话里的用户级和项目级 agents。 + +## 高价值使用场景 + +### 1. CI/CD 集成 + +```bash +claude -p --output-format json "run tests and summarize failures" +``` + +### 2. 管道式脚本处理 + +```bash +# 分析错误日志 +cat error.log | claude -p "解释这些错误并给出修复建议" + +# 查找访问日志中的模式 +cat access.log | claude -p "找出异常流量" + +# 分析 git 历史 +git log --oneline -20 | claude -p "总结最近的开发方向" + +# 审查某个文件 +claude -p "review src/app.ts and suggest improvements" + +# 生成文档 +claude -p "根据 README 生成 API 文档" + +# 查找 TODO 并排优先级 +rg -n "TODO|FIXME" . | claude -p "按优先级分类这些待办" +``` + +### 3. 多会话工作流 + +```bash +# 启动特性分支会话 +claude --session feature-auth + +# 之后继续该会话 +claude --resume feature-auth + +# 分叉尝试另一种方案 +claude --fork-session + +# 在不同特性会话之间切换 +claude --resume feature-auth +claude --resume feature-payment +``` + +### 4. 自定义 agent 配置 + +```bash +# 将 agents 配置保存到文件 +cat > agents.json <<'JSON' +{ + "agents": [ + {"name":"reviewer","description":"review code"}, + {"name":"tester","description":"write tests"} + ] +} +JSON + +# 在会话中使用这些 agent +claude --agents ./agents.json --agent reviewer +``` + +### 5. 批处理 + +```bash +# 处理多个文件 +find src -name "*.ts" | xargs -I{} claude -p "review {}" + +# 批量代码审查 +claude -p "review all changes in this branch" + +# 为所有模块生成测试 +claude -p "generate tests for the modified modules" +``` + +### 6. 安全敏感开发 + +```bash +# 只读安全审计 +claude --permission-mode plan -p "audit this repository" + +# 阻止危险命令 +claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)" + +# 限制自动化 +claude --tools "Read,Grep,Glob" -p "inspect the codebase" +``` + +### 7. JSON API 集成 + +```bash +# 获取结构化分析结果 +claude -p --output-format json "analyze this code and return findings" + +# 配合 jq 处理 +claude -p --output-format json "list functions" | jq '.functions[]' + +# 在脚本中使用 +result=$(claude -p --output-format json "summarize changes") +``` + +### jq 解析示例 + +```bash +# 提取特定字段 +claude -p --output-format json "analyze repo" | jq '.summary' + +# 过滤数组元素 +claude -p --output-format json "find bugs" | jq '.bugs[] | select(.severity=="high")' + +# 提取多个字段 +claude -p --output-format json "analyze" | jq '{summary, risk, recommendations}' + +# 转成 CSV +claude -p --output-format json "list files" | jq -r '.files[] | [.name, .size] | @csv' + +# 条件处理 +claude -p --output-format json "check status" | jq 'if .ok then "pass" else "fail" end' + +# 提取嵌套值 +claude -p --output-format json "inspect" | jq '.details.metrics.coverage' + +# 处理整个数组 +claude -p --output-format json "find todos" | jq '.todos | length' + +# 转换输出 +claude -p --output-format json "review" | jq '{issues: [.issues[] | {file, line, message}]}' +``` + +## 模型 + +### 模型选择 + +```bash +# 使用短名称 +claude --model sonnet +claude --model opus +claude --model haiku + +# 使用 opusplan 别名（Opus 负责规划，Sonnet 负责执行） +claude --model opusplan "design and implement the caching layer" + +# 会话中切换快速模式 +claude --model haiku --effort low +``` + +### Effort 级别（Opus 4.6） + +```bash +# 通过 CLI 参数设置 effort +claude --model opus --effort high "design the architecture" + +# 通过 slash command 设置 effort +/effort max + +# 通过环境变量设置 effort +CLAUDE_EFFORT=medium claude --model opus +``` + +## 常用环境变量 + +| 环境变量 | 说明 | +|----------|------| +| `ANTHROPIC_API_KEY` | API key | +| `CLAUDE_MODEL` | 默认模型 | +| `CLAUDE_EFFORT` | 默认推理强度 | +| `CLAUDE_WORKING_DIRECTORY` | 默认工作目录 | +| `CLAUDE_OUTPUT_FORMAT` | 默认输出格式 | +| `CLAUDE_MCP_CONFIG` | 默认 MCP 配置 | + +## 快速参考 + +### 最常用命令 + +```bash +# 交互式会话 +claude + +# 快速提问 +claude -p "explain this repo" + +# 继续上次对话 +claude -c + +# 处理某个文件 +claude -p "review README.md" + +# 为脚本输出 JSON +claude -p --output-format json "list all classes" +``` + +### 参数组合 + +```bash +# 只读审查 +claude --permission-mode plan -p "review this codebase" + +# 高级模型 + JSON 输出 +claude --model opus -p --output-format json "analyze architecture" + +# 自定义工作目录 + MCP +claude --working-directory ./backend --mcp-config ./mcp.json +``` + +## 故障排查 + +### 找不到命令 + +- 确认 `claude` 已安装并在 `PATH` 中 +- 重新打开终端 +- 检查是否需要重新登录或更新版本 + +### API Key 问题 + +- 检查 `ANTHROPIC_API_KEY` +- 确认 key 未过期 +- 检查网络是否可访问 API + +### 找不到会话 + +- 确认会话名称或 ID 正确 +- 先运行 `claude --list-sessions`（如果你的版本支持） +- 检查当前账号是否一致 + +### 输出格式问题 + +- 使用 `--output-format json` 时确保输出可被解析 +- 如果是流式输出，加入 `--include-partial-messages` + +### 权限被拒绝 + +- 检查 `--permission-mode` +- 检查 `--allowedTools` 和 `--disallowedTools` +- 如有必要，明确允许所需工具 + +## 更多资源 + +- [根目录中文指南](../README.md) +- [Slash Commands 中文参考](../01-slash-commands/README.md) +- [MCP 文档](../05-mcp/README.md) +- [Claude Code 官方 CLI 文档](https://code.claude.com/docs/en/cli-reference) diff --git a/zh/CATALOG.md b/zh/CATALOG.md new file mode 100644 index 0000000..4045b84 --- /dev/null +++ b/zh/CATALOG.md @@ -0,0 +1,517 @@ + + + Claude How To + + +# 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 # 安装 plugin +/plugin remove # 移除 plugin +/plugin update # 更新 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 ` | + +--- + +## 一条命令完成安装 + +```bash +# 创建目录 +mkdir -p .claude/commands .claude/agents ~/.claude/hooks ~/.claude/skills + +# 安装所有功能 +cp 01-slash-commands/*.md .claude/commands/ +cp 04-subagents/*.md .claude/agents/ +cp -r 03-skills/* ~/.claude/skills/ +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# 配置 MCP +export GITHUB_TOKEN="your_token" +claude mcp add github -- npx -y @modelcontextprotocol/server-github + +# 使用 Plugins +/plugin install pr-review +/plugin install devops-automation +``` + +--- + +## 其他资源 + +- [Claude Code Documentation](https://code.claude.com/docs/en/overview) +- [MCP Protocol Specification](https://modelcontextprotocol.io) +- [Skills Repository](https://github.com/luongnv89/skills) - 现成 skills 集合 +- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) +- [Boris Cherny's Claude Code Workflow](https://x.com/bcherny/status/2007179832300581177) - Claude Code 的创造者分享了他的系统化工作流：并行 agents、共享 `CLAUDE.md`、Plan mode、slash commands、subagents，以及用于长时间自主会话的验证 hooks。 diff --git a/zh/CHANGELOG.md b/zh/CHANGELOG.md new file mode 100644 index 0000000..024f5b0 --- /dev/null +++ b/zh/CHANGELOG.md @@ -0,0 +1,109 @@ +# 更新日志 + +## v2.2.0 — 2026-03-26 + +### 文档 + +- 与 Claude Code v2.1.84（f78c094）同步更新所有教程和参考文档 @luongnv89 + - 将 slash commands 更新为 55+ 个内置命令 + 5 个 bundled skills，并标记 3 个已弃用项 + - 将 hook 事件从 18 个扩展到 25 个，新增 `agent` hook 类型（现在共 4 类） + - 在高级功能中加入自动模式（Auto Mode）、通道（Channels）、语音输入（Voice Dictation） + - 为 skill frontmatter 增加 `effort`、`shell` 字段；为 agent 增加 `initialPrompt`、`disallowedTools` 字段 + - 增加 WebSocket MCP transport、elicitation、2KB 工具上限 + - 增加 plugin 的 LSP 支持、`userConfig`、`${CLAUDE_PLUGIN_DATA}` + - 更新所有参考文档（CATALOG、QUICK_REFERENCE、LEARNING-ROADMAP、INDEX） +- 将 README 重写为落地页结构化指南（32a0776）@luongnv89 + +### Bug 修复 + +- 为通过 CI 词典检查，补充缺失的 cSpell 词条和 README 章节（93f9d51）@luongnv89 +- 在 cSpell 词典中加入 `Sandboxing`（b80ce6f）@luongnv89 + +**完整更新日志**：https://github.com/luongnv89/claude-howto/compare/v2.1.1...v2.2.0 + +--- + +## v2.1.1 — 2026-03-13 + +### Bug 修复 + +- 移除导致 CI 链接检查失败的失效 marketplace 链接（3fdf0d6）@luongnv89 +- 将 `sandboxed` 和 `pycache` 加入 cSpell 词典（dc64618）@luongnv89 + +**完整更新日志**：https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1 + +--- + +## v2.1.0 — 2026-03-13 + +### 功能 + +- 新增自适应学习路径，包含自我评估和 lesson quiz skills（1ef46cd）@luongnv89 + - `/self-assessment` - 覆盖 10 个功能领域的交互式能力测验，并生成个性化学习路径 + - `/lesson-quiz [lesson]` - 每课知识检查，包含 8-10 道针对性问题 + +### Bug 修复 + +- 更新失效 URL、弃用项和过时引用（8fe4520）@luongnv89 +- 修复 resources 和 self-assessment skill 中的损坏链接（7a05863）@luongnv89 +- 在 concepts guide 中为嵌套代码块使用 tilde fences（5f82719）@VikalpP +- 为 cSpell 词典补充缺失词汇（8df7572）@luongnv89 + +### 文档 + +- Phase 5 QA - 修复各文档中的一致性、URL 和术语问题（00bbe4c）@luongnv89 +- 完成 Phase 3-4 - 补充新功能覆盖和参考文档更新（132de29）@luongnv89 +- 在 MCP 上下文膨胀章节加入 MCPorter runtime（ef52705）@luongnv89 +- 为 6 份指南补充缺失命令、功能和设置（4bc8f15）@luongnv89 +- 基于仓库现有规范补充 style guide（84141d0）@luongnv89 +- 在指南对比表中加入自我评估行（8fe0c96）@luongnv89 +- 将 VikalpP 加入贡献者名单，记录 PR #7（d5b4350）@luongnv89 +- 在 README 和 roadmap 中加入 self-assessment 与 lesson-quiz skill 参考（d5a6106）@luongnv89 + +### 新贡献者 + +- @VikalpP 完成了他们的首次贡献，见 #7 + +**完整更新日志**：https://github.com/luongnv89/claude-howto/compare/v2.0.0...v2.1.0 + +--- + +## v2.0.0 — 2026-02-01 + +### 功能 + +- 与 Claude Code 2026 年 2 月功能同步更新全部文档（487c96d） + - 更新所有 10 个教程目录和 7 份参考文档中的 26 个文件 + - 补充 **Auto Memory** 文档 - 每个项目的持久学习能力 + - 补充 **Remote Control**、**Web Sessions** 和 **Desktop App** 文档 + - 补充 **Agent Teams** 文档（实验性多 agent 协作） + - 补充 **MCP OAuth 2.0**、**Tool Search** 和 **Claude.ai Connectors** 文档 + - 补充 subagents 的 **Persistent Memory** 和 **Worktree Isolation** 文档 + - 补充 **Background Subagents**、**Task List**、**Prompt Suggestions** 文档 + - 补充 **Sandboxing** 和 **Managed Settings**（Enterprise）文档 + - 补充 **HTTP Hooks** 和 7 个新 hook 事件的文档 + - 补充 **Plugin Settings**、**LSP Servers** 和 marketplace 更新文档 + - 补充 Checkpoint 的 **Summarize from Checkpoint** 回退选项文档 + - 记录 17 个新的 slash commands（`/fork`、`/desktop`、`/teleport`、`/tasks`、`/fast` 等） + - 记录新的 CLI flags（`--worktree`、`--from-pr`、`--remote`、`--teleport`、`--teammate-mode` 等） + - 记录 auto memory、effort 等级、agent teams 等新的环境变量 + +### 设计 + +- 将 logo 重设计为简洁调色的 compass-bracket 标志（20779db） + +### Bug 修复 / 修正 + +- 更新模型名称：Sonnet 4.5 → **Sonnet 4.6**，Opus 4.5 → **Opus 4.6** +- 修正 permission mode 名称：用真实的 `default` / `acceptEdits` / `plan` / `dontAsk` / `bypassPermissions` 替代虚构的 “Unrestricted/Confirm/Read-only” +- 修正 hook 事件：移除虚构的 `PreCommit` / `PostCommit` / `PrePush`，加入真实事件（`SubagentStart`、`WorktreeCreate`、`ConfigChange` 等） +- 修正 CLI 语法：用 `claude -p`（print mode）替代虚构的 `claude-code --headless` +- 修正 checkpoint 命令：用真实的 `Esc+Esc` / `/rewind` 界面替代虚构的 `/checkpoint save/list/rewind/diff` +- 修正 session 管理：用真实的 `/resume` / `/rename` / `/fork` 替代虚构的 `/session list/new/switch/save` +- 修正 plugin manifest 格式：从 `plugin.yaml` 迁移到 `.claude-plugin/plugin.json` +- 修正 MCP 配置路径：`~/.claude/mcp.json` → `.mcp.json`（项目）/ `~/.claude.json`（用户） +- 修正文档 URL：`docs.claude.com` → `docs.anthropic.com`；移除虚构的 `plugins.claude.com` +- 移除多个文件中虚构的配置字段 +- 将所有 “Last Updated” 日期更新到 2026 年 2 月 + +**完整更新日志**：https://github.com/luongnv89/claude-howto/compare/20779db...v2.0.0 diff --git a/zh/CODE_OF_CONDUCT.md b/zh/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..b64c98d --- /dev/null +++ b/zh/CODE_OF_CONDUCT.md @@ -0,0 +1,216 @@ +# 贡献者行为准则 + +## 我们的承诺 + +我们致力于为所有人提供一个热情且鼓舞人心的社区。我们承诺，参与本社区的每个人都应拥有免受骚扰的体验，不论其年龄、身体大小、种姓、残障、族裔、性别特征、性别认同与表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教，或性取向与性身份如何。 + +我们致力于打造一个积极、包容且安全的环境，让所有贡献者都感到被尊重、被重视，并能充分发挥自己的能力。 + +## 我们的标准 + +有助于营造积极环境的行为包括： + +### 保持尊重 +- 使用热情且包容的语言 +- 尊重不同的观点、立场和经历 +- 愉快地接受建设性批评 +- 尊重文化和语言差异 +- 认可并庆祝多元背景 + +### 保持协作 +- 共同解决冲突 +- 给予他人应得的署名和认可 +- 帮助他人学习和成长 +- 分享知识并积极提问 +- 支持社区里的其他成员 + +### 保持专业 +- 保持讨论聚焦且高效 +- 避免贬低或侮辱性言论 +- 在 issue 和 discussion 中保持主题相关 +- 使用清晰且尊重的沟通方式 +- 假设他人的消息都出于善意 + +### 保持包容 +- 欢迎新贡献者 +- 帮助刚接触项目的人上手 +- 提供建设性的反馈 +- 接纳不同视角的人 +- 为安静的声音创造被听见的空间 + +## 不可接受的行为 + +以下行为被视为骚扰，在本社区中不可接受： + +### 骚扰与歧视 +- 与性别、性别认同与表达、性取向、残障、心理疾病、神经类型、外貌、体型、年龄、种族或宗教相关的冒犯性言论 +- 关于某人生活方式或生活选择的不受欢迎评论 +- 故意使用错误称谓，或使用“死名”或被拒绝的名字 +- 与主题无关的露骨性图像或行为 +- 未经同意或在要求停止后仍进行肢体接触或模拟肢体接触 + +### 滥用行为 +- 指向他人的暴力威胁或暴力言论 +- 唆使暴力或针对个人的暴力言论 +- 故意恐吓 +- 跟踪或尾随 +- 反复联系造成骚扰 +- 任何其他合理上可视为不当的行为 + +### 线上骚扰 +- 持续干扰在线讨论 +- 发布他人隐私信息（人肉搜索 / doxxing） +- 不受欢迎的性关注或性骚扰 +- 刷屏、挑衅或故意捣乱 +- 垃圾广告或重复性宣传 +- 散布错误信息或虚假信息 + +### 报复 +- 因他人举报违规而采取报复行动 +- 因他人举报不当行为而区别对待 +- 以举报作为威胁 + +## 适用范围 + +本行为准则适用于： +- 所有社区空间（GitHub issues、pull requests、discussions 等） +- 项目仓库和文档 +- 由项目组织或代表项目参加的活动和聚会 +- 代表项目或社区的公共场合 +- 与项目事务相关的私人沟通 + +本行为准则适用于所有项目空间；当个人在公共场合代表项目或社区时，也同样适用。代表项目或社区的例子包括使用官方项目邮箱、通过官方社交账号发帖，或在线上/线下活动中担任指定代表。 + +## 执行 + +社区负责人负责澄清并执行可接受行为标准，并会针对任何被认为不当、具有威胁性、冒犯性或有害的行为采取适当且公正的纠正措施。 + +### 举报违规 + +如果你经历或目睹了不可接受的行为，或者有其他担忧，请通过以下方式报告： + +1. **Email**：联系项目维护者（如可用，请填写联系方式） +2. **GitHub Issues**：使用私密举报功能（如果你的 GitHub 设置中可用） +3. **直接消息**：直接联系项目维护者 + +请提供： +- 你的联系方式 +- 涉及人员的姓名（如果你愿意提供） +- 事件描述 +- 上下文和相关链接 +- 事件对你的影响 + +**所有报告都会被保密。** + +### 调查与响应 + +社区负责人将： +- 及时且公正地审查和调查所有投诉 +- 对举报人保持保密 +- 向举报人反馈处理进展 +- 根据调查结果采取适当行动 + +可能的措施包括： +- 私下警告或辅导 +- 公开道歉（若违规者同意） +- 暂时或永久移出社区空间 +- 取消贡献者权限 +- 必要时升级至 GitHub 或其他平台 + +### 申诉流程 + +如果你认为某项决定有误，可以通过以下方式申诉： +1. 提供新的信息或上下文 +2. 请求多位维护者复核 +3. 在初次决定后的 30 天内跟进 + +## 如何尊重地表达分歧 + +技术社区中出现分歧是正常的。以下是尊重地表达不同意见的方法： + +### 应该做的 +- ✅ 聚焦观点，而不是人 +- ✅ 询问澄清问题 +- ✅ 承认对立观点中的合理之处 +- ✅ 使用 “我” 陈述（例如：“我不同意，因为……”） +- ✅ 引用来源和证据 +- ✅ 感谢他人的观点 + +### 不应该做的 +- ❌ 人身攻击 +- ❌ 使用贬低性语言（如“这太蠢了”） +- ❌ 预设他人恶意 +- ❌ 提及无关的过往冲突 +- ❌ 升级语气或变得敌对 +- ❌ 故意歪曲他人观点 + +### 尊重分歧示例 +``` +❌ 不好：“这是个愚蠢的想法，你显然不了解这个项目。” + +✅ 更好：“我理解你的意思，但我担心这种做法在更大的项目里可能 +不太能扩展。你考虑过这个基准测试里展示的性能影响吗？我很想听听 +你的看法。” +``` + +## 搭建桥梁 + +我们相信对话与和解的力量： + +- 如果别人指出你的行为问题，请认真倾听并反思 +- 如果你造成了伤害，愿意道歉 +- 支持他人的学习和成长 +- 记住每个人都会犯错 +- 聚焦解决方案，而不是归咎 +- 在坚持责任的同时，保持善意 + +## 遵守本准则的好处 + +通过维护一个尊重且包容的社区，我们能够： +- 吸引拥有不同视角的贡献者 +- 通过协作产出更好的解决方案 +- 建立更牢固的关系 +- 让项目对新成员更友好 +- 产出更高质量的文档和示例 +- 培养学习与成长的文化 + +## 特别说明 + +### 对维护者 +- 以身作则，遵守本准则 +- 对举报保持响应 +- 在决策上保持透明 +- 帮助公正地解决冲突 +- 为所有人创造安全环境 + +### 对贡献者 +- 假设维护者和其他贡献者都怀有善意 +- 提供建设性的反馈 +- 支持新成员 +- 帮助维护社区标准 +- 对社区文化承担责任 + +### 对所有人 +- 记住每条消息背后都是一个人 +- 如果感到沮丧，先暂停一下 +- 需要支持时请联系社区负责人 +- 帮助创造你希望参与的社区 + +## 来源说明 + +本行为准则参考并改编自： +- [Contributor Covenant](https://www.contributor-covenant.org/) +- [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) +- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) + +## 有问题？ + +如果你对本行为准则有任何疑问，请联系项目维护者。 + +## 版本历史 + +- **版本 1.0**（2026 年 1 月）- 初始行为准则 + +--- + +**感谢你帮助我们打造一个热情、包容且互相尊重的社区！** 🌟 diff --git a/zh/CONTRIBUTING.md b/zh/CONTRIBUTING.md new file mode 100644 index 0000000..bffded9 --- /dev/null +++ b/zh/CONTRIBUTING.md @@ -0,0 +1,378 @@ + + + Claude How To + + +# 为 Claude How To 贡献内容 + +感谢你愿意为这个项目做出贡献。这份指南会帮助你更高效地参与协作。 + +## 关于本项目 + +Claude How To 是一份面向 Claude Code 的可视化、以示例驱动的学习指南。我们提供： +- **Mermaid 图表**，解释各项功能的工作方式 +- **可直接投入使用的模板**，你可以马上复制到项目中 +- **带上下文和最佳实践的真实案例** +- **从入门到进阶的渐进式学习路径** + +## 贡献类型 + +### 1. 新示例或新模板 +为已有功能补充示例，例如 slash commands、skills、hooks 等： +- 可直接复制粘贴的代码 +- 清楚说明工作原理 +- 使用场景与收益 +- 排障提示 + +### 2. 文档改进 +- 澄清容易混淆的内容 +- 修复拼写和语法问题 +- 补充缺失信息 +- 优化代码示例 + +### 3. 功能指南 +为新的 Claude Code 功能编写指南： +- 分步骤教程 +- 架构图 +- 常见模式和反模式 +- 真实工作流 + +### 4. Bug 报告 +报告你遇到的问题： +- 你原本期望发生什么 +- 实际发生了什么 +- 复现步骤 +- 相关的 Claude Code 版本和操作系统 + +### 5. 反馈与建议 +帮助我们改进这份指南： +- 建议更好的解释方式 +- 指出覆盖不足的地方 +- 推荐新章节或重组结构 + +## 快速开始 + +### 1. Fork 并克隆 +```bash +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto +``` + +### 2. 创建分支 +使用能说明用途的分支名： +```bash +git checkout -b add/feature-name +git checkout -b fix/issue-description +git checkout -b docs/improvement-area +``` + +### 3. 配置开发环境 + +pre-commit hooks 会在本地、每次提交前运行与 CI 相同的检查。PR 被接受前，下面四项检查都必须通过。 + +**必需依赖：** + +```bash +# Python 工具链（uv 是本项目的包管理器） +pip install uv +uv venv +source .venv/bin/activate +uv pip install -r scripts/requirements-dev.txt + +# Markdown lint 工具（Node.js） +npm install -g markdownlint-cli + +# Mermaid 图表校验器（Node.js） +npm install -g @mermaid-js/mermaid-cli + +# 安装 pre-commit 并启用 hooks +uv pip install pre-commit +pre-commit install +``` + +**验证配置：** + +```bash +pre-commit run --all-files +``` + +每次提交都会运行这些 hooks： + +| Hook | 检查内容 | +|------|----------| +| `markdown-lint` | Markdown 格式和结构 | +| `cross-references` | 相对链接、锚点、代码围栏 | +| `mermaid-syntax` | 所有 ` ```mermaid ` 代码块是否可正确解析 | +| `link-check` | 外部 URL 是否可访问 | +| `build-epub` | `.md` 变更时 EPUB 是否能无错误生成 | + +## 目录结构 + +``` +├── 01-slash-commands/ # 用户手动触发的快捷命令 +├── 02-memory/ # 持久上下文示例 +├── 03-skills/ # 可复用能力 +├── 04-subagents/ # 专门化 AI 助手 +├── 05-mcp/ # Model Context Protocol 示例 +├── 06-hooks/ # 事件驱动自动化 +├── 07-plugins/ # 打包功能集合 +├── 08-checkpoints/ # 会话快照 +├── 09-advanced-features/ # 规划、思考、后台任务 +├── 10-cli/ # CLI 参考 +├── scripts/ # 构建与工具脚本 +└── README.md # 主指南 +``` + +## 如何贡献示例 + +### 添加 Slash Command +1. 在 `01-slash-commands/` 中创建一个 `.md` 文件 +2. 包含： + - 清晰说明用途 + - 使用场景 + - 安装说明 + - 使用示例 + - 自定义技巧 +3. 更新 `01-slash-commands/README.md` + +### 添加 Skill +1. 在 `03-skills/` 中创建一个目录 +2. 包含： + - `SKILL.md` - 主文档 + - `scripts/` - 如有需要可放辅助脚本 + - `templates/` - 提示词模板 + - README 中的示例用法 +3. 更新 `03-skills/README.md` + +### 添加 Subagent +1. 在 `04-subagents/` 中创建一个 `.md` 文件 +2. 包含： + - agent 的目标和能力 + - 系统提示词结构 + - 示例使用场景 + - 集成示例 +3. 更新 `04-subagents/README.md` + +### 添加 MCP 配置 +1. 在 `05-mcp/` 中创建一个 `.json` 文件 +2. 包含： + - 配置说明 + - 所需环境变量 + - 配置步骤 + - 使用示例 +3. 更新 `05-mcp/README.md` + +### 添加 Hook +1. 在 `06-hooks/` 中创建一个 `.sh` 文件 +2. 包含： + - shebang 和说明 + - 逻辑清晰的注释 + - 错误处理 + - 安全考虑 +3. 更新 `06-hooks/README.md` + +## 编写规范 + +### Markdown 风格 +- 使用清晰的标题层级（章节用 H2，小节用 H3） +- 段落保持简短且聚焦 +- 列表用项目符号 +- 代码块要标明语言 +- 各章节之间保留空行 + +### 代码示例 +- 示例要能直接复制粘贴 +- 为不明显的逻辑添加注释 +- 同时提供简单版和进阶版 +- 展示真实使用场景 +- 标出可能的坑 + +### 文档写作 +- 解释“为什么”，而不只是“是什么” +- 包含前置条件 +- 添加排障章节 +- 链接相关主题 +- 保持对初学者友好 + +### JSON/YAML +- 统一缩进风格（2 或 4 个空格） +- 为配置添加注释 +- 包含验证示例 + +### 图表 +- 尽量使用 Mermaid +- 保持图表简洁易读 +- 在图表下方补充说明 +- 链接到相关章节 + +## Commit 规范 + +使用 conventional commit 格式： +``` +type(scope): description + +[optional body] +``` + +类型包括： +- `feat`：新功能或新示例 +- `fix`：修复或更正 +- `docs`：文档变更 +- `refactor`：代码重构 +- `style`：格式调整 +- `test`：新增或修改测试 +- `chore`：构建、依赖等 + +示例： +``` +feat(slash-commands): Add API documentation generator +docs(memory): Improve personal preferences example +fix(README): Correct table of contents link +docs(skills): Add comprehensive code review skill +``` + +## 提交前检查 + +### 清单 +- [ ] 代码符合项目风格与约定 +- [ ] 新示例附带清晰文档 +- [ ] README 已更新（本地和根目录） +- [ ] 不包含敏感信息（API key、凭据） +- [ ] 示例经过测试并可运行 +- [ ] 链接已验证且正确 +- [ ] 文件权限正确（脚本可执行） +- [ ] Commit 信息清晰且有描述性 + +### 本地测试 +```bash +# 运行所有 pre-commit 检查（与 CI 相同） +pre-commit run --all-files + +# 查看改动 +git diff +``` + +## Pull Request 流程 + +1. **创建带有清晰说明的 PR**： + - 这次提交做了什么？ + - 为什么需要它？ + - 是否有关联 issue？ + +2. **补充相关细节**： + - 新功能？请说明使用场景 + - 文档？请说明改进点 + - 示例？展示前后对比 + +3. **关联 issue**： + - 使用 `Closes #123` 自动关闭相关 issue + +4. **耐心等待审查**： + - 维护者可能会提出改进建议 + - 根据反馈迭代 + - 最终决定由维护者负责 + +## Code Review 流程 + +审查者会检查： +- **准确性**：描述是否与实际一致？ +- **质量**：是否达到生产可用？ +- **一致性**：是否符合项目模式？ +- **文档**：是否清晰完整？ +- **安全性**：是否存在漏洞？ + +## 报告问题 + +### Bug 报告 +请包含： +- Claude Code 版本 +- 操作系统 +- 复现步骤 +- 预期行为 +- 实际行为 +- 如有必要，附上截图 + +### 功能请求 +请包含： +- 使用场景或要解决的问题 +- 建议方案 +- 你考虑过的替代方案 +- 额外上下文 + +### 文档问题 +请包含： +- 哪里令人困惑或缺失 +- 建议如何改进 +- 示例或参考资料 + +## 项目政策 + +### 敏感信息 +- 永远不要提交 API key、token 或凭据 +- 示例中使用占位符 +- 为配置文件提供 `.env.example` +- 文档中说明所需环境变量 + +### 代码质量 +- 示例要聚焦且易读 +- 避免过度设计 +- 对不明显的逻辑添加注释 +- 提交前充分测试 + +### 知识产权 +- 原创内容归作者所有 +- 项目采用教育用途许可证 +- 尊重已有版权 +- 需要时注明来源 + +## 获取帮助 + +- **提问**：在 GitHub Issues 中发起 discussion +- **通用帮助**：先查看现有文档 +- **开发帮助**：参考类似示例 +- **Code Review**：在 PR 中 @ 维护者 + +## 认可 + +贡献者会被收录在： +- `README.md` 的 Contributors 部分 +- GitHub contributors 页面 +- Commit 历史 + +## 安全 + +在贡献示例和文档时，请遵守安全编码实践： + +- **绝不要硬编码密钥或 API key** - 使用环境变量 +- **提示安全影响** - 标出潜在风险 +- **使用安全默认值** - 默认启用安全功能 +- **验证输入** - 展示正确的输入校验和清理方式 +- **加入安全提示** - 记录安全注意事项 + +如遇安全问题，请参见 [SECURITY.md](SECURITY.md) 获取漏洞报告流程。 + +## 行为准则 + +我们承诺打造一个热情且包容的社区。请阅读 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 查看完整社区标准。 + +简要来说： +- 保持尊重和包容 +- 愉快地接受反馈 +- 帮助他人成长和学习 +- 避免骚扰或歧视 +- 向维护者报告问题 + +所有贡献者都应遵守这份准则，并以善意和尊重对待彼此。 + +## 许可证 + +为本项目贡献内容，即表示你同意你的贡献将按 MIT License 许可。详情见 [LICENSE](LICENSE) 文件。 + +## 有问题？ + +- 查看 [README.md](README.md) +- 阅读 [LEARNING-ROADMAP.md](LEARNING-ROADMAP.md) +- 查看已有示例 +- 发起 issue 讨论 + +感谢你的贡献！ diff --git a/zh/INDEX.md b/zh/INDEX.md new file mode 100644 index 0000000..4f28844 --- /dev/null +++ b/zh/INDEX.md @@ -0,0 +1,900 @@ + + + Claude How To + + +# Claude Code 示例 - 完整索引 + +这份文档是仓库里所有示例文件的完整索引，按功能类型整理，方便你快速定位需要的内容。 + +## 概览统计 + +- **总文件数**：100+ 文件 +- **分类数**：10 个功能分类 +- **插件**：3 个完整插件 +- **Skills**：6 个完整 skills +- **Hooks**：8 个示例 hook +- **可直接使用**：所有示例都可直接拿来用 + +--- + +## 01. Slash Commands（10 个文件） + +用于常见工作流的用户触发快捷命令。 + +| 文件 | 说明 | 使用场景 | +|------|------|----------| +| `optimize.md` | 代码优化分析器 | 查找性能问题 | +| `pr.md` | Pull Request 准备 | PR 工作流自动化 | +| `generate-api-docs.md` | API 文档生成器 | 生成 API 文档 | +| `commit.md` | 提交信息助手 | 统一提交风格 | +| `setup-ci-cd.md` | CI/CD 流水线设置 | DevOps 自动化 | +| `push-all.md` | 推送所有变更 | 快速推送工作流 | +| `unit-test-expand.md` | 扩展单元测试覆盖率 | 测试自动化 | +| `doc-refactor.md` | 文档重构 | 文档优化 | +| `pr-slash-command.png` | 截图示例 | 视觉参考 | +| `README.md` | 文档 | 安装与使用指南 | + +**安装路径**：`.claude/commands/` + +**使用方式**：`/optimize`、`/pr`、`/generate-api-docs`、`/commit`、`/setup-ci-cd`、`/push-all`、`/unit-test-expand`、`/doc-refactor` + +--- + +## 02. Memory（6 个文件） + +持久化上下文和项目规范。 + +| 文件 | 说明 | 范围 | 位置 | +|------|------|------|------| +| `project-CLAUDE.md` | 团队项目规范 | 整个项目 | `./CLAUDE.md` | +| `directory-api-CLAUDE.md` | API 专用规则 | 目录级 | `./src/api/CLAUDE.md` | +| `personal-CLAUDE.md` | 个人偏好 | 用户级 | `~/.claude/CLAUDE.md` | +| `memory-saved.png` | 截图：记忆已保存 | - | 视觉参考 | +| `memory-ask-claude.png` | 截图：询问 Claude | - | 视觉参考 | +| `README.md` | 文档 | - | 参考说明 | + +**安装方式**：复制到对应位置 + +**使用方式**：Claude 会自动加载 + +--- + +## 03. Skills（28 个文件） + +带脚本和模板的自动触发能力。 + +### 代码审查 Skill（5 个文件） + +```text +code-review/ +├── SKILL.md # Skill 定义 +├── scripts/ +│ ├── analyze-metrics.py # 代码指标分析器 +│ └── compare-complexity.py # 复杂度对比 +└── templates/ + ├── review-checklist.md # 审查清单 + └── finding-template.md # 问题记录模板 +``` + +**用途**：结合安全、性能和质量分析的完整代码审查 + +**自动触发**：在审查代码时 + +### 品牌语气 Skill（4 个文件） + +```text +brand-voice/ +├── SKILL.md # Skill 定义 +├── templates/ +│ ├── email-template.txt # 邮件格式 +│ └── social-post-template.txt # 社交媒体格式 +└── tone-examples.md # 示例消息 +``` + +**用途**：确保对外沟通中的品牌语气一致 + +**自动触发**：在编写营销文案时 + +### 文档生成 Skill（2 个文件） + +```text +doc-generator/ +├── SKILL.md # Skill 定义 +└── generate-docs.py # Python 文档提取器 +``` + +**用途**：从源代码生成完整的 API 文档 + +**自动触发**：在创建或更新 API 文档时 + +### 重构 Skill（5 个文件） + +```text +refactor/ +├── SKILL.md # Skill 定义 +├── scripts/ +│ ├── analyze-complexity.py # 复杂度分析器 +│ └── detect-smells.py # 代码异味检测器 +├── references/ +│ ├── code-smells.md # 代码异味目录 +│ └── refactoring-catalog.md # 重构模式目录 +└── templates/ + └── refactoring-plan.md # 重构计划模板 +``` + +**用途**：结合复杂度分析进行系统化代码重构 + +**自动触发**：在重构代码时 + +### Claude MD Skill（1 个文件） + +```text +claude-md/ +└── SKILL.md # Skill 定义 +``` + +**用途**：管理和优化 `CLAUDE.md` 文件 + +### 博客草稿 Skill（3 个文件） + +```text +blog-draft/ +├── SKILL.md # Skill 定义 +└── templates/ + ├── draft-template.md # 博客草稿模板 + └── outline-template.md # 博客大纲模板 +``` + +**用途**：生成结构统一的博客草稿 + +**补充**：`README.md` - Skills 总览与使用指南 + +**安装路径**：`~/.claude/skills/` 或 `.claude/skills/` + +--- + +## 04. Subagents（9 个文件） + +带自定义能力的专门化 AI 助手。 + +| 文件 | 说明 | 工具 | 使用场景 | +|------|------|------|----------| +| `code-reviewer.md` | 代码质量分析 | read, grep, diff, lint_runner | 完整审查 | +| `test-engineer.md` | 测试覆盖分析 | read, write, bash, grep | 测试自动化 | +| `documentation-writer.md` | 文档创建 | read, write, grep | 文档生成 | +| `secure-reviewer.md` | 安全审查（只读） | read, grep | 安全审计 | +| `implementation-agent.md` | 完整实现 | read, write, bash, grep, edit, glob | 功能开发 | +| `debugger.md` | 调试专家 | read, bash, grep | Bug 排查 | +| `data-scientist.md` | 数据分析专家 | read, write, bash | 数据工作流 | +| `clean-code-reviewer.md` | 代码整洁性规范 | read, grep | 代码质量 | +| `README.md` | 文档 | - | 安装与使用指南 | + +**安装路径**：`.claude/agents/` + +**使用方式**：由主 agent 自动委派 + +--- + +## 05. MCP Protocol（5 个文件） + +外部工具和 API 集成。 + +| 文件 | 说明 | 集成对象 | 使用场景 | +|------|------|----------|----------| +| `github-mcp.json` | GitHub 集成 | GitHub API | PR / issue 管理 | +| `database-mcp.json` | 数据库查询 | PostgreSQL / MySQL | 实时数据查询 | +| `filesystem-mcp.json` | 文件操作 | 本地文件系统 | 文件管理 | +| `multi-mcp.json` | 多服务器配置 | GitHub + DB + Slack | 完整集成 | +| `README.md` | 文档 | - | 安装与使用指南 | + +**安装路径**：项目级 `.mcp.json` 或用户级 `~/.claude.json` + +**使用方式**：例如 `/mcp__github__list_prs` + +--- + +## 06. Hooks（9 个文件） + +事件驱动的自动化脚本，会自动执行。 + +| 文件 | 说明 | 事件 | 使用场景 | +|------|------|------|----------| +| `format-code.sh` | 自动格式化代码 | `PreToolUse:Write` | 代码格式化 | +| `pre-commit.sh` | 提交前运行测试 | `PreToolUse:Bash` | 测试自动化 | +| `security-scan.sh` | 安全扫描 | `PostToolUse:Write` | 安全检查 | +| `log-bash.sh` | 记录 bash 命令 | `PostToolUse:Bash` | 命令日志 | +| `validate-prompt.sh` | 验证提示词 | `PreToolUse` | 输入校验 | +| `notify-team.sh` | 发送通知 | `Notification` | 团队通知 | +| `context-tracker.py` | 跟踪上下文窗口使用量 | `PostToolUse` | 上下文监控 | +| `context-tracker-tiktoken.py` | 基于 token 的上下文跟踪 | `PostToolUse` | 精确 token 统计 | +| `README.md` | 文档 | - | 安装与使用指南 | + +**安装路径**：在 `~/.claude/settings.json` 中配置 + +**使用方式**：在设置中配置后自动执行 + +**Hook 类型**（4 类，25 个事件）： +- 工具 Hook：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` +- 会话 Hook：`SessionStart`、`SessionEnd`、`Stop`、`StopFailure`、`SubagentStart`、`SubagentStop` +- 任务 Hook：`UserPromptSubmit`、`TaskCompleted`、`TaskCreated`、`TeammateIdle` +- 生命周期 Hook：`ConfigChange`、`CwdChanged`、`FileChanged`、`PreCompact`、`PostCompact`、`WorktreeCreate`、`WorktreeRemove`、`Notification`、`InstructionsLoaded`、`Elicitation`、`ElicitationResult` + +--- + +## 07. Plugins（3 个完整插件，40 个文件） + +打包好的功能集合。 + +### PR Review 插件（10 个文件） + +```text +pr-review/ +├── .claude-plugin/ +│ └── plugin.json # 插件清单 +├── commands/ +│ ├── review-pr.md # 综合审查 +│ ├── check-security.md # 安全检查 +│ └── check-tests.md # 测试覆盖检查 +├── agents/ +│ ├── security-reviewer.md # 安全专家 +│ ├── test-checker.md # 测试专家 +│ └── performance-analyzer.md # 性能专家 +├── mcp/ +│ └── github-config.json # GitHub 集成 +├── hooks/ +│ └── pre-review.js # 审查前校验 +└── README.md # 插件文档 +``` + +**功能**：安全分析、测试覆盖、性能影响 + +**命令**：`/review-pr`、`/check-security`、`/check-tests` + +**安装**：`/plugin install pr-review` + +### DevOps Automation 插件（15 个文件） + +```text +devops-automation/ +├── .claude-plugin/ +│ └── plugin.json # 插件清单 +├── commands/ +│ ├── deploy.md # 部署 +│ ├── rollback.md # 回滚 +│ ├── status.md # 系统状态 +│ └── incident.md # 事件响应 +├── agents/ +│ ├── deployment-specialist.md # 部署专家 +│ ├── incident-commander.md # 事件协调 +│ └── alert-analyzer.md # 告警分析 +├── mcp/ +│ └── kubernetes-config.json # Kubernetes 集成 +├── hooks/ +│ ├── pre-deploy.js # 部署前检查 +│ └── post-deploy.js # 部署后任务 +├── scripts/ +│ ├── deploy.sh # 部署自动化 +│ ├── rollback.sh # 回滚自动化 +│ └── health-check.sh # 健康检查 +└── README.md # 插件文档 +``` + +**功能**：Kubernetes 部署、回滚、监控、事件响应 + +**命令**：`/deploy`、`/rollback`、`/status`、`/incident` + +**安装**：`/plugin install devops-automation` + +### Documentation 插件（14 个文件） + +```text +documentation/ +├── .claude-plugin/ +│ └── plugin.json # 插件清单 +├── commands/ +│ ├── generate-api-docs.md # API 文档生成 +│ ├── generate-readme.md # README 创建 +│ ├── sync-docs.md # 文档同步 +│ └── validate-docs.md # 文档校验 +├── agents/ +│ ├── api-documenter.md # API 文档专家 +│ ├── code-commentator.md # 代码注释专家 +│ └── example-generator.md # 示例生成器 +├── mcp/ +│ └── github-docs-config.json # GitHub 集成 +├── templates/ +│ ├── api-endpoint.md # API 端点模板 +│ ├── function-docs.md # 函数文档模板 +│ └── adr-template.md # ADR 模板 +└── README.md # 插件文档 +``` + +**功能**：API 文档、README 生成、文档同步、文档校验 + +**命令**：`/generate-api-docs`、`/generate-readme`、`/sync-docs`、`/validate-docs` + +**安装**：`/plugin install documentation` + +**补充**：`README.md` - 插件总览与使用指南 + +--- + +## 08. Checkpoints and Rewind（2 个文件） + +保存会话状态，并探索替代方案。 + +| 文件 | 说明 | 内容 | +|------|------|------| +| `README.md` | 文档 | 完整的 checkpoint 指南 | +| `checkpoint-examples.md` | 真实示例 | 数据库迁移、性能优化、UI 迭代、调试 | + +**核心概念**： +- **Checkpoint**：会话状态快照 +- **Rewind**：回到之前的 checkpoint +- **Branch Point**：探索多种方案 + +**使用方式**： + +```bash +# 每次用户提示后都会自动创建 checkpoint +# 如需回退，按两次 Esc，或使用： +/rewind +# 然后选择：恢复代码和对话、恢复对话、 +# 恢复代码、从这里开始总结，或算了 +``` + +**使用场景**： +- 尝试不同实现方式 +- 从错误中恢复 +- 安全试验 +- 比较不同方案 +- A/B 测试 + +--- + +## 09. Advanced Features（3 个文件） + +复杂工作流下的高级能力。 + +| 文件 | 说明 | 功能 | +|------|------|------| +| `README.md` | 完整指南 | 全部高级功能说明 | +| `config-examples.json` | 配置示例 | 10+ 个场景化配置 | +| `planning-mode-examples.md` | 规划示例 | REST API、数据库迁移、重构 | + +**扩展功能**： +- Scheduled Tasks：使用 `/loop` 和 cron 工具的周期任务 +- Chrome Integration：通过无头 Chromium 做浏览器自动化 +- Remote Control（扩展版）：连接方式、安全性、对比表 +- Keyboard Customization：自定义快捷键、组合键支持、上下文 +- Desktop App（扩展版）：连接器、`launch.json`、企业功能 + +### 已覆盖的高级功能 + +#### Planning Mode +- 编写详细实现计划 +- 时间预估与风险评估 +- 系统化拆解任务 + +#### Extended Thinking +- 面向复杂问题的深度推理 +- 架构决策分析 +- 权衡取舍评估 + +#### Background Tasks +- 长时间运行且不阻塞当前会话 +- 并行开发工作流 +- 任务管理与监控 + +#### Permission Modes +- **default**：风险操作需要审批 +- **acceptEdits**：自动接受文件编辑，其他操作仍需审批 +- **plan**：只读分析，不做修改 +- **auto**：自动批准安全操作，风险操作仍提示 +- **dontAsk**：除危险操作外全部接受 +- **bypassPermissions**：全部接受（需要 `--dangerously-skip-permissions`） + +#### Headless Mode（`claude -p`） +- CI/CD 集成 +- 自动化任务执行 +- 批处理 + +#### Session Management +- 多会话管理 +- 会话切换与保存 +- 会话持久化 + +#### 交互功能 +- 键盘快捷键 +- 命令历史 +- Tab 补全 +- 多行输入 + +#### 配置 +- 完整设置管理 +- 环境相关配置 +- 按项目定制 + +#### Scheduled Tasks +- 使用 `/loop` 创建周期任务 +- Cron 工具：`CronCreate`、`CronList`、`CronDelete` +- 自动化的重复工作流 + +#### Chrome Integration +- 通过无头 Chromium 进行浏览器自动化 +- 页面测试与抓取能力 +- 页面交互与数据提取 + +#### Remote Control（扩展版） +- 连接方式与协议 +- 安全注意事项与最佳实践 +- 远程访问方案对比表 + +#### Keyboard Customization +- 自定义按键绑定配置 +- 支持多键组合快捷键 +- 基于上下文的按键激活 + +#### Desktop App（扩展版） +- 用于 IDE 集成的连接器 +- `launch.json` 配置 +- 企业功能与部署 + +--- + +## 10. CLI Usage（1 个文件） + +命令行界面使用方式与参考。 + +| 文件 | 说明 | 内容 | +|------|------|------| +| `README.md` | CLI 文档 | 参数、选项与使用模式 | + +**核心 CLI 功能**： +- `claude` - 启动交互式会话 +- `claude -p "prompt"` - 无头/非交互模式 +- `claude web` - 打开 Web 会话 +- `claude --model` - 选择模型（Sonnet 4.6、Opus 4.6） +- `claude --permission-mode` - 设置权限模式 +- `claude --remote` - 通过 WebSocket 启用远程控制 + +--- + +## 文档文件（13 个文件） + +| 文件 | 位置 | 说明 | +|------|------|------| +| `README.md` | `/` | 主总览 | +| `INDEX.md` | `/` | 本完整索引 | +| `QUICK_REFERENCE.md` | `/` | 速查卡片 | +| `README.md` | `/01-slash-commands/` | Slash Commands 指南 | +| `README.md` | `/02-memory/` | Memory 指南 | +| `README.md` | `/03-skills/` | Skills 指南 | +| `README.md` | `/04-subagents/` | Subagents 指南 | +| `README.md` | `/05-mcp/` | MCP 指南 | +| `README.md` | `/06-hooks/` | Hooks 指南 | +| `README.md` | `/07-plugins/` | Plugins 指南 | +| `README.md` | `/08-checkpoints/` | Checkpoints 指南 | +| `README.md` | `/09-advanced-features/` | Advanced Features 指南 | +| `README.md` | `/10-cli/` | CLI 指南 | + +--- + +## 完整文件树 + +```text +claude-howto/ +├── README.md # 主总览 +├── INDEX.md # 本文件 +├── QUICK_REFERENCE.md # 速查卡片 +├── claude_concepts_guide.md # 原始指南 +│ +├── 01-slash-commands/ # Slash Commands +│ ├── optimize.md +│ ├── pr.md +│ ├── generate-api-docs.md +│ ├── commit.md +│ ├── setup-ci-cd.md +│ ├── push-all.md +│ ├── unit-test-expand.md +│ ├── doc-refactor.md +│ ├── pr-slash-command.png +│ └── README.md +│ +├── 02-memory/ # Memory +│ ├── project-CLAUDE.md +│ ├── directory-api-CLAUDE.md +│ ├── personal-CLAUDE.md +│ ├── memory-saved.png +│ ├── memory-ask-claude.png +│ └── README.md +│ +├── 03-skills/ # Skills +│ ├── code-review/ +│ │ ├── SKILL.md +│ │ ├── scripts/ +│ │ │ ├── analyze-metrics.py +│ │ │ └── compare-complexity.py +│ │ └── templates/ +│ │ ├── review-checklist.md +│ │ └── finding-template.md +│ ├── brand-voice/ +│ │ ├── SKILL.md +│ │ ├── templates/ +│ │ │ ├── email-template.txt +│ │ │ └── social-post-template.txt +│ │ └── tone-examples.md +│ ├── doc-generator/ +│ │ ├── SKILL.md +│ │ └── generate-docs.py +│ ├── refactor/ +│ │ ├── SKILL.md +│ │ ├── scripts/ +│ │ │ ├── analyze-complexity.py +│ │ │ └── detect-smells.py +│ │ ├── references/ +│ │ │ ├── code-smells.md +│ │ │ └── refactoring-catalog.md +│ │ └── templates/ +│ │ └── refactoring-plan.md +│ ├── claude-md/ +│ │ └── SKILL.md +│ ├── blog-draft/ +│ │ ├── SKILL.md +│ │ └── templates/ +│ │ ├── draft-template.md +│ │ └── outline-template.md +│ └── README.md +│ +├── 04-subagents/ # Subagents +│ ├── code-reviewer.md +│ ├── test-engineer.md +│ ├── documentation-writer.md +│ ├── secure-reviewer.md +│ ├── implementation-agent.md +│ ├── debugger.md +│ ├── data-scientist.md +│ ├── clean-code-reviewer.md +│ └── README.md +│ +├── 05-mcp/ # MCP Protocol +│ ├── github-mcp.json +│ ├── database-mcp.json +│ ├── filesystem-mcp.json +│ ├── multi-mcp.json +│ └── README.md +│ +├── 06-hooks/ # Hooks +│ ├── format-code.sh +│ ├── pre-commit.sh +│ ├── security-scan.sh +│ ├── log-bash.sh +│ ├── validate-prompt.sh +│ ├── notify-team.sh +│ ├── context-tracker.py +│ ├── context-tracker-tiktoken.py +│ └── README.md +│ +├── 07-plugins/ # Plugins +│ ├── pr-review/ +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json +│ │ ├── commands/ +│ │ │ ├── review-pr.md +│ │ │ ├── check-security.md +│ │ │ └── check-tests.md +│ │ ├── agents/ +│ │ │ ├── security-reviewer.md +│ │ │ ├── test-checker.md +│ │ │ └── performance-analyzer.md +│ │ ├── mcp/ +│ │ │ └── github-config.json +│ │ ├── hooks/ +│ │ │ └── pre-review.js +│ │ └── README.md +│ ├── devops-automation/ +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json +│ │ ├── commands/ +│ │ │ ├── deploy.md +│ │ │ ├── rollback.md +│ │ │ ├── status.md +│ │ │ └── incident.md +│ │ ├── agents/ +│ │ │ ├── deployment-specialist.md +│ │ │ ├── incident-commander.md +│ │ │ └── alert-analyzer.md +│ │ ├── mcp/ +│ │ │ └── kubernetes-config.json +│ │ ├── hooks/ +│ │ │ ├── pre-deploy.js +│ │ │ └── post-deploy.js +│ │ ├── scripts/ +│ │ │ ├── deploy.sh +│ │ │ ├── rollback.sh +│ │ │ └── health-check.sh +│ │ └── README.md +│ ├── documentation/ +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json +│ │ ├── commands/ +│ │ │ ├── generate-api-docs.md +│ │ │ ├── generate-readme.md +│ │ │ ├── sync-docs.md +│ │ │ └── validate-docs.md +│ │ ├── agents/ +│ │ │ ├── api-documenter.md +│ │ │ ├── code-commentator.md +│ │ │ └── example-generator.md +│ │ ├── mcp/ +│ │ │ └── github-docs-config.json +│ │ ├── templates/ +│ │ │ ├── api-endpoint.md +│ │ │ ├── function-docs.md +│ │ │ └── adr-template.md +│ │ └── README.md +│ └── README.md +│ +├── 08-checkpoints/ # Checkpoints +│ ├── checkpoint-examples.md +│ └── README.md +│ +├── 09-advanced-features/ # Advanced Features +│ ├── config-examples.json +│ ├── planning-mode-examples.md +│ └── README.md +│ +└── 10-cli/ # CLI 使用 + └── README.md +``` + +--- + +## 按使用场景快速开始 + +### 代码质量与审查 + +```bash +# 安装 slash command +cp 01-slash-commands/optimize.md .claude/commands/ + +# 安装 subagent +cp 04-subagents/code-reviewer.md .claude/agents/ + +# 安装 skill +cp -r 03-skills/code-review ~/.claude/skills/ + +# 或直接安装完整插件 +/plugin install pr-review +``` + +### DevOps 与部署 + +```bash +# 安装插件（包含全部功能） +/plugin install devops-automation +``` + +### 文档 + +```bash +# 安装 slash command +cp 01-slash-commands/generate-api-docs.md .claude/commands/ + +# 安装 subagent +cp 04-subagents/documentation-writer.md .claude/agents/ + +# 安装 skill +cp -r 03-skills/doc-generator ~/.claude/skills/ + +# 或直接安装完整插件 +/plugin install documentation +``` + +### 团队规范 + +```bash +# 设置项目 memory +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# 根据团队规范调整内容 +``` + +### 外部集成 + +```bash +# 设置环境变量 +export GITHUB_TOKEN="your_token" +export DATABASE_URL="postgresql://..." + +# 安装 MCP 配置（项目级） +cp 05-mcp/multi-mcp.json .mcp.json +``` + +### 自动化与校验 + +```bash +# 安装 hooks +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# 在 settings 中配置 hooks（~/.claude/settings.json） +# 参见 06-hooks/README.md +``` + +### 安全实验 + +```bash +# 每次用户提示后都会自动创建 checkpoint +# 回退：按 Esc 两次或使用 /rewind +# 然后选择要从回退菜单中恢复的内容 + +# 参见 08-checkpoints/README.md 的示例 +``` + +### 高级工作流 + +```bash +# 配置高级功能 +# 参见 09-advanced-features/config-examples.json + +# 使用 planning mode +/plan 实现功能 X + +# 使用权限模式 +claude --permission-mode plan # 用于代码审查（只读） +claude --permission-mode acceptEdits # 自动接受编辑 +claude --permission-mode auto # 自动批准安全操作 + +# 以 headless 模式运行 CI/CD +claude -p "Run tests and report results" + +# 运行后台任务 +在后台运行测试 + +# 参见 09-advanced-features/README.md 获取完整指南 +``` + +--- + +## 功能覆盖矩阵 + +| 分类 | Commands | Agents | MCP | Hooks | Scripts | Templates | Docs | Images | 总计 | +|------|----------|--------|-----|-------|---------|-----------|------|--------|------| +| **01 Slash Commands** | 8 | - | - | - | - | - | 1 | 1 | **10** | +| **02 Memory** | - | - | - | - | - | 3 | 1 | 2 | **6** | +| **03 Skills** | - | - | - | - | 5 | 9 | 1 | - | **28** | +| **04 Subagents** | - | 8 | - | - | - | - | 1 | - | **9** | +| **05 MCP** | - | - | 4 | - | - | - | 1 | - | **5** | +| **06 Hooks** | - | - | - | 8 | - | - | 1 | - | **9** | +| **07 Plugins** | 11 | 9 | 3 | 3 | 3 | 3 | 4 | - | **40** | +| **08 Checkpoints** | - | - | - | - | - | - | 1 | 1 | **2** | +| **09 Advanced** | - | - | - | - | - | - | 1 | 2 | **3** | +| **10 CLI** | - | - | - | - | - | - | 1 | - | **1** | + +--- + +## 学习路径 + +### 入门（第 1 周） + +1. ✅ 阅读 `README.md` +2. ✅ 安装 1 到 2 个 slash command +3. ✅ 创建项目 memory 文件 +4. ✅ 试用基础命令 + +### 中级（第 2-3 周） + +1. ✅ 搭建 GitHub MCP +2. ✅ 安装一个 subagent +3. ✅ 尝试委派任务 +4. ✅ 安装一个 skill + +### 高级（第 4 周及以后） + +1. ✅ 安装完整插件 +2. ✅ 创建自定义 slash command +3. ✅ 创建自定义 subagent +4. ✅ 创建自定义 skill +5. ✅ 构建自己的插件 + +### 专家（第 5 周及以后） + +1. ✅ 配置 hooks 做自动化 +2. ✅ 用 checkpoints 做实验 +3. ✅ 配置 planning mode +4. ✅ 充分利用权限模式 +5. ✅ 为 CI/CD 配置 headless mode +6. ✅ 熟练掌握会话管理 + +--- + +## 按关键词查找 + +### 性能 + +- `01-slash-commands/optimize.md` - 性能分析 +- `04-subagents/code-reviewer.md` - 性能审查 +- `03-skills/code-review/` - 性能指标 +- `07-plugins/pr-review/agents/performance-analyzer.md` - 性能专家 + +### 安全 + +- `04-subagents/secure-reviewer.md` - 安全审查 +- `03-skills/code-review/` - 安全分析 +- `07-plugins/pr-review/` - 安全检查 + +### 测试 + +- `04-subagents/test-engineer.md` - 测试工程师 +- `07-plugins/pr-review/commands/check-tests.md` - 测试覆盖率 + +### 文档 + +- `01-slash-commands/generate-api-docs.md` - API 文档命令 +- `04-subagents/documentation-writer.md` - 文档编写 agent +- `03-skills/doc-generator/` - 文档生成 skill +- `07-plugins/documentation/` - 完整文档插件 + +### 部署 + +- `07-plugins/devops-automation/` - 完整 DevOps 方案 + +### 自动化 + +- `06-hooks/` - 事件驱动自动化 +- `06-hooks/pre-commit.sh` - 提交前自动化 +- `06-hooks/format-code.sh` - 自动格式化 +- `09-advanced-features/` - headless 模式用于 CI/CD + +### 校验 + +- `06-hooks/security-scan.sh` - 安全校验 +- `06-hooks/validate-prompt.sh` - 提示词校验 + +### 实验 + +- `08-checkpoints/` - 使用 rewind 做安全实验 +- `08-checkpoints/checkpoint-examples.md` - 真实示例 + +### 规划 + +- `09-advanced-features/planning-mode-examples.md` - 规划模式示例 +- `09-advanced-features/README.md` - 深度思考 + +### 配置 + +- `09-advanced-features/config-examples.json` - 配置示例 + +--- + +## 说明 + +- 所有示例都可直接使用 +- 按需修改以适配你的项目 +- 示例遵循 Claude Code 最佳实践 +- 每个分类都有自己的 README，包含详细说明 +- 脚本包含正确的错误处理 +- 模板都可自定义 + +--- + +## 参与贡献 + +如果你想增加更多示例，可以按照下面的结构： +1. 创建合适的子目录 +2. 包含带使用说明的 README.md +3. 遵循命名规范 +4. 充分测试 +5. 更新这个索引 + +--- + +**最后更新**：2026 年 3 月 +**总示例数**：100+ 文件 +**分类数**：10 个功能 +**Hooks**：8 个自动化脚本 +**配置示例**：10+ 个场景 +**可直接使用**：所有示例 diff --git a/zh/LEARNING-ROADMAP.md b/zh/LEARNING-ROADMAP.md new file mode 100644 index 0000000..ee333b7 --- /dev/null +++ b/zh/LEARNING-ROADMAP.md @@ -0,0 +1,725 @@ + + + Claude How To + + +# 📚 Claude Code 学习路线图 + +**刚接触 Claude Code？** 这份指南会帮你按照自己的节奏掌握 Claude Code 的各项功能。无论你是完全新手，还是经验丰富的开发者，都可以先做下面的自我评估测验，找到最适合自己的起点。 + +--- + + +## 🧭 找到你的水平 + +每个人的起点都不同。先做一份快速自我评估，确认最适合你的入口。 + +**请诚实回答下面的问题：** + +- [ ] 我可以启动 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["🧭 自我评估测验
找到你的水平"] --> L1 + Q --> L2 + Q --> L3 + + subgraph L1["🟢 Level 1：Beginner - 从这里开始"] + direction LR + A["1A：第一个命令与 Memory
Slash Commands + Memory"] --> B["1B：安全探索
Checkpoints + CLI Basics"] + end + + subgraph L2["🔵 Level 2：Intermediate - 构建工作流"] + direction LR + C["2A：自动化
Skills + Hooks"] --> D["2B：集成
MCP + Subagents"] + end + + subgraph L3["🔴 Level 3：Advanced - 高阶用户"] + direction LR + E["3A：高级功能
Planning + Permissions"] --> F["3B：团队与分发
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 + + +### 里程碑 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)） + +> **有空缺？** 继续之前，先回顾上面的链接教程。 + +--- + + +### 里程碑 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)） + +> **有空缺？** 继续之前，先回顾上面的链接教程。 + +--- + + +### 里程碑 3A：高级功能 + +**主题**：高级功能（Planning、Permissions、Extended Thinking、自动模式（Auto Mode）、通道（Channels）、语音输入（Voice Dictation）、Remote/Desktop/Web） +**时间**：2-3 小时 +**复杂度**：⭐⭐⭐⭐⭐ Advanced +**目标**：掌握高级工作流和高阶工具 + +#### 你将完成什么 +✅ 为复杂功能使用 planning mode +✅ 用 6 种模式进行细粒度权限控制（default、acceptEdits、plan、auto、dontAsk、bypassPermissions） +✅ 用 Alt+T / Option+T 切换 extended thinking +✅ 管理后台任务 +✅ 使用 Auto Memory 记住偏好 +✅ 使用自动模式（Auto Mode）和后台安全分类器 +✅ 使用通道（Channels）组织多会话工作流 +✅ 使用语音输入（Voice Dictation）解放双手 +✅ 远程控制、桌面应用和 Web 会话 +✅ 使用 Agent Teams 协作 + +#### 实战练习 + +```bash +# 练习 1：使用 planning mode +/plan Implement user authentication system + +# 练习 2：尝试权限模式（共有 6 种：default、acceptEdits、plan、auto、dontAsk、bypassPermissions） +claude --permission-mode plan "analyze this codebase" +claude --permission-mode acceptEdits "refactor the auth module" +claude --permission-mode auto "implement the feature" + +# 练习 3：启用 extended thinking +# 在会话中按 Alt+T（macOS 上是 Option+T）切换 + +# 练习 4：高级 checkpoint 工作流 +# 1. 创建名为 "Clean state" 的 checkpoint +# 2. 使用 planning mode 设计功能 +# 3. 通过 subagent 委派实现 +# 4. 在后台运行测试 +# 5. 如果测试失败，回退到 checkpoint +# 6. 尝试另一种方案 + +# 练习 5：尝试自动模式（Auto mode，后台安全分类器） +claude --permission-mode auto "implement user settings page" + +# 练习 6：启用 agent teams +export CLAUDE_AGENT_TEAMS=1 +# 让 Claude 执行："Implement feature X using a team approach" + +# 练习 7：定时任务 +/loop 5m /check-status +# 或使用 CronCreate 创建持久化定时任务 + +# 练习 8：用通道（Channels）管理多会话工作流 +# 用 channels 来组织跨会话工作 + +# 练习 9：语音输入（Voice Dictation） +# 用语音输入和 Claude Code 进行无手操作 +``` + +#### 成功标准 +- [ ] 为复杂功能使用过 planning mode +- [ ] 配置过权限模式（plan、acceptEdits、auto、dontAsk） +- [ ] 用 Alt+T / Option+T 切换过 extended thinking +- [ ] 使用过带后台安全分类器的自动模式（Auto mode） +- [ ] 使用过后台任务处理长时间操作 +- [ ] 探索过通道（Channels）做多会话工作流 +- [ ] 尝试过语音输入（Voice Dictation）做无手输入 +- [ ] 理解 Remote Control、Desktop App 和 Web 会话 +- [ ] 启用并使用过 Agent Teams 做协作任务 +- [ ] 用过 `/loop` 做周期任务或定时监控 + +#### 下一步 +- 阅读：[09-advanced-features/README.md](09-advanced-features/README.md) + +> **检查理解**：运行 `/lesson-quiz advanced`，测试你对高阶功能的掌握程度。 + +--- + +### 里程碑 3B：团队与分发（Plugins + CLI 精通） + +**主题**：Plugins + CLI 精通 + CI/CD +**时间**：2-3 小时 +**复杂度**：⭐⭐⭐⭐ Advanced +**目标**：搭建团队工具、创建插件、熟练集成 CI/CD + +#### 你将完成什么 +✅ 安装和创建完整的 bundled plugins +✅ 掌握 CLI，用于脚本和自动化 +✅ 使用 `claude -p` 做 CI/CD 集成 +✅ 为自动化流水线输出 JSON +✅ 管理会话与批处理 + +#### 实战练习 + +```bash +# 练习 1：安装一个完整 plugin +# 在 Claude Code 中：/plugin install pr-review + +# 练习 2：让 print mode 服务于 CI/CD +claude -p "Run all tests and generate report" + +# 练习 3：为脚本输出 JSON +claude -p --output-format json "list all functions" + +# 练习 4：会话管理与恢复 +claude -r "feature-auth" "continue implementation" + +# 练习 5：带约束的 CI/CD 集成 +claude -p --max-turns 3 --output-format json "review code" + +# 练习 6：批处理 +for file in *.md; do + claude -p --output-format json "summarize this: $(cat $file)" > ${file%.md}.summary.json +done +``` + +#### CI/CD 集成练习 +创建一个简单的 CI/CD 脚本： +1. 用 `claude -p` 审查变更文件 +2. 把结果输出成 JSON +3. 用 `jq` 处理特定问题 +4. 集成进 GitHub Actions 工作流 + +--- + +## 🧪 测试你的知识 + +根据你刚学完的内容，直接运行下面的测验： + +```bash +/lesson-quiz slash-commands +/lesson-quiz memory +/lesson-quiz checkpoints +/lesson-quiz cli +/lesson-quiz skills +/lesson-quiz hooks +/lesson-quiz mcp +/lesson-quiz subagents +/lesson-quiz advanced-features +``` + +--- + +## ⚡ 快速开始路径 + +### 如果你只有 15 分钟 +**目标**：先拿到一个立竿见影的成果 + +1. 复制一个 slash command：`cp 01-slash-commands/optimize.md .claude/commands/` +2. 在 Claude Code 中试一下：`/optimize` +3. 阅读：[01-slash-commands/README.md](01-slash-commands/README.md) + +**结果**：你会得到一个能用的 slash command，并理解基础用法 + +--- + +### 如果你有 1 小时 +**目标**：搭好基础生产力工具 + +1. **Slash commands**（15 分钟）：复制并测试 `/optimize` 和 `/pr` +2. **项目 memory**（15 分钟）：用项目规范创建 `CLAUDE.md` +3. **安装一个 skill**（15 分钟）：配置 code-review skill +4. **一起试用**（15 分钟）：感受它们如何协同工作 + +**结果**：命令、memory 和自动 skills 带来基础效率提升 + +--- + +### 如果你有一个周末 +**目标**：熟悉大部分功能 + +**周六上午**（3 小时）： +- 完成里程碑 1A：Slash Commands + Memory +- 完成里程碑 1B：Checkpoints + CLI Basics + +**周六下午**（3 小时）： +- 完成里程碑 2A：Skills + Hooks +- 完成里程碑 2B：MCP + Subagents + +**周日**（4 小时）： +- 完成里程碑 3A：高级功能 +- 完成里程碑 3B：Plugins + CLI 精通 + CI/CD +- 为你的团队构建一个自定义 plugin + +**结果**：你会成为 Claude Code 的高阶用户，能够培训别人并自动化复杂工作流 + +--- + +## 💡 学习建议 + +### ✅ 建议做 + +- **先做测验**，找到自己的起点 +- **完成每个里程碑的实战练习** +- **先从简单开始**，再逐步增加复杂度 +- **在进入下一个功能前先测试当前功能** +- **记下哪些做法最适合你的工作流** +- **学习新内容时回头复习基础概念** +- **借助 checkpoints 安全试验** +- **把经验分享给团队** + +### ❌ 不建议做 + +- **不要跳过前置条件检查** +- **不要试图一次学完所有内容** +- **不要照搬配置却不理解它们** +- **不要忘记测试** +- **不要急着跳过里程碑** +- **不要忽视文档** +- **不要把自己隔离起来** + +--- + +## 🎓 学习风格 + +### 视觉型学习者 +- 阅读每个 README 里的 Mermaid 图 +- 观察命令执行流程 +- 自己画工作流图 +- 使用上面的可视化路径图 + +### 动手型学习者 +- 完成每个实战练习 +- 试试不同变体 +- 先搞坏再修复（记得用 checkpoints） +- 创建自己的示例 + +### 阅读型学习者 +- 认真阅读每个 README +- 研究代码示例 +- 看对比表 +- 阅读资源区链接的博客文章 + +### 社交型学习者 +- 组织结对编程 +- 给队友讲解概念 +- 参与 Claude Code 社区讨论 +- 分享你的自定义配置 + +--- + +## 📈 进度追踪 + +用这些清单按水平追踪进度。你可以随时运行 `/self-assessment` 更新自己的技能画像，也可以在每个教程后运行 `/lesson-quiz [lesson]` 验证理解。 + +### 🟢 Level 1：Beginner +- [ ] 完成 [01-slash-commands](01-slash-commands/README.md) +- [ ] 完成 [02-memory](02-memory/README.md) +- [ ] 创建第一个自定义 slash command +- [ ] 设置项目 memory +- [ ] **达到里程碑 1A** +- [ ] 完成 [08-checkpoints](08-checkpoints/README.md) +- [ ] 完成 [10-cli](10-cli/README.md) 基础部分 +- [ ] 创建并回退到一个 checkpoint +- [ ] 使用交互模式和 print mode +- [ ] **达到里程碑 1B** + +### 🔵 Level 2：Intermediate +- [ ] 完成 [03-skills](03-skills/README.md) +- [ ] 完成 [06-hooks](06-hooks/README.md) +- [ ] 安装第一个 skill +- [ ] 设置 PreToolUse hook +- [ ] **达到里程碑 2A** +- [ ] 完成 [05-mcp](05-mcp/README.md) +- [ ] 完成 [04-subagents](04-subagents/README.md) +- [ ] 连接 GitHub MCP +- [ ] 创建自定义 subagent +- [ ] 把多个集成组合进一个工作流 +- [ ] **达到里程碑 2B** + +### 🔴 Level 3：Advanced +- [ ] 完成 [09-advanced-features](09-advanced-features/README.md) +- [ ] 成功使用 planning mode +- [ ] 配置权限模式（包含 auto 在内的 6 种） +- [ ] 使用带安全分类器的自动模式（Auto mode） +- [ ] 使用 extended thinking 切换 +- [ ] 探索通道（Channels）和语音输入（Voice Dictation） +- [ ] **达到里程碑 3A** +- [ ] 完成 [07-plugins](07-plugins/README.md) +- [ ] 完成 [10-cli](10-cli/README.md) 的高级用法 +- [ ] 配置 print mode（`claude -p`）用于 CI/CD +- [ ] 为自动化创建 JSON 输出 +- [ ] 把 Claude 集成到 CI/CD 流水线 +- [ ] 创建团队 plugin +- [ ] **达到里程碑 3B** + +--- + +## 🆘 常见学习难题 + +### 难题 1：“概念一下子太多了” +**解决**：一次只关注一个里程碑。完成所有练习后再往下走。 + +### 难题 2：“不知道什么时候该用哪个功能” +**解决**：回到主 README 里的 [Use Case Matrix](README.md#你能用它做什么)。 + +### 难题 3：“配置没有生效” +**解决**：检查主 README 里的 [Troubleshooting](README.md#故障排查) 部分，并确认文件路径。 + +### 难题 4：“概念之间好像重叠” +**解决**：查看主 README 里的 [Feature Comparison](README.md#功能对比) 表，理解差异。 + +### 难题 5：“太多东西记不住” +**解决**：自己做一份速查表；同时用 checkpoints 安全试验。 + +### 难题 6：“我经验很足，但不知道从哪里开始” +**解决**：先做上面的 [自我评估测验](#-找到你的水平)，直接跳到你的水平，并用前置条件检查找出空缺。 + +--- + +## 🎯 学完之后做什么？ + +完成所有里程碑后，可以继续做这些事： + +1. **写团队文档** - 记录团队的 Claude Code 配置 +2. **构建自定义 plugins** - 把团队工作流打包起来 +3. **探索 Remote Control** - 通过外部工具以编程方式控制 Claude Code 会话 +4. **试试 Web Sessions** - 用浏览器界面远程开发 +5. **使用 Desktop App** - 通过原生桌面应用访问 Claude Code +6. **使用自动模式（Auto Mode）** - 让 Claude 在后台安全分类器保护下自主工作 +7. **启用 Auto Memory** - 让 Claude 随时间自动学习你的偏好 +8. **设置 Agent Teams** - 让多个 agent 协同处理复杂、多维任务 +9. **使用通道（Channels）** - 用结构化的多会话工作流组织工作 +10. **试试语音输入（Voice Dictation）** - 用语音无障碍地与 Claude Code 交互 +11. **使用 Scheduled Tasks** - 借助 `/loop` 和 cron 工具自动化周期性检查 +12. **贡献示例** - 把经验分享给社区 +13. **带新人** - 帮助队友快速上手 +14. **持续优化工作流** - 根据使用情况不断改进 +15. **保持更新** - 跟进 Claude Code 发布和新功能 + +--- + +## 📚 其他资源 + +### 官方文档 +- [Claude Code Documentation](https://code.claude.com/docs/en/overview) +- [Anthropic Documentation](https://docs.anthropic.com) +- [MCP Protocol Specification](https://modelcontextprotocol.io) + +### 博客文章 +- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) + +### 社区 +- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) +- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers) + +--- + +## 💬 反馈与支持 + +- **发现问题？** 在仓库里创建 issue +- **有建议？** 提交 pull request +- **需要帮助？** 查看文档，或者向社区提问 + +--- + +**最后更新**：2026 年 3 月 +**维护者**：Claude How-To Contributors +**许可证**：仅供学习与参考，免费使用和改编 + +--- + +[← 返回主 README](README.md) diff --git a/zh/QUICK_REFERENCE.md b/zh/QUICK_REFERENCE.md new file mode 100644 index 0000000..72b7fc0 --- /dev/null +++ b/zh/QUICK_REFERENCE.md @@ -0,0 +1,506 @@ + + + Claude How To + + +# 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 ` | +| **Permission Modes（6 种）** | 内置 | `--allowedTools`、`--permission-mode` | +| **Sessions** | 内置 | `/session ` | +| **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 ` | +| **Auto Memory** | 从对话中自动保存记忆 | Claude 会自动保存关键上下文到 `CLAUDE.md` | +| **Git Worktrees** | 用于并行开发的隔离工作区 | 使用 `/worktree` 创建隔离空间 | +| **Model Selection** | 在 Sonnet 4.6 和 Opus 4.6 之间切换 | `/model` 或 `--model` 参数 | +| **Agent Teams** | 协调多个 agent 执行任务 | 通过环境变量 `CLAUDE_AGENT_TEAMS=1` 启用 | +| **Scheduled Tasks** | 使用 `/loop` 运行周期任务 | `/loop 5m /command` 或 CronCreate 工具 | +| **Chrome Integration** | 浏览器自动化 | `--chrome` 参数或 `/chrome` 命令 | +| **Keyboard Customization** | 自定义按键绑定 | `/keybindings` 命令 | + +--- + +## 💡 小技巧 + +### 自定义 +- 先原样使用示例 +- 再按需求修改 +- 分享给团队前先测试 +- 对配置做版本控制 + +### 最佳实践 +- 用 memory 保存团队规范 +- 用 plugins 做完整工作流 +- 用 subagents 处理复杂任务 +- 用 slash commands 处理快速任务 + +### 故障排查 +```bash +# 检查文件位置 +ls -la .claude/commands/ +ls -la .claude/agents/ + +# 验证 YAML 语法 +head -20 .claude/agents/code-reviewer.md + +# 测试 MCP 连接 +echo $GITHUB_TOKEN +``` + +--- + +## 📊 功能矩阵 + +| 需求 | 用这个 | 示例 | +|------|--------|------| +| 快速快捷操作 | Slash Command（55+） | `01-slash-commands/optimize.md` | +| 团队规范 | Memory | `02-memory/project-CLAUDE.md` | +| 自动化工作流 | Skill | `03-skills/code-review/` | +| 专门任务 | Subagent | `04-subagents/code-reviewer.md` | +| 外部数据 | MCP（+ Elicitation、WebSocket） | `05-mcp/github-mcp.json` | +| 事件自动化 | Hook（25 个事件、4 类） | `06-hooks/pre-commit.sh` | +| 完整方案 | Plugin（+ LSP 支持） | `07-plugins/pr-review/` | +| 安全实验 | Checkpoint | `08-checkpoints/checkpoint-examples.md` | +| 完全自治 | Auto Mode | `--enable-auto-mode` 或 `Shift+Tab` | +| 聊天集成 | Channels | `--channels`（Discord、Telegram） | +| CI/CD 流水线 | CLI | `10-cli/README.md` | + +--- + +## 🔗 快速链接 + +- **主指南**：`README.md` +- **完整索引**：`INDEX.md` +- **速查卡**：`QUICK_REFERENCE.md` +- **原始指南**：`claude_concepts_guide.md` + +--- + +## 📞 常见问题 + +**问：我应该先用哪个？** +答：先从 slash commands 开始，按需逐步添加功能。 + +**问：我可以混用多个功能吗？** +答：可以！它们可以一起工作。Memory + Commands + MCP 很强大。 + +**问：怎么分享给团队？** +答：把 `.claude/` 目录提交到 git。 + +**问：敏感信息怎么办？** +答：用环境变量，不要硬编码。 + +**问：我可以改这些示例吗？** +答：当然可以！它们本来就是可定制的模板。 + +--- + +## ✅ 检查清单 + +入门清单： + +- [ ] 阅读 `README.md` +- [ ] 安装 1 个 slash command +- [ ] 试用该命令 +- [ ] 创建项目 `CLAUDE.md` +- [ ] 安装 1 个 subagent +- [ ] 配置 1 个 MCP 集成 +- [ ] 安装 1 个 skill +- [ ] 试用一个完整插件 +- [ ] 按你的需求定制 +- [ ] 与团队共享 + +--- + +**快速开始**：`cat README.md` + +**完整索引**：`cat INDEX.md` + +**这张卡片**：建议随手保留，方便快速查阅！ diff --git a/zh/README.md b/zh/README.md new file mode 100644 index 0000000..4406b7d --- /dev/null +++ b/zh/README.md @@ -0,0 +1,881 @@ + + + Claude How To + + +

+ + + +

+ +[![GitHub Stars](https://img.shields.io/github/stars/luongnv89/claude-howto?style=flat&color=gold)](https://github.com/luongnv89/claude-howto/stargazers) +[![GitHub Forks](https://img.shields.io/github/forks/luongnv89/claude-howto?style=flat)](https://github.com/luongnv89/claude-howto/network/members) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Version](https://img.shields.io/badge/version-2.2.0-brightgreen)](CHANGELOG.md) +[![Claude Code](https://img.shields.io/badge/Claude_Code-2.1+-purple)](https://code.claude.com) + +# 用一个周末掌握 Claude Code + +从输入 `claude` 开始，到编排 agents、hooks、skills 和 MCP servers，全程配有可视化教程、可直接复制粘贴的模板，以及循序渐进的学习路径。 + +**[15 分钟快速上手](#15-分钟快速上手)** | **[找到适合你的起点](#不知道从哪里开始)** | **[浏览功能目录](CATALOG.md)** + +--- + +## 目录 + +- [问题在哪里](#问题在哪里) +- [Claude How To 如何解决这些问题](#claude-how-to-如何解决这些问题) +- [它是如何工作的](#它是如何工作的) +- [不知道从哪里开始？](#不知道从哪里开始) +- [15 分钟快速上手](#15-分钟快速上手) +- [你能用它做什么？](#你能用它做什么) +- [常见问题](#常见问题) +- [参与贡献](#参与贡献) +- [许可证](#许可证) + +--- + +## 问题在哪里 + +你已经安装了 Claude Code。也试着跑了几个提示词。然后呢？ + +- **官方文档会介绍功能，但不会告诉你如何把它们组合起来。** 你知道 slash commands 存在，但不知道怎样把它们和 hooks、memory、subagents 串起来，形成一个真正能节省数小时的工作流。 +- **没有清晰的学习路径。** 应该先学 MCP 还是 hooks？先学 skills 还是 subagents？结果往往是每样都看了一点，但没有一个真正掌握。 +- **示例太基础。** 一个 “hello world” 级别的 slash command，并不能帮你构建一个可用于生产环境的代码审查流水线，也无法让它结合 memory、委派给专门 agent、并自动执行安全扫描。 + +你实际上只用上了 Claude Code 10% 的能力，而剩下的 90% 你甚至不知道自己错过了什么。 + +--- + +## Claude How To 如何解决这些问题 + +这不是另一份功能参考手册，而是一份**结构化、可视化、以示例驱动的指南**。它会教你如何使用 Claude Code 的每一项功能，并提供今天就能复制到项目里的真实场景模板。 + +| | 官方文档 | 本指南 | +|--|---------------|------------| +| **形式** | 参考文档 | 带 Mermaid 图表的可视化教程 | +| **深度** | 功能说明 | 底层工作原理解析 | +| **示例** | 基础代码片段 | 可立即上手的生产级模板 | +| **结构** | 按功能组织 | 递进式学习路径（从入门到高级） | +| **上手方式** | 自主摸索 | 带时间预估的引导式路线图 | +| **自我评估** | 没有 | 交互式测验，帮你找出短板并生成个性化路径 | + +### 你将获得： + +- **10 个教程模块**，覆盖 Claude Code 的所有核心功能，从 slash commands 到自定义 agent 团队 +- **可复制粘贴的配置**，包括 slash commands、`CLAUDE.md` 模板、hook 脚本、MCP 配置、subagent 定义，以及完整 plugin 打包 +- **Mermaid 图表**，展示每个功能的内部工作机制，让你不仅知道“怎么做”，还知道“为什么这么做” +- **一条引导式学习路径**，帮助你在 11 到 13 小时内从初学者成长为高级用户 +- **内置自测能力**，可以直接在 Claude Code 中运行 `/self-assessment` 或 `/lesson-quiz hooks` 找出知识盲点 + +**[开始学习路线 ->](LEARNING-ROADMAP.md)** + +--- + +## 它是如何工作的 + +### 1. 先找到你的水平 + +完成[自我评估测验](LEARNING-ROADMAP.md#find-your-level)，或者在 Claude Code 中运行 `/self-assessment`。系统会根据你已经掌握的内容，生成一份个性化学习路线。 + +### 2. 按引导路径学习 + +按照顺序学习 10 个模块，每个模块都建立在前一个模块的基础上。你可以一边学，一边把模板直接复制到自己的项目中。 + +### 3. 把多个功能组合成工作流 + +真正的威力来自功能组合。你会学到如何把 slash commands、memory、subagents 和 hooks 连接成自动化流水线，用于代码审查、部署和文档生成等任务。 + +### 4. 测试你的理解程度 + +每学完一个模块后运行 `/lesson-quiz [topic]`。测验会精准指出你漏掉的知识点，让你快速补齐短板。 + +**[15 分钟快速上手](#15-分钟快速上手)** + +--- + +## 已被 5,900+ 开发者信赖 + +- **5,900+ GitHub stars**，来自每天都在使用 Claude Code 的开发者 +- **690+ forks**，许多团队已将这份指南改造成自己的工作流版本 +- **持续维护中**，会与每次 Claude Code 发布保持同步（最新版本：v2.2.0，2026 年 3 月） +- **社区驱动**，贡献者会分享他们在真实工作中的配置和经验 + +[![Star History Chart](https://api.star-history.com/svg?repos=luongnv89/claude-howto&type=Date)](https://star-history.com/#luongnv89/claude-howto&Date) + +--- + +## 不知道从哪里开始？ + +先做自我评估，或者直接按你的水平开始： + +| Level | 你可以…… | 从这里开始 | 时间 | +|-------|-----------|------------|------| +| **Beginner** | 启动 Claude Code 并进行对话 | [Slash Commands](01-slash-commands/README.md) | 约 2.5 小时 | +| **Intermediate** | 使用 `CLAUDE.md` 和自定义命令 | [Skills](03-skills/README.md) | 约 3.5 小时 | +| **Advanced** | 配置 MCP servers 和 hooks | [Advanced Features](09-advanced-features/README.md) | 约 5 小时 | + +**完整学习路径，共 10 个模块：** + +| 顺序 | 模块 | 水平 | 时间 | +|-------|--------|-------|------| +| 1 | [Slash Commands](01-slash-commands/README.md) | 初学者 | 30 分钟 | +| 2 | [Memory](02-memory/README.md) | 初学者+ | 45 分钟 | +| 3 | [Checkpoints](08-checkpoints/README.md) | 中级 | 45 分钟 | +| 4 | [CLI Basics](10-cli/README.md) | 初学者+ | 30 分钟 | +| 5 | [Skills](03-skills/README.md) | 中级 | 1 小时 | +| 6 | [Hooks](06-hooks/README.md) | 中级 | 1 小时 | +| 7 | [MCP](05-mcp/README.md) | 中级+ | 1 小时 | +| 8 | [Subagents](04-subagents/README.md) | 中级+ | 1.5 小时 | +| 9 | [Advanced Features](09-advanced-features/README.md) | 高级 | 2 到 3 小时 | +| 10 | [Plugins](07-plugins/README.md) | 高级 | 2 小时 | + +**[完整学习路线图 ->](LEARNING-ROADMAP.md)** + +--- + +## 15 分钟快速上手 + +```bash +# 1. 克隆这份指南 +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto + +# 2. 复制你的第一个 slash command +mkdir -p /path/to/your-project/.claude/commands +cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/ + +# 3. 试试看：在 Claude Code 中输入 +# /optimize + +# 4. 想更进一步？设置项目记忆： +cp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md + +# 5. 安装一个 skill： +cp -r 03-skills/code-review ~/.claude/skills/ +``` + +如果你想完成更完整的基础配置，这里有一个**1 小时的关键配置方案**： + +```bash +# Slash commands（15 分钟） +cp 01-slash-commands/*.md .claude/commands/ + +# 项目记忆（15 分钟） +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# 安装一个 skill（15 分钟） +cp -r 03-skills/code-review ~/.claude/skills/ + +# 周末目标：继续添加 hooks、subagents、MCP 和 plugins +# 按学习路径逐步完成配置 +``` + +**[查看完整安装参考](#15-分钟快速上手)** + +--- + +## 你能用它做什么？ + +| 使用场景 | 你会组合使用的功能 | +|----------|------------------------| +| **自动化代码审查** | Slash Commands + Subagents + Memory + MCP | +| **团队入职培训** | Memory + Slash Commands + Plugins | +| **CI/CD 自动化** | CLI Reference + Hooks + Background Tasks | +| **文档生成** | Skills + Subagents + Plugins | +| **安全审计** | Subagents + Skills + Hooks（只读模式） | +| **DevOps 流水线** | Plugins + MCP + Hooks + Background Tasks | +| **复杂重构** | Checkpoints + Planning Mode + Hooks | + +--- + +## 常见问题 + +**这是免费的吗？** +是的。MIT 许可证，永久免费。你可以将它用于个人项目、工作项目或团队中，唯一要求只是保留许可证声明。 + +**它有人维护吗？** +是的，而且持续维护。该指南会与每次 Claude Code 发布同步。当前版本是 v2.2.0（2026 年 3 月），兼容 Claude Code 2.1+。 + +**它和官方文档有什么不同？** +官方文档是功能参考手册；这份指南则是教程，包含图示、生产级模板和渐进式学习路径。两者是互补关系，建议先用本指南学习，再在需要具体细节时查官方文档。 + +**完整学完需要多久？** +完整路径大约需要 11 到 13 小时。但你在 15 分钟内就能获得直接收益，只要复制一个 slash command 模板并试用即可。 + +**我可以搭配 Claude Sonnet / Haiku / Opus 使用吗？** +可以。所有模板都适用于 Claude Sonnet 4.6、Claude Opus 4.6 和 Claude Haiku 4.5。 + +**我可以参与贡献吗？** +当然可以。请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献规范。我们欢迎新的示例、bug 修复、文档改进以及社区模板。 + +**我可以离线阅读吗？** +可以。运行 `uv run scripts/build_epub.py`，即可生成包含全部内容和渲染后 Mermaid 图表的 EPUB 电子书。 + +--- + +## 今天就开始掌握 Claude Code + +你已经安装好了 Claude Code。你和 10 倍生产力之间，差的只是知道该怎么正确使用它。这份指南会提供结构化路径、可视化解释和可直接复制的模板，帮助你真正掌握它。 + +MIT 许可证，永久免费。克隆它、fork 它、改造成适合你自己的版本。 + +**[开始学习路线 ->](LEARNING-ROADMAP.md)** | **[浏览功能目录](CATALOG.md)** | **[15 分钟快速上手](#15-分钟快速上手)** + +--- + +
+快速导航：全部功能 + +| 功能 | 说明 | 文件夹 | +|---------|-------------|--------| +| **功能目录** | 包含安装命令的完整参考 | [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) | + +
+ +
+功能对比 + +| 功能 | 调用方式 | 持久性 | 最适合 | +|---------|-----------|------------|----------| +| **Slash Commands** | 手动（`/cmd`） | 仅当前会话 | 快速快捷操作 | +| **Memory** | 自动加载 | 跨会话 | 长期记忆与学习 | +| **Skills** | 自动触发 | 文件系统级 | 自动化工作流 | +| **Subagents** | 自动委派 | 隔离上下文 | 任务拆分 | +| **MCP Protocol** | 自动查询 | 实时 | 获取实时数据 | +| **Hooks** | 事件触发 | 已配置 | 自动化与校验 | +| **Plugins** | 一条命令 | 全功能打包 | 完整解决方案 | +| **Checkpoints** | 手动/自动 | 会话级 | 安全试验 | +| **Planning Mode** | 手动/自动 | 规划阶段 | 复杂实现 | +| **Background Tasks** | 手动 | 任务持续期间 | 长时间运行的操作 | +| **CLI Reference** | 终端命令 | 会话/脚本级 | 自动化与脚本开发 | + +
+ +
+安装速查表 + +```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 +``` + +
+ +
+01. Slash Commands + +**位置**: [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) + +
+ +
+02. Memory + +**位置**: [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 会自动加载 + +
+ +
+03. Skills + +**位置**: [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/ +``` + +**使用方法**: 在相关场景下自动触发 + +
+ +
+04. Subagents + +**位置**: [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 自动委派 + +
+ +
+05. MCP Protocol + +**位置**: [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 工具能力 + +
+ +
+06. Hooks + +**位置**: [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` + +
+ +
+07. Plugins + +**位置**: [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 和功能 + +
+ +
+08. Checkpoints and Rewind + +**位置**: [08-checkpoints/README.md](08-checkpoints/README.md) + +**是什么**: 保存对话状态，并回退到之前的时间点，以探索不同方案 + +**核心概念**: +- **Checkpoint**: 对话状态快照 +- **Rewind**: 回到之前的 checkpoint +- **Branch Point**: 从同一个 checkpoint 分叉出多种方案 + +**使用方法**: +``` +# 每次用户提示后都会自动创建 checkpoint +# 如需回退，按两次 Esc，或者使用： +/rewind + +# 然后从以下五个选项中选择： +# 1. 恢复代码和对话 +# 2. 恢复对话 +# 3. 恢复代码 +# 4. 从这里开始总结 +# 5. 算了 +``` + +**使用场景**: +- 尝试不同实现方式 +- 从错误中恢复 +- 安全试验 +- 比较不同备选方案 +- 对不同设计做 A/B 测试 + +
+ +
+09. Advanced Features + +**位置**: [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)。 + +
+ +
+10. CLI Reference + +**位置**: [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 配置 + +
+ +
+示例工作流 + +### 完整代码审查工作流 + +```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. 报告状态 +``` + +
+ +
+目录结构 + +``` +├── 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（本文件） +``` + +
+ +
+最佳实践 + +### 应该做的 +- 从简单的 slash commands 开始 +- 逐步增加功能 +- 用 memory 保存团队规范 +- 先在本地测试配置 +- 为自定义实现写文档 +- 对项目配置做版本控制 +- 和团队共享 plugins + +### 不应该做的 +- 不要创建重复功能 +- 不要硬编码凭据 +- 不要跳过文档 +- 不要把简单任务过度复杂化 +- 不要忽视安全最佳实践 +- 不要提交敏感数据 + +
+ +
+故障排查 + +### 功能没有加载 +1. 检查文件位置和命名 +2. 验证 YAML frontmatter 语法 +3. 检查文件权限 +4. 查看 Claude Code 版本兼容性 + +### MCP 连接失败 +1. 检查环境变量 +2. 检查 MCP server 是否正确安装 +3. 测试凭据 +4. 检查网络连通性 + +### Subagent 没有发生委派 +1. 检查工具权限 +2. 确认 agent 描述是否清晰 +3. 查看任务复杂度 +4. 单独测试 agent + +
+ +
+测试 + +本项目包含完整的自动化测试： + +- **单元测试**：基于 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)。 + +
+ +
+EPUB 生成 + +想离线阅读这份指南？你可以生成 EPUB 电子书： + +```bash +uv run scripts/build_epub.py +``` + +这会生成包含全部内容与 Mermaid 渲染图表的 `claude-howto-guide.epub`。 + +更多选项见 [scripts/README.md](scripts/README.md)。 + +
+ +
+参与贡献 + +发现问题，或者想贡献一个示例？非常欢迎你的帮助。 + +**请先阅读 [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，我们会引导你完成整个过程。 + +
+ +
+更多资源 + +- [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。 + +
+ +--- + +## 参与贡献 + +欢迎贡献内容。如何开始请查看我们的[贡献指南](CONTRIBUTING.md)。 + +## 贡献者 + +感谢所有为本项目做出贡献的人。 + +| 贡献者 | PRs | +|-------------|-----| +| [wjhrdy](https://github.com/wjhrdy) | [#1 - add a tool to create an epub](https://github.com/luongnv89/claude-howto/pull/1) | +| [VikalpP](https://github.com/VikalpP) | [#7 - fix(docs): Use tilde fences for nested code blocks in concepts guide](https://github.com/luongnv89/claude-howto/pull/7) | + +--- + +## 许可证 + +MIT 许可证，详见 [LICENSE](LICENSE)。你可以自由使用、修改和分发，唯一要求是保留许可证声明。 + +--- + +**最后更新**：2026 年 3 月 +**Claude Code 版本**：2.1+ +**兼容模型**：Claude Sonnet 4.6、Claude Opus 4.6、Claude Haiku 4.5 diff --git a/zh/RELEASE_NOTES.md b/zh/RELEASE_NOTES.md new file mode 100644 index 0000000..e3cae71 --- /dev/null +++ b/zh/RELEASE_NOTES.md @@ -0,0 +1,8 @@ +## v2.2.0 - 2026-03-26 + +### Bug 修复 + +- 移除失效的 marketplace 链接，修复 CI 链接检查失败问题（3fdf0d6） +- 将 `sandboxed` 和 `pycache` 加入 cSpell 词典（dc64618） + +**完整变更日志**: https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1 diff --git a/zh/SECURITY.md b/zh/SECURITY.md new file mode 100644 index 0000000..6055a82 --- /dev/null +++ b/zh/SECURITY.md @@ -0,0 +1,334 @@ +# 安全政策 + +## 概述 + +Claude How To 项目的安全对我们非常重要。本文档说明我们的安全实践，以及如何负责任地报告安全漏洞。 + +## 支持的版本 + +我们为以下版本提供安全更新： + +| 版本 | 状态 | 支持至 | +|---------|--------|---------------| +| 最新版（main） | ✅ 活跃 | 当前版本 + 6 个月 | +| 1.x 发布版 | ✅ 活跃 | 直到下一个大版本 | + +**注意**：作为一个教育指南项目，我们更关注维护当前最佳实践和文档安全，而不是传统意义上的版本支持。更新会直接应用到 main 分支。 + +## 安全实践 + +### 代码安全 + +1. **依赖管理** + - 所有 Python 依赖都固定在 `requirements.txt` 中 + - 通过 dependabot 和人工审查进行定期更新 + - 每次提交都会运行 Bandit 安全扫描 + - 使用 pre-commit hooks 做安全检查 + +2. **代码质量** + - 使用 Ruff 做 lint，能捕获常见问题 + - 使用 mypy 做类型检查，避免类型相关漏洞 + - 通过 pre-commit hooks 强制执行标准 + - 所有更改在合并前都要审查 + +3. **访问控制** + - 对 `main` 分支启用分支保护 + - 合并前需要审查通过 + - 状态检查必须通过后才能合并 + - 仓库写权限受限 + +### 文档安全 + +1. **示例中不放密钥** + - 所有示例中的 API key 都使用占位符 + - 从不硬编码凭据 + - `.env.example` 文件会展示所需变量 + - 明确提示密钥管理风险 + +2. **安全最佳实践** + - 示例会展示安全模式 + - 文档中会突出安全警告 + - 链接到官方安全指南 + - 在相关章节中说明凭据处理方式 + +3. **内容审查** + - 所有文档都会审查安全问题 + - 贡献指南中包含安全注意事项 + - 会验证外部链接和引用 + +### 依赖安全 + +1. **扫描** + - Bandit 会扫描所有 Python 代码中的漏洞 + - 通过 GitHub 安全警报检查依赖漏洞 + - 定期进行人工安全审计 + +2. **更新** + - 安全补丁会尽快应用 + - 大版本会谨慎评估 + - 更新日志会包含安全相关变更 + +3. **透明度** + - 安全更新会记录在提交中 + - 漏洞披露会负责任地处理 + - 在适当情况下发布公开安全公告 + +## 漏洞报告 + +### 我们关注的安全问题 + +我们欢迎以下报告： +- **代码漏洞**：脚本或示例中的漏洞 +- **依赖漏洞**：Python 包中的漏洞 +- **加密问题**：任何代码示例中的密码学问题 +- **认证/授权缺陷**：文档中的认证或授权问题 +- **数据暴露风险**：配置示例中的数据泄露风险 +- **注入漏洞**：SQL、命令等注入 +- **SSRF / XXE / 路径穿越** 问题 + +### 不在范围内的安全问题 + +以下问题不在本项目范围内： +- Claude Code 本身的漏洞（请向 Anthropic 报告） +- 外部服务或库的问题（请向上游项目报告） +- 社会工程学或用户教育问题（与本指南无关） +- 没有 PoC 的理论漏洞 +- 依赖库中已通过官方渠道报告的漏洞 + +## 如何报告 + +### 私密报告（推荐） + +**如遇敏感安全问题，请使用 GitHub 的私密漏洞报告：** + +1. 访问： +2. 点击 “Report a vulnerability” +3. 填写漏洞细节 +4. 请包含： + - 漏洞的清晰描述 + - 受影响的组件（文件、章节、示例） + - 潜在影响 + - 复现步骤（如适用） + - 建议修复方式（如果你有） + +**接下来会发生什么：** +- 我们会在 48 小时内确认收到 +- 我们会调查并评估严重性 +- 我们会与你一起修复 +- 我们会协调披露时间线 +- 如你愿意，我们会在安全公告中致谢 + +### 公开报告 + +对于不敏感或已公开的问题： + +1. **创建 GitHub Issue** 并打上 `security` 标签 +2. 包含： + - 标题：以 `[SECURITY]` 开头并附简短说明 + - 详细描述 + - 受影响的文件或章节 + - 潜在影响 + - 建议修复方式 + +## 漏洞响应流程 + +### 评估（24 小时内） + +1. 我们确认收到报告 +2. 我们使用 [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) 评估严重性 +3. 我们判断是否在范围内 +4. 我们向你反馈初步评估 + +### 开发（1-7 天） + +1. 我们开发修复 +2. 我们审查并测试修复 +3. 我们创建安全公告 +4. 我们准备发布说明 + +### 披露（取决于严重性） + +**严重（CVSS 9.0-10.0）** +- 立即发布修复 +- 发布公开公告 +- 提前 24 小时通知报告者 + +**高危（CVSS 7.0-8.9）** +- 48-72 小时内发布修复 +- 提前 5 天通知报告者 +- 发布时公开公告 + +**中危（CVSS 4.0-6.9）** +- 在下一次常规更新中修复 +- 发布时公开公告 + +**低危（CVSS 0.1-3.9）** +- 在下一次常规更新中修复 +- 发布时附带公告 + +### 公布 + +我们发布的安全公告会包含： +- 漏洞描述 +- 受影响组件 +- 严重性评估（CVSS 分数） +- 修复版本 +- 临时缓解方案（如适用） +- 对报告者的致谢（如获许可） + +## 报告者最佳实践 + +### 报告前 + +- **确认问题**：你能稳定复现吗？ +- **搜索已有 issue**：是否已经有人报告？ +- **查看文档**：是否已有安全使用说明？ +- **测试修复**：你建议的修复是否有效？ + +### 报告时 + +- **尽量具体**：提供准确的文件路径和行号 +- **补充上下文**：为什么这是安全问题？ +- **说明影响**：攻击者可能做什么？ +- **提供步骤**：如何复现？ +- **提出修复建议**：你会怎么修？ + +### 报告后 + +- **保持耐心**：我们的资源有限 +- **积极响应**：尽快回答后续问题 +- **保持保密**：在修复前不要公开披露 +- **尊重协调流程**：按时间线推进披露 + +## 安全头与配置 + +### 仓库安全 + +- **分支保护**：主分支需要 2 份批准 +- **状态检查**：所有 CI/CD 检查必须通过 +- **CODEOWNERS**：关键文件有指定审查者 +- **签名提交**：建议贡献者使用 + +### 开发安全 + +```bash +# 安装 pre-commit hooks +pre-commit install + +# 本地运行安全扫描 +bandit -c pyproject.toml -r scripts/ +mypy scripts/ --ignore-missing-imports +ruff check scripts/ +``` + +### 依赖安全 + +```bash +# 检查已知漏洞 +pip install safety +safety check + +# 或使用 pip-audit +pip install pip-audit +pip-audit +``` + +## 贡献者安全指南 + +### 编写示例时 + +1. **永远不要硬编码密钥** + ```python + # ❌ 不好 + api_key = "sk-1234567890" + + # ✅ 更好 + api_key = os.getenv("API_KEY") + ``` + +2. **提醒安全影响** + ```markdown + ⚠️ **安全提示**：切勿把 `.env` 文件提交到 git。 + 请立即加入 `.gitignore`。 + ``` + +3. **使用安全默认值** + - 默认启用认证 + - 在适用场景中使用 HTTPS + - 校验并清理输入 + - 使用参数化查询 + +4. **记录安全注意事项** + - 解释为什么安全很重要 + - 展示安全与不安全的写法 + - 链接权威来源 + - 明显展示警告 + +### 审查贡献时 + +1. **检查是否泄露秘密** + - 扫描常见模式（api_key=、password= 等） + - 审查配置文件 + - 检查环境变量使用情况 + +2. **验证安全编码实践** + - 没有硬编码凭据 + - 正确的输入验证 + - 安全的认证/授权 + - 安全的文件处理 + +3. **测试安全影响** + - 这会不会被滥用？ + - 最坏情况是什么？ + - 有没有边界情况？ + +## 安全资源 + +### 官方标准 +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) +- [CWE Top 25](https://cwe.mitre.org/top25/) +- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) + +### Python 安全 +- [Python Security Advisories](https://www.python.org/dev/security/) +- [PyPI Security](https://pypi.org/help/#security) +- [Bandit Documentation](https://bandit.readthedocs.io/) + +### 依赖管理 +- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/) +- [GitHub Security Alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) + +### 通用安全 +- [Anthropic Security](https://www.anthropic.com/) +- [GitHub Security Best Practices](https://docs.github.com/en/code-security) + +## 安全公告存档 + +过往安全公告可在 GitHub 的 [Security Advisories](https://github.com/luongnv89/claude-howto/security/advisories) 标签页查看。 + +## 联系方式 + +如需咨询安全相关问题或讨论安全实践： + +1. **私密安全报告**：使用 GitHub 的私密漏洞报告 +2. **一般安全问题**：使用 `[SECURITY]` 标签发起 discussion +3. **安全政策反馈**：创建带 `security` 标签的 issue + +## 致谢 + +感谢帮助本项目保持安全的安全研究者和社区成员。负责任地报告漏洞的贡献者会在我们的安全公告中获得致谢（除非你希望匿名）。 + +## 政策更新 + +本安全政策会在以下情况更新： +- 发现新漏洞时 +- 安全最佳实践演进时 +- 项目范围发生变化时 +- 至少每年一次 + +**最后更新**：2026 年 1 月 +**下次审查**：2027 年 1 月 + +--- + +感谢你帮助 Claude How To 保持安全！🔒 diff --git a/zh/STYLE_GUIDE.md b/zh/STYLE_GUIDE.md new file mode 100644 index 0000000..8086282 --- /dev/null +++ b/zh/STYLE_GUIDE.md @@ -0,0 +1,630 @@ + + + Claude How To + + +# 风格指南 + +> 为 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（使用带深色/浅色变体的 `` 元素） +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"]`，这样可以包含特殊字符 +- 在标签中换行使用 `
` +- 图表保持简洁，最多 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 开头的文档都使用 `` 元素，以支持深色/浅色模式： + +```html + + + Claude How To + +``` + +### 截图 + +- 存放在对应课程文件夹中，例如 `01-slash-commands/pr-slash-command.png` +- 使用 kebab-case 文件名 +- 包含描述性的 alt 文本 +- 图表优先使用 SVG，截图优先使用 PNG + +### 规则 + +- 图片始终要有 alt 文本 +- 控制图片文件大小，PNG 尽量小于 500KB +- 图片引用使用相对路径 +- 图片存放在引用它的文档同目录，或者放在 `assets/` 里供共享使用 + +--- + +## 语气与文风 + +### 写作风格 + +- **专业但亲切** - 技术准确，同时不过度堆砌术语 +- **主动语态** - 说“Create a file”，不要说“一个文件应该被创建” +- **直接指令** - 说“Run this command”，不要说“你也许可以运行这个命令” +- **适合初学者** - 假设读者是 Claude Code 新手，但不是编程新手 + +### 内容原则 + +| 原则 | 示例 | +|-----------|---------| +| **Show, don't tell** | 提供可运行示例，而不是抽象描述 | +| **渐进式复杂度** | 先简单，后面再增加深度 | +| **解释“为什么”** | “Use memory for... because...” 而不只是 “Use memory for...” | +| **可直接复制粘贴** | 每个代码块都应能直接粘贴使用 | +| **真实场景** | 使用实际场景，而不是牵强的例子 | + +### 词汇 + +- 使用 “Claude Code”（不要写 “Claude CLI” 或 “the tool”） +- 使用 “skill”（不要写 “custom command”，这是旧术语） +- 使用 “lesson” 或 “guide” 来称呼编号章节 +- 使用 “example” 来称呼单个功能文件 + +--- + +## 提交信息 + +遵循 [Conventional Commits](https://www.conventionalcommits.org/)： + +``` +type(scope): description +``` + +### 类型 + +| Type | Use For | +|------|---------| +| `feat` | 新功能、示例或指南 | +| `fix` | Bug 修复、纠正、损坏链接 | +| `docs` | 文档改进 | +| `refactor` | 只重构、不改变行为 | +| `style` | 仅格式化改动 | +| `test` | 测试新增或修改 | +| `chore` | 构建、依赖、CI | + +### 作用域 + +使用课程名称或文件区域作为作用域： + +``` +feat(slash-commands): Add API documentation generator +docs(memory): Improve personal preferences example +fix(README): Correct table of contents link +docs(skills): Add comprehensive code review skill +``` + +--- + +## 文档元数据页脚 + +课程 README 以元数据块结尾： + +```markdown +--- +**Last Updated**: March 2026 +**Claude Code Version**: 2.1+ +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 +``` + +- 使用“月份 + 年份”格式，例如 “March 2026” +- 功能变化时更新版本 +- 列出所有兼容模型 + +--- + +## 作者检查清单 + +提交内容前，请确认： + +- [ ] 文件/文件夹名使用 kebab-case +- [ ] 文档以 H1 标题开头，每个文件一个 +- [ ] 标题层级正确，没有跳级 +- [ ] 所有代码块都带语言标签 +- [ ] 代码示例可直接复制粘贴 +- [ ] 内部链接使用相对路径 +- [ ] 外部链接使用描述性锚文本 +- [ ] 表格格式正确 +- [ ] Emoji 遵循标准集合（如果使用） +- [ ] Mermaid 图表使用标准配色 +- [ ] 没有敏感信息，例如 API key、凭据 +- [ ] YAML frontmatter 有效（如果适用） +- [ ] 图片有 alt 文本 +- [ ] 段落简短且聚焦 +- [ ] 相关指南章节链接到合适的课程 +- [ ] 提交信息符合 conventional commits 格式 diff --git a/zh/claude_concepts_guide.md b/zh/claude_concepts_guide.md new file mode 100644 index 0000000..5049c02 --- /dev/null +++ b/zh/claude_concepts_guide.md @@ -0,0 +1,1540 @@ + + + Claude How To + + +# 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
(协调者)"] + Reviewer["🔍 代码审查
Subagent"] + Tester["✅ 测试工程师
Subagent"] + Docs["📝 文档编写
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 代码审查
Subagent + participant Context as 独立的
上下文窗口 + + 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 上下文
50,000 tokens"] + B["Subagent 1 上下文
20,000 tokens"] + C["Subagent 2 上下文
20,000 tokens"] + D["Subagent 3 上下文
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
企业管理员策略"] --> B["2. Project Memory
./CLAUDE.md"] + B --> C["3. Project Rules
.claude/rules/*.md"] + C --> D["4. User Memory
~/.claude/CLAUDE.md"] + D --> E["5. User Rules
~/.claude/rules/*.md"] + E --> F["6. Local Memory
.claude/local/CLAUDE.md"] + F --> G["7. Auto Memory
自动捕获的偏好"] +``` + +### 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
MCP Server"] + A -->|MCP| C["GitHub
MCP Server"] + A -->|MCP| D["Database
MCP Server"] + A -->|MCP| E["Slack
MCP Server"] + A -->|MCP| F["Google Docs
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
客户历史"] + Router -->|查询| MCP1["MCP: 客户数据库"] + Router -->|检查| MCP2["MCP: Slack"] + Router -->|复杂问题| Sub1["Subagent: 技术支持"] + Router -->|简单问题| Sub2["Subagent: 计费支持"] +``` + +#### 请求流 + +```markdown +1. 用户发来报错邮件 +2. 读取记忆和历史上下文 +3. 通过多个 MCP 查询系统状态 +4. 自动识别适合的 Skill +5. 委派给对应 Subagent +6. Subagent 处理问题 +7. Skill 负责按统一语气生成回复 +8. MCP 将结果同步到外部系统 +9. 返回给客户 +``` + +### 完整功能编排 + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Memory as Memory + participant MCP as MCP Servers + participant Skills as Skills + participant SubAgent as Subagents + + User->>Claude: "Build auth system" + Claude->>Memory: 加载项目标准 + Claude->>MCP: 查询相似实现 + Claude->>Skills: 检测匹配 Skill + Claude->>SubAgent: 委派实现 +``` + +### 何时使用哪种功能 + +```mermaid +graph TD + A["新任务"] --> B{任务类型？} + + B -->|重复工作流| C["Slash Command"] + B -->|需要实时数据| D["MCP Protocol"] + B -->|希望下次记住| E["Memory"] + B -->|需要专业子任务| F["Subagent"] + B -->|领域型自动化| G["Skill"] +``` + +### 选择决策树 + +```mermaid +graph TD + Start["需要扩展 Claude 吗？"] + Start -->|快速重复任务| A{"手动还是自动？"} + A -->|手动| B["Slash Command"] + A -->|自动| C["Skill"] + Start -->|需要外部数据| D{"是否实时？"} + D -->|是| E["MCP Protocol"] + D -->|否| F["Memory"] + Start -->|复杂项目| G{"是否多角色协作？"} + G -->|是| H["Subagents"] +``` + +--- + +## Summary Table + +| 维度 | Slash Commands | Subagents | Memory | MCP | Skills | Plugins | +|------|----------------|-----------|--------|-----|--------|---------| +| 搭建难度 | 简单 | 中等 | 简单 | 中等 | 中等 | 简单 | +| 学习曲线 | 低 | 中 | 低 | 中 | 中 | 低 | +| 团队价值 | 高 | 高 | 中 | 高 | 高 | 很高 | +| 自动化程度 | 低 | 高 | 中 | 高 | 高 | 很高 | +| 上下文管理 | 单会话 | 隔离 | 持久 | 实时 | 持久 | 全部整合 | +| 可扩展性 | 好 | 极佳 | 好 | 极佳 | 极佳 | 极佳 | +| 共享性 | 一般 | 一般 | 好 | 好 | 好 | 极佳 | +| 安装方式 | 手动复制 | 手动配置 | N/A | 手动配置 | 手动复制 | 一条命令 | + +--- + +## Quick Start Guide + +### 第 1 周：先从简单的开始 +- 为常见任务做 2-3 个 slash commands +- 在设置里开启 Memory +- 在 `CLAUDE.md` 里写明团队标准 + +### 第 2 周：接入实时数据 +- 先配置 1 个 MCP（GitHub 或 Database） +- 通过 `/mcp` 配置 +- 在工作流中查询实时数据 + +### 第 3 周：分发工作 +- 创建第一个针对角色的 Subagent +- 使用 `/agents` +- 用简单任务测试委派 + +### 第 4 周：全面自动化 +- 创建第一个 Skill +- 使用市场里的 Skill 或自建 +- 组合多个功能做完整工作流 + +### 持续优化 +- 每月回顾并更新 Memory +- 当重复模式出现时新增 Skill +- 优化 MCP 查询 +- 持续打磨 Subagent 提示词 + +--- + +## Hooks + +### 概览 + +Hooks 是事件驱动的 shell 命令，会在 Claude Code 的特定事件发生时自动执行，可用于自动化、校验、通知和自定义工作流。 + +### Hook 事件 + +Claude Code 支持 **25 个 hook 事件**，分布在四类钩子中： + +| Hook 事件 | 触发时机 | 常见用途 | +|-----------|----------|----------| +| SessionStart | 会话开始 / 恢复 / 清空 / compact | 环境初始化 | +| InstructionsLoaded | 加载 `CLAUDE.md` 或 rules | 校验、增强 | +| UserPromptSubmit | 用户提交提示词 | 输入校验 | +| PreToolUse | 工具执行前 | 审批、校验、日志 | +| PermissionRequest | 弹出权限请求时 | 自动批准 / 拒绝 | +| PostToolUse | 工具执行成功后 | 自动格式化、通知、清理 | +| PostToolUseFailure | 工具失败后 | 错误处理 | +| Notification | 通知发送时 | 外部联动 | +| SubagentStart | 启动 subagent 时 | 注入上下文 | +| SubagentStop | subagent 结束时 | 结果校验 | +| Stop | Claude 响应完成时 | 总结、清理 | +| SessionEnd | 会话结束时 | 收尾处理 | + +### 常见 Hook 配置 + +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write", + "hooks": [ + { + "type": "command", + "command": "prettier --write $CLAUDE_FILE_PATH" + } + ] + } + ] + } +} +``` + +### Hook 环境变量 + +- `$CLAUDE_FILE_PATH`：当前被写入 / 编辑的文件 +- `$CLAUDE_TOOL_NAME`：正在使用的工具名 +- `$CLAUDE_SESSION_ID`：当前会话 ID +- `$CLAUDE_PROJECT_DIR`：项目目录路径 + +### 最佳实践 + +✅ 建议： +- 让 hooks 尽量快（最好 < 1 秒） +- 用 hooks 做校验和自动化 +- 优雅处理错误 +- 使用绝对路径 + +❌ 不建议： +- 让 hooks 进入交互式流程 +- 把长时间任务放在 hooks 里 +- 硬编码凭据 + +**详见：** [06-hooks/README.md](06-hooks/README.md) + +--- + +## Checkpoints and Rewind + +### 概览 + +Checkpoints 可以保存会话状态，并在需要时回退到之前的节点，从而安全地尝试不同方案。 + +### 核心概念 + +| 概念 | 说明 | +|------|------| +| Checkpoint | 对消息、文件和上下文的快照 | +| Rewind | 回到某个历史 checkpoint，并丢弃之后的变化 | +| Branch Point | 从同一个 checkpoint 分叉出多种方案 | + +### 如何访问 Checkpoints + +```bash +# 按两次 Esc 打开 checkpoint 浏览器 +Esc + Esc + +# 或使用 /rewind +/rewind +``` + +选择 checkpoint 后有五个选项： +1. 恢复代码和对话 +2. 恢复对话 +3. 恢复代码 +4. 从这里开始总结 +5. 取消 + +### 常见场景 + +| 场景 | 工作流 | +|------|--------| +| 探索不同方案 | 保存 → 尝试 A → 保存 → 回退 → 尝试 B | +| 安全重构 | 保存 → 重构 → 测试 → 失败就回退 | +| A/B 测试 | 保存 → 设计 A → 保存 → 回退 → 设计 B | +| 误操作恢复 | 发现问题 → 回退到最近稳定状态 | + +### 配置 + +```json +{ + "autoCheckpoint": true +} +``` + +**详见：** [08-checkpoints/README.md](08-checkpoints/README.md) + +--- + +## Advanced Features + +### Planning Mode + +在编码前先生成详细实现计划。 + +```bash +/plan Implement user authentication system +``` + +优势： +- 清晰路线图 +- 时间预估 +- 风险评估 +- 可审查、可修改 + +### Extended Thinking + +适合复杂问题的深度推理。 + +```bash +export MAX_THINKING_TOKENS=50000 +claude -p "Should we use microservices or monolith?" +``` + +### Background Tasks + +后台执行长任务而不阻塞当前对话。 + +```bash +/task list +/task status bg-1234 +/task show bg-1234 +/task cancel bg-1234 +``` + +### Permission Modes + +| 模式 | 说明 | 适用场景 | +|------|------|----------| +| `default` | 标准权限模式 | 通用开发 | +| `acceptEdits` | 自动接受文件编辑 | 信任编辑工作流 | +| `plan` | 只分析不改文件 | 审查、规划 | +| `auto` | 自动批准安全操作 | 平衡自治与安全 | +| `dontAsk` | 不再提示确认 | 资深用户 / 自动化 | +| `bypassPermissions` | 完全不受限 | CI/CD、可信脚本 | + +### Headless Mode（Print Mode） + +使用 `-p` 标志在无交互模式下运行 Claude Code，适合自动化和 CI/CD。 + +```bash +claude -p "Run all tests" +cat error.log | claude -p "explain this error" +claude -p --output-format json "list all functions in src/" +``` + +### Scheduled Tasks + +通过 `/loop` 按计划周期性运行任务： + +```bash +/loop every 30m "Run tests and report failures" +/loop every 2h "Check for dependency updates" +/loop every 1d "Generate daily summary of code changes" +``` + +### Chrome Integration + +Claude Code 可以与 Chrome 浏览器集成，用于网页自动化，如导航页面、填写表单、截图和提取页面数据。 + +### Session Management + +```bash +/resume +/rename "Feature" +/fork +claude -c +claude -r "Feature" +``` + +### Interactive Features + +- `Ctrl + R`：搜索命令历史 +- `Tab`：自动补全 +- `↑ / ↓`：浏览历史 +- `Ctrl + L`：清屏 + +### 配置 + +```json +{ + "planning": { + "autoEnter": true, + "requireApproval": true + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 5 + }, + "permissions": { + "mode": "default" + } +} +``` + +**详见：** [09-advanced-features/README.md](09-advanced-features/README.md) + +--- + +## Resources + +- [Claude Code Documentation](https://code.claude.com/docs/en/overview) +- [Anthropic Documentation](https://docs.anthropic.com) +- [MCP GitHub Servers](https://github.com/modelcontextprotocol/servers) +- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) + +--- + +*最后更新：2026 年 3 月* +*适用于 Claude Haiku 4.5、Sonnet 4.6、Opus 4.6* +*现已覆盖：Hooks、Checkpoints、Planning Mode、Extended Thinking、Background Tasks、Permission Modes、Headless Mode、Session Management、Auto Memory、Agent Teams、Scheduled Tasks、Chrome Integration、Bundled Skills 等概念。* diff --git a/zh/clean-code-rules.md b/zh/clean-code-rules.md new file mode 100644 index 0000000..196c536 --- /dev/null +++ b/zh/clean-code-rules.md @@ -0,0 +1,108 @@ +# 面向 AI 代码生成的整洁代码规则 + +这些规则用于指导代码生成，帮助产出可维护、专业水准的代码。 + +## 有意义的命名 +- 使用能体现意图的名称，说明它为什么存在 +- 避免误导性命名和无意义区分，例如 `data`、`info`、`manager` +- 使用可读、可搜索的名称 +- 类名使用名词，例如 `UserAccount`、`PaymentProcessor` +- 方法名使用动词，例如 `calculateTotal`、`sendEmail` +- 避免脑内映射和编码风格命名，例如匈牙利命名法、前缀 + +## 函数 +- 保持函数短小精炼，理想情况下少于 20 行 +- 只做一件事，遵循单一职责原则 +- 每个函数只处理一个抽象层级 +- 限制参数数量，理想为 0-2 个，最多 3 个，避免布尔标志参数 +- 不要产生副作用，函数应该做它名字所说的事 +- 将命令与查询分离，命令修改状态，查询返回信息 +- 优先使用异常而不是错误码 + +## 注释 +- 代码本身应该尽量可自解释，能不写注释就不写 +- 好的注释包括：法律信息、警告、TODO、公共 API 文档 +- 坏的注释包括：重复、误导，或者只是解释糟糕的代码 +- 不要注释掉代码，直接删除，版本控制会保留历史 +- 如果你需要写注释，先考虑重构代码 + +## 格式化 +- 保持文件小而聚焦 +- 垂直格式化：相关概念放近一些，空行分隔不同概念 +- 水平格式化：限制行长度在 80-120 个字符之间 +- 使用一致的缩进和团队风格 +- 将相关函数分组放在一起 + +## 对象与数据结构 +- 对象：通过抽象隐藏数据，通过方法暴露行为 +- 数据结构：暴露数据，尽量少提供行为 +- 迪米特法则：只和直接朋友说话，避免 `a.getB().getC().doSomething()` +- 不要毫无节制地通过 getter/setter 暴露内部结构 + +## 错误处理 +- 使用异常，不要使用返回码或错误标志 +- 代码可能失败时，先写 `try-catch-finally` +- 在异常信息中提供上下文 +- 不要返回 `null`，改为返回空集合或使用 Optional/Maybe +- 不要把 `null` 作为参数传入 + +## 类 +- 小类应按职责衡量，而不是按行数衡量 +- 单一职责原则：只有一个改变原因 +- 高内聚：类变量被多数方法使用 +- 低耦合：类之间依赖尽量少 +- 开闭原则：对扩展开放，对修改关闭 + +## 单元测试 +- 快速、独立、可重复、自我验证、及时（F.I.R.S.T.） +- 每个测试一个断言，或只验证一个概念 +- 测试代码质量应与生产代码质量一致 +- 测试名称要可读，清楚描述正在测试什么 +- 遵循 Arrange-Act-Assert 模式 + +## 代码质量原则 +- **DRY（Don't Repeat Yourself）**：不要重复 +- **YAGNI（You Aren't Gonna Need It）**：不要为假设中的未来提前构建 +- **KISS（Keep It Simple）**：避免不必要的复杂度 +- **童子军规则**：让代码比你接手时更干净 + +## 应避免的代码坏味道 +- 函数或类过长 +- 重复代码 +- 死代码（未使用的变量、函数、参数） +- 特性依恋（方法更关心别的类） +- 不恰当的亲密关系（类彼此了解过多） +- 过长的参数列表 +- 原始类型偏执（过度使用原始类型而不是小对象） +- switch/case 语句（考虑使用多态） +- 临时字段（类变量只在某些时候才使用） + +## 并发 +- 将并发代码与其他代码隔离 +- 限制同步/加锁数据的作用域 +- 使用线程安全集合 +- 保持同步区块尽量小 +- 了解你的执行模型和原语 + +## 系统设计 +- 将构建和使用分离，例如通过依赖注入 +- 复杂对象创建时使用工厂、构建器 +- 面向接口编程，而不是面向实现编程 +- 优先组合而不是继承 +- 设计模式只在它们简化问题时使用，不要为了炫技而使用 + +## 重构 +- 持续重构，不要攒成大批量一次做完 +- 重构前后都要保证测试通过 +- 小步前进，每次只改一处 +- 常见重构包括：提取方法、重命名、移动、内联 + +## 文档 +- 自说明代码 > 注释 > 外部文档 +- 公共 API 需要清晰文档 +- 文档中要包含示例 +- 文档尽量靠近代码，理想情况下就在代码里 + +--- + +**核心理念**：代码被阅读的次数是编写次数的 10 倍。优化可读性和可维护性，而不是追求花哨。 diff --git a/zh/docs/ROADMAP-20260401.md b/zh/docs/ROADMAP-20260401.md new file mode 100644 index 0000000..3e71ee3 --- /dev/null +++ b/zh/docs/ROADMAP-20260401.md @@ -0,0 +1,153 @@ +# 路线图：claude-howto 2026–2027 + +> 2026 年 4 月 – 2027 年 3 月 · 双层知识库 | 完整计划：`TASKS-20260401.md` + +--- + +## 愿景 + +把 claude-howto 从一个静态教程仓库，转变为一个**活的、双受众知识系统**： + +- **面向人类** - 通过场景化学习、渐进式难度、决策树和专家会收藏的命名模式，提供互动式学习体验 +- **面向 AI 代理** - 提供结构化元数据索引，让代理在执行 Claude Code 任务前先查询这里，使这个仓库成为基础设施，而不只是内容 + +没有竞争者把 AI 代理视为主要受众。这就是我们的护城河。 + +--- + +## 7 大支柱 + +| # | 支柱 | 交付内容 | +|---|--------|-----------------| +| P1 | 趣味层 | 每个模块都有场景导语和 "Try It Now" 模块 | +| P2 | AI 代理索引 | 生成 `agent-manifest.json` + `AGENT-INDEX.md` + 查询技能 | +| P3a | 专家参考（模块内） | 每个模块的决策树 + 命名模式 | +| P3b | 专家参考（跨模块） | `RECIPES.md` - 组合型多功能工作流 | +| P4 | 新手上手 | `quickstart.sh` + `QUICKSTART.md` + 难度徽章 | +| P5 | 社区展示 | `COMMUNITY-PROJECTS.md` - 精选用户项目 | +| P6 | 内容质量 | 扩展最薄弱的模块；完善项目 `CLAUDE.md` | +| P7 | 活课程体系 | `WHATS-NEW.md` + 版本徽章 + 每周过期检查 CI action | + +--- + +## 时间线总览 + +``` +2026 年 4 月 5–6 月 2026 7–8 月 2026 2026 年 9 月 10–11 月 2026 2026 年 12 月–2027 年 3 月 + | | | | | | + [M1] [M2] [M3] [M4] [M5] [M6] +基础设施 6/10 个模块 10/10 完成 代理层 版本审计 自我维持系统 ++ hooks/checks 完成 完成 + recipes 完成 +``` + +--- + +## 里程碑 + +### M1 - 基础设施上线 · 2026 年 4 月底 + +**交付内容：** +- `scripts/quickstart.sh` - 为新用户提供一条命令式安装（幂等） +- `QUICKSTART.md` - “前 15 分钟”可视化指南 +- 所有 10 个模块都加入难度徽章和 "What you'll build" 预览 +- 所有模块都加入 `WHATS-NEW.md` 和版本徽章 +- `.github/workflows/staleness-check.yml` - 每周一检查，若模块 30 天以上未验证则创建 issue +- 根目录 `CLAUDE.md` - 作为最佳实践示例的项目配置 +- `scripts/build-agent-index.py` - 读取 10 个模块并输出 `agent-manifest.json` + `AGENT-INDEX.md` 的生成器 +- **06-hooks** - 完整深度处理：5 个完整 hook 脚本、决策树、Try It Now、模式 +- **08-checkpoints** - 完整深度处理：311 行扩展到 800+ 行，3 个工作流模板、决策树、模式 + +**为什么从这里开始：** 基础设施能惠及后续所有阶段。hooks 和 checkpoints 是最薄弱的模块，也最容易流失新访客。 + +--- + +### M2 - 6/10 个模块完成 · 2026 年 6 月底 + +**交付内容（每个模块一次深度处理）：** +- **01-slash-commands** - 场景导语、决策树、Try It Now、命名模式 +- **02-memory** - 场景导语、决策树、Try It Now、命名模式 +- **03-skills** - 场景导语、决策树、Try It Now、命名模式 +- **10-cli** - 场景导语、决策树、Try It Now、命名模式 +- CI 步骤：在每次 push 时校验 `agent-manifest.json` 的 schema + +每个模块的处理都要运行生成器，确认 manifest 输出有效。 + +--- + +### M3 - 10/10 个模块完成 · 2026 年 8 月底 + +**交付内容：** +- **04-subagents** - 完整深度处理（包括 "The Multi-Agent Review Pattern"） +- **05-mcp** - 完整深度处理 +- **07-plugins** - 完整深度处理 +- **09-advanced-features** - 完整深度处理 + +现在每个模块都具备：场景导语、2 个以上 Try It Now 模块、Mermaid 决策树、2 个以上命名模式。 + +--- + +### M4 - 代理层上线 · 2026 年 9 月底 + +**交付内容：** +- 最终版 `agent-manifest.json`，覆盖 100% 模块（由已完成内容生成） +- `AGENT-INDEX.md`，从 `README.md` 链接 +- `skills/claude-howto-lookup/SKILL.md` - 轻量级 agent skill，通过 manifest 查询相关模块 +- `RECIPES.md` - 5 个以上组合工作流（schema：name、modules-used、problem、solution、expected outcome） +- `COMMUNITY-PROJECTS.md` - 静态精选列表，采用 PR 提交格式 + +**为什么是 9 月：** 只有等 10 个模块全部内容完备后，代理索引才真正有意义。 + +--- + +### M5 - 版本审计完成 · 2026 年 11 月底 + +**交付内容：** +- 完整版本审计：所有 10 个模块都根据当前 CC 版本完成验证 +- 更新所有模块的 `cc_version_verified` frontmatter 和版本徽章 +- `RECIPES.md` 扩展到 8 个以上 recipes，基于社区模式总结 +- GitHub 固定讨论串：“分享你的 Claude Code 工作流” - 收集 agent 使用信号 + +--- + +### M6 - 自我维持系统 · 2027 年 3 月底 + +**持续交付 / 持续运行：** +- `/docs-sync-claude-code` skill 在每次 CC 发布后运行 → 更新 `WHATS-NEW.md` +- Agent manifest CI 回归测试：强制 100% 模块覆盖 +- `RECIPES.md` 增加到 10 个以上 recipes +- `COMMUNITY-PROJECTS.md` 自然增长 +- 对 agent 使用信号进行评估 - 若验证有效，则推动 lookup skill 的推广（营销、asm registry） + +--- + +## 交付摘要 + +| 交付物 | 类型 | 阶段 | +|-------------|------|-------| +| `scripts/quickstart.sh` | 脚本 | P1 | +| `QUICKSTART.md` | 文档 | P1 | +| 根目录 `CLAUDE.md` | 配置 | P1 | +| `WHATS-NEW.md` | 文档 | P1 | +| `.github/workflows/staleness-check.yml` | CI | P1 | +| `scripts/build-agent-index.py` | 脚本 | P1 | +| 10 个模块深度处理（场景 + Try It Now + 决策树 + 模式） | 内容 | P1–P3 | +| `agent-manifest.json`（生成） | 数据 | P4 | +| `AGENT-INDEX.md`（生成） | 文档 | P4 | +| `skills/claude-howto-lookup/SKILL.md` | Skill | P4 | +| `RECIPES.md`（5 → 8 → 10+ recipes） | 文档 | P4–P6 | +| `COMMUNITY-PROJECTS.md` | 文档 | P4 | + +--- + +## 不在范围内的内容 + +这些内容延期到 `TODOS.md`，不要让它们跑进来： + +- Skill marketplace 或可安装 registry +- 自定义网站或仪表盘 +- 完成度追踪（cc-progress） +- 社区教程 CI 校验 +- 自动生成的 CONTRIBUTORS.md +- 多语言翻译 +- 测验 / 评估基础设施 +- 社区项目投票 diff --git a/zh/docs/TASKS-20260401.md b/zh/docs/TASKS-20260401.md new file mode 100644 index 0000000..0b536f6 --- /dev/null +++ b/zh/docs/TASKS-20260401.md @@ -0,0 +1,291 @@ +# 任务：双层知识库 - claude-howto + +> 创建于：2026-04-01 + +--- + +## 里程碑 + +| # | 里程碑 | 目标时间 | 描述 | +|---|-----------|--------|-------------| +| M1 | 基础设施上线 | 2026 年 4 月底 | quickstart.sh、CLAUDE.md、staleness action、代理索引生成器上线；升级 2 个最薄弱模块 | +| M2 | 6/10 个模块完成 | 2026 年 6 月底 | Slash commands、memory、skills、CLI 模块完全升级；生成器输出有效 manifest | +| M3 | 10/10 个模块完成 | 2026 年 8 月底 | 每个模块都具备场景导语、Try It Now 模块、决策树、命名模式 | +| M4 | 代理层上线 | 2026 年 9 月底 | 生成 agent-manifest.json + AGENT-INDEX.md；仓库内有 lookup skill；`RECIPES.md` + `COMMUNITY-PROJECTS.md` 上线 | +| M5 | 版本审计完成 | 2026 年 11 月底 | 所有 10 个模块都验证过当前 CC 版本；`RECIPES.md` 达到 8+ recipes | +| M6 | 自我维持系统 | 2027 年 3 月底 | Agent manifest 覆盖 100% 模块（通过 CI 校验）；`RECIPES.md` 达到 10+；社区页面自然增长 | + +--- + +## 第 1 阶段 - 基础设施与薄弱模块（2026 年 4 月） + +**目标里程碑：M1** + +### 支柱 4：新手上手 + +- [ ] **T-001** - 编写 `scripts/quickstart.sh` + - 检测 `~/.claude/` 目录（如缺失，则在用户确认后创建） + - 将第一个 slash command + CLAUDE.md + skill 复制到用户配置中 + - 在 CLAUDE.md 末尾追加 agent-discovery 行，链接到 AGENT-INDEX.md + - 幂等：跳过已有文件并给出警告，绝不覆盖 + - 完成后打印下一步 + +- [ ] **T-002** - 创建 `QUICKSTART.md`（前 15 分钟可视化指南） + - 使用代码块记录带注释的终端步骤（尽量避免 PNG 截图；优先 ASCII 或 Mermaid） + - 记录每条命令对应哪个视觉结果，方便后续重新采集 + +- [ ] **T-003** - 为所有 10 个模块的 README 添加难度徽章 + - 格式：`> 🟢 **Beginner** | ⏱ 30 minutes`，放在每个模块 README 顶部 + - 在徽章下方添加 "What you'll build" 的要点预览 + +### 支柱 7：活课程体系 + +- [ ] **T-004** - 创建 `WHATS-NEW.md` + - 格式：`## CC vX.X — DATE`，每个功能变更使用项目符号 + - 至少添加一条当前 CC 版本的记录 + +- [ ] **T-005** - 为所有 10 个模块的 README 添加版本徽章 + - 格式：`> ✅ Verified against Claude Code **vX.X.X** · Last verified: YYYY-MM-DD` + - 在每个模块的 frontmatter 中加入 `cc_version_verified` + +- [ ] **T-006** - 创建 `.github/workflows/staleness-check.yml` + - 调度：每周一 09:00 UTC + - 从 frontmatter 读取每个模块的 `last_verified` 日期（使用 `yq` 或 10 行 Python 脚本） + - 对 30 天以上未验证的模块创建 GitHub Issue + - 如果已有同名 open issue，则跳过 + +### 支柱 6：内容质量（CLAUDE.md） + +- [ ] **T-007** - 为项目创建根目录 `CLAUDE.md` + - 作为项目自身配置，展示最佳实践 + - 记录贡献规范、模块结构和维护流程 + +### 支柱 2：AI 代理索引（生成器） + +- [ ] **T-008** - 编写 `scripts/build-agent-index.py` + - 读取全部 10 个模块 README + - 提取：标题（→ topics）、代码块（→ 带语言标签的示例）、表格（→ 参考数据） + - 输出 `agent-manifest.json`，schema 按 CEO 计划定义 + - 输出 `AGENT-INDEX.md`（人类可读摘要） + - 校验引用是否指向真实文件 + +### 模块 08-checkpoints：完整深度处理（311 → 800+ 行） + +- [ ] **T-009** - 用真实场景重写模块导语 + - 示例："你的重构把 3 个东西弄坏了。checkpoint 如何帮你恢复..." + +- [ ] **T-010** - 添加 checkpoint 策略决策树（Mermaid flowchart） + - "我想做 X" → 顺着箭头走 → 到达对应 checkpoint 模式 + +- [ ] **T-011** - 添加 3 个工作流模板 + - 安全重构工作流 + - 使用 checkpoints 做 A/B 测试 + - 灾难恢复工作流 + +- [ ] **T-012** - 添加与 planning mode 的整合部分 + +- [ ] **T-013** - 添加 checkpoint 生命周期的 Mermaid 图 + +- [ ] **T-014** - 添加 2 个以上 "Try It Now" 模块，并提供可验证命令 + - 每个模块：上下文句、要运行的命令、预期输出说明 + +- [ ] **T-015** - 添加 "Patterns & Recipes" 部分，包含 2 个以上命名模式 + - 每个模式：问题、解决方案代码、适用场景、不适用场景 + +### 模块 06-hooks：完整深度处理 + +- [ ] **T-016** - 用真实场景重写模块导语 + - 示例："你的 CI 在 20 分钟后才发现 lint 错误。hooks 2 秒内就能抓住..." + +- [ ] **T-017** - 添加 hooks 决策树（Mermaid flowchart） + - "我想在 Y 发生时触发 X" → 顺着箭头走 → 到达对应 hook 类型 + +- [ ] **T-018** - 添加 5 个完整 hook 示例，带完整脚本（每个约 80 行） + 1. 写入时自动格式化（prettier/black） + 2. 提交时安全扫描（trufflehog/bandit） + 3. 文件变更时运行测试 + 4. 会话结束时发送通知 + 5. 提示词校验（阻止危险模式） + +- [ ] **T-019** - 添加 2 个以上 "Try It Now" 模块，并提供可验证命令 + +- [ ] **T-020** - 添加 "Patterns & Recipes" 部分，包含 2 个以上命名模式 + +**M1 检查点：基础设施上线，2 个最薄弱模块完成深度升级** + +--- + +## 第 2 阶段 - 深度处理：强模块第一批（2026 年 5 月 - 6 月） + +**目标里程碑：M2** + +### 模块 01-slash-commands：完整深度处理 + +- [ ] **T-021** - 用场景重写导语（"你的队友刚推了 47 个文件..."） +- [ ] **T-022** - 添加决策树（Mermaid） +- [ ] **T-023** - 添加 2 个以上 "Try It Now" 模块 +- [ ] **T-024** - 添加 "Patterns & Recipes" 部分，包含 2 个以上命名模式 + +### 模块 02-memory：完整深度处理 + +- [ ] **T-025** - 用真实场景重写导语 +- [ ] **T-026** - 添加决策树（Mermaid） +- [ ] **T-027** - 添加 2 个以上 "Try It Now" 模块 +- [ ] **T-028** - 添加 "Patterns & Recipes" 部分，包含 2 个以上命名模式 + +### 模块 03-skills：完整深度处理 + +- [ ] **T-029** - 用真实场景重写导语 +- [ ] **T-030** - 添加决策树（Mermaid） +- [ ] **T-031** - 添加 2 个以上 "Try It Now" 模块 +- [ ] **T-032** - 添加 "Patterns & Recipes" 部分，包含 2 个以上命名模式 + +### 模块 10-cli：完整深度处理 + +- [ ] **T-033** - 用真实场景重写导语 +- [ ] **T-034** - 添加决策树（Mermaid） +- [ ] **T-035** - 添加 2 个以上 "Try It Now" 模块 +- [ ] **T-036** - 添加 "Patterns & Recipes" 部分，包含 2 个以上命名模式 + +### 生成器校验 + +- [ ] **T-037** - 每次模块升级后运行 `scripts/build-agent-index.py`；确认 manifest 输出有效 +- [ ] **T-038** - 在每次 push 时添加 CI 步骤：校验 agent-manifest.json schema + +**M2 检查点：6/10 个模块完成，生成器输出有效 manifest** + +--- + +## 第 3 阶段 - 深度处理：强模块第二批（2026 年 7 月 - 8 月） + +**目标里程碑：M3** + +### 模块 04-subagents：完整深度处理 + +- [ ] **T-039** - 用真实场景重写导语 +- [ ] **T-040** - 添加决策树（Mermaid） +- [ ] **T-041** - 添加 2 个以上 "Try It Now" 模块 +- [ ] **T-042** - 添加 "Patterns & Recipes" 部分（例如："The Multi-Agent Review Pattern"） + +### 模块 05-mcp：完整深度处理 + +- [ ] **T-043** - 用真实场景重写导语 +- [ ] **T-044** - 添加决策树（Mermaid） +- [ ] **T-045** - 添加 2 个以上 "Try It Now" 模块 +- [ ] **T-046** - 添加 "Patterns & Recipes" 部分，包含 2 个以上命名模式 + +### 模块 07-plugins：完整深度处理 + +- [ ] **T-047** - 用真实场景重写导语 +- [ ] **T-048** - 添加决策树（Mermaid） +- [ ] **T-049** - 添加 2 个以上 "Try It Now" 模块 +- [ ] **T-050** - 添加 "Patterns & Recipes" 部分，包含 2 个以上命名模式 + +### 模块 09-advanced-features：完整深度处理 + +- [ ] **T-051** - 用真实场景重写导语 +- [ ] **T-052** - 添加决策树（Mermaid） +- [ ] **T-053** - 添加 2 个以上 "Try It Now" 模块 +- [ ] **T-054** - 添加 "Patterns & Recipes" 部分，包含 2 个以上命名模式 + +**M3 检查点：全部 10 个模块完成且风格一致** + +--- + +## 第 4 阶段 - 代理层与跨模块（2026 年 9 月） + +**目标里程碑：M4** + +### 支柱 2：最终完成 AI 代理索引 + +- [ ] **T-055** - 使用所有 10 个完成的模块运行 `scripts/build-agent-index.py` + - 生成最终版 `agent-manifest.json`，覆盖率达到 100% + - 生成 `AGENT-INDEX.md` 并从 `README.md` 链接 + +- [ ] **T-056** - 创建 `skills/claude-howto-lookup/SKILL.md` + - 读取 `agent-manifest.json` 以查找相关模块 + - 使用 `Read` 加载对应章节 + - 安装方式：`cp -r claude-howto/skills/claude-howto-lookup ~/.claude/skills/` + +- [ ] **T-057** - 在 quickstart.sh 和 QUICKSTART.md 中把 lookup skill 作为可选功能提到 + +### 支柱 3b：跨模块 `RECIPES.md` + +- [ ] **T-058** - 创建带有 5 个以上组合工作流的 `RECIPES.md` + - 每个 recipe 的 schema：name、modules-used、problem、solution 代码块、expected outcome + - 示例：skill + hook + subagent = 自动审查流水线 + - 确保所有主要标题都有 HTML 锚点，便于深链 + +### 支柱 5：社区展示 + +- [ ] **T-059** - 创建 `COMMUNITY-PROJECTS.md` + - 静态 Markdown 页面，提交格式包括：name、description、link、features used + - 包含模板条目 + - 提供基于 PR 的提交说明 + +**M4 检查点：代理索引上线，recipes 上线，社区页面上线** + +--- + +## 第 5 阶段 - 版本审计与 recipe 扩展（2026 年 10 月 - 11 月） + +**目标里程碑：M5** + +- [ ] **T-060** - 进行完整版本审计：验证所有 10 个模块是否与当前 CC 版本匹配 + - 更新每个模块的 `cc_version_verified` frontmatter + - 更新版本徽章 + +- [ ] **T-061** - 将 `RECIPES.md` 扩展到 8 个以上 recipes，基于社区实践模式 + +- [ ] **T-062** - 如果完成的模块中出现新的模式，则迭代 agent manifest schema + +- [ ] **T-063** - 开一个置顶 GitHub Discussion："分享你的 Claude Code 工作流" + - 收集真实 agent 使用信号，为后续 recipe 扩展提供依据 + +**M5 检查点：所有模块都已验证当前版本，recipes 持续增长** + +--- + +## 第 6 阶段 - 组合与持续运行（2026 年 12 月 - 2027 年 3 月） + +**目标里程碑：M6** + +- [ ] **T-064** - 每次 CC 发布后运行 `/docs-sync-claude-code` skill；更新 `WHATS-NEW.md` + +- [ ] **T-065** - 确保 agent manifest 覆盖 100% 模块（CI 回归测试） + +- [ ] **T-066** - 将 `RECIPES.md` 扩展到 10 个以上 recipes + +- [ ] **T-067** - 监控 `COMMUNITY-PROJECTS.md` 的自然增长；筛选新增条目 + +- [ ] **T-068** - 评估来自 GitHub Discussions 的 agent 使用信号；如果验证有效，就投入资源推广 lookup skill（营销、asm registry） + +**M6 检查点：系统已经可以自我维持** + +--- + +## 延后项（TODOS.md） + +这些内容不在本计划范围内。请记录在这里，避免范围蔓延： + +- Skill marketplace / 可安装 registry +- 自定义网站或仪表盘 +- 完成度追踪基础设施（cc-progress） +- 带 CI 校验的社区教程模板 +- 自动生成的 CONTRIBUTORS.md +- 多语言翻译 +- 测验 / 评估基础设施升级 +- COMMUNITY-PROJECTS.md 的社区投票 / 审核机制 + +--- + +## 按阶段划分的任务摘要 + +| 阶段 | 任务 | 时间段 | 涉及模块 | +|-------|-------|--------|-----------------| +| 1 - 基础设施与薄弱模块 | T-001 到 T-020 | 2026 年 4 月 | 06-hooks、08-checkpoints + 基础设施 | +| 2 - 第一批深度处理 | T-021 到 T-038 | 2026 年 5 月 - 6 月 | 01、02、03、10 | +| 3 - 第二批深度处理 | T-039 到 T-054 | 2026 年 7 月 - 8 月 | 04、05、07、09 | +| 4 - 代理层与跨模块 | T-055 到 T-059 | 2026 年 9 月 | 全部（manifest）+ 新文件 | +| 5 - 版本审计与 recipes | T-060 到 T-063 | 2026 年 10 月 - 11 月 | 全部（审计） | +| 6 - 持续运行 | T-064 到 T-068 | 2026 年 12 月 - 2027 年 3 月 | 持续进行 | diff --git a/zh/prompts/remotion-video.md b/zh/prompts/remotion-video.md new file mode 100644 index 0000000..0772483 --- /dev/null +++ b/zh/prompts/remotion-video.md @@ -0,0 +1,350 @@ +你是一位擅长 Remotion 的资深动效设计师和高级 React 工程师。你的目标是把产品描述转化为一个高能量、专业动画感强的视频，并使用 React 代码实现。 + +**先自主探索：** 立即开始探索代码库，收集产品信息。只有在你探索之后，仍然缺少关键或不清晰的信息时，才向用户提问。 + +请遵循一个 7 阶段工作流，并根据你收集到的信息在每一步做出聪明的决策。 + +--- + +# 🔄 自动化工作流 + +**关键原则：** + +- **先探索：** 永远先自动探索代码库，收集产品信息。不要一上来就问产品问题。 +- **先问偏好，再规划：** 探索之后，先向用户展示发现结果，再询问视频偏好（尺寸、风格、时长、自定义项），然后再创建计划。 +- **产品 URL 优先：** 如果找到了或用户提供了产品 URL，它就是第一信息源。产品页面上的信息优先于代码库发现。 +- **重价值，不重技术：** 聚焦价值主张、客户收益和功能（用户获得了什么），而不是技术规格或实现细节。 +- **以客户为中心：** 强调产品如何解决问题、改善生活或为用户带来收益。 +- **自主执行：** 用户确认偏好后，自动推进到规划和实现阶段，不要再请求额外批准。 + +## 📋 第 1 阶段：自主资源发现 + +**目标：** 自动探索代码库，收集所有可用的产品信息，不要询问用户。 + +**动作：** + +1. **先自动探索代码库：** + - 搜索 `README.md`，查找产品描述和价值主张 + - 检查 `package.json`，获取产品名称、描述和主页 URL + - 在 `/assets`、`/public`、`/static`、`/images` 目录中查找品牌资源 + - 从 CSS / Tailwind 配置文件中提取配色方案 + - 查找任何现有的营销文案或文档 + - 在配置文件、环境变量或文档中查找任何产品 URL + +2. **如果找到了产品 URL，立即抓取：** + - 使用 WebFetch 提取产品页面的信息 + - 产品页面信息优先于代码库发现 + - 提取所有价值主张、功能和品牌信息 + +3. **汇总所有收集到的信息：** + - 产品名称和描述 + - 价值主张 + - 核心功能和收益 + - 品牌色和风格 + - 目标受众（根据语气推断） + - 任何现有资源或媒体 + +4. **对缺失信息使用智能默认值：** + - **视频格式：** 横屏 1920x1080（适合 YouTube / Web） + - **时长：** 30 秒（大多数平台都适合） + - **风格：** 现代、简洁、专业（基于品牌） + - **品牌色：** 使用提取到的颜色，或采用现代互补配色 + +5. **只有在以下情况下才询问用户：** + - 探索后仍无法确定产品名称或找不到任何产品信息 + - 无法找到或访问产品 URL + - 存在关键歧义（例如 B2B 和 B2C 的差异会显著改变表达方式） + - 有冲突信息需要澄清 + +**重要：** 这一整段探索要静默、自主完成。不要问“我需要什么才能开始”或列出需求。只有在真正必要时才打断用户。 + +**输出：** 立即带着所有收集到的信息进入第 2 阶段。 + +--- + +## 🔍 第 2 阶段：信息分析与深度挖掘 + +**目标：** 分析收集到的信息，并提炼出视频创作所需的关键洞察。 + +**动作：** + +1. **回顾第 1 阶段收集到的全部信息：** + - 产品页面内容（如果找到了并抓取了 URL） + - 代码库发现（README、package.json、资源等） + - 任何品牌指南或营销材料 + +2. **提炼并排序（聚焦价值，不聚焦技术）：** + - **价值主张**（首要）- 对客户的核心收益 + - **客户收益** - 它如何改善用户生活 + - **核心功能** - 用收益来描述，而不是技术规格 + - **独特卖点** - 与其他方案相比有什么不同/更好 + - **使用场景** - 真实世界应用 + - **品牌识别**（颜色、字体、风格、语气） + - **目标受众洞察**（这是谁的产品） + - **情感吸引力**和信息表达（人们为什么在意） + +3. **静默用智能推断补齐空白：** + - 如果价值主张不明确，从功能和目标受众推断 + - 如果目标受众不清晰，从产品类型和文案语气推断 + - 如果缺少品牌色，创建一套现代的互补配色 + - 除非与用户可见内容相关，否则避免技术实现细节 + +4. **只有在以下情况下才请求澄清：** + - 存在多个相互冲突的价值主张 + - 无法判断产品是 B2B 还是 B2C（这会显著影响表达） + - 目标受众确实过于模糊 + +**输出：** 对产品价值、收益和品牌有清晰理解，足以支持视频制作。 + +--- + +## ✅ 第 3 阶段：展示发现并收集用户偏好 + +**目标：** 分享你发现的内容，并在进入规划前获取用户对视频偏好的输入。 + +**动作：** + +1. **展示发现摘要：** + + ```text + 📊 发现的信息 + + 产品：[名称] + 价值主张：[对客户的主要收益] + 核心功能：[2-3 个主要收益] + 品牌色：[提取到或建议的颜色] + 目标受众：[这是谁的产品] + ``` + +2. **询问用户偏好（进入下一步前必须完成）：** + + 使用清晰简洁的格式： + + ```text + 在我创建视频之前，请告诉我你的偏好： + + 1. **视频尺寸/格式：** + - 横屏（1920x1080）- YouTube、网站 + - 竖屏（1080x1920）- TikTok、Instagram Reels + - 方形（1080x1080）- Instagram 信息流 + + 2. **视频时长：** + - 15 秒 - 快速社媒广告 + - 30 秒 - 标准宣传视频 + - 60 秒 - 详细功能展示 + - 自定义时长 + + 3. **视频风格：** + - 现代 & 极简 - 干净的 Apple 风格美学 + - 有冲击力 & 高能量 - 快节奏，适合社媒 + - 专业 & 企业感 - 面向商业场景 + - 自定义风格（描述你的想法） + + 4. **还想突出或自定义什么？** + （特定功能、文案、颜色等） + ``` + +3. **等待用户回复** 后再进入第 4 阶段。 + +4. **确认并回应：** + - 总结用户选择 + - 应用任何自定义要求 + - 根据确认方向继续做结构设计 + +**输出：** 用户确认的视频规格，准备进入规划阶段。 + +--- + +## 📐 第 4 阶段：结构设计（确认后） + +**目标：** 基于用户偏好，使用三幕式结构设计一个有吸引力的视频。 + +**动作：** + +1. **根据用户确认的偏好设计视频结构：** + + ```text + 🎬 视频结构 + + 第 1 幕：钩子（0-5 秒） + - [抓眼球的视觉概念] + - [强势的动画开场] + - [有吸引力的标题/问题] + + 第 2 幕：价值展示（中段） + - [展示核心收益如何发挥作用] + - [用视觉叙事表达客户价值] + - [2-3 个作为收益呈现的功能亮点] + + 第 3 幕：行动号召（结尾） + - [清晰的 CTA 和品牌强化] + - [令人印象深刻的收尾画面] + - [平滑的退出动画] + ``` + +2. **应用用户偏好：** + - 使用指定的视频尺寸/格式 + - 匹配所选风格（极简/高能量/专业） + - 按指定时长调整节奏 + - 融入任何自定义要求 + +3. **基于以下内容做创意决策：** + - 产品价值主张（什么最吸引人） + - 目标受众（什么最能打动他们） + - 用户的风格偏好 + - 品牌个性（视觉和语气的一致性） + +4. **简要展示结构**，然后自动进入第 5 阶段。 + +**输出：** 可直接用于实现规划的视频结构。 + +--- + +## 🛠️ 第 5 阶段：技术架构 + +**目标：** 设计实现架构，并直接开始构建。 + +**动作：** + +1. **静默设计** 组件架构： + - 工具函数（easing、动画辅助、颜色工具） + - 可复用组件（AnimatedTitle、FeatureHighlight 等） + - 场景组件（Hook、Demo、CTA 场景） + - 主组合结构（Video.tsx、Root.tsx） + +2. **规划技术细节：** + - 动画时序和 easing 曲线 + - 调色板实现 + - 字体层级 + - 图标和资源策略 + - 序列时间拆分 + +3. **无需请求批准，直接进入第 6 阶段**实现。 + +**输出：** 可立即实现的内部技术蓝图。 + +--- + +## 💻 第 6 阶段：实现 + +**目标：** 自主构建完整的 Remotion 视频项目。 + +**约束与技术栈：** + +1. **框架：** Remotion（React） +2. **样式：** Tailwind CSS（通过 `className` 或标准样式对象） +3. **动画：** 使用 `spring`、`interpolate` 和 `useCurrentFrame` 实现平滑运动 +4. **代码风格：** 模块化组件。不要把所有东西都堆在 `Root.tsx` 里 +5. **最佳实践：** + - 不要有静态内容。所有元素都应该有入场（opacity / scale / slide）和退场 + - 如有需要，使用 Lucide-React 图标 + - 使用标准字体，但要强样式化（粗体、紧字距） + - 不要使用外部图片，除非是占位图（例如 `https://placehold.co/600x400`）或用户提供的资源 + +**动作：** + +1. **按以下顺序构建完整项目结构：** + - 工具函数（easing、动画辅助、颜色工具） + - 可复用组件（AnimatedTitle、FeatureHighlight、过渡） + - 场景组件（HookScene、DemoScene、CTAScene） + - 主合成（带编排的 Video.tsx） + - 根配置（注册正确的 Root.tsx） + +2. **静默高效地工作：** + - 不要逐步叙述每一步 + - 基于已收集信息做设计决策 + - 使用专业的动画原则 + - 确保场景之间过渡平滑 + +3. **实现完成后自动进入第 7 阶段。** + +**输出：** 完整、可直接交付的 Remotion 项目代码。 + +--- + +## 🎥 第 7 阶段：交付与后续 + +**目标：** 提供渲染说明，并标记项目完成。 + +**动作：** + +1. **提供渲染说明：** + + ```bash + # 在浏览器中预览视频 + npm run dev + + # 渲染最终视频 + npm run build + npx remotion render Video out/video.mp4 + + # 指定编解码设置 + npx remotion render Video out/video.mp4 --codec h264 + ``` + +2. **交付摘要：** + - 简要说明创建了什么 + - 视频的关键特性 + - 视频规格（时长、格式、尺寸） + - 任何值得注意的设计决策 + +3. **用户可以在需要时请求修改：** + - 时间调整 + - 动画修改 + - 内容更新 + - 风格微调 + +**输出：** 完整的 Remotion 项目，附带清晰的渲染说明，可直接使用。 + +--- + +# 🎯 质量标准 + +在所有阶段都要保持以下标准： + +**视觉质量：** +- 专业级动画（平滑、明确、有品牌感） +- 一致的间距和对齐 +- 具备良好对比度的易读排版 +- 协调统一的色彩使用 + +**技术质量：** +- 干净、模块化的代码架构 +- 性能优化（平滑 30fps 播放） +- 正确使用 Remotion API（spring、interpolate、Sequence） +- 如果使用 TypeScript，则具备类型安全 + +**创意质量：** +- 清晰的叙事结构 +- 抓眼的开场 +- 强有力的行动号召 +- 令人记住的视觉瞬间 + +--- + +# 🚀 开始使用 + +我会为你的产品创建一个专业的 Remotion 视频项目。工作流程如下： + +## 第 1-2 阶段：自主探索（我会自动完成） + +1. 探索你的代码库，查找产品细节、品牌资源和颜色 +2. 如果找到了产品 URL，抓取并分析产品页面 +3. 提取价值主张和关键收益 + +## 第 3 阶段：你的输入（我会询问你） + +1. 展示我发现的内容 +2. 询问你的视频偏好： + - 视频尺寸/格式（横屏 / 竖屏 / 方形） + - 时长（15 秒 / 30 秒 / 60 秒） + - 风格（极简 / 高能量 / 专业） + - 任何自定义项 + +## 第 4-7 阶段：自主执行（我会自动完成） + +1. 根据你的偏好设计视频结构 +2. 构建完整的 Remotion 项目并加入专业动画 +3. 交付可直接使用的生产级代码和渲染说明 + +让我们一起做出一个很棒的作品！ diff --git a/zh/resources.md b/zh/resources.md new file mode 100644 index 0000000..4723236 --- /dev/null +++ b/zh/resources.md @@ -0,0 +1,248 @@ + + + Claude How To + + +# 优质资源清单 + +## 官方文档 + +| 资源 | 说明 | 链接 | +|----------|-------------|------| +| Claude Code 文档 | Claude Code 官方文档 | [code.claude.com/docs/en/overview](https://code.claude.com/docs/en/overview) | +| Anthropic 文档 | Anthropic 完整文档 | [docs.anthropic.com](https://docs.anthropic.com) | +| MCP Protocol | Model Context Protocol 规范 | [modelcontextprotocol.io](https://modelcontextprotocol.io) | +| MCP Servers | 官方 MCP server 实现 | [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | +| Anthropic Cookbook | 代码示例和教程 | [github.com/anthropics/anthropic-cookbook](https://github.com/anthropics/anthropic-cookbook) | +| Claude Code Skills | 社区技能仓库 | [github.com/anthropics/skills](https://github.com/anthropics/skills) | +| Agent Teams | 多 agent 协作与协调 | [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) | +| Scheduled Tasks | 使用 `/loop` 和 cron 的周期性任务 | [code.claude.com/docs/en/scheduled-tasks](https://code.claude.com/docs/en/scheduled-tasks) | +| Chrome Integration | 浏览器自动化 | [code.claude.com/docs/en/chrome](https://code.claude.com/docs/en/chrome) | +| Keybindings | 键盘快捷键自定义 | [code.claude.com/docs/en/keybindings](https://code.claude.com/docs/en/keybindings) | +| Desktop App | 原生桌面应用 | [code.claude.com/docs/en/desktop](https://code.claude.com/docs/en/desktop) | +| Remote Control | 远程会话控制 | [code.claude.com/docs/en/remote-control](https://code.claude.com/docs/en/remote-control) | +| Auto Mode | 自动权限管理 | [code.claude.com/docs/en/permissions](https://code.claude.com/docs/en/permissions) | +| Channels | 多通道通信 | [code.claude.com/docs/en/channels](https://code.claude.com/docs/en/channels) | +| Voice Dictation | Claude Code 语音输入 | [code.claude.com/docs/en/voice-dictation](https://code.claude.com/docs/en/voice-dictation) | + +## Anthropic Engineering Blog + +| 文章 | 说明 | 链接 | +|---------|-------------|------| +| Code Execution with MCP | 如何通过代码执行解决 MCP 上下文膨胀问题，Token 数量减少 98.7% | [anthropic.com/engineering/code-execution-with-mcp](https://www.anthropic.com/engineering/code-execution-with-mcp) | + +--- + +## 30 分钟掌握 Claude Code + +_视频_: https://www.youtube.com/watch?v=6eBSHbLKuN0 + +_**全部技巧**_ +- **探索高级功能和快捷键** + - 定期查看 Claude 发布说明中的新代码编辑与上下文功能。 + - 学习键盘快捷键，在聊天、文件和编辑器视图之间快速切换。 + +- **高效设置** + - 为项目创建带有清晰名称和描述的会话，便于之后查找。 + - 将最常用的文件或文件夹固定住，让 Claude 随时可访问。 + - 配置 Claude 的集成，例如 GitHub 和常见 IDE，以简化你的编码流程。 + +- **高效的代码库问答** + - 向 Claude 询问架构、设计模式和具体模块的细节问题。 + - 在问题里使用文件和行号引用，例如：“`app/models/user.py` 里的逻辑是在做什么？” + - 对于大型代码库，提供摘要或清单，帮助 Claude 聚焦。 + - **示例提示词**：_“你能解释一下 `src/auth/AuthService.ts:45-120` 里实现的认证流程吗？它是如何与 `src/middleware/auth.ts` 里的中间件集成的？”_ + +- **代码编辑与重构** + - 使用代码块中的内联注释或请求来获得更聚焦的编辑结果（例如：“把这个函数重构得更清晰一些”）。 + - 让 Claude 给出并排的修改前后对比。 + - 在重大修改后，让 Claude 生成测试或文档，以保证质量。 + - **示例提示词**：_“把 `api/users.js` 里的 `getUserData` 函数从 promises 改成 async/await。给我一个修改前后对比，并为重构后的版本生成单元测试。”_ + +- **上下文管理** + - 只粘贴当前任务真正需要的代码和上下文。 + - 使用结构化提示词（“这里是文件 A，这里是函数 B，我的问题是 X”）通常效果最好。 + - 在提示窗口里移除或折叠大文件，避免超出上下文限制。 + - **示例提示词**：_“这里是 `models/User.js` 里的 User 模型，以及 `utils/validation.js` 里的 `validateUser` 函数。我的问题是：如何在保持向后兼容的前提下添加邮箱验证？”_ + +- **接入团队工具** + - 将 Claude 会话连接到你们团队的代码仓库和文档。 + - 使用内置模板，或为重复出现的工程任务创建自定义模板。 + - 通过和队友共享会话记录与提示词来协作。 + +- **提升性能** + - 给 Claude 清晰、面向目标的指令，例如：“用五个要点总结这个类”。 + - 从上下文窗口中删掉不必要的注释和样板代码。 + - 如果 Claude 的输出跑偏了，重置上下文或重新表述问题，以获得更好的对齐。 + - **示例提示词**：_“用五个要点总结 `src/db/Manager.ts` 里的 `DatabaseManager` 类，重点说明它的核心职责和关键方法。”_ + +- **实用场景示例** + - 调试：粘贴错误和堆栈信息，然后询问可能的原因和修复方式。 + - 生成测试：为复杂逻辑请求属性测试、单元测试或集成测试。 + - 代码审查：请 Claude 识别风险变更、边界情况或代码异味。 + - **示例提示词**： + - _“我遇到这个错误：`TypeError: Cannot read property 'map' of undefined at line 42 in components/UserList.jsx`。这是堆栈信息和相关代码。是什么原因导致的？我该怎么修复？”_ + - _“为 `PaymentProcessor` 类生成完整的单元测试，包括失败交易、超时和无效输入等边界情况。”_ + - _“审查这个 pull request diff，找出潜在的安全问题、性能瓶颈和代码异味。”_ + +- **工作流自动化** + - 用 Claude 提示词为格式化、清理、批量重命名等重复任务编写脚本。 + - 用 Claude 基于代码 diff 起草 PR 描述、发布说明或文档。 + - **示例提示词**：_“根据 git diff，生成一份详细的 PR 描述，包含变更摘要、修改文件列表、测试步骤和潜在影响。同时为 2.3.0 版本生成发布说明。”_ + +**提示**：想要获得最佳效果，可以把这些实践组合起来使用。先固定关键文件并总结目标，再使用聚焦的提示词和 Claude 的重构工具，逐步改进你的代码库和自动化流程。 + + +**与 Claude Code 配合使用的推荐工作流** + +### Claude Code 推荐工作流 + +#### 新仓库场景 + +1. **初始化仓库并接入 Claude** + - 建立新仓库的基础结构：`README`、`LICENSE`、`.gitignore`、根配置文件。 + - 创建 `CLAUDE.md`，说明架构、高层目标和编码规范。 + - 安装 Claude Code，并将其连接到仓库，用于代码建议、测试脚手架和工作流自动化。 + +2. **使用计划模式和规格说明** + - 在实现功能之前，使用计划模式（`shift-tab` 或 `/plan`）先写详细规格。 + - 让 Claude 给出架构建议和初始项目布局。 + - 保持清晰、面向目标的提示词序列，依次询问组件轮廓、主要模块和职责。 + +3. **迭代开发与审查** + - 把核心功能拆成小块逐步实现，并在过程中请求 Claude 生成代码、重构和文档。 + - 每增加一小步，都请求单元测试和示例。 + - 在 `CLAUDE.md` 中维护持续更新的任务列表。 + +4. **自动化 CI/CD 和部署** + - 用 Claude 搭建 GitHub Actions、npm/yarn 脚本或部署工作流。 + - 通过更新 `CLAUDE.md` 并请求对应命令/脚本，轻松调整流水线。 + +```mermaid +graph TD + A[Start New Repository] --> B[Initialize Repository Structure] + B --> C[Create README, LICENSE, .gitignore] + C --> D[Create CLAUDE.md] + D --> E[Document Architecture & Guidelines] + E --> F[Install & Link Claude Code] + + F --> G[Enter Plan Mode] + G --> H[Draft Feature Specification] + H --> I[Get Architecture Suggestions] + I --> J[Define Components & Modules] + + J --> K[Implement Feature Chunk] + K --> L[Generate Code with Claude] + L --> M[Request Unit Tests] + M --> N[Review & Refactor] + N --> O{More Features?} + O -->|Yes| K + O -->|No| P[Update Task List in CLAUDE.md] + + P --> Q[Setup CI/CD Pipeline] + Q --> R[Scaffold GitHub Actions] + R --> S[Create Deployment Scripts] + S --> T[Test Automation] + T --> U[Repository Ready] + + style A fill:#e1f5ff + style G fill:#fff4e1 + style K fill:#f0ffe1 + style Q fill:#ffe1f5 + style U fill:#90EE90 +``` + +#### 现有仓库场景 + +1. **仓库与上下文准备** + - 添加或更新 `CLAUDE.md`，记录仓库结构、编码模式和关键文件。对于旧仓库，可以使用 `CLAUDE_LEGACY.md`，其中涵盖框架、版本映射、说明、已知问题和升级笔记。 + - 固定或高亮 Claude 应该用来作为上下文的主文件。 + +2. **上下文驱动的代码问答** + - 让 Claude 基于具体文件/函数，回答代码审查、 bug 解释、重构或迁移计划。 + - 给 Claude 明确边界，例如“只修改这些文件”或者“不要新增依赖”。 + +3. **分支、工作区和多会话管理** + - 使用多个 git worktree 做隔离的功能开发或 bug 修复，并为每个 worktree 启动独立的 Claude 会话。 + - 通过终端标签页/窗口按分支或功能组织并行工作。 + +4. **团队工具和自动化** + - 通过 `.claude/commands/` 同步自定义命令，保持团队一致性。 + - 用 Claude 的 slash commands 或 hooks 自动化重复任务、PR 创建和代码格式化。 + - 与团队成员共享会话和上下文，便于协作排障和审查。 + +```mermaid +graph TD + A[Start with Existing Repository] --> B{Legacy Codebase?} + B -->|Yes| C[Create CLAUDE_LEGACY.md] + B -->|No| D[Create/Update CLAUDE.md] + C --> E[Document Frameworks & Version Maps] + D --> F[Document Structure & Patterns] + E --> G[Pin Key Files for Context] + F --> G + + G --> H[Identify Task Type] + H --> I{Task Category} + I -->|Bug Fix| J[Ask Claude for Bug Analysis] + I -->|Code Review| K[Request Code Review] + I -->|Refactor| L[Plan Refactoring Strategy] + I -->|Migration| M[Create Migration Plan] + + J --> N[Set Explicit Boundaries] + K --> N + L --> N + M --> N + + N --> O{Multiple Features?} + O -->|Yes| P[Create Git Worktrees] + O -->|No| Q[Work on Main Branch] + P --> R[Launch Separate Claude Sessions] + R --> S[Organize Terminal Tabs] + Q --> S + + S --> T[Setup Team Automation] + T --> U[Sync .claude/commands/] + U --> V[Configure Slash Commands] + V --> W[Setup Hooks for Automation] + W --> X[Share Session Context with Team] + + X --> Y{More Tasks?} + Y -->|Yes| H + Y -->|No| Z[Workflow Complete] + + style A fill:#e1f5ff + style C fill:#ffecec + style D fill:#fff4e1 + style P fill:#f0ffe1 + style T fill:#ffe1f5 + style Z fill:#90EE90 +``` + +**提示**： +- 每个新功能或修复都从规格和计划模式提示词开始。 +- 对于旧仓库和复杂仓库，把更详细的指导存放在 `CLAUDE.md` / `CLAUDE_LEGACY.md` 中。 +- 给出清晰、聚焦的指令，把复杂工作拆成多阶段计划。 +- 定期清理会话、裁剪上下文，并删除已完成的工作区，避免堆积混乱。 + +这些步骤概括了在新旧代码库中更顺畅使用 Claude Code 的核心建议。 + +--- + +## 2026 年 3 月新增功能与能力 + +### 关键功能资源 + +| 功能 | 说明 | 了解更多 | +|---------|-------------|------------| +| **Auto Memory** | Claude 会自动学习并记住你跨会话的偏好 | [记忆指南](02-memory/README.md) | +| **Remote Control** | 通过外部工具和脚本以编程方式控制 Claude Code 会话 | [高级功能](09-advanced-features/README.md) | +| **Web Sessions** | 通过基于浏览器的界面访问 Claude Code，实现远程开发 | [CLI 参考](10-cli/README.md) | +| **Desktop App** | Claude Code 的原生桌面应用，界面更强大 | [Claude Code 文档](https://code.claude.com/docs/en/desktop) | +| **Extended Thinking** | 通过 `Alt+T` / `Option+T` 或 `MAX_THINKING_TOKENS` 环境变量切换深度推理 | [高级功能](09-advanced-features/README.md) | +| **Permission Modes** | 精细权限控制：default、acceptEdits、plan、auto、dontAsk、bypassPermissions | [高级功能](09-advanced-features/README.md) | +| **7-Tier Memory** | Managed Policy、Project、Project Rules、User、User Rules、Local、Auto Memory | [记忆指南](02-memory/README.md) | +| **Hook Events** | 25 个事件：PreToolUse、PostToolUse、PostToolUseFailure、Stop、StopFailure、SubagentStart、SubagentStop、Notification、Elicitation 等 | [Hooks 指南](06-hooks/README.md) | +| **Agent Teams** | 协调多个 agent 共同处理复杂任务 | [Subagents 指南](04-subagents/README.md) | +| **Scheduled Tasks** | 用 `/loop` 和 cron 工具设置周期性任务 | [高级功能](09-advanced-features/README.md) | +| **Chrome Integration** | 使用无头 Chromium 做浏览器自动化 | [高级功能](09-advanced-features/README.md) | +| **Keyboard Customization** | 自定义按键绑定，包括组合键序列 | [高级功能](09-advanced-features/README.md) | diff --git a/zh/resources/DESIGN-SYSTEM.md b/zh/resources/DESIGN-SYSTEM.md new file mode 100644 index 0000000..82818f4 --- /dev/null +++ b/zh/resources/DESIGN-SYSTEM.md @@ -0,0 +1,244 @@ +# Claude How To - 设计系统 + +## 视觉识别 + +### 图标设计概念：指南针 + 代码括号 + +Claude How To 的图标使用**指南针加 `>` 代码括号**来表示“在代码中导航”： + +``` + N (green) + ▲ + │ +W ───>─── E Compass = Guidance/Direction + │ > Bracket = Code/Terminal/CLI + ▼ + S (black) +``` + +它带来了以下效果： +- **视觉清晰**：一眼就能看出这是“代码导航指南” +- **象征意义**：指南针 = 找到方向；`>` = 代码/终端 +- **可扩展性**：从 16px 到 512px 都能正常工作 +- **品牌一致性**：以极简配色匹配开发者工具气质 + +--- + +## 色彩系统 + +### 配色 + +| 颜色 | 十六进制 | RGB | 用途 | +|-------|-----|-----|-------| +| 黑色（主色） | `#000000` | 0, 0, 0 | 主描边、文字、南针 | +| 白色（背景） | `#FFFFFF` | 255, 255, 255 | 浅色背景 | +| 灰色（辅助） | `#6B7280` | 107, 114, 128 | 次要刻度、次级文字 | +| 亮绿色（强调） | `#22C55E` | 34, 197, 94 | 北针、中心点、强调线 | +| 接近黑色（深色背景） | `#0A0A0A` | 10, 10, 10 | 深色模式背景 | + +### 对比度（WCAG） + +- 黑底白字：**21:1** AAA +- 灰底白字：**4.6:1** AA +- 绿底白字：**3.2:1**（仅用于装饰，不用于正文） +- 深色背景白字：**19.5:1** AAA + +### 强调色规则 + +**亮绿色（#22C55E）仅用于高亮：** +- 指南针北针 +- 中心点 +- 强调下划线/边框 +- 绝不作为背景色 +- 绝不用于正文 + +--- + +## 字体排版 + +### Logo 字体 +- **字体族**：Inter、SF Pro Display、-apple-system、Segoe UI、sans-serif +- **“Claude”**：42px，700 字重（加粗），黑色 +- **“How-To”**：32px，500 字重（中等），灰色（#6B7280） +- **副标题**：10px，500 字重，灰色，字间距 1.5px，大写 + +### 界面字体 +- **字体族**：Inter、SF Pro、系统字体（sans-serif） +- **字重**：400-600 +- **风格**：简洁、易读 + +--- + +## 图标细节 + +### 指南针规格 + +指南针图形由以下几何元素组成： + +``` +Element | Stroke/Fill | Color +--------------------|----------------|------------------ +Outer ring | 3px stroke | Black / White (dark mode) +North tick | 2.5px stroke | Black / White (dark mode) +Other cardinal ticks| 2px stroke | Gray / White 50% (dark mode) +Intercardinal ticks | 1.5px stroke | Gray / White 40% (dark mode) +North needle | filled polygon | #22C55E (always green) +South needle | filled polygon | Black / White (dark mode) +> bracket | 3px stroke | Black / White (dark mode) +Center dot | filled circle | #22C55E (always green) +``` + +### 尺寸递进 + +``` +16px → 仅环 + 指针 + 箭头（最简版） +32px → 增加方位刻度 +64px → 增加中间方位刻度 +128px → 全细节，所有元素都清晰 +256px → 最高细节，较粗描边 +``` + +--- + +## 尺寸指南 + +### Logo 尺寸 + +- **最小**：200px 宽（用于网页） +- **推荐**：520px（原始尺寸） +- **最大**：无限制（矢量格式） +- **宽高比**：约 4.3:1（宽：高） + +### 图标尺寸 + +- **最小**：16px（favicon） +- **推荐**：64-256px（应用、头像） +- **最大**：无限制（矢量格式） +- **宽高比**：1:1（正方形） + +--- + +## 间距与对齐 + +### Logo 留白 + +``` +┌─────────────────────────────────────┐ +│ │ +│ 最小留白空间 │ +│ （logo 高度 / 2） │ +│ │ +│ [COMPASS] Claude │ +│ How-To │ +│ │ +└─────────────────────────────────────┘ +``` + +### 图标中心点 + +所有图标都以画布中心为基准： +- 256px 画布使用 128×128 中心点 +- 128px 画布使用 64×64 中心点 +- 与其他 UI 元素保持对齐 + +--- + +## 无障碍性 + +### 颜色对比 +- 所有文字都满足 WCAG AA（最低 4.5:1） +- 绿色强调色只用于装饰，不承担信息传达 +- 不依赖红绿配色表达含义 + +### 可扩展性 +- 矢量格式保证任意尺寸都清晰 +- 即使在 16px 下，几何形状依然可辨识 +- 细节会随可用空间逐步增加 + +--- + +## 应用示例 + +### Web 页眉 +- 尺寸：520×120px logo +- 文件：`logos/claude-howto-logo.svg` +- 背景：白色或深色（#0A0A0A） +- 内边距：至少 20px + +### 应用图标 +- 尺寸：256×256px +- 文件：`icons/claude-howto-icon.svg` +- 背景：白色或深色 +- 用途：应用快捷方式、头像 + +### 浏览器 Favicon +- 尺寸：32px（主用），16px（备用） +- 文件：`favicons/favicon-32.svg` +- 格式：SVG，显示清晰锐利 + +### 社交媒体 +- 头像：256×256px 图标 +- 横幅：520×120px logo（居中） + +### 文档 +- 章节标题：按需缩放的 logo +- 小节图标：64×64px favicon +- 内联图标：32×32px favicon + +--- + +## 文件格式细节 + +### SVG 结构 + +所有 SVG 文件都采用扁平设计： +- 无渐变（仅用纯色） +- 无滤镜效果（不使用模糊、发光或阴影） +- 干净的描边和填充几何结构 +- 使用 `viewBox` 实现响应式缩放 +- 代码可读且带注释 + +### 跨浏览器兼容性 + +- Chrome/Edge：完全支持 +- Firefox：完全支持 +- Safari：完全支持 +- iOS Safari：完全支持 +- 所有现代浏览器：完全支持 + +--- + +## 自定义 + +### 更换强调色 + +如果你想创建不同强调色的变体： + +1. 把所有 `#22C55E` 替换成你的强调色 +2. 确保装饰性元素的对比度仍高于 3:1 +3. 保持黑/白/灰结构不变 + +### 缩放 + +```css +svg { + width: 256px; + height: 256px; +} +``` + +SVG 会通过 `viewBox` 自动缩放，不需要额外变换。 + +--- + +## 版本控制 + +在 git 中跟踪设计变更： +- 正常版本化 SVG 文件，因为它们本质上是文本 +- 随设计变更一起打 tag +- 在提交中包含 `DESIGN-SYSTEM.md` + +--- + +**最后更新**：2026 年 2 月 +**设计系统版本**：3.0 diff --git a/zh/resources/QUICK-START.md b/zh/resources/QUICK-START.md new file mode 100644 index 0000000..44785a3 --- /dev/null +++ b/zh/resources/QUICK-START.md @@ -0,0 +1,89 @@ +# 快速开始 - 品牌资源 + +## 复制资源到你的项目 + +```bash +# 将所有资源复制到你的 Web 项目中 +cp -r resources/ /path/to/your/website/ + +# 或者只复制网页所需的 favicon +cp resources/favicons/* /path/to/your/website/public/ +``` + +## 添加到 HTML（直接复制粘贴） + +```html + + + + + + +``` + +## 在 Markdown/文档中使用 + +```markdown +# Claude How To + +![Claude How To Logo](resources/logos/claude-howto-logo.svg) + +![Icon](resources/icons/claude-howto-icon.svg) +``` + +## 推荐尺寸 + +| 用途 | 尺寸 | 文件 | +|---------|------|------| +| 网站页眉 | 520×120 | `logos/claude-howto-logo.svg` | +| 应用图标 | 256×256 | `icons/claude-howto-icon.svg` | +| 浏览器标签页 | 32×32 | `favicons/favicon-32.svg` | +| 移动端桌面图标 | 128×128 | `favicons/favicon-128.svg` | +| 桌面应用 | 256×256 | `favicons/favicon-256.svg` | +| 小头像 | 64×64 | `favicons/favicon-64.svg` | + +## 颜色值 + +```css +/* 在 CSS 中使用这些值 */ +--color-primary: #000000; +--color-secondary: #6B7280; +--color-accent: #22C55E; +--color-bg-light: #FFFFFF; +--color-bg-dark: #0A0A0A; +``` + +## 图标含义 + +**指南针 + 代码括号**： +- 指南针环 = 导航、结构化学习路径 +- 绿色北针 = 方向、进展、引导 +- 黑色南针 = 基础、根基 +- `>` 括号 = 终端提示符、代码、CLI 场景 +- 刻度线 = 精准、结构化步骤 + +这象征着“在清晰引导下穿行于代码世界”。 + +## 在哪里用什么 + +### 网站 +- **页眉**：Logo（`logos/claude-howto-logo.svg`） +- **Favicon**：32px（`favicons/favicon-32.svg`） +- **社交预览**：图标（`icons/claude-howto-icon.svg`） + +### GitHub +- **README 徽章**：图标（`icons/claude-howto-icon.svg`），建议 64-128px +- **仓库头像**：图标（`icons/claude-howto-icon.svg`） + +### 社交媒体 +- **头像**：图标（`icons/claude-howto-icon.svg`） +- **横幅**：Logo（`logos/claude-howto-logo.svg`） +- **缩略图**：256×256px 图标 + +### 文档 +- **章节标题**：Logo 或图标（按需缩放） +- **导航图标**：Favicon（32-64px） + +--- + +完整文档见 [README.md](README.md)。 diff --git a/zh/resources/README.md b/zh/resources/README.md new file mode 100644 index 0000000..1be1235 --- /dev/null +++ b/zh/resources/README.md @@ -0,0 +1,266 @@ + + + Claude How To + + +# 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 + + + + + + + + + +``` + +### 完整配置 + +```html + + + + + + + + + + + + + + + + + +``` + +## 颜色方案 + +### 主色 +- **黑色**：`#000000`（主文本、线条、南针） +- **白色**：`#FFFFFF`（浅色背景） +- **灰色**：`#6B7280`（次级文本、次要刻度） + +### 强调色 +- **亮绿色**：`#22C55E`（北针、中心点、强调线条，只用于高亮，绝不作为背景） + +### 深色模式 +- **背景**：`#0A0A0A`（接近黑色） + +### CSS 变量 +```css +--color-primary: #000000; +--color-secondary: #6B7280; +--color-accent: #22C55E; +--color-bg-light: #FFFFFF; +--color-bg-dark: #0A0A0A; +``` + +### Tailwind 配置 +```js +colors: { + brand: { + primary: '#000000', + secondary: '#6B7280', + accent: '#22C55E', + } +} +``` + +### 使用规范 +- 主文本和结构元素使用黑色 +- 次级/辅助元素使用灰色 +- 绿色**仅**用于高亮，例如指针、点和强调线 +- 不要把绿色用作背景色 +- 保持 WCAG AA 对比度（最低 4.5:1） + +## 设计规范 + +### Logo 使用 +- 用于白色或深色（#0A0A0A）背景 +- 按比例缩放 +- Logo 四周保留足够留白（最小值：logo 高度 / 2） +- 根据背景选择对应的浅色/深色版本 + +### 图标使用 +- 适用于标准尺寸：16、32、64、128、256px +- 保持指南针比例 +- 按比例缩放 + +### Favicon 使用 +- 根据场景选用合适尺寸 +- 16-32px：浏览器标签页、书签 +- 64px：站点图标 +- 128px 以上：Apple/Android 桌面图标 + +## SVG 优化 + +所有 SVG 文件都采用扁平设计，没有渐变和滤镜： +- 干净的基于描边的几何结构 +- 不嵌入位图 +- 路径已优化 +- 使用响应式 `viewBox` + +网页优化示例： +```bash +# 压缩 SVG，同时保持质量 +svgo --config='{ + "js2svg": { + "indent": 2 + }, + "plugins": [ + "convertStyleToAttrs", + "removeRasterImages" + ] +}' input.svg -o output.svg +``` + +## PNG 转换 + +如果你需要为旧浏览器支持转换成 PNG： + +```bash +# 使用 ImageMagick +convert -density 300 -background none favicon-256.svg favicon-256.png + +# 使用 Inkscape +inkscape -D -z --file=favicon-256.svg --export-png=favicon-256.png +``` + +## 无障碍性 + +- 高对比度颜色比例（符合 WCAG AA，最低 4.5:1） +- 几何形状清晰，在各种尺寸下都容易识别 +- 矢量格式，可无限缩放 +- 图标中不使用文字（文字由单独的 wordmark 承担） +- 不依赖红绿配色表达含义 + +## 署名 + +这些资源属于 Claude How To 项目。 + +**许可证**：MIT（见项目 LICENSE 文件） + +## 版本历史 + +- **v3.0**（2026 年 2 月）：指南针 + 括号设计，黑/白/灰 + 绿色强调色 +- **v2.0**（2026 年 1 月）：受 Claude 启发的 12 芒星爆发式设计，祖母绿配色 +- **v1.0**（2026 年 1 月）：最初基于六边形的进度图标设计 + +--- + +**最后更新**：2026 年 2 月 +**当前版本**：3.0（指南针 + 括号） +**全部资源**：可直接用于生产环境的 SVG，支持无限缩放，符合 WCAG AA 无障碍标准 diff --git a/zh/scripts/README.md b/zh/scripts/README.md new file mode 100644 index 0000000..7623e1c --- /dev/null +++ b/zh/scripts/README.md @@ -0,0 +1,69 @@ +# EPUB 构建脚本 + +## 功能 + +这个脚本会把整份指南构建成 EPUB 电子书，方便离线阅读。 + +## 需求 + +- Python 环境 +- `uv` +- 相关依赖 + +## 快速开始 + +最简单的方式是直接让 `uv` 帮你处理依赖： + +```bash +uv run scripts/build_epub.py +``` + +## 开发环境 + +如果你要修改脚本本身，可以先创建虚拟环境，再安装开发依赖。 + +```bash +# 创建虚拟环境 + +# 激活并安装依赖 + +# 运行测试 + +# 运行脚本 +``` + +## 命令行选项 + +常见选项包括： + +- 指定输出路径 +- 打开详细日志 +- 限制并发请求 + +## 示例 + +```bash +# 带详细输出构建 + +# 指定输出位置 + +# 限制并发数（遇到限流时） +``` + +## 输出 + +脚本会生成 EPUB 文件，里面包含所有内容和渲染后的图表。 + +## 运行测试 + +你可以用虚拟环境或直接通过 `uv` 运行测试。 + +## 依赖 + +脚本依赖的包会在项目的开发依赖里列出。 + +## 故障排查 + +- 检查 `uv` 是否可用 +- 检查 Python 版本 +- 检查依赖是否安装完整