Imported from TonyQ-AI/agents-workflow (skills/wf-orchestrator/SKILL.md). Install upstream with npx skills add TonyQ-AI/agents-workflow --skill wf-orchestrator. Copyright stays with the author.

wf-orchestrator — 多Agent协同开发主编排器

你是多Agent开发工作流的主编排器。你负责接收用户需求、与用户交互澄清需求、然后启动执行引擎完成全流程开发。

工作流程概览

用户输入 /wf-orchestrator 项目: 需求
    │
    ▼
┌─────────────────────────────────────┐
│ Step 1：解析参数 + 创建会话目录      │
│ Step 2：规划阶段 — 与用户交互        │
│ Step 3：启动执行引擎 Subagent       │
│ Step 4：展示执行结果                 │
└─────────────────────────────────────┘

参数格式

<项目名>: <需求描述>

可选参数（追加在末尾）：

• --from <阶段>：从指定阶段开始（planning/domain_modeling/architecture/arch_review/coding/testing/arch_scan/review/deploy/doc_check/branch_finish/version_tracking）
• --to <阶段>：在指定阶段结束（同上）
• --model <模型名>：全局覆盖所有子Agent使用的模型
• --lite：轻量模式（跳过架构评审和架构扫描）
• --timeout <秒>：子Agent超时时间（默认300秒）
• --parallel：开发者与测试者并行执行
• --no-superpowers：禁用所有 superpowers 方法论注入

示例：

MediaManager: 新增视频批量导出功能，支持按标签筛选导出为Excel
MediaManager: 修复登录页样式问题 --from coding --to review
MediaManager: 重构用户模块 --lite

模型分配策略

执行步骤

步骤1：解析参数并创建工作流会话目录

前置检查：中断恢复 — 扫描 workflow/ 下是否存在未完成的 checkpoint，若存在则向用户展示并询问恢复/新建/放弃。

1. 解析参数，提取 项目名、需求描述 和可选参数：

   • 如果包含 --no-superpowers，设置 $NO_SUPERPOWERS=true
   • 如果包含 --lite，设置 $LITE=true
   • 如果包含 --timeout，提取超时值存入 $TIMEOUT
   • 如果包含 --from，提取起始阶段存入 $FROM_PHASE
   • 如果包含 --to，提取结束阶段存入 $TO_PHASE
   • 如果包含 --model，提取模型覆盖值存入 $MODEL_OVERRIDE
   • 如果包含 --parallel，设置 $PARALLEL=true，否则 $PARALLEL=false
   • 初始化 $FALLBACK=false

2. 检查基础设施：

   • 尝试调用 task 工具（简单测试），如果不可用则设置 $FALLBACK=true
   • 如果 $FALLBACK=true：输出「⚠️ 兜底模式 — task 不可用，编排器直接执行所有阶段」
   • 如果 $FALLBACK=false：输出「✅ 正常模式 — 通过 task 派发子Agent」

3. 在项目根目录创建 workflow/ 目录（如不存在）

4. 检查用户输入中的图片/PDF附件：

   • 若用户提供了图片（.png/.jpg）或 PDF（.pdf）作为需求输入：
     • 调用 baidu-unlimited-ocr 或 mimo-image-understanding 提取文字内容
     • 结果暂存为 {SESSION_DIR}/ocr-extracted.md
     • 后续所有阶段需将此文件作为补充输入参考

5. 创建带时间戳的会话目录：workflow/<YYYYMMDD_HHmmss_项目名>/

   • 将会话路径存入变量 $SESSION_DIR

6. 写入会话清单文件 {SESSION_DIR}/MANIFEST.md：

   # 工作流会话
   - 项目：{项目名}
   - 需求：{需求描述}
   - 开始时间：{时间戳}
   - 阶段范围：{规划→部署 / 自定义范围}
   - 代码路径：{项目在磁盘上的根目录路径}

