dsh-token-optimizer

dsh-token-optimizer

> v3.0.0 变更摘要（2026-10-29）：重写 MCP 工具发现/懒加载（按名称与描述搜索、分页、真实可见性确认、重连恢复）；暂停缺少可靠失效证明的 cache 与 fileDiff；通用设置新增“Token 优化与压缩”（旧驱动/分层/关闭、阈值、状态记录）；新增 runtime 原文归档与 conversation_archive 回查工具；修复预设级摘要/清理服务的作用域读取。升级前请先读下面的“升级到 3.0”。

>

> v2.2：分层压缩编排 layeredCompact（L0 观测 / L1 清理历史工具结果 / L2 模型摘要，默认关）、/token-status、outputLadder 基线重建、按会话分桶统计。

> DeepSeek Harness 分层 Token 优化管道。在 DSH 已内置能力之外做真实增量：

> 把进入模型的文本压缩/裁剪/采样，降低上下文开销；摘要和采样可能丢失细节，任务质量与实际费用需要分别验证。

基于真实 DSH 插件 API（agent/pre-step、tools/execute、tools/post-execute、agent/status 等）实现，

与社区方案文档中虚构的事件(如 message:before / context:building)无关。

它做什么（30 秒版）

| 模块 | 钩子 | 作用 |

| :--- | :--- | :--- |

| text2img | agent/pre-step | 长文本（≥1000 字符）→ 弹窗询问（转图摘要 / 直接阅读原文，推荐项与超时默认按内容类型定）→ 渲染成图 → vision 读图 → 摘要替换进上下文。动态分辨率分档（800×450 / 1440×810 / 1920×1080），摘要磁盘缓存跨会话 0 API 调用。单次样本曾省 ~72%；真正价值是长会话越省（后续轮次不再携带原文） |

| outputLadder | tools/post-execute | 工具输出出生点单次遍历分流：错误结果→300 字符摘要；JSON 数组/CSV（≥10k 字符）→结构感知压缩；shell 输出（≥8k 字符）→头尾+等距采样；≥50k 字节交核心 spill；read 类豁免。原文落盘可逆 |

| cache（暂停） | tools/execute | 默认关闭；glob/grep 每次都重新执行，不复用可能过期的结果 |

| fileDiff（暂停） | tools/post-execute | 当前始终保留原文；不能确认模型请求仍持有基线时不生成 diff |

| toolTrim | agent/created | 工具可见性管理：静态裁剪 + MCP 懒加载——不用的 mcp__* 工具 schema 不进原生工具定义列表；目录按名称/描述搜索与分页，加载后确认真实可见 |

| compactionDriver / layeredCompact | agent/status | 旧驱动或分层互斥调度核心压缩；阈值可配置，准确区分尝试、成功和跳过原因 |

| monitor | session/disposed | 会话结束输出节省统计 + 真实 usage 聚合与缓存命中率(长会话常态 97%–99.3%) |

与 DSH 核心的边界

DSH 已内置 token-meter、compaction-basic、tool-result-pruner、spill、llm-retry、repeat-tool-reminder——

本插件一律不重复实现，只做上面这些内置之外的增量。

安装

dsh plugin --profile web add @zoria-lind/dsh-token-optimizer

本地开发目录也可以直接挂载：dsh plugin --profile web add ./dsh-token-optimizer。

卸载：

dsh plugin --profile web remove @zoria-lind/dsh-token-optimizer

升级到 3.0

这是带破坏性配置语义的主版本升级。升级前请检查 profile 的 cordis.patch.yml：

• toolTrim.allow: [] 的含义反转：2.x 里空数组表示“不限”，3.0 起表示“禁止所有可裁剪的继承工具”（与内核 restrict 的空 allow 语义一致）。想要“不限”请删除该键或写 allow: null。
• 过时的内置工具白名单已移除：bundle 不再硬编码旧工具名。你自己配置的长白名单仍会生效，但会让名单外的新工具不可见，建议人工审阅。
• cache / fileDiff 默认停用：两者都缺少可靠的失效/基线证明，3.0 不再复用缓存或只发 diff 原文片段，即使旧配置写了 enabled: true 也只透传原结果。相关参数保留仅为配置兼容。
• 新增通用设置“Token 优化与压缩”和 runtime 原文归档，默认都不改变你现有的压缩策略。

工具发现与 MCP 懒加载

工具目录不再塞进工具 description 后截断。固定大小的发现工具支持按名称/描述搜索与分页，隐藏后仍可搜索描述，目录末尾也可找到。先成功注册并确认发现工具在当前作用域可见，再隐藏 MCP；注册失败、接口缺失或名字冲突时保留原可见性。以下行为按 DSH 0.2.1-rc.2 的 tools 服务源码核对；真实 API token 节省需要你自己测量。

