<!-- title: Claude Code Headless八大管道模式与输出解析实战 -->

## 概述

本教程深入剖析Claude Code Headless模式（`-p` / `--print`）的底层I/O机制，掌握`stdin`管道注入、三种输出格式（`text`/`json`/`stream-json`）的精确解析方法，以及八大实战管道编排模式。适用人群：DevOps工程师、SRE、需要将Claude Code集成到CI/CD或Shell脚本流水线中的自动化开发者。

## 前置条件

- Claude Code CLI已安装并完成认证（`claude` 命令可用）
- 熟悉Shell脚本基础（Bash/Zsh）
- 了解JSON/JSONL格式
- 拥有至少一个可用的Claude Code项目目录

---

## 一、Headless模式核心机制

### 1.1 什么是Headless模式

Headless模式是Claude Code的非交互式运行方式。与交互式终端不同，它接收输入、执行任务、输出结果后立即退出，天然适合管道编排和自动化场景。

```mermaid
flowchart LR
    subgraph 输入源
        A[命令行参数]
        B[stdin管道]
        C[文件重定向]
    end
    subgraph Claude Code Headless
        D[-p模式引擎]
        E[Agent Loop]
        F[工具调用链]
    end
    subgraph 输出目标
        G[stdout文本]
        H[JSON结构化]
        I[stream-json流]
    end
    A --> D
    B --> D
    C --> D
    D --> E --> F
    F --> G
    F --> H
    F --> I
```

### 1.2 最简启动方式

```bash
# 最基本的headless调用
claude -p "解释当前项目的目录结构"

# 带输出格式控制
claude -p "列出所有TODO注释" --output-format json

# 从stdin管道输入
echo "这段代码有什么问题？" | claude -p
```

### 1.3 关键CLI标志一览

| 标志 | 作用 | 示例 |
|------|------|------|
| `-p, --print` | 非交互模式，输出后退出 | `claude -p "task"` |
| `--output-format` | 控制输出格式（text/json/stream-json） | `--output-format json` |
| `--input-format` | 控制stdin输入格式（text/jsonl） | `--input-format jsonl` |
| `--bare` | 跳过hooks发现和自动上下文加载，加速启动 | `claude -p --bare "task"` |
| `--continue` | 继续最近一次会话 | `claude -p --continue "继续修改"` |
| `--resume` | 恢复指定会话ID | `claude -p --resume abc123 "新指令"` |
| `--max-turns` | 限制Agent最大轮次 | `--max-turns 5` |
| `--model` | 指定模型 | `--model claude-sonnet-4-6` |
| `--allowedTools` | 限定可用工具列表 | `--allowedTools Read,Glob,Grep` |
| `--system-prompt` | 覆盖系统提示 | `--system-prompt "你是安全审计专家"` |
| `--append-system-prompt` | 追加系统提示 | `--append-system-prompt "回复用中文"` |

---

## 二、三种输出格式深度解析

### 2.1 text模式（默认）

纯文本输出，适合人类阅读和简单的grep/sed后处理。

```bash
# 基础用法
result=$(claude -p "当前目录下有哪些TypeScript文件？")

# 结合grep提取关键信息
claude -p "分析package.json中的依赖列表" | grep -E "react|vue|angular"
```

**输出特征**：纯Markdown文本，包含代码块、列表、表格等格式。

### 2.2 json模式

结构化JSON输出，适合程序化解析。返回完整的对话结果对象。

```bash
# 获取JSON输出
claude -p "统计src目录下的代码行数" --output-format json

# 典型JSON输出结构
# {
#   "type": "result",
#   "subtype": "success",
#   "cost_usd": 0.0234,
#   "is_error": false,
#   "duration_ms": 4523,
#   "duration_api_ms": 3800,
#   "num_turns": 2,
#   "result": "src目录共包含...",
#   "session_id": "abc123def456",
#   "model": "claude-sonnet-4-6"
# }
```

**解析实战**：用`jq`提取关键字段。

```bash
# 提取任务结果和成本
output=$(claude -p "检查是否有未提交的变更" --output-format json)
result=$(echo "$output" | jq -r '.result')
cost=$(echo "$output" | jq -r '.cost_usd')
echo "结果: $result"
echo "成本: \$$cost"
```

### 2.3 stream-json模式（最强大）

