15.3 多 Agent 体系

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

oh-my-opencode 最核心的创新在于它的多 Agent 编排系统。它不是简单地配置一个更强的 Agent，而是定义了一个由多个角色化 Agent 组成的"团队"，通过主 Agent 的意图分类和委托决策，将不同类型的任务分配给最适合的专家 Agent。

15.3.1 Agent 分类与角色设计

oh-my-opencode 定义了 11 个内置 Agent，每个 Agent 都有明确的角色定位、工作模式和成本级别：

Agent	角色定位	模式	成本	类别
Sisyphus	主 Agent / 编排者	primary	EXPENSIVE	utility
Oracle	高级技术顾问（只读）	subagent	EXPENSIVE	advisor
Explore	代码库搜索专家	subagent	FREE	exploration
Librarian	外部资源搜索员	subagent	CHEAP	exploration
Prometheus	任务规划器	subagent	EXPENSIVE	specialist
Metis	预规划分析师	subagent	EXPENSIVE	advisor
Momus	方案评审专家	subagent	EXPENSIVE	advisor
Hephaestus	自主工匠执行者	primary	EXPENSIVE	utility
Atlas	项目导航器	primary	EXPENSIVE	utility
Sisyphus Junior	轻量级任务执行	subagent	CHEAP	utility
Multimodal Looker	多模态分析	subagent	CHEAP	specialist

Agent 类型系统

每个 Agent 通过 TypeScript 类型系统定义了关键属性：

// oh-my-opencode/src/agents/types.ts

/**
 * Agent 模式决定了 UI 模型选择行为：
 * - "primary": 尊重用户在 UI 中选择的模型（如 Sisyphus、Atlas）
 * - "subagent": 使用自己的回退链，忽略 UI 选择（如 Oracle、Explore）
 * - "all": 在两种上下文中都可用（OpenCode 兼容性）
 */
export type AgentMode = "primary" | "subagent" | "all"

/**
 * Agent 类别，用于在 Sisyphus Prompt 中分组展示
 */
export type AgentCategory = "exploration" | "specialist" | "advisor" | "utility"

/**
 * 成本分类，用于工具选择表
 */
export type AgentCost = "FREE" | "CHEAP" | "EXPENSIVE"

这里有一个重要的设计决策：模式（Mode） 区分了 Agent 如何获取模型。primary 模式的 Agent（如 Sisyphus）使用用户在 UI 中手动选择的模型——这意味着用户可以自由切换 Sisyphus 使用 Claude Opus 还是 GPT-5。而 subagent 模式的 Agent（如 Oracle、Explore）使用预定义的模型，不受 UI 选择影响——这确保了子 Agent 始终使用最适合其角色的模型。

Agent 工厂模式

Agent 的创建采用工厂函数模式。每个 Agent 文件导出一个工厂函数，接收模型名称作为参数，返回 AgentConfig 对象：

// oh-my-opencode/src/agents/types.ts
export type AgentFactory = ((model: string) => AgentConfig) & {
  mode: AgentMode  // 模式作为静态属性附加在函数上
}

所有内置 Agent 的工厂函数被集中注册在 builtin-agents.ts：

// oh-my-opencode/src/agents/builtin-agents.ts
const agentSources: Record<BuiltinAgentName, AgentSource> = {
  sisyphus: createSisyphusAgent,
  hephaestus: createHephaestusAgent,
  oracle: createOracleAgent,
  librarian: createLibrarianAgent,
  explore: createExploreAgent,
  "multimodal-looker": createMultimodalLookerAgent,
  metis: createMetisAgent,
  momus: createMomusAgent,
  atlas: createAtlasAgent,
}

Agent Prompt 元数据

oh-my-opencode 的一个独特设计是 Agent Prompt 元数据（AgentPromptMetadata）。每个 Agent 不仅定义了自己的行为 Prompt，还声明了一组结构化的元数据，描述自己"应该在什么场景下被调用"：

// oh-my-opencode/src/agents/types.ts
export interface AgentPromptMetadata {
  category: AgentCategory          // 分组类别
  cost: AgentCost                  // 成本级别
  triggers: DelegationTrigger[]    // 委托触发条件
  useWhen?: string[]               // 适用场景
  avoidWhen?: string[]             // 不适用场景
  dedicatedSection?: string        // 专用 Prompt 段
  promptAlias?: string             // Prompt 中的别名
  keyTrigger?: string              // Phase 0 关键触发条件
}

例如，Oracle 的元数据声明了它应该被用于架构决策和困难调试：

