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

# LSP 檢查

**新增於：** `@mastra/core@1.1.0`

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

## 何時使用 LSP 檢查

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

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

## LSP 設定

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

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

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

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

## 自訂語言伺服器

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

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

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

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

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

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

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

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

## 相關內容

- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)
- [檔案系統](https://mastra.zisheng.pro/zh-HK/docs/workspace/filesystem)
- [Sandbox](https://mastra.zisheng.pro/zh-HK/docs/workspace/sandbox)
- [搜尋與索引](https://mastra.zisheng.pro/zh-HK/docs/workspace/search)
- [Workspace class 參考資料](https://mastra.zisheng.pro/zh-HK/reference/workspace/workspace-class)