第 0 章 · 写在前面

这一章不教任何花哨技巧，只解决三件事：你手里拿的是什么工具、该用什么心智模型理解它、以及如何把这套教程用出最大效果。

本章包含 4 个知识点：

1. OpenCode 与 TUI 是什么
2. OpenCode V2 的核心心智模型
3. 安装、升级与环境验证
4. 如何使用这套教程

---

知识点 1：OpenCode 与 TUI 是什么

① 定位

这是全教程的起点。在学任何快捷键之前，先要准确知道 OpenCode 的产品边界——它是什么、不是什么。边界不清会导致两类典型问题：把它当搜索引擎用（失望），或把它当魔法用（闯祸）。

② 是什么（What）

OpenCode 是一个运行在终端里的 AI 编程助手（AI Coding Agent）。你用自然语言下达任务，它能够阅读代码、编写和修改文件、执行命令、搜索网络，并在你授权下完成多步骤的真实开发工作。

需要分清三个层次：

概念	含义
OpenCode	产品本身，包含服务端核心与多种交互界面
TUI（终端界面）	Terminal User Interface，在终端窗口里运行的全屏文字界面，是本教程的主角
模型（Model）	背后真正做推理的大语言模型，由供应商提供，可配置和切换（第 6 章详解）

打个比方：OpenCode TUI 是「驾驶舱」，模型是「发动机」，工具（读写文件、跑命令、联网）是「机械臂」。你是机长——机械臂能干，但每次干什么、干到什么程度、何时刹车，由你决定。

TUI 不是「落后的界面」，而是为高频操作者设计的效率界面：键盘不离手、启动极快、远程 SSH 可用、资源占用极低、内容以纯文本为主便于复制。它的学习曲线比图形界面略陡，但上限更高。

③ 怎么做（How）

在终端中进入任意项目目录，运行：

opencode

即可进入 TUI 全屏界面。也可以直接带上首条指令：

opencode "解释一下这个项目的目录结构"

退出 TUI 通常使用 Leader 键菜单（默认 Ctrl+X）中的退出项，或在命令面板中选择退出——具体操作第 2 章会手把手展开，现在只需知道「它是一个可以随时进出的普通终端程序」即可。

④ 为什么这么做（Why）

• 「聊天机器人」和「Agent（智能体）」是两代东西。 聊天机器人只在对话框里输出文字，回答完就结束；Agent 拥有工具——它能真的读你的文件、改你的代码、跑你的测试。输出会从「屏幕上的字」变成「磁盘上的变更」，能力和风险同时上了一个台阶。
• 终端是程序员的主场。 代码、Git、构建、日志都在终端里，TUI 让 AI 和这些东西处在同一个战场，不需要在浏览器和编辑器之间来回搬运上下文。
• 理解「界面 / 产品 / 模型」三层分离，能解释绝大多数现象。 回答变慢可能是模型问题，文件没被读到可能是你没给上下文，快捷键失灵可能是 TUI 版本问题——分层定位，才不会把所有问题都归咎于「AI 不行」。

⑤ 这样做的好处

• 预期正确：知道它是 Agent 而非聊天框，你才会主动给上下文、设约束、做验收。
• 选型不纠结：理解 TUI 的价值（快、轻、可远程），就不会因为「界面朴素」而低估它。
• 故障可定位：三层模型让你遇到问题时知道该查配置、查模型还是查操作。
• 为后续章节打好地基：后面所有内容都是在「驾驶舱 + 发动机 + 机械臂」这个比喻上展开的。

⑥ 不这么做的问题 / 坏处

• 当聊天框用 → 只问「这段代码什么意思」，从不给项目上下文，得到正确的废话。
• 当魔法用 → 一句「帮我把项目弄好」就放手，它可能大改一通、删掉你不希望动的东西。
• 把 TUI 当残次品 → 没理解键盘驱动的设计逻辑，到处找鼠标按钮，处处别扭。
• 概念混淆 → 模型答得差时去重装 TUI，界面卡住时去换模型，南辕北辙。

