<!-- title: Claude Code CI/CD全实战：Actions到Agent SDK -->

# Claude Code CI/CD全实战：GitHub Actions到Agent SDK

## 概述

本教程面向希望在CI/CD流水线中集成Claude Code的开发者和DevOps工程师。你将学会三种自动化路径：GitHub Actions官方Action集成、Headless模式脚本编排、以及Agent SDK程序化调用。学完后，你的团队可以在每次PR触发AI代码审查、定时批量重构、甚至构建自定义AI Agent串联整个交付流程。

**适用人群**：有基础命令行经验的开发者、DevOps工程师、技术负责人
**预计教学时长**：6-8小时（含实战练习）

## 前置条件

- Claude Code CLI已安装（`npm install -g @anthropic-ai/claude-code`）
- 一个GitHub仓库的管理权限
- Anthropic API Key（从console.anthropic.com获取）
- Python 3.10+或Node.js 18+（Agent SDK二选一）
- 基本的YAML和shell脚本知识

## 整体架构：三条自动化路径

```mermaid
flowchart TB
    subgraph 触发层
        PR[Pull Request事件]
        Issue[Issue评论 @claude]
        Schedule[定时任务 cron]
        Manual[手动触发 workflow_dispatch]
        API[外部API调用]
    end

    subgraph 路径A[路径A: GitHub Actions]
        A1[claude-code-action@v1]
        A2[自动PR审查]
        A3[Issue自动实现]
        A1 --> A2
        A1 --> A3
    end

    subgraph 路径B[路径B: Headless模式]
        B1[claude -p '提示词']
        B2[stdin/stdout管道]
        B3[shell脚本编排]
        B1 --> B2 --> B3
    end

    subgraph 路径C[路径C: Agent SDK]
        C1[Python: claude_agent_sdk]
        C2[TypeScript: @anthropic-ai/claude-code]
        C3[自定义工具+Hook]
        C1 --> C3
        C2 --> C3
    end

    PR --> A1
    Issue --> A1
    Schedule --> B1
    Manual --> B1
    API --> C1
    API --> C2

    style 路径A fill:#e8f5e9
    style 路径B fill:#e3f2fd
    style 路径C fill:#fff3e0
```

---

## 第一章：GitHub Actions官方集成

### 1.1 三步快速接入

Anthropic提供的`anthropics/claude-code-action`是官方GitHub Action，零代码即可在PR和Issue上触发Claude Code。

**步骤一：配置API Key**

进入你的GitHub仓库 → Settings → Secrets and variables → Actions → New repository secret，添加：

```
名称: ANTHROPIC_API_KEY
值: sk-ant-api03-xxxxx
```

**步骤二：创建Workflow文件**

在仓库中创建`.github/workflows/claude.yml`：

```yaml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

**步骤三：触发使用**

- PR自动审查：每次创建或更新PR时，Claude自动读取diff并给出审查意见
- Issue评论触发：在Issue或PR评论中输入`@claude`开头即可触发

```mermaid
sequenceDiagram
    participant Dev as 开发者
    participant GH as GitHub
    participant GHA as GitHub Actions
    participant CC as Claude Code Action
    participant PR as Pull Request

    Dev->>GH: 创建PR
    GH->>GHA: 触发 pull_request 事件
    GHA->>CC: 启动 claude-code-action@v1
    CC->>PR: 读取diff和上下文
    CC->>CC: 分析代码变更
    CC->>PR: 发布审查评论
    Note over PR: 带有具体建议的行内评论

    Dev->>PR: 评论 @claude 请修复这个问题
    PR->>GHA: 触发 issue_comment 事件
    GHA->>CC: 启动action，传入评论内容
    CC->>PR: 自动push修复commit
