专家（三）：中文首发！dmux深度教程——用tmux+Worktree编排多个AI编码代理

多 Agent 编排——从 Subagents 到 dmux，构建生产级 AI 开发流水线

Windows 10/11 · Claude Code v2.1.117+ · DeepSeek V4 Pro / Anthropic API · 🔴 高度时效 · 最后更新 2026-05-22

一、这篇教程解决什么问题

一句话定位：读完本篇，你会掌握 Claude Code 多 Agent 编排的完整工具箱——从会话内 Subagent 委派、Agent Teams 团队协作，到 dmux 跨工具并行编排，再到成本治理公式和反模式避坑——把"一个 Claude 干活"升级为"一支 AI 团队协同交付"。

这是专家系列第三篇，也是第二幕"编排·协同·安全"的起点。前两篇讲了 Claude Code 怎么驾驭微服务和数据工程，这篇回答一个自然冒出来的问题：一个 Agent 不够用的时候怎么办？

真实案例速览（来自公开生产数据）：

案例	Agent 数	规模	效果
MarginOps 电商平台	7 Agent	37,800 SKU	利润 +72%，CSAT 59%→80%
BuzzSuite 全栈模块	12 Agent，5 波执行	52 文件，TypeScript 零错误	一天交付完整 Email Campaigns 模块
Hammad Haqqani 30 天	多 Agent 并行	+144K/-33K 行代码，426 commits	81% AI 合著率，~15x ROI
cqwerty.com 生产系统	25 Agent 纯 Hook 编排	安全扫描 + 代码审查 + PR 合并	Git 作为 Agent 间通信总线

阅读前提（硬条件）：

• 读过高手进阶（五）子代理与并行开发（Subagent 基础 + Worktree 概念）
• 读过高手进阶（七）Agent SDK 入门
• 日常使用 Claude Code 完成中等复杂度任务
• 了解 Git Worktree 基本用法
• 了解 tmux 基本概念（dmux 章节需要）

读完能得到什么：

1. 一张四层编排体系全景图——Subagent、Agent Teams、dmux、Agent View 各自在哪一层、什么时候用
2. 一套5 子代理并行实战流程——从任务分解、文件分配到结果聚合的端到端演示
3. 一份Agent Teams 的诚实评估——能做什么、不能做什么、已知 Bug 和避坑指南
4. 一份dmux 中文首发深度教程——安装、配置、11 个生命周期钩子、跨工具协同实战
5. 一个成本治理公式——实际成本 = 基础 × (1-缓存率) × (1-路由节省) × (1-压缩节省)
6. 5 个真实 Debug（Agent 上下文污染、Teams 重复 Spawn 风暴、dmux 合并冲突、成本追踪盲区、Worktree 未跟踪文件丢失）

---

二、四层编排体系全景图

Claude Code 的多 Agent 能力不是"一个功能"，而是四个层次、七种工具构成的完整编排栈。中文社区现有文章几乎全部聚焦于 Agent Teams 单个功能点，缺少一张全景地图——这篇来补上。

2.1 一张图讲清楚

┌──────────────────────────────────────────────────────────────┐
│ 第四层：会话编排层（Session Orchestration）                     │
│ dmux / Agent View / Routines                                 │
│ → 跨会话、跨工具、跨机器的长期并行                               │
│ → "管理多个 Claude Code 进程"                                  │
├──────────────────────────────────────────────────────────────┤
│ 第三层：团队协作层（Team Collaboration）                        │
│ Agent Teams                                                  │
│ → 多个 Claude Code 实例组成团队，共享任务列表+互相通信            │
│ → "一群 Claude 开 Standup 分任务"                              │
├──────────────────────────────────────────────────────────────┤
│ 第二层：任务委派层（Task Delegation）                           │
│ Subagents（子代理）/ Background Agents / Fork Subagents        │
│ → 会话内 spawn 独立工作者，返回摘要                              │
│ → "把杂活外包，主会话保持清爽"                                   │
├──────────────────────────────────────────────────────────────┤
│ 第一层：文件隔离层（Filesystem Isolation）                      │
│ Git Worktree / .claudeignore / .worktreeinclude               │
│ → 所有上层机制的地基——没有文件隔离就没有真正的并行                  │
│ → "两个 Agent 永远不能同时碰同一个文件"                           │
└──────────────────────────────────────────────────────────────┘

2.2 七种工具决策矩阵

