<!-- title: Claude Code自动化实战全攻略 -->

# Claude Code Agent模式与自动化实战全攻略：从 `-p` 无头模式到多 Agent 编排

> **学习目标**：掌握 Claude Code 的三大自动化核心能力——无头（Headless）模式执行、Hooks 事件钩子系统、定时任务与多 Agent 并行编排。学完后，你将能够把 Claude Code 嵌入 CI/CD 流水线、构建安全合规的自动审批机制、实现代码库级别的批量迁移与审查。
>
> **适用人群**：已在日常开发中使用 Claude Code 的中高级开发者、DevOps 工程师、技术团队负责人。

---

## 一、前置条件

| 项目 | 要求 |
|------|------|
| Claude Code 版本 | ≥ v2.1.72（定时任务）、≥ v2.1.154（动态工作流） |
| 运行环境 | macOS / Linux / Windows (WSL2) |
| API 访问 | Anthropic API key 或 Amazon Bedrock / Google Vertex AI |
| 基础知识 | 熟悉 Claude Code 交互模式、了解 JSON 配置格式 |
| 检查版本命令 | `claude --version` |

```bash
# 确认版本
claude --version
# 预期输出: claude-code/2.1.xxx
```

---

## 二、自动化全景图：Claude Code 的四层自动化体系

在深入每个模块之前，先理解 Claude Code 自动化的整体架构。它由四个层次组成，从最简单的单命令执行到最复杂的多 Agent 编排，层层递进：

```mermaid
graph TB
    subgraph L1["第1层：无头模式"]
        H1["claude -p"]
        H2["stdin 管道"]
        H3["--output-format"]
    end

    subgraph L2["第2层：事件钩子"]
        K1["PreToolUse"]
        K2["PostToolUse"]
        K3["Stop / Notification"]
    end

    subgraph L3["第3层：定时与循环"]
        S1["/loop 固定间隔"]
        S2["/loop 动态间隔"]
        S3["CronCreate API"]
    end

    subgraph L4["第4层：多Agent编排"]
        A1["Subagents 子代理"]
        A2["Agent Teams 团队"]
        A3["Dynamic Workflows 工作流"]
    end

    L1 --> L2 --> L3 --> L4

    style L1 fill:#e8f5e9
    style L2 fill:#e3f2fd
    style L3 fill:#fff3e0
    style L4 fill:#fce4ec
```

| 层次 | 核心能力 | 典型场景 |
|------|---------|---------|
| 第1层 | 单次非交互执行 | CI 代码审查、批量文件处理 |
| 第2层 | 事件驱动拦截 | 安全防护、审计日志、自动格式化 |
| 第3层 | 定时重复执行 | 部署监控、PR 看护、日报生成 |
| 第4层 | 多Agent并行协作 | 代码库审计、500+文件迁移、交叉验证研究 |

---

## 三、第1层实战：无头模式（Headless Mode）

### 3.1 核心概念

无头模式让 Claude Code 在**非交互环境**下运行——不需要终端界面、不需要人类逐条确认。它是将 Claude Code 接入自动化流水线的基石。

### 3.2 基础用法

```bash
# 方式1：直接传入提示词
claude -p "为 src/auth.ts 中的 login 函数编写单元测试"

# 方式2：通过管道传入文件内容
cat src/auth.ts | claude -p "审查这段代码中的安全漏洞"

# 方式3：重定向文件输入
claude -p "总结这个模块的功能" < README.md

# 方式4：组合管道
echo "修复 main.py 中的类型错误" | claude -p
```

### 3.3 输出格式控制

在自动化场景中，结构化输出至关重要：

```bash
# JSON 格式输出，便于程序解析
claude -p "列出 package.json 中的所有依赖" \
  --output-format json

# 纯文本流式输出
claude -p "生成 CHANGELOG" \
  --output-format stream-json

# 仅输出文本内容（适合管道拼接）
claude -p "将以下错误日志分类" < error.log \
  --output-format text
```

### 3.4 CI/CD 集成实战

