ECC 中的 DevFleet 多智能体编排：在隔离 worktree 中并行调度 Claude Code 代理的完整实战指南

DevFleet 是 ECC 仓库中面向并行编码任务的多智能体编排方案：它通过 MCP 接入独立运行的 DevFleet 服务器，把用户的一句话描述拆解为带依赖关系的任务 DAG，再逐个派发 Claude Code 代理到彼此隔离的 git worktree 中并行执行，并在完成后自动合并、读取结构化报告。本文以 docs/ja-JP/commands/devfleet.md 为骨架，结合仓库中的技能定义 skills/claude-devfleet/SKILL.md、MCP 注册表 mcp-configs/mcp-servers.json 与配套测试，完整讲解从环境接入、计划审批、派发监控到报告汇总的端到端操作，读完即可在 ECC 中跑通一套「计划 → 派发 → 监控 → 报告」的并行代理工作流。

DevFleet 是什么：并行的 Claude Code 代理编排

Claude DevFleet 用于编排并行的 Claude Code 代理。与单代理顺序执行不同，DevFleet 的核心设计是：

• 每个代理运行在隔离的 git worktree 中，拥有完整工具链，互不干扰；
• 任务之间以依赖 DAG 组织，满足依赖的任务自动触发后续任务；
• 代理完成时自动合并其 worktree 变更，冲突时保留在分支上供人工解决；
• 通过 MCP 工具暴露完整能力，供 Claude Code 等宿主直接调用。

在 ECC 仓库中，DevFleet 被声明为一项正式能力：agent.yaml 第 33 行将 claude-devfleet 列入装配的技能列表；manifests/install-modules.json 第 809 行将 skills/claude-devfleet 纳入安装模块；tests/ci/agent-yaml-surface.test.js 中的表面测试会校验 devfleet 技能入口的存在，保证装配面与测试面一致。

接入前提：DevFleet MCP 服务器

DevFleet MCP 服务器是独立项目，不随 ECC 打包分发。需要先自行安装并启动其服务端进程，再通过 MCP 接入宿主。

连接命令：

claude mcp add devfleet --transport http http://localhost:18801/mcp

在首次使用前，建议先确认监听 18801 端口的进程确实是你所安装的 DevFleet 二进制（对 localhost 上的 MCP 服务器做身份核对，属于本仓库安全实践的一部分，可参考 docs/ja-JP/SECURITY.md）。

ECC 同时把该服务器预注册进自己的 MCP 配置清单 mcp-configs/mcp-servers.json 的 devfleet 条目：

"devfleet": {
  "type": "http",
  "url": "http://localhost:18801/mcp",
  "description": "Multi-agent orchestration — dispatch parallel Claude Code agents in isolated worktrees. Plan projects, auto-chain missions, read structured reports."
}

该条目的描述与文档口径一致：多代理编排、隔离 worktree、自动链式任务、结构化报告。接入后，宿主即可调用 mcp__devfleet__* 前缀的工具。

核心执行流程

DevFleet 的整体流程可以概括为一次「计划 → 审批 → 派发 → 自动链式推进 → 报告」的循环：

用户描述项目
  → plan_project(prompt) → 任务 DAG 与依赖关系
  → 展示计划，获取批准
  → dispatch_mission(M1) → 代理在工作区中生成
  → M1 完成 → 自动合并 → M2 自动调度（依赖于 M1）
  → M2 完成 → 自动合并
  → get_report(M2) → 文件变更、完成内容、错误、后续步骤
  → 向用户报告总结

关键点在于：只有第一个任务（根任务）需要显式派发，其余任务在其依赖完成时自动派发，因为 plan_project 创建任务时统一携带 auto_dispatch=true。

标准工作流：计划 → 派发 → 监控 → 报告

1. 根据用户描述规划项目

调用 plan_project，将用户的自然语言描述交给 DevFleet 的 AI 分解为链式任务：

mcp__devfleet__plan_project(prompt="<用户描述>")

返回结果是一个包含链式任务的项目，需要向用户清晰展示：

• 项目名称和 ID
• 每个任务：标题、类型、依赖项
• 依赖关系 DAG（哪些任务阻塞了哪些任务）

