退出码标注 sunruize93-cmyk/dsh-benign-exit

dsh-benign-exit

在 DeepSeek Harness 里确定性地标注 bash/pwsh 的正常非零退出码，让模型不再对正常结果过度排查。

grep 没匹配到内容时退出码是 1——这很正常，不是失败。但 DeepSeek Harness 的 bash 工具会告诉模型：

“检查每个 bash 结果上的 [exit code: N] 标记；继续下一步之前先排查失败。”

模型跑完 grep 什么都没找到，看到 [exit code: 1]，可能把这条常驻指令理解成“这失败了，得排查”，于是反复检查一个完全正常的结果——白白烧掉请求和 token。

这个插件让退出码在模型真正看到的那一层自我说明：当开头的命令是已知工具、退出码是有据可查的正常结果时，就给模型看到的结果加上标注，让模型明白这个退出码为什么正常。

这句话的适用范围。 对于正常结果，插件确实改变了模型看到的内容（下面用真实的 harness 机制验证过）。一次实时的前后对比实验发现，在一组精心构造的 4 个任务上，计费输入 token 合并后减少 20%（见下文）——但单次运行的典型效果很小（约 +3%），收益集中在 shell 密集的重复验证任务上。完整的诚实拆解见实验一节。

工作原理

分两层：

1. 结果层（确定性）。 一个 tools/post-execute 钩子会改写 bash / pwsh 结果中模型看到的内容，但只在结构化结果确认是真正的非零退出时才动手（没有信号杀死、没有超时、没有中止）。比如，一次真实的 grep 运行没找到任何内容，渲染出来是：

