Doramagic.ai
English

Doramagic 项目包 · 项目说明书

opencode 项目

opencode 是一个面向「软件开发与交付」的开源项目，重点覆盖 AI Agent 框架、Agent 工作流构建；Doramagic 已整理安装入口、说明书、上下文包和风险边界，方便先判断再试用。

系统架构与核心服务

本页面向希望理解 opencode（v1.15.13）整体技术形态的开发者梳理其系统架构、Monorepo 布局、核心服务边界与运行时关系。opencode 是一套"AI 驱动的开发工具"，由 CLI、桌面端、Web 控制台、企业版、统计服务、Slack 集成、JavaScript/Go SDK、HTTP 录制回放、LLM 协议抽象、插件系统以及 GitHub Action...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 4.1 packages/opencode —— 运行时主入口

继续阅读本节完整说明和来源证据。

章节 4.2 packages/core —— 业务核心

继续阅读本节完整说明和来源证据。

章节 4.3 packages/llm —— LLM 协议抽象

继续阅读本节完整说明和来源证据。

本页面向希望理解 opencode（v1.15.13）整体技术形态的开发者梳理其系统架构、Monorepo 布局、核心服务边界与运行时关系。opencode 是一套"AI 驱动的开发工具"，由 CLI、桌面端、Web 控制台、企业版、统计服务、Slack 集成、JavaScript/Go SDK、HTTP 录制回放、LLM 协议抽象、插件系统以及 GitHub Action 共同构成。整套工程在 Bun 1.3.14 与 TypeScript 5.8 之上构建，并以 Effect、Hono、Solid、Astro、SST 等为核心依赖。

1. 顶层目标与设计原则

opencode 的目标是让开发者以一致的体验在不同终端（终端 CLI、桌面 TUI、Web 控制台、GitHub Issue/PR、企业控制台）调用多模型 LLM 完成编码任务。其架构遵循以下原则：

  • 多端复用同一核心：所有客户端最终都通过 packages/opencode 提供的 server/CLI 入口（bin/opencode）获得 LLM 会话能力 package.json:21-23。
  • 运行时分层：CLI 与服务端使用 Node/Bun，浏览器条件分支走 --conditions=browser；数据库连接器在 Bun 与 Node 下分别走 db.bun.ts 与 db.node.ts package.json:19-25。
  • 可插拔模型与协议：packages/llm 抽象统一 Schema（LLMRequest、LLMEvent 等），各 Provider 仅做"协议转换层"，并提供 cache: "auto" 默认策略 packages/llm/README.md:1-20。
  • Effect-first 服务编排：CLI、Core、内部服务大量使用 Effect 框架；@opencode-ai/cli 显式声明依赖 effect 与 @effect/platform-node packages/cli/package.json:13-19。
  • 可观测与可回放：内置 http-recorder 提供 Cassette/Redactor/Matching 原语，使协议层测试可在脱机环境下重放 packages/http-recorder/README.md:1-8。

2. Monorepo 工作区

根 package.json 通过 workspaces.packages 显式声明 5 组工作区，并使用 Bun 作为包管理器。