```

### 1.2 进阶配置：权限控制与自定义提示

官方Action支持精细化的权限控制：

```yaml
jobs:
  claude-advanced:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # 限制可用工具，防止CI环境中执行危险操作
          allowed_tools: |
            Read
            Glob
            Grep
            Bash(git diff*)
            Bash(git log*)
          # 自定义系统提示词
          custom_instructions: |
            你是一个代码审查专家。请重点关注：
            1. 安全漏洞（SQL注入、XSS等）
            2. 性能问题（N+1查询、内存泄漏）
            3. 测试覆盖率不足
            用中文回复，给出具体的改进建议和代码示例。
          # 指定使用的模型
          model: claude-sonnet-4-6
```

### 1.3 三种典型CI场景

**场景一：每次PR自动审查**

```yaml
on:
  pull_request:
    types: [opened, synchronize, ready_for_review]
```

**场景二：定时代码质量扫描**

```yaml
on:
  schedule:
    - cron: '0 2 * * 1'  # 每周一凌晨2点
  workflow_dispatch:  # 同时支持手动触发

jobs:
  weekly-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Code analysis
        run: |
          npm install -g @anthropic-ai/claude-code
          claude -p "审查整个src/目录，找出所有潜在的TypeScript类型安全问题、未处理的Promise、以及可以优化的异步代码。输出格式化的Markdown报告。" \
            --allowedTools "Read,Glob,Grep" \
            --output-format text > report.md
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - name: Create Issue from report
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('report.md', 'utf8');
            await github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: `Weekly Code Review - ${new Date().toISOString().split('T')[0]}`,
              body: report,
              labels: ['automated-review']
            });
```

**场景三：CI失败自动修复**

```yaml
on:
  workflow_run:
    workflows: ["CI"]  # 监听你的CI workflow
    types: [completed]

jobs:
  auto-fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_branch }}
      - name: Get CI failure logs
        run: |
          # 获取失败的CI日志
          gh run view ${{ github.event.workflow_run.id }} --log-failed > ci-errors.txt
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Claude auto-fix
        run: |
          claude -p "$(cat ci-errors.txt)" \
            --allowedTools "Read,Edit,Bash(npm test*),Bash(git *)" \
            --output-format text
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```

### 1.4 常见问题与解决方案

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| Action无响应 | API Key未配置或无效 | 检查Secret名称和Key有效性 |
| 审查评论过长 | 默认审查范围过大 | 在`custom_instructions`中限定审查维度 |
| 超时失败 | 大型PR处理时间过长 | 使用`timeout-minutes: 10`增加超时 |
| 权限被拒绝 | `permissions`配置不全 | 确保包含`contents: write`和`pull-requests: write` |

---

## 第二章：Headless模式深度实战

### 2.1 核心参数全景

Headless模式通过`-p`（或`--print`）标志启动，将Claude Code从交互式工具变为命令行管道工具：

```bash
# 基础用法：单次提示
claude -p "解释这个项目的架构"

# 管道输入：将文件内容作为上下文
cat src/main.ts | claude -p "重构这个文件，提取可复用的函数"

# JSON输出：便于程序解析
claude -p "列出所有TODO注释" --output-format json

# 流式JSON：实时获取Agent执行过程
claude -p "修复所有lint错误" --output-format stream-json

# 限制工具权限
claude -p "检查安全漏洞" --allowedTools "Read,Glob,Grep"

# 指定模型
claude -p "性能优化建议" --model claude-sonnet-4-6

# 组合使用：完整参数
claude -p "为所有API端点编写集成测试" \
  --output-format json \
  --allowedTools "Read,Write,Edit,Glob,Grep,Bash(npm test*)" \
  --model claude-sonnet-4-6 \
  --max-turns 30
```

### 2.2 输出格式详解

三种输出格式对应不同场景：

```mermaid
flowchart LR
    subgraph text["text 纯文本"]
        T1[简单查询]
        T2[邮件/报告生成]
        T3[管道到其他命令]
    end

    subgraph json["json 结构化"]
        J1[程序解析]
        J2[CI结果判定]
        J3[数据库存储]
    end

    subgraph stream["stream-json 流式"]
        S1[实时监控]
        S2[进度追踪]
        S3[超长时间任务]
    end

    text -->|简单| D{场景选择}
    json -->|需要解析| D
    stream -->|长任务| D