(no output)
(exit 1 = no matching lines — the command's documented meaning) [exit code: 1]

模型看到退出码被标为预期结果——这是对模型所见的改变，与模型心情或提示词措辞无关。

2. 提示词层（强化）。 一小段系统提示词教模型认识正常退出码这套词汇，这样常驻的“排查失败”指引就能被正确理解。（harness 自己的指令没有被删掉；这是一条纠正性说明，不是替代品。）

哪些算正常

内置表只覆盖有据可查的正常结果：

| 命令 | 退出码 | 含义 |
| grep、egrep、fgrep、rg、ack | 1 | 没有匹配的行 |
| diff、cmp、comm | 1 | 输入不同 |
| test、[ | 1 | 条件为假 |
| which、type | 1 | 未找到（信息性） |
| jq -e | 1 | 过滤器求值为 false 或 null |
| git grep | 1 | 没有匹配的行 |
| git diff --exit-code / --quiet | 1 | 存在差异 |
| git diff-index --exit-code | 1 | 存在差异 |

标注插在真实 [exit code: N] 标记上方的一行——标记文本本身从不改写，因为 harness 的 parseExitStatus（UI 终端卡片用它）要求标记必须是字面意义上的最后一行。

覆盖范围与限制（评判前先读这里）

设计上偏保守。 插件只标注单条、简单、前台命令，且要求开头的程序是已知工具、退出码是文档中写明的良性结果。以下情况刻意不覆盖：

- 复合命令（grep -q p f && echo yes、grep x | head、if grep ...; then、$(...)、子 shell）：这类命令报出的退出码含义模糊，因此原样放行。
- 后台任务：job_output 走的是另一个工具，渲染格式也不同（[status: completed, exit code: 1]），不做标注。
- 终端通道（terminal_send / terminal_read）：标记格式不同（exited code=N），不做标注。
- 显式路径（./script.sh）：永远不当作已知工具。
- 包装器（sudo、env、nice、nohup、timeout、sh -c、command、前置环境变量赋值）以及任何重定向（>、<、2>&1、heredoc）：直接拒绝——包装器或重定向失败最终都落在 exit 1，绝不能算到工具头上。
- 真实失败（grep exit 2、任何未知命令、任何不在表中的退出码）：原样放行。内置表是权威依据——用户自定义规则永远不能掩盖内置命令的真实失败。
- 语义限制： 对 test/[/which/type/diff 来说，exit 1 是工具文档中写明的含义，但它仍可能与任务相关（比如 test -f /critical/file 找不到文件，这本身就是答案）。所以标注措辞说的是「如实上报，不要重新排查」，而不是「这没问题」——模型被告知要上报结果，只是别把命令当成坏了。如果你希望 test/which 永远不被标注，用 extraRules 覆盖内置命令是不支持的；请改为在这些场景下关掉 annotate（或者提 issue）。
- Windows 上的 pwsh 被杀：在 Windows 上，被杀的 pwsh 进程最终只留下裸 exit 1，没有信号标记，所以在 Windows 主机上插件完全不标注 pwsh 的结果（真实的 kill 绝不能被掩盖）。在 macOS/Linux 上，pwsh 被杀会报告信号，会被结构化退出码闸门跳过。pwsh 按设计接了钩子，但本仓库没有 e2e 覆盖（这里没有 PowerShell）。

另外注意：DeepSeek Harness 自带一个 grep 工具（@deepseek-ai/dsh-tool-fs-search，在基础 bundle 里），它已经把文件内容搜索从 shell grep 引开，并把「0 matches」当作成功返回。因此本插件要处理的剩余暴露面，主要是非文件搜索类的 grep（git grep、对命令输出做的 grep）、其他良性退出码（git diff --exit-code、test -f、which、diff、rg、jq -e），以及模型那条长期指令——凡是遇到非零退出码就去排查。

安装

需要 DeepSeek Harness 0.1.0-rc.5+ 和 Node ^22.19.0 || >=24.0.0。

from npm (once published)
dsh plugin --profile web add dsh-benign-exit

or from source
git clone https://github.com/sunruize93-cmyk/dsh-benign-exit
cd dsh-benign-exit
pnpm install
dsh plugin --profile web add .
package.json 里的 dsh.bundle 声明会让 dsh plugin add 自动把它注册为生效的配置档层（已针对 0.1.0-rc.5 验证）。添加之后，重启配置档。

要确认它已生效，可以任选一种： bash
dsh --profile web --dump-config | grep benign-exit # should show the layer

或者在智能体里跑一次无匹配的 grep，检查结果在退出标记上方显示 (exit 1 = no matching lines — the command's documented meaning)。

无头 / 一次性任务

--profile headless 同样适用： bash
dsh plugin --profile headless add dsh-benign-exit
dsh --profile headless "search for getLegacyConfig and report whether it exists"

配置

| Key | Type | Default | Meaning |
| annotate | boolean | true | Rewrite benign exit markers in tool results |
| promptSection | boolean | true | Add the benign-exit guidance system-prompt section |
| extraRules | {command, exitCodes, reason}[] | [] | Annotate YOUR tools' benign exits (only for commands not in the built-in table) |

示例： yaml

profile cordis.patch.yml

- insert:
- id: dsh-benign-exit
name: 'dsh-benign-exit'
config:
annotate: true
promptSection: true
extraRules:
- command: my-checker
exitCodes: [3]
reason: 'resource already provisioned'

验证

哪些已被证明 / 哪些没有。 插件会确定性地改写模型可见的文本，下面用真实的 harness 机制做了验证。一次实时的前后对比实验（见上一节）在精心设计的 4 任务集上测了 token / 时间差值；引用任何数字之前，先读一读它诚实的注意事项。机制上已被证明的部分：

- 36 个单元测试，覆盖解析器 / 标注器（边界情况、复合命令拒绝、防遮蔽、结构化退出码门控、包装形式、末位标记锚定）。
- 10 个集成测试，跑在真实的 ToolRuntime 派发管线里（tools/post-execute waterfall）：良性标记会被标注；真实错误（exit 2）、未知命令、非 bash 工具、输出里只是恰好包含 [exit code: 1] 的 exit-0 运行、被信号杀掉的运行、超时的运行，全部原样通过；下游的 additionalContexts 保留；系统提示词段落完成注册。
- 6 个端到端测试，用的是真实 bash 工具（拉起真实的 grep/git 进程）：真实的无匹配 grep 产出模型可见内容 (exit 1 = no matching lines — the command's documented meaning)\n[exit code: 1]；真实的 grep 错误（exit 2）和有匹配的 grep（exit 0）原样通过；有差异的 git diff --exit-code 会被标注；harness 自己的 parseExitStatus 仍然把标注后的结果读作 exit 1（UI 退出标记完好）。

自己跑一遍： bash
cd dsh-benign-exit && npm test # unit tests

integration + real-bash tests run inside a DeepSeek Harness source checkout:

npx vitest run <path-to>/verification/dsh-benign-exit.integration.spec.ts

npx vitest run <path-to>/verification/dsh-benign-exit.real-bash.spec.ts

(set DSH_BENIGN_EXIT_PATH if the plugin lives elsewhere)

真实的前后对比实验（2026-08-17）

我们在 deepseek-v4-flash 上跑了一次真实的前后对比（24 次无头运行：4 个任务 × 3 轮 × 装插件与不装插件）。完整原始数据 + 报告：results/experiment-20260817/。

把 24 次运行汇总起来：步数约少 13%，计费输入 token 约少 20%，估算成本约低 22% —— 但这是按 token 加权的总量，被其中一个任务主导。单次运行的典型效果很小（约 +3%）；汇总时剔除那个主导任务：−2%。唯一可靠的信号来自一个「用 shell 反复重新验证一大片搜索范围」的任务（3 个 after 轮全部优于 3 个 before 轮；计费输入 −38%）。任务集是刻意按负面结果设计的，所以这些数字是有代表性的 bash 工作的上限，不是下限。每个任务上，装与不装插件得到的答案都等价。Harness 会把文件内容搜索引导到内置的 grep 工具（不在本插件范围内），所以回避 bash 的工作流几乎得不到收益。

第三方实测数据（Bohu，2026-08）在同一个任务上对比 dsh 与 pi：请求数 61 对 32，墙钟时间 10:38 对 4:55，输入 token 2.9M 对 548K，成本 $0.17 对 $0.05。那个基准比较的是结构上不同的 harness（把它归因到本插件这一个机制，是作者的假设，不是隔离实验），我们也没有复现那些数字。过度调查循环才是本插件针对的机制；它不声称能补上全部差距。

兼容性

- 截至 2026-08-17，已针对 DeepSeek Harness 0.1.0-rc.5（tool-bash/dsh-tools）测试，cordis 4.0.1，schemastery 3.18.1。本 README 中所有验证都锁定在这个版本。
- DeepSeek Harness 处于开发者预览阶段（「THERE WILL BE COMPATIBILITY-BREAKING CHANGES」）。请锁定版本；本插件锁定注入的 tools/post-execute 与 systemPrompt 接缝，这两处属于核心且稳定。

License

MIT