@rayfalling/dsh-tool-visibility：控制 DeepSeek Harness 模型上下文的工具注入

在 DeepSeek Harness（DSH）的智能體開發中，模型上下文的長度通常有限。當項目中包含大量工具時，將所有工具的 schema 注入到模型請求中會消耗額外的 token，甚至導致上下文溢出或請求失敗。@rayfalling/dsh-tool-visibility 插件旨在解決這個問題，它允許開發者靜態控制哪些工具 schema 被注入到模型的上下文中。

插件定位¶

這是一個靜態 DSH 插件，由 rayfalling 維護，歸類於 admin-security 類別。它通過提供設置頁 UI 和模型側管理工具，配合框架原生的 tools.restrict 過濾機制，實現對工具注入的全局控制。

核心功能¶

設置頁 UI：在瀏覽器設置中增加「工具注入控制」入口，支持逐個工具開關、按名稱前綴分組過濾、搜索以及整組批量操作。
管理工具：提供 tool_visibility 管理工具，支持 list、hide、show、reset 等命令。
原生過濾：優先使用 DSH 框架原生的 ctx.tools.restrict({ deny}) 過濾器。
持久化狀態：隱藏的工具列表會被保存到 JSON 文件，重啓後自動恢復。

安裝與掛載¶

安裝插件：

dsh plugin add @rayfalling/dsh-tool-visibility

在 agent preset 的配置文件（如 <preset>/agent.cordis.yml）中掛載：

- id: tool-visibility
  name: '@rayfalling/dsh-tool-visibility'

工作原理¶

插件在每步模型調用前，通過 systemPrompt.assemble() 收集工具 schema。它按優先級使用兩種機制來決定是否注入：

ctx.tools.restrict({ deny})（首選）：作爲 agent preset 掛載時生效。被限制的工具 schema 不會注入上下文，且調用時會返回 UNKNOWN_TOOL 錯誤。
system-prompt/assemble 兜底：僅在 restrict 不可用時啓用。它從組裝結果中剔除隱藏的 schema，僅影響模型所見，不阻止工具執行。

注意：tool_visibility 管理工具本身無法被隱藏。

持久化配置¶

默認情況下，隱藏工具的狀態保存在 $DSH_HOME/tool-visibility.json（通常爲 ~/.dsh/tool-visibility.json）。每次執行 hide/show/reset 操作後，狀態會寫入磁盤。

狀態文件格式如下：

{
  "hidden": ["import_claude", "store_search"],
  "descriptions": {
    "import_claude": "..."
  }
}

也可以自定義狀態文件路徑：

- id: tool-visibility
  name: '@rayfalling/dsh-tool-visibility'
  config:
    stateFile: 'F:/my/state.json'

注意事項¶

版本要求：本插件需要 DSH 版本 >= 0.1.5-rc.1（基於 cordis 4.0.2）以保證 Connection RPC 兼容性。
適用場景：適合純工具類插件，用於從每步模型請求中剔除不必要的工具 schema，節省上下文空間。

總結¶

該插件通過設置頁和命令行工具，結合框架原生的 tools.restrict 過濾機制，爲 DSH 提供了精細化的工具注入控制能力。安裝後，開發者可以輕鬆管理工具的可見性，優化模型上下文使用。

倉庫：https://github.com/rayfalling/dsh-tool-visibility