@deepseek-ai/dsh-lsp 0.1.1-rc.2 → 0.1.2-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.i18n.yaml CHANGED
@@ -2,5 +2,5 @@
2
2
  # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
3
  # after editing either side, bring the other along and re-record with:
4
4
  # pnpm run verify-translation-pairing --write packages/lsp/lsp/README.md
5
- README.md: cf32f9cc60a346def48d9720bf0695db36553b0e
6
- README.zh.md: eba25a7494f8c624b0e9d0aa5b5c7dd484d1f0f9
5
+ README.md: 807f9301784423553c11b6b544f9e1eaee60e78b
6
+ README.zh.md: 8674132e2de58c7327db7431d658872a17589309
package/README.md CHANGED
@@ -1,37 +1,119 @@
1
+ ---
2
+ description: "The LSP capability seam (ctx.lsp): provider selection by file extension, four normalized code-navigation operations, and structured errors, for users and maintainers composing or extending code navigation."
3
+ kind: "package-reference"
4
+ ---
5
+
1
6
  # @deepseek-ai/dsh-lsp
2
7
 
3
8
  English | [中文](README.zh.md)
4
9
 
5
- 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.
10
+ ## Summary
11
+
12
+ `dsh-lsp` provides the harness's language-server code navigation: an agent can go to a symbol's definition, find its references, jump to its implementations, or read hover documentation, and the code-navigation service (`ctx.lsp`) routes each query to the language-server provider that owns the file's extension. Providers register by branded id and file extension, so a provider swap never changes how navigation is requested or what the model sees. The service exposes exactly four read-only operations and no generic JSON-RPC escape hatch, and it contributes no prompt or tool schema itself — the model-facing `lsp` tool lives in `dsh-tool-lsp`. Compose it with a provider such as `dsh-lsp-stdio` and the tool to give agents precise navigation; this package does nothing on its own.
13
+
14
+ ## Table of Contents
15
+
16
+ - [Use this package](#use-this-package)
17
+ - [Understand the implementation](#understand-the-implementation)
18
+ - [Further Exploration](#further-exploration)
19
+ - [Model Experience](#model-experience)
20
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
21
+ - [Dev Note](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## Use this package
27
+
28
+ Mount a language-server provider and the `lsp` tool to give agents semantics-based code navigation that text search cannot reliably provide — distinguishing same-named functions, following import aliases, connecting an interface to its implementations, or reading inferred types. This package is the service those packages register against; it defines no UI, tool, or provider of its own.
29
+
30
+ ### When to choose it
31
+
32
+ Choose this service when a deployment wants model-visible code navigation backed by language servers. It covers read-only navigation — definitions, references, implementations, and hover — and deliberately omits mutations (rename, code actions, formatting), symbol lists, and diagnostics. The service is provider-neutral: local stdio servers, remote servers, and sandbox-native providers register the same way, so replacing the backend does not change what the model sees or how it asks.
6
33
 
7
- This package owns the Service Definition role of the LSP capability:
34
+ ### Composing a navigation stack
8
35
 
9
- | Package | Role |
36
+ The seam needs a provider and a consumer to do anything. A minimal composition mounts the service, a stdio provider, and the tool:
37
+
38
+ ```yaml
39
+ - name: '@deepseek-ai/dsh-fs-local'
40
+ - name: '@deepseek-ai/dsh-subprocess-local'
41
+ - name: '@deepseek-ai/dsh-lsp'
42
+ - name: '@deepseek-ai/dsh-lsp-stdio'
43
+ - name: '@deepseek-ai/dsh-tool-lsp'
44
+ ```
45
+
46
+ Server commands, extension mappings, and the filesystem/subprocess pairing are configured in the provider and tool packages; see [dsh-lsp-stdio](../lsp-stdio/README.md) and [dsh-tool-lsp](../tool-lsp/README.md).
47
+
48
+ ### The four operations
49
+
50
+ Each query asks one of four semantic questions at a cursor position in a source file; results are normalized locations or hover content, never raw protocol payloads.
51
+
52
+ | Operation | What the agent gets |
10
53
  |---|---|
11
- | `@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 |
12
- | `@deepseek-ai/dsh-lsp-stdio` | Service Provider: a generic local backend that registers configured stdio language-server providers |
13
- | `@deepseek-ai/dsh-tool-lsp` | Consumer: the model-facing `lsp` tool over `ctx.lsp` |
54
+ | `goToDefinition` | The declaration site(s) of the symbol at the cursor |
55
+ | `findReferences` | Every reference, always including the declaration |
56
+ | `goToImplementation` | The concrete implementation site(s) |
57
+ | `hover` | Normalized documentation for the symbol, or none |
58
+
59
+ `findReferences` always includes declarations, so impact analysis never misses the defining site. Positions are zero-based UTF-16 on the wire; the model-facing tool accepts one-based cursor coordinates and converts them.
60
+
61
+ ### Failures and recovery
62
+
63
+ A query fails with the structured error `LSP_UNAVAILABLE` when no registered provider handles the file's extension — add a provider for that extension or query a supported file. Invalid or conflicting provider registrations fail with `LSP_INVALID_PROVIDER` or `LSP_CONFLICT` before any route is published, and a query against a disposed provider fails with `LSP_DISPOSED`. Consumers catch `LspError` and route on its stable `code`; through the tool, these surface as error results the model can read.
14
64
 
15
- 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`.
65
+ -----
16
66
 
17
- ## Service API (`ctx.lsp`)
67
+ <a id="understand-the-implementation"></a>
68
+ ## Understand the implementation
18
69
 
19
- | Member | Semantics |
70
+ <details>
71
+ <summary>Implementation internals — click to expand</summary>
72
+
73
+ This section explains the design decisions behind the seam and where the code realizes them; observable behavior is covered in [Use this package](#use-this-package).
74
+
75
+ ### Design philosophy
76
+
77
+ - **Capability seam, Service Definition role.** The package owns `ctx.lsp` and the provider registry; providers register capabilities, not tools, and `dsh-tool-lsp` is the only owner of the model-facing surface.
78
+ - **Atomic registration.** `registerProvider()` validates and conflict-checks everything before mutating: an invalid or conflicting registration publishes nothing, and its disposer releases the id and every extension reservation together.
79
+ - **Order-independent selection.** `query()` routes by the file's final extension, normalized to lowercase leading-dot form; registration and HMR order never change routing. The language id only synchronizes the transient document and never participates in selection.
80
+ - **Closed vocabulary.** The four-operation union is closed — adding an operation is a compile-enforced change across the seam, providers, and the tool. There is no JSON-RPC escape hatch, and every request field is required, so there is no `resolve()` step.
81
+ - **Provider-owned workspace coordinate.** Location results carry the provider's canonical workspace URI, so consumers relativize file URIs in the execution world's namespace instead of applying host-platform path rules.
82
+
83
+ ### Source map
84
+
85
+ | File | Role |
20
86
  |---|---|
21
- | `registerProvider(provider)` | Register a backend, atomically reserving its branded `id` and every normalized file extension. Any invalid input or conflict publishes nothing and throws `LspError` (`LSP_INVALID_PROVIDER` / `LSP_CONFLICT`). Returns a disposer releasing all reservations. Disposed with the calling fiber. |
22
- | `query(request, signal?)` | Select the provider by the file's final extension, derive the `languageId` from that provider's mapping, and run one query. No match throws `LspError` `LSP_UNAVAILABLE`. |
87
+ | [`src/index.ts`](src/index.ts) | Plugin entry: `Lsp` service, `registerProvider`/`query`, `finalExtension`, `LspError` codes |
88
+ | [`src/types.ts`](src/types.ts) | Seam vocabulary: request, result, provider, and service contracts |
89
+ | [`src/brand.ts`](src/brand.ts) | `LspProviderId` branded-id type and factory |
90
+ | [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; routes are private atomic state) |
91
+
92
+ ### Registration and selection lifecycle
93
+
94
+ Registration and disposal run through `ctx.effect()`, so provider routes live and die with the registering fiber. `finalExtension()` splits on both path separators and returns `''` for names without an extension or leading-dot dotfiles, which no route matches. `LspError` extends `HarnessError` with stable codes (`LSP_INVALID_PROVIDER`, `LSP_CONFLICT`, `LSP_UNAVAILABLE`, `LSP_DISPOSED`, `LSP_UNSUPPORTED_OPERATION`, `LSP_MALFORMED_RESPONSE`) that callers route on instead of parsing `message`.
95
+
96
+ </details>
23
97
 
24
- Selection is per query and order-independent: a provider owns a set of extensions exclusively, so registration and HMR order never change routing. Extension keys normalize to lowercase, leading-dot form; the `languageId` only synchronizes the transient document, never participates in selection. The first version has no glob, language-id, or explicit route selector.
98
+ -----
25
99
 
26
- Providers register **capabilities**, not tools. `dsh-tool-lsp` is the only owner of the model-facing name, description, prompt guidance, schema, and presentation.
100
+ <a id="further-exploration"></a>
101
+ ## Further Exploration
27
102
 
28
- ## Vocabulary
103
+ Read these pages when the package-level contract is not enough. They move from the shared navigation model to the provider, the tool, and the decision evidence.
29
104
 
30
- `LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `findReferences` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations; resolvedWorkspaceUri }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. `resolvedWorkspaceUri` is the provider's canonical workspace `file:` URI; callers relativize location URIs against it instead of applying host-platform path rules to the possibly symlinked request root. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes, including `LSP_DISPOSED` and `LSP_MALFORMED_RESPONSE`.
105
+ - [LSP navigation subsystem](../../../docs/subsystems/lsp.md) — operations, coordinates, requests and results, and `LspError` codes.
106
+ - [LSP capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) — design rationale, alternatives, and deliberately deferred API.
107
+ - [dsh-lsp-stdio](../lsp-stdio/README.md) — the stdio provider that registers against this seam.
108
+ - [dsh-tool-lsp](../tool-lsp/README.md) — the model-facing tool over this seam.
109
+ - [lsp group map](../README.md) — the three-package family and its related documentation.
31
110
 
111
+ -----
112
+
113
+ <a id="model-experience"></a>
32
114
  ## Model Experience
33
115
 
34
- Indirectly, through `dsh-tool-lsp`, which owns the model-facing `lsp` schema, prompt, and rendered results while this registry contributes no prompt or schema itself.
116
+ Indirectly, through `dsh-tool-lsp`, which owns the model-facing `lsp` schema, prompt guidance, and rendered results while this registry contributes no prompt or schema itself.
35
117
 
36
118
  #### KV Cache effect
37
119
 
@@ -39,6 +121,21 @@ No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
39
121
 
40
122
  ## Known Limitations and Deferred Work
41
123
 
42
- - **Exclusive extension ownership within one runtime** — two providers cannot both claim `.ts`, even with different language ids; overlaps fail registration. The intended extension is a deployment-configured selector above registrations, which can relax exclusive reservation without adding provider choice to model input ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)).
43
- - **Four operations only** — symbols and call hierarchy are deferred (they need different schemas); diagnostics need separate freshness/accumulation rules; mutations (rename, code actions, formatting) require separate tools with preview, permission, and write-policy integration.
124
+ <a id="known-limitations-and-deferred-work"></a>
125
+
126
+
127
+ These limits define the seam's current scope. They are package constraints, not a task backlog.
128
+
129
+ - **Exclusive extension ownership within one runtime** — two providers cannot both claim `.ts`, even with different language ids; overlaps fail registration. A deployment-configured selector above registrations is the intended extension, which can relax exclusive reservation without adding provider choice to model input ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)).
130
+ - **Four read-only operations only** — symbols and call hierarchy are deferred because they need different schemas; diagnostics need separate freshness and accumulation rules; mutations (rename, code actions, formatting) require separate tools with preview, permission, and write-policy integration.
44
131
  - **No observation API** — availability is observed only by running `query()` and routing the thrown `LspError` codes; there is no provider-change event or capability-status query.
132
+
133
+ <a id="dev-note"></a>
134
+ ### Dev Note
135
+
136
+ <details>
137
+ <summary>Working context for maintainers — click to expand</summary>
138
+
139
+ None.
140
+
141
+ </details>
package/README.zh.md CHANGED
@@ -1,44 +1,141 @@
1
+ ---
2
+ description: "LSP 能力 seam(ctx.lsp):按文件扩展名选择提供方、四种规范化的代码导航操作与结构化错误,供组合或扩展代码导航的用户与维护者阅读。"
3
+ kind: "package-reference"
4
+ ---
5
+
1
6
  # @deepseek-ai/dsh-lsp
2
7
 
3
8
  [English](README.md) | 中文
4
9
 
5
- **LSP 能力 seam**:抽象 `LspService`(`ctx.lsp`)定义 harness 具备哪些语义代码导航能力(转到定义、查找引用、查找实现、悬停),并通过语言服务器提供方实现,不把模型约定绑定到本地子进程。
10
+ ## 概述
11
+
12
+ `dsh-lsp` 为 harness 提供语言服务器代码导航:agent 可以转到符号的定义、查找其引用、跳转到其实现或阅读悬停文档,代码导航服务(`ctx.lsp`)会把每个查询路由到拥有该文件扩展名的语言服务器提供方。提供方按品牌化 id 与文件扩展名注册,因此更换提供方绝不会改变请求导航的方式,也不会改变模型看到的内容。该服务恰好暴露四种只读操作,没有通用 JSON-RPC 逃生口;它自身不贡献提示词或工具 schema——面向模型的 `lsp` 工具位于 `dsh-tool-lsp`。与 `dsh-lsp-stdio` 之类的提供方及该工具组合,即可为 agent 提供精确导航;本包单独加载时什么也不做。
13
+
14
+ ## 目录
15
+
16
+ - [使用本包](#use-this-package)
17
+ - [理解实现](#understand-the-implementation)
18
+ - [进一步探索](#further-exploration)
19
+ - [模型体验](#model-experience)
20
+ - [已知限制与延期工作](#known-limitations-and-deferred-work)
21
+ - [开发备注](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## 使用本包
27
+
28
+ 挂载语言服务器提供方与 `lsp` 工具,即可为 agent 提供文本搜索无法可靠给出的、基于语义的代码导航——区分同名函数、跟随导入别名、把接口连接到其实现,或读取推断出的类型。本包就是这些包所注册的服务;它自身不定义任何 UI、工具或提供方。
29
+
30
+ ### 何时选择
31
+
32
+ 当部署希望模型可见的代码导航由语言服务器支撑时,选择此服务。它覆盖只读导航——定义、引用、实现与悬停——并刻意排除修改(重命名、code action、格式化)、符号列表与诊断。该服务提供方无关:本地 stdio 服务器、远程服务器与沙箱原生提供方都以相同方式注册,因此更换后端不会改变模型看到的内容或请求方式。
6
33
 
7
- 本包承担 LSP 能力的 Service Definition 角色:
34
+ ### 组合导航栈
8
35
 
9
- | | 职责 |
36
+ seam 需要提供方与消费方才能发挥作用。最小组合挂载服务、stdio 提供方与工具:
37
+
38
+ ```yaml
39
+ - name: '@deepseek-ai/dsh-fs-local'
40
+ - name: '@deepseek-ai/dsh-subprocess-local'
41
+ - name: '@deepseek-ai/dsh-lsp'
42
+ - name: '@deepseek-ai/dsh-lsp-stdio'
43
+ - name: '@deepseek-ai/dsh-tool-lsp'
44
+ ```
45
+
46
+ 服务器命令、扩展名映射与文件系统/子进程配对在提供方与工具包中配置;见 [dsh-lsp-stdio](../lsp-stdio/README.zh.md) 与 [dsh-tool-lsp](../tool-lsp/README.zh.md)。
47
+
48
+ ### 四种操作
49
+
50
+ 每个查询在源文件的某个光标位置提出四个语义问题之一;结果是被规范化的位置或悬停内容,绝不是原始协议载荷。
51
+
52
+ | 操作 | agent 获得的内容 |
10
53
  |---|---|
11
- | `@deepseek-ai/dsh-lsp`(本包) | Service Definition:服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求/结果词汇、`LspError` 分类体系 |
12
- | `@deepseek-ai/dsh-lsp-stdio` | Service Provider:通用本地后端,注册已配置的 stdio 语言服务器提供方 |
13
- | `@deepseek-ai/dsh-tool-lsp` | Consumer:面向模型的 `lsp` 工具,基于 `ctx.lsp` |
54
+ | `goToDefinition` | 光标处符号的定义位置 |
55
+ | `findReferences` | 所有引用,始终包含声明 |
56
+ | `goToImplementation` | 具体实现位置 |
57
+ | `hover` | 该符号的规范化文档,或没有 |
58
+
59
+ `findReferences` 始终包含声明,因此影响分析绝不会遗漏定义位置。协议上的位置是从零开始的 UTF-16;面向模型的工具接受从 1 开始的光标坐标并自行转换。
60
+
61
+ ### 失败与恢复
62
+
63
+ 当没有注册的提供方处理该文件扩展名时,查询会以结构化错误 `LSP_UNAVAILABLE` 失败——为该扩展名添加提供方,或查询受支持的文件。无效或冲突的提供方注册会在任何路由发布前以 `LSP_INVALID_PROVIDER` 或 `LSP_CONFLICT` 失败;对已释放提供方的查询以 `LSP_DISPOSED` 失败。消费方捕获 `LspError` 并按稳定的 `code` 路由;经由工具,这些会呈现为模型可读的错误结果。
14
64
 
15
- 该 seam 恰好公开四种语义操作:`goToDefinition`、`findReferences`、`goToImplementation`、`hover`,且没有通用 JSON-RPC 逃生口,因此任何协议载荷或未经评审的命令/修改都无法通过 `ctx.lsp` 到达提供方。
65
+ -----
16
66
 
17
- ## 服务 API(`ctx.lsp`)
67
+ <a id="understand-the-implementation"></a>
68
+ ## 理解实现
18
69
 
19
- | 成员 | 语义 |
70
+ <details>
71
+ <summary>实现细节——点击展开</summary>
72
+
73
+ 本节解释 seam 背后的设计决策并指出实现它们的代码位置;可观察行为已在[使用本包](#use-this-package)中完整说明。
74
+
75
+ ### 设计理念
76
+
77
+ - **能力 seam,Service Definition 角色。** 本包拥有 `ctx.lsp` 与提供方注册表;提供方注册的是能力而非工具,`dsh-tool-lsp` 是面向模型表层的唯一 owner。
78
+ - **原子注册。** `registerProvider()` 在变更前验证并检查全部冲突:无效或冲突的注册不会发布任何内容,其 disposer 会一并释放 id 与全部扩展名保留。
79
+ - **与顺序无关的选择。** `query()` 按文件的最终扩展名(规范化为小写、以点开头的形式)路由;注册与 HMR 顺序绝不会改变路由。language id 只用于同步临时文档,绝不参与选择。
80
+ - **封闭的词汇。** 四种操作的联合是封闭的——新增操作是跨 seam、提供方与工具的编译期强制变更。没有 JSON-RPC 逃生口,且每个请求字段都必填,因此不存在 `resolve()` 步骤。
81
+ - **提供方拥有的工作区坐标。** 位置结果携带提供方的规范工作区 URI,消费方据此在执行世界的命名空间内相对化文件 URI,而不是应用宿主平台路径规则。
82
+
83
+ ### 源码地图
84
+
85
+ | 文件 | 职责 |
20
86
  |---|---|
21
- | `registerProvider(provider)` | 注册后端,以原子方式保留其品牌化 `id` 与每个规范化文件扩展名。任何无效输入或冲突都不会发布内容,并抛出 `LspError`(`LSP_INVALID_PROVIDER`/`LSP_CONFLICT`)。返回释放所有保留项的 disposer。随调用 fiber 释放。 |
22
- | `query(request, signal?)` | 按文件最终扩展名选择提供方,从该提供方的映射派生 `languageId`,并运行一次查询。没有匹配项时抛出 `LspError` `LSP_UNAVAILABLE`。 |
87
+ | [`src/index.ts`](src/index.ts) | 插件入口:`Lsp` 服务、`registerProvider`/`query`、`finalExtension`、`LspError` code |
88
+ | [`src/types.ts`](src/types.ts) | seam 词汇:请求、结果、提供方与服务约定 |
89
+ | [`src/brand.ts`](src/brand.ts) | `LspProviderId` 品牌化 id 类型与工厂 |
90
+ | [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件(无运行时不变式;路由是私有原子状态) |
91
+
92
+ ### 注册与选择生命周期
93
+
94
+ 注册与释放通过 `ctx.effect()` 执行,因此提供方路由随注册 fiber 一同存活与消亡。`finalExtension()` 按两种路径分隔符切分,对没有扩展名的名称或点开头的 dotfile 返回 `''`,任何路由都不会匹配。`LspError` 扩展 `HarnessError`,携带稳定的 code(`LSP_INVALID_PROVIDER`、`LSP_CONFLICT`、`LSP_UNAVAILABLE`、`LSP_DISPOSED`、`LSP_UNSUPPORTED_OPERATION`、`LSP_MALFORMED_RESPONSE`),调用方据此路由,而不是解析 `message`。
95
+
96
+ </details>
23
97
 
24
- 选择逐查询进行且与顺序无关:一个提供方独占一组扩展名,因此注册和 HMR(热模块替换)顺序绝不会改变路由。扩展名 key 规范化为小写且以点开头;`languageId` 只用于同步临时文档,绝不参与选择。第一版没有 glob、language-id 或显式路由 selector。
98
+ -----
25
99
 
26
- 提供方注册的是**能力**而非工具。`dsh-tool-lsp` 是面向模型的名称、描述、提示词指引、schema 和呈现的唯一 owner。
100
+ <a id="further-exploration"></a>
101
+ ## 进一步探索
27
102
 
28
- ## 词汇
103
+ 当包级约定不够用时阅读以下页面。它们从共享的导航模型逐步进入提供方、工具与决策证据。
29
104
 
30
- `LspQueryRequest`(`operation`、`filePath`、`position`、`workspaceRoot`):每个字段都必填,因此没有字段需要实现默认值,也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16,与协议一致;工具拥有从 1 开始的光标约定。`findReferences` 始终包含声明,提供方在内部强制执行,因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合:导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceUri }`,悬停使用 `{ kind: 'hover'; hover }`(内容或 `null`);消费方通过 `switch` 实现穷尽检查,因此新增分支会使编译失败,直到完成处理。`resolvedWorkspaceUri` 是提供方的规范工作区 `file:` URI;调用方相对化位置 URI 时以它为基准,而不是对可能含符号链接的请求根应用宿主平台路径规则。完整约定见 `src/types.ts`;`src/index.ts` 给出 `LspError` code,包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
105
+ - [LSP 导航子系统](../../../docs/subsystems/lsp.zh.md)——操作、坐标、请求与结果,以及 `LspError` code
106
+ - [LSP 能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md)——设计原理、备选方案与刻意推迟的 API。
107
+ - [dsh-lsp-stdio](../lsp-stdio/README.zh.md)——注册到该 seam 的 stdio 提供方。
108
+ - [dsh-tool-lsp](../tool-lsp/README.zh.md)——基于该 seam 的面向模型工具。
109
+ - [lsp 组地图](../README.zh.md)——三个包的家族及其相关文档。
31
110
 
111
+ -----
112
+
113
+ <a id="model-experience"></a>
32
114
  ## 模型体验
33
115
 
34
- 通过 `dsh-tool-lsp` 间接影响;该工具拥有面向模型的 `lsp` schema、提示词与渲染结果,本注册表自身不贡献提示词或 schema。
116
+ 通过 `dsh-tool-lsp` 间接影响;该工具拥有面向模型的 `lsp` schema、提示词指引与渲染结果,本注册表自身不贡献提示词或 schema。
35
117
 
36
118
  #### KV Cache 影响
37
119
 
38
120
  不会直接失效;请求前缀变更由 `dsh-tool-lsp` 负责。
39
121
 
40
- ## 已知限制与暂缓事项
122
+ ## 已知限制与延期工作
123
+
124
+ <a id="known-limitations-and-deferred-work"></a>
125
+
126
+
127
+ 这些限制定义 seam 当前的范围。它们是包约束,不是任务积压。
128
+
129
+ - **同一运行时内扩展名归属互斥**——两个提供方不能同时声明 `.ts`,即使 language id 不同;重叠会使注册失败。预期扩展是在注册之上增加部署配置的 selector,它可以在不把提供方选择加入模型输入的前提下放宽互斥保留(见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md))。
130
+ - **仅四种只读操作**——symbol 与 call hierarchy 因需要不同 schema 而推迟;diagnostics 需要独立的新鲜度与累积规则;修改(重命名、code action、格式化)需要独立工具,并集成预览、权限与写入策略。
131
+ - **没有观测表层**——可用性只能通过运行 `query()` 并按抛出的 `LspError` code 路由来观测;没有提供方变更事件或能力状态查询。
132
+
133
+ <a id="dev-note"></a>
134
+ ### 开发备注
135
+
136
+ <details>
137
+ <summary>维护者的工作上下文——点击展开</summary>
138
+
139
+ 无。
41
140
 
42
- - **同一运行时内扩展名归属互斥**:两个提供方不能同时声明 `.ts`,即使 language id 不同;重叠会使注册失败。预期扩展是在注册之上增加部署配置的 selector;它可以放宽互斥保留,而无需把提供方选择加入模型输入(见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md))。
43
- - **仅四种操作**:symbol 与 call hierarchy 暂缓(它们需要不同 schema);diagnostics 需要独立的新鲜度/累积规则;修改操作(rename、code action、formatting)需要独立工具,并集成预览、权限和写入策略。
44
- - **没有观测表层**:可用性只能通过运行 `query()` 并按抛出的 `LspError` code 路由来观测;没有提供方变更事件或能力状态查询。
141
+ </details>
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@deepseek-ai/dsh-lsp",
3
3
  "description": "Abstract LSP capability seam (ctx.lsp) for the DeepSeek Harness — language-server provider registry keyed by branded id and extension mapping, order-independent per-query selection, normalized definition/references/implementation/hover requests and results, and the LspError taxonomy",
4
- "version": "0.1.1-rc.2",
4
+ "version": "0.1.2-alpha.2",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -32,15 +32,15 @@
32
32
  ],
33
33
  "license": "MIT",
34
34
  "peerDependencies": {
35
- "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
36
- "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
37
- "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
38
- "@deepseek-ai/cordis": "^4.0.1"
35
+ "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
36
+ "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
37
+ "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
38
+ "@deepseek-ai/cordis": "^4.0.2"
39
39
  },
40
40
  "devDependencies": {
41
- "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
42
- "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
43
- "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
44
- "@deepseek-ai/cordis": "^4.0.1"
41
+ "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
42
+ "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
43
+ "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
44
+ "@deepseek-ai/cordis": "^4.0.2"
45
45
  }
46
46
  }