Code intelligence 实战：为 Claude Code 搭建 LSP 语义导航层

1. 大型仓库里 Claude Code 为什么总在“盲读”我在一个 TypeScript monorepo 里让 Claude Code 改一个订单状态字段它先 grep 了status然后一口气打开了 14 个文件DTO、selector、test fixture、i18n 文案、甚至一个同名的 CSS class。最后它改对了 3 处漏了 2 处还顺手把一个无关组件的变量名也改了。这不是模型笨而是它当时只有“文本搜索”这一种眼睛。Code intelligence 要解决的就是这件事。它是 Claude Code 连接 language server 的扩展能力让模型获得类似 IDE 的语义导航跳转定义、查找引用、hover 类型信息、列出符号、追踪调用层级以及文件编辑后的实时 diagnostics。它适合 typed languages 和大型代码库尤其是 TypeScript、Python、Go、Rust、Java 这类有成熟 language server 生态的项目。一句话区分grep 找的是字符串LSP 找的是符号关系。OrderService不是几个字母它有构造函数注入、interface 约束、mock 实现、Controller 调用链。粗暴搜索会把概念相近但语义不同的东西混在一起而 language server 知道当前这个submit到底是哪个 function、method 还是 interface member。这篇我会从零搭一遍先讲清楚 LSP 和 diagnostics 在 Claude Code 里怎么工作再给出可复制的settings.json配置骨架然后用 TaoToken 统一 Key/API 通道接入工具链最后用一次跨文件重构验证语义导航到底有没有生效。2. 前置准备LSP、diagnostics 与 TaoToken 通道2.1 Code intelligence 的加载时机很多人一听“语义索引”就担心上下文成本暴涨实际逻辑恰好相反。Code intelligence 不会在 session start 时把整个项目的 AST、类型图全量灌进上下文。官方给出的时机是文件编辑之后加载 type errors 和 warningsClaude 导航代码时按需触发才加载 definition、reference 和 type information。这跟 CLAUDE.md 完全不同。CLAUDE.md 适合放总是要遵守的项目约定比如包管理器、测试命令、架构边界它在 session start 就完整加载并进入每次请求。Code intelligence 负责的是会随文件变动而变化的代码结构事实。一次精准的 symbol lookup常常能替代多次大范围文件读取净上下文用量反而可能下降。2.2 plugin 和 language server 是两回事Code intelligence 不是 Claude Code 凭空生成的能力。它需要对应语言的 LSP plugin还需要系统里装好 language server binary。plugin 是连接器负责告诉 Claude Code 怎么接上 server真正理解语言的是 TypeScript language server、Pyright、rust-analyzer、gopls 这些成熟组件。常见对应关系如下语言plugin需要的 binaryTypeScripttypescript-lsptypescript-language-serverPythonpyright-lsppyright-langserverRustrust-analyzer-lsprust-analyzerGogopls-lspgopls在装好对应 plugin 之前Claude Code 内置的 LSP tool 是 inactive 状态自然拿不到 symbol lookup 或 diagnostics。2.3 用 TaoToken 统一 Key 与 API 通道Claude Code 本身要连模型工具链里可能还有别的 AI 工具如果每个都单独配 Key 和地址管理起来很乱。我习惯用 TaoToken 做统一入口官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。先在控制台建好 Key后面 Claude Code 和验证脚本都复用同一个通道。拿 Key 的入口在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到接入问题先翻这里。3. 可复制配置settings.json 骨架与 language server 安装3.1 安装 language server binary以 TypeScript 为例先确认 binary 能被找到npm install -g typescript typescript-language-server which typescript-language-serverPython 项目用 Pyrightnpm install -g pyright which pyright-langserverRust 项目直接装 rust-analyzerrustup component add rust-analyzer which rust-analyzerwhich有输出说明 Claude Code 启动 language server 时能找到它。这一步没做后面 plugin 装了也是空转。3.2 settings.json 配置骨架Claude Code 的配置放在项目级.claude/settings.json或用户级配置里。下面是一份可复制的骨架把 LSP plugin、环境变量和 TaoToken 通道都串起来{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey }, plugins: { typescript-lsp: { enabled: true, command: typescript-language-server, args: [--stdio] }, pyright-lsp: { enabled: true, command: pyright-langserver, args: [--stdio] } }, codeIntelligence: { diagnosticsOnEdit: true, symbolNavigation: true } }几个参数说明command必须和which输出一致--stdio是 LSP 的标准通信方式language server 通过 JSON-RPC 与 Claude Code 通信diagnosticsOnEdit打开后每次文件编辑都会触发类型错误和警告回传symbolNavigation控制 definition、reference、type info 这类按需查询。注意ANTHROPIC_API_KEY不要提交到 git。建议用环境变量注入或者放在用户级配置里项目级配置只保留 plugin 部分。3.3 验证 language server 能独立跑起来在让 Claude Code 调用之前先手动确认 server 本身健康echo {jsonrpc:2.0,id:1,method:initialize,params:{capabilities:{}}} \ | typescript-language-server --stdio如果返回一段带capabilities的 JSON说明 server 能正常握手。这一步能排掉大部分“plugin 装了但没反应”的问题。4. 验证请求从符号导航到跨文件重构4.1 用 TaoToken 通道验证模型连通先确认 Key 和通道没问题用 curl 打一次模型对话接口curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoTokenKey \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 128, messages: [{role: user, content: 回复 ok}] }返回里有正常文本内容说明通道通了。这一步和 LSP 无关但它是后面所有 AI 工具链的地基。想直接在网页里试模型可以用模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。4.2 验证 definition 与 references在 Claude Code 里打开一个 TypeScript 文件让它做一次符号导航帮我找到 OrderService 这个 class 的 definition 位置 然后列出所有 reference 它的文件不要读整个文件只给符号级结果。启用 Code intelligence 后Claude 会走 LSP 的 definition 和 find references而不是 grep。你会看到它给出的是一组精确的符号位置而不是一堆包含OrderService字样的行。如果它还在大段读文件说明 plugin 没生效回到第 3 节检查 binary 和配置。4.3 验证 edit 后的 diagnostics故意制造一个类型错误看 Claude 能不能在同一轮发现把 OrderService 里 createOrder 方法的返回类型从 PromiseOrder 改成 PromiseOrderDTO 先不要改调用方。保存后language server 会分析变化并把 type errors 回传给 Claude。正常情况下Claude 会主动指出调用方类型不匹配并询问是否一起修。这就是 diagnostics 的价值不用等tsc或测试跑完编辑后立刻拿到红线反馈。4.4 一次跨文件重构验证最后做一次真实重构。假设要把status字段重命名为orderStatus把 Order 类型里的 status 字段重命名为 orderStatus 用 find references 找出所有引用点并同步修改 改完检查 diagnostics 是否还有类型错误。实测下来启用 Code intelligence 后Claude 会沿着符号引用链走而不是全文搜status。它改动的范围更准漏改和误改明显减少。改完后 diagnostics 如果干净说明语义导航这一层真的在工作。对于长期跑编码任务和 Agent 流程的团队可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。5. 本篇常见错排查plugin 装了但 LSP tool 还是 inactive。九成是 binary 不在 PATH 里。回到 3.1 用which确认Claude Code 启动 server 时用的是同一个 PATH。diagnostics 一直不出现。先确认diagnosticsOnEdit为 true再确认 language server 能独立握手3.3 那步。如果 server 自己都跑不起来Claude 这边不会有任何反馈。definition 跳转结果为空。多半是项目配置问题。TypeScript 看tsconfig.json的include和pathsPython 看 venv 和 pyright 配置Rust 看 Cargo workspace。language server 解析不了项目语义能力就打折。上下文反而变大了。检查是不是同时开了大量 broad file reads。Code intelligence 的收益来自替代效应如果 Claude 还在全文搜索说明它没走 LSP 路径回去确认 plugin 是否真的启用。改了 settings.json 没生效。配置改动后需要重启 Claude Code session。另外项目级和用户级配置可能冲突优先确认哪一层在起作用。TaoToken 通道报 401。Key 没带对或者被空格污染。用第 4.1 的 curl 单独验证排除是 Claude Code 配置问题还是 Key 本身问题。接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 把语义导航接进你的日常工具链Code intelligence 让 Claude Code 从读文件走向读关系。它不会替代测试不会替代 code review也不会保证业务逻辑一定正确。它降低的是语义定位成本和低级错误成本少读无关文件更快看到类型错误更准地沿着符号关系定位影响范围。配置顺序记住这条线先装 language server binary 并确认which有输出再配 plugin 和settings.json然后用 TaoToken 统一 Key 和 API 通道最后用 definition、references、diagnostics 三步验证。仓库还小的时候普通搜索够用仓库变大以后代码就是一张不断变化的语义网络把这张网的一部分交给 language server 维护再让 Claude Code 按需调用上下文会更干净反馈会更早。如果你要长期跑编码任务或 Agent 流程建议把 Key 管理和通道统一到一处省得每个工具单独折腾。API Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 需要跑长任务就上 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。