步数熔断器 JiewiW/dsh-step-governor

dsh-step-governor

DeepSeek Harness（DSH）插件：模型跑长任务时「想了很多步却不推进」，这个插件在步骤层面强制刹车——不靠提示词劝它自律，直接剥夺继续空转的执行权。

- 默认 shadow 模式：只观测、写日志，永不拦截。
- 所有判据都是可机械计算的确定性信号（步数、指纹、错误码），不调用模型自评。
- 任何内部异常一律 fail-open（放行），不会因为插件故障卡住正常任务。

它是 dsh-cot-anchor 的姊妹插件：cot-anchor 管单次生成内的软切，step-governor 管跨步骤的硬熔断。长任务账单的大头是「步数 × 每步膨胀的上下文重读」，步数治理对准的就是这个杠杆。

什么时候用它

某些模型跑长任务时会：把同一结论在十几步里反复重推；对同一取证目标反复换路径尝试；连续多步既不交付也不改文件。这类会话里缓存重读可占 token 的 95% 以上，模型往往知道自己在空转却停不下来。

step-governor 判得出：调用是否重复/失败、推理指纹是否重现、有没有交付或改文件。
判不出：刚读到的新数据与任务是否相关——语义级偏离不在覆盖范围内（见能力边界）。

两个熔断点

| 熔断 | 宿主钩子 | 动作 | 效果 |
| G1 步级 | agent/pre-step | {kind:"reject"} | 终止当前回合（turn/end reason=blocked），不再发出本次请求 |
| G2 支线 | tools/pre-execute | {kind:"deny"} | 跳过这一次工具调用，回喂一条错误文本，回合继续 |

G1 触发条件（括号内为默认值）：

- G1-A 滑窗失速：近 8 步滑窗（g1aWindowSize）内出现连续 4 步（g1aZeroSteps）无文本交付、无文件变更，且窗内成功工具占比 ≤ 0.25、reasoning 总量 < 160 字——后两个条件用来排除「安静干活」的正常步骤。
- G1-B 指纹重现：同一段推理结论的指纹跨 6 步（g1bFingerprintSteps）重现且其间无文件变更。专抓「每步都读到新东西、却在重推同一结论」。
- G1-C 硬顶：单回合 60 步（g1cMaxStepsPerTurn）安全网。

G2 触发条件：

- G2-A：同一调用目标（归一化后的文件 / URL / 命令 / 参数）尝试超过 3 次（g2aSameTargetCalls）。
- G2-B：同一目标连续失败 2 次（g2bConsecutiveFailures），与「同命令失败最多重试 2 次」纪律对齐。

目标键归一化（决定 G2 的「同一目标」到底是什么）：

| 工具 | 键体组成 |
| read | 文件路径 + offset/limit（分页即不同目标） |
| grep | pattern + path |
| edit / write | 文件路径 + 变更语料哈希（改内容即不同目标） |
| pwsh / bash / sh | 管道首段的全部参数 + 后续段哈希 |
| 其他工具 | 依次取 file_path/path/url/command/pattern/script/query/name；这些字段一个都取不到时，回退到全参数规范化 JSON 的哈希 |

最后那行兜底很关键：若键体退化为空串，同一工具下的所有调用会塌成同一个目标键（FNV-1a 空串恒为 0x811c9dc5），G2-B 一旦命中就永久拦截，改参数也无法脱身。

终态提交工具豁免：工具名中含 submit / report / finalize / finish / complete / deliver / accept 词元的（如工作流编排的 fusion_submit_result），G2-A 与 G2-B 只观测不拦截。理由是这类工具是外部工作流「本轮必须以它提交结果」的唯一出口，拦截它不会让模型换一条路，只会让外部编排永远读不到提交、进而判定该角色不可用、把一次可修正的参数错误升级成整任务死锁。防刷屏交给 G1-C 的回合步数上限。命中时仍写一条 action:"exempt" 的观测日志（无失败历史时不写，避免正常提交刷屏）。

真人用户发来的新消息会重置全部计数（插件自己注入的消息不会）。

工作模式

五档，灰度顺序 shadow → g2b → g2 → g1g2：

| 模式 | 行为 |
| off | 完全透传，不观测 |
| shadow | 观测并写结构化日志，永不拦截（默认） |
| g2b | 仅 G2-B（连续失败）强制拦截 |
| g2 | G2-A + G2-B 拦截，G1 仍只观测 |
| g1g2 | G1 + G2 全部拦截（实验档：零误杀影子期未达标，设置页中标记为 experimental） |

安装与配置

dsh plugin --profile <你的profile> add github:JiewiW/dsh-step-governor#v0.1.3

host + client 双半边插件：加载后在 DSH 设置页出现「步数治理」卡片，14 项配置可直接改并持久化；也可用 GET/POST /plugins/step-governor/settings 读写（GET 返回完整 schema）。

环境变量只作为启动初始值，且优先级最高（env 显式设置的键，设置页保存不会覆盖）：

| 环境变量 | 对应配置 | 默认 |
| DSH_GOVERNOR_MODE | mode | shadow |
| DSH_GOVERNOR_G1A_N | g1aZeroSteps | 4 |
| DSH_GOVERNOR_G1B_K | g1bFingerprintSteps | 6 |
| DSH_GOVERNOR_G1C_MAX | g1cMaxStepsPerTurn | 60 |
| DSH_GOVERNOR_G2A_M | g2aSameTargetCalls | 3 |
| DSH_GOVERNOR_G2B_F | g2bConsecutiveFailures | 2 |

加载成功时 stderr 打印一行：

[dsh-step-governor] {"mode":"shadow","at":"loaded","thresholds":{...}}

实验期间建议用独立配置档 + 独立端口运行，不要直接在日常配置档开启强制档。

能力边界

- G2 的目标键归一化识别不了「换一种方法追同一个目的」（直连 → token → cookie → 本地缓存），那需要理解每步意图。
- 「每步都成功、内容不重复、但整体在偏离任务」属于语义级空转，本插件不覆盖。
- 熔断只让模型更早带着已有证据停手，不保证已交付内容正确。
- 与 goal 自动续跑驱动并存时，pre-step 钩子的注册顺序仍属待核实项。

测试

node --test test/services.test.mjs test/payloads.test.mjs test/settings.test.mjs \
test/test-governor-logic.mjs test/test-integration.mjs

纯逻辑断言 + 伪内核钩子集成断言，共 21+ 用例。shadow / g2b / g1g2 三档真实启动冒烟结果见 SMOKE-REPORT.md。

许可

MIT