尧图网站建设 
Cate会话持久化机制深度剖析AI Agent终端会话跨重启存活的完整实现【免费下载链接】cateAn infinite zoomable canvas for coding. Editor, terminal, and browser panels in a spatial workspace.项目地址: https://gitcode.com/gh_mirrors/cate5/cateCate 是一款“无限缩放画布”式编码工具把编辑器、终端和浏览器面板装进同一个空间工作台。它的会话持久化机制是 Cate 最有价值的特性之一无论是手动拖动画布、切换工作区还是直接重启甚至崩溃退出Cate 都会把终端会话、AI Agent 会话的现场完整保存下来重启后跨重启存活——滚动输出、当前工作目录、面板位置全部原样恢复。本文将完整剖析这套 Cate 会话自动保存与恢复机制的实现细节。 核心设计把会话文件写进项目.cate 目录Cate 会话持久化的第一个设计决策会话数据跟着项目走而不是跟着应用走。每次保存时Cate 会把工作区状态序列化写入仓库根目录下的.cate/文件夹包含两个文件.cate/workspace.json—— 面板清单、画布几何节点位置/缩放/视口、面板关系.cate/session.json—— 停靠布局dock 分区、分离窗口、终端滚动回存索引序列化与落盘逻辑集中在 sessionSave.ts 与 sessionSerialize.ts统一入口在 session.ts 这个 barrel 文件中重新导出。 好处会话文件可以提交到仓库、克隆后开箱即用远程项目cate-runtime://的.cate/则写在远端仓库旁重连后恢复方式与本地完全一致见 sessionSave.ts#L232-L247。⏱️ Cate 会话自动保存策略500ms / 4s / 30s 三重保险自动保存在 sessionAutosave.ts 中实现采用经典的“三重保险”策略保证持续操作下也不会丢状态触发器间隔作用空闲防抖IDLE_DELAY500ms最后一次修改后 0.5 秒即落盘最长等待MAX_WAIT4s持续拖拽/输入时保底刷盘周期强制保存PERIODIC_INTERVAL30s无条件保存防崩溃/强杀/更新重启IDLE_DELAY 500 / MAX_WAIT 4000 / PERIODIC_INTERVAL 30_000见 sessionAutosave.ts#L27-L29。两个精巧的工程细节按项目去重每次序列化后的 payload 与上次对比lastSerializedByRoot内容没变就跳过 IPC 写盘周期保存不会反复写同一份文件恢复期静默Quiescence重建布局期间短暂“半成品”状态被beginRestoreQuiescence()屏蔽绝不把半成品的布局写到磁盘——这是防止数据损坏的关键闸门。此外主进程退出/窗口关闭时会通过onSessionFlushSaveIPC 主动请求渲染进程立即刷盘渲染进程写完后以sessionFlushSaveDone回执确认确保“优雅退出零丢失”。 保存了什么从画布几何到终端工作目录persistSession()sessionSave.ts#L58-L190对每个可持久化工作区采集五类现场停靠布局dock zones左右中下的分区与尺寸画布几何每个画布面板的canvasNodeszoomLevelviewportOffset面板记录以“恢复稳定”的 panel id 为键保证重启后 id 一致、引用可解析终端工作目录对每个存活 PTY 批量调用terminalGetCwd存入terminalCwds——重启后终端原地在原目录重生sessionSave.ts#L133-L153终端滚动回存见下节。️ 终端会话跨重启存活的关键实现滚动回存序列化这是“AI Agent 终端会话跨重启存活”最核心的部分分三步第 1 步序列化整个终端缓冲区。captureAndSaveScrollback.ts#L16-L23 调用serializeTerminalState借助 xterm.js 的 SerializeAddon 把文本 颜色样式 换行折叠一起序列化成字符串——不只是文字恢复后终端“看起来”也一模一样。第 2 步以 panel id 为键落盘。主进程将内容写入日志目录下的${panelId}.scrollback文件terminal.ts#L660-L669。文件名来自“恢复稳定”的 panel id而不是随机变化的 PTY id这是重启后能重新找到它的前提。第 3 步重启后回放。新 shell 启动完成后replayTerminalLog 把序列化字符串逐字节写回新的 xterm然后打印一行灰色分隔线--- restored session ---分隔线下方的就是全新 shell 的提示符。你重启 Cate 打开终端看到的就是“重启前的一切 一条分隔线 新提示符”。 重启恢复全流程从快照到活终端启动时 sessionStartup.ts 的restoreMultiWorkspaceSession按快照重建每个工作区统一走 restoreSession 这条路径重建面板记录按原 id 写回 store画布节点、停靠分区全部对号入座预置终端恢复参数对每个 terminal 面板调用terminalRegistry.setPendingRestore(panelId, cwd)——“待恢复”状态挂起等 PTY 真正创建时消费sessionRestore.ts#L320-L325懒加载恢复Deferred Restore启动时从未激活过的工作区只保留快照、不实际重建等你第一次切到它时才真正恢复启动速度不受项目数量拖累分离窗口重建独立窗口里的面板同样按快照重新弹出。运行中还有两条“恢复”支线重开已关闭的工作区hydrateWorkspaceFromDiskIfEmpty只在“有 rootPath 无活动面板”时从.cate/补水幂等且安全sessionRestore.ts#L155-L208外部编辑守卫手动改了.cate/workspace.json后reloadActiveWorkspaceFromDisk会读盘并整体重建布局期间自动保存被静默避免把你的修改覆盖回去。所有恢复路径都受项目信任门isProjectTrusted保护未信任的文件夹不会读取其中的会话文件克隆陌生仓库不会被悄悄“注入布局”。 关键源码地图快速定位 Cate 会话持久化实现环节文件说明公共入口session.ts序列化/保存/加载/恢复的 barrel 导出快照采集sessionSave.ts采集全部工作区现场并写.cate/自动保存调度sessionAutosave.ts防抖 保底 周期保存布局恢复sessionRestore.ts快照重建、终端日志回放启动恢复sessionStartup.ts多工作区 分离窗口启动恢复滚动回存captureAndSaveScrollback.ts终端缓冲区序列化与落盘PTY 会话层terminal.ts终端日志读写、跨窗口迁移✅ 小结Cate 会话持久化的精髓可以归纳为三句话会话随项目走.cate/两个 JSON 文件让布局、终端、画布状态可提交、可迁移、可远程同步保存永不缺席500ms 防抖 4s 保底 30s 强刷 退出回执四种机制叠加把数据丢失窗口压到最小恢复看得见xterm 级序列化让终端连颜色和换行都能原样回放--- restored session ---一行让你一眼确认“会话活过来了”。对于常年在 Cate 里跑 AI Agent 长任务的开发者来说这意味着合上电脑、重启应用Agent 的现场原封不动地等在原地。这就是 Cate 把“空间化工作台”做得真正可托付的底层原因。【免费下载链接】cateAn infinite zoomable canvas for coding. Editor, terminal, and browser panels in a spatial workspace.项目地址: https://gitcode.com/gh_mirrors/cate5/cate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cate会话持久化机制深度剖析：AI Agent终端会话跨重启存活的完整实现
Cate会话持久化机制深度剖析AI Agent终端会话跨重启存活的完整实现【免费下载链接】cateAn infinite zoomable canvas for coding. Editor, terminal, and browser panels in a spatial workspace.项目地址: https://gitcode.com/gh_mirrors/cate5/cateCate 是一款“无限缩放画布”式编码工具把编辑器、终端和浏览器面板装进同一个空间工作台。它的会话持久化机制是 Cate 最有价值的特性之一无论是手动拖动画布、切换工作区还是直接重启甚至崩溃退出Cate 都会把终端会话、AI Agent 会话的现场完整保存下来重启后跨重启存活——滚动输出、当前工作目录、面板位置全部原样恢复。本文将完整剖析这套 Cate 会话自动保存与恢复机制的实现细节。 核心设计把会话文件写进项目.cate 目录Cate 会话持久化的第一个设计决策会话数据跟着项目走而不是跟着应用走。每次保存时Cate 会把工作区状态序列化写入仓库根目录下的.cate/文件夹包含两个文件.cate/workspace.json—— 面板清单、画布几何节点位置/缩放/视口、面板关系.cate/session.json—— 停靠布局dock 分区、分离窗口、终端滚动回存索引序列化与落盘逻辑集中在 sessionSave.ts 与 sessionSerialize.ts统一入口在 session.ts 这个 barrel 文件中重新导出。 好处会话文件可以提交到仓库、克隆后开箱即用远程项目cate-runtime://的.cate/则写在远端仓库旁重连后恢复方式与本地完全一致见 sessionSave.ts#L232-L247。⏱️ Cate 会话自动保存策略500ms / 4s / 30s 三重保险自动保存在 sessionAutosave.ts 中实现采用经典的“三重保险”策略保证持续操作下也不会丢状态触发器间隔作用空闲防抖IDLE_DELAY500ms最后一次修改后 0.5 秒即落盘最长等待MAX_WAIT4s持续拖拽/输入时保底刷盘周期强制保存PERIODIC_INTERVAL30s无条件保存防崩溃/强杀/更新重启IDLE_DELAY 500 / MAX_WAIT 4000 / PERIODIC_INTERVAL 30_000见 sessionAutosave.ts#L27-L29。两个精巧的工程细节按项目去重每次序列化后的 payload 与上次对比lastSerializedByRoot内容没变就跳过 IPC 写盘周期保存不会反复写同一份文件恢复期静默Quiescence重建布局期间短暂“半成品”状态被beginRestoreQuiescence()屏蔽绝不把半成品的布局写到磁盘——这是防止数据损坏的关键闸门。此外主进程退出/窗口关闭时会通过onSessionFlushSaveIPC 主动请求渲染进程立即刷盘渲染进程写完后以sessionFlushSaveDone回执确认确保“优雅退出零丢失”。 保存了什么从画布几何到终端工作目录persistSession()sessionSave.ts#L58-L190对每个可持久化工作区采集五类现场停靠布局dock zones左右中下的分区与尺寸画布几何每个画布面板的canvasNodeszoomLevelviewportOffset面板记录以“恢复稳定”的 panel id 为键保证重启后 id 一致、引用可解析终端工作目录对每个存活 PTY 批量调用terminalGetCwd存入terminalCwds——重启后终端原地在原目录重生sessionSave.ts#L133-L153终端滚动回存见下节。️ 终端会话跨重启存活的关键实现滚动回存序列化这是“AI Agent 终端会话跨重启存活”最核心的部分分三步第 1 步序列化整个终端缓冲区。captureAndSaveScrollback.ts#L16-L23 调用serializeTerminalState借助 xterm.js 的 SerializeAddon 把文本 颜色样式 换行折叠一起序列化成字符串——不只是文字恢复后终端“看起来”也一模一样。第 2 步以 panel id 为键落盘。主进程将内容写入日志目录下的${panelId}.scrollback文件terminal.ts#L660-L669。文件名来自“恢复稳定”的 panel id而不是随机变化的 PTY id这是重启后能重新找到它的前提。第 3 步重启后回放。新 shell 启动完成后replayTerminalLog 把序列化字符串逐字节写回新的 xterm然后打印一行灰色分隔线--- restored session ---分隔线下方的就是全新 shell 的提示符。你重启 Cate 打开终端看到的就是“重启前的一切 一条分隔线 新提示符”。 重启恢复全流程从快照到活终端启动时 sessionStartup.ts 的restoreMultiWorkspaceSession按快照重建每个工作区统一走 restoreSession 这条路径重建面板记录按原 id 写回 store画布节点、停靠分区全部对号入座预置终端恢复参数对每个 terminal 面板调用terminalRegistry.setPendingRestore(panelId, cwd)——“待恢复”状态挂起等 PTY 真正创建时消费sessionRestore.ts#L320-L325懒加载恢复Deferred Restore启动时从未激活过的工作区只保留快照、不实际重建等你第一次切到它时才真正恢复启动速度不受项目数量拖累分离窗口重建独立窗口里的面板同样按快照重新弹出。运行中还有两条“恢复”支线重开已关闭的工作区hydrateWorkspaceFromDiskIfEmpty只在“有 rootPath 无活动面板”时从.cate/补水幂等且安全sessionRestore.ts#L155-L208外部编辑守卫手动改了.cate/workspace.json后reloadActiveWorkspaceFromDisk会读盘并整体重建布局期间自动保存被静默避免把你的修改覆盖回去。所有恢复路径都受项目信任门isProjectTrusted保护未信任的文件夹不会读取其中的会话文件克隆陌生仓库不会被悄悄“注入布局”。 关键源码地图快速定位 Cate 会话持久化实现环节文件说明公共入口session.ts序列化/保存/加载/恢复的 barrel 导出快照采集sessionSave.ts采集全部工作区现场并写.cate/自动保存调度sessionAutosave.ts防抖 保底 周期保存布局恢复sessionRestore.ts快照重建、终端日志回放启动恢复sessionStartup.ts多工作区 分离窗口启动恢复滚动回存captureAndSaveScrollback.ts终端缓冲区序列化与落盘PTY 会话层terminal.ts终端日志读写、跨窗口迁移✅ 小结Cate 会话持久化的精髓可以归纳为三句话会话随项目走.cate/两个 JSON 文件让布局、终端、画布状态可提交、可迁移、可远程同步保存永不缺席500ms 防抖 4s 保底 30s 强刷 退出回执四种机制叠加把数据丢失窗口压到最小恢复看得见xterm 级序列化让终端连颜色和换行都能原样回放--- restored session ---一行让你一眼确认“会话活过来了”。对于常年在 Cate 里跑 AI Agent 长任务的开发者来说这意味着合上电脑、重启应用Agent 的现场原封不动地等在原地。这就是 Cate 把“空间化工作台”做得真正可托付的底层原因。【免费下载链接】cateAn infinite zoomable canvas for coding. Editor, terminal, and browser panels in a spatial workspace.项目地址: https://gitcode.com/gh_mirrors/cate5/cate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考