README.md 5.1 KB
@deepseek-ai/dsh-tool-lsp
English | 中文
The model-facing lsp tool over ctx.lsp: one read-only tool with four operations for precise code navigation. It owns the model schema, prompt guidance, coordinate conversion, result limits and formatting, and UI presentation; it imports no provider.
Namespace plugin (name / inject / Config / apply, no default export). Injects tools, lsp, and systemPrompt.
The tool
lsp accepts operation (goToDefinition | findReferences | goToImplementation | hover), file_path, line, and character. line and character are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based positions and converts rendered locations back. findReferences includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable stay outside model input.
The tool requires the workspace root from the session header.cwd, with no fallback: absence fails as LSP_WORKSPACE_REQUIRED before querying. Its canonical result is the complete normalized seam union: { kind: "locations", locations, resolvedWorkspaceRoot } or { kind: "hover", hover }; Code Mode can inspect every acquired location and zero-based range directly. Native rendering then projects stable, file-grouped path:line:character entries relativized against the result's resolvedWorkspaceRoot (the provider's canonical root), not the session cwd — so a symlinked cwd still renders in-workspace results as workspace-relative paths; a file: URI becomes a workspace-relative path (inside) or absolute path (outside), and any other URI stays verbatim. Empty locations and null hover are successful no-result responses; malformed provider payloads remain structured errors.
Configuration
| Key | Default | Meaning |
|---|---|---|
maxLocations |
100 |
Largest number of rendered locations before an omission marker. |
maxResultChars |
16000 |
Largest complete rendered result, including truncation metadata. |
timeoutMs |
60000 |
Tool-call timeout budget, enforced by dsh-timeout-policy; covers the complete queued open/query/close lifecycle and is not model-configurable. |
Model Experience
System prompt
What the model sees
One system-prompt section (order 112) positions LSP as a precision aid with the following text:
Verbatim guidance
Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references. Positions are one-based line and character (UTF-16) at the cursor; an off-symbol position may return no results. findReferences always includes the declaration.
Token effect
Fixed guidance cost on every request while the plugin is active.
KV Cache effect
Prefix-stable while the plugin scope and guidance text are unchanged; activation or disposal may invalidate reuse from this section.
Tool schema
What the model sees
The model sees the generated lsp schema.
Token effect
Fixed schema cost on every request while enabled; the timeoutMs budget is never sent to the model.
KV Cache effect
Prefix-stable while the visible tool definition and order are unchanged; registration lifecycle or scoped restrictions may invalidate reuse from the first changed schema token.
Results
What the model sees
File-grouped path:line:character location lines or normalized hover text, capped first by maxLocations and then by maxResultChars; omission and truncation markers are included inside the complete character cap. These caps affect only Native/model presentation, not the canonical value. Empty results use distinct No results. / No hover information. lines.
Token effect
Capped per tool result by maxResultChars, with maxLocations additionally bounding navigation item count.
KV Cache effect
Tool results append after the cached request prefix and do not directly invalidate it.
UI presentation
What the model sees
Nothing. The client renders a generic search card — { card: 'generic', kind: 'search', title, locations: [{ path, line }] } — whose args-derived title carries the operation and one-based cursor; follow-along focuses the queried line while the title preserves the column.
Token effect
Zero direct token effect because rendering is client-side only.
KV Cache effect
None; UI presentation is outside the model request.
Known Limitations and Deferred Work
- UTF-16 cursor coordinates — columns are exact for the protocol but hard for a model to count around non-BMP characters; an off-symbol position may return empty results, so the prompt explains the convention without encouraging broad LSP use (seam Agent Note).
- No cross-server completeness promise — supported servers may return empty or partial results depending on indexing readiness; the tool promises no completeness across languages or servers.