流式JSON输出，每行一个JSON对象（JSONL格式），实时捕获Agent的每一步操作。

```bash
# 流式输出
claude -p "重构utils目录下的所有测试文件" --output-format stream-json

# 每行输出示例（简化）：
# {"type":"init","session_id":"abc123","model":"claude-sonnet-4-6"}
# {"type":"assistant","message":{"role":"assistant","content":[...]}}
# {"type":"tool_use","tool":"Read","input":{"file_path":"src/utils/test.ts"}}
# {"type":"tool_result","tool":"Read","output":"file content..."}
# {"type":"assistant","message":{"role":"assistant","content":"已重构..."}}
# {"type":"result","subtype":"success","cost_usd":0.0567}
```

**实时监控实战**：

```bash
# 实时提取工具调用并打印
claude -p "审计项目中的安全隐患" --output-format stream-json | \
  while IFS= read -r line; do
    type=$(echo "$line" | jq -r '.type // empty')
    case "$type" in
      tool_use)
        tool=$(echo "$line" | jq -r '.tool')
        echo "[工具调用] $tool"
        ;;
      tool_result)
        tool=$(echo "$line" | jq -r '.tool')
        echo "[工具完成] $tool"
        ;;
      result)
        cost=$(echo "$line" | jq -r '.cost_usd')
        echo "[完成] 成本: \$$cost"
        ;;
    esac
  done
```

---

## 三、八大管道模式实战

### 模式一：单次命令管道

最基本的用法——将Claude Code作为Unix管道的一个环节。

```bash
# 从文件读取错误日志，让Claude分析
cat error.log | claude -p "分析这些错误日志的根本原因并给出修复建议"

# 与其他命令组合
git log --oneline -20 | claude -p "总结最近20条提交的主题和趋势"
```

### 模式二：JSON管道——结构化提取

将Claude Code的输出直接传递给下游工具处理。

```bash
#!/bin/bash
# analyze_code.sh - 代码质量分析管道

ANALYSIS=$(claude -p "分析src/目录的代码质量，包括：
1. 圈复杂度最高的5个函数
2. 最长的5个文件
3. 潜在的代码异味
以JSON格式输出" --output-format json)

# 提取分析结果
RESULT=$(echo "$ANALYSIS" | jq -r '.result')
COST=$(echo "$ANALYSIS" | jq -r '.cost_usd')
SESSION=$(echo "$ANALYSIS" | jq -r '.session_id')

echo "=== 代码质量分析报告 ==="
echo "$RESULT"
echo "---"
echo "会话ID: $SESSION"
echo "API成本: \$$COST"

# 如果发现严重问题，触发告警
if echo "$RESULT" | grep -qi "critical\|严重"; then
  echo "⚠️  检测到严重问题，发送告警..."
  # curl -X POST "$WEBHOOK_URL" -d "{\"text\": \"$RESULT\"}"
fi
```

### 模式三：多步骤会话管道

使用`--input-format jsonl`实现多轮对话的自动化编排。

```bash
#!/bin/bash
# multi_step_audit.sh - 多步骤安全审计

# 构建多轮对话输入（JSONL格式，每行一个JSON对象）
cat <<'JSONL' | claude -p --input-format jsonl --output-format json
{"role":"user","content":"扫描项目中所有使用eval()的地方，列出文件和行号"}
{"role":"user","content":"针对每一处eval()的使用，分析是否存在注入风险"}
{"role":"user","content":"为每个有风险的eval()提供安全的替代方案代码"}
JSONL
```

**JSONL输入格式**：每行是一个标准的对话消息对象，包含`role`和`content`字段。Claude Code会依次处理每条消息，保持上下文连贯。

### 模式四：会话恢复管道

利用`session_id`实现跨调用的有状态工作流。

```bash
#!/bin/bash
# session_pipeline.sh - 跨会话管道

WORK_DIR="/path/to/project"
cd "$WORK_DIR"

# 第一步：初始化分析
echo "步骤1: 初始分析..."
STEP1=$(claude -p "分析当前项目的架构，输出组件依赖关系" --output-format json)
SESSION_ID=$(echo "$STEP1" | jq -r '.session_id')
echo "会话ID: $SESSION_ID"

# 第二步：在同一会话中深入分析
echo "步骤2: 深入分析..."
claude -p "基于刚才的分析，找出3个最需要重构的模块" \
  --resume "$SESSION_ID" \
  --output-format json | jq -r '.result'

# 第三步：生成重构计划
echo "步骤3: 生成重构计划..."
claude -p "为这3个模块生成详细的重构计划，包含时间估算" \
  --resume "$SESSION_ID" \
  --output-format json | jq -r '.result'
```