// oh-my-opencode/src/agents/oracle.ts
export const ORACLE_PROMPT_METADATA: AgentPromptMetadata = {
  category: "advisor",
  cost: "EXPENSIVE",
  promptAlias: "Oracle",
  triggers: [
    { domain: "Architecture decisions", trigger: "Multi-system tradeoffs, unfamiliar patterns" },
    { domain: "Self-review", trigger: "After completing significant implementation" },
    { domain: "Hard debugging", trigger: "After 2+ failed fix attempts" },
  ],
  useWhen: [
    "Complex architecture design",
    "After completing significant work",
    "2+ failed fix attempts",
    "Security/performance concerns",
  ],
  avoidWhen: [
    "Simple file operations (use direct tools)",
    "First attempt at any fix (try yourself first)",
    "Questions answerable from code you've read",
  ],
}

这些元数据的消费者不是人类开发者，而是 Sisyphus 主 Agent。Sisyphus 的 Prompt 会动态拼接这些元数据，告诉 Sisyphus 在什么条件下应该把任务委托给 Oracle。

15.3.2 Agent 动态 Prompt 构建器

dynamic-agent-prompt-builder.ts 是 oh-my-opencode 中最精巧的模块之一。它接收所有 Agent 的元数据，动态生成 Sisyphus 主 Agent 的 Prompt 中关于"如何使用子 Agent"的部分。

衍生解释：什么是动态 Prompt？

在传统的 LLM 应用中，System Prompt 通常是静态的——在代码中写死一段文本。但在 oh-my-opencode 中，Sisyphus 的 Prompt 是在运行时动态生成的。它会根据当前启用的 Agent 列表、可用的 Skill、Category 配置等信息，实时拼接出完整的 Prompt。

这意味着：如果用户通过配置禁用了 Oracle Agent，那么 Sisyphus 的 Prompt 中就不会出现"何时使用 Oracle"的指导——从根本上避免了 Sisyphus 尝试调用一个不存在的 Agent。

构建器函数概览

动态 Prompt 构建器提供了 8 个核心构建函数：

// oh-my-opencode/src/agents/dynamic-agent-prompt-builder.ts

// 1. 关键触发条件段：在意图分类之前检查的触发器
buildKeyTriggersSection(agents, skills)

// 2. 工具选择表：按成本排序的 Agent 和工具列表
buildToolSelectionTable(agents, tools, skills)

// 3. Explore 使用指南段
buildExploreSection(agents)

// 4. Librarian 使用指南段
buildLibrarianSection(agents)

// 5. 委托决策表：何时把什么任务委托给谁
buildDelegationTable(agents)

// 6. Category + Skill 委托指南：如何选择 Category 和 Skill
buildCategorySkillsDelegationGuide(categories, skills)

// 7. Oracle 使用指南段
buildOracleSection(agents)

// 8. 工具分类器：将工具按类型分组
categorizeTools(toolNames)

关键触发条件

buildKeyTriggersSection() 从每个 Agent 的 keyTrigger 字段中提取触发条件，生成一个检查列表：

export function buildKeyTriggersSection(agents, skills): string {
  const keyTriggers = agents
    .filter((a) => a.metadata.keyTrigger)
    .map((a) => `- ${a.metadata.keyTrigger}`)

  return `### Key Triggers (check BEFORE classification):

${keyTriggers.join("\n")}
- **"Look into" + "create PR"** → Not just research. Full implementation cycle expected.`
}

输出的 Prompt 片段类似于：

### Key Triggers (check BEFORE classification):

- External library/source mentioned → fire `librarian` background
- 2+ modules involved → fire `explore` background
- **"Look into" + "create PR"** → Not just research.

工具选择表

buildToolSelectionTable() 生成一个按成本排序的 Agent 和工具推荐表。它首先列出免费的直接工具，然后按 FREE → CHEAP → EXPENSIVE 的顺序列出 Agent：

export function buildToolSelectionTable(agents, tools, skills): string {
  const rows = ["### Tool & Agent Selection:", ""]

  // 先列出免费的直接工具
  if (tools.length > 0) {
    const toolsDisplay = formatToolsForPrompt(tools)
    rows.push(`- ${toolsDisplay} — **FREE** — Not Complex, Scope Clear`)
  }

  // 再按成本排序列出 Agent
  const costOrder = { FREE: 0, CHEAP: 1, EXPENSIVE: 2 }
  const sortedAgents = [...agents]
    .filter((a) => a.metadata.category !== "utility")
    .sort((a, b) => costOrder[a.metadata.cost] - costOrder[b.metadata.cost])

  for (const agent of sortedAgents) {
    rows.push(`- \`${agent.name}\` agent — **${agent.metadata.cost}** — ${shortDesc}`)
  }

  return rows.join("\n")
}

