Warp 会话恢复增强：代码编辑器面板与 Markdown 编辑器的跨重启还原实现

• 桌面应用
• 开发者工具
• 人工智能
• AI 应用
• AI Agent
• 代码智能体

在 Warp 中，终端标签页、AI 对话与 Notebook 等面板在应用退出并重新启动后都能自动恢复，唯独内置代码编辑器打开的文件标签页会被静默丢弃，Markdown 文件面板虽能恢复却存在显示模式丢失的体验缺口。本文基于开源仓库中的产品规格 specs/GH371/product.md 及其对应源码实现，系统讲解 Warp 如何将"打开的代码文件"与"Markdown 编辑器"纳入会话恢复体系，覆盖快照持久化、多标签还原、显示模式保留、缺失文件容错与源码语义保留等完整机制。读完本文，你将掌握 Warp 面板恢复体系的数据模型、SQLite 存储结构以及代码面板快照→还原的完整调用链。

背景：为什么代码面板会被静默丢弃

Warp 的会话恢复机制已经覆盖了终端会话、AI 对话、Notebook、环境变量集合、工作流等多种面板类型。但根据 specs/GH371/product.md 的描述，存在一个明显的体验断层：

代码编辑器面板（内置编辑器中打开的文件）和 Markdown 查看器/编辑器面板应在重启后恢复到之前的状态，就像终端标签页、AI 对话、Notebook 等其他面板类型已经做到的那样。

实际现状是：代码编辑器面板的状态虽然已经持久化到 SQLite 数据库，但在会话恢复阶段被跳过（skipped during restoration）。用户退出应用时打开的所有编辑器标签页会在重启后全部消失，而终端会话等其他面板却总能可靠恢复，这种反差让用户不得不手动重新打开文件，丢失全部工作上下文。

Markdown 文件面板的情况稍好——它们已经能通过NotebookPaneSnapshot::LocalFileNotebook路径成功恢复，但整体上基于文件的面板恢复体验仍不完整。

目标与范围界定

规格文档 specs/GH371/product.md 明确定义了本次改进的目标，共五项：

1. 重启后恢复代码编辑器面板：退出时打开的每个代码面板，应恢复到面板树中相同的位置，并保持相同的文件处于打开状态。
2. 恢复代码面板内的全部标签页：一个代码面板可以包含多个文件标签，所有打开的标签（以及活动标签索引）都应被恢复，而不仅仅是单个活动文件。
3. 保留 Markdown 查看器显示模式：当 Markdown 文件在FileNotebookView（渲染模式）中打开时，重启后应恢复到正确的显示模式（渲染 vs. 原始文本）。
4. 优雅处理文件缺失：如果恢复时持久化的文件路径在磁盘上已不存在，面板仍应被恢复（例如显示错误状态或空编辑器），而不是导致整个标签/面板树恢复失败。
5. 保留代码面板的源码语义：恢复基于文件的代码面板时，尽可能保留足够的来源信息以维持该面板的去重行为（例如将文件树面板恢复为CodeSource::FileTree，而不是全部坍缩成CodeSource::Link）。

同时，规格也划定了明确的非目标（Non-goals），防止范围蔓延：

• 不恢复未保存的编辑内容 / 脏缓冲区内容——只恢复文件路径和标签结构，编辑器重新从磁盘加载内容。
• 不恢复滚动位置或光标位置。
• 不恢复代码 diff 面板（CodeDiff与瞬态的 AI 动作绑定，跨会话恢复无意义）。
• 不恢复代码审查面板（已有独立的恢复路径）。
• 不恢复远程文件——只恢复本地可访问的文件，远程/SSH 路径会被跳过。

数据模型：快照如何捕获面板状态

代码面板的恢复能力建立在快照（snapshot）数据模型之上。相关定义位于 app/src/app_state.rs：

