opencode 框架手册

OpenCode 应用框架手册

⚠️ 重要说明: OpenCode 项目已被归档，以 "Crush" 名称在 Charm 团队继续发展。新仓库：https://github.com/charmbracelet/crush

---

目录

1. 项目概述
2. 核心架构
3. [Agents 系统设计](#3-agents 系统设计)
4. [工具与 MCP 集成](#4-工具与 mcp 集成)
5. [LSP 语言服务支持](#5-lsp 语言服务支持)
6. 配置系统详解
7. 自定义命令系统
8. 应用场景框架

---

1. 项目概述

1.1 项目背景

OpenCode 是一个基于 Go 构建的终端 AI 编程助手，提供智能编码辅助、调试和开发支持。采用 Bubble Tea 框架打造流畅的终端用户体验。

项目状态变更：

• 原仓库: https://github.com/opencode-ai/opencode (已归档)
• 继任项目: Crush (Charm 团队维护)

1.2 核心特性

特性	说明
交互式 TUI	基于 Bubble Tea，提供流畅的终端界面体验
多 AI 提供商支持	OpenAI、Claude、Gemini、AWS Bedrock、Groq、Azure、OpenRouter
会话管理	保存和管理多个对话会话，支持自动压缩
工具集成	AI 可执行命令、搜索文件、修改代码
Vim 编辑器	内置 Vim 风格编辑器，支持文本输入操作
持久化存储	SQLite 数据库存储会话和对话历史
LSP 集成	语言服务器协议支持，提供代码智能功能
文件变更追踪	实时可视化文件修改过程
外部编辑器	支持使用偏好编辑器编写消息
参数化命令	自定义命令支持命名参数占位符

1.3 安装方式

# 方法一：安装脚本（推荐）
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

# 指定版本安装
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | VERSION=0.1.0 bash

# 方法二：Homebrew (macOS/Linux)
brew install opencode-ai/tap/opencode

# 方法三：AUR (Arch Linux)
yay -S opencode-ai-bin

# 方法四：Go 安装
go install github.com/opencode-ai/opencode@latest

---

2. 核心架构

2.1 目录结构

opencode/
├── cmd/                    # CLI 命令入口（基于 Cobra）
│   ├── root.go            # 根命令定义
│   └── [子命令]           # 各功能模块命令
├── internal/
│   ├── app/               # 核心应用服务
│   │   ├── session.go     # 会话管理
│   │   └── message.go     # 消息处理
│   ├── config/            # 配置管理系统
│   │   ├── loader.go      # 配置加载器
│   │   └── schema.go      # 配置结构定义
│   ├── db/                # 数据库层
│   │   ├── migrations/    # 数据迁移脚本
│   │   └── models.go      # 数据模型
│   ├── llm/               # LLM 集成层
│   │   ├── providers/     # AI 提供商实现
│   │   │   ├── openai.go
│   │   │   ├── anthropic.go
│   │   │   ├── gemini.go
│   │   │   └── [其他 provider]
│   │   └── tools/         # AI 工具系统
│   ├── lsp/               # 语言服务器协议客户端
│   │   ├── client.go      # LSP 客户端实现
│   │   └── diagnostics.go # 诊断信息处理
│   ├── mcp/               # MCP 协议实现
│   │   ├── server.go      # MCP 服务器管理
│   │   └── tools.go       # MCP 工具注册
│   ├── tui/               # 终端用户界面
│   │   ├── components/    # UI 组件库
│   │   │   ├── editor.go  # Vim 编辑器组件
│   │   │   ├── chat.go    # 聊天界面
│   │   │   └── [其他组件]
│   │   ├── layouts/       # 布局管理器
│   │   └── keymaps.go     # 键盘映射配置
│   └── logging/           # 日志系统
├── install                 # 安装脚本
└── go.mod                  # Go 模块定义

2.2 数据流架构

┌─────────────────────────────────────────────────────────────┐
│                        用户交互层                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   TUI 界面    │  │   Vim 编辑器  │  │  命令对话框   │       │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
└─────────┼─────────────────┼─────────────────┼────────────────┘
          │                 │                 │
          └─────────────────┴─────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                        消息处理层                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Session Manager → Message Queue → AI Request Builder│   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                      AI 提供商层                               │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │ OpenAI  │  │Claude   │  │Gemini   │  │Local    │        │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
└──────────────┬─────┴────┬───────┴────┬───────┴────┬─────────┘
               │          │           │           │
               ▼          ▼           ▼           ▼
┌─────────────────────────────────────────────────────────────┐
│                      工具执行层                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Bash │ Glob │ Grep │ Edit │ Write │ Fetch │ LSP    │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              MCP Servers (外部工具)                    │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                      数据存储层                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              SQLite Database (会话、对话历史)           │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

3. Agents 系统设计

3.1 Agent 类型与职责

OpenCode 采用多 Agent 协作模式，每种 Agent 专注于特定任务领域：

Agent 名称	职责范围	适用场景	典型模型
Build	代码构建与开发	文件创建、修改、重构、新功能实现	Claude 3.7 Sonnet / GPT-4o
Plan	只读分析与规划	代码理解、架构分析、任务拆解	Gemini 1.5 Pro / Claude
General	复杂任务编排	多步骤任务、跨文件操作	GPT-4 Turbo
Explore	代码库探索	搜索模式匹配、上下文发现	轻量级模型即可

3.2 Agent 协作流程

用户请求
    │
    ▼
┌─────────────────────────────┐
│      Intent Classifier       │
│   (意图识别与路由)            │
└──────────────┬──────────────┘
               │
        ┌──────┴──────┐
        ▼             ▼
   ┌────────┐    ┌────────┐
   │ Build  │    │  Plan  │
   │ Agent  │    │ Agent  │
   └───┬────┘    └───┬────┘
       │             │
       └──────┬──────┘
              ▼
      ┌─────────────────┐
      │  General Agent  │
      │  (任务编排者)    │
      └────────┬────────┘
               │
         ┌─────┴─────┐
         ▼           ▼
    [子任务分发]   [结果聚合]
         │           │
    ┌────┴────┐     │
    ▼         ▼     │
[Explore] [Build]   │
 Agent   Agent       │
    │         │      │
    └─────────┴──────┘
              │
              ▼
        返回给用户

3.3 Agent 配置示例

{
  "agents": {
    "build": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 8192,
      "temperature": 0.7,
      "systemPrompt": "你是一名专业的代码构建专家，专注于..."
    },
    "plan": {
      "model": "gemini-1.5-pro",
      "maxTokens": 4096,
      "temperature": 0.3,
      "readOnly": true
    },
    "general": {
      "model": "gpt-4-turbo",
      "maxTokens": 8192,
      "temperature": 0.5,
      "subAgentMode": true
    },
    "explore": {
      "model": "claude-3-haiku",
      "maxTokens": 2048,
      "temperature": 0.7,
      "toolFocus": ["glob", "grep"]
    }
  }
}

3.4 Agent 工具权限模型

每个 Agent 拥有不同的工具访问权限：

工具	Build	Plan	General	Explore
edit/write	✅	❌	✅ (需确认)	❌
bash	⚠️	❌	✅ (需确认)	❌
glob/grep	✅	✅	✅	✅
fetch	✅	✅	✅	⚠️
diagnostics	✅	✅	✅	✅

---

4. 工具与 MCP 集成

4.1 内置工具集

文件操作工具

工具	功能描述	关键参数
glob	按模式搜索文件	pattern(必需), path(可选)
grep	在文件内容中搜索	pattern, path, include, literal_text
ls	列出目录内容	path, ignore(排除模式数组)
view/read	查看文件内容	file_path, offset, limit
write	写入文件	file_path, content
edit	编辑文件	file_path, oldString, newString, replaceAll
patch	应用补丁	file_path, diff

AI 辅助工具

工具	功能描述
bash	执行 Shell 命令（带超时控制）
fetch/webfetch	从 URL 获取内容，支持多种格式
diagnostics	获取 LSP 诊断信息（错误、警告）

4.2 MCP (Model Context Protocol) 集成

MCP 提供标准化的外部工具集成方式。

MCP 连接类型

{
  "mcpServers": {
    "本地文件服务": {
      "type": "stdio",
      "command": "/usr/local/bin/file-mcp",
      "args": ["--port", "3000"],
      "env": {},
      "timeout": 30000
    },
    "远程 API 服务": {
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      },
      "timeout": 15000
    }
  }
}

MCP 工具使用流程

配置 MCP Server
       │
       ▼
自动发现可用工具
       │
       ▼
AI 决定调用外部工具
       │
       ▼
权限检查 → 用户确认
       │
       ▼
执行工具 → 返回结果
       │
       ▼
AI 基于结果生成响应

4.3 MCP 工具示例

假设配置了 GitHub MCP Server：

用户请求："帮我查看这个 PR 的状态"

AI 内部思考:
1. 需要获取 PR 信息 → 使用 mcp_github_pull_requests_get
2. 需要检查 CI 状态 → 使用 mcp_github_check_runs_list

执行工具调用...

返回给用户整合后的 PR 状态报告

---

5. LSP 语言服务支持

5.1 LSP 集成架构

┌─────────────────────────────────────────────┐
│           OpenCode AI Agent                  │
└──────────────────┬──────────────────────────┘
                   │ 请求诊断信息
                   ▼
┌─────────────────────────────────────────────┐
│         LSP Client (内置)                    │
│  ┌─────────────────────────────────────┐   │
│  │  Diagnostics Manager                 │   │
│  │  - 错误聚合                           │   │
│  │  - 警告分类                           │   │
│  │  - 信息缓存                           │   │
│  └─────────────────────────────────────┘   │
└──────────────────┬──────────────────────────┘
                   │ 发送请求
                   ▼
┌─────────────────────────────────────────────┐
│        Language Server (外部)                │
│  ┌──────────────┐  ┌──────────────┐        │
│  │   gopls      │  │ tsserver     │        │
│  │  (Go)        │  │(TypeScript)  │        │
│  └──────────────┘  └──────────────┘        │
└─────────────────────────────────────────────┘

5.2 LSP 配置示例

{
  "lsp": {
    "go": {
      "disabled": false,
      "command": "gopls",
      "args": []
    },
    "typescript": {
      "disabled": false,
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "rust": {
      "disabled": false,
      "command": "rust-analyzer"
    }
  }
}

5.3 AI 使用 LSP 诊断的场景

用户："这段代码为什么报错？"

AI 执行流程:
1. 调用 diagnostics 工具获取文件错误信息
2. 分析错误原因和上下文
3. 提供修复建议

返回：
"发现两个问题：
1. line 25: undefined variable 'user' 
   → 应该是 'users'（注意复数形式）
   
2. line 42: type mismatch
   → expect string, got number"

---

6. 配置系统详解

6.1 配置层级结构

┌─────────────────────────────────────────────┐
│           Inline Config (行内)               │
│    (消息中的 [[...]] 指令)                   │
└─────────────────────────────────────────────┘
                    ↓ 叠加
┌─────────────────────────────────────────────┐
│          Project Config (.opencode.json)     │
│       (当前项目目录，优先级 4)                │
└─────────────────────────────────────────────┘
                    ↓ 叠加
┌─────────────────────────────────────────────┐
│         Global Config (~/.opencode.json)     │
│        (用户全局配置，优先级 3)               │
└─────────────────────────────────────────────┘
                    ↓ 叠加
┌─────────────────────────────────────────────┐
│       Remote Config (服务器推送)             │
│         (最低优先级，优先级 1)               │
└─────────────────────────────────────────────┘

6.2 完整配置示例

{
  "data": {
    "directory": ".opencode"
  },
  
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "disabled": false
    },
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "disabled": false
    },
    "gemini": {
      "apiKey": "${GEMINI_API_KEY}",
      "disabled": false
    },
    "groq": {
      "apiKey": "${GROQ_API_KEY}",
      "disabled": false
    }
  },
  
  "agents": {
    "coder": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 8192,
      "temperature": 0.7
    },
    "task": {
      "model": "gpt-4-turbo",
      "maxTokens": 4096,
      "temperature": 0.5
    },
    "title": {
      "model": "claude-3-haiku",
      "maxTokens": 80
    }
  },
  
  "autoCompact": true,
  "compactThreshold": 0.95,
  
  "shell": {
    "path": "/bin/zsh",
    "args": ["-l"]
  },
  
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  },
  
  "lsp": {
    "go": {
      "disabled": false,
      "command": "gopls"
    },
    "typescript": {
      "disabled": false,
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  },
  
  "debug": false
}