工作区主要内容关键依赖
packages/*核心 SDK、CLI、LLM、Plugin、Script、Web、HTTP-Recorder 等@opencode-ai/sdk, effect, hono, zod
packages/console/*控制台 SolidStart 应用@solidjs/start, solid-js
packages/stats/*统计与遥测应用SST, @sentry/solid
packages/sdk/js对外发布的 JS SDKcross-spawn, @hey-api/openapi-ts
packages/slackSlack 集成（依赖根 catalog:）

资料来源：package.json:32-38

dev:* 脚本可分别启动子项目：

bun run dev               # 启动 packages/opencode（浏览器条件）
bun run dev:desktop       # 启动 packages/desktop
bun run dev:web           # 启动 packages/app（Astro + Starlight）
bun run dev:console       # 启动 packages/console/app（SolidStart）
bun run dev:stats         # 启动 packages/stats/app（SST shell）

资料来源：package.json:13-19

3. 系统总体架构

下图为 opencode 的总体架构视角：客户端层（TUI / 桌面 / Web / 控制台 / Slack / GitHub Action）通过 @opencode-ai/sdk 与 opencode serve 子系统交互；核心服务（CLI、Server、HTTP API、Provider Gateway、Session）由 packages/core 与 packages/opencode 共同承载；packages/llm 与 packages/http-recorder 提供协议与录制回放能力；底层数据落到 SQLite（Bun/Node 两种适配）。

graph TD
  subgraph Clients[客户端层]
    TUI[终端 TUI / OpenTUI]
    Desktop[Desktop 应用]
    Web[Web 控制台 packages/web]
    Console[Enterprise Console]
    Slack[Slack 集成]
    GHA[GitHub Action /oc]
  end

  subgraph SDK[SDK 层]
    JSSDK[packages/sdk/js v2]
    Plugin[packages/plugin]
  end

  subgraph Core[核心服务 packages/opencode + packages/core]
    CLI[CLI 入口 packages/cli]
    Serve[opencode serve]
    HTTP[HTTP API /server/routes]
    Gateway[Provider Gateway]
    Session[Session / Storage]
  end

  subgraph LLM[LLM 协议层 packages/llm]
    Schema[Canonical Schema]
    Proto[Provider Protocols]
    Cache[Cache Hints]
  end

  subgraph Infra[基础设施]
    Recorder[http-recorder]
    DB[(SQLite db.bun / db.node)]
    Copilot[GitHub Copilot 适配]
  end

  TUI --> CLI
  Desktop --> CLI
  Web --> CLI
  Console --> CLI
  Slack --> CLI
  GHA --> CLI
  TUI --> JSSDK
  Desktop --> JSSDK
  Web --> JSSDK
  CLI --> Serve
  CLI --> Session
  Serve --> HTTP
  HTTP --> Gateway
  Gateway --> Proto
  Gateway --> Copilot
  Proto --> Schema
  Schema --> Cache
  Serve --> Recorder
  Session --> DB

4. 核心包与职责

4.1 `packages/opencode` —— 运行时主入口

4.2 `packages/core` —— 业务核心

packages/core 承载 Session、Provider、Project、Storage 等领域模型，并通过 src/github-copilot 子包处理 GitHub Copilot 专属协议。仓库中明确提示该子包为"仅用于 GitHub Copilot 的临时实现"，不要直接修改其兼容层代码 packages/core/src/github-copilot/README.md:1-4。

4.3 `packages/llm` —— LLM 协议抽象

LLM 层是 Provider Gateway 的内部实现基础，关键特性包括：

  • 暴露高层 API：LLM.generate / LLM.stream、消息与工具构造函数 packages/llm/README.md:3-9。
  • LLMClient.prepare(request) 用于在不真正发送的情况下编译请求，便于检查与测试 packages/llm/README.md:10-12。
  • 缓存默认开启（cache: "auto"），自动放置 3 个断点：最后一个 tool 定义、最后一条 system 段、最后一条 user 消息；这在 tool-use 循环中可最大化前缀复用 packages/llm/README.md:25-31。
  • 协议差异：Anthropic/Bedrock 使用 cache_control/cachePoint 内联标记；OpenAI 与 Gemini 走服务端隐式缓存，auto 在其上是 no-op packages/llm/README.md:18-22。
  • 细粒度策略：可指定 tools / system / messages / ttlSeconds；ttlSeconds >= 3600 触发 Anthropic/Bedrock 的 1 小时缓存，否则 5 分钟 packages/llm/README.md:43-48。

4.4 `packages/cli` —— Effect CLI 框架

4.5 `packages/sdk/js` —— 对外 SDK

4.6 `packages/plugin` —— 插件体系

4.7 `packages/web`、`packages/console`、`packages/enterprise` —— Web 端

包框架备注
packages/webAstro + Starlight文档主题 toolbeam-docs-theme，依赖 shiki、marked-shiki 做代码高亮 packages/web/package.json:11-19
packages/console/appSolidStart通过 ulimit -n 10240 提升文件描述符限制，避免本地 dev 端口耗尽 package.json:14-14
packages/enterpriseSolidStart企业版控制台，模板来自 Solid CLI packages/enterprise/README.md:1-3

4.8 `packages/script` 与 `packages/slack`

5. 运行时与数据流

opencode 的请求/响应生命周期可概括为：客户端 → SDK/CLI → Server → Provider Gateway → 上游 LLM 协议 → 返回事件流。下图以 stream 为例展示从工具调用到事件回放的过程。

sequenceDiagram
  participant C as 客户端 (TUI/Web/桌面)
  participant SDK as @opencode-ai/sdk
  participant CLI as opencode serve / CLI
  participant S as Session
  participant G as Provider Gateway
  participant L as LLM 协议层
  participant R as http-recorder

  C->>SDK: 发起 prompt/工具调用
  SDK->>CLI: HTTP API + 流式订阅
  CLI->>S: 读取/写入会话
  CLI->>G: 构造 LLMRequest（含 cache hints）
  G->>L: 协议转换 (Anthropic/OpenAI/Gemini/...)
  L-->>G: LLMEvent 流 (textDelta/toolCall/finish)
  G-->>CLI: 规范化事件
  CLI-->>SDK: 推送事件 / 持久化
  R-->>L: 录制/回放（测试或审计）

要点：

6. HTTP API 与测试闭环

packages/opencode 通过三条互斥的 test:httpapi 阶段保证 API 契约不退化：

模式目的
coverage验证端点被请求与响应字段被覆盖
auth验证鉴权场景（未带 token、带错 token、多用户）
effect验证 Effect 流式与并发语义

资料来源：packages/opencode/package.json:11-12

测试结果以 JUnit 形式落到 .artifacts/unit/junit.xml，便于在 CI 中聚合 packages/opencode/package.json:9-10。

7. HTTP 录制与回放（http-recorder）

packages/http-recorder 为协议层提供 Cassette 形式的录制回放能力，主要文件包括：

模块作用
redactor.ts组合式 Redactor，对 header、url、body 做脱敏
redaction.ts底层 header/URL 原语 + Secret 模式识别
schema.tsEffect Schema，定义 Cassette JSON 格式
matching.ts请求匹配、规范化、Sequential Cursor、不一致诊断

资料来源：packages/http-recorder/README.md:3-7

这一层使得 Provider Gateway 的回归测试可离线运行，规避了真实模型在 CI 中的不可重现问题。

8. 客户端矩阵

客户端技术栈关键集成点
TUIOpenTUI（Solid + keymap）通过 @opencode-ai/plugin/tui 扩展；可选 peer deps packages/plugin/package.json:18-32
Desktop独立包 packages/desktop通过 bun --cwd packages/desktop dev 启动 package.json:13-13
Web（文档）Astro + Starlight文档站，使用 toolbeam-docs-theme packages/web/package.json:16-19
Console / EnterpriseSolidStart通过根 dev:console 启动 package.json:14-14
GitHubAction 形式触发词 /oc 或 /opencode github/README.md:18-19
Slackpackages/slack工作区之一 package.json:32-38

9. GitHub 集成

github 子包发布为 GitHub Action：

  • 入口 index.ts，依赖 @opencode-ai/sdk、@actions/core、@actions/github、@octokit/rest 等 github/package.json:11-16。
  • 安装方式：opencode github install，自动完成 GitHub App 安装、Workflow 创建、Secret 配置 github/README.md:7-9。
  • 手动安装时需提供 ANTHROPIC_API_KEY、GITHUB_TOKEN 与 model 输入；工作流通过 uses: anomalyco/opencode/github@latest 调用 github/README.md:16-46。

10. 配置与目录加载

v1.15.13 引入了"从打开位置向上递归加载 Config"的能力，使目录级配置与 Provider 策略按预期生效。社区曾多次反馈配置作用域不够直观，本次更新直接回应了"在子目录打开终端时配置不生效"类问题。

Session 现在可通过 API/SDK 写入自定义元数据，便于在企业/团队场景下做上下文标签和审计。

11. 社区关注点映射

下列是社区高互动议题与系统架构的对应关系：

议题涉及模块
#16992 提议新增 /btw 命令TUI 命令面板（@opentui/core + plugin/tui）
#1686 期望 OpenAI ChatGPT 订阅登录Provider Gateway + packages/llm 协议适配层
#2072 询问 Cursor CLI 支持LLM 协议层（Proto）+ SDK v2
#8501 希望展开 [Pasted ~N lines] 摘要TUI 渲染层 + Session 持久化
#4695 提议 Speech-to-Text 语音输入Desktop/Web 客户端 → SDK 输入流

资料来源：community context（Top Community Issues by engagement）

这些议题共同指向"多模型协议 + 强可扩展 TUI"两个核心子系统，验证了 packages/llm 与 packages/plugin 在架构中的中心地位。

12. 常见失败模式

  • 配置未生效：在子目录打开仓库时，目录级 opencode.json 可能因为搜索路径被截断而未加载。v1.15.13 起改为"从打开位置向上加载"，但自定义 Provider 仍需确认 provider 节点命名与 packages/llm 协议映射一致。
  • 缓存不命中：当 messages 策略不是 latest-user-message 时，最后一条 user 断点可能不会落在工具循环的"逻辑前缀"上，应改用 cache: "auto" 或显式 CacheHint packages/llm/README.md:25-31。
  • One-shot 请求被无谓写入缓存：低于 Provider 的"最小可缓存 token"阈值时，auto 会安全地 no-op；如对延迟敏感可显式 cache: "none" packages/llm/README.md:35-37。
  • Bun vs Node DB 适配器不一致：自定义脚本若绕过 imports.#db 而直接引用 SQLite 库，可能在 Node 上找不到原生模块。统一通过 imports 解析即可 packages/opencode/package.json:23-26。
  • GitHub Copilot 协议变更：仓库明确警告 packages/core/src/github-copilot 为临时实现，请勿直接修改其文件 packages/core/src/github-copilot/README.md:1-4。
  • 测试录制器误过滤关键 header：http-recorder 的 Redactor 若匹配过宽，会将鉴权 header 误删，影响回放断言；调整 redaction.ts 中的 secret 模式顺序即可 packages/http-recorder/README.md:3-7。

13. 开发与构建入口

See Also

资料来源：package.json:32-38

LLM 集成、代理与认证

LLM 集成、代理与认证模块是 opencode 项目的核心基础设施，负责将不同厂商的大型语言模型（LLM）API 统一抽象为一致的内部接口，并管理用户与各提供商之间的认证凭据。该模块在架构上分为两层：

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 顶层导出与构造器

继续阅读本节完整说明和来源证据。

章节 缓存策略

继续阅读本节完整说明和来源证据。

概述

LLM 集成、代理与认证模块是 opencode 项目的核心基础设施，负责将不同厂商的大型语言模型（LLM）API 统一抽象为一致的内部接口，并管理用户与各提供商之间的认证凭据。该模块在架构上分为两层：

  • 核心 LLM 客户端层（packages/llm）：提供协议无关的请求编译、消息模型、流式事件、缓存策略等通用能力。
  • 提供商插件与认证层（packages/core/src/plugin/provider、packages/opencode/src/provider）：针对具体厂商（Anthropic、OpenAI、Amazon Bedrock、Google Gemini、GitHub Copilot 等）实现协议适配和凭据获取。

社区中最受关注的需求之一是 OpenAI 的 ChatGPT 订阅登录（#1686），以及 对 Cursor CLI 等新兴提供商的支持（#2072）。这些都直接落在本模块的扩展点上。

资料来源：packages/llm/README.md:1-20、packages/core/src/github-copilot/README.md:1-5。

架构概览

下图展示了从用户调用到底层 LLM API 的整体数据流：

graph TD
    A[用户/SDK 调用方] --> B[packages/opencode/src/provider]
    B --> C{认证层}
    C --> C1[API Key 静态凭据]
    C --> C2[OAuth/订阅登录]
    C --> C3[环境变量]
    B --> D[packages/llm LLMClient]
    D --> E[协议编译层<br/>packages/llm/src/protocols]
    E --> F1[Anthropic 协议]
    E --> F2[OpenAI 协议]
    E --> F3[Bedrock 协议]
    E --> F4[Gemini 协议]
    E --> F5[GitHub Copilot 协议]
    F1 --> G1[Anthropic API]
    F2 --> G2[OpenAI / 兼容 API]
    F3 --> G3[AWS Bedrock]
    F4 --> G4[Google Gemini]
    F5 --> G5[GitHub Copilot]
    D --> H[LLMEvent 流]
    H --> A

各层职责分工明确：上层使用统一的 LLM.generate / LLM.stream 接口发起请求，认证层注入凭据，协议层将通用请求编译为厂商特定的 wire format（如 Anthropic 的 cache_control、Bedrock 的 cachePoint），最终通过 LLMEvent.is.* 类型守卫以流式方式回传结果。

资料来源：packages/llm/README.md:1-40、packages/llm/src/llm.ts。

LLM 客户端核心

顶层导出与构造器

LLMClient 是协议无关的统一入口，常用的导出与构造器包括：

名称作用
LLM.generate单次生成请求（re-exported from LLMClient）
LLM.stream流式生成请求（re-exported from LLMClient）
LLMClient.prepare(request)仅编译请求，不发送，便于测试与检查
Message.user(prompt)用户消息构造器
Message.assistant(...)助手消息构造器
Message.tool(...)工具消息构造器
Model.make(...)模型对象构造器
ToolCallPart.make(...)工具调用片段构造器
ToolResultPart.make(...)工具结果片段构造器
ToolDefinition.make(...)工具定义构造器

所有构造器都基于规范化的 Schema 类，将 (system: string, prompt: string) 这类输入归一化为内部规范模型。

资料来源：packages/llm/README.md:1-15。

缓存策略

提示缓存默认开启。每一个 LLMRequest 都会被解析为 cache: "auto"，除非调用方显式指定 cache: "none"。

不同协议对 CacheHint 的翻译方式：

协议Wire Format
Anthropiccache_control
Amazon BedrockcachePoint
OpenAI隐式缓存（服务端处理，无需内联标记）
Google Gemini隐式缓存（服务端处理，无需内联标记）

"auto" 模式会在以下三个位置放置缓存断点：

  1. 最后一个工具定义 之后
  2. 最后一个系统片段 之后
  3. 最新的用户消息 边界

最后一条最为关键：在工具调用循环中，单次用户回合会展开为多轮助手/工具往返，它们共享同一前缀。把 Error with Openai API: output new_sensitive (1027)

Please check that you have set the OPENAI_API_KEY environment variable with a valid API key.

资料来源：packages/llm/README.md:1-20、packages/core/src/github-copilot/README.md:1-5。

前端、桌面与 UI 组件

OpenCode 项目的"前端、桌面与 UI 组件"由多个相互独立的 npm workspace 包组成，分别覆盖桌面端、浏览器端 Web App、共享 UI 组件库、文档站以及控制台后端等不同交付形态。根目录的 package.json 通过 Bun workspaces 统一管理这些包，并提供 dev:desktop、dev:web、dev:console 等并行开发脚...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 顶层工作区

继续阅读本节完整说明和来源证据。

章节 顶层脚本

继续阅读本节完整说明和来源证据。

章节 构建体系

继续阅读本节完整说明和来源证据。

概述

OpenCode 项目的"前端、桌面与 UI 组件"由多个相互独立的 npm workspace 包组成，分别覆盖桌面端、浏览器端 Web App、共享 UI 组件库、文档站以及控制台后端等不同交付形态。根目录的 package.json 通过 Bun workspaces 统一管理这些包，并提供 dev:desktop、dev:web、dev:console 等并行开发脚本。资料来源：package.json:dev:desktop、资料来源：package.json:dev:web、资料来源：package.json:dev:console。

graph TD
    A[opencode monorepo] --> B[packages/app<br/>SolidStart Web App]
    A --> C[packages/desktop<br/>Tauri 桌面应用]
    A --> D[packages/ui<br/>共享 UI 组件库]
    A --> E[packages/web<br/>Astro 文档站]
    A --> F[packages/console/app<br/>控制台 SolidStart]
    A --> G[packages/enterprise]
    A --> H[packages/opencode<br/>CLI 核心]
    D -.提供组件与主题.-> B
    D -.提供组件与主题.-> C
    D -.提供组件与主题.-> F

工作区与脚本约定

顶层工作区

根 package.json 声明的 workspaces 列表同时覆盖子包、Slack 集成、SDK 与统计服务：

工作区路径类型主要技术栈
packages/*通用子包各包独立
packages/console/*控制台子包SolidStart
packages/stats/*统计子包SST / Bun
packages/sdk/jsJS SDKTypeScript
packages/slackSlack 集成独立服务

资料来源：package.json:workspaces。

顶层脚本

脚本作用
dev在 packages/opencode 中以 browser 条件运行 src/index.ts
dev:desktop在 packages/desktop 中启动桌面端开发服务
dev:web在 packages/app 中启动 Web 开发服务
dev:console调整文件描述符后启动 packages/console/app
dev:stats在 production 阶段下进入 packages/stats/app 的开发 shell
lint使用 oxlint 静态检查
typecheck通过 bun turbo typecheck 执行全仓类型检查

资料来源：package.json:scripts。

桌面应用（Desktop）

构建体系

桌面应用以 Tauri 为打包与原生壳层。图标脚本明确要求使用 bun tauri icon 命令生成多平台图标，并输出到 src-tauri/icons/{environment} 目录。资料来源：packages/desktop/icons/README.md。

图标与多渠道资源

packages/desktop/icons/README.md 描述了桌面端图标的工作流：

  1. 将源图保存为 packages/desktop/app-icon.png。
  2. 在 packages/desktop 目录中执行 bun tauri icon -o src-tauri/icons/{environment}。
  3. macOS 平台需使用 Image2Icon 工具以 'Big Sur Icon' 预设重新生成 icon.icns，避免阴影与内边距问题。
  4. 未打包的 Electron/macOS 开发模式下，需通过 app.dock.setIcon() 加载 PNG；每个渠道目录中的 dock.png 应与从 icon.icns 抽取的 [email protected] 保持一致。
上述流程虽主要约束 macOS 资源，但 src-tauri/icons/{environment} 的目录布局说明桌面端是按发布渠道（environment）组织多套图标的。资料来源：packages/desktop/icons/README.md。

与其他前端包的关系

桌面端开发时通常会同时依赖 packages/ui 提供组件和主题，并通过 packages/opencode 的二进制 opencode 命令作为核心后端。packages/opencode/package.json 中定义的 bin.opencode 指向 ./bin/opencode，说明桌面壳层会以子进程或进程间通信方式复用该 CLI。资料来源：packages/opencode/package.json:bin。

Web 应用（App）

框架与运行模式

packages/app 由 dev:web 脚本直接启动（SST/Astro 之外另起一个 SolidStart 进程），其 opencode 包通过 bun run --conditions=browser ./src/index.ts 进入浏览器条件分支。资料来源：package.json:dev:web、资料来源：packages/opencode/package.json:dev。

浏览器条件下的差异

packages/opencode 的 imports 字段中 #db 按运行时区分实现：

运行时实现
bun./src/storage/db.bun.ts
node./src/storage/db.node…

资料来源：packages/opencode/package.json:imports。这种条件导入同样适用于 Web 端，让同一个 CLI 入口可以在浏览器与服务器环境之间共享业务代码。

共享 UI 组件库

包元信息

packages/ui 是一个独立可发布的 UI 组件包，名字空间为 @opencode-ai/ui，并通过 exports 同时暴露 v1 与 v2 两套组件：

  • "./v2/components/*": "./src/v2/components/*.tsx"
  • "./v2/*": "./src/v2/components/*.tsx"
  • "./v2/styles/*": "./src/v2/styles/*"

资料来源：packages/ui/package.json:exports。

依赖栈

UI 组件库的核心依赖与开发依赖按职责划分如下：

类别主要依赖用途
核心渲染solid-jsSolid 框架
组件原语@kobalte/core无样式可访问组件
样式tailwindcss、@tailwindcss/vite原子化样式与构建
Diff 渲染@pierre/diffs代码差异组件
语法高亮@shikijs/transformersShiki 转换器
行为原语@solid-primitives/event-listener、@solid-primitives/bounds事件与边界观察
测试bun test内置测试运行器
代码生成script/tailwind.tsTailwind 类名生成
类型检查tsgo --noEmit原生 TS 预览编译器

资料来源：packages/ui/package.json:dependencies、资料来源：packages/ui/package.json:devDependencies、资料来源：packages/ui/package.json:scripts。

主题与样式管线

UI 库自带 dev、generate:tailwind 脚本，并通过 vite-plugin-icons-spritesheet 把图标生成雪碧图。组件由 Tailwind 原子类与 Kobalte 原语组合而成，在 src/v2 目录下形成新一代组件体系。资料来源：packages/ui/package.json:scripts、资料来源：packages/ui/package.json:devDependencies。

跨端复用

packages/app 与 packages/desktop 都在 devDependencies 中通过 workspace:* 形式引用 opencode，间接消费 @opencode-ai/core 与 @opencode-ai/sdk 提供的数据模型与服务契约。资料来源：packages/ui/package.json:dependencies。

文档站（Web）

框架基础

packages/web 基于 Astro + Starlight 模板。packages/web/README.md 引用了 "Starlight Starter Kit: Basics" 模板与 npm create astro@latest -- --template starlight 创建命令。资料来源：packages/web/README.md。

包元信息

文档站主要依赖与开发依赖：

类别包用途
内容marked、marked-shiki、shiki、luxon文档渲染与时间格式化
链接rehype-autolink-headings标题锚点
数据处理remeda、fuzzysort工具函数
框架solid-js交互组件
文档主题toolbeam-docs-themeStarlight 主题
类型vscode-languageserver-typesLSP 协议类型
开发opencode (workspace)自家 CLI

资料来源：packages/web/package.json:dependencies、资料来源：packages/web/package.json:devDependencies。

目录结构

packages/web/README.md 描述的 Starlight 项目结构为：

.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

资料来源：packages/web/README.md。

控制台与后端前端（Console / Enterprise）

控制台

packages/console/app/README.md 说明控制台应用使用 SolidStart 框架。根 package.json 的 dev:console 脚本会在启动前调用 ulimit -n 10240 提升文件描述符上限，以满足控制台在开发态的并发需求。资料来源：packages/console/app/README.md、资料来源：package.json:dev:console。

企业版

packages/enterprise 同样基于 SolidStart，对应包通过 workspaces 间接被消费。README 中描述的内容与控制台一致地引用了 npm init solid@latest。资料来源：packages/enterprise/README.md。

graph TD
    subgraph Web[浏览器端交付]
      A1[packages/app<br/>主 Web App]
      A2[packages/web<br/>Astro 文档站]
    end
    subgraph Native[桌面端交付]
      B1[packages/desktop<br/>Tauri 壳]
      B2[src-tauri/icons/*<br/>渠道化图标]
    end
    subgraph Console[后端前端]
      C1[packages/console/app<br/>SolidStart]
      C2[packages/enterprise<br/>SolidStart]
    end
    D[packages/ui<br/>共享组件 + 主题] --> A1
    D --> B1
    D --> C1
    D --> C2
    E[packages/opencode<br/>CLI 核心] --> A1
    E --> B1

主题、样式与多语言资源

顶层品牌资源

根 README.md 通过 <picture> 标签分别引用 packages/console/app/src/asset/logo-ornate-dark.svg 与 logo-ornate-light.svg，结合 prefers-color-scheme 实现深浅色自适应。资料来源：README.md:logo。

多语言 README 索引

根 README.md 在顶部维护了多语言版本链接，覆盖简体中文、繁體中文、韩文、德文、西班牙文、法文、意大利文、丹麦文、日文、波兰文、俄文、波斯尼亚文、阿拉伯文、挪威文、巴西葡萄牙文、泰文、土耳其文与乌克兰文。资料来源：README.md:languages。

跨端主题共享

由于 @opencode-ai/ui 同时被 packages/app、packages/desktop、packages/console/app 引用，主题色、字体与图标雪碧图逻辑只需在 packages/ui 一处定义。资料来源：packages/ui/package.json:exports。

SDK 与插件对 UI 的影响

SDK 暴露面

@opencode-ai/sdk 暴露多个端点（./v2、./v2/client、./v2/server 等），下游 UI 层可通过 SDK client 与服务端 API 通信。资料来源：packages/sdk/js/package.json:exports。

插件 SDK

@opencode-ai/plugin 把插件入口分拆为 ./tool 与 ./tui 两条导出，依赖 effect 与 zod 描述工具与终端 UI 协议，并通过可选 peer 依赖 @opentui/core、@opentui/keymap、@opentui/solid 与终端 UI 框架解耦。资料来源：packages/plugin/package.json:exports、资料来源：packages/plugin/package.json:peerDependencies。

与社区关注点的对应

桌面与 UI 体验相关讨论

  • 粘贴文本展开（#8501）：希望在 TUI 中对 [Pasted ~1 lines] 占位提供"展开"动作。由于粘贴摘要主要发生在 CLI 会话与 TUI 中，前端 UI 在提供相同体验时需要保持与服务端协议一致。资料来源：issue #8501。
  • Speech-to-Text 语音输入（#4695）：语音转写流程通常会先落到 Web/桌面端的输入框，再注入会话；UI 组件库需要提供可挂载的麦克风按钮与状态指示。资料来源：issue #4695。
  • /btw 命令（#16992）：作为 TUI 快捷命令，其实现位置通常在 packages/opencode 内部的命令解析器；UI 层需在 TUI/Web/桌面端保持一致的提示与回显。资料来源：issue #16992。

第三方工具与认证接入

  • OpenAI ChatGPT 订阅登录（#1686）：影响 packages/opencode 中 OAuth 流程与 packages/ui 的登录页面，桌面/Web 端均需在同一 UI 组件中提供入口。资料来源：issue #1686。
  • Cursor CLI 支持（#2072）：若新增 Cursor 提供方，UI 需要在模型选择面板中暴露新的条目，并复用 packages/ui 的下拉与徽章组件。资料来源：issue #2072。

v1.15.13 同步说明

社区上下文指出 v1.15.13 在 TUI 之外的改进包括"会话可通过 API 与 SDK 存储自定义元数据（@shantur）"以及"配置从打开位置向上加载"，前者与 packages/sdk/js 的 v2 API 扩展相关，后者与 CLI 启动逻辑相关，间接影响前端显示"工作目录配置"等信息的来源。资料来源：v1.15.13 release notes（社区上下文引用）。

开发与构建工作流

入口与测试脚本

  • packages/opencode 通过 bun test 跑单元测试，CI 模式下将 junit 报告写入 .artifacts/unit/junit.xml。资料来源：packages/opencode/package.json:test:ci。
  • HTTP API 通过 script/httpapi-exercise.ts 进行 coverage / auth / effect 三种模式演练。资料来源：packages/opencode/package.json:test:httpapi。
  • packages/ui 使用 bun test src 跑测试，同样产出 junit 报告。资料来源：packages/ui/package.json:test:ci。

端到端验证

packages/ui 引入 @playwright/test（由 package.json 的 catalog 统一管理）作为浏览器端 E2E 验证手段。资料来源：package.json:catalog。

故障模式与注意事项

桌面图标生成

packages/desktop/icons/README.md 明确指出：仅靠 app-icon.png 生成的 icon.icns 在 macOS 上缺少预期的阴影与内边距，必须通过 Image2Icon 的 'Big Sur Icon' 预设重新生成，否则应用图标会"显得比预期更大"。资料来源：packages/desktop/icons/README.md。

Tauri 渠道目录

图标目录按 src-tauri/icons/{environment} 切分渠道，意味着不同环境（dev、staging、release）必须各自拥有完整图标集；只更新根目录的 app-icon.png 不会自动同步到已存在的渠道目录。资料来源：packages/desktop/icons/README.md。

GitHub Copilot 兼容层

packages/core/src/github-copilot/README.md 声明该目录为 GitHub Copilot 兼容性临时包，且"不适用于支持 completions/responses API 的 OpenAI 兼容提供方"，提醒开发者避免在通用提供方逻辑中复用其代码。资料来源：packages/core/src/github-copilot/README.md。

HTTP 录制器

packages/http-recorder 的 redactor.ts 与 redaction.ts 区分了"组合式 Redactor"与"底层 header/URL 脱敏原语"，调用方应避免在测试环境绕过 redactor 直接记录敏感头部。资料来源：packages/http-recorder/README.md。

缓存策略默认值

packages/llm/README.md 强调"缓存默认开启"且 cache: "auto" 在一次工具循环内复用同一前缀；一次性请求若低于模型最小可缓存 token 阈值会在协议层"静默 no-op"，属于无害失败模式。资料来源：packages/llm/README.md:Auto placement。

参见

  • OpenCode 核心与 CLI（packages/opencode）
  • LLM 提供方与缓存策略（packages/llm）
  • JavaScript SDK（packages/sdk/js）
  • 插件与工具 SDK（packages/plugin）
  • HTTP 录制器（packages/http-recorder）
  • 控制台与企业版（packages/console, packages/enterprise）
  • 文档站（packages/web）
  • 桌面应用图标与 Tauri 资源（packages/desktop/icons）

资料来源：package.json:workspaces。

扩展、配置、部署与运维

OpenCode 是一个 AI 驱动的开发工具，采用 Bun monorepo 架构组织多个子包，覆盖 CLI、桌面应用、网页控制台、统计后端、SDK、插件、LLM 协议层等组成部分。"扩展、配置、部署与运维"这一主题聚焦于如何在多个运行形态（终端 TUI、桌面 GUI、Web 控制台、GitHub Action、SDK 集成）下对 OpenCode 进行定制化扩展、安全配...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 插件包与扩展点

继续阅读本节完整说明和来源证据。

章节 SDK 双版本契约

继续阅读本节完整说明和来源证据。

章节 LLM 协议层的扩展能力

继续阅读本节完整说明和来源证据。

概述

OpenCode 是一个 AI 驱动的开发工具，采用 Bun monorepo 架构组织多个子包，覆盖 CLI、桌面应用、网页控制台、统计后端、SDK、插件、LLM 协议层等组成部分。"扩展、配置、部署与运维"这一主题聚焦于如何在多个运行形态（终端 TUI、桌面 GUI、Web 控制台、GitHub Action、SDK 集成）下对 OpenCode 进行定制化扩展、安全配置以及生产化部署与运维。

从顶层 package.json 可以看到，项目使用 [email protected] 作为包管理器，并定义了 6 个独立工作区：packages/*、packages/console/*、packages/stats/*、packages/sdk/js、packages/slack，通过 dev:desktop、dev:web、dev:console、dev:stats、dev:storybook 等脚本并行启动各子项目。

资料来源：package.json

工作区与子包结构

OpenCode 把核心能力拆分为多个可独立发布的包，下表总结了主要工作区及其职责。

子包 / 路径名称主要职责关键产物
packages/opencodeopencode v1.15.13核心 CLI 与 TUI 入口，导出 src/*.ts 全部子模块bin/opencode 可执行文件
packages/plugin@opencode-ai/plugin v1.15.13插件运行时契约（.、./tool、./tui）dist 包
packages/sdk/js@opencode-ai/sdk v1.15.13v1 / v2 客户端与服务端 SDKdist + gen/client 生成代码
packages/llm（README 记录）协议无关的 LLM 调用层，启用默认 prompt 缓存库代码
packages/webStarlight (Astro)静态文档站点dist/ 构建产物
packages/desktopTauri桌面客户端（含 macOS 定制图标）原生安装包
packages/consoleSolidStartWeb 控制台Node 部署产物
packages/statscore / appAthena + Drizzle 统计后端数据库迁移脚本
packages/slack（工作区）Slack 集成库代码
packages/script@opencode-ai/script通用脚本工具（semver）库代码
github/githubGitHub Action（基于 @actions/core）动作定义

资料来源：package.json、packages/opencode/package.json、packages/plugin/package.json、packages/sdk/js/package.json、packages/stats/core/package.json

扩展体系

插件包与扩展点

@opencode-ai/plugin 是 OpenCode 的官方扩展入口，其 package.json 暴露了三个子路径，对应不同的扩展面：

导出路径用途Peer 依赖
.插件主入口（与运行时集成）—
./tool工具（tool）注册接口—
./tuiTUI 主题/视图扩展@opentui/core @opentui/keymap @opentui/solid（均为可选 peer）

OpenTUI 的三项 peer 依赖被标记为 optional: true，意味着第三方插件可以按需选择是否引入 TUI 扩展能力。运行时的核心依赖是 @opencode-ai/sdk、effect 与 zod，其中 SDK 提供与服务端通讯的强类型 schema，effect 与 zod 共同承担校验与组合子语义。

资料来源：packages/plugin/package.json

SDK 双版本契约

@opencode-ai/sdk 同时提供 v1 与 v2 两条独立导出路径，方便在保持向后兼容的同时引入新协议：

.                       → ./src/index.ts
./client                → ./src/client.ts
./server                → ./src/server.ts
./v2                    → ./src/v2/index.ts
./v2/client             → ./src/v2/client.ts
./v2/gen/client         → ./src/v2/gen/client/index.ts
./v2/server             → ./src/v2/server.ts

扩展作者可以使用 ./v2/gen/client 拿到由 OpenAPI 生成的强类型客户端，使用 ./v2/server 复用服务端适配层，从而快速构建自定义的 OpenCode 集成（例如 IDE 插件、CI Agent、第三方 CLI 包装器）。v2 路径与 v1 共存，避免破坏既有的 SDK 消费者。

资料来源：packages/sdk/js/package.json

LLM 协议层的扩展能力

packages/llm 描述的协议无关 LLM 客户端提供了若干公共扩展点：

  • LLM.generate / LLM.stream：统一接口，每个协议（Anthropic、OpenAI、Gemini、Bedrock）只需实现适配器。
  • Message.user(...) / Message.assistant(...) / Message.tool(...)：规范化消息构造。
  • LLMClient.prepare(request)：在不真正发送请求的情况下执行协议构造、校验与 HTTP 准备，可用于调试、录制回放与单元测试。
  • LLMEvent.is.*：流式事件类型守卫，便于按事件类型做扩展处理。

缓存层是默认开启的——除非显式传入 cache: "none"，否则 LLMRequest 会被解析为 cache: "auto"。"auto" 模式会在三个边界插入断点：最后一个 tool 定义、最后一个 system part、最后一条 user message。这种"最后一条用户消息"边界对于工具调用循环尤为关键，因为单次用户回合会展开成多次 assistant/tool 往返，所有这些调用共享同一前缀，缓存命中可以显著降低重复开销。OpenAI 与 Gemini 走隐式服务器端缓存，所以"auto"对其是无操作。

资料来源：packages/llm/README.md

GitHub Copilot 兼容层

packages/core/src/github-copilot 是一个临时的内部兼容包，仅用于对接 GitHub Copilot。README.md 明确指出："THIS IS ONLY FOR GITHUB COPILOT!!! Avoid making edits to these files"——这是给扩展者的明确警告：不要基于这套文件去对接其他 OpenAI 兼容服务，否则协议差异会引发难以追踪的回归。

资料来源：packages/core/src/github-copilot/README.md

HTTP 录制与回放基础设施

packages/http-recorder 提供了一套用于"录制-重放"LLM 流量的基础设施，适合用于离线测试与回归验证。

文件作用
redactor.ts可组合的 Redactor，对 header、url、body 做脱敏
redaction.ts底层 header / URL 脱敏原语与密钥模式匹配
schema.tsEffect Schema 定义 cassette JSON 格式
matching.ts请求匹配、规范化、顺序游标、失配诊断

对于离线回归测试、CI 录制回放、企业内私有部署的"无网络回归"，这套设施是基础设施层的关键扩展点。

资料来源：packages/http-recorder/README.md

配置管理

多包统一管理

根 package.json 的 catalog: 占位符（如 hono: 4.10.7、zod: 4.1.8、typescript: 5.8.2 等）让所有 workspace 子包共享一份版本目录。这种 Bun 提供的 catalog 机制可以避免在多个子包的 devDependencies / dependencies 中重复声明相同版本，减少漂移。

资料来源：package.json

核心包 `imports` 字段

packages/opencode/package.json 通过 imports 字段为同一个标识符提供多运行时实现，例如：

"imports": {
  "#db": {
    "bun": "./src/storage/db.bun.ts",
    "node": "./src/storage/db.node.ts"
  }
}

这种 "条件导入" 让 OpenCode 既能在 Bun 下直接运行（拿到原生性能），也能在 Node 环境下回退到兼容实现。它是配置层"按运行环境自动切换实现"的典型模式。

资料来源：packages/opencode/package.json

配置加载方向

社区反馈中 v1.15.13 的发布说明提到："Config now loads from the opened location upward, so directory-specific settings and provider policies apply more predictably." 这意味着配置从用户当前打开的位置向父级目录逐级加载，更靠近工作区根目录的 .opencode/config 等设置将优先生效。这一行为对多仓库、monorepo、远程开发场景非常关键——开发者可以在子目录里放置项目级 provider 策略，而不必污染根仓库或家目录。

控制台与变更日志

packages/console/app/src/lib/changelog.ts 描述了 Web 控制台如何加载变更日志。它通过 fetch("https://api.github.com/repos/anomalyco/opencode/releases?per_page=20") 拉取最近 20 个发布，并借助 Cloudflare 边缘缓存（cacheTtl: 60 * 5、五秒级 User-Agent）降低对 GitHub API 的压力；一旦请求失败，函数返回 { ok: false, releases: [] }，UI 端可以无副作用降级展示。

资料来源：packages/console/app/src/lib/changelog.ts

部署目标

部署形态一览

graph TD
  Repo[OpenCode Monorepo<br/>package.json]
  CLI[packages/opencode<br/>CLI / TUI]
  Desktop[packages/desktop<br/>Tauri App]
  Web[packages/web<br/>Starlight Docs]
  Console[packages/console<br/>SolidStart Web App]
  Stats[packages/stats<br/>Athena + Drizzle]
  SDK[packages/sdk/js<br/>v1 / v2 SDK]
  Plugin[packages/plugin<br/>@opencode-ai/plugin]
  GHAction[github/<br/>GitHub Action]
  Slack[packages/slack<br/>Slack 集成]
  LLM[packages/llm<br/>协议无关 LLM 客户端]
  HTTPRec[packages/http-recorder<br/>录制回放]
  Script[packages/script<br/>通用脚本]

  Repo --> CLI
  Repo --> Desktop
  Repo --> Web
  Repo --> Console
  Repo --> Stats
  Repo --> SDK
  Repo --> Plugin
  Repo --> GHAction
  Repo --> Slack
  Repo --> LLM
  Repo --> HTTPRec
  Repo --> Script

  Plugin --> SDK
  CLI --> LLM
  SDK --> LLM

终端 CLI / TUI 部署

packages/opencode/package.json 暴露 bin.opencode: "./bin/opencode"，并提供 dev 脚本 bun run --conditions=browser ./src/index.ts。--conditions=browser 这一条件允许同一份源码在浏览器兼容模式下运行（用于 Web 端的 TUI 内嵌），而不需要改写模块加载路径。

测试与发布方面，仓库提供 test、test:ci（JUnit 报告落盘到 .artifacts/unit/junit.xml）、test:httpapi（覆盖 / auth / effect 三种模式的 API 演练）、bench:test、profile:test 等子命令，覆盖了从单元测试、性能基准到协议层的多种验证场景。

资料来源：packages/opencode/package.json

桌面端（Tauri）部署

packages/desktop/icons/README.md 记录了 macOS 桌面端的图标生成流程：

  1. 将源图另存为 packages/desktop/app-icon.png。
  2. 在 packages/desktop 目录执行 bun tauri icon -o src-tauri/icons/{environment}。
  3. 使用 Image2Icon 的 "Big Sur Icon" 预设生成 icon.icns，因为 Tauri 默认生成图标缺少 macOS 期望的阴影/内边距，会让应用图标显得过大。
  4. 在 app.dock.setIcon() 中使用 PNG dock.png（dev 模式），并保持其与从 icon.icns 抽出的 [email protected] 同步。

桌面端的图标管道之所以重要，是因为 OpenCode 的多渠道发布（alpha / beta / stable）需要保持视觉一致，同时又必须遵循 macOS HIG。

资料来源：packages/desktop/icons/README.md

Web 文档站点

packages/web 是基于 Starlight（Astro）的静态文档站。README 列出了标准命令：npm run dev（localhost:4321）、npm run build（输出 dist/）、npm run preview 等。Starlight 约定 src/content/docs/*.md(x) 自动成为路由，因此 OpenCode 的"扩展、配置、部署"文档可以直接以 MDX 形式新增，部署到 CDN 即可。

资料来源：packages/web/README.md

Web 控制台

packages/console/app 与 packages/enterprise 都基于 SolidStart。其 README 提示：npm run dev 启动开发服务器，npm run build 会按 app.config.js 选择的 preset（默认 Node）生成可执行产物，npm start 在 Node 环境下启动；切换到 SSR/Edge/Cloudflare 等 preset 只需修改 devDependencies 与 app.config.js。这意味着同一个 SolidStart 应用可以在不同部署目标间复用源码，仅需切换运行时 preset。

资料来源：packages/console/app/README.md、packages/enterprise/README.md

GitHub Action 部署

github/package.json 描述了一个独立的 GitHub Action 包，依赖 @actions/[email protected]、@actions/[email protected] 与 @octokit/[email protected]、@octokit/rest，并通过 workspace:* 直接引用 @opencode-ai/sdk。这是 OpenCode 把"AI 编码能力"以 GitHub 自动化形式分发到企业 CI 流水线的标准扩展方式。

资料来源：github/package.json

运维与统计

统计后端

packages/stats/core/package.json 显示统计核心使用 @aws-sdk/client-athena（查询）与 @planetscale/database（事务）组合，配合 drizzle-orm 做 schema 映射，并通过 sst 部署到 AWS。可用脚本包括：

脚本作用
db:generate通过 drizzle-kit generate 生成迁移
db:migrate执行 bun src/migrate.ts
db:push通过 drizzle-kit push 直接同步 schema
db:studio启动 Drizzle Studio 调试
honeycomb:backfill回填 Honeycomb 遥测数据
typechecktsgo --noEmit

这种 "Drizzle + 计划数据库（PlanetScale）+ Athena 离线分析" 的组合是典型的"事务-分析双链路"运维设计：业务写入走 MySQL 兼容的事务库，分析查询走 Athena，避免 OLTP 库被大查询拖慢。

资料来源：packages/stats/core/package.json

HTTP 录制与回放对运维的意义

packages/http-recorder 提供的 Redactor/Schema/Matching 工具链不仅用于测试，也是生产化运维的关键：它能录制真实 provider 流量再回放给本地 LLM 客户端，从而在断网/受限网络环境下继续运行回归；同时通过 redaction.ts 自动识别密钥模式，避免把真实凭据写入 cassette。这种 "录制即服务" 的形态在企业部署中尤其重要。

资料来源：packages/http-recorder/README.md

控制台变更日志的边缘缓存

changelog.ts 中通过 Cloudflare Worker 的 cf.cacheTtl 与 cacheEverything: true 标志实现"尽力而为"的边缘缓存——对 GitHub API 的调用在边缘节点被缓存 5 分钟，从而在大型版本发布期间保持控制台响应稳定。当上游失败时，函数返回 { ok: false, releases: [] } 防止 UI 崩溃。运维层面，这种"边缘缓存 + 失败降级"是典型的防御式设计。

资料来源：packages/console/app/src/lib/changelog.ts

脚本与发布工具

packages/script/package.json 提供 @opencode-ai/script 工具包，依赖 semver ^7.6.3，并通过 exports: { ".": "./src/index.ts" } 暴露单入口。它常被 monorepo 中其他包复用，统一管理版本号解析、对比等发布期操作。package.json 中的 upgrade-opentui 脚本 bun run script/upgrade-opentui.ts 也是发布链路的辅助步骤——把 OpenTUI 升级逻辑集中在仓库级脚本里，避免在每个插件中重复实现。

资料来源：packages/script/package.json、package.json

社区反馈与改进方向

用户高互动议题

社区中关注度最高的扩展与配置相关议题包括：

  • #1686 "Add OpenAI auth login like claude"（126 条评论）：希望 OpenCode 像 Claude 一样支持基于 ChatGPT 订阅的 OAuth 登录，免去用户在本地管理 OpenAI Key 的负担。这与控制台/SDK 的 auth path 紧密耦合，会涉及控制台后端与 SDK 客户端的扩展点。
  • #2072 "Support for Cursor?"（68 条评论）：在 Cursor 推出官方 CLI 后，社区希望 OpenCode 能像集成其他 LLM CLI 一样对接 Cursor CLI，从而获得"为 Claude 优化的命令面板"在 OpenCode 中的可复用性。
  • #8501 "Allow to expand the pasted text"：希望在 TUI 中点击被折叠的 [Pasted ~1 lines] 占位符后能展开原文，属于 TUI/CLI 体验扩展。
  • #4695 "Speech-to-Text Voice Input"：希望增加语音输入，属于工具（tool）扩展层的新能力。
  • #16992 "add /btw command"：参考 Anthropic 在 Claude Code 中推出的 /btw 命令，希望在 OpenCode 也提供类似侧边备注命令。

v1.15.13 中的关键改进

v1.15.13 发布说明中提到：

  • Gateway 在 Anthropic Opus 4.7+ 自适应推理下，保留汇总后的思考块而非返回空块——这是对核心 LLM 网关层的健壮性修复。
  • Session 现可通过 API 与 SDK 存储自定义元数据（@shantur 贡献）——属于 SDK 扩展面。
  • Config 现在从打开位置向上加载，目录级设置与 provider 策略的生效顺序更可预测——属于配置管理层。
  • 桌面端 TUI 的若干 Bugfixes 紧跟发布。

资料来源：community_context

常见失败模式与最佳实践

1. 把 GitHub Copilot 兼容层复用到其他 provider

如 packages/core/src/github-copilot/README.md 所警告，Copilot 兼容层只针对 Copilot 实现，将其当作通用 OpenAI 适配器来扩展会导致难以诊断的协议不一致。扩展者应改用 packages/llm 的协议无关接口或 packages/sdk/js 的 v2 客户端。

2. 在浏览器条件下误用 CLI 入口

bun run --conditions=browser ./src/index.ts 启用了浏览器兼容条件。如果在生产部署中忘记恢复默认条件，可能导致错误的模块解析路径（例如把 db.bun.ts 切换到 db.node.ts）。运维侧应明确区分 "浏览器内嵌 TUI" 与 "本地 CLI" 两种启动模式。

3. 误把统计回填脚本当作常规任务

honeycomb:backfill 是回填脚本，频繁执行会污染遥测数据并消耗 Athena 配额。运维调度时应将其限制在数据修复窗口期。

4. 桌面端图标缺阴影

Tauri 默认生成的 icon.icns 缺少 macOS 期望的内边距/阴影，必须使用 Image2Icon 的 "Big Sur Icon" 预设替换。packages/desktop/icons/README.md 详细列出了步骤。

5. 跨语言协作导致 `imports` 解析失败

packages/opencode/package.json 的 imports 字段同时为 Bun 与 Node 准备了不同实现。如果上层脚本硬编码了具体路径（如直接 import "./src/storage/db.bun.ts"）而非通过 #db 标识符，就会在 Node 运行时上失败。运维侧应统一通过 package alias 访问。

端到端扩展-部署-运维流程

graph TD
  Dev[开发者贡献代码]
  Plugin[编写 @opencode-ai/plugin]
  SDK[使用 @opencode-ai/sdk v2]
  Test[运行 test / test:ci / test:httpapi]
  Rec[使用 http-recorder 录制回放]
  Build[bun run build]
  Release[发布到 npm / GitHub Action]
  Console[部署 Console + 控制台 SSR]
  Stats[写入 PlanetScale, 查询 Athena]
  Monitor[Cloudflare 边缘缓存 / Sentry]
  EndUser[终端用户使用 TUI / 桌面 / 控制台]

  Dev --> Plugin
  Plugin --> SDK
  Plugin --> Test
  Test --> Rec
  Rec --> Build
  Build --> Release
  Release --> Console
  Release --> EndUser
  Console --> Stats
  Console --> Monitor
  EndUser --> Stats
  EndUser --> Monitor

See Also

资料来源：package.json

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Crash at start

可能阻塞安装或首次运行。

high 来源证据：High CPU usage in newer versions of OpenCode

可能增加新用户试用和生产接入成本。

high 来源证据：Desktop: sidecar dies silently on Windows, renderer loses connection (event stream error)

可能阻塞安装或首次运行。

high 来源证据：[BUG] Session title generation fails silently since v1.3.3 — effort parameter leaks into small model call

可能增加新用户试用和生产接入成本。

Pitfall Log / 踩坑日志

项目：anomalyco/opencode

摘要：发现 18 个潜在踩坑项，其中 9 个为 high/blocking；最高优先级：安装坑 - 来源证据：Crash at start。

1. 安装坑 · 来源证据：Crash at start

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Crash at start
  • 对用户的影响：可能阻塞安装或首次运行。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/28996 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：High CPU usage in newer versions of OpenCode

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：High CPU usage in newer versions of OpenCode
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/30086 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：Desktop: sidecar dies silently on Windows, renderer loses connection (event stream error)

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Desktop: sidecar dies silently on Windows, renderer loses connection (event stream error)
  • 对用户的影响：可能阻塞安装或首次运行。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/30597 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：[BUG] Session title generation fails silently since v1.3.3 — effort parameter leaks into small model call

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[BUG] Session title generation fails silently since v1.3.3 — effort parameter leaks into small model call
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/20269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

5. 维护坑 · 来源证据：failed to send command

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：failed to send command
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/30596 | 来源类型 github_issue 暴露的待验证使用条件。

6. 维护坑 · 来源证据：fix(tui): TUI message list doesn't update for cross-instance agent messages

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：fix(tui): TUI message list doesn't update for cross-instance agent messages
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/22588 | 来源类型 github_issue 暴露的待验证使用条件。

7. 维护坑 · 来源证据：lo Error 0 A JavaScript error occurred in the main process

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：lo Error 0 A JavaScript error occurred in the main process
  • 对用户的影响：可能阻塞安装或首次运行。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/30297 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

8. 安全/权限坑 · 来源证据：Missing Authentication header when I try to use open code

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Missing Authentication header when I try to use open code
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/25757 | 来源类型 github_issue 暴露的待验证使用条件。

9. 安全/权限坑 · 来源证据：TUI double-ESC loops and Desktop stop button fails to interrupt

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TUI double-ESC loops and Desktop stop button fails to interrupt
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/24217 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

10. 配置坑 · 可能修改宿主 AI 配置

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
  • 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
  • 证据：capability.host_targets | github_repo:975734319 | https://github.com/anomalyco/opencode | host_targets=local_cli

11. 配置坑 · 来源证据：Web UI v1.15.13 crash

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Web UI v1.15.13 crash
  • 对用户的影响：可能阻塞安装或首次运行。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/30563 | 来源类型 github_issue 暴露的待验证使用条件。

12. 能力坑 · 能力判断依赖假设

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：README/documentation is current enough for a first validation pass.
  • 对用户的影响：假设不成立时，用户拿不到承诺的能力。
  • 证据：capability.assumptions | github_repo:975734319 | https://github.com/anomalyco/opencode | README/documentation is current enough for a first validation pass.

13. 维护坑 · 来源证据："Error: missing key" after renaming a bunch of old sessions

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题："Error: missing key" after renaming a bunch of old sessions
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/anomalyco/opencode/issues/30579 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

14. 维护坑 · 维护活跃度未知

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：未记录 last_activity_observed。
  • 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
  • 证据：evidence.maintainer_signals | github_repo:975734319 | https://github.com/anomalyco/opencode | last_activity_observed missing
  • 严重度：medium
  • 证据强度：source_linked
  • 发现：no_demo
  • 证据：downstream_validation.risk_items | github_repo:975734319 | https://github.com/anomalyco/opencode | no_demo; severity=medium

16. 安全/权限坑 · 存在评分风险

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：no_demo
  • 对用户的影响：风险会影响是否适合普通用户安装。
  • 证据：risks.scoring_risks | github_repo:975734319 | https://github.com/anomalyco/opencode | no_demo; severity=medium

17. 维护坑 · issue/PR 响应质量未知

  • 严重度：low
  • 证据强度：source_linked
  • 发现：issue_or_pr_quality=unknown。
  • 对用户的影响：用户无法判断遇到问题后是否有人维护。
  • 证据：evidence.maintainer_signals | github_repo:975734319 | https://github.com/anomalyco/opencode | issue_or_pr_quality=unknown

18. 维护坑 · 发布节奏不明确

  • 严重度：low
  • 证据强度：source_linked
  • 发现：release_recency=unknown。
  • 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
  • 证据：evidence.maintainer_signals | github_repo:975734319 | https://github.com/anomalyco/opencode | release_recency=unknown

来源：Doramagic 发现、验证与编译记录