前言¶

在 DeepSeek Harness (DSH) 的开发中，处理超长工具结果是一个常见痛点。DSH 自带两种机制：dsh-spill-policy 和 dsh-compaction-tool-result-pruner。前者在结果超过 50KB 时触发，后者在文本超过 8192 字符且满足压缩压力条件时触发。前者支持无损恢复，后者在模型侧无法恢复中间内容。本文介绍的插件填补了这个空白，旨在解决中间态结果的剪枝与恢复问题。

这是什么¶

这是一个针对 DeepSeek Harness (DSH) 的 dsh-plugin。其核心功能是在工具执行后，优先将过大的纯文本结果溢出到文件，然后用包含精确截断位置和文件定位符的头部/尾部预览替换原始结果。这确保了模型始终可以通过 read、grep 或 sed 恢复被截断的中间内容，且没有任何数据丢失。由 may3rr 维护，遵循 MIT 许可证。

核心功能¶

1. 无损剪枝：针对 DSH 的工具结果进行剪枝，确保不丢失任何数据。
2. 先溢出后剪枝：将过大的纯文本结果优先写入文件，再在返回给模型的内容中保留头部和尾部。
3. 精确定位：预览内容包含被截断的精确范围和溢出文件的路径。
4. 可恢复性：模型可以通过 read、grep 或 sed 在溢出文件中找回被截断的中间部分。
5. 监听器模式：作为 tools/post-execute 水位线监听器运行，在工具投影和其他钩子之后执行剪枝。
6. 幂等性：剪枝后的内容始终在阈值范围内，不会重复剪枝。

安装与启用¶

安装只需一条命令：

dsh plugin --profile web add dsh-tool-result-guard

安装后重启 DSH。插件会自动应用到该 profile 下的所有智能体预设。

配置文件位于 ~/.dsh/profiles/web/cordis.patch.yml：

- id: tool-result-guard
  config:
    thresholdChars: 16384

典型用法¶

恢复被剪枝的内容
当模型收到类似以下的剪枝结果时：

[pruned: kept chars [0, 4096) + [28976, 30000) of 30000; the elided middle
[4096, 28976) is NOT lost — full output saved at: /tmp/dsh-spill/.../bash.txt.
Recover any elided span with the read tool (offset/limit), grep, or sed on that file.]

<head: first 4096 chars>
...
<tail: last 1024 chars>

模型可以使用 read 工具（配合 offset/limit 参数）、grep -n 或 sed -n 'X,Yp' 在溢出文件中读取被截断的部分。

配置剪枝阈值
在配置文件中调整剪枝参数：

- id: tool-result-guard
  config:
    thresholdChars: 8192    # 超过此字数开始剪枝
    headChars: 4096          # 保留前多少字符
    tailChars: 1024          # 保留后多少字符
    excludeTools: ["read"]   # 不剪枝这些工具的结果

适用场景与注意¶

适用场景
适用于需要处理中等长度（8K-50K 字节）工具结果的场景，这些结果超过了 dsh-compaction-tool-result-pruner 的处理范围但未达到 dsh-spill-policy 的阈值。适合追求模型侧完全可控、无数据丢失的 LLM Agent 开发。

注意事项
1. 配置限制：headChars + tailChars 必须小于 thresholdChars，否则标记无法放入结果中。
2. 容错机制：如果溢出文件写入失败，插件会保持原始内联结果不变（Fail-open），不会导致任务报错。
3. 配置键检查：配置文件中未知的键会导致加载失败，需严格使用支持的字段。
4. 依赖要求：需要 Node.js 环境版本 >= 18。
5. 权限与安全：插件以当前 DSH 进程权限运行，安装前请检查源码与许可证。

短结尾¶

通过 dsh-tool-result-guard，DSH 开发者可以解决工具结果中间态剪枝不可恢复的痛点。它通过文件溢出与精确标记，确保了上下文管理的完整性。更多细节请查看插件目录或源码仓库。