مجموعة تطوير البرمجيات (SDK)

عميل JavaScript آمن الأنواع لخادم opencode.

توفر 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-3-5-sonnet-20241022",
  },
})

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)
}

APIs

توفر SDK جميع واجهات الخادم عبر عميل آمن للأنواع.

عام (`global`)

الطريقة	الوصف	الاستجابة
`global.health()`	التحقق من صحة الخادم وإصداره	`{ healthy: true, version: string }`

أمثلة

const health = await client.global.health()
console.log(health.data.version)

التطبيق (`app`)

الطريقة	الوصف	الاستجابة
`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`)

الطريقة	الوصف	الاستجابة
`project.list()`	سرد جميع المشاريع	`Project[]`
`project.current()`	جلب المشروع الحالي	`Project`

أمثلة

// List all projects
const projects = await client.project.list()

// Get current project
const currentProject = await client.project.current()

المسار (`path`)

الطريقة	الوصف	الاستجابة
`path.get()`	جلب المسار الحالي	`Path`

أمثلة

// Get current path information
const pathInfo = await client.path.get()

الإعدادات (`config`)

الطريقة	الوصف	الاستجابة
`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`)

الطريقة	الوصف	ملاحظات
`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
`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-3-5-sonnet-20241022" },
    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 (`tui`)

الطريقة	الوصف	الاستجابة
`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`)

الطريقة	الوصف	الاستجابة
`auth.set({ ... })`	تعيين بيانات اعتماد المصادقة	`boolean`

أمثلة

await client.auth.set({
  path: { id: "anthropic" },
  body: { type: "api", key: "your-api-key" },
})

الأحداث (`event`)

الطريقة	الوصف	الاستجابة
`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)
}