<!-- title: Claude Code管道编程与Shell自动化 -->

# Claude Code Shell管道编程：Unix哲学驱动的智能自动化实战

## 概述

本教程面向有一定Linux/Shell基础的读者，系统讲解如何将Claude Code的`-p`（Print模式）视为一个Unix管道组件，与`jq`、`xargs`、`grep`等经典工具组合，构建真正的智能自动化脚本。你将学会stdin管道输入、JSON结构化输出、批量文件处理、成本追踪、错误恢复等核心模式，最终完成一个可部署的代码库健康巡检系统。

**适用人群**：熟悉Shell基础命令、已安装Claude Code CLI的开发者

**学习目标**：
- 掌握`-p`模式的管道输入/输出机制
- 用`jq`解析JSON响应构建处理管线
- 编写批量文件处理的Shell脚本
- 实现带成本控制和错误恢复的自动化流程

## 前置条件

- Node.js 18+（Claude Code运行环境）
- Claude Code CLI已安装并完成登录（`claude login`）
- 基础Shell知识（管道、重定向、变量、循环）
- `jq`工具已安装（`brew install jq`或`apt install jq`）

---

## 第一章：理解管道模式的核心机制

### 1.1 从交互式到管道式：思维转换

Claude Code默认运行在交互式TUI模式——你输入提示词，它在终端里渲染彩色输出，等待你的下一步指令。这对开发很好，但对自动化毫无用处。

`--print`（简写`-p`）标志将其转换为**无头管道组件**：读取stdin，输出到stdout，然后干净退出。

```bash
# 交互模式：进入TUI，等待输入
claude

# 管道模式：单次执行，结果直接输出到stdout
claude -p "解释这个函数的作用" < src/auth.ts
```

这种设计完全符合Unix哲学——**做一件事，做好它**。Claude Code在管道模式下就是一个"智能文本处理器"：接收输入流，返回处理结果。

### 1.2 三种输出格式详解

管道模式的核心决策是选择输出格式。`--output-format`标志控制Claude Code返回什么：

```bash
# 文本格式——适合人类阅读或简单管道
claude -p "用一句话总结这段代码" < src/main.py

# JSON格式——适合程序解析，包含完整的元数据
claude -p --output-format json "列出所有TODO注释" < src/main.py

# 流式JSON——适合实时进度监控
claude -p --output-format stream-json "重写这个模块的单元测试" < src/utils.ts
```

**JSON输出格式**是自动化的基础。每次调用返回的结构如下：

```json
{
  "type": "result",
  "subtype": "success",
  "result": "实际的文本响应内容",
  "session_id": "abc123-def456",
  "total_cost_usd": 0.00247,
  "usage": {
    "input_tokens": 1842,
    "output_tokens": 318,
    "cache_read_input_tokens": 12500
  },
  "duration_ms": 2500
}
```

关键字段解读：
- `result`：Claude的实际回答（可能包含`\n`换行）
- `total_cost_usd`：本次调用的美元成本
- `session_id`：会话ID，可用于后续恢复
- `usage`：Token使用明细，成本优化的关键数据

### 1.3 stdin管道输入的五种模式

Claude Code的`-p`模式天然支持stdin输入，这意味着你可以用Unix管道将任何数据"喂"给它：

```bash
# 模式1：文件重定向
claude -p "代码审查" < src/api/routes.ts

# 模式2：管道传递命令输出
cat error.log | claude -p "分析这个错误日志，找出根本原因"

# 模式3：多命令组合
git diff HEAD~1 | claude -p "总结本次代码变更的风险点"

# 模式4：Here Document（多行输入）
claude -p "比较这两个函数的性能特征" <<EOF
函数A：
$(cat src/slow_sort.ts)

函数B：
$(cat src/fast_sort.ts)
EOF

# 模式5：进程替换（多个文件）
claude -p "对比这两个配置文件的差异" < <(cat config/dev.yaml config/prod.yaml)
```

### 1.4 权限控制：无头模式的安全边界

默认情况下，Claude Code在执行修改操作时会请求人类批准。在自动化脚本中，你必须显式处理权限问题：

