Team Dispatch

Use when a request requires multi-agent workflow orchestration (task decomposition + dependency/DAG + parallel execution), needs durable task tracking across context compaction, or needs retries/fallbacks and completion notifications.

🚀 Team Dispatch v1.0.8 — Multi-Agent Workflow Orchestration

一句需求 → 自动分析 → 智能拆解 → DAG 派发 → 故障重试 → 自动交付。

---

⚡ 第〇步：自动安装与环境检测（必须首先执行）

真实项目代码空间（默认）

• 默认真实项目/仓库目录：~/work（可通过 <SKILL_DIR>/config.json 或 ~/.openclaw/configs/team-dispatch.json 的 paths.projectsRoot 修改）
• 约定：每个项目在 paths.projectsRoot/<project> 下创建与产出代码（而不是放在 ~/.openclaw/workspace/）
• setup.sh 会自动创建该目录（若不存在）

Agent 读到本文件后，必须先执行以下检测流程，确认系统就绪后再处理用户需求。 新用户首次安装、或已有用户技能更新后，均走此流程。

SKILL_DIR 解析

<SKILL_DIR> = 本 SKILL.md 文件所在的目录。 Agent 应从自身读取本文件的路径自动推导，例如：

• 若从 /Users/xxx/skills/team-dispatch/SKILL.md 读取，则 SKILL_DIR=/Users/xxx/skills/team-dispatch
• 若从软连接 ~/.openclaw/skills/team-dispatch/SKILL.md 读取，用 readlink 解析真实路径

一键安装

直接运行安装脚本即可完成全部配置：

bash

bash <SKILL_DIR>/scripts/setup.sh

如果遇到模型 404/quota 问题，可追加基线模型参数：

bash

bash <SKILL_DIR>/scripts/setup.sh --baseline-models

安装脚本自动完成的 8 项配置

setup.sh 会自动检测并配置以下所有项目，已存在的不覆盖：

#	配置项	说明
1	软连接	~/.openclaw/skills/team-dispatch → <SKILL_DIR>
2	任务目录（使用安装用户的主工作区）	~/.openclaw/workspace/tasks/{active,done,templates}（不会创建额外的 main 工作区）
3	项目模板	复制 project.json 到 templates/
4	用户配置	生成 ~/.openclaw/configs/team-dispatch.json（语言、通知策略、团队显示名）
5	子 Agent agentDir 模板	全新安装：cp -R <SKILL_DIR>/assets/agents/<id> ~/.openclaw/agents/<id>（内含 workspace 模板 + 预置文件）
6	补齐缺失文件	已有 ~/.openclaw/agents/<id>：仅补齐 workspace/ 下缺失文件，不覆盖用户改动；并创建 sessions/
7	写入 openclaw.json	在 agents.list 中确保存在 main（dispatcher/root）并配置 main.subagents.allowAgents: ["*"]；同时写入 7 个子 Agent 配置（含 workspace、identity、model），已存在的补齐缺失字段
8	重启 Gateway	配置写入后自动重启 Gateway 使生效

子 Agent 完整配置规范

在 openclaw.json 的 agents.list 中：必须存在 main（dispatcher/root），并在 main 上配置 subagents.allowAgents。

main agent 配置示例（安装时应确保存在/补齐）

json

{
  "id": "main",
  "default": true,
  "name": "main",
  "workspace": "/Users/vvusu/.openclaw/workspace",
  "agentDir": "/Users/vvusu/.openclaw/agents/main/agent",
  "model": "openai-codex/gpt-5.4",
  "identity": {
    "name": "调度台",
    "emoji": "🎯"
  },
  "subagents": {
    "allowAgents": ["*"]
  }
}

子 Agent 配置示例

json

{
  "id": "<agentId>",
  "name": "<中文名>",
  "workspace": "~/.openclaw/agents/<agentId>/workspace",
  "model": {
    "primary": "<见下方模型选择策略>",
    "fallbacks": ["bailian/qwen3.5-plus", "bailian/kimi-k2.5", "zai/glm-4.7"]
  },
  "tools": { "profile": "<coding|full>" },
  "skills": [],
  "identity": {
    "name": "<中文名>",
    "emoji": "<角色 emoji>",
    "theme": "<英文角色描述>"
  }
}

模型选择策略

• coder → openai-codex/gpt-5.3-codex（OAuth，专为编码优化）
• 其他 Agent → openai-codex/gpt-5.4（OAuth，通用稳定）
• fallbacks 从用户已配置的 providers 中选取，确保不会 404

工具集分配

• coder, tester → "coding"
• product, research, trader, writer → "full"

子 Agent Workspace 结构

