oh-my-openagent Agent（智能体） 设计与开发指南

从“怎么配一个自己的 Agent“到“怎么设计一套 Agent 体系“——读完本文，你应该能独立设计、实现并迭代生产级的自定义 Agent。

oh-my-openagent（以下简称 OMO）的核心价值不仅是提供 11 个内置 Agent，更在于设计了一套可复制的 Agent 编排体系。本文面向需要设计 Agent 的开发者——不只告诉你有什么，还告诉你怎么想、怎么选、怎么迭代。

快速上手：创建一个自定义 Agent

创建自定义 Agent 只需要三步：

第 1 步：定义 Category

在项目根目录的 oh-my-openagent.jsonc 中添加 categories 字段：

{
  "categories": {
    "my-sql-optimizer": {
      "model": "anthropic/claude-sonnet-4-6",
      "temperature": 0.1,
      "prompt_append": "你是一个 SQL 优化专家。分析查询瓶颈，建议索引策略，输出可执行的优化方案。"
    }
  }
}

配置文件修改后立即生效，无需重启。如果项目还没有 oh-my-openagent.jsonc，从 oh-my-openagent 集成 了解初始化。

第 2 步：用 task() 调用

// 使用自定义 Category
task(category="my-sql-optimizer", prompt="分析这个查询: SELECT * FROM orders WHERE status = 'pending'")

// 组合使用 Category + Skills（推荐）
task(category="visual-engineering", load_skills=["frontend-ui-ux", "playwright"],
     prompt="实现一个响应式导航栏，并在浏览器中验证")

第 3 步：验证

task(category="my-sql-optimizer", prompt="解释一下什么是索引下推（Index Condition Pushdown）")

如果输出符合预期，说明自定义 Category 已经生效。你可以像使用内置 Category 一样使用它。

完整示例：生产级自定义 Agent

{
  "categories": {
    "api-design-reviewer": {
      "model": "google/gemini-3.1-pro",
      "variant": "high",
      "temperature": 0.2,
      "prompt_append": "你是一个 API 设计评审专家。注意 RESTful 规范、命名一致性、错误处理完整性、安全性隐患。输出格式：问题列表 + 严重级别 + 修改建议。",
      "fallback_models": ["anthropic/claude-sonnet-4-6"],
      "tools": {
        "deny": ["write", "edit", "bash"]
      }
    }
  }
}

这个示例配置了一个只读的 API 设计评审 Agent，使用 Gemini 模型，如果不可用则降级到 Claude Sonnet。

快速选型指南

面对配置式 Agent（Category）、SDK、Plugin（插件）、Skill（技能） 四种扩展方式，新手常不知道从哪个入手。下表帮你 30 秒决策：

一句话原则：配得住的用 Category，需要编程集成的用 SDK，要动系统层面的用 Plugin，只需要加知识或流程的用 Skill。

Agent 设计模式

掌握了“怎么配“之后，下一个问题是“怎么设计“。以下五种模式覆盖了 90% 的多 Agent 场景。

1. Simple Agent（单 Agent）

适用场景：任务边界清晰、不需要分工协作。大多数自定义 Category 都是这种模式。

{
  "categories": {
    "code-reviewer": {
      "model": "anthropic/claude-opus-4-7",
      "variant": "max",
      "temperature": 0.1,
      "prompt_append": "你是严格的代码审查者。检查：逻辑错误、安全漏洞、性能问题、代码风格。对每个问题标注严重级别。"
    }
  }
}

什么时候用：当你只需要“一个人干一件事“时。这是默认模式，也是大多数自定义 Agent 的模式。

2. Chain（链式模式）

适用场景：一个任务的输出是下一个任务的输入。典型例子：需求分析 → 方案设计 → 代码实现 → 代码审查。

// Chain 模式：A → B → C
const requirements = await task(category="analyst", prompt="分析需求文档，提取核心功能点");
const design = await task(category="architect", prompt=`基于以下需求设计方案：\n${requirements}`);
const code = await task(category="implementor", prompt=`按设计实现代码：\n${design}`);
const review = await task(category="code-reviewer", prompt=`审查以下实现：\n${code}`);

Chain 的关键在于每个 Agent 的 prompt_append 必须聚焦单一职责——分析的不写代码，审查不改代码。这降低了每个 Agent 的认知负载，提高了输出质量。

