收尾哨兵 566001/dsh-wrapup-guard

dsh-wrapup-guard · 收尾哨兵

EN — 一个 DeepSeek Harness 插件，把「任务做完了」变成一道关卡：它强制走 检查 → 修复 → 再检查 的循环，自动跑命令类检查，只要哪一轮还有没修好的问题就拦下，只有连续三次全面检查都干净才判定任务完成 —— 然后通知用户。
专门用来拦住「差不多得了」式的交差。

一个 DeepSeek Harness 插件：在任务收尾时强制「检查 → 修复 → 再检查」的循环，直到连续三次全面检查都没有发现问题，才判定收尾完成并通知用户。

它的存在意义只有一个：拦住「差不多可以了」。

它解决什么问题

AI 干完活常说「改好了」，但没跑测试、没看有没有引入回归、没核对文档。
这个插件把「收尾」变成一个有门槛的动作：

全面检查 → 发现问题 → 修复 → 再全面检查 → …
↑__________________________|
直到连续 3 轮零问题 → 通知用户「收尾完成」

只要有未修复的问题就必然被打回；哪怕这轮只是修了个小 bug，也不算干净 （计数归零）。这样才不会被「边查边修、修完就说好了」糊弄过去。

分工

| 谁 | 负责什么 |
| 插件 | 轮次状态机、连续干净计数、自动跑命令类检查（测试 / lint / audit）、判定放行、通知用户 |
| AI | 代码审查、构建 / 运行验证、一致性检查，以及真正的修复动作 |

插件是纯 JS，它没法「理解」代码审查发现的问题并动手修 —— 那是 AI 的活。
插件做的是纪律：计数、拦截、放行、报告。

用法

AI 在判断任务做完时调用 wrapup_check（也会在系统提示里被提醒这么做）：

| action | 作用 |
| start | 开始一次收尾自检，重置计数。会顺带探测项目里可自动运行的检查命令并告诉你。 |
| check | 插件自动跑命令类检查，把原始输出抓回来给你看。 |
| report | 汇报本轮全面检查的结论。必须带 problems 数组（空数组才表示干净）。 |
| status | 看当前轮次、连续干净计数、各轮摘要。 |
| abort | 放弃本次收尾。 |

report 的参数：

- problems：本轮发现的问题列表，每项 { kind, where, what, fixed }。
有 fixed !== true 的项就会被立刻打回；有修复动作的轮次不计入「连续干净」。
- checks：本轮你手动做过的检查类别（review / build / consistency）。
缺项时插件会提醒你还有哪类没做。
- summary：本轮小结（会出现在最终报告里）。

自动探测哪些命令

在项目根目录按顺序找：

1. package.json 的 scripts.test / scripts.lint / scripts.typecheck / scripts.check
2. tools/audit.js、tools/check.js、tools/selftest.mjs

探测不到就返回「没有可自动运行的检查」——这是合法结果，不是错误，意味着命令类检查要靠 AI 手动完成。

为什么 check 和 selftest.mjs 也在白名单里：本插件自己的仓库用的就是
npm run check + tools/selftest.mjs。旧白名单只认 test/lint/typecheck，
结果它连自己都检查不了，每次自检都报「没有可自动运行的检查」。
这两个名字同样是约定俗成的检查名，纳入白名单不是「猜脚本内容」。

仍然不做的是：扫描 scripts 里所有 key 全跑一遍。check 已经是最宽的安全边界，再往外扩就可能跑到构建、发布之类有副作用的脚本。

Windows 上怎么跑这些命令

npm 在 Windows 上只是 npm.cmd 批处理垫片，没有可执行文件，所以：

- 直接 execFile('npm', …) 会以 ENOENT 失败；
- .cmd 又因为 Node 24 的 CVE-2024-27980 补丁禁止带参数直跑（EINVAL）。

因此 Windows 下统一交给 cmd.exe /d /s /c 解析，并只给确实需要的 token 加引号（每个 token 都套引号反而会让 cmd 把 ""npm" "run"" 当成一个整体命令名）。非 Windows 平台走原来的 spawn + 裸参数。

超时必须杀整棵进程树：npm → cmd.exe → node 是一条链，child.kill() 只放倒第一环，孙进程会继续持有 stdout 管道，'close' 要等它自己结束才触发—— 超时就形同虚设（实测 2 秒超时拖到 60 秒才返回）。所以超时走 taskkill /T /F，并额外挂一个 5 秒兜底定时器，保证一定会收尾。

通知

达到「连续 3 轮零问题」时：

- 宿主端写一份完成记录，并通过 /dsh-wrapup-guard/status 暴露给浏览器端；
- 浏览器端轮询这个路由，右下角弹出完成卡片（含汇总：共几轮、修了几个问题、完整报告），12 秒后自动收成小徽章，点开可再看；
- 工具返回值里同时带完整报告，AI 会把它转述给用户。

安装

// profiles/<profile>/package.json
{
"dependencies": {
"dsh-wrapup-guard": "^0.1.0"
},
"dsh": {
"profile": {
"bundles": ["…", "dsh-wrapup-guard"]
}
}
}

本地开发时依赖可写 file:/absolute/path/to/dsh-wrapup-guard；从 npm 安装则直接写版本号。

然后在该 profile 目录用 DSH 自带的 pnpm 安装：

node <DSH>/resources/runtime/pnpm/bin/pnpm.cjs install --no-frozen-lockfile

file: 依赖会被复制进 profile 的 node_modules，所以改了源码之后要重跑 install 才能在 DSH 里生效。

改完需要重启 DSH（插件行的加载在启动时完成）。

自检

node tools/selftest.mjs # 状态机 30 项断言（不打桩 DSH）
node tools/check-commands.mjs <项目路径> # 验证自动探测 + 真实跑命令

设计取舍

- 不 import 任何 @deepseek-ai/*：profile 安装的插件从自己的目录解析模块， harness 包在那里不可达。全部走 ctx 和 node 内置模块。
- 状态落盘到 ~/.dsh/wrapup-guard/<sessionId>.json：收尾循环会跨很多轮工具调用，DSH 中途重启也不该把计数丢掉 —— 否则 AI 会误以为「三轮干净」已达成。
- 每轮都必须重新做全面检查，而不是只看刚改的地方：这正是「发现 → 解决 → 检查 → 发现」循环的价值所在。
- 状态机对「漏报」没有任何自动化防御（AI 撒谎插件管不了），所以系统提示里明确写了诚实要求，且每轮会核对 AI 声明的检查类别是否齐全。

License

MIT