📚 摘要

本文分析 OpenCode Agents 指南，全面涵盖代理类型、配置模式以及 AI 辅助开发工作流的最佳实践。

🎯 核心概念

什么是 OpenCode Agents？

OpenCode 中的 Agents（代理）是具备特定配置的专业 AI 角色：

• 提示词（Prompts）：自定义指令和行为准则
• 工具（Tools）：文件访问、shell 命令等权限设置
• 模型（Models）：专用或共享的 AI 模型
• 温度（Temperature）：创造力与确定性设置（0.0-1.0）
• 详细程度（Verbosity）：响应的详细级别（低、中、高、详细）

代理类型

1. 主代理（Primary Agents）：主要通过 Tab 键切换的主要对话代理
2. 子代理（Subagents）：通过 @提及 方式调用的专业代理
3. 系统代理（System Agents）：用于压缩、标题生成等的隐藏代理

🤖 内置代理分析

核心主代理

代理	用途	工具权限	温度	主要特点
Build	实现和代码更改	完全访问（读、写、编辑、bash）	0.1	默认模式，确定性高
Plan	分析、规划、头脑风暴	有限访问（通常仅询问）	0.3	略微创造性，可 Tab 切换

专业子代理

代理	用途	工具权限	使用场景
General	复杂任务执行	完全访问	多步骤任务
Explore	代码库探索	只读访问	分析和解释

🔄 代理工作流模式

模式 1：规划 → 构建循环

最常见模式

1. 在 Plan 模式下开始分析和设计
2. 审查和优化规划
3. 切换到 Build 模式进行实现

模式 2：多代理协作

团队协作方法

• 使用 @提及 调用特定代理
• 示例：@explore 分析，@general 创建计划，Build 实现

模式 3：专业任务委派

专家代理模式

• 为特定任务创建自定义代理
• 示例：@code-reviewer、@test-writer、@documentation

🛠️ 代理配置方法

方法 1：Markdown 配置（推荐）

# ~/.config/opencode/agents/code-reviewer.md
name: Code Reviewer
description: 专业代码审查代理
model: claude-sonnet-4.6
temperature: 0.2
verbosity: high

## 指令
你是一个资深代码审查员...

## 工具
- read: true
- ask: true
- write: false
- edit: false
- bash: false

方法 2：JSON 配置

{
  "name": "Code Reviewer",
  "description": "专业代码审查代理",
  "model": "claude-sonnet-4.6",
  "temperature": 0.2,
  "tools": {
    "read": true,
    "ask": true,
    "write": false,
    "edit": false,
    "bash": false
  }
}

方法 3：项目特定代理

• 在项目根目录创建：.opencode/agents/
• 项目代理覆盖全局代理
• 支持团队特定配置

⚙️ 配置选项深度解析

工具权限矩阵

工具	用途	安全级别
read	读取文件	低风险
ask	提出澄清问题	无风险
write	创建新文件	中等风险
edit	编辑现有文件	中等风险
bash	执行 shell 命令	高风险
skill	特定技能	可配置

模型选择指南

任务类型	推荐模型	温度
代码分析	claude-sonnet-4.6	0.1-0.2
代码生成	gpt-5.2-codex	0.2-0.3
创意写作	gemini-2.5-pro	0.4-0.7
头脑风暴	任意	0.6-0.8

行为设置

• 温度：0.0（确定性）到 1.0（创造性）
• 详细程度：低、中、高、详细
• 最大令牌数：响应长度限制（例如 4000）
• 思考过程：显示/隐藏思考步骤

🔗 高级模式

1. 代理链模式

复杂项目的顺序工作流：

@explore → @architect → @implementer → @tester → @reviewer

2. 并行代理团队

跨不同方面的并发开发：

@frontend (UI) ↘
@backend (API) → 集成 → @documentation
@devops (部署) ↗

3. 条件代理路由

基于任务类型的智能路由：

• Bug 修复 → @debugger
• 新功能 → @implementer
• 文档 → @technical-writer
• 重构 → @refactor-specialist

📋 代理管理命令

