DSH Tool Discovery

四个小入口与初始工具集合在前，其它工具的真实 schema 按需到场。

本文对应 manifest 0.6.0 的工作树源码：本版起只支持 DSH Core 0.2.2-rc.1+，旧投影宿主路径（冻结 wire、缓存周期、可信记录、PTC 开关、描述精简）整体移除。现行参数、状态与边界集中在当前实现契约。

功能预览

首轮只带必要的东西

首轮请求里只有四个固定入口、每类能力的简短摘要，以及默认初始集合的完整 schema。其它普通工具首轮不披露，不占上下文。

选中之后，下一轮才出现

tool_load 准入这些工具、不执行它们；披露与可执行都从下一轮开始，模型读到的定义与目录当前版本一致。

不需要了就收回

tool_unload 把已准入的工具移出下一轮的声明；撤权、换版同样立即不可执行——披露收回，不残留执行权。

为什么需要它

没有它	有了它
每个已注册工具的完整 JSON Schema 都在首轮注入，无论任务是否用得上	首轮带四个小入口、有界类别摘要，以及默认初始集合的完整 schema（DSH 核心工具与当前 preset 保留的工具）；其它工具的真实原生 schema 在模型显式选定后的下一轮出现
用完的工具只能在上下文里赖着不走	`tool_unload` 从下一轮起收回披露与执行资格，腾出声明位
哪个类别里有什么工具，全靠猜	`tool_search` 给 Top-K 候选卡（短用途 + ref/revision），`tool_list` 给分页的完整名称；两者都不改变激活集合
「现在到底激活了哪些工具」没有答案	`tool_load`/`tool_unload` 返回即时回执；`view: "state"` 投影列出 `selected` / `invalidated`

四个入口

这是一个 DSH 插件。首轮请求里模型看到下面四个固定入口，外加每个能力类别的一段简短摘要， 以及默认初始集合：DSH 自带的核心工具（手动基线）与当前 agent 自己 preset 登记的工具（默认保留）。其它普通工具首轮不披露。

入口	回答的问题	改变激活集合？
`tool_list`	这个类别里有哪些可发现的工具？	否
`tool_search`	哪个工具适合当前任务？	否
`tool_load`	我要用这些工具。	是（准入）
`tool_unload`	我不再需要这些工具。	是（撤回）

tool_load/tool_unload 不会执行目标工具；披露与可执行都从下一轮起生效——同一次 toolSet 已定型，load 当步不可调。初始/框架保留等例外之外，未准入的工具执行被拒；准入在 storageDomain 可用时跨重启恢复（按当前目录版本对齐），不可用时按会话存活。

准入是单一事实源

披露与执行读同一个 admission 集合：tool_load 后下一轮同时披露并可调用，tool_unload 后下一轮同时消失且不可调用；没有"看得见却调不动"或"调得动却看不见"的漂移。agent 自己 scope 注册的工具宿主遮不住，可能披露，但默认仍须准入才能执行（gateOwnScopeTools）。

披露不等于执行权限。已披露的工具每次调用仍要经过宿主自身的审批、沙箱与授权检查，与它从未被本插件中介过完全一样。

渐进式披露解决的是上下文，不是速度：只携带模型大概率会用到的内容，就不必携带宿主本可以提供的全部内容。内核自身不持有任何工具，也从不绕过宿主。

快速开始

# CLI Web profile 安装示例；将 web 换成实际目标，先写包名再给完整 URL
dsh plugin --profile web add \
  "dsh-tool-discovery@https://github.com/KouzakiUmi/dsh-tool-discovery/releases/download/<build-tag>/dsh-tool-discovery.tgz"

安装并启用 bundle，按部署方式重载或重启（只刷新页面不保证 Host 升级）。
打开 设置 → 工具发现——插件自己的主页：可选功能开关、应用全局工具目录（按名称筛选、勾选、恢复 DSH 默认），以及高级的预算 / 语言字段。
回到会话，三个入口即已生效。其余一切不变：每次工具调用仍走 DSH 自身的审批、沙箱与权限链。

<build-tag> 是提交级 Release 标签，例如 build-80216ba3effa。完整的安装 / 更新规则（Node 项目的 npm 包、标签钉住、CLI 与 Core 版本的区别）见安装与更新；配置项见配置。

技术文档

环境要求