2. 派发前等待用户批准

在派发前必须等待用户批准，除非用户已经明确说「开始吧」。将计划清晰呈现给用户后再进入下一步。

3. 派发第一个任务

找到 depends_on 为空的任务（即 DAG 根节点）并派发：

mcp__devfleet__dispatch_mission(mission_id="<first_mission_id>")

剩余任务会在其依赖项完成时自动派发（plan_project 创建时已设置 auto_dispatch=true）。注意：如果使用 create_mission 手动创建任务，必须显式设置 auto_dispatch=true 才会启用自动派发行为；否则任务停留在 draft 状态等待手动触发。

4. 监控进度

查看系统级概览：

mcp__devfleet__get_dashboard()

或检查特定任务：

mcp__devfleet__get_mission_status(mission_id="<id>")

对于长时间运行的任务，优先使用 get_mission_status 轮询（建议每 30～60 秒一次），而不是 wait_for_mission 阻塞等待——这样用户能持续看到进度更新。这与 skills/claude-devfleet/SKILL.md 中对 wait_for_mission 的说明一致：它会阻塞会话最长 timeout_seconds（默认 600 秒），适合短任务，长任务应轮询。

5. 读取已完成任务的报告

对每个达到终止状态（completed / failed / cancelled）的任务调用：

mcp__devfleet__get_report(mission_id="<mission_id>")

结构化报告包含七个字段：

字段	含义
files_changed	变更的文件清单
what_done	完成了什么
what_open	遗留的开放项
what_tested	测试过什么
what_untested	未测试的部分
next_steps	建议的后续步骤
errors_encountered	遇到的错误

向用户汇报时，应包含任务标题与 ID、变更文件、失败项与错误、以及下一步建议。

全部可用工具速查

DevFleet 通过 MCP 暴露如下工具（均以 mcp__devfleet__ 前缀调用）：

工具	用途
plan_project(prompt)	AI 将描述分解为具有 auto_dispatch=true 的链式任务
create_project(name, path?, description?)	手动创建项目，返回 project_id
create_mission(project_id, title, prompt, depends_on?, auto_dispatch?)	添加任务。depends_on 是任务 ID 字符串列表，例如 ["abc-123"]
dispatch_mission(mission_id, model?, max_turns?)	启动一个智能体（可指定模型与最大轮数）
cancel_mission(mission_id)	停止一个正在运行的智能体
wait_for_mission(mission_id, timeout_seconds?)	阻塞直到完成（长任务优先使用轮询）
get_mission_status(mission_id)	非阻塞地检查进度
get_report(mission_id)	读取结构化报告（变更文件、测试、错误、后续步骤）
get_dashboard()	系统概览：运行中的代理、统计、最近活动
list_projects()	浏览项目
list_missions(project_id, status?)	列出项目中的任务，可按状态过滤

其中手动建链时 depends_on 接受任务 ID 字符串列表，是构造 DAG 的主要手段；dispatch_mission 的 model? 与 max_turns? 允许按任务粒度定制运行模型和预算轮数。

并发控制与排队机制

DevFleet 默认最多同时运行 3 个代理，该值可通过 DEVFLEET_MAX_AGENTS 环境变量配置（见 skills/claude-devfleet/SKILL.md 的 Concurrency 一节）。

• 当所有槽位占满时，带 auto_dispatch=true 的任务会在 mission watcher 中排队，一旦有槽位空出便自动派发；
• 批量派发前，先调用 get_dashboard() 检查当前槽位可用性；
• 依赖关系形成 DAG，切勿创建循环依赖。

三种实战编排模式

skills/claude-devfleet/SKILL.md 给出了三种可直接套用的模式，覆盖从全自动到逐级审批的不同需求。

模式一：全自动（plan and launch）

1. plan_project(prompt="...") 得到带任务和依赖的计划；
2. 派发第一个任务（depends_on 为空的那个）；
3. 其余任务随依赖解决自动派发（均已带 auto_dispatch=true）；
4. 向用户汇报项目 ID 与任务数量，让用户知道启动了哪些内容；
5. 周期性轮询 get_mission_status 或 get_dashboard()，直到所有任务进入终止状态（completed / failed / cancelled）；
6. 对每个终止任务调用 get_report(mission_id=...)，汇总成功项，并单独指出失败任务的错误与后续步骤。

