WorkBuddy 迁移助手

将一台旧电脑上的 WorkBuddy 国内版（~/.workbuddy/）全部个人资产，完整迁移到新电脑。两包分离、路径自动映射、冲突可见可控。

本文档只保留入口分派与关键约束。命令参数、流程图、冲突规则、已知问题等细节按需加载 references/（见文末索引）。

快速开始

# 导出（旧电脑）
python scripts/export.py --source auto --output ~/Desktop/wb.zip

# 导入（新电脑，自动跨平台路径映射）
python scripts/import.py --package ~/Desktop/wb.zip --auto-map --dry-run
python scripts/import.py --package ~/Desktop/wb.zip --auto-map

# 检视迁移包
python scripts/info.py --package ~/Desktop/wb.zip

python 优先使用 WorkBuddy managed Python，也可用系统 Python 3.8+。

适用场景

不适用：同机国内版↔海外版迁移（请使用 WorkBuddy 资产迁移 技能）。

资产范围全景

迁移覆盖 WorkBuddy 个人数据的全部资产类型：

~/.workbuddy/
├── workbuddy.db              → DB 表（sessions/automations/workspaces）
├── skills/                   → 所有已安装技能包
├── memory/                   → {uid}_memory.md 记忆文件
├── MEMORY.md                 → 根级长期记忆（5.3.3+，双轨并存）
├── settings.json             → 应用设置
├── mcp.json                  → MCP 连接器配置
├── models.json               → 模型配置
├── IDENTITY.md               → 人格身份定义
├── SOUL.md                   → 灵魂设定
├── USER.md                   → 用户信息
├── connectors/{uid}/         → 连接器状态与凭证
├── connectors/skills/        → 连接器技能包（connector-*，5.3.11+）
├── automation-backups/       → 自动化配置备份
├── brain/                    → 研究计划数据
├── todos/  plans/  deliverables/ → 任务/计划/交付物数据
├── experts/                  → 自定义专家（含专家团），4.24.0+
├── plugins/                  → 仅 known_marketplaces.json + 自建专家包(my-experts)
├── projects/                 → 所有历史对话记录（.jsonl + meta.json）
└── ~/WorkBuddy/              → 对话工作目录（代码生成产物、下载文件等）
                                  ⚡ 仅通过 --with-workspaces 打包

绝对不迁移的

两包分离架构

导出产出两个独立 zip，职责完全解耦：

设计意图：

• 主包小而精，可用网盘/微信快速传输
• 产物包独立传输（U盘、局域网、大文件分享），下载失败不影响主包导入
• 用户可不传产物包，仅让对话历史在新机上"可回顾但无文件"，后续按需补传

关键约束（每次执行必须遵守）

1. 导入前必须退出 WorkBuddy 客户端（SQLite 写锁冲突会导致导入失败）
2. 必须排除当前迁移会话（防止目标端出现僵尸对话）——优先级：环境变量 → 源端 DB 最新 session → --exclude-session-id
3. 默认合并不覆盖（目标端已有资产保留，仅补充缺失），除非显式 --overwrite
4. 跨平台必做路径映射：推荐 --auto-map（零配置），或手工 --path-map + --target-os
5. 导入后必须重启：DB、models.json、settings.json 等需要重启才能生效
6. 导入前先用 dry-run 预览：导出看计划、导入看冲突报告，确认后再正式执行
7. 推荐跨机排除凭证：--no-credentials（OAuth token 跨机大概率失效），目标端到连接器面板重新授权

Agent 调用入口分派

skill 自身不提问，由 host agent 交互。按意图关键词直接分发，不做多余预扫描：

完整分派流程、步骤 0 资产扫描、流程 A/B/C：见 references/flows.md

内部参考（按需加载）