CodeWhale 崩溃恢复：如何用 checkpoint 与 --resume 找回意外退出前的会话

CodeWhale 崩溃恢复如何用 checkpoint 与 --resume 找回意外退出前的会话【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodewhaleCodewhale 的 TUI 进程可能在流式响应中途、工具执行期间或终端断开时意外退出。由于 Codewhale 默认以全新会话启动不自动重连旧会话退出前正在进行的对话需要通过它的崩溃检查点checkpoint机制和--resume/--continue标志显式恢复。本文基于 docs/OPERATIONS_RUNBOOK.md 与 docs/ARCHITECTURE.md 中记载的行为给出从确认检查点到恢复会话的完整操作路径。checkpoint 的写入与清除时机恢复的前提是理解检查点何时存在。根据 docs/ARCHITECTURE.md 的 Crash Recovery Offline Queue 小节在把用户输入发送给模型之前TUI 会先把一份检查点快照写入~/.codewhale/sessions/checkpoints/latest.json启动默认保持全新会话旧会话必须通过--resume/--continue或 TUI 内的CtrlR显式恢复一个 turn 成功完成后当前激活的检查点会被清除并写入一份持久的会话快照目录~/.codewhale/sessions/checkpoints/同时承载崩溃检查点与离线队列offline_queue.json的持久化。由此可以判断两种现场如果进程在输入已提交、turn 尚未成功完成时崩溃latest.json应当还在如果最后一个 turn 正常完成过激活检查点已被清除此时恢复依赖的是~/.codewhale/sessions/下的持久会话记录。第一步确认检查点与会话状态Runbook 的 Quick Triage 给出的状态检查命令ls ~/.codewhale/sessions ls ~/.codewhale/sessions/checkpointssessions/中列出的是持久会话记录其中的 id或 id 前缀就是恢复参数checkpoints/中存在latest.json说明最近有一次尚未成功完成的输入留有崩溃检查点。如果需要检查检查点内容Runbook 中列为恢复动作之一cat ~/.codewhale/sessions/checkpoints/latest.json第二步恢复会话Runbook Incident: Crash Recovery Needed 与 docs/MODES.md Related CLI Flags 给出以下等价入口# 按会话 id 或 id 前缀恢复-r 是 --resume 的短选项 codewhale --resume id # 上面命令的别名写法 codewhale resume id # 直接取该工作区最近一次被中断的检查点 codewhale --continue其中id是第一步中从~/.codewhale/sessions里看到的会话 iddocs/MODES.md 中该标志的定义是-r, --resume ID|PREFIX|latest因此也可以只传 id 前缀或传latest表示最近的已保存会话。已经在 TUI 内运行时也可以用CtrlR触发恢复。非交互场景脚本、管道对应 docs/MODES.md 中的exec形式codewhale exec --resume ID|PREFIX PROMPT codewhale exec --continue PROMPTID|PREFIX与PROMPT分别替换为要恢复的会话标识和要发回该会话的提示词。第三步验证恢复是否成功文档明确记载的恢复后行为与失败信号恢复的是已保存的会话--resume/--continue成功后 TUI 进入带原有转录的会话而非空白启动屏docs/CONFIGURATION.md 提到 only an explicit resume or an explicit initial prompt enters the live session directlysession_auto_resume的说明同时界定了恢复会被拒绝的情况已归档、加载失败、或记录在另一个工作区下的会话不会被恢复启动会回退到全新转录并说明跳过了哪个会话及原因。--resume、--continue、--fresh的优先级始终高于该自动恢复设置。如果你看到类似schema vX is newer than supported vY的错误说明持久化记录的 schema 版本高于当前二进制支持——这是 docs/OPERATIONS_RUNBOOK.md Persistent State Schema Errors 一节描述的已知现象处理方式见下文排查。可选让启动自动重新附着到最近会话docs/CONFIGURATION.md 中的session_auto_resume设置on/off默认off控制启动时是否自动重新附着该工作区最近的会话。默认关闭是为了让普通的codewhale命令保持全新启动。如果你希望每次启动都自动接上工作区最近会话可以开启它注意它只作用于交互式启动——codewhale prompt与codewhale exec不会被静默加上先前对话前缀。排查schema 过新与残留检查点Runbook 给出了两条对应处理路径检查点 schema 过新当latest.json的 schema 高于当前二进制支持时Runbook 建议升级二进制或删除过期的检查点。持久化状态 schema 错误症状如schema vX is newer than supported vY影响~/.codewhale/sessions/*.json、runtime thread/turn/item 记录、~/.codewhale/tasks/tasks/*.json先确认二进制版本与迁移预期编辑状态文件前先备份状态目录例如把~/.codewhale/sessions/复制一份然后二选一使用更新且兼容的二进制运行或归档不兼容的记录并重新生成状态。另据 docs/ARCHITECTURE.md 的 Durable Schema Gates 说明session_manager.rs、runtime_threads.rs、task_manager.rs会在持久化记录中写入schema_version加载时遇到更新的 schema 版本会直接报显式错误而不是静默截断或覆盖数据——所以遇到该报错时不要直接改写 JSON 文件。相关但独立的恢复路径以下机制与崩溃恢复相关但服务于不同目的仅在需要时使用来源docs/MODES.md Branching and Rollbackcodewhale fork ID|PREFIX/codewhale fork --last把已保存会话复制为一个新的兄弟会话用于在不动原会话的前提下探索另一条答案路径Esc-Esc 回退把当前转录回退到某条用户提示并放回输入框编辑只作用于活动转录/restore N与revert_turn从 side-git 快照恢复工作区文件快照位于~/.codewhale/snapshots/project_hash/worktree_hash/.git不改变对话历史也不动用户自己的.git。小结恢复的主路径只有三步用ls ~/.codewhale/sessions[/checkpoints]确认状态用codewhale --resume id|prefix|latest或codewhale --continue显式恢复再按文档记载的拒绝条件与 schema 报错信息判断是否恢复成功。TUI 内随时可用CtrlR走同一条恢复实现若只想恢复工作区文件而不关心对话使用/restore或revert_turn而不是重放会话。【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考