```bash
# 方案A：允许所有工具（仅限受信任的隔离环境！）
claude -p --dangerously-skip-permissions "运行测试并修复失败的用例"

# 方案B：限制可用工具（更安全）
claude -p --allowed-tools "Read,Grep,Glob" "分析项目结构"

# 方案C：通过settings.json配置细粒度权限
# .claude/settings.json
{
  "permissions": {
    "allow": ["Read", "Grep", "Glob", "Bash(npm test*)"],
    "deny": ["Bash(rm *)", "Bash(curl *)"]
  }
}
```

**安全原则**：生产脚本应遵循最小权限原则——只开放任务必需的工具。

---

## 第二章：jq集成——构建结构化处理管线

### 2.1 提取纯文本响应

最常见的操作是从JSON响应中提取`result`字段：

```bash
# 提取纯文本
claude -p --output-format json "用三句话总结这段代码" < src/main.py \
  | jq -r '.result'

# 带fallback的提取
claude -p --output-format json "评估代码质量评分（1-10）" < src/api.ts \
  | jq -r '.result // "分析失败"'
```

### 2.2 成本追踪管线

在自动化脚本中追踪每次调用的成本至关重要：

```bash
#!/bin/bash
# cost-tracked-query.sh - 带成本追踪的Claude查询

QUERY="$1"
INPUT_FILE="$2"

response=$(claude -p --output-format json "$QUERY" < "$INPUT_FILE")

# 提取结果和成本
result=$(echo "$response" | jq -r '.result')
cost=$(echo "$response" | jq -r '.total_cost_usd')
tokens=$(echo "$response" | jq -r '.usage.output_tokens')
duration=$(echo "$response" | jq -r '.duration_ms')

echo "$result"

# 记录到成本日志
echo "$(date -Iseconds)|${INPUT_FILE}|${cost}|${tokens}|${duration}" \
  >> ~/.claude/cost-log.csv

echo "[$(basename "$INPUT_FILE")] 成本: \$${cost}, Token: ${tokens}, 耗时: ${duration}ms" >&2
```

### 2.3 批量处理中的成本聚合

处理大量文件时，需要实时监控累计成本：

```bash
#!/bin/bash
# batch-review.sh - 批量代码审查，带成本上限

BUDGET_USD=1.00          # 总预算：1美元
COST_LOG="/tmp/batch-cost.log"
TARGET_DIR="src/"
> "$COST_LOG"

total_cost=0

for file in $(find "$TARGET_DIR" -name "*.ts" -not -path "*/node_modules/*"); do
  # 检查预算
  if (( $(echo "$total_cost >= $BUDGET_USD" | bc -l) )); then
    echo "⚠️ 预算已耗尽 (\$${total_cost} >= \$${BUDGET_USD})，停止处理" >&2
    break
  fi

  response=$(claude -p --output-format json --model haiku \
    "用一句话评估这个文件的安全风险：高/中/低。说明原因。" \
    < "$file")

  result=$(echo "$response" | jq -r '.result')
  cost=$(echo "$response" | jq -r '.total_cost_usd')

  # 累加成本
  total_cost=$(echo "$total_cost + $cost" | bc -l)

  echo "[$(basename "$file")] $result (+\$${cost})"
  echo "${file}|${cost}|${total_cost}" >> "$COST_LOG"
done

echo ""
echo "========== 批量审查完成 =========="
echo "总成本: \$${total_cost}"
echo "已处理: $(wc -l < "$COST_LOG") 个文件"
```

### 2.4 结构化数据提取

让Claude返回结构化数据，然后用`jq`处理：

```bash
# 让Claude分析依赖关系并返回JSON
claude -p --output-format json \
  "分析这个package.json，返回JSON格式的依赖风险评估。
  格式：{\"high_risk\": [{\"name\": \"...\", \"reason\": \"...\"}], 
         \"outdated\": [{\"name\": \"...\", \"current\": \"...\", \"latest\": \"...\"}]}" \
  < package.json \
  | jq '.result' | jq '.'
```

---

## 第三章：批量文件处理实战

### 3.1 并行处理框架

当需要处理大量文件时，串行处理太慢。使用`xargs -P`实现受控并行：

