KouzakiUmi/dsh-tool-discovery ↗★ 2
dsh-tool-discovery
Progressive tool discovery for DSH: three-entry control protocol with a host-independent domain kernel and a DSH adapter
安裝
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:KouzakiUmi/dsh-tool-discovery說明文件
閱讀完整 README ↗配置
插件没有必需配置,所有字段都是插件自身配置命名空间里的扁平根字段——在当前的原生配置面上
没有 progressiveDiscovery 外层包装:
{
// "alwaysVisible": ["read", "grep"], // 整项省略即保持 DSH 默认名单
"initialToolsEnabled": true, // 可关闭手动初始注入,不删除已配置名单
"alwaysAllowPresetTools": true, // 保留当前实际绑定的 preset 所登记工具
"compactBuiltinToolDescriptions": false, // 描述精简总开关,仅 native;不重载,周期边界采用
"compactBuiltinToolOverrides": {}, // 逐工具布尔开关;原五项沿用,新支持的工具默认关闭
"ptcCompatibility": false, // 默认旁路 PTC;开启后发现进入下一轮 run_code SDK
"requireTrustedEpoch": false, // 高级严格校验,默认不阻断存量会话
"requireTrustedEpochForSubagents": false, // 仅主严格开关也开启时对子代理强制校验
"frameworkRetained": [], // 投影必须保留的可信框架工具名
"categoryConfig": {}, // 本地化类别卡
"tolerantLoadProtected": true, // 容忍重复加载已在册的工具(幂等)
"respectAlwaysVisible": false, // false(默认):核心工具自动常驻;true:你的名单就是上限
"budgets": null, // 见下;null 表示不覆盖
"locale": "auto" // "auto" 跟随桌面语言;写 "zh"/"en" 可钉住语言并跳过读文件
}
alwaysVisible 是替换手动初始名单,而不是追加默认项;省略它即保持 DSH 核心工具默认值。
preset 保留是独立来源:alwaysAllowPresetTools 开启时,当前实际绑定 preset 所登记且原生作用域允许
的工具会与手动名单合并。若只需要三个发现入口,应设 alwaysAllowPresetTools: false,并设
initialToolsEnabled: false,或同时设 alwaysVisible: [] 与 respectAlwaysVisible: true(显式框架保留仍可能贡献工具)。三个入口不可删除。
设置页全局目录中存在某工具,不意味着它会被授予所有会话。
可选:DSH 默认工具提示词精简
compactBuiltinToolDescriptions 总开关默认关闭。当前支持 28 个工具、53 种已核验定义变体,每个工具在设置页都有独立开关。compactBuiltinToolOverrides 是工具名到布尔值的映射:原 bash、pwsh、workflow、read_image、create_goal 五项未配置时延续总开关行为;新增工具默认关闭,例如 { "subagent_fork": true, "pwsh": false } 可启用子代理描述精简并单独关闭 PowerShell 精简。
仅在 native 模式下替换完整原始定义指纹匹配的工具顶层描述,不改参数、参数说明、执行函数、审批或沙箱。未知变体和未核验的第三方覆盖保留原文。
保存此开关不重载插件,在新会话或成功压缩后采用。当前周期继续使用原来披露的文案;冷恢复也不因开关/语言变化重写已有定义。它不精简全局规则或 MCP 提示词,也不改变初始工具名单。适配版本、短版本标记、恢复与验证边界见详细设计。
设置页:工具发现主页
在原生 schemastery peer 在场时,插件贡献自己的顶层设置页——设置 → 工具发现(一个
settings.section 贡献,即本插件在 GUI 里的主页)。它按「一眼看懂的主页」组织,而不是一张裸表单:
- 状态条——与面板所编辑的同一份元数据上的实时计数:常驻入口、目录工具、初始名单大小, 以及多少名字未在应用全局目录登记或尚未确认。
- 三个入口参考卡——
tool_list/tool_search/tool_load:各自回答什么、返回什么、 哪个会改变激活集合,外加上述两条不变量。 - 可选功能开关与手动初始工具名单——应用全局登记目录。目录读取当前全部注册层,包括
无需创建会话就已预加载的 preset;不读取会话资格、发现/加载状态或历史请求头。支持按名称筛选、
勾选切换与恢复 DSH 默认,勾选只写根级
alwaysVisible。完整目录中缺少名字时标注为未在 应用全局目录登记,不断言调用失败;宿主 SDK 无法提供完整目录时,未列出的名字标注为全局登记 状态尚未确认。全局已登记不保证每个会话都具备执行权限。 - 高级——界面语言、
budgets与categoryConfig的 JSON 编辑器,frameworkRetained只读展示。
每个开关与字段:
-
PTC 兼容(
ptcCompatibility,默认false):关闭时保留宿主 PTC SDK,开启后发现入口与选定工具进入下一轮run_codeSDK,下一轮采用。SDK 仍会重新渲染,冻结、稳定追加和跨重启冻结尚未实现;这不是 native 冻结开关。 -
自动注入初始工具(
initialToolsEnabled,默认true):关闭不删除勾选名单,不自动注入这些工具,仍可用tool_load加载。开关和名单改动在新会话或成功压缩后采用,当前周期不改变。 -
永远放行 preset 规定的工具(
alwaysAllowPresetTools,默认true):只读取当前 agent 实际绑定的 preset 修订自身登记、且该 agent 原生目录仍允许的工具。不根据会话 header 中的 preset 名或设置页全局目录授信;其它 preset、后装 agent-only 工具不会被自动放行。与手动注入独立,在新会话或成功压缩后采用;保留初始集合,不绕过原生权限和执行校验。 -
强制可信周期校验(
requireTrustedEpoch,默认false):默认不读写可信周期存储、不因缺少记录或 storageDomain 阻断会话;常驻工具来自当前配置快照,历史出站头不授予资格。开启会重新加载插件,要求持久化周期记录;存量会话缺记录时需要成功执行用户/compact,存储故障也会阻断。关闭后可恢复没有记录的会话,但不提供严格模式的跨重启名单冻结保证。 -
对子代理强制可信周期校验(
requireTrustedEpochForSubagents,默认false):只有主严格开关也开启时才生效。默认情况下,宿主运行时拥有的子代理使用配置基线,不读写 epoch 记录,不因缺记录要求/compact,包括已有历史的子会话恢复。身份依据实时父子所有权,不信 header/meta 自称或单纯的持久 fork 血缘;作为顶层恢复的 fork 会话仍受主严格开关约束。该普通设置会重载插件,关闭后可恢复旧子会话,无需伪造压缩。显式开启可能阻断旧子会话;子代理不能代替用户执行/compact。 -
界面语言(
locale,默认auto):auto先读当前 profile patch 里宿主自己的locale.preference,没有再回落到桌面语言文件;任何失败(文件缺失、JSON 损坏、语言不受支持)都回落en,且回落一定会留日志、不静默。写zh/en会钉住模型可见文案的语言,并完全跳过这两次读取。非 volatile 字段:改动在插件重载后生效。 -
让初始名单成为精确集合(
respectAlwaysVisible,默认false):关闭且初始注入开启时,当前 scope 真实提供的 DSH 核心工具会被自动并入常驻名单,且不经 load 即可调用——省一次往返。这里只识别插件维护表中的核心名称;上游新增且未入表的名字仍需跟版核验。打开后,你的alwaysVisible(加 preset 保留项)就是上限:没列出的核心工具必须像别的工具一样先 load。被拒不会死锁——被排除的核心工具不在受保护的基线里,一次普通tool_load就能在下一轮把它放行(tolerantLoadProtected管的是另一件事:已在名单里的工具重复 load 保持幂等)。两点注意:已经在严格模式下跑的会话,仍会按它落盘的记录继续放行到下一次用户/compact;本字段非 volatile,改动在插件重载后生效。 -
工具资格、协议回执、历史损坏校验和执行门禁始终有效,不提供关闭这些保护的开关。三个发现入口始终保留。
主页还提供容忍重复加载初始工具(tolerantLoadProtected)、精确初始名单(respectAlwaysVisible)开关;高级配置中可选择语言,并编辑 budgets 与 categoryConfig JSON。JSON 编辑器显示支持的键,在保存前拒绝语法错误、未知键、非法限额和不完整的类别文案;较小预算可能增加往返或阻断任务。frameworkRetained 仅只读展示,不可由此页面修改。
省略 alwaysVisible 时展示宿主 schema 的实际默认名单。加载中、只读或保存进行中禁用所有修改控件,防止并发写覆盖;元数据缺失时不可恢复默认,名单已经默认时不重复写。保存失败会显示错误,不宣称生效。非 volatile 字段保存会重载插件,页面提供提示。该主页即原生配置面;不承诺旧包装配置或旧版设置 UI 的兼容性。独立浏览器 DOM 探针使用真实渲染器及受控保存通道,不代表在线配置持久化或当前 GUI 已部署新代码。
预算:硬上限默认关闭
省略 limit 时默认 20/5 会被显式 maxListLimit/maxSearchLimit 收窄;显式超限仍拒绝。list 四个 view 与 search 的字节限额覆盖完整成功 JSON 外壳,空页也计量;错误与宿主额外包装不受该成功上限保证。state 只可带标记裁 invalidated,不裁 selected/advertised。详见当前契约的预算说明。
本插件默认不额外增加风险阈值。所有硬上限——工具数量、批次大小、schema 字节、页大小、
结果字节、查询长度、技能字节——默认都是 null,即关闭。给它一个正整数即启用该项上限;
填回 null 即关闭。这里用 null 而不是 Infinity,因为 Infinity 无法在 JSON 中存在。
"budgets": {
"maxActiveTools": null, // 例如 12:限制同时加载的工具数
"maxActiveSchemaBytes": null, // 例如 49152:限制冻结的 schema 字节
"maxLoadBatch": null, // 例如 4:限制单次 load 的工具数
"maxListLimit": null, // 例如 20:限制页大小
"maxSearchLimit": null,
"maxListResultBytes": null,
"maxSearchResultBytes": null,
"maxQueryCodePoints": null,
"maxSkillBytesPerLoad": null
}
maxActiveTools 与 maxActiveSchemaBytes 只统计按需选择项——已加载、已冻结或待披露的。它们
不统计初始 alwaysVisible 基线,那是宿主注入的,不属于本插件的预算面。
打开上限是有代价的权衡,不是免费的安全加成:
- 它会阻断任务。 超出上限时被拒绝的是新增项。已披露的工具在任何配置下都不会被淘汰 来腾位置——不存在"为了塞进去而卸载"这种行为。
- 它会增加轮次。 模型必须把同一件事拆成更小的多次 load,代价是更多模型往返、更高延迟、 更高总成本。
- 它可能给下一次 load 造成压力,并可能诱使用户提前压缩。 当已披露集合超过上限时,可选的应对 包括调高限额、关闭限额,或压缩得更早一些——而过早的压缩需要重建上下文。这些都不是被迫的, 限额由设置者完全掌控。
- 限额不等同于优化。 一个让任务失败或变慢的上限,并没有让任何东西变得更便宜。默认建议保持 关闭;只有在有明确理由时(例如部署必须约束 prompt 增长)才设置。
如果你确实想约束 prompt 增长,可以从这组值起步。 本插件的存在意义就是把工具块压小;而任何 配置下都不会卸载,所以不设上限时,一个积极的模型可以一直 load 到下次压缩。与其依赖模型自律, 不如让插件守住这条线——下面的数值可以先照用,再按实际观察调整:
"budgets": {
"maxActiveTools": 12, // 同时在册的按需工具数
"maxActiveSchemaBytes": 49152, // 这些工具冻结 schema 的上限(48 KiB)
"maxLoadBatch": 4, // 单次 load 的工具数
"maxQueryCodePoints": 512, // 拒绝异常长的检索词
"maxListResultBytes": 4096 // 约束名称列表**与** state 投影
}
前三项是护栏:它们才是这个卖点的执行机制,而既然不会卸载,关掉它们就等于长会话只增不减。
后两项是交互边界:保护宿主免受单次异常调用,不改变日常使用。maxListResultBytes 现在还覆盖
view: "state"——超限时先裁剪诊断性的 invalidated 列表(带显式 invalidatedTruncated 标记),
selected 与 advertised 永不裁剪;连空列表都放不下时才以 BUDGET_EXCEEDED 明确失败。
即使所有硬上限都关闭,以下仍然有界:默认页大小(defaultListLimit,20)、默认候选数
(defaultSearchLimit,5)、分页本身,以及各项 TTL。关闭硬上限不会让输出变得无界,只是表示在
这些默认值之上没有额外天花板。
maxListResultBytes / maxSearchResultBytes 按完整成功 JSON 外壳的 UTF-8 字节计量,包含
数组、游标、截断标记和 nextAction;空页及零命中也不能越界。连最小成功响应都放不下时返回
BUDGET_EXCEEDED,不裁剪名称、ref 或错误信息。该上限不限制错误外壳本身,也不包含宿主另外添加的消息包装。
initialSchemaTargetTokens 与 maxInitialBytes 是历史目标值,当前代码路径并未强制它们,因此
不是"实测保证的初始 2K 预算"。