dsh-tool-discovery

dsh plugin --profile web add dsh-tool-discovery

<div align="center">

<img src="assets/banner.zh.svg" width="1000" alt="DSH Tool Discovery：三个小入口先行，真实 schema 仅按需到场。控制台风格示意图：工具目录中只有 glob 被加载，其余工具保持关闭">

# DSH Tool Discovery

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

中文 | [English](README.en.md)




[快速开始](#快速开始) · [三个入口](#三个入口) · [配置](#配置) · [自行验证](#自行验证) · [设计文档](plugin/docs/README.md)

</div>

---

本文对应 manifest 0.5.1 的主线构建源码。后续修复以 build-<sha> 区分，不代表已包含在 npm 0.5.1 正式版中。现行参数、状态与边界集中在[当前实现契约](plugin/docs/00-current-contract.md)，旧冻结稿与实验记录按其日期阅读。下列功能预览以 native 路径为主；PTC 默认旁路，显式兼容仍有 SDK 冻结缺口。

功能预览

首轮只带必要的东西

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

选中之后，下一轮才出现

tool_load 只记录选择、不执行工具；披露发生在下一轮，模型读到的定义与选择一致。

已披露的不被悄悄改写

同一缓存周期内，已披露的内容与顺序只增不改，宿主侧工具升级不会在会话中途改写模型已读过的定义。只有成功压缩才会重置周期。

冻结承诺目前限于 native。 同名新 schema 与冻结定义冲突时，tool_load 返回

COMPACTION_REQUIRED，须等待用户或 DSH 成功压缩后再加载；相同 schema 的绑定重连或技能换版仍可加载。

原生冷恢复保留本周期曾实际披露的旧定义，但不因此恢复失效权限。可选 PTC 兼容目前仍重渲染当前 SDK，

不保证逐字冻结或稳定追加，也不保证跨重启 SDK 冻结；该缺口尚未修复。

---

为什么需要它

没有它 · 有了它

每个已注册工具的完整 JSON Schema 都在首轮注入，无论任务是否用得上 · 首轮带三个小入口、有界类别摘要，以及默认初始集合的完整 schema（DSH 核心工具与当前 preset 保留的工具）；其它工具的真实原生 schema 在模型显式选定后的下一轮出现

宿主侧工具升级可以在会话中途悄悄改写模型已经读过的定义 · 一个缓存周期内已披露的 wire 只增不改——首披露时记录的定义就是它一直被发送的定义

哪个类别里有什么工具，全靠猜 · tool_search 给 Top-K 候选卡（短用途 + ref/revision），tool_list 给分页的完整名称；两者都不改变激活集合

「现在到底激活了哪些工具」没有答案 · tool_load 回执是版本化的 canonical 记录；view: "state" 投影列出 selected / advertised / invalidated

三个入口

这是一个 DSH 插件。首轮请求里模型看到下面三个固定入口，外加每个能力类别的一段简短摘要，

以及默认初始集合：DSH 自带的核心工具（手动基线）与当前 agent 自己 preset 登记的工具

（默认保留）。其它普通工具首轮不披露。

入口 · 回答的问题 · 改变激活集合？

tool_list · 这个类别里有哪些可发现的工具？ · 否

tool_search · 哪个工具适合当前任务？ · 否

tool_load · 我要用这些工具。 · 是

tool_load 不会执行目标工具，它只记录选择，披露发生在下一轮。初始/框架保留等例外之外，未按需加载的工具会被拒绝；卸载根本

不是模型的动作——action: "unload" 会被拒绝，因此两次成功压缩之间已披露集合只增不减。

两条不变量框住整个设计

• 健康 native 缓存周期内，已披露内容与顺序只增不改。 加载不会移动或改写已披露条目：首次披露时记录的

wire 会被持续原样发送，因此宿主侧工具升级不会静默改写模型已经读过的定义。

• 只有成功压缩才会重置周期。 手动 /compact 与 DSH 自动压缩都算；失败、取消或没有摘要的压缩

不算。

冻结 wire 不等于执行权限。已披露的工具每次调用仍要经过宿主自身的审批、沙箱与授权检查，与它从未

被本插件中介过完全一样。

渐进式披露解决的是上下文，不是速度：只携带模型大概率会用到的内容，就不必携带宿主本可以提供的

全部内容。内核自身不持有任何工具，也从不绕过宿主。

快速开始

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

1. 安装并启用 bundle，按部署方式重载或重启（只刷新页面不保证 Host 升级）。

2. 打开 设置 → 工具发现——插件自己的主页：可选功能开关、应用全局工具目录（按名称筛选、

勾选、恢复 DSH 默认），以及高级的预算 / 语言字段。

3. 回到会话，三个入口即已生效。其余一切不变：每次工具调用仍走 DSH 自身的审批、沙箱与权限链。

<build-tag> 是提交级 Release 标签，例如 build-80216ba3effa。完整的安装 / 更新规则（Node 项目的

npm 包、标签钉住、CLI 与 Core 版本的区别）见[安装与更新](#安装与更新)；配置项见[配置](#配置)。

---

技术文档

环境要求

• DSH Core >=0.2.1-alpha.1——这是所有 @deepseek-ai/dsh 与 @deepseek-ai/dsh-* peer 的

安装准入范围。宿主升到更新的发行版时仍允许安装，不会因版本钉死而被直接拒绝。这不是兼容声明：

dshReleases 仍只把 0.2.1-alpha.1 与 0.2.1-alpha.2 标为 compatible，其它版本仍未测试，

契约变化时仍可能在运行时失败。逐版本矩阵与一次性 Profile 记录见

[上架与兼容声明](plugin/docs/10-store-compatibility.md)。

• 原生 @deepseek-ai/schemastery peer 是配置面与设置页的前提。缺少它时发现内核仍正常运行，

但没有 Config，插件会记录 ConfigUnavailable，而不是假装存在一个设置页。

• native 是完整披露路径。非 native 会话不在插件激活期被一律拒绝：PTC 默认旁路，开启 ptcCompatibility 后进入下一轮 run_code SDK；不保证 native 式冻结，不把展示模式静默改成另一种。
• 每会话单个活动 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 服务落盘：每个会话一条记录，内容是 epoch 身份加该会话允许常驻的工具名名单，不含文件内容、消息正文或凭据。

会话数据 · 通过公开的 ctx.sessionQuery 只读回放本会话事件（一次折叠 + 增量），用于恢复会话已 load 过的集合。

网络 · 无。插件不发起任何出站请求。

命令 · 无。不使用子进程、shell 或动态代码求值。

凭据 · 无。不读 process.env、不碰钥匙串或账号状态、不保存任何密钥。

日志 · 仅诊断信息（会话 id、状态、原因）。工具参数、文件内容与消息正文永不入日志。

运行时依赖：zod。 宿主存储 API（@deepseek-ai/dsh-storage-domain）接收 zod schema，因此可选的可信周期功能把 zod 声明为真实依赖。解析不到时插件不伪造内存存储：会话落入终态 STORAGE_UNAVAILABLE 并停止发请求。其余功能——三入口、目录、投影、门禁——不依赖它。

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

承诺范围。 本插件面向单用户、单 profile（即它被挂载的那一份安装）构建与验证。它不承诺

在共享、多用户、远程或多租户部署中充当边界：会话历史与可信周期存储是受信任的输入，能写它们的人

就能影响某个会话可以执行什么。请把它当作单个 profile 内的披露门禁，而不是用户之间的墙。若你确实

需要那堵墙，请把它放在宿主侧（分账号、沙箱、文件系统权限），而不是这里。

安装与更新

DSH profile 安装仍可使用 GitHub Release 构建资产：main 绿跑会把仓库打包，在提交级

build-<sha> Release 上发布 dsh-tool-discovery.tgz（若已有更新的 main 提交，旧一次运行会直接跳过，

不会把旧提交重新发布成最新资产）。该资产是构建产物，不是验收声明；某个版本覆盖什么、明确

不宣称什么，见[当前状态](plugin/docs/05-current-status.md)。

本包自 0.2.1 起已发布到 npm。之后推送与 package.json 版本匹配的稳定 v<version> 标签，通过便携测试和

仓库检查后，npm 发布任务会自动运行。GitHub Actions 通过 OIDC 向 npm 验证身份，npm 同时生成 provenance；

GitHub 不保存 npm 写入令牌。发布步骤见[发布到 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

…(truncated)