OmX 高控制编排工作流全解析：`ralplan -＞ team -＞ ralph` 的定位、设计与仓库现状

OmX 高控制编排工作流全解析：ralplan -> team -> ralph的定位、设计与仓库现状

【免费下载链接】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

本篇技术指南以 OmX 仓库中的 PR 草稿 dev-team-ralph-workflow-positioning.md 为骨架，完整展开其核心命题：为什么$team不只是并行 fanout，而是"协调、可检查、runtime 感知"的执行模型；以及ralplan -> team -> ralph如何构成一套既快又操作纪律严明的完整工作流。读者读完后，将掌握三阶段工作流的职责边界、$team与$ultrawork的定位差异、后续规划（follow-up planning）的源码级设计方向，并了解该工作流在当前仓库中已发生的版本演化（ultrawork/ralph相继退役、omx team ralph弃用）。

一、工作流全景：为什么team不只是 fanout

原 PR 草稿的立论起点是一个经常被误解的问题：当$ultrawork（或如今的$team）已经能提供并行执行时，为什么还需要专门的 team 模式？

原文档给出的答案是：team mode 不是简单的扇出（fanout）。它同时具备三个$ultrawork时代所不具备的工程属性：

• 协调（Coordinated）：workers 之间可以共享阻塞感知（blocker awareness），可以早期暴露阻塞、重新分配工作，而不是各干各的互不感知；
• 可检查（Inspectable）：执行过程通过 tmux panes 可见，同时叠加持久化状态（durable state），让"现在团队在做什么"随时可审计；
• runtime 感知（Runtime-aware）：leader 对恢复（recovery）和生命周期命令（lifecycle commands）拥有更强的控制权。

把这三点与前置的ralplan（共识规划）和后置的ralph（持久化 + 验证）配对，就得到一条"既快又操作纪律严明"（fast and operationally disciplined）的主路径：

ralplan -> team -> ralph

这条工作流在仓库中的落地证据直接可见于 src/team/followup-planner.ts：后续规划器明确定义了FollowupMode = 'team' | 'ralph'，并输出FollowupStaffingPlan（含recommendedHeadcount、allocations、launchHints、verificationPlan），也就是说"规划产出直接导向 team 或 ralph 启动"这一设计，在源码层面已经成真。

二、前置阶段：ralplan共识规划

ralplan是 OmX 的共识规划阶段，作为$autopilot默认链$deep-interview -> $ralplan -> $ultragoal的中间环节（见 README.md）。从 skills/ralplan/SKILL.md 看，它的核心不是"写一个计划文件"，而是驱动Planner → Architect → Critic三个角色的顺序评审生命周期：

1. Planner产出右规模的实施计划与紧凑的 RALPLAN-DR 摘要（原则、决策驱动、可行选项及取舍、唯一选项时的失效理由）；
2. Architect评审架构合理性，必须给出最强的 steelman 反题与至少一个真实取舍张力；
3. Critic按质量标准评估，可返回APPROVE/ITERATE/REJECT，非通过则进入最多 5 轮的全闭环重评审。

原 PR 草稿将ralplan定位为"team 后续规划应该变得更显式的地方"，并提出了具体的设计方向：

In future work,ralplancan emit lane recommendations, role placement hints, and launch guidance for a directteamhandoff, whileralphremains the persistence and verification layer.

这个设计方向在仓库中已经有对应的落地痕迹。首先，ralplan的执行入口是omx ralplan run --task <arguments> [--session <id>]，其ralplan_execution_handoff记录{authorized: true, reason, authorized_at, session_id, review_cycle, source: "autopilot"|"user"}，只有当该记录持久化后执行才被允许（见 skills/ralplan/SKILL.md）。其次，ralplan的 Goal-Mode 后续建议明确把$team作为一等执行选项：

Keep$teamas a first-class execution option and keep$ralphavailable only as an explicit fallback where appropriate: use Ultragoal as the default durable goal-mode follow-up, Team for coordinated parallel implementation, and Ralph only for intentionally selected persistent single-owner completion/verification pressure.