```bash
#!/bin/bash
# parallel-review.sh - 并行代码审查

MAX_PARALLEL=4          # 最大并行数（避免API限流）
MAX_BUDGET=2.00         # 总预算上限
TARGET_DIR="src/"
OUTPUT_DIR="reviews/"
mkdir -p "$OUTPUT_DIR"

# 生成文件列表
files=$(find "$TARGET_DIR" -name "*.py" -not -path "*/venv/*")

total_files=$(echo "$files" | wc -l)
echo "📋 准备审查 ${total_files} 个文件，并行度: ${MAX_PARALLEL}"

# 并行处理函数
review_file() {
  local file="$1"
  local basename=$(basename "$file" .py)

  claude -p --output-format json --model haiku \
    --system-prompt "你是安全审计专家。用中文回答。" \
    "审查以下Python代码的安全问题。列出：
    1. SQL注入风险
    2. XSS风险  
    3. 敏感信息泄露
    4. 其他安全问题
    如果没有问题，回答'未发现安全问题'。" \
    < "$file" \
    | jq -r '.result' > "${OUTPUT_DIR}/${basename}-review.md"

  echo "✅ 完成: $file"
}

# 使用xargs并行执行
export -f review_file
echo "$files" | xargs -P "$MAX_PARALLEL" -I {} bash -c 'review_file "$@"' _ {}

echo ""
echo "========== 审查报告已生成 =========="
echo "输出目录: ${OUTPUT_DIR}"
ls -la "$OUTPUT_DIR"
```

### 3.2 增量处理：只处理变更文件

结合Git，只处理有变更的文件，大幅降低成本：

```bash
#!/bin/bash
# incremental-review.sh - 只审查本次变更的文件

# 获取变更文件列表（相对于主分支）
CHANGED_FILES=$(git diff --name-only --diff-filter=ACMR main...HEAD \
  | grep -E '\.(ts|tsx|js|jsx|py|go|rs)$')

if [ -z "$CHANGED_FILES" ]; then
  echo "✨ 没有代码文件变更，无需审查"
  exit 0
fi

echo "📋 检测到 $(echo "$CHANGED_FILES" | wc -l) 个变更文件"

# 获取完整diff上下文
DIFF_CONTEXT=$(git diff main...HEAD -- $CHANGED_FILES)

# 一次性审查所有变更（比逐文件更省钱）
claude -p --output-format json \
  --system-prompt "你是高级代码审查员。重点关注：
  1. 安全漏洞
  2. 性能退化
  3. 逻辑错误
  4. 代码风格一致性
  按文件分组列出问题，标注严重程度：🔴严重 🟡警告 🟢建议" \
  "以下是本次代码变更的完整diff，请审查：

$DIFF_CONTEXT

请按以下格式输出：
### [文件名]
- [严重程度] 问题描述" \
  | jq -r '.result'
```

### 3.3 智能Issue分类器

将Claude Code作为智能分类引擎，自动处理GitHub Issue：

```bash
#!/bin/bash
# issue-triage.sh - 自动分类GitHub Issue

REPO="owner/repo"
LABELS=("bug" "feature" "documentation" "question" "enhancement")

# 获取未标记的Issue列表
ISSUES=$(gh issue list --repo "$REPO" --state open \
  --json number,title,body --limit 20 \
  | jq -c '.[] | select(.labels | length == 0)')

echo "$ISSUES" | while read -r issue; do
  number=$(echo "$issue" | jq -r '.number')
  title=$(echo "$issue" | jq -r '.title')
  body=$(echo "$issue" | jq -r '.body')

  # 调用Claude分类
  classification=$(claude -p --output-format json --model haiku \
    "将以下GitHub Issue分类为一个标签。
    可选标签：${LABELS[*]}
    只返回标签名称，不要其他文字。

    标题：${title}
    内容：${body}")

  label=$(echo "$classification" | jq -r '.result' | tr '[:upper:]' '[:lower:]')

  # 验证标签有效性
  if echo "${LABELS[@]}" | grep -qw "$label"; then
    gh issue edit "$number" --repo "$REPO" --add-label "$label"
    echo "✅ #${number} → ${label}"
  else
    echo "⚠️ #${number} → 无法识别: ${label}"
  fi
done
```

---

## 第四章：错误处理与可靠性工程

### 4.1 三层错误恢复

生产级Shell脚本必须有健壮的错误处理：

