前言¶
在 DeepSeek Harness（dsh）里接 MCP、技能和普通工具之后，每轮对话的系统提示往往会带上大量工具 schema。插件和类别越多，占用的上下文越长，模型却未必每轮都用得上全部能力。常见做法是手工把工具分成几组、改可见性，但类别一多就要跟着维护名单，和新装插件也容易脱节。
dsh-tool-compass（维护者 nidehogger）的做法是：让模型默认只看到按任务场景归类的工具目录，需要具体能力时用 tool_search 检索，命中的工具才在当前 Agent 会话里展开。分类本身由默认模型在启动或工具变更时完成，并写入本地目录文件，属于 DSH 社区目录里「工作流」分类下的插件。插件在本地以当前 dsh 进程权限运行，安装前建议自行查看仓库源码与 MIT 许可证。
这是什么¶
一句话：dsh-tool-compass 是为 dsh 提供的工具罗盘——agents 先见功能类别，再按需拉取具体工具，用来削减每轮请求里工具 schema 占用的 token。
它针对的是「工具 schema 挤占上下文」这一具体问题；与纯手写分组相比，分类由插件调用默认模型按「用户任务场景」生成，并支持增量合并与手动重建。
模型侧看到什么¶
安装并启用后，系统提示里只呈现类别名、描述、数量，不罗列每个工具名。
下列工具默认常开（还包含四个路由相关工具）：bash、read、write、edit、glob、grep、web_search、web_fetch、todo_write、skill、ask_user_question、present。
其余工具默认隐藏；若直接调用会收到 UNKNOWN_TOOL，需先通过 tool_search 检索并在当前会话中开放（下一步生效）。技能命中后需用 skill 工具加载。
核心功能¶
分类与目录¶
- 首次分类：插件加载后调用一次默认模型，将当前全部 tools + skills 按任务场景归类，写入
~/.dsh/tool-compass.json。 - 增量分类：监听
tools/change，有新工具时再次调用模型，只归类新增项并合并进已有类别。 - 手动重建：通过
tool_router_refresh，new为增量、all为全量清空重建。 - 兜底：默认模型不可用或输出不合法时，退化为关键词归类（fail-open），保证插件仍可用。
分类变更只改写目录文件与系统提示，不改变工具在 Harness 里的注册关系。
四个路由工具¶
| 工具 | 作用 |
|---|---|
tool_search(query, limit?) |
按名称/描述/类别检索；命中的工具对当前会话开放 |
tool_catalog() |
查看类别目录 |
tool_router_refresh(mode?) |
new 增量、all 清空重建 |
tool_router_status() |
查看「目录分类 / 已登记 / 当前可见」数量，并提示是否需要重建 |
「开放」状态按 Agent 会话隔离，不跨进程重启持久化；重启后重新检索即可。子代理与其他会话不继承某次检索的可见性。
任何一步失败时插件 fail-open：恢复原工具可见性，避免把 Harness 卡在不可用状态。目录变化会使对应前缀的 prompt cache 失效一次。
安装与启用¶
要求 DSH >= 0.2.2-rc.1、Node.js 20+。当前 package 版本为 0.1.0。
下面介绍官方 README 中的安装方式（勿凭仓库名自行拼接 github:owner/repo 命令）：
# 从 npm（发布后）
dsh plugin --profile web add dsh-tool-compass
# 本地目录
dsh plugin --profile web add link:/path/to/dsh-tool-compass
安装后重启一次 DSH。可用下面命令确认目录文件是否生成及类别、工具、技能数量：
python3 -c "import json;d=json.load(open('$HOME/.dsh/tool-compass.json'));print(len(d['categories']),sum(len(c['tools']) for c in d['categories']),sum(len(c['skills']) for c in d['categories']))"
在对话中调用 tool_catalog 或 tool_router_status 亦可验证是否生效。
配置片段¶
在插件配置中常见字段如下（摘自文档）：
- id: tool-compass
name: 'dsh-tool-compass'
config:
enabled: true
classifyOnStart: true
classifyOnChange: true
| 字段 | 默认 | 说明 |
|---|---|---|
enabled |
true |
关闭后不注册工具、不隐藏工具 |
catalogPath |
~/.dsh/tool-compass.json |
分类目录文件 |
classifyOnStart |
true |
启动后自动分类（目录为空则全量，否则增量） |
classifyOnChange |
true |
工具变化时自动增量分类 |
classifyDelayMs |
4000 |
启动后等待工具注册完成再分类 |
searchLimit |
6 |
单次检索返回条数上限 |
alwaysVisible |
核心工具列表 | 始终对模型可见的工具名 |
典型用法¶
- 装好插件并重启 DSH，等待首次分类写入
tool-compass.json（若classifyOnStart为 true）。 - 在 Agent 对话里执行
tool_catalog()，确认类别与描述是否符合当前工具集。 - 需要某类能力时调用
tool_search，例如按功能关键词检索；命中后于下一轮再调用原先被隐藏的具体工具。 - 新装插件或 MCP 后，可依赖
classifyOnChange自动增量；若目录与登记数不一致，用tool_router_status()查看提示，必要时tool_router_refresh('new')或tool_router_refresh('all')。
适用场景与注意¶
适合：本地或 web profile 下工具、技能较多，希望压缩每轮 tool schema，又愿意让模型多一步「先搜再调」的开发者。
需注意 README 中列出的限制：
- 首次分类依赖默认模型；
agentDefaultModel不可用时类别会变粗（关键词兜底）。 - 重启后开放状态不保留，需重新
tool_search。 - 工具被隐藏时无法直接调用，属预期行为。
- 热重载或反复启停可能留下旧的可见性限制，完整重启 DSH 可清空；
tool_router_status会在「目录少于已登记工具」时给出提示。
DSH 生态主张「一切皆插件」；SkillHub 目录页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-tool-compass 用模型生成的任务场景目录加上会话内检索，把「全量 schema 常开」改成「目录常开、工具按需展开」，是面向上下文开销的一条可落地工作流。进一步细节见 GitHub 仓库 与 SkillHub 插件页。
