SDK
opencode JS/TS SDK จัดเตรียมไคลเอ็นต์ประเภทที่ปลอดภัยสำหรับการโต้ตอบกับเซิร์ฟเวอร์ ใช้เพื่อสร้างการบูรณาการและควบคุม opencode โดยทางโปรแกรม
เรียนรู้เพิ่มเติม เกี่ยวกับวิธีการทำงานของเซิร์ฟเวอร์ ตัวอย่างเช่น ลองดู โครงการ ที่สร้างโดยชุมชน
ติดตั้ง SDK จาก npm:
npm install @opencode-ai/sdkสร้างอินสแตนซ์ของ opencode:
import { createOpencode } from "@opencode-ai/sdk"
const { client } = await createOpencode()สิ่งนี้จะเริ่มต้นทั้งเซิร์ฟเวอร์และไคลเอนต์
ตัวเลือก
| ตัวเลือก | Type | คำอธิบาย | ค่าเริ่มต้น |
|---|---|---|---|
hostname | string | ชื่อโฮสต์ของเซิร์ฟเวอร์ | 127.0.0.1 |
port | number | พอร์ตเซิร์ฟเวอร์ | 4096 |
signal | AbortSignal | ยกเลิกสัญญาณสำหรับการยกเลิก | undefined |
timeout | number | หมดเวลาเป็น ms สำหรับการเริ่มต้นเซิร์ฟเวอร์ | 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",
})ตัวเลือก
| ตัวเลือก | Type | คำอธิบาย | ค่าเริ่มต้น |
|---|---|---|---|
baseUrl | string | URL ของเซิร์ฟเวอร์ | http://localhost:4096 |
fetch | function | การใช้งานการดึงข้อมูลแบบกำหนดเอง | globalThis.fetch |
parseAs | string | Methodการแยกวิเคราะห์การตอบสนอง | 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 schema โมเดลจะใช้เครื่องมือ 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 | คำอธิบาย |
|---|---|---|
type | 'json_schema' | จำเป็น ระบุโหมด JSON schema |
schema | object | จำเป็น วัตถุ JSON Schema ที่กำหนดโครงสร้างผลลัพธ์ |
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 เปิดเผย API ของเซิร์ฟเวอร์ทั้งหมดผ่านไคลเอ็นต์ประเภทที่ปลอดภัย
| Method | คำอธิบาย | การตอบสนอง |
|---|---|---|
global.health() | ตรวจสอบสภาพและเวอร์ชันของเซิร์ฟเวอร์ | { healthy: true, version: string } |
ตัวอย่าง
const health = await client.global.health()
console.log(health.data.version)| Method | คำอธิบาย | การตอบสนอง |
|---|---|---|
app.log() | เขียนรายการบันทึก | boolean |
app.agents() | รายชื่อตัวแทนที่มีอยู่ทั้งหมด | ตัวแทน[] |
ตัวอย่าง
// 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()| Method | คำอธิบาย | การตอบสนอง |
|---|---|---|
project.list() | แสดงรายการโครงการทั้งหมด | Project[] |
ตัวอย่าง
// List all projects
const projects = await client.project.list()
| Method | คำอธิบาย | การตอบสนอง |
|---|---|---|
path.get() | รับเส้นทางปัจจุบัน | Path |
ตัวอย่าง
// Get current path information
const pathInfo = await client.path.get()| Method | คำอธิบาย | การตอบสนอง |
|---|---|---|
config.get() | รับข้อมูลการกำหนดค่า | กำหนดค่า |
config.providers() | ผู้ให้บริการรายชื่อและโมเดลเริ่มต้น | { providers: ผู้ให้บริการ[], default: { [key: string]: string } } |
ตัวอย่าง
const config = await client.config.get()
const { providers, default: defaults } = await client.config.providers()| Method | คำอธิบาย | หมายเหตุ |
|---|---|---|
session.list() | แสดงรายการเซสชัน | ส่งคืน เซสชัน[] |
session.get({ path }) | รับเซสชัน | ส่งคืน เซสชัน |
session.children({ path }) | แสดงรายการเซสชันย่อย | ส่งคืน เซสชัน[] |
session.create({ body }) | สร้างเซสชัน | ส่งคืน เซสชัน |
session.delete({ path }) | ลบเซสชัน | ส่งคืน boolean |
session.update({ path, body }) | อัปเดตคุณสมบัติเซสชัน | ส่งคืน เซสชัน |
session.init({ path, body }) | วิเคราะห์แอปและสร้าง AGENTS.md | ส่งคืน boolean |
session.abort({ path }) | ยกเลิกเซสชันที่ทำงานอยู่ | ส่งคืน boolean |
session.share({ path }) | แบ่งปันเซสชั่น | ส่งคืน เซสชัน |
session.unshare({ path }) | เลิกแชร์เซสชัน | ส่งคืน เซสชัน |
session.summarize({ path, body }) | สรุปเซสชัน | ส่งคืน boolean |
session.messages({ path }) | แสดงรายการข้อความในเซสชัน | ส่งคืน { info: ข้อความ, parts: ส่วน[]}[] |
session.message({ path }) | รับรายละเอียดข้อความ | ส่งคืน { info: ข้อความ, parts: ส่วน[]} |
session.prompt({ path, body }) | ส่งข้อความแจ้ง | body.noReply: true ส่งคืน UserMessage (บริบทเท่านั้น) ค่าเริ่มต้นส่งคืน AssistantMessage พร้อมการตอบสนองของ AI รองรับ body.outputFormat สำหรับ ผลลัพธ์แบบมีโครงสร้าง |
session.command({ path, body }) | ส่งคำสั่งไปยังเซสชั่น | ส่งคืน { info: AssistantMessage, parts: ส่วน[]} |
session.shell({ path, body }) | รันคำสั่ง shell | ส่งคืน AssistantMessage |
session.revert({ path, body }) | คืนค่าข้อความ | ส่งคืน เซสชัน |
session.unrevert({ path }) | คืนค่าข้อความที่เปลี่ยนกลับ | ส่งคืน เซสชัน |
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." }],
},
})| Method | คำอธิบาย | การตอบสนอง |
|---|---|---|
find.text({ query }) | ค้นหาข้อความในไฟล์ | อาร์เรย์ของวัตถุที่ตรงกับ path, lines, line_number, absolute_offset, submatches |
find.files({ query }) | ค้นหาไฟล์และไดเร็กทอรีตามชื่อ | string[] (paths) |
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" },
})| Method | คำอธิบาย | การตอบสนอง |
|---|---|---|
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 }) | แสดงการแจ้งเตือนขนมปังปิ้ง | boolean |
ตัวอย่าง
// Control TUI interface
await client.tui.appendPrompt({
body: { text: "Add this to prompt" },
})
await client.tui.showToast({
body: { message: "Task completed", variant: "success" },
})| Method | คำอธิบาย | การตอบสนอง |
|---|---|---|
auth.set({ ... }) | ตั้งค่าข้อมูลประจำตัวการรับรองความถูกต้อง | boolean |
ตัวอย่าง
await client.auth.set({
path: { id: "anthropic" },
body: { type: "api", key: "your-api-key" },
})| Method | คำอธิบาย | การตอบสนอง |
|---|---|---|
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)
}