<!-- title: Claude Code无人化编排：从-p到多Agent工作树 -->

## 概述

本教程面向需要将Claude Code从"手动对话工具"升级为"无人化编程引擎"的开发者。你将掌握三大自动化支柱：`-p`无头模式的脚本化调用、Hooks钩子的事件驱动自动化、以及多Agent并行工作树编排。学完后，你能够构建从单行命令到CI/CD流水线到并行多仓库处理的完整自动化体系。

**适用人群**：已熟悉Claude Code基本操作，希望实现批量任务、无人值守开发、CI/CD集成的中高级用户。

## 前置条件

- Claude Code已安装并配置（`claude --version` ≥ 1.0）
- 熟悉Shell脚本（Bash/Zsh）
- Git基础操作（branch、worktree）
- Node.js ≥ 18（Agent SDK需要）
- 一个GitHub仓库用于练习

---

## 第一部分：`-p`无头模式 — 脚本化调用的基石

### 1.1 基本语法与三种调用方式

`-p`（或`--print`）标志将Claude Code从交互式TUI转变为纯命令行工具。所有输出直接写入stdout，无需人工干预。

```bash
# 方式一：直接传参
claude -p "解释这个项目的目录结构"

# 方式二：管道输入
cat src/main.ts | claude -p "为这个TypeScript文件添加单元测试"

# 方式三：文件重定向
claude -p "总结以下变更" < git-diff.txt
```

**预期输出**：纯文本响应直接打印到终端，不显示TUI界面。适合管道串联和脚本嵌套。

### 1.2 输出格式控制

```bash
# JSON格式输出，便于程序解析
claude -p "列出package.json中的所有依赖" --output-format json

# 流式JSON输出（逐事件推送）
claude -p "重构auth模块" --output-format stream-json

# 纯文本输出（默认）
claude -p "解释API路由结构" --output-format text
```

JSON输出结构示例：

```json
{
  "type": "result",
  "subtype": "success",
  "cost_usd": 0.034,
  "duration_ms": 12450,
  "duration_api_ms": 8200,
  "is_error": false,
  "num_turns": 3,
  "result": "项目使用Express框架，API路由结构如下..."
}
```

流式JSON每条事件包含：

```json
{"type": "assistant", "subtype": "text", "text": "正在分析..."}
{"type": "tool_use", "name": "Read", "input": {"file_path": "/src/app.ts"}}
{"type": "result", "subtype": "success", "result": "..."}
```

### 1.3 会话连续性：`--continue`与`--resume`

无人化场景中，"断点续传"是刚需。

```bash
# 延续上一次对话（保持上下文）
claude -p --continue "基于刚才的分析，开始重构"

# 恢复指定会话ID
claude -p --resume abc123 "继续这个任务"

# 命名会话，便于后续恢复
claude --session-name "refactor-auth" -p "开始重构认证模块"
claude -p --resume "refactor-auth" "继续重构，处理JWT部分"

# 列出历史会话
claude sessions list
```

**常见问题**：`--continue`只能恢复最近一次会话，如果需要恢复更早的会话，使用`--resume`加会话ID或名称。

### 1.4 权限模式选择

无头模式下权限控制尤为关键，提供三级方案：

```bash
# 方案一：自动接受所有编辑（适合受控环境）
claude -p "修复所有TypeScript错误" \
  --allowedTools "Edit,Write,Bash(npm test),Bash(npm run build)" \
  --acceptEdits

# 方案二：跳过所有权限确认（高风险，仅CI/CD）
claude -p "运行测试并修复失败用例" \
  --dangerously-skip-permissions

# 方案三：通过配置文件预设允许列表（推荐生产方案）
# .claude/settings.json
{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(npm *)",
      "Bash(git *)",
      "Bash(npx *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | *)"
    ]
  }
}
```

**安全提醒**：`--dangerously-skip-permissions`绕过所有安全检查，仅在隔离容器或CI环境中使用。配置文件方式更安全，粒度更细。

### 1.5 实战：构建代码审查脚本