以 GitHub Actions 为例，展示一个完整的自动化代码审查工作流：

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

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  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 Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 获取变更文件列表
          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)

          # 让 Claude 审查变更
          claude -p "审查以下变更文件中的代码质量问题、安全漏洞和性能问题：
          变更文件：${CHANGED_FILES}

          请用以下格式输出：
          1. 🔴 严重问题
          2. 🟡 建议改进
          3. 🟢 良好实践
          " --output-format text > review_output.md

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review_output.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 Claude Code Review\n\n${review}`
            });
```

### 3.5 批量处理脚本

一个更实用的场景——批量处理项目中的所有 TODO 注释：

```bash
#!/bin/bash
# batch-todo.sh — 批量处理 TODO 注释

PROJECT_DIR="${1:-.}"
OUTPUT_DIR="./claude-reports"
mkdir -p "$OUTPUT_DIR"

# 查找所有包含 TODO 的文件
TODO_FILES=$(grep -rl "TODO\|FIXME\|HACK" "$PROJECT_DIR" \
  --include="*.ts" --include="*.py" --include="*.js" | head -20)

for file in $TODO_FILES; do
  filename=$(basename "$file")
  echo "正在处理: $file"

  # 用 Claude 分析每个文件的 TODO
  claude -p "分析以下文件中的所有 TODO/FIXME/HACK 注释。
  对于每个注释：
  1. 估算优先级（P0-P3）
  2. 建议修复方案
  3. 预估工作量（分钟）

  输出 JSON 格式。" < "$file" \
    --output-format json \
    > "${OUTPUT_DIR}/${filename}.todo.json"
done

echo "处理完成，报告保存在 ${OUTPUT_DIR}/"
```

### 3.6 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| `Error: No API key` | 环境变量未设置 | `export ANTHROPIC_API_KEY=sk-ant-...` |
| 输出截断 | 默认 token 限制 | 添加 `--max-tokens 4096` |
| 管道输入为空 | stdin 未正确传递 | 使用 `< file` 而非 `cat file \|` |
| 超时退出 | CI 环境超时设置 | `--timeout 300000`（毫秒） |

---

## 四、第2层实战：Hooks 事件钩子系统

### 4.1 Hooks 核心概念

Hooks 是 Claude Code 的**确定性自动化层**——它们在特定事件触发时执行你预定义的代码，不经过 AI 判断，完全可预测。与 CLAUDE.md（告诉 Claude "应该做什么"）不同，Hooks 告诉系统"必须做什么"。

```mermaid
sequenceDiagram
    participant U as 用户
    participant C as Claude Agent
    participant H as Hook 系统
    participant T as 工具

    U->>C: 发送指令
    C->>H: PreToolUse 事件
    H->>H: 执行匹配器过滤
    alt Hook 返回 deny
        H-->>C: 阻止执行
        C-->>U: 操作被拦截
    else Hook 返回 allow
        H-->>C: 允许执行
        C->>T: 执行工具
        T-->>C: 返回结果
        C->>H: PostToolUse 事件
        H->>H: 记录/转换结果
    end
```

### 4.2 可用事件类型

Claude Code 提供了丰富的事件钩子：

| 事件 | 触发时机 | 典型用途 |
|------|---------|---------|
| `PreToolUse` | 工具调用前 | 阻止危险操作、修改输入参数 |
| `PostToolUse` | 工具执行后 | 审计日志、自动格式化 |
| `PostToolUseFailure` | 工具执行失败 | 错误处理、告警 |
| `Stop` | Agent 停止时 | 保存状态、发送通知 |
| `Notification` | 状态变更消息 | 转发到 Slack/钉钉 |
| `SessionStart` | 会话开始 | 初始化日志、加载配置 |
| `SubagentStart` / `SubagentStop` | 子代理生命周期 | 跟踪并行任务 |
| `PreCompact` | 上下文压缩前 | 归档完整对话记录 |

### 4.3 配置位置

Hooks 在 `settings.json` 中配置，支持全局和项目两个层级：

