7.1 SDK使用指南

OpenCode提供了类型安全的JavaScript/TypeScript SDK，让开发者能够以编程方式与OpenCode进行交互。

SDK概述

OpenCode SDK是一个完全类型安全的客户端库，提供以下特性：

• 完整的TypeScript类型支持
• 自动处理与OpenCode服务器的通信
• 支持会话管理、文件操作、配置等功能
• 事件驱动的实时更新机制

安装方法

使用npm或其他包管理器安装SDK：

# 使用npm安装
npm install @opencode/sdk

# 使用yarn安装
yarn add @opencode/sdk

# 使用pnpm安装
pnpm add @opencode/sdk

创建客户端

导入并创建OpenCode客户端实例：

import { createClient } from "@opencode/sdk";

// 创建客户端（自动连接到本地OpenCode服务器）
const client = createClient();

// 或者指定自定义URL
const client = createClient({
  url: "http://localhost:8080"
});

主要API模块

SDK提供了多个功能模块，覆盖OpenCode的所有核心功能：

Global - 全局状态

获取OpenCode的全局状态信息：

// 获取全局状态
const state = await client.global.get();

console.log(state.version);  // OpenCode版本
console.log(state.cwd);      // 当前工作目录
console.log(state.app);      // 应用状态

Sessions - 会话管理

创建、管理和操作会话：

// 列出所有会话
const sessions = await client.session.list();

// 创建新会话
const session = await client.session.create();

// 获取特定会话
const session = await client.session.get(sessionId);

// 在会话中发送消息
await client.session.chat(sessionId, {
  message: "帮我创建一个React组件"
});

// 中止正在进行的会话
await client.session.abort(sessionId);

// 删除会话
await client.session.delete(sessionId);

Files - 文件操作

读取和管理项目文件：

// 列出目录内容
const files = await client.file.list("/src");

// 读取文件内容
const content = await client.file.read("/src/main.ts");

// 搜索文件
const results = await client.file.search("config");

Config - 配置管理

读取和修改OpenCode配置：

// 获取当前配置
const config = await client.config.get();

// 更新配置
await client.config.update({
  provider: {
    default: "anthropic"
  }
});

TUI - 终端界面控制

控制TUI界面的行为：

// 获取TUI状态
const tuiState = await client.tui.get();

// 发送输入
await client.tui.input("hello");

// 模拟按键
await client.tui.keypress("enter");

Auth - 认证管理

管理API密钥和认证状态：

// 获取认证状态
const authStatus = await client.auth.status();

// 检查特定提供商的认证状态
const isAuthenticated = await client.auth.check("anthropic");

Events - 事件订阅

订阅实时事件更新：

// 订阅会话事件
client.events.on("session.message", (event) => {
  console.log("新消息:", event.content);
});

// 订阅工具调用事件
client.events.on("tool.call", (event) => {
  console.log("工具调用:", event.tool, event.args);
});

// 订阅错误事件
client.events.on("error", (error) => {
  console.error("错误:", error);
});

会话管理最佳实践

高效管理会话的推荐做法：

import { createClient } from "@opencode/sdk";

async function runCodingSession() {
  const client = createClient();

  // 创建新会话
  const session = await client.session.create();
  console.log("会话ID:", session.id);

  // 监听消息事件
  client.events.on("session.message", (event) => {
    if (event.sessionId === session.id) {
      console.log("AI:", event.content);
    }
  });

  // 发送编码请求
  await client.session.chat(session.id, {
    message: "创建一个简单的Express服务器",
    files: ["package.json"]  // 附加文件上下文
  });

  // 等待完成后继续对话
  await client.session.chat(session.id, {
    message: "添加一个健康检查端点"
  });
}

runCodingSession();

搜索功能

使用SDK进行代码和文件搜索：

// 文件名搜索
const files = await client.file.search("component");

// 内容搜索（grep）
const matches = await client.file.grep({
  pattern: "useState",
  path: "/src",
  fileTypes: ["ts", "tsx"]
});

// 符号搜索（需要LSP支持）
const symbols = await client.file.symbols({
  query: "handleClick",
  kind: "function"
});

完整示例

import { createClient } from "@opencode/sdk";

async function main() {
  const client = createClient();

  // 获取全局状态
  const global = await client.global.get();
  console.log(`OpenCode v${global.version}`);
  console.log(`工作目录: ${global.cwd}`);

  // 列出现有会话
  const sessions = await client.session.list();
  console.log(`现有会话数: ${sessions.length}`);

  // 创建新会话并发送消息
  const session = await client.session.create();

  await client.session.chat(session.id, {
    message: "分析当前项目的结构并给出改进建议"
  });

  // 订阅实时更新
  client.events.on("session.complete", (event) => {
    if (event.sessionId === session.id) {
      console.log("会话完成！");
    }
  });
}

main().catch(console.error);

下一步

接下来学习OpenCode的网络配置，包括代理设置和认证方法。