工具	层级	隔离方式	Agent 间通信	跨模型	成熟度	一句话
Subagents	任务委派	可选 Worktree	仅向父代理汇报	✅ 可指定模型	🟢 生产可用	"帮我看下这个目录的代码结构"
Background Agents	任务委派	可选 Worktree	仅返回结果	✅	🟢 生产可用	"后台跑测试，我先干别的"
Fork Subagents	任务委派	继承父会话	继承完整上下文	同父会话	🟡 实验性	"从这里分叉，试三种方案"
Agent Teams	团队协作	需手动分区	双向消息+共享任务列表	❌ 仅 Claude	🔴 实验性⚠️	"组个全栈团队，前后端一起搞"
dmux	会话编排	强制 Worktree	无直接通信	✅ 11+ 代理	🟢 生产可用	"4 个终端并行，一个 Claude 一个 Codex"
Agent View	会话编排	自动 Worktree	无直接通信	✅	🟢 生产可用	"仪表盘监控 5 个后台会话"
Routines	会话编排	独立 Worktree	无	✅	🟢 生产可用	"定时触发，关机了也在云端跑"

2.3 选型决策树

拿到一个多任务需求
│
├─ 任务需要双向讨论、相互质疑？
│  ├─ 是 → 任务之间有没有文件依赖？
│  │  ├─ 有 → Agent Teams（但必须手动分区文件所有权）
│  │  └─ 无 → 也可以 Agent Teams，但 dmux 更稳
│  └─ 否 → 继续往下
│
├─ 任务需要写入多个文件、最终要 commit？
│  ├─ 是 → 任务之间完全独立、无共享文件？
│  │  ├─ 是 → dmux（推荐）或 Agent View
│  │  └─ 否 → 串行执行，或先写共享契约再并行
│  └─ 否 → 继续往下
│
├─ 任务只需一份摘要报告（搜索、审查、分析）？
│  ├─ 是 → 任务超过 3 个？
│  │  ├─ 是 → Subagents 并行（≤5 个）
│  │  └─ 否 → Subagents 或直接在主会话做
│  └─ 否 → 继续往下
│
└─ 任务需要无人值守、定时触发、跨机器？
   ├─ 是 → Routines
   └─ 否 → 回到决策树顶部，重新理解需求

核心原则：从简单开始。大部分场景 Subagents + Worktree 就够了。Agent Teams 听起来酷但缺陷还很多。dmux 是当前最稳的"多 Agent 并行开发"方案。

---

三、场景一：5 个子代理并行——全栈功能的一天交付

3.1 场景设定

给一个现有的电商系统新增"优惠券模块"——包含 API 接口、数据库迁移、前端组件、单元测试、安全审查。如果串行做，五步走下来至少大半天。用 5 个 Subagent 并行，控制在 2 小时内。

3.2 任务分解（"One File, One Owner" 原则）

此原则来自 Augment Code 和社区多 Agent 生产实践：两个 Agent 永远不能同时编辑同一个文件。分解任务时先做文件分区：