模式二：手动分步（逐步控制）

1. create_project(name="My Project") 获得 project_id；
2. 先创建根任务：create_mission(project_id=project_id, title="...", prompt="...", auto_dispatch=true)，记录 root_mission_id；
3. 对每个后续任务：create_mission(project_id=project_id, title="...", prompt="...", auto_dispatch=true, depends_on=["<root_mission_id>"])；
4. 对第一个任务 dispatch_mission(mission_id=...) 启动整条链；
5. 完成后 get_report(mission_id=...) 读取结果。

该模式的关键是：手动创建任务时若希望依赖满足后自动触发，必须显式 auto_dispatch=true，否则任务保持 draft。

模式三：顺序执行 + 人工审查（sequential with review）

适合「先实现、再审查」的受控流水线：

1. create_project(name="...") 获得 project_id；
2. create_mission(project_id=project_id, title="Implement feature", prompt="...") 获得 impl_mission_id；
3. dispatch_mission(mission_id=impl_mission_id)，用 get_mission_status 轮询至完成；
4. get_report(mission_id=impl_mission_id) 审查实现结果；
5. 创建审查任务 create_mission(project_id=project_id, title="Review", prompt="...", depends_on=[impl_mission_id], auto_dispatch=true)——由于依赖已满足，它会自动启动。

使用指南与最佳实践

结合 docs/ja-JP/commands/devfleet.md 与技能文件，以下是完整的使用纪律：

• 派发前确认计划：除非用户明确说「开始吧」，否则派发前始终先展示计划并取得批准；
• 报告带上下文：报告状态时始终包含任务标题与 ID；
• 失败先读报告：任务失败后，重试前先读取其报告以理解错误，而不是盲目重试；
• 注意并发槽位：代理并发数可配置（默认 3），超额任务排队，空闲槽位自动派发；批量派发前用 get_dashboard() 确认槽位；
• DAG 无环：依赖关系形成 DAG，绝不创建循环依赖；
• worktree 合并语义：每个代理完成时自动合并其 worktree；若发生合并冲突，变更保留在代理的 worktree 分支上，供手动解决；
• auto_dispatch 显式化：手动创建任务时，如希望依赖完成后自动触发，务必设置 auto_dispatch=true，否则任务停留在 draft 状态。

在 ECC 中的集成入口

DevFleet 在 ECC 中有清晰的落点，方便按需查阅与维护：

• 命令文档：docs/ja-JP/commands/devfleet.md（本主题原始文档，另有 docs/zh-CN/commands/devfleet.md 中文版）；
• 技能定义：skills/claude-devfleet/SKILL.md，包含安装步骤、工具表、并发说明与三种示例模式，是本主题的权威英文版本；
• 遗留命令 shim：legacy-command-shims/commands/devfleet.md，为仍在使用 /devfleet 斜杠命令的会话保留的兼容入口，其行为是委托给 claude-devfleet 技能本身；
• 命令映射：COMMANDS-QUICK-REF.md 将 /devfleet 映射到 claude-devfleet，确认了命令优先用法已退役、技能优先；
• MCP 注册：mcp-configs/mcp-servers.json 中预置了 devfleet 的 HTTP 端点配置；
• 装配面：agent.yaml 声明装配 claude-devfleet 技能，manifests/install-modules.json 将其纳入安装模块，tests/ci/agent-yaml-surface.test.js 提供表面一致性校验。

总结

DevFleet 为 ECC 提供了「并行代理 × 隔离 worktree × 依赖 DAG × 自动合并」的多智能体编排能力。掌握这条主线即可在实际项目中落地：用 plan_project 生成计划并征求批准，用 dispatch_mission 启动根任务让链条自动推进，用 get_dashboard / get_mission_status 监控进度，最后用 get_report 汇总结构化结果。需要更细粒度控制时，create_project + create_mission 的手动模式配合 auto_dispatch 与 depends_on，可以精确编排任意形状的依赖流水线。