ruflo 双模式编排器（Dual-Mode Orchestrator）实战指南：用 Claude Code 思考、用 Codex 并行执行的混合工作流架构

导读

Dual-Mode Orchestrator 是 ruflo（开源 Agent 元调度框架）中专门用于「Claude Code 交互式 + Codex 无头式」混合工作流编排的 Agent。它回答了这样一个工程问题：复杂推理型任务与高并行执行型任务应该由谁来干、如何分工、如何同步结果。阅读本文后，你将掌握双模式平台模型的拆分原理、任务路由规则、三类混合工作流模板（Hybrid Development / Parallel Feature / Design & Execute）的定义方式，以及通过共享内存（memory namespace）+ MCP 工具完成跨进程协调的完整可落地方案。

本文核心依据为 .claude/agents/dual-mode/dual-orchestrator.md，并与仓库内配套的 dual-mode 技能集、codex-coordinator / codex-worker Agent 定义 相互印证，全部命令与参数均可在仓库当前内容中找到出处。

一、为什么需要「双模式」：Claude Code 负责想，Codex 负责做

单一交互式会话的瓶颈在于：一次只能顺序地处理一件事，且每一步都要等人反馈。ruflo 的 Dual-Mode 架构把 Agent 工作负载按「是否需要交互」切成两类：

• Claude Code（Interactive，交互式）：面向需要复杂推理、需要人类参与讨论、需要实时理解既有代码的任务。它擅长 架构、调试、设计、评审、讲解既有代码、战略规划；
• Codex（Headless，无头式）：面向可以被分解、可以在后台并行执行、无需交互即可跑完的任务。它擅长 实现、批量生成文件、写测试、写文档、批量处理。

从 codex-worker.md 的定义可以确认，Codex worker 的实际启动语法是非交互式的 codex exec：

codex exec --sandbox workspace-write --skip-git-repo-check "<prompt>" &

而 Claude 一侧的 worker 则使用 claude -p "<prompt>" --output-format text。当双模式编排器混合使用两个平台时，codex-worker 一律用 codex exec 启动，claude 类 worker 一律用 claude -p 启动，二者通过共享 memory 通信，这是理解整套架构的关键前提。

二、平台模型：一张图看懂「谁在什么时候干什么」

原文档给出的平台模型图精确刻画了职责边界：

┌─────────────────────────────────────────────────────────────┐
│                    🔀 DUAL ORCHESTRATOR                     │
│                         (You)                                │
├────────────────────────┬────────────────────────────────────┤
│  ┌──────────────────┐  │  ┌──────────────────────────────┐ │
│  │  CLAUDE CODE     │  │  │        CODEX                 │ │
│  │  (Interactive)   │  │  │      (Headless)              │ │
│  │  • Architecture  │  │  │  • Implementation ────┐     │ │
│  │  • Debugging     │  │  │  • Testing ──────────┤     │ │
│  │  • Design        │  │  │  • Documentation ────┤     │ │
│  │  • Review        │  │  │  • Batch work ───────┘     │ │
│  └──────────────────┘  │  └──────────────────────────────┘ │
│         THINK          │           EXECUTE                 │
└────────────────────────┴────────────────────────────────────┘

可提炼为一句口诀：Claude Code 负责 THINK（想清楚），Codex 负责 EXECUTE（执行掉）。编排器（也就是交互式会话中的 Agent 自己）处于两列之上，负责把同一任务的思考阶段和执行阶段分别派发给正确的平台。

与之配套的 codex-coordinator.md 给出了更精细的"协调者—工人"拓扑：交互式协调者负责 任务分解 → 并行 spawn → 通过 memory 监控进度 → 聚合结果，N 个无头 worker 各自执行后把结果写回 results 命名空间，由协调者统一收集。

三、路由规则：什么时候交给 Claude，什么时候交给 Codex

路由是双模式编排的核心决策点。原文档给出了两条判断准则，开发中应作为第一直觉使用。

3.1 路由到 Claude Code（交互式）

当任务需要以下能力时走 Claude Code：