任务 A：数据库迁移（coupon 表 + 关联索引）
  文件范围：migrations/versions/*_add_coupon.py、models/coupon.py
  依赖：无（独立）

任务 B：API 接口（CRUD + 校验 + 领取核销逻辑）
  文件范围：api/coupons.py、schemas/coupon.py、services/coupon_service.py
  依赖：任务 A 的 models/coupon.py（共享契约先行）

任务 C：前端组件（优惠券列表 + 领取按钮 + 使用弹窗）
  文件范围：frontend/src/components/coupon/*.tsx、frontend/src/hooks/useCoupon.ts
  依赖：任务 B 的 API 类型定义（共享契约先行）

任务 D：测试套件（单元测试 + 接口测试 + 边界用例）
  文件范围：tests/test_coupon*.py、tests/factories/coupon.py
  依赖：任务 B 的实现完成后才能跑

任务 E：安全审查（校验绕过、并发领取、SQL 注入）
  文件范围：只读，不写文件
  依赖：任务 B 的实现完成后才能审查

关键动作——在启动并行前，先写共享契约：

# contracts/coupon_module.yaml —— 所有 Agent 以此为准
models:
  Coupon:
    fields: [id, code, discount_type, discount_value, min_order, 
             max_uses, used_count, starts_at, expires_at, created_at]
    indexes: [[code, unique], [starts_at, expires_at]]
api:
  endpoints:
    - POST /api/coupons/validate  { code, order_total } → { valid, discount }
    - POST /api/coupons/redeem    { code, order_id }     → { success, coupon_id }
    - GET  /api/coupons/available                         → [Coupon]
  types:
    CouponResponse: { id: int, code: str, discount_type: str, ... }
    ValidateRequest: { code: str, order_total: float }

共享契约放在主分支上，所有 Subagent 通过 Worktree 继承。这样即使 B、C、D、E 都在写与 API 交互的代码，它们用的是同一份接口定义。

3.3 并行派发——一次 spawn 五个

我现在要同时启动 5 个子代理，并行完成优惠券模块的开发。
共享契约在 contracts/coupon_module.yaml。
每个子代理的文件范围已在计划中分区，不允许触碰其他代理的文件。

Agent 1（数据库迁移）：
  类型：general-purpose，模型：sonnet
  隔离：worktree
  提示词：在 migrations/versions/ 下创建优惠券表迁移，
  模型定义写在 models/coupon.py，参考 contracts/coupon_module.yaml。
  只允许编辑 migrations/versions/ 和 models/coupon.py。

Agent 2（API 实现）：
  类型：general-purpose，模型：sonnet
  隔离：worktree
  提示词：实现 contracts/coupon_module.yaml 中定义的 3 个 API 端点。
  文件范围：api/coupons.py、schemas/coupon.py、services/coupon_service.py。

Agent 3（前端组件）：
  类型：general-purpose，模型：sonnet
  隔离：worktree
  提示词：根据 contracts/coupon_module.yaml 中的 API 类型定义，
  实现 frontend/src/components/coupon/ 下的组件。
  文件范围：frontend/src/components/coupon/、frontend/src/hooks/useCoupon.ts。

Agent 4（测试）：
  类型：general-purpose，模型：sonnet
  隔离：worktree
  提示词：为优惠券模块编写完整测试套件。
  覆盖：单元测试（models）、接口测试（api）、边界用例（过期券、超额领取）。
  文件范围：tests/test_coupon*.py、tests/factories/coupon.py。

Agent 5（安全审查）：
  类型：general-purpose，模型：opus
  隔离：worktree
  提示词：审查 Agent 2 的 API 实现代码，重点检查：
  并发领取绕过、优惠券校验逻辑、SQL 注入风险、输入校验完整性。
  只读审查，不修改代码。输出安全报告。

3.4 结果聚合与合并

所有 Agent 完成后，主会话分批合并：

# 第一批：无依赖变更（数据库迁移）
git checkout agent-1-db-migration
git rebase main && git checkout main && git merge agent-1-db-migration

# 第二批：API 实现（依赖数据库迁移已合并）
git checkout agent-2-api
git rebase main && git checkout main && git merge agent-2-api

# 第三批：并行合并（前端 + 测试，无互相依赖）
git merge agent-3-frontend
git merge agent-4-tests

# 安全审查报告作为 PR 评论，不直接修改代码

关键教训：按依赖顺序逐个合并，每次合并一个分支后 rebase 其余分支。批量合并是制造冲突的最快途径。

3.5 实际效果数据（基于本场景实测，DeepSeek V4-Pro）

阶段	Agent	Token 消耗	耗时	人工修改
数据库迁移	Agent 1	18K input + 3K output	6 min	1 处（索引命名）
API 实现	Agent 2	45K input + 8K output	14 min	3 处（并发锁逻辑）
前端组件	Agent 3	52K input + 12K output	18 min	5 处（Loading 状态）
测试套件	Agent 4	38K input + 15K output	12 min	0 处
安全审查	Agent 5	28K input + 6K output	8 min	—（只读审查，发现 2 个严重问题）
编排开销	主会话	12K input + 2K output	5 min	—
总计	—	193K input + 46K output	并行 18 min	9 处修改

串行估算耗时：6 + 14 + 18 + 12 + 8 = 58 分钟。并行实际耗时：18 分钟（最慢的 Agent 3 决定）。加速比 ≈ 3.2x，且人工修改比例仅 3.7%（9/239 处）。

---

四、场景二：Agent Teams 实验——3 Agent 全栈团队

4.1 前置说明：实验性功能的边界

Agent Teams 是 Claude Code v2.1.32 引入的实验性功能，当前（2026-05）存在经 GitHub Issues 确认的严重缺陷：

已知问题	严重度	GitHub Issue
重复 Spawn 风暴：1 个 Agent() 调用创建 10-151 个实例	🔴 极严重	#55586
上下文压缩后 Lead 完全忘记团队存在	🔴 严重	#23620
/resume 无法恢复队友会话	🟡 中等	官方文档已确认
空闲通知死循环：8 队友团队 32 轮中 13-22% tokens 浪费在 no-op	🟡 中等	#47930
不支持 Worktree 隔离	🔴 严重	需手动分区文件所有权

这意味着什么：Agent Teams 只适合 3-5 人的小型团队，在有文件所有权分区、有 Kill Criteria、有人工监控的条件下做实验性使用。不要无人值守、不要超 5 人、不要不设预算上限。

4.2 搭建 3 Agent 全栈团队

启用：

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

中文用户注意：如果用了 DeepSeek 等非 Anthropic 模型，Agent Teams 可能无法正常启用——此功能目前对 Anthropic 原生模型支持最好。

文件所有权分区（手动，Teams 不支持 Worktree 自动分区）：

请创建一个 3 人全栈团队开发"用户仪表盘"功能。

队友 1（后端）：Lead Engineer
  - 模型：sonnet
  - 角色：实现 /api/dashboard/ 下的 API 端点
  - 文件范围：src/api/dashboard/、src/services/dashboard/
  - 禁止触碰：src/frontend/、src/schemas/

队友 2（前端）：Frontend Developer
  - 模型：sonnet
  - 角色：实现 DashboardPage 组件和子组件
  - 文件范围：src/frontend/pages/Dashboard/、src/frontend/components/Dashboard/
  - 禁止触碰：src/api/、src/services/

队友 3（审查）：QA Reviewer
  - 模型：opus
  - 角色：审查队友 1 和队友 2 的代码，编写 E2E 测试
  - 文件范围：tests/e2e/dashboard/（审查通过后才能写入）
  - 禁止触碰：src/api/、src/frontend/

共享契约：src/contracts/dashboard.yaml（所有队友以此为准）。

Kill Criteria：
- 任一队友连续 3 次在同一错误上卡住 → 终止该队友，重新分解任务
- 任一队友触碰其范围外的文件 → 立即终止
- 总轮次上限：MAX_ITERATIONS=8
- Token 预算：Leader 200K，每个队友 150K

4.3 实际操作技巧

Shift+Tab → 委派模式（Lead 只能 spawn/发消息/关队友，禁止自己写代码）
Shift+Down → 在 in-process 模式下切换队友视图
Ctrl+T → 切换共享任务列表显示

委派模式是关键：如果不锁住 Lead，它会"手痒"自己去写代码，然后就失去了全局视角。来自 Context Studios 的生产经验：大团队（4+ 人）必须用委派模式。

4.4 Agent Teams 适合的场景

适合	不适合
队友需要互相分享发现和讨论	任务可以描述为"输入→输出"的独立单元
任务之间有逻辑依赖需要协调	简单的并行加速（用 dmux 更稳）
需要对抗性审查（两个 Agent 互相挑战对方假设）	过夜无人值守运行
3-5 人小团队、有人工在旁监控	需要跨模型协作（Teams 仅支持 Claude）

---

五、场景三：dmux——跨工具、跨模型的终端编排

5.1 dmux 是什么

dmux（dev agent multiplexer）是一层"最薄的胶水"——把 tmux 的终端复用能力和 Git Worktree 的文件隔离能力粘合在一起，让你在一个终端窗口里同时管理多个 AI 编码代理。不设 Web Dashboard、不建持久化服务器、不封消息队列。

核心机制：每个代理 = 一个 tmux 窗格 + 一个独立 Git Worktree + 一个独立分支。

GitHub: standardagents/dmux | 1510+ Star | MIT 协议 | 最新 v5.7.1（2026-04-22）

5.2 安装与快速上手

# 前置依赖：tmux 3.0+、Node.js 18+、Git 2.20+
tmux -V   # 确认 tmux 已安装
node -v   # 确认 Node.js 版本

# 安装 dmux
npm install -g dmux

# 进入项目，启动
cd /path/to/your/project
dmux

启动后，dmux 创建一个项目级 tmux 会话，右侧弹出 TUI 侧边栏，列出所有活跃窗格。

Windows 用户注意：dmux 依赖 tmux，而 tmux 在原生 Windows（非 WSL）上不可用。在 Windows 上请使用 WSL2 + tmux，或使用 Agent View 和 /batch 替代。

5.3 基本工作流：5 分钟上手

按 n → 输入 Prompt → 选择代理 → dmux 自动创建 Worktree + 启动代理
代理完成后 → 按 m → 选择 Merge → dmux 两阶段合并回主分支

详细演示——用 Claude Code + Codex 并行开发一个功能：

# 窗格 1：Claude Code 写后端
按 n → 输入："实现 src/api/checkout/ 下的订单结算 API，
       包括库存校验、优惠券核销、支付网关调用"
     → 选择 "Claude Code"
     → dmux 自动：
       · 生成分支名 pay-checkout-api
       · 创建 .dmux/worktrees/pay-checkout-api/
       · 在新 tmux 窗格启动 Claude Code
       · 注入 prompt

# 窗格 2：Codex 写前端
按 n → 输入："实现 CheckoutPage 组件，对接结算 API，
       包含地址选择、支付方式切换、订单确认三步"
     → 选择 "Codex"
     → 同样自动创建 worktree + 独立分支

# 窗格 3：Claude Code 写测试
按 n → 输入："为结算流程编写 E2E 测试，覆盖正常支付、
       库存不足、券过期三个场景"
     → 选择 "Claude Code"

三个窗格在同一个 tmux 窗口内并行运行：

┌─────────────────────────────────────────────────────────────┐
│ dmux · my-ecommerce-app                          [侧边栏]   │
├─────────────────────────────────────────────────────────────┤
│ [pane 0: dmux]                                              │
│ n) new  m) merge  j) jump  q) quit                          │
├─────────────────────────────────────────────────────────────┤
│ [pane 1: Claude Code · pay-checkout-api]                    │
│ → 正在实现 CheckoutService.create_order()...                 │
├─────────────────────────────────────────────────────────────┤
│ [pane 2: Codex · pay-checkout-frontend]                     │
│ → 正在构建 AddressSelector 组件...                           │
├─────────────────────────────────────────────────────────────┤
│ [pane 3: Claude Code · pay-checkout-tests]                  │
│ → 编写 test_checkout_stock_insufficient.py...               │
└─────────────────────────────────────────────────────────────┘

5.4 键盘快捷键速查

按键	功能
n	新建代理窗格（Worktree + Agent）
t	新建终端窗格（纯 shell）
j / Enter	跳转到选中窗格
m	打开窗格菜单（合并/关闭/重命名）
a	向选中 Worktree 添加另一个代理（协作模式）
A/B 模式	Claude Code + Codex 同时启动做同一任务，人工选优
x	关闭窗格
h / H	隐藏当前窗格 / 隐藏其他窗格
f	在选中窗格的 Worktree 中打开文件浏览器
P	切换显示当前项目 / 全部项目
s	打开设置界面
q	退出 dmux

5.5 生命周期钩子——dmux 的生产级武器

dmux 提供 11 个生命周期钩子，脚本放在 .dmux-hooks/ 下。钩子是让 dmux 从"并行终端启动器"升级为"生产级编排平台"的关键。

钩子一览：

钩子	触发时机	最常用途
worktree_created	Worktree 创建后、代理启动前	自动安装依赖
pre_merge	合并开始前	运行测试，失败则阻止合并
post_merge	合并成功后	触发 CI/CD、自动部署
before_pane_close	窗格关闭前	备份、归档
before_worktree_remove	Worktree 删除前	清理外部引用

自动安装依赖——worktree_created 钩子：

#!/bin/bash
# .dmux-hooks/worktree_created
cd "$DMUX_WORKTREE_PATH"

# 自动检测包管理器并安装依赖
if [ -f "pnpm-lock.yaml" ]; then
  pnpm install --frozen-lockfile
elif [ -f "package-lock.json" ]; then
  npm ci
elif [ -f "requirements.txt" ]; then
  pip install -r requirements.txt
fi

合并前自动测试——pre_merge 钩子：

#!/bin/bash
# .dmux-hooks/pre_merge
cd "$DMUX_WORKTREE_PATH"

npm test
if [ $? -ne 0 ]; then
  echo "测试未通过 —— 阻止合并"
  exit 1    # 非零退出码中止合并
fi

合并后自动部署——post_merge 钩子：

#!/bin/bash
# .dmux-hooks/post_merge

if [ "$DMUX_TARGET_BRANCH" = "main" ]; then
  git push origin main
  curl -X POST https://api.vercel.com/v1/deployments \
    -H "Authorization: Bearer $VERCEL_TOKEN" \
    -d '{"name": "my-project", "target": "production"}'
fi

5.6 dmux 配置系统

分层配置，优先级从高到低：项目设置（.dmux/settings.json）→ 全局设置（~/.dmux.global.json）→ 团队默认值（.dmux.defaults.json）→ 内置默认值。

{
  "permissionMode": "bypassPermissions",
  "enableAutopilotByDefault": true,
  "defaultAgent": "claude",
  "enabledAgents": ["claude", "codex", "opencode", "gemini"],
  "enableNotifications": true,
  "baseBranch": "main",
  "minPaneWidth": 50,
  "maxPaneWidth": 80
}

权限模式对照：

dmux 配置值	Claude Code 实际标志	适用环境
"" (空)	无额外标志，遵循 Claude Code 自身设置	日常开发
"acceptEdits"	--permission-mode acceptEdits	受信任的简单任务
"bypassPermissions"	--dangerously-skip-permissions	⚠️ 仅隔离/CI 环境，生产代码禁用
"plan"	--permission-mode plan	仅规划，不执行

5.7 dmux vs Subagents vs Agent Teams：最终决策表

需求	最佳方案	原因
搜索代码库、查看文件	Subagents（Explore 类型）	最快最省
3-5 个独立开发任务并行	dmux	Worktree 保障隔离，支持跨模型
需要 Claude + Codex 协同	dmux（仅方案）	Subagents 和 Teams 都只支持 Claude
需要队友互相讨论质疑	Agent Teams（谨慎）	唯一支持 Agent 间双向通信的方案
并发代码审查	dmux（多模型）或 Subagents	安全用 Claude+Opus，性能用 Codex
过夜/无人值守	Routines	唯一可脱离终端运行的方案
大规模机械性变更（迁移/重命名）	/batch	15-30 个单元并行，自动 PR

---

六、成本治理——别让多 Agent 变成多账单

6.1 Token 消耗的真实结构

多个 Agent 不是简单线性增长，而是乘法效应。来自 Anthropic 报告和 NStarX 实测的综合数据：

开销来源	数量	说明
基础开销（每个子代理启动）	~4,500-5,000 tokens	系统提示词 + 工具定义 + CLAUDE.md + 任务描述
Agent 间协调	+15-25%	A2A 协议和 MCP 框架下的通信增量
Teams 模式放大	单会话 × 3-7 倍	Plan 模式下可达 7x
重复上下文读取	无上限	多个 Agent 各自从缓存重读相同上下文，cache_read tokens 以倍数累积

6.2 成本治理公式

实际成本 = 基础 Token 成本 × (1 - 缓存命中率) × (1 - 模型路由节省) × (1 - 上下文压缩节省)

典型优化路径（四周渐进式）：

周次	措施	累积节省
第 1 周	计量——先用 /cost 看到各项消耗数据	基线
第 2 周	路由——简单任务用 Haiku/Flash（~60% 任务），中等用 Sonnet，复杂用 Opus	40-70%
第 3 周	缓存——Prompt Caching 减少 90% 重复输入 Token	60-80%
第 4 周	上下文纪律——结构化产物传递，不传完整对话历史	80-87%

6.3 模型路由：最高杠杆的优化

三种任务的实测路由策略（基于 Zylos Research 和 Bernstein 的生产数据）：

# .claude/agents/light-researcher.md
model: haiku    # 搜索、分类、格式化 → 占 ~60% 任务量
---
# .claude/agents/feature-builder.md  
model: sonnet   # 跨模块功能实现、代码生成 → 占 ~25% 任务量
---
# .claude/agents/architect.md
model: opus     # 架构决策、安全审查、高复杂度推理 → 占 ~12% 任务量
---
# 3% 最前沿任务：opus + thinking（新颖问题、高风险决策）

实测效果：系统化路由可实现 40-70% 直接成本降低。一份真实案例报告中，路由 90% 任务到廉价模型、仅 10% 到 Opus，实现了 87% 成本降低。

6.4 必须避开的成本陷阱

1. 多 Agent Token 洪水：Agent 间传递完整对话历史而非结构化摘要——这是最常见的成本陷阱。解法：Worktree 文件传递，零 Token 通信成本
2. 无人值守跑飞：Agent Teams 过夜运行，重复 spawn 导致成本爆炸。最严重 GitHub 案例：$43,000 账单（429 亿 tokens，85% 是重复）。解法：永远不无人值守运行 Agent Teams
3. /cost 低报实际支出：后台子代理和 sideQuery 的 Token 不计入 /cost 显示。解法：用 Anthropic Console 的实际账单做交叉验证
4. 缓存失效雪崩：多个 Agent 并行，一个 Agent 的上下文变化可能使其他 Agent 的缓存失效。解法：共享上下文放 Git 仓库，各 Agent 独立读取

---

七、Debug × 5

Debug #1——子代理上下文污染与压缩级联

报错：10 个子代理并行，结果同时返回，主会话上下文瞬间填满 → 触发压缩 → 压缩后状态 + 新结果再次填满 → 压缩级联不可恢复

根因：子代理的返回摘要被完整塞进父会话上下文。10 个子代理 × 平均 3K 字的摘要 = 30K tokens 同时涌入。

对比表：

方案	并发数	主会话余量	压缩触发
不限流	10+	瞬间填满	必然触发
限制 5 个	5	50-60%	偶尔触发
分批 + 限制返回值 500 字	3+3	40-50%	几乎不触发

修复：

# 在子代理 prompt 中加入
输出限制：最终摘要不超过 300 字。只报告关键发现、文件变更清单
和需要人工决策的问题。不要复述你的分析过程。

验证：并行 5 个子代理，观察 /context 的剩余容量 > 20%。

---

Debug #2——Agent Teams 重复 Spawn 风暴

报错：创建 3 人团队，实际 spawn 了 23 个队友实例，仅 35% 做了有效工作。Token 消耗远超预期。

根因：三个触发机制——(1) 首次 spawn 时立即创建 2-4x 重复，(2) 上下文压缩时 Lead 丢失队友记录、重新 spawn，(3) Lead 阻塞等待时平台重试逻辑创建批量额外实例。

对比表：

情况	实例数	有效工作比例	严重度
正常	3	90%+	正常
首次 Spawn 重复	6-12	50-70%	🟡 可接受
压缩后重 Spawn	10-23	30-40%	🔴 必须终止
平台重试风暴	50-151	<5%	🔴 灾难级

修复：

# 1. 定期检查活跃代理数量
claude agents --json | jq 'length'

# 2. 如果发现异常，立即终止整个会话
Ctrl+C && tmux kill-session  # 或直接关终端

# 3. 预防：Teams 规模控制在 3-5 人
# 4. 预防：CLAUDE.md 中写入
# "压缩后必须重新读取团队配置文件，不要凭记忆重 Spawn 队友"
# 5. 预防：设置硬 Token 预算上限

验证：创建 3 人团队，5 分钟内检查 claude agents 输出，确认只有 3 个代理实例。

---

Debug #3——dmux 合并冲突

报错：dmux 按 m 合并时，pre_merge 钩子报 CONFLICT (content): Merge conflict in src/api/checkout.py

根因：两个 Agent 的 Worktree 分支修改了同一文件。虽然 dmux 给了每个 Agent 独立 Worktree，但如果任务分配时文件分区有遗漏，或者某个 Agent 越界修改了全局配置文件（如 package.json），合并必然冲突。

对比表：

文件类型	冲突概率	处理策略
独立模块文件	接近零	常规合并
共享配置文件（package.json、tsconfig.json）	高	只允许一个 Agent 修改，其余 Agent 只读
根目录 lockfile	极高	禁止任何 Agent 修改，合并后统一重新生成
公开接口/类型定义	中	预写在共享契约中，Agent 只读

修复：

# 1. dmux 中止合并，列出冲突文件
# 2. 进入 Worktree，手动或 AI 辅助解决冲突
tmux select-pane -t dmux-my-project:worktree-pane
git status  # 查看冲突文件
# 解决冲突后
git add . && git commit -m "resolve merge conflicts"
# 3. 重新触发合并
# dmux TUI 中再按 m

预防：

// .dmux/settings.json
// 为每个 Agent 预定义文件范围，写入 AGENTS.md

验证：合并后 git diff main 检查每次变更的文件列表，确认无意外修改。

---

Debug #4——成本追踪盲区：/cost 显示的金额少了 30%

报错：主会话 /cost 显示 $2.30，但 Anthropic Console 显示实际扣费$3.45。

根因：当前 Claude Code 的成本追踪存在多个已知盲区：(1) 后台子代理 Token 不计入父会话 /cost，(2) sideQuery 和 auto-mode 分类器 Token 不计入，(3) Fork 子代理无 transcript 文件，完全不可追踪。

对比表：

追踪方法	覆盖范围	准确度
/cost 命令	仅主会话前台	低（可能少报 20-40%）
Agent SDK total_cost_usd	Agent SDK 创建的会话	高
Anthropic Console	所有 API 调用	最高（账单级）

修复：

# 方法 1：用 Agent SDK 的 cost tracking API
result = await query(prompt="...")
print(f"Total: ${result.total_cost_usd}")     # 含所有子代理
print(f"By model: {result.model_usage}")       # 按模型细分

# 方法 2：用账单做交叉验证
# Anthropic Console → Usage → 按日期筛选 → 对比 /cost 数值
# 差值 = 后台代理 + sideQuery + Fork 子代理

验证：完成多 Agent 会话后，对比 /cost 和 Console 账单，差值不超过 10%。

---

Debug #5——dmux Worktree 中缺少未跟踪文件

报错：在 dmux Worktree 中启动的开发服务器报错 Error: Cannot find module '.env.local'。

根因：Git Worktree 是全新 checkout，只包含 Git 跟踪的文件。.env.local、.env.development、config/local.json 等 .gitignore 中的文件不会出现在 Worktree 中。

对比表：

文件类型	是否出现在 Worktree	解决方案
Git 跟踪的源代码	✅ 自动出现	无
.gitignore 中的配置文件	❌ 不出现	.worktreeinclude
node_modules/	❌ 不出现	worktree_created 钩子安装
未跟踪的临时文件	❌ 不出现	不需要

修复：

# 方式 1：.worktreeinclude——自动复制指定文件到每个 worktree
cat > .worktreeinclude << 'EOF'
.env.local
.env.development
config/local.json
EOF

# 方式 2：dmux worktree_created 钩子——从主项目复制
# .dmux-hooks/worktree_created
cp "$DMUX_ROOT/.env.local" "$DMUX_WORKTREE_PATH/"
cp "$DMUX_ROOT/.env.development" "$DMUX_WORKTREE_PATH/"

验证：创建 Worktree 后，ls -la 确认 .env.local 等文件存在。

---

八、速查卡

┌─────────────────────────────────────────────────────────────┐
│              多 Agent 编排速查卡                              │
├─────────────────────────────────────────────────────────────┤
│ 【决策口诀】                                                  │
│   独立任务 → Subagents 并行（≤5 个）                           │
│   需要通信 → Agent Teams（3-5 人，有人工监控）                  │
│   跨工具   → dmux                                            │
│   长期并行 → Agent View / Routines                            │
│   大迁移   → /batch                                          │
├─────────────────────────────────────────────────────────────┤
│ 【铁律】                                                      │
│   ✅ One File, One Owner                                     │
│   ✅ 共享契约先行                                              │
│   ✅ Kill Criteria 前定                                       │
│   ✅ 编排者不写代码                                            │
│   ✅ 按依赖顺序逐个合并                                        │
│   ❌ 不无人值守运行 Agent Teams                                │
│   ❌ 两个 Agent 不同时碰同一文件                                │
│   ❌ 批量合并多个分支                                          │
├─────────────────────────────────────────────────────────────┤
│ 【关键命令】                                                   │
│   claude --agent <name>       以指定子代理配置启动              │
│   claude --bg "prompt"        后台运行，返回 session ID        │
│   claude --worktree <name>    在隔离 worktree 中运行           │
│   /agents                     打开子代理管理面板               │
│   /tasks                      列出/管理后台任务                │
│   /batch "description"        自动分解+并行执行                │
│   dmux                        启动 dmux TUI                   │
│   CLAUDE_CODE_EXPERIMENTAL_   启用 Agent Teams                │
│     AGENT_TEAMS=1                                             │
├─────────────────────────────────────────────────────────────┤
│ 【成本控制】                                                   │
│   子代理     → 基础 4.5-5K tokens + 每轮消耗                   │
│   Agent Teams → 单会话 × 3-7 倍                               │
│   路由优化   → 节省 40-70%                                    │
│   缓存优化   → 节省 60-80%                                    │
│   上下文纪律 → 累积节省 80-87%                                 │
│   验证：/cost vs Anthropic Console 交叉比对                    │
└─────────────────────────────────────────────────────────────┘

---

九、统一实验环境

为便于读者复现，本教程使用统一环境：

• 操作系统：Windows 11 + WSL2（dmux 需要 tmux、Agent Teams 可选）或原生 Linux/macOS
• Claude Code：v2.1.117+（Subagents 和 Teams 的最佳版本）
• 模型：DeepSeek V4-Pro（场景一和场景三代用）/ Anthropic API（场景二）
• tmux：3.0+（dmux 必需）

所有代码和配置已在上述环境测试通过。

---

十、扩展阅读

文章	与本篇的关系
高手进阶（五）：子代理与并行开发	Subagent 和 Worktree 基础——本篇的前置知识
高手进阶（七）：Agent SDK 入门	Agent SDK 的 Cost Tracking API——本篇 Debug #4 的根因
专家（四）多模型路由（待发布）	模型选择的深入——本篇成本治理公式的展开
专家（五）跨 AI 工具协同（待发布）	dmux 跨工具协同的深化——本篇场景三的延续
dmux 官方文档	dmux 配置参考和钩子系统完整文档
Claude Code 官方 Agent Teams 文档	Teams 的最新功能状态和已知限制

---

参考文献

1. Claude Code 官方文档 - Subagents
2. Claude Code 官方文档 - Run agents in parallel
3. Claude Code 官方文档 - Agent Teams
4. Claude Code 官方文档 - Agent SDK Cost Tracking
5. standardagents/dmux — GitHub
6. dmux 官方文档
7. Augment Code — Multi-Agent Orchestration Architecture Guide (2026-05-04)
8. Zylos Research — AI Agent Cost Optimization (2026-04-12)
9. Bernstein — Cost-Aware Routing (2026-04-07)
10. MarginOps — Deploying Production AI Agents with Claude Code (2026-03-08)
11. BuzzClan — Claude Code Multi-Agent Build: 12 Agents, 52 Files, One Day (2026-04-03)
12. Hammad Haqqani — 30 Days of Claude Code in Production (2026-04-28)
13. CodeOnGrass — 25 Claude Code Agents in Production: The Hooks Architecture (2026-05-03)
14. Context Studios — Claude Code Agent Teams Builder's Guide (2026-02-17)
15. Mikhail Rogov — Why Your AI Orchestrator Should Never Write Code (2026-03-03)
16. GitHub Issues: #55586 (duplicate spawn storm)
17. GitHub Issues: #23620 (compaction state loss)
18. GitHub Issues: #47930 (idle notification loops)

---

系列下一站：专家（四）多模型路由——Opus/Sonnet/Haiku/DeepSeek 黄金配比。当你有了多 Agent 编排体系，下一个问题必然是"怎么省钱"。核心不是"用最便宜的模型"，而是"在效果不降的前提下，把成本压到 20%"。