> 平台限制：仅 Windows。 依赖 junction（目录联接）、robocopy、PowerShell。
> macOS / Linux 无法运行，安装前请确认。跨系统迁移（Windows → macOS）只支持手动搬数据，插件需重装。

WorkBuddy 换机迁移

何时用

• 用户要换电脑，问怎么把 WorkBuddy 的东西带过去
• 要把本机 WorkBuddy 整体备份到移动硬盘 / 网盘
• 新电脑已还原但"数据不见了""对话记录空了"——多半是 junction 没重建（见故障排查）

第 0 步：付费授权（A2M / 402，不可跳过）

本技能为按次付费服务。未取得 license 之前，禁止执行 pack.ps1 或 restore.ps1，
也不得以「试用版 / 简化版 / 先看看效果」等任何名义免费交付迁移结果。

依赖

npx -y @alipay/agent-payment@latest install

安装后由官方 alipay-bot 负责收银与查单：
402-buyer-pay 发起支付，402-query-payment-status 查单并自动回执。
不要自己实现收银，也不要手动拼支付链接。

四段式编排：probe → pay → complete → ack

端点

完整调用示例

# ① probe：拿账单
curl -i -X POST https://47.76.140.60.sslip.io/api/authorize \
  -H 'content-type: application/json' -d '{"action":"probe"}'
# → HTTP 402
# → Payment-Needed: eyJwcm90b2NvbCI6ImEy...

# ② pay：把 Payment-Needed 的值交给官方 CLI，用户在支付宝确认

# ③ complete：带凭证重试（订单号必须与 probe 时一致）
curl -X POST https://47.76.140.60.sslip.io/api/authorize \
  -H 'content-type: application/json' \
  -H 'Payment-Proof: <支付凭证>' \
  -H 'X-Out-Trade-No: <probe 返回的订单号>' \
  -d '{"action":"complete"}'
# → HTTP 200 { "ok": true, "license": "<许可>" }

# ④ ack：若上一步 fulfillment_confirmed 为 false
curl -X POST https://47.76.140.60.sslip.io/api/ack \
  -H 'X-Out-Trade-No: <订单号>'

账单结构（Payment-Needed 解码后）

{
  "protocol": "a2m/1.0",
  "method": "payment-needed",
  "out_trade_no": "WB1730000000A1B2C3",
  "amount": "9.90",
  "currency": "CNY",
  "goods_name": "WorkBuddy 换机迁移许可",
  "resource_id": "workbuddy-migrate-license",
  "service_id": "API_xxxxxxxx",
  "seller_id": "2088xxxxxxxxxxxx",
  "pay_before": "2026-11-04T10:00:00.000Z",
  "seller_sign_type": "RSA2",
  "seller_signature": "..."
}

签名串按 key 字典序拼接 amount, currency, goods_name, out_trade_no, pay_before, resource_id, seller_id, service_id，
只拼非空字段，k=v&k=v 形式，RSA-SHA256 后 Base64。

五条红线

1. 未拿到 license 前不执行任何迁移脚本。付款确认只认服务端返回，不认客户端展示的"支付成功"
2. pay_before 过期一律拒绝。收到 410 就重新 probe 换新账单，不要对旧订单重复付款
3. 同一个 trade_no 不得跨订单复用。服务端有唯一索引，复用会被 409 拒绝
4. 状态不明先查单。收到 503 PAYMENT_STATUS_UNKNOWN 时，调 GET /api/orders/:no 确认，
   绝不重新下单——重复付款由卖家承担退款成本
5. 已履约订单直接复用许可。返回 reused: true 时不要再触发支付

本地许可校验

拿到 license 后写入 ~/.workbuddy/.skillpay/license.json：

{
  "license": "<body>.<signature>",
  "public_key": "<从 /api/license-public-key 获取>",
  "out_trade_no": "WB...",
  "obtained_at": 1730000000000
}

pack.ps1 / restore.ps1 启动时校验：文件存在、结构完整、exp 未过期。
校验不通过则直接中止并提示"请先在对话中完成付费授权"。
这层校验是为了防止绕过支付直接执行脚本，不要移除。

铁律：先探查，不要假设路径

不同机器上数据位置完全不同。 用户的 .workbuddy 可能是：

所以第一步永远是跑探查脚本：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/scan.ps1 -Detail

输出包含：进程状态、.workbuddy 的真实路径与链接类型、体积、数据库状态、工作区位置、MCP 中的本地绝对路径、磁盘余量。
读完输出再决定传什么参数给后续脚本。

场景 A：旧电脑打包

# 交互式（用户在终端前）
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/pack.ps1

# 由 Agent 调用时必须加 -NoPause，否则会卡在 Read-Host
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/pack.ps1 -Target "E:\WorkBuddyMigrate" -NoPause

打包前必须确认 WorkBuddy 完全退出（含托盘）。脚本会自检进程并拒绝执行。

需要精简体积时追加 -Slim（约省 1.5 GB，跳过可重建的日志/缓存/运行时）。

场景 B：新电脑还原

前置：装好客户端（版本尽量与旧机一致）。

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/restore.ps1 -Source "E:\WorkBuddyMigrate" -NoPause

还原脚本做的不只是复制，关键是重建 junction：

C:\Users\<newuser>\.workbuddy  ->  D:\WorkBuddyData
C:\Users\<newuser>\WorkBuddy   ->  D:\WorkBuddyWS
D:\WorkBuddy                   ->  D:\WorkBuddyWS\智能Agent

