> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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 名稱。設定鍵仍為 `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-TW/docs/workspace/overview)
- [檔案系統](https://mastra.zisheng.pro/zh-TW/docs/workspace/filesystem)
- [Sandbox](https://mastra.zisheng.pro/zh-TW/docs/workspace/sandbox)
- [搜尋與索引](https://mastra.zisheng.pro/zh-TW/docs/workspace/search)
- [Workspace 類別參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/workspace-class)