--- title: SDK description: opencode 服务器的类型安全 JS 客户端。 --- import config from "../../../../config.mjs" export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts` opencode JS/TS SDK 提供了一个类型安全的客户端，用于与服务器进行交互。 你可以用它来构建集成方案，并以编程方式控制 opencode。 [了解更多](/docs/server)关于服务器的工作原理。如需示例，请查看社区构建的[项目](/docs/ecosystem#projects)。 --- ## 安装 从 npm 安装 SDK： ```bash npm install @opencode-ai/sdk ``` --- ## 创建客户端 创建一个 opencode 实例： ```javascript 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`，但你可以通过内联方式覆盖或添加配置： ```javascript 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 实例，可以创建一个客户端实例来连接它： ```javascript 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 包含所有 API 类型的 TypeScript 定义。你可以直接导入它们： ```typescript import type { Session, Message, Part } from "@opencode-ai/sdk" ``` 所有类型均根据服务器的 OpenAPI 规范生成，可在类型文件中查看。 --- ## 错误处理 SDK 可能会抛出错误，你可以捕获并处理这些错误： ```typescript try { await client.session.get({ path: { id: "invalid-id" } }) } catch (error) { console.error("Failed to get session:", (error as Error).message) } ``` --- ## 结构化输出 你可以通过指定带有 JSON Schema 的 `format` 来请求模型返回结构化的 JSON 输出。模型会使用 `StructuredOutput` 工具返回符合你 Schema 的经过验证的 JSON。 ### 基本用法 ```typescript 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` | 返回符合所提供 Schema 的经过验证的 JSON | ### JSON Schema 格式 使用 `type: 'json_schema'` 时，需提供以下字段： | 字段 | 类型 | 描述 | | ------------ | --------------- | ------------------------------------- | | `type` | `'json_schema'` | 必填。指定 JSON Schema 模式 | | `schema` | `object` | 必填。定义输出结构的 JSON Schema 对象 | | `retryCount` | `number` | 可选。验证重试次数（默认值：2） | ### 错误处理 如果模型在所有重试后仍无法生成有效的结构化输出，响应中会包含 `StructuredOutputError`： ```typescript 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) } ``` ### 最佳实践 1. **在 Schema 属性中提供清晰的描述**，帮助模型理解需要提取的数据 2. **使用 `required`** 指定哪些字段必须存在 3. **保持 Schema 简洁** — 复杂的嵌套 Schema 可能会让模型更难正确填充 4. **设置合适的 `retryCount`** — 对于复杂 Schema 可增加重试次数，对于简单 Schema 可减少 --- ## API SDK 通过类型安全的客户端暴露所有服务器 API。 --- ### Global | 方法 | 描述 | 响应 | | ----------------- | ------------------------ | ------------------------------------ | | `global.health()` | 检查服务器健康状态和版本 | `{ healthy: true, version: string }` | --- #### 示例 ```javascript const health = await client.global.health() console.log(health.data.version) ``` --- ### App | 方法 | 描述 | 响应 | | -------------- | ------------------ | ------------------------------------------- | | `app.log()` | 写入一条日志 | `boolean` | | `app.agents()` | 列出所有可用的代理 | Agent[] | --- #### 示例 ```javascript // 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 | --- #### 示例 ```javascript // List all projects const projects = await client.project.list() // Get current project const currentProject = await client.project.current() ``` --- ### Path | 方法 | 描述 | 响应 | | ------------ | ------------ | ---------------------------------------- | | `path.get()` | 获取当前路径 | Path | --- #### 示例 ```javascript // Get current path information const pathInfo = await client.path.get() ``` --- ### Config | 方法 | 描述 | 响应 | | -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- | | `config.get()` | 获取配置信息 | Config | | `config.providers()` | 列出提供商和默认模型 | `{ providers: `Provider[]`, default: { [key: string]: string } }` | --- #### 示例 ```javascript const config = await client.config.get() const { providers, default: defaults } = await client.config.providers() ``` --- ### Sessions | 方法 | 描述 | 备注 | | ---------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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（仅注入上下文）。默认返回带有 AI 响应的 AssistantMessage。支持通过 `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` | --- #### 示例 ```javascript // 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." }], }, }) ``` --- ### Files | 方法 | 描述 | 响应 | | ------------------------- | -------------------- | ----------------------------------------------------------------------------------- | | `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） --- #### 示例 ```javascript // 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.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` | --- #### 示例 ```javascript // 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` | --- #### 示例 ```javascript await client.auth.set({ path: { id: "anthropic" }, body: { type: "api", key: "your-api-key" }, }) ``` --- ### Events | 方法 | 描述 | 响应 | | ------------------- | ------------------ | ------------------ | | `event.subscribe()` | 服务器发送的事件流 | 服务器发送的事件流 | --- #### 示例 ```javascript // 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) } ```