### 模式五：并行批量管道

同时启动多个Headless实例处理独立任务，最大化吞吐。

```bash
#!/bin/bash
# batch_review.sh - 批量代码审查

# 获取所有最近修改的文件
FILES=$(git diff --name-only main...HEAD | grep '\.ts$')

echo "待审查文件: $(echo $FILES | wc -w) 个"

# 并行审查每个文件
for file in $FILES; do
  (
    result=$(claude -p "审查文件 $file 的代码质量，重点关注：
    - 类型安全
    - 错误处理
    - 性能问题
    - 可读性
    输出JSON格式的审查结果" \
      --output-format json \
      --allowedTools Read,Grep \
      --max-turns 3 \
      --model claude-haiku-4-5)  # 使用Haiku控制成本
    
    score=$(echo "$result" | jq -r '.result' | grep -oP '评分:\s*\K\d+')
    echo "[$file] 评分: ${score:-N/A}/10"
  ) &
done

# 等待所有审查完成
wait
echo "=== 批量审查完成 ==="
```

### 模式六：Git Hook集成管道

将Claude Code嵌入Git工作流，实现提交前自动检查。

```bash
#!/bin/bash
# .git/hooks/pre-commit - Git预提交钩子

# 获取暂存区的变更文件
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx)$')

if [ -z "$STAGED_FILES" ]; then
  exit 0
fi

echo "🔍 Claude Code正在审查暂存的变更..."

# 使用--bare加速启动，限定工具范围
REVIEW=$(echo "$STAGED_FILES" | claude -p --bare \
  --allowedTools Read \
  --max-turns 2 \
  --model claude-haiku-4-5 \
  "审查以下文件的暂存变更，只检查是否有明显的bug或安全问题。
   如果有问题，以BLOCK:开头输出；如果没问题，输出OK。
   文件列表如下：
   $(git diff --cached)" \
  --output-format json 2>/dev/null)

RESULT=$(echo "$REVIEW" | jq -r '.result')

if echo "$RESULT" | grep -q "^BLOCK:"; then
  echo "❌ Claude Code发现了问题："
  echo "$RESULT" | sed 's/^BLOCK://'
  exit 1
fi

echo "✅ 代码审查通过"
exit 0
```

### 模式七：CI/CD管道

在GitHub Actions中使用Headless模式。

```yaml
# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      
      - name: Run AI Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 获取PR变更
          DIFF=$(git diff origin/${{ github.base_ref }}...HEAD)
          
          # Claude Code审查
          REVIEW=$(echo "$DIFF" | claude -p --bare \
            --output-format json \
            --max-turns 3 \
            --model claude-sonnet-4-6 \
            "你是一位高级代码审查专家。审查这个PR的变更：
            1. 逻辑错误和安全漏洞
            2. 性能退化风险
            3. 代码可维护性
            用中文输出审查意见。")
          
          # 提取结果并发布为PR评论
          echo "$REVIEW" | jq -r '.result' > review_comment.md
          
      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const comment = fs.readFileSync('review_comment.md', 'utf8');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 Claude Code AI Review\n\n${comment}`
            });
```

### 模式八：监控与告警管道

持续集成中的自动化巡检和告警。

```bash
#!/bin/bash
# nightly_audit.sh - 夜间自动巡检

PROJECT_DIR="/path/to/project"
REPORT_FILE="/tmp/claude_audit_$(date +%Y%m%d).md"
ALERT_WEBHOOK="https://hooks.slack.com/services/xxx"

cd "$PROJECT_DIR"

echo "# 安全巡检报告 - $(date +%Y-%m-%d)" > "$REPORT_FILE"

# 1. 依赖安全检查
echo "## 依赖安全" >> "$REPORT_FILE"
claude -p "检查package.json中的依赖是否有已知安全漏洞。
建议升级的包、已知CVE编号，以及替代方案。" \
  --bare --max-turns 3 --output-format json | \
  jq -r '.result' >> "$REPORT_FILE"

