WorkBuddy 环境迁移恢复
> 换电脑不停工。三模块完成备份→打包→释放，或扫描诊断修复已有文件。
快速启动
能看到本技能？ → 直接 @skill 调用，选择模块。
看不到本技能？ → 跳到文末「零基础启动」——一个命令即可。
主流程：三模块工作流
旧电脑 新电脑
─────── ───────
模块一：备份 模块三：释放
↓ 生成「移动资料」文件夹 ↑ 从移动资料恢复
模块二：打包 ↑
↓ 打包为 .zip → 传到新电脑 ↑
模块一：备份移动资料
用途：将当前 WorkBuddy 环境的核心资产自动集中到一个文件夹，方便同步。
python scripts/workbuddy_mobile_assets.py
自动备份的 11 项资产：
| 资产 | 来源 |
|---|---|
| 自定义技能（用户目录） | ~/.workbuddy/skills/ |
| 自定义技能（工作区） | 工作区 .workbuddy/skills/ |
| 全局偏好 | ~/.workbuddy/MEMORY.md |
| 技能记录 | ~/.workbuddy/SKILLS_RECORD.md |
| MCP 配置 | ~/.workbuddy/mcp.json |
| 自动化任务 | ~/.workbuddy/workbuddy.db |
| 身份文件 | ~/.workbuddy/IDENTITY.md |
| 专家配置 | ~/.workbuddy/experts/ |
| 项目记忆 | 工作区 .workbuddy/memory/ |
| 对话记录 | ~/.workbuddy/conversations/ |
| 自动化配置 | ~/.workbuddy/automations/（如存在） |
输出：移动资料_WorkBuddy/ 文件夹（工作区根目录），零交互自动覆盖。
✅ 检查点：备份完成
- 展示：备份资产清单 + 源路径 → 目标路径映射
- 确认：清单无遗漏，同步盘已覆盖
移动资料_WorkBuddy/ - 拒绝时：列出遗漏项，用户指定后追加备份
模块二：打包
用途：将「移动资料」文件夹打包为单个 .zip 文件，生成桌面快捷方式。
python scripts/workbuddy_package.py
参数：
- --desktop PATH — 指定桌面路径（自动检测不准时使用）
- --auto — 跳过交互确认，全自动执行
输出：移动资料_WorkBuddy.zip → 复制到新电脑后解压即可。
✅ 检查点：打包完成
- 展示：.zip 文件路径 + 大小 + 文件数 + 快捷方式位置
- 确认：.zip 可正常解压，快捷方式指向正确
- 拒绝时：提示手动打包命令或重试参数
模块三：释放恢复
用途：在新电脑上，从「移动资料」文件夹恢复全部资产到正确位置。
python scripts/workbuddy_release.py
差异报告：释放前自动对比新旧版本，列出新增/保留/修改/不变的技能清单，以及单文件差异。用户确认后再执行，避免误覆盖。
合并释放：skills/ 目录采用合并策略——保留旧环境独有的技能，仅覆盖/新增同名技能，不会造成数据丢失。
自动恢复 11 项：与模块一备份资产一一对应，逐项恢复到正确路径。
平台检测：自动识别 Windows/macOS/Linux，使用正确路径。
✅ 检查点：释放完成
- 展示：恢复报告（成功 X/11，跳过 Y，失败 Z）+ 详细路径
- 确认：重启 WorkBuddy 后技能列表完整 + 中文名正确
- 拒绝时：逐项手动修复失败项，或回滚到备份
统一入口
不记得用哪个模块？运行统一菜单：
python scripts/workbuddy_migrate.py
命令行参数：
- --backup → 直接执行模块一
- --package → 直接执行模块二
- --release → 直接执行模块三
- --auto → 全自动模式（跳过所有确认）
- --desktop PATH → 指定桌面路径
诊断修复模式
> 适用场景：文件已在正确位置，但技能显示异常（名称英文、不显示等）。
第一步：扫描
扫描 ~/.workbuddy/skills/ 下所有 skill_* 目录：
| 检查项 | 正常 | 异常 |
|---|---|---|
| 目录名格式 | skill_* |
非标准命名 |
_skillhub_meta.json |
存在 + JSON 有效 | 缺失/解析失败 |
name 字段 |
中文名 | 空/英文 |
skillId |
与目录名一致 | 不匹配 |
iconSource |
有效值 | 含反斜杠 |
✅ 检查点：扫描结果
- 展示：扫描摘要（共 N 个技能，M 个异常）+ 异常明细
- 确认：修复列表无误后进入修复
- 拒绝时：调整范围（仅修复用户选定的项）
第二步：修复
python scripts/sinicize_skills.py
名称修复优先级：
1. 有 SKILLS_RECORD.md → 按映射表写入（最准）
2. 无记录 → 读 SKILL.md frontmatter name: 字段
3. 以上均无 → 用目录名作临时名，提示确认
第三步：验证
- JSON 验证：
python scripts/workbuddy_env_restore.py自动完成 - UI 验证：重启 WorkBuddy，检查技能列表
✅ 检查点：验证完成
- 展示：修复后摘要 + JSON 验证结果
- 确认：提醒重启，用户确认后结束
- 拒绝时：回退到修复前状态，逐项排查
排障速查
| 现象 | 原因 | 修复 |
|---|---|---|
| 技能不显示 | 目录名非 skill_* |
重命名 |
| 技能不显示 | 仅在工作区目录 | cp -r 到用户目录 |
| 中文名不显示 | name 为空/英文 |
运行 sinicize_skills.py |
| JSON 报错 | iconLocalPath 反斜杠 |
改为 letter:auto |
| 市场技能名被还原 | WorkBuddy 升级覆盖 | 重跑修复 |
| 打包找不到桌面 | 沙箱路径问题 | 加 --desktop PATH 参数 |
日常维护
每次技能/配置变更后，同步盘自动同步以下文件即可：
| 资产 | 路径 |
|---|---|
| 全局偏好 | ~/.workbuddy/MEMORY.md |
| 身份文件 | ~/.workbuddy/IDENTITY.md |
| 技能记录 | ~/.workbuddy/SKILLS_RECORD.md |
| 自定义技能 | ~/.workbuddy/skills/ |
| MCP 配置 | ~/.workbuddy/mcp.json |
配套资源
| 路径 | 用途 |
|---|---|
scripts/workbuddy_mobile_assets.py |
模块一：备份移动资料（11项资产） |
scripts/workbuddy_package.py |
模块二：打包为 .zip + 桌面快捷方式 |
scripts/workbuddy_release.py |
模块三：释放恢复到新电脑 |
scripts/workbuddy_migrate.py |
统一入口：交互菜单 + 命令行参数 |
scripts/sinicize_skills.py |
技能中文化批量修复 |
scripts/workbuddy_env_restore.py |
一键诊断修复脚本（旧版，功能被模块脚本覆盖） |
references/skills_record_template.md |
名称映射模板 |
references/checklist.md |
检查清单 |
零基础启动
> 刚装 WorkBuddy，什么技能都看不到？用下面命令自救：
python scripts/workbuddy_release.py
前提：同步盘里有「移动资料_WorkBuddy」文件夹。
还没有这个文件夹？先在旧电脑上运行 python scripts/workbuddy_mobile_assets.py。
详细图文步骤（含 Windows/macOS/Linux 三平台截图指引）→ 见 references/checklist.md。
还不行？
在 WorkBuddy 对话里输入：
找出为什么技能列表为空：
1. 列出 ~/.workbuddy/skills/ 下的所有目录
2. 检查 _skillhub_meta.json 是否存在
3. 给出具体修复步骤
