wip(docs): i18n (#12681)
This commit is contained in:
Adam
385
packages/web/src/content/docs/ko/plugins.mdx
Normal file
385
packages/web/src/content/docs/ko/plugins.mdx
Normal file
@@ -0,0 +1,385 @@
|
||||
---
|
||||
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` 배열은 이 경우에 무시됩니다.
|
||||
Reference in New Issue
Block a user