企业官网建设流程全解析

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

Warp（项目仓库）会在保存会话快照时记录终端当前工作目录（PWD），并在重启后恢复。本文以specs/andy/ad-hoc/session-restore-wsl-msys2-pwd/TECH.md技术规格为核心，结合crates/warp_terminal、app/src/pane_group、crates/warp_util中的真实源码，完整剖析 WSL 与 MSYS2/Git Bash 会话恢复时工作目录丢失问题的根因、修复方案与验证方法，帮助你理解 Warp 是如何在 Windows 宿主与 Unix 风格 shell 之间安全地传递启动目录的。

背景：会话快照如何记录 PWD

Warp 保存会话快照时，会通过TerminalView::active_session_path_if_local记录终端当前工作目录。该方法在 app/src/terminal/view.rs 中定义，调用链如下：

1. 先确认当前会话是本地会话（active_session_is_local）；
2. 从活动块的元数据中取出 shell 上报的原始 Unix 风格$PWD字符串；
3. 调用ShellLaunchData::maybe_convert_absolute_path对该字符串做"shell 感知"的路径转换。

maybe_convert_absolute_path定义于 crates/warp_terminal/src/shell/mod.rs 的ShellLaunchDataimpl 中，核心逻辑按 shell 类型分派：

pub fn maybe_convert_absolute_path(&self, path_str: &str) -> Option<PathBuf> { match self { ShellLaunchData::Executable { .. } => Some(PathBuf::from(path_str)), ShellLaunchData::WSL { distro } => { let unix_path = TypedPath::unix(path_str); convert_wsl_to_windows_host_path(&unix_path, distro).ok() } ShellLaunchData::MSYS2 { executable_path, .. } => { let unix_path = TypedPath::unix(path_str); convert_msys2_to_windows_native_path( &unix_path, &msys2_exe_to_root(WindowsPath::new( executable_path.as_os_str().as_encoded_bytes(), )), ) .ok() } // 容器内是纯 Unix 路径，无需转换 ShellLaunchData::DockerSandbox { .. } => Some(PathBuf::from(path_str)), } }

也就是说，在路径写入快照之前，它已经被转换为 Windows 原生路径：

• 对于 WSL：/home/user/projects→\\WSL$\<distro>\home\user\projects（Windows UNC 路径）；
• 对于 MSYS2/Git Bash：/c/Users/user/projects→C:\Users\user\projects（原生盘符路径）。

因此，最终写入TerminalSnapshot::cwd的永远是一个 Windows 原生路径，而不是 guest（子系统/仿真环境）内部的 Unix 风格路径。

为什么 SQLite 快照里存的是宿主原生路径

技术规格明确给出三个理由，说明快照中存储 Windows 原生路径而非 guest 原生路径是刻意设计：

1. CreateProcessW要求如此。创建进程时lpCurrentDirectory必须是 Windows 路径，存储宿主原生路径意味着恢复时无需再做任何转换。
2. is_dir()可原生工作。Windows 可以直接 stat\\WSL$\<distro>\...这类路径，恢复代码无需额外逻辑即可校验目录是否仍然存在。
3. 避免恢复时按 shell 类型分支。若存储 guest 原生路径、恢复时再重新转换，就需要再次从shell_launch_data中提取 distro 或 MSYS2 可执行文件——这正是原始 bug 的根源逻辑，等于把易错点搬回恢复路径。

从源码看，WSL 的转换依赖 distro 名（convert_wsl_to_windows_host_path(&unix_path, distro)），MSYS2 的转换依赖从可执行文件推导出的安装根目录（msys2_exe_to_root向上取三级父目录并校验目录名是git或msys64，见 crates/warp_util/src/path.rs）。这些"shell 感知"信息在快照时一次性消费，恢复时不应再触碰。

根因：恢复路径上的二次转换

会话恢复逻辑位于 app/src/pane_group/mod.rs 的restore_pane_leaf（该函数从restore_pane_tree逐叶递归调用，负责还原单个终端窗格）。问题出在这里：恢复代码对cwd再次执行了 Unix → Windows 转换，把已经是 Windows 路径的cwd又传回给：

• convert_wsl_to_windows_host_path
• convert_msys2_to_windows_native_path

而这两个函数都期望 Unix 风格输入。查看 crates/warp_util/src/path.rs 中的实现即可印证：

• convert_wsl_to_windows_host_path开头就检查!unix_path.is_unix()则返回Err(WSLPathConversionError::NonUnixPath)；
• convert_msys2_to_windows_native_path同样在非 Unix 输入时进入错误分支（仅对//wsl$/、//wsl.localhost/这类 MSYS2 内的 WSL 路径有特例处理）。

因此，给定 Windows 路径时二者都会失败并返回None，导致startup_directory对 WSL 和 MSYS2 会话始终为None，恢复出的终端只能在 shell 默认目录打开，而丢失了用户保存时所在的目录。

此外，旧版 WSL 分支中的TODO(CORE-3130)注释也指出：转换得到的路径在后续流程中被忽略——这本身就是"整个转换多余"的信号，佐证了修复方向。

修复方案：直接用PathBuf::from(cwd)

技术规格提出的修复简洁直接：删除shell_launch_data感知的路径转换块，改为直接构造PathBuf并做存在性校验：

let startup_directory = terminal_snapshot .cwd .map(PathBuf::from) .filter(|path| path.is_dir());

这一模式在仓库的恢复代码中已被采纳。在 app/src/pane_group/mod.rs 的restore_pane_leaf中，startup_directory正是这样计算并传给create_session的（随后create_session将其作为startup_directory参数传入LocalTtyTerminalManager::create_model，最终进入进程启动逻辑）。

为什么可以这样做？因为CreateProcessW的lpCurrentDirectory同时接受两种形式：

• \\WSL$\<distro>\...UNC 路径：wsl.exe启动时会将它们翻译回 Linux 路径；
• 原生C:\...盘符路径：MSYS2 的bash.exe启动时通过自身挂载表将其映射为对应的 MSYS2 路径（如/c/...）。

换句话说，快照里的 Windows 原生路径已经"两端兼容"：它既满足 Windows API 的要求，又会被各 shell 在启动时正确还原为 guest 内部的 Unix 路径，恢复代码无需再掺和任何转换。

随之而来的清理

修复同时简化了shell_launch_data派生变量：

• chosen_shell仅用于AvailableShells::get_from_shell_launch_data（在FeatureFlag::ShellSelector启用时解析用户选择的 shell），以简化形式保留；
• wsl_distro、msys2_executable这两个仅为路径转换而存在的局部变量被删除；
• 仅供旧转换逻辑使用的convert_msys2_to_windows_native_path、msys2_exe_to_root、WindowsPath等导入也随之移除。

注意：convert_wsl_to_windows_host_path的导入并非全部删除——它在 app/src/pane_group/mod.rs 的另一处（新会话启动路径计算，涉及active_session_wsl_distro与TypedPath::unix的场景）仍有用途，说明清理是"按需保留"，而非一刀切。

测试与验证清单

技术规格给出了四条行为验证路径，可用于回归确认修复效果：

• Behavior 2（WSL）：打开 WSL 终端，cd到非默认目录（例如~/projects），退出 Warp 并重新启动，确认恢复出的 WSL 标签页在~/projects打开。
• Behavior 3（MSYS2/Git Bash）：打开 Git Bash 终端，cd /c/Users/<user>/projects，退出并重启 Warp，确认恢复出的标签页在/c/Users/<user>/projects打开。
• Behavior 4（目录已删除）：重启前删除快照中保存的目录，确认终端仍能无错误打开，并回退到 shell 默认目录。这正是.filter(|path| path.is_dir())的兜底语义：目录不存在时不传启动目录覆盖。
• Behavior 5（不受影响的 shell）：确认 PowerShell、Cmd 以及原生 Unix shell 的会话恢复行为与修复前一致。

配套的 PRODUCT.md 从用户视角总结了同等行为：会话快照时持久化 PWD；WSL 恢复回原目录；MSYS2/Git Bash 恢复回原目录；目录缺失时回退默认；纯 Windows shell 与原生 Unix shell 不受影响。

结语：一次"删代码"式的正确修复

这个修复的本质是：在正确的时机（快照时）完成路径转换，并在错误的时机（恢复时）移除重复转换。它不引入任何新的路径解析逻辑，而是删除了一段被TODO(CORE-3130)标记为无效的代码，让"快照存宿主路径、恢复直接使用"的数据流保持单一职责。对读者而言，这也是一个观察 Warp 如何处理跨环境路径边界的良好样例：转换逻辑收敛在ShellLaunchData这一 shell 元数据载体上，其余环节只需信任已归一化的路径。

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