学习目标：掌握
claude -p的全部参数组合、三种输出格式的差异与适用场景、stream-json 事件流的实时解析、多实例并行管道编排，以及/batch命令的批量文件处理。读完本文后，你能将 Claude Code 作为 Unix 管道中的一个标准组件，嵌入任何自动化流水线。适用人群：有 6 个月以上 Claude Code 使用经验、熟悉 Shell 脚本、需要将 AI 编码能力集成到 CI/CD 或批量处理流水线中的中高级开发者。
| 依赖 | 最低版本 | 验证命令 |
|---|---|---|
| Claude Code CLI | ≥ 1.0.50 | claude --version |
| Node.js | ≥ 18 | node --version |
| jq | ≥ 1.7 | jq --version |
| Git | ≥ 2.40 | git --version |
确认 CLI 版本后，运行一次交互式 claude 确保认证正常，再继续本文的实验。
-p 模式——从交互到管道的范式转变-p（也叫 --print）将 Claude Code 从一个交互式终端工具变成一个 stdin→stdout 的 Unix 命令。它不启动 TUI、不接受用户输入、直接将响应打印到标准输出：
# 最简单的用法——直接问问题
claude -p "用一行命令找出当前目录下最大的5个文件"
# 管道输入——将文件内容作为上下文
cat src/main.ts | claude -p "解释这段TypeScript代码的架构模式"
# 组合使用——在指定项目目录下执行
claude -p --cwd ./my-project "列出所有未处理的TODO注释"
关键特性：
- 无交互：不弹出权限确认、不需要按 Enter
- 纯文本输出：默认输出纯 Markdown 文本到 stdout
- 管道友好：可被 | 管道连接、被 $() 捕获
- 退出码语义：成功返回 0，错误返回非零值
--output-format 是与 -p 搭配的核心参数，有三种值：
| 格式 | 参数 | 特点 | 适用场景 |
|---|---|---|---|
| text（默认） | --output-format text |
纯 Markdown 文本 | 人类阅读、简单脚本 |
| json | --output-format json |
完整响应的 JSON 对象 | 结构化提取、API 集成 |
| stream-json | --output-format stream-json |
JSONL 逐行事件流 | 实时监控、管道链式处理 |
# text 格式——直接拿到答案
claude -p "什么是React Server Components" --output-format text
# json 格式——结构化提取
claude -p "分析 package.json 中的依赖" --output-format json | jq '.result'
# stream-json 格式——实时事件流
claude -p "重构 auth 模块" --output-format stream-json --verbose
# === 基础组合 ===
# 指定工作目录 + 输出 JSON
claude -p --cwd ./backend --output-format json "列出所有API端点"
# 限制对话轮数，防止跑飞
claude -p --max-turns 5 "修复所有TypeScript编译错误"
# 指定允许的工具（安全控制）
claude -p --allowedTools "Read,Write,Bash(git*)" "运行测试并提交"
# === 进阶组合 ===
# 完全无头 + 流式输出 + 详细日志
claude -p \
--output-format stream-json \
--verbose \
--max-turns 10 \
--allowedTools "Read,Write,Bash(npm test)" \
"修复所有失败的测试用例"
# 从 stdin 读取 prompt（适合长 prompt）
echo "请审查以下代码变更：$(git diff HEAD~1)" | claude -p --output-format json
stream-json 格式输出的是 JSONL（JSON Lines）——每行一个完整的 JSON 对象，包含一个必需的 type 字段：
claude -p --output-format stream-json --verbose "列出src目录结构"
输出示例（逐行）：
{"type":"system","subtype":"init","session_id":"sess_abc123","tools":["Read","Write","Bash","Grep","Glob"],"mcp_servers":[{"name":"context7","status":"connected"}]}
{"type":"assistant","subtype":"text","content":"我来分析 src 目录结构...\n\n","stop_reason":null}
{"type":"assistant","subtype":"tool_use","tool":"Glob","input":{"pattern":"src/**/*"}}
{"type":"tool_result","tool":"Glob","output":"src/main.ts\nsrc/config.ts\nsrc/utils.ts"}
{"type":"assistant","subtype":"text","content":"src目录包含3个TypeScript文件...","stop_reason":"end_turn"}
{"type":"result","subtype":"success","cost_usd":0.0042,"duration_ms":3200,"num_turns":2}
┌──────────────────────────────────────────────────────────┐
│ stream-json 事件类型 │
├────────────┬─────────────────────────────────────────────┤
│ 事件类型 │ 含义 │
├────────────┼─────────────────────────────────────────────┤
│ system │ 会话初始化，包含可用工具和MCP服务器列表 │
│ assistant │ Claude的响应（文本或工具调用） │
│ tool_result│ 工具执行结果 │
│ user │ 用户消息（多轮时出现） │
│ result │ 最终汇总：成本、耗时、轮数 │
│ error │ 错误事件 │
└────────────┴─────────────────────────────────────────────┘
场景：监控 Claude Code 执行进度，实时显示成本和工具调用
#!/bin/bash
# monitor.sh — 实时监控 claude -p 执行过程
claude -p --output-format stream-json --verbose "$@" | while IFS= read -r line; do
type=$(echo "$line" | jq -r '.type // empty')
case "$type" in
system)
session_id=$(echo "$line" | jq -r '.session_id')
echo "🔗 会话启动: $session_id"
;;
assistant)
subtype=$(echo "$line" | jq -r '.subtype')
if [ "$subtype" = "tool_use" ]; then
tool=$(echo "$line" | jq -r '.tool')
echo "🔧 调用工具: $tool"
elif [ "$subtype" = "text" ]; then
content=$(echo "$line" | jq -r '.content')
echo "💬 $content"
fi
;;
tool_result)
tool=$(echo "$line" | jq -r '.tool')
echo "✅ 工具完成: $tool"
;;
result)
cost=$(echo "$line" | jq -r '.cost_usd')
duration=$(echo "$line" | jq -r '.duration_ms')
turns=$(echo "$line" | jq -r '.num_turns')
echo ""
echo "═══════════════════════════════════"
echo "📊 执行完成"
echo " 💰 成本: \$$cost"
echo " ⏱️ 耗时: ${duration}ms"
echo " 🔄 轮数: $turns"
echo "═══════════════════════════════════"
;;
error)
msg=$(echo "$line" | jq -r '.error.message')
echo "❌ 错误: $msg"
;;
esac
done
使用方式：
chmod +x monitor.sh
./monitor.sh "分析项目架构并生成文档"
在管道中，我们通常只关心 Claude 的最终文本回复：
#!/bin/bash
# extract-result.sh — 只提取Claude最终回复文本
claude -p --output-format stream-json --verbose "$@" | \
jq -r 'select(.type == "assistant" and .subtype == "text" and .stop_reason == "end_turn") | .content' | \
head -1
更优雅的方式——使用 json 格式直接拿到结构化结果：
# JSON格式直接返回完整结果对象
RESULT=$(claude -p --output-format json "分析这段代码的安全漏洞" <<'EOF'
const password = "hardcoded123";
app.get('/user/:id', (req, res) => {
db.query(`SELECT * FROM users WHERE id = ${req.params.id}`);
});
EOF
)
# 提取各字段
echo "回复内容: $(echo "$RESULT" | jq -r '.result')"
echo "执行成本: \$(echo "$RESULT" | jq -r '.cost_usd')"
echo "使用轮数: $(echo "$RESULT" | jq -r '.num_turns')"
Claude Code 的 -p 模式天然适配 Unix 管道哲学。以下是五种经典管道模式：
flowchart LR
A[数据源] -->|stdin/参数| B[claude -p]
B -->|stdout| C[后处理]
subgraph "模式1: 过滤器"
D[git diff] -->|管道| B
B -->|文本| E[人类阅读]
end
subgraph "模式2: 变换器"
F[JSON数据] --> B
B -->|JSON| G[jq提取]
end
subgraph "模式3: 聚合器"
H[多个文件] --> B
B -->|汇总| I[报告文件]
end
subgraph "模式4: 链式Agent"
J[claude -p] -->|输出| K[claude -p]
K -->|输出| L[最终结果]
end
subgraph "模式5: 扇出并行"
M[文件列表] --> N1[claude -p]
M --> N2[claude -p]
M --> N3[claude -p]
N1 & N2 & N3 --> O[结果合并]
end
#!/bin/bash
# review-pipeline.sh — Git 变更自动审查管道
# 获取变更内容
DIFF=$(git diff --cached)
if [ -z "$DIFF" ]; then
echo "没有暂存的变更"
exit 0
fi
# Claude 审查 + 结构化输出
REVIEW=$(claude -p --output-format json --max-turns 3 <<PROMPT
你是一位资深代码审查员。请审查以下 Git 暂存区的代码变更，给出：
1. **严重程度**：critical/warning/info
2. **问题列表**：每个问题包含文件名、行号、问题描述、修复建议
3. **总体评价**：approve/request_changes/comment
以 JSON 格式返回结果。
变更内容：
$DIFF
PROMPT
)
# 提取并判断
SEVERITY=$(echo "$REVIEW" | jq -r '.result' | jq -r '.severity // "info"')
VERDICT=$(echo "$REVIEW" | jq -r '.result' | jq -r '.verdict // "comment"')
echo "审查结果: $VERDICT (严重程度: $SEVERITY)"
if [ "$VERDICT" = "request_changes" ]; then
echo "❌ 审查未通过，请修改后重新提交"
exit 1
fi
echo "✅ 审查通过"
#!/bin/bash
# chain-agents.sh — 多Agent链式处理
PROJECT_DIR="./my-project"
OUTPUT_DIR="./reports"
mkdir -p "$OUTPUT_DIR"
# Agent 1: 分析架构
echo "🔍 Agent 1: 分析项目架构..."
ARCH=$(claude -p --cwd "$PROJECT_DIR" --output-format text --max-turns 5 \
"分析这个项目的架构，列出所有模块和它们的职责，输出Markdown格式")
echo "$ARCH" > "$OUTPUT_DIR/architecture.md"
# Agent 2: 基于架构分析生成API文档
echo "📝 Agent 2: 生成API文档..."
API_DOC=$(claude -p --cwd "$PROJECT_DIR" --output-format text --max-turns 8 \
"基于以下架构分析，为所有公开API生成详细的接口文档：\n\n$ARCH")
echo "$API_DOC" > "$OUTPUT_DIR/api-docs.md"
# Agent 3: 基于API文档生成测试计划
echo "🧪 Agent 3: 生成测试计划..."
TEST_PLAN=$(claude -p --cwd "$PROJECT_DIR" --output-format text --max-turns 5 \
"基于以下API文档，生成完整的测试计划，包含边界条件和异常用例：\n\n$API_DOC")
echo "$TEST_PLAN" > "$OUTPUT_DIR/test-plan.md"
echo "✅ 全链路完成！报告保存在 $OUTPUT_DIR/"
#!/bin/bash
# fanout-parallel.sh — 并行处理多个文件
FILES=(src/auth.ts src/api.ts src/db.ts src/utils.ts)
PROMPT="为这个文件生成完整的单元测试，使用 Jest 框架，覆盖所有导出函数"
# 并行启动多个 claude -p 实例
declare -a PIDS
for file in "${FILES[@]}"; do
BASENAME=$(basename "$file" .ts)
OUTPUT_FILE="tests/${BASENAME}.test.ts"
claude -p --output-format text --max-turns 5 \
--allowedTools "Read,Write" \
"读取 $file 的内容，然后 $PROMPT。将测试文件写入 $OUTPUT_FILE" \
> "/tmp/claude-${BASENAME}.log" 2>&1 &
PIDS+=($!)
echo "🚀 已启动: $file (PID: $!)"
done
# 等待所有实例完成
echo ""
echo "⏳ 等待所有任务完成..."
FAILURES=0
for i in "${!PIDS[@]}"; do
if ! wait "${PIDS[$i]}"; then
echo "❌ 失败: ${FILES[$i]}"
((FAILURES++))
else
echo "✅ 完成: ${FILES[$i]}"
fi
done
echo ""
echo "📊 结果: $(( ${#FILES[@]} - FAILURES ))/${#FILES[@]} 成功"
#!/bin/bash
# extract-pipeline.sh — 从日志中提取和结构化信息
# 从应用日志中提取错误，Claude做语义理解
tail -1000 app.log | claude -p --output-format json --max-turns 1 <<'PROMPT'
分析以下应用日志，提取所有错误信息，按以下JSON Schema返回：
{
"errors": [
{
"timestamp": "ISO8601格式",
"level": "ERROR|WARN",
"service": "服务名",
"message": "错误消息",
"root_cause": "你的分析",
"suggested_fix": "修复建议"
}
],
"summary": {
"total_errors": 数量,
"by_service": {"服务名": 数量},
"critical_count": 数量
}
}
日志内容：
PROMPT
/batch 命令——批量文件处理/batch 核心概念/batch 是 Claude Code 内置的批量处理命令，专门用于对大量文件执行相同变换。与手动 -p 并行不同，/batch 由 Claude Code 内部调度，效率可提升 10 倍：
# /batch 是交互式命令，在 Claude Code REPL 中使用
# 用法：先描述你要做什么，然后 /batch 自动匹配文件
/batch 工作流程flowchart TD
A[描述变换意图] --> B[/batch 生成文件列表]
B --> C{确认文件范围}
C -->|确认| D[样本验证: 对前3个文件试运行]
D --> E{检查样本结果}
E -->|满意| F[全量执行]
E -->|需调整| A
F --> G[生成执行报告]
C -->|拒绝| A
style D fill:#f9f,stroke:#333
style F fill:#9f9,stroke:#333
场景：将项目中所有 JavaScript 文件迁移为 TypeScript
在 Claude Code 交互模式中：
> /batch 将所有 .js 文件转换为 .ts，添加类型注解，保持功能不变
Claude: 我找到了 47 个 .js 文件。让我先对 3 个样本文件进行试运行...
[样本 1] src/config.js → src/config.ts ✅
[样本 2] src/utils.js → src/utils.ts ✅
[样本 3] src/errors.js → src/errors.ts ✅
样本结果是否符合预期？(y/n/edit): y
正在处理剩余 44 个文件...
[========================] 47/47 完成
结果：47 个文件已成功转换
- 添加了类型注解: 312 处
- 修复了隐式 any: 89 处
- 新增 interface 定义: 23 个
-p 模拟批量处理如果需要在非交互环境中批量处理，可以组合 -p 和 Shell 脚本：
#!/bin/bash
# batch-migrate.sh — 非交互式批量迁移脚本
# 安全控制：只允许读取和写入
ALLOWED="Read,Write"
MAX_TURNS=3
find ./src -name "*.js" -type f | while read -r file; do
ts_file="${file%.js}.ts"
echo "🔄 处理: $file → $ts_file"
claude -p \
--allowedTools "$ALLOWED" \
--max-turns $MAX_TURNS \
--output-format json \
"读取 $file，将其转换为 TypeScript（添加类型注解），保存到 $ts_file，然后删除原文件" \
> "/tmp/batch-$(basename "$file").json"
# 检查是否成功
status=$(jq -r '.result' "/tmp/batch-$(basename "$file").json" 2>/dev/null)
if [ $? -eq 0 ]; then
echo " ✅ 成功"
else
echo " ❌ 失败"
fi
done
#!/bin/bash
# safe-batch.sh — 安全批量处理：测试 → 验证 → 全量
PROMPT="将所有 class 组件转换为函数组件，使用 React Hooks"
TARGET_DIR="./src/components"
SAMPLE_SIZE=3
# 第一阶段：发现目标文件
FILES=($(find "$TARGET_DIR" -name "*.tsx" -type f))
TOTAL=${#FILES[@]}
echo "🎯 发现 $TOTAL 个目标文件"
# 第二阶段：样本测试
echo ""
echo "🧪 阶段1：样本测试（前 $SAMPLE_SIZE 个文件）"
for ((i=0; i<SAMPLE_SIZE && i<TOTAL; i++)); do
echo " 处理样本: ${FILES[$i]}"
claude -p --max-turns 5 --allowedTools "Read,Write" \
"$PROMPT。文件: ${FILES[$i]}" > /dev/null
done
# 第三阶段：运行测试验证
echo ""
echo "🔍 阶段2：运行测试验证"
npm test 2>&1 | tail -5
read -p "样本结果是否满意？(y/n) " CONFIRM
if [ "$CONFIRM" != "y" ]; then
echo "已取消"
exit 0
fi
# 第四阶段：全量执行
echo ""
echo "🚀 阶段3：全量执行"
for ((i=SAMPLE_SIZE; i<TOTAL; i++)); do
echo " [$((i+1))/$TOTAL] ${FILES[$i]}"
claude -p --max-turns 5 --allowedTools "Read,Write" \
"$PROMPT。文件: ${FILES[$i]}" > /dev/null
done
echo ""
echo "✅ 全量执行完成，运行最终测试..."
npm test
--allowedTools 精细化控制在非交互模式中，权限控制是安全的核心。--allowedTools 可以精确限制 Claude 能使用的工具：
# 只读分析——最安全的模式
claude -p --allowedTools "Read,Glob,Grep" \
"分析项目的技术债务"
# 读写但不能执行命令
claude -p --allowedTools "Read,Write,Glob,Grep" \
"重构所有导出函数的命名规范"
# 允许特定 Bash 命令（支持 glob 模式）
claude -p --allowedTools "Read,Write,Bash(npm*),Bash(git*)" \
"运行测试并修复失败的用例"
# 允许所有 Bash 命令（慎用！）
claude -p --allowedTools "Read,Write,Bash" \
"安装依赖并配置项目"
--dangerously-skip-permissions 使用守则当需要完全自动化时，这个标志跳过所有权限确认：
# CI 环境专用——结合环境变量保护
if [ "$CI" = "true" ]; then
claude -p \
--dangerously-skip-permissions \
--max-turns 20 \
--output-format stream-json \
"修复所有lint错误" | ./monitor.sh
else
echo "此脚本仅在CI环境中运行"
exit 1
fi
安全清单：
| 检查项 | 说明 |
|---|---|
| ✅ 仅在 CI 容器中运行 | 隔离环境，不影响宿主 |
✅ 设置 --max-turns |
防止无限循环 |
| ✅ 限制网络访问 | 容器级别禁止外联 |
| ✅ 审计日志 | stream-json 记录所有操作 |
| ❌ 不要在生产数据上直接运行 | 先在 staging 验证 |
| ❌ 不要暴露 API Key | 使用 CI 密钥管理 |
flowchart TD
A[claude -p 启动] --> B{权限配置}
B -->|--allowedTools| C[白名单模式]
B -->|--dangerously-skip-permissions| D[完全跳过]
B -->|无参数| E[交互确认<br/>不适用-p模式]
C --> C1{工具在白名单?}
C1 -->|是| F[执行]
C1 -->|否| G[报错退出]
D --> F
E --> H[挂起等待输入<br/>超时失败]
style D fill:#fbb,stroke:#333
style C fill:#bfb,stroke:#333
style H fill:#fbb,stroke:#333
# .github/workflows/claude-review.yml
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
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 Claude Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
# 获取 PR 变更文件列表
CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
# Claude 审查并输出 JSON
claude -p --output-format json --max-turns 5 <<REVIEW_PROMPT
你是代码审查专家。审查以下 PR 变更文件：
$CHANGED_FILES
请关注：
1. 安全漏洞（SQL注入、XSS等）
2. 性能问题（N+1查询、内存泄漏等）
3. 代码质量（命名、复杂度等）
4. 测试覆盖
输出 JSON 格式的审查结果。
REVIEW_PROMPT
#!/bin/bash
# .git/hooks/pre-commit — Claude 自动代码检查
# 获取暂存的文件
STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx|py)$')
if [ -z "$STAGED" ]; then
exit 0
fi
echo "🔍 Claude 正在审查暂存的文件..."
# 读取暂存内容并审查
ISSUES=$(git diff --cached -- $STAGED | claude -p \
--output-format json \
--max-turns 1 \
--allowedTools "Read" \
"审查以下代码变更，只关注严重问题(bugs和安全漏洞)。如果有严重问题，返回JSON: {\"has_issues\": true, \"issues\": [...]}。如果没有，返回 {\"has_issues\": false}")
HAS_ISSUES=$(echo "$ISSUES" | jq -r '.result' | jq -r '.has_issues // false')
if [ "$HAS_ISSUES" = "true" ]; then
echo "⚠️ Claude 发现潜在问题："
echo "$ISSUES" | jq -r '.result' | jq -r '.issues[] | " • \(.file):\(.line) - \(.message)"'
echo ""
read -p "是否仍然提交？(y/n) " OVERRIDE
[ "$OVERRIDE" = "y" ] || exit 1
fi
exit 0
#!/bin/bash
# daily-deps-check.sh — 每日依赖安全检查
REPORT_FILE="reports/deps-check-$(date +%Y%m%d).md"
mkdir -p reports
claude -p \
--output-format text \
--max-turns 10 \
--allowedTools "Read,Bash(npm*),Bash(npx*)" \
"执行以下任务：
1. 运行 npm audit 检查安全漏洞
2. 运行 npm outdated 检查过时依赖
3. 分析 package.json 中的依赖是否有更好的替代品
4. 生成 Markdown 格式的报告，包含优先级排序
将报告写入 $REPORT_FILE"
# 如果有高危漏洞，发送告警
if grep -q "critical\|high" "$REPORT_FILE" 2>/dev/null; then
echo "🚨 发现高危依赖漏洞，请查看 $REPORT_FILE"
# 可接入 Slack/邮件通知
fi
Cron 配置：
# 每天早上8点执行依赖检查
0 8 * * * cd /path/to/project && ./daily-deps-check.sh >> logs/deps-cron.log 2>&1
构建一个完整的文档生成流水线：扫描源代码 → 生成架构文档 → 生成 API 文档 → 生成变更日志 → 输出统一站点。
doc-pipeline/
├── run-pipeline.sh # 主流水线脚本
├── agents/
│ ├── architect.sh # 架构分析Agent
│ ├── api-docs.sh # API文档Agent
│ ├── changelog.sh # 变更日志Agent
│ └── qa-review.sh # QA审查Agent
├── templates/
│ └── site-template.html # 输出模板
└── output/ # 生成结果
#!/bin/bash
# run-pipeline.sh — 文档生成主流水线
set -euo pipefail
PROJECT_DIR="${1:-.}"
OUTPUT_DIR="./output"
LOG_DIR="./logs"
mkdir -p "$OUTPUT_DIR" "$LOG_DIR"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
LOG_FILE="$LOG_DIR/pipeline-${TIMESTAMP}.log"
log() { echo "[$(date '+%H:%M:%S')] $*" | tee -a "$LOG_FILE"; }
# ============================================
# 阶段 1：架构分析
# ============================================
log "📋 阶段1/4：架构分析"
ARCH=$(claude -p \
--cwd "$PROJECT_DIR" \
--output-format json \
--max-turns 8 \
--allowedTools "Read,Glob,Grep" \
"分析这个项目的完整架构。输出 JSON 格式：
{
\"modules\": [{\"name\": \"模块名\", \"path\": \"路径\", \"description\": \"描述\", \"dependencies\": [\"依赖模块\"]}],
\"entry_points\": [\"入口文件\"],
\"tech_stack\": [\"技术栈\"],
\"data_flow\": \"数据流描述\"
}")
echo "$ARCH" | jq -r '.result' > "$OUTPUT_DIR/architecture.json"
log " ✅ 架构分析完成"
# ============================================
# 阶段 2：API 文档生成
# ============================================
log "📝 阶段2/4：API文档生成"
claude -p \
--cwd "$PROJECT_DIR" \
--output-format text \
--max-turns 10 \
--allowedTools "Read,Glob,Grep" \
"基于架构分析生成完整的API文档。每个API包含：端点、方法、参数、返回值、示例、错误码。
架构参考：$(cat "$OUTPUT_DIR/architecture.json")" \
> "$OUTPUT_DIR/api-docs.md"
log " ✅ API文档完成"
# ============================================
# 阶段 3：变更日志生成
# ============================================
log "📜 阶段3/4：变更日志"
CHANGELOG=$(claude -p \
--cwd "$PROJECT_DIR" \
--output-format text \
--max-turns 5 \
--allowedTools "Read,Bash(git*)" \
"分析 git 历史（最近30天），生成变更日志：
- 按日期分组
- 按类型分类（feature/fix/refactor/docs）
- 每条变更包含简短描述和相关commit hash")
echo "$CHANGELOG" > "$OUTPUT_DIR/changelog.md"
log " ✅ 变更日志完成"
# ============================================
# 阶段 4：QA 审查
# ============================================
log "🔍 阶段4/4：QA审查"
QA_RESULT=$(claude -p \
--output-format json \
--max-turns 3 \
--allowedTools "Read" \
"审查以下三份文档的质量和一致性：
架构文档: $(cat "$OUTPUT_DIR/architecture.json")
API文档: $(head -100 "$OUTPUT_DIR/api-docs.md")
变更日志: $(head -50 "$OUTPUT_DIR/changelog.md")
返回 JSON: {\"score\": 0-100, \"issues\": [...], \"suggestions\": [...]}")
SCORE=$(echo "$QA_RESULT" | jq -r '.result' | jq -r '.score')
log " ✅ QA评分: $SCORE/100"
# ============================================
# 汇总报告
# ============================================
log ""
log "═══════════════════════════════════"
log "📊 流水线完成"
log " 架构分析: $OUTPUT_DIR/architecture.json"
log " API文档: $OUTPUT_DIR/api-docs.md"
log " 变更日志: $OUTPUT_DIR/changelog.md"
log " QA评分: $SCORE/100"
log " 日志: $LOG_FILE"
log "═══════════════════════════════════"
flowchart TB
subgraph "输入层"
A1[源代码仓库]
A2[Git 历史]
A3[架构元数据]
end
subgraph "Agent 层（并行/串行）"
B1["🔍 架构分析 Agent<br/>claude -p --max-turns 8"]
B2["📝 API文档 Agent<br/>claude -p --max-turns 10"]
B3["📜 变更日志 Agent<br/>claude -p --max-turns 5"]
B4["🔍 QA审查 Agent<br/>claude -p --max-turns 3"]
end
subgraph "输出层"
C1[architecture.json]
C2[api-docs.md]
C3[changelog.md]
C4[qa-score.json]
end
A1 --> B1
A1 --> B2
A2 --> B3
B1 --> A3
A3 --> B2
C1 --> B4
C2 --> B4
C3 --> B4
B1 --> C1
B2 --> C2
B3 --> C3
B4 --> C4
style B1 fill:#e1f5fe
style B2 fill:#e8f5e9
style B3 fill:#fff3e0
style B4 fill:#fce4ec
--no-stream 与超时控制# 等待完整响应再输出（适合短任务）
claude -p --no-stream "快速回答：Python的GIL是什么"
# 配合 timeout 命令防止卡死
timeout 300 claude -p --max-turns 10 \
--output-format json \
"执行复杂重构任务" || echo "⚠️ 超时退出"
# 指定 session ID 续接上次对话
claude -p --session-id "sess_abc123" "继续上次的重构"
# 从上次的 JSON 结果中提取 session_id
SESSION=$(claude -p --output-format stream-json --verbose "分析项目" | \
jq -r 'select(.type == "system") | .session_id')
echo "会话ID: $SESSION"
# 用同一个 session 做后续操作
claude -p --session-id "$SESSION" "基于刚才的分析生成报告"
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 权限挂起超时 | -p 模式下遇到未授权工具 |
添加 --allowedTools 或 --dangerously-skip-permissions |
| 输出截断 | --max-turns 限制 |
增加 --max-turns 值（建议 ≤ 30） |
| JSON 解析失败 | 输出包含 Markdown 包裹 | 使用 stream-json 格式后用 jq 过滤 |
| 多实例冲突 | 并行写入同一文件 | 每个实例操作不同文件，最后合并 |
| 成本失控 | 长时间运行无监控 | 结合 stream-json 实时监控 cost_usd |
| CI 中认证失败 | API Key 未配置 | 使用 ANTHROPIC_API_KEY 环境变量 |
#!/bin/bash
# cost-optimizer.sh — 带成本控制的批量处理
MAX_COST_USD=1.00 # 单次任务最大成本
TOTAL_COST=0
process_file() {
local file=$1
local result
result=$(claude -p \
--output-format stream-json \
--verbose \
--max-turns 3 \
"为 $file 生成单元测试")
# 提取本次成本
local cost=$(echo "$result" | jq -r 'select(.type == "result") | .cost_usd' | head -1)
# 累加并检查
TOTAL_COST=$(echo "$TOTAL_COST + $cost" | bc)
echo "💰 本次: \$$cost | 累计: \$$TOTAL_COST"
# 超预算则停止
if (( $(echo "$TOTAL_COST >= $MAX_COST_USD" | bc -l) )); then
echo "⚠️ 已达预算上限 \$$MAX_COST_USD，停止处理"
exit 0
fi
}
for file in src/*.ts; do
process_file "$file"
done
/batch 命令的系统化教程| 训练营类型 | 适用性 | 预计教学时长 | 备注 |
|---|---|---|---|
| AI 开发工具训练营 | ⭐⭐⭐⭐⭐ | 4-6 小时 | 核心内容，完整实验 |
| DevOps 自动化训练营 | ⭐⭐⭐⭐ | 3-4 小时 | 侧重 CI/CD 集成章节 |
| 企业 AI 落地工作坊 | ⭐⭐⭐ | 2-3 小时 | 侧重流水线和成本控制 |
| 前端工程化训练营 | ⭐⭐⭐ | 2-3 小时 | 侧重批量迁移和管道 |
[!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 等场景全覆盖。