3. Router（路由模式）

适用场景：需要根据输入类型动态决定由哪个 Agent 处理。

// Router 逻辑（通常由主 Agent Sisyphus 执行）
function routeTask(input: string) {
  if (isSecurityQuestion(input)) {
    return task(category="security-auditor", prompt=input);
  } else if (isUIQuestion(input)) {
    return task(category="visual-engineering", load_skills=["frontend-ui-ux"], prompt=input);
  } else if (isQuickFix(input)) {
    return task(category="quick", prompt=input);
  } else {
    return task(category="ultrabrain", prompt=input);
  }
}

什么时候用：当你不确定输入属于哪类任务时。Sisyphus 内置了路由能力——它会根据你的输入自动选择合适的 Category 或子 Agent 委派。

4. Parallel（并行模式）

适用场景：多个独立任务可以同时执行，互不依赖。

// 并行模式：同时启动 3 个独立检查
const bgTasks = [
  task(category="security-auditor", run_in_background=true, prompt="检查代码中的安全漏洞"),
  task(category="performance-reviewer", run_in_background=true, prompt="分析性能瓶颈"),
  task(category="style-checker", run_in_background=true, prompt="检查代码风格一致性")
];

// 稍后收集所有结果
const [security, perf, style] = await Promise.all(
  bgTasks.map(t => background_output(task_id=t.taskId))
);

什么时候用：互不依赖的审查、独立模块的测试、多维度分析场景。节省总执行时间。

5. Orchestrator（编排模式）

适用场景：需要一个主 Agent 协调多个子 Agent，根据中间结果动态决策下一步。

主 Agent（Sisyphus）
  ├─ 第 1 步：Plan Agent → 输出实现计划
  ├─ 第 2 步：审阅计划通过？
  │    ├─ 是 → 进入第 3 步
  │    └─ 否 → 回到第 1 步（迭代）
  ├─ 第 3 步：并行实现（多个 Implementor）
  ├─ 第 4 步：Reviewer 审查 → 反馈修改
  └─ 第 5 步：Tester 验证 → 完成

Orchestrator 模式是最强大的模式，也是 7-Agent Pipeline 的核心。主 Agent 拥有全权决策——判断 Plan 是否充分、Review 是否通过、是否要重试。

实现方式：Sisyphus 默认就是 Orchestrator。你不需要写编排逻辑，只需要定义好子 Agent 的 Category 和 Skill，Sisyphus 会自动编排。

模式选择决策树

任务需要多人协作？
  ├─ 否 → Simple Agent
  └─ 是 → 任务步骤有依赖关系？
       ├─ 是，前一步输出是下一步输入 → Chain
       ├─ 否，彼此独立 → Parallel
       └─ 部分依赖，需要主 Agent 协调 → Orchestrator

不确定输入属于哪类任务？
  └─ Router（交给 Sisyphus 自动路由）

Agent 路由机制

理解 OMO 如何将你的输入分派给合适的 Agent，有助于你更精准地控制执行流程。

flowchart LR
    User["你的输入"]
    Primary["主 Agent<br/>(Sisyphus)"]
    CatLookup{"有 category<br/>参数吗？"}
    SubCat["按 Category 创建<br/>Sisyphus-Junior"]
    SubAgent["按 subagent_type<br/>创建子 Agent"]
    Ret["结果返回"]

    User --> Primary
    Primary -->|"task() 调用"| CatLookup
    CatLookup -->|"有 category"| SubCat
    CatLookup -->|"有 subagent_type"| SubAgent
    SubCat --> Ret
    SubAgent --> Ret

OMO 有三种调用模式：

主 Agent 的 Tab 循环顺序（固定优先级）：Sisyphus（0）→ Hephaestus（1）→ Prometheus（2）→ Atlas（3）。可通过 agent_order 配置定制。

输入分派决策

用户输入 → Sisyphus（主 Agent）
  ├─ 普通问答 → Sisyphus 自己处理
  ├─ task(category="...") → 创建 Sisyphus-Junior，用 Category 配置
  ├─ task(subagent_type="oracle") → 创建 Oracle 子 Agent
  └─ @AgentName → 按名称匹配对应的子 Agent

Subagent vs Task API 对比

OMO 提供了两种子任务执行机制——subagent_type（进程内编排）和 task() API（独立会话）。两者看似都可以“让其他 Agent 干活“，但设计哲学完全不同：

