AaronandWork/dsh-evidence-gate

dsh-evidence-gate

让 DeepSeek Harness（DSH）中的 agent 停止从未经核实的猜测中得出结论——并让每一个结论都可审计。

一个 agent 说“我读了这个文件”，会被对照会话中实际的工具活动进行交叉核验。没有匹配工具日志条目的声明，会当场从 VERIFIED 降级为 UNVERIFIED。

Demo / 演示

Chip ON → the claim goes through evidence_gate before it may be stated / 开关开启 → 结论先过门再落笔

Per-session toggle: OFF means the gate does not apply to this conversation / 会话级开关：关闭仅影响本会话

The verdict card follows the GUI language and switches live / 判定卡片跟随 GUI 语言实时切换

/evidence-gate report: the per-session ledger, preserved across restarts / 本会话台账，跨重启保留

Why

仅靠提示词的“不要猜测”指令无法强制执行，也无法审计。本插件让结论纪律变得结构化：

1. Policy——在每次模型步骤前注入一个系统提示词章节，确立证据层级。
2. Gate——一个模型工具，agent 在陈述关键结论前调用它；每个声明都会得到一个判定。
3. Cross-check——声称的直接观察会对照会话中记录的工具活动（tools/result 流）进行核验。
4. Ledger——按会话统计：有多少猜测被拦截，有多少被转化为真正的核实。

How it works

| Component | Mechanism |
|---|---|
| Policy section | systemPrompt.section（顺序 550），文本提供器 |
| evidence_gate tool | 通过 tools 注册表注册；判定为 VERIFIED / REFERENCED / UNVERIFIED / INVALID / OFF |
| Evidence hierarchy | tested / measured / read_directly / prior_verified（直接）· documented / community_practice（必须引用来源）· assumption（仅作为带标签的假设 + 下一步核实步骤） |
| 交叉核对 | tools/result 监听器记录每个会话的持久化证据索引（400 条）——工具参数和输出锚点（路径 / URL / 有辨识度的输出词）；直接观察的断言必须与之匹配 |
| 反误杀阶梯 | 本会话命中 → 已记录输出关键词命中 → 其他会话命中（子代理）→ 存在性兜底（引用的路径确实存在 → 以 ⚠ 弱提示通过）→ 拦截 |
| 指标 | blocked（猜测被降级）vs converted（被拦截的断言后来回归为 VERIFIED）vs charity（存在性兜底通过，表现为采信） |
| 卡片徽章 | 工具卡片标题：🟢 VERIFIED · 🔵 REFERENCED · 🟠 UNVERIFIED · ⚪ OFF |
| 开关 | /evidence-gate on\|off\|status\|report + evidence_gate_switch 模型工具——按会话，持久化 |

v0.2 语义

- 一切按会话隔离：开关、账本和提示词段落都以 sessionId 为作用域。在一个对话中开启门禁绝不会泄漏到另一个对话；芯片提示框只显示本会话统计。策略段落的文本提供者按每次组装解析（context.agent.sessionId）。
- 持久化：账本 + 开关 + 证据索引在部署重启和上下文压缩后依然保留（JSON 存储位于 DSH_HOME/evidence-gate/store.json，防抖原子写入；可用 EVIDENCE_GATE_STORE 覆盖路径）。按最近使用保留前 50 个会话。
- 静默启动：挂载该 bundle 不会向宿主控制台打印任何内容——设置 EVIDENCE_GATE_DEBUG=1 可在诊断挂载问题时打印加载面包屑（存储恢复 + 每个已注册组件）。错误/警告诊断信息永不被门禁拦截。
- 输出感知交叉核对：诸如 "pnpm test → SMOKE PASSED" 的证据现在会与已记录的工具 OUTPUT（从 tools/result 载荷中提取的关键词、路径、URL）进行关联，而不仅仅是命令字符串。
- 诚实断言保护：未命中会依次落到其他会话（子代理工作），再到存在性兜底（磁盘上确实存在的引用路径会以弱/采信提示通过，而不是拦截）。伪造路径、空证据和 assumption 仍会被拦截。

已验证演示（来自实际开发）

agent claims: "I read C:\Users\...\fake\never-read-this-module.txt"
→ 🟠 UNVERIFIED — cross-check failed (no tool activity matches c:\users\...\fake\never-read-this-module.txt)

agent claims: "I read C:\...\3d12c8d4e809-cordis_inspect_query.txt"
→ 🟢 VERIFIED (read_directly, cross-checked ✓ matched tool activity)

安装

该包是一个 dsh bundle：它自带 cordis.patch.yml（用于插入插件行）以及一个 Web 客户端部分——无需手动编辑组合。

