lordqyxz/dsh-tool-search

dsh-tool-search

面向 DeepSeek Harness 的厂商风格延迟工具加载。复刻了提供商托管工具搜索的延迟加载模型：每个可延迟工具只向稳定请求面贡献其名称和用途，发现工具按需返回完整参数 Schema，已发现的工具通过普通 Harness 执行管线直接调用。

简介（中文）

dsh-tool-search 是一个 DeepSeek Harness（DSH）插件，为工具注册表提供厂商风格的延迟加载（deferred tool loading）能力。

它解决的问题：当宿主注册的工具数量很多时，把所有工具的完整参数 Schema 常驻在请求里会占用大量上下文。本插件的做法是：

- 常驻目录区 — 系统提示词中每个可延迟工具只保留一行「名称 + 截断用途」，注册表不变时字节数完全稳定。
- 搜索展开 Schema — 注册一个 tool_search 发现工具，用精确名加权 + 紧凑 BM25 风格打分（支持 CJK 二元分词）对工具排序，只返回最相关工具的完整参数 Schema。
- 发现后直接调用 — 没有调度器转发。已发现的工具按精确名称直接调用，走完整的宿主执行管线（校验、审批、守卫、超时、结果策略）；单调递增的守卫会拒绝未发现工具的直接调用，并提示自愈路径（先搜索）。
- 按工具发现 — 一次搜索只解锁返回的工具名，不解锁整个工具族。
- 阈值惰性 — 可延迟工具数低于配置阈值时插件完全惰性，所有工具保持全量可见。
- 可恢复 — 发现状态基于事件溯源：搜索结果在 presentation meta 中携带累积发现列表，重建的 agent 状态可从会话日志恢复。

语义

- 常驻目录区。 系统提示词将每个延迟工具列为一行：名称加截断用途。工具注册表不变时字节数保持稳定；注册表变化会重建该区。
- 搜索展开 Schema。 注册的搜索工具对单个工具进行排序，采用精确名加权加上针对名称、描述和参数文本的紧凑 BM25 风格评分，并返回排名靠前匹配项的完整参数 Schema。CJK 查询通过字符二元分词进行分词。
- 发现后直接调用。 没有调度器。已发现的工具按其精确名称调用，并重新进入完整管线（校验、审批、守卫、超时、结果策略）。单调递增的守卫会拒绝未发现的延迟工具的直接调用，并指明自愈的下一步。
- 按工具发现。 一次搜索只解锁返回的工具名，绝不解锁整个工具族。
- 阈值。 低于配置的可延迟工具阈值时插件处于惰性状态：所有工具保持完全可见，搜索工具报告没有任何工具被延迟。
- 恢复。 发现状态基于事件溯源：搜索结果在 presentation meta 中携带累积发现列表，重建的 agent 状态会从会话日志中恢复它。

保留的 run_code 传输保持豁免于延迟和守卫。

配置

| 字段 | 默认值 | 含义 |
| --- | --- | --- |
| toolName | tool_search | 注册的发现工具名称 |
| alwaysVisible | skill, ask_user_question, report, submit_, structured_output | 完整 Schema 保持直接可见的通配符模式（可延迟：从不） |
| threshold | 15 | 可延迟工具数达到或超过此值时激活延迟加载 |
| maxResults | 5 | 一次搜索返回的完整定义最大数量 |
| requireDiscovery | true | 拒绝直接调用未发现的延迟工具 |
| charactersPerToken | 4 | 每个估算 token 对应的 Schema 字符数 |
| descriptionChars | 110 | 常驻目录区中每个工具用途说明的字符上限 |
| deferToolGuidance | true | 移除稳定提示词中每个工具的指导提示段落 |

alwaysVisible 是一个替换列表：扩展时保留默认值。

效率 / 效率对比

方法：120 个合成工具（12 领域 × 10 操作）的真实 JSON Schema。基线 = 全量 Schema 常驻；对比 = 目录区常驻 + 按需搜索。

| Tools | 基线 tok/请求 | 插件 tok/请求 | 常驻节省 | 单次搜索 tok | 回本搜索次数 | Top-1（名称） | R@5（同义改写） | 搜索延迟 |
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 15 | 1849 | 596 | 67.8% | 755 | 1 | 100% | 100% | 108 µs |
| 30 | 3706 | 1025 | 72.3% | 756 | 1 | 100% | 100% | 213 µs |
| 60 | 7347 | 1820 | 75.2% | 756 | 1 | 100% | 100% | 454 µs |
| 120 | 14632 | 3417 | 76.6% | 756 | 1 | 100% | 100% | 986 µs |

基准：bench/run-benchmark.mjs · 回归守护：tests/efficiency.spec.ts · 复现：pnpm run bench

- 1 次搜索即回本：省下的常驻开销一次搜索就覆盖其自身成本，此后每次请求持续净省。
- 质量：精确名称查询全部排第一；不含名称词的同义改写查询 100% 命中 Top-5。

开发

pnpm install          # pnpm 11, Node 22.19+ or 24+
pnpm run typecheck    # tsc --noEmit
pnpm run lint         # oxlint src tests
pnpm run test         # vitest run
pnpm run bench        # build + efficiency benchmark
pnpm run build        # tsc -> lib/
pnpm run check        # typecheck + lint + test + build

局限性

- 排序基于词法；词汇差异（repository 与 project、remember 与 save）可能导致排序错误。常驻目录区会保留每个名称和用途的可见性，以便模型可以用精确词汇再次搜索。
- 描述是排序的输入；描述为空或过于笼统的工具排序效果较差。

许可证

MIT

标签

deepseek-harness · dsh · cordis · tool-search · deferred-loading · tool-deferral · context-optimization · token-optimization · system-prompt · plugin · typescript