叶云梦天

OpenCode Plan 模式与 Build 模式完全指南：用 Tab 键掌握 AI 编程的最佳节奏

引言

如果你用过 AI 编程助手，一定遇到过这样的场景：话还没说完，AI 就已经开始改文件了，而且改得不对。你不得不手忙脚乱地 git checkout 回退，然后重新组织语言再次尝试。这种"先开枪再瞄准"的交互方式，不仅浪费时间，更消耗信任。

OpenCode 的设计者显然深谙此痛点。从第一天起，它就提供了 Plan 模式和 Build 模式的双模式切换机制——按下 Tab 键，你就能在"架构师"和"工程师"两种身份之间自由切换。这篇文章将深入解析这两种模式的原理、配置和实战技巧，帮助你建立一套安全高效的 AI 编程工作流。

Plan 与 Build：两种模式，两种角色

Build 模式（默认）

Build 模式是 OpenCode 启动后的默认状态，它拥有完整的读写权限：

读取文件（read）
全局搜索代码（grep）
文件匹配查找（glob）
编辑修改文件（edit, write）
执行 Shell 命令（bash）

在 Build 模式下，AI 可以像一名开发者一样直接动手写代码、运行测试、安装依赖。这是实际开发工作的核心模式。

Plan 模式

按下 Tab 键切换到 Plan 模式后，OpenCode 的行为发生了根本性变化：

