12 编程式调用与 CI 集成——Agent 作为服务

原文：Headless Mode + GitHub Actions

从交互到自动化

Claude Code 不只是一个终端里的交互工具——它可以作为 Agent SDK 被编程调用，嵌入到 CI/CD 管线、脚本、甚至其他应用中。

这标志着 AI Agent 使用方式的一个重要演进：从人机交互到 Agent-as-a-Service。

CLI 编程调用（`-p` 模式）

基础用法

# 非交互式执行
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

# 管道输入
cat build-error.txt | claude -p '解释这个构建错误' > output.txt

`--bare` 模式（推荐脚本使用）

跳过所有自动发现（Hooks、Skills、Plugins、MCP、CLAUDE.md），只执行你显式指定的：

claude --bare -p "Summarize this file" --allowedTools "Read"

为什么：保证在任何机器上结果一致——不会因为某个同事的 ~/.claude 配置而行为不同。

结构化输出

# JSON 输出（含 session_id、usage 等元数据）
claude -p "Summarize this project" --output-format json

# JSON Schema 约束输出
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}}}'

# 流式 JSON
claude -p "Explain recursion" --output-format stream-json

延续对话

# 第一次调用
claude -p "Review this codebase for performance issues"

# 延续上一次对话
claude -p "Now focus on the database queries" --continue

# 获取 session_id 精确恢复
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

权限控制

# 细粒度工具授权
claude -p "Look at staged changes and create a commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git commit *)"

* 是前缀匹配——Bash(git diff *) 允许任何以 git diff 开头的命令。注意 * 前有空格。

GitHub Actions 集成

Claude Code 提供官方 GitHub Action，可以在 PR 上自动执行代码审查、实现需求、回复评论等。

典型用法：PR 上的 AI 助手

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

用法模式

场景	触发	Claude 做什么
PR 评论中 @claude	评论创建	执行请求的任务
新 PR 自动审查	PR 创建	代码审查 + 建议
定时任务	cron	依赖审计、文档检查

Agent SDK（Python / TypeScript）

CLI 之上还有完整的 SDK，支持：

结构化输出和 JSON Schema
工具审批回调
原生消息对象
流式输出

from claude_code import Agent

agent = Agent()
result = agent.run("Fix the auth bug", allowed_tools=["Read", "Edit", "Bash"])

关键架构洞察

编程式调用揭示了 Agent 的本质：Agent 是一个函数——接受输入（prompt + 上下文），产生输出（文本 + 文件变更 + 命令执行）。

这意味着：

Agent 可以被组合（一个 Agent 的输出作为另一个的输入）
Agent 可以被编排（CI 管线中的一个步骤）
Agent 可以被测试（给定输入，验证输出）
Agent 可以被监控（token 成本、执行时间、成功率）

知识检测

概念理解题

--bare 模式为什么被推荐用于脚本？“在任何机器上结果一致”意味着什么？
“Agent 是一个函数”这个洞察有什么深远影响？如果 Agent 可以被测试，测试的输入和输出分别是什么？

应用题

你的 TypeScript 项目用 GitHub Actions 做 CI。设计一个工作流：每个 PR 自动让 Claude 审查代码质量、检查安全漏洞、生成审查报告。写出 GitHub Actions YAML 的关键部分。
你想用 claude -p 做一个每天凌晨 2 点自动运行的代码库健康检查。它需要：检查过期的依赖、找出没有测试覆盖的文件、生成报告发到 Slack。设计命令行管道。

迁移思考题

OpenClaw 的 Cron 系统和 Claude Code 的 -p + GitHub Actions 在自动化方面分别有什么优势和劣势？

参见

08-最佳实践与工作模式 — 交互式使用的最佳实践
10-Agent-Teams-多代理协作 — 更复杂的自动化编排
SlipBox 相关：Claude Code、Agent、Cron

参考答案

1. —bare 模式的重要性

“在任何机器上结果一致”意味着可重现性。不加 --bare 时，claude -p 会加载当前目录的 CLAUDE.md、Hook、Skill、MCP——这些在你本机和 CI 机器上可能不同。--bare 跳过所有自动发现，只执行你显式传入的参数，就像 Docker 容器一样提供干净的执行环境。CI 脚本必须用 --bare，否则本地能跑的脚本在 CI 上可能行为不同。

2. “Agent 是一个函数”的影响

如果 Agent 是函数，那么：可以被测试——输入是 prompt + 上下文 + 工具集，输出是文本 + 文件变更 + 退出码。你可以写测试用例：“给定这段有 bug 的代码 + ‘修复 null pointer bug’ 的 prompt，验证输出的 diff 是否正确”。可以被组合——一个 Agent 的输出 pipe 给另一个 Agent。可以被监控——记录每次调用的 token 成本、执行时间、成功率，建立 SLA。可以被版本控制——Agent 的行为由 prompt + skill + model 决定，都可以版本化。

3. TypeScript PR 审查 GitHub Actions

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
    paths: ['src/**/*.ts', 'src/**/*.tsx']
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this PR's TypeScript code changes for:
            1. Code quality and TypeScript best practices
            2. Security vulnerabilities (SQL injection, XSS, auth bypasses)
            3. Performance issues (N+1 queries, memory leaks, unoptimized renders)
            4. Type safety (unnecessary 'any', missing null checks)
            Post findings as inline PR comments with severity levels.

4. 每日代码库健康检查

#!/bin/bash
# 跑在 cron 或 CI 定时任务中
REPORT=$(claude --bare -p "Check this project:
1. Run 'npm outdated' and list packages >2 major versions behind
2. Find source files with no corresponding test file
3. Check for TODO/FIXME/HACK comments added in the last 30 days
Output a structured JSON report with sections: outdated_deps, untested_files, recent_todos" \
  --allowedTools "Bash,Read,Glob,Grep" \
  --output-format json | jq -r '.result')

# 发送到 Slack
curl -X POST "$SLACK_WEBHOOK" \
  -H 'Content-Type: application/json' \
  -d "{\"text\": \"Daily Health Check:\n$REPORT\"}"

5. OpenClaw Cron vs Claude Code -p + GitHub Actions

OpenClaw Cron 优势：Gateway 长驻所以任务保证执行、结果可以直接发到 WhatsApp/Telegram、有状态（可以记住上次检查的结果）。劣势：需要自己运维 Gateway、单点故障。Claude Code -p + GitHub Actions 优势：基础设施由 GitHub 管理、高可用、可复现、天然和 Git 流程集成。劣势：无状态（每次独立执行）、不能直接发消息到 IM、冷启动慢。选择取决于：任务是否需要状态、是否需要 IM 通知、是否能接受自运维。