命令	用途	示例
/agents	列出可用代理	/agents
/agents select	切换到特定代理	/agents select code-reviewer
/agents create	交互式代理创建	/agents create
/agents edit	编辑现有代理	/agents edit code-reviewer
/agents delete	删除代理	/agents delete old-agent

📝 预制代理示例

代码审查代理

专注：安全性、性能、可维护性
模型：claude-sonnet-4.6
温度：0.1
工具：仅读、询问

测试编写代理

专注：TDD、全面测试
模型：gpt-5.2-codex
温度：0.3
原则：AAA 模式、真实数据、高覆盖率

文档代理

专注：用户友好、全面文档
模型：gemini-2.5-pro
温度：0.4
风格：清晰、实用示例、视觉辅助

⚡ 性能优化

1. 模型选择策略

• 将代理用途与适当的模型能力匹配
• 考虑成本与性能权衡

2. 温度调节

• 0.1-0.3：代码分析、审查、重构
• 0.4-0.7：创意任务、头脑风暴、命名
• 0.8-1.0：实验性、高度创意工作

3. 工具限制安全

• 审查员：仅读、询问
• 实现者：读、写、编辑
• 管理员：完全访问包括 bash

4. 详细程度控制

• 调试：详细（显示所有推理）
• 生产：中等（平衡的详细程度）
• 自动化：低（最小输出）

🎯 最佳实践总结

1. 从简单开始

• 从基本代理开始（审查员、实现者）
• 逐步增加复杂性
• 彻底测试每个代理

2. 清晰的提示词

• 明确指定代理的角色
• 包含良好输出的示例
• 定义边界和限制

3. 安全第一

• 限制敏感代理的 bash 访问
• 为客户工作使用项目特定代理
• 定期审查代理权限

4. 性能监控

• 跟踪每个代理的令牌使用
• 监控响应时间
• 基于性能调整模型

5. 迭代改进

• 收集代理使用反馈
• 基于结果优化提示词
• 与团队分享成功的代理

🔧 常见使用场景

代码审查工作流

1. 创建包含更改的 PR
2. @code-reviewer 审查所有更改的文件
3. Build 代理修复已识别的问题
4. @test-writer 添加全面测试
5. 代码审查员最终验证

功能开发工作流

1. 规划阶段：@explore + @architect
2. 实现阶段：@frontend + @backend + @database
3. 测试阶段：@test-writer + @security-reviewer
4. 文档阶段：@documentation

Bug 修复工作流

1. 诊断：@debugger + @explore
2. 解决方案：@architect + @reviewer
3. 实现：Build 代理
4. 验证：@test-writer + @reviewer

🐛 故障排除指南

常见问题与解决方案

问题	解决方案
代理无响应	检查 /agents list 和 /models
权限不正确	使用 /agents show 和 /agents edit
响应质量差	调整温度或更换模型
上下文错误	在 @提及 中更具体

调试命令

• /thinking on - 查看代理推理过程
• !cat ~/.config/opencode/agents/agent-name.md - 检查配置
• @agent-name 2+2等于多少？ - 测试基本功能

📚 代理模板仓库

团队共享的推荐结构：

agents-templates/
├── code-review/
├── development/
├── testing/
└── documentation/

🔄 与其他 OpenCode 功能集成

• 技能指南：创建可重用工作流
• 工作流指南：设计开发工作流
• MCP 指南：使用外部服务器扩展

📊 关键要点

1. 代理专业化：不同任务使用不同代理提高质量和安全性
2. 工作流模式：Plan→Build 循环是基础，但高级模式支持复杂项目
3. 配置灵活性：多种配置方法支持不同团队偏好
4. 安全意识：工具限制和项目特定代理实现安全使用
5. 性能意识：模型选择和温度调节优化结果
6. 团队协作：代理模板和共享实现一致实践

🚀 实施建议

1. 从内置开始：首先掌握 Plan 和 Build 代理
2. 创建核心自定义代理：代码审查员、测试编写员、文档专家
3. 建立工作流：为团队定义标准模式
4. 监控和优化：跟踪使用情况并优化配置
5. 分享和标准化：创建团队代理模板仓库

附录

[1].https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/blob/main/docs/AGENTS-GUIDE.md