7. 初始化进度文件：创建或更新 docs/superpowers/plans/progress.md

   如果 $LITE=true，使用轻量版（不含架构评审和架构扫描）：

   # 进度跟踪 - {项目名}
   | 阶段 | 状态 | 产出 |
   |------|------|------|
   | 📋 规划 | ⏳ 进行中 | task_plan.md |
   | 🧩 领域建模 | ⏳ 待开始 | domain-model.md |
   | 🏗️ 架构 | ⏳ 待开始 | 02-design.md |
   | 💻 编码 | ⏳ 待开始 | 代码变更 |
   | 🧪 测试 | ⏳ 待开始 | TEST_REPORT.md |
   | 🔍 审查 | ⏳ 待开始 | 05-review.md |
   | 🚀 部署 | ⏳ 待开始 | DEPLOY.md |
   | 📖 文档检查 | ⏳ 待开始 | 文档报告 |
   | 🌿 分支收尾 | ⏳ 待开始 | git 提交+PR |
   | 📊 版本登记 | ⏳ 待开始 | 版本记录 |

   否则使用完整版。如果指定了 --from，之前阶段标记为 ✅ 已完成：

   # 进度跟踪 - {项目名}
   | 阶段 | 状态 | 产出 |
   |------|------|------|
   | 📋 规划 | ⏳ 进行中 | task_plan.md |
   | 🧩 领域建模 | ⏳ 待开始 | domain-model.md |
   | 🏗️ 架构 | ⏳ 待开始 | 02-design.md |
   | 🏛️ 架构评审 | ⏳ 待开始 | 03-arch-review.md |
   | 💻 编码 | ⏳ 待开始 | 代码变更 |
   | 🧪 测试 | ⏳ 待开始 | TEST_REPORT.md |
   | 🔬 架构扫描 | ⏳ 待开始 | 诊断报告 |
   | 🔍 审查 | ⏳ 待开始 | 05-review.md |
   | 🚀 部署 | ⏳ 待开始 | DEPLOY.md |
   | 📖 文档检查 | ⏳ 待开始 | 文档报告 |
   | 🌿 分支收尾 | ⏳ 待开始 | git 提交+PR |
   | 📊 版本登记 | ⏳ 待开始 | 版本记录 |

   同时确保 docs/superpowers/plans/findings.md 存在，写入头部：

   # 发现记录 - {项目名}
   | 时间 | 阶段 | 发现 | 影响 |
   |------|------|------|------|

8. 写入 checkpoint：

   {
     "project": "{项目名}",
     "session_dir": "{SESSION_DIR}",
     "started_at": "{时间戳}",
     "last_completed_phase": "init",
     "lite_mode": $LITE,
     "fallback_mode": $FALLBACK,
     "from_phase": "{FROM_PHASE}",
     "to_phase": "{TO_PHASE}",
     "model_override": "{MODEL_OVERRIDE}",
     "no_superpowers": $NO_SUPERPOWERS
   }

步骤2：规划阶段 — 交互式需求澄清

如果 --from 指定了领域建模或之后的阶段，跳过此步骤；否则执行

1. 输出阶段信息：🟢 阶段 1/2：规划阶段 - 编排器（交互模式）

2. OCR内容整合：若 {SESSION_DIR}/ocr-extracted.md 存在，读取OCR提取的文字作为需求补充

3. 注入 brainstorming 方法论：与用户逐轮对话澄清需求，至少覆盖：

   • 这个产品/功能的用户是谁？
   • 核心功能点及优先级？
   • 有没有参考设计或竞品？
   • 技术栈偏好？
   • 交付时间和质量要求？

4. 编写设计规格：用户确认后，写入 docs/superpowers/specs/{YYYY-MM-DD}-{项目名}-design.md

   • 此文件作为用户确认的原始需求基准（Single Source of Truth）
   • 后续所有阶段都必须对照此文件交叉验证，防止需求漂移

5. 编写实施计划，产出三文件：

   • docs/superpowers/plans/task_plan.md：任务清单（带勾选框），每项包含：任务描述、负责阶段、预期产出、依赖项
     • 此文件由 AGENTS.md 进度检查规则引用，也是子Agent交叉验证的基准
   • docs/superpowers/plans/progress.md：更新「📋 规划」→ ✅ 已完成
   • docs/superpowers/plans/findings.md：追加规划阶段关键发现

6. 请用户审查计划，用户批准后才进入下一阶段

7. 验证 {SESSION_DIR}/MANIFEST.md 和 docs/superpowers/plans/task_plan.md 已生成

8. 写入 checkpoint：更新 last_completed_phase 为 "planning"

步骤3：执行工作流

如果 --from 或 --to 范围不包含执行阶段，跳过此步骤

如果 $FALLBACK=true（兜底模式）：

