ECC dmux Workflows 实战指南：基于 tmux 窗格的 AI Agent 多会话并行编排

在 ECC（agent harness performance optimization system）中，dmux-workflows 是负责"多 Agent 并行编排"的核心技能文档：它教你用 dmux（一个面向 AI Agent 的 tmux 窗格管理器）把多个 Claude Code、Codex、OpenCode 等会话拆到不同 tmux 窗格中并行执行，并在完成后把各窗格的产出合并回主会话。读完本篇，你既能掌握 dmux 的快捷键操作、五种并行工作流模式、Git worktree 隔离方案和故障排查手段，也能从 ECC 源码层面理解 dmux-tmux 会话适配器如何把这些窗格会话规范化为 ecc.session.v1 快照，供状态检查与持久化消费。

dmux 是什么，何时启用

dmux 是一个基于 tmux 的 Agent 编排工具，把每个 AI Agent 会话放进独立的 tmux 窗格（pane）中统一管理。它的核心交互只有两个键位：

• 按 n：新建一个窗格并输入 prompt，启动一个新的 Agent 会话；
• 按 m：把指定窗格的输出合并（merge）回主会话。

dmux 支持多种 harness：Claude Code、Codex、OpenCode、Cline、Gemini、Qwen。安装方式为 npm install -g dmux，依赖本机已安装 tmux。

根据 技能文档 中"Activation"一节，以下场景应启用 dmux 工作流：

• 需要并行运行多个 Agent 会话；
• 需要在 Claude Code、Codex 等多个 harness 之间协调工作；
• 复杂任务适合"分而治之"的并行拆解；
• 用户明确说出 "run in parallel"、"split this work"、"use dmux"、"multi-agent" 等意图。

在仓库中，这份技能同时维护在 skills/dmux-workflows/SKILL.md（旧命令入口说明 指出 /orchestrate 等旧斜杠命令已被弃用，正式指引以技能文档为准）。技能元信息声明允许隐式调用（见 agents/openai.yaml 中 allow_implicit_invocation: true），即当任务匹配上述场景时，Agent 可自动套用这套工作流。

快速上手

最小化的 dmux 使用流程如下（完整继承自原文档的 Quick Start 示例）：

# 启动 dmux 会话
dmux

# 在 dmux 中按 'n' 创建 Agent 窗格，然后输入 prompt：
# Pane 1: "Implement the auth middleware in src/auth/"
# Pane 2: "Write tests for the user service"
# Pane 3: "Update API documentation"

# 每个窗格运行各自的 Agent 会话
# 完成后按 'm' 把结果合并回主会话

要点在于：主会话（main pane）是合并结果的汇聚点，所有并行窗格视为"工人"（worker），其产出在合并前彼此不可见。因此任务拆分的第一步永远是确认各窗格之间没有未声明的依赖关系。

五种并行工作流模式

原文档给出了五种经过验证的拆窗格模式，下面完整保留其 prompt 写法，并补充适用边界。

模式 1：研究 + 实现（Research + Implement）

把"调研"和"落地"拆成两条并行轨道，调研结果先落盘成文件，实现侧完成后并：

Pane 1 (Research): "Research best practices for rate limiting in Node.js.
  Check current libraries, compare approaches, and write findings to
  /tmp/rate-limit-research.md"

Pane 2 (Implement): "Implement rate limiting middleware for our Express API.
  Start with a basic token bucket, we'll refine after research completes."

# Pane 1 完成后，把调研结论合并进 Pane 2 的上下文

关键技巧是要求研究窗格把结论写入约定路径的文件（如 /tmp/rate-limit-research.md），这样合并阶段可以直接引用文件内容，而不是靠人肉转述。实现窗格先按保守方案开工，调研完成后做精化，避免实现侧空等。

模式 2：多文件特性（Multi-File Feature）

把一个特性拆到互不重叠的文件集合上并行推进：

Pane 1: "Create the database schema and migrations for the billing feature"
Pane 2: "Build the billing API endpoints in src/api/billing/"
Pane 3: "Create the billing dashboard UI components"

# 全部合并后，在主窗格做集成

这个模式的前提是三个窗格各自的文件边界清晰。若边界模糊（例如 API 端点与 schema 强耦合），应退回到 Git worktree 隔离模式（见下文），或者接受串行。

模式 3：测试 + 修复循环（Test + Fix Loop）

一个窗格专职跑测试并汇总失败，另一个窗格专职修：

Pane 1 (Watcher): "Run the test suite in watch mode. When tests fail,
  summarize the failures."

Pane 2 (Fixer): "Fix failing tests based on the error output from pane 1"

这是典型的"生产者-消费者"分工：Watcher 输出结构化的失败摘要，Fixer 只消费摘要去改代码，避免两个窗格同时改同一批文件。

模式 4：跨 Harness 分工（Cross-Harness）

