技能路由与闸门 yuanfeng637-cmyk/dsh-skill-router-and-gate

dsh-skill-router-and-gate

为 DeepSeek Harness 提供三层技能管控：每轮一份候选清单，一道硬闸门让清单真正生效，再加一份可选策略，把受管命令精确绑定。

DSH 每轮都注入完整技能目录，并指望模型自己调用正确的技能。长会话里这套机制会失效：目录从第一条消息就在，技能却几千轮都没被碰过。本插件在目录之上加三层——路由负责挑选，闸门负责强制执行，策略负责绑定关键命令。

| 层 | 作用 |
| Router | 每轮由一个进程内 LLM 裁判读取实时技能目录，注入一份排序后的候选清单，只列任务真正需要的技能。裁判超时、报错或输出非法时，改由 9 路词法打分器接管。 |
| Gate | 某次工具调用需要受管格式（xlsx / docx / pptx / pdf / csv-tsv），而对应技能本会话从未加载，调用会被拒绝，并提示先加载技能、再重发同一条命令。 |
| Policy（可选开启） | 把 DSH_SKILL_GATE_POLICY 指向项目自有的 JSON 文件后，受管命令按精确文本注册，绑定输入/脚本哈希，并要求同会话内 30 分钟 TTL 内的成功证据。不对散文做 LLM 解读：策略即数据，trace 账本记录每次判定。 |

名称与短句柄。 包名和仓库名是 dsh-skill-router-and-gate；斜杠命令和环境变量用短句柄 skill-gate（/skill-gate、DSH_SKILL_GATE_）。同一个插件。

答案闸门默认关闭。 可选的 llm/stream 检查（数值出处、分母、能力声明）仅在 DSH_ANSWER_GATE=warn|block 时生效。不设置时，插件绝不注入文本、包装流或改写答案。

当前版本 v33；逐版行为变化见 CHANGELOG.md。

合规策略层（可选开启）

加载成功现在写 skill-loaded，并同步路由账本的 loaded。它证明加载，不能证明技能全部得到遵守。
加载 bioinformatics-toolkit 后，首次直接执行裸命令 mafft / iqtree / iqtree2 / iqtree3 前，须有同会话先前成功、被接受的独立 --help / -h 输出；有效期 30 分钟。
独立版本查询放行，但不计帮助证据。路径调用、复合 shell、SSH、脚本内部调用不在这个默认规则的覆盖面。

项目特有约束通过 DSH_SKILL_GATE_POLICY=<策略 JSON 的绝对路径> 显式开启；未设置时不猜项目标准。
完整策略格式和例子见 设计记录末节。策略用 protect 字符串命中受管命令，用 actions[].command 固定完整命令；用输入/脚本/引用 SHA256、用户裁定原文和来源 SHA256、先前验证命令及实际输出片段建立前置条件。达到任一阈值（wall ≥300 秒 / CPU ≥1,800 秒 / 输出 ≥100 MiB / 请求 ≥100 次）须声明假设、至少一项已成功的便宜验证及中止条件。
四项是显式估计，不是插件对任意进程的预测或资源配额。

审计默认写 ~/.dsh/skill-gate-compliance.ndjson，可用 DSH_SKILL_GATE_COMPLIANCE_TRACE 改路径。
前置审计写入失败就拒绝受管动作；结果审计失败不改变已执行事实，也不会解锁后续验证。
回执含实际文本片段、输入/脚本来源、输出文件 SHA256、生成时间与插件版本。
输出文件未更新或不存在时 receiptComplete=false；旧脚本/引用来源缺标注或超过24小时会记告警。
没有回复发布闸，因此日志不能保证模型在最终回复展示证据或禁止它说“完成”。
后台、远端、普通工具文本中的退出码，以及自然语言规则的科学含义仍需要执行端或人工核验。

策略应由用户审核和保管；插件不提供防止 agent 改写策略的安全隔离。错误/缺失的已配置策略会拒绝 shell 工具，可通过 /skill-gate off 恢复；总开关和文件 kill switch 现在对全部执行闸生效。
新增的依从闸没有「拒绝三次后放行」的退路；原格式加载闸仍保留原有 skillGateMaxDeny 行为。

为什么需要它

DSH 会注入完整技能目录，并期望模型自己调用正确的技能。长会话里这一点撑不住：目录从第一条消息就在，技能却几千轮都没人碰。
给一份候选清单有帮助，但清单只是建议——于是第二层来强制执行：需要某个技能的调用会被拒绝，直到该技能加载完成。

