Skip to content

dsh-tool-gate

Verified

@mzzsfy/dsh-tool-gate · v0.2.2 · MIT · Web UI

工具白名单延迟加载(全局层与全部 per-agent scope 层):白名单内工具全量注入,白名单外统一打 deferLoading 交给宿主 deferred tool loading 链(API 服务端按需搜索激活);声明式收敛,行退场按 undo journal 还原原状

Install

dsh plugin add @mzzsfy/dsh-tool-gate

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Creators

Readme

dsh-tool-gate

工具白名单延迟加载(全局层与全部 per-agent scope 层)。白名单内工具全量注入模型上下文;白名单外统一打 deferLoading 标,交给宿主 deferred tool loading 原生链路(API defer_loading, 服务端按需搜索激活),解决插件注入大量工具污染上下文的问题。

机制

  • 声明式收敛:白名单是全系统工具 defer 态的唯一事实源——白名单内清标 (覆盖插件作者自带声明),白名单外打标;每次收敛只动与目标态有差异的名。 打标落在 definition:0.2.2 起层条目为 registration 包装 ({ definition, when },投影读 registration.definition);更早代际条目是 裸 definition(投影读 definition.deferLoading)。读取先解包,写入目标恒为 definition,两形态同一条收敛路径。
  • 原生链路零干预:支持 defer_loading 的路由(DeepSeek Messages 端)上, 搜索、激活、会话投影(tool-addition/tool-removal)全部由宿主承担。
  • 降级折叠:第三方路由(无 defer_loading 能力,宿主剥标全量注入)在官方 llm-pi-ai adapter 的请求缝上把 deferred 工具折叠为占位(name 保留 + 占位引导 description + 参数骨架——键名/类型/required,深剥 description, 白名单工具原样;provider 按请求 tools 集合校验 tool call 名与参数 schema, 占位保住生成端名字与参数可见性:剔除会让调用意图被收敛到语义最近的白 名单工具,空 schema 会让模型发空参数,均真机实证);模型经 tool_search 检索完整定义后以正确名字与参数调用(宿主按名执行 registry 完整定义)。 capable 路由(请求带 defer 标)与 deepseek 原生 adapter 一律透传。
  • 会话隔离检索:tool_search 只搜索调用方本步可见工具,继承、限制、同名 覆盖与条件注册(when)准入由宿主解析:0.2.2+ 模型步内用宿主 toolSet 的 准入面(tools.definitions(scope, toolSet));更早代际无 toolSet,退回注册 视图(view(scope).visible)。程序化调用(无 toolSet)同一读取面返回注册 视图;无 agent 的调用只搜索全局层。搜索只返回定义文本,不注册工具、不修改 白名单或任何会话的加载态。
  • 原状还原:收敛改动以 undo journal 按 definition 记录原状,行禁用/卸载 按 journal 逐条还原,系统回到「没装本包」的世界(层表换代后同 definition 重建仍可还原)。
  • 干净禁用:层条目为未知形态(既非 registration 包装也无 name)或 tools 缺 register/可见面时打日志零动作,不崩;llm 面失败只损失折叠, 打标收敛不受影响。

使用(设置 → 工具门)

GUI 卡片是唯一配置入口(原生 schemastery 节已抑制):

  • 启用工具门开关:关 = 全部工具恢复注册原状(全量注入),白名单保留
  • 降级折叠开关:关 = 请求缝全量透传(打标维持),行为回到只打标
  • 工具清单:全部层聚合的工具名列表,每行开关 = 是否进白名单;点击行展开 完整描述、参数(名/类型/必填/说明)与层明细,悬停行头直接以 tooltip 显示 描述;行尾显示注入状态与层数(tool_search 为折叠入口,常驻在列,开关禁点)
  • 白名单含未注册名时卡片顶部警示

HTTP 面(/api/tool-gate/*,GUI 数据通道):GET /state、 POST /allowlist、POST /enabled、POST /collapse。

配置(行条目,经 GUI 写)

字段 默认 说明
allowlist 官方核心工具集 + 平台终端工具 全量注入白名单,精确工具名;插件注入的工具不默认启用(Windows 的 shell 例外)
enabled true false = 还原全部原状并停止打标(临时停用,不动行)
collapse true 降级折叠总开关(第三方路由请求改写)

出厂白名单跨平台只差终端工具:Windows 为 shell-select 的 shell + 官方 pwsh 兜底(shell-select 在场时其请求缝隐藏 pwsh),POSIX 为官方 bash (shell-select 在 POSIX 全部行停用)。其余第三方插件注入的工具(检索、浏览器 cdp 等)一律不在默认内,出厂即延迟加载,由用户在卡片中按需勾选。

volatile 字段热改即时收敛(loader/volatile-update),不重启;新工具注册/ 重注册由 tools/change 驱动重收敛。

局限

  • 原生 defer 收益(DeepSeek 端服务端搜索)不变;第三方路由折叠由本地 tool_search 承载,模型检索定义多一轮交互属机制内成本。
  • 降级折叠只 patch 官方 llm-pi-ai 行 adapter;未来出现其他无 defer 能力的 官方 adapter 需扩 sweep 名单(settingsNs 过滤单点收敛)。
  • 彻底屏蔽某工具(不可搜索不可调用)走宿主 market 禁插件行,不在本包范围。

设计全文见 白名单延迟加载-BDD.md,兼容性见 兼容性测试.md。

dsh 版本兼容

按仓库动态窗口验证(scripts/compat/window.mjs),不预置任何固定版本槽:主测 = 渠道 dist-tag 最新 rc,完全适配口径;基线 = npm latest,不崩溃底线口径;主测与基线同版时收敛单槽。本包声明 dsh.hostMin = "0.2.0-rc.1":支持的两种层条目形态 已在 0.2.1-rc.3(裸 definition)与 0.2.2-rc.1(registration 包装)实机对账, 两代际同一收敛/检索/还原链路。低于 hostMin 的宿主由 compat 装载层排除 (不装载);被强制加载(旧 profile 手工挂载,或宿主版本不可读时 dev-link 跳过校验)时按形态探测:裸 definition 正常生效,未知形态干净禁用(打日志、 零动作、不崩)。逐轮实测结论见 docs/兼容性测试/逐包测试进度.md(本地维护,不入库)与本包 兼容性测试.md。