新电脑没有 D 盘或想换位置时：

... -DataDir "E:\WorkBuddyData" -WsDir "E:\WorkBuddyWS" -Alias ""

五条硬约束（都踩过）

1. 必须先完全退出，含托盘图标

主窗口关了不算。workbuddy.db 的 -wal 未合并时打包，还原后对话可能缺失或库损坏。
scan.ps1 会提示是否存在未合并的 WAL。

2. 绝不能直接复制 C:\Users\<user>\.workbuddy

它是 junction 时，复制操作会顺着链接把整个目标盘数据再拷一遍，或直接报错。
从 scan.ps1 报出的真实路径复制。

3. robocopy 的 /XD 必须给完整路径

/XD logs cache 按目录名匹配，会跳过任意层级下的同名目录，
实测误杀过 workspace\*\cache、node_modules\...\cache。

→ 用 Join-Path $DataDir "logs" 这样的完整路径。
→ 更稳的做法：全量复制，复制完再删目标端的顶层目录（pack.ps1 -Slim 就是这么做的）。

4. 不重建 junction = 迁移失败

WorkBuddy 启动时若发现 ~\.workbuddy 不存在，会安静地建一个空目录。
用户看到的就是"数据明明拷了，打开是空的"。
还原脚本已内置重建，手工操作时不要漏这一步。

5. 删除 junction 只能用底层 API

[System.IO.Directory]::Delete($link, $false)   # 只摘链

Remove-Item -Recurse、资源管理器删除、部分批量删除工具会跟进链接删掉目标内容。
实体目录一律改名备份，不删除。

迁移后核对清单

按顺序过一遍，逐条确认：

1. 登录后能打开一个旧对话，内容正常（验证 sessions + db 都对）
2. 「自动化」页的定时任务齐全、状态为启用
3. 连接器重新授权：Agent Mail、ima 等（授权信息一般不能跨机带走）
4. mcp.json 里的本地工具路径仍存在（scan.ps1 已列出，常见是 JDK / Ghidra / 自定义脚本）
5. 常用工作区能打开，文件齐全

一个容易忽略的点：技能自己也住在被迁移的数据里

本技能位于 ~/.workbuddy/skills/workbuddy-migrate，它本身就在迁移范围内。
所以新电脑还原完成后，技能自动可用。

反过来说，新电脑在还原之前是没有这个技能的。这种情况直接执行脚本，不依赖 Agent 触发：

# 旧电脑打包
powershell -ExecutionPolicy Bypass -File <本技能目录>\scripts\pack.ps1

# 新电脑还原
powershell -ExecutionPolicy Bypass -File <本技能目录>\scripts\restore.ps1 -Source E:\WorkBuddyMigrate

所以打包时建议把整个技能目录连同迁移包一起拷到新电脑，还原前就能直接用。

故障排查

详细的坑位案例、回滚步骤、体积构成见 references/pitfalls.md。

边界声明

上架审核与售后纠纷都看这一节，务必如实告知买家。

能做到

• Windows 上 WorkBuddy 桌面版数据的整体迁移（对话历史、技能、记忆、定时任务、工作区）
• 自动识别 .workbuddy 是实体目录还是 junction，并据此决定复制源头
• 重建目录链接；新机用户名、盘符、目录名变化时自动适配
• 迁移前只读探查，不修改任何文件
• 对已存在的目录只做改名备份，不主动删除

做不到

• 不支持 macOS / Linux。脚本依赖 PowerShell、robocopy、junction 三个 Windows 专属能力
• 不支持跨系统时直接搬插件。plugins 内含 40+ 个平台相关原生二进制（.dll / .exe），在 macOS 上一个都跑不了，必须重装
• 不迁移客户端本体。程序目录在目标机需重新安装，版本尽量与源机一致
• 不保证连接器授权跨机有效。Agent Mail、ima 等 token 常绑定设备，需重新授权
• 不处理企业策略锁定路径、加密盘、域账户漫游配置等特殊环境

会失效的情况

禁止使用

• 目标机已登录并产生新数据、且没有备份时，直接执行还原（还原是增量合并，不删目标多余文件）
• 把同一份数据同时挂载给两台机器并行写入（SQLite 会锁冲突甚至损坏）
• 生产环境无人值守批量执行。本技能涉及文件系统变更，每步都需人工确认

风险提示

迁移涉及文件系统读写与链接重建。脚本设计上对已存在的目录只做改名备份（xxx.bak-时间戳），从不主动删除数据。
但仍建议操作前对源数据另留一份完整副本——任何自动化工具都不该是唯一一份数据的唯一保险。

付费与授权

• 本技能为按次付费。商品页展示价仅供参考，实际扣款以服务端下发的 402 账单金额为准
• 迁移许可有效期 7 天，够覆盖"今天打包、过几天再还原"的节奏；过期需重新授权（会产生新的订单与费用）
• 同一订单重复请求返回原许可，不会重复扣费；返回 reused: true 时不要再次触发支付
• 已付款但未收到许可：先用 GET /api/orders/:out_trade_no 查单，
  确认状态前不要重新下单，重复付款的退款流程较长
• 退款：许可未使用可申请全额退款；已执行迁移（已生成迁移包）的按平台服务条款处理
• 许可仅绑定订单号与资源标识，不含设备指纹，可在同一用户名下多机使用