@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