6.3 环境变量替换

配置支持 ${VARIABLE_NAME} 语法，自动从环境变量注入敏感信息。

---

7. 自定义命令系统

7.1 命令组织方式

自定义命令是存储在 .md 文件中的预定义提示模板，通过快捷键 Ctrl+K 快速调用。

目录结构

~/.config/opencode/commands/          # 用户命令 (user:)
├── git/
│   ├── commit.md
│   └── amend.md
├── deploy/
│   └── production.md
└── docs.md

项目目录/.opencode/commands/          # 项目命令 (project:)
└── tests.md

7.2 命令文件格式

.md 文件内容使用特殊指令格式：

# Commit Message Generator

RUN git diff --cached
READ README.md
WRITE commit_message.txt

支持的特殊指令：

指令	说明
RUN <command>	执行 Shell 命令
READ <file>	读取文件内容
WRITE <file>	写入文件（AI 生成）
EDIT <file> ...	编辑文件

7.3 参数化命令

支持使用 $PARAM_NAME 占位符：

# Generate Test for $FUNCTION_NAME

READ src/$MODULE_PATH
RUN grep -n "export function $FUNCTION_NAME" src/$MODULE_PATH
WRITE test_$FUNCTION_NAME.test.ts

运行时会自动提示输入参数值。