工具分类

categorizeTools() 将工具名按前缀自动分类：

export function categorizeTools(toolNames: string[]): AvailableTool[] {
  return toolNames.map((name) => {
    let category: "lsp" | "ast" | "search" | "session" | "command" | "other" = "other"
    if (name.startsWith("lsp_"))      category = "lsp"
    else if (name.startsWith("ast_grep")) category = "ast"
    else if (name === "grep" || name === "glob") category = "search"
    else if (name.startsWith("session_")) category = "session"
    else if (name === "slashcommand") category = "command"
    return { name, category }
  })
}

Category + Skill 委托指南

buildCategorySkillsDelegationGuide() 是最复杂的构建函数。它生成一套三步协议，告诉 Sisyphus 如何为子任务选择正确的 Category 和 Skill：

### MANDATORY: Category + Skill Selection Protocol

**STEP 1: Select Category**
- Read each category's description
- Match task requirements to category domain

**STEP 2: Evaluate ALL Skills (Built-in AND User-Installed)**
For EVERY skill listed above, ask yourself:
> "Does this skill's expertise domain overlap with my task?"
- If YES → INCLUDE in `load_skills=[...]`
- If NO → You MUST justify why

**STEP 3: Justify Omissions**
If you choose NOT to include a skill that MIGHT be relevant, provide:

SKILL EVALUATION for "[skill-name]":

• Skill domain: [what the skill description says]

• Task domain: [what your task is about]

• Decision: OMIT

• Reason: [specific explanation]

这个设计特别强调了用户安装的 Skill。它区分了 plugin 类型的内置 Skill（由 oh-my-opencode 提供）和 user/project 类型的自定义 Skill（由用户安装）。对于用户安装的 Skill，Prompt 会加入特别强调的警告，要求 Sisyphus 优先考虑这些 Skill。

15.3.3 Sisyphus 主 Agent 详解

Sisyphus 是整个系统的"指挥官"，它的 Prompt 是所有 Agent 中最复杂的——由多个动态构建的段落拼接而成。

Prompt 组装

// oh-my-opencode/src/agents/sisyphus.ts
function buildDynamicSisyphusPrompt(
  availableAgents, availableTools, availableSkills,
  availableCategories, useTaskSystem
): string {
  const keyTriggers = buildKeyTriggersSection(availableAgents, availableSkills)
  const toolSelection = buildToolSelectionTable(availableAgents, availableTools, availableSkills)
  const exploreSection = buildExploreSection(availableAgents)
  const librarianSection = buildLibrarianSection(availableAgents)
  const categorySkillsGuide = buildCategorySkillsDelegationGuide(availableCategories, availableSkills)
  const delegationTable = buildDelegationTable(availableAgents)
  const oracleSection = buildOracleSection(availableAgents)
  const hardBlocks = buildHardBlocksSection()
  const antiPatterns = buildAntiPatternsSection()
  const taskManagementSection = buildTaskManagementSection(useTaskSystem)

  return `<Role>
You are "Sisyphus" - Powerful AI Agent with orchestration capabilities...
</Role>
<Behavior_Instructions>
## Phase 0 - Intent Gate (EVERY message)
${keyTriggers}
...
## Phase 2A - Exploration & Research
${toolSelection}
${exploreSection}
${librarianSection}
...
## Phase 2B - Implementation
${categorySkillsGuide}
${delegationTable}
...
</Behavior_Instructions>
${oracleSection}
${taskManagementSection}
<Constraints>
${hardBlocks}
${antiPatterns}
</Constraints>`
}

行为指令的四个阶段

Sisyphus 的行为被组织为四个阶段：

Phase 0 — 意图门控：每条消息都必须经过的分类步骤。

1. 分类请求类型：Trivial / Explicit / Exploratory / Open-ended / Ambiguous
2. 检查歧义：如果多种解释的工作量差异超过 2x，必须询问
3. 执行前验证：检查假设、确认委托决策

Phase 1 — 代码库评估：对于开放式任务，先评估代码库的成熟度。

Quick Assessment:
1. 检查配置文件：linter、formatter、type config
2. 采样 2-3 个类似文件看一致性
3. 判断项目年龄信号

State Classification:
- Disciplined（有纪律的）→ 严格遵循现有风格
- Transitional（过渡期）→ 询问用户遵循哪种模式
- Legacy/Chaotic（遗留/混乱）→ 建议新模式
- Greenfield（新项目）→ 应用现代最佳实践

Phase 2 — 执行：分为 2A（探索研究）、2B（实现）、2C（故障恢复）。

Phase 3 — 完成：验证清单和交付。

