🤖 第四课：AI 分析 Issue — 第一个 AI 驱动的工作流

预计完成时间：30 分钟  |  难度：中级  |  类型：实践

本课目标

在本课结束时，你将在自己的仓库中部署一个真实工作的 AI 驱动工作流：

• 给 Issue 添加 agent:analyze 标签
• GitHub Actions 自动触发，调用 Claude Code 分析 Issue
• AI 的分析结果自动发布为 Issue 评论

这是你从"看懂别人的工作流"到"自己的仓库跑 AI"的关键一步。

你会看到什么

部署完成后，你的仓库行为如下：

新概念：Agent-Runner 契约

在开始写 YAML 之前，需要理解工作流和 AI 之间如何协作。sandcastle 和 course-video-manager 都遵循同一条设计铁律：

具体的"合同条款"：

第一步：创建 Secret

Claude Code 在 CI 中运行需要一个认证凭证——这个 token 来自 Anthropic（Claude 的开发商），而不是 GitHub。完整链路分两段：

1-A：获取 Claude Code OAuth Token

在你的本地终端执行：

claude login

这会弹出浏览器，跳转到 Anthropic 的 OAuth 授权页面。授权完成后，Claude Code 将 token 保存在本地。用以下命令查看这个 token：

# macOS / Linux
cat ~/.claude/credentials.json

# Windows（PowerShell）
Get-Content "$env:USERPROFILE\.claude\credentials.json"

复制输出中的 OAuth token 值。

1-B：存入 GitHub Repository Secret

1. 进入你的仓库 → Settings → Secrets and variables → Actions
2. 点击 New repository secret
3. Name: CLAUDE_CODE_OAUTH_TOKEN
4. Value: 粘贴刚才从 ~/.claude/credentials.json 中复制的 token
5. 点击 Add secret

第二步：理解工作流 YAML

下面是完整的工作流文件。先通读一遍，然后我们逐段拆解：

# .github/workflows/agent-analyze.yml
name: Agent Analyze Issue

on:
  issues:
    types: [labeled]

jobs:
  analyze:
    if: github.event.label.name == 'agent:analyze'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    concurrency:
      group: agent-analyze-issue-${{ github.event.issue.number }}
      cancel-in-progress: false
    permissions:
      issues: write
      contents: read

    env:
      ISSUE_NUMBER: ${{ github.event.issue.number }}
      ISSUE_TITLE: ${{ github.event.issue.title }}
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      GH_REPO: ${{ github.repository }}

    steps:
      # ── 阶段 1: 标签转换 ──
      - name: Transition to in-progress
        run: |
          gh issue edit "$ISSUE_NUMBER" --remove-label "agent:analyze" || true
          gh issue edit "$ISSUE_NUMBER" --remove-label "agent:blocked" || true
          gh issue edit "$ISSUE_NUMBER" --add-label "agent:in-progress"

      # ── 阶段 2: 准备环境 ──
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      # ── 阶段 3: 获取上下文 ──
      - name: Fetch issue body
        run: |
          gh issue view "$ISSUE_NUMBER" --json title,body,labels \
            > "$RUNNER_TEMP/issue-context.json"

      # ── 阶段 4: AI 分析 ──
      - name: Run AI analysis
        id: analyze
        env:
          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
        run: |
          claude -p "$(cat <<'PROMPT'
          你是一个软件架构分析助手。下面是一个 GitHub Issue 的 JSON 数据。
          请阅读这个 Issue 并用中文做以下分析：

          1. **需求理解**：用 2-3 句话总结 Issue 想解决的问题
          2. **技术方案**：提出 1-2 个可行的技术实现思路
          3. **潜在风险**：指出实现中需要注意的 1-3 个风险点
          4. **建议的下一步**：给出具体的行动建议

          请直接输出分析结果，不要做其他操作。
          PROMPT
          )" --output-format text --allowedTools Read,Grep,Glob \
          > "$RUNNER_TEMP/analysis.md"

      # ── 阶段 5: 发布结果 ──
      - name: Post analysis as comment
        if: success()
        run: |
          {
            echo "## 🤖 AI 分析结果"
            echo
            echo "> 由 Claude Code 自动生成 | Issue #$ISSUE_NUMBER"
            echo
            cat "$RUNNER_TEMP/analysis.md"
          } | gh issue comment "$ISSUE_NUMBER" --body-file -

      # ── 阶段 6: 标签收尾 ──
      - name: Mark analyzed
        if: success()
        run: |
          gh issue edit "$ISSUE_NUMBER" --remove-label "agent:in-progress" || true
          gh issue edit "$ISSUE_NUMBER" --add-label "agent:analyzed"

      - name: Mark blocked on failure
        if: failure()
        run: |
          gh issue edit "$ISSUE_NUMBER" --add-label "agent:blocked" || true
          gh issue edit "$ISSUE_NUMBER" --remove-label "agent:in-progress" || true
          gh issue comment "$ISSUE_NUMBER" \
            --body "❌ AI 分析失败。请检查 [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) 的日志。修复后重新添加 \`agent:analyze\` 标签重试。"