DSH Core >=0.2.2-rc.1——由 engines.dsh 声明的安装准入范围。dshReleases 把 0.2.2-rc.1 标为 compatible、更旧版为 incompatible；0.2.2 更晚版本未逐一验收，契约变化时仍可能在运行时失败。逐版本矩阵与一次性 Profile 记录见上架与兼容声明。
原生 @deepseek-ai/schemastery peer 是配置面与设置页的前提。缺少它时发现内核仍正常运行，但没有 Config，插件会记录 ConfigUnavailable，而不是假装存在一个设置页。
native 与 PTC 会话走同一套准入：掩码对 run_code 内的 SDK 投影同样生效，无独立兼容开关。
每会话单个活动 agent。单会话内多 agent 并发不受支持——请求无法无歧义地归属。
Node ^22.19.0 || >=24.0.0。

权限与外部依赖

DSH STORE 要求插件在安装前列清它能触及什么。以下是本插件的完整清单——不以「没搜到」代替事实：

面	行为
文件（读）	激活时读当前 profile 的 patch 文件，取宿主自己的 `locale.preference`；没有再回落到 `$DSH_HOME/desktop-locale.json`（该文件以 profile 名为键）。任何失败（文件缺失、JSON 损坏、语言未知）都回落 `en` 并留一行日志。把配置项 `locale` 设为 `zh`/`en` 会钉住语言并完全跳过这两次读取。
文件（写）	不直接写文件系统。持久状态经宿主 `@deepseek-ai/dsh-storage-domain` 服务落盘：每个会话一条记录，内容是本会话已准入的工具名 + 版本摘要，不含文件内容、消息正文或凭据。
会话数据	不读取会话事件；恢复按 admission 记录与当前目录对齐。
网络	无。插件不发起任何出站请求。
命令	无。不使用子进程、shell 或动态代码求值。
凭据	无。不读 `process.env`、不碰钥匙串或账号状态、不保存任何密钥。
日志	仅诊断信息（会话 id、状态、原因）。工具参数、文件内容与消息正文永不入日志。

运行时依赖：zod。 宿主存储 API（@deepseek-ai/dsh-storage-domain）接收 zod schema，因此 admission 持久化把 zod 声明为真实依赖。解析不到或存储服务缺席时准入退化为纯内存（不阻断会话，仅不跨重启保留），不做伪造存储。

宿主 peer。 @deepseek-ai/dsh 与 @deepseek-ai/dsh-tools 必需；@deepseek-ai/dsh-storage-domain（admission 持久化）与 @deepseek-ai/dsh-home-paths（界面语言路径）为可选：缺失时对应功能诚实降级，不做模拟。

承诺范围。 本插件面向单用户、单 profile（即它被挂载的那一份安装）构建与验证。它不承诺在共享、多用户、远程或多租户部署中充当边界：会话准入记录是受信任的输入，能写它们的人就能影响某个会话可以执行什么。请把它当作单个 profile 内的披露门禁，而不是用户之间的墙。若你确实需要那堵墙，请把它放在宿主侧（分账号、沙箱、文件系统权限），而不是这里。

安装与更新

DSH profile 安装仍可使用 GitHub Release 构建资产：main 绿跑会把仓库打包，在提交级 build-<sha> Release 上发布 dsh-tool-discovery.tgz（若已有更新的 main 提交，旧一次运行会直接跳过，不会把旧提交重新发布成最新资产）。该资产是构建产物，不是验收声明；某个版本覆盖什么、明确不宣称什么，见当前状态。

本包自 0.2.1 起已发布到 npm。之后推送与 package.json 版本匹配的稳定 v<version> 标签，通过便携测试和仓库检查后，npm 发布任务会自动运行。GitHub Actions 通过 OIDC 向 npm 验证身份，npm 同时生成 provenance； GitHub 不保存 npm 写入令牌。发布步骤见发布到 npm。

上述与下面的命令是公共 CLI 的 Web profile 示例，web 不是对实际安装目标的推断。 DSH NEXT Desktop 的 profile 由随包 Desktop CLI 管理；全局 npm 的公共 CLI 不能冒充该入口。桌面用户应先核验目标安装提供的 CLI、实际 profile 与 plugin --help，按目标版本要求退出/重开应用；不要复制文档中的内部 bootstrap 路径，也不要在受管 profile 裸跑 npm/pnpm 或手改锁文件。 CLI/桌面壳版本不代替实际 Core 版本。官方参考：CLI 插件管理、Desktop 所有权。公开 master 文档不是每个已安装版本都通过验证的证明。

# 首次安装 —— 先写包名，再给完整 tarball URL
dsh plugin --profile web add \
  "dsh-tool-discovery@https://github.com/KouzakiUmi/dsh-tool-discovery/releases/download/<build-tag>/dsh-tool-discovery.tgz"