什么时候用 Subagent？ 当子任务需要感知主 Agent 的上下文——比如 Oracle 需要理解前面的对话才能给出架构建议。Subagent 共享上下文，沟通成本低，但副作用是子任务可能受主 Agent 上下文中无关内容干扰。

什么时候用 Task API？ 当子任务完全独立——比如同时审查 3 个模块的安全、性能、风格。Task API 提供完整的隔离性，可以并行，不会互相干扰。它的代价是每次调用都要重新初始化上下文，成本略高。

实践中两者常组合使用：主 Agent（Orchestrator）用 task() 派发独立子任务，遇到需要深度咨询的场景再用 subagent_type 调用 Oracle 或 Librarian。

四种扩展方式对比

除了 Category，OMO 还提供了其他扩展方式。新手常困惑“该用 Skill 还是 Category 还是 Plugin“，下表帮你决策：

怎么选？

• 只是想告诉 AI “遇到 XX 问题用 XX 方式处理” → Skill
• 想创建一个有特定模型和行为的专属子 Agent → Category
• 想做一个团队都能用的快捷命令 → Command
• 想拦截文件写入、自定义工具 → Plugin

→ Skill 开发指南见 Skill 开发 → Command 创建见 OpenCode 内置命令参考 → Plugin 开发见 OpenCode Plugin 系统参考

Prompt（提示词） 设计指南

prompt_append 是你定义 Agent 行为的核心工具。写得好不好，直接决定 Agent 的输出质量。

基本原则

Prompt 模板仓库

以下模板可以直接复制使用：

// 代码审查 Agent
"prompt_append": "你是严格的高级代码审查者。审查维度：① 逻辑正确性 ② 安全漏洞（OWASP Top 10）③ 性能瓶颈 ④ 代码异味。输出格式：[严重级别] 问题描述 → 修改建议。不允许修改代码。"

// 安全审计 Agent
"prompt_append": "你是一名安全审计专家。检查顺序：① 认证与授权 ② 输入验证 ③ 敏感数据泄露 ④ 配置安全 ⑤ 依赖风险。每个发现必须附 CWE ID。只读模式，不修改任何文件。"

// 文档生成 Agent
"prompt_append": "你是一名技术文档写手。用中文输出。风格：简洁、准确、有代码示例。结构：概述 → 安装 → 快速开始 → API → 进阶。不要写与主题无关的内容。"

// SQL 优化 Agent
"prompt_append": "你是 SQL 性能专家。分析查询执行计划，找出全表扫描、缺失索引、N+1 查询等问题。每项建议附带预估的优化效果（如'预计减少 80% 扫描行数'）。"

// 架构评审 Agent（只读）
"prompt_append": "你是解决架构师。评审维度：① 模块职责是否单一 ② 依赖方向是否正确（高层不依赖低层）③ 扩展性 ④ 错误处理完备性。输出格式：问题 → 风险等级 → 建议方案。只读。"

Prompt 反模式

模型选择策略

不同模型有不同的性价比。选对模型可以让你的自定义 Agent 又快又省。

OMO 模型评级

选择矩阵

降级链设计

为每个自定义 Agent 配置 fallback_models，确保模型不可用时自动降级：

{
  "categories": {
    "critical-code-reviewer": {
      "model": "anthropic/claude-opus-4-7",
      "variant": "max",
      "fallback_models": [
        "openai/gpt-5.5",
        "google/gemini-3.1-pro"
      ],
      "prompt_append": "严格代码审查……"
    }
  }
}

降级链的顺序原则：质量优先，优先降级到质量接近的模型，最后才是经济模型。

错误处理与重试

Agent 运行中可能出现各种异常。合理的错误处理策略决定了 Agent 体系的健壮性。

常见异常场景

重试策略模板

在 Workflow（工作流） 中实现重试逻辑：

async function robustTask(category: string, prompt: string, maxRetries = 2) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const result = await task(category, prompt);
      if (validateOutput(result)) return result;
      console.warn(`Attempt ${attempt + 1} output invalid, retrying...`);
    } catch (e) {
      if (attempt === maxRetries) throw e;
      console.warn(`Attempt ${attempt + 1} failed: ${e}, retrying...`);
    }
  }
}

幂等性设计

