工具按需加载 lvy-jsd/dsh-tool-ultra

Tool Ultra
为 DeepSeek Harness 按需加载工具 —— 所有工具组织成目录，只有 Agent 主动加载的才进入上下文。

English · 中文

它是什么

为 DeepSeek Harness 按需加载工具：所有工具都组织成一个目录（分类 → 分组 → 工具），只有 Agent 主动加载的部分才会进入模型上下文。整体是一个小的核心加若干可替换的扩展插件。

已改名。 本项目原名 dsh-tool-manager。从 0.5.0 起，所有包从 @lvy-jsd/dsh-tool-manager-<名字> 改名为 @lvy-jsd/dsh-tool-ultra-<名字>（核心是 @lvy-jsd/dsh-tool-ultra-core）。其他都不变：入口工具、 toolCatalog 服务（另外也以 toolUltra 的名字提供）、钩子、配置和状态目录 <DSH_HOME>/tool-manager/。
已有的配置可以继续用 @lvy-jsd/dsh-tool-manager：从 0.5.0 起它只是转出新核心。旧版扩展也能和新核心一起用。

快速开始

1. 安装核心包和基于规则的分类器（可选，但推荐）
dsh plugin --profile web add @lvy-jsd/dsh-tool-ultra-core @lvy-jsd/dsh-tool-ultra-classifier-rules

2. 重启 DSH，然后问 Agent："你有哪些工具？"
它会用 tools_ls("/") 回答 —— 是一个目录，不是 200 个工具 schema

3. 想要界面？装上面板，然后打开 设置 →"工具管理"
dsh plugin --profile web add @lvy-jsd/dsh-tool-ultra-panel

请安装带 scope 的 @lvy-jsd/… 包。 npm 上不带 scope 的 dsh-tool-manager 是另一个项目。不要两个同时安装：两者都会收窄 Agent 能看到的工具，装在一起会互相把对方的工具藏起来。

全新安装后，所有分组都归在 uncategorized 下，直到装上分类器 ——工具本身仍然可以浏览和加载，只是缺了分类。想自己写分类器见扩展。

包

| 包 | 作用 |
| @lvy-jsd/dsh-tool-ultra-core | 核心：目录、tools_ls / tools_load / tools_unload、按 Agent 的可见白名单、toolCatalog 扩展服务，外加按意图的检索与路由（tools_find / tools_route / skills_find / skills_route，BM25 + Rust 侧车）。没有扩展时所有分组都在 uncategorized 下。 |
| @lvy-jsd/dsh-tool-ultra-classifier-rules | 按内置规则和你的配置覆盖，把分组放进分类。 |
| @lvy-jsd/dsh-tool-ultra-risk-gate | 通过 DSH 的审批通道确认高危工具的加载，并支持按会话的白名单。 |
| @lvy-jsd/dsh-tool-ultra-persist | DSH 重启后保留已加载的工具，每个会话一个状态文件。 |
| @lvy-jsd/dsh-tool-ultra-panel | 网页面板：浏览目录树、查看每个活动会话已加载的工具和 token 开销，在界面上加载 / 卸载，编辑常驻工具和高危名单，编辑单个工具的元数据，以及豁免某个会话。 |
| @lvy-jsd/dsh-tool-ultra-classifier-llm | 用小模型给分组分类，每个分组一次请求，按分组及其工具描述的哈希缓存结果。 |
| @lvy-jsd/dsh-tool-ultra-capability-bridge | 一次调用加载一组具名工具：tools_load(["cap:android-debug"])。 |
| @lvy-jsd/dsh-tool-ultra-attribution-scan | 按定义这些工具的源码所属的插件包来分组。 |
| @lvy-jsd/dsh-tool-ultra-pack-essentials | 原生工具包，无需 API key：时区与日期计算、带单位的计算器（mathjs）、天气（Open-Meteo）、地点搜索（Nominatim）、维基百科。 |
| @lvy-jsd/dsh-tool-ultra-pack-web | 原生工具包：web_read 把网页正文转成干净的 Markdown（Readability + turndown），web_links 列出页面链接。默认拒绝访问内网地址。 |
| @lvy-jsd/dsh-tool-ultra-pack-mcp | 通过 DSH 的 MCP 客户端启动预设的 MCP 服务器：记忆、顺序思考、Context7、Playwright、文件系统无需 key 就能用；GitHub、SearXNG、Brave、Tavily、Firecrawl、Notion、高德地图在填好 key 后启动。用 mcp_presets 查看状态。 |
| @lvy-jsd/dsh-tool-manager-dsbot-entry | 已弃用，不再发版。在 ds-bot 的设置弹窗里加一行"工具管理"，点开显示面板。 |
| @lvy-jsd/dsh-tool-manager | 旧的核心包名：转出 @lvy-jsd/dsh-tool-ultra-core，让已有配置继续可用。 |
| @lvy-jsd/create-dsh-tool-ultra-plugin | 生成你自己的扩展：npm create @lvy-jsd/dsh-tool-ultra-plugin@latest my-ext -- --type classifier。 |

