前言¶
WorkBuddy 国内版把技能、记忆、对话、连接器与身份设定都落在本机 ~/.workbuddy/。换电脑时若只拷贝其中一两个目录，往往会出现对话能打开但产物路径失效、MCP 要重新授权、或 SQLite 被客户端占用导致写入失败。
手工打包又容易漏掉 DB 表、artifact-index、自动化备份等分散资产。下面介绍社区 Skill「WorkBuddy迁移助手」：用导出/导入脚本和两包分离结构，把搬家流程收成可复现的主线六步。
这是什么¶
WorkBuddy迁移助手是 SkillHub 上的社区 Skill，坐标 @user_73de2035/workbuddy-migration-assistant，当前版本 2.0.0，分类 it-ops-security，发布者为 user_73de2035，requires_api_key=false。
它面向 WorkBuddy 国内版（官方说明适配客户端 5.7.6）的跨机器场景：在旧机导出全部个人资产，传到新机后合并导入，并做路径映射与导入后校验。SkillHub 页面简介概括为：一键导出/导入技能、记忆、对话、配置、连接器凭证、会话产物索引等，两包分离传输、路径自动映射、导入后自动校验，按主线六步完成搬家。
官方入口：
- API：
https://api.skillhub.cn/user_73de2035/workbuddy-migration-assistant - 展示页：
https://www.skillhub.cn/skills/user_73de2035/workbuddy-migration-assistant
核心功能¶
以下能力均来自 Skill 的 SKILL.md 与 SkillHub 检索摘要，可按需由 Agent 加载 references/ 下的命令与排障文档。
资产覆盖范围¶
迁移目标为 ~/.workbuddy/ 下的个人数据，包括但不限于：
- 技能与记忆：
skills/、memory/、MEMORY.md - 对话与自动化：
projects/（历史对话）、DB 中的 sessions/automations 等；automation-backups/ - 连接器与 MCP：
settings.json、mcp.json、connectors/、.credentials.json（OAuth 凭证，可用--no-credentials排除） - 身份与个性化：
IDENTITY.md、SOUL.md、USER.md，以及app/app-config.json中personalization.*子树 - 其它：专家与插件、artifact-index、行业 Buddy 快照、工作区信任决策等
平台相关二进制、日志、设备绑定标识、认证 token 等明确不迁移（见 Skill 内「绝对不迁移的」清单）。
两包分离¶
| 包 | 典型文件名 | 内容 | 是否必传 |
|---|---|---|---|
| 主包 | wb-migration-{timestamp}.zip |
DB、技能、配置、身份、记忆、连接器、对话元数据等 | 必须 |
| 产物包 | wb-migration-{timestamp}-workspaces.zip |
对话工作目录下的文件（代码、报告、下载等）；对应 ~/WorkBuddy/，需 --with-workspaces 或 full 类配置 |
可选 |
主包体积小，便于网盘或即时通讯传输；产物包可后补，丢失不影响主包导入（对话可能可回顾但无本地文件）。
导入策略与跨平台¶
- 默认合并不覆盖：目标机已有内容保留，仅补充缺失；需覆盖时使用
--overwrite。 - 路径映射：跨平台推荐
--auto-map，或使用--profile auto做零配置映射（含 artifact-index 的 URL 编码路径重写）；本机从 backup 包恢复时文档建议用--auto-map以免凭证路径问题。 - 冲突与校验：导入前可用
--dry-run预览合并计划；正式导入后输出 verify 报告（如「N/N 项全部就位」）。 - 预设：
--profile lite（快速换机）、full（含对话工作目录文件）、backup（本机备份）；新机导入常用--profile auto。
Agent 分派方式¶
Skill 不自行追问用户，由宿主 Agent 根据意图进入导出（流程 A）、导入（流程 B）或检视包（流程 C）。常见触发词包括：WorkBuddy 迁移、资产迁移、换电脑搬家、迁移助手、搬家工具、数据迁移。
安装与启用¶
安装 SkillHub CLI¶
若尚未安装 CLI，可先检查版本：
command -v skillhub && skillhub --version
未安装时，可按 SkillHub 官方安装文档执行完整安装（节选）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
文档地址：https://skillhub.cn/install/skillhub.md（亦可通过 https://www.skillhub.cn/install/skillhub.md 访问）。
安装本 Skill¶
SkillHub 页面提示：根据上述安装文档，安装 @user_73de2035/workbuddy-migration-assistant。
在 WorkBuddy 环境中，技能应装入 WorkBuddy 的 skills 目录（安装文档列出 workbuddy: ~/.workbuddy/skills/）。示例：
skillhub install workbuddy-migration-assistant --namespace user_73de2035 --dir ~/.workbuddy/skills/
若在 Cursor 等其它 Agent 中仅希望把 Skill 装进该 Agent 的目录，需将 --dir 改为对应当前环境的 skills 路径（如 Cursor 为 ~/.cursor/skills/），并重启或刷新 Agent 以便识别新 Skill。本 Skill 的业务脚本针对 ~/.workbuddy/ 数据目录，实际搬家仍建议在已安装 WorkBuddy 客户端的机器上由 Agent 调用 Skill 内的 scripts/export.py / scripts/import.py。
安装完成后，对 Agent 说明需求即可（例如「WorkBuddy 换电脑，帮我按迁移助手导出」），无需额外 API Key。
典型用法：主线六步¶
下列命令在 Skill 安装目录下执行（路径以你本机 --dir 安装结果为准），python 优先使用 WorkBuddy 自带的 managed Python；系统 Python 3.8+ 亦可。
第 1 步 · 选场景：换机常用 --profile lite；需要对话工作目录文件时用 full；仅本机备份用 backup。
第 2 步 · 旧机导出：
python scripts/export.py --source auto --output ~/Desktop/wb.zip --profile lite
预期看到 Profile 与各资产 copied，以及主包路径；错误行以 [E-xxx] 稳定错误码开头，可对照 references/faq.md。
第 3 步 · 传包：将 wb.zip 拷到新机。若使用 full，另传 wb-workspaces.zip；产物包丢失不影响主包导入。
第 4 步 · 新机预检：
python scripts/import.py --package ~/Desktop/wb.zip --profile auto --dry-run
查看 would-merge 计划与冲突预览，确认后再写入。
第 5 步 · 新机正式导入：
python scripts/import.py --package ~/Desktop/wb.zip --profile auto
导入前须退出 WorkBuddy 客户端；若沙箱 strip_write 拦截写入，需按 Skill 说明关闭沙箱后重跑（幂等可续传）。成功后应看到合并结果与资产校验，并提示重启 WorkBuddy。
第 6 步 · 重启验证：完全退出并重新打开 WorkBuddy，确认 verify 为全部就位，旧对话与技能可用。
更细的输出样例与 JSON 字段说明见 Skill 内 references/walkthrough.md。
适用场景与注意¶
适合：WorkBuddy 国内版换电脑（Windows / macOS / Linux 互迁）、本机备份与恢复、在可控前提下做多机同步。
不适合：同机国内版与海外版互迁（Skill 明确应使用「WorkBuddy 资产迁移」类其它技能）。
操作注意（来自 Skill 关键约束）：
- 导入前退出客户端，避免 SQLite 写锁失败。
- 导入前确认沙箱不会剥写核心配置；被拦截时关闭沙箱后重跑。
- 默认不覆盖目标机已有资产；跨机 OAuth 凭证常失效，推荐
--no-credentials并在新机连接器面板重新授权。 - 导入后必须重启客户端，settings、models 等才会生效。
- 同机国内版↔海外版、设备 ID、日志缓存等不在迁移范围，勿指望靠本 Skill 带上。
SkillHub 统计（以脚本抓取为准）：评分 100000，下载 29756 次。
结尾¶
WorkBuddy迁移助手把换机时的分散目录收成「导出两包 → 传输 → dry-run → 合并导入 → 校验 → 重启」的固定流程，并处理路径映射与冲突预览。若你正在更换运行 WorkBuddy 的机器，可在 SkillHub 安装该 Skill 后，让 Agent 按主线六步驱动脚本完成搬家。
官方地址：https://api.skillhub.cn/user_73de2035/workbuddy-migration-assistant
SkillHub 页面：https://www.skillhub.cn/skills/user_73de2035/workbuddy-migration-assistant