```bash
#!/bin/bash
# review-pr.sh — 自动审查PR变更
set -euo pipefail

PR_NUMBER="${1:?用法: ./review-pr.sh <PR号>}"
REPO_DIR="${2:-.}"

# 获取PR diff
cd "$REPO_DIR"
gh pr diff "$PR_NUMBER" > /tmp/pr-diff.txt

# 运行审查
claude -p "
你是一位资深代码审查员。审查以下PR变更，关注：
1. 安全漏洞（注入、XSS等）
2. 性能问题
3. 代码可维护性
4. 测试覆盖率

$(cat /tmp/pr-diff.txt)
" --output-format json > "/tmp/review-pr-${PR_NUMBER}.json"

# 提取审查结果并发布评论
REVIEW=$(jq -r '.result' "/tmp/review-pr-${PR_NUMBER}.json")
gh pr comment "$PR_NUMBER" --body "## 🤖 AI Code Review

$REVIEW"

echo "✅ PR #$PR_NUMBER 审查完成"
```

运行方式：

```bash
chmod +x review-pr.sh
./review-pr.sh 42
```

---

## 第二部分：Hooks — 事件驱动的自动化层

### 2.1 Hooks生命周期全景

Hooks是Claude Code的"中间件"系统，在特定生命周期事件触发时执行Shell命令。

```mermaid
flowchart TD
    A[用户发送消息] --> B[PreToolUse Hook]
    B --> C{工具执行}
    C --> D[PostToolUse Hook]
    D --> E[AI生成回复]
    E --> F[Notification Hook]

    G[会话启动] --> H[SessionStart Hook]
    I[会话结束] --> J[Stop Hook]

    K[上下文压缩] --> L[PostCompact Hook]
```

四种核心Hook事件：

| 事件 | 触发时机 | 典型用途 |
|------|---------|---------|
| `PreToolUse` | 工具执行前 | 拦截危险操作、注入上下文 |
| `PostToolUse` | 工具执行后 | 自动格式化、日志记录 |
| `Notification` | AI回复完成时 | 发送通知、触发后续任务 |
| `SessionStart` | 会话开始时 | 加载环境信息、注入上下文 |

### 2.2 配置位置与优先级

Hooks配置支持三个层级，按优先级从低到高：

```
~/.claude/settings.json          # 全局（所有项目）
项目/.claude/settings.json       # 项目级（团队成员共享）
项目/.claude/settings.local.json # 本地覆盖（不提交到Git）
```

### 2.3 PreToolUse：守护安全防线

PreToolUse是最强大的防护层，能根据工具类型和参数进行精准拦截。

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/pre-bash.sh"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/pre-edit.sh"
          }
        ]
      }
    ]
  }
}
```

Hook脚本接收JSON格式的stdin输入：

```bash
#!/bin/bash
# .claude/hooks/pre-bash.sh — Bash命令安全检查
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

# 拦截危险命令
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "drop table"
  "DROP TABLE"
  ":(){ :|:& };:"
  "> /dev/sda"
  "curl.*|.*sh"
  "wget.*|.*bash"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qiE "$pattern"; then
    echo "{\"decision\":\"block\",\"reason\":\"危险命令被拦截: $COMMAND\"}"
    exit 0
  fi
done

# 允许执行
echo "{\"decision\":\"approve\"}"
```

**关键机制**：脚本通过stdout返回JSON决策。三个可选决策：
- `approve`：允许执行
- `block`：阻止执行，`reason`会展示给AI
- 不输出或输出无效JSON：使用默认权限逻辑

### 2.4 PostToolUse：自动格式化与增强

```bash
#!/bin/bash
# .claude/hooks/post-edit.sh — 编辑后自动格式化
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

if [ "$TOOL_NAME" = "Edit" ] || [ "$TOOL_NAME" = "Write" ]; then
  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')
  
  # 根据文件类型选择格式化工具
  case "$FILE_PATH" in
    *.ts|*.tsx|*.js|*.jsx)
      npx prettier --write "$FILE_PATH" 2>/dev/null
      npx eslint --fix "$FILE_PATH" 2>/dev/null
      ;;
    *.py)
      python -m black "$FILE_PATH" 2>/dev/null
      python -m isort "$FILE_PATH" 2>/dev/null
      ;;
    *.go)
      gofmt -w "$FILE_PATH" 2>/dev/null
      ;;
    *.rs)
      rustfmt "$FILE_PATH" 2>/dev/null
      ;;
  esac