# 2. 代码模式扫描
echo -e "\n## 代码模式扫描" >> "$REPORT_FILE"
claude -p "扫描src/目录，查找以下反模式：
- 硬编码的密钥或凭证
- 未处理的Promise rejection
- 过度使用any类型（TypeScript）
- 未使用的导入" \
  --allowedTools Read,Grep,Glob --max-turns 5 --output-format json | \
  jq -r '.result' >> "$REPORT_FILE"

# 3. 性能回归检查
echo -e "\n## 性能建议" >> "$REPORT_FILE"
claude -p "分析关键路径代码（api/和services/目录），
找出N+1查询、不必要的同步操作、大循环中的内存分配等性能问题。" \
  --allowedTools Read,Grep,Glob --max-turns 5 --output-format json | \
  jq -r '.result' >> "$REPORT_FILE"

# 发送告警
TOTAL_ISSUES=$(grep -ci "漏洞\|风险\|问题\|vulnerability\|risk" "$REPORT_FILE")
if [ "$TOTAL_ISSUES" -gt 5 ]; then
  curl -X POST "$ALERT_WEBHOOK" \
    -H "Content-Type: application/json" \
    -d "{\"text\": \"⚠️ 夜间巡检发现 $TOTAL_ISSUES 个问题，请查看报告: $REPORT_FILE\"}"
fi

echo "巡检完成，报告已保存到 $REPORT_FILE"
```

---

## 四、Headless模式高级技巧

### 4.1 --bare模式：启动加速

`--bare`标志跳过hooks发现、MCP服务器启动等自动加载流程，显著减少启动时间。

```bash
# 对比启动时间
time claude -p "hello"                    # ~3-5秒（加载所有hooks/MCP）
time claude -p --bare "hello"             # ~1-2秒（跳过加载）

# 适合纯文本问答场景
claude -p --bare "TypeScript中interface和type的区别"
```

**何时使用--bare**：
- 纯知识问答，不需要工具调用
- CI/CD中需要快速响应
- 成本敏感的批量任务

**何时不使用--bare**：
- 需要读取项目文件
- 需要执行Shell命令
- 需要MCP服务器提供的工具

### 4.2 --allowedTools：精确控制工具范围

限制可用工具既降低成本又提高安全性。

```bash
# 只读审查——不允许任何修改操作
claude -p "审查src/index.ts" \
  --allowedTools Read,Grep,Glob \
  --output-format json

# 允许读写但不允许执行Shell命令
claude -p "修复src/utils.ts中的所有lint错误" \
  --allowedTools Read,Write,Edit,Grep,Glob \
  --output-format json

# 最小权限——只允许搜索
claude -p "查找项目中所有TODO注释" \
  --allowedTools Grep \
  --output-format json
```

### 4.3 --max-turns：成本控制

限制Agent Loop的最大轮次，防止任务失控导致成本飙升。

```bash
# 单轮问答
claude -p "什么是React Server Components" --max-turns 1 --bare

# 限制3轮——适合简单分析
claude -p "检查这个函数的性能问题" --max-turns 3 --allowedTools Read

# 较复杂任务——5轮
claude -p "重构这个模块" --max-turns 5 --allowedTools Read,Write,Edit
```

### 4.4 会话管理与--continue/--resume

```bash
# 继续最近的对话
claude -p --continue "根据刚才的分析，生成详细的重构代码"

# 恢复指定会话
SESSION="abc123-def456-ghi789"
claude -p --resume "$SESSION" "修改上一版的方案，重点关注性能"

# 获取会话ID（从JSON输出中提取）
SESSION_ID=$(claude -p "初始分析" --output-format json | jq -r '.session_id')

# 使用会话ID进行后续操作
claude -p --resume "$SESSION_ID" "深入分析性能瓶颈" --output-format json
```

### 4.5 --system-prompt与--append-system-prompt

```bash
# 完全覆盖系统提示——创建专用角色
claude -p "审查这段代码" \
  --system-prompt "你是一位安全审计专家。只关注安全漏洞，忽略代码风格问题。输出格式：严重级别 | 文件:行号 | 问题描述 | 修复建议"

