skill-updater v1.2.0

0. 定位与边界

skill-updater 是按需触发的技能库更新器。它解决一个具体痛点：当前 ~/.workbuddy/skills/ 下的技能来源混杂（skillhub 市场安装、GitHub 克隆、自研），但溯源信息不可靠——.skills_store_lock.json 把几乎所有技能都记为 community/skillhub，GitHub 克隆的技能甚至不在锁文件中。本技能通过多信号分类器重建每个技能的出处，仅对可证伪的外部来源（skillhub / github）执行溯源升级，对自研技能一律跳过，杜绝误覆盖用户自有成果。

安全原则（来自用户纪律）：更新即写入，必须先备份、再安全审计、高危即回滚。绝不静默覆盖。

1. 触发方式

用户说出以下任一短语即触发：

• 技能库更新 / 更新技能库 / 更新skills / 升级技能 / 升级技能库
• skill update / 更新所有技能 / 升级所有skill

触发后按第 4 节流程执行三阶段流水线。

2. 设计目标

1. 分类可证伪：每个技能必须有明确出处标签 skillhub / github / self / unknown，不可臆测。
2. 自研零风险：无外部溯源证据的技能一律按 self/unknown 跳过，默认保护用户自有技能。
3. 可审计可追溯：每次操作写 manifest.json（分类缓存）与 update_log.json（操作日志）。
4. 失败可逆：更新前全量备份，P0 风险或命令失败即回滚。
5. 幂等：重复运行不产生副作用，已最新者跳过。

3. 技能三分类与溯源判定（分类器决策树）

分类在 scripts/inventory.py 中实现，优先级如下（命中即停）：

对每个技能目录 name/:
 ① references/self_authored.txt 列出该名
      → self（用户显式声明，最高优先，持久化）
 ② SKILL.md frontmatter 含 origin ∈ {self,skillhub,github}
      → 采用该值（权威覆盖）
 ③ frontmatter 含 agent_created: true
      → self（模型/助手创建的技能视为自研）
 ④ 目录内含 .git/ 且 remote.origin.url 存在
      → github，sourceUrl = git remote
 ⑤ .skills_store_lock.json 存在该技能条目（含真实 slug）：
      zip_url 含 "skillhub"        → skillhub，slug 取自 zip_url
      zip_url 含 "github/gitclone" → github
 ⑥ 以上皆不命中
      → skillhub 候选（待注册表验证；404 后尝试搜索同源，仍无则 unknown 跳过）

关键设计取舍：第 ⑤ 步把"无法证明来自外部"的技能全部判为 unknown 并跳过。这比"猜测后误覆盖"安全得多。报告会列出所有 unknown 供用户人工确认；确认后可写入 references/self_authored.txt 持久化（或在前端 matter 显式加 origin: self/origin: skillhub/origin: github 提升判定优先级）。

已知限制：经 skillhub 市场安装的 GitHub 源技能，其锁文件 zip_url 指向 api.skillhub.cn，会被标为 skillhub 并通过市场重装获取最新——功能上仍能更新，仅 origin 标签精度下降。v1.0.0 接受此误差。

4. 整体架构与数据流（三阶段流水线）

[1] inventory.py   扫描 + 分类 + 版本读取  ──► manifest.json（分类缓存，幂等）
        │
[2] check_updates.py  按 origin 查最新版本/提交   ──► manifest["skills"][n]["_check"]
        │   skillhub: GET api.skillhub.cn/v1/skills/ 取 version（best-effort）
        │   github:   git fetch + HEAD vs @{u} 比较
        │   404 技能: lightmake.site 模糊搜索 → --adopt / --auto-adopt-prefix 采纳
        │            → 采纳映射持久化到 slug_map.json
        │
[3] apply_update.py  对 hasUpdate 者执行：备份 → 拉取 → 安全审计 → (回滚|P0) → 写日志
        │   支持多 --only 与 --no-shared-state（多 agent 并行安全模式，不写共享状态）
        │
        └─► update_log.json（追加式操作记录）+ 控制台汇总报告

一键执行入口：scripts/run.py（顺序调用上述三步并打印汇总）。

5. 各来源更新机制

6. 安全闸门（备份 + 审计 + 回滚）

每次单技能更新严格按序：

1. 备份：整目录复制到 /.skillup_backup/_<时间戳>（标准库 shutil.copytree，跨平台）。
2. 拉取：执行第 5 节对应命令。失败 → 回滚 + 记 failed。
3. 安全审计：audit() 扫描更新后文件（跳过 .git），匹配高危模式清单（见 references/SECURITY_AUDIT.md），含 curl|sh、wget|sh、危险 rm -rf /、sudo、base64 解码管道、chmod 777 等。
   • 命中 P0 → 立即回滚备份 + 记 rolled-back，不写入。
   • 命中 P1 → 报告警告但仍应用（用户可事后审查）。
4. 写回：更新 manifest.json 中的 currentVersion 与 lastResult，追加 update_log.json。

7. 产物文件

