Gemini CLI 会话管理实战会话自动保存、恢复、检查点与保留策略深度解析【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cliGemini CLI 的会话管理Session Management负责把你与模型的完整对话历史持久化到本地让你可以随时从上次中断的地方继续工作。本文基于官方文档 session-management.md 并结合当前仓库源码系统讲解会话的自动保存机制、通过命令行与交互式浏览器恢复会话的完整操作、Git worktree 并行会话方案以及sessionRetention与maxSessionTurns的保留策略配置——读完之后你可以独立完成会话的查看、恢复、删除与清理策略定制。会话自动保存保存什么、存在哪里你与模型交互时会话历史会被自动记录无需任何手动操作。这一后台持久化过程即使在你中断会话如 CtrlC、终端意外关闭的情况下也能保证工作现场得以保留。保存的内容包括完整的对话上下文你的提示词prompts和模型的回复所有工具执行记录输入与输出Token 用量统计输入、输出、缓存等维度助理的思考与推理摘要thoughts / reasoning summaries在模型支持时可用。存储位置为~/.gemini/tmp/project_hash/chats/其中project_hash是基于项目根目录生成的唯一标识。这带来一个关键特性会话是按项目隔离的。切换到另一个目录另一个项目再启动 CLI加载的就是那个项目自己的会话历史互不干扰。从源码结构看这一隔离逻辑由核心包的Storage类统一管理sessions.ts 中listSessions通过config.storage拿到项目级临时目录再拼接chats子目录扫描会话文件。会话文件名遵循session-时间戳-ID前8位.jsonl格式——在 sessionUtils.ts 的注释中明确写道The filename format issession-TIMESTAMP-ID_SLICE(0,8).jsonl文件名中只保留 UUID 的前 8 位作为短标识完整 UUID 记录在文件内容的sessionId字段中。恢复或按短 ID 查找时SessionSelector.sessionExists会先按前 8 位过滤候选文件再逐个解析确认完整 ID 是否匹配见 sessionUtils.ts#L415-L440。另外扫描时会主动过滤三类文件它们不会出现在会话列表中子代理subagent会话属于工具调用的内部实现细节不对主代理历史开放无可恢复内容的会话仅含启动信息、系统消息或内部上下文的会话被跳过hasResumableContent校验损坏文件解析失败的文件标记为 corrupted列表接口自动剔除。恢复会话命令行三种方式启动 Gemini CLI 时使用--resume简写-r标志加载已有会话支持三种寻址方式1. 恢复最近一次会话gemini --resume不带参数时立即加载最新会话。对应源码中RESUME_LATEST常量sessionUtils.ts#L26--resume无值时被解析为latestSessionSelector.resolveSession会按startTime升序排序后取最后一个。值得注意的是当项目根本没有任何会话时latest不会报错退出而是发出警告并回退创建一个新会话见 gemini.tsx#L315-L319。2. 按索引恢复先列出可用会话见下文 列出会话再用序号恢复gemini --resume 1索引是 1 基的按会话开始时间从旧到新编号——越新的会话编号越大。3. 按 UUID 恢复直接提供完整会话 IDgemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890从 SessionSelector.findSession 的实现可以确认解析优先级先按完整 UUID 精确匹配匹配失败才尝试解析为纯数字索引且要求索引严格为数字字符串、大于 0 且不超过会话总数。找不到时抛出带INVALID_SESSION_IDENTIFIER错误码的SessionError提示信息会引导你使用--list-sessions查看可用会话。恢复会话交互式 Session Browser在 CLI 运行中输入/resume斜杠命令即可打开Session Browser/resume从源码看resumeCommand.ts 将其定义为CommandKind.BUILT_IN的内建命令autoExecute: true——即无需带参数直接执行其动作是返回dialog: sessionBrowser交给 DialogManager 渲染。在斜杠命令补全界面中/resume或/chat等命令会按标题分隔符分组展示-- auto --会话浏览器组其中的list可被选中直接打开会话浏览器-- checkpoints --手动检查点命令组。唯一前缀如/resum、/cha也会解析到同一个分组菜单。Session Browser 支持的交互操作如下这些按键处理逻辑可在 SessionBrowser.tsx 的键盘事件分支中找到对应实现操作按键说明浏览上下方向键 / PageUp / PageDown滚动浏览历史会话列表预览选中项显示会话日期、消息数、首条用户提示词等详情搜索/进入搜索模式按 ID 或会话内容过滤恢复Enter恢复选中的会话退出Esc关闭 Session Browser删除x或X删除选中的会话源码中key.sequence x \|\| key.sequence X分支触发删除流程预览信息来自SessionInfo结构sessionUtils.ts#L90-L121包含startTime、messageCount、lastUpdated、displayName通常为 AI 摘要或首条用户消息等字段。搜索模式下会按需加载会话全文includeFullContent选项进行内容级匹配并展示带上下文的片段。手动会话检查点对于会话内部需要命名分支点branch point的场景使用 chat checkpoints 保存和回跳/resume save decision-point /resume list /resume resume decision-point兼容性别名/chat ...可以执行同样的命令/resume checkpoints ...在迁移期内也保持可用。使用 Git worktrees 并行多个会话同时处理多个任务时可以用 Git worktrees 为每个 Gemini 会话提供独立的代码库副本避免一个会话的改动与另一个会话冲突。由于会话按项目根目录project_hash隔离每个 worktree 目录天然对应独立的会话存储空间这与 worktree 的隔离诉求正好契合。管理会话列出与删除列出会话gemini --list-sessions输出当前项目所有可用会话的示例Available sessions for this project (3): 1. Fix bug in auth (2 days ago) [a1b2c3d4] 2. Refactor database schema (5 hours ago) [e5f67890] 3. Update documentation (Just now) [abcd1234]实现位于 listSessions会话按开始时间升序编号每行显示序号、标题超过 100 字符截断为 97 字符加省略号、相对时间与 8 位短 ID当前活动会话会额外标注, current。此外列表生成前会先调用generateSummary为最近一次会话生成 AI 摘要未配置认证时优雅跳过因此列表中的标题可能是摘要而非原始首条消息。删除会话命令行方式--delete-session后跟索引或 IDgemini --delete-session 2deleteSession 的解析策略与--resume一致——先 UUID 后索引同时有一条硬性保护不允许删除当前活动会话isCurrentSession为真时直接提示Cannot delete the current active session.并返回。Session Browser 方式用/resume打开浏览器导航到要删除的会话按x。配置保留策略sessionRetention你可以在settings.json中控制会话历史的保留方式。默认情况下Gemini CLI 会自动清理过期的会话数据防止历史无限膨胀某个会话被删除时其所有关联数据实现计划、任务跟踪器、工具输出、活动日志会一并清除。默认策略是保留会话 30 天。通过/settings命令或直接编辑settings.json自定义{ general: { sessionRetention: { enabled: true, maxAge: 30d, maxCount: 50 } } }enabledboolean会话清理总开关默认true。maxAgestring会话保留时长例如24h、7d、4w超过该时长的会话将被删除默认30d。maxCountnumber保留的会话数量上限超出部分从最旧的开始删除。默认为未定义不限制。minRetentionstring最短保留期安全下限默认1d比该期限更新的会话永远不会被自动清理。底层实现细节见 sessionCleanup.ts时长字符串由parseRetentionPeriod解析支持的单位是h小时、d天、w周、m月按 30 天计且数值必须大于 0——注意文档示例中的4w之外的单位如s、y不在支持范围启动时执行的validateRetentionConfig会做三项校验maxAge不得小于minRetentionmaxCount至少为 1maxAge与maxCount必须至少指定其一。任何一项不满足清理会被整体禁用并写警告日志Session cleanup disabled: ...而不是误删数据清理入口cleanupExpiredSessions在 CLI 启动时运行删除判定基于lastUpdated时间戳且当前活动会话永远被排除在删除范围之外除了会话文件本身还会级联调用deleteSessionArtifactsAsync与deleteSubagentSessionDirAndArtifactsAsync清除该会话的工具输出目录、子代理会话等关联产物同一份保留策略同样作用于tool-outputs目录的清理cleanupToolOutputFiles即工具输出的年龄与数量上限与maxAge/maxCount联动全局兜底原则是“清理失败不阻断启动”任何异常都会被捕获并计入failed统计不会导致 CLI 无法启动。配置单会话长度上限maxSessionTurns为防止单个会话的上下文窗口过大、成本过高可以限制会话轮次{ model: { maxSessionTurns: 100 } }maxSessionTurnsnumber单次会话允许的最大轮数用户与模型的交互往返数。设为-1表示无限制默认值。达到上限后的行为交互模式CLI 显示一条提示信息并停止向模型发送请求需要手动开启新会话非交互模式CLI 直接以错误退出。延伸阅读Memory 工具把信息持久化并跨会话保留Checkpoint会话状态的检查点机制CLI 参考全部命令行标志Git worktrees 指南并行会话的目录隔离方案实现与测试sessions.ts、sessionUtils.ts、sessionCleanup.ts、sessionCleanup.integration.test.ts、SessionBrowser 组件。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考