企业官网建设流程全解析

Crush LSP 集成指南：3 步让终端 AI 助手读懂你的代码库

【免费下载链接】crushGlamourous agentic coding for all 💘项目地址: https://gitcode.com/gh_mirrors/crush3/crush

如果你用过 Crush——那个跑在终端里的 AI 编程助手——大概率遇到过这样的场景：让它找一个函数的定义，它只能靠 grep 满仓库扫，字符串和注释里的假匹配也分不清。这篇 Crush LSP 集成指南会讲清楚：如何给 Crush 接上一个语言服务器（Language Server），让 AI 从"按文本猜"升级到"按语义查"。全程只需要改一个配置文件。

接入 LSP 后，AI 能多做什么

Crush 内置了一组 LSP 工具，接上语言服务器后它们才真正生效：

• 查定义（lsp_definition）：AI 从此知道"这个函数在哪定义"，返回文件、行号和周边上下文，跳过注释和字符串里的干扰项；
• 查引用（lsp_references）：改一个接口前，先看清哪些地方还在用它；
• 调用层级（lsp_call_hierarchy）：重构前看"谁调用了它、它又调用了谁"，评估影响面；
• 语义重命名（lsp_rename）：跨文件改名交给语言服务器处理，自动尊重作用域、重载和 import，比手工多文件编辑可靠得多；
• 符号级编辑（lsp_replace_symbol）：按名字整体替换/插入/删除一个函数或结构体，靠符号边界定位，不再依赖精确的文本匹配；
• 实时诊断：写代码时语言服务器报出的编译错误、告警会即时同步给 AI，而不是等它自己go build才发现。

这些能力的实现主要在 internal/lsp/ 目录下，协议通信在client.go，多语言服务器的调度在manager.go。

LSP 是个什么东西

一句话：LSP 是让编辑器"听懂"代码语义的通用接口。gopls、pyright、typescript-language-server 这些语言服务器各自精通一门语言，通过同一套协议对外提供定义跳转、诊断、重命名等服务。Crush 的 LSP 集成做的事情，就是替 AI 把这套 IDE 能力接进终端会话。

三步启用一个语言服务器

第 1 步：装好对应的语言服务器二进制

Crush 本身不打包语言服务器，它只负责启动和管理。Go 项目装gopls，TypeScript 项目装typescript-language-server，Nix 项目装nil。确认command -v gopls能找到即可。

第 2 步：在 crush.json 里写一段配置

在项目根目录（或全局配置）的crush.json中加一个lsp段。下面是最小可用的 Go 配置，其余字段可省略：

{ "lsp": { "go": { "command": "gopls", "filetypes": ["go", "mod"], "root_markers": ["go.mod"], "timeout": 60 } } }

不想手改 JSON 的话，也可以在 Crush 的 shell 配置里用lsp add命令完成，比如为 gopls 指定启动命令、文件类型和根目录标记，详见 docs/config/README.md。

第 3 步：确认服务器真的起来了

Crush 启动时会按root_markers找到项目根目录，然后从 PATH 里找二进制并拉起服务器。会话界面能看到各 LSP 客户端的状态（连接中、就绪、报错）；如果诊断迟迟不更新，可以让 AI 调用lsp_restart工具重连，这个工具就是为"服务器卡死了"这种情况准备的。

五个常用配置字段怎么填

• command：语言服务器可执行文件名，必填，其余都围着它转；
• filetypes：这个服务器负责哪些后缀。Crush 靠HandlesFile（见internal/lsp/client.go）按扩展名把文件路由给对应服务器，不填就可能"服务器在跑，但你的文件不归它管"；
• root_markers：项目根标记，如go.mod、package.json、Cargo.toml。多仓库或 monorepo 下，填对了才能保证服务器以正确的目录为工作根；
• env和args：分别给语言服务器注入环境变量和启动参数。比如给 gopls 固定GOTOOLCHAIN、给 typescript-language-server 传--stdio，都在这两个字段里解决；options则用于传递服务器私有设置（本仓库自己的 crush.json 里就给 gopls 开了 staticcheck 和 gofumpt）；
• timeout：初始化超时，单位秒，默认 30。大型项目首启慢的话调到 60 或 120，免得被默认值误杀。

另外配置项支持disabled字段，想临时停掉某个服务器而不删配置时，把它置为 true 即可。

几个容易踩的坑

• 诊断是旧的：改了代码但诊断没刷新，多半是服务器状态异常，先lsp_restart，再怀疑别的东西；
• 跨了工作区：文件不在该 LSP 客户端的cwd之下时会被HandlesFile直接拒掉，多开仓库时注意每个服务器是各自独立的；
• root_markers 漏配：服务器可能启动在错误的目录里，表现是诊断一大片"找不到模块"之类的低级错误；
• 按需启用：只给项目实际用到的语言开 LSP，每个语言服务器都是常驻进程，白开只会吃内存。

常见问题

问：不配置 filetypes 行不行？建议配。虽然有些场景能靠默认值推断，但显式声明后缀（比如 Go 同时挂go和mod）最稳。

问：一个项目多个语言怎么接？lsp段下写多个条目即可，各服务器按 filetypes 分工，互不干扰。

问：配置改了要重启吗？改完crush.json后重新进入 Crush 会话生效；运行中想恢复异常服务器，用lsp_restart就行。

一句话上手

装好语言服务器二进制 →crush.json里加一段带command、filetypes、root_markers的 LSP 配置 → 重启会话确认状态就绪。之后你就可以让 AI 用"查引用""按语义改名"这类 IDE 级操作来干活了。

更多配置项的完整说明见 docs/config/README.md，LSP 客户端与管理器的源码在 internal/lsp/。

【免费下载链接】crushGlamourous agentic coding for all 💘项目地址: https://gitcode.com/gh_mirrors/crush3/crush