#[derive(Clone, Debug, PartialEq)] pub struct CodePaneTabSnapshot { pub path: Option<PathBuf>, } #[derive(Clone, Debug, PartialEq)] pub enum CodePaneSnapShot { Local { tabs: Vec<CodePaneTabSnapshot>, active_tab_index: usize, /// The full `CodeSource` for this pane, serialized as JSON in the DB. source: Option<CodeSource>, }, }

要点解析：

• CodePaneTabSnapshot仅保存path: Option<PathBuf>——这正是"只恢复路径结构、不恢复缓冲区内容"设计意图的体现。
• tabs以标签顺序保存所有打开的文件路径，支持多标签面板的完整还原。
• active_tab_index记录哪个标签是活动的，恢复后用于聚焦。
• source是完整的CodeSource枚举，作为 JSON 序列化存入数据库，用于保留面板来源语义。

CodePaneSnapShot::Local作为LeafContents的一个变体挂接到面板树的统一快照体系（见 app/src/app_state.rs 中的enum LeafContents），这意味着代码面板与其他所有面板类型共享同一套持久化与恢复框架。

快照的生成时机

快照由CodePane的snapshot()方法生成，实现在 app/src/pane_group/pane/code_pane.rs：

fn snapshot(&self, app: &AppContext) -> LeafContents { let code_view_ref = self.file_view(app).as_ref(app); let tabs: Vec<CodePaneTabSnapshot> = (0..code_view_ref.tab_count()) .filter_map(|i| code_view_ref.tab_at(i)) .map(|tab| CodePaneTabSnapshot { path: tab.local_path(), }) .collect(); let active_tab_index = code_view_ref.active_tab_index(); let source = code_view_ref.source().clone(); LeafContents::Code(CodePaneSnapShot::Local { tabs, active_tab_index, source: Some(source), }) }

这段代码清晰地展示了快照的三个关键来源：tab_count()遍历所有标签、tab.local_path()提取路径、active_tab_index()记录活动标签，最后连同source一起打包成LeafContents::Code。这也是文档中"保存打开文件路径列表（按标签顺序）、哪个标签是活动的、是否预览标签"三项状态的实现基础。

持久化：SQLite 中的存储结构

数据库表设计

代码面板的持久化由两代数据库迁移支撑，均位于 crates/persistence/migrations：

第一代（2024-05-21）：code_panes表最初只有id、kind、local_path三列，仅支持单个文件：

CREATE TABLE code_panes ( id INTEGER PRIMARY KEY NOT NULL, kind TEXT NOT NULL DEFAULT 'code' CHECK (kind = 'code'), local_path BLOB, FOREIGN KEY (id, kind) REFERENCES pane_leaves (pane_node_id, kind) );

第二代（2026-04-14）：迁移 2026-04-14-150000_add_code_pane_tabs/up.sql 重构了表结构，以支持多标签与来源语义：

CREATE TABLE code_panes_new ( id INTEGER PRIMARY KEY NOT NULL, active_tab_index INTEGER NOT NULL DEFAULT 0, source_data TEXT ); CREATE TABLE code_pane_tabs ( id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, code_pane_id INTEGER NOT NULL, tab_index INTEGER NOT NULL, local_path BLOB, FOREIGN KEY (code_pane_id) REFERENCES code_panes_new (id) ON DELETE CASCADE, UNIQUE (code_pane_id, tab_index) );

这次迁移做了三件事：为code_panes重建了显式主键（原表没有显式PRIMARY KEY，导致 SQLite 外键无法引用它）；新增active_tab_index与source_data列；将标签拆分到独立的code_pane_tabs表，并以UNIQUE (code_pane_id, tab_index)约束保证标签顺序。迁移还通过INSERT ... SELECT将旧local_path回填为tab_index = 0的单个标签，保证老数据平滑升级。

保存路径

持久化写入实现在 app/src/persistence/sqlite.rs 的save_app_state与save_pane_state函数中：

• save_app_state在单个事务内先删除旧状态（包括code_panes表），再写入新状态，确保数据库永远不会处于部分状态。
• save_pane_state中，代码面板分支把active_tab_index转成i32写入，source通过serde_json::to_string序列化后存入source_data：

