Loading...
Loading...
Compare original and translation side by side
export const MyPlugin = async (context) => {
// context: { project, client, $, directory, worktree }
return {
event: async ({ event }) => {
// event: { type: 'event.name', data: {...} }
switch(event.type) {
case 'file.edited':
// Handle file edits
break;
case 'tool.execute.before':
// Pre-process tool execution
break;
}
}
};
};export const MyPlugin = async (context) => {
// context: { project, client, $, directory, worktree }
return {
event: async ({ event }) => {
// event: { type: 'event.name', data: {...} }
switch(event.type) {
case 'file.edited':
// 处理文件编辑
break;
case 'tool.execute.before':
// 预处理工具执行
break;
}
}
};
};| Category | Events | Use Cases |
|---|---|---|
| command | | Track command history, notifications |
| file | | File validation, auto-formatting |
| installation | | Dependency tracking |
| lsp | | Custom error handling |
| message | | Message filtering, logging |
| permission | | Permission policies |
| server | | Connection monitoring |
| session | | Session management |
| todo | | Todo synchronization |
| tool | | Tool interception, augmentation |
| tui | | UI customization |
| 分类 | 事件 | 适用场景 |
|---|---|---|
| command | | 追踪命令历史、发送通知 |
| file | | 文件验证、自动格式化 |
| installation | | 依赖追踪 |
| lsp | | 自定义错误处理 |
| message | | 消息过滤、日志记录 |
| permission | | 权限策略管理 |
| server | | 连接监控 |
| session | | 会话管理 |
| todo | | 待办事项同步 |
| tool | | 工具拦截、功能增强 |
| tui | | UI自定义 |
{
"name": "env-protection",
"description": "Prevents sharing .env files",
"version": "1.0.0",
"author": "Security Team",
"plugin": {
"file": "plugin.js",
"location": "global"
},
"hooks": {
"file": ["file.edited"],
"permission": ["permission.replied"]
}
}{
"name": "env-protection",
"description": "Prevents sharing .env files",
"version": "1.0.0",
"author": "Security Team",
"plugin": {
"file": "plugin.js",
"location": "global"
},
"hooks": {
"file": ["file.edited"],
"permission": ["permission.replied"]
}
}// .opencode/plugin/env-protection.js
export const EnvProtectionPlugin = async ({ project, client }) => {
const sensitivePatterns = [
/\.env$/,
/\.env\..+$/,
/credentials\.json$/,
/\.secret$/,
];
const isSensitiveFile = (filePath) => {
return sensitivePatterns.some(pattern => pattern.test(filePath));
};
return {
event: async ({ event }) => {
switch (event.type) {
case 'file.edited': {
const { path } = event.data;
if (isSensitiveFile(path)) {
console.warn(`⚠️ Sensitive file edited: ${path}`);
console.warn('This file should not be shared or committed.');
}
break;
}
case 'permission.replied': {
const { action, target, decision } = event.data;
// Block read/share operations on sensitive files
if ((action === 'read' || action === 'share') &&
isSensitiveFile(target) &&
decision === 'allow') {
console.error(`🚫 Blocked ${action} operation on sensitive file: ${target}`);
// Override permission decision
return {
override: true,
decision: 'deny',
reason: 'Sensitive file protection policy'
};
}
break;
}
}
}
};
};// .opencode/plugin/env-protection.js
export const EnvProtectionPlugin = async ({ project, client }) => {
const sensitivePatterns = [
/\.env$/,
/\.env\..+$/,
/credentials\.json$/,
/\.secret$/,
];
const isSensitiveFile = (filePath) => {
return sensitivePatterns.some(pattern => pattern.test(filePath));
};
return {
event: async ({ event }) => {
switch (event.type) {
case 'file.edited': {
const { path } = event.data;
if (isSensitiveFile(path)) {
console.warn(`⚠️ Sensitive file edited: ${path}`);
console.warn('This file should not be shared or committed.');
}
break;
}
case 'permission.replied': {
const { action, target, decision } = event.data;
// Block read/share operations on sensitive files
if ((action === 'read' || action === 'share') &&
isSensitiveFile(target) &&
decision === 'allow') {
console.error(`🚫 Blocked ${action} operation on sensitive file: ${target}`);
// Override permission decision
return {
override: true,
decision: 'deny',
reason: 'Sensitive file protection policy'
};
}
break;
}
}
}
};
};// .opencode/plugin/notify.js
export const NotifyPlugin = async ({ project, $ }) => {
let commandStartTime = null;
return {
event: async ({ event }) => {
switch (event.type) {
case 'command.executed': {
const { command, args, status } = event.data;
commandStartTime = Date.now();
console.log(`▶️ Executing: ${command} ${args.join(' ')}`);
break;
}
case 'tool.execute.after': {
const { tool, duration, success } = event.data;
if (duration > 5000) {
// Notify for long-running operations
await $`osascript -e 'display notification "Completed in ${duration}ms" with title "${tool}"'`;
}
console.log(`✅ ${tool} completed in ${duration}ms`);
break;
}
}
}
};
};// .opencode/plugin/notify.js
export const NotifyPlugin = async ({ project, $ }) => {
let commandStartTime = null;
return {
event: async ({ event }) => {
switch (event.type) {
case 'command.executed': {
const { command, args, status } = event.data;
commandStartTime = Date.now();
console.log(`▶️ Executing: ${command} ${args.join(' ')}`);
break;
}
case 'tool.execute.after': {
const { tool, duration, success } = event.data;
if (duration > 5000) {
// Notify for long-running operations
await $`osascript -e 'display notification "Completed in ${duration}ms" with title "${tool}"'`;
}
console.log(`✅ ${tool} completed in ${duration}ms`);
break;
}
}
}
};
};// .opencode/plugin/custom-tools.js
export const CustomToolsPlugin = async ({ client }) => {
// Register custom tool on initialization
await client.registerTool({
name: 'lint',
description: 'Run linter on current file with auto-fix option',
parameters: {
type: 'object',
properties: {
fix: {
type: 'boolean',
description: 'Auto-fix issues'
}
}
},
handler: async ({ fix }) => {
const result = await $`eslint ${fix ? '--fix' : ''} .`;
return {
output: result.stdout,
errors: result.stderr
};
}
});
return {
event: async ({ event }) => {
// Monitor tool usage
if (event.type === 'tool.execute.before') {
console.log(`🔧 Tool: ${event.data.tool}`);
}
}
};
};// .opencode/plugin/custom-tools.js
export const CustomToolsPlugin = async ({ client }) => {
// Register custom tool on initialization
await client.registerTool({
name: 'lint',
description: 'Run linter on current file with auto-fix option',
parameters: {
type: 'object',
properties: {
fix: {
type: 'boolean',
description: 'Auto-fix issues'
}
}
},
handler: async ({ fix }) => {
const result = await $`eslint ${fix ? '--fix' : ''} .`;
return {
output: result.stdout,
errors: result.stderr
};
}
});
return {
event: async ({ event }) => {
// Monitor tool usage
if (event.type === 'tool.execute.before') {
console.log(`🔧 Tool: ${event.data.tool}`);
}
}
};
};| Location | Path | Scope | Use Case |
|---|---|---|---|
| Global | | All projects | Security policies, global utilities |
| Project | | Current project | Project-specific hooks, validators |
| 位置 | 路径 | 作用范围 | 适用场景 |
|---|---|---|---|
| Global | | 所有项目 | 安全策略、全局工具 |
| Project | | 当前项目 | 项目专属钩子、验证器 |
| Mistake | Why It Fails | Fix |
|---|---|---|
| Synchronous event handler | Blocks event loop | Use |
| Missing error handling | Plugin crashes on error | Wrap in try/catch |
| Heavy computation in handler | Slows down operations | Defer to background process |
| Mutating event data directly | Causes side effects | Return override object |
| Not checking event type | Handles wrong events | Use switch/case on |
| Forgetting context destructuring | Missing key utilities | Destructure |
| 错误 | 失败原因 | 修复方案 |
|---|---|---|
| 同步事件处理器 | 阻塞事件循环 | 使用 |
| 缺少错误处理 | 插件遇错崩溃 | 用try/catch包裹逻辑 |
| 处理器中执行重计算 | 拖慢操作速度 | 延迟到后台进程执行 |
| 直接修改事件数据 | 产生副作用 | 返回override对象 |
| 未检查事件类型 | 处理错误事件 | 对 |
| 忘记解构context | 缺少关键工具函数 | 解构 |
// File Events
interface FileEditedEvent {
type: 'file.edited';
data: {
path: string;
content: string;
timestamp: number;
};
}
// Tool Events
interface ToolExecuteBeforeEvent {
type: 'tool.execute.before';
data: {
tool: string;
args: Record<string, any>;
user: string;
};
}
interface ToolExecuteAfterEvent {
type: 'tool.execute.after';
data: {
tool: string;
duration: number;
success: boolean;
output?: any;
error?: string;
};
}
// Permission Events
interface PermissionRepliedEvent {
type: 'permission.replied';
data: {
action: 'read' | 'write' | 'execute' | 'share';
target: string;
decision: 'allow' | 'deny';
};
}// File Events
interface FileEditedEvent {
type: 'file.edited';
data: {
path: string;
content: string;
timestamp: number;
};
}
// Tool Events
interface ToolExecuteBeforeEvent {
type: 'tool.execute.before';
data: {
tool: string;
args: Record<string, any>;
user: string;
};
}
interface ToolExecuteAfterEvent {
type: 'tool.execute.after';
data: {
tool: string;
duration: number;
success: boolean;
output?: any;
error?: string;
};
}
// Permission Events
interface PermissionRepliedEvent {
type: 'permission.replied';
data: {
action: 'read' | 'write' | 'execute' | 'share';
target: string;
decision: 'allow' | 'deny';
};
}// Test plugin locally before installation
import { EnvProtectionPlugin } from './env-protection.js';
const mockContext = {
project: { root: '/test/project' },
client: {},
$: async (cmd) => ({ stdout: '', stderr: '' }),
directory: '/test/project',
worktree: null
};
const plugin = await EnvProtectionPlugin(mockContext);
// Simulate event
await plugin.event({
event: {
type: 'file.edited',
data: { path: '.env', content: 'SECRET=123', timestamp: Date.now() }
}
});// Test plugin locally before installation
import { EnvProtectionPlugin } from './env-protection.js';
const mockContext = {
project: { root: '/test/project' },
client: {},
$: async (cmd) => ({ stdout: '', stderr: '' }),
directory: '/test/project',
worktree: null
};
const plugin = await EnvProtectionPlugin(mockContext);
// Simulate event
await plugin.event({
event: {
type: 'file.edited',
data: { path: '.env', content: 'SECRET=123', timestamp: Date.now() }
}
});| Claude Hook | OpenCode Event | Description |
|---|---|---|
| | Run before tool execution, can block |
| | Run after tool execution |
| | Process user prompts |
| | Session completion |
| Claude钩子 | OpenCode事件 | 描述 |
|---|---|---|
| | 工具执行前运行,可阻止执行 |
| | 工具执行后运行 |
| | 处理用户提示 |
| | 会话结束时触发 |
export const CompatiblePlugin = async (context) => {
return {
// Equivalent to Claude's PreToolUse hook
'tool.execute.before': async (input, output) => {
if (shouldBlock(input)) {
throw new Error('Blocked by policy');
}
},
// Equivalent to Claude's PostToolUse hook
'tool.execute.after': async (result) => {
console.log(`Tool completed: ${result.tool}`);
},
// Equivalent to Claude's SessionEnd hook
event: async ({ event }) => {
if (event.type === 'session.idle') {
await cleanup();
}
}
};
};export const CompatiblePlugin = async (context) => {
return {
// 等价于Claude的PreToolUse钩子
'tool.execute.before': async (input, output) => {
if (shouldBlock(input)) {
throw new Error('Blocked by policy');
}
},
// 等价于Claude的PostToolUse钩子
'tool.execute.after': async (result) => {
console.log(`Tool completed: ${result.tool}`);
},
// 等价于Claude的SessionEnd钩子
event: async ({ event }) => {
if (event.type === 'session.idle') {
await cleanup();
}
}
};
};import { compose } from "opencode-plugin-compose";
const composedPlugin = compose([
envProtectionPlugin,
notifyPlugin,
customToolsPlugin
]);
// Runs all hooks in sequenceimport { compose } from "opencode-plugin-compose";
const composedPlugin = compose([
envProtectionPlugin,
notifyPlugin,
customToolsPlugin
]);
// 按顺序运行所有钩子packages/converters/schemas/opencode-plugin.schema.jsonpackages/converters/schemas/opencode-plugin.schema.json