dsh-tool-result-trimmer

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

dsh-tool-result-trimmer





[English](README.md) | 中文

dsh-tool-result-trimmer 是专为 DeepSeek Harness (DSH) 与 Cordis 打造的轻量级、零运行时依赖的即时工具输出修剪插件。它直接挂载在工具执行流水线上，在超大输出进入会话历史与 LLM 上下文之前实现即时裁剪、命令感知语义提纯、结构化 JSON 保护与可追溯磁盘恢复，从源头杜绝上下文污染。

---

为什么需要 dsh-tool-result-trimmer？

传统上下文优化（如压缩阶段的修剪插件）属于事后被动补救：巨量输出已先完整写入 Session 日志和内存，等到上下文接近上限时才通过复杂的事件重放做节点替换，容易造成界面卡顿、日志膨胀与压缩抖动。

dsh-tool-result-trimmer 采用“治未病”的主动流水线截断：

1. 时机提前（Eager Trim · 零日志死重）：

直接挂载于 DSH 官方 tools/post-execute 瀑布流流水线。超长结果在进入持久化日志、提交给模型上下文之前就已经被裁剪完毕。

2. 权重倒置（Tail-Heavy · 强化尾部）：

命令行与编译测试的最关键报错信息（断言失败、异常堆栈、Exit Code）永远在末尾。默认策略：头部保留 1,500 字符（查看命令启动入参与初始状态），尾部保留 5,000 字符（完整保留关键报错与原因）。

3. 命令感知语义压缩器（Semantic Reducers · 严格 Fail-Open）：

内置针对高频开发命令的智能提纯器。在进入截断前优先提纯信息，遇错严格放行（Fail-Open）：

• Git Reducer：干净工作区一键收敛为单行，脏工作区自动剥离 (use "git add...") 样板提示，100% 完整保留修改文件列表；剥离 git diff 无效的 index 哈希行。
• Package Manager Reducer：自动过滤 npm/pnpm/yarn/pip 进度条、peer deprecation 杂讯、funding 提示与升级提醒，完整保留安装包统计与漏洞审计。
• Test Reducer：当且仅当测试全量通过时（node --test, vitest, pytest, cargo test 等），将数百行冗长打勾日志折叠为单行摘要；一旦有任何用例失败，绝不压缩，完整保留所有报错堆栈与断言现场。
• Build 与 Lint Reducer：仅在明确成功时保守压缩可识别的不含路径的 Vite/Cargo/webpack 进度或重复 Prettier 检查提示，保留 warning、error、路径及未知输出。

4. 结构化 JSON 保护（Structured Output Protection）：

默认完整保留合法 JSON（mode: preserve），即便超出字符阈值也绝不暴力破坏语法结构；可选 mode: summary 安全采样超大顶层数组并生成合法的带标记 JSON 摘要；亦支持 mode: off 恢复旧版普通截断。

5. 受控可追溯持久化（Controlled Spillover）：

识别并复用 bash 或官方 spill-policy 已有的恢复提示；新增存储优先使用宿主按会话管理的 ctx.spillStore，保留定位符和读取指引。独立使用时回退到具备原子写入、容量上限、TTL 清理和跨进程锁的本地文件（spillover.enabled: true 默认启用）。

6. 行吸附算法（Line-Aware Snapping · 绝不截断代码行）：

优先吸附附近的换行符（\n），必要时回退到字符边界，并严格避免拆开 UTF-16 代理对。

7. 终端 ANSI 控制字符自动剥离（Clean Terminal Output）：

