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 <tanqingkuang@users.noreply.github.com> Translations originally contributed by @tanqingkuang in #45. Restructured from *-CN.md suffix pattern into zh/ directory to prevent the EPUB builder (scripts/build_epub.py collect_folder_files) from picking up Chinese files via glob("*.md") inside module folders.
2026-04-06 23:08:54 +02:00
parent 100c45eef2
commit 89e89d4aa3
100 changed files with 20487 additions and 1 deletions
--- a/zh/CONTRIBUTING.md
+++ b/zh/CONTRIBUTING.md
@@ -0,0 +1,378 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+  <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+# 为 Claude How To 贡献内容
+
+感谢你愿意为这个项目做出贡献。这份指南会帮助你更高效地参与协作。
+
+## 关于本项目
+
+Claude How To 是一份面向 Claude Code 的可视化、以示例驱动的学习指南。我们提供：
+- **Mermaid 图表**，解释各项功能的工作方式
+- **可直接投入使用的模板**，你可以马上复制到项目中
+- **带上下文和最佳实践的真实案例**
+- **从入门到进阶的渐进式学习路径**
+
+## 贡献类型
+
+### 1. 新示例或新模板
+为已有功能补充示例，例如 slash commands、skills、hooks 等：
+- 可直接复制粘贴的代码
+- 清楚说明工作原理
+- 使用场景与收益
+- 排障提示
+
+### 2. 文档改进
+- 澄清容易混淆的内容
+- 修复拼写和语法问题
+- 补充缺失信息
+- 优化代码示例
+
+### 3. 功能指南
+为新的 Claude Code 功能编写指南：
+- 分步骤教程
+- 架构图
+- 常见模式和反模式
+- 真实工作流
+
+### 4. Bug 报告
+报告你遇到的问题：
+- 你原本期望发生什么
+- 实际发生了什么
+- 复现步骤
+- 相关的 Claude Code 版本和操作系统
+
+### 5. 反馈与建议
+帮助我们改进这份指南：
+- 建议更好的解释方式
+- 指出覆盖不足的地方
+- 推荐新章节或重组结构
+
+## 快速开始
+
+### 1. Fork 并克隆
+```bash
+git clone https://github.com/luongnv89/claude-howto.git
+cd claude-howto
+```
+
+### 2. 创建分支
+使用能说明用途的分支名：
+```bash
+git checkout -b add/feature-name
+git checkout -b fix/issue-description
+git checkout -b docs/improvement-area
+```
+
+### 3. 配置开发环境
+
+pre-commit hooks 会在本地、每次提交前运行与 CI 相同的检查。PR 被接受前，下面四项检查都必须通过。
+
+**必需依赖：**
+
+```bash
+# Python 工具链（uv 是本项目的包管理器）
+pip install uv
+uv venv
+source .venv/bin/activate
+uv pip install -r scripts/requirements-dev.txt
+
+# Markdown lint 工具（Node.js）
+npm install -g markdownlint-cli
+
+# Mermaid 图表校验器（Node.js）
+npm install -g @mermaid-js/mermaid-cli
+
+# 安装 pre-commit 并启用 hooks
+uv pip install pre-commit
+pre-commit install
+```
+
+**验证配置：**
+
+```bash
+pre-commit run --all-files
+```
+
+每次提交都会运行这些 hooks：
+
+| Hook | 检查内容 |
+|------|----------|
+| `markdown-lint` | Markdown 格式和结构 |
+| `cross-references` | 相对链接、锚点、代码围栏 |
+| `mermaid-syntax` | 所有 ` ```mermaid ` 代码块是否可正确解析 |
+| `link-check` | 外部 URL 是否可访问 |
+| `build-epub` | `.md` 变更时 EPUB 是否能无错误生成 |
+
+## 目录结构
+
+```
+├── 01-slash-commands/      # 用户手动触发的快捷命令
+├── 02-memory/              # 持久上下文示例
+├── 03-skills/              # 可复用能力
+├── 04-subagents/           # 专门化 AI 助手
+├── 05-mcp/                 # Model Context Protocol 示例
+├── 06-hooks/               # 事件驱动自动化
+├── 07-plugins/             # 打包功能集合
+├── 08-checkpoints/         # 会话快照
+├── 09-advanced-features/   # 规划、思考、后台任务
+├── 10-cli/                 # CLI 参考
+├── scripts/                # 构建与工具脚本
+└── README.md            # 主指南
+```
+
+## 如何贡献示例
+
+### 添加 Slash Command
+1. 在 `01-slash-commands/` 中创建一个 `.md` 文件
+2. 包含：
+   - 清晰说明用途
+   - 使用场景
+   - 安装说明
+   - 使用示例
+   - 自定义技巧
+3. 更新 `01-slash-commands/README.md`
+
+### 添加 Skill
+1. 在 `03-skills/` 中创建一个目录
+2. 包含：
+   - `SKILL.md` - 主文档
+   - `scripts/` - 如有需要可放辅助脚本
+   - `templates/` - 提示词模板
+   - README 中的示例用法
+3. 更新 `03-skills/README.md`
+
+### 添加 Subagent
+1. 在 `04-subagents/` 中创建一个 `.md` 文件
+2. 包含：
+   - agent 的目标和能力
+   - 系统提示词结构
+   - 示例使用场景
+   - 集成示例
+3. 更新 `04-subagents/README.md`
+
+### 添加 MCP 配置
+1. 在 `05-mcp/` 中创建一个 `.json` 文件
+2. 包含：
+   - 配置说明
+   - 所需环境变量
+   - 配置步骤
+   - 使用示例
+3. 更新 `05-mcp/README.md`
+
+### 添加 Hook
+1. 在 `06-hooks/` 中创建一个 `.sh` 文件
+2. 包含：
+   - shebang 和说明
+   - 逻辑清晰的注释
+   - 错误处理
+   - 安全考虑
+3. 更新 `06-hooks/README.md`
+
+## 编写规范
+
+### Markdown 风格
+- 使用清晰的标题层级（章节用 H2，小节用 H3）
+- 段落保持简短且聚焦
+- 列表用项目符号
+- 代码块要标明语言
+- 各章节之间保留空行
+
+### 代码示例
+- 示例要能直接复制粘贴
+- 为不明显的逻辑添加注释
+- 同时提供简单版和进阶版
+- 展示真实使用场景
+- 标出可能的坑
+
+### 文档写作
+- 解释“为什么”，而不只是“是什么”
+- 包含前置条件
+- 添加排障章节
+- 链接相关主题
+- 保持对初学者友好
+
+### JSON/YAML
+- 统一缩进风格（2 或 4 个空格）
+- 为配置添加注释
+- 包含验证示例
+
+### 图表
+- 尽量使用 Mermaid
+- 保持图表简洁易读
+- 在图表下方补充说明
+- 链接到相关章节
+
+## Commit 规范
+
+使用 conventional commit 格式：
+```
+type(scope): description
+
+[optional body]
+```
+
+类型包括：
+- `feat`：新功能或新示例
+- `fix`：修复或更正
+- `docs`：文档变更
+- `refactor`：代码重构
+- `style`：格式调整
+- `test`：新增或修改测试
+- `chore`：构建、依赖等
+
+示例：
+```
+feat(slash-commands): Add API documentation generator
+docs(memory): Improve personal preferences example
+fix(README): Correct table of contents link
+docs(skills): Add comprehensive code review skill
+```
+
+## 提交前检查
+
+### 清单
+- [ ] 代码符合项目风格与约定
+- [ ] 新示例附带清晰文档
+- [ ] README 已更新（本地和根目录）
+- [ ] 不包含敏感信息（API key、凭据）
+- [ ] 示例经过测试并可运行
+- [ ] 链接已验证且正确
+- [ ] 文件权限正确（脚本可执行）
+- [ ] Commit 信息清晰且有描述性
+
+### 本地测试
+```bash
+# 运行所有 pre-commit 检查（与 CI 相同）
+pre-commit run --all-files
+
+# 查看改动
+git diff
+```
+
+## Pull Request 流程
+
+1. **创建带有清晰说明的 PR**：
+   - 这次提交做了什么？
+   - 为什么需要它？
+   - 是否有关联 issue？
+
+2. **补充相关细节**：
+   - 新功能？请说明使用场景
+   - 文档？请说明改进点
+   - 示例？展示前后对比
+
+3. **关联 issue**：
+   - 使用 `Closes #123` 自动关闭相关 issue
+
+4. **耐心等待审查**：
+   - 维护者可能会提出改进建议
+   - 根据反馈迭代
+   - 最终决定由维护者负责
+
+## Code Review 流程
+
+审查者会检查：
+- **准确性**：描述是否与实际一致？
+- **质量**：是否达到生产可用？
+- **一致性**：是否符合项目模式？
+- **文档**：是否清晰完整？
+- **安全性**：是否存在漏洞？
+
+## 报告问题
+
+### Bug 报告
+请包含：
+- Claude Code 版本
+- 操作系统
+- 复现步骤
+- 预期行为
+- 实际行为
+- 如有必要，附上截图
+
+### 功能请求
+请包含：
+- 使用场景或要解决的问题
+- 建议方案
+- 你考虑过的替代方案
+- 额外上下文
+
+### 文档问题
+请包含：
+- 哪里令人困惑或缺失
+- 建议如何改进
+- 示例或参考资料
+
+## 项目政策
+
+### 敏感信息
+- 永远不要提交 API key、token 或凭据
+- 示例中使用占位符
+- 为配置文件提供 `.env.example`
+- 文档中说明所需环境变量
+
+### 代码质量
+- 示例要聚焦且易读
+- 避免过度设计
+- 对不明显的逻辑添加注释
+- 提交前充分测试
+
+### 知识产权
+- 原创内容归作者所有
+- 项目采用教育用途许可证
+- 尊重已有版权
+- 需要时注明来源
+
+## 获取帮助
+
+- **提问**：在 GitHub Issues 中发起 discussion
+- **通用帮助**：先查看现有文档
+- **开发帮助**：参考类似示例
+- **Code Review**：在 PR 中 @ 维护者
+
+## 认可
+
+贡献者会被收录在：
+- `README.md` 的 Contributors 部分
+- GitHub contributors 页面
+- Commit 历史
+
+## 安全
+
+在贡献示例和文档时，请遵守安全编码实践：
+
+- **绝不要硬编码密钥或 API key** - 使用环境变量
+- **提示安全影响** - 标出潜在风险
+- **使用安全默认值** - 默认启用安全功能
+- **验证输入** - 展示正确的输入校验和清理方式
+- **加入安全提示** - 记录安全注意事项
+
+如遇安全问题，请参见 [SECURITY.md](SECURITY.md) 获取漏洞报告流程。
+
+## 行为准则
+
+我们承诺打造一个热情且包容的社区。请阅读 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 查看完整社区标准。
+
+简要来说：
+- 保持尊重和包容
+- 愉快地接受反馈
+- 帮助他人成长和学习
+- 避免骚扰或歧视
+- 向维护者报告问题
+
+所有贡献者都应遵守这份准则，并以善意和尊重对待彼此。
+
+## 许可证
+
+为本项目贡献内容，即表示你同意你的贡献将按 MIT License 许可。详情见 [LICENSE](LICENSE) 文件。
+
+## 有问题？
+
+- 查看 [README.md](README.md)
+- 阅读 [LEARNING-ROADMAP.md](LEARNING-ROADMAP.md)
+- 查看已有示例
+- 发起 issue 讨论
+
+感谢你的贡献！