```

**text格式**：直接输出纯文本，适合人类阅读或管道传递：

```bash
# 生成变更日志
claude -p "根据最近的git log生成CHANGELOG.md" \
  --output-format text > CHANGELOG.md
```

**json格式**：结构化输出，适合程序处理：

```bash
# 分析结果输出为JSON
claude -p "分析package.json中的所有依赖，按风险等级分类" \
  --output-format json | jq '.result'
```

**stream-json格式**：实时流式输出，适合监控长时间运行的任务：

```bash
# 流式输出并实时解析
claude -p "重构整个src目录，将所有class组件转为函数组件" \
  --output-format stream-json | \
  while read line; do
    event=$(echo "$line" | jq -r '.type')
    if [ "$event" = "tool_use" ]; then
      echo "🔧 使用工具: $(echo "$line" | jq -r '.tool_name')"
    elif [ "$event" = "text_delta" ]; then
      echo -n "$(echo "$line" | jq -r '.text')"
    fi
  done
```

### 2.3 stdin多轮对话

Headless模式支持通过stdin传入多轮对话，实现复杂的工作流：

```bash
# 多轮对话：每行一个JSON消息
echo '{"role":"user","content":"分析这个项目的目录结构，找出架构问题"}' | \
  claude -p --input-format messages --output-format json
```

更复杂的多轮场景，通过会话恢复实现：

```bash
# 第一轮：分析问题
SESSION=$(claude -p "分析src/api/目录下的所有endpoint，列出缺少错误处理的" \
  --output-format json | jq -r '.session_id')

# 第二轮：基于前一轮上下文修复
claude -p "请修复上一轮列出的所有问题" \
  --resume "$SESSION" \
  --output-format text
```

### 2.4 批量任务编排实战

**实战：批量更新多个仓库的依赖**

创建`batch-update-deps.sh`：

```bash
#!/bin/bash
set -euo pipefail

# 仓库列表
REPOS=(
  "org/frontend-app"
  "org/backend-api"
  "org/shared-libs"
  "org/admin-dashboard"
  "org/mobile-gateway"
)

# 要更新的依赖模式
UPDATE_PATTERN="$1"  # 例如 "lodash" 或 "eslint*"

BRANCH_NAME="deps/update-${UPDATE_PATTERN}-$(date +%Y%m%d)"

