ruflo Workflow Automation 实战指南：多步骤流程的创建、编排与模板管理

ruflo 作为多 Agent 元编排框架，将"复杂多步骤过程自动化"沉淀为一套可复用的 Workflow Automation 能力。本文基于 .agents/skills/workflow-automation/SKILL.md 展开，系统讲解如何用 claude-flow 命令创建、执行、导出与监控工作流，并结合仓库源码剖析其底层两种编排表面（MCP 生命周期工作流与原生 JS 编排脚本）的实现差异与选型依据。读完本文，你将掌握从零构建一个具备依赖关系、阶段式执行与可追溯状态的自动化流水线，并把工作流固化为可复用模板的完整方法。

一、这个技能解决什么问题

Workflow Automation Skill 面向的是多步骤、需要编排与状态管理的自动化任务。它的定位非常明确：

• 触发时机：多步骤自动化过程、可复用工作流创建、复杂任务编排、CI/CD 流水线搭建；
• 跳过场景：简单单步任务、临时的一次性操作（这类任务直接用 Agent 单次执行即可，无需引入工作流引擎）。

换言之，当一项工作"不是一个 TodoList 线性推进能覆盖、而是有着真实依赖图、需要步骤间产出传递与跨会话可恢复"时，工作流才是正确的抽象。这一点在底层 MCP 工具的实现说明中写得更加直白：在 workflow-tools.ts 中，workflow_run/workflow_create 的工具描述反复强调："当工作存在需要持久化、重试策略、暂停/恢复与 LLM 驱动步骤间产出绑定的真实依赖图时使用；单一线性待办列表用原生 TodoWrite 即可。"

二、核心命令详解

Skill 文档定义了一套以 npx claude-flow workflow 为主体的命令面，涵盖工作流全生命周期：

# 从模板创建工作流
npx claude-flow workflow create --name "deploy-flow" --template ci

# 执行工作流（可指定环境变量）
npx claude-flow workflow execute --name "deploy-flow" --env production

# 列出全部工作流
npx claude-flow workflow list

# 将工作流导出为可复用模板/文件
npx claude-flow workflow export --name "deploy-flow" --format yaml

# 查看工作流运行状态
npx claude-flow workflow status --name "deploy-flow"

2.1 命令面在仓库中的实际落地

需要注意：命令的精确集合会随 CLI 版本演化。从当前仓库的 V3 CLI 实现 v3/@claude-flow/cli/src/commands/workflow.ts 可见，workflow 主命令实际注册了以下子命令：

子命令	用途	关键参数
workflow run	执行工作流	-t/--template、-f/--file、--task、-p/--parallel（默认 true）、-m/--max-agents（默认 5）、--timeout（分钟，默认 30）、-d/--dry-run
workflow validate	校验工作流定义	-f/--file（必填）、-s/--strict
workflow list	列出工作流	-s/--status（running/completed/failed/all）、-l/--limit（默认 10）
workflow status	查看单个工作流状态	--watch
workflow stop	停止运行中的工作流	-f/--force
workflow template	模板管理	list / show / create

实际使用请以 npx claude-flow workflow --help 与 claude-flow workflow <subcommand> --help 输出的参数为准。以下是源码示例中给出的可直接复制的组合用法：

# 以 development 模板执行并携带任务描述
claude-flow workflow run -t development --task "Build auth system"

# 从 YAML 定义文件执行（校验 + 执行一次完成）
claude-flow workflow run -f ./workflow.yaml

# SPARC 模板做干跑验证，不产生任何副作用
claude-flow workflow run -t sparc --dry-run

# 先校验再执行，校验结果含 stages/agents/预计耗时
claude-flow workflow validate -f ./workflow.yaml

run 子命令交互式运行时（未传 -t/-f）会弹出模板选择器；--dry-run 模式下流程只做校验（status 变为 validated），不会在存储中落盘任何工作流记录，适合上线前演练。

2.2 底层 MCP 工具面

命令面并非孤岛——每个子命令背后都调用一个同名 MCP 工具。以 ADR-0001：ruflo-workflows plugin contract 为契约，ruflo-workflows 插件封装了 10 个 workflow_* MCP 工具（实现在 workflow-tools.ts）：

MCP 工具	用途	对应命令
workflow_create	创建持久化工作流定义	workflow create
workflow_run	以模板/文件运行工作流	workflow run
workflow_execute	执行一次性（不持久化）工作流	workflow execute
workflow_status	检查运行中工作流	workflow status
workflow_list	列出工作流	workflow list
workflow_pause / workflow_resume / workflow_cancel	暂停 / 恢复 / 取消	生命周期控制
workflow_delete	删除工作流定义	清理
workflow_template	管理模板	workflow template

存储与状态机：工作流定义与运行状态以 JSON 形式持久化在项目 .claude-flow/workflows/store.json（源码常量见 workflow-tools.ts）。状态机为 created → running ↔ paused → completed / cancelled，其运行时索引归属 workflows-state AgentDB 命名空间——这就是"跨会话可暂停/恢复"能力的来源。

三、内置模板清单

Skill 文档声明了以下内置模板，覆盖了软件交付侧最常见的流水线形态：

模板	用途
ci	持续集成流水线
deploy	部署工作流
test	测试工作流
release	发布自动化
review	代码评审工作流

3.1 V3 CLI 中的模板清单

在 V3 CLI 中，模板系统被建模为可枚举、可展示、可固化的对象。源码 workflow.ts 定义了如下可选项，且每个模板都预置了阶段划分、参与 Agent 类型与预计耗时（见同文件 L703-L740 的辅助函数）：

