Claude Code 桌面端新增的 /resume 恢复会话功能我这两周用得比预期频繁。它解决的不是“翻聊天记录”的问题而是把一次被中断的长任务接回来继续跑。如果你经常用 Claude Code 处理多文件修改、代码迁移、连续排查问题或者跑着跑着遇到服务繁忙、窗口误关、电脑重启这个功能值得优先熟悉。先说一个容易误解的点/resume 不是聊天软件里的历史消息列表也不等于备份。它恢复的是一次会话的上下文状态包括之前你和模型说过的关键要求、已经做出的决策、正在处理的文件位置。对编码类 Agent 工具来说上下文就是最值钱的东西。重新开一个空白会话再粘贴一遍需求看起来只多花几分钟实际上往往要把前半段已经验证过的方案重新跑一遍遇到长任务时非常折磨。下面我会按实际使用顺序把桌面端 /resume 的能力边界、操作流程、环境准备、常见报错和适合的工作方式拆开说。1. 先说结论/resume 恢复的是上下文不是翻历史记录1.1 它和聊天历史到底有什么区别聊天历史是“你能看到以前说过什么”但要继续干活得把上下文重新喂给模型。Claude Code 的 /resume 则是直接加载一次会话的完整上下文让模型接着上次的思路继续执行。这个区别在实际体验里非常明显。恢复之后它仍然记得你之前约定的代码风格、目录结构、已经改到第几个文件、删掉了哪几个方案。这些信息不需要你再解释第二遍。举个具体例子。有一次我在做某个项目的依赖升级任务量大分了上午和下午两段做。上午结束时窗口已经关了下午重新打开桌面端输入 /resume 选回那个会话它直接说“继续处理剩下三个模块的兼容性问题”连我在哪个文件、用什么方式处理的都还记得。这种体验和“新建会话后重新上传背景”完全不一样。1.2 上下文具体包含哪些内容从实际表现来看/resume 恢复的内容大致包括这几个层面多轮对话记录包括你对需求的补充和修改。已经执行过的工具调用结果比如读取过的文件内容、搜索到的代码位置。模型自己在推理过程中形成的阶段性结论。当前工作目录和项目路径信息。需要注意恢复的是“会话内部状态”不保证恢复“外部系统状态”。如果任务跑到一半模型已经启动了一个本地服务、改过数据库、部署了测试环境这些外部状态不会因为会话恢复而自动回来。恢复会话后一定要先问一句“现在进行到哪一步了”让模型把当前外部状态重新核对一遍。1.3 什么场景最值得用 /resume我梳理了几个高频场景途中被打断。批处理任务跑到一半你要临时开会窗口一关回来还能接着跑。服务端繁忙。模型接口返回限流或负载过高错误等几分钟后恢复会话继续。长任务分多天做。不是每个人都能一个下午搞定整个需求跨天继续是常态。换设备或换网络环境。本机会话文件还在重新打开基本能把上下文接回来。这里也要说清边界。/resume 能恢复的是会话内容不保证恢复所有外部状态。它之前启动的本地进程、创建的临时文件、修改过的环境变量都需要你手工确认。不要把它当成万能断电保护更不要因为有了这个功能就不写进度文档。2. 桌面端实操从 /resume 列表里选回刚才的任务2.1 在输入框直接输入 /resume桌面端虽然是图形界面但命令框入口仍然保留。直接在输入框输入/resume按回车后界面上会列出当前可恢复的会话列表。列表一般会显示会话对应的项目目录、最近的对话摘要或时间点。选一个进去就恢复到了上次的上下文。如果记得具体会话也可以直接指定会话/resume 会话ID会话 ID 通常在 /resume 列表里能看到也可以在会话文件信息里找到。我一般不太背 ID都是先列出来再选。桌面端列表一般会按时间倒序排列最近用过的排在最前面。2.2 先看项目路径再看时间基本不会认错桌面端比命令行多一些项目维度信息。它通常会根据你打开的项目目录来组织会话所以恢复的时候先看项目路径再看时间。这里有一个容易踩的坑同一个项目如果你通过不同路径打开比如一个用/home/user/project一个用/home/user/project/带斜杠或者通过软链接进入系统可能把它识别成不同项目/resume 列表里就会出现多个相似条目。恢复的时候别只看名字像要确认项目路径完全一致。一个实用习惯是每个独立需求开一个会话不要在同一个会话里反复切换不同任务。这样 /resume 列表清楚找起来也快也不会出现一个会话里挤了三个不相关需求的混乱情况。2.3 恢复之后先验证再继续恢复成功之后不要马上让它执行高风险操作。我会先输入一句类似“继续刚才的任务”或“先总结一下当前进度”让它把当前状态反馈出来。这一步有两个作用。第一确认它知道要做什么、改到哪个文件了第二给自己一个反悔的机会。如果发现恢复的内容不对或者恢复的是另一个会话立刻退出还来得及。这个习惯能避免一种尴尬情况你以为它恢复了实际上只恢复了最后几轮对话前面的关键上下文因为窗口关闭太早没来得及写入会话文件。先让它复述任务能省掉后面一系列返工。2.4 和 /rewind、/compact 配合使用恢复会话是“跳到另一个时间点的会话”而同一个会话内部也有类似能力常见的是 /rewind 和 /compact。/rewind在同一个会话里回退到之前的某个对话轮次适合想撤销某几步操作时使用。/compact对当前会话做上下文压缩适合长任务后期对话内容太多、模型看不全时使用。如果你的桌面端版本支持这两个命令我的建议是任务刚跑偏用 /rewind 回退几步任务已经推进了很长时间用 /compact 压缩后再继续会话被中断或者要跨天恢复用 /resume。三个命令各有分工不要混用。注意不同版本内置命令可能不同具体命令是否保留以你当前安装的版本为准。遇到找不到命令的情况先看版本更新说明不要急着重装。3. 环境准备安装、登录、模型配置和编码问题都先排掉3.1 安装之后先确认三件事把桌面端装好只是第一步。我建议按这个顺序确认环境确认登录状态和账号权限。未登录或登录过期时即使会话目录里有历史文件界面也可能不展示。确认模型配置。也就是当前请求走哪个接口、哪个模型。确认工作目录的项目路径。因为会话是按项目组织的。很多人忽略第三点。同一个目录名如果通过不同路径打开会被当成不同项目/resume 列表里就会出现多个相似条目。我就遇到过两次明明恢复的是同一个项目但在两个路径下各留了一套会话后面对齐进度花了很长时间。3.2 接入自定义模型时会影响 /resume 吗关于“claude code 接入 deepseek”“settings.json 配置模型”的问题非常多。实际使用中接入自定义模型一般通过环境变量或配置文件指定接口地址、密钥和模型名大致长这样ANTHROPIC_BASE_URLhttps://你的接口地址 ANTHROPIC_AUTH_TOKENsk-你的密钥 ANTHROPIC_MODEL模型名也可以把这些配置写进 settings.json 或启动脚本里。这类工具的基本逻辑是让 Claude Code 把请求发到你指定的兼容接口而不是默认官方接口。这种配置会影响你“下一次生成”时用的模型但会话文件里保存的上下文是独立存在的。换句话说切换模型后恢复旧会话它仍然能读回之前的记录只是后续回答会由当前配置的模型来生成。这里最容易踩的坑是模型名写错。比如把模型名写成了当前接口根本不支持的名称就会看到类似“某个模型名 is not a model this version of claude code recognizes”的报错。遇到这种报错先去核对配置里的模型名是否和接口提供方一致不用急着重装。有些人会用一个切换工具在多个接口地址之间快速切换。我的经验是切换工具本身不影响会话文件但建议切换后先跑一条简单命令确认新模型可用再恢复旧会话继续干活。否则容易把“模型配置问题”误判成“会话恢复问题”。3.3 Windows 下输出乱码先别怪 /resume另一个高频问题是“claude code输出乱码”。这通常和 /resume 没关系更多是终端编码或字体问题。Windows 下建议把终端代码页切到 UTF-8可以试试在终端里运行chcp 65001然后再看输出。如果正在用 VS Code 集成终端跑命令行版编码设置的影响更大。桌面端如果是自带的界面乱码一般更少但如果你把日志输出重定向到文件后用系统记事本打开也可能因为编码问题显示乱码。我建议把排查顺序分成两段先确认是不是终端编码和字体导致再确认是不是会话内容里的特殊字符在恢复后没有被正确渲染。大多数情况下第一段就能解决。3.4 低配置机器能不能用桌面端本质上是在本地跑一个前端界面真正的模型计算在远端接口完成。所以本机性能压力主要来自界面渲染、会话文件读取和终端日志写入。低配置机器也能用但要注意这几点项目文件特别大时扫描目录会变慢会话文件特别多时/resume 列表加载可能卡顿日志量很大的长任务会把磁盘占用撑起来。对这些情况先把项目目录范围缩小或定期清理旧会话比升级硬件更有效。4. 会话文件是怎么组织的和 CLI、VS Code 插件的关系4.1 会话到底存在哪里Claude Code 的会话历史通常保存在用户目录下的隐藏目录中常见路径是~/.claude/projects/里面按项目路径生成不同文件夹每个会话对应一个或多个带时间戳的 JSONL 文件。JSONL 里记录的就是每轮对话、工具调用和结果。你可以用文件管理器直接看这个目录也可以在终端里检查ls -lt ~/.claude/projects/如果 /resume 列表里找不到某个旧会话而这个目录下还有文件那基本可以判断是项目路径或会话索引问题而不是记录丢失。4.2 桌面端、CLI、VS Code 插件之间能不能互通因为会话文件共用一套目录桌面端、CLI、VS Code 插件在理论上会看到同一批会话。但我在实际使用时发现前端展示不一定完全同步跨界面恢复时最好先去 /resume 列表确认。举个例子你在 CLI 里建的会话回到桌面端后可能要重新扫描目录才会出现在列表里反过来也一样。不同客户端版本对会话元数据的解析也可能有差异。这个部分我建议以本机实测为准不要假设一定互通。尤其不要在一个会话刚结束时就立刻换客户端去恢复先让文件写入完成。4.3 什么时候不要依赖 /resume有两种情况我不会把宝押在 /resume 上。第一种是涉及外部系统状态的任务。比如已经部署到测试环境、改动了数据库、启动了一个长期运行的本地服务。这些状态不会因为会话恢复而自动回来。重开会话前先把当前外部状态记录清楚。第二种是超长会话。上下文太大会挤占模型可用的输入窗口恢复后可能出现“明明有记录但模型看不全”的情况。对这种任务更稳妥的做法是分阶段推进每个阶段结束把关键结论写进项目里的 NOTES 或 TODO 文件。注意/resume 恢复的是会话记录不是项目快照。项目文件本身需要你用 Git 或其他版本管理工具维护这一条不能省。5. 常见问题排查会话找不到、恢复不全、卡住、报模型名错5.1 /resume 列不出刚才的会话优先检查三个地方是否同一个项目路径。换个路径打开就等于换了个会话列表。是否有写入权限。用户目录被限制写入时会话文件可能没落盘。是否刚关闭就立刻打开。我会等一两秒再操作给会话文件写入留时间。如果这三项都正常再看会话文件目录。只要 JSONL 文件还在就还有救。你可以手动把项目切回原路径再打开或者在新会话里补充说明之前的进度。5.2 恢复之后感觉“少了一段”这种情况多是会话文件没有完整写入或者最后几轮工具调用过于复杂导致记录不完整。先看会话记录文件里最后的时间戳确认写入到哪一步。如果确实缺了一段而你能找到当时的终端输出或笔记就把关键结论重新补进去。比如这样和模型说之前我们已经完成了 A 模块的改造B 模块的方案也确认了 现在接着处理 C 模块注意要继续使用前面约定的命名规范。这种补充方式虽然不能做到完全无缝但至少能把重要上下文接回来。5.3 恢复后一直在转圈或没有响应先把网络和模型接口状态确认一遍再看当前配置的模型名是否有效。桌面端界面卡住的时候打开日志文件看具体报错比反复重开窗口更有用。日志定位方法先找到日志文件路径打开后搜索最近的报错关键词比如超时、连接失败、模型名错误、认证失败。大部分卡住问题都能在日志里找到答案不要瞎猜。5.4 遇到 529 等服务端繁忙错误529 通常表示模型服务端负载过高。处理顺序是先停下手头操作。等待一段时间让限流窗口过去。再通过 /resume 恢复会话继续。如果连续多次都返回类似错误再检查是不是接口配置或账号额度出了问题。不要在同一时间反复重试容易把限流窗口拉长。我之前有一次连续点了几次重试结果原本可能几分钟就能恢复硬是拖了更久。冷静等待往往比频繁操作更有效。5.5 一个通用排查顺序现象优先检查处理方向会话列表为空项目路径、登录状态、写入权限回到原目录重新打开恢复内容不完整会话文件时间戳、最后写入时间补关键结论重新继续恢复后转圈网络、模型名、接口地址看日志核对配置输出乱码终端编码、字体切 UTF-8或改用桌面端报模型名无法识别配置的模型名和接口提供方核对准确名称服务端繁忙 529限流、账号额度等待后恢复不要频繁重试排查时不要把“功能本身有问题”放在第一位。大多数情况下原因出在路径、权限、模型名、编码和网络这几类常见因素上。先看现象再看输入再看环境最后才怀疑工具本身。6. 把 /resume 变成工作流的一部分而不只是应急功能6.1 单任务单会话及时收尾每开一个新需求就新建会话不要长时间混用。一个会话里如果混了三个任务恢复时很难定位上下文也会被无关内容污染。我给自己的规则是一个需求对应一个会话完成后再归档。如果 /resume 列表能看到最近对话摘要那么给每个会话一个明确的任务边界找起来会非常快。6.2 长任务的关键信息要落盘不要只依赖模型记住。我会在每个阶段的最后把当前进度、改过的文件、待办事项写进项目里的 notes 文件。这样即使遇到 /resume 也救不回来的极端情况还能手工把上下文补回来。推荐的记录格式很简单任务升级依赖并修复兼容性 已完成A 模块改造完成B 模块方案已确认 进行中C 模块正在处理 待办D 模块需要确认新增参数 注意命名规范按项目现有风格这些内容不一定要写得很正式但必须是你自己回来看得懂的信息。有了它/resume 就是锦上添花没有它/resume 一旦失灵你就得靠记忆重建整个上下文。6.3 定时清理会话文件会话文件会一直累积既占磁盘也让 /resume 列表变长。建议定期清理已经完成任务的会话记录。清理前先确认没有正在进行的任务再删除对应项目目录下的旧 JSONL 文件。想保守一点就先把旧会话目录压缩备份再删。如果你有团队协作需求还可以把重要的会话摘要放到项目文档里方便其他人了解进展。6.4 建议把第一次测试拆成三步如果你刚接触桌面端 /resume不要直接拿一个大任务做实验。先把第一次完整测试拆成几步第一步开一个会话随便聊几句比如让它分析一下当前项目结构。第二步关闭窗口重新打开输入 /resume 看能不能恢复。第三步再开一个真实小任务跑到一半手动关闭然后恢复继续。三步都通过了再把它用于平时的主力开发流程。这样即使中间出问题你也能快速定位是操作问题、环境问题还是功能边界问题而不是在一个大任务里两头为难。踩过几次之后我的感受是/resume 不是一个被反复宣传的“大功能”但它直接把编码 Agent 从“一次性对话工具”往“可持续工作的协作者”推了一步。真正落地时最该盯住的不是菜单里有几个按钮而是项目路径是否一致、会话文件是否完整、长任务有没有把关键状态写到外部。把这几点做好恢复会话才会真的像“接着上次继续干活”而不是“从零开始再讲一遍需求”。
Claude Code /resume：恢复上下文，让长任务无缝续跑
Claude Code 桌面端新增的 /resume 恢复会话功能我这两周用得比预期频繁。它解决的不是“翻聊天记录”的问题而是把一次被中断的长任务接回来继续跑。如果你经常用 Claude Code 处理多文件修改、代码迁移、连续排查问题或者跑着跑着遇到服务繁忙、窗口误关、电脑重启这个功能值得优先熟悉。先说一个容易误解的点/resume 不是聊天软件里的历史消息列表也不等于备份。它恢复的是一次会话的上下文状态包括之前你和模型说过的关键要求、已经做出的决策、正在处理的文件位置。对编码类 Agent 工具来说上下文就是最值钱的东西。重新开一个空白会话再粘贴一遍需求看起来只多花几分钟实际上往往要把前半段已经验证过的方案重新跑一遍遇到长任务时非常折磨。下面我会按实际使用顺序把桌面端 /resume 的能力边界、操作流程、环境准备、常见报错和适合的工作方式拆开说。1. 先说结论/resume 恢复的是上下文不是翻历史记录1.1 它和聊天历史到底有什么区别聊天历史是“你能看到以前说过什么”但要继续干活得把上下文重新喂给模型。Claude Code 的 /resume 则是直接加载一次会话的完整上下文让模型接着上次的思路继续执行。这个区别在实际体验里非常明显。恢复之后它仍然记得你之前约定的代码风格、目录结构、已经改到第几个文件、删掉了哪几个方案。这些信息不需要你再解释第二遍。举个具体例子。有一次我在做某个项目的依赖升级任务量大分了上午和下午两段做。上午结束时窗口已经关了下午重新打开桌面端输入 /resume 选回那个会话它直接说“继续处理剩下三个模块的兼容性问题”连我在哪个文件、用什么方式处理的都还记得。这种体验和“新建会话后重新上传背景”完全不一样。1.2 上下文具体包含哪些内容从实际表现来看/resume 恢复的内容大致包括这几个层面多轮对话记录包括你对需求的补充和修改。已经执行过的工具调用结果比如读取过的文件内容、搜索到的代码位置。模型自己在推理过程中形成的阶段性结论。当前工作目录和项目路径信息。需要注意恢复的是“会话内部状态”不保证恢复“外部系统状态”。如果任务跑到一半模型已经启动了一个本地服务、改过数据库、部署了测试环境这些外部状态不会因为会话恢复而自动回来。恢复会话后一定要先问一句“现在进行到哪一步了”让模型把当前外部状态重新核对一遍。1.3 什么场景最值得用 /resume我梳理了几个高频场景途中被打断。批处理任务跑到一半你要临时开会窗口一关回来还能接着跑。服务端繁忙。模型接口返回限流或负载过高错误等几分钟后恢复会话继续。长任务分多天做。不是每个人都能一个下午搞定整个需求跨天继续是常态。换设备或换网络环境。本机会话文件还在重新打开基本能把上下文接回来。这里也要说清边界。/resume 能恢复的是会话内容不保证恢复所有外部状态。它之前启动的本地进程、创建的临时文件、修改过的环境变量都需要你手工确认。不要把它当成万能断电保护更不要因为有了这个功能就不写进度文档。2. 桌面端实操从 /resume 列表里选回刚才的任务2.1 在输入框直接输入 /resume桌面端虽然是图形界面但命令框入口仍然保留。直接在输入框输入/resume按回车后界面上会列出当前可恢复的会话列表。列表一般会显示会话对应的项目目录、最近的对话摘要或时间点。选一个进去就恢复到了上次的上下文。如果记得具体会话也可以直接指定会话/resume 会话ID会话 ID 通常在 /resume 列表里能看到也可以在会话文件信息里找到。我一般不太背 ID都是先列出来再选。桌面端列表一般会按时间倒序排列最近用过的排在最前面。2.2 先看项目路径再看时间基本不会认错桌面端比命令行多一些项目维度信息。它通常会根据你打开的项目目录来组织会话所以恢复的时候先看项目路径再看时间。这里有一个容易踩的坑同一个项目如果你通过不同路径打开比如一个用/home/user/project一个用/home/user/project/带斜杠或者通过软链接进入系统可能把它识别成不同项目/resume 列表里就会出现多个相似条目。恢复的时候别只看名字像要确认项目路径完全一致。一个实用习惯是每个独立需求开一个会话不要在同一个会话里反复切换不同任务。这样 /resume 列表清楚找起来也快也不会出现一个会话里挤了三个不相关需求的混乱情况。2.3 恢复之后先验证再继续恢复成功之后不要马上让它执行高风险操作。我会先输入一句类似“继续刚才的任务”或“先总结一下当前进度”让它把当前状态反馈出来。这一步有两个作用。第一确认它知道要做什么、改到哪个文件了第二给自己一个反悔的机会。如果发现恢复的内容不对或者恢复的是另一个会话立刻退出还来得及。这个习惯能避免一种尴尬情况你以为它恢复了实际上只恢复了最后几轮对话前面的关键上下文因为窗口关闭太早没来得及写入会话文件。先让它复述任务能省掉后面一系列返工。2.4 和 /rewind、/compact 配合使用恢复会话是“跳到另一个时间点的会话”而同一个会话内部也有类似能力常见的是 /rewind 和 /compact。/rewind在同一个会话里回退到之前的某个对话轮次适合想撤销某几步操作时使用。/compact对当前会话做上下文压缩适合长任务后期对话内容太多、模型看不全时使用。如果你的桌面端版本支持这两个命令我的建议是任务刚跑偏用 /rewind 回退几步任务已经推进了很长时间用 /compact 压缩后再继续会话被中断或者要跨天恢复用 /resume。三个命令各有分工不要混用。注意不同版本内置命令可能不同具体命令是否保留以你当前安装的版本为准。遇到找不到命令的情况先看版本更新说明不要急着重装。3. 环境准备安装、登录、模型配置和编码问题都先排掉3.1 安装之后先确认三件事把桌面端装好只是第一步。我建议按这个顺序确认环境确认登录状态和账号权限。未登录或登录过期时即使会话目录里有历史文件界面也可能不展示。确认模型配置。也就是当前请求走哪个接口、哪个模型。确认工作目录的项目路径。因为会话是按项目组织的。很多人忽略第三点。同一个目录名如果通过不同路径打开会被当成不同项目/resume 列表里就会出现多个相似条目。我就遇到过两次明明恢复的是同一个项目但在两个路径下各留了一套会话后面对齐进度花了很长时间。3.2 接入自定义模型时会影响 /resume 吗关于“claude code 接入 deepseek”“settings.json 配置模型”的问题非常多。实际使用中接入自定义模型一般通过环境变量或配置文件指定接口地址、密钥和模型名大致长这样ANTHROPIC_BASE_URLhttps://你的接口地址 ANTHROPIC_AUTH_TOKENsk-你的密钥 ANTHROPIC_MODEL模型名也可以把这些配置写进 settings.json 或启动脚本里。这类工具的基本逻辑是让 Claude Code 把请求发到你指定的兼容接口而不是默认官方接口。这种配置会影响你“下一次生成”时用的模型但会话文件里保存的上下文是独立存在的。换句话说切换模型后恢复旧会话它仍然能读回之前的记录只是后续回答会由当前配置的模型来生成。这里最容易踩的坑是模型名写错。比如把模型名写成了当前接口根本不支持的名称就会看到类似“某个模型名 is not a model this version of claude code recognizes”的报错。遇到这种报错先去核对配置里的模型名是否和接口提供方一致不用急着重装。有些人会用一个切换工具在多个接口地址之间快速切换。我的经验是切换工具本身不影响会话文件但建议切换后先跑一条简单命令确认新模型可用再恢复旧会话继续干活。否则容易把“模型配置问题”误判成“会话恢复问题”。3.3 Windows 下输出乱码先别怪 /resume另一个高频问题是“claude code输出乱码”。这通常和 /resume 没关系更多是终端编码或字体问题。Windows 下建议把终端代码页切到 UTF-8可以试试在终端里运行chcp 65001然后再看输出。如果正在用 VS Code 集成终端跑命令行版编码设置的影响更大。桌面端如果是自带的界面乱码一般更少但如果你把日志输出重定向到文件后用系统记事本打开也可能因为编码问题显示乱码。我建议把排查顺序分成两段先确认是不是终端编码和字体导致再确认是不是会话内容里的特殊字符在恢复后没有被正确渲染。大多数情况下第一段就能解决。3.4 低配置机器能不能用桌面端本质上是在本地跑一个前端界面真正的模型计算在远端接口完成。所以本机性能压力主要来自界面渲染、会话文件读取和终端日志写入。低配置机器也能用但要注意这几点项目文件特别大时扫描目录会变慢会话文件特别多时/resume 列表加载可能卡顿日志量很大的长任务会把磁盘占用撑起来。对这些情况先把项目目录范围缩小或定期清理旧会话比升级硬件更有效。4. 会话文件是怎么组织的和 CLI、VS Code 插件的关系4.1 会话到底存在哪里Claude Code 的会话历史通常保存在用户目录下的隐藏目录中常见路径是~/.claude/projects/里面按项目路径生成不同文件夹每个会话对应一个或多个带时间戳的 JSONL 文件。JSONL 里记录的就是每轮对话、工具调用和结果。你可以用文件管理器直接看这个目录也可以在终端里检查ls -lt ~/.claude/projects/如果 /resume 列表里找不到某个旧会话而这个目录下还有文件那基本可以判断是项目路径或会话索引问题而不是记录丢失。4.2 桌面端、CLI、VS Code 插件之间能不能互通因为会话文件共用一套目录桌面端、CLI、VS Code 插件在理论上会看到同一批会话。但我在实际使用时发现前端展示不一定完全同步跨界面恢复时最好先去 /resume 列表确认。举个例子你在 CLI 里建的会话回到桌面端后可能要重新扫描目录才会出现在列表里反过来也一样。不同客户端版本对会话元数据的解析也可能有差异。这个部分我建议以本机实测为准不要假设一定互通。尤其不要在一个会话刚结束时就立刻换客户端去恢复先让文件写入完成。4.3 什么时候不要依赖 /resume有两种情况我不会把宝押在 /resume 上。第一种是涉及外部系统状态的任务。比如已经部署到测试环境、改动了数据库、启动了一个长期运行的本地服务。这些状态不会因为会话恢复而自动回来。重开会话前先把当前外部状态记录清楚。第二种是超长会话。上下文太大会挤占模型可用的输入窗口恢复后可能出现“明明有记录但模型看不全”的情况。对这种任务更稳妥的做法是分阶段推进每个阶段结束把关键结论写进项目里的 NOTES 或 TODO 文件。注意/resume 恢复的是会话记录不是项目快照。项目文件本身需要你用 Git 或其他版本管理工具维护这一条不能省。5. 常见问题排查会话找不到、恢复不全、卡住、报模型名错5.1 /resume 列不出刚才的会话优先检查三个地方是否同一个项目路径。换个路径打开就等于换了个会话列表。是否有写入权限。用户目录被限制写入时会话文件可能没落盘。是否刚关闭就立刻打开。我会等一两秒再操作给会话文件写入留时间。如果这三项都正常再看会话文件目录。只要 JSONL 文件还在就还有救。你可以手动把项目切回原路径再打开或者在新会话里补充说明之前的进度。5.2 恢复之后感觉“少了一段”这种情况多是会话文件没有完整写入或者最后几轮工具调用过于复杂导致记录不完整。先看会话记录文件里最后的时间戳确认写入到哪一步。如果确实缺了一段而你能找到当时的终端输出或笔记就把关键结论重新补进去。比如这样和模型说之前我们已经完成了 A 模块的改造B 模块的方案也确认了 现在接着处理 C 模块注意要继续使用前面约定的命名规范。这种补充方式虽然不能做到完全无缝但至少能把重要上下文接回来。5.3 恢复后一直在转圈或没有响应先把网络和模型接口状态确认一遍再看当前配置的模型名是否有效。桌面端界面卡住的时候打开日志文件看具体报错比反复重开窗口更有用。日志定位方法先找到日志文件路径打开后搜索最近的报错关键词比如超时、连接失败、模型名错误、认证失败。大部分卡住问题都能在日志里找到答案不要瞎猜。5.4 遇到 529 等服务端繁忙错误529 通常表示模型服务端负载过高。处理顺序是先停下手头操作。等待一段时间让限流窗口过去。再通过 /resume 恢复会话继续。如果连续多次都返回类似错误再检查是不是接口配置或账号额度出了问题。不要在同一时间反复重试容易把限流窗口拉长。我之前有一次连续点了几次重试结果原本可能几分钟就能恢复硬是拖了更久。冷静等待往往比频繁操作更有效。5.5 一个通用排查顺序现象优先检查处理方向会话列表为空项目路径、登录状态、写入权限回到原目录重新打开恢复内容不完整会话文件时间戳、最后写入时间补关键结论重新继续恢复后转圈网络、模型名、接口地址看日志核对配置输出乱码终端编码、字体切 UTF-8或改用桌面端报模型名无法识别配置的模型名和接口提供方核对准确名称服务端繁忙 529限流、账号额度等待后恢复不要频繁重试排查时不要把“功能本身有问题”放在第一位。大多数情况下原因出在路径、权限、模型名、编码和网络这几类常见因素上。先看现象再看输入再看环境最后才怀疑工具本身。6. 把 /resume 变成工作流的一部分而不只是应急功能6.1 单任务单会话及时收尾每开一个新需求就新建会话不要长时间混用。一个会话里如果混了三个任务恢复时很难定位上下文也会被无关内容污染。我给自己的规则是一个需求对应一个会话完成后再归档。如果 /resume 列表能看到最近对话摘要那么给每个会话一个明确的任务边界找起来会非常快。6.2 长任务的关键信息要落盘不要只依赖模型记住。我会在每个阶段的最后把当前进度、改过的文件、待办事项写进项目里的 notes 文件。这样即使遇到 /resume 也救不回来的极端情况还能手工把上下文补回来。推荐的记录格式很简单任务升级依赖并修复兼容性 已完成A 模块改造完成B 模块方案已确认 进行中C 模块正在处理 待办D 模块需要确认新增参数 注意命名规范按项目现有风格这些内容不一定要写得很正式但必须是你自己回来看得懂的信息。有了它/resume 就是锦上添花没有它/resume 一旦失灵你就得靠记忆重建整个上下文。6.3 定时清理会话文件会话文件会一直累积既占磁盘也让 /resume 列表变长。建议定期清理已经完成任务的会话记录。清理前先确认没有正在进行的任务再删除对应项目目录下的旧 JSONL 文件。想保守一点就先把旧会话目录压缩备份再删。如果你有团队协作需求还可以把重要的会话摘要放到项目文档里方便其他人了解进展。6.4 建议把第一次测试拆成三步如果你刚接触桌面端 /resume不要直接拿一个大任务做实验。先把第一次完整测试拆成几步第一步开一个会话随便聊几句比如让它分析一下当前项目结构。第二步关闭窗口重新打开输入 /resume 看能不能恢复。第三步再开一个真实小任务跑到一半手动关闭然后恢复继续。三步都通过了再把它用于平时的主力开发流程。这样即使中间出问题你也能快速定位是操作问题、环境问题还是功能边界问题而不是在一个大任务里两头为难。踩过几次之后我的感受是/resume 不是一个被反复宣传的“大功能”但它直接把编码 Agent 从“一次性对话工具”往“可持续工作的协作者”推了一步。真正落地时最该盯住的不是菜单里有几个按钮而是项目路径是否一致、会话文件是否完整、长任务有没有把关键状态写到外部。把这几点做好恢复会话才会真的像“接着上次继续干活”而不是“从零开始再讲一遍需求”。
