harnessmm-dsh
Verifiedharnessmm-dsh · v1.2.5 · Apache-2.0 · Web UI
Guarded decision reuse for the DeepSeek Harness: the model authors already-decided tool actions once, and receipt-supported ones execute through the native tools without another reasoning request. Ships a read-only decision-reuse panel with per-number dat
Install
dsh plugin add harnessmm-dsh Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
HarnessMM 决策复用面板
给 harnessmm-dsh 加一个只读的可视化面板,面板上每个数字都能追溯到插件的具体内部状态。
1. 架构
┌─────────────────────────────────────────────────────────────┐
│ Host 进程(插件所在进程) │
│ │
│ index.js ──┬─ controller (GuardedReuseController) │
│ ├─ counters (8 个计数器) │
│ └─ admissions (环形缓冲,上限 2000) │
│ │ │
│ ▼ │
│ snapshot.js ← 纯函数聚合,带 provenance │
│ │ │
│ panel.js ← 注册 3 条只读路由 │
│ │ │
│ ┌──────────┼──────────┐ │
│ ▼ ▼ ▼ │
│ /status /panel /health │
│ (JSON) (HTML) (JSON) │
└─────────────────────────────────────────────────────────────┘
│
▼
浏览器打开 /panel → 每 2s 拉 /status → 渲染
或 DSH 右侧栏 tab(client.js 内嵌 iframe)
关键取舍:面板本体是 Host 直接提供的完整 HTML 页面,不是浏览器侧重写的 UI。这样:
- 面板可以独立在浏览器打开(新标签页),不依赖 DSH 客户端环境
- 客户端 bundle 只需一个
<iframe>,浏览器侧不可测的表面积压到最小 - UI 与数据格式在 Host 侧就能完整测试
2. 数据溯源对照表
面板上每个数字的出处,代码里也逐项写进了快照的 provenance 字段。
| 面板显示 | 数据来源 | 代码位置 | 生命周期 |
|---|---|---|---|
| 拦截请求 | counters.requests |
index.js llm/stream 边界计数 |
进程重启归零 |
| 跳过推理 | counters.substitutions |
同上,替换分支计数 | 进程重启归零 |
| 签发证书 | counters.certificates |
record() 收到 gdr/substitution-certificate |
进程重启归零 |
| 动作库 | counters.banksAuthored |
record() 收到 gdr/bank-authored 且 admitted=true |
进程重启归零 |
| 守卫命中率 | substitutions / (substitutions + deferrals + uncertified) |
snapshot.js:guardHitRate |
同上 |
| 为什么没命中 | admissions 中 gdr/pre-admission 的 rejected[].reason |
snapshot.js:rejectionBreakdown |
缓冲 2000 条 |
| 守卫字段分布 | certificates[].guard 的键 |
snapshot.js:guardFieldUsage |
同上 |
| 被替换的工具 | certificates[].exact_native_tool |
snapshot.js:toolUsage |
同上 |
| 按会话分布 | certificates[].session |
snapshot.js:sessionUsage |
同上 |
| 动作库 DAG | controller.sessions[*].banks(Map) |
snapshot.js:collectBanks |
进程内存 |
| 替换证书 | admissions 中 gdr/substitution-certificate |
snapshot.js:collectCertificates |
缓冲 2000 条 |
| 趋势曲线 | certificates[].steps_after(真实步号) |
snapshot.js:trendSeries |
同上 |
| 事件流 | admissions 全量 |
snapshot.js:eventClassCounts |
缓冲 2000 条 |
| 审计行数 | $DSH_HOME/harnessmm-audit.jsonl 行数 |
panel.js:countAuditLines(增量读,只读新增字节) |
磁盘持久,超过 8 MiB 轮转为 .1 |
| 统计口径 | 快照里的 scope / session / knownSessions |
snapshot.js:buildSnapshot |
每次请求现算 |
口径(1.2.0 起):上表除「审计行数」外,都可以按会话过滤。 面板默认只统计当前对话,读的是
index.js:sessionCounters[<sessionId>]; 点右上角角标切到「全部会话」才读进程级的index.js:counters。 「审计行数」是全局一个 JSONL 文件,不分会话,面板上会如实标明。
9 种事件 → 5 个分类(分类表在 snapshot.js:EVENT_CLASS,键与插件实际记录的 kind 逐字对应):
| 分类 | 包含事件 |
|---|---|
| 授权 | gdr/bank-authored · gdr/bank-recovered · gdr/invalid-bank |
| 准入 | gdr/pre-admission |
| 替换 | gdr/compiled-native-action · gdr/substitution-certificate |
| 拒绝 | gdr/uncertified-execution · gdr/session-identity-mismatch |
| 延迟 | gdr/defer |
3. 三态判定
面板状态完全由真实计数器推导,没有人工开关:
substitutions > 0 → C 正在复用
banksAuthored > 0 → B 已授权·等待命中
否则 → A 已启用·尚未产出动作库
A 态不是「全 0」:它会显示「已拦截 N 次推理请求(M 个会话),但没有一次写出合格的 CHISEL_PLAN」。
这个数字来自 counters.requests,能证明插件确实在工作,避免用户误以为插件坏了。
4. 安装
4.1 一行安装(推荐)
在 DSH 的 插件页 → 添加插件 里填包名:
harnessmm-dsh
或者在终端里:
npm i harnessmm-dsh
装完重启 DSH,对话页签条会多出「决策复用」页签。
也可以填 GitHub 地址
https://github.com/Xiuxiu-6/harnessmm-dsh,装的是 main 最新代码;npm 版是稳定版。
4.2 手动复制(仅开发用)
把本目录下这些文件整份覆盖到
~/.dsh/profiles/<你的 profile>/node_modules/harnessmm-dsh/:
index.js engine.js panel.js snapshot.js web-routes.js
panel.html client.js package.json cordis.patch.yml
client.js 是构建产物(npm run build:client 生成),不要手改。
⚠️
cordis.patch.yml必须一起复制。里面insert[].name必须等于package.json的name(当前是harnessmm-dsh)。名字对不上时加载器import(name)直接失败,插件静默不激活——面板只会显示「读取失败」, 不报错、不提示,很难查。
4.3 确认它真的加载了
重启后先看路由有没有注册(<端口> 换成实际端口):
curl -i http://127.0.0.1:<端口>/plugins/harnessmm/health
| 返回 | 含义 |
|---|---|
401 {"error":"unauthorized"} |
路由已注册,插件加载成功(401 是认证层在拦,正常) |
404 且 body 为空 |
路由不存在,插件没加载——先核对 cordis.patch.yml 的 name |
面板本身也有一张降级卡片:读不到 /status 时会写「宿主插件可能未启动或路由未注册」。
4.4 重启
桌面端重启应用;CLI 端重启对应 profile 进程。
4.5 打开面板
两种方式:
A. 独立浏览器标签页(推荐先验证)
http://127.0.0.1:<你的 DSH 端口>/plugins/harnessmm/panel
端口看 DSH 启动时打印的 URL,或环境变量 DSH_WEB_URL。
B. DSH 右侧栏 tab
重启后右侧栏应出现「HarnessMM」tab。若未出现,见 §6 已知限制。
4.6 面板统计口径:跟着对话走
面板默认只统计当前打开的这一个对话:
- 打开对话 A → 显示 A 的跳过次数、证书、动作库
- 切到对话 B → 面板立刻换成 B 的,不会带着 A 的数字
- 新建对话 → 全部是 0,并说明「本会话还没有被插件记录」
右上角有个角标:
[ 本会话 · 3f2a1b8c ] ← 默认,只统计当前对话
[ 全部会话 ] ← 点一下切换,看进程内所有对话的总账
- 切换按钮会记住选择(存在
localStorage的harnessmm.scope) - 右侧栏那个 tab 和对话头部页签行为一致,都跟随当前对话
- 会话 id 取的是宿主
uiSession.current,和引擎记录用的sessionId是同一个 UUID
为什么改:1.1.x 的计数器是进程级的,面板却写着「本会话」——
数字对不上,属于措辞错误。1.2.0 把计数按会话拆开(index.js:sessionCounters),
面板的口径和文字现在一致了。
5. 验证
5.1 自动化测试(不需要装进 DSH)
node test-snapshot.mjs # 聚合逻辑:驱动真实 engine.js 跑完整流程
node test-panel-contract.mjs # 面板字段契约:验证 UI 读的字段都真实存在
node test-routes.mjs # HTTP 路由:真服务器 + 真状态 + 认证围栏
node test-client.mjs # 客户端 bundle:模拟宿主加载器
四套测试全部基于已安装插件的真实 engine.js,不 mock 引擎。
5.2 装好后手动验证
# 1. 健康检查
curl http://127.0.0.1:<port>/plugins/harnessmm/health
# → {"ok":true,"schema":"harnessmm-panel/v1","uptimeSeconds":...}
# 2. 快照(对照 harnessmm_status 工具输出,数字应一致)
curl http://127.0.0.1:<port>/plugins/harnessmm/status | head -c 600
# 3. 页面
curl -s http://127.0.0.1:<port>/plugins/harnessmm/panel | head -5
交叉验证方法:在对话里调 harnessmm_status,把返回的 counters 和面板上五颗药丸对比——应当完全一致。
面板的「数据溯源」卡片会直接列出 admissions 条数、缓冲容量、审计文件路径与行数。
5.3 安全性验证
未认证请求会被拦:
curl -i http://127.0.0.1:<port>/plugins/harnessmm/status
# 无有效 cookie 时应返回 401/403,而不是数据
裸 WebServer 路由不继承 Connection 认证围栏,所以 web-routes.js 必须包一层。
test-routes.mjs 的第 4 组断言专门验证这条(401 / 403 / 503 三种情况)。
6. 已知限制(请先读)
6.1 已验证 vs 未验证
| 项 | 状态 |
|---|---|
| 聚合逻辑正确性 | ✅ 用真实 engine.js 端到端验证(60+ 断言) |
| 面板字段契约 | ✅ 两种真实快照(有数据 / 空数据)都验证 |
| HTTP 路由可用性 | ✅ 真 http 服务器 + 真状态 + 认证围栏 |
| 客户端 bundle 契约 | ✅ 模拟宿主加载器,确认注册 slot 并渲染 iframe |
| 实际装进 DSH 运行 | ❌ 未验证(开发环境无法重启应用、无法写 profile 目录) |
| 浏览器渲染效果 | ❌ 未验证(沙箱内无法启动浏览器) |
后两项需要你装好后实际确认。如果右侧栏 tab 没出现,优先用 §4.4 的 A 方式(独立页面)验证数据层是否正常。
6.2 数据生命周期
counters与admissions都在进程内存里,重启归零admissions环形缓冲上限 2000 条,超出丢弃最旧- 只有审计文件
harnessmm-audit.jsonl是磁盘持久,但当前插件只在auditLog: true时写入 - 面板不读审计文件内容,只统计行数;历史数据回放不在本次范围
6.3 面板不做什么
- 不写任何状态:三条路由全部只读,没有 POST
- 不折算 token 或金额:插件本身声明「只记录确实被跳过的回调」,面板遵守这条
- 不改
engine.js:聚合逻辑全在snapshot.js,引擎零改动
7. 文件清单
| 文件 | 作用 | 行数 |
|---|---|---|
snapshot.js |
纯函数聚合 + provenance 标注 | ~400 |
web-routes.js |
认证路由包装(照抄 agent-teams 已验证实现) | ~120 |
panel.js |
Host 侧路由注册 + 审计行数统计 | ~160 |
panel.html |
面板本体(无框架、无外部依赖) | ~900 |
client-src.js |
客户端源码(iframe 嵌入) | ~45 |
build-client.mjs |
构建 client.js | ~35 |
client.js |
构建产物,宿主可直接加载 | 41 KB |
test-snapshot.mjs |
聚合端到端测试 | ~250 |
test-panel-contract.mjs |
字段契约测试 | ~220 |
test-routes.mjs |
HTTP 路由测试 | ~250 |
test-client.mjs |
客户端契约测试 | ~90 |
8. 重新构建客户端
改了 client-src.js / view.js / panel-css.js 后:
npm install # 第一次才要,装 rolldown
node build-client.mjs
npm test # 30 项,含 bundle 冒烟测试
构建产物是 window.__ModuleLoader__.load({id, factory}) 包裹的 IIFE,
格式对齐 [email protected] 的 lib/client.js。
关于 panel.html:它是独立页面,代码是面板的一份手抄副本(不参与上面的构建)。
改面板时两边都要改。它显示的是全部会话——一个独立浏览器标签页没有「当前对话」
可言,所以它如实写着全部会话,而不是假装跟着某个对话。
9. 许可证
本面板代码沿用插件原有许可:Apache-2.0。
web-routes.js 的认证包装实现参照 @nanmicoder/dsh-agent-teams(MIT)。