OpenCode 源码解析

第 20 讲：总结与实战指南——从源码到生产部署的完整路径

基于 OpenCode 源码 · 2026-07-27

一、架构全景回顾：一张图串起所有模块

packages/opencode (v1.17.13) · TypeScript Monorepo · Bun 1.3.14 · Effect 4.0 beta · SolidJS · Hono · Drizzle ORM

数据流向全景

Monorepo 包结构

二、三大设计哲学

哲学一：函数式编程 —— Effect 运行时贯穿一切

OpenCode 最显著的技术选择是将 Effect 4.0 作为整个应用的运行时基础。这不是一个可有可无的框架，而是整个架构的"操作系统"。

在 packages/opencode/src/cli/cmd/run.ts 的 CLI 入口中，每个命令的处理都通过 Effect.fn 声明：

// packages/opencode/src/cli/cmd/run.ts 第263行
export const RunCommand = effectCmd({
  command: "run [message..]",
  describe: "run opencode with a message",
  instance: (args) => !args.attach,
  directory: (args) => (args.dir && !args.attach
    ? path.resolve(process.cwd(), args.dir)
    : process.cwd()),
  handler: Effect.fn("Cli.run")(function* (args) {
    const { Agent } = yield* Effect.promise(
      () => import("@/agent/agent")
    )
    const flags = yield* RuntimeFlags.Service
    const localInstance = yield* InstanceRef
    // ... 所有副作用都被 Effect 追踪
  }),
})

Effect 带来的核心价值：

Desktop 端同样使用 Effect 管理主进程生命周期，packages/desktop/src/main/index.ts 第 106 行：

const main = Effect.gen(function* () {
  contextMenu({ showSaveImageAs: true })
  process.chdir(homedir())
  process.env.OPENCODE_DISABLE_EMBEDDED_WEB_UI = "true"

  const serverReady = Deferred.makeUnsafe<ServerReadyData>()

  yield* Effect.promise(() => app.whenReady())

  // 启动 sidecar 服务器
  const loadingTask = yield* Effect.gen(function* () {
    const { listener, health } = yield* Effect.promise(() =>
      spawnLocalServer(hostname, port, password, {
        userDataPath: app.getPath("userData"),
        onStdout: (msg) => writeLog("server", "stdout", { message: msg }),
        onExit: (code) => writeLog("utility", "sidecar exited", { code }, "warn"),
      }),
    )
    // ...
  }).pipe(Effect.forkChild)

  yield* Fiber.await(loadingTask)
  const windows = restoreMainWindows()
})

Effect.runFork(main)

哲学二：插件化 —— 一切皆可扩展

OpenCode 的插件系统（第 5 讲详细分析）不是事后补充，而是架构的核心设计。从 packages/plugin/src/index.ts 可以看到，插件通过 Hooks 接口 渗透到系统的每一个角落：

// packages/plugin/src/index.ts 第222行
export interface Hooks {
  dispose?: () => Promise<void>
  event?: (input: { event: Event }) => Promise<void>
  tool?: { [key: string]: ToolDefinition }
  auth?: AuthHook
  provider?: ProviderHook
  "chat.message"?: (input, output) => Promise<void>
  "chat.params"?: (input, output) => Promise<void>
  "chat.headers"?: (input, output) => Promise<void>
  "permission.ask"?: (input, output) => Promise<void>
  "command.execute.before"?: (input, output) => Promise<void>
  "tool.execute.before"?: (input, output) => Promise<void>
  "shell.env"?: (input, output) => Promise<void>
  "tool.execute.after"?: (input, output) => Promise<void>
  "experimental.chat.messages.transform"?: (input, output) => Promise<void>
  "experimental.chat.system.transform"?: (input, output) => Promise<void>
  "experimental.session.compacting"?: (input, output) => Promise<void>
  // ... 共 15+ 个 Hook 入口
}

插件可以：

哲学三：协议优先 —— ACP / MCP / LSP 三剑客

OpenCode 不把自己绑定到任何单一的交互模式。它实现了三大协议的互操作：

这种"协议优先"的设计意味着 OpenCode 既可以作为独立终端工具使用，也可以嵌入到 VS Code、Cursor、Windsurf 等 IDE 中，甚至可以通过 ACP 被其他 AI Agent 调用。

三、从源码到生产部署的完整路径

阶段一：本地开发环境搭建

OpenCode 使用 Bun 1.3.14 作为包管理器，Turborepo 作为任务编排工具。根目录 package.json 定义了完整的 workspace 结构：

// 克隆与初始化
git clone https://github.com/anomalyco/opencode.git
cd opencode
bun install

// 开发模式启动（TUI 界面）
bun dev

// 单独启动各组件
bun run dev:desktop    # Electron 桌面应用
bun run dev:web        # Web 前端
bun run dev:console    # 控制台服务

// 类型检查
bun typecheck

开发时的关键环境变量：

阶段二：生产部署

方式一：一键安装（推荐）

# 一键安装脚本
curl -fsSL https://opencode.ai/install | bash

# 或包管理器
npm i -g opencode-ai@latest
brew install anomalyco/tap/opencode     # macOS / Linux
scoop install opencode                  # Windows

