@caesarloo/dsh-skill-audit 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caesarloo/dsh-skill-audit",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Audit DSH skills automatically: a host-layer tools/post-execute plugin that ships both the skill body and the audit engine, runs the engine after skill files change (write/edit/shell) or after a bulk restore/backup (any tool invoked with mode: restore|backup), feeding findings back to the model as context; also registers the skill_audit tool.",
   "keywords": [
     "dsh",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ category: quality
 description: "DSH 技能的审核通道：以确定性脚本对技能做静态体检——frontmatter 契约、脚本可用性（UTF-8 BOM + PowerShell 5.1 可解析）、SKILL.md 引用完整性、敏感信息与凭据泄漏、机器专属路径、危险命令模式；并提供技能被修改或从备份仓库恢复后自动执行审核的通道（结论作为上下文回传给模型）。当技能被新建/修改/从备份恢复、技能里的脚本改过、多机同步技能之后，或需要回答『这个技能是否可用、有没有把密钥写进去、引用的脚本还在不在』时使用。触发词：技能审核、skill audit、审核技能、技能体检、技能改动后检查、恢复技能后检查、技能脚本没BOM、技能引用失效、技能泄漏密钥。"
 whenToUse: "技能新增或修改之后（尤其改了 SKILL.md 或技能内脚本）；从备份仓库恢复技能之后；跨机同步技能之后；排查『技能加载了却不管用』（脚本跑不起来、引用文件缺失）时；提交技能进备份仓库之前做入库前体检。"
 last_updated: 2026-09-17
-version: 1.1.0
+version: 1.1.1
 created_by: agent
 metadata:
   hermes:
@@ -63,7 +63,8 @@ metadata:
 
 1. 技能语义是否正确、步骤是否最新（脚本已改但 SKILL.md 没跟上）；
 2. 触发词是否覆盖真实说法（模型是否会在对的场景加载它）；
-3. 记录是否过期（引用了已卸载的插件、已改名的工具、已废弃的路径）。
+3. 记录是否过期（引用了已卸载的插件、已改名的工具、已废弃的路径）；
+4. **正文里的可执行片段是否真跑过、并留了实测结论**（见 §3.1）。
 
 ```powershell
 # 全量体检（人读）
@@ -80,6 +81,19 @@ powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.dsh\skill
 
 深度审核做完后应把结论落成档案，内容包含：审核时间、静态结论、人工核对的语义项、结论（可用 / 需修 / 建议重写）、遗留风险。**落档位置由你本机的约定决定**（通常放你自己的笔记或备份仓库）——别把本机路径写进技能正文。
 
+### 3.1 写作纪律：可执行片段必须真跑过，并在正文留实测结论
+
+**凡写在正文里供人直接复制执行的片段**（PowerShell / bash / SQL / 配置块），**作者必须真跑一遍，并把实测结果写进正文**（时间 + 结果，形如"2026-09-17 实测：exit 0，命中 2 条"）。脚本资产（技能 `scripts/<脚本名>.ps1`）同样适用——判据 S1 只保证**能解析**（BOM + 语法），**不保证跑得对**。
+
+**这条只能靠人守，静态引擎查不了**：引擎不执行片段，也无从知道它跑没跑过。而正文片段恰恰是使用者会**直接复制执行**的东西——一段没跑过、或跑不通的片段，会让人照着做却得出**相反结论**，比不写更糟。
+
+**最危险的不是报错，是假阳性**。实例（2026-09-17）：一个"比对两侧文件哈希"的验收片段先是硬编码了错误入口路径，两侧 `Get-FileHash` 双双失败、变量都成了 `$null`，而 `$null -eq $null` 成立——于是把**根本没找到文件**的项打印成「✓ 逐字节一致」。它不报错、满屏绿色，给出的正是"验收已通过"的错觉。
+
+由此两条写法要求：
+
+- **取不到数据必须显式失败**：任何"两侧比对"类片段都要先做存在性 / 取值守卫（`Test-Path`、非空判断），**绝不能让"两边都取不到"落进"相等"分支**；
+- **不硬编码会变的细节**：入口路径、字段名、分隔符这类随对象变化的东西，从对象自身读（如包内 `package.json` 的 `main`），而不是假设它长什么样。
+
 ## 四、审核项与判据
 
 | 代码 | 检查 | 级别 | 判据 |