本教程面向已掌握Claude Code基础操作的开发者,深入讲解三大自动化武器:Headless模式(-p)、Hooks系统、批量任务编排。学完后你将能构建完整的自动化工作流——从CI/CD代码审查到批量重构、从安全防护到通知推送,让Claude Code从"对话助手"进化为"自动化引擎"。
适用人群:有Claude Code使用经验的开发者、DevOps工程师、需要大规模代码改造的技术负责人。
学习目标:
- 掌握 -p 模式的所有参数与输出格式
- 独立配置Hooks的6种事件类型和Matcher模式
- 构建多步骤、可编排的批量自动化流水线
| 条件 | 说明 |
|---|---|
| Claude Code CLI | 已安装并完成认证(claude 命令可用) |
| 终端基础 | 熟悉 Bash/Zsh 管道、重定向、退出码 |
| API Key | ANTHROPIC_API_KEY 环境变量已配置 |
| 项目目录 | 一个有实际代码的 Git 仓库用于练习 |
Headless模式是Claude Code的非交互执行模式。当你使用 -p(或 --print)标志时,Claude Code不再启动交互式REPL,而是接受一条Prompt,执行后直接输出结果到stdout。
flowchart LR
A["用户输入<br/>claude -p 'prompt'"] --> B["Headless模式<br/>非交互执行"]
B --> C{"输出格式"}
C -->|"--output-format text"| D["纯文本到stdout"]
C -->|"--output-format json"| E["JSON结构体"]
C -->|"--output-format stream-json"| F["NDJSON事件流"]
D --> G["管道到其他命令"]
E --> H["程序化解析"]
F --> I["实时流式处理"]
最简形式——一行命令获得回答:
claude -p "解释这个函数的作用:$(cat src/utils/parse.ts)"
管道输入——把文件内容"喂"给Claude:
cat error.log | claude -p "分析这些错误日志,找出根本原因"
输出重定向——结果写入文件:
claude -p "为 src/api/ 下所有接口生成TypeScript类型定义" > types.generated.ts
| 参数 | 作用 | 示例 |
|---|---|---|
-p / --print |
启用非交互模式 | claude -p "prompt" |
--output-format |
输出格式:text/json/stream-json |
--output-format json |
--max-turns |
限制Agent最大执行轮数 | --max-turns 5 |
--allowedTools |
限制可用工具列表 | --allowedTools "Read,Glob,Grep" |
--model |
指定使用的模型 | --model claude-sonnet-4-6 |
--system-prompt |
自定义系统提示 | --system-prompt "你是一个代码审查专家" |
--input-format |
输入格式:text/stream-json |
--input-format stream-json |
--resume |
恢复之前的会话 | --resume <session-id> |
--append-system-prompt |
追加系统提示(不覆盖默认) | --append-system-prompt "项目使用React 19" |
格式一:text(默认)
纯文本输出,适合人类阅读和简单管道:
claude -p "列出package.json中过时的依赖" --output-format text
# 输出:直接的文字回答
格式二:json
返回结构化JSON,包含完整会话信息:
claude -p "这段代码有什么问题?" --output-format json
输出结构(简化):
{
"result": "代码中存在以下问题...",
"session_id": "abc-123-def",
"cost_usd": 0.034,
"duration_ms": 4500,
"num_turns": 3,
"is_error": false
}
格式三:stream-json
实时NDJSON(Newline Delimited JSON)事件流——这是自动化的核心:
claude -p "重构auth模块" --output-format stream-json --verbose
每行是一个JSON事件,关键事件类型包括:
{"type":"system","subtype":"init","session_id":"...","tools":[...]}
{"type":"assistant","subtype":"text","content":"我来分析auth模块..."}
{"type":"tool_use","name":"Read","input":{"file_path":"src/auth/index.ts"}}
{"type":"tool_result","name":"Read","output":"文件内容..."}
{"type":"result","result":"重构完成...","cost_usd":0.12,"duration_ms":12000}
通过 --input-format stream-json 可以实现多轮对话式自动化:
cat <<'EOF' | claude -p --input-format stream-json --output-format stream-json
{"type":"user","content":"分析src/api目录下的代码结构"}
{"type":"user","content":"为每个接口生成对应的单元测试"}
{"type":"user","content":"运行测试并报告结果"}
EOF
每条JSON消息代表一个用户轮次,Claude会按顺序处理所有轮次。
在自动化场景中,限制Claude的工具权限是关键安全措施:
# 只读审查——不允许修改任何文件
claude -p "审查这个PR的安全问题" \
--allowedTools "Read,Glob,Grep,Bash" \
--max-turns 10
# 纯分析模式——只能读取和搜索
claude -p "生成项目架构文档" \
--allowedTools "Read,Glob,Grep"
可用工具名列表:Read、Write、Edit、Bash、Glob、Grep、Task、WebSearch、TodoWrite、NotebookEdit 等。
Hooks是Claude Code的事件驱动机制,允许你在特定时机注入自定义逻辑——无论是安全防护、自动格式化、还是通知推送。
flowchart TB
subgraph "Hook事件生命周期"
A["SessionStart"] --> B["UserPromptSubmit"]
B --> C["PreToolUse"]
C --> D["工具执行"]
D --> E["PostToolUse"]
E --> F["继续Agent循环"]
F --> C
F --> G["Stop"]
G --> H["Notification"]
end
subgraph "Hook处理器类型"
I["command<br/>Shell命令"]
J["http<br/>HTTP请求"]
K["prompt<br/>LLM判断"]
end
C -.-> I
C -.-> J
C -.-> K
E -.-> I
E -.-> J
| 事件 | 触发时机 | 典型用途 |
|---|---|---|
PreToolUse |
工具执行之前 | 拦截危险操作、输入校验、权限控制 |
PostToolUse |
工具执行之后 | 自动格式化、日志审计、触发通知 |
Notification |
Agent发出通知时 | 发送到Slack/Discord、桌面通知 |
Stop |
Agent会话结束时 | 执行清理、生成报告、记录指标 |
SubagentStop |
子Agent结束时 | 聚合子Agent结果、资源清理 |
SessionStart |
会话启动时 | 注入上下文、环境检测、加载配置 |
Hooks可以在三个层级配置,优先级从低到高:
~/.claude/settings.json # 全局配置(所有项目)
├── .claude/settings.json # 项目级配置(团队共享)
└── .claude/settings.local.json # 本地配置(个人偏好,不提交到Git)
完整的Hooks配置结构:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "your-script.sh"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $CLAUDE_FILE_PATH"
}
]
}
],
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "send-slack-notification.sh"
}
]
}
]
}
}
关键字段说明:
matcher:正则表达式,匹配工具名。PreToolUse 和 PostToolUse 专用,省略则匹配所有工具hooks[].type:处理器类型,支持 command、http、prompthooks[].command:要执行的Shell命令输入——Hook通过stdin接收JSON数据:
{
"session_id": "sess_abc123",
"tool_name": "Bash",
"tool_input": {
"command": "rm -rf node_modules",
"description": "删除node_modules"
}
}
输出——通过stdout返回JSON,退出码决定行为:
| 退出码 | 含义 | 效果 |
|---|---|---|
0 |
通过 | 继续执行(可返回额外信息) |
2 |
阻止 | 阻止工具执行,向Agent显示原因 |
阻止执行的示例脚本:
#!/bin/bash
# block-dangerous-commands.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
if echo "$COMMAND" | grep -qE 'rm\s+-rf\s+/|drop\s+table|DROP\s+TABLE'; then
echo '{"decision":"block","reason":"禁止执行危险操作:'$COMMAND'"}'
exit 2
fi
exit 0
配置一:自动代码格式化(PostToolUse)
每次文件写入后自动格式化:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "bash -c 'FILE=$(cat | jq -r .tool_input.file_path); ext=${FILE##*.}; case $ext in ts|tsx|js|jsx) npx prettier --write \"$FILE\" ;; py) black \"$FILE\" ;; go) gofmt -w \"$FILE\" ;; esac'"
}
]
}
]
}
}
配置二:保护敏感文件(PreToolUse)
阻止修改.env等敏感文件:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); if echo \"$FILE\" | grep -qE \"\\.env|credentials|secret|\\.pem\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"禁止修改敏感文件: $FILE\\\"}\"; exit 2; fi; exit 0'"
}
]
}
]
}
}
配置三:Slack通知(Notification)
Agent任务完成时发送通知:
{
"hooks": {
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "bash -c 'MSG=$(cat | jq -r .message); curl -s -X POST \"$SLACK_WEBHOOK_URL\" -H \"Content-Type: application/json\" -d \"{\\\"text\\\":\\\"🤖 Claude Code: $MSG\\\"}\"'"
}
]
}
]
}
}
配置四:Bash命令安全审计(PreToolUse)
记录并审查所有Shell命令执行:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash -c 'INPUT=$(cat); CMD=$(echo $INPUT | jq -r .tool_input.command); echo \"[$(date -Iseconds)] CMD: $CMD\" >> ~/.claude/bash-audit.log; if echo \"$CMD\" | grep -qE \"curl.*\\|.*sh|wget.*\\|.*bash\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"禁止管道到Shell执行\\\"}\"; exit 2; fi; exit 0'"
}
]
}
]
}
}
配置五:测试自动运行(PostToolUse)
源码修改后自动运行相关测试:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "bash -c 'FILE=$(cat | jq -r .tool_input.file_path); if [[ \"$FILE\" == src/**/*.ts ]] && [[ \"$FILE\" != *.test.ts ]]; then TEST_FILE=\"${FILE%.ts}.test.ts\"; if [ -f \"$TEST_FILE\" ]; then npx vitest run \"$TEST_FILE\" 2>&1 | tail -5; fi; fi; exit 0'"
}
]
}
]
}
}
配置六:会话启动环境检测(SessionStart)
每次会话开始时注入项目上下文:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "bash -c 'echo \"项目: $(basename $(pwd)) | 分支: $(git branch --show-current 2>/dev/null || echo N/A) | 最后提交: $(git log -1 --oneline 2>/dev/null || echo N/A)\"'"
}
]
}
]
}
}
matcher 字段使用正则表达式匹配工具名:
Bash # 精确匹配Bash工具
Write|Edit # 匹配Write或Edit
.* # 匹配所有工具
Read|Glob|Grep # 匹配所有只读工具
常见工具名列表:
| 工具名 | 类别 |
|---|---|
Read |
文件读取 |
Write |
文件创建 |
Edit |
文件编辑 |
Bash |
Shell命令 |
Glob |
文件搜索 |
Grep |
内容搜索 |
Task |
子Agent |
TodoWrite |
任务管理 |
WebSearch |
网络搜索 |
验证Hook是否加载:
在Claude Code交互模式中使用 /hooks 命令查看当前已加载的所有Hooks。
调试Hook脚本:
# 手动测试Hook脚本
echo '{"session_id":"test","tool_name":"Bash","tool_input":{"command":"ls -la"}}' | bash your-hook-script.sh
echo "Exit code: $?"
查看Hook执行日志:
Hooks的标准错误输出会显示在Claude Code的调试信息中。启动时加上 --verbose 可以看到完整的Hook执行过程。
flowchart TB
subgraph "模式一:Shell循环"
A1["for file in *.ts"] --> A2["claude -p 处理单个文件"]
A2 --> A3["下一个文件"]
end
subgraph "模式二:并行进程"
B1["文件列表"] --> B2["xargs -P 并行"]
B2 --> B3["多个claude -p同时执行"]
end
subgraph "模式三:/batch命令"
C1["交互式输入"] --> C2["/batch"]
C2 --> C3["自动并行spawn"]
end
| 模式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| Shell循环 | 简单、可控、顺序执行 | 速度慢 | 有依赖关系的任务 |
| 并行进程 | 快速、可控制并发数 | 需处理资源竞争 | 独立的大批量任务 |
| /batch命令 | 智能调度、内置并行 | 仅交互模式可用 | 代码库大规模改造 |
适合有依赖关系的多步任务:
#!/bin/bash
# migrate-api-endpoints.sh — 顺序迁移API端点
APIS=("users" "products" "orders" "payments" "notifications")
for api in "${APIS[@]}"; do
echo "=== 迁移 $api API ==="
claude -p "将 src/api/$api.ts 从Express风格迁移到Fastify风格。保持所有接口签名不变,只修改框架相关代码。" \
--output-format text \
--max-turns 15 \
--allowedTools "Read,Write,Edit,Bash,Glob,Grep"
echo "=== 运行 $api 测试 ==="
npx vitest run "src/api/$api.test.ts"
if [ $? -ne 0 ]; then
echo "❌ $api 测试失败,停止迁移"
exit 1
fi
echo "✅ $api 迁移完成"
done
echo "🎉 所有API迁移完成"
适合独立的、无依赖关系的任务:
#!/bin/bash
# batch-add-tests.sh — 并行为所有模块生成测试
MAX_PARALLEL=4 # 控制并发数
generate_test() {
local file=$1
local test_file="${file%.ts}.test.ts"
if [ -f "$test_file" ]; then
echo "跳过 $file(测试已存在)"
return
fi
echo "为 $file 生成测试..."
claude -p "为以下文件生成完整的单元测试:$file。使用vitest框架,覆盖所有导出函数,包含正常路径和边界情况。" \
--output-format text \
--max-turns 10 \
--allowedTools "Read,Write,Glob,Grep" \
> "$test_file"
echo "✅ $test_file 已生成"
}
export -f generate_test
# 查找所有源文件并并行处理
find src -name "*.ts" ! -name "*.test.ts" ! -name "*.d.ts" | \
xargs -P $MAX_PARALLEL -I {} bash -c 'generate_test "$@"' _ {}
echo "🎉 批量测试生成完成"
/batch 是Claude Code v2.1.63引入的内置命令,在交互模式下使用,能自动并行spawn子Agent处理多个文件:
使用方式:
> /batch 将所有 src/components/ 下的组件从 Class 组件迁移为函数组件
/batch的工作机制:
/batch适用场景: - 大规模重命名/迁移(如替换API、更新import路径) - 批量添加JSDoc注释 - 批量修改代码风格(如从Options API改Composition API) - 批量添加错误处理
将Headless模式、Hooks和批量执行组合成完整的自动化Pipeline:
flowchart TB
A["Git Push触发"] --> B["PreToolUse Hook<br/>环境检查"]
B --> C["Step 1: claude -p<br/>代码审查"]
C --> D["PostToolUse Hook<br/>记录审查结果"]
D --> E["Step 2: claude -p<br/>自动修复"]
E --> F["PostToolUse Hook<br/>自动格式化+测试"]
F --> G["Step 3: claude -p<br/>生成变更摘要"]
G --> H["Notification Hook<br/>发送Slack通知"]
H --> I["Stop Hook<br/>生成最终报告"]
完整的Pipeline脚本:
#!/bin/bash
# auto-code-review-pipeline.sh — 全自动代码审查Pipeline
set -euo pipefail
BRANCH=$(git branch --show-current)
DIFF=$(git diff main...HEAD --stat)
SESSION_ID=""
echo "🚀 启动代码审查Pipeline — 分支: $BRANCH"
echo "📊 变更文件统计:"
echo "$DIFF"
# Step 1: 安全审查
echo ""
echo "=== Step 1/3: 安全审查 ==="
SECURITY_REPORT=$(claude -p "审查以下Git diff中的安全隐患(SQL注入、XSS、硬编码密钥、不安全的依赖)。只报告确定的漏洞,不要误报。输出JSON格式:{\"issues\": [{\"file\": \"...\", \"line\": N, \"severity\": \"high|medium|low\", \"description\": \"...\"}]}
Diff:
$(git diff main...HEAD)" \
--output-format json \
--allowedTools "Read,Glob,Grep" \
--max-turns 8)
echo "$SECURITY_REPORT" | jq '.result' 2>/dev/null || echo "$SECURITY_REPORT"
# Step 2: 代码质量改进建议
echo ""
echo "=== Step 2/3: 质量审查 ==="
QUALITY_REPORT=$(claude -p "审查以下Git diff的代码质量。关注:1)性能问题 2)可维护性 3)测试覆盖率 4)错误处理。输出简洁的改进建议列表。
Diff:
$(git diff main...HEAD)" \
--output-format text \
--allowedTools "Read,Glob,Grep,Bash" \
--max-turns 10)
echo "$QUALITY_REPORT"
# Step 3: 生成PR摘要
echo ""
echo "=== Step 3/3: 生成变更摘要 ==="
SUMMARY=$(claude -p "为以下代码变更生成一个简洁的PR描述,包括:1)主要变更内容(3-5个要点)2)影响范围 3)建议的测试重点
Diff stat:
$(git diff main...HEAD --stat)
最近的Commits:
$(git log main..HEAD --oneline)" \
--output-format text \
--allowedTools "Read,Glob,Grep" \
--max-turns 5)
echo "$SUMMARY"
# 输出最终报告
echo ""
echo "========================================="
echo "📋 审查报告已生成"
echo "========================================="
GitHub Actions集成示例:
name: AI Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
ai-review:
runs-on: ubuntu-latest
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: |
claude -p "你是高级代码审查员。审查这个PR的变更,重点关注:
1. 安全漏洞(OWASP Top 10)
2. 性能退化
3. 逻辑错误
4. 测试覆盖是否充分
只报告确定的、可操作的问题。不要报告风格偏好。
变更内容:
$(git diff origin/main...HEAD)" \
--output-format text \
--allowedTools "Read,Glob,Grep,Bash" \
--max-turns 15 \
> review_output.md
- name: Post Review Comment
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh pr comment ${{ github.event.pull_request.number }} \
--body-file review_output.md
Git Pre-commit Hook集成:
#!/bin/bash
# .git/hooks/pre-commit — 提交前自动审查
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx|py)$')
if [ -z "$STAGED_FILES" ]; then
exit 0
fi
echo "🔍 AI审查暂存文件..."
REVIEW=$(claude -p "快速审查以下文件的代码质量,只报告严重问题。如果代码质量可接受,输出PASS。
文件列表:
$STAGED_FILES
具体内容:
$(git diff --cached)" \
--output-format text \
--max-turns 5 \
--allowedTools "Read,Glob,Grep")
echo "$REVIEW"
if echo "$REVIEW" | grep -q "BLOCK"; then
echo "❌ 代码审查未通过,请修复上述问题后重新提交"
exit 1
fi
echo "✅ 代码审查通过"
exit 0
对于特别大的任务(如全项目迁移),可以采用RALF(Read-Analyze-Loop-Fix)循环模式,将多个Claude Code会话串联起来:
#!/bin/bash
# ralf-loop-migration.sh — RALF循环模式
TARGET_FILES=($(find src -name "*.vue" -type f))
MAX_ITERATIONS=5
PASS=0
while [ $PASS -lt $MAX_ITERATIONS ]; do
PASS=$((PASS + 1))
echo "=== 第 $PASS 轮 ==="
# Read & Analyze
ISSUES=$(claude -p "检查以下Vue组件是否已完全迁移到Vue 3 Composition API。列出仍使用Options API的组件。
文件列表:
$(printf '%s\n' "${TARGET_FILES[@]}")" \
--output-format text \
--allowedTools "Read,Glob,Grep" \
--max-turns 8)
if echo "$ISSUES" | grep -q "全部迁移完成\|没有遗留问题\|all migrated"; then
echo "🎉 迁移完成!共 $PASS 轮"
break
fi
echo "发现问题:"
echo "$ISSUES"
# Loop & Fix
claude -p "根据以下问题列表,修复所有未完成迁移的Vue组件。
问题:
$ISSUES" \
--output-format text \
--max-turns 20 \
--allowedTools "Read,Write,Edit,Glob,Grep,Bash"
# 运行测试验证
npx vitest run 2>&1 | tail -10
done
构建一个完整的自动化系统,当代码变更时自动:审查安全→运行测试→修复问题→更新文档→发送通知。
project/
├── .claude/
│ ├── settings.json # Hooks配置
│ └── settings.local.json # 本地配置
├── scripts/
│ └── auto-quality-guard.sh # 主Pipeline脚本
├── CLAUDE.md # Claude行为指引
└── .github/
└── workflows/
└── quality-guard.yml # CI/CD配置
.claude/settings.json——项目级Hooks:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); if echo \"$FILE\" | grep -qE \"\\.env|credentials|\\.pem|secret\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"安全策略:禁止修改敏感文件 $FILE\\\"}\"; exit 2; fi; exit 0'"
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash -c 'INPUT=$(cat); CMD=$(echo $INPUT | jq -r .tool_input.command); echo \"[$(date -Iseconds)] BASH: $CMD\" >> .claude/command-log.txt; if echo \"$CMD\" | grep -qE \"rm\\s+-rf\\s+/|DROP\\s+TABLE|truncate\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"危险命令被拦截: $CMD\\\"}\"; exit 2; fi; exit 0'"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); ext=${FILE##*.}; case $ext in ts|tsx|js|jsx) npx prettier --write \"$FILE\" 2>/dev/null; npx eslint --fix \"$FILE\" 2>/dev/null ;; py) black \"$FILE\" 2>/dev/null ;; esac; exit 0'"
}
]
}
],
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "bash -c 'MSG=$(cat | jq -r .message // .text // empty); if [ -n \"$MSG\" ] && [ -n \"$SLACK_WEBHOOK\" ]; then curl -s -X POST \"$SLACK_WEBHOOK\" -H \"Content-Type: application/json\" -d \"{\\\"text\\\":\\\"[Claude Code] $MSG\\\"}\" > /dev/null; fi; exit 0'"
}
]
}
],
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "bash -c 'echo \"项目: $(basename $(pwd)) | 分支: $(git branch --show-current 2>/dev/null || echo detached) | 最后提交: $(git log -1 --oneline 2>/dev/null || echo none) | Node: $(node -v 2>/dev/null || echo N/A)\"'"
}
]
}
]
}
}
scripts/auto-quality-guard.sh:
#!/bin/bash
set -euo pipefail
PROJECT_DIR=$(pwd)
REPORT_DIR="$PROJECT_DIR/.claude/reports"
mkdir -p "$REPORT_DIR"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
REPORT_FILE="$REPORT_DIR/quality-$TIMESTAMP.md"
echo "# 代码质量报告 - $(date +%Y-%m-%d\ %H:%M)" > "$REPORT_FILE"
echo "" >> "$REPORT_FILE"
# Step 1: 安全扫描
echo "## 1. 安全扫描" >> "$REPORT_FILE"
SEC_RESULT=$(claude -p "扫描项目中所有源文件的安全问题。重点检查:
- 硬编码的密钥或Token
- SQL注入风险
- XSS风险
- 不安全的依赖引用
- 敏感信息泄露
输出格式:按严重程度排序,每条包含文件路径、行号、问题描述。" \
--output-format text \
--allowedTools "Read,Glob,Grep" \
--max-turns 12)
echo "$SEC_RESULT" >> "$REPORT_FILE"
echo "" >> "$REPORT_FILE"
# Step 2: 代码质量分析
echo "## 2. 代码质量分析" >> "$REPORT_FILE"
QUALITY_RESULT=$(claude -p "分析项目代码质量,输出以下指标:
1. 重复代码比例较高的区域
2. 圈复杂度超过10的函数
3. 过长的函数(超过50行)
4. 缺少错误处理的异步函数
5. 潜在的性能瓶颈
给出具体的文件路径和行号。" \
--output-format text \
--allowedTools "Read,Glob,Grep,Bash" \
--max-turns 15)
echo "$QUALITY_RESULT" >> "$REPORT_FILE"
echo "" >> "$REPORT_FILE"
# Step 3: 测试覆盖率分析
echo "## 3. 测试覆盖分析" >> "$REPORT_FILE"
COV_RESULT=$(claude -p "分析项目的测试覆盖率。列出:
1. 没有对应测试的源文件
2. 测试中缺少的边界情况
3. 建议优先添加测试的模块(按风险排序)" \
--output-format text \
--allowedTools "Read,Glob,Grep" \
--max-turns 10)
echo "$COV_RESULT" >> "$REPORT_FILE"
# 输出报告位置
echo ""
echo "📊 质量报告已生成: $REPORT_FILE"
cat "$REPORT_FILE"
.github/workflows/quality-guard.yml:
name: AI Quality Guard
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
schedule:
- cron: '0 2 * * 1' # 每周一凌晨2点
jobs:
quality-scan:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: |
npm ci
npm install -g @anthropic-ai/claude-code
- name: Security Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
claude -p "审查这个仓库的安全状况。检查所有源代码文件中是否存在:硬编码密钥、SQL注入、XSS、不安全的反序列化、路径遍历。输出JSON格式报告。" \
--output-format json \
--allowedTools "Read,Glob,Grep" \
--max-turns 15 > security-report.json
- name: Quality Analysis
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
claude -p "分析代码库的整体质量。重点关注:代码复杂度、重复代码、错误处理、API设计。输出改进建议列表,按优先级排序。" \
--output-format text \
--allowedTools "Read,Glob,Grep,Bash" \
--max-turns 12 > quality-report.md
- name: Upload Reports
uses: actions/upload-artifact@v4
with:
name: quality-reports
path: |
security-report.json
quality-report.md
- name: Comment on PR
if: github.event_name == 'pull_request'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh pr comment ${{ github.event.pull_request.number }} \
--body-file quality-report.md
自动化场景容易产生大量API调用,需要严格控制:
# 限制最大轮数,防止Agent"跑飞"
claude -p "任务" --max-turns 5
# 使用更经济的模型处理简单任务
claude -p "格式化这个文件" --model claude-haiku-4-5
# 只读任务限制工具,减少不必要调用
claude -p "分析代码" --allowedTools "Read,Glob,Grep"
#!/bin/bash
# 带重试的Claude Code调用
call_claude_with_retry() {
local prompt="$1"
local max_retries=3
local attempt=1
while [ $attempt -le $max_retries ]; do
RESULT=$(claude -p "$prompt" --output-format json 2>&1)
EXIT_CODE=$?
if [ $EXIT_CODE -eq 0 ]; then
echo "$RESULT"
return 0
fi
echo "尝试 $attempt/$max_retries 失败,退出码: $EXIT_CODE" >&2
attempt=$((attempt + 1))
sleep 5
done
echo "所有重试失败" >&2
return 1
}
--resume对于复杂任务,可以保存会话ID并在后续继续:
# 第一次调用,获取session_id
RESULT=$(claude -p "分析项目架构" --output-format json)
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')
echo "Session ID: $SESSION_ID" > .claude/last-session
# 后续调用,继续同一会话
claude -p "基于刚才的分析,生成架构改进方案" \
--resume "$SESSION_ID" \
--output-format text
使用 jq 实时过滤stream-json输出:
claude -p "重构整个auth模块" \
--output-format stream-json \
--max-turns 20 \
| while read -r line; do
TYPE=$(echo "$line" | jq -r '.type // empty')
case "$TYPE" in
tool_use)
TOOL=$(echo "$line" | jq -r '.name')
echo "🔧 使用工具: $TOOL"
;;
tool_result)
echo "✅ 工具执行完成"
;;
result)
COST=$(echo "$line" | jq -r '.cost_usd')
DURATION=$(echo "$line" | jq -r '.duration_ms')
echo "💰 费用: \$$COST | ⏱ 耗时: ${DURATION}ms"
;;
esac
done
flowchart TB
subgraph "触发层"
T1["Git Push"]
T2["定时任务"]
T3["手动触发"]
T4["PR创建"]
end
subgraph "Hook拦截层"
H1["SessionStart<br/>环境检测"]
H2["PreToolUse<br/>安全防护"]
H3["PostToolUse<br/>自动格式化"]
H4["Notification<br/>消息推送"]
end
subgraph "执行层"
E1["claude -p<br/>代码审查"]
E2["claude -p<br/>自动修复"]
E3["claude -p<br/>测试生成"]
E4["claude -p<br/>文档更新"]
end
subgraph "输出层"
O1["JSON报告"]
O2["Git Commit"]
O3["PR评论"]
O4["Slack通知"]
end
T1 --> H1 --> E1
T4 --> E1
T2 --> E1
T3 --> E1
E1 --> E2 --> E3 --> E4
E1 --> H2
E2 --> H2
E2 --> H3
E4 --> H4
E1 --> O1
E2 --> O2
E1 --> O3
H4 --> O4
| 资源 | 说明 |
|---|---|
| Claude Code Headless模式官方文档 | 编程式使用Claude Code的权威参考 |
| Claude Code Hooks官方文档 | Hooks的完整Schema和事件参考 |
| Claude Code CLI Reference | 所有CLI标志和命令的完整列表 |
| Stream-JSON Protocol Reference | stream-json协议的详细事件类型文档 |
| Claude Code Hooks完整指南 | 20+个即用型Hooks配置示例 |
[!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 等场景全覆盖。
