dsh-verify-cheap

一个 DSH 插件，内容只有一份技能：用最低成本验证改动。安装时把包内的 skills/ 注册为一个技能根，于是这份技能随插件进入 agent 的技能目录。

An installable DSH plugin that carries one skill: verify a change with the cheapest check that still yields a definite answer. Installing it registers the package's own skills/ directory as a skill root.

dsh plugin --profile web add github:Ushio155/dsh-verify-cheap

技能正文是中文；SKILL.md 的 description 也是中文（它决定触发）。脚本本身与语言无关，可脱离 DSH 单独使用。 The skill body is written in Chinese, as is its frontmatter description (that text is the trigger surface). The bundled scripts are language-agnostic and run outside DSH.

技能覆盖什么

• 成本阶梯 L0–L3：静态检查 / 探针 / 单个测试套件 / 全量，各自典型耗时与适用场景，以及怎么按"改的是行为还是表现"选档
• 不要用固定延时等后台作业：条件轮询 + 超时；确实需要固定延时的三个并列条件（否则就是猜）
• 断言必须能失败：举不出失败场景的断言等价于没有验证；优先断言具体取值而不是"存在 / 不为空 / 小于 N"
• 耗时必须实测：脚本要打印分段耗时表，并同时给出外部总时长与脚本内计时 —— 两者差距明显说明有句柄 / 连接 / 定时器挂在事件循环上
• 把坑沉淀给下一个会话：读代码读不出来的事实要落进该仓库的长期索引，而不是 README 或阶段笔记
• 何时不该用 / 直接跳档：改动触及公共代码或构建配置 → 直接 L3，不必先走 L0 试探；探索性调试先弄清问题再选档；安全、并发、时序类改动静态检查置信度极低，直接从 L2 起步
• 成本表落位：每次验证记三项（档位 / 实测耗时 / 能否再降一档），表落在仓库根 .verify-cost.md；仓库已有 SUMMARY.md 这类索引时并进其中「成本表」小节

布局

package.json        # dsh.bundle.patch → cordis.patch.yml
cordis.patch.yml    # 插入一行 @deepseek-ai/dsh-skill-filesystem，customSkillDirs 指向 skills/
skills/
  verify-cheap/
    SKILL.md
    references/
      anti-patterns.md        # 恒真断言、等价反模式、手写轮询的两个坑
      cost-measurement.md     # 计时实现、内外差异判定、成本表模板
      probe-cookbook.md       # 探针外壳规范与各技术栈写法
    scripts/
      wait-until.mjs
      measure-runtime.mjs

cordis.patch.yml 用 createRequire(baseUrl).resolve('<包名>/package.json') 定位本包目录，再把 skills/ 拼上去 —— 这与 DSH 自带 agent preset 装载自己技能用的是同一套写法。providerName 必须每包唯一——技能注册表拒绝同名 provider，所以默认值 filesystem 会和 harness 自带 provider 以及任何用同一机制的插件撞名；includeDefaultRoots: false 让这个 provider 只管自己的目录（project / user 根由 harness 自带 provider 负责，不用重复声明）。

⚠️ 不要用 new URL('skills/', baseUrl) 那种写法。 baseUrl 锚在 profile 目录，不是包目录；那种写法会静默指向 <profile>/skills，目录不存在，于是一个技能都加载不出来，而且不报错。

这条是实测出来的，不是推断：在同一个已安装的 profile 里， ① 按 new URL 写，放一个只存在于包内的探针技能 → 技能目录里看不到； ② 只改这一行成 createRequire 写法 → 探针立刻出现； ③ 删掉探针 → 又消失。 同 profile、同安装、同提问，唯一变量是那一行。若你的技能装上了却"没生效"，先查这里。

peerDependencies 用的是 "*"，理由如下