也就是说：规划阶段就要产出 role/staffing 分配、按 lane 的 reasoning 建议、以及omx team的具体启动提示。

三、核心阶段：$team协调执行与 runtime 状态模型

3.1 启动形态与前置条件

按照 skills/team/SKILL.md，team 的启动形态是：

omx team [N:agent-type] "<task>" $team [N:agent-type] "<task>"

例如omx team 3:executor "implement X"。前置条件包括：

• 需要tmux -V、leader 会话运行在$TMUX中（macOS/Linux 主路径，Windows 仅psmux次路径，推荐 WSL2）；
• 启动前任务应落地到最近的.omx/context/{slug}-*.md上下文快照；
• 禁止嵌套启动 Team 运行；
• worker CLI 可通过OMX_TEAM_WORKER_CLI=codex|claude|auto或OMX_TEAM_WORKER_CLI_MAP=...指定；
• 每个 agent 的 reasoning 由agentReasoning控制，合法值为low、medium、high、xhigh、max（ultra不被支持）。

3.2 运行产物与状态权威

启动后，runtime 会创建.omx/state/team/<name>/下的config.json、manifest.v2.json、tasks/task-<id>.json、worker 身份/inbox、mailbox 文件与 dispatch 队列；workers 通过环境变量OMX_TEAM_WORKER、OMX_TEAM_STATE_ROOT、OMX_TEAM_LEADER_CWD感知归属。

关于状态归属，docs/contracts/team-runtime-state-contract.md 明确了一份"权威归属"清单，这正是"可检查 + runtime 感知"的契约基础：

状态	权威归属	主要入口
pending/notified/delivered/failed	team dispatch 请求状态（dispatchstatus为权威，时间戳只是佐证）	src/team/state/dispatch.ts、src/team/state.ts，Rust 侧见 crates/omx-runtime-core/src/dispatch.rs
integrated	monitor 快照integrationByWorker；worker 只有通过 leader-head 推进/收敛检查后才算integrated，mailbox 投递和 tmux 活动都不充分	src/team/runtime.ts、src/team/state/monitor.ts
stale	按边界拆分：runtime authority（crates/omx-runtime-core/src/lib.rs）、leader activity（src/team/leader-activity.ts）、session（src/hooks/session.ts）	不得仅凭 dispatch/integration 状态推断

这套契约强调：notify-hook观察到的 mailbox/tmux 证据是派生证据，dispatch 成功必须通过 dispatch-request 状态转移表达——这正是"协调执行、状态可检查"与"纯 fanout"的本质差异。

3.3 机器可读的操作接口

team 提供 CLI API 供 leader 与 workers 以 JSON 方式交互（见 skills/team/SKILL.md）：

omx team api send-message --input '{"team_name":"<name>","from_worker":"leader-fixed","to_worker":"worker-1","body":"<short trigger>"}' --json omx team api read-task --input '{"team_name":"<name>","task_id":"<id>"}' --json omx team api transition-task-status --input '{"team_name":"<name>","task_id":"<id>","from":"in_progress","to":"completed","claim_token":"<token>"}' --json

监控与收尾：

omx team status <name> --json omx team await <name> --timeout-ms 30000 --json omx team shutdown <name>

只有pending=0、in_progress=0、failed=0（或明确承认的失败路径）时才执行 shutdown，且必须先验证 shutdown 证据与状态清理，不能在 workers 仍在写入时就宣告完成。

四、后置阶段：ralph持久化 + 验证层（含版本演化说明）

原 PR 草稿把ralph描述为"persistence and verification layer"：在 team 执行完成后，由一个 leader 或独立 worker 选择性地启动ralph作为独立的持久化回环，持续施加"直到证据支持的完成"（evidence-backed completion）的压力，让工作流保持诚实（keep the workflow honest）。

需要特别说明的版本演化：从当前仓库的实际状态看，原 PR 草稿写作时的三条工作流组件已发生显著演化：