• 复杂推理或调试（Complex reasoning / debugging）
• 架构决策（Architecture decisions）
• 实时评审与讨论（Real-time review and discussion）
• 理解既有代码（Understanding existing code）
• 战略规划（Strategic planning）

触发模式（Patterns）——原文档给出的正则级关键词参考：

"explain *"              // 解释
"debug *"                // 调试
"design *"               // 设计
"review with me *"       // 与我一起评审
"help me understand *"   // 帮我理解

3.2 路由到 Codex（无头式）

当任务可以被以下特征覆盖时走 Codex：

• 可在多个 worker 间并行（Parallelized across workers）
• 可在后台运行（Run in background）
• 可批量处理（Batch processed）
• 无需交互即可执行（Executed without interaction）

触发模式（Patterns）：

"implement * in parallel"  // 并行实现
"generate * files"         // 批量生成文件
"write tests for *"        // 写测试
"document *"               // 写文档
"batch process *"          // 批量处理

3.3 可编程的路由决策函数

原文档把「路由规则」翻译成了可直接使用的 JavaScript 决策函数。它用正则匹配任务描述，命中交互式关键词则路由到 Claude Code，否则路由到 Codex：

// Analyze task and decide platform
const decideRouting = (task) => {
  const interactivePatterns = [
    /explain/i, /debug/i, /design/i,
    /review/i, /help.*understand/i
  ];

  const isInteractive = interactivePatterns.some(p => p.test(task));

  return {
    platform: isInteractive ? "claude-code" : "codex",
    reason: isInteractive
      ? "Requires interaction and reasoning"
      : "Can run in background, parallelizable"
  };
};

这段代码的工程价值在于：它把 3.1/3.2 的路由经验变成了无状态、可单测、可被上层 skill 复用的纯函数——在仓库中它正是 dual-coordinate skill「Routing Decision」步骤的实现原型（见 plugin/skills/dual-mode/dual-coordinate.md）。

四、混合工作流：三种官方模板精讲

4.1 Workflow 1：Hybrid Development Flow（设计→并行实现→交互评审）

原文档给出的 YAML 是"三段式"工作流的标准范式：

phases:
  - phase: design
    platform: claude-code
    interactive: true
    tasks:
      - Discuss requirements
      - Design architecture
      - Store design in memory

  - phase: implement
    platform: codex
    parallel: true
    workers:
      - type: coder
        count: 2
      - type: tester
        count: 1

  - phase: review
    platform: claude-code
    interactive: true
    tasks:
      - Review implementation
      - Discuss improvements
      - Finalize

字段语义与实现要点：

字段	语义	说明
phase	阶段名	design / implement / review 三阶段
platform	平台归属	claude-code 走交互式会话，codex 走无头 worker
interactive	是否交互	true 表示由当前 Claude Code 会话承担
parallel	是否并行	为 true 时意味着可以同时 spawn 多个 worker
workers[].type	工人角色	仓库中已实现 coder / tester / docs / reviewer / architect 等类型（见 codex-coordinator.md 的 Worker Types Reference）
workers[].count	并发数量	决定同一角色 spawn 几个后台进程

仓库中的 dual-coordinate skill 将这段 YAML 抽象成了可直接调用的命令，并提供 hybrid_development、parallel_feature、design_and_execute 三种 workflow 模板与 --interactive-first 开关：

/dual-coordinate --workflow hybrid_development --task "Build user authentication"

4.2 Workflow 2：Parallel Feature Implementation（并行特性开发）

当一次特性开发可以被拆成「架构 / 核心实现 / API 实现 / 测试 / 文档」五条并行线时，使用如下 action 序列：

steps:
  - action: swarm_init
    args: { topology: hierarchical, maxAgents: 6 }

  - action: spawn_headless
    workers:
      - { role: architect, task: "Design feature" }
      - { role: coder-1, task: "Implement core" }
      - { role: coder-2, task: "Implement API" }
      - { role: tester, task: "Write tests" }
      - { role: docs, task: "Write documentation" }

  - action: wait_all

  - action: interactive_review
    platform: claude-code

