autonomous-orchestration

自主编排

概述

使用 Task 工具启动并行工作 Agent，并通过 TaskOutput 监控其进度，在多个问题中编排长时间运行的自主工作。

核心原则： GitHub 是事实来源。工作 Agent 可随时弃用。状态可在重启后保留。

开始时宣布：“我正在使用 autonomous-orchestration 处理 [SCOPE]。现在开始自主运行。”

前置条件

• 用于通过 Task 工具启动工作 Agent 的 worker-dispatch 技能
• 用于规定工作 Agent 行为的 worker-protocol 技能
• 用于处理 CI/WAKE 的 ci-monitoring 技能
• 已完成身份验证的 GitHub CLI（gh）
• 已配置 GitHub Project 看板

并行执行模型

使用 Task 工具将工作 Agent 作为后台 Agent启动：

Orchestrator
    │
    ├── Task(run_in_background: true) → Worker Agent #1 (task_id: aa93f22)
    ├── Task(run_in_background: true) → Worker Agent #2 (task_id: b51e54b)
    └── Task(run_in_background: true) → Worker Agent #3 (task_id: c72f3d1)

使用 TaskOutput 监控进度：

TaskOutput(task_id: "aa93f22", block: false) → "Task is still running..."
TaskOutput(task_id: "b51e54b", block: false) → Completed with result
TaskOutput(task_id: "c72f3d1", block: false) → "Task is still running..."

重要： 在同一条消息中启动所有工作 Agent，才能实现真正的并发执行。

状态管理

重要： 所有持久化状态都存储在 GitHub 中。Task ID 是临时会话状态。

状态存储	用途	用于
Project Board 状态	唯一事实来源	Ready、In Progress、In Review、Blocked、Done
Issue 评论	活动日志	工作 Agent 分配、进度、偏差
Labels	仅用于追溯关系	spawned-from:#N、depth:N、epic-*
MCP Memory	活动标记 + 任务追踪	检测正在进行的编排、活跃的 task_ids
编排器记忆	临时会话状态	用于监控的 issue# → task_id 映射

参阅： reference/state-management.md，了解详细的状态查询和更新方法。

在上下文压缩后恢复

重要： 编排必须能在循环中途发生上下文压缩后继续运行。

启动时：写入活动标记

# Write to MCP Memory when orchestration starts
mcp__memory__create_entities([{
  "name": "ActiveOrchestration",
  "entityType": "Orchestration",
  "observations": [
    "Status: ACTIVE",
    "Scope: [MILESTONE/EPIC/unbounded]",
    "Tracking Issue: #[NUMBER]",
    "Started: [ISO_TIMESTAMP]",
    "Repository: [owner/repo]",
    "Phase: BOOTSTRAP|MAIN_LOOP",
    "Last Loop: [ISO_TIMESTAMP]"
  ]
}])

每次循环迭代时：更新标记

mcp__memory__add_observations({
  "observations": [{
    "entityName": "ActiveOrchestration",
    "contents": ["Last Loop: [ISO_TIMESTAMP]", "Phase: MAIN_LOOP"]
  }]
})

完成时：移除标记

mcp__memory__delete_entities({
  "entityNames": ["ActiveOrchestration"]
})

会话恢复时（压缩后）

会话启动技能会检查是否存在正在进行的编排：

# Check MCP Memory for active orchestration
ACTIVE=$(mcp__memory__open_nodes({"names": ["ActiveOrchestration"]}))

if [ -n "$ACTIVE" ]; then
  echo "⚠️ ACTIVE ORCHESTRATION DETECTED"
  echo "Scope: [from ACTIVE]"
  echo "Tracking: [from ACTIVE]"
  echo ""
  echo "Resuming orchestration loop..."
  # Invoke autonomous-orchestration skill to resume
fi

这样可以确保： 即使循环中途发生上下文压缩，下一个会话也会检测到正在进行的编排并恢复运行。

立即开始（默认已获用户同意）

用户请求自主运行即表示用户已同意。 无需额外确认。

当用户请求自主工作时：

