dsh-compactor：DeepSeek Harness 的上下文压缩插件

前言¶

DeepSeek Harness（dsh）采用「一切皆插件」的架构，旨在通过插件扩展系统能力。在长会话场景中，模型的输入由全部历史消息组成，其中工具结果（如搜索结果、文件内容、命令输出）往往占据上下文的大部分，且包含大量对后续推理无价值的细节。此外，重复的工具调用和冗长回复会持续膨胀上下文，甚至诱发死循环。

dsh-compactor 是由 lionwill 维护的上下文压缩插件。它在不破坏 dsh append-only 会话日志的前提下，通过三层处理机制（实时层、批处理层、归档层）对上下文进行剪枝与摘要，并提供了死循环护栏与数据回滚功能。

核心能力¶

该插件主要解决长会话上下文膨胀问题，核心能力包括：

三层处理机制：
- 实时层：在工具结果（tool/result）进入事件流时，按固定策略剪枝（例如搜索只留标题/链接，文件只留预览）。
- 批处理层：当会话 token 量超过阈值时，将可压缩片段（工具结果、冗长回复）替换为摘要，压缩边界自动对齐，最近 N 轮消息不会被触碰。
- 归档层：被替换的原文写入 append-only 归档目录，支持通过命令完整还原。
两种摘要引擎：
- API 摘要：依赖 DEEPSEEK_API_KEY，调用 deepseek-chat 进行骨架化摘要；无 Key 时自动降级。
- 本地规则压缩：基于正则与固定规则（如折叠重复句、截断长输出），无需网络请求，零额外依赖。
命令与工具：
- 语义理解压缩 (/su-compact)：将意图和策略喂给 LLM，保留关键结论。
- 本地规则压缩 (/local-compact)：基于规则文件执行压缩，需用户确认。
- 数据回滚 (/restore)：将压缩过的原文重新注入会话。
- 死循环护栏：监测工具调用，触发阈值时注入防循环提示或记录取消判定。

安装与启用¶

插件以 dsh 宿主权限运行，安装前请确认来源可信。

推荐使用本地目录安装（file: 协议），无需处理 git 构建脚本：

# 1. 克隆仓库
git clone https://github.com/lionwill/dsh-compactor.git
cd dsh-compactor

# 2. 构建产物（lib/ 目录由 prepare 钩子自动生成）
npm install && npm run build

# 3. 安装插件
dsh plugin add "dsh-compactor@file:$PWD"

命令与用法¶

安装完成后，dsh 会通过 bundle patch 显式重新启用内置的 /compact 命令。本插件新增以下命令：

本地规则压缩：
首次调用仅输出风险说明，需用户确认后执行：

    /local-compact confirm

语义理解压缩：
利用 LLM 理解上下文意图并生成摘要：

    /su-compact

数据回滚：
恢复最近一次压缩操作的数据：

    /restore

配置方式¶

插件通过 cordis.patch.yml（内置）或环境变量进行配置。主要配置项包括：

thresholdTokens：触发压缩的 token 阈值（默认 32768）。
targetTokens：压缩后的目标 token 数（参考值）。
qualityThreshold：关键信息保留率告警阈值（默认 0.85）。
exemptTools：豁免工具列表（默认 write、edit、task）。
localRulesPath：自定义本地规则文件路径。

示例配置片段：

- insert:
    - id: dsh-compactor
      name: dsh-compactor
      config:
        thresholdTokens: 32768
        targetTokens: 8192
        retainRecentRounds: 3
        qualityThreshold: 0.85
        exemptTools: [write, edit, task]
        enablePruning: true
        enableSummary: true

注意事项¶

信息丢失：压缩是“保留骨架、丢弃细节”的过程。snippet、长输出中段等细节可能丢失，若后续推理依赖这些细节，结果质量可能下降。
Token 估算偏差：插件使用启发式方法估算 token，与真实计费 token 存在偏差。
权限风险：插件以宿主权限运行，仅建议从可信来源安装并 pin 版本。
归档目录：默认为 $DSH_DATA_DIR/archive/ 或 ./.dsh-compactor-archive/，请确保目录可写且不要手工编辑。
命令冲突：本插件通过 patch 显式重新启用 dsh 内置的 /compact。如果同时安装了其他注册同名 /compact 的插件，可能会出现命令冲突导致失效。
热重载：修改规则文件后无需重启会话，每次执行 /local-compact 均会重新读取。