7.4 内置命令

命令	功能
Initialize Project	创建/更新项目记忆文件 OpenCode.md
Compact Session	手动压缩当前会话，创建摘要新会话

---

8. 应用场景框架

8.1 虚拟团队项目编程场景

场景架构

┌─────────────────────────────────────────────────────────────┐
│              虚拟团队协作环境                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │   Product    │    │    Tech      │    │   QA         │  │
│  │   Manager    │◄──►│    Lead      │◄──►│   Engineer   │  │
│  │   (Plan)     │    │   (Build)    │    │   (General)  │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│       │                   │                   │             │
│       ▼                   ▼                   ▼             │
│  ┌──────────────────────────────────────────────────┐     │
│  │           Agent Orchestrator                     │     │
│  │   - 任务路由与分发                                 │     │
│  │   - 上下文共享                                     │     │
│  │   - 结果聚合                                       │     │
│  └──────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘

典型工作流

需求分析阶段：

1. Product Agent (Plan) 接收产品需求文档
2. 执行代码库探索，理解现有架构
3. 输出技术方案和任务拆解

开发实施阶段：

1. Tech Lead Agent (Build) 接管具体实现
2. 使用 edit/write 工具修改代码
3. 调用 bash 运行测试验证

质量保证阶段：

1. QA Engineer Agent (General) 执行全面检查
2. 集成 LSP 诊断确保代码质量
3. 输出测试报告和修复建议