关键设计点：

• swarm_init 的 topology: hierarchical 与 maxAgents: 6 建立了层级式 swarm，对应真实 swarm 命令行：

  npx claude-flow swarm init --topology hierarchical --max-agents 6
  

  （仓库语境下的等价写法参见 codex-coordinator.md 中的 npx ruflo@latest swarm init --topology hierarchical --max-agents 4 完整脚本示例。）
• spawn_headless 一次性注册 5 个异构 worker（architect / coder-1 / coder-2 / tester / docs），它们彼此独立、可并行；
• wait_all 是屏障同步点，保证聚合发生在全部 worker 完成后；
• 最后一步 interactive_review 把产物拉回交互式会话做质量把关。

4.3 Workflow 3：Design and Execute（先设计后批量执行）

见 dual-coordinate skill 内置模板：

/dual-coordinate --workflow design_and_execute --task "Refactor auth module"

流程为：交互式设计阶段先行，随后一次性批量执行，适合重构这类「方案必须在动刀前被确认，但落地动作本身机械可并行」的任务。

4.4 一条命令串起完整编排：/dual-coordinate 的幕后

根据 dual-coordinate.md 的 "Generated Commands" 段，/dual-coordinate 实际生成并执行的是：

# Phase 1: Interactive (Claude Code) —— 当前会话完成设计/规划
# Phase 2: Parallel (Codex)
{{#each workers}}
claude -p "{{this.task}}" --session-id {{this.id}} &
{{/each}}
wait
# Phase 3: Review (Claude Code)
npx claude-flow@v3alpha memory list --namespace results

可以看到 skill 层用 Mustache 风格模板把「多 worker 的 task 列表」渲染成一组后台 claude -p ... & + wait，结果聚合统一走 memory。这也解释了为什么 dual-mode 技能集 声明其工作方式为：Skills 定义命令行接口 → Agents 定义行为 → Memory 提供 worker 间协调 → MCP tools 承担底层操作。

五、端到端实战示例：构建一个 API 特性

原文档用一个完整的 "Build API Feature" 例子，串联起三个阶段的真实操作。

5.1 Phase 1：交互式设计（Claude Code）

在交互式会话中与 Claude Code 完成需求讨论、数据模型与错误处理策略的设计，把结论沉淀为 memory 中的共享设计文档：

Let's design the API endpoints together.
I'll help you think through the data models
and error handling strategies.

5.2 Phase 2：无头式并行实现（Codex）

把「实现 GET /users」「实现 POST /users」「写集成测试」三个互不阻塞的子任务，用 claude -p 打入后台并行执行：

claude -p "Implement GET /users endpoint" &
claude -p "Implement POST /users endpoint" &
claude -p "Write integration tests" &
wait

补充说明：在仓库的混合平台定义中，如果这三个 worker 全部由 Codex 承担，等价写法是三条 codex exec --sandbox workspace-write --skip-git-repo-check "..." &；同一任务里 claude 与 codex 两类 worker 可以混跑，只是 spawn 语法不同（见 codex-worker.md）。

5.3 Phase 3：交互式评审（Claude Code）

等 wait 放行后，回到交互式会话审查 worker 产物、识别问题与改进点：

Now let's review what the workers produced.
I'll help identify any issues or improvements.

六、Spawn 命令与结果收集

6.1 完整混合工作流的 shell 命令

原文档给出的四步命令串：

# 1. Interactive: Claude Code designs
# (This happens in current session)

# 2. Headless: Codex implements in parallel
claude -p "Implement user service" --session-id impl-1 &
claude -p "Implement user controller" --session-id impl-2 &
claude -p "Write user tests" --session-id test-1 &
wait

# 3. Interactive: Claude Code reviews results
npx claude-flow@v3alpha memory list --namespace results

要点解析：

• 给每个后台 worker 分配唯一 --session-id（impl-1 / impl-2 / test-1），便于结果归属与故障排查——codex-worker.md 中 Best Practices 也强调 "Use a clear worker id in your result keys for tracking"；
• wait 是 bash 内置的进程屏障，保证后续评审阶段开始时全部 worker 已落盘；
• 结果收集命令 npx claude-flow@v3alpha memory list --namespace results 的命名空间参数与原文档协调模式中的 namespace: "results" 一一对应。

6.2 更细的 spawn 与 collect：dual-spawn / dual-collect

不想手动写 &/wait 时，可直接用仓库预置的两个 skill：

/dual-spawn "Implement user authentication" --workers 2 --type coder
/dual-collect --namespace results

dual-spawn（见 dual-spawn.md）的参数表：

参数	默认值	说明
task	必填	下发给各 worker 的任务描述
--workers	3	并行 worker 数量
--type	coder	worker 类型：coder / tester / docs / reviewer
--wait	false	是否等待完成

其后台执行链为：npx claude-flow swarm init --topology hierarchical --max-agents {workers} 初始化协调 → 每个 worker 被渲染成一条带指令的 claude -p ... &（含 搜索 memory → 执行 → 以 upsert=true 写入 results 命名空间 三步）→ 完成后可通过 /dual-collect 或 npx claude-flow memory list --namespace results 收集。

dual-collect（见 dual-collect.md）的参数表：

参数	默认值	说明
--namespace	results	搜索的 memory 命名空间
--format	summary	输出格式：summary / detailed / json
--filter	none	按 key 模式过滤（如 worker-auth-*）

三种输出格式示例（原样摘录自 skill 文档）：

• summary：Workers Completed: 4/4 加逐 worker 状态树；
• detailed：带 Duration / Files / Result 的块状明细（如 Duration: 45s、Files: auth.service.ts, auth.types.ts）；
• json：结构化结果，含 summary: {total, completed, failed}，便于下游程序消费。

七、MCP 集成：跨进程协调的通信层

并行 worker 与交互式协调者不共享进程，ruflo 的解法是把 memory 作为进程间唯一的协调媒介，worker 只通过 MCP 工具读写它，绝不互相直接通信。

7.1 两个平台共享的工具集

原文档列举了 Claude Code 与 Codex 均可调用的 MCP 工具：

mcp__claude-flow__memory_search  // Find patterns —— 检索既有模式
mcp__claude-flow__memory_store   // Store results —— 存储结果
mcp__ruv-swarm__swarm_init       // Initialize coordination
mcp__ruv-swarm__swarm_status     // Check status
mcp__ruv-swarm__agent_spawn      // Spawn agents

7.2 三段式协调模式（设计→读设计→存结果）

原文档给出的协调模式是全套架构的"最小闭环"：

// 1. Store design from interactive phase —— 交互阶段把设计沉淀进共享命名空间
mcp__claude-flow__memory_store {
  key: "design/api-feature",
  value: JSON.stringify({
    endpoints: [...],
    models: [...],
    decisions: [...]
  }),
  namespace: "shared"
}

// 2. Workers read shared design —— worker 开工前先检索共享设计
mcp__claude-flow__memory_search {
  query: "api feature design",
  namespace: "shared"
}

// 3. Workers store results —— worker 完工后写回 results
mcp__claude-flow__memory_store {
  key: "result-worker-1",
  value: "implementation complete",
  namespace: "results",
  upsert: true
}

该模式与 codex-worker.md 的 Self-Learning Workflow 深度一致，后者把同样的三段式扩展为四步自学习闭环：

// 开工前：检索 patterns 命名空间中与任务关键词匹配的历史模式
mcp__ruflo__memory_search {
  query: "keywords from task",
  namespace: "patterns",
  limit: 5
}
// 命中相似度 > 0.7 的模式则直接复用其方案

// 完工后：把「什么方法有效、何时适用」写回 patterns，供后续 worker 复用
mcp__ruflo__memory_store {
  key: "pattern-[task-type]",
  value: JSON.stringify({ approach: "what worked", context: "when to use this" }),
  namespace: "patterns",
  upsert: true
}
// 完工后：把完成状态写回 results，供协调者聚合
mcp__ruflo__memory_store {
  key: "result-[worker-id]",
  value: JSON.stringify({ status: "complete", summary: "what was done" }),
  namespace: "results",
  upsert: true
}

值得特别强调的工程细节（均出自仓库文档，非推测）：

• upsert 必须为 true：避免重复 key 导致写入报错（见 codex-worker 的 Important Notes 第 5 条）；
• 两个命名空间职责分离：patterns 存"可复用的方法论"，results 存"本次任务的完成状态"，coordination 可存运行中的协调元数据（见 codex-coordinator.md 的 Coordination 示例）；
• worker 对自学习的使用是"软性"的——搜索到的模式只有相似度 > 0.7 才被采纳，避免低质量历史经验干扰新任务。

7.3 worker 提示词模板

dual-spawn 实际下发给每个无头 worker 的提示词骨架为（来自 dual-spawn.md）：

claude -p "
You are worker-{{@index}}.
TASK: {{task}}

1. Search: memory_search(query='{{task_keywords}}')
2. Execute your assigned work
3. Store: memory_store(key='result-{{@index}}', namespace='results', upsert=true)
" --session-id task-{{@index}} &

三步结构（先搜→再干→后存）保证了每个 worker 即便并行运行，也能感知既有代码模式，并把产物交回统一出口。

八、平台选择速查表

原文档将路由规则压缩成了一张可直接对照的任务类型决策表，是全篇最值得贴在工位旁的参考：

Task Type	Platform	Reason
Design/Architecture	Claude Code	Needs reasoning
Debugging	Claude Code	Interactive analysis
Code Review	Claude Code	Discussion required
Implementation	Codex	Can parallelize
Test Writing	Codex	Batch execution
Documentation	Codex	Independent work
Refactoring	Hybrid	Design → Execute
New Feature	Hybrid	Design → Implement → Review

读法提醒：绝大多数"复杂任务"不是被路由到单一平台，而是被路由成 Hybrid 时间线——例如"重构"被拆成「交互设计（Claude Code）→ 批量执行（Codex）」两段，"新特性"被拆成「设计 → 实现 → 评审」三段。这正是第五节 4.1/4.2 两种 YAML 模板要表达的内容。

九、最佳实践与常用命令

9.1 五条最佳实践

原文档总结的调度纪律，建议直接写入团队约定：

1. Start Interactive（先交互）：先用 Claude Code 理解需求、完成设计；
2. Parallelize Execution（再并行）：把实现交给多个 Codex worker；
3. Review Interactive（后评审）：回到 Claude Code 做质量把关；
4. Share via Memory（全走 Memory）：所有协调信息经由 memory 命名空间传递，不做进程间直连；
5. Track Progress（看进度）：用 swarm 工具监控 worker 状态。

9.2 常用命令速查

# 检查当前任务应路由到哪个平台
npx claude-flow@v3alpha hooks route --task "[your task]"

# 启动一个完整混合工作流
/dual-coordinate --workflow hybrid_development --task "[feature]"

# 只 spawn 无头 worker（不入场协调）
/dual-spawn "Implement auth module" --workers 3

# 收集所有 worker 结果
/dual-collect --namespace results

十、进一步阅读

• 编排器角色定义原文：.claude/agents/dual-mode/dual-orchestrator.md，及同目录的并行协调定义 codex-coordinator.md（注意仓库同时在 plugin/agents/dual-mode/ 维护了一份可分发副本）；
• 命令层技能：/dual-coordinate、/dual-spawn、/dual-collect，总览见 dual-mode 技能集 README；
• Codex 平台侧的 CLI 用法可参考 v3/@claude-flow/codex/README.md。

核心结论回顾：双模式编排并非简单的"两套工具轮换"，而是一条完整的设计（interactive, Claude Code）→ 并行执行（headless, Codex/claude -p &）→ 记忆协同（shared memory namespaces）→ 评审聚合（interactive） 流水线。只要遵循"Claude 想、Codex 做、Memory 传"这三条纪律，就可以在 ruflo 上稳定地把特性开发、重构、文档冲刺等任务规模化并行，而不损失推理质量。