agentic-workflow-orchestration

🎭 Agentic 工作流编排技能

目的

为复杂问题提供多个 Agentic 工作流的编排指导，包括协调、委派和并行执行。包含来自 Agent Factory 的成熟模式（100+ 个工作流，500+ 个已合并 PR），包括 /plan 分解、任务挖掘和堆叠式 Agent 协调。

适用场景

在以下情况下使用此技能：

• 将复杂自动化拆分为相互协调的工作流
• 实现编排器-工作器模式
• 使用 /plan 命令分解问题
• 构建流水线或 MapReduce 模式
• 协调具有不同专长的多个 AI Agent

规则

编排基础

必须：

• 设计编排器，使其负责协调而非执行
• 创建职责单一、目标明确的工作器
• 使用工作流分发进行编排器与工作器之间的通信
• 明确编排器与工作器之间的契约
• 在编排器中妥善处理工作器故障
• 汇总并验证工作器结果
• 记录编排决策和结果

不得：

• 混合编排逻辑与执行逻辑
• 创建过于复杂的编排层级
• 忽略工作器故障
• 在工作流之间创建循环依赖
• 跳过对工作器结果的验证

编排器设计

必须：

• 尽可能让编排器保持无状态
• 使用 GitHub API 跟踪工作器状态
• 为故障工作器实现重试逻辑
• 明确成功和失败标准
• 生成编排工作摘要报告
• 通过横向扩展而非纵向扩展工作器
• 清楚记录编排逻辑

不得：

• 将工作器名称或配置硬编码
• 假定工作器总能成功
• 创建长时间运行的编排器（应改用定时检查）
• 将编排器与特定工作器实现紧密耦合

工作器设计

必须：

• 让每个工作器专注于一项明确定义的任务
• 确保工作器可以独立测试
• 清楚报告成功或失败状态
• 提供供编排器使用的详细输出
• 在本地处理边缘情况
• 实现适当的超时机制
• 使用一致的输出格式

不得：

• 创建职责不止一项的工作器
• 直接依赖其他工作器（应通过编排器协调）
• 假定编排器上下文
• 创建永不结束的工作器
• 跳过错误报告

通信模式

必须：

• 使用带输入参数的 workflow_dispatch 实现编排器→工作器通信
• 使用 issue、评论或拉取请求实现工作器→编排器通信
• 使用结构化数据格式（JSON、YAML）进行工作流间通信
• 对通信协议进行版本管理
• 验证所有工作流间消息
• 记录通信契约

不得：

• 使用文件系统进行工作流间通信
• 信任未经检查的其他工作流数据
• 创建隐蔽的通信渠道
• 跳过消息验证

并行执行

必须：

• 并行分发相互独立的工作器
• 设置适当的并发限制
• 为并行工作器实现超时处理
• 收集并验证所有工作器的结果
• 处理部分成功的情况
• 跟踪执行指标（耗时、成功率）

不得：

• 在可以并行执行时仍按顺序等待工作器
• 创建无界并行
• 忽略部分失败
• 假定工作器会按特定顺序完成

错误处理与弹性

必须：

• 为故障工作器实现熔断器
• 使用指数退避进行重试
• 设置最大重试次数
• 记录所有故障及其上下文
• 将持续性故障升级给人工处理
• 实现优雅降级
• 保留编排决策的审计跟踪

不得：

• 无限重试
• 向编排器隐瞒故障
• 在缺乏隔离措施的情况下导致故障级联
• 跳过错误情况的日志记录

编排模式

模式 1：简单编排器-工作器

结构：

• 1 个编排工作流
• N 个同质工作器工作流
• 工作器针对不同输入执行相同任务

适用场景：

• 批量处理（分析所有未关闭的问题）
• 并行验证（测试多种配置）
• 分布式扫描（跨仓库进行安全审计）

模式 2：分层编排

结构：

• 顶层编排器
• 中层专业编排器
• 叶级执行工作器

适用场景：

• 复杂的多阶段操作
• 每个阶段采用不同的编排策略
• 嵌套任务分解

模式 3：流水线编排

结构：

• 编排器管理顺序执行的阶段
• 每个阶段都有专业工作器
• 一个阶段的输出作为下一阶段的输入

适用场景：

• CI/CD 流水线
• 数据处理流水线
• 多步骤验证工作流

模式 4：路由器/分发器

结构：

• 路由器分析输入并选择合适的工作器
• 不同工作器具备不同能力
• 根据上下文动态选择工作器

适用场景：

• 问题分类（路由至专门的处理器）
• 内容审核（按内容类型路由）
• 多语言支持（按语言路由）

模式 5：Map-Reduce

结构：

• Map 阶段：编排器为每个输入启动工作器
• Reduce 阶段：编排器汇总工作器的结果
• 生成最终报告

适用场景：

• 跨多个仓库进行仓库分析
• 并行测试并汇总结果
• 分布式数据收集与综合

模式 6：反思（自我改进）