8.2 多媒体文件设计私人助理场景

MCP 工具链扩展

用户请求："分析这个视频文件的元数据并生成说明文档"

┌──────────────────────────────────────────────┐
│  AI Agent 决策层                              │
│  └─→ 需要多媒体处理 → 调用 MCP 工具           │
└──────────────────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────────┐
│  MCP Tool Chain                               │
│  ┌─────────────┐  ┌─────────────┐           │
│  │ ffprobe-mcp │──►│ markdown-gen│           │
│  │ (提取元数据) │  │(生成文档)    │           │
│  └─────────────┘  └─────────────┘           │
└──────────────────────────────────────────────┘

配置示例：多媒体处理 MCP

{
  "mcpServers": {
    "multimedia": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@your-org/multimedia-mcp"],
      "env": {
        "FFPROBE_PATH": "/usr/local/bin/ffprobe"
      }
    },
    "image-analyzer": {
      "type": "sse",
      "url": "https://api.imageservice.com/mcp",
      "headers": {
        "X-API-Key": "${IMAGE_SERVICE_KEY}"
      }
    }
  }
}

应用场景示例

场景	Agent 协作模式	MCP 工具链
视频项目文档生成	Plan → Build	ffprobe-mcp + markdown-generator
图像素材管理	Explore → General	image-analyzer + file-system-mcp
音频处理工作流	Build (多次迭代)	audio-processor-mcp

---

附录

A. 快捷键参考

快捷键	功能
Ctrl+K	打开自定义命令对话框
Esc	取消当前操作/关闭对话框
Tab	自动补全

B. 配置环境变量速查表

变量名	用途
ANTHROPIC_API_KEY	Claude API
OPENAI_API_KEY	OpenAI API
GEMINI_API_KEY	Google Gemini
GROQ_API_KEY	Groq 平台
GITHUB_TOKEN	GitHub Copilot / MCP

C. 相关资源

• 原项目仓库: https://github.com/opencode-ai/opencode (已归档)
• 继任项目 Crush: https://github.com/charmbracelet/crush
• MCP 规范文档: https://modelcontextprotocol.io
• LSP 规范: https://microsoft.github.io/language-server-protocol

---

最后更新：2026 年 4 月 | 基于 OpenCode GitHub 仓库最新信息整理