fi

echo "{\"decision\":\"approve\"}"
```

### 2.5 SessionStart：智能上下文注入

```bash
#!/bin/bash
# .claude/hooks/session-start.sh — 注入项目状态信息
cat << 'CTX'
## 当前项目状态

CTX

# 注入Git状态
echo "### Git分支: $(git branch --show-current)"
echo "### 未提交变更:"
git status --short 2>/dev/null | head -20
echo ""

# 注入最近的TODO
if [ -f "TODO.md" ]; then
  echo "### 待办事项:"
  head -20 TODO.md
  echo ""
fi

# 注入测试状态
if [ -f "package.json" ]; then
  echo "### 最近测试结果:"
  npm test 2>&1 | tail -5
  echo ""
fi

echo "以上信息仅供参考，帮助理解当前项目状态。"
```

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/session-start.sh"
          }
        ]
      }
    ]
  }
}
```

### 2.6 Notification：任务完成通知

```bash
#!/bin/bash
# .claude/hooks/notification.sh — 任务完成时发送通知
INPUT=$(cat)
MESSAGE=$(echo "$INPUT" | jq -r '.message // .notification_text // empty')

# macOS通知
if [[ "$OSTYPE" == "darwin"* ]]; then
  osascript -e "display notification \"Claude Code任务完成\" with title \"Claude Code\" sound name \"Glass\""
fi

# Linux桌面通知
if command -v notify-send &>/dev/null; then
  notify-send "Claude Code" "任务已完成" --icon=dialog-information
fi

# Slack通知（可选）
if [ -n "$SLACK_WEBHOOK_URL" ]; then
  curl -s -X POST "$SLACK_WEBHOOK_URL" \
    -H 'Content-Type: application/json' \
    -d "{\"text\": \"✅ Claude Code任务完成: ${MESSAGE:0:200}\"}"
fi
```

---

## 第三部分：多Agent并行工作树

### 3.1 并行架构概览

单Agent串行处理是Claude Code的默认模式。当面对多个独立任务时，并行化可将效率提升数倍。

```mermaid
flowchart TB
    subgraph Main["主Agent（编排器）"]
        direction TB
        M1[接收用户任务]
        M2[任务分解]
        M3[结果合并]
        M1 --> M2 --> M3
    end

    subgraph Agents["并行Subagent"]
        direction LR
        A1["Agent A<br/>研究任务<br/>📂 worktree-a"]
        A2["Agent B<br/>代码重构<br/>📂 worktree-b"]
        A3["Agent C<br/>测试编写<br/>📂 worktree-c"]
    end

    M2 --> A1
    M2 --> A2
    M2 --> A3
    A1 --> M3
    A2 --> M3
    A3 --> M3
```

### 3.2 Task工具：Subagent的核心

在Claude Code交互中，Task工具是创建子代理的唯一入口。它支持五种Subagent类型：

```
subagent_type:
  - general-purpose   # 通用：搜索、研究、多步骤任务
  - Explore           # 快速探索：文件查找、内容搜索
  - Plan              # 规划：设计方案、架构分析
```

**关键参数**：

| 参数 | 作用 | 建议 |
|------|------|------|
| `prompt` | 任务描述 | 越具体越好，包含所有必要上下文 |
| `subagent_type` | Agent类型 | 按需选择，Explore用于只读搜索 |
| `isolation` | 隔离模式 | `"worktree"` 创建独立Git工作树 |
| `run_in_background` | 后台运行 | `true` 实现真正的并行执行 |

### 3.3 Worktree隔离模式

Worktree是并行Agent避免文件冲突的核心机制。每个Agent获得独立的Git工作目录。

```bash
# 手动创建worktree
claude --worktree feature-auth    # 在.claude/worktrees/下创建独立工作目录
claude --worktree feature-tests   # 另一个独立工作目录
```

在Task工具中使用worktree隔离：

```json
{
  "subagent_type": "general-purpose",
  "prompt": "为认证模块编写单元测试，覆盖登录、注册、Token刷新三个场景",
  "isolation": "worktree"
}
```