# 追加系统提示——在默认行为之上增加约束
claude -p "分析项目架构" \
  --append-system-prompt "所有输出使用中文。重点关注微服务间的通信模式。"
```

---

## 五、完整实战案例：自动化代码质量门禁

将上述所有模式组合成一个生产级的自动化代码质量门禁系统。

### 5.1 项目结构

```
project/
├── .claude/
│   └── quality_gate.sh        # 主脚本
├── scripts/
│   ├── pre_commit_check.sh     # Git Hook
│   ├── ci_review.sh            # CI/CD审查
│   └── nightly_audit.sh        # 夜间巡检
└── .github/
    └── workflows/
        └── claude-quality.yml  # GitHub Actions
```

### 5.2 核心质量门禁脚本

```bash
#!/bin/bash
# .claude/quality_gate.sh - 代码质量门禁
set -euo pipefail

# 配置
MODEL_FAST="claude-haiku-4-5"
MODEL_DEEP="claude-sonnet-4-6"
MAX_TURNS_FAST=3
MAX_TURNS_DEEP=8
OUTPUT_FORMAT="json"
PASS_THRESHOLD=7  # 0-10分

# 颜色输出
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

# 用法
usage() {
  echo "用法: $0 <mode> [files...]"
  echo "模式:"
  echo "  check    - 快速检查（适合pre-commit）"
  echo "  review   - 深度审查（适合PR review）"
  echo "  audit    - 全面审计（适合夜间巡检）"
  exit 1
}

# 统一调用函数
run_claude() {
  local model=$1
  local turns=$2
  local tools=$3
  local prompt=$4
  local extra_flags=${5:-}
  
  claude -p --bare \
    --model "$model" \
    --max-turns "$turns" \
    --allowedTools "$tools" \
    --output-format "$OUTPUT_FORMAT" \
    $extra_flags \
    "$prompt" 2>/dev/null
}

# 模式一：快速检查（<10秒）
quick_check() {
  local files="$*"
  
  if [ -z "$files" ]; then
    files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx|py|go)$')
  fi
  
  [ -z "$files" ] && exit 0
  
  local diff_content=$(git diff --cached --stat)
  
  local result=$(run_claude "$MODEL_FAST" "$MAX_TURNS_FAST" "Read" \
    "快速检查以下文件的暂存变更，只关注明显的bug和安全漏洞。
     评分（0-10）并在第一行输出。
     如果有明显问题输出 BLOCK: + 描述，否则输出 PASS。
     变更文件: $files
     变更统计: $diff_content")
  
  local text=$(echo "$result" | jq -r '.result')
  local cost=$(echo "$result" | jq -r '.cost_usd')
  
  if echo "$text" | grep -q "^BLOCK:"; then
    echo -e "${RED}❌ 快速检查未通过${NC}"
    echo "$text"
    echo "成本: \$$cost"
    return 1
  fi
  
  echo -e "${GREEN}✅ 快速检查通过${NC} (成本: \$$cost)"
  return 0
}

