---
created: "2026-04-06"
type: resource
tags: [resource, claude-code, AI-tools, dmux, multi-agent, parallel, orchestration, ECC]
source: "~/.claude/skills/dmux-workflows/SKILL.md"
---

# dmux 多Agent并行编排

> **平台限制：需要 tmux，仅 Linux/macOS 可用。Windows 不可用（除非使用 WSL）。**
> Windows 替代方案见 [[ECC 编排替代方案 (orchestrate 迁移)]]。

用 tmux 管理多个 AI agent 面板，每个面板跑独立 agent 会话，最后合并结果。ECC v1.10.0 中 `/ecc:orchestrate` 已标记为 legacy，底层的并行部分路由到此 skill。

相关笔记：[[Autonomous Loops 自主循环模式]]、[[Everything Claude Code 完整指南]]、[[ECC 编排替代方案 (orchestrate 迁移)]]、[[Autonomous Agent Harness 自主代理框架]]

## 什么是 dmux

tmux-based 的 AI agent 面板管理工具：
- 按 `n` 创建新面板 + 输入 prompt
- 按 `m` 合并面板输出到主会话
- 支持：Claude Code、Codex、OpenCode、Cline、Gemini、Qwen

安装：`https://github.com/standardagents/dmux`

## 快速开始

```bash
# 启动 dmux
dmux

# 创建面板 (按 n，输入 prompt)
# 面板1: "Implement auth middleware in src/auth/"
# 面板2: "Write tests for the user service"
# 面板3: "Update API documentation"

# 各面板独立运行
# 完成后按 m 合并
```

---

## 5 种工作模式

### 模式 1: Research + Implement (调研 + 实现)

```
面板1 (Research): "Research best practices for rate limiting in Node.js.
  Write findings to /tmp/rate-limit-research.md"

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

# 面板1完成后，合并到面板2的上下文
```

### 模式 2: Multi-File Feature (多文件并行)

```
面板1: "Create database schema and migrations for billing"
面板2: "Build billing API endpoints in src/api/billing/"
面板3: "Create billing dashboard UI components"

# 全部合并后在主面板做集成
```

### 模式 3: Test + Fix Loop (测试 + 修复)

```
面板1 (Watcher): "Run test suite in watch mode. Summarize failures."
面板2 (Fixer): "Fix failing tests based on error output from pane 1"
```

### 模式 4: Cross-Harness (跨工具)

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

### 模式 5: Code Review Pipeline (并行审查)

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

# 合并为单份报告
```

---

## Git Worktree 隔离

当并行任务可能编辑同一文件时，用 worktree 隔离：

```bash
# 创建隔离 worktree
git worktree add -b feat/auth ../feature-auth HEAD
git worktree add -b feat/billing ../feature-billing HEAD

# 各面板在不同 worktree 里工作
# 面板1: cd ../feature-auth && claude
# 面板2: cd ../feature-billing && claude

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

---

## ECC orchestrate-worktrees.js

ECC 提供的 worktree 编排辅助脚本，位于 `~/.claude/scripts/orchestrate-worktrees.js`。

### 使用方式

```bash
# 干跑 (只打印计划)
node ~/.claude/scripts/orchestrate-worktrees.js plan.json

# 只写编排文件
node ~/.claude/scripts/orchestrate-worktrees.js plan.json --write-only

# 执行 (创建 worktree + tmux session)
node ~/.claude/scripts/orchestrate-worktrees.js plan.json --execute
```

### plan.json 格式

```json
{
  "sessionName": "feature-auth",
  "baseRef": "HEAD",
  "launcherCommand": "claude -p \"$(cat {task_file})\"",
  "workers": [
    { "name": "backend-api", "task": "Implement auth API endpoints" },
    { "name": "frontend-ui", "task": "Build login UI components" },
    { "name": "tests", "task": "Write integration tests for auth" }
  ]
}
```

### 可用占位符

| 占位符 | 说明 |
|--------|------|
| `{worker_name}` | Worker 名称 |
| `{worker_slug}` | Worker slug |
| `{session_name}` | Session 名称 |
| `{repo_root}` | 仓库根目录 |
| `{worktree_path}` | Worktree 路径 |
| `{branch_name}` | 分支名 |
| `{task_file}` | 任务文件路径 |
| `{handoff_file}` | 交接文件路径 |
| `{status_file}` | 状态文件路径 |

