Knowledge Extension Ecosystem Lsp Code Intelligence

Module Structure

LSP 配置按 source project 解析并冻结，SessionRuntime 再以 execution workspace 创建私有 manager；语言服务器按目标文件扩展名懒启动，语义查询和写后诊断共享同一连接。

Directory Layout

• packages/cli/src/lsp/ — LSP client、Session manager 与 Workspace 资源快照
• packages/cli/src/config/lspSettings.ts — LSP server 配置规范化和硬边界
• packages/cli/src/tools/builtin/lsp/ — ReadOnly LSP 工具与协议结果格式化
• packages/cli/src/ide/ — IDE 检测和 Blade IDE 扩展安装入口
• docs/reference/lsp-session-intelligence.md — Session LSP 行为契约与资格要求

Key Entry Points

• resolveWorkspaceLspResources() in packages/cli/src/lsp/WorkspaceLspResources.ts — 合并用户、项目和插件服务器并冻结快照
• LspSessionManager.query() in packages/cli/src/lsp/LspSessionManager.ts — 执行语义查询
• LspSessionManager.afterToolUse() in packages/cli/src/lsp/LspSessionManager.ts — 写后同步并回注新诊断
• LspClient.start() / LspClient.stop() in packages/cli/src/lsp/LspClient.ts — 管理 stdio JSON-RPC 与 owned process tree
• createLspTool() in packages/cli/src/tools/builtin/lsp/lsp.ts — 将 manager 暴露为统一只读工具

API Surface

Workspace LSP Resources

• resolveWorkspaceLspResources(projectRoot, base) — 合并 Workspace 配置和插件 .lsp.json
• snapshotWorkspaceLspResources(resources) — 规范化、深拷贝并冻结 Session 配置

LspSessionManager

• available — 仅在存在启用服务器、Session 非 ACP remote 且未 dispose 时为真
• query(input, signal) — 路由 definition、references、hover、symbols、implementation、call hierarchy 或 diagnostics
• afterToolUse(toolName, params, result, context) — 同步成功写操作并把新诊断追加到 ToolResult
• getStatus() — 返回服务器状态、重启次数、扩展映射和最近错误
• dispose() — 解除 waiter、发送 shutdown/exit 并回收所有服务器进程

LspClient

• start(options) / initialize(params, timeout, signal) — 建立 stdio transport 与协议握手
• request(method, params, timeout, signal) — 带 JSON-RPC cancellation 和本地 timeout 的请求
• stop(timeout) — 尝试协议关闭后以 owned process tree 作为最终回收边界

Usage Examples

Session 创建私有 Manager (packages/cli/src/agent/runtime/SessionRuntime.ts)

this.lspManager = new LspSessionManager({
  sessionId: this.sessionId,
  workspaceRoot: this.workspaceRoot,
  environment: this.sessionEnvironment,
  servers: this.lspResources.servers,
});

工具成功后同步诊断 (packages/cli/src/tools/execution/ToolExecutor.ts)

await runPostToolUseHooks(tool, params, result, context, hookResult.toolUseId);
if (context.signal?.aborted) return createCancellationResult(false);
await this.lspManager?.afterToolUse(tool.name, params, result, context);

子代理继承父 Session 快照 (packages/cli/src/agent/subagents/SubagentExecutor.ts)

runtime = await SessionRuntime.create({
  sessionId: agentId,
  workspaceRoot,
  agentResources: this.agentResources,
  modelResources: this.modelResources,
  lspResources: this.lspResources,
});

Gotchas

• ACP remote Session 即使带有 LSP 配置也不会启动宿主本地服务器，query() 会明确返回 remote-files unavailable；不能把 IDE 远端路径交给本地 realpath(packages/cli/src/lsp/LspSessionManager.ts)
• 只要本地 Session 配置了至少一个启用服务器，available 就为真并关闭 AutoVerify fallback；服务器后续启动失败或没有覆盖某类文件时不会自动恢复 package-script 验证(packages/cli/src/agent/runtime/SessionRuntime.ts, packages/cli/src/lsp/LspSessionManager.ts)
• 同一扩展名只选择一个 server，规则是 priority 降序、名称升序；配置多个同语言服务器不会并行聚合诊断或查询结果(packages/cli/src/lsp/LspSessionManager.ts)
• LSP 工具接收 1-based line/character，manager 在发协议请求前转为 0-based；直接调用 manager API 时也应遵循工具侧 1-based 契约(packages/cli/src/tools/builtin/lsp/lsp.ts, packages/cli/src/lsp/LspSessionManager.ts)
• 目标文件先 realpath 并验证位于 Session workspace 内；symlink 逃逸会拒绝，删除文件则通过最近存在祖先重建 canonical path 后再发送 didClose(packages/cli/src/lsp/LspSessionManager.ts)
• 只有成功的 Write/Edit 和带标准 metadata.changes 的 ApplyPatch 会触发同步；失败结果、其他写工具或自定义 metadata 不会产生 didChange/didSave(packages/cli/src/lsp/LspSessionManager.ts)
• 写后诊断在 PostToolUse Hook 之后、AutoVerify 之前追加到同一 ToolResult；Hook 看不到本次新 LSP 诊断，模型看到的最终结果则可以包含两者(packages/cli/src/tools/execution/ToolExecutor.ts)
• 诊断按内容 hash 跨轮去重，每文件最多注入 10 条、单次最多 30 条；重复问题仍可通过显式 diagnostics 查询看到，但不会反复附加到写工具结果(packages/cli/src/lsp/LspSessionManager.ts)
• server crash 只把状态设为 error 并清空 opened-files；真正重启发生在下一次相关查询或写同步，超过 maxRestarts 后 fail closed(packages/cli/src/lsp/LspSessionManager.ts)
• 已 dispose transport 的迟到 child close 或 JSON-RPC close 必须被 identity guard 忽略，否则会把新 transport 错误标记为未初始化；该回归由独立代际测试锁定(packages/cli/src/lsp/LspClient.ts, packages/cli/tests/unit/services/lsp-client.test.ts, git:8a29b24e)
• 只有 JSON-RPC ContentModified 会最多重试 4 次并做指数退避；timeout、abort、server error 和其他协议错误都直接返回(packages/cli/src/lsp/LspSessionManager.ts)
• LSP 文件读取上限是 10 MiB，服务器 stderr 只保留前 64 KiB 且崩溃消息只带 512 字符预览；不能依赖完整 stderr 做长期诊断(packages/cli/src/lsp/LspSessionManager.ts, packages/cli/src/lsp/LspClient.ts)