typescript-lsp

clickhouse-js 中的 TypeScript 语言服务

typescript-language-server 声明为根目录的开发依赖项，因此运行 npm install 后（参见 setup 技能），即可通过 npx 使用，并且会使用工作区本地的 typescript（6.x）编译器，与 CI 完全一致。

该服务（6.x）要求 Node.js >= 22.22.2，高于仓库要求的 Node 20 最低版本；在 Node 20 上，npm install 只会发出警告，但该服务不受支持。

启动服务

在仓库根目录运行：

npx typescript-language-server --stdio

它通过标准输入/输出使用 LSP（JSON-RPC，采用 Content-Length 分帧）。无需额外配置：每个 packages/* 工作区、tests/clickhouse-test-runner、examples/node 和 examples/web 都有自己的 tsconfig.json，服务会自动为每个打开的文件选择最近的配置。

协议要点

1. 发送 initialize，将 rootUri/workspaceFolders 指向仓库根目录，然后发送 initialized 通知。
2. 对要查询的每个文件发送 textDocument/didOpen，并附上完整文件文本（服务会自行从磁盘读取依赖项；只需打开要查询位置的文件）。
3. 位置采用从 0 开始的索引（行和字符）。

已验证的功能（typescript-language-server 5.x，TS 6.x）

请求	说明
textDocument/hover	返回完整的推断签名和 JSDoc Markdown
textDocument/definition	通过源代码解析跨工作区包的定义，而非通过 dist/
textDocument/references	在已打开文件所属的项目内查找引用
workspace/symbol	例如，查询 ClickHouseClient 可找到类和重新导出项
textDocument/completion	提供上下文感知的成员补全
诊断	仅推送（textDocument/publishDiagnostics 通知，会在 didOpen 后约 1–3 秒发送）。不支持拉取式的 textDocument/diagnostic 请求（-32601）——请等待推送通知。

提示

• 如果你的环境提供内置的 LSP/代码智能工具，请将其指向 npx typescript-language-server --stdio，并将仓库根目录设为工作区文件夹。
• 对于一次性脚本查询，可从 Node 启动服务，使用 Content-Length: <bytes>\r\n\r\n<json> 对消息分帧，并按 id 匹配响应。
• 完整的工作区类型检查仍需运行 npm run build && npm run typecheck（先构建——部分工作区会导入已编译的 dist/ 输出）；LSP 用于有针对性的交互式查询，而非等同于 CI 的验证。