مجموعة تطوير البرمجيات (SDK)
توفر SDK الخاصة بـ opencode لـ JS/TS عميلا آمنا للأنواع للتفاعل مع الخادم. استخدمها لبناء التكاملات والتحكم في opencode برمجيا.
اعرف المزيد حول كيفية عمل الخادم. للاطلاع على أمثلة، تفقد المشاريع التي أنشأها المجتمع.
ثبّت SDK من npm:
npm install @opencode-ai/sdkأنشئ مثيلا من opencode:
import { createOpencode } from "@opencode-ai/sdk"
const { client } = await createOpencode()هذا يشغّل خادما وعميلا معا.
الخيارات
| الخيار | النوع | الوصف | الافتراضي |
|---|---|---|---|
hostname | string | اسم مضيف الخادم | 127.0.0.1 |
port | number | منفذ الخادم | 4096 |
signal | AbortSignal | إشارة إلغاء للإيقاف | undefined |
timeout | number | مهلة بدء الخادم بالمللي ثانية | 5000 |
config | Config | كائن الإعدادات | {} |
يمكنك تمرير كائن إعدادات لتخصيص السلوك. سيستمر المثيل في التقاط opencode.json لديك، لكن يمكنك تجاوز الإعدادات أو إضافة إعدادات مباشرة:
import { createOpencode } from "@opencode-ai/sdk"
const opencode = await createOpencode({
hostname: "127.0.0.1",
port: 4096,
config: {
model: "anthropic/claude-sonnet-5-5",
},
})
console.log(`Server running at ${opencode.server.url}`)
opencode.server.close()إذا كان لديك مثيل opencode يعمل بالفعل، يمكنك إنشاء مثيل عميل للاتصال به:
import { createOpencodeClient } from "@opencode-ai/sdk"
const client = createOpencodeClient({
baseUrl: "http://localhost:4096",
})الخيارات
| الخيار | النوع | الوصف | الافتراضي |
|---|---|---|---|
baseUrl | string | عنوان URL للخادم | http://localhost:4096 |
fetch | function | تنفيذ fetch مخصص | globalThis.fetch |
parseAs | string | طريقة تحليل الاستجابة | auto |
responseStyle | string | أسلوب الإرجاع: data أو fields | fields |
throwOnError | boolean | رمي الأخطاء بدلا من إرجاعها | false |
تتضمن SDK تعريفات TypeScript لجميع أنواع API. استوردها مباشرة:
import type { Session, Message, Part } from "@opencode-ai/sdk"جميع الأنواع مولّدة من مواصفات OpenAPI الخاصة بالخادم ومتاحة في ملف الأنواع.
يمكن أن ترمي SDK أخطاء يمكنك التقاطها ومعالجتها:
try {
await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
console.error("Failed to get session:", (error as Error).message)
}يمكنك طلب مخرجات JSON منظمة من النموذج عن طريق تحديد format مع مخطط JSON. سيستخدم النموذج أداة StructuredOutput لإرجاع JSON تم التحقق من صحته ومطابق للمخطط الخاص بك.
const result = await client.session.prompt({
path: { id: sessionId },
body: {
parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
format: {
type: "json_schema",
schema: {
type: "object",
properties: {
company: { type: "string", description: "Company name" },
founded: { type: "number", description: "Year founded" },
products: {
type: "array",
items: { type: "string" },
description: "Main products",
},
},
required: ["company", "founded"],
},
},
},
})
// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }| النوع | الوصف |
|---|---|
text | الافتراضي. استجابة نصية قياسية (بدون مخرجات منظمة) |
json_schema | يرجع JSON تم التحقق من صحته ومطابق للمخطط المقدم |
عند استخدام type: 'json_schema'، يجب تقديم:
| الحقل | النوع | الوصف |
|---|---|---|
type | 'json_schema' | مطلوب. يحدد وضع مخطط JSON |
schema | object | مطلوب. كائن مخطط JSON الذي يحدد بنية الإخراج |
retryCount | number | اختياري. عدد محاولات إعادة التحقق (الافتراضي: 2) |
إذا فشل النموذج في إنتاج مخرجات منظمة صالحة بعد جميع المحاولات، ستتضمن الاستجابة StructuredOutputError:
if (result.data.info.error?.name === "StructuredOutputError") {
console.error("Failed to produce structured output:", result.data.info.error.message)
console.error("Attempts:", result.data.info.error.retries)
}- قدّم أوصافا واضحة في خصائص المخطط لمساعدة النموذج على فهم البيانات التي يجب استخراجها
- استخدم
requiredلتحديد الحقول التي يجب أن تكون موجودة - حافظ على تركيز المخططات - المخططات المتداخلة المعقدة قد تكون أصعب على النموذج لملئها بشكل صحيح
- عيّن
retryCountمناسبا - قم بزيادته للمخططات المعقدة، وتقليله للمخططات البسيطة
توفر SDK جميع واجهات الخادم عبر عميل آمن للأنواع.
| الطريقة | الوصف | الاستجابة |
|---|---|---|
global.health() | التحقق من صحة الخادم وإصداره | { healthy: true, version: string } |
أمثلة
const health = await client.global.health()
console.log(health.data.version)| الطريقة | الوصف | الاستجابة |
|---|---|---|
app.log() | كتابة إدخال في السجل | boolean |
app.agents() | سرد جميع الوكلاء المتاحين | Agent[] |
أمثلة
// Write a log entry
await client.app.log({
body: {
service: "my-app",
level: "info",
message: "Operation completed",
},
})
// List available agents
const agents = await client.app.agents()| الطريقة | الوصف | الاستجابة |
|---|---|---|
project.list() | سرد جميع المشاريع | Project[] |
أمثلة
// List all projects
const projects = await client.project.list()
| الطريقة | الوصف | الاستجابة |
|---|---|---|
path.get() | جلب المسار الحالي | Path |
أمثلة
// Get current path information
const pathInfo = await client.path.get()| الطريقة | الوصف | الاستجابة |
|---|---|---|
config.get() | جلب معلومات الإعدادات | Config |
config.providers() | سرد المزوّدين والنماذج الافتراضية | { providers: Provider[], default: { [key: string]: string } } |
أمثلة
const config = await client.config.get()
const { providers, default: defaults } = await client.config.providers()| الطريقة | الوصف | ملاحظات |
|---|---|---|
session.list() | سرد الجلسات | يعيد Session[] |
session.get({ path }) | جلب جلسة | يعيد Session |
session.children({ path }) | سرد الجلسات الفرعية | يعيد Session[] |
session.create({ body }) | إنشاء جلسة | يعيد Session |
session.delete({ path }) | حذف جلسة | يعيد boolean |
session.update({ path, body }) | تحديث خصائص الجلسة | يعيد Session |
session.init({ path, body }) | تحليل التطبيق وإنشاء AGENTS.md | يعيد boolean |
session.abort({ path }) | إيقاف جلسة قيد التشغيل | يعيد boolean |
session.share({ path }) | مشاركة جلسة | يعيد Session |
session.unshare({ path }) | إلغاء مشاركة جلسة | يعيد Session |
session.summarize({ path, body }) | تلخيص جلسة | يعيد boolean |
session.messages({ path }) | سرد الرسائل في جلسة | يعيد { info: Message, parts: Part[]}[] |
session.message({ path }) | جلب تفاصيل الرسالة | يعيد { info: Message, parts: Part[]} |
session.prompt({ path, body }) | إرسال رسالة مطالبة | body.noReply: true يعيد UserMessage (للسياق فقط). الافتراضي يعيد AssistantMessage مع استجابة AI. يدعم body.outputFormat من أجل المخرجات المنظمة |
session.command({ path, body }) | إرسال أمر إلى الجلسة | يعيد { info: AssistantMessage, parts: Part[]} |
session.shell({ path, body }) | تشغيل أمر shell | يعيد AssistantMessage |
session.revert({ path, body }) | التراجع عن رسالة | يعيد Session |
session.unrevert({ path }) | استعادة الرسائل المتراجع عنها | يعيد Session |
postSessionByIdPermissionsByPermissionId({ path, body }) | الاستجابة لطلب إذن | يعيد boolean |
أمثلة
// Create and manage sessions
const session = await client.session.create({
body: { title: "My session" },
})
const sessions = await client.session.list()
// Send a prompt message
const result = await client.session.prompt({
path: { id: session.id },
body: {
model: { providerID: "anthropic", modelID: "claude-sonnet-5-5" },
parts: [{ type: "text", text: "Hello!" }],
},
})
// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
path: { id: session.id },
body: {
noReply: true,
parts: [{ type: "text", text: "You are a helpful assistant." }],
},
})| الطريقة | الوصف | الاستجابة |
|---|---|---|
find.text({ query }) | البحث عن نص داخل الملفات | مصفوفة من كائنات المطابقة مع path وlines وline_number وabsolute_offset وsubmatches |
find.files({ query }) | العثور على الملفات والمجلدات بالاسم | string[] (مسارات) |
find.symbols({ query }) | العثور على رموز مساحة العمل | Symbol[] |
file.read({ query }) | قراءة ملف | { type: "raw" | "patch", content: string } |
file.status({ query? }) | جلب حالة الملفات المتتبَّعة | File[] |
يدعم find.files بعض حقول الاستعلام الاختيارية:
type:"file"أو"directory"directory: تجاوز جذر المشروع لعملية البحثlimit: الحد الأقصى للنتائج (1–200)
أمثلة
// Search and read files
const textResults = await client.find.text({
query: { pattern: "function.*opencode" },
})
const files = await client.find.files({
query: { query: "*.ts", type: "file" },
})
const directories = await client.find.files({
query: { query: "packages", type: "directory", limit: 20 },
})
const content = await client.file.read({
query: { path: "src/index.ts" },
})| الطريقة | الوصف | الاستجابة |
|---|---|---|
tui.appendPrompt({ body }) | إلحاق نص بالمطالبة | boolean |
tui.openHelp() | فتح مربع حوار المساعدة | boolean |
tui.openSessions() | فتح محدد الجلسات | boolean |
tui.openThemes() | فتح محدد السمات | boolean |
tui.openModels() | فتح محدد النماذج | boolean |
tui.submitPrompt() | إرسال المطالبة الحالية | boolean |
tui.clearPrompt() | مسح المطالبة | boolean |
tui.executeCommand({ body }) | تنفيذ أمر | boolean |
tui.showToast({ body }) | عرض إشعار toast | boolean |
أمثلة
// Control TUI interface
await client.tui.appendPrompt({
body: { text: "Add this to prompt" },
})
await client.tui.showToast({
body: { message: "Task completed", variant: "success" },
})| الطريقة | الوصف | الاستجابة |
|---|---|---|
auth.set({ ... }) | تعيين بيانات اعتماد المصادقة | boolean |
أمثلة
await client.auth.set({
path: { id: "anthropic" },
body: { type: "api", key: "your-api-key" },
})| الطريقة | الوصف | الاستجابة |
|---|---|---|
event.subscribe() | تدفق أحداث مرسلة من الخادم | تدفق أحداث مرسلة من الخادم |
أمثلة
// Listen to real-time events
const events = await client.event.subscribe()
for await (const event of events.stream) {
console.log("Event:", event.type, event.properties)
}