mirror of
https://gitea.toothfairyai.com/ToothFairyAI/tf_code.git
synced 2026-04-09 10:18:57 +00:00
386 lines
8.8 KiB
Plaintext
386 lines
8.8 KiB
Plaintext
---
|
||
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.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 工具和用戶 terminal）：
|
||
|
||
```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(`
|
||
## 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` 數組將被忽略。
|