不同窗格跑不同 AI 工具，按任务性质选工具：

Pane 1 (Claude Code): "Review the security of the auth module"
Pane 2 (Codex): "Refactor the utility functions for performance"
Pane 3 (Claude Code): "Write E2E tests for the checkout flow"

dmux 的价值正在于它把 harness 差异收敛到"窗格里跑什么命令"这一层，主会话只关心各窗格的产出。ECC 中与此对应的能力还有 docs/architecture/cross-harness.md 所述的跨 harness 一致性约定。

模式 5：代码评审流水线（Code Review Pipeline）

同一份代码并行跑多个评审视角，最后汇总成一份报告：

Pane 1: "Review src/api/ for security vulnerabilities"
Pane 2: "Review src/api/ for performance issues"
Pane 3: "Review src/api/ for test coverage gaps"

# 把三份评审合并为一份报告

这是"扇出-聚合"（fan-out / fan-in）形态：三个窗格只读不改，合并零冲突风险，是 dmux 中最安全的并行模式。ECC 仓库自身也提供了单会话内的对应物，如 code-review 命令 与 security-review 技能，可视为该模式在单 Agent 场景下的替代。

最佳实践

原文档的五条实践是并行窗格稳定运行的经验总结：

1. 只并行独立任务。 不要并行化存在输出依赖的任务；有依赖时先落盘中间产物（如模式 1 的 /tmp/rate-limit-research.md）。
2. 边界清晰。 每个窗格负责不同的文件或关注点。
3. 审慎合并。 合并前先审查窗格产出，避免引入冲突。
4. 善用 git worktrees。 文件冲突风险高的工作，每个窗格用独立 worktree。
5. 资源意识。 每个窗格都是完整的 Agent 会话、消耗 API token，并行窗格总数建议控制在 5～6 个以内。

第 4 条的 worktree 集成在原文档中有完整命令示例：

# 为隔离创建 worktrees
git worktree add ../feature-auth feat/auth
git worktree add ../feature-billing feat/billing

# 在各自 worktree 中运行 Agent
# Pane 1: cd ../feature-auth && claude
# Pane 2: cd ../feature-billing && claude

# 完成后合并分支
git merge feat/auth
git merge feat/billing

这个做法与 ECC 仓库自身的 worktree 编排脚本一致：scripts/orchestrate-worktrees.js 负责创建/回收 worktree 及对应会话，scripts/worktree-lifecycle.js 管理 worktree 生命周期，legacy-command-shims/commands/claw.md 中的旧命令也指向同一套指引。

互补工具选型

原文档用一张表划清了 dmux 与其他编排手段的分工边界：

工具	作用	适用时机
dmux	面向 Agent 的 tmux 窗格管理	并行 Agent 会话
Superset	支持 10+ 并行 Agent 的终端 IDE	大规模编排
Claude Code Task 工具	进程内派生子 Agent	单会话内的程序化并行
Codex multi-agent	内建 Agent 角色	Codex 专属的并行工作

选型逻辑：窗格级、跨 harness、需要人在 tmux 里直接观察每个会话的，用 dmux；单会话内想程序化派活，用 harness 内置子 Agent 机制；超大规模（10 以上并行）再考虑专用终端 IDE。

故障排查

症状	处理
窗格无响应	检查该 Agent 会话是否在等待输入；用 m 读取其输出
合并冲突	用 git worktree 隔离每个窗格的文件改动
token 消耗过高	减少并行窗格数——每个窗格都是完整 Agent 会话
找不到 tmux	macOS 用 brew install tmux，Linux 用 apt install tmux

源码纵深：ECC 如何把 dmux 会话纳入统一会话契约

以上模式解决"人怎么用 dmux"，而 ECC 作为 Agent harness 性能优化系统，还回答"编排状态如何被机器读取"。仓库中 dmux-tmux 是官方会话适配器之一，其调用链为：registry 选适配器 → dmux-tmux 适配器开目标 → orchestration-session 采集原始快照 → canonical-session 归一化并持久化。

适配器注册与目标路由

scripts/lib/session-adapters/registry.js 中的 TARGET_TYPE_TO_ADAPTER_ID 把目标类型静态映射到适配器 id：plan 与 session 两类目标都路由到 dmux-tmux（第 8-17 行），与 Claude 历史会话（claude-history）、Codex worktree 会话（codex-worktree）、OpenCode 会话并列注册。select() 方法的逻辑是：若上下文中已显式指定 adapterId 则直接取用，否则遍历各适配器的 canOpen(target, context) 找到第一个能打开该目标的适配器（第 119-129 行）。

canOpen：什么样的目标算 dmux 会话

scripts/lib/session-adapters/dmux-tmux.js 的 canOpen 判据（第 51-62 行）有两类来源：

• plan 文件目标：目标是一个存在的 .json 文件（isPlanFileTarget，第 9-18 行）；
• 会话名目标：目标对应 .claude/orchestration/<sessionName>/ 协调目录存在（isSessionNameTarget，第 20-27 行）。

