dsh-decision-layer

dsh-decision-layer

English | 简体中文

DeepSeek Harness（DSH）的结构化裁决插件。它把有明确判断标准的问题交给同协议的裁决后端，供 agent 在需要时使用，并在 agent loop 上接入危险门控、产出自检、工具收窄和防循环等自动介入。

0.7.0 是体验版。 插件功能已可用，但裁决介入能带来多少实际价值仍在探索中——各决策点的阈值都是未经验证的启发式默认值，建议先以观察心态体验，别当成经过验证的效果保证。功能与后续进度以 ROADMAP.md 为准。

安装

已发布到 npm 与 GitHub Release。

从 npm 安装（补 @latest）：

dsh plugin --profile web add dsh-decision-layer@latest

或从 GitHub Release 安装：下载对应版本的 tgz 附件，直接装本地包。

dsh plugin --profile web add https://github.com/xbzbing/dsh-decision-layer/releases/download/v<版本>/dsh-decision-layer-<版本>.tgz

仓库不再提交构建产物 lib/client.js（ADR-0012），因此不带 ref 的 `github:xbzbing/dsh-decision-layer` 安装不可用——那样拿到的是没有 lib/ 的源码树，host 半仍能加载，但面板不会出现。GitHub 侧请用上面的 Release 附件。

也可从源码本地构建后用 file: 安装：

npm ci --ignore-scripts
npm run build:client
dsh plugin --profile web add file:/绝对路径/dsh-decision-layer

安装或更新后需重启 dsh web 服务再刷新页面：host 与 client 两半在服务启动时生成挂载与 bundle 清单，仅刷新页面可能看不到变化。插件管理 API 只接受本机 loopback Web 服务上的同源请求；把 DSH Web 绑定到所有网卡时该接口会拒绝请求。不要在未确认目标地址和数据流向前填入生产 Key。

功能

