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/02-memory/README.md
+++ b/zh/02-memory/README.md
@@ -0,0 +1,305 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+  <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Memory 指南
+
+## 概览
+
+Memory 让 Claude Code 在不同会话之间保留上下文。你可以把团队规范、项目规则、个人偏好和目录级约束写进 `CLAUDE.md`，让 Claude 在合适的时候自动加载。
+
+## Memory 命令速查
+
+| 命令 | 作用 |
+|------|------|
+| `/init` | 初始化项目级 `CLAUDE.md` |
+| `/memory` | 打开并编辑记忆文件 |
+| `#` | 快速把当前规则写入 memory |
+
+## 快速上手：初始化 Memory
+
+### 使用 `/init`
+
+在项目目录中运行：
+
+```bash
+/init
+```
+
+Claude 会根据当前项目生成一个 `CLAUDE.md`，通常包含类似如下结构：
+
+```md
+# 项目配置
+## 项目概览
+## 开发规范
+```
+
+### 使用 `#` 快速更新记忆
+
+当你想把一句规则写入 memory 时，可以直接在输入前加 `#`：
+
+```text
+# 这个项目始终使用 TypeScript 严格模式
+# 优先使用 async/await，而不是 promise 链
+# 每次提交前都运行 npm test
+# 文件名统一使用 kebab-case
+```
+
+这会把规则加入当前会话能感知到的记忆中。
+
+### 使用 `/memory`
+
+`/memory` 会打开记忆编辑器，让你在不同范围之间切换：
+
+1. 受管策略记忆
+2. 项目记忆（`./CLAUDE.md`）
+3. 用户记忆（`~/.claude/CLAUDE.md`）
+4. 本地项目记忆
+
+适合你把长期规则、项目规范和个人偏好分层管理。
+
+## Memory 架构
+
+Claude Code 的记忆系统通常有以下层级：
+
+| 层级 | 作用范围 | 典型内容 |
+|------|----------|----------|
+| 受管策略 | 组织级 | 合规、安全、统一流程 |
+| 项目记忆 | 单个项目 | 架构、编码标准、工作流 |
+| 目录记忆 | 子目录 | 模块约束、局部规范 |
+| 用户记忆 | 单个用户 | 个人偏好、默认设置 |
+
+## 记忆层级
+
+Claude 会按更接近当前上下文的规则优先使用更具体的 memory。一般来说：
+
+- 组织级规则优先于普通偏好
+- 项目规则优先于个人偏好
+- 目录级规则优先于项目级通用规则
+
+## 排除规则
+
+如果某些 `CLAUDE.md` 不应该被自动加载，可以通过 `claudeMdExcludes` 之类的设置排除。
+
+## 配置文件层级
+
+项目设置、用户设置和企业托管设置会共同影响 memory 的加载方式。你可以把它理解为：
+
+1. 组织策略
+2. 项目设置
+3. 本地设置
+4. 临时会话输入
+
+## 模块化规则系统
+
+Memory 不一定要写成一个巨大文件。你可以把规则拆成多个目录文件，再按路径组织。
+
+### 通过 YAML frontmatter 设置路径规则
+
+```md
+---
+description: API development rules
+---
+
+# API Development Rules
+```
+
+### 子目录与符号链接
+
+你可以用子目录和 symlink 把局部规则复用到多个项目区域。
+
+## Memory 位置表
+
+常见位置包括：
+
+- 项目根目录的 `CLAUDE.md`
+- 用户目录的 `~/.claude/CLAUDE.md`
+- 子目录的 `CLAUDE.md`
+
+## Memory 更新生命周期
+
+一般流程是：
+
+1. 创建或编辑 `CLAUDE.md`
+2. Claude 重新加载
+3. 新规则在后续会话中生效
+
+## Auto Memory
+
+Auto memory 让 Claude 根据当前目录自动寻找并加载合适的记忆文件。
+
+### 工作方式
+
+Claude 会根据当前工作目录、父目录和已配置路径，逐层查找相关 memory。
+
+### 目录结构
+
+```text
+project/
+├── CLAUDE.md
+├── src/
+│   ├── CLAUDE.md
+│   └── api/
+│       └── CLAUDE.md
+```
+
+### 版本要求
+
+某些 auto memory 行为依赖较新的 Claude Code 版本。
+
+### 自定义 auto memory 目录
+
+如果默认目录不适合你的项目，可以在设置中指定新的 memory 路径。
+
+### worktree 和仓库共享
+
+在 worktree、monorepo 或多人协作场景中，auto memory 可以帮助保持规则一致。
+
+### Subagent 记忆
+
+Subagents 也可以拥有自己的记忆范围，用于在各自职责内保持一致性。
+
+### 控制 auto memory
+
+```bash
+# 当前会话禁用 auto memory
+
+# 显式开启 auto memory
+```
+
+## 通过 `--add-dir` 添加额外目录
+
+你可以用 `--add-dir` 把额外目录也加入 Claude 的可见范围，适合多目录协作。
+
+## 实战示例
+
+### 示例 1：项目记忆结构
+
+```md
+# 项目配置
+## 项目概览
+## 架构
+## 开发规范
+### 代码风格
+### 命名约定
+### Git 工作流
+### 测试要求
+### API 规范
+### 数据库
+### 部署
+## 常用命令
+## 团队联系人
+## 已知问题与解决办法
+## 相关项目
+```
+
+### 示例 2：目录级记忆
+
+```md
+# API 模块规范
+## API 专属规范
+### 请求校验
+### 身份验证
+### 响应格式
+### 分页
+### 限流
+### 缓存
+```
+
+### 示例 3：个人记忆
+
+```md
+# 我的开发偏好
+## 关于我
+## 代码偏好
+### 错误处理
+### 注释
+### 测试
+### 架构
+## 调试偏好
+## 沟通方式
+## 项目组织
+## 工具链
+```
+
+### 示例 4：会话中更新记忆
+
+两种常见方式：
+
+1. 直接提要求，让 Claude 把规则写进 memory
+2. 使用 `# new rule into memory` 这种模式追加规则
+
+## 最佳实践
+
+### 应该做的
+
+- 用项目记忆保存团队标准
+- 用目录记忆保存局部差异
+- 先写简洁规则，再逐步补充
+- 把可重复内容写进 `CLAUDE.md`
+
+### 不应该做的
+
+- 不要把 README 整份复制进 `CLAUDE.md`
+- 不要把明显属于代码的实现细节硬塞进 memory
+- 不要让 memory 变成垃圾桶
+
+### 记忆管理建议
+
+- 优先引用已有文档，而不是重复粘贴
+- 只保留真正影响 Claude 行为的信息
+- 定期整理过期或冲突的规则
+
+## 安装说明
+
+### 设置项目记忆
+
+#### 方法 1：使用 `/init`（推荐）
+
+```bash
+/init
+```
+
+#### 方法 2：手动创建
+
+```bash
+cp project-CLAUDE.md CLAUDE.md
+```
+
+#### 方法 3：快速更新
+
+```text
+# Use semantic versioning for all releases
+# Always run tests before committing
+# Prefer composition over inheritance
+```
+
+### 设置个人记忆
+
+```bash
+cp personal-CLAUDE.md ~/.claude/CLAUDE.md
+```
+
+### 设置目录记忆
+
+```bash
+cp directory-api-CLAUDE.md src/api/CLAUDE.md
+```
+
+### 验证安装
+
+- 重新打开 Claude Code 会话
+- 检查 `CLAUDE.md` 是否被自动加载
+- 用一条明显会受 memory 影响的提示词测试
+
+## 官方文档
+
+如果你想看更详细的行为定义、兼容性和最新限制，建议参考 Claude Code 官方 memory 文档。
+
+## 相关概念
+
+- [Slash Commands 中文参考](../01-slash-commands/README.md)
+- [Skills 中文指南](../03-skills/README.md)
+- [Subagents 中文参考](../04-subagents/README.md)
+- [Advanced Features 中文指南](../09-advanced-features/README.md)
--- a/zh/02-memory/directory-api-CLAUDE.md
+++ 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 分钟
+- 写操作时失效缓存
+- 用资源类型给缓存键打标签
--- a/zh/02-memory/personal-CLAUDE.md
+++ 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
--- a/zh/02-memory/project-CLAUDE.md
+++ 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`