📖 第三课：高级模式 — 链式触发、预检、形状检测与 PRD 链式推进

# 在 Implement 工作流的最后一步中：
- name: "Request review on new PR"
  run: |
    if [ -n "$AGENT_PAT" ]; then
      # PAT 可用 → 下游 Review 工作流会被自动触发
      GH_TOKEN="$AGENT_PAT" gh pr edit "$PR_NUMBER" --add-label "agent:review"
    else
      # 回退到 GITHUB_TOKEN → 下游不被触发，需要手动帮助
      gh pr edit "$PR_NUMBER" --add-label "agent:review"
      echo "::warning::没有 AGENT_PAT。请手动给 PR 添加 agent:review 标签"
    fi
  env:
    AGENT_PAT: ${{ secrets.AGENT_PAT }}
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

jobs:
  preflight:
    if: github.event.label.name == 'agent:implement'
    runs-on: ubuntu-latest
    outputs:
      proceed: ${{ steps.check_pr.outputs.proceed }}
      reason: ${{ steps.check_pr.outputs.reason }}
    steps:
      # 预检 1: 检查是否存在已有的 PR
      - name: "Check for existing PR"
        id: check_pr
        run: |
          PRS=$(gh pr list --repo "$REPO" --state open \
            --search "Closes #$ISSUE_NUMBER" --json number -q length)
          if [ "$PRS" -gt 0 ]; then
            echo "proceed=false" >> "$GITHUB_OUTPUT"
            echo "reason=已有开放 PR 引用了该 Issue" >> "$GITHUB_OUTPUT"
          else
            echo "proceed=true" >> "$GITHUB_OUTPUT"
          fi

  # 只有预检通过后，这个 job 才运行
  implement:
    needs: preflight
    if: needs.preflight.outputs.proceed == 'true'
    # ... 昂贵的 AI 代理任务 ...

- uses: actions/checkout@v4
  with:
    ref: ${{ github.event.pull_request.head.sha }}
    fetch-depth: 0

# 检测 1: Issue 是否有子 Issue？（REST API）
- name: "Detect sub-issues"
  id: detect
  run: |
    SUB_COUNT=$(gh api "repos/$REPO/issues/$N/sub_issues" \
      --jq 'length')
    echo "has_sub_issues=$([ "$SUB_COUNT" -gt 0 ] \
      && echo true || echo false)" >> "$GITHUB_OUTPUT"

# 检测 2: Issue 是否是子 Issue？（GraphQL — REST 不支持）
    PARENT=$(gh api graphql -f query='
      query($owner:String!, $repo:String!, $number:Int!) {
        repository(owner:$owner, name:$repo) {
          issue(number:$number) {
            parent { number title }
          }
        }
      }
    ' -f owner="$OWNER" -f repo="$REPO" -f number="$N" \
      --jq '.data.repository.issue.parent.number')

    echo "is_sub_issue=$([ -n "$PARENT" ] \
      && echo true || echo false)" >> "$GITHUB_OUTPUT"

┌─────────────────────────────────────────────────────┐ │ 用户添加 agent:implement 标签到 Issue │ └──────────────────────┬──────────────────────────────┘ │ ┌────────────▼────────────┐ │ 阶段 1: 预检 + 形状检测 │ │ ─ 检查子 Issue / 父 Issue│ │ ─ 检查已有 PR │ │ ─ 拒绝不合格的 Issue │ └─────┬──────────┬────────┘ │ │ proceed blocked │ │ ┌──────────▼──────────┐ │ 阶段 2: 状态转换 │ │ ─ remove agent: │ │ implement │ │ ─ remove blocked │ │ + add in-progress │ └──────────┬──────────┘ │ ┌──────────▼──────────┐ │ 阶段 3: AI 代理执行 │ │ ─ 实现代码 │ │ ─ 创建分支 │ │ ─ 提交更改 │ └──────┬──────┬───────┘ │ │ ✅ 成功 ❌ 失败 │ │ ┌────────▼──┐ ┌─▼───────────┐ │ 创建 PR │ │ + blocked │ │ 用 PAT 给 │ │ + 失败评论 │ │ PR 添加 │ │ ─ in-progress│ │ agent: │ └─────────────┘ │ review │ └────┬───────┘ │ ┌────▼──────────┐ │ Review 工作流 │ │ 自动启动！ │ └───────────────┘

┌─ 运行 #1 ─────────────────────────────────────────────┐ │ │ │ ① 形状检测: Issue #42 has_sub_issues=true │ │ → 走 Implement PRD 工作流（不是单 Issue 工作流） │ │ │ │ ② 标签转换: -agent:implement +agent:in-progress │ │ │ │ ③ 找第一个 open 子 Issue: #43 │ │ (gh api ".../issues/42/sub_issues" → 按 API │ │ 返回顺序取第一个 state=open 的) │ │ │ │ ④ 创建/复用分支: agent/prd-42-<slug> │ │ 首次运行 → 从 main 创建 │ │ 后续运行 → checkout 已有分支继续在上面提交 │ │ │ │ ⑤ AI 代理实现子 Issue #43 │ │ 提交信息: "feat: ... Part of #42" │ │ (没有 "Closes #43" — 关闭是工作流的事) │ │ │ │ ⑥ git push (普通 push，不用 --force) │ │ ← 注意：这里不 force！分支上的历史提交要保留 │ │ │ │ ⑦ 关闭子 Issue #43 │ │ gh issue close 43 -c "Done in <commit-sha>" │ │ │ │ ⑧ 检查是否已有 PR → 首次: 没有 → 创建草稿 PR │ │ 标题覆盖整个 PRD，正文含 Closes #42 │ │ ← 这个 PR 只创建一次，后续运行复用 │ │ │ │ ⑨ 检查剩余 open 子 Issue │ │ 结果: #44, #45, #46 还开着 → 还有 3 个! │ │ │ │ ⑩ 重新加标签 (用 PAT!) │ │ GH_TOKEN="$AGENT_PAT" gh issue edit 42 │ │ --add-label "agent:implement" │ │ ← 因为用 PAT，标签会触发新的工作流运行! │ │ │ │ ⑪ 收尾: -agent:in-progress │ │ │ └────────────────────────────────────────────────────────┘ │ ▼ (GitHub 触发新运行) ┌─ 运行 #2 ─────────────────────────────────────────────┐ │ ③ 找第一个 open 子 Issue: #43→已关闭, #44→找到了! │ │ ④ 分支已存在 → checkout 复用 │ │ ⑤ AI 实现 #44，提交到同一分支 │ │ ⑦ 关闭 #44 │ │ ⑨ 检查剩余: #45, #46 还开着 → 还有! │ │ ⑩ 再加 agent:implement → 触发运行 #3 │ └────────────────────────────────────────────────────────┘ │ ▼ ... 运行 #3, #4 ... │ ▼ ┌─ 运行 #4 (最后一个子 Issue #46) ───────────────────────┐ │ ⑦ 关闭 #46 │ │ ⑨ 检查剩余 open 子 Issue: 0 个! │ │ ⑩ 不走 agent:implement 了! │ │ 改加 agent:review 到 PR → 触发 Review 工作流 │ └────────────────────────────────────────────────────────┘