```bash
#!/bin/bash
# robust-query.sh - 带错误恢复的Claude查询

set -euo pipefail

query_with_retry() {
  local prompt="$1"
  local input="$2"
  local max_retries=3
  local timeout_sec=120
  local attempt=0

  while [ $attempt -lt $max_retries ]; do
    attempt=$((attempt + 1))
    echo "🔄 第${attempt}次尝试..." >&2

    # 使用timeout防止挂起
    response=$(timeout "$timeout_sec" \
      claude -p --output-format json "$prompt" <<< "$input" 2>/dev/null) \
      || exit_code=$?

    # 检查超时
    if [ "${exit_code:-0}" -eq 124 ]; then
      echo "⏰ 第${attempt}次尝试超时" >&2
      continue
    fi

    # 检查退出码
    if [ "${exit_code:-0}" -ne 0 ]; then
      echo "❌ 第${attempt}次执行失败 (exit: ${exit_code})" >&2
      sleep $((attempt * 5))  # 指数退避
      continue
    fi

    # 检查JSON有效性
    if ! echo "$response" | jq -e '.result' >/dev/null 2>&1; then
      echo "⚠️ 第${attempt}次返回无效JSON" >&2
      sleep $((attempt * 5))
      continue
    fi

    # 检查Claude内部错误
    subtype=$(echo "$response" | jq -r '.subtype')
    if [ "$subtype" != "success" ]; then
      echo "❌ Claude返回错误: $(echo "$response" | jq -r '.result')" >&2
      sleep $((attempt * 5))
      continue
    fi

    # 成功！
    echo "$response"
    return 0
  done

  echo "💥 所有重试均已失败" >&2
  return 1
}

# 使用示例
result=$(query_with_retry \
  "分析以下日志中的异常模式，返回JSON格式的错误摘要" \
  "$(cat /var/log/app/error.log)")

if [ $? -eq 0 ]; then
  echo "$result" | jq -r '.result'
  cost=$(echo "$result" | jq -r '.total_cost_usd')
  echo "本次分析成本: \$${cost}"
fi
```

### 4.2 幂等性保证

自动化脚本必须是幂等的——运行一次和运行十次产生相同结果：

```bash
#!/bin/bash
# idempotent-docs.sh - 幂等的文档生成

DOCS_DIR="docs/api"
FRONTIER_FILE=".claude/docs-frontier.md"

# 记录已处理的文件哈希，避免重复处理
get_file_hash() {
  md5sum "$1" | cut -d' ' -f1
}

# 检查文件是否已处理且未变更
is_processed() {
  local file="$1"
  local hash=$(get_file_hash "$file")
  local marker="${DOCS_DIR}/.processed/$(basename "$file").${hash}"

  [ -f "$marker" ]
}

# 标记文件已处理
mark_processed() {
  local file="$1"
  local hash=$(get_file_hash "$file")
  mkdir -p "${DOCS_DIR}/.processed"
  touch "${DOCS_DIR}/.processed/$(basename "$file").${hash}"
}

# 清理旧标记（文件已变更的）
cleanup_markers() {
  local file="$1"
  local basename=$(basename "$file")
  ls "${DOCS_DIR}/.processed/${basename}."* 2>/dev/null | grep -v "$(get_file_hash "$file")" | xargs rm -f 2>/dev/null || true
}

# 主处理逻辑
for src_file in src/**/*.ts; do
  cleanup_markers "$src_file"

  if is_processed "$src_file"; then
    echo "⏭️ 跳过（未变更）: $src_file"
    continue
  fi

  echo "📝 生成文档: $src_file"

  claude -p --model haiku \
    --system-prompt "你是技术文档专家。生成简洁的API文档。" \
    "为以下TypeScript代码生成Markdown格式的API文档。
    包括：函数签名、参数说明、返回值、使用示例。
    只输出文档内容，不要其他文字。" \
    < "$src_file" > "${DOCS_DIR}/$(basename "$src_file" .ts).md"

  mark_processed "$src_file"
  echo "✅ 完成: $src_file"
done
```

### 4.3 流式JSON实时监控

长时间运行的任务需要实时进度反馈。`stream-json`格式逐行输出事件：

