docs: reserve seam for complete capabilities
This commit is contained in:
Turtle
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/lsp/README.md
|
||||
README.md: 01c464c9993571990e0542df9fadb2848a6c9a79
|
||||
README.zh.md: 7a24bffa0e92f30c16a3307357ba7f1aa295ef52
|
||||
README.md: 3b472492ba12146101bae0e2eae9c837a7f6cb1d
|
||||
README.zh.md: e9e2781fdb9da8a3094080759730d01e179bff98
|
||||
@@ -2,15 +2,15 @@
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
The language-server capability seam: an abstract LSP interface, a generic stdio provider, and the model-facing `lsp` tool. All **product** packages.
|
||||
The language-server capability seam: an LSP Service Definition, a generic stdio provider, and the model-facing `lsp` tool. All **product** packages.
|
||||
|
||||
| Package | Role | ctx key |
|
||||
|---|---|---|
|
||||
| `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
|
||||
| `lsp/` | Service Definition (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
|
||||
| `lsp-local/` | Generic multi-server stdio backend over `ctx.fs` and `ctx.subprocess` (JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
|
||||
| `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
|
||||
|
||||
The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
|
||||
The Service Definition lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
|
||||
|
||||
See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
|
||||
|
||||
|
||||
@@ -2,15 +2,15 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品**包。
|
||||
语言服务器能力 seam：LSP Service Definition、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品** 包。
|
||||
|
||||
| 包 | 职责 | ctx key |
|
||||
|---|---|---|
|
||||
| `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
|
||||
| `lsp/` | Service Definition（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
|
||||
| `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
|
||||
| `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
|
||||
|
||||
接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型约定。提供方注册的是**能力**而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
|
||||
Service Definition 位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型约定。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
|
||||
|
||||
设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
/**
|
||||
* A JSON-RPC endpoint over one language server spawned through the subprocess
|
||||
* seam. Owns id correlation, outbound requests/notifications, and inbound
|
||||
* capability. Owns id correlation, outbound requests/notifications, and inbound
|
||||
* server→client requests: it answers `workspace/configuration` from static
|
||||
* config, and rejects `workspace/applyEdit` (this host never applies edits or
|
||||
* runs commands). It caps stderr, surfaces framing/decoder failures as a
|
||||
* fatal close, and exposes tree-scoped termination through the handle so the
|
||||
* instance owns teardown; group/tree mechanics live in the seam's
|
||||
* implementation.
|
||||
* instance owns teardown; group/tree mechanics live in the subprocess
|
||||
* Service provider.
|
||||
* @module @deepseek-ai/dsh-lsp-local/connection
|
||||
*/
|
||||
|
||||
|
||||
@@ -92,7 +92,7 @@ export class LspInstance {
|
||||
*/
|
||||
query(request: LspProviderQuery, source: HostSource, signal?: AbortSignal): Promise<LspQueryResult> {
|
||||
// Serialize behind prior work, but observe abort DURING the queue wait too: if an earlier query
|
||||
// hangs (e.g. a signal-less seam caller), a later tool's timeout must still be able to give up
|
||||
// hangs (e.g. a signal-less service caller), a later tool's timeout must still be able to give up
|
||||
// rather than block on the shared tail forever.
|
||||
const run = abortable(this.queue, signal)
|
||||
.then(() => this.runQuery(request, source, signal))
|
||||
|
||||
@@ -25,8 +25,8 @@ import type {
|
||||
} from './protocol.ts'
|
||||
|
||||
/**
|
||||
* The `textDocument/*` request method for each seam operation.
|
||||
* @param operation - the seam operation to map.
|
||||
* The `textDocument/*` request method for each LSP operation.
|
||||
* @param operation - the LSP operation to map.
|
||||
* @returns the LSP request method name.
|
||||
*/
|
||||
export function requestMethod(operation: LspOperation): string {
|
||||
@@ -62,7 +62,7 @@ function supportsCapability(value: WireProviderCapability): boolean {
|
||||
/**
|
||||
* Whether the server advertises the requested operation.
|
||||
* @param capabilities - the server's `initialize` capabilities.
|
||||
* @param operation - the seam operation to check.
|
||||
* @param operation - the LSP operation to check.
|
||||
* @returns true when the corresponding provider capability is present.
|
||||
*/
|
||||
export function supportsOperation(capabilities: WireServerCapabilities, operation: LspOperation): boolean {
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/lsp/lsp/README.md
|
||||
README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
|
||||
README.zh.md: a35f870603718ee6b7bcbfdf65f5d689d800447b
|
||||
README.md: bab312e73f746d0d782ab5771429fed1397255aa
|
||||
README.zh.md: 7ef95c725eba4a35f99014b446fc5648d8aab20a
|
||||
@@ -4,13 +4,13 @@ English | [中文](README.zh.md)
|
||||
|
||||
The **LSP capability seam**: an abstract `LspService` (`ctx.lsp`) defining WHAT semantic code navigation the harness has — go to definition, find references, find implementations, hover — over language-server providers, without binding the model contract to local subprocesses.
|
||||
|
||||
This package is the interface third of the LSP capability:
|
||||
This package owns the Service Definition role of the LSP capability:
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@deepseek-ai/dsh-lsp` (this) | the interface: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
|
||||
| `@deepseek-ai/dsh-lsp-local` | a generic local backend that registers configured stdio language-server providers |
|
||||
| `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool over `ctx.lsp` |
|
||||
| `@deepseek-ai/dsh-lsp` (this) | Service Definition: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
|
||||
| `@deepseek-ai/dsh-lsp-local` | Service provider: a generic local backend that registers configured stdio language-server providers |
|
||||
| `@deepseek-ai/dsh-tool-lsp` | Consumer: the model-facing `lsp` tool over `ctx.lsp` |
|
||||
|
||||
The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`.
|
||||
|
||||
|
||||
@@ -4,13 +4,13 @@
|
||||
|
||||
**LSP 能力 seam**：抽象 `LspService`（`ctx.lsp`）定义 harness 具备哪些语义代码导航能力（转到定义、查找引用、查找实现、悬停），并通过语言服务器提供方实现，不把模型约定绑定到本地子进程。
|
||||
|
||||
该包是 LSP 能力中负责接口的三分之一：
|
||||
本包承担 LSP 能力的 Service Definition 角色：
|
||||
|
||||
| 包 | 职责 |
|
||||
|---|---|
|
||||
| `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
|
||||
| `@deepseek-ai/dsh-lsp-local` | 通用本地后端，注册已配置的 stdio 语言服务器提供方 |
|
||||
| `@deepseek-ai/dsh-tool-lsp` | 面向模型的 `lsp` 工具，基于 `ctx.lsp` |
|
||||
| `@deepseek-ai/dsh-lsp`（本包） | Service Definition：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
|
||||
| `@deepseek-ai/dsh-lsp-local` | Service provider：通用本地后端，注册已配置的 stdio 语言服务器提供方 |
|
||||
| `@deepseek-ai/dsh-tool-lsp` | Consumer：面向模型的 `lsp` 工具，基于 `ctx.lsp` |
|
||||
|
||||
该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且没有通用 JSON-RPC 逃生口，因此任何协议载荷或未经评审的命令／修改都无法通过 `ctx.lsp` 到达提供方。
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
/**
|
||||
* The LSP capability seam (`ctx.lsp`): a language-server provider registry and per-query,
|
||||
* Service Definition for the LSP capability seam (`ctx.lsp`): a language-server provider registry and per-query,
|
||||
* order-independent selection over normalized goToDefinition/findReferences/goToImplementation/
|
||||
* hover queries.
|
||||
*
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/lsp/tool-lsp/README.md
|
||||
README.md: 1e89abf22e853735c094d17047b2c946af210905
|
||||
README.zh.md: 396b4d22ada8761b17c01d0c40e4bb4cfe80ca67
|
||||
README.md: 36fa3026cba3fc692ae5a86c7307acf77563cf53
|
||||
README.zh.md: 1b0b1f4847cf711e7939b79ac2f8035f26cb73aa
|
||||
@@ -10,7 +10,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). In
|
||||
|
||||
`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, resolvedWorkspaceUri }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering projects stable, file-grouped `path:line:character` entries against the provider's canonical workspace URI rather than applying host-platform path rules to the session cwd. A `file:` URI becomes a workspace-relative path inside that URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs stay verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
|
||||
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 Service Definition union: `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering projects stable, file-grouped `path:line:character` entries against the provider's canonical workspace URI rather than applying host-platform path rules to the session cwd. A `file:` URI becomes a workspace-relative path inside that URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs stay verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
|
||||
|
||||
## Configuration
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
|
||||
|
||||
`lsp` 接受 `operation`（`goToDefinition` | `findReferences` | `goToImplementation` | `hover`）、`file_path`、`line` 和 `character`。`line` 与 `character` 是正的、从 1 开始的 UTF-16 光标坐标；工具将其转换为 seam 从零开始的位置，并把渲染位置转换回来。`findReferences` 包含声明，因此影响分析不会遗漏定义位置。提供方、language id、Workspace 根、限制、超时、初始化和可执行文件均不进入模型输入。
|
||||
|
||||
该工具要求从会话 `header.cwd` 取得 Workspace 根，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 seam 联合：`{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。原生渲染以提供方的规范工作区 URI 为基准，投影按文件稳定分组的 `path:line:character` 条目，而不对会话 cwd 应用宿主平台路径规则。`file:` URI 落在该工作区 URI 内时成为工作区相对路径，位于其外时成为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
|
||||
该工具要求从会话 `header.cwd` 取得 Workspace 根，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 Service Definition 联合：`{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。原生渲染以提供方的规范工作区 URI 为基准，投影按文件稳定分组的 `path:line:character` 条目，而不对会话 cwd 应用宿主平台路径规则。`file:` URI 落在该工作区 URI 内时成为工作区相对路径，位于其外时成为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
|
||||
|
||||
## 配置
|
||||
|
||||
|
||||
Reference in New Issue
Block a user