# dsh-tool-retriever

[English](README.md) | 中文

`dsh-tool-retriever` 是一个早期 Alpha 阶段的 DeepSeek Harness 插件。它会注册真实可调用的 `tool_search`，读取当前 Agent 可见的 Tool Registry，再用归一化名称精确匹配和 Field-aware BM25 对工具 Schema 排序。

## 状态与兼容性

`0.0.1-alpha.0` 是预发布版本，精确面向以下宿主契约：

- DeepSeek Harness 工具包：`0.1.0-rc.6`
- `@deepseek-ai/cordis`：`4.0.1`
- Node.js：`^22.19.0 || >=24.0.0`

这一版只做词法检索，支持工具名称、原始描述和输入 Schema 的同语言匹配。它不使用别名、人工词典、查询翻译、生成式描述、Embedding 或 LLM Query Rewrite。因此，中文 Query 可以命中中文描述的工具，但不承诺命中词面完全无关的英文工具。

这一版也不会限制 Agent 原本可见的工具。所有原生工具仍然可用，`tool_search` 只返回排序后的候选。多语言 Dense 检索和动态 Top-K 激活计划在 `0.1.x` 提供。

## 安装

npm Alpha 发布后，可以安装到 DSH Profile：

```sh
dsh plugin --profile <profile> add dsh-tool-retriever@next
```

包内声明了 Bundle Patch，DSH 会把它加入 Profile 的有序 Bundle 列表。目标 Profile 必须已经提供 DSH `tools` 服务；标准 headless 和 web Profile 都满足这一条件。

安装本地打包产物：

```sh
dsh plugin --profile <profile> add ./dsh-tool-retriever-0.0.1-alpha.0.tgz
```

启动长期运行的应用前，先查看最终生效配置：

```sh
dsh --profile <profile> --dump-config
```

## 模型可见接口

输入保持最小：

```ts
interface ToolSearchInput {
  query: string
}
```

`query` 应该继续使用用户的原始语言描述能力需求，同时保留具体工具名、产品名、标识符和操作名。

返回值是稳定 JSON：

```ts
interface ToolSearchOutput {
  query: string
  catalogSize: number
  results: Array<{
    name: string
    description: string
    rank: number
    score: number
    exact: boolean
    bm25: number
    matchedFields: Array<'name' | 'description' | 'parameterName' | 'parameterDescription'>
  }>
}
```

插件在每次执行时读取 Tool Registry。插件启动后新增或移除的工具，会在下一次搜索中生效；`tool_search` 自身不会进入检索目录。

空字符串或纯空白 Query 会返回工具错误。没有任何词法命中时，调用成功并返回空 `results`。

## 配置

Bundle 默认值如下：

```yaml
topK: 8
bm25K1: 1.2
bm25B: 0.75
fieldWeights:
  name: 4
  description: 2
  parameterName: 1.5
  parameterDescription: 1
```

`topK` 允许 1 到 32 的整数；字段权重可以为 0；`bm25K1` 范围是 `0.01` 到 `10`；`bm25B` 范围是 `0` 到 `1`。

DSH Patch 覆盖一个配置行时，会替换完整的 `config`，不会深度合并嵌套字段。因此覆盖插件配置行时，需要重新写出所有希望保留的值。

## 生命周期与数据边界

插件不启动额外进程，不下载模型，也不使用文件、网络或外部缓存。每次调用只读取 `tools.schemas(agent)` 返回的工具名、原始描述和输入参数 Schema。插件只在自己的 Cordis Fiber 内注册一个工具，并原样返回 Tool Registry 的 disposer；卸载插件后，`tool_search` 会被移除。

## 开发验证

```sh
pnpm install
pnpm run verify:self-contained
pnpm run typecheck
pnpm test
pnpm run build
pnpm run prepare
pnpm pack --dry-run --json
```

贡献、安全报告和第三方说明分别见 [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md) 和 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

## 许可证

[MIT](LICENSE)