安装到 dsh profile——四种方式，①–③ 无需 npm 账号（均已验证）：

cd "$DSH_HOME/profiles/"

① straight from GitHub (recommended)
pnpm add github:AaronandWork/dsh-evidence-gate

② prebuilt tarball from the GitHub Release (no git needed)
pnpm add https://github.com/AaronandWork/dsh-evidence-gate/releases/latest/download/dsh-evidence-gate.tgz

③ 从本地克隆 / 检出
pnpm add file:E:/path/to/dsh-evidence-gate

④ 从 npm（已发布：@aaronandwork/dsh-evidence-gate）
pnpm add @aaronandwork/dsh-evidence-gate

然后将包名添加到配置文件的 package.json → dsh.profile.bundles：

"bundles": [ "...", "@aaronandwork/dsh-evidence-gate" ]

注意：pnpm 按 URL 缓存远程 tarball —— 发布更新后，需用 --force 重新安装。

重启部署。该 bundle 自带的补丁层会插入该行；浏览器刷新后 Web 客户端会自动加载。

我们在编写配置文件时踩过的坑（这样你就不必再踩）：

- Web 客户端以 text/javascript 原样提供，并且必须通过 window.__ModuleLoader__.load({ id, factory }) 自行注册 —— 仅用 export default/module.exports 永远不会注册，而且一个损坏的客户端文件会拖垮整个浏览器模块链（GUI 无法打开）。React 不是客户端全局变量：需在 factory 内部用 require('react') 引入。
- pnpm add 会重写配置文件的 package.json —— 运行后要重新检查任何手动编辑的 bundles；最好先编辑清单，再执行一次 pnpm install。
- package.json 中的 files 白名单必须包含 cordis.patch.yml（启动时会从已安装的副本中读取它）。
- dsh --profile  --dump-config 会组合所有层然后退出 —— 这是一个安全的启动前检查，能在不触碰正在运行的部署的情况下捕获清单/补丁错误。

用法

| 命令 | 效果 |
|---|---|
| /evidence-gate on | 为当前会话启用门控（策略文本 + 判定在下一个模型步骤生效；状态在重启后仍保留） |
| /evidence-gate off | 为当前会话禁用（门控工具仍保持注册，但返回 ⚪ 门未开启 且不计入任何内容） |
| /evidence-gate status | 每个会话状态的一行摘要 + 账本 + 交叉核验/采信命中数 + 索引大小 |
| /evidence-gate report | 完整会话报告：判定分组、按依据统计、拦截/转化/采信、近期声明 |

输入框的盾牌图标可切换相同的每会话状态；其提示框仅显示当前会话的数字。也可以要求 agent 切换/报告 —— 它会调用 evidence_gate_switch（其描述将 on/off 限制为仅响应用户的明确请求）。

解读数字

统计 Stats: 实证 verified 12 · 引用 cited 3 · 拦截 blocked 5 · 无效 invalid 0 · 转化 converted 3 · 核验命中 cross-checked 9 · 采信 floor-passed 1（索引 index 214）

解读为：12 条声明通过（9 条由证据索引佐证，1 条基于存在性下限被采信）；5 条猜测被捕获并降级；其中 3 条在 agent 实际执行核验后重新变为已验证；持久索引当前保存 214 条工具活动记录。

本地化 / 双语
Web UI（chip + 卡片）为双语：它遵循 GUI 语言设置（设置 → 语言），回退到浏览器语言，再回退到中文。切换 GUI 语言会实时重新渲染 gate UI。宿主侧工具/命令输出为紧凑双语——判定横幅（【已实证 Verified】）、动作标签和报告表头带有英文对照，以便两类受众都能快速浏览，而指令句保持中文（由模型按对话语言转述）。工具与命令输出为紧凑双语：判定横幅、动作短语与报告表头带英文对照，指令句保持中文（由模型按对话语言转述）。

作用域语义（v0.2）

- 按会话切换、按会话记账、按会话策略文本——以 sessionId 为作用域；对话之间绝不相互泄漏。从未选择启用的会话不付出任何代价（其策略部分组装为空字符串）。
- 持久化：账本、开关状态和证据索引在部署重启和上下文压缩后依然存活（JSON 存储位于 DSH_HOME/evidence-gate/store.json，路径可通过 EVIDENCE_GATE_STORE 覆盖；按最近使用保留前 50 个会话）。
- 加固的 UI 桥接：/api/dsh-evidence-gate 路由仅接受同源的 application/json POST，请求体上限 64KB，校验会话密钥，在触碰任何状态之前校验动作，并将 status 严格视为只读——一个误入的网页既无法通过它耗尽宿主内存，也无法翻转另一个会话的开关。
- 所有数据均保留在本地——不会发送到任何地方；存储文件是纯 JSON，你可以检查或删除。