```bash
# 全局配置
~/.claude/settings.json

# 项目配置
.claude/settings.json

# 项目本地配置（不提交到 Git）
.claude/settings.local.json
```

### 4.4 实战案例1：保护敏感文件

阻止 Claude 修改 `.env` 文件和 `credentials` 目录：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"\nimport sys, json\ninput_data = json.load(sys.stdin)\nfile_path = input_data.get('tool_input', {}).get('file_path', '')\nif '.env' in file_path or 'credentials' in file_path:\n    print(json.dumps({\n        'decision': 'deny',\n        'reason': '⛔ 安全策略：禁止修改敏感文件 ' + file_path\n    }))\n    sys.exit(0)\nprint(json.dumps({}))\n\""
          }
        ]
      }
    ]
  }
}
```

**更优雅的方式**——用独立的 shell 脚本：

```bash
#!/bin/bash
# .claude/hooks/protect-sensitive.sh
# PreToolUse hook: 保护敏感文件

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 敏感文件模式
SENSITIVE_PATTERNS=(
  ".env"
  "credentials"
  "secrets"
  ".pem"
  ".key"
  "id_rsa"
)

for pattern in "${SENSITIVE_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    jq -n --arg reason "⛔ 安全策略：禁止修改包含 '$pattern' 的文件" \
      '{decision: "deny", reason: $reason}'
    exit 0
  fi
done

# 允许操作
echo '{}'
```

对应的 `settings.json`：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/protect-sensitive.sh"
          }
        ]
      }
    ]
  }
}
```

### 4.5 实战案例2：自动代码格式化

每次文件写入后自动运行 Prettier：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-format.sh"
          }
        ]
      }
    ]
  }
}
```

```bash
#!/bin/bash
# .claude/hooks/auto-format.sh
# PostToolUse hook: 自动格式化

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then
  echo '{}'
  exit 0
fi

EXT="${FILE_PATH##*.}"

case "$EXT" in
  ts|tsx|js|jsx|json|css|md)
    npx prettier --write "$FILE_PATH" 2>/dev/null
    ;;
  py)
    python3 -m black "$FILE_PATH" 2>/dev/null
    ;;
  go)
    gofmt -w "$FILE_PATH" 2>/dev/null
    ;;
esac

echo '{}'
```

### 4.6 实战案例3：Slack 通知集成

当长时间任务完成时自动推送通知：

```json
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/notify-slack.sh"
          }
        ]
      }
    ]
  }
}
```

```bash
#!/bin/bash
# .claude/hooks/notify-slack.sh
# Notification hook: 转发到 Slack

INPUT=$(cat)
MESSAGE=$(echo "$INPUT" | jq -r '.message // empty')

if [ -z "$MESSAGE" ]; then
  echo '{}'
  exit 0
fi

# 发送到 Slack Webhook
curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  -d "{\"text\": \"🤖 Claude Code: $MESSAGE\"}" > /dev/null 2>&1

echo '{}'
```

### 4.7 Matcher 匹配规则详解

Matcher 是 Hooks 的过滤引擎，使用正则表达式匹配工具名称：

```json
// 精确匹配单个工具
"matcher": "Bash"

// 匹配多个工具（管道符表示 OR）
"matcher": "Write|Edit"

// 匹配所有文件操作
"matcher": "Write|Edit|NotebookEdit"

// 匹配所有工具（空字符串或省略）
"matcher": ""

// 使用正则表达式
"matcher": "Bash|Write|Edit"
```

---

## 五、第3层实战：定时任务与循环

### 5.1 三种调度方式对比

Claude Code 提供了三种调度机制，适用于不同场景：

| 特性 | Cloud Routines | Desktop 任务 | `/loop` |
|------|---------------|-------------|---------|
| 运行位置 | Anthropic 云端 | 本地机器 | 当前会话 |
| 需要开机 | ❌ | ✅ | ✅ |
| 需要会话 | ❌ | ❌ | ✅ |
| 重启后持久 | ✅ | ✅ | `--resume` 恢复 |
| 访问本地文件 | ❌（新克隆） | ✅ | ✅ |
| 最小间隔 | 1 小时 | 1 分钟 | 1 分钟 |
| 权限提示 | 无（自主运行） | 可配置 | 继承会话 |

### 5.2 `/loop` 固定间隔模式

```bash
# 每5分钟检查部署状态
/loop 5m check if the deployment finished and tell me what happened

