OpenCode 中文社区

Appearance

3.1 Plan vs Build：规划与执行 ​

💡 一句话总结：Plan Agent 只读分析，Build Agent 读写执行。按 Tab 切换。

学完你能做什么 ​

  • 理解 Plan 和 Build 两个 Primary Agents 的区别
  • 知道什么场景用 Plan，什么场景用 Build
  • 能熟练用 Tab 切换 Agent

核心思路 ​

Plan 和 Build 是什么 ​

Plan 和 Build 是 OpenCode 内置的两个 Primary Agents（主要助手）。

  • Primary Agent：你可以直接对话的主助手，用 Tab 切换
  • Subagent：由 Primary Agent 调用的专家助手，用 @ 提及

OpenCode 默认提供两个 Primary Agents：

Agent类型说明
BuildPrimary默认助手，所有工具可用，适合开发工作
PlanPrimary受限助手，权限询问，适合分析和规划

权限系统 ​

Plan Agent 使用权限询问机制保护你的代码：

权限Plan AgentBuild Agent
edit（写/改文件）ask（询问）allow
bash（执行命令）ask（询问）allow
read、grep、glob 等allowallow

ask 模式：在 Agent 尝试执行操作前提示你确认，可以选择：

  • allow：允许这次操作
  • deny：拒绝这次操作
  • allow all：本次会话允许所有此类操作

什么时候用 Plan ​

  • 分析代码结构，但不要改动
  • 让 AI 做规划和设计
  • 代码审查
  • 理解陌生代码库

什么时候用 Build ​

  • 让 AI 写新功能
  • 让 AI 修 Bug
  • 让 AI 重构代码
  • 让 AI 创建/修改文件

可用工具 ​

只读工具（Plan 和 Build 都可用） ​

工具说明
read读取文件内容
grep搜索文件内容
glob按模式查找文件
list列出目录内容
webfetch获取网页内容

读写工具（仅 Build 默认可用） ​

工具说明
write创建新文件
edit修改现有文件
bash执行 Shell 命令

跟我做 ​

第 1 步：确认当前 Agent ​

看状态栏右侧，会显示 Plan 或 Build。

第 2 步：切换到 Plan Agent ​

按 Tab 键，直到状态栏显示 Plan。

第 3 步：用 Plan Agent 分析代码 ​

输入：

@src/main.ts 分析这个文件的结构，列出所有函数和它们的作用

你应该看到：AI 使用 read 工具读取文件，分析结构。由于 Plan Agent 的 edit 权限是 ask，AI 不会直接修改文件。

第 4 步：切换到 Build Agent ​

按 Tab 键，状态栏显示 Build。

第 5 步：用 Build Agent 重构代码 ​

输入：

给 @src/main.ts 添加详细的 JSDoc 注释

你应该看到：AI 使用 edit 工具修改文件，添加注释。

第 6 步：撤销更改（如需要） ​

如果不满意，可以撤销：

/undo

检查点 ​

✅ 全部通过才能继续：

  • [ ] Tab 能在 Plan Agent 和 Build Agent 之间切换
  • [ ] Plan Agent 默认 ask 权限，写文件/执行命令前会提示确认
  • [ ] Build Agent 默认 allow 权限，可以自由修改文件和执行命令

踩坑提醒 ​

现象原因解决
想让 AI 改文件但没改可能在 Plan Agent按 Tab 切换到 Build
AI 改了不该改的文件在 Build Agent用 /undo 撤销，下次用 Plan 先分析

下一课预告 ​

下一课我们将 3.2 认识 Agent，学会调用不同专家完成任务。

微信群