技能库审计与修复

对本机 DSH 技能库做一次完整体检并修复：库级两级扫描 + 单技能纵深体检 → 分类裁决 → 原子修复 → 复验 → 报告。

目标与边界

做：

• 扫描技能库全部文件，找出真缺陷（断链、frontmatter 不合法、name 不合规、CRLF、机器路径、重复内容、description 过短）
• 对单个技能做纵深体检（frontmatter 残留键与键吞并、description 双语、专有运行时残留、引用精度、技能内重复、嵌套注册性）
• 区分「真缺陷」与「已知误报」，只修前者
• 按 epoch 循环逐个原子修复，每个修复都真实验证后才 commit
• 输出可核对的审计报告

不做：

• ❌ 不擅自删除技能、不擅自改技能语义（description 内容、工作流步骤）——灰色项先问用户
• ❌ 不自动 git push、不自动 npm publish
• ❌ 不把「同名不同内容」当重复删掉

本技能自带的三个工具

三个脚本都用自身位置反推技能库根目录，不需要硬编码路径；技能库整体移动后仍可用。三者共用同一套误报口径（NON_REPO / ARTIFACTS / BENIGN_TILDE），改口径要三处同步。

工作流程

阶段 0：建立安全基线（不可跳过）

git -C <skills-root> status --short
git -C <skills-root> log --oneline -1

• 工作树必须 clean；有未提交改动时先问用户是否先提交。
• 看到 D（工作树删了文件）先问，不要 git restore：未提交的删除可能是有意为之。实测踩过——把用户手删的 3 个技能当成事故恢复了，方向完全反了。
• 记录基线 commit，便于回退。

阶段 1：跑三级扫描

node "<skills-root>\_shared\validate-skills.cjs"
node "<skills-root>\skill-audit\scripts\audit-library.cjs"
node "<skills-root>\skill-audit\scripts\audit-skill.cjs"                # 全部顶层技能
node "<skills-root>\skill-audit\scripts\audit-skill.cjs" <skill-a> <技能b>   # 只体检指定技能

读退出码和汇总行（passed/failed、ERROR/WARN/INFO、PASS/WARN/FAIL），不要只看有没有红字。

单技能体检的输出约定：

• [PASS] 无问题；[WARN] 有建议项；[FAIL] 有必须修的 ERROR（退出码 1）。
• · 行是信息（含已归类的误报）；! 行是 WARN；- 行是 ERROR。
• 技能库刚做增删/移植时，必须对新技能单独跑一次（audit-skill.cjs <name>），库级扫描不会告诉你 description 是否双语、是否残留上游 frontmatter 键。

阶段 2：分类裁决

把 ERROR / WARN 分成三类，不要跳过分拣：

阶段 3：修复（epoch 循环）

每个真缺陷 = 一个原子 commit：

1. 先改引用，后删文件——避免中间态断链。
2. 每轮：改 → 复跑两级扫描 → 通过才 git commit。
3. 失败就 git restore 回退，换思路重试，不要原样重试。
4. commit message 写清「改了什么 + 用什么命令验证」。

阶段 4：复验

• validate-skills.cjs → failed=0
• audit-library.cjs → ERROR=0
• audit-skill.cjs → FAIL=0（WARN 逐条裁决后记入报告）
• 顶层技能数与 catalog 条目数符合预期（除非本轮就是增删技能）

阶段 5：报告

用下方输出模板，如实写返工次数与未修项。

阶段 6：发布（可选，需用户明确同意）

CHANGELOG + package.json + tag。不自动 push、不自动 npm publish。

误报分类表（务必对照，别把误报改坏）

自检（证明体检器不是空转）

改过 scripts/audit-skill.cjs 或怀疑它漏检时，在临时目录（不要放进技能库）造一份故意做坏的夹具库验证它确实报错：

# 自己写一个 .cjs 在 <fixture-dir>\fake-lib 下造各类坏样本，
# 并把真实的 scripts/audit-skill.cjs 复制到 <fixture-dir>\fake-lib\skill-audit\scripts\ 下
# （体检器用自身位置反推根目录，复制后 ROOT 才指向夹具库）
node <fixture-dir>\make-fixture.cjs <fixture-dir>\fake-lib <skills-root>\skill-audit\scripts
node <fixture-dir>\fake-lib\skill-audit\scripts\audit-skill.cjs

夹具必须含正样本（一个干净技能，期望 PASS），否则证明不了「不误报」。期望命中：

• FAIL：非 kebab name / 与目录名不一致、相对引用断链、SKILL.md 含 CRLF、本机用户名绝对路径、read ~/（反例写法）、description 标量吞并后续顶层键（顶层与嵌套各造一例）。
• WARN：上游 frontmatter 残留键、正文专有运行时残留、技能内内容完全相同的副本、description 缺中文/英文半句。
• INFO：嵌套 SKILL.md、说明性引用。
• 退出码 1；正样本 PASS。

注意：裸文件名读引用（tool-index.md、frameworks.md）不由本脚本报出，那是 audit-library.cjs 的 INFO 类。夹具库用完即删，不要放进技能库。

修复规范

路径引用

• 技能内引用一律相对本技能目录；跨技能用 ../<其他技能>/x.md
• 禁止 read ~/...（read 不展开 ~，会解析成 <cwd>~/... 直接 not found）
• 禁止本机真实用户名绝对路径，改用 $env:USERPROFILE

第三方技能（最小改动）

• 只改 frontmatter 与路径引用，正文保持原样，保住上游可同步性
• 交叉引用优于物理合并；合并会丢上游归属与许可证

共享文件去重

• 先按 md5 分组，只有内容完全相同的才算重复
• 两份内容不同时：取超集（或更新版），把另一份独有内容并入；不要随手选体积大的
• 顺序：先改引用 → 再删副本 → 复扫

输出模板

## 技能库审计报告（<日期>）
规模: SKILL.md=<n>  顶层技能=<n>  catalog=<n>
硬门禁: validate-skills.cjs → passed=<n> failed=<n>
宽口径: audit-library.cjs → ERROR=<n> WARN=<n> INFO=<n>
单技能: audit-skill.cjs → 体检=<n> PASS=<n> WARN=<n> FAIL=<n>

真缺陷（已修）
| 位置 | 问题 | 修法 | 验证命令 |

灰色（待你拍板）
- <逐条>

已知误报（未改，分类计数）
- <分类>: <n>

返工记录
- 第 <k> 轮：<失败原因> → <换的思路>

版本: <是否发布 / tag>

常见坑