# 每30分钟检查 PR 审查评论
/loop 30m check for new review comments on PR #42 and address them

# 每2小时运行代码审查
/loop 2h /review
```

**支持的时间单位**：`s`（秒）、`m`（分钟）、`h`（小时）、`d`（天）。秒数会上取整到分钟。

### 5.3 `/loop` 动态间隔模式

省略间隔参数时，Claude 会**智能选择**间隔——忙碌时缩短等待，空闲时延长等待：

```bash
# Claude 自行决定检查频率
/loop check whether CI passed and address any review comments

# 裸 /loop 运行内置维护提示
/loop
```

动态模式的行为：
- **构建即将完成** → 等待 1-3 分钟
- **PR 活跃讨论** → 等待 3-5 分钟
- **一切平静** → 等待 20-60 分钟
- 每次迭代的延迟原因会打印在输出中

### 5.4 自定义 loop.md

在项目根目录创建 `.claude/loop.md`，替换内置维护提示：

```markdown
<!-- .claude/loop.md — 项目级循环维护指令 -->

检查 `release/next` 分支的 PR 状态：
1. 如果 CI 红灯，拉取失败日志，诊断并推送最小修复
2. 如果有新审查评论，逐一处理
3. 如果出现合并冲突，解决并更新
4. 如果一切正常，报告当前状态即可
```

查找优先级：`.claude/loop.md`（项目级） > `~/.claude/loop.md`（用户级）

### 5.5 CronCreate API 精细控制

在对话中通过 Claude 的 CronCreate 工具实现更精细的调度：

```
请帮我设置以下定时任务：
1. 每天早上9点（避开整点）检查未处理的 PR
2. 每小时检查一次测试流水线状态
3. 30分钟后提醒我做代码评审
```

Claude 会使用以下参数创建任务：

```
CronCreate({
  cron: "57 8 * * 1-5",          // 工作日 8:57
  prompt: "检查未处理的 PR 并汇报",
  recurring: true,
  durable: false                   // 会话级
})

CronCreate({
  cron: "7 * * * *",             // 每小时第7分钟
  prompt: "检查 CI 流水线状态",
  recurring: true
})

CronCreate({
  cron: "30 14 10 6 *",          // 6月10日 14:30（一次性）
  prompt: "提醒：该做代码评审了",
  recurring: false
})
```

**注意**：Claude 会**有意避开整点和半点**（如 :00 和 :30），除非你明确指定，以避免 API 峰值。

### 5.6 七天自动过期

所有 `/loop` 和 CronCreate 创建的循环任务会在 **7 天后自动过期**——触发最后一次执行后删除。这是设计如此，防止无限运行。

---

## 六、第4层实战：多 Agent 并行编排

### 6.1 四种并行方式选择指南

```mermaid
graph TD
    START["需要并行工作"] --> Q1{"谁协调任务？"}
    Q1 -->|"我自己逐步委派"| SUB["Subagents<br/>子代理"]
    Q1 -->|"我想甩手不管"| AV["Agent View<br/>后台调度"]
    Q1 -->|"让 Claude 自动分工"| TEAM["Agent Teams<br/>团队协作"]
    Q1 -->|"写成脚本可复现"| WF["Dynamic Workflows<br/>动态工作流"]

    SUB --> S1["场景：搜索结果汇总<br/>代码审查副任务"]
    AV --> S2["场景：多个独立研究<br/>并行开发功能"]
    TEAM --> S3["场景：项目拆分开发<br/>需要同步进度"]
    WF --> S4["场景：500+文件迁移<br/>代码库全量审计"]

    style SUB fill:#e8f5e9
    style AV fill:#e3f2fd
    style TEAM fill:#fff3e0
    style WF fill:#fce4ec
