LSP 配置

English | 中文 本指南说明如何为 OMP coding agent 配置 language server。

代码中的事实来源:

• Server config type:packages/coding-agent/src/lsp/types.ts（ServerConfig）
• Config loader:packages/coding-agent/src/lsp/config.ts
• 内置 server 定义:packages/coding-agent/src/lsp/defaults.json

自动检测

当不存在 LSP config 文件时，OMP 通过对两个条件的交集进行自动检测:

1. 项目目录包含该 server 的至少一个 rootMarkers。
2. 该 server 二进制文件可用——先检查项目本地 bin 目录（例如 node_modules/.bin/、.venv/bin/），然后检查 $PATH。

常见配置无需手动配置。内置 server 列表覆盖大多数主流语言；完整集合见 defaults.json。

配置文件位置

OMP 从多个文件合并 LSP 配置，从低到高优先级:

每个位置都接受 .json、.yaml 和 .yml 变体，包括隐藏文件版本（.lsp.json、.lsp.yaml、.lsp.yml）。文件按顺序合并:更高优先级的文件对同一 server 覆盖更低优先级的字段。在任何 override 文件中都未提到的 server 保持其内置默认值。

推荐位置:

• 用户级偏好 → ~/.musepi/agent/lsp.json
• 项目特定 override → <project>/.musepi/lsp.json

注意: 仅当至少一个配置文件贡献 server overrides 时，才会跳过自动检测。只设置 idleTimeoutMs 的配置文件仍允许 OMP 自动检测内置 servers。当存在 server overrides 时，OMP 将它们与 defaults 合并，然后加载具有匹配 rootMarkers、可用二进制文件且未显式 disabled 的 servers。

文件结构

JSON 和 YAML 都被接受。顶层对象可以使用 servers 包装键，也可以直接使用 flat map:

{
  "servers": {
    "server-name": { ... }
  },
  "idleTimeoutMs": 300000
}

或（flat，不带 servers 包装）:

{
  "server-name": { ... },
  "idleTimeoutMs": 300000
}

顶层键:

• servers — server 名称到 ServerConfig 的映射（可选包装；flat 形式等价）
• idleTimeoutMs — 在指定毫秒数后关闭空闲 language server；默认禁用

ServerConfig 字段

resolvedCommand 会在运行时自动填充——不要手动设置。

Capabilities

capabilities 对象启用 OMP 按 server 支持的可选特性:

{
  "capabilities": {
    "flycheck": true,
    "ssr": true,
    "expandMacro": true,
    "runnables": true,
    "relatedTests": true
  }
}

所有字段都是布尔值且可选。目前仅 rust-analyzer 使用它们。

常见做法

覆盖内置 server 的设置

部分覆盖会合并到内置默认值上。你只需指定要更改的字段。

{
  "servers": {
    "typescript-language-server": {
      "args": ["--stdio", "--log-level", "4"]
    }
  }
}

servers:
  gopls:
    settings:
      gopls:
        gofumpt: false
        staticcheck: false

禁用内置 server

{
  "servers": {
    "eslint": {
      "disabled": true
    }
  }
}

注册自定义 server

新 server 需要 command、fileTypes 和 rootMarkers。所有其他字段都是可选的。

{
  "servers": {
    "my-lsp": {
      "command": "my-lsp-server",
      "args": ["--stdio"],
      "fileTypes": [".xyz"],
      "rootMarkers": [".xyz-project", ".git"]
    }
  }
}

设置全局空闲超时

关闭空闲超过五分钟的 language server:

{
  "idleTimeoutMs": 300000
}

在单个项目中禁用 server，全局保留

将 override 放在 <project>/.musepi/lsp.json:

{
  "servers": {
    "pylsp": {
      "disabled": true
    }
  }
}

~/.musepi/agent/lsp.json 中的用户级配置不受影响；pylsp 仅在这个项目中被抑制。

内置 server 列表

以下 servers 包含在 defaults.json 中，并且符合自动检测条件: