---
name: dmux-workflows
description: 使用dmux（AI代理的tmux窗格管理器）进行多代理编排。跨Claude Code、Codex、OpenCode及其他工具的并行代理工作流模式。适用于并行运行多个代理会话或协调多代理开发工作流时。
origin: ECC
---

# dmux 工作流

使用 dmux（一个用于代理套件的 tmux 窗格管理器）来编排并行的 AI 代理会话。

## 何时激活

* 并行运行多个代理会话时
* 跨 Claude Code、Codex 和其他套件协调工作时
* 需要分而治之并行处理的复杂任务
* 用户提到“并行运行”、“拆分此工作”、“使用 dmux”或“多代理”时

## 什么是 dmux

dmux 是一个基于 tmux 的编排工具，用于管理 AI 代理窗格：

* 按 `n` 创建一个带有提示的新窗格
* 按 `m` 将窗格输出合并回主会话
* 支持：Claude Code、Codex、OpenCode、Cline、Gemini、Qwen

**安装：** `npm install -g dmux` 或参见 [github.com/standardagents/dmux](https://github.com/standardagents/dmux)

## 快速开始

```bash
# Start dmux session
dmux

# Create agent panes (press 'n' in dmux, then type prompt)
# Pane 1: "Implement the auth middleware in src/auth/"
# Pane 2: "Write tests for the user service"
# Pane 3: "Update API documentation"

# Each pane runs its own agent session
# Press 'm' to merge results back
```

## 工作流模式

### 模式 1：研究 + 实现

将研究和实现拆分为并行轨道：

```
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."

# After Pane 1 completes, merge findings into Pane 2's context
```

### 模式 2：多文件功能

在独立文件间并行工作：

```
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"

# Merge all, then do integration in main pane
```

### 模式 3：测试 + 修复循环

在一个窗格中运行测试，在另一个窗格中修复：

```
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"
```

### 模式 4：跨套件

为不同任务使用不同的 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"
```

### 模式 5：代码审查流水线

并行审查视角：

```
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"

# Merge all reviews into a single report
```

## 最佳实践

1. **仅限独立任务。** 不要并行化相互依赖输出的任务。
2. **明确边界。** 每个窗格应处理不同的文件或关注点。
3. **策略性合并。** 合并前审查窗格输出以避免冲突。
4. **使用 git worktree。** 对于容易产生文件冲突的工作，为每个窗格使用单独的工作树。
5. **资源意识。** 每个窗格都消耗 API 令牌 —— 将总窗格数控制在 5-6 个以下。

## Git Worktree 集成

对于涉及重叠文件的任务：

```bash
# Create worktrees for isolation
git worktree add -b feat/auth ../feature-auth HEAD
git worktree add -b feat/billing ../feature-billing HEAD

# Run agents in separate worktrees
# Pane 1: cd ../feature-auth && claude
# Pane 2: cd ../feature-billing && claude

# Merge branches when done
git merge feat/auth
git merge feat/billing
```

## 互补工具

| 工具 | 功能 | 使用时机 |
|------|-------------|-------------|
| **dmux** | 用于代理的 tmux 窗格管理 | 并行代理会话 |
| **Superset** | 用于 10+ 并行代理的终端 IDE | 大规模编排 |
| **Claude Code Task 工具** | 进程内子代理生成 | 会话内的程序化并行 |
| **Codex 多代理** | 内置代理角色 | Codex 特定的并行工作 |

## ECC 助手

ECC 现在包含一个助手，用于使用独立的 git worktree 进行外部 tmux 窗格编排：

```bash
node scripts/orchestrate-worktrees.js plan.json --execute
```

示例 `plan.json`：

```json
{
  "sessionName": "skill-audit",
  "baseRef": "HEAD",
  "launcherCommand": "codex exec --cwd {worktree_path_sh} --task-file {task_file_sh}",
  "workers": [
    { "name": "docs-a", "task": "Fix skills 1-4 and write handoff notes." },
    { "name": "docs-b", "task": "Fix skills 5-8 and write handoff notes." }
  ]
}
```

该助手：

* 为每个工作器创建一个基于分支的 git worktree
* 可选择将主检出中的选定 `seedPaths` 覆盖到每个工作器的工作树中
* 在 `.orchestration/<session>/` 下写入每个工作器的 `task.md`、`handoff.md` 和 `status.md` 文件
* 启动一个 tmux 会话，每个工作器一个窗格
* 在每个窗格中启动相应的工作器命令
* 为主协调器保留主窗格空闲

当工作器需要访问尚未纳入 `HEAD` 的脏文件或未跟踪的本地文件（例如本地编排脚本、草案计划或文档）时，使用 `seedPaths`：

```json
{
  "sessionName": "workflow-e2e",
  "seedPaths": [
    "scripts/orchestrate-worktrees.js",
    "scripts/lib/tmux-worktree-orchestrator.js",
    ".claude/plan/workflow-e2e-test.json"
  ],
  "launcherCommand": "bash {repo_root_sh}/scripts/orchestrate-codex-worker.sh {task_file_sh} {handoff_file_sh} {status_file_sh}",
  "workers": [
    { "name": "seed-check", "task": "Verify seeded files are present before starting work." }
  ]
}
```

## 故障排除

* **窗格无响应：** 直接切换到该窗格或使用 `tmux capture-pane -pt <session>:0.<pane-index>` 检查它。
* **合并冲突：** 使用 git worktree 隔离每个窗格的文件更改。
* **令牌使用量高：** 减少并行窗格数量。每个窗格都是一个完整的代理会话。
* **未找到 tmux：** 使用 `brew install tmux` (macOS) 或 `apt install tmux` (Linux) 安装。