knowledge-base/4 - Resources/Claude-Code/dmux 多Agent并行编排.md

created, type, tags, source

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

dmux 多Agent并行编排

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

相关笔记：Autonomous Loops 自主循环模式、Everything Claude Code 完整指南

什么是 dmux

tmux-based 的 AI agent 面板管理工具：

• 按 n 创建新面板 + 输入 prompt
• 按 m 合并面板输出到主会话
• 支持：Claude Code、Codex、OpenCode、Cline、Gemini、Qwen

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

快速开始

# 启动 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 隔离：

# 创建隔离 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。

使用方式

# 干跑 (只打印计划)
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 格式

{
  "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 中未提交的文件时（本地脚本、草稿计划等）：

{
  "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." }
  ]
}

查看编排状态

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

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

---

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

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

{
  "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."
    }
  ]
}

# 执行
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

{
  "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 完整指南