• 显式 allow/deny 与父作用域限制继续执行；不接管别人注册的同名工具。后续 tools/change 可重试。
• 加载后检查当前作用域的真实 view；失败、用户限制或父作用域拦截会返回原因，不记为成功。重复加载不重复计数；同名重连刷新目录，断开最后一个 MCP 不撤销静态限制。
• cache 和 fileDiff 已暂停，默认关闭；旧配置即使 enabled:true 也只透传。glob/grep 每次重新执行；fileDiff 保留内层决定中的全文、非文本内容及 additionalContexts，不再写其旧原文目录或记录虚假节省。3.0 未建立可靠的文件失效机制，也未证明某份完整文件基线仍在当前模型请求中；仅监听压缩事件不能替代这一证明。
• bundle 移除旧内置工具白名单，避免新工具因名单过期而消失。显式用户策略仍保留，不自动扩大权限。

配置迁移：

• toolTrim.allow 省略或为 null：不设置静态白名单，未来新增内置工具保留可见。
• toolTrim.allow: []：禁止所有可裁剪的继承工具。allow 非空只允许列出的精确名称；deny 优先。未知/已断开的白名单名被移除后，即使名单为空，也不会变成无限制。
• 旧版把 allow: [] 当作“不限”，3.0 起必须改为省略 allow 或 null。旧 bundle 生成的长白名单也需要人工审阅；保留它就会继续禁止名单外 MCP，加载器不能扩大该名单。
• 核心对作用域自注册工具豁免 restrict；本插件的发现工具属于此类。显式 deny 发现工具名会停用该作用域懒加载。父层限制同样作用于继承能力，子代理不能靠本加载器越权；父层白名单若需要让子代理使用继承的发现工具，也应包含该名称。
• cache.ttl 与 fileDiff 的旧参数保留配置兼容性，暂不生效。后续实现可靠失效与当前请求基线证明后，再另行评审是否恢复。

模型调用发现工具的例子（均为 mcp_load_tools）：

~~~json

{"query":"database","offset":0,"limit":10}

{"offset":10,"limit":10}

{"names":["mcp__server__exact_tool_name"]}

~~~

query 默认空字符串，支持名称和完整缓存描述的大小写不敏感子串匹配，最多取前 200 字符；offset 默认 0；limit 默认 10、上限 20；names 每次处理前 20 个并报告忽略数量。结果含 matched/nextOffset/items，加载后仍受限制会列在 failed 中。只在成功确认可见时增加加载计数。目录使用全局公开 view 中的定义作为元数据补充，实际加载始终按 agent 的 view 和过滤权限验证。

验证命令：

~~~powershell

node test/smoke.mjs

node test/modules.test.js

node test/availability.mjs

~~~

smoke 已包含 availability 用例；3.0 发布前 smoke 245 项、modules 4 项、归档专项 19 项通过。测试覆盖 1000 个工具目录、父子作用域、失败恢复、断开重连、立即销毁、真实文件新增/修改，以及跨 cwd/会话/上下文重置时原文保留。定义规模只是测试夹具的 JSON 字节数，不能换算成真实 API token 节省或桌面体验结论。

压缩设置与状态

通用设置新增“Token 优化与压缩”：可选旧驱动、分层或关闭插件自动压缩；工具历史清理和模型摘要阈值支持百分比输入、滑块，观测线及旧驱动阈值在高级设置中。当前默认仍是旧驱动开启、分层关闭，不自动迁移策略。

分层默认值为：40% 仅观测，50% 清理历史工具结果；清理后复测仍达到 65% 才尝试模型摘要。清理会遮蔽部分历史工具结果；摘要可能丢失任务细节。“可以回查”并不保证摘要无损。旧驱动默认 45%，还受至少 6 轮、100000 估算 token 等条件限制。

保存时客户端和后端都校验 0 < 观测线 ≤ 清理线 < 摘要线 < 100%，旧驱动阈值也须在 0% 与 100% 之间。两套开关和阈值一次提交；保存后下一次 idle 检查读取新配置，已经执行的操作使用原配置快照。切换控制器保留各自成功配额和统计；两者不会并发压缩同一 agent。关闭插件自动压缩不关闭宿主自身的安全压缩。

在当前对话运行 /token-status 可查看生效控制器、阈值、估算压力、窗口来源，以及本插件在当前 agent 的最近六条检查/清理/摘要记录。记录区分尝试、成功、无安全有效区段、忙、超时、失败，包含时间、前后估算量、耗时和模型调用是否确认。空结果不记成功、不占成功配额；同一历史上的无效摘要短暂退避。分层在内核报忙后沿用原来的本会话停止自动摘要策略。

窗口来自最近有效 request/context 声明，缺失时采用配置回落值并标明不确定；它不是模型容量的实测结果。上下文估算量减少不等于账单净节省，宿主未提供逐次摘要 usage 时不推算摘要费用。内核自动/手动/其他插件发起的压缩不计入本插件记录。

设置依赖宿主 React、slots、configForms 和可解析的 @deepseek-ai/schemastery。复用宿主模块，不安装新依赖；schema 解析失败不阻断插件。设置未 served、未就绪或只读时，页面显示默认参考/不可编辑提示，仍可用命令检查状态。

设置投影、volatile 配置与 UI 逻辑由自动测试覆盖；真实桌面面板展示与保存仍需实机确认。3.0 未调整宿主摘要保留范围，也未证明模型摘要能保留所有用户原话和约束。