```

### 6.2 Subagents 子代理

最轻量的并行方式。Claude 在当前会话中自动派生子代理，处理耗时任务后返回摘要：

```
请帮我做以下事情：
1. 搜索整个代码库中使用 deprecated API 的地方
2. 检查所有测试文件的覆盖率
3. 审查最近5个 PR 的代码质量
```

Claude 会自动将每个子任务派给一个子代理并行执行。子代理的特点：
- 在独立上下文中运行，不污染主对话
- 返回摘要而非完整输出
- 自动管理生命周期

### 6.3 Agent View 后台调度

通过 `claude agents` 命令打开全局调度视图：

```bash
# 打开 Agent View
claude agents

# 在 Agent View 中可以：
# → 查看所有后台会话的状态
# → 切入某个需要输入的会话
# → 一目了然地监控进度
```

Agent View 适合"甩手掌柜"模式——派发多个独立任务，偶尔检查状态。

### 6.4 Dynamic Workflows 动态工作流

这是 Claude Code **最强大的自动化能力**——用 JavaScript 脚本编排数十到数百个 Agent，支持流水线、并行屏障、循环等复杂控制流。

#### 6.4.1 何时使用工作流

| 场景 | 用 Subagents | 用 Workflows |
|------|-------------|-------------|
| 3-5 个并行任务 | ✅ | ❌ 过度设计 |
| 50+ 文件迁移 | ❌ 上下文溢出 | ✅ 脚本管理状态 |
| 需要交叉验证 | ❌ 单次无法校验 | ✅ 内置对抗验证 |
| 需要可重复运行 | ❌ 每次重新描述 | ✅ 脚本保存复用 |
| 代码库全量审计 | ❌ 规模不够 | ✅ 100+ Agent 扫描 |

#### 6.4.2 运行内置工作流

```bash
# 深度研究工作流——多源检索 + 交叉验证 + 合成报告
/deep-research Node.js v20 到 v22 的权限模型发生了什么变化？
```

执行过程：
1. Claude 自动编写工作流脚本
2. 脚本在后台执行，会话保持可用
3. 用 `/workflows` 查看进度
4. 完成后报告直接出现在会话中

#### 6.4.3 工作流脚本结构

一个完整的工作流脚本示例——代码库安全审计：

```javascript
// 安全审计工作流
export const meta = {
  name: 'security-audit',
  description: '代码库安全审计：多维度扫描 + 对抗验证',
  phases: [
    { title: '扫描', detail: '并行多维度安全扫描' },
    { title: '验证', detail: '对抗验证每个发现' },
    { title: '合成', detail: '汇总确认的安全问题' }
  ]
}

// 阶段1：多维度扫描
phase('扫描')

const DIMENSIONS = [
  { key: 'injection', prompt: '搜索所有 SQL 注入、命令注入和 XSS 漏洞' },
  { key: 'auth', prompt: '审查认证和授权逻辑中的安全缺陷' },
  { key: 'secrets', prompt: '查找硬编码的密钥、token 和凭证' },
  { key: 'deps', prompt: '检查依赖中的已知漏洞和过时包' }
]

const FINDING_SCHEMA = {
  type: 'object',
  properties: {
    findings: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          file: { type: 'string' },
          line: { type: 'number' },
          severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
          description: { type: 'string' },
          recommendation: { type: 'string' }
        }
      }
    }
  }
}

// 并行扫描：每个维度一个 Agent
const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, {
    label: `scan:${d.key}`,
    phase: '扫描',
    schema: FINDING_SCHEMA
  }),
  // 阶段2：每个发现进行对抗验证
  scanResult => {
    if (!scanResult || !scanResult.findings) return null
    return parallel(
      scanResult.findings.map(f => () =>
        agent(
          `尝试反驳以下安全发现，验证其是否为真实漏洞：\n
          文件：${f.file}:${f.line}\n
          描述：${f.description}\n
          如果无法反驳，标记为 confirmed=true`,
          { label: `verify:${f.file}`, phase: '验证', schema: VERDICT_SCHEMA }
        )
        .then(v => ({ ...f, verdict: v }))
      )
    )
  }
)