for repo in "${REPOS[@]}"; do
  echo "====== 处理仓库: $repo ======"

  # 克隆仓库
  git clone "https://github.com/$repo.git" "/tmp/$repo" 2>/dev/null
  cd "/tmp/$repo"

  # 创建分支
  git checkout -b "$BRANCH_NAME"

  # Claude执行依赖更新
  RESULT=$(claude -p "更新与 '${UPDATE_PATTERN}' 相关的所有npm依赖到最新版本。步骤：
    1. 检查当前版本
    2. 运行npm update或npm install更新
    3. 确保没有breaking changes
    4. 如果有breaking changes，做必要的代码适配
    5. 运行npm test确保通过
    如果测试失败，回滚并报告失败原因。" \
    --allowedTools "Read,Write,Edit,Bash(npm*),Bash(git*)" \
    --max-turns 50 \
    --output-format json)

  # 检查结果
  SUCCESS=$(echo "$RESULT" | jq -r '.success // false')

  if [ "$SUCCESS" = "true" ]; then
    # 提交并推送
    git add -A
    git commit -m "chore: update ${UPDATE_PATTERN} dependencies"
    git push origin "$BRANCH_NAME"

    # 创建PR
    gh pr create \
      --title "chore: update ${UPDATE_PATTERN} dependencies" \
      --body "Automated dependency update by Claude Code" \
      --label "dependencies,automated"

    echo "✅ $repo 更新成功，PR已创建"
  else
    echo "❌ $repo 更新失败: $(echo "$RESULT" | jq -r '.error // unknown')"
  fi

  # 清理
  cd -
  rm -rf "/tmp/$repo"
done

echo "====== 批量更新完成 ======"
```

运行：

```bash
chmod +x batch-update-deps.sh
./batch-update-deps.sh "lodash"
```

---

## 第三章：Agent SDK程序化调用

### 3.1 Agent SDK概述

Claude Agent SDK将Claude Code的完整Agent循环暴露为Python和TypeScript库，你可以：

- 在自己的程序中启动Claude Code Agent
- 注册自定义工具（Tool）
- 监听流式事件（Streaming Events）
- 编排多Agent协作

```text
flowchart TB
    subgraph 你的应用
        A[Python/TypeScript代码]
    end

    subgraph Agent SDK
        B[query函数]
        C[ClaudeSDKClient]
        D[自定义Tool注册]
        E[Hook事件回调]
        F[流式StreamEvent]
    end

    subgraph Claude Code引擎
        G[Agent循环]
        H[内置工具<br/>Read/Write/Edit/Bash]
        I[MCP服务器]
    end

    A -->|调用| B
    A -->|创建| C
    C --> D
    C --> E
    B --> G
    C --> G
    G --> H
    G --> I
    G -->|返回| F
    F --> A

    style Agent SDK fill:#fff3e0
    style Claude Code引擎 fill:#e8f5e9
```

### 3.2 Python SDK快速开始

**安装**：

```bash
pip install claude-agent-sdk
```

**最小示例**：

```python
from claude_agent_sdk import query

# 最简单的调用
result = query("分析当前目录结构，找出可以改进的地方")
print(result)
```

**使用Client进行流式调用**：

```python
from claude_agent_sdk import ClaudeSDKClient
from claude_agent_sdk.types import StreamEvent

client = ClaudeSDKClient()

# 流式处理
for event in client.stream("重构src/utils.ts，提取所有可复用的helper函数"):
    if isinstance(event, StreamEvent.TextDelta):
        print(event.text, end="", flush=True)
    elif isinstance(event, StreamEvent.ToolUse):
        print(f"\n[工具调用] {event.tool_name}: {event.tool_input}")
    elif isinstance(event, StreamEvent.ToolResult):
        print(f"[工具结果] 成功: {event.is_success}")
```

### 3.3 注册自定义工具

这是Agent SDK最强大的能力——扩展Claude的工具集：

```python
from claude_agent_sdk import ClaudeSDKClient, tool
from claude_agent_sdk.types import StreamEvent

client = ClaudeSDKClient()

# 注册自定义工具：查询内部API
@tool(name="query_internal_api", description="查询内部REST API获取服务状态和指标")
def query_internal_api(endpoint: str, method: str = "GET") -> str:
    """查询内部API端点并返回结果。
    
    Args:
        endpoint: API端点路径，如 /api/v1/services/status
        method: HTTP方法，默认GET
    """
    import requests
    base_url = "http://internal-api.company.com"
    response = requests.request(method, f"{base_url}{endpoint}", timeout=10)
    return response.text

# 注册自定义工具：发送Slack通知
@tool(name="send_slack_alert", description="向指定Slack频道发送告警消息")
def send_slack_alert(channel: str, message: str, severity: str = "info") -> str:
    """发送Slack告警通知。
    
    Args:
        channel: Slack频道名称，如 #ops-alerts
        message: 告警消息内容
        severity: 严重程度 info/warning/critical
    """
    import requests
    webhook_url = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
    emoji = {"info": "ℹ️", "warning": "⚠️", "critical": "🚨"}.get(severity, "📢")
    payload = {
        "channel": channel,
        "text": f"{emoji} [{severity.upper()}] {message}"
    }
    response = requests.post(webhook_url, json=payload)
    return f"消息已发送到 {channel}，状态码: {response.status_code}"

# 使用自定义工具进行巡检
for event in client.stream(
    "执行以下巡检任务：\n"
    "1. 查询所有微服务状态\n"
    "2. 检查每个服务的错误率\n"
    "3. 如果发现异常，向 #ops-alerts 发送critical级别告警\n"
    "4. 生成巡检报告摘要"
):
    if isinstance(event, StreamEvent.TextDelta):
        print(event.text, end="", flush=True)
    elif isinstance(event, StreamEvent.ToolUse):
        print(f"\n→ 调用工具: {event.tool_name}")
```

### 3.4 TypeScript SDK快速开始

**安装**：

```bash
npm install @anthropic-ai/claude-code
```

**使用示例**：

```typescript
import { query, ClaudeCodeClient } from '@anthropic-ai/claude-code';

// 简单调用
const result = await query(
  '审查src/目录下的所有TypeScript文件，找出any类型的使用'
);
console.log(result);

// 流式调用
const client = new ClaudeCodeClient();

for await (const event of client.stream(
  '为src/api/下所有endpoint添加JSDoc文档注释'
)) {
  switch (event.type) {
    case 'text_delta':
      process.stdout.write(event.text);
      break;
    case 'tool_use':
      console.log(`\n[Tool] ${event.tool_name}`);
      break;
    case 'tool_result':
      console.log(`[Done] ${event.is_success ? '✓' : '✗'}`);
      break;
  }
}
```

### 3.5 Hook回调机制

Agent SDK支持Hook，让你在Agent执行的关键节点注入逻辑：

```python
from claude_agent_sdk import ClaudeSDKClient, HookType

client = ClaudeSDKClient()

# PreToolUse Hook：在工具执行前拦截
@client.hook(HookType.PRE_TOOL_USE)
def on_before_tool(tool_name: str, tool_input: dict) -> dict:
    """在工具执行前的回调。返回修改后的tool_input或抛出异常阻止执行。"""
    if tool_name == "Bash":
        command = tool_input.get("command", "")
        # 安全检查：禁止执行危险命令
        dangerous_patterns = ["rm -rf", "DROP TABLE", "force push", ":(){:|:&};:"]
        for pattern in dangerous_patterns:
            if pattern in command:
                raise ValueError(f"安全拦截：禁止执行包含 '{pattern}' 的命令")
        
        # 记录所有命令执行
        with open("/var/log/claude-commands.log", "a") as f:
            f.write(f"[{tool_name}] {command}\n")
    
    return tool_input  # 返回（可能修改后的）tool_input

# PostToolUse Hook：工具执行后的回调
@client.hook(HookType.POST_TOOL_USE)
def on_after_tool(tool_name: str, tool_input: dict, result: str, success: bool):
    """工具执行完成后的回调。可用于审计、通知等。"""
    if tool_name == "Edit" and not success:
        # 编辑失败时发送通知
        print(f"⚠️ 文件编辑失败: {tool_input.get('file_path', 'unknown')}")
    
    if tool_name == "Bash":
        # 记录所有bash命令结果
        import logging
        logger = logging.getLogger("claude-audit")
        logger.info(f"Command: {tool_input.get('command')} -> Success: {success}")
```

---

## 第四章：实战案例——全自动代码审查与修复流水线

### 4.1 项目结构

构建一个完整的自动化流水线，实现以下功能：

```mermaid
flowchart TB
    subgraph 触发器
        T1[PR创建/更新]
        T2[每日定时扫描]
        T3[Issue @claude触发]
    end

    subgraph GitHub Actions Workflow
        A1[检出代码]
        A2[Claude自动审查]
        A3{发现问题?}
        A4[创建审查评论]
        A5[自动修复并推送]
        A6[运行测试验证]
        A7{测试通过?}
        A8[保留修复]
        A9[回滚并报告]
    end

    subgraph 报告层
        R1[Slack通知]
        R2[GitHub Dashboard]
        R3[邮件摘要]
    end

    T1 --> A1
    T2 --> A1
    T3 --> A1
    A1 --> A2 --> A3
    A3 -->|是| A4
    A3 -->|否| R1
    A4 --> A5 --> A6 --> A7
    A7 -->|通过| A8 --> R1
    A7 -->|失败| A9 --> R1
    R1 --> R2 --> R3
```

### 4.2 完整Workflow配置

创建`.github/workflows/claude-pipeline.yml`：

```yaml
name: Claude Code Pipeline

on:
  pull_request:
    types: [opened, synchronize]
  schedule:
    - cron: '0 6 * * 1-5'  # 工作日每天早上6点
  issue_comment:
    types: [created]

concurrency:
  group: claude-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: write
  pull-requests: write
  issues: write
  checks: write

env:
  CLAUDE_MODEL: claude-sonnet-4-6

jobs:
  # 作业1：自动审查
  review:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    outputs:
      has_issues: ${{ steps.analyze.outputs.has_issues }}
      report: ${{ steps.analyze.outputs.report }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

      - name: Get PR diff
        id: diff
        run: |
          git diff origin/main...HEAD > pr-diff.txt
          echo "lines=$(wc -l < pr-diff.txt)" >> $GITHUB_OUTPUT

      - name: Claude Code Review
        id: analyze
        run: |
          REPORT=$(claude -p "你是一个高级代码审查专家。请审查以下PR diff，重点检查：

          1. **安全漏洞**: SQL注入、XSS、CSRF、硬编码密钥
          2. **性能问题**: N+1查询、内存泄漏、不必要的同步操作
          3. **代码质量**: 命名规范、函数复杂度、重复代码
          4. **测试覆盖**: 是否有对应的测试用例
          5. **兼容性**: 是否引入breaking changes

          输出格式：
          - 如果没有严重问题，输出: PASS
          - 如果有问题，按严重程度列出，每个问题给出文件名、行号和修复建议

          DIFF内容:
          $(cat pr-diff.txt)" \
            --allowedTools "Read,Glob,Grep" \
            --output-format text \
            --model ${{ env.CLAUDE_MODEL }})

          echo "report<<EOF" >> $GITHUB_OUTPUT
          echo "$REPORT" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

          if echo "$REPORT" | grep -q "PASS"; then
            echo "has_issues=false" >> $GITHUB_OUTPUT
          else
            echo "has_issues=true" >> $GITHUB_OUTPUT
          fi
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Post Review Comment
        if: steps.analyze.outputs.has_issues == 'true'
        uses: actions/github-script@v7
        with:
          script: |
            const report = `${{ steps.analyze.outputs.report }}`;
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: `## 🤖 Claude Code Review\n\n${report}`
            });

  # 作业2：自动修复
  auto-fix:
    needs: review
    if: needs.review.outputs.has_issues == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}
          token: ${{ secrets.GITHUB_TOKEN }}

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

      - name: Claude Auto-Fix
        run: |
          claude -p "根据以下审查报告修复所有问题：

          ${{ needs.review.outputs.report }}

          修复后运行测试确保没有引入新问题。" \
            --allowedTools "Read,Write,Edit,Bash(npm*),Bash(git*)" \
            --model ${{ env.CLAUDE_MODEL }} \
            --max-turns 50
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Run Tests
        id: test
        run: npm test
        continue-on-error: true

      - name: Commit and Push Fix
        if: steps.test.outcome == 'success'
        run: |
          git config user.name "Claude Code Bot"
          git config user.email "claude-bot[bot]@users.noreply.github.com"
          git add -A
          git diff --staged --quiet || git commit -m "fix: auto-fix review issues [skip ci]"
          git push

      - name: Report Failure
        if: steps.test.outcome == 'failure'
        uses: actions/github-script@v7
        with:
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: '⚠️ Claude自动修复后测试未通过，已回滚。请手动处理。'
            });

  # 作业3：每日代码质量扫描
  daily-scan:
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Quality Scan
        run: |
          REPORT=$(claude -p "对整个代码库进行全面质量扫描，输出以下维度的评估报告：

          1. **技术债务评分** (1-10): 找出所有TODO、FIXME、HACK注释
          2. **安全扫描**: 检查硬编码密钥、不安全的依赖
          3. **性能热力图**: 识别可能的性能瓶颈
          4. **测试覆盖率评估**: 分析测试文件和源文件的比例
          5. **依赖健康度**: 检查过时或有漏洞的依赖

          每个维度给出评分和改进建议。" \
            --allowedTools "Read,Glob,Grep,Bash(npm*),Bash(git*)" \
            --output-format text \
            --model ${{ env.CLAUDE_MODEL }})
          
          echo "$REPORT" > quality-report.md
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Create Quality Issue
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('quality-report.md', 'utf8');
            const date = new Date().toISOString().split('T')[0];
            await github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: `📊 Weekly Quality Report - ${date}`,
              body: report,
              labels: ['quality-report', 'automated']
            });