• 手动裁决：decision_evaluate 工具与 decision-layer skill 支持显式提交 noul、score、choice 问题，decision_check_connection 做连通测试。手动调用和连通测试不计入自动裁决指标，也不改变 agent 行为。
• 可配置后端：默认 https://api.typesafe.ai、jev-latest，URL、Key、model 可逐字段覆盖；仅支持相同的结构化裁决协议。未配置 Key 时不发送请求。自定义 HTTP 地址需针对实际目标确认明文传输风险，地址变更须重新确认。用本地 ollama + tev1 作为后端（裁决不出本机、无数据外发）的完整部署步骤见 用本地 tev1 配合插件（部署指南）。
• 危险门控：破坏性工具调用执行前用脱敏摘要请后端裁决，采用两档模型——只有模型高置信判定「拒绝」时才经监控守卫单调拦截该调用；其余情况（高置信放行 / 询问、低置信、后端失败或响应不合法）一律不介入，按宿主原路径执行。门控只做「确信危险才拦」的安全网，不替宿主授权、不降级审批。危险规则可增删配置；拦截置信度门槛可配（gateSettings.minConfidence，默认 0.6），调低更容易拦、也可能误拦正常命令，调高更宽松。
• 产出自检：回合结束用评分量表给最终产出打分（0–2，按各档位概率加权，可能是小数）。默认只提示、不打断；可开启「低分补完」，得分偏低且模型有把握时以你的名义追加一次补完提示，同一回合最多补一次。评分档位、低分阈值（默认 1）、补完置信度门槛（默认 0.4）均可配。
• 任务完成核对：当用户明确列出多个交付条件（编号 / 项目符号 / 多命令）时，回合结束前用单选逐项判定「已满足 / 未满足 / 证据不足」，工具证据优先、回复自述不算证据；确定性提取、不推断隐含期望。默认只观察、可配 steer，与产出自检并存、指标分列。最少条件数（默认 2）与补完置信度门槛（默认 0.4）可配。
• 产出质量趋势告警：建在自检数据上的只读提醒。连续多次高置信低分时，把输入框旁触发按钮的图标从灰变橙、变红，hover 提示可能是任务变难或模型波动、建议调整 prompt 或更换模型。纯提示、不驱动自动干预；高置信门槛 / 连续轮数 / 严重档三个阈值可配（默认 0.6 / 3 / 5），偏保守、待实测校准。
• 工具收窄：回合开始时用 noul 逐个判断可选工具与本轮任务的相关性，摘掉用不上的（相关性概率低于摘除阈值，默认 0.3、可配），只在宿主已允许的集合内取交集、不扩权。默认真正生效，可切到「仅观察」只记录不改工具集。三重保护：核心工具（读写、编辑、Shell、检索、待办，以及问用户、目标、技能、交付、后台作业、协作等 agent 元能力）始终保留、不参与判定；可选工具超过候选上限（默认 20，可配）时自动降为仅观察；保留下来不足 5 个时视为判定不可信、跳过。保留工具前缀白名单里的工具（默认含 mcp__openviking、team_task_）也始终保留、不参与判定，适合记忆 / 检索、协作这类常驻、按需触发的工具。分批策略按后端上下文容量自适应（batchMode，默认 auto）：大上下文后端（如 Jev）一次请求判完全部工具；小上下文后端（如本地 tev1，约 2050 token 单请求上限）在遇到上下文超限错误时自动降级为「每工具一次请求、并发执行」并记住，之后直接走拆分，不再反复探测。也可显式设 single（始终整批）或 split（始终逐工具）。某个工具的拆分请求失败时该工具保守保留。
• 防循环：确定性判断，不走后端；同一调用连续重复超过阈值即拒绝，打断死循环。始终生效，不在决策点开关范围内。
• 会话面板：输入框下方的 dock 触发器弹出面板（与官方上下文用量指示同时出现，会话刚开始、还没有上下文读数时这一行是空的），展示自动裁决指标（评估数、失败回退、模型建议与实际结果分列）、会话总开关和决策日志；无自动裁决时显示空态。总开关关闭只暂停自动介入，不影响手动裁决。
• 决策分析页：会话内「决策分析」tab（conversation.view，与对话/轨迹平级、天然按会话隔离），基于已落盘日志做只读聚合，展示过程画像（各决策点触发数与结果分布、自检平均分）、质量趋势阈值回测、判断准确度汇总，并可对每条决策标注「判对 / 判错 / 说不准」。标注与介入面板同源：任一处标注都写入同一份日志、按决策 id 关联、取最新。只读日志、只追加标注，不改任何决策行为。
• 决策点开关与介入阈值：详情页配置里，危险门控、产出自检、工具收窄、任务完成核对各有独立开关，默认全开；关掉某个决策点就不再对应地介入。防循环不在此范围。可配决策点的介入阈值都在配置页「高级配置」里可调，落到 ~/.config/dsh-decision-layer/config.json（也可直接改该文件，热生效、无需重启）：门控拦截置信度 gateSettings.minConfidence（0.6）、自检低分阈值 lowScoreThreshold（1）/ 补完置信度 minConfidence（0.4）/ 趋势门槛 trendMinConfidence·trendRun·trendSevereRun（0.6·3·5）/ 评分档位 rubric、收窄摘除阈值 threshold（0.3）/ 候选上限 maxCandidates（20）/ 分批策略 batchMode、完成核对最少条件数 minConditions（2）/ 补完置信度 minConfidence（0.4）。防循环的重复阈值（3）是确定性本地逻辑，不在此范围。在配置页填写时，留空或越界的值会被夹取或回落到默认；直接手改 config.json 不会兜底——写错值（越界、拼错字段名、类型不符）会让整份配置校验失败，表现为配置页读不出来、各决策点退回各自的安全默认（如门控回 0.6 与内置规则），所以手改只写合法值即可。连续次数要求「严重档 > 告警档」，配置页会自动纠正。
• 决策日志落盘：决策记录在内存面板之外，还按会话全量落盘到 ~/.config/dsh-decision-layer/logs，供研究回看。文件按运行实例端口和日期滚动切分（decisions--YYYY-MM-DD.jsonl），批量写入，保留 30 天。写盘为尽力而为，失败只丢当批、不影响决策路径。
• 会话指标持久化：面板的实时指标（dock 计数、各决策点卡片、最近决策日志）在重启后不再归零。每个会话的实时状态按会话 id（非端口）另存一份快照到 ~/.config/dsh-decision-layer/state/.json，每次计数变化防抖写盘、原子落盘，保留 30 天。同一会话恢复时优先读该快照续算；若尚无快照但有历史决策日志（如早于本机制、或快照已被清理的会话），则跨全部端口按会话 id 从日志重建种子续算——唯一例外是「实际结果」（gate 观测到的放行 / 拒绝）无法从日志重建，重启后从零重新累计。写盘同为尽力而为，失败绝不进入决策路径。

安全边界

自动介入只减不增：门控只拒绝、收窄只删工具，都不给 agent 新权限。危险门控采用两档模型，只在模型高置信判定拒绝时拦截；后端失败、低置信或响应不合法时一律不介入、按原路径执行，不因裁决故障阻断，也不替宿主放行。自检、收窄与防循环异常则跳过介入。发送到后端的危险摘要只含工具名与命令 / 路径并对疑似密钥脱敏，不含文件内容。

开发

服务端使用 Node.js >=20.11（.mjs，无需构建）；客户端用 TypeScript + esbuild 构建。npm test 跑本地测试，npm run build:client 生成 lib/client.js（tsc 严格模式就在这一步），npm run check 跑完两者。

构建产物不入库（ADR-0012）：lib/ 已被 .gitignore 覆盖，源码是唯一事实来源。发布由 GitHub Actions 的 release.yml 完成——构建、跑门禁、npm pack，并用 scripts/assert-pack.mjs 断言产物里确实有 lib/client.js 且没有源码泄漏，之后才发 npm / 建 Release。该 workflow 只手动触发且默认 dry_run=true，误点不会发版。

架构决策记录见 docs/adr/：每条规则为什么存在、当时放弃了哪些备选。0.7.0 为体验版：介入能力已可用，但实际价值与阈值仍在探索，欢迎反馈决策日志观察到的误判与体感。