WorkBuddy 存储路径配置与跨盘迁移
Overview
本技能把 WorkBuddy 的存储路径机制拆解为可操作的程序性知识。所有结论均来自对安装包 D:\WorkBuddy\resources\app.asar（v5.3.12）路径解析函数的反编译实测，以及本机切换后的复核，而非推测。它用于回答三类问题：文件默认存哪、如何改、改了之后是否真能避开 C 盘。
When to use
在以下情形触发本技能：
- 用户询问 WorkBuddy 的默认文件存储路径或配置方式。
- 用户希望把 WorkBuddy 产生的缓存、日志、导出文件、项目数据统一保存到 D 盘或其他非系统盘。
- 用户确认"是否完全避免占用 C 盘系统盘空间"。
- 用户要在安装或设置阶段指定存储位置，需要具体的配置项或初始化参数。
- 用户遇到迁移后 C 盘仍有数百 MB 占用，怀疑迁移不彻底。
三层路径机制（源码实测）
WorkBuddy 的存储由三层相互独立、解析机制不同的路径构成。改动任一层都要分别对应其配置入口。
| 层级 | 官方配置方式 | 解析优先级 | 默认值 | 覆盖内容 |
|---|---|---|---|---|
| 任务工作区根 | GUI「默认工作空间存储路径」+「更改」按钮（设置 → 数据管理） | AppConfig defaultWorkspacePath → 浏览器本地存储键 CODEBUDDY_DEFAULT_WORKSPACE_PATH → 系统默认 |
%USERPROFILE%\WorkBuddy |
新建任务目录与产物、导出文件、项目数据 |
| 用户数据目录 | 环境变量 WORKBUDDY_CONFIG_DIR（亦读 CODEBUDDY_CONFIG_DIR，前者优先）；无 GUI 入口 |
env → ~/.workbuddy |
%USERPROFILE%\.workbuddy |
配置、技能、插件、记忆、日志、追踪、各类缓存、运行时 |
| Electron 用户数据 | 环境变量 WORKBUDDY_USER_DATA_DIR；缺省自动取 <configDir>\app |
env → <configDir>\app |
.workbuddy\app |
会话、cookies、本地存储 |
关键源码片段（app.asar v5.3.12）：
// 配置目录（.workbuddy）
process.env.CODEBUDDY_CONFIG_DIR?.trim()
|| process.env.WORKBUDDY_CONFIG_DIR?.trim()
|| path.join(os.homedir(), ".workbuddy")
// Electron 用户数据，默认嵌在配置目录内，自动跟随
process.env.WORKBUDDY_USER_DATA_DIR?.trim()
|| path.join(getWorkbuddyConfigDir(), "app")
i18n 键证实：settings.workspacePath.label 为「默认工作空间存储路径」，其描述写明"修改后不影响已有数据"；settings.storage.* 区块仅展示用量与「打开文件夹」，没有更改按钮，即配置目录（.workbuddy）无 GUI 入口，只能走环境变量或联接。
联接优先于改环境变量
当用户的目标是"把现有安装整体搬离 C 盘且历史不丢"，优先采用 NTFS 目录联接，而非修改 WORKBUDDY_CONFIG_DIR。
原因来自源码与索引结构实测：.workbuddy\app\sessions.json 硬编码了绝对路径（如 C:\Users\cmxdyn\WorkBuddy\2026-08-08-14-31-59，共 8 条），.workbuddy\projects\ 的目录名直接编码绝对路径（如 c-Users-cmxdyn-WorkBuddy-2026-08-08-14-31-59）。联接保持路径字符串不变，历史索引全部继续有效；改环境变量会让路径字符串变化，历史条目与新条目分裂为两套命名空间，旧的会话与项目链接失效。
应用启动后会把解析结果回写这两个环境变量供子进程继承，因此在一个运行中的进程里看到 WORKBUDDY_CONFIG_DIR 被设置，不代表用户手动设过，不能作为"已配置"的判据。
未被任何配置项覆盖的 C 盘写入点
以下三处由 Electron / electron-updater / electron-log 决定，WorkBuddy 未暴露配置项，只能靠文件系统层重定向：
| 路径 | 实测占用 | 成因 |
|---|---|---|
%LOCALAPPDATA%\@genieworkbuddy-desktop-updater\installer.exe |
约 395.8 MB | electron-updater 下载缓存，硬编码 localAppData |
%LOCALAPPDATA%\Temp\workbuddy-update-x64 |
约 395.8 MB | 更新解包暂存，走 os.tmpdir() |
%LOCALAPPDATA%\WorkBuddy\logs |
约 7.9 MB | electron-log 走 app.getPath('logs') |
| 合计 | 约 800 MB | 其中约 792 MB 是同一份更新包的两个副本 |
处理手段：先用本技能附带的 scripts/wb-appdata-redirect.ps1 的 Scan 阶段只读体检，确认占用与进程状态；用 Purge 阶段仅清理陈旧更新包（最快释放约 792 MB，无需建联接）；用 Apply 阶段建立三个联接实现真正零 C 盘占用（需先完全退出 WorkBuddy）；Rollback 阶段可拆除联接并恢复原目录。该脚本约束为"仅改存储位置、不动功能、全程可回退"。
在设置或安装阶段指定存储位置
- 任务工作区：安装后进入设置 → 数据管理，将「默认工作空间存储路径」改为目标盘目录（如
D:\WorkBuddyStore\WorkBuddy）。这是唯一 GUI 可配路径，且仅影响此后新建任务，不触动既有数据。 - 用户数据目录：在启动前设置用户级或机器级环境变量
WORKBUDDY_CONFIG_DIR指向目标盘目录（同时可设CODEBUDDY_CONFIG_DIR保持一致）。该层无 GUI 入口。 - Electron 用户数据：可选设
WORKBUDDY_USER_DATA_DIR；不设则自动跟随用户数据目录。 - 正交的增长抑制：设置内「任务保留策略」支持永久 / 90 / 60 / 30 天，仅作用于新建任务。
必须向用户校准的认知
- C 盘与 D 盘若为同一块物理磁盘的两个分区，迁移只释放 C 分区的空间，不提升性能、不分散单盘故障风险。把预期放在"给系统盘减负"是准确的，放在"隔离故障域"则不成立。
- 切换不可能绝对零窗口：被进程独占的文件（如 Chromium 的 Cookies 锁文件）无法在运行时移动，方案承诺的是"零数据丢失 + 秒级窗口"，绝大多数字节已在热复制阶段就位。
- 回退备份
.bak在切换后会暂占 C 盘，需稳定运行数日后再回收。
Resources
references/path-mechanism.md：完整的源码摘录、解析优先级、i18n 键、残留路径表与切换后复核数据，供深入研判时加载。scripts/wb-appdata-redirect.ps1：处理三层主迁移未覆盖的 C 盘残留写入点，含 Scan / Purge / Apply / Rollback 四阶段。
安全与边界
本技能附带的脚本仅做存储位置重定向，不含任何凭据、不做网络外发、不修改 WorkBuddy 功能代码。Apply 与 Rollback 阶段按要求在 WorkBuddy 完全退出后执行，且内置进程占用护栏。