```

### 4.3 验证流水线

推送workflow文件后，通过以下方式触发：

```bash
# 方式1：创建PR自动触发审查
git checkout -b test-claude-ci
echo "// TODO: fix this later" >> src/index.ts
git add . && git commit -m "test: trigger claude review"
git push origin test-claude-ci
gh pr create --title "Test: Claude CI Pipeline" --body "Testing Claude auto-review"

# 方式2：在PR评论中触发
gh pr comment 123 --body "@claude 请检查这个PR中是否有安全隐患"

# 方式3：手动触发定时扫描
gh workflow run claude-pipeline.yml
```

---

## 第五章：计费变更与成本控制

### 5.1 2026年6月15日计费拆分

Anthropic宣布从**2026年6月15日**起，将Claude订阅的计费拆分为两个独立的池：

```mermaid
flowchart LR
    subgraph 变更前["2026年6月15日前"]
        A[Claude订阅<br/>Pro/Max/Team] --> B[所有用途共用<br/>同一额度池]
        B --> C[交互式使用]
        B --> D[Agent SDK]
        B --> E[claude -p]
        B --> F[GitHub Actions]
    end

    subgraph 变更后["2026年6月15日后"]
        G[Claude订阅<br/>Pro/Max/Team] --> H[交互式使用<br/>原有额度]
        G --> I[自动化用量<br/>独立Credit池<br/>按API计费]
        I --> J[Agent SDK]
        I --> K[claude -p]
        I --> L[GitHub Actions]
    end

    变更前 -.->|拆分| 变更后
