@neurocode-ai/web 1.18.8

package/src/content/docs/zh-tw/plugins.mdx

@@ -0,0 +1,388 @@
+---
+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.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 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(`
+## Custom Context
+
+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` 陣列將被忽略。