Agent 可能重复执行同一个子任务。确保你的 Agent 设计是幂等的——多次执行产生相同结果：

• 创建文件的 Agent：先检查文件是否存在，存在则跳过或对比差异
• 修改代码的 Agent：基于 diff 操作，而不是覆盖写入
• 执行命令的 Agent：先检查前置条件是否满足

测试与迭代方法

Agent 开发不是一次性的。好的 Agent 需要持续迭代。

测试四步法

迭代 Checklist

每次修改 prompt_append 后，问自己：

• 输出是否更符合预期格式？
• Agent 是否做了不该做的事（越权）？
• 有没有遗漏关键检查项？
• 是否有不必要的冗余输出？
• 如果删掉一条指令，结果会变差吗？（最少指令原则）

版本管理

把 prompt_append 当成代码来管理：

{
  "categories": {
    "code-reviewer-v1": { /* 最初的版本 */ },
    "code-reviewer-v2": { /* 增加了安全审查维度 */ },
    "code-reviewer-v3": { /* 增加了输出格式约束 */ }
  }
}

保留旧版本可以快速回退，也方便 A/B 对比。

Category 系统详解

Category 是 OMO 最核心的扩展机制——它定义了“什么类型的任务用哪个模型、什么温度、什么思维框架“。每次 task() 调用都会根据 Category 创建一个 Sisyphus-Junior 来执行。

内置 Category

使用技巧：轻度逻辑任务用 quick 比 ultrabrain 更省钱，前端原型用 visual-engineering 比 unspecified-low 效果好。

Category + Skill 组合策略

Category 决定“用哪个能力“，Skill 注入“额外知识和工具“。组合使用可以创建高度专业化的子 Agent：

自定义 Category 字段

内置 Agent 参考

OMO 内置了 11 个 Agent，分三个层次。以下是你真正需要知道的——每个 Agent 什么时候用。

概览

下图以分层图形式展示了 OMO 内置 11 个 Agent 的分层架构概览。

graph TB
    subgraph Planning["规划层 · 只读分析"]
        P1[Prometheus<br/>战略规划]
        P2[Metis<br/>需求分析]
        P3[Momus<br/>计划审阅]
    end

    subgraph Execution["执行层 · 编排驱动"]
        E1[Sisyphus<br/>默认编排]
        E2[Hephaestus<br/>自主执行]
        E3[Atlas<br/>待办执行]
    end

    subgraph Worker["工兵层 · 专一执行"]
        W1[Sisyphus-Junior<br/>类别委派]
        W2[Oracle<br/>架构咨询]
        W3[Librarian<br/>外部检索]
        W4[Explore<br/>代码探索]
        W5[Multimodal-Looker<br/>视觉分析]
    end

    P1 --> E1
    P2 --> P1
    P3 --> P1
    E1 --> E2
    E1 --> E3
    E1 --> W1
    E1 --> W2
    E1 --> W3
    E1 --> W4
    E1 --> W5

规划层（Planning）

规划层 Agent 均为只读模式，不拥有文件写入和执行权限。在动手编码前完成需求分析和方案设计。

执行层（Execution）

核心编排 Agent，负责将高层任务拆解并驱动执行。

工兵层（Worker）

工兵层 Agent 是被编排的“手“—不决策，只执行。Sisyphus 根据任务类型选择合适的工兵 Agent。

Agent 模式

每个 Agent 可以扮演两种角色：

主 Agent 的切换：Tab 键在各个主 Agent 之间循环。默认顺序是 Sisyphus → Hephaestus → Prometheus → Atlas。

工具权限体系

OMO 对每个 Agent 的工具有精确的权限控制，防止越权操作。

子 Agent 工具限制

为自定义 Category 配置权限

{
  "categories": {
    "read-only-analyst": {
      "model": "anthropic/claude-opus-4-7",
      "prompt_append": "你是一个只读分析 Agent。",
      "tools": {
        "deny": ["write", "edit", "bash", "task"]  // 禁止写入、执行、委派
      }
    },
    "safe-implementor": {
      "model": "anthropic/claude-sonnet-4-6",
      "prompt_append": "你是一个安全的代码实现 Agent。",
      "tools": {
        "allow": ["read", "write", "edit", "glob", "grep", "bash"],  // 白名单模式
        "deny": ["task"]  // 明确禁止委派
      }
    }
  }
}

