Juggler会话持久化与恢复:为什么关掉重开,AI的工作上下文和待审批请求都还在
Juggler会话持久化与恢复:为什么关掉重开,AI的工作上下文和待审批请求都还在
Juggler 是一款本地优先的 AI 编程代理(coding agent)工作台。它的会话持久化与恢复机制,让对话不再是屏幕上易逝的聊天记录:关掉应用、重启机器,甚至进程中途崩溃,重新打开后 AI 的工作上下文、每一轮模型调用的记录,以及还在等待你批准的审批请求,都原样等你回来。
一份存到磁盘的"会话文档",而不是一串聊天记录
在 Juggler 里,每个项目对应一个会话(Session),所有状态都写在项目根目录的 .juggler/ 文件夹里——就在代码旁边。每条对话本身是一个独立目录,结构长这样:
<项目>/.juggler/
├── session.json # 会话清单:标签页顺序、当前选中、输入历史等
└── 对话名称--conv_xxxxx/
├── doc.yjs # Yjs 文档:完整对话树 + 待办/待审批状态
├── txns/ # 每一轮 LLM 调用的只写快照(JSON)
├── assets/ # 图片等附件(按内容哈希命名)
└── programs/ # 等待用户操作时的工具现场快照
几个关键点:
doc.yjs是主文档:对话里的消息、工具调用、上下文条目,连同每个线程的pendingRequests(待处理请求队列)都保存在同一份 Yjs 文档里;txns/只写不改:每轮模型往返生成一个 JSON 快照,事后可逐条回看模型收到和返回了什么;assets/内容寻址:附件按哈希存储,重开时按 ID 取回,不依赖任何内存缓存;- 用户级的凭据、默认模型配置则放在
~/.juggler/,与项目会话数据分开。
上图是仓库测试数据中的一张示例图片(2000×1000),用于验证会话附件的显示效果——真实会话里,这类附件就持久化在对话目录的 assets/ 下。
自动保存:2 秒防抖 + 关机强制落盘
你不需要手动点"保存"。后台 worker 用一个防抖调度器(docSaver)管理落盘:
- 任何改动都会把文档标记为"未保存",2 秒内没有新改动就写盘;
- 即使改动连成一片、防抖不断被重置,最多 10 秒也会强制保存一次,不会无限推迟;
- 退出应用前再同步强制一次 flush,确保最后一刻的改动不丢。
而且每次写盘都走原子写入:先写同目录的临时文件并同步到磁盘,再一次性重命名覆盖原文件——任何时刻磁盘上只有"旧版本"或"新版本"两种完整状态,断电也不会留下写了一半的残文件。
待审批请求为什么也还在?
这是 Juggler 会话恢复里最实用的一点。写文件、执行命令这类工具在运行前往往需要你点一次"批准",而这个"等待中"的状态并不只存在内存里,而是直接写在 doc.yjs 文档的 pendingRequests 数组中,按线程隔离,状态机为:requested → claimed → completed / error / cancelled。
重开应用时,worker 从磁盘读回文档并重新扫描这条队列:被中断的请求继续推进,等待你批准的审批会原样出现,AI 的工作现场(包括 programs/ 里为等待用户操作保留的工具快照)也随之一并恢复。你看到的是"继续上次",而不是"从头开始"。
崩溃与损坏:磁盘是唯一真相源
Juggler 对"文件出了问题"做了防御,相关行为都有回归测试锁定:
session.json丢失或损坏:不会丢对话。加载时以磁盘上的对话文件夹为准,重建标签页顺序(见 session_recovery_test.go);- 新旧版本混用:清单里不认识的新字段会被原样保留,降级再升级也不会悄悄丢数据(见 session.go 的
UnmarshalJSON); - 多端同步:桌面应用和浏览器都是同一份文档的同步客户端,多个窗口可以共享同一个活动会话。
重开之后,你会看到什么
- ✅ 原来的标签页顺序、当前打开的对话、输入框的历史输入都回来了;
- ✅ 窗口大小位置、界面主题与缩放偏好也已恢复;
- ✅ 进行中的对话可继续发消息,等待审批的请求仍在队列里;
- ✅ 每一轮模型调用记录可点开复查:系统提示、工具定义、token 用量、耗时一目了然。
相关源码与文档
| 内容 | 路径 |
|---|---|
| 会话清单与项目状态目录说明 | docs/config-directory.md |
| 会话数据结构(Session 清单) | cmd/juggler/core/session.go |
| 对话目录布局(doc.yjs / txns / assets / programs) | cmd/juggler/core/convdir.go |
| 文档从磁盘加载与保存 | cmd/juggler/worker/persistence.go |
| 防抖自动保存(2 秒 / 10 秒) | cmd/juggler/worker/doc_saver.go |
| 待处理与待审批请求队列 | cmd/juggler/worker/pending_requests.go |
| 崩溃与损坏恢复回归测试 | cmd/juggler/core/session_recovery_test.go |
| 持久化集成测试 | tests/integration/worker_persistence_test.go |
| 原子写入实现 | internal/atomicio/write.go |
一句话总结:Juggler 把"会话"当作一份协作文档来管理——Yjs 文档 + 防抖落盘 + 原子写入 + 以磁盘为准的恢复策略,共同保证你可以随时"关掉、重开、接着干"。
