前言¶
DeepSeek Harness（DSH）采用插件化架构，旨在通过扩展组件解决长会话中的 Token 开销问题。dsh-token-optimizer 作为一个分层 Token 优化管道，不重复实现 DSH 核心已有的压缩能力，而是基于真实 API 实现增量压缩与调度，帮助在保持模型能力的前提下降低 Token 消耗。
插件定位¶
- 名称：
dsh-token-optimizer - 维护者：Zoria-Lind
- 分类：模型推理
- 许可证：MIT
- 定位：基于 DSH 插件 API 的增量压缩与调度插件。
核心功能¶
该插件通过多个模块协作，覆盖文本处理、工具输出、文件管理和会话调度四个维度：
- 分层压缩编排 (layeredCompact)：实现 L0 观测、L1 无损裁剪、L2 有损压缩的分级策略。
- 长文本转图摘要：针对长文本（≥1000 字符），支持渲染成图并由 Vision 模型读取摘要，动态调整分辨率。
- 工具输出分流：根据输出类型（错误结果、JSON/CSV、Shell 输出）进行结构感知压缩或采样。
- 文件差异检测：检测重复读文件操作，未变则折叠，有变仅发送变更区段。
- 工具可见性管理：通过静态裁剪与 MCP 懒加载，减少无用工具 Schema 进请求。
- 压缩调度：在 Agent 空闲时，按自定义压力比驱动核心压缩，解决长会话窗口无法触发压缩的问题。
- 会话统计：提供会话结束后的 Token 节省统计、真实 Usage 聚合与缓存命中率。
安装¶
在 DSH 项目目录下执行以下命令安装插件：
dsh plugin --profile web add ./dsh-token-optimizer
配置¶
插件挂载后，需在 Profile 的 cordis.patch.yml 中进行配置。由于 Web 部署默认禁用了核心压缩后端，必须手动启用：
- id: compaction-basic
disabled: false
- id: command-compact
disabled: false
插件主要配置节包括：
* text2img：控制长文本转图摘要的阈值、分辨率分档与缓存策略。
* outputLadder：配置工具输出的压缩率、保留头尾行数及 Shell 采样间隔。
* fileDiff：设置文件差异检测的最小大小与上下文行数。
* toolTrim：控制工具可见性管理与 MCP 懒加载开关（默认关闭）。
* compactionDriver：设置触发压缩的压力比（默认 45%）与最小 Token 数。
权限与边界¶
本插件属于高权限插件，运行时需要访问文件、网络、命令与凭据。其具体行为边界如下：
- 文件边界：仅写入插件自有状态目录（
~/.dsh/token-optimizer/）与临时产物，不修改 Profile 配置或 DSH 核心。 - 网络边界：仅向
https://api.deepseek.com/v1发送请求（用于摘要）。 - 命令边界：Windows 上使用 PowerShell + .NET System.Drawing 进行文本渲染；非 Windows 自动降级为仅落盘。
- 凭据边界：仅用于
text2img的 Vision 调用，不落盘、不外传。 - 失败边界：所有模块采用 Fail-open 策略，任一步出错仅降级跳过（保留原文），不影响核心流程。
- 运行时依赖：零 npm 依赖（除外部服务）。
兼容范围¶
- DSH 版本：基于 DSH >= 0.1.1-rc.2。
- Node 版本：Node >= 18。
- 已知未验证版本：0.1.2+ 与 0.1.3+ 尚未验证兼容性。
结语¶
dsh-token-optimizer 通过分层压缩、智能分流与懒加载机制，为 DSH 提供了针对性的 Token 优化方案。其 fail-open 的设计保证了在不稳定环境下的可用性。完整源码与文档可参考 GitHub 仓库。
