把文件拷到 U 盘——整条链路最脆的一环

便携版（portable）看起来是最简单的交付形式：解压 zip 到 U 盘，双击启动，无需安装、无注册表污染。现实中这个形式却是整个交付链路里最脆弱的一环。四个潜伏的难点会在不同场景下反复触发，造成的故障难以排查、易于遗漏。这一栏专门记录便携版交付在设计与运维中踩过的坑。

难点 1：完整性 —— 几百个文件，缺一不可

便携版的 zip 解压后包含的文件数量出人意料地多。以 Windows 为例，一个完整的便携目录结构大约是这样：

portable/
├── WakouPanel.exe                    (~30 MB)
├── launcher.exe                      (~7 MB)
├── runtime/
│   ├── python/                       (~25 MB)
│   ├── nodejs/                       (~40 MB)
│   └── webview2/                     (bootstrapper)
├── engines/
│   ├── openclaw/                     (~150 MB，含 npm node_modules)
│   └── hermes/                       (~250 MB，含 Python site-packages)
├── data/                             (用户数据)
└── ...

python 目录里是 embeddable Python，完整的 Lib 结构；nodejs 目录含 node.exe 和整个 node_modules/npm；openclaw 是 npm 本地安装的结果，带上百个 transitive 依赖包；hermes 是 Python 环装后的 site-packages，几千个 Python 文件。任何一个文件损坏或缺失，应用启动时都可能失败——但错误信息通常指向别处。

启动时最先执行的是一个检查阶段，逐项验证关键文件完整性：

launcher.exe 启动
  ├─ 检查 runtime/python/python.exe 存在且可执行
  ├─ 检查 runtime/nodejs/node.exe 存在且可执行
  ├─ 检查 engines/openclaw/ 目录结构
  ├─ 检查 engines/hermes/ 目录结构
  └─ 任一失败 → 显示"U 盘损坏，请联系运营"并退出

但这只是皮毛检查。真正的依赖关系隐藏在运行时：OpenClaw 启动时需要一个特定版本的 npm package，Hermes 需要 Python 3.11 及特定的 pip 包。这些 transitive 依赖包本身又依赖其他包。一个文件被病毒软件误删、或从网络同步源拉取出错、或用户错误覆盖，都可能导致启动时的链路中断。而错误日志往往是这样的：

[ERROR] Cannot find module 'xxxx'

指向的是深层依赖包，用户根本不知道这个包应该来自 U 盘的哪个位置。或者更糟的情况，应用在读取某个配置文件时卡死，日志文件根本没有被写入（因为日志初始化本身依赖这些文件）。

这就是我后来在架构中加入"启动期环境扫描"的原因：不只检查文件存在，还要检查版本兼容、引入时序、必要的环保变量设置。但即使这样，Z 盘上某个角落的小文件丢失，依然会造成诡异的故障。

难点 2：双位置状态 —— 哪个才是真相

便携版为了加速和降低 USB I/O 压力，启动时采用了这样的策略：

程序启动后，把 U 盘内容 robocopy（增量复制）到本地磁盘一个临时目录（%LOCALAPPDATA%\Microsoft\WakouAI\Runtime\<缓存ID>\）
所有后续运行都在本地缓存目录进行，直接读写本地 SSD
后台守护进程（guardian）每 60 秒把本地缓存的数据同步回 U 盘

这样做的好处是显而易见的：本地 SSD 读写速度是 USB 的 10 倍以上，用户体验流畅。但代价是引入了两份状态，同步的方向和时机就成了生死攸关的问题。

最危险的场景是这样的：

T0: 用户启动应用 → 本地 cache 已准备好
T1: 用户在应用里操作 → 数据写入本地 cache
T60: guardian 开始同步 → 本地 cache 文件 → U 盘
T55-T60 之间: 用户突然拔 U 盘
→ 同步中断，本地 cache 中的数据丢失
→ 用户下次在别的电脑插 U 盘，看到的是上次完整同步的状态，这次的操作凭空消失

为了降低这个风险，我在设计中采用了两层防护：