安装

from a local checkout (verified)
dsh plugin --profile <profile> add "file:/abs/path/to/dsh-skill-router-and-gate"

straight from this repository (verified: npm resolves the spec; the package manager clones it)
dsh plugin --profile <profile> add "github:yuanfeng637-cmyk/dsh-skill-router-and-gate"

same thing over SSH, for networks where HTTPS to github.com is blocked:
dsh plugin --profile <profile> add "git+ssh://git@github.com/yuanfeng637-cmyk/dsh-skill-router-and-gate.git"

然后重启 DSH——插件代码不会热重载。

- Node ^22.19.0 || >=24.0.0
- DSH：>=0.1.5-rc.1 <0.3.0-0（package.json 中声明；基于 0.2.0-rc.2 开发并验证）
- @deepseek-ai/dsh、@deepseek-ai/dsh-llm 和 @deepseek-ai/dsh-skill 是可选 peer——由配置档提供。

你会看到什么

1. 候选清单——在回合中追加一条系统提醒，列出候选技能（名称 + 原因），并告诉你要用 skill 工具按准确名称加载其中一个。若都不适用，忽略该列表。
2. 目录兜底——如果 DSH 原生的 <available_skills> 块缺失，本插件自行提供目录（并标注来源）。
3. 闸门拒绝——工具调用不会执行；你会收到一条消息，指明要加载哪个技能。加载后重发同一条命令。

命令

| 命令 | 作用 |
| /skill-gate status | 闸门状态、会话账本、各技能拒绝计数、版本 |
| /skill-gate on / /skill-gate off | 运行时开关 |
| /skill-gate eval <fixtures.json> | 在进程内运行路由 fixtures（不污染运行时） |

配置

环境变量。方括号内为默认值；只使用短句柄。

| 变量 | 默认值 | 含义 |
| DSH_SKILL_GATE | true | 总开关 |
| DSH_SKILL_GATE_TOPK | 3 | 候选清单数量（也是评审上限） |
| DSH_SKILL_GATE_MIN_SCORE | 0.75 | 仅词法兜底路径的分数下限 |
| DSH_SKILL_GATE_INCLUDE_LOADED | false | 继续推荐本会话已加载的技能 |
| DSH_SKILL_GATE_JUDGE | true | 使用 LLM 评审（关闭则只走词法） |
| DSH_SKILL_GATE_JUDGE_ROUTE | （会话默认模型）* | 评审调用的 provider/model |
| DSH_SKILL_GATE_JUDGE_TIMEOUT_MS | 8000 | 评审墙钟上限；超时则由词法路径决定 |
| DSH_SKILL_GATE_JUDGE_MAX_TOKENS | 1200 | judge 输出预算 —— 推理模型在输出任何 JSON 前会先消耗一小部分预算 |
| DSH_SKILL_GATE_CATALOG_DESC_MAX | 200 | 展示给 judge 的每条描述截断长度 |
| DSH_SKILL_GATE_CATALOG_FALLBACK | true | DSH 原生块缺失时注入目录 |
| DSH_SKILL_GATE_SUPPRESS_AFTER | 2 | 某个技能被忽略这么多次后，不再推荐它 |
| DSH_SKILL_GATE_SKILL_GATE | true | 启用硬门禁 |
| DSH_SKILL_GATE_SKILL_GATE_MAX_DENY | 3 | 同一技能被拒绝 N 次后，放行调用（防死锁） |
| DSH_SKILL_GATE_TRACE | (开启) | 设为 0 停止写入 trace 账本 |
| DSH_SKILL_GATE_POLICY | (未设置) | 项目自有合规策略 JSON 的绝对路径；未设置 ⇒ 不猜测任何项目标准 |
| DSH_SKILL_GATE_COMPLIANCE_TRACE | ~/.dsh/skill-gate-compliance.ndjson | 合规审计（证据、回执、拒绝）追加写入的位置 |

工作原理

