LSP 服务与代码理解

先说结论

mcp-lsp 在指定 workspace 内提供定义、引用、结构、调用关系和诊断。它能帮你快速缩小影响面；最终验收仍要交给架构守卫和测试。

怎么理解

mcp-lsp 是本地 stdio MCP server。它根据目标文件、语言和 workspace roots 选择语言服务，并公开七个工具：

file：读取文件或请求 diagnostics。
structure：查看文件符号结构。
inspect：定位符号定义与详细信息。
xref：查询引用与关系。
grep：文本或 AST 搜索。
patch_edit：patch、rename、code action 与 format。
completion：光标位置补全。

运行时声明 27 个 primary language ID。这是语言路由/注册入口数量，不是 27 种语言都拥有完整、相同且经过验证的 definition、diagnostics、semantic tokens、format 或 completion 能力。别名可能共享 server，发行 bundle 也可能筛选实际启用集合。

Workspace scope 是信任边界。GO_AGENT_LSP_ROOT 指定主根，GO_AGENT_LSP_ROOTS 是由 JSON encoder 生成的绝对路径数组；目标路径超出范围时必须返回 path_outside_workspace，不能自动扩大根目录。

怎么使用

选择 Windows 原生直连、WSL 原生直连，或 Windows Host → WSL2 显式桥接；分别保持 sidecar 的二进制与路径语义一致。
设置 SUPER_DOLPHIN_RUNTIME_MODE、绝对的 SUPER_DOLPHIN_RUNTIME_RESOURCES_DIR、SUPER_DOLPHIN_DEPENDENCY_PROFILE=production 和两个 LSP root 字段。
先调用 file 和 structure 确认目标与语言，再使用 inspect 和 xref 获取语义关系。
修改后调用 file(action=diagnostics)，并把诊断与仓库门禁一起记录。

Go 项目保留 GOTOOLCHAIN=auto 或 <name>+auto；探测会在解析出的 module/go.work 目录运行。JavaScript/TypeScript、Python、Java、SQL 等语言按 registry、依赖和实际语言服务器就绪情况工作。

Windows 原生 Go LSP 使用发行包中的受信 bundle 与 manifest。共享 gopls 生命周期属于实现细节；对使用者可观察的契约是：bundle 身份通过校验、workspace scope 不被扩大，缺少或不匹配时立即失败。

常见问题

缺少 runtime mode/resources：返回 sidecar requires SUPER_DOLPHIN_RUNTIME_MODE and SUPER_DOLPHIN_RUNTIME_RESOURCES_DIR。
缺少 dependency profile：返回 SUPER_DOLPHIN_DEPENDENCY_PROFILE is required for production bootstrap。
path_outside_workspace：核对 command、cwd、resources 和 roots 是否属于同一 Windows/WSL 路径体系。
Windows 原生无法加载 Go LSP：核对 SUPER_DOLPHIN_LSP_BUNDLE_DIR、SUPER_DOLPHIN_LSP_MANIFEST 与包内 gopls.exe；不得用 PATH fallback 掩盖错误。
WSL 仅暴露 file/grep：语义服务器并未就绪；补齐非登录桥接进程的 Linux PATH，再验证 structure、inspect、xref 与 diagnostics。
语言服务冷启动或退出：先看 diagnostics readiness，再重试具体工具；不以客户端显示 enabled 作为成功。
中文、空格或 % 路径异常：roots 使用真实本机 Unicode 路径，只有 file: URI 边界执行一次百分号解码。

适用范围

不同语言支持深度取决于发行 bundle、已安装并验证的语言服务器、平台与上游 capability；primary ID 存在不是完整支持证明。
WSL 原生使用 Linux 二进制和 /mnt/... 路径。Windows host 只有通过显式 wsl.exe 桥接才能启动 Linux sidecar；隐式混用仍不受支持。
GOTOOLCHAIN=local 会关闭自动切换，版本不足时 fail-fast 是预期行为。
LSP 返回“语义证据”，不是业务正确性或安全证明。

延伸阅读

需要接入外部客户端时查看 Harness/LSP 兼容配置；继续产品主线可阅读 Memory、Prompt 与 Skills。