# https://github.com/anomalyco/opencode 项目说明书

生成时间：2026-06-03 16:46:17 UTC

## 目录

- [系统架构与核心服务](#page-1)
- [LLM 集成、代理与认证](#page-2)
- [前端、桌面与 UI 组件](#page-3)
- [扩展、配置、部署与运维](#page-4)

<a id='page-1'></a>

## 系统架构与核心服务

### 相关页面

相关主题：[LLM 集成、代理与认证](#page-2), [扩展、配置、部署与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/anomalyco/opencode/blob/main/package.json)
- [packages/opencode/package.json](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)
- [packages/core/src/github-copilot/README.md](https://github.com/anomalyco/opencode/blob/main/packages/core/src/github-copilot/README.md)
- [packages/llm/README.md](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md)
- [packages/http-recorder/README.md](https://github.com/anomalyco/opencode/blob/main/packages/http-recorder/README.md)
- [packages/sdk/js/package.json](https://github.com/anomalyco/opencode/blob/main/packages/sdk/js/package.json)
- [packages/cli/package.json](https://github.com/anomalyco/opencode/blob/main/packages/cli/package.json)
- [packages/plugin/package.json](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json)
- [packages/web/package.json](https://github.com/anomalyco/opencode/blob/main/packages/web/package.json)
- [packages/console/app/README.md](https://github.com/anomalyco/opencode/blob/main/packages/console/app/README.md)
- [packages/enterprise/README.md](https://github.com/anomalyco/opencode/blob/main/packages/enterprise/README.md)
- [packages/script/package.json](https://github.com/anomalyco/opencode/blob/main/packages/script/package.json)
- [github/package.json](https://github.com/anomalyco/opencode/blob/main/github/package.json)
- [github/README.md](https://github.com/anomalyco/opencode/blob/main/github/README.md)
- [README.md](https://github.com/anomalyco/opencode/blob/main/README.md)
</details>

# 系统架构与核心服务

本页面向希望理解 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](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)。
- **运行时分层**：CLI 与服务端使用 Node/Bun，浏览器条件分支走 `--conditions=browser`；数据库连接器在 Bun 与 Node 下分别走 `db.bun.ts` 与 `db.node.ts` [package.json:19-25](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)。
- **可插拔模型与协议**：`packages/llm` 抽象统一 Schema（`LLMRequest`、`LLMEvent` 等），各 Provider 仅做"协议转换层"，并提供 `cache: "auto"` 默认策略 [packages/llm/README.md:1-20](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md)。
- **Effect-first 服务编排**：CLI、Core、内部服务大量使用 Effect 框架；`@opencode-ai/cli` 显式声明依赖 `effect` 与 `@effect/platform-node` [packages/cli/package.json:13-19](https://github.com/anomalyco/opencode/blob/main/packages/cli/package.json)。
- **可观测与可回放**：内置 `http-recorder` 提供 Cassette/Redactor/Matching 原语，使协议层测试可在脱机环境下重放 [packages/http-recorder/README.md:1-8](https://github.com/anomalyco/opencode/blob/main/packages/http-recorder/README.md)。

## 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 SDK | `cross-spawn`, `@hey-api/openapi-ts` |
| `packages/slack` | Slack 集成 | （依赖根 `catalog:`） |

资料来源：[package.json:32-38](https://github.com/anomalyco/opencode/blob/main/package.json)

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

```bash
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](https://github.com/anomalyco/opencode/blob/main/package.json)

## 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 两种适配）。

```mermaid
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` —— 运行时主入口

- 暴露可执行文件 `bin/opencode`（通过 `package.json` 的 `bin` 字段）[packages/opencode/package.json:18-20](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)。
- 通过 `imports.#db` 在 Bun 与 Node 下选择不同 DB 适配器，确保跨运行时数据访问一致 [packages/opencode/package.json:23-26](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)。
- 提供构建、测试、性能剖析脚本：`build`、`test`、`test:ci`、`test:httpapi`、`bench:test`、`profile:test` [packages/opencode/package.json:9-16](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)。
- `test:httpapi` 三段式覆盖：coverage、auth、effect，用于回归 HTTP API 行为 [packages/opencode/package.json:11-12](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)。

### 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](https://github.com/anomalyco/opencode/blob/main/packages/core/src/github-copilot/README.md)。

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

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

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

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

- 入口为 `bin/opencode` 指向 `src/index.ts` [packages/cli/package.json:7-9](https://github.com/anomalyco/opencode/blob/main/packages/cli/package.json)。
- 依赖 `@opencode-ai/core`、`effect`、`@effect/platform-node`，统一以 Effect 风格构建命令、子进程、I/O [packages/cli/package.json:13-19](https://github.com/anomalyco/opencode/blob/main/packages/cli/package.json)。

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

- 通过 `exports` 暴露 `.`、`./client`、`./server`、`./v2`、`./v2/client`、`./v2/gen/client`、`./v2/server`，允许用户按需引入 [packages/sdk/js/package.json:13-19](https://github.com/anomalyco/opencode/blob/main/packages/sdk/js/package.json)。
- 使用 `@hey-api/openapi-ts` 自动从服务端 OpenAPI 生成 v2 客户端，减少手写样板 [packages/sdk/js/package.json:25-32](https://github.com/anomalyco/opencode/blob/main/packages/sdk/js/package.json)。

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

- 入口分三类：`@opencode-ai/plugin`（基础）、`@opencode-ai/plugin/tool`（工具扩展）、`@opencode-ai/plugin/tui`（TUI 扩展）[packages/plugin/package.json:11-13](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json)。
- 对 OpenTUI 三个核心包 `@opentui/core`、`@opentui/keymap`、`@opentui/solid` 声明 `>=0.3.1` 的 peer 依赖，且标记为可选（`optional: true`），不强制宿主使用 TUI [packages/plugin/package.json:18-32](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json)。
- 插件层共享 `@opencode-ai/sdk` 与 `effect`/`zod`，保持与核心一致的运行时 [packages/plugin/package.json:14-17](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json)。

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

| 包 | 框架 | 备注 |
| --- | --- | --- |
| `packages/web` | Astro + Starlight | 文档主题 `toolbeam-docs-theme`，依赖 `shiki`、`marked-shiki` 做代码高亮 [packages/web/package.json:11-19](https://github.com/anomalyco/opencode/blob/main/packages/web/package.json) |
| `packages/console/app` | SolidStart | 通过 `ulimit -n 10240` 提升文件描述符限制，避免本地 dev 端口耗尽 [package.json:14-14](https://github.com/anomalyco/opencode/blob/main/package.json) |
| `packages/enterprise` | SolidStart | 企业版控制台，模板来自 Solid CLI [packages/enterprise/README.md:1-3](https://github.com/anomalyco/opencode/blob/main/packages/enterprise/README.md) |

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

- `packages/script` 提供 `semver` 版本处理能力，供 `script/upgrade-opentui.ts` 等升级脚本使用 [packages/script/package.json:6-10](https://github.com/anomalyco/opencode/blob/main/packages/script/package.json)。
- `packages/slack` 作为根工作区之一承载 Slack 集成，复用 SDK 与 Effect 栈 [package.json:32-38](https://github.com/anomalyco/opencode/blob/main/package.json)。

## 5. 运行时与数据流

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

```mermaid
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: 录制/回放（测试或审计）
```

要点：

- `LLMClient.prepare(request)` 仅编译不发送，可被中间件（例如录制器）拦截 [packages/llm/README.md:10-12](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md)。
- `cache: "auto"` 默认在最后一条 user 消息设置断点，tool-use 循环内的多轮请求共享同一前缀 [packages/llm/README.md:25-31](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md)。

## 6. HTTP API 与测试闭环

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

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

资料来源：[packages/opencode/package.json:11-12](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)

测试结果以 JUnit 形式落到 `.artifacts/unit/junit.xml`，便于在 CI 中聚合 [packages/opencode/package.json:9-10](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)。

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

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

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

资料来源：[packages/http-recorder/README.md:3-7](https://github.com/anomalyco/opencode/blob/main/packages/http-recorder/README.md)

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

## 8. 客户端矩阵

| 客户端 | 技术栈 | 关键集成点 |
| --- | --- | --- |
| TUI | OpenTUI（Solid + keymap） | 通过 `@opencode-ai/plugin/tui` 扩展；可选 peer deps [packages/plugin/package.json:18-32](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json) |
| Desktop | 独立包 `packages/desktop` | 通过 `bun --cwd packages/desktop dev` 启动 [package.json:13-13](https://github.com/anomalyco/opencode/blob/main/package.json) |
| Web（文档） | Astro + Starlight | 文档站，使用 `toolbeam-docs-theme` [packages/web/package.json:16-19](https://github.com/anomalyco/opencode/blob/main/packages/web/package.json) |
| Console / Enterprise | SolidStart | 通过根 `dev:console` 启动 [package.json:14-14](https://github.com/anomalyco/opencode/blob/main/package.json) |
| GitHub | Action 形式 | 触发词 `/oc` 或 `/opencode` [github/README.md:18-19](https://github.com/anomalyco/opencode/blob/main/github/README.md) |
| Slack | `packages/slack` | 工作区之一 [package.json:32-38](https://github.com/anomalyco/opencode/blob/main/package.json) |

## 9. GitHub 集成

`github` 子包发布为 GitHub Action：

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

## 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](https://github.com/anomalyco/opencode/issues)（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](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md)。
- **One-shot 请求被无谓写入缓存**：低于 Provider 的"最小可缓存 token"阈值时，`auto` 会安全地 no-op；如对延迟敏感可显式 `cache: "none"` [packages/llm/README.md:35-37](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md)。
- **Bun vs Node DB 适配器不一致**：自定义脚本若绕过 `imports.#db` 而直接引用 SQLite 库，可能在 Node 上找不到原生模块。统一通过 `imports` 解析即可 [packages/opencode/package.json:23-26](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)。
- **GitHub Copilot 协议变更**：仓库明确警告 `packages/core/src/github-copilot` 为临时实现，请勿直接修改其文件 [packages/core/src/github-copilot/README.md:1-4](https://github.com/anomalyco/opencode/blob/main/packages/core/src/github-copilot/README.md)。
- **测试录制器误过滤关键 header**：`http-recorder` 的 `Redactor` 若匹配过宽，会将鉴权 header 误删，影响回放断言；调整 `redaction.ts` 中的 secret 模式顺序即可 [packages/http-recorder/README.md:3-7](https://github.com/anomalyco/opencode/blob/main/packages/http-recorder/README.md)。

## 13. 开发与构建入口

- **Lint**：`bun run lint`（基于 oxlint）[package.json:15-15](https://github.com/anomalyco/opencode/blob/main/package.json)
- **类型检查**：`bun run typecheck`（Turbo 编排）[package.json:16-16](https://github.com/anomalyco/opencode/blob/main/package.json)
- **OpenTUI 升级**：`bun run upgrade-opentui` 走 `script/upgrade-opentui.ts` [package.json:17-17](https://github.com/anomalyco/opencode/blob/main/package.json)
- **Postinstall**：自动修复 `node-pty` 绑定 [package.json:20-20](https://github.com/anomalyco/opencode/blob/main/package.json)
- **测试**：禁止从根目录直接运行 `bun test`，需进入子包 [package.json:23-23](https://github.com/anomalyco/opencode/blob/main/package.json)

## See Also

- LLM 协议与缓存策略：[packages/llm/README.md](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md)
- HTTP 录制与回放：[packages/http-recorder/README.md](https://github.com/anomalyco/opencode/blob/main/packages/http-recorder/README.md)
- 插件 SDK：[packages/plugin/package.json](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json)
- JavaScript SDK：[packages/sdk/js/package.json](https://github.com/anomalyco/opencode/blob/main/packages/sdk/js/package.json)
- GitHub Action：[github/README.md](https://github.com/anomalyco/opencode/blob/main/github/README.md)
- 控制台与企业版：[packages/console/app/README.md](https://github.com/anomalyco/opencode/blob/main/packages/console/app/README.md) / [packages/enterprise/README.md](https://github.com/anomalyco/opencode/blob/main/packages/enterprise/README.md)
- Web 文档：[packages/web/README.md](https://github.com/anomalyco/opencode/blob/main/packages/web/README.md)

---

<a id='page-2'></a>

## LLM 集成、代理与认证

### 相关页面

相关主题：[系统架构与核心服务](#page-1), [扩展、配置、部署与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/llm/README.md](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md)
- [packages/llm/src/llm.ts](https://github.com/anomalyco/opencode/blob/main/packages/llm/src/llm.ts)
- [packages/llm/src/protocols/index.ts](https://github.com/anomalyco/opencode/blob/main/packages/llm/src/protocols/index.ts)
- [packages/llm/src/providers/anthropic.ts](https://github.com/anomalyco/opencode/blob/main/packages/llm/src/providers/anthropic.ts)
- [packages/llm/src/providers/openai.ts](https://github.com/anomalyco/opencode/blob/main/packages/llm/src/providers/openai.ts)
- [packages/llm/src/providers/amazon-bedrock.ts](https://github.com/anomalyco/opencode/blob/main/packages/llm/src/providers/amazon-bedrock.ts)
- [packages/llm/src/providers/github-copilot.ts](https://github.com/anomalyco/opencode/blob/main/packages/llm/src/providers/github-copilot.ts)
- [packages/core/src/plugin/provider/anthropic.ts](https://github.com/anomalyco/opencode/blob/main/packages/core/src/plugin/provider/anthropic.ts)
- [packages/core/src/plugin/provider/openai.ts](https://github.com/anomalyco/opencode/blob/main/packages/core/src/plugin/provider/openai.ts)
- [packages/core/src/plugin/provider/github-copilot.ts](https://github.com/anomalyco/opencode/blob/main/packages/core/src/plugin/provider/github-copilot.ts)
- [packages/core/src/auth.ts](https://github.com/anomalyco/opencode/blob/main/packages/core/src/auth.ts)
- [packages/opencode/src/auth/index.ts](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/auth/index.ts)
- [packages/opencode/src/provider/auth.ts](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/provider/auth.ts)
- [packages/core/src/github-copilot/README.md](https://github.com/anomalyco/opencode/blob/main/packages/core/src/github-copilot/README.md)
- [packages/plugin/package.json](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json)
- [packages/llm/package.json](https://github.com/anomalyco/opencode/blob/main/packages/llm/package.json)
</details>

# LLM 集成、代理与认证

## 概述

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](https://github.com/anomalyco/opencode/issues/1686)），以及 **对 Cursor CLI 等新兴提供商的支持**（[#2072](https://github.com/anomalyco/opencode/issues/2072)）。这些都直接落在本模块的扩展点上。

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

## 架构概览

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

```mermaid
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 |
| --- | --- |
| Anthropic | `cache_control` |
| Amazon Bedrock | `cachePoint` |
| 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.

---

<a id='page-3'></a>

## 前端、桌面与 UI 组件

### 相关页面

相关主题：[系统架构与核心服务](#page-1), [扩展、配置、部署与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/anomalyco/opencode/blob/main/README.md)
- [package.json](https://github.com/anomalyco/opencode/blob/main/package.json)
- [packages/ui/package.json](https://github.com/anomalyco/opencode/blob/main/packages/ui/package.json)
- [packages/desktop/icons/README.md](https://github.com/anomalyco/opencode/blob/main/packages/desktop/icons/README.md)
- [packages/web/README.md](https://github.com/anomalyco/opencode/blob/main/packages/web/README.md)
- [packages/web/package.json](https://github.com/anomalyco/opencode/blob/main/packages/web/package.json)
- [packages/console/app/README.md](https://github.com/anomalyco/opencode/blob/main/packages/console/app/README.md)
- [packages/enterprise/README.md](https://github.com/anomalyco/opencode/blob/main/packages/enterprise/README.md)
- [packages/opencode/package.json](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)
- [packages/plugin/package.json](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json)
- [packages/sdk/js/package.json](https://github.com/anomalyco/opencode/blob/main/packages/sdk/js/package.json)
- [packages/llm/README.md](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md)
- [packages/core/src/github-copilot/README.md](https://github.com/anomalyco/opencode/blob/main/packages/core/src/github-copilot/README.md)
- [packages/http-recorder/README.md](https://github.com/anomalyco/opencode/blob/main/packages/http-recorder/README.md)
- [github/package.json](https://github.com/anomalyco/opencode/blob/main/github/package.json)
</details>

# 前端、桌面与 UI 组件

## 概述

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]()。

```mermaid
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/js` | JS SDK | TypeScript |
| `packages/slack` | Slack 集成 | 独立服务 |

资料来源：[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` 抽取的 `icon_128x128@2x.png` 保持一致。

> 上述流程虽主要约束 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-js` | Solid 框架 |
| 组件原语 | `@kobalte/core` | 无样式可访问组件 |
| 样式 | `tailwindcss`、`@tailwindcss/vite` | 原子化样式与构建 |
| Diff 渲染 | `@pierre/diffs` | 代码差异组件 |
| 语法高亮 | `@shikijs/transformers` | Shiki 转换器 |
| 行为原语 | `@solid-primitives/event-listener`、`@solid-primitives/bounds` | 事件与边界观察 |
| 测试 | `bun test` | 内置测试运行器 |
| 代码生成 | `script/tailwind.ts` | Tailwind 类名生成 |
| 类型检查 | `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-theme` | Starlight 主题 |
| 类型 | `vscode-languageserver-types` | LSP 协议类型 |
| 开发 | `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]()。

```mermaid
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](https://github.com/anomalyco/opencode/issues/8501)。
- **Speech-to-Text 语音输入（#4695）**：语音转写流程通常会先落到 Web/桌面端的输入框，再注入会话；UI 组件库需要提供可挂载的麦克风按钮与状态指示。资料来源：[issue #4695](https://github.com/anomalyco/opencode/issues/4695)。
- **`/btw` 命令（#16992）**：作为 TUI 快捷命令，其实现位置通常在 `packages/opencode` 内部的命令解析器；UI 层需在 TUI/Web/桌面端保持一致的提示与回显。资料来源：[issue #16992](https://github.com/anomalyco/opencode/issues/16992)。

### 第三方工具与认证接入

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

### v1.15.13 同步说明

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

## 开发与构建工作流

### 入口与测试脚本

- `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）](./opencode-core.md)
- [LLM 提供方与缓存策略（packages/llm）](./llm-providers.md)
- [JavaScript SDK（packages/sdk/js）](./js-sdk.md)
- [插件与工具 SDK（packages/plugin）](./plugin-sdk.md)
- [HTTP 录制器（packages/http-recorder）](./http-recorder.md)
- [控制台与企业版（packages/console, packages/enterprise）](./console-enterprise.md)
- [文档站（packages/web）](./web-docs.md)
- [桌面应用图标与 Tauri 资源（packages/desktop/icons）](./desktop-icons.md)

---

<a id='page-4'></a>

## 扩展、配置、部署与运维

### 相关页面

相关主题：[系统架构与核心服务](#page-1), [LLM 集成、代理与认证](#page-2), [前端、桌面与 UI 组件](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/anomalyco/opencode/blob/main/README.md)
- [package.json](https://github.com/anomalyco/opencode/blob/main/package.json)
- [packages/opencode/package.json](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)
- [packages/plugin/package.json](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json)
- [packages/sdk/js/package.json](https://github.com/anomalyco/opencode/blob/main/packages/sdk/js/package.json)
- [packages/llm/README.md](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md)
- [packages/console/app/README.md](https://github.com/anomalyco/opencode/blob/main/packages/console/app/README.md)
- [packages/console/app/src/lib/changelog.ts](https://github.com/anomalyco/opencode/blob/main/packages/console/app/src/lib/changelog.ts)
- [packages/stats/core/package.json](https://github.com/anomalyco/opencode/blob/main/packages/stats/core/package.json)
- [packages/web/README.md](https://github.com/anomalyco/opencode/blob/main/packages/web/README.md)
- [packages/desktop/icons/README.md](https://github.com/anomalyco/opencode/blob/main/packages/desktop/icons/README.md)
- [packages/core/src/github-copilot/README.md](https://github.com/anomalyco/opencode/blob/main/packages/core/src/github-copilot/README.md)
- [packages/http-recorder/README.md](https://github.com/anomalyco/opencode/blob/main/packages/http-recorder/README.md)
- [packages/script/package.json](https://github.com/anomalyco/opencode/blob/main/packages/script/package.json)
- [github/package.json](https://github.com/anomalyco/opencode/blob/main/github/package.json)
</details>

# 扩展、配置、部署与运维

## 概述

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

从顶层 [package.json](https://github.com/anomalyco/opencode/blob/main/package.json) 可以看到，项目使用 `bun@1.3.14` 作为包管理器，并定义了 6 个独立工作区：`packages/*`、`packages/console/*`、`packages/stats/*`、`packages/sdk/js`、`packages/slack`，通过 `dev:desktop`、`dev:web`、`dev:console`、`dev:stats`、`dev:storybook` 等脚本并行启动各子项目。

资料来源：[package.json](https://github.com/anomalyco/opencode/blob/main/package.json)

## 工作区与子包结构

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

| 子包 / 路径 | 名称 | 主要职责 | 关键产物 |
| --- | --- | --- | --- |
| `packages/opencode` | `opencode` 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.13 | v1 / v2 客户端与服务端 SDK | `dist` + `gen/client` 生成代码 |
| `packages/llm` | （README 记录） | 协议无关的 LLM 调用层，启用默认 prompt 缓存 | 库代码 |
| `packages/web` | Starlight (Astro) | 静态文档站点 | `dist/` 构建产物 |
| `packages/desktop` | Tauri | 桌面客户端（含 macOS 定制图标） | 原生安装包 |
| `packages/console` | SolidStart | Web 控制台 | Node 部署产物 |
| `packages/stats` | `core` / `app` | Athena + Drizzle 统计后端 | 数据库迁移脚本 |
| `packages/slack` | （工作区） | Slack 集成 | 库代码 |
| `packages/script` | `@opencode-ai/script` | 通用脚本工具（semver） | 库代码 |
| `github/` | `github` | GitHub Action（基于 `@actions/core`） | 动作定义 |

资料来源：[package.json](https://github.com/anomalyco/opencode/blob/main/package.json)、[packages/opencode/package.json](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json)、[packages/plugin/package.json](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json)、[packages/sdk/js/package.json](https://github.com/anomalyco/opencode/blob/main/packages/sdk/js/package.json)、[packages/stats/core/package.json](https://github.com/anomalyco/opencode/blob/main/packages/stats/core/package.json)

## 扩展体系

### 插件包与扩展点

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

| 导出路径 | 用途 | Peer 依赖 |
| --- | --- | --- |
| `.` | 插件主入口（与运行时集成） | — |
| `./tool` | 工具（tool）注册接口 | — |
| `./tui` | TUI 主题/视图扩展 | `@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](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json)

### SDK 双版本契约

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

```text
.                       → ./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](https://github.com/anomalyco/opencode/blob/main/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](https://github.com/anomalyco/opencode/blob/main/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](https://github.com/anomalyco/opencode/blob/main/packages/core/src/github-copilot/README.md)

### HTTP 录制与回放基础设施

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

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

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

资料来源：[packages/http-recorder/README.md](https://github.com/anomalyco/opencode/blob/main/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](https://github.com/anomalyco/opencode/blob/main/package.json)

### 核心包 `imports` 字段

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

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

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

资料来源：[packages/opencode/package.json](https://github.com/anomalyco/opencode/blob/main/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](https://github.com/anomalyco/opencode/blob/main/packages/console/app/src/lib/changelog.ts)

## 部署目标

### 部署形态一览

```mermaid
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](https://github.com/anomalyco/opencode/blob/main/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` 抽出的 `icon_128x128@2x.png` 同步。

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

资料来源：[packages/desktop/icons/README.md](https://github.com/anomalyco/opencode/blob/main/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](https://github.com/anomalyco/opencode/blob/main/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](https://github.com/anomalyco/opencode/blob/main/packages/console/app/README.md)、[packages/enterprise/README.md](https://github.com/anomalyco/opencode/blob/main/packages/enterprise/README.md)

### GitHub Action 部署

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

资料来源：[github/package.json](https://github.com/anomalyco/opencode/blob/main/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 遥测数据 |
| `typecheck` | `tsgo --noEmit` |

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

资料来源：[packages/stats/core/package.json](https://github.com/anomalyco/opencode/blob/main/packages/stats/core/package.json)

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

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

资料来源：[packages/http-recorder/README.md](https://github.com/anomalyco/opencode/blob/main/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](https://github.com/anomalyco/opencode/blob/main/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](https://github.com/anomalyco/opencode/blob/main/packages/script/package.json)、[package.json](https://github.com/anomalyco/opencode/blob/main/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](https://github.com/anomalyco/opencode)

## 常见失败模式与最佳实践

### 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 访问。

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

```mermaid
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

- [README.md](https://github.com/anomalyco/opencode/blob/main/README.md) — 项目总览与多语言 README 索引（English / 简体中文 / 繁體中文 / 한국어 / Deutsch / Español / Français / Italiano / Dansk / 日本語 / Polski / Русский / Bosanski / العربية / Norsk / Português (Brasil) / ไทย / Türkçe / Українська）
- [packages/llm/README.md](https://github.com/anomalyco/opencode/blob/main/packages/llm/README.md) — LLM 协议无关客户端、缓存策略、Message 构造器
- [packages/opencode/package.json](https://github.com/anomalyco/opencode/blob/main/packages/opencode/package.json) — 核心包入口与 `imports` 条件配置
- [packages/plugin/package.json](https://github.com/anomalyco/opencode/blob/main/packages/plugin/package.json) — 插件子路径与 OpenTUI peer 依赖
- [packages/sdk/js/package.json](https://github.com/anomalyco/opencode/blob/main/packages/sdk/js/package.json) — v1 / v2 双版本 SDK 契约
- [packages/http-recorder/README.md](https://github.com/anomalyco/opencode/blob/main/packages/http-recorder/README.md) — 录制-回放基础设施
- [packages/stats/core/package.json](https://github.com/anomalyco/opencode/blob/main/packages/stats/core/package.json) — 统计后端与回填脚本
- [packages/console/app/src/lib/changelog.ts](https://github.com/anomalyco/opencode/blob/main/packages/console/app/src/lib/changelog.ts) — 控制台变更日志与边缘缓存
- [packages/core/src/github-copilot/README.md](https://github.com/anomalyco/opencode/blob/main/packages/core/src/github-copilot/README.md) — GitHub Copilot 兼容层（仅限该 provider）
- [packages/desktop/icons/README.md](https://github.com/anomalyco/opencode/blob/main/packages/desktop/icons/README.md) — 桌面端 macOS 图标生成流程
- [github/package.json](https://github.com/anomalyco/opencode/blob/main/github/package.json) — GitHub Action 部署
- [package.json](https://github.com/anomalyco/opencode/blob/main/package.json) — 工作区、catalog 依赖、monorepo 脚本

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: anomalyco/opencode; human_manual_source: deepwiki_human_wiki -->