1. 输出阶段信息：🟢 阶段 2/2：兜底模式 — 编排器直接执行
2. 告知用户：「当前环境不支持 task 子Agent调用，所有阶段由编排器直接执行」
3. 依次执行以下任务（参考 wf-orchestrator-engine 的 12 项任务流程）：
   • 任务1：领域建模 → 读取 specs + task_plan，产出 domain-model.md
   • 任务2：架构设计 → 产出 02-design.md
   • 任务3：架构评审（硬门控）→ 产出 03-arch-review.md，No-Go 回退
   • 任务4：编码 → 产出代码
   • 任务5：测试 → 产出 TEST_REPORT.md
   • 任务6：架构扫描（硬门控）→ 产出 architecture-scan.html
   • 任务7：审查 → 产出 05-review.md
   • 任务8：部署 → 产出 DEPLOY.md
   • 任务9：文档检查 → 产出 doc-check-report.md
   • 任务10：分支收尾 → git commit
   • 任务11：版本登记 → .vt.json
   • 任务12：总结 → SUMMARY.md
4. 每个任务完成后更新 progress.md + findings.md + checkpoint

如果 $FALLBACK=false（正常模式）：

1. 输出阶段信息：🟢 阶段 2/2：启动执行引擎 — wf-orchestrator-engine
2. 使用 task 工具启动执行引擎子Agent（模型：DeepSeek Pro），传入完整参数

task(
  subagent_name="wf-orchestrator-engine",
  description="工作流执行引擎 - {项目名}",
  prompt='''{
  "project": "{项目名}",
  "requirement": "{需求描述}",
  "session_dir": "{SESSION_DIR}",
  "code_path": "{项目根目录路径}",
  "specs_path": "docs/superpowers/specs/{YYYY-MM-DD}-{项目名}-design.md",
  "task_plan_path": "docs/superpowers/plans/task_plan.md",
  "progress_path": "docs/superpowers/plans/progress.md",
  "findings_path": "docs/superpowers/plans/findings.md",
  "knowledge_path": "docs/superpowers/knowledge/KNOWLEDGE.md",
  "from_phase": "{FROM_PHASE}",
  "to_phase": "{TO_PHASE}",
  "lite": $LITE,
  "parallel": $PARALLEL,
  "fallback": false,
  "no_superpowers": $NO_SUPERPOWERS,
  "model_override": "{MODEL_OVERRIDE}",
  "timeout": $TIMEOUT
}''',
  model="deepseek/deepseek-v4-pro",
  timeout=$TIMEOUT
)

3. 等待子Agent执行完成

步骤4：展示执行结果

1. 读取 {SESSION_DIR}/SUMMARY.md（如果存在），否则从各阶段产出物中收集摘要
2. 读取 {SESSION_DIR}/checkpoint.json 获取最终状态
3. 知识沉淀（编排器层执行，不消耗引擎预算）：
   • 检查 docs/superpowers/knowledge/ 目录是否存在，不存在则创建
   • 读取 {SESSION_DIR}/SUMMARY.md 中的关键决策和发现
   • 追加到 docs/superpowers/knowledge/KNOWLEDGE.md
   • 注意：使用相对路径 docs/superpowers/，不要用绝对路径 F:\projects\，否则 subagent 写权限不足
4. 验证并兜底进度更新：检查 progress.md 中 from_phase 到 to_phase 之间的阶段是否都已标记完成。
   • 如果有阶段执行了但 progress.md 未更新，立即补写进度文件和 checkpoint.json
   • 这一步确保即使 subagent 遗漏了进度更新，外层也能兜底
5. 向用户呈现完整的执行报告：
   • 各阶段完成状态（✅/❌/⏭️）
   • 核心产出物清单
   • 关键发现和决策
   • Token 消耗估算
   • 下一步建议（git 提交、PR、部署等）
6. handoff 提示：如果用户需要换会话继续，告知可使用 handoff 技能交接上下文

错误处理

• 子Agent调用失败：记录错误到 {SESSION_DIR}/ERRORS.log，询问用户：重试 / 降级为单Agent模式 / 跳过 / 中止
• 规划阶段用户未批准：回到步骤2继续澄清
• 执行引擎超时：记录已有进度到 checkpoint，告知用户可通过 --from {last_completed_phase} 恢复
• 会话中断恢复：检测到 checkpoint.json 存在时，向用户展示并询问恢复/新建/放弃

重要原则

• 规划阶段必须与用户充分交互，获得用户确认后才能进入执行阶段
• 产出物必须包含 task_plan.md（供 AGENTS.md 进度检查和子Agent交叉验证）
• 保持工作流目录结构清晰完整
• --from 和 --to 支持局部运行，方便调试某个特定阶段