当前版本：OpenCode v2（最新官方版）
OpenCode v2 是终端驱动的开源 AI 编码智能体，和传统代码补全工具、网页对话 AI 完全不同。它可以读取完整项目上下文，自动分析代码、制定开发方案、修改本地文件、执行开发任务，真正实现「你描述需求，AI 落地代码，你负责审核决策」的全新开发模式。
OpenCode v2 支持四种使用形态：终端 TUI、桌面客户端、Web 网页会话、Docker 部署，功能全面且轻量化，是新手和开发者高效编码的实用工具。
一、教程适配人群
- 掌握任意一门编程语言（JS、Python、Java、Go 等），能看懂基础代码
- 会简单终端操作、了解基础项目目录结构
- 想借助 AI 提升开发效率、快速完成功能开发与代码重构
- 独立开发者、项目维护者、团队开发成员
二、OpenCode v2 与传统 AI 工具对比
OpenCode v2 不属于聊天工具、也不是简单 IDE 插件，是可自主执行开发任务的智能编码代理，核心差异如下：
| 特性 | 网页聊天 AI（ChatGPT/Claude） | IDE 补全工具（Copilot） | OpenCode v2（AI 智能体） |
|---|---|---|---|
| 交互方式 | 网页对话框 | IDE 内嵌插件 | 终端 TUI / 桌面 App / Web 会话 |
| 项目读取能力 | 手动粘贴/上传代码片段 | 仅读取当前打开单文件 | 自动读取整个项目源码 |
| 文件操作能力 | 仅输出文本代码，无法改文件 | 仅补全代码片段 | 直接新增/修改/重构本地代码文件 |
| 上下文理解 | 有限对话上下文 | 局部单文件理解 | 全局项目级上下文理解 |
| 任务能力 | 方案咨询、代码片段生成 | 辅助编码增强 | 完整落地开发任务（新增功能、修 Bug、重构） |
三、v2 版本前置准备
1. 环境要求
- 现代终端：WezTerm、Alacritty、Ghostty、Kitty（推荐）
- Windows 用户：不再支持原生包管理器，优先使用 WSL2 环境
2. 必备配置
拥有任意 LLM 模型 API 密钥，新手推荐官方 OpenCode Zen / OpenCode Go 模型，开箱即用。
四、快速上手完整流程（必学）
OpenCode v2 标准使用流程：安装 → 连接模型 → 项目初始化 → 智能开发 → 回滚/分享
1. 连接大模型（/connect）
安装完成后，打开终端输入 opencode 进入交互界面，执行核心配置命令：
/connect
根据提示选择模型服务商，粘贴 API 密钥，完成模型绑定。配置后可执行 /models 查看当前可用模型列表。
2. 项目初始化（/init）
进入你的项目根目录，启动 OpenCode 并初始化项目，让 AI 适配你的项目规范：
# 进入项目目录 cd /你的项目路径启动 OpenCode opencode 初始化项目/init
初始化后项目根目录会生成 AGENTS.md 文件（v2 核心配置），用于定义项目编码规范、智能体权限、角色能力。
重要建议：务必将 AGENTS.md 提交到 Git 仓库，后续所有 AI 开发都会遵循该文件规范。
五、核心实操用法（新手常用）
1. 只读解读代码（学习/查 Bug）
使用 @ 符号快速定位项目文件，仅分析不修改代码，适合阅读陌生代码库、梳理逻辑：
帮我解读 @src/api/index.ts 文件的接口鉴权逻辑，标注核心流程和关键点
2. 新增完整功能（v2 智能体模式）
v2 摒弃旧版简单计划/构建模式，升级为多智能体协作，更安全、更精准：
- Tab 快捷键：切换不同角色智能体（方案评审、代码开发、测试校验）
- 先切换「只读评审智能体」：仅输出开发方案，不修改代码，可反复迭代优化
- 方案确认无误后，切换「开发智能体」：自动落地代码修改
完整需求示例（可直接复用）：
优化笔记删除功能，不直接物理删除数据，改为软删除；新增回收站页面，支持已删除笔记恢复和永久清空功能
💡 进阶技巧：可直接将 UI 设计图、参考截图拖拽到终端，AI 可识别图片内容并落地对应样式和功能。
3. 局部快速改代码
简单代码优化、逻辑复用、小 Bug 修复，无需预演方案，直接指定参考文件修改：
参考 @src/notes.ts 的接口鉴权逻辑，为 @src/settings.ts 配置相同的登录校验规则
4. 代码修改回滚/重做
AI 修改效果不符预期、出现代码错误，可一键撤销，支持多次连续操作：
# 撤销上一轮所有代码修改 /undo恢复已撤销的修改/redo
5. 团队会话分享
快速生成开发对话链接，同步需求和实现思路，方便团队协作对接：
/share
提示：对话默认私密，仅手动分享后可查看，保障项目代码安全。
六、v2 专属新功能（进阶必看）
1. Web 网页会话
在系统终端执行命令（非 OpenCode 内部），启动网页端操作界面，支持大屏查看、多人协同：
opencode pair
执行后会生成本地访问地址、账号密码，浏览器打开即可使用网页版 OpenCode。
2. 桌面客户端
v2 原生支持 macOS、Windows、Linux 图形桌面 App，脱离终端即可使用，操作更直观。
3. 插件与自定义配置
支持 MCP 服务器对接、自定义终端主题、快捷键、私有命令，可根据个人开发习惯深度定制工具能力。
七、v2 常用命令速查表
| 命令 | 作用说明 |
|---|---|
/connect | 配置/切换 LLM 模型 API 密钥 |
/models | 查看当前已配置的可用模型列表 |
/init | 初始化项目，生成 AGENTS.md 配置文件 |
/undo | 撤销上一轮代码修改，支持多次撤销 |
/redo | 重做已撤销的代码变更 |
/share | 生成对话分享链接，复制到剪贴板 |
/update | 检查并更新 OpenCode v2 最新版本 |
八、新手避坑注意事项
- v2 与 v1 不兼容，安装 v2 会覆盖旧版本，无法共存
- Windows 原生 Chocolatey、Scoop 不再支持 v2，优先使用 WSL2 或桌面客户端
opencode pair为系统终端命令，不能在 OpenCode 交互界面内执行- 所有 AI 生成代码必须人工审核，工具仅辅助开发，不替代开发者决策
- 复杂功能优先用评审智能体预演方案，确认后再执行代码修改，降低出错概率
九、官方资源
- v2 官方文档：https://opencode.ai/v2/docs
- GitHub 仓库：https://github.com/anomalyco/opencode
十、其他AI编程工具
字节 TRAE：https://www.trae.cn
阿里 Qoder：https://qoder.com
0 条笔记