386 lines
9.9 KiB
Plaintext
386 lines
9.9 KiB
Plaintext
---
|
|
title: Plugins
|
|
description: Write your own plugins to extend OpenCode.
|
|
---
|
|
|
|
플러그인은 다양한 이벤트와 사용자 정의 행동으로 후킹하여 OpenCode를 확장 할 수 있습니다. 플러그인을 만들 수 있습니다 새로운 기능을 추가, 외부 서비스와 통합, 또는 OpenCode의 기본 동작을 수정.
|
|
|
|
예를 들어, 커뮤니티에 의해 생성 된 [plugins](/docs/ecosystem#plugins)를 확인하십시오.
|
|
|
|
---
|
|
|
|
## 플러그인 사용
|
|
|
|
플러그인을로드하는 두 가지 방법이 있습니다.
|
|
|
|
---
|
|
|
|
## 현지 파일에서
|
|
|
|
플러그인 디렉토리에 JavaScript 또는 TypeScript 파일을 배치합니다.
|
|
|
|
- `.opencode/plugins/` - 프로젝트 레벨 플러그인
|
|
- `~/.config/opencode/plugins/` - 글로벌 플러그인
|
|
|
|
이 디렉토리의 파일은 자동으로 시작에로드됩니다.
|
|
|
|
---
|
|
|
|
### 부터 npm
|
|
|
|
config 파일에 npm 패키지를 지정합니다.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
|
|
}
|
|
```
|
|
|
|
일반 및 범위의 npm 패키지 모두 지원됩니다.
|
|
|
|
[ecosystem](/docs/ecosystem#plugins)에서 사용할 수 있는 플러그인을 찾아보세요.
|
|
|
|
---
|
|
|
|
## 플러그인이 설치되는 방법
|
|
|
|
**npm 플러그인**는 시작시 Bun을 사용하여 자동으로 설치됩니다. 패키지와 그들의 의존성은 `~/.cache/opencode/node_modules/`에서 캐시됩니다.
|
|
|
|
**Local 플러그인 ** 플러그인 디렉토리에서 직접로드됩니다. 외부 패키지를 사용하려면 구성 디렉토리 내 `package.json`를 작성해야 합니다 ([Dependencies](#dependencies)), 또는 플러그인을 npm에 게시하고 [config에 추가](/docs/config#plugins).
|
|
|
|
---
|
|
|
|
## 짐 순서
|
|
|
|
플러그인은 모든 소스에서로드되며 모든 후크는 순서대로 실행됩니다. 짐 순서는:
|
|
|
|
1. 글로벌 구성 (`~/.config/opencode/opencode.json`)
|
|
2. 프로젝트 구성 (`opencode.json`)
|
|
3. 글로벌 플러그인 디렉토리 (`~/.config/opencode/plugins/`)
|
|
4. 프로젝트 플러그인 디렉토리 (`.opencode/plugins/`)
|
|
|
|
동일한 이름과 버전을 가진 중복 npm 포장은 한 번 적재됩니다. 하지만, 로컬 플러그인과 같은 이름과 npm 플러그인은 모두 별도로로드됩니다.
|
|
|
|
---
|
|
|
|
## 플러그인 만들기
|
|
|
|
플러그인은 **JavaScript/TypeScript 모듈**입니다.
|
|
기능. 각 함수는 context 객체를 수신하고 Hooks 객체를 반환합니다.
|
|
|
|
---
|
|
|
|
### 종점
|
|
|
|
로컬 플러그인 및 사용자 정의 도구는 외부 npm 패키지를 사용할 수 있습니다. `package.json`를 config 디렉토리에 추가하면 필요한 의존도가 있습니다.
|
|
|
|
```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 worktree 경로.
|
|
- `client`: AI와 상호 작용을 위한 opencode SDK 클라이언트.
|
|
- `$`: Bun's [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.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"'`
|
|
}
|
|
},
|
|
}
|
|
}
|
|
```
|
|
|
|
macOS에서 AppleScript를 실행하려면 `osascript`를 사용하고 있습니다. 여기에 우리는 그것을 사용하여 알림을 보낼 수 있습니다.
|
|
|
|
:::note
|
|
OpenCode 데스크톱 앱을 사용하는 경우 응답이 준비되어 있거나 세션 오류가 있을 때 시스템 알림을 자동으로 보낼 수 있습니다.
|
|
:::
|
|
|
|
---
|
|
|
|
### .env 보호
|
|
|
|
읽기 `.env` 파일에서 opencode를 방지하십시오:
|
|
|
|
```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")
|
|
}
|
|
},
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Inject 환경 변수
|
|
|
|
환경 변수를 모든 쉘 실행 (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` helper는 opencode가 호출 할 수있는 사용자 정의 도구를 만듭니다. Zod schema 기능을 가지고 도구 정의를 반환:
|
|
|
|
- `description`: 도구는 무엇을
|
|
- `args`: 도구의 인수에 대한 Zod 스키마
|
|
- `execute`: 도구가 호출될 때 실행되는 기능
|
|
|
|
사용자 정의 도구는 내장 도구와 함께 Opencode를 사용할 수 있습니다.
|
|
|
|
---
|
|
|
|
### 로깅
|
|
|
|
구조화된 로깅을 위한 `console.log` 대신에 `client.app.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)를 참고하세요.
|
|
|
|
---
|
|
|
|
## Compaction 걸이
|
|
|
|
세션이 압축 될 때 포함 된 컨텍스트를 사용자 지정:
|
|
|
|
```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
|
|
`)
|
|
},
|
|
}
|
|
}
|
|
```
|
|
|
|
LLM의 앞에 `experimental.session.compacting` 걸이 불은 오염 요약을 생성합니다. 기본 압축 프롬프트가 놓을 수 있도록 도메인 별 컨텍스트를 주입합니다.
|
|
|
|
당신은 또한 `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` 배열은 이 경우에 무시됩니다.
|