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.
This commit is contained in:
Luong NGUYEN
2026-04-06 23:08:54 +02:00
committed by GitHub
parent 100c45eef2
commit 89e89d4aa3
100 changed files with 20487 additions and 1 deletions

292
zh/08-checkpoints/README.md Normal file
View File

@@ -0,0 +1,292 @@
<picture>
<source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
<img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
</picture>
# Checkpoints 与 Rewind
Checkpoints 可以让你保存对话状态,并在 Claude Code 会话中回退到之前的时间点。无论你是在探索不同方案、修复错误,还是比较多个实现路径,这个能力都非常有用。
## 概览
Checkpoints 会保存会话状态,让你可以安全地试验和探索多种方案。它们本质上是当前对话状态的快照,包含:
- 所有已交换的消息
- 已做出的文件修改
- 工具使用历史
- 当前会话上下文
当你在尝试不同实现方式、从错误中恢复,或比较替代方案时,这个功能尤其好用。
## 核心概念
| 概念 | 说明 |
|---------|-------------|
| **Checkpoint** | 保存消息、文件和上下文的对话快照 |
| **Rewind** | 回到之前的 checkpoint并丢弃之后的更改 |
| **Branch Point** | 从同一个 checkpoint 出发,探索多个方案 |
## 访问 Checkpoints
你可以通过两种主要方式访问和管理 checkpoints
### 使用键盘快捷键
按两次 `Esc``Esc` + `Esc`)打开 checkpoint 界面并浏览已保存的 checkpoints。
### 使用 Slash Command
使用 `/rewind` 命令(别名:`/checkpoint`)快速进入:
```bash
# 打开 rewind 界面
/rewind
# 或者使用别名
/checkpoint
```
## Rewind 选项
回退时,你会看到一个包含五个选项的菜单:
1. **恢复代码和对话** - 把文件和消息都恢复到那个 checkpoint
2. **恢复对话** - 只回退消息,保留当前代码不变
3. **恢复代码** - 只回退文件修改,保留完整对话历史
4. **从这里开始总结** - 把从这里往后的对话压缩成 AI 生成的摘要,而不是直接丢弃。原始消息仍会保留在记录中。你也可以额外指定摘要应聚焦哪些主题。
5. **算了** - 取消并返回当前状态
## 自动 Checkpoints
Claude Code 会自动为你创建 checkpoints
- **每次用户提示** - 每次用户输入都会创建一个新 checkpoint
- **持久保存** - checkpoints 会跨会话保留
- **自动清理** - 30 天后自动清理旧 checkpoints
这意味着你随时都可以回到之前的任意节点,从几分钟前到几天前都可以。
## 使用场景
| 场景 | 工作流 |
|----------|----------|
| **探索不同方案** | 保存 → 试方案 A → 保存 → Rewind → 试方案 B → 比较 |
| **安全重构** | 保存 → 重构 → 测试 → 如果失败Rewind |
| **A/B 测试** | 保存 → 设计 A → 保存 → Rewind → 设计 B → 比较 |
| **错误恢复** | 发现问题 → Rewind 到最后一个正常状态 |
## 如何使用 Checkpoints
### 查看和回退
按两次 `Esc`,或者使用 `/rewind` 打开 checkpoint 浏览器。你会看到一个带时间戳的可用 checkpoint 列表。选择任意一个 checkpoint即可回退到该状态。
### Checkpoint 详情
每个 checkpoint 会显示:
- 创建时间
- 被修改的文件
- 对话中的消息数量
- 使用过的工具
## 实战示例
更多可直接参考的中文示例见 [checkpoint-examples.md](checkpoint-examples.md)。
### 示例 1探索不同方案
```text
User: 我们给 API 加一个缓存层吧
Claude: 我会为你的 API 端点添加 Redis 缓存……
[在 checkpoint A 处做出修改]
User: 其实我们先试试内存缓存
Claude: 我会 rewind 回去,探索另一种方案……
[用户按下 Esc+Esc 并回退到 checkpoint A]
[在 checkpoint B 处实现内存缓存]
User: 现在我可以比较两种方案了
```
### 示例 2从错误中恢复
```text
User: 把认证模块重构成 JWT
Claude: 我会重构认证模块……
[做出大量修改]
User: 等等,这把 OAuth 集成弄坏了。我们回去。
Claude: 我来帮你回退到重构之前……
[用户按下 Esc+Esc并选择重构前的 checkpoint]
User: 这次我们试一个更保守的方案
```
### 示例 3安全试验
```text
User: 我们试着把它改写成函数式风格
[在实验前创建 checkpoint]
Claude: [执行实验性修改]
User: 测试失败了。我们回退吧。
[用户按下 Esc+Esc 并回退到 checkpoint]
Claude: 我已经回退这些更改了。我们试另一个方案。
```
### 示例 4分支式探索
```text
User: 我想比较两种数据库设计
[记下 checkpoint命名为 "Start"]
Claude: 我先实现第一种设计……
[实现 Schema A]
User: 现在让我回去试第二种方案
[用户按下 Esc+Esc 并回退到 "Start"]
Claude: 现在我实现 Schema B……
[实现 Schema B]
User: 太好了,我现在有两个 schema 可以选择
```
## Checkpoint 保留策略
Claude Code 会自动管理你的 checkpoints
- 每次用户输入都会自动创建 checkpoint
- 旧 checkpoint 最多保留 30 天
- 系统会自动清理,避免存储无限增长
## 工作流模式
### 探索时的分支策略
当你在探索多个方案时:
```text
1. 从初始实现开始 → Checkpoint A
2. 尝试方案 1 → Checkpoint B
3. 回退到 Checkpoint A
4. 尝试方案 2 → Checkpoint C
5. 比较 B 和 C 的结果
6. 选择最佳方案并继续
```
### 安全重构模式
当你在做大改动时:
```text
1. 当前状态 → Checkpoint自动
2. 开始重构
3. 运行测试
4. 如果测试通过 → 继续
5. 如果测试失败 → Rewind 并尝试别的方案
```
## 最佳实践
因为 checkpoints 是自动创建的,所以你可以专注于工作,而不用担心手动保存状态。不过,下面这些习惯仍然很重要:
### 如何高效使用 Checkpoints
**应该做:**
- 回退前先看清楚可用的 checkpoints
- 当你想尝试不同方向时使用 rewind
- 保留 checkpoints 方便比较不同方案
- 理解每个 rewind 选项的作用(恢复代码和对话、恢复对话、恢复代码、或总结)
**不要做:**
- 只依赖 checkpoints 来保存代码
- 指望 checkpoints 跟踪外部文件系统变化
- 把 checkpoints 当成 git commit 的替代品
## 配置
你可以在设置中开启或关闭自动 checkpoints
```json
{
"autoCheckpoint": true
}
```
- `autoCheckpoint`:是否在每次用户提示后自动创建 checkpoint默认`true`
## 局限性
Checkpoints 很适合会话级回退,但它不是版本控制系统。对于需要长期保存、可审计、可共享的改动,仍然应该使用 git。
## 故障排查
### 找不到 Checkpoints
- 检查你是否在支持该功能的 Claude Code 版本中
- 确认自动 checkpoint 没有被关闭
- 重新打开会话再试一次
### Rewind 失败
- 确认你选择了一个有效的 checkpoint
- 查看是否存在与文件系统或权限相关的限制
- 尝试先分别恢复代码或对话,再决定是否同时恢复两者
## 与 Git 的集成
Checkpoints 和 git 是互补关系:
- Checkpoints 用于会话内探索和安全试验
- Git 用于永久保存代码历史
- 你可以先用 checkpoints 快速试错,再把最终方案提交到 git
## 快速开始
### 基本工作流
```text
1. 开始修改前自动创建 checkpoint
2. 尝试某个方案
3. 如果结果不理想,按 Esc 两次
4. 选择合适的 rewind 选项
5. 继续探索或提交最终方案
```
### 键盘快捷键
- `Esc` + `Esc`:打开 checkpoint 浏览器
- `/rewind`:通过命令进入回退界面
- `/checkpoint``/rewind` 的别名
## 什么时候该 rewind上下文监控
如果你发现这些信号,通常就该回退了:
- 当前方案开始变复杂,而且你还没确定方向
- 测试刚失败,问题可能就是最近一两步引入的
- 你想比较两种实现方式
- 你想保留一个“干净起点”继续探索
## 相关概念
- **Memory**:跨会话的长期上下文,见 [02-memory/README.md](../02-memory/README.md)
- **Hooks**:事件驱动自动化,见 [06-hooks/README.md](../06-hooks/README.md)
- **Plugins**:打包功能集合,见 [07-plugins/README.md](../07-plugins/README.md)
- **Advanced Features**:包括 planning mode 和背景任务,见 [09-advanced-features/README.md](../09-advanced-features/README.md)
## 更多资源
- [根目录中文指南](../README.md)
- [Claude Code 官方检查点文档](https://code.claude.com/docs/en/checkpointing)
- [Claude Code 高级功能指南](../09-advanced-features/README.md)
## 总结
Checkpoints 的价值在于让你敢于试错。它让“先试再说”和“试错后立刻回退”变得安全,从而帮你更快找到正确方案。

View File

@@ -0,0 +1,339 @@
# 检查点示例
以下是一些在 Claude Code 中有效使用检查点的真实示例。
注意:每次用户提示都会自动创建检查点。你不需要手动保存。要回退,请连续按两次 `Esc``Esc+Esc`),或者使用 `/rewind` 打开检查点浏览器。
## 示例 1数据库迁移
### 场景
你需要从 MySQL 迁移到 PostgreSQL但想同时探索直接迁移和渐进式双写两种方案。
### 工作流程
```
用户:我们来实现一个从 MySQL 到 PostgreSQL 的直接迁移方案
[检查点 A 自动创建]
Claude我来实现直接迁移……
[更换数据库驱动、更新查询、修改 schema]
用户:运行测试
[检查点 B 自动创建]
Claude正在运行测试……
❌ 15 个测试失败 - 连接池问题
用户:这个方案有问题。我们改试双写模式。
[用户按下 Esc+Esc选择检查点 A选择“恢复代码和对话”]
用户:现在实现双写模式,同时向两个数据库写入
Claude我来实现双写迁移……
[实现双写层、渐进式迁移策略]
用户:运行测试
Claude正在运行测试……
✅ 所有测试通过
用户:双写方案明显更稳妥。我们提交这个版本。
```
## 示例 2性能优化
### 场景
尝试多种性能优化策略。
### 工作流程
```
用户:我们来优化 API 响应时间。当前450ms
[检查点“Baseline”自动创建]
Claude我来加数据库查询缓存……
[实现 Redis 缓存]
用户:运行性能测试
Claude结果平均响应时间 280ms提升 38%
用户:我想试试另一种方法。
[用户按下 Esc+Esc选择“Baseline”检查点选择“恢复代码和对话”]
用户:改试数据库查询优化
Claude我来优化数据库查询……
[添加索引,优化 N+1 查询]
用户:运行性能测试
Claude结果平均响应时间 180ms提升 60%
用户:我也想试第三种方法。
[用户按下 Esc+Esc选择“Baseline”检查点选择“恢复代码和对话”]
用户:尝试响应压缩和 CDN
Claude我来添加压缩和 CDN……
[实现 gzip配置 CDN]
用户:运行性能测试
Claude结果平均响应时间 320ms提升 29%
用户:查询优化最好。让我回到那个版本,再和缓存结合起来。
[用户按下 Esc+Esc选择查询优化后的检查点选择“恢复代码和对话”]
用户:现在在这些优化后的查询之上再加上 Redis 缓存
Claude[在优化后的查询之上添加 Redis 缓存]
用户:运行性能测试
Claude结果平均响应时间 95ms提升 79%)🎉
用户:完美!这就是最终方案。我们提交它。
```
## 示例 3UI/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✅ 内存泄漏修复了!缓存层里的循环引用就是罪魁祸首。
用户:太好了!我们提交这个修复。
```
## 示例 5API 设计演进
### 场景
为 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 单元测试]
用户:运行测试
Claude45 个测试通过,覆盖率 78%
用户:再加上集成测试
Claude[添加集成测试]
用户:运行测试
Claude89 个测试通过,覆盖率 92%但测试太慢了3 分钟)
用户:测试太慢了,我们来优化。
Claude[优化测试设置,增加并行执行]
用户:运行测试
Claude89 个测试通过,覆盖率 92%35 秒完成 ✅
用户:很好!再给关键路径加上 E2E 测试。
Claude[添加 Playwright E2E 测试]
用户:运行所有测试
Claude112 个测试通过,覆盖率 94%2 分钟完成
用户:很好,覆盖率和速度都平衡得不错!
```
## 示例 8从检查点开始总结
### 场景
在一次很长的调试会话后,你想压缩对话内容,同时保留上下文。
### 工作流程
```
用户:[经过 20 多条消息的调试和探索之后]
[用户按下 Esc+Esc选择较早的检查点选择“从这里开始总结”]
[可选地提供指令:“重点保留我们尝试过什么,以及什么有效”]
Claude[生成从该点开始的对话总结]
[原始消息保留在记录里]
[总结会替换当前可见对话,从而减少上下文窗口占用]
用户:现在继续推进那个有效的方案。
```
## 关键结论
1. **检查点是自动创建的**:每次用户提示都会创建一个检查点,不需要手动保存。
2. **使用 `Esc+Esc` 或 `/rewind`**:这两种方式都可以打开检查点浏览器。
3. **选择合适的恢复方式**:根据需要恢复代码、对话、两者都恢复,或者直接总结。
4. **不要害怕试验**:检查点让你可以安全尝试激进的改动。
5. **和 git 结合使用**检查点用于探索git 用于最终落地。
6. **长会话要及时总结**:用“从这里开始总结”来保持对话可管理。