⑦ 举一反三：三个例子

例 1（基础）：第一次启动 TUI

📌 场景：你装好 OpenCode 后，在终端里输入 opencode，进入了全屏界面，看到一个输入框。

✅ 正确认知：「这是 Agent 的驾驶舱。我接下来发的每句话，它都可能转化为真实的文件操作或命令执行。」于是你的第一条消息写的是：

请先浏览当前项目，向我介绍：用什么技术栈、入口文件在哪、如何运行和测试。
先不要修改任何文件。

🔍 讲解：这条消息体现了准确的产品认知：知道 Agent 能读项目（让它浏览），也知道它可能动手（显式加上「先不要修改」）。第一次交互就让 AI 做只读侦察，是最稳妥的开局——先建立共同的项目理解，再谈具体任务。

例 2（进阶）：在远程服务器上使用

📌 场景：你通过 SSH 登录到一台没有图形界面的云服务器，需要在上面排查一个后端服务问题。

✅ 做法：在 SSH 会话中直接进入项目目录运行 opencode，让它读取日志、查看配置、运行诊断命令，并在它要重启服务或改配置前要求停下确认。

🔍 讲解：这正是 TUI 相对图形客户端的独特战场——任何能 SSH 到达的地方就能用。但要注意：远程环境上的操作影响的是真实运行的服务，所以「重启 / 改配置前确认」这道闸门比本地更重要。环境越危险，确认越要严格，这条原则贯穿全书。

例 3（挑战）：分清「这次表现差」是哪一层的问题

📌 场景：你让 AI 修改代码，它连续两次改错方向。同事建议你「重装一下」。

✅ 分层排查：

1. 先看 Prompt 层：我给够背景和目标了吗？（大概率问题在这里）
2. 再看 模型层：当前选的模型是否适合这个复杂任务？要不要换一个？
3. 最后才看 TUI / 配置层：版本是否过旧、配置是否异常。

🔍 讲解：「表现差」绝大多数时候不是程序故障，而是 Prompt 模糊或模型能力不匹配。一上来重装 TUI，就像收音机信号不好时去擦外壳——力气用错了层。这个分层排查习惯会在第 10 章《故障排查》中系统展开，这里先建立直觉。

---

⑧ 练习题 ×2

练习 1（巩固型）

📝 题目：用你自己的话向一位没用过 OpenCode 的同事解释：OpenCode、TUI、模型三者分别是什么，彼此什么关系。

💡 思路提示：可以直接套用本章的「驾驶舱 / 发动机 / 机械臂」比喻，或者自己造一个更好懂的比喻。

✅ 参考答案：

OpenCode 是一个 AI 编程助手（Agent），能读代码、改文件、跑命令；
TUI 是它在终端里的操作界面，用键盘操作，启动快、能远程 SSH 使用；
模型是背后真正做推理的大脑，由供应商提供，可以按任务切换。
关系：我在 TUI（驾驶舱）里下指令，模型（发动机）负责思考，
工具（机械臂）负责真正动手改东西，决定权始终在我手里。

🔍 讲解：检验答案是否合格，看三点：有没有说清 Agent「能动手」的本质、有没有把界面和模型分开、有没有强调「人在决策位」。这三点正是本知识点的核心。

练习 2（迁移型）

📝 题目：除了编程，你能想到至少 2 个「在没有图形界面的远程机器上使用 AI Agent」的实际场景吗？

💡 思路提示：想想哪些工作天然发生在服务器、嵌入式设备或容器内部。

✅ 参考答案：

1. 线上故障排查：SSH 到生产跳板机，让 AI 协助分析日志、定位问题进程；
2. 服务器运维：在远程主机上让 AI 解读配置、生成安全加固命令（执行前人工审核）；
3. 边缘 / 嵌入式设备：在树莓派等设备上直接让 AI 调试脚本和驱动；
4. CI 容器内排障：进入构建容器，让 AI 帮忙分析依赖和构建失败原因。