逐段拆解

阶段 1：标签转换

- name: Transition to in-progress
  run: |
    gh issue edit "$ISSUE_NUMBER" --remove-label "agent:analyze" || true
    gh issue edit "$ISSUE_NUMBER" --remove-label "agent:blocked" || true
    gh issue edit "$ISSUE_NUMBER" --add-label "agent:in-progress"

这是你在第 2 课学到的状态机模式。不同的是这里用了 shell 层的 || true 来处理标签可能不存在的情况——如果 Issue 上没有 agent:blocked，gh issue edit --remove-label 会报错退出（非零状态码），|| true 让它"忽略这个错误，继续执行"。

阶段 2：环境准备

- uses: actions/checkout@v4
  with:
    fetch-depth: 1         # 只拉最新 commit，分析 Issue 不需要完整历史

- uses: actions/setup-node@v4
  with:
    node-version: 22

- name: Install Claude Code
  run: npm install -g @anthropic-ai/claude-code

三个标准步骤。注意 fetch-depth: 1 —— AI 分析 Issue 不需要 git 历史，拉最少就够了（回顾第 3 课的 fetch-depth 讨论）。

npm install -g @anthropic-ai/claude-code 全局安装 Claude Code CLI，之后就可以直接执行 claude 命令。

阶段 3：获取上下文

- name: Fetch issue body
  run: |
    gh issue view "$ISSUE_NUMBER" --json title,body,labels \
      > "$RUNNER_TEMP/issue-context.json"

用 gh issue view --json 把 Issue 数据导出为 JSON 文件。这样做的好处是：AI 可以在后续步骤中读取这个文件获取完整上下文，而不是依赖可能截断的环境变量。

$RUNNER_TEMP 是 GitHub Actions 提供的临时目录，工作流结束后自动清理。

阶段 4：AI 分析 — 核心步骤

- name: Run AI analysis
  id: analyze
  env:
    CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
  run: |
    claude -p "$(cat <<'PROMPT'
    你是一个软件架构分析助手。下面是一个 GitHub Issue 的 JSON 数据。
    请阅读这个 Issue 并用中文做以下分析：

    1. **需求理解**：用 2-3 句话总结 Issue 想解决的问题
    2. **技术方案**：提出 1-2 个可行的技术实现思路
    3. **潜在风险**：指出实现中需要注意的 1-3 个风险点
    4. **建议的下一步**：给出具体的行动建议

    请直接输出分析结果，不要做其他操作。
    PROMPT
    )" --output-format text --allowedTools Read,Grep,Glob \
    > "$RUNNER_TEMP/analysis.md"

这一段的要点：

阶段 5：发布结果

- name: Post analysis as comment
  if: success()
  run: |
    {
      echo "## 🤖 AI 分析结果"
      echo
      echo "> 由 Claude Code 自动生成 | Issue #$ISSUE_NUMBER"
      echo
      cat "$RUNNER_TEMP/analysis.md"
    } | gh issue comment "$ISSUE_NUMBER" --body-file -

这里体现了 Agent-Runner 契约的精髓：AI 只输出文件，工作流负责发布。{ ... } | gh issue comment --body-file - 把 AI 的分析结果加上标题头，通过管道传给 gh CLI 发布。AI 从头到尾没有碰过 GitHub token。

阶段 6：标签收尾

# 成功路径
- name: Mark analyzed
  if: success()
  run: |
    gh issue edit "$ISSUE_NUMBER" --remove-label "agent:in-progress" || true
    gh issue edit "$ISSUE_NUMBER" --add-label "agent:analyzed"

# 失败路径
- name: Mark blocked on failure
  if: failure()
  run: |
    gh issue edit "$ISSUE_NUMBER" --add-label "agent:blocked" || true
    gh issue edit "$ISSUE_NUMBER" --remove-label "agent:in-progress" || true
    gh issue comment "$ISSUE_NUMBER" --body "❌ ..."

状态机收尾——第 2 课的模式在这里完整落地：

注意 agent:in-progress 两个分支都会移除——

第三步：部署到你的仓库

1. 在你的仓库中创建 .github/workflows/agent-analyze.yml
2. 将上面完整的 YAML 内容粘贴进去
3. 确认 CLAUDE_CODE_OAUTH_TOKEN secret 已创建（第一步）
4. 预先创建三个标签：agent:analyze、agent:in-progress、agent:analyzed、agent:blocked
5. 提交并推送到默认分支
6. 创建一个测试 Issue，添加 agent:analyze 标签
7. 观察 Actions 面板 → 等待完成 → 查看 Issue 评论

✏️ 诊断性测验

🎯 总结：你学到了什么

推荐进一步阅读

• 主阅读材料：sandcastle agent-implement.yml — 完整的 AI 实现工作流，对比你刚写的 analyze 工作流，观察相同模式和扩展之处
• Claude Code 官方文档 — --print、--allowedTools、--output-format 等 CLI 参数的完整说明
• GitHub Docs: 在 Actions 中使用 Secrets
• 参考文档：标签工作流语法速查表