第一，缩短同步间隔。最初考虑的是 2 分钟一次，后来改为 60 秒。理由是 USB 场景拔盘风险高，同步频率更高能减少未同步数据窗口。robocopy 的 copy-only 增量同步在百 MB 数据量下耗时不超过 5 秒，性能可接受。

第二，双轨写入策略。当 U 盘可写时，更新内容同时写到 U 盘的 update/staging/ 目录；当 U 盘只读时（或无法写入），改为写到本地 %LOCALAPPDATA%。两种情况下，用户都会得到明确的提示，知道这次变更是"永久保存在 U 盘"还是"仅在当前电脑临时有效"。

但即便如此，这个难点仍然是后续故障的根源。用户在问"为什么我上次保存的聊天记录不见了"时，十有八九就是在这个同步窗口被中断了。

难点 3：就地更新 —— 边跑边修

传统的桌面应用更新流程很简单：停止应用 → 覆盖文件 → 重启。便携版不行。

为什么？因为便携版的目标用户是在客户机上工作的人。他们双击启动应用，正在和 AI 对话、生成代码、调试工具。你不能告诉他"系统要更新，所有东西停止 30 秒"。这不是理想情况下的交付，这是在实际场景中的交付。

更严格的限制还有两个：

第一，不能装程序。应用进程本身是可执行的，但更新时不能覆盖当前运行的 exe。Windows 会锁定正在执行中的文件，强制覆盖会报错。解决方案是引入一个独立的启动器进程（launcher.exe），它的职责很简单：等主应用退出 → 备份旧版本 → 覆盖新文件 → 启动新版本 → 监控启动失败 → 自动回滚到旧版。主应用本身不需要感知更新逻辑。

第二，不能污染客户机。更新的新文件、临时文件、备份文件，都必须存储在 U 盘或本地缓存目录里，绝对不能写入 Windows 系统目录或用户的 Program Files。这意味着更新后的文件验证、备份清理，都要自己处理。

还有一个隐形的复杂性：灰度发布。为了降低全量更新的风险，后台会根据用户 ID 哈希决定是否推送新版本——10% 用户先升级，没问题再 50%、再 100%。这意味着后台需要维护版本清单、灰度配置，客户端需要能解析和判断自己是否应该升级。如果某个版本被发现有严重 bug，还要能强制弹窗"立即升级"或"退出软件"，用户无法选择"先不升"。

这四个细节加在一起，就是为什么 OTA（Over-The-Air）更新被独立列为一个难点——更新失败的最坏结果是应用无法启动，而它发生在没有人在场的客户机上。

难点 4：客户机环境不可控 —— 变量太多

便携版理论上可以工作在任何 Windows 10 / 11 机器上。但"任何"意味着什么？意味着要兼容：

OS 版本：Windows 10 1809（微软已停止支持但仍有用户用）到 Windows 11 24H2（最新版本）
架构：只考虑 x64，32 位与 ARM64 暂不支持
运行库：WebView2 Runtime 可能未预装；应用需要能检测并引导用户安装
Python：客户机可能已有 Python 环境，版本混乱（2.7、3.7、3.9、3.11、3.12 混用）。应用内置了 Python 3.11，但如果客户机已有兼容版本，优先使用以加速启动；如果版本不兼容，自动降级到内置版本
Node.js：同样的问题，但内置版本与系统版本冲突的情况较少
防杀软件：启动期会扫描常见杀毒软件（360、腾讯电脑管家、Windows Defender 等）是否在运行，这会影响 I/O 速度和权限检查
磁盘空间：OTA 升级需要临时空间；本地缓存也需要空间。如果 U 盘剩余 < 500 MB 或目标机 %LOCALAPPDATA% 所在盘 < 500 MB，升级会失败
网络：启动期会触发多个网络请求（检查更新、拉公告、同步用户配置）。不稳定的网络、防火墙阻止、代理认证失败，都要优雅降级而不是卡死

为了应对这些变量，启动器在启动主程序之前做了一整套"环境扫描"：