每个子 Agent 拥有独立的 agentDir + workspace + sessions（符合 OpenClaw 多 Agent 目录规范），互不干扰。

全新安装（您指定的逻辑）

bash

cp -R <SKILL_DIR>/assets/agents/<id> ~/.openclaw/agents/<id>

模板目录结构为：

text

<SKILL_DIR>/assets/agents/<id>/
└── workspace/
        ├── AGENTS.md
        ├── SOUL.md
        ├── IDENTITY.md
        ├── USER.md
        ├── TOOLS.md
        ├── HEARTBEAT.md
        ├── BOOTSTRAP.md
        └── .openclaw/workspace-state.json

安装后运行时会在以下位置写入会话与状态：

text

~/.openclaw/agents/<id>/sessions/

已有安装（升级/补齐）

• 若 ~/.openclaw/agents/<id> 已存在：只补齐 workspace/ 下缺失文件，不覆盖用户已修改的文件
• sessions/ 若缺失会自动创建（本技能脚本也会 mkdir -p）

注：子 Agent 通过 sessions_spawn 启动时只注入 AGENTS.md + TOOLS.md，但完整的 workspace 文件在 Agent 作为独立 agent（而非 subagent）运行时会全部加载。

团队成员一览

agentId	中文名	Emoji	workspace	工具集	角色定位
coder	闪电	⚡️	workspace-coder	coding	编码开发专家
product	诺娃	🧭	workspace-product	full	产品规划专家
tester	亚特拉斯	🔍	workspace-tester	coding	测试验证专家
research	露娜	🔭	workspace-research	full	调研搜索专家
trader	泰坦	📈	workspace-trader	full	投资分析专家
writer	萊拉	✒️	workspace-writer	full	内容写作专家
shield	盾卫	🛡️	workspace-shield	full	安全审计专家

检测通过后的输出

安装脚本或 Agent 检测全部通过后，向用户确认：

text

✅ Team Dispatch 环境就绪！
- 软连接：✅
- 任务目录：✅
- 项目模板：✅
- 用户配置：✅（语言：zh/en）
- 子 Agent Workspace：✅（7 个独立工作目录 + AGENTS.md）
- 子 Agent 配置：✅（workspace + identity + model 完整）
- Gateway：✅（已重启生效）

系统已准备好接收任务，请告诉我您想要完成什么？

常见安装问题与自动修复

问题	原因	修复方式
子 Agent 没有独立 workspace	旧版技能未配置	重新运行 setup.sh，自动创建并补齐
子 Agent 没有角色指令	缺少 AGENTS.md	setup.sh 从 assets/agents/ 复制模板
子 Agent 不知道自己是谁	缺少 identity 配置	setup.sh 自动写入 identity 字段
用户配置不完整	手动创建了简化版	用 <SKILL_DIR>/config.json 覆盖
模型 404 / quota 错误	模型不可用	运行 setup.sh --baseline-models

---

🌍 国际化（i18n）

默认英文，通过 ~/.openclaw/configs/team-dispatch.json 中 "language": "zh" 切换中文。

---

📊 任务分级

收到需求后，先判断复杂度：

级别	判断标准	处理方式
S	单 Agent 可完成	直接 sessions_spawn，不建文件
M	2-3 个 Agent，线性依赖	自动建 DAG + 追踪
L	4+ Agent，有并行分支	自动建 DAG + 追踪 + 进度汇报
XL	跨多领域，需多轮迭代	DAG + 分阶段交付 + 用户确认点

---

🔀 拆解模板

根据需求类型自动选择：

开发类

text

product(PRD) → coder(编码) → tester(测试) → shield(安全审计)
                             → writer(文档)

安全敏感类（带部署）

text

product(PRD) → coder(编码) → tester(测试) → shield(安全审计) → writer(文档)

研究类

text

research(调研) → product(分析框架) → writer(成文)

全栈类

text

research(调研) → product(PRD) → coder(编码) → tester(测试) → shield(安全审计) → writer(文档)

分析类

text

research(数据收集) → trader(分析) → writer(报告)
                   → product(策略建议)

内容类

text

research(素材收集) → writer(初稿) → product(审核优化)

---

⚠️ 重要限制：sessions_spawn 可能不允许指定 agentId

在某些运行环境/工具策略下，sessions_spawn 可能会拒绝 agentId 参数（错误类似：agentId is not allowed for sessions_spawn (allowed: none)）。

此时 Team Dispatch 必须自动降级为“单 Agent 多角色模拟”模式：

• 仍然按 DAG 拆解任务
• 派发时不传 agentId（让 subagent 继承当前 agent 身份）
• 在 task prompt 顶部注入角色指令（例如“你现在扮演 coder/product/tester…”）来模拟团队分工
• 结果收集、依赖解锁、重试逻辑保持不变

如果你有权限配置并希望启用真实多 Agent 派发：

• 在 openclaw.json 中设置 agents.defaults.subagents.allowAgents: ["*"]（或允许列表）
• 重启 Gateway

---

⚙️ 核心调度流程

⚠️ 关键行为约定：事件驱动的自动调度循环

当你通过 sessions_spawn 派发任务后，OpenClaw 会在 subagent 完成时自动向你的会话推送一条 completion event（以 user message 形式到达）。

你必须在收到每一条 completion event 后，立刻执行完整的调度循环：

1. 从 event 中提取 label，匹配到对应的 task
2. 更新该 task 的 status/result/completedAt，写入 JSON
3. 扫描所有 pending 任务，找出依赖已全部 done 的任务
4. 立刻派发这些就绪的任务（sessions_spawn）
5. 检查项目是否全部完成，若完成则归档并通知用户

不要等待用户指令，不要等待其他事件，不要跳过这个循环。每收到一条 completion event 就执行一次。

这是 Team Dispatch 的核心机制——事件驱动的级联派发。如果你不执行这个循环，任务就会"卡住"。

Step 1: 首次派发

扫描项目 JSON 中所有 status=pending 且依赖全部 done（或无依赖）的任务，批量派发：

text

for each task where status=="pending" && allDepsAreDone(task):
  task.status = "in-progress"
  task.startedAt = now()
  prompt = buildPrompt(task)
  sessions_spawn(agentId=task.agentId, task=prompt,
                 runTimeoutSeconds=task.timeoutSeconds,
                 label="{project}:{taskId}")
  task.sessionKey = response.childSessionKey
  writeJSON()

Step 2: 收到 completion event → 立刻执行调度循环

当 subagent completion event 到达时（OpenClaw 自动推送，格式为 "✅ Subagent {agentId} finished\n{result}"），你必须立刻执行以下完整流程，不需要用户指令：

text

# ① 识别完成的任务
task = findByLabel(event.label)   # 或从 event 内容匹配 agentId + 上下文

# ② 更新状态
task.result = summarize(event.result)
task.status = "done"
task.completedAt = now()
writeJSON()

# ③ 扫描并派发就绪的下游任务（关键！）
dispatchReady():
  for each t where t.status=="pending" && allDepsAreDone(t):
    t.status = "in-progress"
    t.startedAt = now()
    prompt = buildPrompt(t)  # 含上游结果注入
    sessions_spawn(agentId=t.agentId, task=prompt, ...)
    t.sessionKey = response.childSessionKey
    writeJSON()

# ④ 检查项目是否全部完成
checkProjectDone():
  if all tasks are done/skipped:
    project.status = "completed"
    moveToArchive()          # tasks/active → tasks/done
    finalizeAndNotify()      # 向用户发送最终交付清单

再次强调：Step 2 是一个自动触发的循环。你不需要也不应该等用户说"继续"或"下一步"。每收到一个 completion event，就执行一轮 ②→③→④。这样任务会像多米诺骨牌一样自动级联推进，直到全部完成。

Step 3: Prompt 构建 — 结果注入

下游 Agent 自动获得上游输出：

text

buildPrompt(task):
  prompt = task.description
  if task.dependsOn:
    prompt += "\n\n--- 上游任务结果 ---"
    for depId in task.dependsOn:
      dep = findTask(depId)
      prompt += "\n\n[{dep.id}] ({dep.agentId}): {dep.result}"
  return prompt

Step 4: 并行派发注意事项

当多个任务同时就绪时（如 t4-tests 和 t5-docs 都依赖 t3-core），应同时派发所有就绪任务，而非逐个等待：

text

# 错误做法 ❌：派发 t4，等 t4 完成，再派发 t5
# 正确做法 ✅：同时派发 t4 和 t5，各自独立完成后触发下游

---

🛡️ 故障处理

故障类型与自动恢复

类型	触发条件	自动处理
超时	超过 timeoutSeconds	超时 × 1.5 后重试
失败	Agent 返回 failed	重试（最多 retryLimit 次）
拒绝	并发上限	进入 queued，自动出队
模型错误	模型不可用(404等)	检查修正模型配置

降级策略（onFailure 字段）

策略	值	行为
阻塞	"block"	中止项目，通知用户（默认）
跳过	"skip"	标记 skipped，下游继续
降级	"fallback"	换备选 Agent 重试
人工	"manual"	暂停，等用户提供结果

---

📈 状态机

项目状态

text

active → completed    (全部 done/skipped)
active → blocked      (关键任务失败，重试耗尽)
active → cancelled    (用户取消)
blocked → active      (用户干预后恢复)