委托协议

Sisyphus 的 Prompt 中定义了一套严格的 6 段委托协议，要求每次委托子任务时必须提供完整的上下文：

1. TASK: 原子化的具体目标（每次委托一个动作）
2. EXPECTED OUTCOME: 具体的可交付成果和成功标准
3. REQUIRED TOOLS: 明确的工具白名单
4. MUST DO: 详尽的必须要求
5. MUST NOT DO: 禁止的行为
6. CONTEXT: 文件路径、现有模式、约束

这种协议设计背后的理念是：子 Agent 是 无状态 的——它们不知道主 Agent 之前做了什么。因此，每次委托都必须提供足够的上下文让子 Agent 独立完成任务。

15.3.4 Oracle 咨询 Agent

Oracle 是一个只读顾问——它只分析和给出建议，不直接修改代码。

// oh-my-opencode/src/agents/oracle.ts
export function createOracleAgent(model: string): AgentConfig {
  const restrictions = createAgentToolRestrictions([
    "write", "edit", "task", "call_omo_agent",  // 禁止写入和委托
  ])

  return {
    description: 'Read-only technical advisor...',
    mode: "subagent",
    model,
    temperature: 0.3,
    ...restrictions,
    prompt: ORACLE_SYSTEM_PROMPT,
  }
}

Oracle 的 Prompt 定义了三个关键框架：

决策框架（Pragmatic Minimalism）

Apply pragmatic minimalism in all recommendations:
- **Bias toward simplicity**: The right solution is typically the least complex one.
- **Leverage what exists**: Favor modifications to current code over new components.
- **Prioritize developer experience**: Optimize for readability and maintainability.
- **One clear path**: Present a single primary recommendation.
- **Match depth to complexity**: Quick questions get quick answers.
- **Signal the investment**: Tag recommendations with effort estimates.
- **Know when to stop**: "Working well" beats "theoretically optimal."

输出冗余控制

Oracle 对输出长度有严格限制：

Verbosity constraints (strictly enforced):
- **Bottom line**: 2-3 sentences maximum. No preamble.
- **Action plan**: ≤7 numbered steps. Each step ≤2 sentences.
- **Why this approach**: ≤4 bullets.
- **Watch out for**: ≤3 bullets.

三层响应结构

**Essential** (always include):
- Bottom line: 2-3 sentences
- Action plan: Numbered steps
- Effort estimate: Quick/Short/Medium/Large

**Expanded** (include when relevant):
- Why this approach
- Watch out for
- Edge cases

**Deep** (only on request):
- Alternative analysis
- Full trade-off matrix

15.3.5 Prometheus 规划 Agent

Prometheus 是一个专门的任务规划器。它的 Prompt 被拆分为 6 个独立模块，体现了关注点分离原则：

// oh-my-opencode/src/agents/prometheus/system-prompt.ts
export const PROMETHEUS_SYSTEM_PROMPT = `
  ${PROMETHEUS_IDENTITY_CONSTRAINTS}    // 身份约束
  ${PROMETHEUS_INTERVIEW_MODE}          // 面试模式
  ${PROMETHEUS_PLAN_GENERATION}         // 计划生成
  ${PROMETHEUS_HIGH_ACCURACY_MODE}      // 高精度模式
  ${PROMETHEUS_PLAN_TEMPLATE}           // 计划模板
  ${PROMETHEUS_BEHAVIORAL_SUMMARY}      // 行为总结
`

各模块的职责：

模块	功能
identity-constraints.ts	定义 Prometheus 的角色边界——它只能规划，不能执行
interview-mode.ts	"面试"用户以澄清需求，通过提问消除歧义
plan-generation.ts	将需求转化为结构化的执行计划
high-accuracy-mode.ts	对计划进行自我验证，检查遗漏和矛盾
plan-template.ts	定义计划文档的标准格式
behavioral-summary.ts	行为规范的精简总结

Prometheus 的权限被严格限制：

export const PROMETHEUS_PERMISSION = {
  edit: "allow",      // 允许编辑（写计划文件）
  bash: "allow",      // 允许运行 bash（探索项目）
  webfetch: "allow",  // 允许网络请求（查找资料）
  question: "allow",  // 允许提问（面试用户）
}

注意，它有编辑权限但没有执行权限——Prometheus 可以写出计划文档，但不会去执行计划。一个专门的 prometheus-md-only Hook 会确保 Prometheus 只能编辑 .md 文件。

15.3.6 Agent Builder —— 统一的 Agent 构建工厂

agent-builder.ts 提供了一个统一的 Agent 构建函数，处理 Category 继承和 Skill 注入：