# 更新已安装副本 —— 同样是 name@URL 形式
dsh plugin --profile web update \
  "dsh-tool-discovery@https://github.com/KouzakiUmi/dsh-tool-discovery/releases/download/<build-tag>/dsh-tool-discovery.tgz"

<build-tag> 是提交级 Release 标签，例如 build-80216ba3effa。标签里带着提交号，因此新构建不会覆盖旧构建；两次构建也可能共用同一个清单版本——version 由维护者 bump，CI 不改——所以请钉住你测过的那个标签对应的提交，始终显式写出包名，并以 Release 名（v<version> · <sha>）或该 tarball 内的清单为准判断它到底是哪个版本，而不是假设 main 与本文一致。

Node 项目可通过 npm install dsh-tool-discovery 从 npm 安装。本节上面的 DSH profile 安装命令仍由 DSH CLI 从 GitHub Release 资产安装。

配置

插件没有必需配置，所有字段都是插件自身配置命名空间里的扁平根字段——在当前的原生配置面上没有 progressiveDiscovery 外层包装：

{
  // "alwaysVisible": ["read", "grep"],  // 整项省略即保持 DSH 默认名单
  "initialToolsEnabled": true,  // 可关闭手动初始注入，不删除已配置名单
  "alwaysAllowPresetTools": true, // 保留当前实际绑定的 preset 所登记工具
  "gateOwnScopeTools": true,    // agent 自己 scope 注册的工具也要先准入才能执行
  "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（显式框架保留仍可能贡献工具）。四个入口不可删除。设置页全局目录中存在某工具，不意味着它会被授予所有会话。

已废弃的配置键

ptcCompatibility、compactBuiltinToolDescriptions、compactBuiltinToolOverrides、 requireTrustedEpoch、requireTrustedEpochForSubagents、allowMissingSessionQuery 在 0.2.2-rc.1+ 上无效果：对应子系统已随旧投影路径移除。字段保留在配置 schema 中只为不吞掉既有配置；设置页以"已废弃/已移除"标注。

设置页：工具发现主页

在原生 schemastery peer 在场时，插件贡献自己的顶层设置页——设置 → 工具发现（一个 settings.section 贡献，即本插件在 GUI 里的主页）。它按「一眼看懂的主页」组织，而不是一张裸表单：

状态条——与面板所编辑的同一份元数据上的实时计数：常驻入口、目录工具、初始名单大小，以及多少名字未在应用全局目录登记或尚未确认。
四个入口参考卡——tool_list / tool_search / tool_load / tool_unload：各自回答什么、返回什么、哪个会改变激活集合，外加上述准入语义。
可选功能开关与手动初始工具名单——应用全局登记目录。目录读取当前全部注册层，包括无需创建会话就已预加载的 preset；不读取会话资格、发现/加载状态或历史请求头。支持按名称筛选、勾选切换与恢复 DSH 默认，勾选只写根级 alwaysVisible。完整目录中缺少名字时标注为未在应用全局目录登记，不断言调用失败；宿主 SDK 无法提供完整目录时，未列出的名字标注为全局登记状态尚未确认。全局已登记不保证每个会话都具备执行权限。
高级——界面语言、budgets 与 categoryConfig 的 JSON 编辑器，frameworkRetained 只读展示。

每个开关与字段：

自动注入初始工具（initialToolsEnabled，默认 true）：关闭不删除勾选名单，不自动注入这些工具，仍可用 tool_load 加载。开关和名单改动在下一请求对齐，已有按需准入保持到显式卸载。
永远放行 preset 规定的工具（alwaysAllowPresetTools，默认 true）：只读取当前 agent 实际绑定的 preset 修订自身登记、且该 agent 原生目录仍允许的工具。不根据会话 header 中的 preset 名或设置页全局目录授信；其它 preset、后装 agent-only 工具不会被自动放行。与手动注入独立，在下一请求对齐；保留初始集合，不绕过原生权限和执行校验。
对 agent 自身注册的工具同样要求准入（gateOwnScopeTools，默认 true）：注册到 agent 自己 scope 的工具宿主遮不住、可能直接披露；开启时目录内的 own-scope 名字也要 tool_load 准入才能执行，关闭时目录之外的 own-scope 名字放行。
界面语言（locale，默认 auto）：auto 先读当前 profile patch 里宿主自己的 locale.preference，没有再回落到桌面语言文件；任何失败（文件缺失、JSON 损坏、语言不受支持）都回落 en，且回落一定会留日志、不静默。写 zh/en 会钉住模型可见文案的语言，并完全跳过这两次读取。非 volatile 字段：改动在插件重载后生效。
让初始名单成为精确集合（respectAlwaysVisible，默认 false）：关闭且初始注入开启时，当前 scope 真实提供的 DSH 核心工具会被自动并入常驻名单，且不经 load 即可调用——省一次往返。这里只识别插件维护表中的核心名称；上游新增且未入表的名字仍需跟版核验。打开后，你的 alwaysVisible（加 preset 保留项）就是上限：没列出的核心工具必须像别的工具一样先 load。被拒不会死锁——被排除的核心工具不在受保护的基线里，一次普通 tool_load 就能在下一轮把它放行（tolerantLoadProtected 管的是另一件事：已在名单里的工具重复 load 保持幂等）。
工具资格、协议回执与准入门禁始终有效，不提供关闭这些保护的开关。四个发现入口始终保留。

主页还提供容忍重复加载初始工具（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。详见当前契约。

本插件默认不额外增加风险阈值。所有硬上限——工具数量、批次大小、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 永不裁剪；连空列表都放不下时才以 BUDGET_EXCEEDED 明确失败。

即使所有硬上限都关闭，以下仍然有界：默认页大小（defaultListLimit，20）、默认候选数（defaultSearchLimit，5）、分页本身，以及各项 TTL。关闭硬上限不会让输出变得无界，只是表示在这些默认值之上没有额外天花板。

maxListResultBytes / maxSearchResultBytes 按完整成功 JSON 外壳的 UTF-8 字节计量，包含数组、游标、截断标记和 nextAction；空页及零命中也不能越界。连最小成功响应都放不下时返回 BUDGET_EXCEEDED，不裁剪名称、ref 或错误信息。该上限不限制错误外壳本身，也不包含宿主另外添加的消息包装。

initialSchemaTargetTokens 与 maxInitialBytes 是历史目标值，当前代码路径并未强制它们，因此不是"实测保证的初始 2K 预算"。

自行验证

在仓库根目录执行：

npm test                          # 单元测试 —— 以该命令的实际输出为准
npm run test:composition          # 组合门禁（真实 DSH Loader）—— 以实际输出为准
npm run test:all                  # 依次运行以上两者
npm run check                     # 包身份 + 文档一致性检查（只需 Node）

单测大部分只需要 Node。其中两个文件依赖宿主：plugin/tests/unit/client.test.mjs 与 plugin/tests/unit/settings.test.mjs 在模块顶层就通过 plugin/contracts/install-resolver.mjs 从已安装的 DSH 里取 React 与 @deepseek-ai/schemastery。要在装有该 DSH 的机器上跑完整套件；安装不在默认位置时用 DSH_INSTALL_ROOT 指向它。

因此 CI 的便携单测作业只跑除这两个文件以外的全部用例，并明确把这两个文件按宿主依赖跳过并给出原因。该作业是便携子集，不等于完整 npm test 通过。精确排除命令见开发指南。宿主测试解析器需要可正常解析包的安装根，仅存在 ASAR 并不自动满足；历史 DOM 探针也不由便携作业重跑。

用例数会随测试增减而变化，因此这里刻意不写死数字。以这两条命令的实际输出为准；写在本文件里的数字必然过时。npm run clean 是额外的删除操作，不是测试前必跑步骤，执行前请核对范围。

test:composition 会在真实 Loader 上运行 plugin/tests/composition/gate-*.test.mjs 的全部文件：适配器门禁、生命周期、resume、掩码契约、设置、工具增减与准入门禁。新增门禁文件会被 glob 自动纳入，无需改其它地方。

组合测试会针对已安装的 DSH 启动真实 Cordis Loader，因此需要宿主在场。它们从该安装解析包；若安装不在默认位置，请用 DSH_INSTALL_ROOT 指向它。这些命令不安装、不重启，也不会改动你的 DSH profile；但会在被 Git 忽略的 plugin/fixtures/tmp/ 下创建临时会话文件，并在每个测试进程退出时清除。设置 DSH_KEEP_TMP=1 可保留现场用于排查；npm run clean 清除任何残留。

质量工装是公开的，但完整跑完需要冻结的评分数据集，而该数据集未公开，因此在公开检出上无法跑完。该数据集覆盖什么、当前处于什么状态，见当前状态。

获取源码

本分支的源码版本为 0.6.0。npm 是否已发布及其 provenance 应以 registry 为准，GitHub 构建版存在本身不证明 npm 已发布。某次下载究竟带哪个版本，以 tarball 内清单为准，不假设 main、Release 名与本文始终一致。

git clone https://github.com/KouzakiUmi/dsh-tool-discovery
cd dsh-tool-discovery

纯 JavaScript，无构建步骤。清单里声明了一个运行时 dependencies 项 zod（^4.4.3）——admission 记录表要以 zod schema 交给宿主的 storage domain——所需宿主包则声明为 peerDependencies，由 DSH 安装提供。项目不做 vendored 副本，也不存在可以拿来掩盖宿主包缺失的构建步骤。

发布到 npm

以下描述仓库工作流的当前定义，不证明 registry 端授权或本次发布已经成功：

项	当前源码
触发	与 manifest 稳定版本完全匹配的 `v<version>` 标签；预发布标签不走此任务
前置门禁	portable unit 与仓库检查
GitHub environment	`npm`，不是“无 environment”
运行时	Node 24；Trusted Publishing 的 npm 发布客户端最低要求见官方文档（11.5.1+）
发布身份	job 授予 `id-token: write`，使用 OIDC；工作流不读取 `NPM_TOKEN`
发布命令	`npm publish --provenance --access public`

维护者需另行核对 npm 端 Trusted Publisher 的仓库、工作流文件名 ci.yml、environment 和直接发布权限；保存配置本身不验证它能成功发布。源码版本、标签、载荷、provenance 与 registry 实际结果要逐项核对，不能靠历史账号操作或 CI 文件宣称已配置成功。官方依据：npm Trusted Publishers。

GitHub 的 build-<sha> 构建资产是另一条流程，不是 npm 发布；二者都不会证明 Profile 已安装或 GUI 已生效。

架构与其代价

准入制披露把"不在任务里的工具"挡在首轮之外，也能用 tool_unload 主动腾位；已知工具名可以批量加载。这是设计意图——不声称任何实测的上下文或 token 节省，也不应从中读出这类承诺。

另一面是权衡的另一侧：初始名单切得过小会增加模型往返与重新发现的开销。默认采用 DSH 核心工具、同时保留可编辑，是一个有意识的平衡——不是"初始 2K 预算"的承诺。

它还不是什么

源码实现不等于完整产品验收。 npm、GitHub 构建资产、STORE、Profile 安装和在线 GUI 是不同状态，应核对各自实际证据；历史一次性 Profile 操作见兼容记录。
当前 GUI 未验收，不等于历史上从未测过 DOM。 历史记录记载了旧版本的 React/Chromium 受控探针，本轮未复核或重跑；VM 单测、历史 DOM 记录与当前在线页面不是同一层证据，详见当前状态。
不声称实测 token 或延迟收益。 工具披露减少是设计目标，任务往返和总耗时需要单独测量。
检索指标未完成。 类别词误命中已修，不代表 Recall@K、负例误命中率或模型选择率达标；纯类别查询可能需要改用浏览。
0.2.2 只声明 rc.1。 rc.1 解包锚点上的回归通过不等同 0.2.2 全部版本与真实 provider、GUI、安装已验收。

许可证

MIT —— 见 LICENSE。

DSH Tool Discovery

四个小入口与初始工具集合在前，其它工具的真实 schema 按需到场。

中文 | English

快速开始 · 四个入口 · 配置 · 自行验证 · 设计文档

本文对应 manifest 0.6.0 的工作树源码：本版起只支持 DSH Core 0.2.2-rc.1+，旧投影宿主路径（冻结 wire、缓存周期、可信记录、PTC 开关、描述精简）整体移除。现行参数、状态与边界集中在当前实现契约。

功能预览

首轮只带必要的东西

首轮请求里只有四个固定入口、每类能力的简短摘要，以及默认初始集合的完整 schema。其它普通工具首轮不披露，不占上下文。

选中之后，下一轮才出现

tool_load 准入这些工具、不执行它们；披露与可执行都从下一轮开始，模型读到的定义与目录当前版本一致。

不需要了就收回

tool_unload 把已准入的工具移出下一轮的声明；撤权、换版同样立即不可执行——披露收回，不残留执行权。

为什么需要它

没有它	有了它
每个已注册工具的完整 JSON Schema 都在首轮注入，无论任务是否用得上	首轮带四个小入口、有界类别摘要，以及默认初始集合的完整 schema（DSH 核心工具与当前 preset 保留的工具）；其它工具的真实原生 schema 在模型显式选定后的下一轮出现
用完的工具只能在上下文里赖着不走	`tool_unload` 从下一轮起收回披露与执行资格，腾出声明位
哪个类别里有什么工具，全靠猜	`tool_search` 给 Top-K 候选卡（短用途 + ref/revision），`tool_list` 给分页的完整名称；两者都不改变激活集合
「现在到底激活了哪些工具」没有答案	`tool_load`/`tool_unload` 返回即时回执；`view: "state"` 投影列出 `selected` / `invalidated`

四个入口

入口	回答的问题	改变激活集合？
`tool_list`	这个类别里有哪些可发现的工具？	否
`tool_search`	哪个工具适合当前任务？	否
`tool_load`	我要用这些工具。	是（准入）
`tool_unload`	我不再需要这些工具。	是（撤回）

准入是单一事实源

披露不等于执行权限。已披露的工具每次调用仍要经过宿主自身的审批、沙箱与授权检查，与它从未被本插件中介过完全一样。

快速开始

# CLI Web profile 安装示例；将 web 换成实际目标，先写包名再给完整 URL
dsh plugin --profile web add \
  "dsh-tool-discovery@https://github.com/KouzakiUmi/dsh-tool-discovery/releases/download/<build-tag>/dsh-tool-discovery.tgz"

安装并启用 bundle，按部署方式重载或重启（只刷新页面不保证 Host 升级）。
打开 设置 → 工具发现——插件自己的主页：可选功能开关、应用全局工具目录（按名称筛选、勾选、恢复 DSH 默认），以及高级的预算 / 语言字段。
回到会话，三个入口即已生效。其余一切不变：每次工具调用仍走 DSH 自身的审批、沙箱与权限链。

技术文档

环境要求

DSH Core >=0.2.2-rc.1——由 engines.dsh 声明的安装准入范围。dshReleases 把 0.2.2-rc.1 标为 compatible、更旧版为 incompatible；0.2.2 更晚版本未逐一验收，契约变化时仍可能在运行时失败。逐版本矩阵与一次性 Profile 记录见上架与兼容声明。
原生 @deepseek-ai/schemastery peer 是配置面与设置页的前提。缺少它时发现内核仍正常运行，但没有 Config，插件会记录 ConfigUnavailable，而不是假装存在一个设置页。
native 与 PTC 会话走同一套准入：掩码对 run_code 内的 SDK 投影同样生效，无独立兼容开关。
每会话单个活动 agent。单会话内多 agent 并发不受支持——请求无法无歧义地归属。
Node ^22.19.0 || >=24.0.0。

权限与外部依赖

DSH STORE 要求插件在安装前列清它能触及什么。以下是本插件的完整清单——不以「没搜到」代替事实：

面	行为
文件（读）	激活时读当前 profile 的 patch 文件，取宿主自己的 `locale.preference`；没有再回落到 `$DSH_HOME/desktop-locale.json`（该文件以 profile 名为键）。任何失败（文件缺失、JSON 损坏、语言未知）都回落 `en` 并留一行日志。把配置项 `locale` 设为 `zh`/`en` 会钉住语言并完全跳过这两次读取。
文件（写）	不直接写文件系统。持久状态经宿主 `@deepseek-ai/dsh-storage-domain` 服务落盘：每个会话一条记录，内容是本会话已准入的工具名 + 版本摘要，不含文件内容、消息正文或凭据。
会话数据	不读取会话事件；恢复按 admission 记录与当前目录对齐。
网络	无。插件不发起任何出站请求。
命令	无。不使用子进程、shell 或动态代码求值。
凭据	无。不读 `process.env`、不碰钥匙串或账号状态、不保存任何密钥。
日志	仅诊断信息（会话 id、状态、原因）。工具参数、文件内容与消息正文永不入日志。

安装与更新

# 首次安装 —— 先写包名，再给完整 tarball URL
dsh plugin --profile web add \
  "dsh-tool-discovery@https://github.com/KouzakiUmi/dsh-tool-discovery/releases/download/<build-tag>/dsh-tool-discovery.tgz"

# 更新已安装副本 —— 同样是 name@URL 形式
dsh plugin --profile web update \
  "dsh-tool-discovery@https://github.com/KouzakiUmi/dsh-tool-discovery/releases/download/<build-tag>/dsh-tool-discovery.tgz"

Node 项目可通过 npm install dsh-tool-discovery 从 npm 安装。本节上面的 DSH profile 安装命令仍由 DSH CLI 从 GitHub Release 资产安装。

配置

插件没有必需配置，所有字段都是插件自身配置命名空间里的扁平根字段——在当前的原生配置面上没有 progressiveDiscovery 外层包装：

{
  // "alwaysVisible": ["read", "grep"],  // 整项省略即保持 DSH 默认名单
  "initialToolsEnabled": true,  // 可关闭手动初始注入，不删除已配置名单
  "alwaysAllowPresetTools": true, // 保留当前实际绑定的 preset 所登记工具
  "gateOwnScopeTools": true,    // agent 自己 scope 注册的工具也要先准入才能执行
  "frameworkRetained": [],  // 掩码必须保留的可信框架工具名
  "categoryConfig": {},     // 本地化类别卡
  "tolerantLoadProtected": true, // 容忍重复加载已在册的工具（幂等）
  "respectAlwaysVisible": false, // false（默认）：核心工具自动常驻；true：你的名单就是上限
  "budgets": null,          // 见下；null 表示不覆盖
  "locale": "auto"          // "auto" 跟随桌面语言；写 "zh"/"en" 可钉住语言并跳过读文件
}

已废弃的配置键

设置页：工具发现主页

状态条——与面板所编辑的同一份元数据上的实时计数：常驻入口、目录工具、初始名单大小，以及多少名字未在应用全局目录登记或尚未确认。
四个入口参考卡——tool_list / tool_search / tool_load / tool_unload：各自回答什么、返回什么、哪个会改变激活集合，外加上述准入语义。
可选功能开关与手动初始工具名单——应用全局登记目录。目录读取当前全部注册层，包括无需创建会话就已预加载的 preset；不读取会话资格、发现/加载状态或历史请求头。支持按名称筛选、勾选切换与恢复 DSH 默认，勾选只写根级 alwaysVisible。完整目录中缺少名字时标注为未在应用全局目录登记，不断言调用失败；宿主 SDK 无法提供完整目录时，未列出的名字标注为全局登记状态尚未确认。全局已登记不保证每个会话都具备执行权限。
高级——界面语言、budgets 与 categoryConfig 的 JSON 编辑器，frameworkRetained 只读展示。

每个开关与字段：

自动注入初始工具（initialToolsEnabled，默认 true）：关闭不删除勾选名单，不自动注入这些工具，仍可用 tool_load 加载。开关和名单改动在下一请求对齐，已有按需准入保持到显式卸载。
永远放行 preset 规定的工具（alwaysAllowPresetTools，默认 true）：只读取当前 agent 实际绑定的 preset 修订自身登记、且该 agent 原生目录仍允许的工具。不根据会话 header 中的 preset 名或设置页全局目录授信；其它 preset、后装 agent-only 工具不会被自动放行。与手动注入独立，在下一请求对齐；保留初始集合，不绕过原生权限和执行校验。
对 agent 自身注册的工具同样要求准入（gateOwnScopeTools，默认 true）：注册到 agent 自己 scope 的工具宿主遮不住、可能直接披露；开启时目录内的 own-scope 名字也要 tool_load 准入才能执行，关闭时目录之外的 own-scope 名字放行。
界面语言（locale，默认 auto）：auto 先读当前 profile patch 里宿主自己的 locale.preference，没有再回落到桌面语言文件；任何失败（文件缺失、JSON 损坏、语言不受支持）都回落 en，且回落一定会留日志、不静默。写 zh/en 会钉住模型可见文案的语言，并完全跳过这两次读取。非 volatile 字段：改动在插件重载后生效。
让初始名单成为精确集合（respectAlwaysVisible，默认 false）：关闭且初始注入开启时，当前 scope 真实提供的 DSH 核心工具会被自动并入常驻名单，且不经 load 即可调用——省一次往返。这里只识别插件维护表中的核心名称；上游新增且未入表的名字仍需跟版核验。打开后，你的 alwaysVisible（加 preset 保留项）就是上限：没列出的核心工具必须像别的工具一样先 load。被拒不会死锁——被排除的核心工具不在受保护的基线里，一次普通 tool_load 就能在下一轮把它放行（tolerantLoadProtected 管的是另一件事：已在名单里的工具重复 load 保持幂等）。
工具资格、协议回执与准入门禁始终有效，不提供关闭这些保护的开关。四个发现入口始终保留。

预算：硬上限默认关闭

"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
}

