workbuddy-asset-migration

name	workbuddy-asset-migration
description	在 WorkBuddy 国内版（~/.workbuddy/）和海外版（~/.workbuddy-ai/）之间，或跨机器之间，迁移用户个人资产（skills、memory、conversations、automations、sessions、MCP/connectors 配置、IDENTITY/SOUL/USER 等）。导出为单 zip 包，导入端默认只合并不覆盖。用于"用户在国内版用了很久、想切到海外版（或反过来），不想从零开始"的场景。支持 `--with-workspaces` 把项目工作目录一起搬走，`--path-map` 跨机器重写路径。触发关键词：WorkBuddy 迁移、资产迁移、国内版/海外版切换、换电脑搬家。
description_zh	WorkBuddy 国内版/海外版/跨机器之间迁移个人资产
description_en	Migrate WorkBuddy assets between CN/AI editions or across machines
version	0.2.0
allowed-tools	Read,Write,Bash

WorkBuddy 资产迁移

把一台机器（或一个 WorkBuddy 变体）上的个人资产打包，搬到另一台机器（或另一个变体）。导入端如果已经有数据，默认走"合并、不覆盖"策略，不会把现有的东西冲掉。

适用场景

• 国内版 ~/.workbuddy/ → 海外版 ~/.workbuddy-ai/（同机或跨机）
• 反向：海外版 → 国内版
• 同变体跨机器搬家（旧 Mac → 新 Mac、Mac → Linux）

快速开始

# 1. 在源端导出
python scripts/export.py --source auto --output ~/Desktop/wb-assets.zip

# 2. 把 zip 拷到目标机器（airdrop / scp / U 盘均可）

# 3. 在目标端导入（先 dry-run 看会做什么）
python scripts/import.py --package ~/Desktop/wb-assets.zip --target auto --dry-run
python scripts/import.py --package ~/Desktop/wb-assets.zip --target auto

重要：导入前请退出 WorkBuddy 客户端，否则 SQLite 写锁会拿不到，脚本会直接报错退出。

命令参数

export.py

参数	说明
--source <path|auto>	源根目录；auto 按 WORKBUDDY_CONFIG_DIR → ~/.workbuddy → ~/.workbuddy-ai 顺序探测
--output <path>	输出 zip 或目录（缺省 ./workbuddy-assets-<yyyymmdd-HHMM>.zip）
--no-conversations	不带 projects/*.jsonl（包体可大幅缩小）
--no-credentials	不带 .credentials.json（推荐跨机器使用）
--no-archive	输出目录树而非 zip

import.py

参数	说明
--package <zip|dir>	必填，迁移包路径
--target <path|auto>	目标根目录，auto 探测规则同 export
--overwrite	冲突时覆盖（默认 skip）；自动备份 .bak-<ts>
--dry-run	只打印计划，不动文件
--uid-map src=dst	重写 user_id（memory 文件名、connectors 子目录、sessions.user_id）
--no-conversations / --no-credentials	即便包里有也排除
--skip-db / --skip-skills / --skip-configs	分类排除（运维用）

冲突合并策略

资产	默认（无 --overwrite）
DB 表（sessions/automations/...）	INSERT OR IGNORE，同 id 保留导入端
Skills 同名目录	skip
memory/{uid}_memory.md	追加分隔符后 append，绝不删原内容
settings.json/mcp.json/models.json	浅 merge，导入端 key 优先
IDENTITY.md/SOUL.md/USER.md	已存在时落 *.imported.md，让用户手工合并
projects/*.jsonl 同 session	skip
.credentials.json	走 --no-credentials 推荐排除（OAuth token 跨机器易失效）

风险与限制

• 不迁移：认证 token（在 CodeBuddyExtension 目录下，机器/账号绑定）、日志、审计日志、binaries/、缓存
• OAuth token：跨机器、跨变体大概率失效，建议导入后到 connector 面板手动重新授权
• 多 uid：同机器多账号登录过时，必须用 --uid-map 显式映射，否则脚本拒绝执行避免数据混乱
• 备份：所有 .bak-<ts> 文件不自动清理，导入结束时 stdout 会列出位置和大小，自行决定何时删

跨机器 / 带 workspace（v0.2）

同机迁移（cn ↔ intl）—— 默认场景

不用动 workspace，对话和 workspace 是解耦的（同一台机器上 cn 和 intl 看到的是同一份 workspace 文件）。直接：

python scripts/export.py --source ~/.workbuddy --output ~/wb.zip --no-credentials
python scripts/import.py --package ~/wb.zip --target ~/.workbuddy-ai

跨机器迁移

跨机器只迁对话不够——目标机上没有源机的 workspace 路径，对话点开会失败。两种选择：

1. 只迁对话元数据（用户接受历史只是用来查阅，不能直接打开）：

   python scripts/import.py --package wb.zip --target ~/.workbuddy \
       --path-map /Users/old=/Users/new --target-os darwin
   

   sessions.cwd / workspaces.path / automations.cwds / meta.json 全部按 --path-map 重写，新机上找得到对应工作目录就能继续。

2. 连 workspace 文件一起搬（用户要把项目代码也带过去）：

   # 源端
   python scripts/export.py --source ~/.workbuddy --output ~/wb.zip \
       --with-workspaces                 # 多产出一个 ~/wb-workspaces.zip
   # 目标端
   python scripts/import.py --package ~/wb.zip \
       --workspaces-package ~/wb-workspaces.zip \
       --target ~/.workbuddy \
       --path-map /Users/old=/Users/new --target-os darwin
   

Agent 调用流程（dry-run JSON）

skill 自身不提问，由调用它的 host agent 负责跟用户交互。流程：

1. export.py --source auto --dry-run --with-workspaces → stdout 输出 JSON 计划
2. agent 解析 JSON，重点呈现给用户：
   • 主包大小（一般几 MB）
   • 每个 workspace 的 du、排除后大小、预估 zip 大小
   • caveats 段里的敏感物清单（.env 文件数、私钥数、symlink 数等）—— 这些默认会被带走，agent 必须主动告知用户，让用户决定是否要用 --workspace-exclude-pattern '*.env' 剔除
3. 用户决策后，agent 再调一次 export（不带 dry-run）正式打包
4. 用户在另一台机器接收包后，agent 跑 import.py --dry-run 看路径映射建议（自动从 manifest 的 source_home 推断），用户确认 --path-map 规则后正式 import

--with-workspaces 默认排除的内容

按 references/workspace_excludes.md 的清单——主要是 node_modules/、.git/、dist/、__pycache__/、.venv/、构建产物、缓存、本地 sqlite、镜像文件、*.log 等仓库型垃圾。

不在默认排除清单的：.env、私钥、secrets、credentials 等——这些是用户个人资产，默认全带，但 dry-run 会在 caveats 里列出，让 agent 转告用户做决定。

重启提示

导入完成后 stdout 会自动打印"请重启 WorkBuddy"。哪些资产需要重启：DB 表、models.json、settings.json、SOUL.md、USER.md、plugins/known_marketplaces.json。哪些热加载：mcp.json、IDENTITY.md、memory/、skills/。

内部参考

• 资产清单白名单：references/asset_inventory.md
• workspace 排除规则：references/workspace_excludes.md
• 完整 FAQ 与回滚步骤：README.md