- 一行 Cordis 挂在 agent/pre-step 上（见 cordis.patch.yml）：不注册工具，不改动已有行，除自己的账本外不保留任何状态。移除这个 bundle 即可恢复原有行为。
- 候选来自会话的实时目录快照；无法由模型调用的技能，以及本会话中已加载的技能，都会被过滤掉。（需要会话账本，是因为 agent/pre-step 只能看到该步骤所认领的消息。）
- judge 是一次进程内的 llm.stream 调用，带自己的上下文 —— 刻意不用子代理，因为子会话会重新进入 agent/pre-step。
- 门禁挂在 tools/pre-execute 上：它按工具位置匹配那些会解析受管格式的命令文本，并要求对应技能已经加载；否则返回 deny，附上可操作的提示。加载状态和目录快照都按会话（agent）跟踪 —— 不同会话可能看到不同的技能根目录，所以一个会话的目录永远不会决定另一个会话的门禁。只有 skill 工具调用成功且被接受之后，技能才算已加载；加载失败（或之后被拦截）不会解锁门禁。按会话的状态有 LRU 上限，会话结束时丢弃。
- trace 账本：~/.dsh/skill-gate-trace.ndjson，每次决策一行 JSON（路由、回退、拒绝、跳过）。

故障排查

| 现象 | 检查什么 |
| 没有出现候选列表 | /skill-gate status；目录快照可能不完整（snapshot.complete === false），或 DSH_SKILL_GATE=0 |
| 你认为没问题的调用被拒了 | 门禁只对受管格式生效；加载被点名的技能后重发同一条命令，或设置 DSH_SKILL_GATE_SKILL_GATE=0 |
| 门禁反复拒绝同一件事 | 同一技能被拒绝 MAX_DENY（默认 3）次后，调用会被放行 —— 查 trace 账本，看加载为什么一直没落地 |
| 代码改动似乎没生效 | 插件代码不会热重载：重启 DSH。如果你是从 file: 路径安装的，先把改动过的文件重新拷进配置档 |
| 判定器始终不给出结论 | 检查 DSH_SKILL_GATE_JUDGE_TIMEOUT_MS / ..._MAX_TOKENS；失败时由词法兜底决定，追踪账本记录 judge- |
| 已登记的命令被拒，提示 "managed action is not bound to an exact command"* | 命令文本与策略登记的内容不是逐字节一致（或者策略被改过）；原样重发，或者更新策略并用 make_policy 那套方式重新生成 |
| 已登记的命令被拒，提示 "missing same-session, same-policy, same-input prior evidence" | 要求的前置步骤没有在当前策略摘要下的本会话里跑过、已过期（TTL 30 分钟），或者某个哈希锁定的输入在磁盘上变了 —— 重跑前置步骤，或者在文件合法变更后重新锁定输入 |
| 策略 JSON 损坏或缺失 | shell 工具一律拒绝；修好文件，或者用 /skill-gate off 恢复 |

停用 / 卸载

- 运行时：/skill-gate off，或者创建 ~/.dsh/skill-gate.off。
- 永久：dsh plugin --profile <profile> remove dsh-skill-router-and-gate。

设计说明、历史、实测

docs/DESIGN.md 是决策日志：为什么用判定器取代纯检索、阈值怎么定的、在真实主机上测了什么、一路上踩到哪些 bug（中文）。改打分、改判定器、改闸规则之前先读它。

许可证

MIT —— 见 LICENSE。

中文速览

做什么：给 DSH 补三层技能控制 —— ① 候选：每轮由一次独立模型判定，读实时技能目录，注入排好序的候选（判定失败则退回 9 路词法打分）； ② 硬闸：工具调用要解析受管格式（xlsx / docx / pptx / pdf / csv-tsv）而对应技能本会话从未加载时，直接 deny，并告诉你先加载哪个技能； ③ 合规策略（可选）：设 DSH_SKILL_GATE_POLICY=<策略 JSON 绝对路径> 后，受管命令按精确命令文本登记、按输入/脚本哈希绑定，并要求同会话、同策略摘要、同输入的先前成功证据（有效期 30 分钟）。
策略是数据、不做自然语言解释；每次判定都写审计账本。

装：dsh plugin --profile <配置名> add "file:<本目录绝对路径>" → 重启 DSH（插件代码不热重载）。

用：/skill-gate status 看状态与账本；/skill-gate on|off 即时开关； /skill-gate eval <fixtures.json> 跑离线标定。

配：环境变量前缀 DSH_SKILL_GATE_（各项默认值见上表）。总开关 DSH_SKILL_GATE=0；只关闸、保留候选：DSH_SKILL_GATE_SKILL_GATE=0。

