Workspace Cross-Drive Migration（工作空间跨盘迁移）

把 WorkBuddy 工作空间整体迁移到另一个磁盘（例如 D 盘搬到移动硬盘以节省空间），并保留会话历史、项目记忆、项目级技能、自动化绑定与侧边栏显示名，迁移后做到无缝衔接。当用户说「工作空间搬家/迁移到移动硬盘/换盘/C盘D盘空间不够/把项目挪个位置/迁移后历史对话不见了/路径改了会话丢了」时使用。适用于 Windows 上的 WorkBuddy/CodeBuddy 工作空间，支持迁移前体检、执行、核对与回滚四个阶段，全程不删除源文件。

工作空间跨盘迁移

这个技能解决什么

工作空间不是「一个文件夹」那么简单。只复制文件夹，一定会丢东西： 历史对话看不见、记忆空白、项目级技能消失、自动化任务报路径不存在、侧边栏多出一个幽灵条目。

真正要搬的是下面五处，缺一处就不算无缝：

#	位置	丢了会怎样
1	工作空间目录本身（含 .workbuddy/：memory、skills、todos）	记忆、项目技能全丢
2	~/.workbuddy/projects/<slug>/（会话历史 jsonl）	历史对话在侧边栏消失
3	会话 jsonl 内的绝对路径	打开会话提示目录不存在、@文件路径失效
4	~/.workbuddy/workbuddy.db 的 workspaces / sessions / automations / workspace_trust_decisions	自动化失效、会话拉不起来、要重新授权信任
5	~/.workbuddy/workspace-display-names.json	侧边栏名字变了或出现幽灵工作空间

其中 <slug> 由工作空间绝对路径派生，这是最容易踩的坑： 盘符小写 + 各级目录用 - 连接，空格/中文/下划线/大小写原样保留。

text

D:\WorkBuddyWork\2026-10-21-09-32-06  ->  d-WorkBuddyWork-2026-10-21-09-32-06
G:\2026\职称申报-20261024            ->  g-2026-职称申报-20261024

细节与实测样例见 references/storage-map.md，不要凭记忆猜。

开工前必须问清的三件事

1. 源：要搬哪个工作空间（绝对路径）。如果用户只说"这个项目"，用当前会话的工作目录。
2. 目标：搬到哪（绝对路径，含新名字）。提醒：移动硬盘建议用固定盘符，否则下次插拔换盘符，路径就又失效了。
3. 是否有自动化：体检会列出来。有自动化绑定就必须改数据库，不能只复制文件。

标准流程（四步，别跳）

所有脚本都在本技能的 scripts/ 下，需要 Python 3.8+，Windows 自带即可。 命令里的路径一律加引号（中文路径和空格很常见）。

第 1 步：体检（只读，随便跑）

bash

python scripts/plan_migration.py --source "D:\Work\项目A" --target "G:\迁移\项目A"

输出会给出：体积、目标盘空间与文件系统、slug 新旧对照、会话历史条数、数据库待改行数、 自动化绑定数、长路径风险、嵌套工作空间、目录联接。最后一屏是结论。

有 [STOP] 就别往下走，先解决阻断项（空间不足、目标已存在、FAT32、目标在源目录内部等）。

第 2 步：演练，给用户看

bash

python scripts/apply_migration.py --source "D:\Work\项目A" --target "G:\迁移\项目A"

不加 --apply 只打印 8 个步骤，一个字节都不改。 把这份步骤和体检结论一起念给用户，等他明确同意再进第 3 步。

第 3 步：执行

bash

python scripts/apply_migration.py --source "D:\Work\项目A" --target "G:\迁移\项目A" --apply

八个步骤：备份元数据 → 复制 → 校验体量 → 会话目录改名 → 改写 jsonl → 改写 .workbuddy 文本 → 显示名换键 → 数据库改路径（可选隔离源目录）。

• 不加 --isolate-source 时源目录原样保留，这是默认且推荐的：先确认新的能用，再自己处理旧的。
• 加 --isolate-source 也只是把源目录改名成 项目A.migrated-20261029-101500，不删除， 同盘改名是瞬时的，随时能改回来。
• 数据库若被占用（应用正在跑），会打印 --db-only --apply 补改命令，不算失败，别慌（补改前会先打印将要改的行数，不加 --apply 只预览）。

第 4 步：核对

bash

python scripts/verify_migration.py --state "<上一步打印的状态目录>"

全绿才算成功。要更彻底加 --deep 做全量 MD5（文件多时很慢，先跟用户说）。

然后请用户：完全退出 WorkBuddy（含托盘）→ 重启 → 打开新路径， 亲眼确认三样东西：历史会话、.workbuddy/memory 里的记忆、项目级 skills。

第 5 步（可选）：回滚

bash

python scripts/rollback_migration.py --state "<状态目录>"          # 演练
python scripts/rollback_migration.py --state "<状态目录>" --apply  # 执行

回滚只做改名/改回路径/还原备份，不删任何文件；新位置目录会被改名成 .rolledback-<时间戳>。

关键判断

目标路径已存在且非空 → 不覆盖。换一个目标名，或让用户自己确认后清空。脚本会直接 STOP。