打开上限是有代价的权衡，不是免费的安全加成：

它会阻断任务。 超出上限时被拒绝的是新增项。已披露的工具在任何配置下都不会被淘汰来腾位置——不存在"为了塞进去而卸载"这种行为。
它会增加轮次。 模型必须把同一件事拆成更小的多次 load，代价是更多模型往返、更高延迟、更高总成本。
它可能给下一次 load 造成压力，并可能诱使用户提前压缩。 当已披露集合超过上限时，可选的应对包括调高限额、关闭限额，或压缩得更早一些——而过早的压缩需要重建上下文。这些都不是被迫的，限额由设置者完全掌控。
限额不等同于优化。 一个让任务失败或变慢的上限，并没有让任何东西变得更便宜。默认建议保持关闭；只有在有明确理由时（例如部署必须约束 prompt 增长）才设置。

"budgets": {
  "maxActiveTools": 12,          // 同时在册的按需工具数
  "maxActiveSchemaBytes": 49152, // 这些工具冻结 schema 的上限（48 KiB）
  "maxLoadBatch": 4,             // 单次 load 的工具数
  "maxQueryCodePoints": 512,     // 拒绝异常长的检索词
  "maxListResultBytes": 4096     // 约束名称列表**与** state 投影
}

initialSchemaTargetTokens 与 maxInitialBytes 是历史目标值，当前代码路径并未强制它们，因此不是"实测保证的初始 2K 预算"。

