04-opencode Agent 与 SubAgent 任务分发

04-Agent 与 SubAgent 任务分发掌握 OpenCode 的 Agent 和 SubAgent 功能实现任务的并行处理和专业化分工大幅提升开发效率。一、Agent 概述1.1 什么是 AgentOpenCode 中有两种类型的 AgentPrimary Agents主 Agent你直接交互的主要助手处理你的主要对话Subagents子 Agent专业助手主 Agent 可以为特定任务自动调用它们你也可以通过提及手动调用主 Agent (Build/Plan) │ ├─ 自动调用 SubAgent ──► general (通用任务处理) │ ├─ 自动调用 SubAgent ──► explore (代码库探索) │ └─ 手动调用 SubAgent ──► your-custom-agent (自定义任务)1.2 内置 AgentAgent类型用途BuildPrimary默认开发 Agent拥有所有工具权限PlanPrimary规划和分析不修改代码GeneralSubagent通用任务可处理研究和多步骤任务ExploreSubagent快速只读探索代码库1.3 适用场景场景说明并行代码生成使用general同时处理多个独立任务代码审查创建专门的审查 Agent只读访问代码库探索使用explore快速了解项目结构规划分析使用 Plan Agent 进行分析而不修改代码文档编写创建专门的文档 Agent二、基本用法2.1 切换主 Agent在 TUI 中使用Tab键在主 Agent 之间切换按 Tab 键: Build → Plan → Build → ...也可以使用配置的switch_agent快捷键。2.2 调用 SubAgent手动调用在消息中使用提及general 帮我搜索这个函数的用法 explore 找出项目中所有使用数据库连接的地方自动调用主 Agent 会根据任务描述自动调用合适的 SubAgent。例如当你要求 Build Agent 搜索项目中所有 API 端点时它可能会自动调用explore来执行只读搜索。2.3 管理 Agent 的 CLI 命令# 创建新的 Agentopencode agent create# 列出所有可用的 Agentopencode agent listopencode agent create是一个交互式命令会引导你选择保存位置全局或项目级输入 Agent 描述生成合适的系统提示和标识符选择 Agent 可以访问的工具创建 Agent 的 Markdown 配置文件三、Agent 配置3.1 JSON 配置在opencode.json中配置 Agent{$schema:https://opencode.ai/config.json,agent:{build:{mode:primary,model:anthropic/claude-sonnet-4-20250514,prompt:{file:./prompts/build.txt}},plan:{mode:primary,model:anthropic/claude-haiku-4-20250514},code-reviewer:{description:审查代码的最佳实践和潜在问题,mode:subagent,model:anthropic/claude-sonnet-4-20250514,prompt:你是一个代码审查员。关注安全性、性能和可维护性。}}}3.2 Markdown 配置在项目目录.opencode/agents/或全局目录~/.config/opencode/agents/中创建 Markdown 文件.opencode/agents/review.md--- description: 审查代码质量和最佳实践 mode: subagent model: anthropic/claude-sonnet-4-20250514 temperature: 0.1 tools: write: false edit: false bash: false --- 你是一个代码审查助手。专注于 - 代码质量和最佳实践 - 潜在的 bug 和边界情况 - 性能影响 - 安全性考虑 只提供建设性反馈不直接修改代码。文件名即为 Agent 名称如review.md创建reviewAgent。3.3 常用配置选项选项说明示例descriptionAgent 描述必填“审查代码安全”modeprimary、subagent或allsubagentmodel指定使用的模型anthropic/claude-sonnet-4-20250514temperature控制随机性 (0.0-1.0)0.1steps最大执行步数5prompt系统提示文件路径{file:./prompts/review.txt}colorUI 颜色#ff6b6b或accent四、并行任务处理4.1 通过 SubAgent 实现并行SubAgent 是实现并行工作的核心机制。当主 Agent 调用 SubAgent 时会创建子会话child session这些子会话可以并行执行独立任务。在 TUI 中的会话导航操作快捷键说明进入第一个子会话LeaderDown从父会话进入第一个子会话切换到下一个子会话Right在子会话间循环切换到上一个子会话Left反向循环子会话返回父会话Up回到主会话4.2 并行代码生成示例向 Build Agent 发出包含多个独立任务的请求请并行处理以下模型的创建 1. 创建 User 模型 (app/models/user.py) - 字段: id, username, email, password_hash, is_active - 关系: posts (一对多) 2. 创建 Post 模型 (app/models/post.py) - 字段: id, title, content, user_id, created_at - 关系: user (多对一), comments (一对多) 3. 创建 Comment 模型 (app/models/comment.py) - 字段: id, content, user_id, post_id, created_at - 关系: user (多对一), post (多对一)主 Agent 会自动将这些任务分发给 SubAgent 并行处理。4.3 并行代码审查示例创建一个专门的审查 Agent 后code-reviewer 请审查以下模块 1. Models 模块 - 检查 SQLAlchemy 使用规范和关系定义 2. Routers 模块 - 检查错误处理和权限控制 3. Services 模块 - 检查业务逻辑和性能问题4.4 并行探索代码库explore 帮我了解项目结构 1. 找出所有的 API 端点 2. 找出数据库模型定义 3. 找出配置文件五、权限控制5.1 Agent 权限配置可以为每个 Agent 配置精细的权限{agent:{build:{permission:{edit:ask,bash:{git *:ask,git status *:allow,*:ask}}},readonly-reviewer:{permission:{edit:deny,bash:deny,webfetch:deny}}}}权限级别allow- 允许所有操作无需确认ask- 执行前请求确认deny- 禁用该工具5.2 Task 权限控制控制主 Agent 可以调用哪些 SubAgent{agent:{orchestrator:{mode:primary,permission:{task:{*:deny,orchestrator-*:allow,code-reviewer:ask}}}}}注意用户始终可以通过自动完成菜单直接调用任何 SubAgent即使 task 权限设置为 deny。六、实战示例6.1 创建项目专用 Agent使用 CLI 创建opencode agent create按提示操作选择保存到.opencode/agents/项目级描述“专门负责 FastAPI 路由生成”选择工具权限生成fastapi-router-generator.md或者手动创建.opencode/agents/fastapi-router-generator.md--- description: 为 FastAPI 项目生成路由和端点 mode: subagent model: anthropic/claude-sonnet-4-20250514 --- 你是一个 FastAPI 路由生成专家。根据模型定义自动生成 - CRUD 端点 - 请求验证 - 错误处理 - 分页和搜索6.2 多语言文档生成请为项目生成多语言文档 1. 英文文档 (docs/en/) - README.md - API.md - Deployment.md 2. 中文文档 (docs/zh/) - README.md - API.md - Deployment.md 3. 日文文档 (docs/ja/) - README.md - API.md - Deployment.md主 Agent 会将这些任务分发给 SubAgent 并行处理。6.3 完整项目开发流程# 1. 使用 Plan Agent 进行规划分析 切换到 Plan Agent按 Tab 请分析当前项目结构给出开发计划。 # 2. 切换回 Build Agent 开始开发 按 Tab 切换回 Build 根据计划开始实现以下功能 - 创建用户认证模块 - 创建数据模型 - 创建 API 路由 # 3. 在开发过程中Build Agent 会自动调用 # - explore 来探索代码结构 # - general 来处理通用任务 # 4. 使用自定义的审查 Agent 进行代码审查 code-reviewer 请审查刚创建的代码七、最佳实践7.1 Agent 设计原则职责单一每个 Agent 专注于特定领域描述清晰提供准确的 description帮助主 Agent 决定何时调用权限最小化只授予必要的工具权限7.2 并行任务拆分好的拆分任务独立 - 创建 User 模型 - 创建 Post 模型 - 创建 Comment 模型 不好的拆分任务耦合 - 创建 User 模型 - 创建依赖 User 的 Post 模型有依赖关系对于有依赖关系的任务应在一个请求中说明依赖关系让主 Agent 按正确顺序处理。7.3 模型选择分析/规划任务使用更快、更便宜的模型如 Haiku代码生成任务使用更强大的模型如 Sonnet创意/头脑风暴使用较高 temperature0.6-0.8代码审查使用较低 temperature0.1-0.2八、故障排除8.1 查看和统计# 查看所有可用 Agentopencode agent list# 查看会话统计信息opencode stats# 查看会话列表opencode session list8.2 调试技巧使用/details切换工具执行详情显示查看 SubAgent 的具体操作使用LeaderDown进入子会话查看 SubAgent 的工作使用Up返回父会话使用Right/Left在不同的子会话间切换8.3 常见问题问题解决方案SubAgent 未被自动调用检查 Agent 的 description 是否清晰Agent 权限不足检查permission配置找不到自定义 Agent确认文件放在.opencode/agents/或~/.config/opencode/agents/Agent 执行步数过多设置steps限制最大步数九、下一步掌握 Agent 和 SubAgent 后建议学习05-Hooks自动化.md - 自动化工作流06-Skills复用.md - 创建可复用技能07-代码分析与重构.md - 批量代码处理