// 合成最终报告
const confirmed = results
  .flat()
  .filter(Boolean)
  .filter(r => r.verdict?.confirmed)

return { confirmed, total: confirmed.length }
```

#### 6.4.4 工作流执行管理

```bash
# 查看所有工作流
/workflows

# 监控特定运行的进度
# ↑/↓ 选择运行 → Enter 展开详情
# 可以看到每个阶段的 Agent 数量、token 用量和耗时

# 恢复暂停的运行（修改脚本后）
# Workflow 会自动使用缓存的已完成 Agent 结果
```

---

## 七、综合实战：构建完整的自动化流水线

将四层能力组合，构建一个从代码提交到部署的完整自动化方案：

```mermaid
graph LR
    subgraph "CI Pipeline"
        A[git push] --> B["claude -p<br/>代码审查"]
        B --> C{审查通过？}
        C -->|是| D[合并 PR]
        C -->|否| E[发送评论]
    end

    subgraph "Hooks 防护"
        F["PreToolUse<br/>阻止危险操作"] --> G["PostToolUse<br/>自动格式化"]
        G --> H["Notification<br/>Slack 告警"]
    end

    subgraph "定时监控"
        I["/loop 10m<br/>部署状态检查"] --> J["/loop 动态<br/>PR 看护"]
    end

    subgraph "批量任务"
        K["Workflow<br/>全量安全审计"]
    end

    D --> I
    F -.-> B
    K -.-> A
```

### 7.1 项目配置文件模板

完整的 `.claude/settings.json` 配置模板：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/guard-commands.sh"
        }]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/protect-sensitive.sh"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/auto-format.sh"
        }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/notify-slack.sh"
        }]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(npm test*)",
      "Bash(npx prettier*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(curl*| bash)"
    ]
  }
}
```

### 7.2 命令守护脚本示例

```bash
#!/bin/bash
# .claude/hooks/guard-commands.sh
# PreToolUse hook: 拦截危险的 Bash 命令

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 危险命令模式
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "DROP TABLE"
  "truncate"
  ":(){ :|:& };:"
  "dd if="
  "mkfs"
  "> /dev/sda"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if [[ "$COMMAND" == *"$pattern"* ]]; then
    jq -n --arg cmd "$COMMAND" --arg pat "$pattern" \
      '{decision: "deny", reason: "⛔ 拦截危险命令: 匹配模式 [\($pat)]"}'
    exit 0
  fi
done

echo '{}'
```

---

## 八、性能与成本优化

### 8.1 Token 预算管理

多层自动化意味着多倍的 Token 消耗。Claude Code 提供了预算控制机制：

```javascript
// 在工作流脚本中使用预算控制
const budget = { total: 500000 } // 50万 token 上限

while (budget.total && budget.remaining() > 50000) {
  const result = await agent("Find bugs in this codebase", {
    schema: BUGS_SCHEMA
  })
  bugs.push(...result.bugs)
  log(`${bugs.length} found, ${Math.round(budget.remaining()/1000)}k remaining`)
}
```

### 8.2 缓存优化策略

| 策略 | 说明 | 节省效果 |
|------|------|---------|
| Prompt Cache | Anthropic 的 5 分钟缓存窗口 | 重复前缀免费 |
| 子代理摘要 | 只返回摘要到主上下文 | 减少 80%+ 上下文占用 |
| Workflow 缓存 | 修改脚本后只重跑变更部分 | 增量执行 |
| 会话恢复 | `--resume` 复用上下文 | 避免重新加载 |

### 8.3 调度间隔建议

根据 Prompt Cache 的 5 分钟 TTL，合理选择调度间隔：

```
┌──────────────────────────────────────────────────┐
│  < 5 分钟（60s-270s）                              │
│  → 缓存命中，低延迟                                │
│  → 适合：活跃监控 CI 构建                          │
├──────────────────────────────────────────────────┤
│  5 分钟 - 1 小时（300s-3600s）                     │
│  → 缓存失效，每次全量加载                          │
│  → 适合：非紧急的定期检查                          │
├──────────────────────────────────────────────────┤
│  > 1 小时                                         │
│  → 低频，总体 Token 消耗最低                      │
│  → 适合：日报、周报生成                            │
└──────────────────────────────────────────────────┘
```