设计说明见 docs/DESIGN.md。

扩展

核心之外的所有功能都是使用 toolCatalog 服务的普通插件，仓库里的 classifier-rules 就是完全按第三方的写法写的。有四个扩展点：

| 扩展点 | 用途 |
| registerClassifier({ name, priority, group?, categorize? }) | 把工具放进分组、把分组放进分类 |
| annotate(match, { group?, category?, risk?, summary? }) | 运行时元数据；package.json 里的 dsh.toolCatalog 不用写代码也能达到同样效果 |
| registerVisibilityFilter({ name, filter(agent, names) }) | 收窄某个 Agent 能看到的范围 —— 只能移除名字 |
| registerTargetResolver({ name, prefix, resolve }) | 认领一个目标前缀，例如 cap:<name> |
| registerRiskGate / registerStateProvider | 确认高危工具的加载 / 跨重启保留状态 |

钩子就是普通事件：tool-catalog/before-load（抛异常即否决）、 after-load、before-unload、after-unload、before-rebuild、 after-rebuild、state-changed。

从一个生成出来的包开始 —— 它自带一个能跑通的测试：

npm create @lvy-jsd/dsh-tool-ultra-plugin@latest my-ext -- --type classifier
cd my-ext && npm test

examples/ 里有两个完整的例子，完整接口列表在核心包的 README 和 docs/DESIGN.md 第 11 节。

开发

所有包都用 TypeScript 编写（src/），编译到 lib/（JavaScript 加 .d.ts 类型声明）； lib/ 是构建产物，不进 git。根目录 tsconfig.json 列出所有包（项目引用）；两个浏览器端模块（client.ts）有各自的 tsconfig.client.json，因为 DSH 把它们当作经典脚本而不是模块加载。

npm install # 同时把本机 DSH 的宿主包链接进来（scripts/link-host.mjs）
npm run build # src/.ts -> lib/.js + lib/.d.ts
npm run typecheck # 严格类型检查（tsc -b；项目引用需要声明文件，所以也会写 lib/）
node --test test/unit/.test.mjs # 纯 catalog 与注册表测试（需先构建）
node test/e2e.mjs # 启动一次性 DSH 实例；绝不碰你的正式 profile

宿主包（@deepseek-ai/）是 peer 依赖，永远不从 npm 安装（.npmrc 设了 legacy-peer-deps）：插件旁边多一份 npm 的副本，会遮蔽你实际运行的 DSH。
npm install 会改为从 $DSH_APP（默认 ~/.local/share/deepseek-harness/app）链接。

许可

Apache-2.0 —— 见 LICENSE。改名为 Tool Ultra 之前的版本（@lvy-jsd/dsh-tool-manager）是 MIT。