```bash
#!/bin/bash
# stream-monitor.sh - 实时监控Claude执行进度

run_with_progress() {
  local prompt="$1"
  local input="$2"
  local total_cost=0

  claude -p --output-format stream-json "$prompt" <<< "$input" \
  | while IFS= read -r line; do
    # 每行是一个JSON事件
    event_type=$(echo "$line" | jq -r '.type // empty')

    case "$event_type" in
      "assistant")
        # 显示正在使用的工具
        tool=$(echo "$line" | jq -r '.message.content[-1].name // empty')
        if [ -n "$tool" ]; then
          echo "🔧 使用工具: $tool" >&2
        fi
        ;;
      "result")
        # 最终结果
        result=$(echo "$line" | jq -r '.result')
        cost=$(echo "$line" | jq -r '.total_cost_usd')
        echo "$result"
        echo "💰 总成本: \$${cost}" >&2
        ;;
    esac
  done
}

run_with_progress \
  "分析项目架构，生成系统架构图描述" \
  "$(find src -name '*.ts' -exec cat {} \;)"
```

---

## 第五章：实战案例——代码库健康巡检系统

这是本教程的完整实战项目：一个可部署的代码库自动巡检脚本，结合了前面所有技术。

### 5.1 系统架构

```mermaid
flowchart TB
    subgraph 触发层
        A[cron定时触发] --> B[巡检主脚本]
        B --> C[Git拉取最新代码]
    end

    subgraph 分析层
        C --> D{文件变更检测}
        D -->|有变更| E[安全扫描Agent]
        D -->|有变更| F[依赖检查Agent]
        D -->|有变更| G[代码质量Agent]
        D -->|无变更| H[跳过本次巡检]
    end

    subgraph 聚合层
        E --> I[结果收集器]
        F --> I
        G --> I
    end

    subgraph 输出层
        I --> J[jq汇总处理]
        J --> K[Markdown报告]
        J --> L[飞书/钉钉通知]
        J --> M[成本统计日志]
    end

    style A fill:#4f46e5,color:#fff
    style I fill:#059669,color:#fff
    style K fill:#d97706,color:#fff
    style L fill:#dc2626,color:#fff
```

### 5.2 完整脚本实现

