LSP 檢查

新增於： @mastra/core@1.1.0

LSP 檢查為以 Workspace 為基礎的 Agent 提供語義程式碼智能。當你在 Workspace 啟用 LSP，Agent 便可檢查支援檔案中的符號，以擷取懸停資訊及跳至定義，亦可尋找實作。

何時使用 LSP 檢查

當 Agent 需要理解程式碼語義，而不只是純文字搜尋時，請使用 LSP 檢查：

• 檢查任何支援語言中的符號及其推斷類型
• 在編輯相關程式碼前，找出符號的宣告位置
• 探索整個程式碼庫中的實作，毋須手動追查每個檔案
• 配合 view 和 search_content 使用語義檢查，加快導覽速度
• 透過註冊自訂語言伺服器，為其他語言加入 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 名稱，設定 key 仍為 WORKSPACE_TOOLS.LSP.LSP_INSPECT。

LSP 設定

將 lsp 設為 true 可使用預設行為，亦可提供物件以自訂伺服器啟動及診斷：

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'],
  },
})

在以下情況使用自訂設定：

• 為大型儲存庫延長逾時時間
• 停用特定語言伺服器
• 指示 Mastra 使用自訂語言伺服器二進制檔案
• 在受限環境中加入額外的二進制檔案搜尋路徑

自訂語言伺服器

Mastra 預設內置 TypeScript、JavaScript、Python、Go 及 Rust 支援。如要對其他語言（例如 PHP、Ruby、Java、Kotlin、Swift、Elixir）使用 LSP 檢查，請透過 servers 欄位註冊自訂語言伺服器：

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',
      },
    },
  },
})

每個自訂伺服器定義都需要以下欄位：

欄位	說明
id	伺服器的唯一識別碼
name	在日誌中顯示、方便閱讀的名稱
languageIds	此伺服器處理的 Language Server Protocol (LSP) 語言識別碼
extensions	檔案副檔名，包括句點
markers	用於識別項目根目錄的檔案或目錄（例如 composer.json、Gemfile）
command	啟動伺服器的完整命令字串

當伺服器有多個語言 ID 時，Mastra 會將每個副檔名對應至 languageIds 的第一個項目。

你亦可傳入選用的 initializationOptions，在 LSP 握手期間傳送自訂設定。

自訂伺服器會與內置伺服器合併。如要取代內置伺服器，請使用相同的 id（例如 id: 'go' 會取代內置 Go 伺服器）。註冊多個伺服器，即可同時支援多種語言：

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 檢查只適用於有相符內置或自訂語言伺服器的檔案類型
• 受檢查的 path 必須解析至 Workspace 檔案系統或允許路徑內
• 檢查外部依賴套件時，可能會解析至 .d.ts 等宣告檔案，而非執行階段原始碼檔案
• lsp_inspect 是 view 和 search_content 的補充；需要完整上下文時，仍須閱讀實作程式碼

相關內容

• Workspace 概覽
• 檔案系統
• Sandbox
• 搜尋與索引
• Workspace class 參考資料