任务状态

text

pending → in-progress → done
       → queued       → in-progress   (并发满)
       → in-progress  → failed → pending (重试)
                               → skipped (跳过)

---

🔒 并发控制

• 并发上限由 agents.defaults.subagents.maxChildrenPerAgent/maxConcurrent 决定（默认 5，建议 10）
• 超出时任务进入 queued 状态，有 Agent 完成后自动出队
• 优先级：关键路径 > 依赖链长 > 声明顺序

---

🔗 依赖模式

模式	图示	场景
线性	A → B → C	Bug 修复、简单功能
扇出	A → B, C, D	一个输入多个并行处理
扇入	B, C → D	多个结果汇合
菱形	A → B, C → D	先分后合

---

⏸️ 用户确认点（XL 级）

关键节点暂停等用户审核：

json

{
  "id": "review-prd",
  "agentId": null,
  "description": "请用户确认 PRD 是否符合预期",
  "status": "pending",
  "dependsOn": ["prd"],
  "type": "checkpoint"
}

checkpoint 类型不派发 Agent，暂停并通知用户。

---

📁 项目文件

存储路径：<workspace>/tasks/

text

tasks/
├── active/          # 进行中
│   └── <project>.json
├── done/            # 已完成
│   └── <project>.json
└── templates/
    └── project.json  # 任务模板

---

🔧 运维工具

脚本	用途	命令
scripts/setup.sh	一键安装/配置	bash <SKILL_DIR>/scripts/setup.sh
scripts/setup.sh --baseline-models	切换稳定基线模型	解决 404/quota 问题
scripts/setup-config.sh	生成用户配置	自动跳过已存在
scripts/doctor.sh	环境健康检查	bash <SKILL_DIR>/scripts/doctor.sh
scripts/demo-project.sh	生成闭环自测 Demo 项目（product → coder → tester）	bash <SKILL_DIR>/scripts/demo-project.sh
scripts/watch.sh	低频巡检卡死任务（前台运行）	INTERVAL=300 GRACE=20 bash <SKILL_DIR>/scripts/watch.sh
scripts/watch-install.sh	安装 watcher（后台常驻，跨平台：macOS/Linux；Windows见ps1）	bash <SKILL_DIR>/scripts/watch-install.sh
scripts/watch-uninstall.sh	卸载 watcher（后台常驻）	bash <SKILL_DIR>/scripts/watch-uninstall.sh
assets/windows/watch-install.ps1.txt	Windows 安装 watcher（Scheduled Task）	copy <SKILL_DIR>\\assets\\windows\\watch-install.ps1.txt watch-install.ps1; powershell -ExecutionPolicy Bypass -File .\\watch-install.ps1
scripts/demo-project.sh	生成协作开发测试 Demo 项目（写入 tasks/active）	bash <SKILL_DIR>/scripts/demo-project.sh

✅ 闭环自测（最小协作链路）

1. 生成一个带 3 个任务的 Demo DAG（写入 ~/.openclaw/workspace/tasks/active/）：

bash

bash <SKILL_DIR>/scripts/demo-project.sh

2. 然后在 main agent 对话中说：

• “请用 team-dispatch 跑一下刚生成的 demo-collab-loop 项目（product → coder → tester），并在完成后归档到 tasks/done。”

预期：main 会按依赖顺序依次 sessions_spawn(product/coder/tester)，并把结果写回项目 JSON，最终移动到 tasks/done/ 并汇总汇报。

---

✅ 闭环自测（协作开发测试 Demo）

生成一个最小可验证的协作开发 DAG 项目（默认 team-mvp-1），写入：~/.openclaw/workspace/tasks/active/：

bash

bash <SKILL_DIR>/scripts/demo-project.sh

生成后，在主 Agent 里发一句话触发调度（示例）：

请用 team-dispatch 跑一下刚生成的 team-mvp-1 demo 项目，按 DAG 依赖派发 product/coder/tester/writer，完成后归档到 tasks/done。

---

📋 完整调度示例

输入

text

用户: "帮我调研 AI Agent 市场，写一篇分析报告"

自动处理

text

1. 分析: 研究类，L 级
2. 拆解: research → product(框架) → writer(成文) + coder(可视化)
3. 建 DAG: tasks/active/ai-report.json
4. 派发: research（无依赖）
5. research done → 派发 product（注入 research 结果）
6. product done → 并行派发 writer + coder（注入上游结果）
7. 全部完成 → 归档 tasks/done/ → 汇报用户

输出

text

✅ 项目完成！
- 📝 分析报告: [内容]
- 📊 可视化: ~/work/ai-report/index.html
- 🔎 预览方式: open ~/work/ai-report/index.html