```bash
#!/bin/bash
# health-patrol.sh - 代码库健康巡检系统
set -euo pipefail

# ========== 配置区 ==========
PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
REPORT_DIR="${PROJECT_DIR}/patrol-reports"
COST_LOG="${PROJECT_DIR}/.claude/patrol-costs.csv"
MAX_BUDGET=0.50         # 单次巡检预算上限（美元）
NOTIFICATION_WEBHOOK=""  # 飞书/钉钉Webhook（可选）
MODEL="haiku"            # 使用Haiku控制成本
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
REPORT_FILE="${REPORT_DIR}/patrol_${TIMESTAMP}.md"

mkdir -p "$REPORT_DIR"

# ========== 工具函数 ==========
# 带预算检查的Claude调用
budgeted_query() {
  local prompt="$1"
  local input="${2:-}"

  # 检查累计成本
  local spent=$(awk -F'|' '{sum+=$3} END{print sum}' "$COST_LOG" 2>/dev/null || echo "0")
  if (( $(echo "$spent >= $MAX_BUDGET" | bc -l) )); then
    echo "⚠️ 预算已耗尽 (\$${spent} / \$${MAX_BUDGET})" >&2
    return 1
  fi

  # 执行查询
  local response
  response=$(timeout 90 claude -p --output-format json --model "$MODEL" \
    --system-prompt "你是资深安全工程师和代码质量专家。用中文回答，简洁精炼。" \
    "$prompt" <<< "$input" 2>/dev/null) || {
    echo "❌ 查询执行失败" >&2
    return 1
  }

  # 提取结果和成本
  local result cost
  result=$(echo "$response" | jq -r '.result // "无结果"')
  cost=$(echo "$response" | jq -r '.total_cost_usd // 0')

  # 记录成本
  echo "${TIMESTAMP}|${prompt:0:30}|${cost}" >> "$COST_LOG"

  echo "$result"
}

# ========== 巡检模块 ==========

# 模块1：安全扫描
security_scan() {
  echo "🔍 执行安全扫描..."

  # 收集敏感文件列表
  local sensitive_files=""
  sensitive_files=$(find . -type f \( \
    -name "*.env" -o -name "*.secret" -o -name "*.key" -o \
    -name "credentials*" -o -name "*.pem" \) \
    -not -path "*/node_modules/*" -not -path "*/.git/*" \
    2>/dev/null || true)

  # 收集可能的硬编码密钥
  local hardcoded=""
  hardcoded=$(grep -rn --include="*.{ts,js,py,go}" \
    -E '(password|secret|api_key|token)\s*=\s*["\x27][^"\x27]{8,}' \
    --include="*.{ts,js,py,go}" . 2>/dev/null | head -20 || true)

  local scan_input="敏感文件检查：
${sensitive_files:-无}

硬编码密钥检查：
${hardcoded:-无}

请评估安全风险等级（高/中/低），并列出具体问题。"

  budgeted_query "安全扫描报告" "$scan_input"
}

# 模块2：依赖健康检查
dependency_check() {
  echo "📦 检查依赖健康度..."

  if [ -f "package.json" ]; then
    budgeted_query "分析package.json中的依赖：
1. 哪些依赖已过时超过2个大版本？
2. 哪些依赖有已知安全漏洞（基于名称判断）？
3. 是否有不必要的冗余依赖？
简明列出问题。" "$(cat package.json)"
  elif [ -f "requirements.txt" ]; then
    budgeted_query "分析Python依赖的健康状况：
1. 过时依赖
2. 已知安全风险的包
3. 冗余依赖
简明列出问题。" "$(cat requirements.txt)"
  else
    echo "⏭️ 未发现依赖文件，跳过"
  fi
}

# 模块3：代码质量评估
quality_assessment() {
  echo "📊 评估代码质量..."

  # 统计代码行数和文件数
  local stats
  stats=$(find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" \) \
    -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" \
    | xargs wc -l 2>/dev/null | tail -1 || echo "无法统计")

  # 检查TODO/FIXME/HACK
  local tech_debt
  tech_debt=$(grep -rn --include="*.{ts,js,py,go}" \
    -E '(TODO|FIXME|HACK|XXX|WORKAROUND)' . 2>/dev/null | head -30 || echo "无")

  budgeted_query "基于以下指标评估代码健康度（评分1-10）：
代码统计：${stats}
技术债务标记：
${tech_debt}

请给出：
1. 总体评分
2. 主要风险点
3. 改善建议（最多3条）" "$stats"
}

# ========== 报告生成 ==========
generate_report() {
  local security_result="$1"
  local dependency_result="$2"
  local quality_result="$3"

  cat > "$REPORT_FILE" <<EOF
# 🏥 代码库健康巡检报告

**项目**: $(basename "$PROJECT_DIR")
**时间**: $(date '+%Y-%m-%d %H:%M:%S')
**分支**: $(git branch --show-current 2>/dev/null || echo "N/A")

---

## 🔒 安全扫描

${security_result}

---

## 📦 依赖健康

${dependency_result}

---

## 📊 代码质量

${quality_result}

---

## 💰 本次巡检成本

$(awk -F'|' -v ts="$TIMESTAMP" '$1==ts{sum+=$3} END{printf "总成本: $%.4f", sum}' "$COST_LOG" 2>/dev/null || echo "无法统计")

---
*由 Claude Code 巡检系统自动生成*
EOF

  echo ""
  echo "📄 报告已生成: $REPORT_FILE"
}

# ========== 通知发送 ==========
send_notification() {
  if [ -z "$NOTIFICATION_WEBHOOK" ]; then
    return 0
  fi

  local summary=$(head -20 "$REPORT_FILE")
  curl -s -X POST "$NOTIFICATION_WEBHOOK" \
    -H 'Content-Type: application/json' \
    -d "{\"content\": \"🏥 代码库巡检完成\n$(date '+%Y-%m-%d %H:%M')\n\n${summary}\"}" \
    >/dev/null 2>&1 || true
}

# ========== 主流程 ==========
main() {
  cd "$PROJECT_DIR"

  echo "🚀 开始代码库健康巡检..."
  echo "   项目: $(basename "$PROJECT_DIR")"
  echo "   预算: \$${MAX_BUDGET}"
  echo ""

  # 执行三个巡检模块
  security_result=$(security_scan)
  dependency_result=$(dependency_check)
  quality_result=$(quality_assessment)

  # 生成报告
  generate_report "$security_result" "$dependency_result" "$quality_result"

  # 发送通知
  send_notification

  echo ""
  echo "✅ 巡检完成！"
}

main "$@"
```

