WorkBuddy 迁移工具使用说明
一、准备工作
环境要求
- Windows 10/11 或 macOS 11+
- Python 3.8 及以上（工具仅用标准库，无需安装其他包）
启动工具
Windows：打开工具所在文件夹，进入 scripts/windows/，双击 start.bat。启动成功后会自动打开默认浏览器进入工具页面。
macOS：进入 scripts/macos/，双击 start.command。首次运行前，请在终端执行一次 chmod +x scripts/macos/start.command scripts/macos/start.sh。
- 请勿关闭启动时的黑色命令行窗口（可以最小化）。关闭该窗口 = 退出迁移工具，页面会提示连接失败。
- 首次打开页面会显示「正在扫描本机空间与文件大小」，空间较多或目录较大时需要十几秒到一分钟，页面会自动刷新，无需任何操作。
二、在旧电脑上导出数据
- 在旧电脑上双击启动脚本，等待浏览器自动打开工具页面。
- 确认页面顶部显示的是「导出」标签页。
- 在「导出保存到」一栏，可以：
- 直接在输入框里修改路径；
- 点击「浏览…」按钮选择保存位置（如 D 盘、网盘同步文件夹等）。
- 勾选要迁移的空间。建议保留默认全选。
- 如果需要把完整对话记录一起迁移，勾选「包含完整对话记录」。
- 点击「开始导出」，等待进度完成。
三、传输导出包到新电脑
导出完成后，页面会显示生成的 zip 文件路径，例如：
把这个 zip 文件通过网盘、邮件、U 盘等方式传到新电脑。
四、在新电脑上导入数据
- 在新电脑上把整个 workbuddy-migrate 文件夹复制过去，按系统进入 scripts/windows/ 或 scripts/macos/，双击启动脚本。
- 点击页面顶部的「导入」标签。
- 把 zip 文件拖入上传区，或点击上传区选择文件。
4.1 核对预览
上传后工具会先校验 zip 并展示预览，你可以看到：
- 每个空间从旧电脑路径 → 新电脑路径的自动重写结果
- 哪些项目与本机已存在冲突
- 哪些文件校验不通过（损坏）
4.2 选择去重策略
预览页下方有三种策略：
- 智能合并（推荐）：双方数据取并集，冲突保留较新版本，绝不删除本机内容。
- 跳过已存在：本机已有的完全不动，只补充没有的部分。
- 覆盖同名：同名项以导出包版本替换，被覆盖内容会先自动备份。
4.3 确认导入
点击「开始导入」后，会弹出确认窗口。工具会自动备份本机将被改动的数据，确认无误后点击「确认导入」。
4.4 查看结果
导入完成后会显示统计：成功写入的空间、会话、任务、文件数量，以及是否有损坏文件被跳过。
五、导入后打开空间
- 启动 WorkBuddy。
- 在空间列表中找到导入的空间文件夹（路径就是预览页里显示的「本机路径」）。
- 打开文件夹，WorkBuddy 会自动加载其中的会话和任务。
六、常见问题
Q：双击 start.bat 后黑窗口一闪而过？
A：先看同目录的 start.log，里面记录了启动过程。常见问题是没有 Python，按日志提示一键安装即可。
Q：提示「未检测到 Python」或一键安装失败？
A：重新双击 start.bat 会弹出一键安装向导（免安装版约 12MB，无需管理员权限）。如果自动下载失败（网络问题），可以手动安装：
- 打开下载地址 https://www.python.org/downloads/（官网打不开可用华为镜像 https://mirrors.huaweicloud.com/python/）
- 下载 Windows installer (64-bit)
- 安装时务必勾选 Add python.exe to PATH
- 安装完成后重新双击 start.bat，会自动检测到新装的 Python
Q：页面一直显示「正在扫描本机空间」？
A：这是正常的首次扫描——工具要统计每个空间的文件数和大小，空间多、目录大时可能需要几十秒。页面会自动刷新出结果，期间请不要关闭黑窗口。
Q：页面提示「无法连接到本地服务器 (Failed to fetch)」？
A：说明启动工具的黑窗口被关闭了，或服务没启动成功。重新双击 start.bat，保持黑窗口开启（可最小化），再刷新页面。
Q：导入时提示「检测到 WorkBuddy 正在运行」？
A：完全退出 WorkBuddy（包括系统托盘图标）后重试。
Q：两台电脑用户名不同，路径能自动对吗？
A：工具会自动把旧电脑的 C:\Users\旧用户名\WorkBuddy 前缀重写为新电脑的对应路径。导入预览页会明确显示重写结果。
Q：zip 文件传输后提示损坏？
A：重新下载/发送导出包，必要时对比新旧电脑的 SHA256 是否一致。损坏的文件导入时会被跳过并报告。
Q：可以跨系统迁移吗？比如公司 Windows 导出、导入到家里 Mac？
A：可以。导出包会记录源机器系统，导入时自动把路径前缀重写为本机风格（如 C:\Users\你\WorkBuddy\空间A → /Users/你/WorkBuddy/空间A）。导入预览页会显示来源与本机的系统徽标和跨系统提示；个别文件名不符合本机系统规范时会跳过并计入失败清单，不影响其余数据。
七、数据安全说明
- 导入前会自动备份数据库、将被改动的任务与文件到 ~\.workbuddy\migrate-backup\时间戳\。
- 三种策略均不会删除目标电脑上的任何已有数据。
- 文件先写临时名再改名，中断后可安全重跑。