自行验证

在仓库根目录执行：

npm test                          # 单元测试 —— 以该命令的实际输出为准
npm run test:composition          # 组合门禁（真实 DSH Loader）—— 以实际输出为准
npm run test:all                  # 依次运行以上两者
npm run check                     # 包身份 + 文档一致性检查（只需 Node）

获取源码

git clone https://github.com/KouzakiUmi/dsh-tool-discovery
cd dsh-tool-discovery

发布到 npm

以下描述仓库工作流的当前定义，不证明 registry 端授权或本次发布已经成功：

项	当前源码
触发	与 manifest 稳定版本完全匹配的 `v<version>` 标签；预发布标签不走此任务
前置门禁	portable unit 与仓库检查
GitHub environment	`npm`，不是“无 environment”
运行时	Node 24；Trusted Publishing 的 npm 发布客户端最低要求见官方文档（11.5.1+）
发布身份	job 授予 `id-token: write`，使用 OIDC；工作流不读取 `NPM_TOKEN`
发布命令	`npm publish --provenance --access public`

GitHub 的 build-<sha> 构建资产是另一条流程，不是 npm 发布；二者都不会证明 Profile 已安装或 GUI 已生效。

架构与其代价

它还不是什么

源码实现不等于完整产品验收。 npm、GitHub 构建资产、STORE、Profile 安装和在线 GUI 是不同状态，应核对各自实际证据；历史一次性 Profile 操作见兼容记录。
当前 GUI 未验收，不等于历史上从未测过 DOM。 历史记录记载了旧版本的 React/Chromium 受控探针，本轮未复核或重跑；VM 单测、历史 DOM 记录与当前在线页面不是同一层证据，详见当前状态。
不声称实测 token 或延迟收益。 工具披露减少是设计目标，任务往返和总耗时需要单独测量。
检索指标未完成。 类别词误命中已修，不代表 Recall@K、负例误命中率或模型选择率达标；纯类别查询可能需要改用浏览。
0.2.2 只声明 rc.1。 rc.1 解包锚点上的回归通过不等同 0.2.2 全部版本与真实 provider、GUI、安装已验收。

许可证

MIT —— 见 LICENSE。

KouzakiUmi/dsh-tool-discovery

DSH Tool Discovery

功能预览

首轮只带必要的东西

选中之后，下一轮才出现

不需要了就收回

为什么需要它

四个入口

准入是单一事实源

快速开始

技术文档

环境要求

权限与外部依赖

安装与更新

配置

已废弃的配置键

设置页：工具发现主页

预算：硬上限默认关闭

自行验证

获取源码

发布到 npm

架构与其代价

它还不是什么

延伸阅读

许可证

Community comments

KouzakiUmi/dsh-tool-discovery

DSH Tool Discovery

功能预览

首轮只带必要的东西

选中之后，下一轮才出现

不需要了就收回

为什么需要它

四个入口

准入是单一事实源

快速开始

技术文档

环境要求

权限与外部依赖

安装与更新

配置

已废弃的配置键

设置页：工具发现主页

预算：硬上限默认关闭

自行验证

获取源码

发布到 npm

架构与其代价

它还不是什么

延伸阅读

许可证

Community comments