技能一键同步
这个技能做什么
把本机 .workbuddy/skills/ 下的技能打包成一个 zip，投递到 OneDrive 的同步文件夹；在另一台电脑上再从那里把技能装回去。
解决的是一个很常见的误解：自建 / 本地技能不是账号资产，它只是硬盘上的文件夹，换个账号登录或换台电脑当然看不到。这个技能负责把文件夹搬过去。
触发条件
用户出现以下任意意图时调用：
- 现象类：「换电脑后我创建的技能不见了」「第二个电脑上看不到我的 skill」「同一个账号为什么技能不同步」
- 搬运类：「把技能搬到另一台电脑」「技能迁移」「备份我的技能」「导出所有技能」「从公司电脑拷到家里」
- 操作类：「一键上传技能」「一键还原技能」「同步技能到 OneDrive」「把技能放到 U 盘」
何时不要使用
- 用户要的是账号级自动同步（以为登录就该同步）→ 先纠正认知：本地技能不同步是设计如此，不存在开关可打开；再提供本技能的搬运方案。
- 用户要修改技能内容 → 这是编辑任务，直接改
SKILL.md，不要调用本技能。 - 用户只是想看看装了哪些技能 → 跑
list即可，不要执行打包或上传。 - 同步目标是技能市场 / 公开发布 → 那是另一个流程，与「把本地技能搬到自己另一台机器」不同。
依赖
- 运行环境：Python 3.7+，Windows / macOS / Linux 均可
- 第三方库：无。只用标准库（
argparse/zipfile/hashlib/pathlib等） - 外部服务：不调用任何 API，不需要 API Key、不需要账号密码
- 可选前提：走 OneDrive 方式时，需要本机已安装并登录 OneDrive 客户端（提供同步文件夹）；用 U 盘或
--onedir手动指定目录则不需要 - 权限范围：读取
~/.workbuddy/skills，写入用户指定的同步文件夹；覆盖已存在技能前会先重命名为.bak-<时间戳> - 双击启动器：技能市场不允许
.bat上传，随包携带的是.bat.txt模板。首次使用双击入口前，先执行一次python "<技能目录>/scripts/skill-sync.py" make-launchers在同目录生成真正的.bat（已存在则跳过，--force覆盖） - 风险等级：L1（会写入文件，但默认不覆盖，覆盖前自动备份，可回滚）
工作流
第一步：判断是哪一侧的操作
| 用户所在场景 | 执行 |
|---|---|
| 要「送出去」的技能在当前这台电脑 | sync（打包并投递） |
| 要「收进来」的技能在另一台电脑 | restore-from-onedrive（读取并安装） |
| 只想看清单 | list |
| 两边都要手动控制文件位置 | pack + restore |
第二步：确认 Python 可用
直接调用 python 前先验证它真能跑。Windows 上一个常见的坑：where python 命中的可能是微软商店的占位符（一个 121 字节的跳板），它执行任何脚本都会静默退出、退出码 49、零输出——看起来像"上传失败但没有报错"。
验证与兜底：
- 先试
python --version，能打印版本号才算可用。 - 若返回空输出或退出码 49，改用 WorkBuddy 内置解释器：
~/.workbuddy/binaries/python/versions/*/python.exe - 或者先执行
python "<技能目录>/scripts/skill-sync.py" make-launchers生成双击启动器，再让用户双击scripts/一键上传技能.bat/scripts/一键还原技能.bat——这两个批处理内部会调用scripts/find-python.bat，用「写哨兵文件实跑验证」的方式自动挑出真正可用的解释器（系统 Python 优先，找不到再回退到内置）。
第三步：执行对应命令
# 送出：打包并投递到 OneDrive
python "<技能目录>/scripts/skill-sync.py" sync
# 收进：从 OneDrive 读取并安装
python "<技能目录>/scripts/skill-sync.py" restore-from-onedrive
# 看清单
python "<技能目录>/scripts/skill-sync.py" list
首次使用建议先跑一次 restore-from-onedrive --dry-run，只预览不写文件。
第四步：交付后必须交代的三件事
做完同步或还原，务必提醒用户：
- 等 OneDrive 图标转完圈（文件还在上传/下载中时，另一台电脑拿不到）
- 还原后在技能面板确认技能处于启用状态
- 新开一个对话——技能只在新对话开始时加载；仍不显示就重启 WorkBuddy
命令速查
| 命令 | 作用 |
|---|---|
list |
列出本机技能（含层级、大小、文件数） |
pack [名字...] [-o 文件] |
打包为 zip，省略名字则全部 |
restore <zip> [--target 目录] [--dry-run] [--force] |
从 zip 还原 |
sync [名字...] [--onedir 目录] [--force-all] |
打包并投递到同步目录 |
restore-from-onedrive [--onedir 目录] [--target 目录] [--dry-run] [--force] |
从同步目录读取并还原 |
make-launchers [目录] [--force] |
把随包的 .bat.txt 模板生成为可双击的 .bat（默认生成在本脚本同目录） |
默认行为：还原时目标已存在同名技能则跳过；加 --force 才覆盖。sync 会对每个技能算内容指纹，没改动过的自动跳过（状态存在同步目录的 .skill-sync-state.json），加 --force-all 强制全量重传。
交付前验证清单
- [ ] Python 真的能执行（
--version有输出，不是空返回） - [ ]
list能正确列出技能，且同名技能的实际生效层级已确认（项目级优先于用户级，别搬错那一份） - [ ] 打包产物存在且体积合理（含全部目标技能）
- [ ] 还原侧先用
--dry-run看过落点，再实际执行 - [ ] 已提醒用户：等同步完成、确认技能启用、新开对话
- [ ] 覆盖操作前确认已生成
.bak-<时间戳>备份
安全边界
- 不改技能内容：只做目录复制，
SKILL.md与脚本原样搬运。 - 不动安装元数据：
_meta.json、_skillhub_meta.json、_user_meta.json原样搬运，不写入、不改写。 - 默认不覆盖：目标已存在同名技能时跳过并提示；
--force覆盖前必先备份。 - 自动排除垃圾：
.DS_Store、Thumbs.db、__pycache__、*.pyc等不打包。 - 只用本地文件系统：不联网、不上传任何数据到第三方服务；OneDrive 的传输由用户自己的客户端完成。
参考文档
- 使用手册 —— 文件放置与双击入口、OneDrive 文件夹路径怎么找
- 排错指南 —— Python 占位符、批处理乱码、同步未完成、路径报错
