04-Agent 与 SubAgent 任务分发

掌握 OpenCode 的 Agent 和 SubAgent 功能，实现任务的并行处理和专业化分工，大幅提升开发效率。

---

一、Agent 概述

1.1 什么是 Agent

OpenCode 中有两种类型的 Agent：

• Primary Agents（主 Agent）：你直接交互的主要助手，处理你的主要对话
• Subagents（子 Agent）：专业助手，主 Agent 可以为特定任务自动调用它们，你也可以通过 @ 提及手动调用

主 Agent (Build/Plan)
    │
    ├─ 自动调用 SubAgent ──► @general (通用任务处理)
    │
    ├─ 自动调用 SubAgent ──► @explore (代码库探索)
    │
    └─ 手动调用 SubAgent ──► @your-custom-agent (自定义任务)

1.2 内置 Agent

Agent	类型	用途
Build	Primary	默认开发 Agent，拥有所有工具权限
Plan	Primary	规划和分析，不修改代码
General	Subagent	通用任务，可处理研究和多步骤任务
Explore	Subagent	快速只读探索代码库

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 命令

# 创建新的 Agent
opencode agent create

# 列出所有可用的 Agent
opencode agent list

opencode agent create 是一个交互式命令，会引导你：

1. 选择保存位置（全局或项目级）
2. 输入 Agent 描述
3. 生成合适的系统提示和标识符
4. 选择 Agent 可以访问的工具
5. 创建 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 创建 review Agent）。

3.3 常用配置选项

选项	说明	示例
description	Agent 描述（必填）	“审查代码安全”
mode	primary、subagent 或 all	subagent
model	指定使用的模型	anthropic/claude-sonnet-4-20250514
temperature	控制随机性 (0.0-1.0)	0.1
steps	最大执行步数	5
prompt	系统提示文件路径	{file:./prompts/review.txt}
color	UI 颜色	#ff6b6b 或 accent

---

四、并行任务处理

4.1 通过 SubAgent 实现并行

SubAgent 是实现并行工作的核心机制。当主 Agent 调用 SubAgent 时，会创建子会话（child session），这些子会话可以并行执行独立任务。

在 TUI 中的会话导航：

操作	快捷键	说明
进入第一个子会话	<Leader>+Down	从父会话进入第一个子会话
切换到下一个子会话	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

按提示操作：

1. 选择保存到 .opencode/agents/（项目级）
2. 描述：“专门负责 FastAPI 路由生成”
3. 选择工具权限
4. 生成 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）
• 创意/头脑风暴：使用较高 temperature（0.6-0.8）
• 代码审查：使用较低 temperature（0.1-0.2）

---

八、故障排除

8.1 查看和统计

# 查看所有可用 Agent
opencode agent list

# 查看会话统计信息
opencode stats

# 查看会话列表
opencode session list

8.2 调试技巧

• 使用 /details 切换工具执行详情显示，查看 SubAgent 的具体操作
• 使用 <Leader>+Down 进入子会话查看 SubAgent 的工作
• 使用 Up 返回父会话
• 使用 Right/Left 在不同的子会话间切换

8.3 常见问题

问题	解决方案
SubAgent 未被自动调用	检查 Agent 的 description 是否清晰
Agent 权限不足	检查 permission 配置
找不到自定义 Agent	确认文件放在 .opencode/agents/ 或 ~/.config/opencode/agents/
Agent 执行步数过多	设置 steps 限制最大步数

---

九、下一步

掌握 Agent 和 SubAgent 后，建议学习：

1. 05-Hooks自动化.md - 自动化工作流
2. 06-Skills复用.md - 创建可复用技能
3. 07-代码分析与重构.md - 批量代码处理

---