launcher.exe 启动
  ├─ 检查 Windows 版本 → 太旧则拒绝启动
  ├─ 检查 WebView2 Runtime → 缺失则触发 Bootstrapper 安装
  ├─ 扫描目标机 Python → 找兼容版本记录来源
  ├─ 探测防杀软件进程 → 记录可能影响性能的软件
  ├─ 检查磁盘空间 → 空间不足则警告
  ├─ 检查 U 盘接入方式 → 检测是否被识别为网络驱动器（某些网络盘可能导致 WebView2 异常）
  └─ 收集诊断信息 → 写本地文件并异步上报后台

这个扫描过程通常耗时 1-3 秒。收集到的诊断信息会异步发送到后台，但不阻塞应用启动——即使网络不通，应用仍然能启动。

客户机环境的复杂性最容易导致的问题就是"我这台电脑能用，为什么别的电脑不行"。同样一个 v0.14.0 版本的便携包，在配置 A（Win11 24H2、Python 3.11 官方版、SSD、无防火墙）上跑得飞快，在配置 B（Win10 1809、PyCharm 装的 Python 3.8、机械硬盘、严格防火墙）上可能卡死。排查的线索分散在多个地方：系统日志、应用日志、诊断数据、用户描述。

U 盘、本地缓存、OTA 的关系模型

讲完了这四个难点，需要把它们串联起来，看清整个便携版的信息流动图：

启动时序：
  用户双击 Start.cmd
    ↓
  launcher.exe stage 0-7（环境检查 + 诊断收集）
    ↓
  robocopy U 盘 → 本地缓存
    ↓
  设置环境变量（HOME / USERPROFILE / PATH 等）指向缓存路径
    ↓
  启动 WakouPanel.exe（运行在缓存中）
    ↓
  启动 guardian.exe（后台守护）

运行时流程：
  应用在缓存中读写数据（快速，本地 I/O）
    ↓
  每 60 秒 guardian 触发一次 robocopy
    ↓
  缓存中的变更同步回 U 盘
    ↓
  如果同步中断（拔盘 / USB 断电），下次插上时重新同步
    ↓
  应用中的"换机无感切换"依赖这个同步

OTA 升级流程：
  launcher.exe 检测到新版本
    ↓
  下载新版本到 update/staging/
    ↓
  等待主应用退出
    ↓
  备份当前 engines/ 为 *.old
    ↓
  覆盖 U 盘上的 WakouPanel.exe / engines/
    ↓
  启动新版本
    ↓
  如果新版本连续启动失败，自动回滚到 *.old

这个模型的核心是分层：U 盘是"源"（truth source），缓存是"镜像"（working copy），OTA 触发时更新源，然后下一次启动时缓存自动同步最新的源。

但这个分层在以下场景下会产生矛盾：

更新与拔盘同时发生：用户正在下载新版本，突然拔盘。缓存中的 staging/ 目录消失，但 U 盘上的 staging/ 可能不完整。重新插盘启动时会尝试恢复，但流程复杂容易出错。
多个缓存实例竞争：同一台机器上多个用户账户，或用户在不同时间以不同身份登录，都会产生不同的缓存目录。如果 U 盘在两个缓存间不一致地同步，可能导致"缓存 A 看到的是旧数据，缓存 B 看到的是新数据"。
本地缓存被意外清理：Windows 的磁盘清理工具或杀毒软件的隔离功能，可能会删除 %LOCALAPPDATA% 下的陈旧目录。如果缓存被清理而 U 盘还活着，下次启动会重新同步，但如果同步过程出错就会卡死。

这些矛盾大多数时候能正常处理（因为设计中有检测和回滚机制），但在网络不稳定、用户异常操作的时候，就会逐个暴露出来。

四个难点——完整性、双位置状态、就地更新、环境检测——不是孤立的。它们交互作用，放大彼此的风险。一个完整的文件列表，如果同步中断就变得不完整；一个完成了 50% 的 OTA 更新，如果被中断的网络打乱时序，就会导致两个版本的文件混在一起；一个环境扫描失败的启动，往往不是单一原因，而是几个小问题的叠加。

这就是为什么这一栏叫"交付与更新"。便携版交付看起来简单，实际却是最复杂的交付链路。后续每一篇故障档案，都可以溯源到这四个难点中的某一个，或它们的组合。

■