1. 确定范围——解析用户请求，识别里程碑、Epic、具体问题或“全部”
2. 宣布意图——简要说明即将执行的工作
3. 立即开始——启动编排，无需等待更多输入

## Starting Autonomous Operation

**Scope:** [MILESTONE/EPIC/ISSUES or "all open issues"]
**Workers:** Up to 5 parallel
**Mode:** Continuous until complete

Beginning work now...

不要要求用户回复“PROCEED”或进行任何确认。 用户已请求自主运行，这本身就是确认。

自动确定范围

当用户请求自主运行但未指定范围时：

优先顺序

1. 用户指定的范围——如果用户提到了具体问题、Epic 或里程碑
2. 紧急/高优先级的独立问题——带有 priority:urgent 或 priority:high 标签且不属于任何 Epic 的问题
3. 按 Epic 顺序处理工作——依次处理各个 Epic，并完成每个 Epic 中的所有问题
4. 其余独立问题——不属于任何 Epic 的其他问题

detect_work_scope() {
  # 1. Check for urgent/high priority standalone issues first
  PRIORITY_ISSUES=$(gh issue list --state open \
    --label "priority:urgent,priority:high" \
    --json number,labels \
    --jq '[.[] | select(.labels | map(.name) | any(startswith("epic-")) | not)] | .[].number')

  if [ -n "$PRIORITY_ISSUES" ]; then
    echo "priority_standalone"
    echo "$PRIORITY_ISSUES"
    return
  fi

  # 2. Get epics in order (by creation date)
  EPICS=$(gh issue list --state open --label "type:epic" \
    --json number,title,createdAt \
    --jq 'sort_by(.createdAt) | .[].number')

  if [ -n "$EPICS" ]; then
    echo "epics"
    echo "$EPICS"
    return
  fi

  # 3. Fall back to all open issues
  ALL_ISSUES=$(gh issue list --state open --json number --jq '.[].number')
  echo "all_issues"
  echo "$ALL_ISSUES"
}

持续运行直至完成

自主运行会持续进行，直到满足以下所有条件：

• 范围内没有未关闭的问题
• 没有等待合并的未关闭 PR
• 没有处于“In Progress”或“In Review”状态的问题

运行过程中不会因为以下情况暂停：

• 进度更新
• 处理问题之间的确认
• 在不同 Epic 之间切换
• 任何用户输入（致命错误导致受阻时除外）

PR 处理引导阶段

重要： 启动任何新工作 Agent 之前，先处理所有现有的未关闭 PR。

