session-management

会话管理

适用场景

• 管理会话检查点并保留状态
• 在多个 Claude Code 会话间继续工作

不适用场景

• 不需要检查点的短会话
• 没有先前会话上下文的全新开始

概述

Claude Code 支持命名会话，以便更好地组织工作流。使用此技能管理跨多个会话的复杂、长期工作。

可用命令

命令	描述
/rename	为当前会话命名（未提供参数时自动生成名称，2.1.41+）
/resume	恢复之前的会话（REPL）
claude --resume <name>	从终端恢复会话

工作流模式

1. 调试会话

为调试会话命名，以便轻松恢复：

# Start debugging
/rename debugging-auth-issue

# ... work on the issue ...

# If you need to pause, session is auto-saved
# Resume later:
claude --resume debugging-auth-issue

2. 功能开发检查点

在长期功能开发过程中创建检查点：

# After completing milestone 1
/rename feature-x-milestone-1

# Continue in new session
# Reference old session if needed

3. PR 审查会话

适用于需要分多次进行的复杂 PR 审查：

# Start review
/rename pr-review-123

# Take breaks without losing context
# Resume:
claude --resume pr-review-123

4. 关联 PR 的会话（Claude Code 2.1.27+）

通过 gh pr create 创建会话时，系统会自动将其关联到 PR。之后可恢复特定 PR 的会话：

# Resume session for a specific PR
claude --from-pr 156
claude --from-pr https://github.com/org/repo/pull/156

# Workflow: review → pause → resume with full context
/rename pr-review-156
# ... review work ...
# Later:
claude --from-pr 156

5. 调查会话

调查可能需要研究的问题时：

# Start investigation
/rename investigate-memory-leak

# Pause to gather more info externally
# Resume with full context:
claude --resume investigate-memory-leak

恢复界面功能

/resume 界面提供：

• 分组显示派生会话：查看彼此相关的会话
• 键盘快捷键（默认为下列功能，可通过 /keybindings 自定义）：
  • 预览会话内容
  • 重命名会话
• 最近会话：按最近活动时间排序

6. 退出时显示恢复提示（Claude Code 2.1.31+）

现在，Claude Code 会在退出时显示恢复提示，展示用于继续对话的命令。这让恢复会话更加直观：用户无需事先了解 --resume。

最佳实践

命名约定

使用描述性名称，并以连字符分隔：

模式	示例	用途
debugging-<issue>	debugging-auth-401	调查 Bug
feature-<name>-<milestone>	feature-search-v2	功能开发
pr-review-<number>	pr-review-156	PR 审查
investigate-<topic>	investigate-perf	研究
refactor-<area>	refactor-api-layer	重构工作

何时为会话命名

在以下情况下为会话命名：

• 工作会持续多天
• 你可能需要临时暂停
• 会话中包含有价值的上下文
• 你之后还想引用该会话

会话清理

未命名的会话最终会被垃圾回收。命名的会话会保留更长时间。定期清理不再需要的旧命名会话。

与 Sanctum 集成

将会话管理与其他 Sanctum 技能结合使用：

1. 开始前：运行 Skill(sanctum:git-workspace-review) 以保存上下文
2. 为会话命名：/rename <descriptive-name>
3. 开展工作：针对任务使用合适的技能
4. 按需恢复：claude --resume <name>

故障排除

找不到会话

如果命名的会话未显示在 /resume 中：

• 检查名称中是否有拼写错误
• 长时间未活动后，会话可能会过期
• 使用 /resume 界面浏览可用会话

VS Code 中出现重复会话

如果在 VS Code 中恢复会话时看到重复条目：

• Claude Code 2.1.38+：已修复：恢复会话现在会正确复用现有会话，不再创建重复项
• 较旧版本：忽略重复条目；它们指向同一个底层会话

恢复后上下文丢失

如果上下文似乎不完整或恢复速度较慢：

• Claude Code 2.1.30+：通过基于 stat 的会话加载和渐进式补充，--resume 的内存占用降低了 68%，对会话较多的用户尤其明显。还修复了恢复包含损坏转录文件（parentUuid 循环）的会话时卡住的问题。
• Claude Code 2.1.29+：修复了恢复包含许多 once: true 钩子的会话时启动缓慢的问题：现在已优化 saved_hook_context 的加载
• Claude Code 2.1.21+：修复了恢复在工具执行期间中断的会话时出现的 API 错误：此前这些会话可能完全无法恢复
• Claude Code 2.1.20+：会话压缩和恢复现已修复：恢复时会正确加载压缩后的摘要，而不是完整历史记录
• 使用 /catchup 刷新 git 状态
• 使用 /debug（Claude Code 2.1.30+）诊断会话问题
• 如有需要，重新运行 Skill(sanctum:git-workspace-review)
• 如果使用较旧版本：恢复会话时可能会重新加载未压缩的历史记录，导致上下文占用意外增加

macOS 孤立进程（Claude Code 2.1.46+）

此前，在 macOS 上断开终端连接可能会导致 Claude Code 进程成为孤立进程并继续运行。此问题已在 2.1.46+ 中修复。如果在较旧版本中遇到残留的 CC 进程，请手动检查并终止：

# Find orphaned claude processes
ps aux | grep -i claude | grep -v grep

7. 自动记忆（Claude Code 2.1.32+）

Claude 现在会在工作过程中自动记录和回忆记忆。会话摘要、关键结果和工作日志会被隐式记录，并在未来的会话中回忆。这无需手动管理检查点，即可实现跨会话的被动延续。

• 无需操作：在 Anthropic 第一方 API 上会自动记录记忆
• 与命名会话互为补充：自动记忆处理隐式延续；命名会话提供显式组织
• Token 开销：回忆的记忆会增加基础上下文占用，请将其纳入 MECW 预算

8. 恢复时保留 Agent（Claude Code 2.1.32+）

现在，默认情况下，--resume 会沿用上一次对话中的 --agent 值。恢复的特定 Agent 工作流会继续使用相同的 Agent 配置，无需重新指定。

# Start with a specific agent
claude --agent my-agent

# Resume later — my-agent is automatically used
claude --resume

另请参阅

• /catchup - 根据 git 更改刷新上下文
• /clear - 开始新会话
• Skill(sanctum:git-workspace-review) - 获取仓库上下文

退出条件

• 使用 /rename 将会话命名为带连字符的描述性名称， 符合文档中列出的一种模式（例如 debugging-*、 feature-*、pr-review-*）
• 使用 claude --resume <name> 恢复会话时不会丢失 先前的上下文（通过确认先前的对话仍然存在来验证）
• 如果恢复时找不到会话名称，应显示错误信息 并提供故障排查步骤（检查拼写错误、会话是否过期）
• 对于与 PR 关联的会话（Claude Code 2.1.27+），claude --from-pr <number> 能正确重新打开与该 PR 关联的会话
• 如果恢复后会话上下文似乎不完整，应重新运行 Skill(sanctum: git-workspace-review)，且其输出确认当前 仓库状态