LeafContents::Code(code_snapshot) => { let CodePaneSnapShot::Local { tabs, active_tab_index, source, } = code_snapshot; let serialized_source = source.as_ref().and_then(|s| serde_json::to_string(s).ok()); let code = model::NewCodePane { id, active_tab_index: *active_tab_index as i32, source_data: serialized_source, }; diesel::insert_into(schema::code_panes::dsl::code_panes) .values(code) .execute(conn)?; // Write ordered tab rows. for (tab_idx, tab) in tabs.iter().enumerate() { let tab_row = model::NewCodePaneTab { code_pane_id: id, tab_index: tab_idx as i32, local_path: tab.path.clone().map(encode_path), }; diesel::insert_into(schema::code_pane_tabs::dsl::code_pane_tabs) .values(tab_row) .execute(conn)?; } }

注意local_path使用encode_path编码后以BLOB形式存储，与表定义中的BLOB列类型一致。

读取路径

恢复读取同样位于 app/src/persistence/sqlite.rs。对于CODE_PANE_KIND叶子节点，先读取code_panes主记录，再按tab_index排序读取子表code_pane_tabs，反编码路径并反序列化CodeSource：

let tab_rows: Vec<model::CodePaneTab> = schema::code_pane_tabs::dsl::code_pane_tabs // ...filter by code_pane_id, ordered by tab_index .load(conn)?; let tabs: Vec<CodePaneTabSnapshot> = tab_rows .into_iter() .map(|row| CodePaneTabSnapshot { path: row.local_path.map(decode_path), }) .collect(); let active_tab_index = code_pane.active_tab_index as usize; let source = code_pane .source_data .as_deref() .and_then(|data| serde_json::from_str::<CodeSource>(data).ok()); LeafContents::Code(CodePaneSnapShot::Local { tabs, active_tab_index, source, })

至此，"快照 → SQLite → 快照"的完整往返（round trip）链路打通，这正是规格 Validation 一节要求单元/集成测试覆盖的核心路径。

还原：从快照到面板树

面板树重建发生在 app/src/pane_group/mod.rs 中。对LeafContents::Code的处理是整个机制的关键，它体现了规格中的多项容错设计：

#[cfg(feature = "local_fs")] LeafContents::Code(snapshot) => { let CodePaneSnapShot::Local { tabs, active_tab_index, source, } = snapshot; let Some(source) = source.filter(|s: &CodeSource| s.is_restorable()) else { return Err(anyhow::anyhow!( "Skipping code pane with non-restorable source" )); }; let code_view = ctx.add_typed_action_view(move |ctx| { // ...create CodeView from source }); // ... Ok((PaneData::new(pane_id), focus)) }

值得注意的细节：

• 该还原路径受local_fsfeature 门控，非本地文件系统平台会返回 "Code pane restoration not supported on this platform" 错误。
• is_restorable()过滤：不可恢复的来源会被跳过（返回错误），但根据成功标准，单个面板恢复失败不会破坏整个面板树，其他面板继续恢复。
• 恢复后的面板会按leaf.is_focused决定是否设为焦点面板。

哪些来源可恢复

is_restorable()定义在 app/src/code/editor_management.rs：

/// Returns `true` if this source should be restored across app restarts. /// /// `AIAction` is ephemeral (tied to a live conversation) and should not /// be restored. pub fn is_restorable(&self) -> bool { !matches!( self, Self::AIAction { .. } | Self::FileTree { location: LocalOrRemotePath::Remote(_), // ... remote CommandPalette etc. } // ... ) }

这与规格的语义完全对应：

• CodeSource::AIAction与存活的 AI 对话绑定，属于瞬态来源，不恢复——这与"不恢复代码 diff 面板"的非目标一脉相承。
• CodeSource::FileTree等来源如果指向远程路径（LocalOrRemotePath::Remote），同样不恢复——这正是"只恢复本地可访问文件，跳过远程/SSH 路径"的实现。
• 本地FileTree、Link、CommandPalette、Finder、ProjectRules等来源均可恢复。

源码语义与去重行为

CodeSource枚举（app/src/code/editor_management.rs）完整刻画了代码面板的各种来源：

pub enum CodeSource { /// A new code pane not attached to an existing file. New { default_directory: Option<PathBuf> }, /// Opened from file links. Link { path: PathBuf, range_start: Option<LineAndColumnArg>, range_end: Option<LineAndColumnArg> }, /// Opened from an active AI agent conversation. AIAction { id: AIAgentActionId }, /// Opened from project rules (WARP.md) file. ProjectRules { location: LocalOrRemotePath }, /// Opened from file tree (local or remote). FileTree { location: LocalOrRemotePath }, /// Opened from command palette file search (local or remote). CommandPalette { location: LocalOrRemotePath }, /// Opened from macOS Finder via "Open With". Finder { path: PathBuf }, /// Opened from a skill. Skill { /* ... */ }, }

规格目标 5 明确要求：恢复文件树面板时保留CodeSource::FileTree语义，而不是坍缩为CodeSource::Link。原因在于用户体验第 6 条的期望：

如果恢复的面板最初来自文件树，那么从文件树重新打开同一文件时，应聚焦到已恢复的面板而不是创建重复面板。

即CodeManager在同一个面板组内负责去重（deduplication），而去重行为依赖CodeSource的身份信息。快照中把source以 JSON 形式完整持久化、恢复时原样反序列化，正是为了让去重逻辑跨重启依然成立。用户在面板组内打开同一文件于两个不同代码面板时，两个面板也互不干扰、各自独立恢复。

Markdown 文件面板：显示模式的保留

基础恢复已存在

规格明确指出，Markdown 文件的基础恢复已经工作，无需改动：FileNotebookView（渲染模式 Markdown 查看器）通过NotebookPaneSnapshot::LocalFileNotebook路径持久化与恢复，相关逻辑在 app/src/notebooks/file/mod.rs 中。恢复路径的写入分支也出现在 app/src/persistence/sqlite.rs 的save_pane_state中。

显示模式状态

FileNotebookView维护了一个显示模式枚举（app/src/notebooks/file/mod.rs）：

/// Display mode for markdown files shown via the header segmented control. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum MarkdownDisplayMode { Rendered, Raw, }

规格要求：Markdown 显示模式（渲染 vs. 原始）应被保留——如果退出时处于 "raw"（代码编辑器）模式，重启后应回到 raw 模式，反之亦然。

源码中还揭示了一个关键细节：FileNotebookView带有一个code_source: Option<CodeSource>字段，注释说明：

Set when the file was opened from a CodePane, and restored on a raw/rendered toggle.

也就是说，当 Markdown 文件从代码面板打开时，FileNotebookView会记住它的CodeSource，并在 raw/rendered 模式切换时恢复。这解释了为何 Markdown 文件面板能与代码面板体系共享来源语义——两种视图之间的模式切换不会丢失面板的身份来源。

边界情况与容错行为

规格文档 specs/GH371/product.md 专门列出了三类边界情况，并明确了各自的处理策略：

此外还有两个核心容错场景：

• 文件已不存在：退出与重启之间文件被删除时，对应标签仍会被创建，但编辑器显示标准的 file-not-found / 错误状态；同一面板内其他有效标签不受影响。
• 面板内无有效文件：代码面板原本打开的文件无法定位时，面板以空/错误状态恢复，而不是被整体丢弃。

这两条容错逻辑的支撑点在于：快照只持久化路径（Option<PathBuf>），恢复时编辑器对不存在的路径自然进入错误状态；同时source.filter(is_restorable)的单面板失败被隔离，不会拖垮整个面板树的恢复（见成功标准第 5 条："单个无效文件路径不会阻止其他面板恢复"）。

成功标准与验证方案

成功标准

1. 退出时打开一个或多个代码面板，重启后所有代码面板恢复到面板树中的正确位置（正确的窗口、正确的标签页、正确的分屏位置）。
2. 单个代码面板内的多个文件标签全部恢复，顺序正确，活动标签正确。
3. Markdown 文件面板（FileNotebookView）继续正确恢复（已可用，不得回归）。
4. 持久化文件路径在磁盘上不存在时，代码面板仍被恢复（显示错误/空状态），而非被静默丢弃。
5. 代码面板恢复失败不会破坏面板树结构——单个无效文件路径不会阻止其他面板恢复。

验证方案（来自规格 Validation 一节）

规格给出了完整的验证矩阵，可直接作为回归测试清单：

1. 单代码面板、单文件：在代码编辑器中打开一个文件，退出 Warp，重启，验证文件在同一标签/面板位置重新打开。
2. 多标签代码面板：在同一个代码面板中打开 3 个文件（作为标签），将第 2 个标签设为活动，退出，重启，验证 3 个标签全部恢复且第 2 个标签处于活动状态。
3. 代码 + 终端分屏：水平分屏，左侧终端、右侧代码编辑器，退出，重启，验证两个面板在正确的分屏位置恢复。
4. 已删除文件：打开一个文件，退出，从磁盘删除该文件，重启，验证代码面板仍然出现（对缺失文件显示错误状态）且恢复不崩溃。
5. Markdown 查看器：在渲染模式的 Markdown 查看器中打开文件，退出，重启，验证文件以相同的显示模式显示。
6. 单元/集成测试：CodePaneSnapShot的快照→恢复往返应被测试覆盖——序列化一个代码面板快照，并验证恢复时会创建代码面板。

其中第 6 条对应的测试路径已具备现实支撑：快照的保存与读取均实现于 app/src/persistence/sqlite.rs，围绕save_app_state/load_app_state的往返逻辑在 app/src/persistence/sqlite_tests.rs 中有对应测试基础；代码面板的snapshot()实现见 app/src/pane_group/pane/code_pane.rs，面板树还原逻辑见 app/src/pane_group/mod.rs。

遗留开放问题

规格最后保留了一个开放问题（Open Questions），等待产品决策：

预览标签是否应被恢复？预览标签（文件树单击产生的标签）本质上是瞬态的。本规格建议将它们作为预览标签恢复以保留用户上下文，但另一种方案是丢弃仅含预览标签的标签，以保持会话整洁。

这个决策会影响CodePaneTabSnapshot是否需要补充"是否预览标签"字段，以及恢复阶段对预览标签的处理策略。从当前数据模型看，CodePaneTabSnapshot只含path，尚未记录预览状态，说明该决策尚未落定——这也解释了规格中"是否预览标签"被列为待定项的现状。

小结

本次会话恢复增强围绕"文件类面板"补齐了 Warp 恢复体系的关键缺口：

• 代码面板：从"已持久化但被跳过"变为完整恢复，通过CodePaneSnapShot::Local { tabs, active_tab_index, source }快照结构，实现多标签、活动标签与来源语义的跨重启还原。
• 存储层：code_panes+code_pane_tabs两级表结构（迁移见 crates/persistence/migrations/2026-04-14-150000_add_code_pane_tabs/up.sql），以事务方式在 SQLite 中保存标签顺序与 JSON 序列化的CodeSource。
• 容错：缺失文件、不可读文件、二进制文件分别落入既有的标准错误处理路径，单面板失败不影响面板树整体恢复。
• Markdown 面板：基础恢复保持稳定，显示模式（MarkdownDisplayMode::Rendered | Raw）成为新增的保留维度。

理解这套机制的最佳路径是沿着"快照生成（code_pane.rs）→ 持久化（sqlite.rs）→ 面板树还原（pane_group/mod.rs）→ 来源语义（editor_management.rs）"的调用链通读源码，再结合规格中的五项手动测试用例进行验证。

• 桌面应用
• 开发者工具
• 人工智能
• AI 应用
• AI Agent
• 代码智能体