# 模式二：深度审查
deep_review() {
  local target=${1:-"src/"}
  
  echo "🔍 深度审查: $target"
  
  local result=$(run_claude "$MODEL_DEEP" "$MAX_TURNS_DEEP" "Read,Grep,Glob" \
    "对 $target 进行全面代码审查，输出JSON格式的报告，包含：
     {
       \"score\": <0-10>,
       \"issues\": [{\"severity\": \"critical|warning|info\", \"file\": \"...\", \"line\": ..., \"desc\": \"...\"}],
       \"suggestions\": [\"...\"],
       \"summary\": \"...\"
     }
     审查维度：安全、性能、可维护性、测试覆盖率")
  
  local text=$(echo "$result" | jq -r '.result')
  local cost=$(echo "$result" | jq -r '.cost_usd')
  
  # 尝试从结果中提取评分
  local score=$(echo "$text" | jq -r '.score' 2>/dev/null || echo "N/A")
  
  echo "评分: $score/10"
  echo "成本: \$$cost"
  echo "---"
  echo "$text" | jq '.' 2>/dev/null || echo "$text"
  
  if [ "$score" != "N/A" ] && [ "$score" -lt "$PASS_THRESHOLD" ]; then
    echo -e "${RED}❌ 质量门禁未通过（${score} < ${PASS_THRESHOLD}）${NC}"
    return 1
  fi
  
  echo -e "${GREEN}✅ 质量门禁通过${NC}"
  return 0
}

# 模式三：全面审计
full_audit() {
  local report_file="quality_report_$(date +%Y%m%d_%H%M%S).md"
  
  echo "# 代码质量审计报告" > "$report_file"
  echo "生成时间: $(date)" >> "$report_file"
  echo "" >> "$report_file"
  
  # 阶段1: 依赖安全
  echo "## 1. 依赖安全" >> "$report_file"
  run_claude "$MODEL_FAST" "3" "Read" \
    "检查package.json/go.mod/requirements.txt中的依赖安全风险" \
    >> "$report_file" 2>/dev/null
  
  # 阶段2: 代码模式
  echo -e "\n## 2. 代码反模式" >> "$report_file"
  run_claude "$MODEL_DEEP" "$MAX_TURNS_DEEP" "Read,Grep,Glob" \
    "扫描src/中的代码反模式" >> "$report_file" 2>/dev/null
  
  # 阶段3: 架构分析
  echo -e "\n## 3. 架构建议" >> "$report_file"
  run_claude "$MODEL_DEEP" "$MAX_TURNS_DEEP" "Read,Grep,Glob" \
    "分析项目架构，评估模块耦合度，给出改进建议" >> "$report_file" 2>/dev/null
  
  echo "报告已生成: $report_file"
}

# 主入口
case "${1:-}" in
  check)  quick_check "${@:2}" ;;
  review) deep_review "${2:-src/}" ;;
  audit)  full_audit ;;
  *)      usage ;;
esac
```

### 5.3 质量门禁工作流图

```mermaid
flowchart TD
    A[开发者 git commit] --> B{pre-commit hook}
    B --> C[quick_check<br/>Haiku + 3轮]
    C --> D{通过?}
    D -->|否| E[❌ 阻止提交<br/>显示问题]
    D -->|是| F[✅ 允许提交]
    F --> G[git push]
    G --> H{GitHub Actions}
    H --> I[deep_review<br/>Sonnet + 8轮]
    I --> J{评分 ≥ 7?}
    J -->|否| K[❌ PR评论<br/>阻止合并]
    J -->|是| L[✅ PR通过]
    L --> M[合并到main]
    M --> N[定时任务 cron]
    N --> O[full_audit<br/>多阶段深度审计]
    O --> P[生成报告<br/>触发告警]

    style E fill:#ff6b6b,color:#fff
    style K fill:#ff6b6b,color:#fff
    style F fill:#51cf66,color:#fff
    style L fill:#51cf66,color:#fff
```

---

## 六、成本控制与性能优化

### 6.1 模型选择策略

```bash
# 通用决策框架
choose_model() {
  local task_type=$1
  
  case "$task_type" in
    "简单问答"|"格式检查"|"快速分类")
      echo "claude-haiku-4-5"    # ~$0.001/次
      ;;
    "代码审查"|"重构建议"|"架构分析")
      echo "claude-sonnet-4-6"   # ~$0.01/次
      ;;
    "复杂调试"|"多文件重构"|"设计决策")
      echo "claude-opus-4-6"     # ~$0.05/次
      ;;
    *)
      echo "claude-sonnet-4-6"   # 默认
      ;;
  esac
}
```

### 6.2 批量任务成本估算

```bash
#!/bin/bash
# cost_estimator.sh - 批量任务成本预估

FILES=(src/api.ts src/utils.ts src/config.ts src/index.ts)
MODEL="claude-haiku-4-5"
TOTAL_COST=0

for file in "${FILES[@]}"; do
  result=$(claude -p "简要描述 $file 的职责（一句话）" \
    --bare --model "$MODEL" --max-turns 1 --output-format json 2>/dev/null)
  
  cost=$(echo "$result" | jq -r '.cost_usd')
  TOTAL_COST=$(echo "$TOTAL_COST + $cost" | bc)
  
  echo "[$file] \$$cost"
done

