CodeWhale 会话状态如何落盘与恢复SQLite 持久化完整指南【免费下载链接】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 是一款用 Rust 编写的开源终端 AI 编码助手。你与它进行的每一轮对话、保存的检查点、后台任务状态都会通过SQLite 持久化机制写入本地数据库下次启动时即可一键恢复会话。本文将带你了解 CodeWhale 的会话状态是如何落盘的、数据存放在哪里以及崩溃后如何安全恢复。为什么 CodeWhale 要引入 SQLite 持久化早期版本的 CodeWhale 用一条会话一个 JSON 文件的方式保存状态。这种方式简单但带来了五个明显痛点详见 docs/rfcs/2189-persistence-sqlite.md列出会话很慢—— 每次都要扫描目录并反序列化每一个文件过滤困难—— 比如查最近 7 天所有失败任务只能全量扫描缺乏事务一致性—— 崩溃时可能留下孤立的中间数据事件时间线无索引—— JSONL 追加文件重放成本 O(n)版本策略分散—— 六个模块各自维护一套 schema 版本号。为此CodeWhale 把核心状态迁移到了 SQLite基于rusqlite并保留少量 JSONL 作为补充索引获得了 SQL 查询、索引加速和事务一致性。会话数据落盘位置一览都在你的家目录所有持久化数据默认存放在用户主目录下结构非常清晰数据内容存储位置写入方式线程/消息/检查点/任务~/.codewhale/state.dbSQLiteSQL 事务会话名称索引~/.codewhale/session_index.jsonl仅追加会话快照~/.codewhale/sessions/{id}.json原子写入崩溃恢复检查点~/.codewhale/sessions/checkpoints/latest.json原子写入离线降级队列~/.codewhale/sessions/checkpoints/offline_queue.json原子写入数据库连接入口在 crates/state/src/lib.rs 的StateStore::open中首次打开时自动创建目录、初始化 schema若走旧路径则回退到~/.deepseek/state.db。state.db 里有什么六类核心表打开 crates/state/src/lib.rs 可以看到完整的建表语句threads—— 会话元数据工作目录、模型提供方、Git 分支/commit、CLI 版本、状态、是否归档等messages—— 追加式的消息记录通过parent_entry_id形成树状结构这是会话分叉fork与编辑重发的能力基础checkpoints—— 命名的状态快照用于回滚和恢复进度jobs—— 后台任务的状态排队/运行中/暂停/完成/失败/取消与进度百分比thread_dynamic_tools—— 会话内动态注册的工具及其 JSON Schemathread_goals与工作流运行表workflow_runs、branch_runs等—— 记录自动工作流的执行轨迹。每张表都配有针对按更新时间倒序列出场景的索引所以列出最近会话是一次轻量查询而不再是文件扫描。三个关键设计让落盘在崩溃面前也安全1. WAL 模式多进程不互相阻塞configure_connection 会强制开启 SQLite 的 WAL写前日志模式并设置 5 秒 busy timeout。即使你同时开两个 CodeWhale 窗口读写也不会立刻互相锁死第二个进程会重试而不是报错。2. 原子写入绝不留下半截文件JSON 类快照会话文件、检查点、离线队列统一通过write_atomic先写临时文件再原子重命名见 crates/tui/src/session_manager.rs。任何时刻断电你看到的要么是旧文件要么是完整的新文件永远不会是损坏的中间状态。3. Schema 版本号 reject-newer 策略会话文件带有CURRENT_SESSION_SCHEMA_VERSION 1之类的版本常量。旧版本二进制拒绝加载新版本写出的数据避免解析出错误状态而静默损坏。此外session_index.jsonl在累积到 5000 行后会自动压实只保留每个线程的最新条目索引文件不会无限膨胀。会话数量上限为 50 条超出的最旧会话按保留策略清理。如何恢复之前的 CodeWhale 会话恢复流程对使用者来说非常简单启动 CodeWhale 后在New session界面直接查看最近的会话列表上图所示输入会话关键词即可检索、选中任意历史会话继续对话会话内的中间进度还可通过checkpoints回滚到此前保存的快照若上次运行时程中断checkpoints/latest.json中的崩溃恢复检查点会帮你接回现场。下面的界面展示了左侧栏的会话恢复列表——你可以按工作区快速找回2 天前未完成的那次对话 小提示会话元数据里记录了创建时的工作目录和 Git 分支恢复时你能确认它属于哪个项目上下文避免拿错会话。想深入源码从这几个文件入手持久化总体设计动机与问题清单docs/rfcs/2189-persistence-sqlite.mdSQLite 状态库建表、WAL、迁移crates/state/src/lib.rs会话保存/列出/恢复生命周期crates/tui/src/session_manager.rs目录常量定义crates/paths/src/lib.rs迁移背景与痛点对照表docs/rfcs/2189-persistence-sqlite.md#L68-L86如果想亲手试一下可以克隆仓库源码git clone https://gitcode.com/GitHub_Trending/de/CodeWhale然后按 docs/INSTALL.md 构建运行。小结CodeWhale 的 SQLite 持久化方案可以概括为三句话落盘核心状态集中在~/.codewhale/state.db会话快照用原子写入的 JSON 文件补充查询threads/messages/checkpoints/jobs 等表全部带索引列会话、过滤、排序都是毫秒级 SQL恢复会话选择器 checkpoints 崩溃检查点让上次聊到哪了永远有据可查。对新手来说你几乎不需要关心这些细节——只要正常退出 CodeWhale下次启动就能无缝接上而当你真正遇到进程崩溃时正是这些落盘机制在悄悄保护你的工作进度。【免费下载链接】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），仅供参考
CodeWhale 会话状态如何落盘与恢复：SQLite 持久化完整指南
CodeWhale 会话状态如何落盘与恢复SQLite 持久化完整指南【免费下载链接】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 是一款用 Rust 编写的开源终端 AI 编码助手。你与它进行的每一轮对话、保存的检查点、后台任务状态都会通过SQLite 持久化机制写入本地数据库下次启动时即可一键恢复会话。本文将带你了解 CodeWhale 的会话状态是如何落盘的、数据存放在哪里以及崩溃后如何安全恢复。为什么 CodeWhale 要引入 SQLite 持久化早期版本的 CodeWhale 用一条会话一个 JSON 文件的方式保存状态。这种方式简单但带来了五个明显痛点详见 docs/rfcs/2189-persistence-sqlite.md列出会话很慢—— 每次都要扫描目录并反序列化每一个文件过滤困难—— 比如查最近 7 天所有失败任务只能全量扫描缺乏事务一致性—— 崩溃时可能留下孤立的中间数据事件时间线无索引—— JSONL 追加文件重放成本 O(n)版本策略分散—— 六个模块各自维护一套 schema 版本号。为此CodeWhale 把核心状态迁移到了 SQLite基于rusqlite并保留少量 JSONL 作为补充索引获得了 SQL 查询、索引加速和事务一致性。会话数据落盘位置一览都在你的家目录所有持久化数据默认存放在用户主目录下结构非常清晰数据内容存储位置写入方式线程/消息/检查点/任务~/.codewhale/state.dbSQLiteSQL 事务会话名称索引~/.codewhale/session_index.jsonl仅追加会话快照~/.codewhale/sessions/{id}.json原子写入崩溃恢复检查点~/.codewhale/sessions/checkpoints/latest.json原子写入离线降级队列~/.codewhale/sessions/checkpoints/offline_queue.json原子写入数据库连接入口在 crates/state/src/lib.rs 的StateStore::open中首次打开时自动创建目录、初始化 schema若走旧路径则回退到~/.deepseek/state.db。state.db 里有什么六类核心表打开 crates/state/src/lib.rs 可以看到完整的建表语句threads—— 会话元数据工作目录、模型提供方、Git 分支/commit、CLI 版本、状态、是否归档等messages—— 追加式的消息记录通过parent_entry_id形成树状结构这是会话分叉fork与编辑重发的能力基础checkpoints—— 命名的状态快照用于回滚和恢复进度jobs—— 后台任务的状态排队/运行中/暂停/完成/失败/取消与进度百分比thread_dynamic_tools—— 会话内动态注册的工具及其 JSON Schemathread_goals与工作流运行表workflow_runs、branch_runs等—— 记录自动工作流的执行轨迹。每张表都配有针对按更新时间倒序列出场景的索引所以列出最近会话是一次轻量查询而不再是文件扫描。三个关键设计让落盘在崩溃面前也安全1. WAL 模式多进程不互相阻塞configure_connection 会强制开启 SQLite 的 WAL写前日志模式并设置 5 秒 busy timeout。即使你同时开两个 CodeWhale 窗口读写也不会立刻互相锁死第二个进程会重试而不是报错。2. 原子写入绝不留下半截文件JSON 类快照会话文件、检查点、离线队列统一通过write_atomic先写临时文件再原子重命名见 crates/tui/src/session_manager.rs。任何时刻断电你看到的要么是旧文件要么是完整的新文件永远不会是损坏的中间状态。3. Schema 版本号 reject-newer 策略会话文件带有CURRENT_SESSION_SCHEMA_VERSION 1之类的版本常量。旧版本二进制拒绝加载新版本写出的数据避免解析出错误状态而静默损坏。此外session_index.jsonl在累积到 5000 行后会自动压实只保留每个线程的最新条目索引文件不会无限膨胀。会话数量上限为 50 条超出的最旧会话按保留策略清理。如何恢复之前的 CodeWhale 会话恢复流程对使用者来说非常简单启动 CodeWhale 后在New session界面直接查看最近的会话列表上图所示输入会话关键词即可检索、选中任意历史会话继续对话会话内的中间进度还可通过checkpoints回滚到此前保存的快照若上次运行时程中断checkpoints/latest.json中的崩溃恢复检查点会帮你接回现场。下面的界面展示了左侧栏的会话恢复列表——你可以按工作区快速找回2 天前未完成的那次对话 小提示会话元数据里记录了创建时的工作目录和 Git 分支恢复时你能确认它属于哪个项目上下文避免拿错会话。想深入源码从这几个文件入手持久化总体设计动机与问题清单docs/rfcs/2189-persistence-sqlite.mdSQLite 状态库建表、WAL、迁移crates/state/src/lib.rs会话保存/列出/恢复生命周期crates/tui/src/session_manager.rs目录常量定义crates/paths/src/lib.rs迁移背景与痛点对照表docs/rfcs/2189-persistence-sqlite.md#L68-L86如果想亲手试一下可以克隆仓库源码git clone https://gitcode.com/GitHub_Trending/de/CodeWhale然后按 docs/INSTALL.md 构建运行。小结CodeWhale 的 SQLite 持久化方案可以概括为三句话落盘核心状态集中在~/.codewhale/state.db会话快照用原子写入的 JSON 文件补充查询threads/messages/checkpoints/jobs 等表全部带索引列会话、过滤、排序都是毫秒级 SQL恢复会话选择器 checkpoints 崩溃检查点让上次聊到哪了永远有据可查。对新手来说你几乎不需要关心这些细节——只要正常退出 CodeWhale下次启动就能无缝接上而当你真正遇到进程崩溃时正是这些落盘机制在悄悄保护你的工作进度。【免费下载链接】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），仅供参考