**Worktree生命周期**：
1. 创建时：基于HEAD创建新分支和独立工作目录
2. 运行中：所有文件修改在隔离目录中进行
3. 完成后：如果无修改自动清理；有修改则保留分支

### 3.4 并行模式实战：前后台配合

**模式一：前景等待模式**（适合有依赖关系的任务）

在Claude Code中直接对话：

```
请并行完成以下任务：
1. 研究React 19的新特性，总结关键变更点
2. 分析当前项目的依赖树，找出过时的包
3. 审查最近的10个commit，识别代码质量趋势
```

Claude会自动启动多个Task并行执行，等待全部完成后汇总结果。

**模式二：后台并行模式**（适合独立的长任务）

```
请将以下三个任务分配给后台Agent并行执行：
1. 将所有API端点从REST迁移到tRPC
2. 迁移完成后在worktree中进行
3. 每个任务使用独立的worktree隔离
```

**模式三：脚本编排模式**（适合CI/CD）

```bash
#!/bin/bash
# parallel-tasks.sh — 多仓库并行处理
set -euo pipefail

TASKS=(
  "审查frontend仓库的安全性并生成报告"
  "为backend仓库添加OpenAPI文档"
  "优化shared-lib的性能瓶颈"
)

REPOS=(
  "./frontend"
  "./backend"
  "./shared-lib"
)

PIDS=()

for i in "${!TASKS[@]}"; do
  (
    cd "${REPOS[$i]}"
    claude -p "${TASKS[$i]}" \
      --output-format json \
      --dangerously-skip-permissions \
      > "/tmp/task-${i}-result.json"
  ) &
  PIDS+=($!)
done

# 等待所有任务完成
for pid in "${PIDS[@]}"; do
  wait "$pid"
done

# 汇总结果
echo "=== 任务执行汇总 ==="
for i in "${!TASKS[@]}"; do
  STATUS=$(jq -r '.is_error // false' "/tmp/task-${i}-result.json")
  COST=$(jq -r '.cost_usd // 0' "/tmp/task-${i}-result.json")
  if [ "$STATUS" = "false" ]; then
    echo "✅ 任务$((i+1))完成 - 费用: \$${COST}"
  else
    echo "❌ 任务$((i+1))失败"
  fi
done
```

### 3.5 Agent SDK：编程式编排

对于复杂的编排需求，Agent SDK提供TypeScript和Python两种语言的编程接口。

```typescript
// orchestrator.ts — TypeScript Agent SDK编排器
import { ClaudeCode, type Session } from "@anthropic-ai/claude-agent-sdk";

async function parallelOrchestration() {
  const sdk = new ClaudeCode();

  // 任务1：代码审查（后台）
  const reviewSession = await sdk.createSession({
    prompt: "审查src/目录下所有文件的代码质量，给出改进建议",
    outputFormat: "json",
    acceptEdits: true,
  });

  // 任务2：测试生成（后台）
  const testSession = await sdk.createSession({
    prompt: "为src/目录下所有模块生成单元测试",
    outputFormat: "json",
    acceptEdits: true,
  });

  // 任务3：文档生成（后台）
  const docSession = await sdk.createSession({
    prompt: "根据代码生成API文档",
    outputFormat: "json",
  });

  // 等待所有任务完成
  const [reviewResult, testResult, docResult] = await Promise.all([
    reviewSession.result,
    testSession.result,
    docSession.result,
  ]);

  console.log("审查费用:", reviewResult.cost_usd);
  console.log("测试费用:", testResult.cost_usd);
  console.log("文档费用:", docResult.cost_usd);

  return { reviewResult, testResult, docResult };
}

parallelOrchestration().catch(console.error);
```

安装SDK：

```bash
# TypeScript SDK
npm install @anthropic-ai/claude-agent-sdk

# Python SDK
pip install claude-agent-sdk
```

---

## 第四部分：Routines — 定时任务自动化

### 4.1 三层定时机制

Claude Code提供三种定时任务方案，覆盖不同场景：

