WorkBuddy 配置同步
用途
在没有 Git、SSH 或不方便联网的场景下，用「打包 → 手动搬运 → 解析应用」三步，
把一台机器的 WorkBuddy 配置搬到另一台。
导出包是自包含的：内含导入脚本与供 Agent 阅读的 APPLY.md，
因此目标机即使没装本技能，也能完成导入。
何时使用
出现以下任一情形时使用本技能：
- 用户要把本机 WorkBuddy 的配置/技能搬到另一台电脑
- 用户提到「同步 WorkBuddy 配置」「打包技能」「迁移 WorkBuddy」
- 用户拿到一个
wb-config-*.zip，要把它导入本机 - 用户只想例行备份 skills 与用户级配置文件
不要使用的情形：
- 用户要同步运行时数据库（
*.db）——本技能有意不处理，见「关键约束」 - 用户要的是实时/自动同步——本技能是手动方案，不提供常驻同步进程
- 用户要的是远程操控另一台机器——那是官方「助理」功能，与本技能无关
能力边界
| 做 | 不做 |
|---|---|
打包 skills/ 全量（含素材型技能） |
不打包 *.db / -wal / -shm（进程独占，会损坏） |
| 打包 5 个用户级配置 md/json | 不打包 credentials/（含 token，敏感） |
| 目标机合并式导入（不删已有技能） | 不自动覆盖 mcp.json（平台路径不同，需人工合并） |
| 导入前自动两级备份 | 不提供常驻/定时同步 |
环境要求
| 端 | 系统 | 依赖 |
|---|---|---|
| 导出 | macOS / Linux | bash、zip、python3（生成 MANIFEST） |
| 导出 | Windows | PowerShell 5.1+ |
| 导入 | 全平台（推荐） | python3 / python（纯标准库，无第三方依赖） |
| 导入 | macOS / Linux | bash；装 rsync 可快约 100 倍（缺失则回退 cp） |
| 导入 | Windows | PowerShell 5.1+；robocopy（系统自带，缺失则回退 Copy-Item） |
导入端为什么多一个 python 入口：实测遇到过目标机 PowerShell 异常
（连 Write-Output 都返回 exit 1），此时 apply.ps1 完全无法执行。
apply.py 只用 Python 标准库，是这种情况下的唯一通道，且支持直读 zip、无需解压。
快速开始
工作流一：导出（在源机器）
macOS / Linux：
~/.workbuddy/skills/workbuddy-config-sync/scripts/export.sh [输出目录]
Windows（PowerShell）：
Set-ExecutionPolicy -Scope Process Bypass
~\.workbuddy\skills\workbuddy-config-sync\scripts\export.ps1 [-OutDir <目录>] [-Exclude "<技能名>"]
产出 wb-config-<主机名>-<时间戳>.zip，并打印体积与收录项数。
把该 zip 交给用户手动搬运（U 盘 / 网盘 / AirDrop 等）。
默认全量导出，包含所有技能，含素材型技能（如 ppt-master，约 115M）。
全量约 130M / 13,000+ 文件，zip 打包需数十秒，属正常现象。
导出可调参数
| 变量 / 参数 | 作用 |
|---|---|
WB_HOME |
指定 WorkBuddy 配置目录，默认 ~/.workbuddy |
--exclude / -Exclude |
指定排除的技能名，逗号分隔 |
WB_SYNC_EXCLUDE_SKILLS |
同上，环境变量形式 |
OutDir / 位置参数 |
输出目录，默认当前目录 |
恒定排除 .git/、__pycache__/、.DS_Store——版本控制与缓存产物，非技能内容，
排除可显著减小体积且无功能损失。
工作流二：导入（在目标机器）
推荐：直接对 zip 操作，不必先解压（apply.py 只按需读取 zip 内容）。
先解压整包在 13,000+ 文件时既慢又容易中断，中断还会造成「技能静默丢失」——
直读 zip 从根上绕开这个故障模式。
任选一种入口：
# ① 跨平台推荐：纯标准库，支持直读 zip（macOS / Linux / Windows 通用）
python3 tools/apply.py --zip wb-config-<主机名>-<时间戳>.zip --dry-run
python3 tools/apply.py --zip wb-config-<主机名>-<时间戳>.zip
# ② macOS / Linux：解压后执行
cd <解压目录>/tools && chmod +x apply.sh
./apply.sh --dry-run && ./apply.sh
# ③ Windows：cmd 里直接跑（自动挑 python，缺失则回退 PowerShell）
tools\apply.cmd --zip ..\wb-config-<主机名>-<时间戳>.zip --dry-run
# ④ Windows：PowerShell 健康时
Set-ExecutionPolicy -Scope Process Bypass
cd <解压目录>\tools
.\apply.ps1 -Zip ..\wb-config-<主机名>-<时间戳>.zip -DryRun
无论走哪种入口，收尾都会做导入后完整性校验（见下节），并把结果作为退出码：
0 = 校验通过；1 = 前置条件不满足 / 导入出错 / 校验未通过。
校验未通过时脚本会明确报出「哪个技能缺失、差多少文件」，并提示可用备份回滚。
导入参数
| 参数（python 风格 / PowerShell 风格） | 作用 |
|---|---|
--zip PATH / -Zip PATH |
直接对 zip 操作，免手工解压（推荐） |
--dry-run / -DryRun |
只预览，不写入 |
--target DIR / -Target DIR |
指定目标目录，用于测试或非常规路径 |
--config-only / -ConfigOnly |
只应用配置文件 |
--skills-only / -SkillsOnly |
只应用技能 |
--skip-verify / -SkipVerify |
跳过导入后完整性校验（不建议） |
--remove-bootstrap / -RemoveBootstrap |
把遗留 BOOTSTRAP.md 移入备份目录（默认保留） |
--force / -Force |
保留以兼容旧用法，现已无实际作用 |
> 性能说明：技能导入优先用 rsync（macOS/Linux）或 robocopy（Windows），
> 不可用时回退 cp -R / Copy-Item。实测 13376 个文件：rsync 约 3 秒，
> 纯 cp -R 约 7 分钟。脚本自动择优，无需干预。
导入后完整性校验（硬性闸门）
导入收尾时，脚本会逐条比对 MANIFEST.json 声明与实际落盘状态：
- 包侧自洽：MANIFEST 声明的技能，包内是否都在
- 磁盘侧落地：每个声明技能是否都落到
skills/下、且非空目录、文件数不少于包内 - 配置文件：4 个 md 是否就位（
mcp.json以mcp.json.incoming形式落地）
任一项不满足即 FAIL 并列出具体技能名，退出码 1，绝不静默通过。
这是本技能 1.1.0 的核心修复：此前解压中断导致 2 个技能静默丢失而流程照样报成功。
也可以单独跑校验脚本（导出包给他人前、或怀疑导入不完整时）：
python3 tools/verify_sync.py zip <配置包>.zip # 导出一致性
python3 tools/verify_sync.py import <目标目录> --zip <配置包>.zip # 导入完整性
备份与回滚
导入时脚本自动生成两类备份，按体积与价值区别对待：
| 备份目录 | 内容 | 体积 | 保留策略 |
|---|---|---|---|
sync-backup-<时间戳>/ |
被覆盖的 MEMORY.md / SOUL.md / IDENTITY.md / USER.md |
KB 级 | 始终保留，不轮转 |
sync-backup-skills-<时间戳>/skills/ |
导入前目标机 skills/ 全量快照 |
约 128M | 仅保留最近 1 份 |
设计理由：配置文件体积小、丢失代价高，删掉省不下空间却可能丢历史；
技能快照体积大且可从源机重导，留 1 份足够回滚一步，多留纯属占盘。
回滚方式：
- 配置回滚：从
sync-backup-<时间戳>/把文件拷回<目标目录>覆盖 - 技能回滚：从
sync-backup-skills-<时间戳>/skills/拷回<目标目录>/skills/
技能快照保留份数可用环境变量 WB_SYNC_KEEP_SKILL_BACKUPS 调整（默认 1）。
配置备份始终保留、永不轮转，不受任何参数影响。
关于「是否必须退出 WorkBuddy」
不需要退出。 实测结论：
- 导入写入的是
MEMORY.md、SOUL.md、IDENTITY.md、USER.md、mcp.json.incoming
及skills/下文件，全部是普通文本文件，macOS 与 Windows 都不加独占锁，
运行时覆盖不会失败 - 真正被独占锁住的只有 SQLite 数据库（
workbuddy.db、edge-sync-mapping*.db
及其-wal/-shm），而导入不涉及它们
不退出带来的两条真实代价，须告知用户：
- 生效延迟：这些文件在会话启动时注入上下文。运行中导入后，当前会话仍是旧内容，
需新开会话才生效 - 写回覆盖风险：这些文件并非只读，Agent 有权改写。若此刻有会话正在编辑它们，
可能基于旧内容写回，冲掉本次导入结果——导入期间不要在目标机上并发修改这些文件
关键约束（务必遵守）
mcp.json不自动覆盖：含平台相关路径，脚本存为mcp.json.incoming，
需人工核对后合并，并提示用户处理- 技能是合并而非替换：不会删除目标机已有技能，避免误删
- 不同步运行时数据库：
*.db及其-wal/-shm绝不可纳入同步，
它们被进程独占且含本机状态，覆盖会导致数据损坏 - 不动
credentials/：含 token，属敏感目录 - 跨平台要警示：macOS/Linux 产出的技能若含
.sh脚本，在 Windows 上可能不可用 - 排除项要告知用户：
MANIFEST.json中excluded.skills非空时说明原因，
不要静默略过
典型对话示例
用户：帮我打包 WorkBuddy 配置
Agent：[调用 export.sh] 已生成 wb-config-macbook-20260911-0200.zip（19K，收录 6 项）。
默认全量导出会含 ppt-master 等素材技能（整包约 130M），
若只要配置和小技能请告知排除项。
用户：把这个包导入到 WorkBuddy
Agent：[解压 → 读 APPLY.md → apply.sh --dry-run → 汇报影响范围 → 确认后正式导入]
已导入 4 个配置文件、更新 12 个技能；备份在 sync-backup-20260911-0200/。
mcp.json 已存为 mcp.json.incoming，需你人工核对合并。
注意：新开会话后配置才生效。
文件清单
SKILL.md 本文件
scripts/
├── export.sh 导出打包（macOS/Linux，会打进包）
├── export.ps1 导出打包（Windows，会打进包）
├── apply.py 导入应用（跨平台·纯标准库·支持直读 zip，会打进包）★推荐
├── apply.cmd 导入入口（Windows 自动选 python / PowerShell，会打进包）
├── apply.sh 导入应用（macOS/Linux，会打进包）
├── apply.ps1 导入应用（Windows，会打进包）
├── verify_sync.py 独立校验（导出/导入双模式，会打进包）
└── make_icon.py 生成 512×512 技能图标（发布到技能市场用）
references/
├── APPLY.md 目标机 Agent 的导入指引，会复制到包根目录
└── PUBLISH.md 发布本技能到 SkillHub 的流程
assets/
└── icon.png 技能图标，512×512 PNG
> export.sh / export.ps1 会把上述 5 个导入脚本（apply.py / apply.cmd /
> apply.sh / apply.ps1 / verify_sync.py）一并写入包的 tools/，
> 保证目标机无论处于哪种环境都有可用入口。
常见问题
Q：报「找不到 MANIFEST.json」？
不在解压后的包目录内执行。先 cd 到包的 tools/。
Q：报「目标目录不存在」？
WorkBuddy 未安装或从未启动过；或用 --target / -Target 指定目录。
不要自行创建目标目录。
Q：zip 体积异常大？
确认排除项生效，检查是否误打包了素材型技能。
Q：目标机已有的技能会不会被删掉？
不会。导入是合并式：同名技能被覆盖更新，目标机独有的技能保留。
Q：为什么导入后没变化？
配置在会话启动时注入。新开一个会话即可生效。脚本收尾会醒目提示这句。
Q：Windows 上 PowerShell 跑不了（连 Write-Output 都报错）？
这正是 1.1.0 增加 apply.py 的原因。改用 Python 入口即可，完全绕开 PowerShell：
python apply.py --zip <配置包>.zip
或直接在 cmd 里跑 apply.cmd --zip <配置包>.zip，它会自动挑可用引擎。
Q：脚本报「校验未通过」怎么办？
这是闸门生效，不是脚本坏了。按输出里点名的技能处理：删掉目标机对应目录后重跑，
或改用 --zip 直读模式重导（避开解压中断）。目标机原有文件未被破坏，
必要时用 sync-backup-skills-<时间戳>/ 回滚。
Q：目标目录多出一个 BOOTSTRAP.md？
那是历史遗留文件。加 --remove-bootstrap 重跑会把它移入备份目录（不是直接删，可随时取回）。
Q：能做成自动/定时同步吗？
本技能定位是手动方案。定时同步需要常驻进程与冲突策略，不在范围内。
（远程操控另一台机器请用官方「助理」功能。）
变更记录
1.1.0 —— 依据一次真实的 macOS → Windows 跨平台导入复盘迭代（导出侧经核查无缺陷）：
- 新增导入后完整性校验（硬性闸门）：声明技能未全部落地即 FAIL 并点名，杜绝「静默丢技能」
- 新增跨平台
apply.py入口：纯标准库，仅需 python；支持直读 zip、免解压 - 新增
apply.cmd（Windows）：自动在 python 与 PowerShell 间择优，参数风格自动转换 - 导出端打包全部导入脚本：此前只打
apply.sh/apply.ps1，导致新入口到不了目标机 - 增强导入收尾提示：醒目提示「需新开会话 / 重启 WorkBuddy 才生效」
BOOTSTRAP.md处理选项：--remove-bootstrap移入备份目录而非直接删除- 导出端打包后自检：断言声明技能 ⊆ 归档内容（双保险）
- 统一 Windows 导出包结构：
export.ps1改为与export.sh一致（zip 内含同名外层目录） - MANIFEST 条目归一化：
contents.skills为对象数组（{"name": ...}）时不再崩溃，
三个入口统一归一化；另补"半包检测"（导入后文件数少于包内即判失败）
1.0.0 —— 首个发布版本：导出/导入双向、两级备份、跨平台告警。
发布到技能市场
若要把它分享给其他人，可发布到 SkillHub：https://skillhub.cn
—— WorkBuddy 客户端「技能」入口的技能来源。完整步骤见 references/PUBLISH.md。