// oh-my-opencode/src/agents/agent-builder.ts
export function buildAgent(
  source: AgentSource,
  model: string,
  categories?: CategoriesConfig,
  gitMasterConfig?: GitMasterConfig,
  browserProvider?: BrowserAutomationProvider,
  disabledSkills?: Set<string>
): AgentConfig {
  // 1. 调用工厂函数或使用静态配置
  const base = isFactory(source) ? source(model) : { ...source }

  // 2. Category 继承：如果 Agent 指定了 category，从 category 继承 model、temperature 等
  const categoryConfigs = mergeCategories(categories)
  if (agentWithCategory.category) {
    const categoryConfig = categoryConfigs[agentWithCategory.category]
    if (categoryConfig) {
      if (!base.model) base.model = categoryConfig.model
      if (base.temperature === undefined) base.temperature = categoryConfig.temperature
      if (base.variant === undefined) base.variant = categoryConfig.variant
    }
  }

  // 3. Skill 注入：将 Skill 内容解析并前置到 Prompt
  if (agentWithCategory.skills?.length) {
    const { resolved } = resolveMultipleSkills(agentWithCategory.skills, { ... })
    if (resolved.size > 0) {
      const skillContent = Array.from(resolved.values()).join("\n\n")
      base.prompt = skillContent + (base.prompt ? "\n\n" + base.prompt : "")
    }
  }

  return base
}

这个构建器体现了组合优于继承的设计原则：

1. Category 机制：Agent 不直接指定模型，而是声明自己属于哪个 Category。Category 定义了模型和参数，多个 Agent 可以共享同一个 Category。这使得用户可以通过修改一个 Category 配置来同时影响多个 Agent。

2. Skill 注入：Agent 声明自己需要哪些 Skill，构建器自动将 Skill 的 Markdown 内容解析出来，注入到 Agent 的 Prompt 前面。这实现了"知识的可组合性"——一个 git-master Skill 可以被注入到任何需要 Git 操作专业知识的 Agent 中。

15.3.7 环境上下文注入

env-context.ts 为 Agent 注入运行时环境信息：

// oh-my-opencode/src/agents/env-context.ts
export function createEnvContext(): string {
  const now = new Date()
  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
  const locale = Intl.DateTimeFormat().resolvedOptions().locale

  return `
<omo-env>
  Current date: ${dateStr}
  Current time: ${timeStr}
  Timezone: ${timezone}
  Locale: ${locale}
</omo-env>`
}

这个看似简单的函数解决了 LLM 的一个根本问题：LLM 没有内在的时间概念。模型的训练数据截止到某个时间点，它不知道"现在"是什么时候。通过注入实时的日期、时间和时区信息，Agent 可以做出基于时间的正确判断——比如 Librarian Agent 搜索文档时应该搜索最新年份的内容。

值得注意的是，env-context.ts 只注入 OpenCode 本身没有提供的信息（时间、时区、语言环境），避免了与 OpenCode 的 system.ts 重复。

衍生解释：什么是 Prompt 工程中的"角色设定"？

在 LLM 应用中，"角色设定"（Role Prompting）是一种常见的 Prompt 工程技术。通过在 System Prompt 中赋予模型一个特定的角色身份（如"你是一个代码审查专家"），可以引导模型产出更专业、更聚焦的回答。

oh-my-opencode 将这一技术推向了极致：它不是简单地说"你是一个专家"，而是为每个角色定义了完整的行为规范——包括何时介入、何时回避、输出格式约束、决策框架等。这种深度的角色设定使得每个 Agent 的行为更加可预测和可控。

从工程角度看，这种方式将 Prompt 从"魔法咒语"变成了"可维护的代码"——每个 Agent 的行为规范被模块化地定义、测试和维护。

本节小结

oh-my-opencode 的多 Agent 体系的核心创新在于：

1. 元数据驱动的动态 Prompt：每个 Agent 声明自己的元数据（适用场景、成本、触发条件），这些元数据被动态 Prompt 构建器消费，自动生成 Sisyphus 主 Agent 的委托决策指南。增减 Agent 不需要手动修改 Sisyphus 的 Prompt。

2. Category + Skill 组合模式：Agent 通过 Category 继承模型配置，通过 Skill 注入专业知识，实现了"知识的可组合性"。

3. 分层的角色设计：从免费的 Explore（代码搜索）到昂贵的 Oracle（架构顾问），不同成本级别的 Agent 对应不同复杂度的任务，既保证了质量又控制了成本。

4. 严格的委托协议：6 段结构的委托协议确保子 Agent 获得足够的上下文，弥补了其无状态的天然劣势。