README.md 9.3 KB
description: "The model-facing lsp tool: four read-only code-navigation operations with one-based UTF-16 cursor coordinates, bounded results, and hover text, for users and maintainers composing model code navigation."
kind: "package-reference"
@deepseek-ai/dsh-tool-lsp
English | 中文
Summary
dsh-tool-lsp lets a model navigate code through one read-only lsp tool: open a symbol's definition, find references and implementations, or read hover documentation. Requests use one-based UTF-16 line and character positions. Navigation results are bounded, grouped by file, and labeled when locations are omitted or text is truncated; hover results are normalized and distinguish missing information from errors. The package requires a configured LSP provider and a session workspace root. Choose it when textual search is ambiguous or a change needs precise symbol relationships; ordinary navigation should continue to use search and read.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
An agent uses lsp when textual matches are ambiguous or before a change that needs precise definitions, implementations, or references; the tool's prompt guidance tells it to prefer search/read for ordinary navigation.
The tool
lsp takes operation (goToDefinition, findReferences, goToImplementation, or hover), file_path, line, and character. line and character are positive one-based UTF-16 cursor coordinates; an off-symbol position may return no results. findReferences always includes the declaration, so impact analysis never misses the defining site. Provider choice, language id, workspace root, limits, timeout, and executable stay outside model input.
What the model gets back
Navigation returns path:line:character locations grouped by file (one-based); hover returns normalized text or a no-hover notice. Empty locations and no hover are successful no-result responses. Results are capped first by maxLocations and then by maxResultChars, with omission and truncation markers inside the complete cap; the caps affect only presentation, not the canonical result value.
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-tool-call-timeout-policy; covers the complete queued open/query/close lifecycle and is not model-configurable |
The generated configuration catalog is the exhaustive source for every accepted field.
Failures and recovery
The tool requires a session workspace root (header.cwd) with no fallback; absence fails with LSP_WORKSPACE_REQUIRED before any query. When no provider handles the file's extension, the query fails with LSP_UNAVAILABLE; malformed provider payloads remain structured LSP_MALFORMED_RESPONSE errors. These surface to the model as error tool results it can read and route on.
Understand the implementation
Implementation internals — click to expand
This section explains the design decisions behind the tool and where the code realizes them; observable behavior is covered in [Use this package](#use-this-package). ### Design notes - **Consumer-only.** The tool runtime-injects only `tools`, `lsp`, and `systemPrompt`, imports no provider, and passes only `exec.signal` to the seam. - **Coordinate conversion.** `parseLspArgs` validates that `line` and `character` are positive integers and converts them to the seam's zero-based positions; rendered locations convert back to one-based form. - **Canonical result passthrough.** The tool returns the seam's closed union (`{ kind: 'locations', locations, resolvedWorkspaceUri }` or `{ kind: 'hover', hover }`) so native renderers can inspect every acquired location and zero-based range directly. - **Execution-world URI rendering.** `renderUri` resolves a `file:` URI against the provider's canonical workspace URI — workspace-relative inside it, URI-derived absolute outside it, verbatim when malformed or not `file:` — never applying host-platform path rules to the session cwd. - **Caps after rendering.** `maxLocations` bounds the item count first, then `maxResultChars` bounds the complete rendered text including its omission or truncation marker. - **Generic search-card presentation.** `presentLspCall` renders a `{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }` view; the args-derived title carries the operation and one-based cursor, and follow-along focuses the queried line while the title preserves the column. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: config schema, tool registration, system-prompt section, execution | | [`src/render.ts`](src/render.ts) | Pure formatting, coordinate conversion, URI resolution, result caps, UI presentation | | [`src/session-cwd.ts`](src/session-cwd.ts) | Workspace root from the session `header.cwd` | | — | No runtime invariant companion is published; this stateless adapter contributes one tool and prompt section, while query lifecycle and result relations remain owned by the tool and LSP seams it composes. |Further Exploration
Read these pages when the package-level contract is not enough. They move from the model-facing surface to the seam and the provider.
- LSP navigation subsystem — operations, coordinates, requests and results, and
LspErrorcodes. - dsh-lsp — the seam this tool queries.
- dsh-lsp-stdio — the stdio provider that answers these queries.
- lsp group map — the three-package family and its related documentation.
Model Experience
System prompt
What the model sees
One system-prompt section (first-party order 2200) 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
These limits define when the tool is a poor fit. They are current package constraints, not a task backlog.
- 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.
- 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.