知识点 2：OpenCode V2 的核心心智模型

① 定位

知识点 1 讲产品形态，本知识点讲使用哲学。同一个工具，用「问答」心态和用「协作」心态，效果天差地别。本知识点给出贯穿全书的四句话心智模型，也是后续所有章节的总纲。

② 是什么（What）

使用 OpenCode V2，需要建立四个核心心智模型：

① 它是一个「新同事」，不是「搜索引擎」。 搜索是你给关键词、它给链接；新同事需要你交代背景、说明目标、检查产出，而且它会犯错、会遗忘、会误解——需要协作而非索取。

② 会话即上下文（Conversation = Context）。 模型没有记忆，它在某一刻「知道」的全部内容，就是当前会话里的东西：你说的话、你附上的文件、它自己之前的回答、工具返回的结果。关掉会话，上下文就消失（规则文件除外，见模型④）。

③ 规则靠文件持久化（AGENTS.md）。 每次重复交代同样的规范是低效的。V2 通过 AGENTS.md 把长期规则固化下来——它在每次会话启动时自动加载。V2 只识别 AGENTS.md，不会回退使用 CLAUDE.md，这是 V2 与 V1 / 其它工具的重要差异，第 4 章详解。

④ 权限是闸门（Permissions）。 AI 可以读文件、写文件、执行命令，但高风险动作需要你授权。你可以在每次提示时批准，也可以按项目配置策略。授权不是走流程，是你控制风险的核心手段。

四句话可以压缩成一句总纲：用会话提供当下的上下文，用 AGENTS.md 沉淀长期的规则，用权限守住风险的底线，而你始终是决策者。

③ 怎么做（How）

把心智模型落成四个日常习惯：

1. 像带新人一样写任务：交代背景 → 说明目标 → 划清边界 → 定义验收（第 1 章已系统训练）。
2. 主动管理上下文：用 @文件 提供资料；任务跑偏时果断开新会话，而不是在混乱的长对话里硬撑（第 3 章）。
3. 把重复说三遍的规则写进 AGENTS.md：编码规范、测试要求、禁区清单——写一次，永久生效（第 4 章）。

④ 为什么这么做（Why）

• 模型本质是「上下文内的概率生成」。 这决定了「会话即上下文」不是产品设定，而是技术原理：你不给的信息它真的没有，会话外的规则它真的看不见。
• 人脑带宽有限，重复沟通必出错。 AGENTS.md 的存在是为了对抗「同一条规范说一百遍还可能漏」的人性弱点——把易忘的事外置成文件，比依赖记忆可靠。
• Agent 的能力与风险对称增长。 它能改文件、能跑命令，这既是效率来源也是事故来源。权限闸门是让「能力」不变成「破坏力」的机械设计：没有闸门的自主执行，等于把键盘交给一个会犯错的陌生人。
• 把 AI 当同事，是唯一可持续的协作姿态。 当搜索用，你会因为「答案不是现成的」而持续失望；当神用，你会放弃自己的判断责任。同事心态既利用它的执行力，又保留人的审查权。

⑤ 这样做的好处

• 协作可预期：知道它会犯错，你会自然地做验收，而不是盲信。
• 上下文干净：主动管理会话，减少长对话跑偏和信息丢失。
• 规则零重复：规范沉淀进文件，新人、新项目、未来的自己都直接受益。
• 风险始终可控：授权闸门让危险操作在发生前被拦截。
• 能力随使用持续增长：你每写一条好 Prompt、沉淀一条规则，工具就越用越顺手——这是「越用越强」的复利。

⑥ 不这么做的问题 / 坏处

• 搜索心态 → 期待「一问即得」，不给上下文不做验收，失望而归。
• 迷信心态 → 全盘信任产出，隐藏 bug、错误改动直接进入代码库。
• 不管理上下文 → 一个会话用到底，早期关键信息被压缩丢失，AI 前后矛盾。
• 规则只靠嘴说 → 每次会话重新交代编码规范，十次有三次漏，团队协作更是灾难。
• 授权走形式 → 不看内容一路批准，权限闸门形同虚设。