• $ultrawork已在 OMX 0.21 中移除：skills/ultrawork/SKILL.md 目前是 sunset stub，明确写着"$ultraworkwas removed in OMX 0.21; use$teaminstead"，理由正是原 PR 草稿的核心论点——"并行执行是 team 的职责；ultrawork 的纯提示词并行引擎在没有独立 runtime 的情况下制造了第二个权威"。换句话说，原文档"team 不是 fanout"的论证，最终在版本演化中直接取代了 ultrawork。
• $ralph也已在 OMX 0.21 中移除：skills/ralph/SKILL.md 同样是 sunset stub，指明改用$ultragoal。Ralph 的"loop-until-done"行为被视为退化的单目标 ultragoal run，由$ultragoal承接持久化 Codex goal 交接、.omx/ultragoalledger 检查点、实现/测试/构建/lint/typecheck 证据以及跨 story 恢复。
• omx team ralph ...的链接工作流已被弃用：见 docs/prs/dev-deprecate-team-ralph.md。它移除了 team↔Ralph 的链接 runtime bridge、链接 notify-hook 终端同步、链接 cleanup/shutdown 策略、linked_ralph生命周期 profile 与omx team ralph ...启动提示，让omx team ...成为唯一受支持的团队启动路径，而omx ralph ...保留为独立、显式的后续动作。现在调用omx team ralph ...会得到明确的弃用错误，而非被静默容忍。

因此，在阅读原 PR 草稿时，ralplan -> team -> ralph应理解为设计方向与思想骨架；在当前仓库（0.21+）中，等价的推荐落地形态是：ralplan规划 →$team协调并行执行（含自身验证 lane）→ 需要持久化单目标完成回环时用$ultragoal（或按需显式选择$ralph作为后备）。原文档"ralphremains the persistence and verification layer"的职责，如今由 team 自己的验证 lane 与ultragoal共同承接。

五、$team与$ultrawork的定位差异：从文档澄清到版本事实

原 PR 草稿的"Changes"清单第一条就是clarify the positioning difference between$teamand$ultrawork。二者的差异可以总结为下表（依据 skills/team/SKILL.md、skills/ultrawork/SKILL.md 与 README.md）：

维度	$team	$ultrawork（已移除）
定位	协调执行（coordinated execution）	纯提示词并行扇出
worker 载体	tmux worker panes	无独立 runtime
状态	共享任务状态、mailbox/dispatch、monitor 快照	无持久状态模型
生命周期	leader 拥有 shutdown/await/恢复控制	无生命周期命令
现状	唯一受支持的团队启动路径	OMX 0.21 起为 sunset stub，迁移到$team

README 中也给出了当前推荐的分工（README.md）：默认用$ultragoal作为持久完成包装；只有当某个特定 story 需要协调并行时才在该执行路径内使用$team；当想要单所有者的完成回环时用$ralph。这与原 PR 草稿"帮助高级用户判断何时选 team 而非简单并行扇出"的目标完全一致。

六、设计方向：让ralplan显式产出 team 后续规划

原 PR 草稿提出的后续工作方向是：让ralplan成为 team 后续规划的显式出口，并附带一份 issue 草案：docs/issues/team-ralph-followup-team.md。该 issue 提案ralplan支持--followup team这类显式后续模式，其产出应包含五项内容：

1. 常规实施计划与验收标准（acceptance criteria）；
2. 推荐的 worker lanes / 角色分配（recommended worker lanes / role allocation）；
3. 每条 lane 的建议 reasoning 级别（suggested reasoning levels by lane）；
4. 面向omx team/$team的显式后续命令或启动提示（explicit follow-up commands or launch hints）；
5. 匹配team -> ralph执行路径的验证预期（verification expectations）。

该 issue 同时记录了备选方案与取舍：仅把模式写在文档里（帮助发现性，但用户仍需手工把计划翻译成 worker lanes）；或全部折叠进autopilot（适合默认自动化，但对想直接控制规划、人员配置与验证的用户太弱）。