排错：没出现候选 → 看 /skill-gate status 与追踪账本 ~/.dsh/skill-gate-trace.ndjson；被闸拦 → 按提示加载技能后原样重发同一条命令；同一技能被拦满 3 次会自动放行（DSH_SKILL_GATE_SKILL_GATE_MAX_DENY）；改了代码没生效 → 插件不热重载，重启 DSH；用 file: 安装的还要先把改动拷进 profile。

设计取舍、阈值依据与全部实测记录（中文）：见 docs/DESIGN.md。

开发

运行时 v24 新增确定性的学术写作路由。明确的中文请求，例如 写材料方法、写材料与方法、写论文，以及英文请求，例如 write the Methods section，会在当前可调用目录里存在 scientific-writing 时选中它。这条规则不受判定器 none/unsure/失败的影响，也不受重复推荐抑制的影响。已确认的加载和现有的总开关依然生效。注入会命名 references/imrad_structure.md，解析相对于已加载技能的 SKILL.md 目录，并指示完整读取，不带 offset/limit。

策略 schema version: 1 现在还支持可选的 artifact.specs[].requireReads：

{
"paths": ["/METHODS.md", "/MATERIALS.md", "/材料方法.md"],
"genre": ["methods", "methods-prose", "材料方法"],
"requireReads": ["C:/Users/19818/.dsh/skills/scientific-writing/references/imrad_structure.md"]
}

路径是大小写不敏感的项目相对 glob；**/ 包含项目根目录。每个匹配的 spec 都会贡献自己的前置条件，与全局 artifact.requireReads 叠加。引用路径可以是绝对路径，也可以是相对项目 cwd 的路径。R4 覆盖 write/create_file/edit 目标、现有 R7 扫描器识别的 shell 目标，以及精确注册的动作输出。全局 R4 范围仍是写工具和已注册动作。证据仍按每轮 absolute-path#sha256 计算：部分读取、失败读取、被阻止的读取都不计入，内容变化会使证据失效。引用文件缺失和内部异常沿用现有的 fail-open 行为。脚本内部的任意写入仍在插件的可观察范围之外。

npm test # node --test, with a stub for @deepseek-ai/dsh-llm (that package only exists inside the host)
npm run check

测试套件在 DSH 之外运行：_test/resolve-stub.mjs 把 @deepseek-ai/dsh-llm（仅宿主内存在的包）重定向到 _test/stubs/ 里的最小 stub，这样 apply 级闸测试能在任何 checkout 里跑。宿主加载的插件仍使用真实包。请从 checkout 运行测试套件，不要从已安装的配置档副本运行。

v28：分级回答闸

插件通过 llm/stream waterfall 检查 loop-owned 回答。默认 block 只拦截明确的计数、全称比较或整体能力否定等缺证据断言；孤立数字、普通「一致/全部」和局部「该接口不可用」降为告警，正文保留，末尾追加逐项 [回答闸] 提示。工具调用保持原有块与结束原因，继续接受其他工具闸检查。

- 数字证据覆盖请求内全部工具历史，以及本插件已观察到的同会话工具结果，默认保留最近 1000 条。代码、行内代码、路径、日期和版本常量单独豁免；无出处数字仍可紧邻标 [未验]。
- 分母支持 分母=N、(分母: N 列)、N 条/链/项、N/N 相同、共 N 项中的 M 项，可位于当前段或紧邻上一段。
- 不可用证据接受本轮真实失败的「工具名 + 命令或路径 + 失败输出首行」，[失败证据:toolCallId] 可选。局部否定需一条失败方法；整体能力否定需两种不同方法。「没有改文件」不触发能力检查。

DSH_ANSWER_GATE=block|warn|off 选择模式（默认 block，兼容旧值 0）。DSH_ANSWER_GATE_MAX_RESULTS 配置证据条数，上限 10000；旧 RECENT_TURNS 不再生效。DSH_ANSWER_GATE_TIMEOUT_MS 配置缓存期限，默认 2000ms，上限 60000ms；默认缓存上限 1 MiB / 10000 chunks。超时或超长即释放缓存、继续逐块输出，并在末尾提示检查未完成。真实用户消息明确说「本次免检」或「不用闸」可每会话豁免一个模型请求。总开关、kill switch 和其他工具闸仍生效。审计沿用 trace，不等待审计写入；/skill-gate status 展示模式及 VERSION。

本次只修改仓库，未同步配置档、未重启宿主。当前行为、验证记录与能力边界见 ANSWER-GATE-v28.md；v27 文档 保留宿主源码依据和历史实现记录。