⑦ 举一反三：三个例子

例 1（基础）：同一个 bug，两种协作姿态

📌 场景：测试报错，你想让 AI 修。

❌ 搜索心态：「TypeError 怎么解决？」——期待一个通用答案。

✅ 同事心态：

运行 npm test 报 TypeError: Cannot read properties of undefined (reading 'id')，
位置 src/order.ts:42。请先只定位根因、说明 undefined 从哪来，
给最小修复方案，等我确认后再改，只允许动 src/order.ts。

🔍 讲解：同一个任务，第二种姿态给了证据（完整报错 + 位置）、边界（只动一个文件）、节奏（先诊断后动手）。这不是 Prompt 技巧问题，而是你心里把对方放在什么位置：当搜索框，你只配输入关键词；当同事，你才会交代这些。姿态对了，话自然就对了。

例 2（进阶）：该开新会话时果断开

📌 场景：你和 AI 在一个会话里折腾了很久登录页的样式，中途还穿插问了两个无关问题。现在你要开始做支付模块，AI 回答时不断引用登录页的旧假设。

✅ 做法：新开一个会话处理支付模块，只带上支付相关的文件和背景，让上下文从零开始保持纯净。

🔍 讲解：「会话即上下文」是双刃剑：旧上下文能提供连续记忆，也会成为偏见来源。当任务领域切换、且旧信息不再相关时，新会话不是放弃历史，而是主动重置语境。很多人舍不得开新会话，觉得「再聊聊就掰回来了」，结果在被污染的上下文里越陷越深。

例 3（挑战）：用 AGENTS.md 替代「每天的唠叨」

📌 场景：你发现自己每次会话都要重复说「提交信息用 Conventional Commits、不要动数据库迁移、测试用 Vitest」。

✅ 做法：在项目根目录创建 AGENTS.md，写清这些长期规则；V2 每次启动自动加载。同时删掉你之前写的 CLAUDE.md 幻想（V2 不读它）。

# 项目约定
- 提交信息必须使用 Conventional Commits 格式（feat:/fix:/docs: ……）
- 未经明确授权，不要创建或修改数据库迁移文件
- 单元测试使用 Vitest，测试文件与源码同级放置

🔍 讲解：这一步是从「一次性 Prompt」走向「规则资产」的分水岭。写一次，以后每个会话、每位团队成员都自动遵守。反过来说，如果规则只存在你嘴里，那么你请假那天、新项目启动那天、深夜疲劳那天，规则就会失效。文件不会疲劳，这就是持久化的价值。

---

⑧ 练习题 ×2

练习 1（巩固型）

📝 题目：判断下面做法分别违反了哪个心智模型：（a）一个长会话里什么任务都聊；（b）每次都口头重新说测试规范；（c）AI 弹出授权框时看也不看一路回车。

💡 思路提示：回到四个心智模型逐一对应。

✅ 参考答案：

(a) 违反「会话即上下文」：无关任务混杂会污染语境、稀释关键信息，
    应按任务领域分开会话。
(b) 违反「规则靠文件持久化」：重复规范应写进 AGENTS.md，而不是靠每次口述。
(c) 违反「权限是闸门」：不看内容就批准等于放弃风险控制，
    危险操作可能在不知不觉中执行。

🔍 讲解：这类判断题练的是「看见行为 → 映射到原则」的能力。原则只有真正能用来审视自己的行为时，才不是空话。

练习 2（迁移型）

📝 题目：把「会话 / 持久化规则 / 权限闸门」这套模型迁移到带一位人类新同事的场景：你会如何安排他的入职和工作？

💡 思路提示：一次性口头交代 vs 一份员工手册；每次任务口头说明 vs 任务单；财务/生产权限直接给 vs 分级审批。

✅ 参考答案：