结构：

• 生成器工作流生成输出
• 评审工作流审查并提供反馈
• 协调器编排迭代，直至达到质量阈值

适用场景：

• 生成文档并进行质量审查
• 生成代码并进行安全审查
• 创建内容并验证风格

示例

示例 1：简单编排器-工作器模式

编排器（daily-orchestrator.md）：

---
on: daily
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Daily Repository Orchestrator

Coordinate daily analysis across all open issues:

1. List all open issues in repository
2. For each issue, dispatch `issue-analyzer` worker workflow with issue number
3. Wait for all workers to complete (check workflow run statuses)
4. Collect results from worker comments
5. Generate summary report issue titled "Daily Analysis Report - [DATE]"

Include:
- Total issues analyzed
- Critical issues found
- Recommendations summary
- Links to worker analysis comments

工作器（issue-analyzer.md）：

---
on:
  workflow_dispatch:
    inputs:
      issue_number:
        required: true
        type: number
permissions: read-all
tools:
  github:
safe-outputs:
  create-comment:
    max: 1
---

# Issue Analyzer Worker

Analyze issue #${{ inputs.issue_number }}:

1. Read issue title, body, labels, and comments
2. Check for duplicates
3. Assess clarity and completeness
4. Identify missing information
5. Suggest appropriate labels

Post analysis as comment on the issue.
Use structured format:
- Status: [Clear/Unclear/Duplicate]
- Suggested Labels: [label1, label2]
- Action: [what should happen next]

示例 2：分层编排

顶层编排器（repo-health-orchestrator.md）：

---
on: weekly on monday
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Repository Health Orchestrator

Coordinate comprehensive repository health check:

Phase 1: Dispatch specialized orchestrators
1. Dispatch `issue-health-orchestrator`
2. Dispatch `pr-health-orchestrator`
3. Dispatch `code-health-orchestrator`

Phase 2: Wait and collect
1. Wait for all phase 1 orchestrators to complete
2. Collect results from each orchestrator issue

Phase 3: Synthesize
1. Combine results into master health report
2. Generate action items by priority
3. Create issue with complete repository health status

中层编排器（issue-health-orchestrator.md）：

---
on:
  workflow_dispatch:
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Issue Health Orchestrator

Coordinate issue-specific analysis:

1. Dispatch workers for:
   - Stale issue detection
   - Issue categorization
   - Response time analysis
   - Label consistency check

2. Collect worker results
3. Generate issue health report
4. Create issue with findings

示例 3：流水线编排

流水线编排器（deployment-pipeline.md）：

---
on: workflow_dispatch
permissions: read-all
tools:
  github:
safe-outputs:
  create-comment:
    max: 5
---

# Deployment Pipeline Orchestrator

Coordinate deployment pipeline stages:

Stage 1: Validation
1. Dispatch `security-validator` worker
2. Dispatch `test-validator` worker
3. Wait for both, check results
4. If any failures, stop and report

Stage 2: Staging Deployment
1. Dispatch `staging-deployer` worker
2. Wait for completion
3. Dispatch `staging-validator` worker
4. If validation fails, rollback and stop

Stage 3: Production Deployment
1. Require manual approval (create approval issue)
2. After approval, dispatch `production-deployer` worker
3. Dispatch `production-validator` worker
4. Generate deployment report

Post progress comments at each stage.

示例 4：路由器/分发器模式

路由器（issue-router.md）：

---
on: issues
permissions: read-all
tools:
  github:
---

# Issue Router

Route new issues to specialized handlers:

1. Analyze issue labels and content
2. Determine issue type:
   - Bug → dispatch `bug-triage-worker`
   - Feature Request → dispatch `feature-triage-worker`
   - Security → dispatch `security-triage-worker`
   - Documentation → dispatch `docs-triage-worker`
   - General → dispatch `general-triage-worker`

3. Dispatch appropriate worker with issue number
4. Post comment indicating routing decision

示例 5：Map-Reduce 模式

Map-Reduce 编排器（security-audit-orchestrator.md）：

---
on: workflow_dispatch
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
  create-code-scanning-alert:
    max: 1
---

# Security Audit Orchestrator (Map-Reduce)

Coordinate security audit across entire codebase:

MAP PHASE:
1. List all repositories in organization
2. For each repository, dispatch `security-scanner` worker
3. Track dispatched workers

REDUCE PHASE:
1. Wait for all scanners to complete
2. Collect SARIF reports from each worker
3. Aggregate findings:
   - Total vulnerabilities by severity
   - Top vulnerability types
   - Repositories with most issues
4. Generate consolidated SARIF report
5. Create master security issue with summary

示例 6：反思模式

反思编排器（doc-generator-orchestrator.md）：

---
on: workflow_dispatch
permissions: read-all
tools:
  github:
safe-outputs:
  create-pull-request:
    max: 1
---

# Documentation Generator with Reflection

Use reflection pattern for high-quality docs:

Iteration Loop (max 3 iterations):
1. Dispatch `doc-generator` worker to create documentation
2. Dispatch `doc-critic` worker to review generated docs
3. Collect critique feedback
4. If quality score >= 8/10, proceed to next step
5. If quality score < 8/10, regenerate with critique feedback

Final Step:
1. Create pull request with approved documentation
2. Include quality metrics in PR description
3. Link to critic reviews

示例 7：断路器模式

带断路器的编排器（resilient-orchestrator.md）：

---
on: schedule
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Resilient Orchestrator with Circuit Breaker

Coordinate workers with failure protection:

For each task in task_list:
  1. Check circuit breaker state for worker type
  2. If OPEN (too many recent failures), skip and log
  3. If CLOSED, dispatch worker
  4. Track worker success/failure
  5. Update circuit breaker state:
     - 3 consecutive failures → OPEN circuit
     - 1 success after OPEN → HALF-OPEN
     - 3 successes in HALF-OPEN → CLOSED

Generate report with:
- Tasks completed successfully
- Tasks skipped (circuit open)
- Circuit breaker states
- Recommended actions

示例 8：动态工作器池

动态池编排器（scalable-orchestrator.md）：

---
on: workflow_dispatch
permissions: read-all
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Dynamic Worker Pool Orchestrator

Scale workers based on workload:

1. Assess workload size (e.g., count of items to process)
2. Calculate optimal worker count (workload / items_per_worker)
3. Respect concurrency limits (max 10 concurrent workers)
4. Batch items for each worker
5. Dispatch workers with batch assignments
6. Monitor worker progress
7. If workers fail, redistribute work to new workers
8. Aggregate results when all batches complete
9. Generate completion report with metrics:
   - Items processed
   - Workers used
   - Success rate
   - Processing time

最佳实践

编排器设计

• 保持编排逻辑简单、线性
• 使用超时以防止无限等待
• 为长时间运行的协调操作实现健康检查
• 记录所有编排决策
• 生成易于理解的摘要报告

工作器设计

• 确保工作器具备幂等性（可安全重试）
• 在输出中包含工作器 ID，以便追踪
• 为长时间运行的工作器报告进度
• 使用一致的成功/失败信号
• 尽量减少外部依赖

通信

• 所有工作流间数据均使用结构化数据（JSON/YAML）
• 对通信协议进行版本管理
• 验证来自其他工作流的所有输入
• 清晰记录通信约定

测试

• 在编排之前独立测试工作器
• 使用模拟的工作器响应测试编排器
• 测试故障场景（超时、错误）
• 测试部分成功场景
• 使用真实的工作负载进行负载测试

监控

• 跟踪编排执行时间
• 监控工作器成功率
• 编排失败时发出警报
• 衡量端到端延迟
• 通过仪表板展示关键指标

故障排除

Worker 未完成

• 检查 worker 超时设置
• 查看 worker 日志中的错误
• 验证 worker 分发是否成功
• 检查 GitHub Actions 队列状态
• 实施 worker 健康检查

编排挂起

• 验证编排器中的超时逻辑
• 检查是否存在循环依赖
• 查看 worker 状态轮询逻辑
• 确保已处理故障情况

结果不一致

• 验证 worker 的幂等性
• 检查是否存在竞态条件
• 查看结果聚合逻辑
• 验证 worker 通信格式

性能问题

• 优化 worker 批次大小
• 尽可能提高并行度
• 查看编排器轮询频率
• 考虑 worker 缓存策略

相关 ISMS 政策

此技能符合以下政策：

• 安全开发政策 - 安全的编排实践
• 变更管理政策 - 协同部署模式
• 信息安全政策 - 整体安全框架

相关技能

• GitHub Agentic Workflows - 工作流核心基础知识
• Agentic Workflow Security - 编排工作流的安全性
• Agentic Workflow Development - 开发与测试
• Copilot Agent Patterns - 自定义 Agent 模式

相关文档

• Agent Factory 工作流
• 编排指南
• GitHub Actions 可复用工作流

合规性映射

ISO 27001:2022

• A.8.25 安全开发生命周期
• A.8.32 变更管理
• A.5.37 已文档化的操作规程

NIST Cybersecurity Framework 2.0

• PR.IP-02：实施系统开发生命周期
• PR.MA-01：执行维护
• DE.AE-03：收集并关联事件数据

CIS Controls v8.1

• Control 16：应用软件安全
  • 16.1 建立安全开发流程
  • 16.14 建立修复流程

执行

违反编排模式的情况：

• 严重：循环依赖、无限循环 — 阻止部署
• 高：缺少错误处理、未设置超时 — 要求修复
• 中：模式不理想、缺少监控 — 创建改进工单
• 低：文档缺失、优化机会 — 可选改进

版本历史

• 2026-04-02：更新了经 Agent Factory 验证的模式（/plan、任务挖掘）和实际合并率数据
• 2026-02-11：初始创建技能