模板 value	阶段示例	默认 Agents	预计耗时
development	Planning → Implementation → Testing → Review → Integration	coder, tester, reviewer	15-30 min
research	Discovery → Analysis → Synthesis → Documentation	researcher, analyst	10-20 min
testing	Unit → Integration → E2E → Performance	tester, coder	5-15 min
security-audit	Threat Model → Static → Dynamic → Report	security-architect, security-auditor	20-40 min
code-review	Initial Review → Security Check → Quality → Feedback	reviewer, security-auditor, analyst	10-25 min
refactoring	Analysis → Planning → Refactor → Validation	architect, coder, reviewer	15-35 min
sparc	Specification → Pseudocode → Architecture → Refinement → Completion	architect, coder, tester, reviewer	25-45 min
custom	Initialize → Execute → Complete	coder	10-20 min

模板管理与路由：workflow template list 展示全部模板；workflow template show <name> 查看某模板的阶段与 Agent 构成；workflow template create -n <name> [-w <workflowId> | -f <file>] 可将一次运行固化为新模板，之后即可用 claude-flow workflow run -t <name> 反复调用。仓库中预置的 Agent 角色定义可在 v3/agents（如 coder.yaml、reviewer.yaml、tester.yaml、security-architect.yaml）找到对应能力配置。

四、Workflow 结构与步骤建模

工作流定义采用声明式 YAML，其最小结构是"阶段名 + 执行 Agent + 依赖关系 + 任务描述"：

name: example-workflow
steps:
  - name: analyze
    agent: researcher
    task: "Analyze requirements"
  - name: implement
    agent: coder
    depends: [analyze]
    task: "Implement solution"
  - name: test
    agent: tester
    depends: [implement]
    task: "Write and run tests"

4.1 底层步骤模型的类型化

这套 YAML 在引擎内部会被解析为类型化的步骤对象。源码 workflow-tools.ts 定义了 WorkflowStep 与 WorkflowRecord 两个核心接口：

• 步骤类型（type）：task（任务）、condition（条件分支）、parallel（并行扇出）、loop（循环）、wait（等待/门控）；
• 步骤状态（status）：pending → running → completed / failed / skipped，可回溯每步的开始与完成时间；
• 工作流状态（record.status）：draft / ready / running / paused / completed / failed，配合 currentStep 游标实现断点续跑；
• variables：承载模板名与运行期选项，实现步骤产出向后续步骤的绑定传递。

从这套数据结构可以推断，引擎并不把工作流当作"一串命令"，而是当作一组带依赖图、带生命周期、可暂停可恢复的步骤记录来管理——这与第一节所述的设计意图完全吻合。

五、两种编排表面的选型：MCP 生命周期 vs 原生 JS 编排

ruflo 项目在 MCP 声明式工作流之外，还支持 Claude Code 原生的 Workflow 工具编排脚本，二者是互补而非替代关系，契约由 ADR-0002：native workflow orchestration 确立：

维度	MCP workflow_*	原生 Workflow JS
形态	声明式定义 + 生命周期状态机	命令式 JS 编排脚本
工作单元	持久化的工作流步骤	子 Agent（agent()）
持久化	有状态、跨会话可恢复（workflows-state）	每次运行的 journal，经 resumeFromRunId 恢复
并发	引擎调度步骤	parallel() 屏障 / pipeline() 流式
适用场景	长期存活、可暂停、有人工门控的流水线	大规模扇出：审查、审计、迁移、研究
存放位置	AgentDB 中的定义	.claude/workflows/*.js

• 选 MCP 表面：需要长时间运行、步骤间需人工审批门控、要暂停后在断点继续的场景，走 MCP 定义 + workflow_run 生命周期驱动；
• 选原生表面：需要把一项大任务确定性扇出给多个子 Agent、并在代码中聚合结构化结果的场景，编写 .claude/workflows/*.js（workflow-create 提供完整创作指引，workflow-run 提供运行与恢复指引）。

两者的差异在 parallel()（屏障式，等待全部完成后再聚合）与 pipeline()（流式，各条目独立流经各阶段）之间体现得最为典型：ADR-0002 明确建议优先使用 pipeline 而非 parallel 屏障，因为前者的吞吐与隔离性更优。

六、Best Practices：把工作流做成可靠资产

Skill 文档给出了四条核心实践，结合仓库实现可进一步细化：

1. 明确定义步骤依赖关系：在 depends 中显式声明前置步骤，让引擎据此构建依赖图；真实依赖图正是"该用工作流而非线性 TodoList"的判据。
2. 按步骤选择合适 Agent 类型：将 Agent 角色与任务性质对齐（分析交给 researcher、实现交给 coder、质量把关交给 tester/reviewer、安全交给 security-auditor）。源码中每个模板的 getTemplateAgents 都是这种对齐的预置样例。
3. 纳入验证门控（validation gates）：正式执行前先 workflow validate -f ./workflow.yaml（必要时加 --strict），或对高频流水线以 --dry-run 演练；校验结果会逐行报告错误（行号 + 严重级别）与告警，杜绝带病上线。
4. 导出工作流以便复用：通过模板固化（workflow template create）或 export 为 YAML 保存为仓库资产，让 CI/CD、发布、评审等流程一次建设、处处复用，并纳入版本管理。

此外还建议：为 workflow run 设置合理的 --timeout 上限防止失控；用 workflow status <workflowId> 观察 progress、token 消耗与 spawn 的 Agent 数；对不再使用的定义用 workflow_delete 及时清理，避免 store.json 膨胀。

七、延伸阅读

• 工作流自动化技能定义（本文主体）
• V3 CLI workflow 命令实现（子命令与模板路由源码）
• 10 个 workflow MCP 工具实现（持久化存储与步骤模型）
• ADR-0001：workflows 插件契约
• ADR-0002：原生 Workflow 编排
• ruflo-workflows 命令手册
• workflow-create / workflow-run 技能