### seedPaths：共享未提交文件

当 worker 需要访问主 checkout 中未提交的文件时（本地脚本、草稿计划等）：

```json
{
  "sessionName": "workflow-e2e",
  "seedPaths": [
    "scripts/orchestrate-worktrees.js",
    ".claude/plan/workflow-e2e-test.json"
  ],
  "launcherCommand": "bash {repo_root}/scripts/worker.sh {task_file}",
  "workers": [
    { "name": "seed-check", "task": "Verify seeded files are present." }
  ]
}
```

### 查看编排状态

```bash
node ~/.claude/scripts/orchestration-status.js plan.json
```

输出包含：session 活跃度、tmux 面板元数据、worker 状态、目标、交接摘要。

---

## 实际例子：smart-support 并行开发

### 例1：反馈功能三面板并行

```json
{
  "sessionName": "feedback-feature",
  "baseRef": "HEAD",
  "launcherCommand": "claude -p \"$(cat {task_file})\"",
  "workers": [
    {
      "name": "backend-api",
      "task": "In backend/app/feedback/, create models.py (Feedback SQLAlchemy model) and router.py (POST /api/feedback, GET /api/feedback/stats). Follow backend/app/replay/router.py patterns. Write tests in backend/tests/unit/test_feedback.py FIRST. Run pytest --cov=app."
    },
    {
      "name": "frontend-ui",
      "task": "In frontend/src/components/, create FeedbackButton.tsx (thumbs-up/down). onClick calls POST /api/feedback. Integrate into chat message component."
    },
    {
      "name": "docs-update",
      "task": "Update docs/ARCHITECTURE.md to add feedback module. Update docs/DEVELOPMENT-PLAN.md with feedback feature."
    }
  ]
}
```

```bash
# 执行
node ~/.claude/scripts/orchestrate-worktrees.js .claude/plan/feedback.json --execute

# 完成后合并
git merge feedback-feature/backend-api
git merge feedback-feature/frontend-ui
git merge feedback-feature/docs-update
```

### 例2：Code Review Pipeline

```json
{
  "sessionName": "review-pipeline",
  "baseRef": "HEAD",
  "launcherCommand": "claude -p --allowedTools 'Read,Grep,Glob' \"$(cat {task_file})\"",
  "workers": [
    { "name": "security", "task": "Review backend/app/ for security vulnerabilities. Write report to /tmp/security-review.md" },
    { "name": "performance", "task": "Review backend/app/ for performance issues. Write report to /tmp/perf-review.md" },
    { "name": "coverage", "task": "Analyze backend/tests/ for coverage gaps. Write report to /tmp/coverage-review.md" }
  ]
}
```

---

## 最佳实践

1. **只并行独立任务** -- 有依赖关系的不要并行
2. **清晰边界** -- 每个面板处理不同的文件或关注点
3. **策略性合并** -- 合并前先 review 面板输出
4. **用 worktree** -- 可能编辑同一文件时必须隔离
5. **控制面板数** -- 每个面板消耗 API token，建议不超过 5-6 个

## 互补工具对比

| 工具 | 功能 | 适用 |
|------|------|------|
| dmux | tmux 面板管理 | 并行 agent 会话 |
| Superset | 终端 IDE (10+ 并行) | 大规模编排 |
| Claude Code Task tool | 进程内子 agent | 会话内程序化并行 |
| orchestrate-worktrees.js | ECC worktree 编排 | 长时间/跨工具会话 |

## 故障排除

| 问题 | 解决 |
|------|------|
| 面板无响应 | `tmux capture-pane -pt <session>:0.<pane>` 检查 |
| 合并冲突 | 用 git worktree 隔离 |
| Token 消耗高 | 减少并行面板数 |
| tmux 未找到 | `brew install tmux` (macOS) / `apt install tmux` (Linux) |

## Related

- [[Autonomous Loops 自主循环模式]]
- [[Ralphinho RFC-DAG 编排模式]]
- [[Everything Claude Code 完整指南]]