前言¶
在 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 插件頁。