| 层级 | 机制 | 适用场景 |
|------|------|---------|
| `/loop` | 会话内轮询 | 短期重复（本次会话内） |
| Desktop定时任务 | 系统调度器 | 每日本地任务 |
| Cloud Routines | 云端调度 | 团队共享、跨设备 |

### 4.2 `/loop`：会话内自动化

```
/loop 每5分钟检查一次测试是否通过，如果失败则自动修复
```

`/loop`命令让Claude在当前会话内按间隔重复执行任务。

### 4.3 Cron驱动的定时任务

```bash
# 每天早上8点运行代码审查
# 添加到crontab
0 8 * * * cd /path/to/project && claude -p "审查昨天所有新提交，检查安全漏洞和代码质量" --output-format json >> /var/log/claude-review.log 2>&1

# 每周一生成周报
0 9 * * 1 cd /path/to/project && claude -p "基于上周的Git历史生成本周开发周报" --output-format json | jq -r '.result' | mail -s "周报" team@company.com
```

### 4.4 Cloud Routines

Cloud Routines是Claude Code的云端调度方案，支持三种触发方式：

- **定时触发**：Cron表达式定义执行时间
- **API触发**：通过HTTP请求触发
- **GitHub触发**：基于仓库事件（push、PR等）

```
# 创建Routine
/routine create --name "每日安全扫描" \
  --schedule "0 6 * * *" \
  --prompt "扫描所有依赖的安全漏洞，检查是否有已知CVE"
```

---

## 第五部分：实战案例 — 全自动Issue处理流水线

### 5.1 架构设计

```mermaid
sequenceDiagram
    participant GH as GitHub
    participant Hook as Webhook
    participant Orch as 编排脚本
    participant C1 as Agent: 分类
    participant C2 as Agent: 修复
    participant C3 as Agent: 测试
    participant C4 as Agent: PR

    GH->>Hook: 新Issue创建
    Hook->>Orch: 触发处理
    Orch->>C1: 分类Issue
    C1-->>Orch: bug/feature/question
    
    alt Bug类型
        Orch->>C2: 在worktree中修复
        C2-->>Orch: 修复完成
        Orch->>C3: 运行测试
        C3-->>Orch: 测试通过
        Orch->>C4: 创建PR
        C4-->>GH: PR创建
    else 非Bug
        Orch->>GH: 添加标签+评论
    end
```

### 5.2 完整实现