### 5.3 定时调度配置

将巡检脚本配置为cron定时任务：

```bash
# 每天早上8:30执行巡检（使用非整点避免API峰值）
# crontab -e
30 8 * * 1-5 cd /path/to/project && bash scripts/health-patrol.sh >> /tmp/patrol.log 2>&1

# 或者使用Claude Code内置调度（如果可用）
# /loop 24h /health-patrol
```

---

## 第六章：高级模式——跨工具编排

### 6.1 Claude Code + ripgrep + jq 流水线

将Claude Code嵌入经典的Unix工具链中：

```bash
#!/bin/bash
# smart-grep.sh - 智能代码搜索：ripgrep找到 + Claude理解

QUERY="$1"

# 第一步：ripgrep精确搜索
matches=$(rg --json -n "$QUERY" --type-add 'config:*.json,*.yaml,*.toml' \
  --type ts --type py --type go 2>/dev/null | head -50)

if [ -z "$matches" ]; then
  echo "未找到匹配结果"
  exit 0
fi

# 第二步：Claude分析匹配结果的语义
claude -p --model haiku \
  "以下是代码搜索 '${QUERY}' 的匹配结果。
  按重要性排序，为每个匹配给出：
  1. 文件路径和行号
  2. 该匹配的上下文语义
  3. 相关性评分（1-5星）
  
  只展示3星以上的结果。" <<< "$matches"
```

### 6.2 多语言翻译管线

利用管道模式构建文档翻译管线：

```bash
#!/bin/bash
# translate-docs.sh - 多语言文档翻译管线

SOURCE_DOC="$1"
TARGET_LANG="${2:-日语}"
GLOSSARY="${3:-.claude/glossary.md}"

# 加载术语表（确保专业术语一致性）
glossary_content=""
if [ -f "$GLOSSARY" ]; then
  glossary_content=$(cat "$GLOSSARY")
fi

claude -p --output-format json \
  --system-prompt "你是专业技术翻译。保持Markdown格式不变。
参考术语表：${glossary_content}
翻译原则：
1. 技术术语保留英文
2. 保持代码块不变
3. 保持链接地址不变" \
  "将以下文档翻译为${TARGET_LANG}：$(cat "$SOURCE_DOC")" \
  | jq -r '.result' > "${SOURCE_DOC%.md}.${TARGET_LANG}.md"

echo "✅ 翻译完成: ${SOURCE_DOC} → ${TARGET_LANG}"
```

### 6.3 日志智能分析管线

```bash
#!/bin/bash
# log-analyzer.sh - 实时日志智能分析

LOG_FILE="${1:-/var/log/app/error.log}"
LINES="${2:-100}"

# 提取最近的错误日志
recent_errors=$(tail -n "$LINES" "$LOG_FILE" | grep -i "error\|exception\|panic" | head -30)

if [ -z "$recent_errors" ]; then
  echo "✅ 最近${LINES}行日志中无错误"
  exit 0
fi

# Claude分析
analysis=$(claude -p --output-format json --model haiku \
  "分析以下应用错误日志，返回JSON格式：
{
  \"severity\": \"critical|high|medium|low\",
  \"root_cause\": \"一句话描述根因\",
  \"affected_services\": [\"服务列表\"],
  \"suggested_fix\": \"修复建议\",
  \"pattern\": \"是否为已知模式（是/否）\"
}

日志内容：
${recent_errors}")

# 提取并展示
severity=$(echo "$analysis" | jq -r '.result' | jq -r '.severity // "unknown"')
root_cause=$(echo "$analysis" | jq -r '.result' | jq -r '.root_cause // "分析失败"')

case "$severity" in
  critical|high)
    echo "🚨 [${severity^^}] ${root_cause}"
    echo "$analysis" | jq -r '.result' | jq '.'
    # 可选：触发告警
    ;;
  medium|low)
    echo "⚠️ [${severity}] ${root_cause}"
    ;;
  *)
    echo "ℹ️ 日志分析完成"
    echo "$analysis" | jq -r '.result'
    ;;
esac
```

