OpenCode LSP 指南：作用、启用方法与禁用排错

LSP 是 Language Server Protocol，即语言服务器协议。语言服务器会在项目旁运行，提供诊断、符号、定义、引用、悬停信息等结构化数据。OpenCode 因此可以把代码当作具有语言关系的项目来理解，而不是只读取孤立的文本。

它真正带来的价值是更好的上下文。如果 TypeScript 服务器知道某个符号来自哪个模块，agent 在解释类型错误或重命名时就有更多证据。但 LSP 不保证答案一定正确：服务器可能没有启动，项目可能没有正确加载，语言包也可能有自己的配置要求。它补充工作流信息，不能代替审查、测试和 Git diff。

LSP 条目需要可执行命令，并需要和文件扩展名建立明确关系。命令负责启动服务器，扩展名列表告诉 OpenCode 哪些文件应该使用它。具体可执行文件、参数、安装方法和项目要求取决于语言服务器的文档，不要根据搜索结果猜包名。

先在小仓库中验证一种语言。打开目标扩展名的文件，必要时在同一终端中确认服务器可以启动，再让 OpenCode 做只读摘要或诊断检查。如果扩展名没有匹配，即使服务器本身有效，OpenCode 也没有理由把它连接到当前文件。

整个仓库都需要的 LSP 决策可以放在经过审查的项目配置中。个人实验先放在全局配置，等命令、扩展名和项目根目录都确认后再共享。已有的 OpenCode JSONC 指南适合处理配置层级和 Schema 校验；本页聚焦语言服务器行为。

最小条目比一次加入很多服务器更容易排错。给服务器一个可读的名称，明确写出命令数组，只填写服务器真正支持的扩展名。基础进程正常后再添加初始化参数。JSON 有效不代表运行时一定成功，因为可执行文件、工作区和语言包仍可能不匹配。

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx"]
    }
  }
}

当前官方文档说明：如果省略 lsp，所有 LSP 服务器都会被禁用。如果其他配置已经启用服务器，可以把 lsp 设为 false 来全部关闭；也可以把某个服务器的 disabled 设为 true。服务器慢、输出噪声过多或不适合某个仓库时，这些开关很有用。

自定义服务器适合内置配置没有覆盖的语言或文件类型。先定义命令和扩展名，再根据服务器文档添加初始化参数。保留一份最后可用的配置，每次只改一个点，避免把自定义条目故障误判为模型或 MCP 故障。

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": false
}

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"],
      "initialization": { "preferences": { "mode": "strict" } }
    }
  }
}

不要一开始就让 agent 重写大模块。使用 Git 状态清晰的仓库，打开一个确定的文件，先发起只读请求：让 OpenCode 识别符号、解释诊断或定位定义。结果应当足够具体，能够与编辑器、编译器或你信任的语言服务器输出对照。

只读路径稳定后，再做一次可回滚的小修改并检查 diff。记录系统、服务器命令、扩展名、项目根目录和测试提示词。这份小记录比一句“安装成功”更有用，也能帮助下一次故障定位。

1. 清理从分支和工作树状态明确的仓库开始。
2. 匹配打开 LSP 条目列出的扩展名文件。
3. 读取请求符号、定义、引用或诊断解释。
4. 修改做一次小而可回滚的修改并查看 diff。
5. 记录保存命令、模型、服务器和回滚方式。

当 OpenCode 提示 LSP 被禁用时，先检查配置层级，不要马上重装。更高优先级的文件可能设置了 lsp: false，项目可能没有写服务器名称，或者某个服务器带有 disabled 标记。把最终生效的项目路径和配置文件实际所在目录对照起来。

服务器已启用但没有诊断时，再检查命令和扩展名。尽量在相同 shell 中直接运行服务器，确认运行时和 PATH，并检查项目是否需要 lockfile、编译器配置或工作区根目录。第一次结果较慢，可能只是服务器正在索引大型仓库。

权限调整要保持最小范围。LSP 需要进程和项目上下文，但这不自动意味着可以开放宽泛的 shell、更多 MCP 工具或自动批准模式。权限页负责 ask/allow/deny，MCP 页负责外部工具服务器；跨层排错时再链接它们。

LSP 负责仓库里的语言智能；MCP 连接外部工具或数据；格式化工具改变样式；测试运行器提供可执行证据。VS Code 可以有自己的语言集成，但编辑器显示诊断，并不能证明 OpenCode 使用了同一个服务器或项目根目录。

症状属于其他层时应回到对应指南：MCP 页处理本地和远程工具服务器，VS Code 页处理编辑器上下文和终端集成，权限页处理审批边界。把这些意图分开，也能让 OpenCode LSP 页面保持聚焦。