```

**关键影响**：
- `claude -p`（Headless模式）的用量不再占用你的交互式订阅额度
- Agent SDK的使用将通过独立的API Credit池计费
- GitHub Actions中的Claude Code同样计入新的自动化额度池
- 需要在Anthropic Console中为自动化用途单独配置预算

### 5.2 成本控制策略

```bash
# 策略1：使用--max-turns限制Agent循环次数
claude -p "修复lint错误" --max-turns 10

# 策略2：使用更经济的模型处理简单任务
claude -p "格式化代码" --model claude-haiku-4-5

# 策略3：限制工具范围减少token消耗
claude -p "检查README中的拼写错误" --allowedTools "Read"

# 策略4：CI中添加超时保护
timeout 300 claude -p "分析代码" --output-format text
```

在GitHub Actions中添加预算保护：

```yaml
- name: Claude with budget guard
  run: |
    # 设置最大执行时间
    timeout 600 claude -p "$PROMPT" \
      --max-turns 30 \
      --model claude-sonnet-4-6 \
      --output-format text || echo "Claude执行超时或失败"
```

---

## 第六章：安全最佳实践

### 6.1 CI环境安全清单

```mermaid
flowchart TB
    S[CI安全策略] --> A[API Key保护]
    S --> B[工具权限限制]
    S --> C[网络隔离]
    S --> D[审计日志]
    S --> E[输入验证]

    A --> A1[使用GitHub Secrets]
    A --> A2[不记录到日志]
    A --> A3[定期轮换]

    B --> B1[allowedTools白名单]
    B --> B2[禁止危险Bash命令]
    B --> B3[只读模式优先]

    C --> C1[限制外部网络访问]
    C --> C2[不暴露内网地址]

    D --> D1[记录所有工具调用]
    D --> D2[Hook审计]
    D --> D3[结果归档]

    E --> E1[验证PR作者]
    E --> E2[限制触发条件]
    E --> E3[输入长度限制]