```bash
#!/bin/bash
# auto-issue-handler.sh — 全自动Issue处理器
set -euo pipefail

ISSUE_NUMBER="${1:?用法: ./auto-issue-handler.sh <Issue号>}"
REPO_DIR="${2:-.}"
WORK_DIR="/tmp/claude-issue-${ISSUE_NUMBER}"

cd "$REPO_DIR"

echo "🔍 处理Issue #$ISSUE_NUMBER..."

# === 第一步：获取并分类Issue ===
ISSUE_BODY=$(gh issue view "$ISSUE_NUMBER" --json title,body,labels --jq '.')
ISSUE_TITLE=$(echo "$ISSUE_BODY" | jq -r '.title')
ISSUE_CONTENT=$(echo "$ISSUE_BODY" | jq -r '.body')

CLASSIFICATION=$(claude -p "
分析以下GitHub Issue，只返回一个分类标签（bug/feature/question/docs）：

标题: $ISSUE_TITLE
内容: $ISSUE_CONTENT

格式：只输出一个单词。
" --output-format json | jq -r '.result' | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')

echo "📋 分类结果: $CLASSIFICATION"

# === 第二步：根据分类采取不同策略 ===
case "$CLASSIFICATION" in
  bug)
    echo "🐛 Bug报告，开始自动修复流程..."
    
    # 创建worktree隔离
    git worktree add "$WORK_DIR" -b "fix/issue-${ISSUE_NUMBER}" HEAD 2>/dev/null || true
    
    # 分析并修复（在worktree中）
    claude -p "
这是一个Bug报告，请修复它：

标题: $ISSUE_TITLE
内容: $ISSUE_CONTENT

要求：
1. 先找到相关代码
2. 理解Bug的根因
3. 实现最小修复
4. 确保不引入新问题
" --acceptEdits --output-format json \
      > "${WORK_DIR}/fix-result.json"
    
    # 在worktree中运行测试
    FIX_SUCCESS=$(jq -r '.is_error' "${WORK_DIR}/fix-result.json")
    
    if [ "$FIX_SUCCESS" = "false" ]; then
      # 提交并创建PR
      cd "$WORK_DIR"
      git add -A
      git commit -m "fix: resolve #${ISSUE_NUMBER} - ${ISSUE_TITLE}"
      git push origin "fix/issue-${ISSUE_NUMBER}" 2>/dev/null || git push -u origin "fix/issue-${ISSUE_NUMBER}"
      
      PR_URL=$(gh pr create \
        --title "fix: ${ISSUE_TITLE}" \
        --body "## 自动修复

修复 Issue #${ISSUE_NUMBER}

### 修复内容
$(jq -r '.result' "${WORK_DIR}/fix-result.json" | head -50)

🤖 由Claude Code自动生成" \
        --base main)
      
      echo "✅ PR已创建: $PR_URL"
      
      # 清理worktree
      cd "$REPO_DIR"
      git worktree remove "$WORK_DIR" --force 2>/dev/null || true
    else
      echo "⚠️ 自动修复失败，添加需要人工处理的标签"
      gh issue edit "$ISSUE_NUMBER" --add-label "needs-human-review"
    fi
    ;;
    
  feature)
    echo "💡 Feature请求，添加待规划标签"
    gh issue edit "$ISSUE_NUMBER" --add-label "enhancement"
    gh issue comment "$ISSUE_NUMBER" --body "已标记为功能请求，将在下次迭代中评估优先级。"
    ;;
    
  question)
    echo "❓ 提问，自动回答"
    ANSWER=$(claude -p "回答以下关于项目的问题，基于项目代码给出准确答案：

$ISSUE_CONTENT
" --output-format json | jq -r '.result')
    
    gh issue comment "$ISSUE_NUMBER" --body "## 自动回复

$ANSWER

---
如果这个回答解决了你的问题，请关闭Issue。"
    gh issue edit "$ISSUE_NUMBER" --add-label "answered"
    ;;
    
  *)
    echo "📄 其他类型，添加待分类标签"
    gh issue edit "$ISSUE_NUMBER" --add-label "triage"
    ;;
esac

echo "🏁 Issue #$ISSUE_NUMBER 处理完成"
```

### 5.3 配套Hooks配置

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/guard-rbac.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-format.sh"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(git *)",
      "Bash(gh *)",
      "Bash(npm test *)",
      "Bash(npx prettier *)",
      "Bash(npx eslint *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | *)",
      "Bash(sudo *)"
    ]
  }
}
```

### 5.4 设置GitHub Webhook触发

```bash
# 使用GitHub Actions自动触发
# .github/workflows/auto-issue.yml
cat > .github/workflows/auto-issue.yml << 'YAML'
name: Auto Issue Handler

on:
  issues:
    types: [opened, labeled]

jobs:
  handle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            处理Issue #${{ github.event.issue.number }}
            1. 分析Issue类型
            2. 如果是Bug，尝试修复并创建PR
            3. 如果是Feature，添加标签
            4. 如果是Question，基于代码回答
          allowed_tools: "Read,Edit,Write,Bash(git *),Bash(gh *)"
YAML
```

---

## 第六部分：性能与成本优化

### 6.1 上下文窗口管理

并行Agent数量受上下文窗口限制。以下是优化策略：

```bash
# 限制Agent的max_turns，防止无限循环
# 在Task调用中设置 max_turns: 10

# 使用Explore agent做只读操作（消耗更少token）
# subagent_type: "Explore" 代替 "general-purpose"

# 对大型代码库，先用Explore缩小范围
claude -p "先使用Explore agent找到所有与认证相关的文件路径，然后再用general-purpose agent修复"
```

### 6.2 成本控制

```bash
# 设置每个任务的成本上限
claude -p "修复bug" --max-cost 1.00  # 限制$1

# 选择合适的模型
claude -p "简单格式化任务" --model haiku    # 低成本
claude -p "复杂架构设计" --model opus      # 高质量

