技能介绍

解决的具体问题

当用户需要更换电脑或进行备份恢复时，WorkBuddy 国内版的个人资产迁移面临多个挑战。传统手动复制 ~/.workbuddy/ 目录可能导致数据不完整、路径冲突或配置错误。例如，数据库文件、技能配置和对话历史分散在不同子目录中，跨平台迁移（如 Mac 到 Linux）时路径映射复杂，且冲突处理缺乏透明度。

技能工作原理

该技能通过以下核心能力解决迁移问题：

两包分离架构：导出时生成两个独立的 zip 文件：

- 主包 (wb-migration-{timestamp}.zip)：包含关键数据如数据库、技能、配置、身份信息等，体积小（10-100 MB），便于快速传输。
- 产物包 (wb-migration-{timestamp}-workspaces.zip)：包含对话目录下的所有文件资料（代码、报告、图片等），可选传输，失败不影响主包导入。

自动路径映射：使用 --auto-map 参数自动处理跨平台路径差异（如 /Users/ 到 /home/），或通过 --path-map 手工指定映射规则。

冲突检测与控制：导入前通过 dry-run 预览冲突报告，默认采用合并不覆盖策略（保留目标端已有资产），除非显式使用 --overwrite。关键约束确保迁移安全：

- 导入前必须退出 WorkBuddy 客户端：避免 SQLite 写锁冲突。
- 必须排除当前迁移会话：防止目标端出现僵尸对话，可通过环境变量或 --exclude-session-id 指定。
- 导入后必须重启客户端：使配置变更生效。

适用边界与注意点

该技能适用于跨机迁移场景，如旧 Mac 到新 Mac、Mac 到 Linux 或 Windows 到 Mac。它也支持备份恢复和多机同步。然而，不适用于同机国内版与海外版之间的迁移（需使用其他专用技能）。用户需注意：

资产范围：迁移覆盖所有个人资产，但排除平台相关二进制（如 binaries/）、缓存（如 app/cache/）和临时日志（如 logs/），这些由目标端自动重建。
凭证处理：推荐使用 --no-credentials 排除 OAuth token 等凭证，跨机后通常失效，需在目标端重新授权。
调试支持：通过 references/ 目录加载详细文档，如流程图、命令参数和已知问题，便于故障排查。