交流群
迁移与导入导出
所有 Skill、MCP、工作流仅供个人学习测试，功能、计费、权限以 workbuddy.cn 官方为准。
本文涉及 WorkBuddy 专有路径、配置项、导出格式、密钥存储位置处，一律标注「待核验（以 workbuddy.cn 官方为准）」，请勿直接照搬路径到生产环境。
内容总览
本专题覆盖四类高频迁移与修复场景，均采用「通用方法论 + 分步骤操作 + 占位符模板」的写法。任何一步开始前，请先阅读本节末尾的三条铁律。
| 序号 | 专题 | 你将获得 | 关键风险点 |
|---|---|---|---|
| 1 | 跨机器迁移（换电脑 / 云机） | 六步闭环流程、迁移前检查清单、迁移后验证清单 | 未备份直接覆盖；版本不一致导致资产打不开 |
| 2 | 缓存目录迁移 | 缓存定位方法、迁移动作、符号链接与环境变量占位 | 路径写错导致客户端重建索引、磁盘反而翻倍 |
| 3 | 资产批量导出导入 | 导出范围决策表、批量导入检查清单、密钥脱敏规则 | 密钥 / 令牌随资产明文导出，造成泄露 |
| 4 | 损坏空间修复（空间打不开 / 索引重建） | 分级排查框架、索引重建通用步骤、回滚预案 | 在损坏副本上反复写操作，破坏恢复线索 |
三条铁律：① 导出 / 迁移任何资产前，先做一次完整备份再动手；② 密钥、令牌、Cookie 一律用占位符表示，禁止明文存储、禁止随资产明文导出；③ WorkBuddy 专有路径与机制一律「待核验」，以 workbuddy.cn 官方文档为准。
一、跨机器迁移（换电脑 / 云机）
跨机器迁移的本质是：在新机器上复原一个与旧机器「可验证等价」的工作环境，而不是简单拷文件。下面先看六步闭环流程图，再展开每一步的操作要点。
1.1 原理与分步骤操作
备份（旧机器）：关闭正在运行的长任务与索引任务，对配置目录、资产目录、会话记录做一次整盘复制备份，备份件单独存放、不与导出件混用。
导出（旧机器）：按「最小可用资产包」原则导出——只导走当前仍在使用的空间、Skill、MCP 配置；历史归档空间可暂不迁移。密钥 / 令牌不随资产包导出，迁移后在新机器手动重新录入。
传输：使用加密通道（加密压缩包 / 加密云盘 / 内网中转）传到新机器；传输完成后校验文件哈希，避免传输损坏。
导入（新机器）：新机器先安装与旧机器同版本号的客户端（版本号待核验，以官方下载页为准），确认登录态可用后，再导入资产包。
验证：按下文 1.3 验证清单逐项核对，全部通过才算迁移完成。
清理：验证通过并稳定运行至少 1–2 个工作日后，再清理旧机器上的敏感副本、临时导出件与传输缓存；清理前先确认新机器无回滚需求。
1.2 示例（官方专有处为占位符）
以「旧 Mac → 新 Windows 云机」为例（路径均为示意占位，待核验（以 workbuddy.cn 官方为准））：
text
# 旧机器：停止任务后打包配置与资产
# 配置目录：$WORKBUDDY_CONFIG_DIR（待核验）
# 资产目录：$WORKBUDDY_ASSETS_DIR（待核验）
# 注意：密钥/令牌不在这两个目录的导出范围内，需单独安全存放占位符
tar -czf workbuddy-migrate-YYYYMMDD.tar.gz \
"$WORKBUDDY_CONFIG_DIR" "$WORKBUDDY_ASSETS_DIR"
# 传输到新机器后校验哈希
sha256sum workbuddy-migrate-YYYYMMDD.tar.gz # 与旧机器输出比对
# 新机器：先装同版本客户端，再解压到对应目录（目录名待核验）
# 解压后手动在设置页重新录入：API Key / MCP Token / 登录态1.3 迁移后验证清单
| 序号 | 验证项 | 通过标准 | 失败处置 |
|---|---|---|---|
| V1 | 客户端版本号与旧机器一致 | 设置页版本号完全相同 | 降级 / 升级到匹配版本后重试 |
| V2 | 空间数量与命名一致 | 空间列表条目数、命名、层级与旧机器截图一致 | 重新导入缺失的空间 |
| V3 | 检索可用 | 选 3 个关键词，新旧机器命中结果一致 | 触发索引重建（见第四章） |
| V4 | Skill / MCP 可调用 | 抽 2 个常用 Skill 跑通一次最小调用 | 检查手动录入的密钥是否填错 |
| V5 | 登录态与权限 | 无需重复扫码即可访问云端同步内容 | 重新登录并核对账号权限 |
1.4 截图脚本占位清单
标记：待补：需在真实客户端按此清单截图。本文不包含、也不编造任何真实客户端截图。
| 截图序号 | 页面 | 要展示内容 | 标注 |
|---|---|---|---|
| 图 1-1 | 设置 → 关于 | 旧机器版本号，用于迁移前记录 | 红框圈出版本号 |
| 图 1-2 | 空间列表 | 迁移前完整空间层级，作为对照基准 | 标注「迁移前基线」 |
| 图 1-3 | 新机器设置 → 关于 | 新机器版本号，与图 1-1 对比 | 标注「须与基线一致」 |
| 图 1-4 | 新机器空间列表 | 导入后空间列表，与图 1-2 并排对照 | 标注「迁移后核对」 |
1.5 配套模板
迁移前检查清单（适配版本：待核验）
[ ] 已关闭所有长任务、索引任务与后台同步
[ ] 已记录旧机器客户端版本号
[ ] 已完成一次完整备份（配置 + 资产）
[ ] 已盘点哪些空间 / Skill 需要迁移，哪些归档暂不迁移
[ ] 已准备好新机器上手动录入密钥的安全渠道（不随包导出）
二、缓存目录迁移
当系统盘空间紧张，或缓存目录所在磁盘已满时，需要把缓存迁到大盘。缓存是可再生数据——迁移错了最多重建索引，不丢资产；但操作不当会让磁盘占用反而翻倍。
2.1 原理与分步骤操作
定位缓存目录：在设置页或官方文档中确认缓存目录位置（路径待核验（以 workbuddy.cn 官方为准））。先用文件管理器确认该目录体积确实占大头，再动手。
停客户端：完全退出客户端（含托盘进程），避免迁移过程中缓存仍在被写入。
复制而非剪切：先把整个缓存目录完整复制到目标大盘新路径，校验文件数量与体积一致后，再删旧目录。
让客户端认新路径：优先使用客户端自带的「缓存目录设置」改路径；若无此设置，再用操作系统级手段（环境变量 / 符号链接）指向新路径，具体机制待核验。
重启观察：启动客户端，确认它在新路径下读写、不再在旧路径重建一份缓存。
2.2 示例（占位符）
bash
# 1. 完全退出客户端后
# 2. 复制缓存目录到大盘
cp -a "$WORKBUDDY_CACHE_DIR" "/bigdisk/workbuddy-cache"
# 3. 确认体积一致后，再备份式改名旧目录（不立刻删）
mv "$WORKBUDDY_CACHE_DIR" "$WORKBUDDY_CACHE_DIR.bak"
# 4. 方式 A（优先）：在客户端设置页改缓存路径
# 方式 B（兜底，待核验是否支持）：建符号链接
ln -s "/bigdisk/workbuddy-cache" "$WORKBUDDY_CACHE_DIR"
# 5. 重启客户端观察 1–2 天，确认新路径持续增长、旧 .bak 不再变化后再删除 .bak2.3 预防 / 验证清单
| 检查点 | 正确做法 | 常见错误 |
|---|---|---|
| 迁移前 | 确认客户端已完全退出 | 托盘进程还在跑，导致文件占用 / 复制不全 |
| 迁移中 | 先复制校验，再改名旧目录留 .bak | 直接剪切，中途失败两头空 |
| 迁移后 | 观察新旧两个目录的体积变化 | 没观察，客户端又在旧路径重建了一份缓存 |
2.4 截图脚本占位清单
待补：需在真实客户端按此清单截图。
| 截图序号 | 页面 | 要展示内容 | 标注 |
|---|---|---|---|
| 图 2-1 | 设置 → 存储 / 缓存 | 缓存目录路径与占用体积 | 圈出路径与体积 |
| 图 2-2 | 文件管理器 | 大盘新缓存目录，与迁移前体积一致 | 标注「迁移后新路径」 |
三、资产批量导出导入
批量导出导入常见于：换机、归档、团队内分享模板、灾难恢复。核心原则：资产可以批量走，密钥绝不批量走。
3.1 导出范围决策
| 资产类型 | 是否随包导出 | 说明 |
|---|---|---|
| 空间内容 / 知识库文档 | 导出 | 批量迁移的主体，导入后按第四章做索引重建 |
| Skill / 工作流定义 | 导出 | 定义本身不含密钥；其中引用的密钥变量名保留，值不导出 |
| MCP / 外部连接配置 | 只导连接定义，不导凭证 | 导入后在新机器手动重填 Token / API Key（占位符 __TOKEN_PLACEHOLDER__） |
| 密钥 / 令牌 / Cookie | 禁止导出 | 禁止明文存储、迁移时不随资产明文导出；走单独的安全渠道 |
| 历史会话 / 聊天记录 | 按需 | 含敏感对话时建议不导出，或脱敏后单独处理 |
3.2 分步骤操作
圈定导出范围：按上表决策，列出本次要导出的空间 / Skill 清单。
导出前备份：同第一章铁律，先完整备份再导出。
批量导出：使用客户端批量导出能力（入口待核验），导出后检查导出包内不含任何形如真实 Key 的字符串。
脱敏抽查：解压导出包，全文搜索常见密钥前缀，确认无明文泄露。
导入：新机器导入后，逐项手动重填密钥，并跑一次最小调用验证。
3.3 配套模板：导出包脱敏自检脚本说明
下面脚本只做模式匹配自检，不存储任何真实密钥。适配版本：待核验。
bash
# 解压导出包后，在包目录内扫描疑似明文密钥
# 仅做"是否命中"检查，命中即停止分发，回去脱敏
grep -rEn "(sk-|api[_-]?key|token|secret|Bearer )" ./exported-pkg/ \
--include="*.json" --include="*.yaml" --include="*.env"
# 预期：无命中。有命中 = 导出包可能含明文密钥，禁止外传 / 上传3.4 截图脚本占位清单
待补：需在真实客户端按此清单截图。
| 截图序号 | 页面 | 要展示内容 | 标注 |
|---|---|---|---|
| 图 3-1 | 批量导出入口 | 导出范围勾选界面 | 圈出「不含凭证」类选项（若有） |
| 图 3-2 | 导入后连接配置页 | 密钥输入框为占位 / 空状态 | 标注「此处手动重填，禁止粘贴明文备份」 |
四、损坏空间修复（空间打不开 / 索引重建）
本章写的是通用排查与修复框架，不是某一次具体故障的复盘。遇到空间打不开、检索报错、索引丢失时，按「先取证、再分级、后修复」的顺序处理，切忌在损坏副本上反复写操作。
4.1 分级排查框架
L0 先取证：在动手前，对损坏空间所在目录做一次只读复制备份，保留现场。后续所有修复都在副本上尝试。
L1 判断故障面：是「单个空间打不开」还是「整个客户端 / 所有空间都异常」？前者偏向单空间索引问题，后者偏向客户端配置或版本问题。
L2 重启与版本：完全退出重启；核对是否刚升级过版本、是否存在版本与资产格式不匹配（版本兼容对照见本站《版本兼容对照表》）。
L3 索引重建：单空间内容可读但检索 / 列表异常时，对该空间触发索引重建（入口与机制待核验（以 workbuddy.cn 官方为准））。
L4 恢复备份：索引重建无效时，用 L0 的只读备份回滚该空间，或从最近一次正常备份恢复。
4.2 索引重建通用步骤
重建前确认：待重建空间的原始文档源（云文档 / 本地文件）仍然完好——索引只是再生数据，源文档丢了重建无意义。
重建期间：不要对该空间做大量写入；重建耗时与空间体量正相关（具体时长口径待核验）。
重建后：用 1.3 验证清单中的 V3（检索命中）做抽查。
4.3 预防 / 验证清单
| 阶段 | 动作 |
|---|---|
| 日常预防 | - 重要空间定期导出备份 - 升级客户端前先看版本兼容对照表 - 不在低磁盘空间环境下跑大批量索引任务 |
| 修复后验证 | - 空间可正常打开、列表完整 - 抽词检索命中正常 - Skill / MCP 最小调用跑通 - 观察 1–2 个工作日无复现再结案 |
4.4 截图脚本占位清单
待补：需在真实客户端按此清单截图。
| 截图序号 | 页面 | 要展示内容 | 标注 |
|---|---|---|---|
| 图 4-1 | 空间异常提示页 | 报错原文（打码敏感信息），用于取证 | 标注「修复前现场」 |
| 图 4-2 | 索引重建入口 / 进度 | 重建操作位置与进度状态 | 标注「L3 索引重建」 |
| 图 4-3 | 修复后空间列表 | 恢复后的空间与检索结果 | 标注「修复后核对」 |
进阶：平时该怎么备份，才不至于换机重来
用一段时间后，你会积累三样真正值钱的东西：配置与偏好、任务 Prompt 模板、项目记忆文件。这三样比客户端本身更值得备份，换机、重装、升级出问题时能不能无损迁过来，全看平时有没有做。
按重要性排：
- Prompt 模板与
CODEBUDDY.md：纯文本，最容易备份，也最值钱。 - 定时任务配置：记下每个任务的触发时间和绑定的 Prompt，写一份文字清单就够。
- 客户端缓存目录：有历史任务记录，量大但可重建，优先级最低。
不该备份的： 明文密钥和令牌（备份文件一旦泄露就是事故）、体积巨大的临时日志。
六步做一次完整备份：
- 建目录，例如
D:\WorkBuddyBackup\2026-11-12\。 - 把所有项目的
CODEBUDDY.md和沉淀下来的 Prompt 模板整体复制进去。 - 定时任务列表导出一份文字版清单。
- 需要的话，把客户端缓存目录打个压缩包，放到数据盘或外置硬盘。
- 换机时按顺序恢复：装新客户端 → 还原工作目录 → 放回
CODEBUDDY.md与 Prompt 模板 → 按清单重建定时任务。 - 最后跑一个只读小任务验证，确认新机器上一切正常，再删旧机器。
text
D:\WorkBuddyBackup\2026-11-12\
├─ prompts\ # 沉淀的所有任务 Prompt 模板
├─ projects\ # 各项目的 CODEBUDDY.md
├─ schedules.md # 定时任务清单（时间 + 绑定哪个 Prompt）
└─ config-notes.md # 客户端关键设置项截图或文字记录频率上，每月一次，或者每次大改配置之后补一次，足够了。
关联文档与收尾
版本号 / 资产格式兼容性：见本站《版本兼容对照表》。
迁移后如何验收资产是否完整：见本站《资产验收测试标准》。
迁移打包的最小可用资产清单：见本站《最小可用配套资产包》。
更多 WorkBuddy 实战玩法（迁移避坑、缓存瘦身、索引自救）会持续更新在本知识营地。欢迎到小红书「牛班长的创业日志」一起交流工具玩法，本文为个人实践记录，供参考。
（注：部分内容由豆包工作 AI 生成）