hj01857655/dsh-verdict

效果评测（dsh-verdict）

中文名称：效果评测；英文名称：Verdict。用于评估规则、技能或模型调整前后的效果，使用可重复的评测与证据判断是否改善。包名 dsh-verdict、命令 verdict 保持不变。

npm version
npm downloads
CI
license
node
GitHub stars
dsh plugin

衡量对 dsh 配置的某次改动是否真的带来了改善。

注册可重复的用例，运行它们，并在你更改规则、技能、模型设置或插件前后对比结果。对 dsh 配置的改动通常感觉像是改进；这个插件能告诉你它是否真的是改进。

状态

已作为 dsh-verdict@0.1.0 发布到 npm。

已实现：捕获、持久化存储、将规则提升到 AGENTS.md、守卫编译、自动重新验证（在常驻宿主中还会每六小时调度一次）、技能蒸馏，以及设置页面。由针对真实文件系统的 87 个单元测试覆盖（npm test），包括面板的静态渲染。CI 在 Ubuntu 和 Windows 上运行。

已在真实硬件上验证：该插件可在 dsh 0.1.5-rc.2 内加载，宿主路由 GET /api/verdict.panel 可提供面板负载，浏览器端在设置中注册了一个“Verdict”页面且无错误。

它的作用

ctx.verdict.learn('never commit the file secrets.env')
// -> rule captured, guard compiled for this platform, written into AGENTS.md
//    behind  -->, and now re-checked on demand

ctx.verdict.check()
// -> { passed, violated, broken, exitCode }
//    exitCode is 1 only for real violations — a guard that cannot run is
//    reported separately and never turns a pipeline red

只有当规则具有可执行检查时，它才会被提升。检查不再成立的规则会被报告；持续失败的规则会在三次不同的违规事件后被降级为 ineffective——不是三次运行，因此长期存在的失败不会虚增计数。

编译器能识别几种句子形态——文件存在、禁止文件、禁止根 glob（“no .pem files”）以及必需文件内容（“the file README.md must mention install”）——并拒绝任何它无法在当前平台上忠实表达的句子，将其保留为候选项，而不是发出一个近似命令。

安装

从 npm 安装（推荐——tarball 附带预构建的 lib/）：

sh
dsh plugin add dsh-verdict --profile web

或者固定到确切的版本：
sh
dsh plugin add dsh-verdict@0.1.0 --profile web

用于无需发布的本地开发：
sh
dsh plugin add link:/path/to/dsh-verdict --profile web

该插件附带了一个 cordis.patch.yml，因此 profile 会在安装时注册它——无需手动插入任何内容。从 GitHub 源码安装无法直接使用，因为 lib/ 被 gitignore 忽略，且 dsh 禁止安装时构建脚本；请改用 npm 或 link:。

CLI

无需启动 dsh 即可访问相同的模块，因此可以独立检查该插件的主张，并且 check 可以在 CI 中运行：
sh
verdict learn "never commit the file .env"    # capture + compile a guard + promote
verdict check                                 # exit 1 on real violations, 0 otherwise
verdict list
verdict recall "env"
verdict session --intent "verify a change" --step "run tests" --step "commit"
verdict skills --write
verdict panel                     # the panel's view of the project
verdict diff before ; verdict diff after ; verdict diff
did that change help? answered from two snapshots
verdict doctor                    # check this package against dsh's plugin rules
verdict inventory --audit         # installed plugins, and what would stop them loading

verdict check 是与 CI 相关的那个：它会在出现真实违规时以非零状态退出，而当唯一的问题是某个无法运行的 guard 时则保持为零，因此 guard 中的拼写错误绝不会单独让流水线变红。

verdict doctor 涵盖了关于加载的所有静态内容——manifest、构建输出、patch id 一致性、peer 放置、生命周期脚本——因此对于真正的 dsh 安装，唯一剩下的就是加载器本身。

Web 面板

该插件还附带了一个浏览器部分（exports["./client"]）。它注册了一个 settings.section 插槽——Settings 内的一个 "Verdict" 页面——并从 GET /api/verdict.panel 读取面板，当存在 web 连接时，宿主部分会在该连接上注册它。没有 web 客户端的宿主会直接跳过它。

该页面只绘制数据支持的内容：一条规则显示 "guard passed"，是因为某个 guard 运行并通过了，而绝不是因为它被提升了；而没有两个快照的前后对比会说明这一点，而不是给出改进。从重复成功中提炼出的技能候选会列出一个写入操作（POST /api/verdict.skills.write）；响应会携带所写入技能的 guard 是否实际运行。

scripts/bundle-client.mjs 复刻了加载器的惰性 CJS 工厂产物（banner、intro vars、footer，react 保留在平台模块表之外）。该 bundle 是 lib/verdict.web.js——刻意不是 lib/client.js，后者是编译后的宿主模块 src/client.ts。

布局

| 路径 | 角色 |
|---|---|
| src/index.ts | 宿主部分——apply(ctx)，暴露 verdict 服务 |
| src/identity.ts | 从文本派生的规则 id，因此重复项会合并为一条规则 |
| src/store.ts | 持久化的 .verdict/ledger.json；原子写入 |
| src/guard.ts | 规则 → shell 命令；运行它；分类为通过 / 违反 / 损坏 |
| src/promote.ts | 将规则写入 AGENTS.md 中的标记之后；验证其存在 |
| src/check.ts | 验证遍历、基于片段的复现、退出码 |
| src/pipeline.ts | learn：捕获 → 编译 → 提升 |
| src/session.ts | 仅追加的会话日志；实际发生了什么 |
| src/skills.ts | 将重复的成功提炼为一项技能（M6） |
| src/cli.ts / src/bin.ts | 命令行入口，无需 dsh 即可使用 |
| src/routes.ts | 宿主 Web 连接上的 GET /api/verdict.panel 和 POST /api/verdict.skills.write |
| src/verdict-view.ts | 载荷 → 视图模型，由宿主路由和浏览器端共享 |
| src/schedule.ts | 常驻宿主的六小时重新检查报告行 |
| src/client/index.tsx | 浏览器端 — 面板状态、fetch、注册 |
| src/client/view.tsx | 浏览器端 — 纯渲染，在 Node 中进行静态测试 |
| scripts/bundle-client.mjs | 以加载器工厂格式进行的 esbuild 打包 |
| cordis.patch.yml | 配置文件注册（insert id dsh-verdict） |
| package.json | 包清单；宿主包保留在 peerDependencies 中 |

载荷必须是同级依赖

dsh 为宿主保留某些包。将其中一个复制到此插件自己的
dependencies 中会产生嵌套或别名副本，配置文件验证会拒绝这种情况。
因此，@deepseek-ai/cordis 以及此插件使用的每个 @deepseek-ai/dsh- 包都应放在
peerDependencies 中（外加用于本地类型检查的 devDependencies），绝不能放在
dependencies 中。

无生命周期脚本

桌面端会拒绝其依赖带有安装生命周期脚本的插件，除非
该包位于桌面项目经过审查的 allowBuilds 策略中。因此，此插件
在安装时不执行任何工作——一切都在 apply 中发生。

开发
sh
npm ci
npm run typecheck
npm run build
npm test
node tests/smoke.mjs   # 针对临时目录的端到端演练