الإضافات
تتيح لك الإضافات توسيع OpenCode عبر ربطها بأحداث مختلفة وتخصيص السلوك. يمكنك إنشاء إضافات لإضافة ميزات جديدة، أو التكامل مع خدمات خارجية، أو تعديل السلوك الافتراضي لـ OpenCode.
للاطلاع على أمثلة، راجع الإضافات التي أنشأها المجتمع.
هناك طريقتان لتحميل الإضافات.
ضع ملفات JavaScript أو TypeScript في دليل الإضافات.
.opencode/plugins/- إضافات على مستوى المشروع~/.config/opencode/plugins/- إضافات عامة
تُحمَّل الملفات في هذه الأدلة تلقائيا عند بدء التشغيل.
حدّد حزم npm في ملف الإعدادات.
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
}يتم دعم حزم npm العادية والحزم ذات النطاق (scoped).
تصفّح الإضافات المتاحة في النظام البيئي.
إضافات npm تُثبَّت تلقائيا باستخدام Bun عند بدء التشغيل. تُخزَّن الحزم واعتمادياتها مؤقتا في ~/.cache/opencode/node_modules/.
الإضافات المحلية تُحمَّل مباشرة من دليل الإضافات. لاستخدام حزم خارجية، يجب إنشاء package.json داخل دليل الإعدادات لديك (راجع الاعتماديات)، أو نشر الإضافة على npm ثم إضافتها إلى إعداداتك.
تُحمَّل الإضافات من جميع المصادر وتعمل جميع الخطافات بالتتابع. ترتيب التحميل هو:
- إعدادات عامة (
~/.config/opencode/opencode.json) - إعدادات المشروع (
opencode.json) - دليل الإضافات العام (
~/.config/opencode/plugins/) - دليل إضافات المشروع (
.opencode/plugins/)
تُحمَّل حزم npm المكررة ذات الاسم والإصدار نفسيهما مرة واحدة. ومع ذلك، تُحمَّل الإضافة المحلية وإضافة npm ذات الاسم المشابه كلتاهما بشكل مستقل.
الإضافة هي وحدة JavaScript/TypeScript تصدّر دالة إضافة واحدة أو أكثر. تستقبل كل دالة كائنا للسياق وتعيد كائنا للخطافات.
يمكن للإضافات المحلية والأدوات المخصصة استخدام حزم npm خارجية. أضف package.json إلى دليل الإعدادات لديك متضمنا الاعتماديات التي تحتاجها.
{
"dependencies": {
"shescape": "^2.1.0"
}
}يشغّل OpenCode الأمر bun install عند بدء التشغيل لتثبيتها. بعد ذلك يمكن لإضافاتك وأدواتك استيرادها.
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)
}
},
}
}export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
console.log("Plugin initialized!")
return {
// Hook implementations go here
}
}تستقبل دالة الإضافة ما يلي:
project: معلومات المشروع الحالي.directory: دليل العمل الحالي.worktree: مسار git worktree.client: عميل SDK لـ opencode للتفاعل مع الذكاء الاصطناعي.$: واجهة shell API الخاصة بـ Bun لتنفيذ الأوامر.
بالنسبة لإضافات TypeScript، يمكنك استيراد الأنواع من حزمة الإضافة:
import type { Plugin } from "@opencode-ai/plugin"
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
return {
// Type-safe hook implementations
}
}يمكن للإضافات الاشتراك في الأحداث كما هو موضح أدناه في قسم الأمثلة. فيما يلي قائمة بالأحداث المتاحة.
أحداث الأوامر
command.executed
أحداث الملفات
file.editedfile.watcher.updated
أحداث التثبيت
installation.updated
أحداث LSP
lsp.client.diagnosticslsp.updated
أحداث الرسائل
message.part.removedmessage.part.updatedmessage.removedmessage.updated
أحداث الأذونات
permission.askedpermission.replied
أحداث الخادم
server.connected
أحداث الجلسة
session.createdsession.compactedsession.deletedsession.diffsession.errorsession.idlesession.statussession.updated
أحداث shell
shell.env
أحداث الأدوات
tool.execute.aftertool.execute.before
أحداث واجهة TUI
tui.prompt.appendtui.command.executetui.toast.show
فيما يلي بعض أمثلة الإضافات التي يمكنك استخدامها لتوسيع opencode.
أرسل إشعارات عند وقوع أحداث معينة:
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 لتشغيل AppleScript على macOS. هنا نستخدمه لإرسال إشعارات.
امنع opencode من قراءة ملفات .env:
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 (أدوات الذكاء الاصطناعي وterminal المستخدم):
export const InjectEnvPlugin = async () => {
return {
"shell.env": async (input, output) => {
output.env.MY_API_KEY = "secret"
output.env.PROJECT_ROOT = input.cwd
},
}
}يمكن للإضافات أيضا إضافة أدوات مخصصة إلى opencode:
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 للتسجيل البنيوي:
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 للتفاصيل.
خصّص السياق الذي يتم تضمينه عند ضغط جلسة:
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:
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 في هذه الحالة.