前言¶

DeepSeek Harness（DSH）的插件生态中，当工具目录变得庞大（例如集成多个 MCP 服务器或大量插件工具）时，每个工具的 JSON 模式都会在每一轮对话中被注入到模型上下文中。这会导致大量无关的 token 消耗，降低推理效率。dsh-tool-search 旨在解决这一问题。它采用 Hermes Agent 的“渐进式披露”设计理念，将长尾工具折叠在后台，仅通过三个桥接工具按需加载，从而控制模型可见的清单规模。

安装¶

安装该插件需要使用 DSH 的命令行工具。在终端中执行以下命令：

dsh plugin --profile web add dsh-tool-search

核心能力¶

该插件的核心功能围绕“按需可见”和“核心保留”展开：

1. 分级披露：根据当前上下文窗口预算和工具目录大小，动态调整模型可见的工具列表。
2. 桥接工具：提供 tool_search、tool_describe 和 tool_call 三个桥接接口，用于替代原本冗长的工具清单。
3. 急切加载：文件操作、Shell 执行及核心必备工具始终直接可见，无需折叠。
4. 动态注入：通过搜索或调用工具后，该工具会被注入到可见上下文中（受 LRU 限制），以便在后续轮次直接使用。

工作原理¶

插件通过监听 system-prompt/assemble 事件来计算“分级”（Tier），并替换模型可见的工具列表。

分级逻辑取决于“预算”计算，公式为 min(thresholdPct% × contextWindow, listingMaxTokens)，并在每一轮对话中重新计算：

• Tier 0：当目录较小或无可折叠工具时，所有工具直接可见。
• Tier 1：当分组后的清单适合预算时，显示桥接工具以及分组标题和描述（## group）。
• Tier 2：当仅工具名称适合预算时，仅显示桥接工具和名称列表。
• Tier 3：当名称也溢出时，仅显示桥接工具，每组一行（如 group_name: 5）。

动态执行：当 tool_call 被调用时，插件通过 ctx.tools.execute 执行真实的工具，而非桥接工具。这意味着审批机制、防护墙和会话事件仍然引用原始工具，而非桥接层。搜索功能默认使用配置的重排序匹配器，若失败或未配置，则回退到关键词匹配（精确名称 > 名称片段 > 描述片段）。

对话式设置¶

插件内置了 tool-slimmer-setup skill，支持通过对话完成配置。你可以直接向 Agent 提出以下请求来启动设置流程：

帮我配置 dsh-tool-search 的工具分组

该 skill 会读取目录，提议分组方案，确认后引导你选择全局或项目级配置，并协助配置重排序匹配器。

配置¶

配置分为静态配置（重启生效）和运行时配置（热重载）。

1. 静态配置
静态配置位于 profile 的 cordis.patch.yml 文件中：

- id: tool-search
  config:
    enabled: auto        # auto | on | off
    thresholdPct: 5      # 清单预算占上下文窗口的百分比
    listingMaxTokens: 4000
    configScope: auto    # user | project | auto (项目文件优先)
    core: [todo_write]   # 额外的始终急切工具
    maxWarmTools: 8      # 动态注入工具的 LRU 上限

2. 运行时配置
工具分组、匹配器和预加载配置位于运行时文件中。用户级路径为 ~/.dsh/dsh-tool-search.json：

{
  "version": 1,
  "scope": "user",
  "groups": [
    { "name": "git", "tools": ["git_status", "git_diff"] },
    { "name": "mcp-github", "prefixes": ["mcp_github_"] }
  ],
  "matcher": {
    "endpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1/rerank",
    "apiKey": "sk-...",
    "model": "qwen3-reranker",
    "topN": 20
  },
  "preload": { "enabled": false, "topK": 5 },
  "core": ["read_file", "write_file"]
}

• groups：精确工具名或前缀，匹配优先级取决于定义顺序。
• matcher：必须是 OpenAI 兼容的 /v1/rerank 端点，否则搜索功能将不可用。
• preload：可选功能，启用后会在首轮对话中预加载语义匹配度最高的 K 个工具。
• 文件支持 mtime 监听，修改后下轮对话生效。

桥接工具¶

插件提供三个主要的桥接工具供模型调用：

适用场景与注意¶

该插件适合拥有大量第三方工具或 MCP 服务器的 DSH 项目。在使用前，请确认以下几点：

1. 权限运行：插件以当前 DSH 进程的权限运行，安装前应检查源码与许可证。
2. 注册表完整性：精简仅重写模型可见的表面，底层注册表保持完整，延迟工具仍可被正常执行。
3. 重排序优先：关键词匹配仅作为后备手段，核心搜索依赖重排序模型。
4. 上下文依赖：清单基于运行时上下文，可以适应完整的提示词组合。

参考资料¶

• GitHub 仓库
• DeepSeek Harness 官方文档