```

### 6.2 安全配置模板

```yaml
# .github/workflows/claude-secure.yml
jobs:
  claude-secure:
    runs-on: ubuntu-latest
    # 仅允许仓库协作者触发
    if: github.event.pull_request.author_association == 'COLLABORATOR'
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # 严格限制工具权限
          allowed_tools: |
            Read
            Glob
            Grep
          # 添加安全指令
          custom_instructions: |
            安全规则：
            - 不要执行任何写操作
            - 不要运行任何命令
            - 不要访问环境变量中的密钥
            - 仅做分析和建议
```

Agent SDK的安全Hook：

```python
from claude_agent_sdk import ClaudeSDKClient, HookType
import re

client = ClaudeSDKClient()

BLOCKED_PATTERNS = [
    r"rm\s+-rf",
    r"DROP\s+TABLE",
    r"git\s+push\s+.*--force",
    r"curl.*\|\s*sh",
    r"eval\s*\(",
    r"chmod\s+777",
    r">\s*/dev/sd",
]

@client.hook(HookType.PRE_TOOL_USE)
def security_guard(tool_name: str, tool_input: dict) -> dict:
    if tool_name == "Bash":
        command = tool_input.get("command", "")
        for pattern in BLOCKED_PATTERNS:
            if re.search(pattern, command, re.IGNORECASE):
                raise ValueError(
                    f"安全策略阻止执行: 检测到危险模式 '{pattern}'"
                )
    if tool_name in ("Write", "Edit"):
        file_path = tool_input.get("file_path", "")
        sensitive_files = [".env", "credentials", "secrets", "id_rsa"]
        for sf in sensitive_files:
            if sf in file_path.lower():
                raise ValueError(f"安全策略阻止修改敏感文件: {file_path}")
    return tool_input