**关键原则**：不要选择恰好 300 秒（5 分钟）——这是缓存刚好失效的最差选择。要么选 270 秒（留在缓存窗口内），要么选 1200 秒以上（一次缓存失效换取更长间隔）。

---

## 九、安全最佳实践

### 9.1 Hooks 安全层级

```
第1级：权限白名单（permissions.allow）
  ↓ 未匹配
第2级：PreToolUse Hooks（条件性拦截）
  ↓ 通过
第3级：Claude 自主判断（AI 安全评估）
  ↓ 通过
第4级：执行操作
```

### 9.2 多层防护清单

- [ ] `.env` 文件写入保护（PreToolUse hook）
- [ ] 危险 Bash 命令拦截（PreToolUse hook + permissions.deny）
- [ ] 敏感目录访问控制（`credentials/`、`secrets/`）
- [ ] 写入后自动格式化（PostToolUse hook）
- [ ] 所有操作审计日志（PostToolUse hook）
- [ ] 长时间任务通知（Notification hook → Slack/钉钉）
- [ ] 生产环境保护（禁止 `rm -rf`、`DROP TABLE` 等）

---

## 十、延伸阅读

| 主题 | 命令/资源 |
|------|----------|
| Hook 事件完整参考 | [Hooks Reference](https://code.claude.com/docs/en/hooks) |
| Agent SDK 文档 | [Agent SDK Overview](https://code.claude.com/docs/en/agent-sdk) |
| Workflows 详细指南 | [Dynamic Workflows](https://code.claude.com/docs/en/workflows) |
| 并行 Agent 对比 | [Run Agents in Parallel](https://code.claude.com/docs/en/agents) |
| 定时任务配置 | [Scheduled Tasks](https://code.claude.com/docs/en/scheduled-tasks) |
| 无头模式详解 | [Headless Mode](https://code.claude.com/docs/en/headless) |

---

## 训练营适用性评估

| 训练营类型 | 适用度 | 建议教学时长 | 说明 |
|-----------|--------|------------|------|
| AI 开发工具训练营 | ⭐⭐⭐⭐⭐ | 4-6 小时 | 核心课程，建议分两天教学 |
| DevOps 自动化训练营 | ⭐⭐⭐⭐ | 3-4 小时 | 重点讲解无头模式 + CI/CD 集成 |
| 企业 AI 落地培训 | ⭐⭐⭐⭐ | 2-3 小时 | 重点讲解 Hooks 安全防护 + 审计 |
| 编程入门训练营 | ⭐⭐ | 不建议 | 需要先掌握 Claude Code 基础操作 |
| 安全工程训练营 | ⭐⭐⭐ | 2 小时 | Hooks 安全防护机制专项 |

**推荐教学路径**：第1天覆盖第1-2层（无头模式 + Hooks），第2天覆盖第3-4层（定时任务 + 多 Agent 编排），每层配合一个动手实验。

---

## 参考来源

1. [Run prompts on a schedule — Claude Code Docs](https://code.claude.com/docs/en/scheduled-tasks) — 官方定时任务与 `/loop` 调度文档
2. [Intercept and control agent behavior with hooks — Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/hooks) — 官方 Hooks 事件钩子系统完整参考
3. [Orchestrate subagents at scale with dynamic workflows — Claude Code Docs](https://code.claude.com/docs/en/workflows) — 官方动态工作流编排文档
4. [Run agents in parallel — Claude Code Docs](https://code.claude.com/docs/en/agents) — 官方多 Agent 并行方案对比指南
5. [Claude Code Hooks: How to Automate Your Workflow in 2026 — AgentIncome](https://agentincome.io/blog/claude-code-hooks-2026/) — Hooks 实战教程与 20+ 配置示例

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