272 lines
7.7 KiB
Markdown
272 lines
7.7 KiB
Markdown
---
|
||
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 完整指南]]
|