| 权限 | Plan 模式 | Build 模式 |
|------|----------|-----------|
| read / grep / glob | 允许 | 允许 |
| edit / write（项目源文件） | 禁止 | 允许 |
| edit（.opencode/plans/*.md） | 允许 | 允许 |
| bash | 允许 | 允许 |

Plan 模式的核心特征是禁止编辑项目源文件——它只能读取和分析代码，然后以文本形式输出分析和计划。唯一例外是它可以写入 .opencode/plans/ 目录下的计划文件。

这种权限隔离意味着：在 Plan 模式下，你可以放心让 AI 尽情探索代码库，它绝不会动你的任何一行源码。

Tab 键背后的切换机制

状态指示器

切换 Plan/Build 模式后，注意观察 TUI 界面右下角的状态栏——它会实时显示当前模式：

Build   ← 默认状态，可读写
Plan    ← 按 Tab 后，只读分析

快捷键

| 操作 | 默认快捷键 |
|------|-----------|
| 切换到下一个 Agent | Tab |
| 切换到上一个 Agent | Shift+Tab |

你可以在配置文件中自定义这些快捷键：

// opencode.jsonc
{
  "keybinds": {
    "agent_cycle": "tab",
    "agent_cycle_reverse": "shift+tab"
  }
}

多 Agent 循环

如果你在项目中定义了多个主 Agent（Primary Agent），Tab 键会在所有主 Agent 之间循环切换。例如，如果你同时定义了 build、plan 和一个自定义的 code-reviewer Agent（mode: "primary"），Tab 会依次遍历它们。你可以通过设置 mode: "subagent" 将非核心 Agent 从 Tab 循环中排除。

实战工作流：Plan → 迭代 → Build

第一步：在 Plan 模式下分析需求

假设你需要在项目中添加一个"软删除"功能。先按 Tab 切换到 Plan 模式，然后描述你的需求：

当用户删除一条笔记时，标记为已删除而不是物理删除。
同时创建一个回收站页面，用户可以查看已删除的笔记，
选择恢复或永久删除。

AI 将在只读模式下分析项目结构，探索相关文件：

定位到 Note 模型和相关数据库迁移文件
查找现有的删除逻辑和 API 端点
分析前端页面结构和路由

然后输出一份详细的实现计划，包括需要修改的文件清单、新增的数据库字段、API 端点变更和前端组件的设计方案。

第二步：迭代优化计划

这是 Plan 模式最大的价值所在。拿到初步计划后，你可以持续对话迭代，而不用担心任何文件被误改：

数据库标记字段用 deleted_at 而不是 is_deleted，
这样我们可以同时记录删除时间。
另外，恢复操作需要加上乐观锁防止并发冲突。

AI 会基于你的反馈更新计划，并将完整的方案写入 .opencode/plans/ 目录下的 Markdown 文件。

第三步：切换到 Build 模式执行

当计划符合预期后，再按一下 Tab 切换到 Build 模式：

计划看起来没问题，开始实现吧。

AI 将根据之前讨论的方案实际修改代码、创建文件、运行迁移命令。由于前期已经在 Plan 模式下充分对齐了需求，执行阶段的偏差会大大降低。

第四步：不满意就撤销

如果 Build 阶段的输出不尽如人意，随时使用 /undo 回退：

/undo

OpenCode 依赖 Git 快照来跟踪每次修改，/undo 会将文件恢复到上一个 checkpoint，同时回退对话状态。如果反悔了，还可以用 /redo 恢复回来。这个安全网让你可以大胆尝试不同的实现方案。

深入配置：为每种模式定制行为

Plan 和 Build 模式的默认行为已经足够日常使用，但如果你有更高要求，可以在 opencode.jsonc 中为每种模式独立配置模型、温度和权限。

基础配置示例

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.1,
      "permission": {
        "edit": {
          "*": "deny",
          ".opencode/plans/*.md": "allow"
        },
        "bash": "allow"
      }
    }
  }
}

配置要点

temperature（温度）：Plan 模式建议使用较低的温度（如 0.1），让输出更加集中和确定性；Build 模式可以适当提高（如 0.3），在执行层面保持一定的灵活度。

model（模型）：你可以为 Plan 模式指定一个推理能力更强的模型来做架构分析，Build 模式则可以选择速度快、成本低的模型来执行具体的编码任务。两套模型互不干扰。

permission（权限）：Plan 模式的核心是 "*": "deny" 加 .opencode/plans/*.md: "allow" 的组合，确保 AI 无法修改源码但可以输出计划文档。Build 模式则放开编辑权限。

steps（最大步数）：可以通过 steps 字段限制 AI 的工具调用次数，防止失控：

{
  "agent": {
    "plan": {
      "steps": 10
    }
  }
}

Markdown 格式的 Agent 定义

除了 JSON，你还可以用 Markdown 文件定义 Agent，放在 .opencode/agents/ 或 ~/.config/opencode/agents/ 目录下：

---
mode: primary
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
---

你是一名资深架构师。你的职责是：
1. 深入分析代码库结构
2. 提出可落地的实现方案
3. 输出清晰的计划文档

你绝对不能修改项目的任何源文件。
只能在 .opencode/plans/ 目录下创建计划文件。

进阶技巧

计划文件的存储位置

Plan 模式下生成的计划会自动保存为 Markdown 文件：

项目使用 Git → 保存到 .opencode/plans/<时间戳>-<标题>.md
项目未使用 Git → 保存到 ~/.local/share/opencode/plans/<时间戳>-<标题>.md

你可以随时查看和回顾这些计划文件，也可以将它们提交到 Git 仓库中作为项目文档的一部分：

ls .opencode/plans/
# 1736854321-soft-delete-feature.md
# 1736855000-refactor-auth-flow.md

cat .opencode/plans/1736854321-soft-delete-feature.md

实验性功能：AI 自动切换模式

手动按 Tab 是常规做法，但 OpenCode 还提供了实验性的 plan_enter 和 plan_exit 工具，允许 AI 自己决定何时切换模式。启用方式：

export OPENCODE_EXPERIMENTAL=true
# 或者只开启 Plan 模式相关实验
export OPENCODE_EXPERIMENTAL_PLAN_MODE=true

启用后，以下场景将成为可能：

用户：这个模块需要重构，先帮我分析一下，不要直接改
AI：[调用 plan_enter 工具]
    → 弹出确认框：切换到 Plan 模式？
    → 用户确认
    → AI 在 Plan 模式分析代码，生成计划文件
用户：计划没问题，开始实施
AI：[调用 plan_exit 工具]
    → 切换到 Build 模式，执行修改

这个功能让模式切换更加自动化，但需要手动确认，安全性不会降低。

TODO 任务追踪

在 Plan 模式下，你可以要求 AI 使用 TODO 系统来追踪复杂的多步骤任务：

分析用户认证模块的重构方案，用 TODO 追踪每个步骤的进度

AI 会创建结构化的任务列表，在分析和实施过程中实时更新状态（pending → in_progress → completed），让你对整体进度一目了然。

Plan 模式与代码审查

Plan 模式不仅适用于新功能的规划阶段，在代码审查场景中同样出色。切换到 Plan 模式后，让 AI 分析某个 PR 的代码变更：

检查 src/services/auth.ts 中的安全漏洞和潜在问题

在只读模式下，AI 会专注分析而不做任何修改，相当于内置了一位免费的代码审查员。

最佳实践总结

复杂功能一律先 Plan 后 Build：让 AI 先在只读模式下充分理解需求和代码结构，切换到 Build 后再动手实施。这个习惯能减少 80% 以上的无效修改。

在 Plan 阶段充分迭代：Plan 模式下改计划零成本，利用这个优势反复讨论和细化方案，直到你真正满意为止。

利用 /undo 作为安全网：哪怕 Build 阶段出了问题，/undo 能让你快速回到上一个 checkpoint。结合 Plan 模式的预演，实际上形成了"Plan → Build → /undo → Plan → Build"的安全循环。

为不同模式配置不同模型：Plan 阶段用推理能力强的模型做分析，Build 阶段用速度快、成本低的模型做执行，兼顾效果和效率。

把计划文件纳入版本控制：.opencode/plans/ 下的 Markdown 文件是团队共享上下文的好载体，提交到仓库后，其他成员也能了解设计决策的来龙去脉。

小块任务，多次迭代：与其给 AI 一个涵盖全项目的超大需求，不如拆成一个个可以在 Plan 模式中独立验证的小任务。小任务更容易撤销，也更容易在 Build 阶段一次性做对。

结语

Plan 模式与 Build 模式的分离，是 OpenCode 在 AI 编程工具中做出的一个关键设计决策。它不是简单地在提示词前面加一句"先思考再动手"——而是通过权限隔离从机制层面确保了"分析时不动代码，执行时效率最大化"。

掌握 Tab 键的切换节奏，就等于掌握了与 AI 协作的主动权。下次打开 OpenCode 时，试试这个流程：Tab → 描述需求 → 迭代计划 → Tab → 开始实施。你会发现，AI 编程不再是一场赌博，而是一次有节奏的合作。

OpenCode Plan 模式与 Build 模式完全指南：用 Tab 键掌握 AI 编程的最佳节奏

OpenCode Plan 模式与 Build 模式完全指南：用 Tab 键掌握 AI 编程的最佳节奏

引言

Plan 与 Build：两种模式，两种角色

Build 模式（默认）

Plan 模式

Tab 键背后的切换机制

状态指示器

快捷键

多 Agent 循环

实战工作流：Plan → 迭代 → Build

第一步：在 Plan 模式下分析需求

第二步：迭代优化计划

第三步：切换到 Build 模式执行

第四步：不满意就撤销

深入配置：为每种模式定制行为

基础配置示例

配置要点

Markdown 格式的 Agent 定义

进阶技巧

计划文件的存储位置

实验性功能：AI 自动切换模式

TODO 任务追踪

Plan 模式与代码审查

最佳实践总结

结语

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客