allow 是白名单（只允许列出的工具），deny 是黑名单（禁止列出的工具）。同时使用时，deny 优先级更高。

权限设计原则

1. 最小权限：子 Agent 只给它完成工作所需的最少工具
2. 规划层只读：分析、审查类 Agent 永远不拥有写权限
3. 防止无限委派：工兵层 Agent 禁止调用 task()，避免嵌套失控
4. 白名单优于黑名单：明确列出允许的工具比禁止某些工具更安全

完整案例：从零构建一个“安全审查 Agent“

以下是一个完整的实战案例——从需求分析到最终迭代。

需求定义

团队需要一个安全审查 Agent，在代码合并前自动检查安全漏洞。要求：只读、覆盖 OWASP Top 10、输出结构化报告。

第 1 版：最小可用

{
  "categories": {
    "security-reviewer-v1": {
      "model": "anthropic/claude-sonnet-4-6",
      "temperature": 0.1,
      "prompt_append": "你是一名安全审计专家。检查代码中的安全问题。只读。",
      "tools": { "deny": ["write", "edit", "bash"] }
    }
  }
}

测试：task(category="security-reviewer-v1", prompt="审查这段 Python 代码……")

发现的问题：输出太泛泛，没有结构化格式，缺乏具体的判断标准。

第 2 版：增加输出格式

"prompt_append": "你是一名安全审计专家。检查：① 注入漏洞 ② 认证缺陷 ③ 敏感数据泄露 ④ XML 外部实体 ⑤ 失效的访问控制 ⑥ 安全配置错误 ⑦ XSS ⑧ 不安全的反序列化 ⑨ 已知漏洞组件 ⑩ 日志和监控不足。\n\n输出格式：\n| 严重级别 | 问题描述 | 文件位置 | CWE ID | 修改建议 |\n只读模式。"

测试：增加了格式约束后，输出结构化了很多。但发现 Agent 有时候跳过后面几条 OWASP 条目。

第 3 版：拆分职责 + 降级链

"security-reviewer-v3": {
  "model": "anthropic/claude-opus-4-7",   // 升级到旗舰模型
  "variant": "max",
  "temperature": 0.1,
  "fallback_models": ["openai/gpt-5.5", "anthropic/claude-sonnet-4-6"],
  "prompt_append": "你是 OWASP Top 10 安全审计专家。\n\n强制性检查项（按优先级）：\n1. SQL/NoSQL 注入（CWE-89）\n2. XSS（CWE-79）\n3. 敏感数据硬编码（CWE-312）\n4. 认证绕过（CWE-287）\n5. 路径遍历（CWE-22）\n6. 不安全的反序列化（CWE-502）\n\n输出格式（Markdown 表格）：\n| 严重度 | 类型 | 文件:行号 | CWE | 建议 |\n严重度仅限：Critical / High / Medium / Low\n\n严格只读。不做任何修改。你的职责是报告，不是修复。",
  "tools": { "deny": ["write", "edit", "bash", "task"] }
}

测试结果：

• ✅ OWASP 10 条全部覆盖
• ✅ 输出格式严格符合表格规范
• ✅ 只读模式被严格遵守
• ⚠️ 旗舰模型成本较高，但每月审查次数有限，可以接受

集成到工作流

// CI 集成脚本
async function preMergeCheck() {
  const result = await task(category="security-reviewer-v3",
    prompt="审查当前分支的所有修改文件");
  printReport(result);
  if (hasCriticalIssues(result)) {
    throw new Error("存在 Critical 级别安全问题，请在合并前修复");
  }
}

这个 Agent 经过了 3 轮迭代才达到生产可用标准。不要期望第一版就完美——每次测试、发现问题、改进 prompt，迭代是最正常的工作方式。

成本与性能优化

Token 预算规划

不同类型的任务 Token 消耗差异巨大：

省钱策略

1. 用 Category 区分成本：简单任务用 quick（gpt-5.4-mini），复杂任务才用 ultrabrain（gpt-5.5）
2. 设置 maxTokens：限制输出长度，防止 Agent 过度生成
3. 缩短 prompt_append：每精简 100 个 Token，长期累计节省显著
4. 利用 fallback_models：主模型不可用时不用空跑一整个任务
5. 并行转串行：多个后台任务同时跑可能导致突发高成本，按优先级串行化

性能优化

