dsh-tool-retriever
English | 中文
dsh-tool-retriever is an early-alpha DeepSeek Harness plugin that registers a real tool_search tool. Its default path combines canonical-name Exact matching, field-aware BM25F, and DSH LLM query expansion for large catalogs. A pinned local multilingual E5 lane remains available only as an explicitly enabled experiment.
Status and compatibility
The current development version is 0.1.0-alpha.1 and targets:
- DeepSeek Harness packages:
0.1.0-rc.6
@deepseek-ai/cordis: 4.0.1- Node.js:
^22.19.0 || >=24.0.0
The npm next tag remains on published 0.0.1-alpha.0. This development version has not been pushed, tagged, or published.
The plugin reads the calling Agent's live Tool Registry and excludes only tool_search. It does not install restrictions or hide native tools. Dynamic Top-K activation remains postponed until DSH exposes the required safe lifecycle boundaries.
Default retrieval path
original query ──→ Exact + BM25F ───────────────┐
└─ catalog size >= 32 │
└─ DSH LLM rewrite → BM25F ──────────┼─→ Weighted RRF → Top-K
└─ experimental Dense enabled → E5 ─────┘
The original query is always searched. A validated LLM rewrite expands BM25F evidence; it never replaces the original query and never contributes to the Exact lane. Exact canonical-name hits skip the auxiliary LLM call.
Query expansion uses DSH's registered llm service. It does not configure credentials, endpoints, or a provider SDK. An explicit rewrite.provider/rewrite.model pair wins; otherwise the plugin reuses the calling Agent's provider/model. If no route or LLM service is available, or the model call/output fails, the result reports the failure and retains the original Exact/BM25F query. An explicitly enabled Dense lane remains independent and still runs.
Install
dsh plugin --profile <profile> add dsh-tool-retriever@next
For the unreleased development artifact:
pnpm pack
dsh plugin --profile <profile> add ./dsh-tool-retriever-0.1.0-alpha.1.tgz
The profile must provide tools. The llm service is optional at plugin load and is consulted only when Rewrite is attempted. Credentials remain owned by the selected DSH provider.
Model-facing contract
interface ToolSearchInput {
query: string
}
interface ToolSearchOutput {
query: string
catalogSize: number
catalogRevision: string
rewrite: {
status: 'skipped' | 'applied' | 'failed'
reason: 'disabled' | 'catalog-below-threshold' | 'exact-match' | 'applied'
| 'llm-unavailable' | 'route-unavailable' | 'llm-error' | 'invalid-response'
query: string // empty unless status is applied
}
results: Array<{
name: string
description: string
rank: number
score: number
rrf: number
exact: number
bm25: number
dense: number // 0 while Dense is disabled
matchedFields: Array<'name' | 'description' | 'parameterName' | 'parameterDescription'>
}>
}
Every call rereads tools.schemas(agent) and computes a stable SHA-256 revision from locale-independent, code-unit-sorted names, original descriptions, and canonical input schemas. Empty queries are Tool Errors. When no Dense vector is active for a search, no Exact/BM25F evidence returns an empty result list.
Configuration
topK: 8
bm25K1: 1.2
bm25B: 0.75
fieldWeights:
name: 4
description: 2
parameterName: 1.5
parameterDescription: 1
rewrite:
enabled: true
minCatalogSize: 32
provider: ''
model: ''
maxTokens: 128
dense: false
fusion:
rankConstant: 60
weights:
exact: 3
bm25: 1
dense: 1
rewrite.provider and rewrite.model must be configured together. Empty values reuse the calling Agent route. Rewrite output is strict JSON, bounded after trimming to one non-empty query of at most 512 characters, and no tools are supplied to the auxiliary model call.
DSH patch layers replace a row's complete config; restate every setting that must be retained.
Experimental Dense lane
Dense is off by default. While disabled, the plugin does not construct an embedding provider, build vector indexes, load Transformers.js, contact Hugging Face, or retain model memory. Once explicitly enabled, Dense is attempted for every non-empty catalog independently of the Rewrite outcome.
To experiment with the current local E5 provider, install the optional peer @huggingface/transformers@4.2.0 and replace dense: false with:
dense:
offline: false
cacheDir: ''
batchSize: 16
maxCachedCatalogs: 8
This provider still loads Xenova/multilingual-e5-small q8 inside the plugin fiber. It is not the intended long-term architecture for DSH. Production Dense retrieval should wait for a DSH-owned embedding service seam and an isolated shared provider rather than loading one local model per applicable fiber.
Failure and lifecycle behavior
- Rewrite failure is visible in
rewrite.status/reason and retains the original Exact/BM25F query; an explicitly enabled Dense lane still runs.
- Explicit Dense failure remains a Tool Error; Dense never silently pretends to be available.
- Native tools remain visible and executable after either failure.
- Plugin disposal unregisters
tool_search, aborts and settles owned Rewrite/index work, and disposes an enabled Dense provider.
Development and evaluation
pnpm install --frozen-lockfile
pnpm run verify:self-contained
pnpm run typecheck
pnpm test
pnpm run build
pnpm run prepare
pnpm pack --dry-run --json
Normal tests use a deterministic fake DSH LLM and do not require credentials. The existing real-E5 checks are explicitly experimental:
pnpm run test:e5
pnpm run eval:verify
pnpm run eval:dense
pnpm run eval:rewrite:prepare
pnpm run eval:rewrite:score
The sealed corpus has 56 tools and 168 queries across 9 domains. The Rewrite comparison is pinned to deepseek-official / deepseek-v4-flash and prompt version query-rewrite-v1. Requests must run through DSH's registered llm route; the plugin and evaluator do not read provider credentials directly. The scorer compares raw BM25 with the actual Rewrite path and rejects incomplete or differently routed artifacts.
The first frozen run reached 71.43% cross-language Recall@5 and failed the 80% release gate because 51 of 112 Rewrite calls produced invalid structured output. 0.1.0-alpha.1 is therefore not release-ready. See evaluation/README.md and evaluation/RESULTS.md.
See DESIGN.zh-CN.md, CONTRIBUTING.md, SECURITY.md, and THIRD_PARTY_NOTICES.md.
License
MIT
