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 名稱。設定鍵仍為 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 類別參考