限制（请阅读）

- 该策略是概率性约束，而非硬性保证——harness 中没有任何机制能拦截最终文本。gate + 交叉核验 + 可见账本是在这一层级的实际最优解。
- 交叉核验只能看到在插件加载期间经过 tools/result 流的内容；当索引为空时，第一手声称会依次经过跨会话查找和存在性下限，然后以失败关闭告终。
- 交叉核验是佐证，而非真相：一个因无关原因运行的真实命令仍可能匹配，一个执意为之的 agent 也能引用真实路径。它提高了撒谎的成本，但并不能让撒谎变得不可能。
- 一次不携带会话身份的工具执行会落入单个共享桶（发生这种情况时宿主日志会警告一次）。当存在多个主会话时，该桶会在它们之间共享——如果你看到该警告，请报告是哪个动作触发了它。
- 共享同一个 DSH_HOME 的部署（例如多个 profile）共享该存储文件（按 1.5 秒防抖，后写覆盖先写）。

路线图

- v0.3——严格/普通严重性模式；按声称的猜测预算；实时 URL 抓取检查（可选启用）；委派结果门控（父级对子 agent 的声称进行门控）；猜测热点分析；账本导出；设置页面；提交前防护

中文

让 DeepSeek Harness（DSH）中的 agent 不再凭未验证的猜测下结论——每条关键结论都可审计。

agent 声称「我读过这个文件」时，会与本会话真实的工具活动记录交叉核验；对不上号的声称当场从「已实证」降级为「已拦截」。

为什么 / Why

只靠提示词写「别猜」既无法强制执行、也无法审计。本插件把结论纪律做成结构性约束：
1. 策略段——每个模型步之前注入证据层级的系统提示段。
2. 门——agent 陈述关键结论前必须调用的模型工具，每条声称获得一个判定。
3. 交叉核验——自称直接观察的结论要与按会话记录的工具活动（tools/result 流）对得上。
4. 台账——按会话计数：拦下了多少猜测、多少被转化为真实验证。

工作原理 / How it works

| 组件 | 机制 |
|---|---|
| 策略段 | systemPrompt.section（order 550），按会话求值的文本函数 |
| evidence_gate 工具 | 经 tools 注册表注册；判定 已实证 VERIFIED / 已引用 REFERENCED / 已拦截 UNVERIFIED / 无效 INVALID / 门未开启 OFF |
| 证据层级 | tested / measured / read_directly / prior_verified（第一手）· documented / community_practice（必须注明来源）· assumption（只能以「推测，未验证」+ 下一步验证步骤出现） |
| 交叉核验 | tools/result 监听构建持久化的按会话证据索引（400 条）——工具参数和输出锚点（路径 / URL / 特征输出词）；直接观察类声称必须命中 |
| 防误伤阶梯 | 本会话命中 → 已记录输出关键词命中 → 其他会话命中（子代理）→ 存在性底线（引用路径真实存在 → 以 ⚠ 弱核验放行）→ 拦截 |
| 指标 | 拦截 blocked（被降级的猜测）vs 转化 converted（拦截后经真实验证翻案的）vs 采信 charity（存在性底线放行，报告中可见） |
| 卡片徽章 | 工具卡标题：🟢 已实证 · 🔵 已引用 · 🟠 已拦截 · ⚪ 门未开启 |
| 开关 | /evidence-gate on\|off\|status\|report + evidence_gate_switch 模型工具——按会话，持久保留 |

v0.2 语义：开关、台账、策略段全部按 sessionId 作用域——会话之间互不泄漏，未开启的会话策略段装配为空串；台账 + 开关 + 证据索引跨重启、跨上下文压缩保留（存储于 DSH_HOME/evidence-gate/store.json，可用 EVIDENCE_GATE_STORE 覆盖，按最近使用保留 50 个会话）；启动默认静默（挂载时不向宿主控制台打印任何内容，排障时设 EVIDENCE_GATE_DEBUG=1 可输出加载凭据：存储恢复与各组件注册；错误/告警诊断不受此开关影响）；证据引用如「pnpm test → SMOKE PASSED」可命中已记录的输出（从 tools/result 提取的关键词、路径、URL），不再只对命令串；诚实声称保护：未命中时依次落跨会话（子代理工作）→ 存在性底线（引用路径真实存在则以弱核验/采信放行）；编造路径、空证据、assumption 仍然拦截。UI 桥接路由仅接受同源 application/json POST、请求体上限 64KB、会话键与 action 先行校验、status 严格只读——无关网页既不能借它拖垮宿主，也翻不动别的会话的开关。所有数据只存本地，存储文件是可直接查看/删除的纯 JSON。

