
OmX 团队执行角色拆分team-executor 与保守 Fanout 治理的完整落地【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex本文基于 OmXOh My codeX仓库中的 PR 设计文档 docs/prs/dev-issue-715-team-brain-role-split.md围绕 issue #715 的修复方案展开团队模式team mode的执行默认值不再复用通用 executor 车道而是引入独立的team-executor角色并配套可安装注册与保守 Fanout 守卫让受监督的团队交付更克制、更可预测。读完本文你将掌握team-executor角色提示词的设计骨架、其在 agent 定义与 catalog/setup 安装链路中的注册方式、显式N:agent-type启动的向后兼容逻辑以及弱结构化小任务如何被限制过度拆分的底层判定规则。背景与问题团队大脑与执行车道的职责混淆在团队模式下OmX 会把任务拆解并分发给多个 worker 执行。修复前的默认行为存在一个隐患团队模式的执行默认值直接落在通用的executor角色上计划orchestration / brain与执行execution lane的关注点混在一条泛化车道里。其结果表现为两类问题团队运行缺少受监督的保守交付语义——通用 executor 提示词面向的是单机独立实现没有团队生命周期、任务边界与 leader 汇报协议约束团队任务的拆分fanout过于激进弱结构化的单任务也可能被默认切成多份制造不必要的协调开销。issue #715 正是要修正这一点。对应 PR目标分支dev给出的方案不是推翻团队模式而是将团队执行默认值从通用 executor 车道中分离出来形成一个职责边界清晰的新角色。变更总览五项改动PR 文档列出的改动可以归纳为五条主线后续各节逐一展开改动意图落地位置仓库证据新增team-executor角色提示词为受监督的默认团队执行提供独立行为规范prompts/team-executor.md在 catalog/setup 路径注册team-executor让提示词与原生 Agent 真正可安装、可被团队运行使用src/catalog/manifest.json、src/cli/setup.ts显式N:agent-type团队启动保持不变向后兼容用户点名角色时不做任何改写src/cli/team.ts增加保守 Fanout 守卫弱结构化的小团队任务默认不过度拆分src/cli/team.ts增加角色发现与拆解行为的回归测试固化上述行为防止回退src/team/tests/repo-aware-decomposition.test.ts、src/cli/tests/team-decompose.test.tsteam-executor 角色提示词受监督的保守执行team-executor的核心是 prompts/team-executor.md 这份角色提示词。它的身份定位一句话概括在受监督的 OmX 团队运行中执行分配的工作交付完成且经过验证的结果同时把协调开销压到最低。整个提示词围绕五个段落约束 Agent 行为约束constraints推理强度reasoning_effort默认medium仅当任务有风险或横跨多个文件时才提升到high。这与 agent 定义中的reasoningEffort: medium完全一致见下文角色定义节确保团队执行默认不走最重推理路径。团队姿态team_posture尊重 leader 的计划、任务边界与生命周期协议优先直接完成而不是投机式 fanout 或重新框定问题对低置信度工作采取保守策略先做最小的正确改动当团队以具名 agent 类型启动时保留用户的显式意图。范围守卫scope_guard留在分配的文件范围内除非正确性要求紧邻的窄幅编辑不因为看到了更多可做的活就扩大任务范围优先删除/复用而不是引入新的抽象。此外还有两条硬性约束没有新鲜的验证输出就不能声称完成被阻塞时就清晰上报阻塞点而不是虚构并行工作。这两条直接服务于证据驱动的团队交付。意图intent把团队任务视为执行请求探索到足以理解任务的程度然后实现并验证最小的正确改动。执行循环execution_loop1. 读取分配的任务与当前仓库状态 2. 在分配的车道上实现最小的正确改动 3. 用与改动区域相关的诊断/测试进行验证 4. 把具体证据回报给 leader成功标准success_criteria一个任务只有在以下条件全部满足时才视为完成请求的改动已实现改动的文件通过诊断检查clean in diagnostics相关区域的测试/构建检查通过或既有失败被明确记录没有调试残留或投机性 TODO。风格style更新以结果优先、证据密集为原则优先给出具体的文件/命令引用而不是长篇解释面对模糊的低置信度工作时选择能保持团队动量的保守解释。与之对应协调侧也有一份独立的大脑提示词 prompts/team-orchestrator.md其中明确把团队视为受监督、高协调开销的协作面而不是通用并行执行器并强调保持编排判断与 worker 运行时协议分离mailbox、claims 与生命周期 API 仍然权威。这就是大脑/角色拆分在提示词层的完整形态规划侧team-orchestrator与执行侧team-executor各司其职。角色定义与注册从提示词到可安装的原生 Agent仅有提示词还不够——要让team-executor真正参与团队运行必须在 agent 定义、catalog 清单与 setup 安装链路中完成注册。PR 的第二个核心改动正是这条可安装性闭环。Agent 定义src/agents/definitions.ts在 src/agents/definitions.ts 中TEAM_EXECUTOR_AGENT被定义为const TEAM_EXECUTOR_AGENT: AgentDefinition { name: team-executor, description: Supervised team execution for conservative delivery lanes, reasoningEffort: medium, posture: deep-worker, modelClass: frontier, routingRole: executor, tools: execution, category: build, };对比通用executorreasoningEffort: medium、posture: deep-worker、modelClass: standardteam-executor的差异点在于modelClass提升为frontier以支撑受监督团队执行的质量要求同时保留deep-worker姿态与execution工具权限。它随后被挂入AGENT_DEFINITIONS注册表src/agents/definitions.tsroutingRole: executor表明它属于执行车道而非协调车道——这正是角色拆分在类型系统层面的体现。Catalog 清单注册src/catalog/manifest.json在 src/catalog/manifest.json 中team-executor以status: internal、category: build登记{ name: team-executor, category: build, status: internal }internal状态意味着它默认面向团队内部运行而非公开宣传但按 src/cli/setup.ts 的isCatalogInstallableStatus判定active与internal都算可安装状态因此它能够被 setup 流程安装到真实团队环境中。此外team-executor也出现在 src/catalog/generated/public-catalog.json 与 templates/catalog-manifest.json 等生成物中说明 catalog 生成链路已将其纳入。Setup 安装路径src/cli/setup.ts在 src/cli/setup.ts 中团队模式专属的安装集合被显式声明const TEAM_MODE_SKILL_NAMES new Set([team, worker]); const TEAM_MODE_PROMPT_NAMES new Set([team-executor]); const TEAM_MODE_NATIVE_AGENT_NAMES new Set([team-executor]);也就是说团队模式安装时会同步安装team/worker技能、team-executor提示词与对应的原生 Agent。配套的测试覆盖了这些安装分支src/cli/tests/setup-install-mode.test.ts、src/cli/tests/setup-refresh.test.ts 与 src/cli/tests/setup-prompts-overwrite.test.ts 均引用了team-executor注册行为。显式 N:agent-type 启动保持不变PR 的第三项改动是兼容性承诺用户显式指定的N:agent-type团队启动行为完全不变。这在 src/cli/team.ts 的resolveImplicitTeamFallbackRole中表达得最清楚function resolveImplicitTeamFallbackRole(agentType: string, explicitAgentType: boolean): string { return !explicitAgentType agentType executor ? team-executor : agentType; }逻辑语义团队以默认方式未显式指定 agent 类型启动且默认角色为executor时才将其隐式回退到team-executor——这是本次拆分的关键行为变化用户显式写出3:executor之类的具名启动时explicitAgentType为真角色原样保留为executor不做任何改写保证既有团队脚本与习惯不变。从源码结构看这一回退发生在buildTeamExecutionPlan的拆解流程中src/cli/team.ts即角色改写只作用于隐式默认路径显式路径始终优先。保守 Fanout 守卫弱结构化小任务不过度拆分PR 的第四项改动是对默认拆分行为的收紧。它的目标很明确弱结构化的小团队任务默认不再被过度拆分。核心实现在 src/cli/team.ts 的resolveTeamFanoutLimitfunction resolveTeamFanoutLimit( task: string, requestedWorkerCount: number, explicitAgentType: boolean, explicitWorkerCount: boolean, plan: DecompositionPlan, ): number { if (requestedWorkerCount 1 || explicitAgentType || explicitWorkerCount || plan.strategy numbered || plan.strategy bulleted) { return requestedWorkerCount; } const size classifyTaskSize(task).size; if (plan.strategy atomic) { if (looksLikeLowConfidenceAnalysisTask(task)) { return 1; } if (size small) { const proseHeavyAtomicTask countWords(task) 18 || CONTEXTUAL_DECOMPOSITION_CLAUSE.test(task); if (!proseHeavyAtomicTask) return 1; } if (!hasAtomicParallelizationSignals(task, size)) { return 1; } } if (plan.strategy conjunction size ! large) { return Math.min(requestedWorkerCount, Math.max(2, plan.subtasks.length)); } return requestedWorkerCount; }守卫的判定维度直接放行的场景请求 worker 数 ≤ 1、用户显式指定了 agent 类型、用户显式指定了 worker 数、或任务天然是编号/项目符号列表numbered/bulleted——这些情况不压缩 worker 数因为要么无需拆分、要么用户意图已经明确。原子任务atomic场景默认拆分被压到 1除非有充分的并行化理由看起来像低置信度分析任务以analyze / audit / evaluate / explore / investigate / research / review / study / summarize等前缀开头并带有actionable recommendations / findings / report / root cause等交付信号见 src/cli/team.ts 中的ANALYSIS_TASK_PREFIX与ANALYSIS_DELIVERABLE_SIGNAL正则→ 直接收敛为 1 个 workersmall且非散文厚重字数 ≤ 18 且不含focusing on / including / while / without / ensuring等上下文拆分从句见CONTEXTUAL_DECOMPOSITION_CLAUSE→ 收敛为 1缺少原子并行化信号如 2 个以上文件引用、文件引用符号引用组合、或 large 任务中的显式并行关键词见hasAtomicParallelizationSignalssrc/cli/team.ts→ 收敛为 1。连词任务conjunction且非 largeworker 数被限制为min(请求数, max(2, 子任务数))即至少 2 个、但不超过实际子任务规模。过度编排通知当守卫生效时团队计划会携带机器可读的提示信息overOrchestrationNoticesrc/cli/team.ts 与 src/cli/team.tsteam_over_orchestration_warning小原子任务被压到 1 个 worker 时提示可以考虑单机执行路径以降低开销explicit_team_override_acknowledged用户显式指定了 worker 数 1尽管任务很小仍走团队 fanout——确认这是用户意图而非系统失控。另外src/cli/team.ts 的注释也给出了一条边界指引小规模会话内 fanout 应优先使用原生 Codex 子代理持久化的 tmux / state / worktree 协调才使用 omx team。这与团队是高协调开销表面的定位相互印证。回归测试固化角色发现与拆解行为PR 的第五项改动是测试用于锁定角色发现role discovery与拆解行为decomposition两类行为防止未来回归src/team/tests/repo-aware-decomposition.test.ts 直接断言拆分结果中的角色为team-executor如role: team-executor验证隐式回退生效src/cli/tests/team-decompose.test.ts 覆盖decomposeTaskString/buildTeamExecutionPlan的拆解与 fanout 守卫路径src/agents/tests/definitions.test.ts 与 src/agents/tests/native-config.test.ts 验证角色定义注册与原生 Agent 配置生成setup 相关测试前文已列验证 catalog/setup 安装链路。这些测试共同构成显式启动不受影响、隐式默认收敛到 team-executor、弱结构化小任务不过度拆分的回归防线。验证与合入状态PR 文档声明的验证步骤为npm run lint通过npm test通过。从仓库当前状态看本次拆分已经合入主线在 CHANGELOG.md 中记录为Team orchestrator brain and executor lane split——团队工作流现在使用专用的team-orchestrator与team-executor角色以更清晰地区分规划与执行关注点。team-executor的提示词、agent 定义、catalog 注册与 setup 安装集合均已落地且omx-capabilities.lock.json中也已锁定该角色能力项。小结拆分带来了什么回顾 issue #715 的修复这套角色拆分方案的价值在于三层分离提示词层team-executor明确受监督、保守、证据驱动、最小正确改动的执行姿态与team-orchestrator的高协调开销表面、保守编排形成互补注册层通过 agent 定义、catalog 清单与 setup 安装集合完成闭环角色真正可安装、可运行行为层显式N:agent-type保持兼容隐式默认回退到team-executor同时用 fanout 守卫把弱结构化小任务的默认拆分压到 1 个 worker并输出机器可读的过度编排提示。对于正在使用或扩展 OmX 团队模式的开发者这套实现给出了一个可复用的范式当通用执行器无法承载受监督团队的特殊语义时与其堆叠条件分支不如拆分出独立的角色车道并用兼容性守卫与回归测试同时锁定新行为生效与旧行为不破。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考