path: root/packages/web/src/content/docs/zh-tw/plugins.mdx

---
title: 外掛
description: 編寫您自己的外掛來擴展 opencode。
---

外掛允許您透過掛鉤各種事件和自定義行為來擴展 opencode。您可以建立外掛來新增新功能、與外部服務整合或修改 opencode 的預設行為。

例如，查看社群建立的[外掛](/docs/ecosystem#plugins)。

---

## 使用外掛

有兩種載入外掛的方法。

---

### 從本地檔案

將 JavaScript 或 TypeScript 檔案放置在外掛目錄中。

- `.opencode/plugins/` - 專案級外掛
- `~/.config/opencode/plugins/` - 全域外掛

這些目錄中的檔案會在啟動時自動載入。

---

### 來自 npm

在設定檔中指定 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 支援

對於 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 事件

- `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 事件

- `todo.updated`

#### Shell 事件

- `shell.env`

#### 工具事件

- `tool.execute.after`
- `tool.execute.before`

#### TUI 事件

- `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 桌面應用程式，它可以在回應準備就緒或工作階段出錯時自動發送系統通知。
:::

---

### .env 保護

阻止 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 模式函式並返回一個工具定義：

- `description`：該工具的作用
- `args`：工具參數的 Zod 模式
- `execute`：呼叫工具時執行的函式

您的自定義工具將可與內建工具一起用於 opencode。

---

### 記錄

使用 `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` 陣列將被忽略。