# 自定义安装目录
OPENCODE_INSTALL_DIR=/usr/local/bin \
  curl -fsSL https://opencode.ai/install | bash

方式二：Server 模式部署

OpenCode 支持以独立 Server 模式运行，多个客户端可以同时连接：

# 启动 Server（后台模式）
opencode serve --port 4096

# 客户端连接
opencode run --attach http://localhost:4096 \
  --username opencode \
  --password your-password \
  "请帮我重构这个模块"

# Desktop 端自动管理 Sidecar Server
# packages/desktop/src/main/index.ts 第 327-346 行：
# 1. 动态分配端口 → 2. 启动 utilityProcess sidecar
# → 3. 等待 health check 通过 → 4. 创建渲染窗口

方式三：Desktop 应用

Desktop 端（packages/desktop）使用 Electron 42.3.3，通过 IPC 与渲染进程通信，内部通过 utilityProcess.fork() 启动 OpenCode Server 作为 Sidecar：

// packages/desktop/src/main/server.ts 第 55-67 行
export async function spawnLocalServer(
  hostname: string,
  port: number,
  password: string,
  options: SpawnLocalServerOptions,
) {
  const sidecar = join(dirname(fileURLToPath(import.meta.url)),
    "sidecar.js")
  const child = utilityProcess.fork(sidecar, [], {
    cwd: process.cwd(),
    env: createSidecarEnv(),
    serviceName: "opencode server",
    stdio: "pipe",
  })
  // 等待 sidecar 发送 "ready" 消息
  // 然后进行 health check 轮询
}

阶段三：生产配置

生产环境的核心配置文件是 .opencode.json（第 11 讲详细分析）。关键配置项：

{
  "model": {
    "default": "anthropic/claude-sonnet-4-20250514"
  },
  "provider": [
    {
      "id": "anthropic",
      "options": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      }
    }
  ],
  "plugin": [
    "opencode-plugin-github",
    ["opencode-plugin-custom", { "baseUrl": "https://api.example.com" }]
  ],
  "permission": {
    "default": "ask",
    "rules": [
      { "action": "allow", "pattern": "*.md", "permission": "fs_write" }
    ]
  },
  "agent": {
    "default": "build"
  }
}

四、如何基于 OpenCode 构建自己的 AI 开发工具

路径一：编写自定义插件

这是最简单的扩展方式。创建一个插件只需导出一个符合 Plugin 签名的函数：

// my-plugin.ts
import type { Plugin, PluginInput, Hooks, ToolDefinition }
  from "@opencode-ai/plugin"

// 定义一个自定义 Tool
const myTool: ToolDefinition = {
  description: "查询内部知识库",
  parameters: {
    type: "object",
    properties: {
      query: { type: "string", description: "搜索关键词" },
    },
    required: ["query"],
  },
  execute: async (args) => {
    const result = await searchKnowledgeBase(args.query)
    return { content: result }
  },
}

// 插件主函数
export const server: Plugin = async (input: PluginInput, options) => {
  return {
    // 注册自定义 Tool
    tool: {
      "knowledge-search": myTool,
    },
    // 拦截聊天消息
    "chat.message": async ({ sessionID, message }, output) => {
      console.log(`Session ${sessionID}: ${message}`)
    },
    // 自定义 Shell 环境变量
    "shell.env": async (input, output) => {
      output.env["MY_CUSTOM_VAR"] = "production"
    },
  } satisfies Hooks
}

路径二：二次开发 Core 模块

如果你需要更深层的定制，可以直接修改 packages/core 中的模块。由于 Effect 的模块化设计，每个服务都是独立的：

自定义 Agent 示例（基于源码结构）：

// 自定义 Agent 配置
// 在 .opencode.json 中添加：
{
  "agent": {
    "custom-reviewer": {
      "system": "你是一个代码审查专家...",
      "tools": ["read", "grep", "diff"],
      "permissions": {
        "fs_write": "deny",
        "bash": "ask"
      }
    }
  }
}

// 运行时通过 Tab 键切换 Agent
// 内置 Agent: build (默认), plan (只读), general (搜索)

路径三：集成到你的产品中

OpenCode 提供了 SDK（packages/sdk）和 HTTP API，可以集成到任何产品中：

import { createOpencodeClient } from "@opencode-ai/sdk/v2"

// 创建客户端
const client = createOpencodeClient({
  baseUrl: "http://localhost:4096",
  directory: "/path/to/project",
  headers: {
    "Authorization": "Basic " + btoa("opencode:password"),
  },
})

// 创建 Session 并发送消息
const session = await client.session.create()
const response = await client.session.prompt({
  sessionID: session.data.id,
  message: { content: "分析这段代码的性能问题" },
  model: { providerID: "anthropic", modelID: "claude-sonnet-4" },
})

// 监听实时事件
client.event.on("message", (event) => {
  console.log("收到消息:", event)
})

五、20 讲学习路径回顾

六、下一步行动建议

七、致谢

系列导航

← 第 19 讲：Agent 核心系统 | 第 20 讲（最终讲）

📡 关注公众号，获取更多技术深度解析

AI 前沿 · 源码解析 · 架构设计 · 工程实践

扫码关注，第一时间获取最新内容