- 会话 ≈ 每次的当面沟通：交代当前任务的具体背景和目标，做完一批再开下一批；
- AGENTS.md ≈ 员工手册 / 团队规范文档：长期有效的规则写下来，入职就给，不必天天重复；
- 权限闸门 ≈ 分级审批：普通操作放手，动生产、动钱、对外发布必须主管签字；
- 人始终是决策者 ≈ 导师负责制：新同事可以提方案、做执行，但方向和拍板权在导师。

知识点 3：安装、升级与环境验证

① 定位

前面两个知识点解决「怎么理解」，本知识点解决「怎么跑起来」。重点不是穷举所有安装方式，而是建立一个意识：安装完成的标准不是「命令能运行」，而是「界面能启动 + 模型能用 + 版本确认」三项全部验证通过。

② 是什么（What）

OpenCode 的获取方式主要有三类（按官方文档为准，命令可能随版本更新调整）：

方式	适用情况	典型命令
官方安装脚本	通用 Linux / macOS	`curl -fsSL https://opencode.ai/install
npm 全局安装	已有 Node.js 环境	npm install -g opencode-ai
系统包管理器	Arch 等发行版	如 paru -S opencode（以 AUR 实际包名为准）

安装后涉及三个独立的验证环节：

1. 程序验证：opencode --version 能输出版本号。
2. 模型验证：需要配置至少一个模型供应商的凭证（如 API Key），通常通过 opencode auth login 或配置文件完成（第 6 章详解）。
3. 界面验证：在任意目录运行 opencode 能进入 TUI 全屏界面并成功发出一条消息。

升级一般使用 opencode upgrade（脚本安装方式）或对应的包管理器更新命令；npm 安装则用 npm update -g opencode-ai。用哪种方式装的，就用哪种方式升级，混装混升容易产生两个版本并存的诡异问题。

③ 怎么做（How）

标准验证流程（四步）：

# 1. 确认版本与实际路径（防止多个版本并存）
opencode --version
which opencode

# 2. 进入一个测试项目目录（先用无关紧要的项目练手）
cd /path/to/test-project

# 3. 启动 TUI
opencode

# 4. 在 TUI 中发一条只读消息验证模型链路
请回复“链路正常”四个字，不要执行任何操作。

④ 为什么这么做（Why）

• 「能运行」不等于「能用」。 程序装好了，但 API Key 没配、网络不通、模型未激活，TUI 照样能启动——一到发消息才报错。三项分别验证，才能一次定位卡在哪一环。
• 多版本并存是终端工具的经典坑。 npm 全局装一份、脚本装一份、AUR 装一份，PATH 里谁在前就用谁。你升级了 A，运行的却是 B，表现为「明明更新了却没有新功能」。which opencode 就是用来照妖的。
• 安装方式决定升级方式。 不同安装源的文件位置、自更新逻辑完全不同；用脚本的 upgrade 去升级 npm 包，要么报错，要么再装出第二份。
• 先用测试项目验证是最低成本的保险。 在真实大项目里第一次试手，一旦配置有问题、误授权了操作，代价大；在无关紧要的目录里验证，错了也无所谓。

⑤ 这样做的好处

• 一次装好、链路清晰，不在第一天就被环境问题劝退。
• 版本唯一可控，升级时心里有数，不会遇到「幽灵旧版本」。
• 凭证问题前置发现，避免任务进行到一半才发现模型不可用。
• 建立验证仪式感：以后每次升级，都可以用这套四步流程快速回归测试。

⑥ 不这么做的问题 / 坏处

• 只验证命令存在 → 进了 TUI 发消息才报认证错误，手忙脚乱。
• 多版本混装 → 行为飘忽、升级无效，排查时连自己都不知道在运行哪个文件。
• 升级方式错配 → 装出第二份、报权限错误，甚至把配置搞乱。
• 直接在重要项目首航 → 对界面和权限都不熟时误批准写操作，可能污染代码。

⑦ 举一反三：三个例子

例 1（基础）：一次干净的安装验证

📌 场景：你刚通过官方脚本装完 OpenCode。

✅ 操作序列：

opencode --version        # 看到版本号 → 程序 OK
which opencode            # 记下实际路径，确认没有第二份
opencode auth login       # 配置模型供应商凭证（按引导完成）
cd ~/test-project && opencode
# TUI 内发送：请回复“链路正常”，不要执行任何操作

🔍 讲解：四步分别验证程序、路径、凭证、端到端链路，任何一步失败都能立刻知道问题归属，而不是把「安装 / 网络 / 凭证」搅成一团乱麻。注意测试消息刻意要求「不要执行任何操作」——验证阶段只验证对话，不引入任何文件变更。

例 2（进阶）：升级后行为不对，先查版本并存

📌 场景：你用 opencode upgrade 升级后，发现教程里说的新快捷键依然不存在。

✅ 排查：

opencode --version        # 实际运行的版本号是多少？
which -a opencode         # -a 列出 PATH 中所有同名命令

🔍 讲解：which -a 是排查多版本并存的利器。如果发现系统里有两份 opencode（比如一份在 /usr/bin、一份在 ~/.opencode/bin），解决办法是保留与你日常使用方式一致的那一份，卸载另一份，而不是继续猜「升级是不是失败了」。这比重装省事得多。

例 3（挑战）：在全新机器或 CI 环境中无人值守准备

📌 场景：你要在一台新服务器（或 CI 容器）上快速准备好 OpenCode，全程没有交互界面。

✅ 思路：用脚本方式安装；通过环境变量注入模型凭证（如对应供应商的 API Key 环境变量）；安装后用 opencode --version 和一条非交互指令做冒烟测试。具体环境变量名与非交互参数以官方文档为准。

🔍 讲解：交互式 auth login 在无人值守环境中不可行，此时应走「环境变量注入凭证」通道——这也是第 6、8 章会反复出现的原则：本地用交互配置省心，自动化环境用环境变量可控。冒烟测试的意义在于：CI 里等到真实任务失败才发现环境没配好，浪费的是整条流水线的时间。

---

⑧ 练习题 ×2

练习 1（巩固型）

📝 题目：安装完成后，下面哪种验收方式是合格的？请说明理由。 （a）opencode --version 有输出就算完成； （b）which opencode 有路径就算完成； （c）发出一条测试消息并收到模型回复，才算完成。

💡 思路提示：回到「三项验证」：程序、凭证、端到端链路。

✅ 参考答案：

合格的是 (c)。(a) 只证明程序文件存在，(b) 只证明 PATH 配置正确；
两者都无法验证模型凭证与网络链路。只有真实发出消息并收到回复，
才证明「程序 → 网络 → 模型」整条链路可用。

🔍 讲解：这道题防的是安装环节最常见的自欺：终端有反应 ≠ 系统能用。养成「端到端验证」的习惯，后面配置 MCP、配置新供应商时同样适用。

练习 2（迁移型）

📝 题目：迁移到其它命令行工具（如 Git、Node、Docker）：为什么「多版本并存」是通用大坑？请各举一个你遇到或听说过的例子。

💡 思路提示：想想系统包管理器装一份、手动编译装一份、语言自身包管理器再装一份的情形。

✅ 参考答案（示例）：

- Node：系统包管理器装了旧版 Node，又用 nvm 装了新版，
  终端里 node 是新版，cron / 脚本里调用的却是旧版，行为不一致。
- Python：系统 python3 与 pyenv/conda 的 Python 并存，
  pip 装包装到了一个解释器，运行时用的是另一个，报 ModuleNotFoundError。
- Git：发行版自带 git 与自编译新版并存，新特性命令时灵时不灵。
共性：PATH 解析决定「实际运行哪份」，人却以为自己用的是刚升级的那份。

知识点 4：如何使用这套教程

① 定位

最后一个知识点是元知识：关于学习本身的方法。 工具类教程最大的浪费是「读完很爽，两周后原样归还」。本知识点给出一套经过验证的使用方法，让你投入的时间真正变成能力。

② 是什么（What）

本教程的最小单元是「知识点」，每个知识点严格按八模块结构展开：

1. 定位：它解决什么问题、在体系中处于什么位置；
2. 是什么：概念、术语、误解澄清；
3. 怎么做：步骤、写法、最小可用示例；
4. 为什么：背后的原理与因果链；
5. 好处：做对了能得到什么；
6. 坏处：不做或做错会失去什么；
7. 举一反三：基础 / 进阶 / 挑战三个例子（场景 → 答案 → 讲解）；
8. 练习题 ×2：巩固型 + 迁移型，答案紧跟题目（提示 → 参考答案 → 讲解）。

这个结构不是形式主义，它对应学习的四个层次：知道是什么（①②）→ 会动手（③）→ 理解为什么（④⑤⑥）→ 能迁移（⑦⑧）。只看不练，到第二层次就停了。

③ 怎么做（How）

推荐学习法（按你属于哪类读者选用）：

• 新手路线：按章节顺序，第 0 → 1（上、下）→ 2 → 3 章覆盖 90% 日常使用；每个知识点读完立刻在真实小任务里用一次，再继续。
• 在用路线：直接精读第 1 章打磨 Prompt，再用第 4、5 章做规则沉淀与定制；其余章节按需查阅。
• 查阅用法：把附录的快捷键表、命令表、模板库当字典，用时即查。

④ 为什么这么做（Why）

• 技能靠「提取练习」形成，不靠「反复阅读」。 认知科学中的测试效应表明：从大脑中主动调取知识（做题、实操）比被动重读的记忆保持率高得多。这就是为什么练习题是教程的一部分而非附录点缀。
• 「即时使用」是最强的记忆锚点。 看完一个知识点马上在真实任务中用一次，知识就和具体场景绑定；只在脑子里过，三天后只剩「好像看过」。
• 迁移能力才是真正学会的标志。 只会照搬教程例子，换个项目就失灵；「迁移型练习」刻意训练你剥离场景表象、看到底层结构——这是从「会用工具」到「会协作」的分水岭。
• 理解「为什么」能救场。 当你遇到教程没覆盖的情况，记住的步骤会失效，理解的原理可以让你现场推导。知其然处理已知，知其所以然处理未知。
• 顺序学习保护认知负荷。 新手跳过基础直接看高级章节，会因为前置概念缺失而处处卡壳；按体系走，每个新知识点都挂在已有的认知树上。

⑤ 这样做的好处

• 学一个会一个，教程读完之日就是能力到手之时。
• 能应对没见过的情况：靠原理推导，而不是等教程更新。
• 练习形成直觉：初期刻意列四要素，熟练后张口即来，基本功内化为本能。
• 可教别人：你能把「为什么」讲清楚时，说明知识真正长在了自己身上。
• 投入产出比高：同样的阅读时间，按这套方法走，留存率数倍于随手翻阅。

⑥ 不这么做的问题 / 坏处

• 只看不动手 → 产生「都懂了」的幻觉，真机一用全卡壳。
• 先看答案再做题 → 练习变成阅读，提取能力从未被训练。
• 只记步骤不问原理 → 界面一改版、场景一变化，知识瞬间作废。
• 跳读高级章节 → 基础概念悬空，越学越觉得「玄」，最终放弃。
• 不做迁移练习 → 只会在教程设定的场景里照抄，换个领域寸步难行。

⑦ 举一反三：三个例子

例 1（基础）：学完「四要素」立刻用

📌 场景：你刚读完第 1 章的核心四要素。

✅ 做法：不要接着读下一章。马上打开手头一个真实小任务（哪怕是「给这个函数改个参数」），先在草稿里列「背景 / 任务 / 约束 / 标准」四行，再发给 AI，对比它的产出和以前随口一问的差别。

🔍 讲解：这就是「即时使用」原则。对比带来的体感（返工少了、追问少了）是任何文字都给不了的正反馈——让你自己尝到甜头，比任何学习号召都有效。一次成功体验，就足以把方法固化成习惯。

例 2（进阶）：用「先写后对」做练习题

📌 场景：你在做某章节的巩固练习，心里痒，想直接看参考答案。

✅ 做法：忍住。哪怕只写出三行、写得很烂，也先写；写完再对答案，重点看自己漏了什么、为什么漏，而不是看答案写得多好。

🔍 讲解：练习的价值不在「得到好答案」，而在「暴露你的思维缺口」。先写，缺口才会暴露；直接看答案，缺口被完美的参考回答盖住了，你永远不知道自己不会什么。做错的题比做对的题值钱，前提是你真的做了。

例 3（挑战）：用迁移练习检验是否真懂

📌 场景：你做完了 Prompt 章节所有巩固练习，自我感觉良好。

✅ 做法：认真做每章的「迁移型练习」——会议纪要、简历筛选、活动策划这些非编程场景。如果迁移题你也能做对，说明掌握的是底层结构；如果迁移题卡住了，说明你掌握的只是编程场景的套路。

🔍 讲解：这是最诚实的能力体检。巩固题可以靠模仿例子蒙混，迁移题不行——它要求你抽象出「单一任务、防编造、可验证」这些跨场景原则。迁移成功的那一刻，知识才算真正完成了从「教程」到「你」的迁移。

---

⑧ 练习题 ×2

练习 1（巩固型）

📝 题目：请为你自己制定一份使用本教程的具体计划：每周学几个知识点、在什么真实任务中练习、用什么方式检验自己是否真的学会。

💡 思路提示：计划要具体到「时间 + 任务 + 检验标准」，避免「我会认真学」这类无法验收的计划。

✅ 参考答案：

示例计划：
- 节奏：每周学 2 个知识点，安排在周三、周日晚上各 40 分钟；
- 练习：每个知识点读完后，次日工作中找一个真实小任务立即使用；
- 检验：先独立完成章节练习题再对答案；连续两次迁移练习做对，
  才算该章过关；
- 复盘：每周末用 5 句话回顾本周学到的原则，讲不出来的重看。

🔍 讲解：计划的关键是可执行、可验收——这恰好就是本教程反复教你的 Prompt 原则：目标具体、约束明确、标准可验证。你给自己写学习计划，和给 AI 写 Prompt，用的是同一套思维。

练习 2（迁移型）

📝 题目：回顾你过去学过但「还给老师」的一项技能（乐器、外语、运动、软件皆可），用本章的四个学习层次分析：你当时停在了哪一层？如果重来，会怎么安排？

💡 思路提示：对照「知道是什么 → 会动手 → 懂为什么 → 能迁移」四层，定位当年的断点。

✅ 参考答案：

示例（学吉他）：
- 当时停在第 2 层「会动手」：照着谱能弹几首固定的歌，但不懂乐理，
  换首没练过的歌就不会，最终放弃。
- 断点分析：缺少第 3 层（为什么这样按弦、和弦如何构成），
  更没有第 4 层（迁移到陌生曲目、即兴）；只做重复阅读式练习，
  没有提取练习。
- 重来安排：学一个和弦立刻在新歌里用（即时使用）；
  每周练一首没见过的谱（迁移检验）；补乐理让自己能推导而非死记。

🔍 讲解：能分析自己的旧经验，说明你已把本章方法从「OpenCode 教程」中抽象出来——这本身就是一次成功的迁移。学习法不是新知识，是把你已经隐约知道的道理，第一次有结构地用在自己身上。

---

本章小结

知识点	一句话核心
1. OpenCode 与 TUI 是什么	能动手的 Agent + 键盘驱动的终端驾驶舱；你是决策者
2. V2 核心心智模型	会话提供上下文，AGENTS.md 沉淀规则，权限守住底线
3. 安装与环境验证	程序 / 凭证 / 端到端链路三项验证，按同一来源升级
4. 如何使用本教程	即时使用、先写后对、迁移检验，技能靠练习形成

准备工作完毕。从下一章起，我们进入全教程最重要的基本功：《Prompt 基本功（上）：核心认知》——学会把话说对，其余一切才有意义。