官方 @deepseek-ai/* 包按 awesome-dsh-plugin 贡献指南的建议声明为 peerDependencies 而非 dependencies，范围写 "*"。

但 "*" 在裸 semver 下并不匹配预发布版本。实测（npm 自带的 semver 库）：

semver.satisfies('0.1.7-rc.2', '*')                              → false
semver.satisfies('0.1.7-rc.2', '*', { includePrerelease: true }) → true
semver.satisfies('0.1.7-rc.2', '>=0.1.0-rc.1 <0.2.0-0')          → false   ← 指南推荐的写法也失效
semver.satisfies('0.1.7-rc.2', '>=0.1.7-rc.1 <0.2.0-0')          → true

而本机装的 harness 正是预发布版本：@deepseek-ai/dsh-skill-filesystem@0.1.7-rc.2（cordis 是稳定的 4.0.4）。

• 贡献指南给的 || 分支写法（>=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.2.0-0）确实修好了它举的那个例子，但只覆盖被写明元组的那一个版本：0.1.7-rc.2 依然不满足，因为该范围里没有任何 0.1.7 元组上的预发布比较符。照抄它，就会在 harness 下一次 rc 跳元组时把一个真实环境静默排除掉。
• 所以这里保留 "*"，并把这条当作已记录的已知事实，而不是加一个会随时间腐坏的范围。实测 dsh plugin add github:Ushio155/dsh-verify-cheap 安装成功、技能正常加载 —— 即该 peer 范围未被判定为不满足（pnpm 是不满足时只告警、还是按 includePrerelease 判定，没有进一步区分）。

结论：在 DSH 插件里写死 @deepseek-ai/* 的预发布范围，比写 "*" 更危险。

两个脚本（零依赖，Node >= 18）

两个脚本都不依赖任何第三方包（只用 node: 内建模块），可以脱离 DSH 直接跑。它们自身只做等待与计时；被执行的是你传给它们的命令。

wait-until.mjs —— 条件轮询 + 超时

替代脚本内的固定延时：每次尝试都重新判断条件，条件满足即刻返回，超时则失败退出，因此不会出现"条件早满足要重试、晚满足就白等"。

node skills/verify-cheap/scripts/wait-until.mjs --timeout 120 -- npm run build
node skills/verify-cheap/scripts/wait-until.mjs --timeout 90 --file out/index.js
node skills/verify-cheap/scripts/wait-until.mjs --timeout 30 --port 3080
node skills/verify-cheap/scripts/wait-until.mjs --timeout 120 --match "listening on" -- npm run dev

也可以当库用：

import { waitUntil } from '<plugin-dir>/skills/verify-cheap/scripts/wait-until.mjs';
await waitUntil(() => isReady(), { timeoutMs: 60_000, intervalMs: 500, label: '被测对象就绪' });

退出码：0 条件已满足 / 1 超时 / 2 参数错误。--match 需要捕获子进程 stdout，在禁止管道 stdio 的受限沙箱中不可用（脚本会用 --help 说明这一点）。

measure-runtime.mjs —— 实测耗时

两种用法：

CLI 模式测任意命令的外部总时长（从子进程启动到退出），退出码透传子进程退出码，无法启动时为 127：

node skills/verify-cheap/scripts/measure-runtime.mjs --label "L2 集成测试" -- npm test
node skills/verify-cheap/scripts/measure-runtime.mjs --json -- pwsh -File build.ps1

库模式才提供分段耗时与内外对比 —— 按 [小节] 边界打印分段表，并同时给出外部总时长与脚本内计时，把两者差值标出来。汇报耗时可以直接引用它，而不是凭印象：

import { createTimer } from '<plugin-dir>/skills/verify-cheap/scripts/measure-runtime.mjs';
const timer = createTimer('L2 注入回归');
timer.start('prepare');
// ... 被测工作 ...
timer.end('prepare');
await timer.section('run', async () => { /* ... */ });
timer.report({ exit: 0 });   // 省略 exit 则不退出进程

报告之后进程若仍存活，退出钩子会补测那段耗时并告警 —— 这正是"有句柄 / 连接 / 定时器挂在事件循环上"的常见表现。

License

MIT