LSP 检查

加入版本： @mastra/core@1.1.0

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

何时使用 LSP 检查

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

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

基本用法

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

src/mastra/workspaces.ts

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。

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

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

Tool 最多返回三组结果：

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

重映射 Tool 名称

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

src/mastra/workspaces.ts

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 启动和诊断：

src/mastra/workspaces.ts

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：

src/mastra/workspaces.ts

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 可以同时支持多种语言：

src/mastra/workspaces.ts

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 概述
• 文件系统
• Sandbox
• 搜索和索引
• Workspace 类 Reference