自动识别并清洗终端 ANSI 颜色转义码（\x1b[31m 等）、光标移动/清行控制序列（\x1b[2K、\x1b[1G）及窗口标题序列，杜绝无意义杂质字符浪费 Token，大幅提升模型对编译报错与日志信息的解析精度。

8. 零副作用安全保护：

• 文件读取保护：默认自动跳过 read 与 read_image 工具，保证文件查看行号与内容绝对精准。
• 多模态内容保护：图片等非文本块原样透传，不影响任何多模态交互。
• 紧急逃生机制（Bypass）：支持命令内标记（# no-trim、DSH_TRIM_BYPASS=1）快速全量放行。

---

安装

通过 DSH 插件命令安装（推荐）

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

通过 npm / pnpm 安装

npm install dsh-tool-result-trimmer
# 或
pnpm add dsh-tool-result-trimmer

---

配置使用

1. 开箱即用（推荐，零配置）

所有核心功能（即时首尾裁剪、ANSI 清理、命令语义压缩、结构化 JSON 保护以及本地 Spillover 落盘恢复）默认全部启用，开箱即用无需任何额外配置。

如果你是通过 DSH 插件市场（Web 界面）或 dsh plugin add 安装的，插件已作为 Bundle 自动装载并生效。无需修改或添加任何 cordis.patch.yml 配置。

2. 高级自定义配置（可选）

如需定制字符预算、切换特定压缩器、修改落盘目录或指定单工具预算，仅需在你的 profile cordis.patch.yml 中通过插件唯一 ID tool-result-trimmer 覆盖需要定制的字段（未声明字段自动沿用默认值）：

- id: tool-result-trimmer
  config:
    thresholdChars: 15000     # 触发裁剪的安全阈值（默认 10000）
    headChars: 2000           # 头部保留字符预算（默认 1500）
    tailChars: 8000           # 尾部保留字符预算（默认 5000）
    overrides:                # 针对特定工具的差异化预算或独立开关
      bash:
        thresholdChars: 20000
        headChars: 2000
        tailChars: 8000
      git:
        enabled: false        # 单独对此工具关闭裁剪
    semanticReducers:         # 命令感知语义压缩器控制
      enabled: true           # 是否启用语义压缩（默认 true）
      git: true               # Git 状态与差异提纯
      packageManager: true    # npm / pnpm / yarn / pip 冗余过滤
      test: true              # 测试全通折叠与严格 Fail-Open
      build: true             # 已识别的成功构建进度
      lint: true              # 已识别的成功格式检查进度
    structuredOutput:
      mode: preserve          # preserve（默认）、summary 或 off
    metrics:
      enabled: false          # 显式启用计数，通过 Cordis logger 输出
    spillover:                # 受控的截断内容本地落盘备份
      enabled: true           # 是否在发生机械裁剪时将完整原文落盘（默认 true）
      directory: null         # 存储目录（null 默认使用系统临时目录下的 dsh-trimmed）
      maxFileBytes: 20000000  # 单个备份文件最大字节数（约 20MB）
      maxTotalBytes: 200000000 # 备份目录总容量预算（约 200MB）
      maxFiles: 1000          # 备份文件最大数量上限（1000 个）
      ttlMs: 604800000        # 日志过期清理时间（7 天）
      onSemanticReduction: false # 仅语义压缩时也保存原文并提供恢复路径

注意：如果插件已通过 DSH 安装（已作为 bundle 装载），请勿在 cordis.patch.yml 中添加 - name: dsh-tool-result-trimmer，直接使用 - id: tool-result-trimmer 进行属性覆盖即可，避免重复注册实例化。

3. 自定义预设或纯 Cordis 环境（高级）

如果你正在自建独立的 Agent Preset，或在脱离 DSH profile bundle 体系的纯 Cordis 环境中使用，可通过包名显式声明引入：

- name: dsh-tool-result-trimmer
  config:
    thresholdChars: 10000
    spillover:
      enabled: true

配置项说明

字段 · 类型 · 默认值 · 说明

enabled · boolean · true · 是否启用该修剪插件。

stripAnsi · boolean · true · 是否自动剥离终端 ANSI 颜色与光标控制字符（大幅节省 Token）。

thresholdChars · number · 10000 · 全局安全触发阈值（字符数）。建议配置大于 headChars + tailChars（默认 6500）。输出小于等于该值或未超出保留预算总和时直接放行，零对象分配。

headChars · number · 1500 · 全局头部保留字符预算（保留初始执行上下文）。

tailChars · number · 5000 · 全局尾部保留字符预算（优先保留错误堆栈与退出状态）。

excludeTools · string[] · ['read', 'read_image'] · 免于裁剪与清洗的工具列表。

overrides · Record<string, ToolOverride> · {} · 按工具完整名称匹配，优先于工具类别默认预算。支持 thresholdChars、headChars、tailChars、stripAnsi；enabled: false 跳过插件，交由宿主策略处理。

semanticReducers · object · { enabled: true, ... } · 命令感知语义压缩器配置。包含 enabled、git、packageManager、test、build、lint 开关，可单独按需控制。

spillover · object · { enabled: true, ... } · 受控的截断日志本地落盘设置（enabled、directory、maxFileBytes、maxTotalBytes、maxFiles、ttlMs、onSemanticReduction）。

structuredOutput.mode

…(truncated)