Headless模式与CI/CD集成2
6 流式输出：实时监控长耗时任务
点击查看代码
claude -p "分析整个src/目录的架构问题" \
--output-format stream-json \
--allowedTools "Read,Grep,Glob" | while read -r line; do
TYPE=$(echo "$line" | jq -r '.type // ""')
case "$TYPE" in
"system")
# 初始化阶段：输出模型信息
echo "[INIT] 模型: $(echo "$line" | jq -r '.model // "unknown"')"
;;
"assistant")
# 提取并输出 Claude 生成的文本内容
TEXT=$(echo "$line" | jq -r '.message.content[0].text // ""')
[ -n "$TEXT" ] && echo "[CLAUDE] $TEXT"
;;
"result")
# 任务结束：输出总轮数与费用
COST=$(echo "$line" | jq -r '.total_cost_usd // 0')
TURNS=$(echo "$line" | jq -r '.num_turns // 0')
echo "[DONE] 任务完成！共 $TURNS 轮，费用: \$$COST"
;;
esac
done
- stream_event（需要添加--include-partial-messages参数）：提供Claude输出的增量数据，精确到每一个Token级别的文本片段。
- system/compact_boundary：上下文压缩边界事件。
7 会话管理：跨步骤维持上下文
- 在Headless模式下，系统默认不持久化会话状态——每次调用均视为独立的全新上下文。然而，在涉及多轮交互的复杂场景中，往往需要在多次调用之间保持上下文的连续性。请看以下代码示例。
点击查看代码
# 第一步：执行初始分析
# 调用 Claude 分析代码结构，并捕获完整的 JSON 输出
RESULT=$(claude -p "分析 src/ 的模块依赖关系" \
--output-format json \
--allowedTools "Read,Grep,Glob")
# 第二步：提取会话标识符
# 从返回结果中解析 session_id，用于后续恢复会话
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')
# 第三步：基于上下文继续对话
# 使用 --resume 参数载入上一轮的会话状态，实现连续推理
claude -p "基于刚才的分析，指出循环依赖问题" \
--resume "$SESSION_ID" \
--output-format text
- CLI工具还提供了一系列高级参数以应对复杂的交互场景。请看以下代码示例。
8 CI 环境配置：生产级清单
8.1 必须设置的环境变量
点击查看代码
# 认证
ANTHROPIC_API_KEY=sk-ant-... # API密钥
# 功能禁用
# 方案一：使用聚合变量（推荐，可一次性禁用多项非必要功能）
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 # 禁用自动更新、遥测及错误上报
# 方案二：分别禁用（如需更细粒度的控制）
DISABLE_AUTOUPDATER=1 # 禁用自动更新（CI环境中必需）
DISABLE_TELEMETRY=1 # 禁用遥测
DISABLE_ERROR_REPORTING=1 # 禁用错误上报
8.2 性能调优参数
点击查看代码
# 超时控制
# Bash 命令默认超时时间（单位：毫秒）
BASH_DEFAULT_TIMEOUT_MS=120000 # 对应2min
# Bash 命令最大允许超时时间（单位：毫秒）
BASH_MAX_TIMEOUT_MS=600000 # 对应10min
# 输出控制
CLAUDE_CODE_MAX_OUTPUT_TOKENS=32000 # 模型单次响应最大Token数（默认值32 000，上限64 000）
MAX_MCP_OUTPUT_TOKENS=25000 # MCP工具响应最大Token数
#上下文管理
CLAUDE_CODE_AUTOCOMPACT_PCT_OVERRIDE=50 # 自动压缩触发阈值（取值范围1~100，代表上下文使用百分比；默认值50%）
8.3 GitHub Actions中的完整配置模板
点击查看代码
- name: Run Claude Analysis
env:
# 认证密钥（从仓库 Secrets 中获取）
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
# 性能与环境控制
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" # 禁用非必要后台流量
BASH_DEFAULT_TIMEOUT_MS: "300000" # Bash 命令默认超时：5 min
run: |
npx @anthropic-ai/claude-code -p "$PROMPT" \
--output-format json \
--max-turns 10 \
--max-budget-usd 1.00 \
--allowedTools "Read,Grep,Glob" \
--model claude-sonnet-4-6 \
--fallback-model haiku \
--append-system-prompt "遵循项目根目录 CLAUDE.md 中的审查规范。"
8.4 MCP服务器在CI中的配置
点击查看代码
npx @anthropic-ai/claude-code \
-p "分析数据库Schema的优化空间" \
--mcp-config ./ci-mcpconfig.json \
--strict-mcp-access \
--allowedTools "Read,Grep,Glob,mcp__database__query" \
--max-turns 10
9 跨平台CI/CD集成（没有的自查，这个可能存在差异）
9.1 GitLab CI/CD配置
9.2 JenkinsPipeline集成配置
9.3 本地自动化脚本
点击查看代码
#!/bin/bash
# review.sh — 团队共享的本地代码审查脚本
set -e
TARGET=${1:-.}
# 前置检查
[ -z "$ANTHROPIC_API_KEY" ] && echo "Error: ANTHROPIC_API_KEY not set" && exit 1
command -v claude &> /dev/null || { echo "Error: Claude Code not installed"; exit 1; }
echo "Starting review for: $TARGET"
# 构建文件列表
if [ -d "$TARGET" ]; then
FILES=$(find "$TARGET" -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" \) | head -20)
else
FILES="$TARGET"
fi
# 运行审查
RESULT=$(claude -p "审查以下文件的代码质量和安全问题：
$FILES
输出格式：使用Markdown格式，每个问题必须指明文件名和行号。" \
--output-format text \
--max-turns 15 \
--max-budget-usd 0.50 \
--allowedTools "Read,Grep,Glob")
# 保存报告
REPORT="review-$(date +%Y%m%d-%H%M%S).md"
echo -e "# Code Review Report\n\n**Date**: $(date)\n**Target**: $TARGET\n\n---\n\n$RESULT" > "$REPORT"
echo "Report saved: $REPORT"
10 安全原则与最佳实践
- 机密泄露
- 破坏性操作
- 费用失控
- 内容污染
10.1 最小权限原则
点击查看代码
# 代码审查任务：只读
--allowedTools "Read,Grep,Glob"
# 格式修复任务：读写
--allowedTools "Read,Grep,Glob,Edit,Write"
# Git操作任务：细粒度Bash白名单
--allowedTools "Read,Grep,Glob,Bash(git diff ),Bash(git log )"
10.2 Secrets管理
点击查看代码
# 错误做法：硬编码密钥（密钥将直接明文出现在 Actions 运行日志中）
env:
ANTHROPIC_API_KEY: "sk-ant-xxx"
# 正确做法：引用仓库密钥
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
10.3 容器隔离
点击查看代码
jobs:
review: runs-on: ubuntu-latest container: image: node:20
options: --read-only --tmpfs /tmp --network none
10.4 成本防护
点击查看代码
# 路径过滤：仅在 src 目录变更时触发
on:
pull_request:
paths:
- 'src/**'
- '!src/**/*.test.*' # 排除测试文件
# 并发限制：同一 PR 仅保留最新一次运行，自动取消中间版本
concurrency:
group: claude-${{ github.event.pull_request.number }}
cancel-in-progress: true
10.5 审计日志
点击查看代码
# JSON输出格式天然包含完整的审计信息
claude -p "任务" --output-format json | tee -a varlog/claude-audit.jsonl
11 从CLI到Agent SDK：Headless模式的编程接口
- TypeScript Agent
点击查看代码
// TypeScript Agent SDK 示例
import { query } from "@anthropic-ai/claude-agent-sdk";
// 假设 reviewSchema 已在外部定义
// const reviewSchema = { ... };
async function reviewPR(changedFiles: string[]) {
let sessionId: string | undefined;
let result: string = "";
for await (const message of query({
prompt: `审查以下文件的代码变更：${changedFiles.join(", ")}`,
options: {
allowedTools: ["Read", "Grep", "Glob"],
maxTurns: 10,
maxBudgetUsd: 0.50,
model: "claude-sonnet-4-6",
outputFormat: {
type: "json_schema",
schema: reviewSchema,
},
},
})) {
if (message.type === "system" && message.subtype === "init") {
sessionId = message.session_id;
}
if (message.type === "result" && message.structured_output) {
result = message.structured_output;
}
}
return { sessionId, result };
}
- Python Agent SDK
点击查看代码
# Python Agent SDK 示例
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def review_pr(changed_files: list[str]):
options = ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob"],
max_turns=10,
max_budget_usd=0.50,
model="claude-sonnet-4-6",
)
async for message in query(
prompt=f"审查以下文件：{', '.join(changed_files)}",
options=options,
):
if isinstance(message, ResultMessage):
return message.result
12 渐进式落地策略
- 阶段一：观察者模式。
- 阶段二：顾问模式。
- 阶段三：门禁模式。
- 阶段四：主动修复模式。
本章小结
- -p（入口）：将Claude Code的运行模式从交互式会话切换为非交互式执行，奠定自动化基础。
- --output-format（数据接口）：规范输出结构，确保下游系统能高效解析与调用审查结果。
- --allowedTools（安全边界）：严格限定工具权限，确保自动化环境中的操作合规、可控。
- --max-turns与--max-budget-usd（成本护栏）：设定执行轮次与预算上限，防止无人值守场景下的资源失控。
浙公网安备 33010602011771号