wb-migrate v2.0.3 — WorkBuddy 全量数据迁移

触发场景

当用户提到以下需求时，使用此 skill:

• "备份 WorkBuddy 数据"
• "迁移到新账号/新电脑"
• "换账号后恢复任务"
• "导出 WorkBuddy 配置"
• "wb-migrate"、"数据迁移"
• 跨平台迁移时提示路径错误需要修复

使用方法

1. 扫描当前数据

python3 ~/.workbuddy/skills/wb-migrate/scripts/wb_migrate.py scan

2. 创建备份

python3 ~/.workbuddy/skills/wb-migrate/scripts/wb_migrate.py backup --output ~/Desktop

3. 查看备份内容 (含跨平台检测)

python3 ~/.workbuddy/skills/wb-migrate/scripts/wb_migrate.py info <backup.tar.gz>

> 自动检测源/目标平台差异并给出建议

4. 恢复备份 (智能合并，不覆盖已有数据)

python3 ~/.workbuddy/skills/wb-migrate/scripts/wb_migrate.py restore <backup.tar.gz>

5. 预览恢复操作

python3 ~/.workbuddy/skills/wb-migrate/scripts/wb_migrate.py restore <backup.tar.gz> --dry-run

6. 跨平台自动映射恢复

python3 ~/.workbuddy/skills/wb-migrate/scripts/wb_migrate.py restore <backup.tar.gz> --auto-map

> 自动：检测源/目标 OS → 映射 sessions.cwd → 合并 user_id → 重命名 projects → 校验

目标账号 user_id 无法自动检测时：

python3 ~/.workbuddy/skills/wb-migrate/scripts/wb_migrate.py restore <backup.tar.gz> --auto-map --target-user-id <uuid>

7. 强制覆盖恢复

python3 ~/.workbuddy/skills/wb-migrate/scripts/wb_migrate.py restore <backup.tar.gz> --force

#windows运行bat

@echo off

REM wb-migrate — WorkBuddy 数据迁移工具 (Windows)

REM 用法: wb-migrate.bat scan|backup|restore|info|migrate [参数...]

setlocal

set SCRIPT_DIR=%~dp0

set PYTHON_SCRIPT=%SCRIPT_DIR%scripts\wb_migrate.py

REM 查找 Python

where python >nul 2>&1

if %ERRORLEVEL% EQU 0 (

set PYTHON=python

) else (

where python3 >nul 2>&1

if %ERRORLEVEL% EQU 0 (

set PYTHON=python3

) else (

echo 错误: 未找到 Python，请先安装 Python 3.9+ 并添加到 PATH

exit /b 1

)

)

"%PYTHON%" "%PYTHON_SCRIPT%" %*

核心能力

跨平台路径与账号自动映射 (--auto-map)

从旧账号/旧设备恢复到新账号/新设备时，自动处理：

• sessions.cwd 路径映射 (/Users/alice/ ↔ C:\Users\Alice\)
• user_id 合并 (源账号 → 当前账号)
• workspaces.path 更新
• projects/ 目录名重命名 (匹配新 cwd 编码)
• 缺失工作区目录创建，并恢复基础 .workbuddy/memory/ 结构
• 按可用 schema 注册 workspaces 表，避免跨版本字段差异导致恢复失败
• 空 ~/.workbuddy 目录首次恢复时同样执行路径映射
• 同系统换账号时也会执行 user_id 合并；目标账号未产生任何会话时，用 --target-user-id 显式指定

恢复后自动校验

每次恢复完成后自动检查：

• sessions-cwd 有效性
• workspace 目录存在性
• projects 目录匹配
• tasks-sessions 关联
• user_id 一致性

安全增强

• 恢复前自动备份目标数据库 (workbuddy.db.backup-{ts})
• SQLite 一致性快照备份，避免遗漏 WAL 中未 checkpoint 的数据
• 备份包完整性校验与安全解包，兼容 Python 3.9+
• 问题报告有明确的修复指引

备份包含的数据

智能合并策略

恢复时采用以下策略避免数据覆盖:

• 数据库: INSERT OR IGNORE — 仅导入目标数据库中不存在的记录
• Skills: 按名合并 — 新文件直接添加，已有文件跳过
• 项目数据: 按目录合并 — 新项目直接添加
• 配置文件: 仅在目标不存在时创建

WorkBuddy 数据架构要点

在执行迁移任务时，需要了解以下关键知识：

路径编码规则

数据隔离

• Sessions: 通过 user_id 字段隔离，不同账号不可见
• Tasks: 挂在 session ID 下
• 对话数据: ~/.workbuddy/projects///
• Skills/Projects/Connectors: 不区分账号，所有用户共享

典型工作流

同机换账号

wb-migrate backup --output ~/Desktop
# 切换账号，建议新账号先创建一次任意会话
wb-migrate restore ~/Desktop/wb-backup-*.tar.gz --auto-map

跨设备迁移 (macOS → Windows)

# macOS 上
wb-migrate backup --output ~/Desktop

# 传输到 Windows 后
wb-migrate restore D:\backup.tar.gz --auto-map

修复已导入但路径错误的数据

# 如果之前没加 --auto-map 导入，重新导入
wb-migrate restore backup.tar.gz --auto-map

限制与注意

• 沙箱权限: 在 WorkBuddy Desktop 的「安全沙箱」模式下执行时，会弹出命令确认框，点击「允许」即可正常完成备份/恢复（整条命令执行期间不会再拦截）。也可切换为「完全放开」模式省去确认步骤。
• 二进制 (binaries/)、应用 (app/)、插件 (plugins/) 默认不备份
• 备份前建议关闭 WorkBuddy，避免数据库写入冲突
• 恢复时不覆盖已有数据，使用 --force 可强制覆盖
• 跨平台迁移时务必使用 --auto-map