引导流程： 获取未关闭的 PR（排除 release/*、release-placeholder、do-not-merge）→ 对每个 PR：检查 CI → 确认审查状态 → 条件满足时合并 → 然后开始主循环

引导流程实现

resolve_existing_prs() {
  echo "=== PR RESOLUTION BOOTSTRAP ==="

  # Get all open PRs, excluding release placeholders
  OPEN_PRS=$(gh pr list --json number,headRefName,labels \
    --jq '[.[] | select(
      (.headRefName | startswith("release/") | not) and
      (.labels | map(.name) | index("release-placeholder") | not)
    )] | .[].number')

  if [ -z "$OPEN_PRS" ]; then
    echo "No actionable PRs to resolve. Proceeding to main loop."
    return 0
  fi

  echo "Found PRs to resolve: $OPEN_PRS"

  for pr in $OPEN_PRS; do
    echo "Processing PR #$pr..."

    # Get CI status
    ci_status=$(gh pr checks "$pr" --json state --jq '.[].state' 2>/dev/null | sort -u)

    # Get linked issue
    ISSUE=$(gh pr view "$pr" --json body --jq '.body' | grep -oE 'Closes #[0-9]+' | grep -oE '[0-9]+' | head -1)

    if [ -z "$ISSUE" ]; then
      echo "  ⚠ No linked issue found, skipping"
      continue
    fi

    # Check if CI passed
    if echo "$ci_status" | grep -q "FAILURE"; then
      echo "  ❌ CI failing - triggering ci-monitoring for PR #$pr"
      # Invoke ci-monitoring skill to fix
      handle_ci_failure "$pr"
      continue
    fi

    if echo "$ci_status" | grep -q "PENDING"; then
      echo "  ⏳ CI pending for PR #$pr, will check in main loop"
      continue
    fi

    if echo "$ci_status" | grep -q "SUCCESS"; then
      # Verify review artifact
      REVIEW_EXISTS=$(gh api "/repos/$OWNER/$REPO/issues/$ISSUE/comments" \
        --jq '[.[] | select(.body | contains(""))] | length' 2>/dev/null || echo "0")

      if [ "$REVIEW_EXISTS" = "0" ]; then
        echo "  ⚠ No review artifact - requesting review for #$ISSUE"
        gh issue comment "$ISSUE" --body "## Review Required

PR #$pr has passing CI but no review artifact.

**Action needed:** Complete comprehensive-review and post artifact to this issue.

---
*Bootstrap phase - Orchestrator*"
        continue
      fi

      # All checks pass - merge
      echo "  ✅ Merging PR #$pr"
      gh pr merge "$pr" --squash --delete-branch
      mark_issue_done "$ISSUE"
    fi
  done

  echo "=== BOOTSTRAP COMPLETE ==="
}

发布占位符检测

满足以下条件的 PR 不会纳入引导解析：

条件	示例
分支以 release/ 开头	release/v2.0.0、release/2025-01
带有 release-placeholder 标签	手动排除
带有 do-not-merge 标签	明确暂缓

编排循环

主循环流程： 监控工作进程（TaskOutput）+ 检查 CI/PR + 启动工作进程（Task）→ 评估状态（完成/休眠/继续）

循环步骤

1. 监控活动工作进程 - 对每个活动 task_id 使用 TaskOutput(block: false)
2. 处理已完成的工作进程 - 在 GitHub 上检查 PR/完成状态
3. 检查 CI/PR - 监控是否已准备好合并，并验证评审产物
4. 合并通过检查的 PR - 任何 CI 通过的 PR 都会立即合并
5. 启动工作进程 - 使用 Task(run_in_background: true) 并行启动最多 5 个工作进程
6. 评估状态 - 确定下一步操作（继续、休眠、完成）
7. 短暂停顿 - 每次迭代间隔 30 秒

使用 TaskOutput 监控工作进程

每次循环迭代都会检查所有活动工作进程：

## Monitor Active Workers

For each task_id in active_workers:
  TaskOutput(task_id: "[ID]", block: false, timeout: 1000)

Interpret results:
- "Task is still running..." → Continue monitoring
- Completed → Check GitHub for PR, update project board, remove from active list
- Error → Handle failure, potentially spawn replacement

启动并行工作进程

在一条消息中启动多个工作进程，以便并发执行：

## Dispatch Workers

1. Count available slots: 5 - len(active_workers)
2. Get Ready issues from project board
3. For each issue to dispatch:

Task(
  description: "Issue #123 worker",
  prompt: [WORKER_PROMPT],
  subagent_type: "general-purpose",
  run_in_background: true
)

4. Store returned task_id → issue mapping

关键：立即合并通过检查的 PR

每次循环迭代都必须检查并合并通过检查的 PR：

# In each loop iteration
for pr in $(gh pr list --json number,statusCheckRollup --jq '.[] | select(.statusCheckRollup | all(.conclusion == "SUCCESS")) | .number'); do
  # Check for do-not-merge label
  if ! gh pr view "$pr" --json labels --jq '.labels[].name' | grep -q "do-not-merge"; then
    echo "Merging PR #$pr (CI passed)"
    gh pr merge "$pr" --squash --delete-branch

    # Get linked issue and mark done
    ISSUE=$(gh pr view "$pr" --json body --jq '.body' | grep -oE 'Closes #[0-9]+' | grep -oE '[0-9]+' | head -1)
    if [ -n "$ISSUE" ]; then
      # Update project board status to Done
      mark_issue_done "$ISSUE"
    fi
  fi
done

不要：

• 报告“PR 已准备好合并”后就停止
• 等待用户请求合并
• 总结已完成的工作并询问下一步

循环会持续进行，直到完成范围内的工作。通过检查的 PR = 立即合并。

范围类型

里程碑

gh issue list --milestone "v1.0.0" --state open --json number --jq '.[].number'

Epic

gh issue list --label "epic-dark-mode" --state open --json number --jq '.[].number'

无界（所有未关闭的问题）

gh issue list --state open --json number --jq '.[].number'

不要询问是否确认“UNBOUNDED”。 用户的请求即表示同意。

故障处理

工作进程失败后，不会立即被标记为阻塞：

Attempt 1 → Research → Attempt 2 → Research → Attempt 3 → Research → Attempt 4 → BLOCKED

只有经过 3 次或更多研究周期后，问题才会被标记为阻塞。

参见： reference/failure-recovery.md，了解研究周期的实现方式。

阻塞判定

仅在以下情况下，问题才会被标记为阻塞：

• 已完成多个研究周期（3 次或更多）
• 研究得出结论：“没有外部输入就无法解决”
• 示例：缺少凭据、需要人工决策、外部服务宕机

休眠/唤醒

进入休眠

在以下情况下，编排将进入休眠：

• 所有问题都已阻塞或处于评审中
• 没有外部事件就无法继续工作

状态会发布到 GitHub 跟踪问题中（可在崩溃后保留）。

唤醒机制

• SessionStart 钩子 - 在新的 Claude 会话中检查 CI 状态
• 手动 - claude --resume [SESSION_ID]

检查清单

开始编排前：

• 已确定范围（明确指定或自动检测）
• GitHub CLI 已完成身份验证（gh auth status）
• 已创建带有 orchestration-tracking 标签的跟踪问题
• 项目看板已配置 Status 字段
• 已将活动标记写入 MCP Memory

引导阶段：

• 已检测现有的未关闭 PR
• 已排除发布占位符（release/*、release-placeholder、do-not-merge 标签）
• 已检查每个 PR 的 CI 状态
• 已在合并前验证评审产物
• PR 已合并或已标记为需要关注
• 已完成引导，然后才启动工作进程

编排期间：

• 已使用 Task(run_in_background: true) 启动工作进程
• 已为每个工作进程保存任务 ID（issue# → task_id 映射）
• 已使用 TaskOutput(block: false) 监控工作进程状态
• 已检测并处理已完成的工作进程
• 已更新项目看板状态（进行中、评审中、已完成）
• 已监控未关闭 PR 的 CI 状态
• 已立即合并通过检查的 PR
• 已在合并 PR 前验证评审产物
• 工作进程失败时会触发研究周期
• 交接时会启动替代工作进程
• 仅等待 CI 时会进入休眠
• 每次循环都会检查偏差解决情况
• 已将状态发布到跟踪问题

评审执行

关键： 编排器会验证评审合规性：

1. PR 合并前：

   • Issue 评论中存在评审记录
   • 评审状态为 COMPLETE
   • 未解决的发现数 = 0

2. 子 Issue（由延期处理的发现创建）：

   • 遵循完整的 issue-driven-development 流程
   • 进行各自的代码评审
   • 使用 spawned-from:#N 标签跟踪

3. 偏差处理：

   • 在项目看板上将父项状态设为 Blocked
   • 仅当所有子项都关闭后才恢复

集成

此技能与以下技能协同：

技能	用途
worker-dispatch	派遣工作者
worker-protocol	工作者行为
worker-handover	传递上下文
ci-monitoring	CI 和 WAKE 处理
research-after-failure	研究周期
issue-driven-development	工作者遵循此流程
comprehensive-review	工作者必须在 PR 前完成
project-board-enforcement	所有状态查询和更新

参考文件

• reference/state-management.md - 状态查询、更新和偏差处理
• reference/loop-implementation.md - 完整循环代码和辅助工具
• reference/failure-recovery.md - 研究周期、阻塞处理、SLEEP/WAKE