开发与调试工作流

本地迭代

修改配置文件后无需重启，立即生效。推荐流程：

1. 写一个小测试 — 用最简 prompt 验证自定义 Category 能被正确调用
2. 迭代 prompt_append — 逐步增加指令细节，每次验证效果
3. 确认模型选择 — 检查选用的模型是否适合任务类型（逻辑 → 低温度，创意 → 高温度）
4. 加上 Skills — 如果需要特定领域知识，加载对应 Skill
5. 检查边界 — 给空输入、错误输入，看 Agent 是否优雅处理

Debug 技巧

分享给团队

自定义 Category 和 Agent 配置在 oh-my-openagent.jsonc 中定义，提交到 Git 即可团队共享。推荐在项目 AGENTS.md 中记录团队的自定义 Category 清单。

→ 使用 AGENTS.md 共享团队 Agent 配置见 AGENTS.md 约定系统

其他高级机制

Hook 系统

OMO 提供 54 个基础 Hook 点（启用 Team Mode 后增至 61 个），按 5 层组织：

→ Hook 系统的完整用法和事件列表见 OpenCode Plugin 系统参考。

MCP（模型上下文协议） 系统

MCP（Model Context（上下文） Protocol）是 Agent 连接外部世界的通道。OMO 提供三层 MCP：

→ MCP 配置指南见 MCP 服务器。

多 Agent 协调

当两个以上后台 Agent 同时运行时，需要关注协调问题。以下覆盖最核心的四个场景：并发上限、资源争用、死锁预防、进度监控。

并发上限

后台 Agent 没有硬性的数量上限，但实际受以下因素限制：

// 推荐的分批并发模式
async function runWithConcurrencyLimit(tasks: Array<{category: string, prompt: string}>, limit = 3) {
  const results = [];
  for (let i = 0; i < tasks.length; i += limit) {
    const batch = tasks.slice(i, i + limit);
    const bgTasks = batch.map(t =>
      task({category: t.category, prompt: t.prompt, run_in_background: true})
    );
    const batchResults = await Promise.all(
      bgTasks.map(t => background_output({task_id: t.taskId}))
    );
    results.push(...batchResults);
  }
  return results;
}

资源争用

当 2 个以上后台 Agent 需要修改同一个文件时，可能出现竞态条件：

最佳实践：

• 后台 Agent 只读不写 — 让主 Agent 收集所有输出后统一写入
• 必须写入时，每个 Agent 写独立路径（如 temp/security-report.md、temp/perf-report.md）
• 启用 tmux 隔离后，每个 Agent 在独立 pane 中运行，文件系统虽未隔离但输出流互不干扰

死锁预防

死锁在 Agent 编排中表现为：Agent A 等待 Agent B 的结果，但 Agent B 又在等待 Agent A 先完成某个前置条件。

// 安全的带超时结果收集
async function safeCollect(taskIds: string[], timeoutMs = 60000) {
  return Promise.all(
    taskIds.map(id =>
      background_output({task_id: id, timeout: timeoutMs})
        .catch(() => ({error: `Task ${id} timed out after ${timeoutMs}ms`}))
    )
  );
}

进度监控

检查后台 Agent 的运行状态和中间结果：

// 查询后台 Agent 的完整会话
background_output({task_id: "bg_abc123", full_session: true});

// 只查看最近几条消息（快速诊断）
background_output({task_id: "bg_abc123", full_session: true, message_limit: 5});

// 包含 Agent 的推理过程
background_output({task_id: "bg_abc123", full_session: true, include_thinking: true});

后台 Agent 继承主会话的工作目录。启用 tmux.enabled 后，每个后台 Agent 在独立的 tmux pane 中运行。

→ 后台任务机制的完整说明见 多 Agent 协作。

Team Mode

Team Mode（实验性，默认关闭）是多 Agent 团队协作模式，启用后增加 7 个 Team 专属 Hook 点（总计 61 个）。

→ Team Mode 的完整文档见 Teams 并行 Agent 协作。

配置管道

OMO 在启动时按以下 6 个阶段顺序初始化：

Provider → Plugin Components → Agents → Tools → MCPs → Commands

→ 完整配置指南见 oh-my-openagent 集成。

工厂模式

