docs: improve zh-cn and zh-tw documentation translations (#13942)
This commit is contained in:
chenmi
@@ -1,21 +1,21 @@
|
||||
---
|
||||
title: 外掛
|
||||
description: 編寫您自己的外掛來擴展 opencode。
|
||||
description: 編寫自己的外掛來擴展 OpenCode。
|
||||
---
|
||||
|
||||
外掛允許您透過掛鉤各種事件和自定義行為來擴展 opencode。您可以建立外掛來新增新功能、與外部服務整合或修改 opencode 的預設行為。
|
||||
外掛允許您透過掛鉤各種事件和自訂行為來擴展 OpenCode。您可以建立外掛來新增新功能、整合外部服務，或修改 OpenCode 的預設行為。
|
||||
|
||||
例如，查看社群建立的[外掛](/docs/ecosystem#plugins)。
|
||||
如需了解範例，請查看社群建立的[外掛](/docs/ecosystem#plugins)。
|
||||
|
||||
---
|
||||
|
||||
## 使用外掛
|
||||
|
||||
有兩種載入外掛的方法。
|
||||
有兩種方式載入外掛。
|
||||
|
||||
---
|
||||
|
||||
### 從本地檔案
|
||||
### 從本地檔案載入
|
||||
|
||||
將 JavaScript 或 TypeScript 檔案放置在外掛目錄中。
|
||||
|
||||
@@ -26,7 +26,7 @@ description: 編寫您自己的外掛來擴展 opencode。
|
||||
|
||||
---
|
||||
|
||||
### 來自 npm
|
||||
### 從 npm 載入
|
||||
|
||||
在設定檔中指定 npm 套件。
|
||||
|
||||
@@ -37,43 +37,42 @@ description: 編寫您自己的外掛來擴展 opencode。
|
||||
}
|
||||
```
|
||||
|
||||
支援常規和範圍 npm 套件。
|
||||
支援常規和帶作用域的 npm 套件。
|
||||
|
||||
瀏覽[生態系統](/docs/ecosystem#plugins)中的可用外掛。
|
||||
|
||||
---
|
||||
|
||||
### 外掛是如何安裝的
|
||||
### 外掛的安裝方式
|
||||
|
||||
**npm 外掛** 在啟動時使用 Bun 自動安裝。套件及其相依套件快取在 `~/.cache/opencode/node_modules/` 中。
|
||||
**npm 外掛**在啟動時使用 Bun 自動安裝。套件及其相依套件會快取在 `~/.cache/opencode/node_modules/` 中。
|
||||
|
||||
**本地外掛**直接從外掛目錄載入。要使用外部套件，您必須在設定目錄中建立 `package.json`（請參閱[相依性](#dependencies)），或將外掛發佈到 npm 和[將其添加到您的設定中](/docs/config#plugins)。
|
||||
**本地外掛**直接從外掛目錄載入。如果需要使用外部套件，您必須在設定目錄中建立 `package.json`（參見[相依套件](#dependencies)），或者將外掛發布到 npm 並[將其新增到設定中](/docs/config#plugins)。
|
||||
|
||||
---
|
||||
|
||||
### 載入順序
|
||||
|
||||
外掛從所有來源載入，所有掛鉤按順序執行。載入順序為：
|
||||
外掛從所有來源載入，所有鉤子按順序執行。載入順序為：
|
||||
|
||||
1. 全域設定 (`~/.config/opencode/opencode.json`)
|
||||
2. 專案設定（`opencode.json`）
|
||||
2. 專案設定 (`opencode.json`)
|
||||
3. 全域外掛目錄 (`~/.config/opencode/plugins/`)
|
||||
4. 專案外掛目錄(`.opencode/plugins/`)
|
||||
4. 專案外掛目錄 (`.opencode/plugins/`)
|
||||
|
||||
具有相同名稱和版本的重複 npm 套件將被載入一次。但是，本地外掛和名稱相似的 npm 外掛都是分開載入的。
|
||||
名稱和版本相同的重複 npm 套件只會載入一次。但本地外掛和名稱相似的 npm 外掛會分別獨立載入。
|
||||
|
||||
---
|
||||
|
||||
## 建立一個外掛
|
||||
## 建立外掛
|
||||
|
||||
外掛是一個 **JavaScript/TypeScript 模組**，它匯出一個或多個外掛
|
||||
函式。每個函式接收一個上下文物件並返回一個掛鉤物件。
|
||||
外掛是一個 **JavaScript/TypeScript 模組**，它匯出一個或多個外掛函式。每個函式接收一個上下文物件，並回傳一個鉤子物件。
|
||||
|
||||
---
|
||||
|
||||
### 相依性
|
||||
### 相依套件
|
||||
|
||||
本地外掛和自定義工具可以使用外部 npm 套件。將 `package.json` 添加到您的設定目錄，其中包含您需要的相依套件。
|
||||
本地外掛和自訂工具可以使用外部 npm 套件。在設定目錄中新增一個 `package.json`，列出所需的相依套件。
|
||||
|
||||
```json title=".opencode/package.json"
|
||||
{
|
||||
@@ -83,7 +82,7 @@ description: 編寫您自己的外掛來擴展 opencode。
|
||||
}
|
||||
```
|
||||
|
||||
opencode 在啟動時執行 `bun install` 來安裝這些。然後您的外掛和工具就可以匯入它們。
|
||||
OpenCode 會在啟動時執行 `bun install` 來安裝這些相依套件。之後您的外掛和工具就可以匯入它們了。
|
||||
|
||||
```ts title=".opencode/plugins/my-plugin.ts"
|
||||
import { escape } from "shescape"
|
||||
@@ -113,13 +112,13 @@ export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
|
||||
}
|
||||
```
|
||||
|
||||
外掛函式接收：
|
||||
外掛函式接收以下參數：
|
||||
|
||||
- `project`：當前專案資訊。
|
||||
- `directory`：當前工作目錄。
|
||||
- `worktree`：git 工作樹路徑。
|
||||
- `client`：用於與 AI 互動的 opencode SDK 客戶端。
|
||||
- `$`：Bun 的 [shell API](https://bun.com/docs/runtime/shell) 用於執行指令。
|
||||
- `client`：用於與 AI 互動的 OpenCode SDK 用戶端。
|
||||
- `$`：Bun 的 [Shell API](https://bun.com/docs/runtime/shell)，用於執行指令。
|
||||
|
||||
---
|
||||
|
||||
@@ -141,7 +140,7 @@ export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree
|
||||
|
||||
### 事件
|
||||
|
||||
外掛可以訂閱事件，如下面的範例部分所示。以下是可用的不同事件的列表。
|
||||
外掛可以訂閱事件，如下方範例部分所示。以下是所有可用事件的列表。
|
||||
|
||||
#### 指令事件
|
||||
|
||||
@@ -188,7 +187,7 @@ export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree
|
||||
- `session.status`
|
||||
- `session.updated`
|
||||
|
||||
#### Todo 事件
|
||||
#### 待辦事項事件
|
||||
|
||||
- `todo.updated`
|
||||
|
||||
@@ -211,13 +210,13 @@ export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree
|
||||
|
||||
## 範例
|
||||
|
||||
以下是一些可用於擴展 opencode 的外掛範例。
|
||||
以下是一些可用於擴展 OpenCode 的外掛範例。
|
||||
|
||||
---
|
||||
|
||||
### 發送通知
|
||||
### 傳送通知
|
||||
|
||||
當某些事件發生時發送通知：
|
||||
在特定事件發生時傳送通知：
|
||||
|
||||
```js title=".opencode/plugins/notification.js"
|
||||
export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
|
||||
@@ -232,17 +231,17 @@ export const NotificationPlugin = async ({ project, client, $, directory, worktr
|
||||
}
|
||||
```
|
||||
|
||||
我們使用 `osascript` 在 macOS 上執行 AppleScript。這裡我們用它來發送通知。
|
||||
這裡使用 `osascript` 在 macOS 上執行 AppleScript 來傳送通知。
|
||||
|
||||
:::note
|
||||
如果您使用 opencode 桌面應用程式，它可以在回應準備就緒或工作階段出錯時自動發送系統通知。
|
||||
如果您使用 OpenCode 桌面應用程式，它可以在回應就緒或工作階段出錯時自動傳送系統通知。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### .env 保護
|
||||
|
||||
阻止 opencode 讀取 `.env` 檔案：
|
||||
阻止 OpenCode 讀取 `.env` 檔案：
|
||||
|
||||
```javascript title=".opencode/plugins/env-protection.js"
|
||||
export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
|
||||
@@ -260,7 +259,7 @@ export const EnvProtection = async ({ project, client, $, directory, worktree })
|
||||
|
||||
### 注入環境變數
|
||||
|
||||
將環境變數注入所有 shell 執行（AI 工具和使用者終端機）：
|
||||
將環境變數注入所有 Shell 執行（AI 工具和使用者終端機）：
|
||||
|
||||
```javascript title=".opencode/plugins/inject-env.js"
|
||||
export const InjectEnvPlugin = async () => {
|
||||
@@ -275,9 +274,9 @@ export const InjectEnvPlugin = async () => {
|
||||
|
||||
---
|
||||
|
||||
### 自定義工具
|
||||
### 自訂工具
|
||||
|
||||
外掛還可以向 opencode 添加自定義工具：
|
||||
外掛還可以為 OpenCode 新增自訂工具：
|
||||
|
||||
```ts title=".opencode/plugins/custom-tools.ts"
|
||||
import { type Plugin, tool } from "@opencode-ai/plugin"
|
||||
@@ -300,19 +299,19 @@ export const CustomToolsPlugin: Plugin = async (ctx) => {
|
||||
}
|
||||
```
|
||||
|
||||
`tool` 輔助程式建立一個 opencode 可以呼叫的自定義工具。它採用 Zod 模式函式並返回一個工具定義：
|
||||
`tool` 輔助函式用於建立 OpenCode 可呼叫的自訂工具。它接受一個 Zod schema 函式，並回傳一個工具定義，包含：
|
||||
|
||||
- `description`：該工具的作用
|
||||
- `args`：工具參數的 Zod 模式
|
||||
- `execute`：呼叫工具時執行的函式
|
||||
- `description`：工具的功能描述
|
||||
- `args`：工具參數的 Zod schema
|
||||
- `execute`：工具被呼叫時執行的函式
|
||||
|
||||
您的自定義工具將可與內建工具一起用於 opencode。
|
||||
您的自訂工具將與內建工具一起在 OpenCode 中可用。
|
||||
|
||||
---
|
||||
|
||||
### 記錄
|
||||
### 日誌記錄
|
||||
|
||||
使用 `client.app.log()` 而不是 `console.log` 進行結構化記錄：
|
||||
使用 `client.app.log()` 代替 `console.log` 進行結構化日誌記錄：
|
||||
|
||||
```ts title=".opencode/plugins/my-plugin.ts"
|
||||
export const MyPlugin = async ({ client }) => {
|
||||
@@ -327,13 +326,13 @@ export const MyPlugin = async ({ client }) => {
|
||||
}
|
||||
```
|
||||
|
||||
等級：`debug`、`info`、`warn`、`error`。詳情請參閱 [SDK 文件](https://opencode.ai/docs/sdk)。
|
||||
日誌層級：`debug`、`info`、`warn`、`error`。詳情請參閱 [SDK 文件](https://opencode.ai/docs/sdk)。
|
||||
|
||||
---
|
||||
|
||||
### 壓縮掛鉤
|
||||
### 壓縮鉤子
|
||||
|
||||
自定義壓縮工作階段時包含的上下文：
|
||||
自訂工作階段壓縮時包含的上下文：
|
||||
|
||||
```ts title=".opencode/plugins/compaction.ts"
|
||||
import type { Plugin } from "@opencode-ai/plugin"
|
||||
@@ -343,7 +342,7 @@ export const CompactionPlugin: Plugin = async (ctx) => {
|
||||
"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
|
||||
@@ -355,9 +354,9 @@ Include any state that should persist across compaction:
|
||||
}
|
||||
```
|
||||
|
||||
`experimental.session.compacting` 掛鉤在 LLM 生成延續摘要之前觸發。使用它來注入預設壓縮提示會錯過的特定於域的上下文。
|
||||
`experimental.session.compacting` 鉤子在 LLM 生成續接摘要之前觸發。使用它來注入預設壓縮提示詞可能遺漏的領域特定上下文。
|
||||
|
||||
您還可以透過設定 `output.prompt` 來完全替換壓縮提示：
|
||||
您還可以透過設定 `output.prompt` 來完全替換壓縮提示詞：
|
||||
|
||||
```ts title=".opencode/plugins/custom-compaction.ts"
|
||||
import type { Plugin } from "@opencode-ai/plugin"
|
||||
@@ -382,4 +381,4 @@ Format as a structured prompt that a new agent can use to resume work.
|
||||
}
|
||||
```
|
||||
|
||||
當設定 `output.prompt` 時，它完全取代預設的壓縮提示。在這種情況下，`output.context` 陣列將被忽略。
|
||||
當設定了 `output.prompt` 時，它會完全替換預設的壓縮提示詞。在這種情況下，`output.context` 陣列將被忽略。
|
||||
|
||||
Reference in New Issue
Block a user