連線 LSP 伺服器

你是 OpenCode LSP 設定顧問。

【角色】
OpenCode LSP 設定顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我的主要語言：___
- 想要的能力（診斷 / 跳轉）：___
- 現有 LSP 環境：___
- 專案規模：___
- 經驗水平：___

【工作流程】
1. 說明 LSP 給 agent 帶來什麼
2. 按語言配 server
3. 說明能力和限制
4. 排查常見設定問題
5. 給驗證

【輸出規範】
▌一、LSP 的價值
▌二、按語言設定
▌三、能力 / 限制
▌四、常見問題 + 驗證

【硬約束】
- 按我的語言給確切設定
- LSP 只補理解不替代 review
- 配後實測生效
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法

LSP 讓 OpenCode 拿到更接近 IDE 的程式碼訊號：診斷、副檔名匹配、語言伺服器反饋和部分語言生態的初始化資訊。它適合提高程式碼理解質量，但不應該替代測試、型別檢查和人工 review。

先給結論：LSP 是診斷訊號，不是構建結果

OpenCode 開啟檔案時，如果 LSP 已啟用，會按副檔名匹配對應語言伺服器；滿足依賴要求時，啟動合適的 LSP server，把診斷資訊反饋給 LLM。

flowchart LR
    File["開啟檔案"] --> Match["按副檔名匹配 LSP"]
    Match --> Requirement["檢查依賴 / 命令 / 專案依賴"]
    Requirement --> Server["啟動 language server"]
    Server --> Diagnostics["返回診斷訊號"]
    Diagnostics --> Agent["幫助 agent 判斷程式碼問題"]
    Agent --> Verify["仍需測試 / 型別檢查驗證"]

    style Diagnostics fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style Verify fill:#fee2e2,stroke:#ef4444

適合依賴 LSP 的任務：

• 找定義、引用和跨檔案關係。
• 利用型別錯誤或診斷定位問題。
• 修復區域性語法、型別、匯入和介面不一致。
• 讓 agent 在大型程式碼庫裡少靠全文猜測。

不適合只靠 LSP 判斷的任務：

• 構建是否透過。
• 測試是否覆蓋。
• 執行時行為是否正確。
• 外部 API、資料庫、許可權、部署狀態。

1. 啟用 LSP

官方目前設定裡，如果省略 lsp，所有 LSP server 都是停用狀態。要啟用所有內建 LSP server，顯式寫：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": true
}

如果你想保留內建 server，同時設定覆蓋項或自定義 server，可以寫成物件：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {}
}

2. 內建 LSP 怎麼判斷

OpenCode 內建支援多種語言伺服器，但它們的前提不同。不要把“支援”理解成“所有機器都會自動可用”。

如果你不希望 OpenCode 自動下載 LSP server，可以設定：

export OPENCODE_DISABLE_LSP_DOWNLOAD=true

這適合受管控的企業機器、離線環境、CI 或必須走內部映象的開發環境。

3. 設定項怎麼寫

每個 LSP server entry 支援這些欄位：

官方文件提醒：server entry 通常需要 command，除非它只是用來停用一個 server。

4. 給 server 注入環境變數

例如給 Rust LSP 開除錯記錄：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "rust": {
      "command": ["rust-analyzer"],
      "env": {
        "RUST_LOG": "debug"
      }
    }
  }
}

環境變數只應該放執行時需要的非敏感設定。許可證、token、內部服務憑據不要隨手寫進專案設定。

5. 傳初始化選項

initialization 會在 LSP initialize 請求期間傳送給 server。不同語言伺服器支援的欄位不一樣，要看對應 LSP 文件。

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"],
      "initialization": {
        "preferences": {
          "importModuleSpecifierPreference": "relative"
        }
      }
    }
  }
}

6. 停用 LSP

要在目前設定裡停用所有 LSP server：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": false
}

只停用某個 server：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

適合停用的場景包括：server 啟動慢、診斷噪音過大、monorepo 解析錯誤、企業環境禁止自動下載、某個語言伺服器版本和專案衝突。

7. 新增自定義 LSP server

自定義 server 至少要給 command 和 extensions：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"]
    }
  }
}

先在終端裡確認命令本身可用，再交給 OpenCode：

which custom-lsp-server
custom-lsp-server --help

如果 server 依賴專案根目錄、虛擬環境、SDK 路徑或內部證書，把這些前提寫進專案說明，不要讓 agent 每次重新猜。

8. PHP Intelephense 許可證

PHP Intelephense 的高階功能需要許可證。官方說明可以把許可證金鑰單獨放在文本檔案裡：

• macOS / Linux：$HOME/intelephense/license.txt
• Windows：%USERPROFILE%/intelephense/license.txt

檔案裡只放許可證 key，不要放註釋、賬號、說明或其他內容。

9. 驗收清單

啟用 LSP 後，用這幾項驗收：

• 目標語言的依賴或本機命令可用。
• opencode.json 明確寫了 lsp。
• 自動下載符合目前機器和企業策略。
• 自定義 server 的 command 能在終端獨立執行。
• LSP 診斷和專案 typecheck / lint / test 沒有明顯矛盾。
• 發現噪音或錯誤時，能快速停用單個 server。

接下來去哪

官方資料

• OpenCode LSP Servers：https://opencode.ai/docs/lsp
• OpenCode Tools：https://opencode.ai/docs/tools
• OpenCode Configuration：https://opencode.ai/docs/config
• OpenCode Formatters：https://opencode.ai/docs/formatters