第 10 章：工具、權限與 LSP 伺服器

10.1 內建工具系統

OpenCode 提供了一套豐富的內建工具，讓代理能夠讀取、寫入、搜尋、編輯檔案，執行命令，以及與外部服務互動。這些工具是代理與開發環境互動的基本介面。

10.2 權限管理系統

OpenCode 的權限系統讓開發者精確控制每個工具的行為，在便利性與安全性之間取得平衡。每個工具都可以設定三種權限等級：

在 opencode.json 中設定權限

權限設定位於 opencode.json 的頂層 tools 欄位：

{
  "tools": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm -rf *": "deny"
    },
    "write": {
      "*": "ask",
      "src/**": "allow"
    },
    "edit": {
      "*": "ask",
      "*.md": "allow"
    },
    "read": {
      "*": "allow"
    },
    "websearch": {
      "*": "allow"
    },
    "webfetch": {
      "*": "ask",
      "api.github.com/*": "allow"
    }
  }
}

權限規則範例

10.3 細粒度規則：物件語法

除了簡單的字串匹配，OpenCode 的權限系統還支援更精細的物件語法，允許根據工具參數的具體內容進行判斷：

{
  "tools": {
    "bash": {
      "rules": [
        {
          "match": { "command": "git push --force *" },
          "permission": "deny",
          "reason": "禁止強制推送，可能造成歷史遺失"
        },
        {
          "match": { "command": "npm publish *" },
          "permission": "ask",
          "reason": "發佈套件需要人工確認"
        },
        {
          "match": { "command": "git *" },
          "permission": "allow"
        }
      ]
    }
  }
}

這種語法讓權限管理變得極具彈性——你可以針對特定命令參數、檔案路徑、或任何工具輸入內容設定不同的權限策略。

10.4 LSP 伺服器整合

語言伺服器協定（Language Server Protocol, LSP）是 OpenCode 提供即時語法檢查與型別診斷的關鍵技術。每當代理編輯檔案後，OpenCode 會自動查詢 LSP 伺服器獲取診斷結果，並將這些發現回饋給代理，形成閉迴路修正。

內建 LSP 支援列表

OpenCode 內建支援以下語言的 LSP 伺服器，無需額外外掛：

10.5 LSP 設定選項

每個 LSP 伺服器都可以在 opencode.json 中進行細部設定：

{
  "lsp": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "extensions": [".ts", ".tsx", ".js", ".jsx"],
      "priority": 10,
      "env": {
        "NODE_OPTIONS": "--max-old-space-size=4096"
      }
    },
    "python": {
      "command": "pylsp",
      "extensions": [".py"],
      "priority": 5,
      "settings": {
        "pylsp.plugins.pyflakes.enabled": true,
        "pylsp.plugins.mccabe.enabled": false
      }
    },
    "rust": {
      "command": "rust-analyzer",
      "extensions": [".rs"],
      "priority": 10,
      "settings": {
        "rust-analyzer.checkOnSave": true
      }
    }
  }
}

10.6 自訂工具 API

除了內建工具，OpenCode 提供了自訂工具 API，讓開發者可以建立專屬的工具來擴充代理的能力。自訂工具透過 OpenCode SDK 開發，並在 opencode.json 中註冊。

基本結構

{
  "customTools": [
    {
      "name": "send-slack-notification",
      "description": "發送通知到 Slack 頻道",
      "schema": {
        "type": "object",
        "properties": {
          "channel": { "type": "string", "description": "目標頻道名稱" },
          "message": { "type": "string", "description": "要發送的訊息內容" }
        },
        "required": ["channel", "message"]
      },
      "handler": "tools/slack-notifier.js"
    }
  ]
}

📝 本章測驗

❓ 常見問題