Agent 角色系统：40+ 专业角色的定义、路由与行为叠加

Agent 角色系统：40+ 专业角色的定义、路由与行为叠加

学习目标

• 理解 OMX 如何通过 AgentDefinition 接口统一管理 40+ 专业角色
• 掌握 posture 叠加层在 TOML 配置生成时的注入机制
• 了解模型路由层次在 Codex 原生 Agent 配置中的落地
• 理解叶子代理守卫防止无限递归的实现

前置知识

本章涉及 Agent 角色定义的通用原理，建议先阅读：

• 多 Agent 路由与隔离
• Agent 角色定义系统

下文假设你已理解上述概念，直接聚焦 Oh-My-Codex 的具体实现。

---

项目实践

单一注册表：AGENT_DEFINITIONS

OMX 将所有 Agent 定义集中在一个映射中（src/agents/definitions.ts）：

伪代码：
const AGENT_DEFINITIONS: Record<string, AgentDefinition> = {
  "explore": {
    name: "explore",
    description: "代码库探索者，快速理解项目结构和关键文件",
    reasoningEffort: "low",
    posture: "fast-lane",
    modelClass: "fast",
    routingRole: "specialist",
    tools: "read-only",
    category: "build"
  },
  "architect": {
    name: "architect",
    description: "系统架构师，设计系统架构并评审实现方案",
    reasoningEffort: "high",
    posture: "frontier-orchestrator",
    modelClass: "frontier",
    routingRole: "leader",
    tools: "analysis",
    category: "build"
  },
  "executor": {
    name: "executor",
    description: "代码执行者，实现具体功能和修改代码",
    reasoningEffort: "medium",
    posture: "deep-worker",
    modelClass: "standard",
    routingRole: "executor",
    tools: "execution",
    category: "build"
  },
  // ... 共 41 个角色
}

四大角色分类：

分类	角色数	典型角色
build	8	explore、analyst、planner、architect、executor、verifier
review	6	code-reviewer、security-reviewer、performance-reviewer、api-reviewer
domain	11	dependency-expert、test-engineer、git-master、designer、qa-tester
product	4	product-manager、ux-researcher、information-architect
coordination	7	critic、scholastic、vision、prometheus-strict-*

TOML 配置生成：从定义到 Codex 原生 Agent

OMX 在 omx setup 时将 Agent 定义编译为 Codex 原生 TOML 配置：

伪代码（generateAgentToml 流程）：
function generateAgentToml(definition, config):
  // 1. 读取提示词文件
  prompt = readPromptFile(`prompts/${definition.name}.md`)

  // 2. 剥离 YAML frontmatter
  promptBody = stripFrontmatter(prompt)

  // 3. 注入 posture 叠加层
  postureOverlay = getPostureOverlay(definition.posture)
  developerInstructions = promptBody + "\n\n" + postureOverlay

  // 4. 解析模型
  model = resolveModel(definition, config)

  // 5. 生成 TOML
  return {
    name: definition.name,
    description: definition.description,
    model: model,
    model_provider: resolveProvider(model),
    model_reasoning_effort: definition.reasoningEffort,
    developer_instructions: developerInstructions
  }

生成的 TOML 文件安装到 ~/.codex/agents/{name}.toml（用户级）或 ./.codex/agents/{name}.toml（项目级）。

Posture 叠加层的三种变体

OMX 的 posture 叠加层是标准化的系统提示追加文本：

Posture	叠加层核心指令
frontier-orchestrator	”优先路由：在开始工作前，先判断此任务是否应该委托给专业 Agent。将第一个决策视为路由问题。“
deep-worker	”偏重直接执行：先探索代码库理解上下文，然后直接实现。只有在穷尽替代方案后才升级给其他角色。“
fast-lane	”优化快速分类：优先进行快速搜索和分类。对于需要深度推理的工作，直接升级给 frontier 模型角色。“

模型路由的具体落地

OMX 的模型解析链（src/agents/native-config.ts）：

伪代码：
function resolveModel(definition, config):
  // 1. 精确模型钉扎
  if definition.exactModel:
    return definition.exactModel

  // 2. executor 特例
  if definition.routingRole == "executor":
    return config.rootModel  // frontier 模型

  // 3. 模型层级
  switch definition.modelClass:
    case "frontier": return config.rootModel
    case "fast": return config.sparkModel
    case "standard": return config.standardModel

OMX v0.18.9 默认推荐的模型配置：gpt-5.5，model_context_window = 250000，model_auto_compact_token_limit = 200000。

叶子代理守卫

对于 nativeSubagentDelegation 未标记为 allowed 的 Agent，OMX 在生成指令时注入守卫：

伪代码：
function generateInstructions(definition):
  base = loadPrompt(definition.name)

  if not definition.nativeSubagentDelegation?.allowed:
    base += "\n\n## Leaf Agent Guard\nYou are a leaf agent and MUST NOT spawn subagents. Do not use agent_type or delegate work to other agents."

  base += getPostureOverlay(definition.posture)
  return base

这防止了 executor 生成 executor 的无限递归链。

别名与合并验证

OMX 的 catalog manifest（templates/catalog-manifest.json）定义了 Agent 的生命周期状态：

伪代码：
{
  "name": "style-reviewer",
  "status": "merged",
  "canonicalTarget": "code-reviewer"
},
{
  "name": "planner",
  "status": "alias",
  "canonicalTarget": "analyst"
}

安装时，assertNativeAgentCanonicalTargets() 验证所有别名/合并目标指向有效 Agent。

问题与规避

问题	后果	OMX 的规避策略
Posture 与 modelClass 不一致	行为期望与能力不匹配	定义时强制 posture-modelClass 一致性
exactModel 钉扎过时模型	模型更新后 Agent 停留旧版	定期审计 exactModel 钉扎
委托链路过深	延迟累积、成本指数增长	叶子代理守卫 + catalog manifest 状态控制
别名链循环	无限循环解析	安装时的循环检测验证

设计取舍

为什么选择集中式注册表而非分散定义？

OMX 选择将所有 Agent 定义集中在 AGENT_DEFINITIONS 映射中，而非分散到独立的 TOML 文件。

优势：

• 类型安全：TypeScript 编译器可以验证所有定义的完整性
• 批量生成：omx setup 一次性生成所有 TOML，确保版本一致
• 别名/合并管理：集中维护状态映射，易于验证

代价：

• 单文件变大（definitions.ts 包含 41 个角色的完整定义）
• 新增 Agent 需要修改核心代码，不如独立文件灵活

替代方案：

• 每个 Agent 独立的 YAML/TOML 文件 + 目录扫描发现
• 适合插件化扩展，但验证和一致性保障较弱

参考来源

• Oh-My-Codex v0.18.9 源码 — src/agents/definitions.ts（41 个角色定义）
• Oh-My-Codex v0.18.9 源码 — src/agents/native-config.ts（TOML 生成逻辑）
• Oh-My-Codex v0.18.9 源码 — src/agents/policy.ts（策略与验证）
• Oh-My-Codex v0.18.9 源码 — templates/catalog-manifest.json（生命周期状态）