技能版本跟踪器
> 心法：第一次全量造册，后续只查差异——把排查成本从 O(n) 降到 O(1)。
一、何时用 / 何时不用
该用：
- 用户想检查已安装技能是否有更新
- 用户说"排查技能更新""技能版本跟踪""看看技能有没有新版本"
- 定时排查自动化触发时
- 用户想了解某个技能的来源/源链接
不该用：
- 单个技能功能排障 → 用该技能的 troubleshooting
- 创建新技能 → 用 yrns-skillcreator
- 技能安装/卸载 → 用 marketplace-skill-installer 或直接操作
二、核心工作流
Step 1 判断排查模式
读取登记册文件（路径见 Step 2）。根据是否存在登记册及内容，判断模式：
| 情况 | 模式 | 动作 |
|---|---|---|
| 登记册不存在或为空 | 首次全量排查 | 执行 Step 3 全量扫描 |
| 登记册存在且有记录 | 增量排查 | 执行 Step 4 增量检查 |
| 用户指定某个技能名 | 定向排查 | 只检查该技能 |
Step 2 登记册路径与格式
登记册是本技能的持久化数据，存储在：
~/.workbuddy/skills/yrns-skill-version-tracker/data/registry.json
详细格式说明见 references/registry-format.md。核心字段：
{
"version": "1.0",
"last_full_scan": "2026-07-05T20:35:52+08:00",
"last_incremental_scan": null,
"scan_interval_days": null,
"skills": [
{
"name": "skill-name",
"local_path": "...",
"scope": "user|project|builtin",
"local_version": "1.0.0",
"source_url": "https://...",
"source_type": "github|anthropic-official|gitee|gitlab|skills-sh|skillsmp|skillhub|marketplace|website|builtin|unknown",
"source_verified": false,
"remote_version": null,
"last_checked": null,
"status": "not-checked|up-to-date|update-available|unknown-source|check-failed",
"user_modified": false,
"changelog": "",
"notes": ""
}
]
}
Step 3 首次全量排查
3.1 扫描已安装技能
运行扫描脚本，提取所有已安装技能的 frontmatter 信息：
python scripts/scan_installed_skills.py
脚本动态发现当前用户机器上的所有技能安装目录（不硬编码任何路径），扫描范围：
| 扫描目录 | 发现方式 | scope 标记 |
|---|---|---|
| 用户级技能 | os.path.expanduser("~/.workbuddy/skills/") |
user |
| 项目级技能 | {当前工作目录}/.workbuddy/skills/（如有） |
project |
| 内置技能 | 脚本自动探测 WorkBuddy 安装路径，跨平台兼容（Win/macOS/Linux） | builtin |
> ⚠️ 关键设计：所有路径均由脚本在运行时动态计算，绝不硬编码任何机器相关路径。换台电脑、换个用户，脚本自动适配当前环境。
脚本输出 JSON 数组到 stdout，每个元素包含：name, local_path, scope, local_version, description, agent_created, source_url（从 frontmatter 中提取，如有）、source_hints（从正文中搜索到的疑似源链接线索）。
3.2 源链接识别
对脚本输出中 source_url 为空的技能，按以下优先级逐一尝试定位来源：
- 检查 SKILL.md 正文：搜索
github.com、gitee.com、skills.sh、skillsmp.com、skillhub.club等 URL - 检查技能内脚本：部分技能（如 baiyin-music-generate）的自更新脚本中包含源 slug
- Anthropic 官方仓库比对：检查是否在
github.com/anthropics/skills中 - skills.sh 搜索：在
www.skills.sh上搜索技能名 - SkillsMP 搜索：在
skillsmp.com/search上搜索技能名 - SkillHub 搜索：在
www.skillhub.club/skills上搜索技能名 - WorkBuddy 市场搜索：用技能名搜索 WorkBuddy 内置市场
- Web 搜索（兜底）：用技能名 + "skill" + "github" / "skills.sh" / "skillsmp" 搜索
详细搜索策略与各平台 URL 格式见 references/scan-guide.md。
Why：大多数技能没有显式的 source_url 字段，需要多平台多渠道挖掘。覆盖 7 类检索源确保尽可能找到技能来源。
3.3 写入登记册
将所有扫描结果写入 data/registry.json。对未找到源链接的技能：
- source_type 设为 "unknown"
- status 设为 "unknown-source"
- 在 notes 中记录已尝试的搜索方式
3.4 汇报首次排查结果
向用户展示表格：
| 技能名 | 本地版本 | 来源类型 | 源链接 | 状态 |
|---|---|---|---|---|
并告知：
- 共扫描到 N 个技能
- 其中 M 个已定位源链接，K 个未能定位
- 未定位的技能列表，询问用户是否知道其来源
Step 4 增量排查
4.1 读取登记册
读取 data/registry.json，获取所有已登记技能及其源链接。
4.2 逐个检查远程版本
对每个 source_type 不为 "unknown" 且 source_type 不为 "builtin" 的技能，按来源类型选择检查方式：
| source_type | 检查方式 |
|---|---|
github / anthropic-official |
WebFetch 访问 GitHub raw URL，提取 frontmatter version 字段 |
gitee / gitlab |
WebFetch 访问 Gitee/GitLab raw URL，提取 version |
skills-sh / skillsmp / skillhub |
从 source_url 提取 owner/repo → 回退到 GitHub raw URL 检查（这些平台最终都指向 GitHub） |
marketplace |
用 workbuddy_marketplace_skill 工具搜索，或 WebFetch 市场页面 |
website |
直接 WebFetch 访问 source_url |
各平台的具体 URL 格式、raw URL 构造方法、WebFetch prompt 模板见 references/scan-guide.md 第二节。
关键：skills.sh / SkillsMP / SkillHub 上的技能最终都指向 GitHub 仓库，版本检查时从 source_url 中提取 owner/repo 后回退到 GitHub raw URL 即可。
4.3 版本对比
将远程版本与本地版本对比：
- 版本相同 → status = "up-to-date"
- 版本不同 → status = "update-available"，记录 remote_version
- 获取失败 → status = "check-failed"，记录原因到 notes
更新 last_checked 时间戳。
Why：增量排查只检查已登记的技能，不需要重新扫描目录，大幅减少工作量。
4.4 汇报增量排查结果
只报告有变化的技能：
| 技能名 | 本地版本 | 远程版本 | 状态 | 更新内容 |
|---|---|---|---|---|
对有更新的技能：
- 尝试获取远程 SKILL.md 的 changelog 或 description 差异
- 简要说明新旧版本的功能差异
- 询问用户是否更新
Step 5 更新决策与执行
对 status = "update-available" 的技能，逐一询问用户：
技能 [xxx] 有新版本：
当前版本: 1.0.0
最新版本: 1.1.0
主要变化: [从远程 SKILL.md 的 changelog 或 description 提取]
是否更新？[更新 / 跳过 / 稍后提醒]
- 更新：下载远程 SKILL.md 及相关文件，覆盖本地（注意：如果
user_modified为 true，先警告用户本地修改将被覆盖） - 跳过：记录用户选择，
status保持"update-available"但标注"user-skipped" - 稍后提醒：下次排查时再次提醒
Step 6 定时排查设置
排查完成后，询问用户：
是否设置定时自动排查？
1. 每天
2. 每周（推荐）
3. 每月
4. 暂不设置
用户选择后，用 automation_update 工具创建定时任务：
- scheduleType: "recurring"
- rrule: 根据选择生成（如每周一为 FREQ=WEEKLY;BYDAY=MO）
- prompt: "执行技能版本增量排查：读取 yrns-skill-version-tracker 技能目录下 data/registry.json 登记册，逐个检查已登记技能的远程版本，报告有更新的技能并询问是否更新。"
- cwds: 当前工作目录
- status: "ACTIVE"
同时在登记册中记录 scan_interval_days。
Why：用户容易忘记手动排查，定时自动化确保不遗漏更新。
三、references / scripts / assets 索引
| 何时读/用 | 文件 |
|---|---|
| 了解登记册完整字段定义 | references/registry-format.md |
| 了解源链接搜索策略与版本检查技巧 | references/scan-guide.md |
| 扫描已安装技能目录并提取 frontmatter | scripts/scan_installed_skills.py |
| 登记册初始化与读写操作 | scripts/manage_registry.py |
| 登记册空模板 | assets/registry-template.json |
四、铁律与红线
- 登记册是唯一真相源 — 所有排查结果必须写入 registry.json，不能只停留在对话中
- 首次全量、后续增量 — 第一次必须扫描全部技能并登记，之后只做差异检查
- 不自动更新 — 发现更新后必须询问用户，绝不擅自覆盖本地技能
- 保护用户修改 — 更新前检查
user_modified标记，有修改时先警告 - 内置技能跳过 — builtin 技能随 WorkBuddy 更新，不需要单独跟踪
- 多平台检索 — 首次排查时覆盖全部 7 类检索源（GitHub / Anthropic 官方 / skills.sh / SkillsMP / SkillHub / WorkBuddy 市场 / Gitee），尽量减少 unknown 数量
- 失败要记录 — 检查失败时记录原因到 notes，不要静默跳过
五、状态流转
not-checked ──首次扫描──> unknown-source（找不到源）
└──> up-to-date（版本一致）
└──> update-available（版本不同）
├── user-skipped（用户选择跳过）
└── updated（用户已更新 → 回到 up-to-date）
└──> check-failed（检查失败）
any-status ──本地卸载──> removed（保留历史，不从登记册删除）
元数据
skill_name: yrns-skill-version-tracker
version: 1.1.0
创建方法: yrns-skillcreator 四层架构
changelog:
- 1.1.0: 复核修复——同步 source_type 枚举；补全 Step 4.2 各平台版本检查方法；修复 automation prompt 硬编码路径；修复 --skill-name 不匹配 frontmatter name；补充 removed 状态；标注平台数据来源
- 1.0.0: 初始版本——首次全量排查 + 增量排查 + 定时自动化
<!--
版权申明：本技能默认使用 yrns 版权申明。
如需修改，请在 frontmatter 中更新 license 字段。
-->