源目录里嵌着别的工作空间（子目录里有 .workbuddy）→ 它们会跟着一起复制，但各自的 projects/<slug> 与数据库记录不会自动跟着改。要么分开迁移，要么先问用户这些子工作空间还要不要。

搬到移动硬盘/网络盘 → 额外三条提醒：

• 盘符必须固定（磁盘管理里改盘符），否则换 USB 口就失效；
• 机械移动硬盘休眠会卡 I/O，大项目建议复制时别做别的事；
• 拔盘前一定「安全删除硬件」，WorkBuddy 还开着时更不能直接拔。

FAT32 目标 → 直接拒绝（4GB 单文件上限 + 长路径问题），让用户先格式化成 NTFS 或 exFAT。

数据库改不动（database is locked） → 正常现象。让用户完全退出应用（任务管理器里确认没有 WorkBuddy 进程），再跑 apply_migration.py --state "<状态目录>" --db-only --apply（不加 --apply 只预览行数）。

用户其实只想省空间，不想换位置 → 先提醒：迁移本身不省空间，省空间靠删掉旧目录。 所以要讲清"先搬、验证、再删"，别一上来就删。

影响范围与安全边界（审计用）

本技能只写下列位置，别处一律不碰：

写入对象	时机	保护措施
目标目录（用户指定的新路径）	第 2 步复制	只新建；目标已存在且非空直接中止，从不覆盖
projects/<旧slug> → <新slug>	第 4 步	先把整个目录复制进备份区，再 rename
jsonl 文件内容	第 5 步	每个文件改前单独复制备份；逐行 json.loads 校验，任何一行失败则该文件整体放弃
目标目录内 .workbuddy/** 的 md/json/txt	第 6 步	只做路径字符串替换；JSON 改后重新 parse 校验，失败则不写
workspace-display-names.json	第 7 步	改前复制 .bak
workbuddy.db 的四张表	第 8 步	改前复制 db 及 -wal/-shm；单事务提交，异常整体回滚
源目录	仅 --isolate-source	只改名为 <名字>.migrated-<时间戳>，绝不删除

硬约束：

• 不加 --apply 时不写任何文件，只打印步骤。
• 脚本内没有删除文件或目录的调用（不使用 rmtree/remove/rmdir/del），也不提供删除源目录的功能；旧数据怎么处理由用户自己决定。唯一的"替换"是保存 JSON 时用临时文件原子替换同名文件（写入前已校验）。
• 不读写任何账号凭据、不访问网络、不启动后台服务；只调用系统自带的 robocopy 与 tasklist（后者仅用于提示"应用正在运行"）。
• 所有改动都可以用 rollback_migration.py 逆向还原，回滚同样只改名/复原、不删除。

红线

• 绝不 rm -rf / del /S /Q 源目录，也绝不替用户删。只改名隔离，删除交给用户。
• 绝不用 robocopy /MIR 做备份或迁移（会删掉目标端多余文件）；复制用 /E。
• 绝不在没跑体检的情况下直接 --apply。
• 绝不在用户没确认前动真实工作空间；先用 --skip-db / 演练模式说话。
• 绝不手改 workbuddy.db 之外的方式绕锁（比如杀掉用户进程）。

脚本清单

脚本	作用	是否写盘
scripts/ws_migrate_common.py	公共库：slug 推导、路径改写、体积统计、数据库改名	被调用时才写
scripts/plan_migration.py	迁移前体检	只读（--json 除外）
scripts/apply_migration.py	执行迁移，默认演练	带 --apply 才写
scripts/verify_migration.py	迁移后核对	只读
scripts/rollback_migration.py	回滚，默认演练	带 --apply 才写

已知限制（别过度承诺）

• 源目录全程只读：迁移是「复制」不是「移动」，源目录的内容在任何阶段都不被修改， 所以永远保有一份原始数据；有它兜底，最坏情况也能重来一遍。 --isolate-source 只是改名隔离，内容不动。
• 回滚的边界：rollback_migration.py 能还原路径、目录名、数据库记录、显示名与已备份的 jsonl/文档。它不能还原用户自己删掉或改过的业务文件——脚本从不删文件，也从不改源数据。
• 自动化 prompt 正文里手写的绝对路径不会被改（那是用户的文字），需要在自动化界面里自己改。
• file-history / file-tree-manifests / artifact-index / changes-index 等索引仍含旧路径， 属可重建缓存，默认不动；用过之后会按新路径重建。
• 移动硬盘盘符一变，整套对应关系（slug、数据库、显示名）全部失效，必须先固定盘符。
• 不碰用户级技能（~/.workbuddy/skills）、不碰任何账号凭据、不联网。
• 目标文件系统是 FAT32 时拒绝执行（4GB 单文件与长路径限制）。

参考资料

• references/storage-map.md — 五处存储的具体路径、格式、哪些能重建、实测样例
• references/playbook.md — 不依赖脚本的手工迁移全流程（含 Windows 命令），以及给用户的话术
• references/troubleshooting.md — 常见报错、盘符漂移、权限、长路径、数据库锁