WorkBuddy 从 Windows 无损迁移到 Mac

这个技能解决什么

痛点：WorkBuddy 的历史任务、产物文件、文件树全部记录绝对路径。
从 Windows 拷到 macOS 后，目录结构根本不同（盘符 C:、反斜杠 \、
用户名目录差异），导致：

关键认知：这是 ENOENT（路径不存在），不是权限问题。
排查时先看日志里是 ENOENT 还是 EACCES——若是 ENOENT 且报错路径带
C:\Users\...，就是本技能要解决的问题，加权限没用。

路径分类：哪些必须改，哪些不用管

别把「历史对话里出现过 Windows 路径」当成「必须修」。真正影响使用的是
长期引用，过程路径改了没有任何收益，反而增加出错面积。

对应参数：--scope=core（默认，按上表）／--scope=full（旧行为，连会话转录一起改）。

Windows 属性文件：.exe / .bat / .cmd / .ps1 / .dll / .msi 等在 Mac
上本来就无法运行，按策略去掉 Windows 后缀名即可（tool.exe → tool），
去掉后打不开属预期，无需进一步处理。用 winext 子命令，默认只列清单。

前置条件（必须严格按序）

① 在 Mac 上安装并启动一次 WorkBuddy  → 生成 ~/.workbuddy 目录结构
② 完全退出 WorkBuddy                    → 释放索引与数据库的文件锁
③ 从 Windows 手工拷贝两个目录：
     C:\Users\<你>\WorkBuddy    →  拷贝到 Mac 的工作区目录
     C:\Users\<你>\.workbuddy   →  拷贝到 Mac 的 ~/.workbuddy（同名覆盖）
④ 运行本技能的脚本修复索引与数据库
⑤ 重新打开 WorkBuddy

为什么第①步不能省：WorkBuddy 首次启动会生成 workbuddy.db、
artifact-index/、projects/ 等目录结构。先启动再拷贝，才能保证
拷贝过来的文件覆盖到正确位置；反过来会出现"目录不存在、拷贝落空"。

为什么第②步不能省：运行中的 WorkBuddy 会缓存索引并持有数据库连接，
边跑边改会得到不一致的结果，甚至把改写覆盖回去。

执行清单

分阶段执行（推荐，大数据量时更稳）：

python3 scripts/wb_migrate.py migrate --apply --stage=projects  # projects 目录 + JSONL（先做）
python3 scripts/wb_migrate.py migrate --apply --stage=index     # 索引 + 文件树
python3 scripts/wb_migrate.py migrate --apply --stage=db        # 数据库（最后做）

顺序很重要：projects 阶段要把 Windows 目录名改成 macOS 目录名，
需要知道「原始 Windows 路径」。db 阶段一旦先把 sessions.cwd 改掉，
原始信息就丢了。因此 --stage=all 会自动按
projects → index → db 执行。

即便如此，首次迁移时脚本也会把「原始 cwd 映射」写进
~/.workbuddy/.wbmigrate_state.json，任意顺序、任意次数重复执行都安全。

每阶段独立可重跑，中断后从下一阶段继续即可。

涉及删除的操作保护：清理悬空引用时，若单文件删除比例超过 50%
（--max-drop-ratio 可调），脚本会中止并报错，而不是删掉数据。
数据库里的会话/工作区清理同样受这条保护。
先跑 scan 核对影响面，确认无误后再用 --max-drop-ratio 0.9 放行。

文本目录始终处理：tasks / audit-log / changes-* / file-history
属于过程路径，默认（--scope=core）整段跳过；需要全文改写时显式传
--scope=full。这与早期版本「任何一次执行都一并改写」的行为不同——旧行为
会把十几万处历史对话原文也改一遍，收益为零。

用户怎么说（可直接复述）

我刚把 WorkBuddy 从 Windows 拷到 Mac，文件夹都拷过来了，
但历史任务里的文档点不开，能帮我修一下吗？

WorkBuddy 迁移到 Mac 后任务列表是空的，产物文件也不显示，
请帮我诊断并修复。

参数说明

--wb-dir PATH     WorkBuddy 数据目录，默认 ~/.workbuddy
--win-user NAME   Windows 用户名（自动探测失败时指定，如 kixp）
--ws-root PATH    macOS 工作区根目录（自动探测失败时指定）
--map WIN=MAC     追加自定义映射，可重复指定
--stage STAGE     projects / index / db / all，默认 all
--scope SCOPE     core（默认，只改长期引用）/ full（连会话转录一起改）
--no-backup        跳过自动备份（不推荐，没有回滚点）
--max-drop-ratio N  涉及删除的比例上限，默认 0.5，超过则中止
--no-cleanup      只改路径、不删悬空条目（安全阀拦下时的替代方案）

winext 子命令参数：

--roots DIR...    扫描根目录，默认：数据目录 + 工作区根目录
--exts .exe ...   要去除的后缀，默认 exe/bat/cmd/ps1/dll/msi/com/scr/msu/lnk
--apply           真正重命名（默认只列清单）

自动探测规则：Windows 用户名从 workbuddy.db 的 sessions.cwd 提取；
macOS 工作区根目录在 ~/WorkBuddy、~/Documents/WorkBuddy、
~/Desktop/WorkBuddy 中选项目数最多的。

应避免的用法

常见问题速查

能力边界

能做：
- 改写 artifact-index / file-tree-manifests / assistant-display 等索引里的路径
- 改写 workbuddy.db 的 workspaces.path / sessions.cwd / automations.prompt 等字段
- 改写 projects/**/*.jsonl 的 cwd 与工具参数里的路径（--scope=full）
- 重命名 projects/ 下按 Windows cwd 命名的目录
- 修复混合路径：盘符+Mac 结构（C:/Users/vin/...）、Mac 前缀+反斜杠（/Users/vin/a\b）
- 识别 Windows 属性文件并去掉 Windows 后缀名（winext）
- 清理指向已不存在文件的悬空 artifact 与文件树条目

不能做：
- 找回没拷过来的源文件（D 盘知识库、桌面文件等）——只能改路径，不能凭空造文件
- 把 .exe 变成可在 Mac 运行的程序 —— 去后缀只是让它不再像可执行文件
- 迁移 WorkBuddy 应用本体（.app 安装包）
- 迁移云端账号数据
- 恢复已被误删且没有备份的数据

失败兜底策略

1. 任何阶段报错：先看 doctor 的输出，确认数据目录路径是否正确
2. 改坏了：用 python3 scripts/wb_migrate.py restore --from ~/.workbuddy-backup-<时间戳>/ 一键回滚
   （回滚会同时清除迁移状态文件）
3. 不确定：先用 scan（只读）确认影响面，再决定是否 --apply
4. 应用行为异常：先 verify，把输出贴给用户判断是否回滚

深入阅读索引

目录结构

workbuddy-windows-to-mac/
├── SKILL.md                          执行卡（本文件）
├── README.md                         方法论手册（给人读）
├── scripts/
│   └── wb_migrate.py                 迁移工具（doctor/scan/backup/migrate/restore/verify/winext）
├── tests/
│   ├── test_wb_migrate.py            单元测试（130 项）
│   └── verify_independent.py         独立验证器（端到端，51 项）
└── references/
    ├── migration-guide.md            完整操作手册与原理
    └── pitfalls.md                   踩坑实录