OpenCode 学习路线图：从原理到实战的完整指南
📚 分类: AI 编程工具教程 ⏱️ 预计耗时: 15 分钟阅读 🎯 难度: 入门 🔧 环境要求: 无特殊要求（本文为概念理解与学习路径规划）
你将学到什么
完成本教程后，你将能够：
- [ ] 理解 OpenCode 的核心定位，以及它与其他 AI 编程工具的区别
- [ ] 掌握 OpenCode 的“六层架构”模型，对它的能力范围有一个清晰的认知
- [ ] 根据自己的学习目标，制定一份个性化的 OpenCode 学习路线图
- [ ] 知道从哪里开始动手实践，以及如何避免常见的“追新”陷阱
最终效果
本文不会让你运行任何代码，但当你读完后，你将拥有一张清晰的“OpenCode 学习地图”。你不会再对着它众多的功能列表感到迷茫，而是能清楚地知道：我现在应该学什么？下一步要去哪里？ 你会理解为什么 OpenCode 的难点在于“能力太开放”，并学会如何安全、高效地驾驭它。
前置准备
在开始阅读前，请确认你已经对“AI 编程助手”（如 GitHub Copilot）有一个基本概念。
1. 理解本文的定位
本文是一篇 “学习路线图” ，而不是操作手册。它旨在帮你建立正确的“心智模型”。如果你在阅读过程中遇到不懂的命令或配置项，请不要停下来深究，先通读全文，建立整体认知。
第 1 步：打破误区 —— OpenCode 不只是另一个“AI 工具”
🎯 目标：理解 OpenCode 最独特的设计理念，为后续学习定下基调。
很多初学者会把 OpenCode 当成一个“能在终端里写代码的 AI”，但这样的理解太浅了。它的独特之处在于一个设计：Plan mode（计划模式）和 Build mode（构建模式）的切换。
📝 操作： 想象一下，你刚在终端里输入 opencode 启动它，然后按下了键盘上的 Tab 键。
- Plan mode: 当你按下
Tab键，你会进入“只规划，不动手”的模式。在这个模式下，AI 会分析你的需求，生成一份详细的执行计划。 - Build mode: 再次按下
Tab键，切换回“构建模式”。AI 会根据刚才的计划，开始修改你的代码文件。
🤔 为什么要这样设计？ 其他工具往往是“你说一句，它改一行”。OpenCode 的设计者认为，好的 AI 编程应该是“先想清楚，再动手干”。这个设计强迫你在执行之前，先让 AI 把逻辑理清楚，从而避免 AI 胡乱修改代码，造成难以预料的问题。
✅ 验证： 你已经理解了 OpenCode 与其他工具最核心的差异点。请记住这个关键词：Plan / Build 模式切换。这是贯穿整个教程的核心概念。
第 2 步：建立全局视角 —— 理解 OpenCode 的“六层架构”
🎯 目标：将 OpenCode 复杂的功能体系归纳为一个易于理解的六层模型。
OpenCode 功能太多，很容易让人迷失。你可以把它想象成一栋六层楼的房子，每层解决不同的问题。
📝 操作： 请记住下面这张“分层图”，我们之后的每一篇文章都会围绕它展开。
| 层级 | 解决的问题 | 你什么时候需要关心它 |
|---|---|---|
| ① 入口层 | OpenCode 在哪里运行？（TUI 终端、IDE 插件、Web 等） | 刚开始，选择你喜欢的运行方式时。 |
| ② 上下文层 | 如何让 AI 知道你的项目结构和当前会话状态？（AGENTS.md 文件、@file 引用等） | 想让 AI 更准确地理解你的项目时。 |
| ③ 执行层 | AI 如何读代码、改文件、运行命令？（read、edit、bash 等） | 想了解 AI 具体做了什么，或接外部工具时。 |
| ④ 角色层 | 如何把重复的任务沉淀成可复用的命令或技能？（commands、agents、skills） | 想让一次成功的经验变成下次自动执行的规则时。 |
| ⑤ 模型层 | 用哪个 AI 模型？哪个供应商？如何管理 API Key？ | 任务复杂度变化，需要为不同任务选择不同模型时。 |
| ⑥ 治理层 | 如何控制 OpenCode 的权限、网络和分享范围？ | 进入真实项目、团队协作或对外分享时。 |
✅ 验证： 你可以尝试用自己的话复述这六层分别是什么。例如：“入口层是‘门’，上下文层是‘窗户’，执行层是‘手脚’，角色层是‘工具箱’，模型层是‘大脑’，治理层是‘保安’。”
💡 提示：对初学者来说，掌握①入口层、②上下文层、③执行层，就足以让它高效地工作了。不要一开始就想着搞懂所有层级。
第 3 步：制定学习路径 —— 按阶段选择你的阅读顺序
🎯 目标：根据你的学习阶段，规划一个清晰、不绕弯子的学习路径。
原始教程提供了一个推荐的阅读顺序，但我们可以把它拆成三个阶段，每个阶段都有明确的目标和“过关标准”。
📝 操作： 请对照下面的“三个学习阶段”，找到你目前的位置，然后按顺序阅读后续教程。
阶段一：上手（快速跑通）
- 目标：让 OpenCode 在你的项目里真正工作起来。
- 阅读顺序：
01 定位→02 安装与运行→03 终端 TUI 工作流 - 过关标准：能成功安装、连接模型供应商、启动 TUI，并让它只读地解释你的项目结构。
阶段二：沉淀（让经验可复用）
- 目标：把一次成功的经验，变成下次自动遵守的规则。
- 阅读顺序：
04 配置与 Rules→05 Agents 与 Skills→06 模型与供应商策略 - 过关标准：能清晰区分
config、rules、commands、agents、skills和plugins的用途，并知道各自应该放什么内容。
阶段三：治理（安全可控地使用）
- 目标：让 OpenCode 进入真实生产环境而不失控。
- 阅读顺序：
07 工具与 MCP→08 安全与分享 - 过关标准：能写出权限基线，知道在什么情况下应该禁止分享、联网、部署和读取密钥。
⚠️ 常见错误：不要在“上手”阶段就去研究 MCP 或 Agents。请务必先完成“只读解释项目结构”这个任务。如果这个基础任务都不稳定，就说明你的模型连接或上下文配置有问题，需要先解决它，而不是盲目地添加更复杂的功能。
✅ 验证： 你已经可以根据自己的目标，从下面的“下一步”中选择对应的文章开始学习了。
进阶技巧（可选）
掌握基础学习路径后，你可以尝试：
使用“AI 导航顾问”：如果你不确定从哪开始，可以把下面这段提示词丢给任何 AI 聊天工具，让它为你规划个性化路径：
你是 OpenCode 理解篇导航顾问。请按“最小够用、安全优先”的原则，根据以下信息给我一个可落地的学习方案： - 我的目标：[你的目标，例如：用OpenCode重构一个React项目] - 对 OpenCode 的了解：[新手 / 已看过官方文档 / 有使用经验] - 最想解决的问题：[例如：如何让AI理解我的项目结构] - 可投入时间：[例如：2小时 / 一周] - 经验水平：[例如：前端初级 / 全栈中级]
常见问题 (FAQ)
Q1: 为什么我不能直接跳到“高级功能”去学？A: 因为 OpenCode 的稳定性来自“低风险起步”。它的上限虽然高，但如果你连最基础的文件引用都搞不定，就接入 MCP 等外部工具，一旦出错，你将很难排查是哪个环节出了问题。
Q2: 这个教程和官方文档有什么区别？A: 官方文档是“字典”，按功能分类，适合查命令和 API。本教程是“使用指南”，按学习阶段组织，教你如何判断“什么时候该用什么功能”。两者互为补充。
总结
恭喜你完成了本教程的“导航”部分！🎉
回顾一下我们今天学到的核心内容：
- 核心设计：OpenCode 通过
Tab键切换Plan和Build模式，强迫 AI “先想后做”。 - 六层架构：将 OpenCode 拆解为入口层、上下文层、执行层、角色层、模型层、治理层，让你从全局理解它的能力。
- 三阶段学习法：按照“上手 → 沉淀 → 治理”的顺序学习，确保每一步都走得稳。