dsh-contract-check
DeepSeek Harness 插件的契约检查：静态验证已注册工具的 output.render() 返回 ContentBlock[]，并在会话事件类型超出内核词汇表时发出警告。仅警告。契约体检插件（不检测恶意）。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:imtokenxinluo/dsh-contract-check#da00daa063f022d7ccf61d2148bb7cc15ccb9d17Contract Check 以 dsh-contract-check 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
点击下方 Badge 复制 Markdown，粘贴到 README 即可。
验证 package.json 声明的 GitHub 仓库，即可管理这个公开页面。认领后，Hub 会优先安排当前版本的安全扫描，并在通过后公开展示结果。
认领这个 Plugin →它检查「契约合规」，不检测恶意，也不拦截执行。
本工具回答一个问题：当前装着的插件，有没有在违反 DSH 的内核契约—— 写坏会话历史的那个雷，现在是不是还埋着。
render() 返回字符串（会让整条会话历史无法加载）、插件写入词汇表外的会话事件类型如果你要的是"防投毒"，这个工具帮不了你；如果答案是"是"的那类事故——它真能挡住。
DSH 社区已有成熟的插件审计工具，本工具不是首创。诚实的定位如下：
omdsh-dev/dsh-plugin-check | 本工具 | |
|---|---|---|
| 扫描对象 | 插件仓库目录（发布前） | 运行中的工具注册表（安装后） |
| 检查内容 | 清单协议 / patch 格式 / 构建陷阱 / hub 收录 / 生态合规，33 项 | 只两条：render 契约、会话事件类型词汇表 |
| 覆盖范围 | 更广（打包、命名、patch、hub 状态） | 更窄（但更深） |
| 压缩/无源码的插件 | 看不到（扫源码树） | 照样看得见（读的是注册表里的定义） |
| GUI 状态徽章 | ❌ | ✅ |
| token 成本 | ⚠️ 注册了模型工具 plugin_check（每请求付 schema 税） | 0 |
同组织还有：dsh-session-health（会话文件帧级健康）、dsh-security-audit（凭据/暴露面）。
因此：
dsh-plugin-check（更全）。
本仓库的 package 子命令只是轻量版（只查"声明要用的文件会不会被漏发"这一类），
够用就好，不够请用他们那个。两者互补而非竞争：他们管"发出去之前对不对"，本工具管"装进来之后有没有在埋雷"。
本插件不注册模型工具、不注入提示词、不产生模型可见输出。
它唯一的对外输出是 ctx.logger.warn(...)——只进控制台/日志，不进模型上下文。
所以它对你每轮对话的 token 消耗零影响。
这条是硬约束，不是巧合：一个模型工具的定义（名字+描述+参数 schema）会进入每一次请求的 上下文，几十轮对话就是上万 token，不管你用没用它。任何"要让 agent 知道"的功能都要付这笔税， 因此本插件永远不加模型工具。
GUI 状态页/徽章不受此约束：它是浏览器侧代码，不进模型上下文，所以 token 成本仍然是零。
装进 profile 并重启后，会话头部会多出一个小按钮：一个颜色圆点 + 「体检」二字。 鼠标移上去展开完整状态条：
🟢 无耗 · 检查 21 个插件 · 违规 0 · 不可判定 1
界面上就只有这一个按钮，没有 Tab、没有面板。理由很直接： 体检是后台该做的事，不该要求用户主动去翻页签。检查由插件自己跑 （加载时 + 工具注册表变化时），按钮只是"想立刻确认一下"的入口。
点击后的反馈（0.5 秒）：圆点变成转圈、文字变「体检中…」、按钮禁用防连点。 即使体检只花几十毫秒，动画也会转完这半秒——否则就是"点一下闪一下"，比不动还难看。
另外设置页会多出一栏「无耗检查」，里面是自愿打赏（装了 dsh-tip-jar 才显示）。
打赏放在设置页而不是日常视野里，是因为它跟体检本身没关系，不该天天占地方。
| 颜色 | 含义 |
|---|---|
| 🟢 绿 | 体检过，0 违规，且确实验证到了东西 —— 健康 |
| 🟡 黄 | 体检过，有违规 —— 有插件在写坏会话的风险 |
| ⚪ 灰 | 尚未体检 / 无法枚举 / 全部判不准 —— 诚实显示"不知道"，绝不假装健康 |
不可判定（unknown）不影响颜色：那是"判不准"，不是"有问题"。
把它算成风险会让你天天看到黄色，然后就再也不看这个颜色了。
但有一个例外（实机教训）：如果 21 个插件全部判不准，那不是"健康"，是"什么都没验" —— 这时显示灰，状态条会写明"全部判不准，等于没有验证"。 绿色必须意味着"真验过了"。
| 手段 | 做法 | 局限 |
|---|---|---|
| 静态 | 读 render 源码，看 return 的是不是数组 | 对 defineTool 写的工具永远失效（见下） |
| 实测 | 按 output.schema 造假数据，真调一次 render，看返回值 | 假数据不合形状时会抛异常 → 归 unknown |
内核的 defineTool 会把作者的 render 包一层：
// 我们读到的是这个壳 —— 函数体只是一句"调用别人"，静态永远看不透
render(args, value) { return userRender(args, value); }
所以静态检查对绝大多数正经插件都只能报 unknown（实机实测：21/21 全 unknown = 等于没检查）。
实测是必需品，不是可选项，因此默认开启（probeRender: false 可关）。
实测的边界（重要）：调用失败绝不等于违规 —— 假数据不合形状会让 render 抛异常，
那是检查器自己的问题，所以一律归 unknown，绝不误报成 violation。
实机效果：21 个插件 → 实测判定 20，剩 1 个如实说"判不准"。
实现方式（刻意从简）：
ctx.webServer 注册两条同源 HTTP 路由：
GET /contract-check/status —— 最近一次体检结果（JSON，含 diag 诊断）POST /contract-check/audit —— 立刻体检一次src/client.js → lib/client.js）只做两件事：fetch 上面两条路由 + 渲染
409（枚举注册表是 CPU 活，不排队堆叠）ctx.inject([...], cb) 延迟注入：
tools 与 webServer 都可能在 apply 之后才就绪（实机踩到过两次：
直接读 ctx.tools / ctx.webServer 会静默失败，界面只能是灰点）。
/status 的 diag 字段会告诉你注入是否触发、用了哪个访问器、view() 返回什么形态。⚠️ 客户端产物需要构建：
npm run build（用本机已有的 esbuild，不联网安装）。 构建产物lib/client.js必须存在，否则 DSH 启动会报 "client bundles not found"。files白名单已含lib，避免打包时漏发（这正是本工具自己检查的那类错误）。
DSH 的写路径宽松、读路径严格，而失败模式是整条会话而不是"那一条记录"：
| 契约 | 违反的后果 | 真实事故 |
|---|---|---|
output.render() 必须返回 ContentBlock[] | 加载器报 SessionPersistenceCorruptionError，整条历史打不开 | 2026-09：dsh-ssh-ops 的 sftp_*/tunnel_* 返回裸字符串，多个会话失联 |
会话事件类型必须在 KNOWN_SESSION_EVENT_TYPES 内 | 加载器拒绝解释整条日志（"unknown to this harness and not marked ignorable"） | 社区多次报告（dsh-agent-teams 等） |
第二条有个容易忽略的硬事实（本工具核验过内核源码）：
if (KNOWN_SESSION_EVENT_TYPES.has(event.type) || event.ignorable === true) continue;Session.append(type, data, ...opts) 的 opts 只接受 sourceEventSeqs / surfaceOp
—— 插件没有设置 ignorable 的入口；而且整个内核里不存在任何 ignorable: true 的赋值结论：插件写一个自定义事件名 = 使用者的会话打不开，且作者无法自救。
把包加进 profile 依赖与 bundle 列表：
// profiles/<profile>/package.json
{
"dependencies": { "dsh-contract-check": "^0.1.0" },
"dsh": { "profile": { "bundles": ["...", "dsh-contract-check"] } }
}
本地开发可以写成
"dsh-contract-check": "link:D:/tool/claude_code/dsh-contract-check"——改代码即时生效，但改完客户端要重跑npm run build再重启 DSH。
它会做三件事：
ctx.tools.view() 里可见的工具定义，逐个静态检查 output.rendersession/event，发现表外事件类型立刻告警插件注册顺序不可控，所以本插件也会监听
tools/change：先加载时注册表还是空的就保持安静， 等注册表变化后再体检（同一问题只告警一次，不刷屏）。
dsh-contract-check scan <文件或目录> # 递归扫源码里的 render 定义
dsh-contract-check package <包目录> # 检查 npm 打包会不会漏发声明要用的文件
dsh-contract-check vocab # 打印内嵌词汇表版本与条目数
package 检查的是"整树起不来"那类事故：package.json 声明要用的文件
（dsh.bundle.patch / exports 目标 / types）有没有被 files 白名单漏在包外。
⚠️ 这是轻量版：只覆盖"声明要用的文件会不会被漏发"这一小类。 完整的插件仓库体检（清单协议 / patch 格式 / 构建陷阱 / 命名 / hub 收录，共 33 项） 请用社区成熟的
omdsh-dev/dsh-plugin-check。 本工具的重点始终是运行中的注册表与会让会话打不开的契约，不是发布前的仓库检查。
它是按 npm 的真实语义判定的（用一次性实验实测，不是猜）：
| npm 行为 | 文件 |
|---|---|
| 总是包含（不会漏） | package.json、README*、LICENSE*、CHANGELOG*、main 指向的文件、bin 指向的文件 |
不自动包含（必须在 files 里） | exports 的目标、types、任何自定义字段——含 dsh.bundle.patch |
files 无此字段时 | 默认全打包，无遗漏风险 |
它不运行 npm、不执行被检查包的脚本——
npm pack会跑prepack/prepare， 对不受信任的包是危险的，所以白名单判定是本工具自己实现的。
发现 violation 时退出码为 1，便于串进脚本或 CI。
unknown| 判定 | 含义 |
|---|---|
ok | 返回值形态正确（静态看出是数组，或实测返回数组） |
violation | 返回字符串 / 非数组 / undefined（静态命中，或实测证实） |
unknown | 判不准（静态看不透 + 实测也失败）——如实说不知道 |
宁 unknown，不 violation 是这个工具的硬原则：误报会让人卸载好插件、并从此不信任检查器。 所以：实测调用抛异常一律归 unknown（那是假数据不合形状，是检查器自己的问题）； 全不可判定时状态显示灰而不是绿（什么都没验 ≠ 健康）。
几个由此得来的实现细节（都有测试锁定）：
[{ text: lines.join("\n") }] 是数组（.join 在数组内部），而 [...].join("") 是字符串return：render 内部的箭头函数/局部函数里的 return "x"
不属于 render 的返回值render(a, v) { ...map((i) => ...) } 是方法简写，
不能因为体内有 => 就当成箭头函数output.schema 造形状合法的假数据（含 required 字段、数组、嵌套对象，有深度上限）；
自引用的病态 schema 不会卡死npm run verify:real 对真实已装代码跑一遍：
真实代码合计：render=52，误报 violation=0
合成样本：violation=2（应 > 0，证明检测有效）
✓ 通过：真实代码零误报，且对已知违规有效
dsh-ssh-ops@0.2.1（15 个 render，0 violation——该版本已修好）。
作为对照：修复前的同款代码会返回裸字符串，正是本项目要防的那类事故把本仓库要防的那次事故原样复现（dsh-session-doctor 修复前的提交 896f6da^）：
$ dsh-contract-check package <修复前的包>
VIOLATION ...（1 项会被漏发）
· cordis.patch.yml
在 files 白名单之外，npm 不会打包它：dsh.bundle.patch（漏发 = 插件树拒启）
——这正是当初让整个插件树拒绝启动的那个 bug。8 个真实已装包中 7 个判 ok
（零误报），唯一命中的 @opendsh/dsh-plugin-scheduled-tasks 是真实瑕疵：
它用 "./src/*": "./src/*" 导出子路径，但 src 不在 files 里 → 安装后该路径 import 会失败。
词汇表漂移检查：npm run verify:vocab → 内嵌 44 条 vs 内核 44 条，一致。
unknown，不是"没问题"tools.guard() 注册执行前守卫——那会影响正常工作，
是另一个决策（见下方"设计取舍"）@deepseek-ai/dsh-session@0.1.0-rc.6。
升级 DSH 后请跑 npm run verify:vocab，不一致就 npm run gen:vocab 重新生成并复核render() 能大幅提高判定率
（实机：静态 21/21 判不准 → 加了实测后 20 个能判定）。
代价是它会真的执行一次插件代码；假数据不合形状时一律归 unknown，绝不误报成违规。
要关：probeRender: falsefiles 是否漏了 dsh.bundle.patch 指向的文件）：那是「包在磁盘上的属性」，
用 npm pack --dry-run 核对，注册表里看不到link: 接入后，
会话头部出现状态按钮，实机读数 无耗 · 检查 21 个插件 · 违规 0 · 不可判定 1
（其中实测判定 20）。两点如实说明：
无耗 · 检查 23 个插件 · 违规 2 · 不可判定 1，且点名准确。
夹具验证完即移除。顺带验证了实测探针的价值：一个静态判不准的 render，
被实测抓成了真实违规 —— 静态看不透的，跑一次就清楚。tools/change 的作用域是否到达本插件也未验证，因此插件额外做了兜底：
首次见到会话流量时补做一次体检。npm run build # 构建客户端产物 lib/client.js（改了 src/client.js 后必须先跑）
npm test # 168 个用例：判定三态 / 实测 / 审计 / 词汇表 / 插件壳 / 源码扫描 / 打包检查 / 状态与路由 / 客户端产物 / CLI
npm run verify:real # 真实代码零误报验收
npm run verify:vocab # 词汇表漂移检查
npm test会校验产物里盖的源码指纹：改了src/client.js却忘了npm run build会直接测试失败（否则用户拿到的是旧界面）。
MIT