也就是说，ECC 的 dmux 编排会话状态落在 .claude/orchestration/ 下的按会话名分目录的结构里，open() 返回的 getSnapshot() 会调用 collectSessionSnapshot（实现在 scripts/lib/orchestration-session.js，内部通过 tmux list-panes -t <sessionName> 枚举窗格，并把窗格信息与协调目录下的 worker 记录对齐），再交给归一化函数。

归一化：从窗格原始数据到 ecc.session.v1

scripts/lib/session-adapters/canonical-session.js 中的 normalizeDmuxSnapshot（第 426-470 行）把原始数据映射成规范快照：

• 每个 worker 的 runtime.kind 固定为 tmux-pane，并携带窗格的 currentCommand、pid、active、dead；
• worker 的 branch/worktree 直接取自 worker 状态文件——这与上文"每窗格一个 worktree"的实战模式形成闭环：并行改动被 worktree 隔离，快照里能看到每个 worker 落在哪个分支和 worktree 上；
• 会话级 state 由 deriveDmuxSessionState（第 132-160 行）按规则推导：sessionActive 为真 → active；无 worker → missing；存在 failed/error → failed；全部 completed/succeeded/success/done → completed；其余 → idle。
• worker 级 health 由 deriveWorkerHealth（第 77-96 行）推导：running 状态下若窗格已死记为 degraded；状态更新时间超过 5 分钟阈值（STALE_THRESHOLD_MS = 5 * 60 * 1000，第 69 行）记为 stale——这为"窗格无响应"这类故障提供了机器可读的信号。

字段约束由 validateCanonicalSnapshot（第 162-263 行）强制校验，包括 aggregates.workerCount 必须等于 workers.length、各计数 map 必须与 worker 实际状态一致等。这份契约的权威说明见 docs/SESSION-ADAPTER-CONTRACT.md，其中给出了完整的 dmux-tmux 快照示例、session.state/worker.state 的取值语义，以及版本策略（schemaVersion 是唯一兼容门槛，破坏性变更必须升版）。

持久化：state store 优先，JSON 文件兜底

persistCanonicalSnapshot（第 388-424 行）的落盘策略是：先尝试 scripts/lib/state-store 的写接口；state store 不可用时回退到 JSON 文件记录器，路径为 <recordingDir>/<adapterId>/<sessionId>.json，其中 recordingDir 的解析顺序是显式参数 → 环境变量 ECC_SESSION_RECORDING_DIR → 系统临时目录下的 ecc-session-recordings（resolveRecordingDir，第 265-275 行）。回退记录器"最新快照原地替换、历史只追加有变化的快照"，避免轮询式读取撑爆历史（契约文档"Recording Fallback Behavior"一节有同描述）。CLI 侧入口为 scripts/session-inspect.js 与 scripts/orchestration-status.js。

测试佐证

上述行为的测试覆盖在 tests/lib/session-adapters.test.js：它直接引入 normalizeDmuxSnapshot、createDmuxTmuxAdapter、createAdapterRegistry 与 inspectSessionTarget，构造规范快照做字段校验与聚合一致性断言；tests/scripts/orchestration-status.test.js 则覆盖编排状态输出。若你要验证"我按文档操作后的会话状态确实能被 ECC 读取"，运行这些测试文件是最直接的依据。

适用前提与限制

• dmux 是外部 npm 包（npm install -g dmux），运行前提是本机装有 tmux；它不属于本仓库的构建产物，本文档只描述用法与 ECC 侧的集成点。
• dmux-tmux 适配器读取的协调结构是 .claude/orchestration/<sessionName>/ 目录与 tmux 会话名，跨 harness 时窗格内命令可以不同（claude/codex 等），但会话名与协调目录约定不变。
• 并行窗格数是 token 成本的线性放大，文档建议的 5～6 上限在长任务中尤需遵守。
• 快照契约当前版本为 ecc.session.v1；消费者不应假设所有适配器都有 tmux 窗格或 markdown 协调文件（契约文档"Consumer Expectations"的约束）。

小结

dmux-workflows 技能的骨架是"窗格 = 独立 Agent 会话，主会话 = 合并汇聚点"：用 n/m 两个键位管理生命周期，用五种模式（研究+实现、多文件特性、测试+修复、跨 harness、评审流水线）覆盖常见的并行拆解，用最佳实践和 worktree 隔离控制冲突与成本。ECC 在此之上补了一层机器可观测性——dmux-tmux 适配器把窗格与 worktree 状态归一化为 ecc.session.v1 快照并持久化，使并行编排从"人在 tmux 里盯"升级为"状态可查询、可校验、可回放"。想继续深入，建议按顺序阅读 技能文档 → 会话适配器契约 → dmux-tmux 适配器实现 → session-adapters 测试。