已验证示例（来自实际开发）：

agent 声称：「我读过 C:\Users\...\fake\never-read-this-module.txt」
→ 🟠 已拦截——交叉核验失败（无工具活动匹配该路径，且路径不存在）

agent 声称：「我读过 C:\...\3d12c8d4e809-cordis_inspect_query.txt」
→ 🟢 已实证（直接读取，交叉核验✓ 命中工具活动）

安装 / Install

本包是一个 dsh bundle：自带 cordis.patch.yml（插入插件行）与 web 客户端半边，无需手工改组合。

装入 dsh profile —— 四种方式，①②③ 无需 npm 账号（均已实测）：

cd "$DSH_HOME/profiles/"

① GitHub 直装（推荐）
pnpm add github:AaronandWork/dsh-evidence-gate

② Release 预构建 tarball（无需 git）
pnpm add https://github.com/AaronandWork/dsh-evidence-gate/releases/latest/download/dsh-evidence-gate.tgz

③ 本地克隆/检出
pnpm add file:E:/path/to/dsh-evidence-gate

④ npm（已发布）
pnpm add @aaronandwork/dsh-evidence-gate

然后把包名加入 profile 的 package.json → dsh.profile.bundles；重启部署，浏览器刷新后 web 客户端自动加载。注意 pnpm 按 URL 缓存远程 tarball——Release 更新后重装请加 --force。

我们踩过的 profile 编写陷阱（帮你避开）：web 客户端以 text/javascript 原样下发，必须经 window.__ModuleLoader__.load({ id, factory }) 自注册（裸 export default 永远不会注册，且一个坏文件会拖垮整个浏览器模块链）；React 不是客户端全局，需在 factory 内 require('react')；pnpm add 会重写 profile 的 package.json——手工编辑的 bundles 要在安装后再核对一遍；files 白名单必须含 cordis.patch.yml；dsh --profile  --dump-config 可在不启动部署的情况下预检组合。

使用 / Usage

| 命令 | 效果 |
|---|---|
| /evidence-gate on | 仅为当前会话开启（下一模型步生效；状态跨重启保留） |
| /evidence-gate off | 当前会话关闭（门工具保持注册但返回 ⚪ 门未开启，不计数） |
| /evidence-gate status | 一行本会话状态 + 台账 + 核验命中/采信 + 索引大小 |
| /evidence-gate report | 本会话完整报告：判定分组、basis 分布、拦截/转化/采信、最近声称 |

输入框旁的盾形开关切换同一份按会话状态；悬停只显示本会话数字。也可以直接让 agent 开关/汇报——它会调用 evidence_gate_switch。

数字读法：统计 Stats: 实证 verified 12 · 引用 cited 3 · 拦截 blocked 5 · 无效 invalid 0 · 转化 converted 3 · 核验命中 cross-checked 9 · 采信 floor-passed 1（索引 index 214） —— 12 条结论过门（9 条有索引佐证、1 条按存在性底线采信）；5 个猜测被拦下；其中 3 个在 agent 真正跑完验证后翻案；持久索引现有 214 条工具活动。

双语：web UI（开关 + 卡片）中英双语，跟随 GUI 语言设置实时切换；宿主侧工具/命令输出为紧凑双语（判定横幅、动作短语与报告表头带英文对照）。

边界（务必阅读）/ Limitations

- 策略是概率性约束，不是硬保证——harness 没有任何机制能拦截最终文本。门 + 交叉核验 + 可见台账已是这一层的实用最优。
- 交叉核验只能看到插件加载期间经过 tools/result 流的内容；空索引时，第一手声称会先落跨会话查找与存在性底线，然后才失败关闭。
- 交叉核验是佐证，不是真相：无关原因跑过的真实命令也可能匹配，蓄意撒谎的 agent 也可以引用真实路径。它提高撒谎成本，不能杜绝撒谎。
- 无会话身份的工具执行会落入单一的 shared 桶（宿主日志会一次性告警）。多开主会话时该桶跨会话共享——看到告警请报告触发动作。
- 共用同一 DSH_HOME 的多个部署（如多个 profile）共享存储文件（每 1.5s 防抖，最后写入者胜）。

路线图 / Roadmap

- v0.3 —— strict/normal 严重度模式；按声称的猜测预算；实时的 URL 抓取核验（可选开启）；委托结果门控（父会话门控子代理声称）；猜测热点分析；台账导出；设置页；pre-commit 防护

License

MIT — see LICENSE.