> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# LSP 检查

**加入版本：** `@mastra/core@1.1.0`

LSP 检查为由 Workspace 支持的 Agent 提供语义代码智能。在 Workspace 上启用 LSP 后，Agent 可以检查受支持文件中的符号、获取 hover 信息、跳转到定义，还可以查找实现。

## 何时使用 LSP 检查

当 Agent 不仅需要纯文本搜索，还需要理解代码语义时，请使用 LSP 检查：

- 检查任何受支持语言中的符号及其推断类型
- 在编辑相关代码前查找符号的声明位置
- 无需手动跟踪每个文件，即可探索整个代码库中的实现
- 将语义检查与 `view`、`search_content` 结合使用，加快导航
- 通过[注册自定义 Language Server](#custom-language-servers)为其他语言添加 LSP 支持

## 基本用法

设置 `lsp: true`，在 Workspace 上启用 LSP：

```typescript
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  lsp: true,
})
```

使用此配置后，Workspace 会在已配置的文件系统和 Sandbox Tool 之外注册默认 LSP 检查 Tool。

## Agent Tool

启用 LSP 后，Workspace 默认会暴露 `mastra_workspace_lsp_inspect`。

```json
{
  "path": "/absolute/path/to/file.ts",
  "line": 10,
  "match": "const foo = <<<bar()"
}
```

`match` 字段必须且只能包含一个 `<<<` 光标标记。该标记用于标识指定行上的符号位置。

Tool 最多返回三组结果：

| 结果               | 说明                         |
| ---------------- | -------------------------- |
| `hover`          | 光标位置符号的类型信息或文档             |
| `diagnostics`    | 检查行存在问题时，返回限定于该行的 LSP 诊断信息 |
| `definition`     | 声明位置及单行预览                  |
| `implementation` | 实现或使用位置                    |

## 重映射 Tool 名称

如果 Agent 需要更短的名称，可以重命名 Tool：

```typescript
import { Workspace, LocalFilesystem, WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  lsp: true,
  tools: {
    [WORKSPACE_TOOLS.LSP.LSP_INSPECT]: {
      name: 'lsp_inspect',
    },
  },
})
```

这只会更改暴露的 Tool 名称。配置键仍为 `WORKSPACE_TOOLS.LSP.LSP_INSPECT`。

## LSP 配置

将 `lsp` 设为 `true` 可使用默认行为，也可以提供对象来定制 Server 启动和诊断：

```typescript
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  lsp: {
    diagnosticTimeout: 4000,
    initTimeout: 8000,
    disableServers: ['eslint'],
    binaryOverrides: {
      typescript: '/custom/path/to/typescript-language-server --stdio',
    },
    searchPaths: ['/opt/homebrew/bin'],
  },
})
```

在以下情况下使用自定义配置：

- 为大型仓库延长超时时间
- 禁用特定 Language Server
- 让 Mastra 使用自定义 Language Server 二进制文件
- 在受限环境中添加额外的二进制文件搜索路径

## 自定义 Language Server

Mastra 默认内置对 TypeScript、JavaScript、Python、Go 和 Rust 的支持。若要在其他语言（例如 PHP、Ruby、Java、Kotlin、Swift、Elixir）中使用 LSP 检查，请通过 `servers` 字段注册自定义 Language Server：

```typescript
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  lsp: {
    servers: {
      phpactor: {
        id: 'phpactor',
        name: 'Phpactor Language Server',
        languageIds: ['php'],
        extensions: ['.php'],
        markers: ['composer.json'],
        command: 'phpactor language-server',
      },
    },
  },
})
```

每项自定义 Server 定义都需要以下字段：

| 字段            | 说明                                              |
| ------------- | ----------------------------------------------- |
| `id`          | Server 的唯一标识符                                   |
| `name`        | 日志中显示的人类可读名称                                    |
| `languageIds` | 该 Server 处理的 Language Server Protocol（LSP）语言标识符 |
| `extensions`  | 包含句点的文件扩展名                                      |
| `markers`     | 用于标识项目根目录的文件或目录（例如 `composer.json`、`Gemfile`）   |
| `command`     | 启动 Server 的完整命令字符串                              |

如果 Server 有多个语言 ID，Mastra 会将每个扩展名映射到 `languageIds` 中的第一项。

还可以传入可选的 `initializationOptions`，在 LSP handshake 期间发送自定义设置。

自定义 Server 会与内置 Server 合并。若要替换内置 Server，请使用相同的 `id`（例如 `id: 'go'` 会替换内置 Go Server）。注册多个 Server 可以同时支持多种语言：

```typescript
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  lsp: {
    servers: {
      phpactor: {
        id: 'phpactor',
        name: 'Phpactor Language Server',
        languageIds: ['php'],
        extensions: ['.php'],
        markers: ['composer.json'],
        command: 'phpactor language-server',
      },
      solargraph: {
        id: 'solargraph',
        name: 'Solargraph',
        languageIds: ['ruby'],
        extensions: ['.rb', '.erb'],
        markers: ['Gemfile'],
        command: 'solargraph stdio',
      },
    },
  },
})
```

## 要求和限制

- LSP 检查仅适用于具有匹配的内置或自定义 Language Server 的文件类型
- 检查的 `path` 必须解析到 Workspace 文件系统或允许的路径内
- 检查外部包时，可能解析到 `.d.ts` 等声明文件，而不是运行时源文件
- `lsp_inspect` 是 `view` 和 `search_content` 的补充；需要完整上下文时，它不能代替阅读实现代码

## 相关内容

- [Workspace 概述](https://mastra.zisheng.pro/docs/workspace/overview)
- [文件系统](https://mastra.zisheng.pro/docs/workspace/filesystem)
- [Sandbox](https://mastra.zisheng.pro/docs/workspace/sandbox)
- [搜索和索引](https://mastra.zisheng.pro/docs/workspace/search)
- [Workspace 类 Reference](https://mastra.zisheng.pro/reference/workspace/workspace-class)