| --- |
| title: 外掛 |
| description: 編寫自己的外掛來擴展 OpenCode。 |
| --- |
| |
| 外掛允許您透過掛鉤各種事件和自訂行為來擴展 OpenCode。您可以建立外掛來新增新功能、整合外部服務，或修改 OpenCode 的預設行為。 |
|
|
| 如需了解範例，請查看社群建立的[外掛](/docs/ecosystem#plugins)。 |
|
|
| --- |
| |
| |
|
|
| 有兩種方式載入外掛。 |
|
|
| --- |
| |
| |
|
|
| 將 JavaScript 或 TypeScript 檔案放置在外掛目錄中。 |
|
|
| - `.opencode/plugins/` - 專案級外掛 |
| - `~/.config/opencode/plugins/` - 全域外掛 |
|
|
| 這些目錄中的檔案會在啟動時自動載入。 |
|
|
| --- |
| |
| |
|
|
| 在設定檔中指定 npm 套件。 |
|
|
| ```json title="opencode.json" |
| { |
| "$schema": "https://opencode.ai/config.json", |
| "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"] |
| } |
| ``` |
|
|
| 支援常規和帶作用域的 npm 套件。 |
|
|
| 瀏覽[生態系統](/docs/ecosystem#plugins)中的可用外掛。 |
|
|
| --- |
| |
| |
|
|
| **npm 外掛**在啟動時使用 Bun 自動安裝。套件及其相依套件會快取在 `~/.cache/opencode/node_modules/` 中。 |
|
|
| **本地外掛**直接從外掛目錄載入。如果需要使用外部套件，您必須在設定目錄中建立 `package.json`（參見[相依套件](#dependencies)），或者將外掛發布到 npm 並[將其新增到設定中](/docs/config#plugins)。 |
|
|
| --- |
| |
| |
|
|
| 外掛從所有來源載入，所有鉤子按順序執行。載入順序為： |
|
|
| 1. 全域設定 (`~/.config/opencode/opencode.json`) |
| 2. 專案設定 (`opencode.json`) |
| 3. 全域外掛目錄 (`~/.config/opencode/plugins/`) |
| 4. 專案外掛目錄 (`.opencode/plugins/`) |
|
|
| 名稱和版本相同的重複 npm 套件只會載入一次。但本地外掛和名稱相似的 npm 外掛會分別獨立載入。 |
|
|
| --- |
| |
| |
|
|
| 外掛是一個 **JavaScript/TypeScript 模組**，它匯出一個或多個外掛函式。每個函式接收一個上下文物件，並回傳一個鉤子物件。 |
|
|
| --- |
| |
| |
|
|
| 本地外掛和自訂工具可以使用外部 npm 套件。在設定目錄中新增一個 `package.json`，列出所需的相依套件。 |
|
|
| ```json title=".opencode/package.json" |
| { |
| "dependencies": { |
| "shescape": "^2.1.0" |
| } |
| } |
| ``` |
|
|
| OpenCode 會在啟動時執行 `bun install` 來安裝這些相依套件。之後您的外掛和工具就可以匯入它們了。 |
|
|
| ```ts title=".opencode/plugins/my-plugin.ts" |
| import { escape } from "shescape" |
|
|
| export const MyPlugin = async (ctx) => { |
| return { |
| "tool.execute.before": async (input, output) => { |
| if (input.tool === "bash") { |
| output.args.command = escape(output.args.command) |
| } |
| }, |
| } |
| } |
| ``` |
|
|
| --- |
| |
| |
|
|
| ```js title=".opencode/plugins/example.js" |
| export const MyPlugin = async ({ project, client, $, directory, worktree }) => { |
| console.log("Plugin initialized!") |
|
|
| return { |
| // Hook implementations go here |
| } |
| } |
| ``` |
|
|
| 外掛函式接收以下參數： |
|
|
| - `project`：當前專案資訊。 |
| - `directory`：當前工作目錄。 |
| - `worktree`：git 工作樹路徑。 |
| - `client`：用於與 AI 互動的 OpenCode SDK 用戶端。 |
| - `$`：Bun 的 [Shell API](https://bun.com/docs/runtime/shell)，用於執行指令。 |
|
|
| --- |
| |
| |
|
|
| 對於 TypeScript 外掛，您可以從外掛套件中匯入類型： |
|
|
| ```ts title="my-plugin.ts" {1} |
| import type { Plugin } from "@opencode-ai/plugin" |
|
|
| export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => { |
| return { |
| // Type-safe hook implementations |
| } |
| } |
| ``` |
|
|
| --- |
| |
| |
|
|
| 外掛可以訂閱事件，如下方範例部分所示。以下是所有可用事件的列表。 |
|
|
| |
|
|
| - `command.executed` |
|
|
| |
|
|
| - `file.edited` |
| - `file.watcher.updated` |
|
|
| |
|
|
| - `installation.updated` |
|
|
| |
|
|
| - `lsp.client.diagnostics` |
| - `lsp.updated` |
|
|
| |
|
|
| - `message.part.removed` |
| - `message.part.updated` |
| - `message.removed` |
| - `message.updated` |
|
|
| |
|
|
| - `permission.asked` |
| - `permission.replied` |
|
|
| |
|
|
| - `server.connected` |
|
|
| |
|
|
| - `session.created` |
| - `session.compacted` |
| - `session.deleted` |
| - `session.diff` |
| - `session.error` |
| - `session.idle` |
| - `session.status` |
| - `session.updated` |
|
|
| |
|
|
| - `todo.updated` |
|
|
| |
|
|
| - `shell.env` |
|
|
| |
|
|
| - `tool.execute.after` |
| - `tool.execute.before` |
|
|
| |
|
|
| - `tui.prompt.append` |
| - `tui.command.execute` |
| - `tui.toast.show` |
|
|
| --- |
| |
| |
|
|
| 以下是一些可用於擴展 OpenCode 的外掛範例。 |
|
|
| --- |
| |
| |
|
|
| 在特定事件發生時傳送通知： |
|
|
| ```js title=".opencode/plugins/notification.js" |
| export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => { |
| return { |
| event: async ({ event }) => { |
| // Send notification on session completion |
| if (event.type === "session.idle") { |
| await $`osascript -e 'display notification "Session completed!" with title "opencode"'` |
| } |
| }, |
| } |
| } |
| ``` |
|
|
| 這裡使用 `osascript` 在 macOS 上執行 AppleScript 來傳送通知。 |
|
|
| :::note |
| 如果您使用 OpenCode 桌面應用程式，它可以在回應就緒或工作階段出錯時自動傳送系統通知。 |
| ::: |
|
|
| --- |
| |
| |
|
|
| 阻止 OpenCode 讀取 `.env` 檔案： |
|
|
| ```javascript title=".opencode/plugins/env-protection.js" |
| export const EnvProtection = async ({ project, client, $, directory, worktree }) => { |
| return { |
| "tool.execute.before": async (input, output) => { |
| if (input.tool === "read" && output.args.filePath.includes(".env")) { |
| throw new Error("Do not read .env files") |
| } |
| }, |
| } |
| } |
| ``` |
|
|
| --- |
| |
| |
|
|
| 將環境變數注入所有 Shell 執行（AI 工具和使用者終端機）： |
|
|
| ```javascript title=".opencode/plugins/inject-env.js" |
| export const InjectEnvPlugin = async () => { |
| return { |
| "shell.env": async (input, output) => { |
| output.env.MY_API_KEY = "secret" |
| output.env.PROJECT_ROOT = input.cwd |
| }, |
| } |
| } |
| ``` |
|
|
| --- |
| |
| |
|
|
| 外掛還可以為 OpenCode 新增自訂工具： |
|
|
| ```ts title=".opencode/plugins/custom-tools.ts" |
| import { type Plugin, tool } from "@opencode-ai/plugin" |
|
|
| export const CustomToolsPlugin: Plugin = async (ctx) => { |
| return { |
| tool: { |
| mytool: tool({ |
| description: "This is a custom tool", |
| args: { |
| foo: tool.schema.string(), |
| }, |
| async execute(args, context) { |
| const { directory, worktree } = context |
| return `Hello ${args.foo} from ${directory} (worktree: ${worktree})` |
| }, |
| }), |
| }, |
| } |
| } |
| ``` |
|
|
| `tool` 輔助函式用於建立 OpenCode 可呼叫的自訂工具。它接受一個 Zod schema 函式，並回傳一個工具定義，包含： |
|
|
| - `description`：工具的功能描述 |
| - `args`：工具參數的 Zod schema |
| - `execute`：工具被呼叫時執行的函式 |
|
|
| 您的自訂工具將與內建工具一起在 OpenCode 中可用。 |
|
|
| :::note |
| 如果外掛工具使用與內建工具相同的名稱，則外掛工具具有優先權。 |
| ::: |
|
|
| --- |
| |
| |
|
|
| 使用 `client.app.log()` 代替 `console.log` 進行結構化日誌記錄： |
|
|
| ```ts title=".opencode/plugins/my-plugin.ts" |
| export const MyPlugin = async ({ client }) => { |
| await client.app.log({ |
| body: { |
| service: "my-plugin", |
| level: "info", |
| message: "Plugin initialized", |
| extra: { foo: "bar" }, |
| }, |
| }) |
| } |
| ``` |
|
|
| 日誌層級：`debug`、`info`、`warn`、`error`。詳情請參閱 [SDK 文件](https://opencode.ai/docs/sdk)。 |
|
|
| --- |
| |
| |
|
|
| 自訂工作階段壓縮時包含的上下文： |
|
|
| ```ts title=".opencode/plugins/compaction.ts" |
| import type { Plugin } from "@opencode-ai/plugin" |
|
|
| export const CompactionPlugin: Plugin = async (ctx) => { |
| return { |
| "experimental.session.compacting": async (input, output) => { |
| // Inject additional context into the compaction prompt |
| output.context.push(` |
| |
|
|
| Include any state that should persist across compaction: |
| - Current task status |
| - Important decisions made |
| - Files being actively worked on |
| `) |
| }, |
| } |
| } |
| ``` |
|
|
| `experimental.session.compacting` 鉤子在 LLM 生成續接摘要之前觸發。使用它來注入預設壓縮提示詞可能遺漏的領域特定上下文。 |
|
|
| 您還可以透過設定 `output.prompt` 來完全替換壓縮提示詞： |
|
|
| ```ts title=".opencode/plugins/custom-compaction.ts" |
| import type { Plugin } from "@opencode-ai/plugin" |
|
|
| export const CustomCompactionPlugin: Plugin = async (ctx) => { |
| return { |
| "experimental.session.compacting": async (input, output) => { |
| // Replace the entire compaction prompt |
| output.prompt = ` |
| You are generating a continuation prompt for a multi-agent swarm session. |
|
|
| Summarize: |
| 1. The current task and its status |
| 2. Which files are being modified and by whom |
| 3. Any blockers or dependencies between agents |
| 4. The next steps to complete the work |
|
|
| Format as a structured prompt that a new agent can use to resume work. |
| ` |
| }, |
| } |
| } |
| ``` |
|
|
| 當設定了 `output.prompt` 時，它會完全替換預設的壓縮提示詞。在這種情況下，`output.context` 陣列將被忽略。 |
|
|
