Juggler会话持久化与恢复:为什么关掉重开,AI的工作上下文和待审批请求都还在

原创2026-10-26 13:52:101,896 阅读

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/,与项目会话数据分开。

Juggler会话持久化示例:会话图片附件以内容寻址方式存于磁盘的assets目录

上图是仓库测试数据中的一张示例图片(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 文档 + 防抖落盘 + 原子写入 + 以磁盘为准的恢复策略,共同保证你可以随时"关掉、重开、接着干"。

登录后查看全文
juggler