技能资产治理器（Skill Inventory）

以文件系统为事实源治理技能资产，取代易过期的手写清单。

本技能自包含：脚本位于 scripts/skill-inventory.py，纯 Python 标准库实现，无需任何第三方依赖、无需建 venv、无需 pip install。

何时用

• 手写《自制技能清单_*.md》与实际技能目录脱节（声明数 ≠ 磁盘数）。
• 想一键产出权威台账（md + json）并发现陈旧 / 遗漏 / 卫生问题。
• 新增 / 删除 / 重命名技能后，刷新资产视图。

调用方式（直接用托管 Python）

PY="C:/Users/13301/.workbuddy/binaries/python/versions/3.13.12/python.exe"
SKILL_DIR="C:/Users/13301/.workbuddy/skills/skill-inventory-v1"
"$PY" "$SKILL_DIR/scripts/skill-inventory.py" --out .

说明：--out . 把台账输出到当前工作目录（cwd）。cwd 同时决定：

• 旧台账查找：glob 自制技能清单_*.md
• 项目级技能扫描：<cwd>/.workbuddy/skills/

用户级技能始终扫描 ~/.workbuddy/skills/（绝对路径，不依赖 cwd）。

参数

| 参数 | 默认值 | 说明 | |------|--------|------| | --skills-dir | ~/.workbuddy/skills | 用户级技能扫描根 | | --ledger | cwd 下《自制技能清单_*.md》 | 旧手写台账路径（对照用，可指定） | | --out | . | 台账输出目录 | | --prev-json | 自动查找 out 目录最近一版 | 变更摘要的对比基准（上一版 skill_inventory_*.json） | | --no-changelog | （关） | 加此开关则不生成变更摘要 |

判定逻辑（不盲信手写数字）

• 自制技能 = SKILL.md frontmatter 含 agent_created: true（用户级真实自制信号）
• 台账声明 = 旧清单表格第 2 列反引号技能名（正则 \|\s*\d+\s*\|\s*([^]+) `，排除散文反引号）
• 偏差 = 台账失效(声明但磁盘无) + 自制未登记(agent_created 但台账没记) + 卫生(无 SKILL.md / 无 frontmatter)

关键实现坑（已修复，备忘）

• YAML 折叠块标量：很多 SKILL.md 用 description: >- / |。朴素 key:val 解析会拿到 >-，需检测 >/| 标记后累加后续缩进行。
• 台账散文反引号：清单正文里的 skill-creator、~/.workbuddy/skills/ 等会被误抓，必须用表格行正则过滤。
• Windows 控制台：stdout 加 reconfigure(utf-8, errors="replace") 防 GBK 编码炸。
• 备份重复目录不识别：卫生检查仅覆盖「无 SKILL.md / 无 frontmatter」，xxx.backup-日期 这类内容重复副本会被当成正常官方技能计入总数，需人工用 cmp 逐文件比对确认是快照后再清理（先归档 zip → 送回收站 FOF_ALLOWUNDO，不永久删）。
• 归档勿放 skills 内：清理产生的 zip/备份若放在 ~/.workbuddy/skills/_archive_trash/，会被下次扫描当目录计入总数。必须放到 skills/ 之外（如 ~/.workbuddy/_archive_trash/）。
• EN_CN_FUNC 映射：大量官方技能 description 为纯英文，内置 22 个已知 ID 的中文功能名映射表。新增官方英文技能时，需在 scan_scope() 的 EN_CN_FUNC 字典中补一条，否则功能列退化为英文原文。
• 台账文件名匹配：脚本默认搜索 自制技能清单_*.md 作旧台账；实际常用名可能是 全量技能清单_*.md、skill_inventory_*.md 等，需用 --ledger 显式指定。同日期运行会覆盖上一版 JSON，做变更摘要前先备份旧 JSON。

产出（落地即用）

• skill_inventory_<日期>.json：全量 records（含 function 字段）+ drift（机器可读，供下游编排/审计消费）
• skill_inventory_<日期>.md：偏差速览 + 自制技能权威台账 + 官方参考 + 卫生 + 用法（含 [TOC]）
  • 表格格式：# | 名称 | 功能 | 登记状态（功能取 description 第一句，不含描述全文）
  • 官方英文技能功能自动翻译为中文（内置 EN_CN_FUNC 映射表，22 个已知 ID）
• 技能台账变更摘要_<旧日期>至<新日期>.md：自动对比上一版 json，产出总量变化表 + 自制增减 + 官方增减 + 当前卫生（含 [TOC]）。首次运行（无历史 json）自动跳过，属正常。

变更摘要基准优先级：--prev-json 指定 > out 目录内最近一版（排除今天）自动查找。每次跑完，今天的 json 即成为下次的对比基准，形成滚动增量链。

进阶：设为每周自动化（可选）

可用 automation_update 每周跑一次，使台账永不过期：

• name：技能资产周度治理
• prompt：运行 skill-inventory 技能脚本（scripts/skill-inventory.py），把台账输出到当前工作目录
• rrule：FREQ=WEEKLY;BYDAY=MO;BYHOUR=9（每周一 9 点）

衔接

• 配合 skill-orchestrator：先治理后编排——资产理清后再把技能串成流水线。
• 治理产出的 json 可直接作为编排器的技能目录清单输入。