结果字节截断 jwilson411/dsh-result-cap

dsh-result-cap

一个 [DeepSeek Harness][dsh] 函数插件：对工具结果施加确定性的字节上限，并附带凭据。

智能体调用一个抓取工具。页面有四兆字节。整个内容进入对话，然后运行就结束了——不是因为出了什么故障，而是因为一个结果吃掉了上下文。

本插件保留前 maxBytes 个 UTF-8 字节，丢弃其余部分：

{
"text": "…the first 8192 bytes…", "truncated": true, "omitted_bytes": 4103217, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }

关于这个对象有三件事成立，而每一件都是重点：

- truncated: true 始终存在。 能放得下的结果会逐字节原样返回，没有包装、没有标志，因此该标志的出现才真正有意义。任何内容都不会被悄悄缩短。
- sha256 是完整原始内容的摘要，而不是前缀的摘要。被缩短的结果指明了被截断的那个东西，因此之后拿到的完整副本可以与之核对。
- 前缀是合法的 UTF-8。 跨越限制的多字节字符会被整体丢弃，而不会被切成一段残缺的序列、解码成 �。

而且，相同的结果配上相同的上限，总是产生相同的输出，摘要也包含在内。这条路径上没有任何时钟、计数器、随机性，也没有任何模型调用。

它不是什么

不是 Headroom。 它不管理上下文窗口，不决定什么该放进窗口，也不重写对话。它一次只给一个工具结果设上限，对运行的其余部分一无所知。

不是压缩器模型。 这个包不调用任何模型。没有压缩器，没有编码器，没有任何学习得来的东西——它只是切分一个字节数组并对其做哈希。

不是语义压缩。 没有任何东西会按相关性被打分。前 N 个字节就是前 N 个字节，仅凭计数选出，别无其他，这正是输出可复现的原因。

不是摘要器。 前缀就是前缀。它不是梗概、不是摘要、也不是改写；它是结果字面意义上的开头，只是缺了尾部，而 truncated 标志说明了这一点。

不是静默截断。 这正是本包存在所要避免的失败模式。一个悄悄缩短结果的上限，会把一个看起来像完整答案、实则结尾已丢失的东西交给模型，而下游没有任何东西能分辨出来。这里每一个被缩短的结果都被打上标签、标注大小并做了哈希。

不是配额。 它不统计调用次数，不拒绝任何东西，也不会让运行失败。

与 dsh-tool-quota 的比较

[dsh-tool-quota][quota] 同样给结果字节设上限，但对超限的结果做了相反的事：它抛出 TOOL_QUOTA_BYTES 并整体丢弃结果，从不截断。本包则截断并继续。

根据工具返回过多内容时应该发生什么来选择：

| | 超限时 |
| dsh-tool-quota | 调用失败，TOOL_QUOTA_BYTES，不返回任何内容 |
| dsh-result-cap | 返回带标签的前缀，运行继续 |
它们可以组合使用。在配额之后用这一行同时安装两者，配额的字节上限就会变成一个封顶结果再也无法触及的天花板——把 maxResultBytes 设为高于 maxBytes，配额就只会对本插件放行的那些形态触发，比如一个过大的二进制结果。

什么会被封顶

v1 只对字符串封顶。 两种形态：

- 一个裸字符串结果，以及
- 结果对象的 text 字段，当它是一个自有、可枚举的字符串时。

其他一切原样放行：数字、布尔值、null、数组、Buffer、类型化数组、图像、{ mimeType, data } 媒体，以及任何没有字符串 text 的对象。PNG 没有有用的前缀，硬造一个只会损坏结果而不是缩短它。任意对象也绝不会被 JSON 字符串化后再测量——嵌套的巨型字符串会被原样保留，而不是被近似处理。

上限以 UTF-8 字节计数，不是字符数，也不是 JavaScript 字符串长度。'€'.repeat(20) 是 20 个码元、60 个字节；在 30 字节的上限下，十个欧元符号能存活。

安装

dsh plugin --profile default add github:jwilson411/dsh-result-cap

安装器会从包清单中读取 dsh.bundle.patch，并将此包追加到该 profile 的有序 bundle 列表。它的 cordis.patch.yml 携带一行插入行，id: result-cap，配置为空——因此在 profile 另行指定之前，包默认的 8192 字节生效。

将 tools 包固定到 0.1.1-rc.2；这是本插件开发和测试所针对的候选发布版本。

配置

一个键。

- id: result-cap
config:
maxBytes: 32000

maxBytes 是一个结果中有多少 UTF-8 字节能进入对话。它默认为 8192——几页文本：大到普通工具结果永远不会被触及，小到抓取了整个页面的工具不会意外花掉一个上下文窗口。

它必须是至少为 1 的整数。带引号的 "8192" 会被接受，因为 YAML 加引号是个容易犯的意外。浮点数、负数、零、布尔值或单词会在插件应用时被拒绝——抛出携带 code: 'RESULT_CAP_CONFIG' 的 InvalidResultCapConfigError——而不是被悄悄替换为默认值。未知键也是如此：maxByte: 200 会大声失败，而不是永远意味着 8192。一个没人看得见的上限，比一个拒绝启动的 profile 更糟。

请注意，以 id 为目标的补丁会替换该行的整个 config 块，而不是合并进去，因此覆盖必须重述它想保留的每一个键。

环境变量

DSH_RESULT_CAP_MAX_BYTES 为一个从未编辑过其 profile 的部署设置上限。优先级是配置，然后环境变量，然后默认值：profile 作者写下并审阅过的内容，胜过三层之上某个 shell 碰巧导出的东西。变量中不可用的值会以与配置中不可用的值相同的方式被拒绝。

直接使用它这个 cap 是一个普通函数，从包根目录以及 dsh-result-cap/cap 导出：

import { capResult } from 'dsh-result-cap'

capResult('short enough', 8192)
// → 'short enough' (the same string, unchanged)

capResult('x'.repeat(20000), 8192)
// → { text: 'xxxx…', truncated: true, omitted_bytes: 11808, sha256: '…' }

没有上下文，没有注册表，没有插件——便于测试，也便于那些希望把 cap 放在工具边界之外的主机使用。

它是如何接入的

有两个接缝，因此工具被调用的两种方式都能覆盖：

- ctx.tools.register 被打补丁，因此在这个 fiber 的生命周期内注册的每个定义都会返回经过 cap 的结果。注册表自身的 disposer 会被原样传回，因此所有权和重载清理保持原样。
- ctx.tools.execute 在运行时暴露它时被打补丁，这样可以捕获在此插件启动之前注册的工具。这是有意设为可选的：没有公开 execute 的运行时仅靠 register 补丁即可覆盖，且不会触及任何私有 API。

同时经过两者的调用会被 cap 两次、缩短一次——内层包装器产生的值已经在 cap 之下，而对一个符合要求的值进行 cap 会原样返回它。

cap 在工具主体返回之后运行。抛出的错误原样传递：错误不是结果，在这里吞掉错误会把工具失败变成一次简短的“成功”。没有可调用 execute 的定义会被原样注册。当上下文提供该钩子时，两个补丁都会在 dispose 时撤销。

没有注册任何面向模型的工具。v1 无法请求尾部——sha256 的存在是为了让省略可被识别，而不是为了让它可被撤销。如果尾部很重要，请提高 cap 或要求工具返回更少内容。

开发

npm install
npm test

node:test，无网络，无 API key，无权重，无需下载 fixtures。

许可证

MIT © 2026 jwilson411。参见 LICENSE。

[dsh]: https://github.com/deepseek-ai
[quota]: https://github.com/jwilson411/dsh-tool-quota