---

## 第七章：成本优化策略

### 7.1 模型选择决策树

```mermaid
flowchart TD
    A[开始任务] --> B{需要工具调用？}
    B -->|是| C{需要写代码？}
    B -->|否| D{响应复杂度？}
    C -->|是| E[使用Sonnet]
    C -->|否| F{是否复杂推理？}
    F -->|是| E
    F -->|否| G[使用Haiku]
    D -->|简单提取/分类| G
    D -->|复杂分析/创作| H{需要深度思考？}
    H -->|是| I[使用Opus]
    H -->|否| E

    style G fill:#059669,color:#fff
    style E fill:#d97706,color:#fff
    style I fill:#dc2626,color:#fff
```

| 模型 | 典型场景 | 相对成本 | 推荐用途 |
|------|---------|---------|---------|
| Haiku | 分类、提取、简短问答 | ¥ | 批量处理、高频调用 |
| Sonnet | 代码审查、重构、中等分析 | ¥¥¥ | 日常开发任务 |
| Opus | 架构设计、复杂推理 | ¥¥¥¥¥ | 关键决策点 |

### 7.2 实用省钱技巧

```bash
# 技巧1：用Haiku做预处理，只在必要时升级模型
# 先用Haiku判断是否需要深度分析
needs_deep=$(claude -p --model haiku \
  "这个文件是否包含复杂的安全问题？只回答yes或no" < "$file")

if [ "$needs_deep" = "yes" ]; then
  # 用Sonnet深度分析
  claude -p --model sonnet "详细安全审查..." < "$file"
fi

# 技巧2：利用缓存减少Token消耗
# 相同的system-prompt会被缓存，多次调用复用
claude -p --system-prompt "你是$(cat .claude/system-prompt.md)" \
  --model haiku "批量任务1..."
claude -p --system-prompt "你是$(cat .claude/system-prompt.md)" \
  --model haiku "批量任务2..."

# 技巧3：限制输出Token数
claude -p --max-tokens 200 "一句话总结" < "$file"
```

---

## 延伸阅读

1. **Anthropic官方文档 - Run Claude Code programmatically** — 无头模式和SDK编程的权威参考
2. **amux.io - Claude Code Headless Mode: The Complete Self-Hosting Guide** — 涵盖Docker部署、并行Agent舰队、认证策略
3. **Learn Prompting - Headless & Programmatic Claude Code** — 生产级无头模式的踩坑经验和社区验证的模式
4. **FlorianBruniaux/claude-code-ultimate-guide (GitHub)** — 15+实用脚本集合，包含会话管理、成本追踪、配置同步

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | DevOps/SRE训练营、Shell脚本进阶营、AI工具链训练营 |
| **教学时长** | 4-5小时（含动手练习） |
| **难度级别** | ⭐⭐⭐ 中高级（需要Shell和CLI基础） |
| **硬件要求** | 任意Linux/macOS终端 + 网络连接 |
| **最大班容量** | 30人（每人需要独立Claude Code账号） |
| **前置课程** | Linux基础 + Claude Code入门 |
| **可拆分模块** | 是，每章可独立授课，1-1.5小时/章 |

---

## 参考来源

1. [Run Claude Code programmatically - Anthropic官方文档](https://code.claude.com/docs/en/headless) — 无头模式、Agent SDK和程序化调用的官方参考
2. [Claude Code Headless Mode: The Complete Self-Hosting Guide (2026) — amux.io](https://amux.io/guides/claude-code-headless/) — 涵盖Docker部署、并行Agent舰队调度和认证策略的深度指南
3. [Headless & Programmatic Claude Code: SDK & Automation — Learn Prompting](https://learn-prompting.fr/blog/claude-code-sdk-headless) — 生产级无头模式的社区踩坑经验和验证模式
4. [Using Claude Code Programmatically - GitHub Gist](https://gist.github.com/JacobFV/2c4a75bc6a835d2c1f6c863cfcbdfa5a) — JSON输出模式的发现、Node.js封装实现和成本追踪方法
5. [Building Production AI Agents with Claude Code CLI — CallSphere](https://callsphere.ai/blog/building-production-ai-agents-claude-code-cli-setup-deployment-2026) — Hooks、MCP服务器和生产部署模式参考

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