从源码结构看，这个设计方向已经部分实现。在 src/team/followup-planner.ts 中：

• FollowupMode = 'team' | 'ralph'是显式的后续模式枚举（第 6 行）；
• buildLaunchHints会按模式生成可直接执行的启动命令（第 172-190 行）：team 模式产出omx team <N>:<role> <task>/$team <N>:<role> <task>，ralph 模式产出omx ralph <task>/$ralph <task>；
• team 模式的验证计划明确："delivery lanes 并行运行，同时由专门的 verification lane 在 shutdown 前捕获新鲜证据"（第 193-203 行）；
• 默认 headcount 计算也区分模式：team 模式默认 2、ralph 模式默认 3（第 280 行），并且 team 模式使用team-exec交付 lane、ralph 模式使用team-verify主实现 lane（第 284 行）。

这些实现细节印证了原 PR 草稿的判断："planning output that already anticipates team staffing and follow-up execution"是一条可信的设计方向。

七、为什么这套工作流重要：预期成果与适用场景

原 PR 草稿列出的预期成果可以归纳为四点，均与当前仓库的架构能力一一对应：

1. 更好的 onboarding：用户评估 OmX 编排模型时，README 不只说"存在 team mode"，而是说清"为什么在已有并行能力时 team 仍重要"；
2. 更容易解释$team与$ultrawork的差异：前者是协调 + runtime 控制，后者只是扇出；
3. 从规划到执行的更清晰路径：ralplan的产出直接包含 staffing 与 launch hints，减少用户把计划手工翻译成 worker lanes 的摩擦；
4. 对混合 CLI 团队与 runtime 边界场景的更好支持：team runtime 已支持 worker roles、mixed CLIs（codex/claude/auto）、runtime state 与可检查的团队生命周期命令（见 skills/team/SKILL.md 与 src/team/ 下的role-router.ts、allocation-policy.ts、rebalance-policy.ts、runtime-cli.ts等模块），这类"runtime 边界 + 编排边界"的工作，恰恰是持久协调比原始任务拆分更重要的场景。

原 PR 草稿还点出一个附带收益：这让autopilot也更容易解释——因为它可以描述为在同一底层工作流之上的一层自动链式封装（"an automatic chaining layer over the same underlying workflow"）。这正是 README.md 中$autopilot的官方定义：$deep-interview -> $ralplan -> $ultragoal链式默认编排器，而每个阶段在输入契约已满足时都可独立调用。

八、验证与实操检查清单

原 PR 草稿给出的验证方式针对的是文档类改动：

npm run build # TypeScript build npm test

对于使用者验证自己的工作流环境，推荐按 README 的 smoke 路径检查三条边界（README.md）：

omx doctor codex login status omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

omx doctor检查 OMX 文件、hooks 与 runtime 前置；真正冒烟测试则验证 auth、profile、provider/base-URL 等只有 Codex 实际发起请求才会暴露的问题。team 模式的平台前置是tmux（macOSbrew install tmux、Debian/Ubuntusudo apt install tmux、Fedorasudo dnf install tmux、Archsudo pacman -S tmux；原生 Windows 仅winget install psmux次路径，推荐 WSL2，见 README.md）。

九、结语：从 PR 草稿到仓库演化的完整图景

ralplan -> team -> ralph是 OmX 文档中最值得研究的一条高控制编排路径。它回答了一个本质问题：当并行执行已经廉价时，编排的价值来自协调、可检查性与 runtime 控制，而不只是任务拆分。原 PR 草稿（docs/prs/dev-team-ralph-workflow-positioning.md）与其配套 issue（docs/issues/team-ralph-followup-team.md）把这条路径的定位与设计方向固化进了文档；而当前仓库的源码与版本演化（src/team/followup-planner.ts 的双模式后续规划、ultrawork与ralph的退役、omx team ralph的显式弃用）则进一步证明了："team 是协调执行而非扇出"不仅是一个叙事，而是最终被代码与产品决策采纳的核心原则。对于评估 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