echo "---"
echo "总成本: \$$TOTAL_COST"
echo "文件数: ${#FILES[@]}"
echo "平均成本: \$$(echo "scale=4; $TOTAL_COST / ${#FILES[@]}" | bc)/文件"
```

### 6.3 缓存与去重策略

```bash
#!/bin/bash
# cached_review.sh - 带缓存的审查

FILE=$1
CACHE_DIR="/tmp/claude_cache"
mkdir -p "$CACHE_DIR"

# 基于文件内容生成缓存key
CACHE_KEY=$(md5sum "$FILE" | cut -d' ' -f1)
CACHE_FILE="$CACHE_DIR/${CACHE_KEY}.json"

# 检查缓存
if [ -f "$CACHE_FILE" ]; then
  CACHE_AGE=$(( $(date +%s) - $(stat -c %Y "$CACHE_FILE") ))
  if [ "$CACHE_AGE" -lt 3600 ]; then  # 1小时内的缓存有效
    echo "命中缓存（${CACHE_AGE}秒前）"
    cat "$CACHE_FILE" | jq -r '.result'
    exit 0
  fi
fi

# 未命中缓存，执行审查
result=$(claude -p "审查 $FILE 的代码质量" \
  --allowedTools Read --max-turns 3 --output-format json 2>/dev/null)

# 写入缓存
echo "$result" > "$CACHE_FILE"
echo "$result" | jq -r '.result'
```

---

## 七、常见问题与解决方案

### Q1: Headless模式超时怎么办？

```bash
# 方案1: 使用--max-turns限制轮次
claude -p "复杂任务" --max-turns 5 --output-format json

# 方案2: 外部超时控制
timeout 120 claude -p "复杂任务" --output-format json || {
  echo "超时，降低任务复杂度或增加timeout"
}

# 方案3: 拆分为多个小任务
# 大任务: "重构整个项目" -> 不推荐
# 小任务: "重构src/utils/format.ts" -> 推荐
```

### Q2: JSON输出解析失败？

```bash
# stream-json输出可能包含多行JSON，需要逐行处理
claude -p "任务" --output-format stream-json | while read -r line; do
  # 跳过空行
  [ -z "$line" ] && continue
  # 尝试解析
  if ! echo "$line" | jq '.' > /dev/null 2>&1; then
    echo "无效JSON: $line" >&2
    continue
  fi
  # 处理有效JSON
  echo "$line" | jq -r '.result // .type'
done
```

### Q3: 并行任务数量控制？

```bash
# 使用GNU parallel控制并发数
echo "$FILES" | tr ' ' '\n' | parallel -j 4 \
  'claude -p "审查 {}" --bare --max-turns 2 --output-format json | jq -r ".result"'
```

---

## 延伸阅读

- [Claude Code Headless官方文档](https://code.claude.com/docs/en/headless) — Headless模式完整参考
- [Claude Code Hooks参考](https://code.claude.com/docs/en/hooks) — 钩子事件与配置全解
- [Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions) — CI/CD集成官方指南
- [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/typescript) — 编程式Agent开发
- [Claude Code权限模式](https://code.claude.com/docs/en/permission-modes) — 安全控制详解

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | DevOps训练营、AI工程化训练营、企业自动化内训 |
| 教学时长 | 4-6小时（含动手实验） |
| 学员基础要求 | Shell脚本中级、Git操作熟练、JSON/JQ基础 |
| 实验环境需求 | 每人一个GitHub仓库 + Claude Code API Key |
| 难度评级 | ⭐⭐⭐⭐ (中高级) |
| 最佳配套 | 与Hooks实战课程搭配，形成完整的自动化体系 |

## 参考来源
1. [Run Claude Code programmatically — Claude Code Docs](https://code.claude.com/docs/en/headless) — Headless模式官方文档，涵盖-p标志、输出格式、输入格式等核心API
2. [Hooks reference — Claude Code Docs](https://code.claude.com/docs/en/hooks) — 钩子系统完整参考，事件schema与配置格式
3. [Claude Code GitHub Actions — Claude Code Docs](https://code.claude.com/docs/en/github-actions) — 官方CI/CD集成方案与Action配置
4. [Headless Mode and CI/CD Cheatsheet — SFEIR Institute](https://institute.sfeir.com/en/claude-code/claude-code-headless-mode-and-ci-cd/cheatsheet/) — Headless模式速查表与CI/CD命令参考
5. [Claude Code stream-json输出格式详解 — Background Claude](https://backgroundclaude.com/blog/stream-json) — stream-json格式的深度解析与实战案例

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