• scripts/inventory.py — 分类器 + manifest 构建（只读扫描，安全可重复）
• scripts/check_updates.py — 版本/提交比对
• scripts/apply_update.py — 备份/拉取/审计/回滚执行器
• scripts/run.py — 三阶段编排入口
• manifest.json — 分类缓存（技能自管，判定的单一事实源）
• update_log.json — 操作日志（追加式）
• references/SECURITY_AUDIT.md — 高危模式清单与分级
• references/self_authored.txt — 自研技能白名单（可选持久化）
• slug_map.json — 已采纳的「别名→slug」映射（自动持久化，免去重复 --adopt）

8. 使用方式

# 完整更新（推荐，触发「技能库更新」后执行）
python3 ~/.workbuddy/skills/skill-updater/scripts/run.py

# 分步
python3 ~/.workbuddy/skills/skill-updater/scripts/inventory.py        # 只看分类
python3 ~/.workbuddy/skills/skill-updater/scripts/check_updates.py    # 只看有无更新
python3 ~/.workbuddy/skills/skill-updater/scripts/apply_update.py     # 执行更新
python3 ~/.workbuddy/skills/skill-updater/scripts/apply_update.py --dry-run  # 预演不写入

# 自动采纳 sp- 前缀技能的同源候选（默认关，需强匹配才采纳），并持久化到 slug_map.json
python3 ~/.workbuddy/skills/skill-updater/scripts/check_updates.py --auto-adopt-prefix sp-

# 多 agent 并行安全更新：--no-shared-state 避免并发写 manifest/update_log 冲突，结果仅打印
python3 ~/.workbuddy/skills/skill-updater/scripts/apply_update.py --only   --no-shared-state

9. 与现有技能的关系

• auto-update / auto-updater 已于 2026-07-06 删除，skill-updater 是技能库更新的唯一入口（按需、分源、带安全闸门）。
• 本技能自身标记 origin: self，故"技能库更新"不会自更新；若将来发布到市场/GitHub，补 origin+update_command 即可启用自更新。

10. 已知限制

1. skillhub 更新已落地真实 curl+unzip 机制（api.skillhub.cn 已验证返回合法 zip）；版本比对基于持久化的 checkedVersion，避免无本地版本号的技能被反复重装。
2. 纯 zip 方式安装的 GitHub 源技能（无 .git、锁文件指向 skillhub）被归为 skillhub 处理。
3. 404 技能经 lightmake.site 模糊搜索产出"同源候选"（报告制，需 --adopt name:slug 人工采纳），不自动覆盖，避免误杀自定义技能。
4. 仅扫描用户空间 ~/.workbuddy/skills/；产品内置技能（App 包内）由产品自身更新，不在范围内。

11. 版本变更

• v1.1.0（2026-07-06）：

  • 🔴 修复 P0：apply_update.py 的 skillhub 更新命令原为 npx skills add（Vercel CLI，仅认 GitHub owner/repo，对 SkillHub 社区技能必然失败且 SKILL.md 声称的 zip 回退从未实现）。改为真实 curl 下载 zip → unzip → 原子替换 链路，并加 zip 魔术字节校验、单顶层目录上提、SKILL.md 存在性校验。
  • 🟡 修复 P1（churn）：版本比对改用持久化 checkedVersion（注册表版本），避免无 frontmatter 版本号的技能每次被判"需重装"。
  • 🟡 修复 P1（覆盖盲区）：404 技能做 lightmake.site 模糊搜索，产出同源候选供人工采纳；scholar-paper-downloader 等真·下架技能正确跳过。
  • 🟡 修复 P1（死代码）：self_authored.txt 现被 inventory.py 真正读取（最高优先级判 self），并提供 apply_update.py --mark-self 持久化声明。
  • 🟢 加固：run.py 改用 sys.executable 可移植解析；github 更新明确区分"已最新"与"需手动处理"。

• v1.2.0（2026-07-06）：

  • 🔴 修复关键 bug：v1.1 的 check_updates.py found 分支未同步置顶层 info["origin"]="skillhub"，导致 --adopt 后的别名技能（如 sp-* 包）在 apply_update.py 中仍因 origin=unknown 被跳过、无法真正更新。v1.2 修复：采纳别名技能后强制置 origin=skillhub。
  • 🟡 新增 slug_map.json 持久化：--adopt / --auto-adopt-prefix 命中后写回映射，后续运行自动复用，免去每次手动 --adopt。
  • 🟡 新增 --auto-adopt-prefix

    （默认关）：对指定前缀技能 404 后做同源搜索，强匹配（slug==去前缀名 / 目录名以 slug 结尾 / slug==原名）才自动采纳，安全兜底覆盖前缀差异技能（如 sp-* 包），避免误杀自定义技能。

  • 🟢 apply_update.py 新增 --no-shared-state：多 agent 并行执行时不写 manifest.json / update_log.json，避免并发写冲突，结果仅打印；主控在全部 agent 结束后 re-sync 状态。