OpenCode Guide
Navigate: Menu

Intro (入门)

Usage (使用指南)

Configure (详细配置)

Develop (开发)

Console (控制台)

@opencode/sdk/effect 是 Effect 原生的嵌入式 SDK。操作返回带类型的 Effect 与 Stream，关闭所属 Scope 会释放 router、Location 服务、fiber 以及插件注册。
bun add @opencode/sdk/effect@4.0.1

创建宿主

在 Effect.scoped 内创建宿主，然后使用其生成的 API 分组或 sessions 别名。
import { AbsolutePath, Location, OpenCode } from "@opencode/sdk/effect"
import { Effect } from "effect"

const program = Effect.scoped(
  Effect.gen(function* () {
    const opencode = yield* OpenCode.create()
    const session = yield* opencode.sessions.create({
      location: Location.Ref.make({ directory: AbsolutePath.make("/workspace") }),
    })
    yield* opencode.sessions.prompt({
      sessionID: session.id,
      text: "Review the current changes",
    })
    return session
  }),
)

const session = await Effect.runPromise(program)
嵌入式宿主使用与 @opencode/client/effect 相同的 schema 值、已声明的错误、请求选项和 Stream。
const info = yield* opencode.server.info()
const sessions = yield* opencode.sessions.list()

流式事件

流式端点返回 Effect 的 Stream 值。若消费者应在后台运行，请在宿主 Scope 中 fork 它们。
import { Effect, Stream } from "effect"

yield* opencode.events.subscribe().pipe(
  Stream.runForEach((event) => Effect.logInfo("OpenCode event", { type: event.type })),
  Effect.forkScoped,
)

自定义

通过注册 Effect 插件来定制你的 OpenCode 实例。使用嵌入式宿主可自定义智能体、模型、工具及其他行为：
import { Plugin } from "@opencode/plugin/effect"
import { Effect } from "effect"

const plugin = Plugin.define({
  id: "customize-agent",
  effect: (ctx) =>
    Effect.gen(function* () {
      const agent = ctx.agent
      yield* agent.transform((agents) => {
        agents.update("build", (agent) => {
          agent.description = "Builds features and fixes bugs for our team"
        })
      })
    }),
})

yield* opencode.plugin(plugin)
参阅完整的 Effect 插件文档，了解插件钩子、转换、工具以及完整的插件上下文。

层（Layer）

当嵌入式宿主应当作为应用服务时，请使用 OpenCode.layer()。
import { OpenCode } from "@opencode/sdk/effect"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  const opencode = yield* OpenCode.Service
  return yield* opencode.server.info()
})

const health = await Effect.runPromise(program.pipe(Effect.provide(OpenCode.layer())))