```

---

## 延伸阅读

- [Anthropic官方：Run Claude Code programmatically](https://code.claude.com/docs/en/headless) — Headless模式完整文档
- [Anthropic官方：Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions) — 官方Action配置指南
- [Anthropic官方：Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview) — Agent SDK架构说明
- [GitHub: anthropics/claude-code-action](https://github.com/anthropics/claude-code-action) — 官方Action源码和示例
- [GitHub: anthropics/claude-agent-sdk-python](https://github.com/anthropics/claude-agent-sdk-python) — Python SDK源码和示例
- [Anthropic Support: Agent SDK with Claude Plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) — 2026年6月计费变更详情

## 训练营适用性评估

| 训练营类型 | 适用性 | 建议时长 | 备注 |
|-----------|--------|---------|------|
| 企业DevOps内训 | ★★★★★ | 4小时 | 直接应用于团队CI/CD流水线 |
| AI工具培训班 | ★★★★☆ | 3小时 | 侧重GitHub Actions部分 |
| 高级开发者工作坊 | ★★★★★ | 6小时 | 含Agent SDK完整实战 |
| 安全合规培训 | ★★★★☆ | 2小时 | 重点第六章安全实践 |
| 在线自学课程 | ★★★★☆ | 自定进度 | 需提供GitHub模板仓库 |

**前置依赖**：建议先完成Round 1（入门篇）和Round 3（MCP服务器开发），理解Claude Code基础概念后再学习本教程。

---

> **Claude Code自动化之旅** | 由Claude Code深度使用专家系列教程出品 | 2026年5月

## 参考来源

1. [Run Claude Code programmatically - Claude Code Docs](https://code.claude.com/docs/en/headless) — Headless模式官方文档，涵盖`-p`标志、输出格式、stdin管道
2. [Claude Code GitHub Actions - Claude Code Docs](https://code.claude.com/docs/en/github-actions) — 官方GitHub Action集成指南，含YAML配置和权限设置
3. [Agent SDK overview - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/overview) — Agent SDK架构概述，Python和TypeScript双语言支持
4. [Use the Claude Agent SDK with your Claude plan - Anthropic Support](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) — 2026年6月15日计费拆分政策详解
5. [anthropics/claude-code-action - GitHub](https://github.com/anthropics/claude-code-action) — 官方Action源码仓库，含完整示例和配置参考

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)