OMO 使用工厂模式创建 Agent，统一了 11 个 Agent 的创建逻辑——每个 Agent 通过 AgentConfig 描述其模型、Prompt、工具权限、温度等属性。开发者自定义 Category 本质上也是在定义一份 AgentConfig。

常见反模式

设计 oh-my-openagent Agent 时，以下反模式会显著降低 Agent 的可靠性和可维护性：

巨无霸 Agent：将所有能力塞进一个 Agent 定义文件，导致 prompt 过长、工具列表混乱。OMO 的 Category 系统本身就是为职责分离设计的，正确的做法是按任务类型拆分 Agent：一个 Agent 负责代码审查，另一个负责架构分析，第三个负责测试生成。每个 Agent 只持有与自身职责相关的工具和约束条件。

过度约束：在约束系统中堆砌过多不可触发的规则。很多团队在 AGENTS.md 中写了 20+ 条约束，但其中一半与 Agent 实际执行的任务无关。约束应该是“护栏“而非“紧身衣“——标注哪些是硬约束（如“不得删除用户代码“）、哪些是软约束（如“优先使用函数式风格“），让 Agent 在软约束范围内有判断空间。

忽略模型差异：为一个模型设计的 Agent prompt，不经调整直接用于另一个模型。Claude 擅长遵循长指令、GPT 擅长结构化输出、本地小模型需要更短的 prompt。OMO 支持多模型混排，但需要为每个模型适配 prompt 风格、约束数量和工具选择，而不是期望一套配置通吃。

常见失败与陷阱

Category 选型不当：将需要大量视觉判断的任务交给 quick 或 unspecified-high Category。visual-engineering 不仅能处理前端代码，其底层模型经过视觉任务优化，对 UI 布局、动画时序、样式一致性有更好的理解。选 Category 时不要只看名字，要理解每个 Category 的模型特性。

Skill 冲突：同时加载两个定义了相同行为的 Skill（如两个都有“提交前必须审查“规则），会导致 Agent 行为不确定。OMO 的 Skill 加载顺序决定了冲突时的优先级，但最安全的做法是在团队层面统一 Skill 目录，通过 dependencies 字段声明引用关系，避免重复定义相同规则。

上下文爆炸：Agent 在长会话中积累过多工具输出和中间结果，超出上下文窗口后出现“遗忘“现象。策略是在 AGENTS.md 中使用 compress 工具进行定期上下文压缩，或者在任务边界明确时使用 /fork 或启动新的子 Agent 来隔离上下文。

异步任务的错误期望：将 run_in_background=true 的异步 Agent 当作同步 Agent 使用，在未收到完成通知时就轮询结果。正确的模式是启动后台任务 → 继续其他工作 → 等待系统通知 → 通过 background_output 收集结果。

适用场景与限制

适用场景：h-agent 的 Category 编排体系最适合多步骤、多角色协作的复杂开发任务，例如“架构设计 → 代码生成 → 代码审查 → 测试编写“的全链路自动化。当任务可以拆分为原子化子任务、每个子任务需要不同专业能力时，Category 编排体系的价值最明显。

不适用场景：对于单步、确定性的简单操作（如格式化代码、修改单个配置项），直接使用主 Agent 比编排子 Agent 更高效。Category 编排的启动开销（上下文传递、结果汇聚）在小任务上得不偿失。

限制说明：当前的编排模型是星型拓扑——主 Agent 分发任务并汇聚结果，缺乏子 Agent 之间的直接通信能力。如果子 Agent A 的输出需要实时反馈给子 Agent B（而非通过主 Agent 中继），现有的编排模式会引入延迟和额外 token 消耗。此外，run_in_background 任务目前不支持跨会话持久化和恢复，会话中断后无法重新连接后台任务。

关联章节

• ← OpenCode 内置能力 — Agent 章节的全景概览
• ← oh-my-openagent 集成 — 安装和基础配置
• → OpenCode Plugin 系统参考 — Hook 系统和 Plugin 开发
• ← 多 Agent 协作 — 后台任务机制和 Agent 编排实践
• ← Agent 编排 — Agent 设计哲学和类型体系
• ← Skill 开发 — Custom Agent 与 Skill 的组合使用
• ← 生态参考 — OMO 开源项目地址和社区资源

数据来源：oh-my-openagent 官方文档（code-yeongyu/oh-my-openagent）。本文基于 v4.13.x 编写，最新版本以 GitHub 主仓库为准。