# Agent SDK中同样支持
const session = await sdk.createSession({
  prompt: "...",
  model: "haiku",  // 简单任务用Haiku
  maxTurns: 5,
});
```

### 6.3 错误处理与重试

```bash
#!/bin/bash
# resilient-task.sh — 带重试机制的自动化任务
MAX_RETRIES=3
RETRY_COUNT=0

while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
  RESULT=$(claude -p "$1" --output-format json 2>&1)
  EXIT_CODE=$?
  
  if [ $EXIT_CODE -eq 0 ]; then
    IS_ERROR=$(echo "$RESULT" | jq -r '.is_error // false')
    if [ "$IS_ERROR" = "false" ]; then
      echo "$RESULT"
      exit 0
    fi
  fi
  
  RETRY_COUNT=$((RETRY_COUNT + 1))
  echo "⚠️ 第${RETRY_COUNT}次尝试失败，重试中..." >&2
  sleep 5
done

echo "❌ ${MAX_RETRIES}次尝试均失败" >&2
exit 1
```

---

## 第七部分：编排模式速查表

```mermaid
mindmap
  root((Claude Code<br/>自动化编排))
    无头模式
      -p单次执行
      管道输入
      JSON输出
      会话恢复
    Hooks
      PreToolUse安全
      PostToolUse增强
      SessionStart注入
      Notification通知
    多Agent
      Task工具
      Worktree隔离
      前景等待
      后台并行
    定时任务
      /loop轮询
      Cron调度
      Cloud Routines
    SDK编排
      TypeScript
      Python
      Promise.all
```

### 模式选择决策树

| 场景 | 推荐模式 | 命令/工具 |
|------|---------|----------|
| 单次脚本执行 | `-p`无头模式 | `claude -p "任务"` |
| CI/CD集成 | `-p` + JSON输出 | `claude -p "..." --output-format json` |
| 代码质量守护 | PreToolUse Hook | Hook + matcher |
| 自动格式化 | PostToolUse Hook | Hook + formatter |
| 环境信息注入 | SessionStart Hook | Hook + context script |
| 2-3个并行研究 | Task工具前景 | `subagent_type: "Explore"` |
| 多任务并行修改 | Task + Worktree | `isolation: "worktree"` |
| 定时每日任务 | Cron + `-p` | crontab |
| 复杂工作流 | Agent SDK | TypeScript Promise.all |

---

## 延伸阅读

- [Claude Code官方文档：Headless Mode](https://code.claude.com/docs/en/headless) — 无头模式完整参考
- [Claude Code官方文档：Hooks Reference](https://code.claude.com/docs/en/hooks) — Hook事件与JSON格式规范
- [Claude Code官方文档：Worktrees](https://code.claude.com/docs/en/worktrees) — 并行会话隔离指南
- [Agent SDK TypeScript参考](https://code.claude.com/docs/en/agent-sdk/typescript) — 编程式编排API
- [Claude Code最佳实践](https://code.claude.com/docs/en/best-practices) — 官方推荐的自动化模式

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | AI工程实战营、DevOps自动化训练营 |
| 预计教学时长 | 4-6小时（含动手实验） |
| 难度等级 | 中高级 |
| 实验环境要求 | 每人一台Linux/macOS终端，Git仓库，Anthropic API Key |
| 建议分组 | 2-3人一组，共同构建自动化流水线 |

---

## 参考来源

1. [Run Claude Code programmatically - Claude Code Docs](https://code.claude.com/docs/en/headless) — 官方无头模式文档，涵盖-p标志、管道输入、JSON输出
2. [Hooks reference - Claude Code Docs](https://code.claude.com/docs/en/hooks) — 官方Hook事件参考，JSON输入输出格式与退出码规范
3. [Run parallel sessions with worktrees - Claude Code Docs](https://code.claude.com/docs/en/worktrees) — 官方Worktree隔离文档
4. [Agent SDK reference - TypeScript - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/typescript) — TypeScript SDK完整API参考
5. [Claude Code Subagents: Parallel Multi-Agent Workflows - Turion](https://turion.ai/blog/claude-code-multi-agents-subagents-guide/) — 多Agent并行编排实战指南

> [!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)