## 项目概述

OpenCode 是一个开源的 AI 编程代理（coding agent），旨在帮助开发者更高效地编写、修改和理解代码。它提供了一个终端用户界面（TUI）以及桌面应用，支持多种安装方式，并可通过内置的代理（agents）进行构建和规划任务。该项目使用 TypeScript 编写，采用 MIT 许可证，并托管在 GitHub 上。

## 核心功能

- **内置代理**：提供 `build`（默认，全权限）和 `plan`（只读，用于分析和探索）两种代理，可通过 Tab 键切换。
- **通用子代理**：内置 `general` 子代理，用于复杂搜索和多步骤任务，可通过 `@general` 调用。
- **终端 UI 与桌面应用**：提供美观的终端界面，并支持 macOS、Windows、Linux 的桌面应用（Beta）。
- **多平台安装**：支持 curl 脚本、npm、scoop、choco、brew、pacman、mise、nix 等多种安装方式。
- **可扩展性**：支持添加新的模型提供商（通过 models.dev），并允许开发者贡献代码。
- **API 服务器**：可启动无头 API 服务器，便于集成和自动化。

## 适用与不适用场景

**适用场景**：
- 日常编码辅助，包括代码生成、修改和重构。
- 探索不熟悉的代码库，进行代码分析和规划变更。
- 自动化开发任务，通过 API 服务器集成到 CI/CD 流程。
- 需要跨平台桌面应用的开发者。

**不适用场景**：
- 需要图形化 IDE 完整功能的场景（OpenCode 主要提供终端 UI）。
- 对隐私要求极高，不能接受代码发送到第三方 LLM 的场景（需自行配置本地模型）。
- 需要多智能体协作或复杂工作流编排的场景（OpenCode 目前主要聚焦于单代理）。

## 技术架构与依赖

- **语言**：TypeScript
- **运行时**：Bun（要求 Bun 1.3+）
- **主要包**：
  - `packages/opencode`：核心业务逻辑与服务器。
  - `packages/app`：共享 Web UI 组件（SolidJS）。
  - `packages/desktop`：桌面应用（Electron）。
  - `packages/plugin`：插件 SDK（`@opencode-ai/plugin`）。
- **UI 框架**：TUI 使用 SolidJS 和 opentui。
- **依赖管理**：使用 Bun 进行依赖安装和脚本运行。

## 安装与快速开始

### 安装

```bash
# YOLO 方式
curl -fsSL https://opencode.ai/install | bash

# 包管理器
npm i -g opencode-ai@latest
scoop install opencode
choco install opencode
brew install anomalyco/tap/opencode
sudo pacman -S opencode
mise use -g opencode
nix run nixpkgs#opencode
```

### 快速开始

安装后，在终端运行 `opencode` 即可启动 TUI。使用 `Tab` 键切换代理，输入消息与代理交互。

## 典型使用方法

- **启动 TUI**：`opencode` 或 `opencode <directory>` 在指定目录启动。
- **启动 API 服务器**：`opencode serve`（默认端口 4096）。
- **启动 Web 界面**：`opencode web`。
- **使用 plan 代理**：在 TUI 中按 Tab 切换到 plan 代理，进行只读分析。
- **调用子代理**：在消息中输入 `@general` 调用通用子代理。

## 配置与部署要点

- **安装目录**：可通过 `$OPENCODE_INSTALL_DIR`、`$XDG_BIN_DIR`、`$HOME/bin` 等环境变量控制。
- **API 服务器**：可通过 `--port` 参数指定端口。
- **模型提供商**：通过 models.dev 添加新提供商，无需修改核心代码。
- **开发环境**：需要 Bun 1.3+，运行 `bun install` 和 `bun dev`。
- **桌面应用**：可通过 Homebrew 或 Scoop 安装，或从 releases 页面下载。

## 限制、风险与许可证

- **许可证**：MIT。
- **限制**：
  - 桌面应用仍为 Beta 版本。
  - 主要面向终端用户，图形界面功能有限。
  - 依赖外部 LLM 提供商，可能涉及数据隐私问题。
- **风险**：
  - 作为 AI 代理，可能生成不准确或有害的代码，需人工审查。
  - 项目处于活跃开发中，API 可能变化。

## 官方链接

- GitHub 仓库：https://github.com/anomalyco/opencode
- 官方网站：https://opencode.ai
- 文档：https://opencode.ai/docs
- Discord：https://opencode.ai/discord
- 最新版本：v1.18.16（发布于 2026-08-10）

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CONTRIBUTING.md、最新发布信息。
- 分析时间：2026-08-10（基于最新发布版本日期）。