6.5. 持续集成与交付管道让 Skills 迭代安全又快速

你需要什么

• 一个 GitHub 仓库：用于存放 Skills 源代码与 CI/CD 配置
• Anthropic API 密钥（需设置 ANTHROPIC_API_KEY 环境变量）：用于在管道中运行评估测试
• Terraform CLI（≥1.5）：用于声明式管理 Skills 运行环境
• Docker（可选）：如果需要在本地模拟管道运行
• 1–2 小时：从零搭建完成全自动评审-交付管道

最终成果

你将拥有一个 GitHub Actions 驱动的 CI/CD 管道，它会在每次 Pull Request 上自动执行代码规范检查、评估测试和金丝雀发布准备；合并到 main 分支后立即触发金丝雀部署，并借助 IaC（基础设施即代码）保持所有环境的一致性。 整个流程的目标是：把上一章建立的评估指标嵌入日常开发，让每一个代码提交都穿过“检查之门”，在安全与速度之间找到最佳平衡。

1. 项目植入：从一次手工发布说起

时间线锚点：你已经用 A/B 测试证明了新版本 Skills 的业务效果，但现在每次上线都需要手动运行评估脚本、人工切换流量、然后祈祷别出故障。反馈循环长达 3 天，迭代速度被严重拖慢。

在这一步，我们要把“发布”这个动作从人工操作变成一条自动化流水线。下面所有步骤将围绕一个示例 Skills 仓库展开，演示如何一步一确认地构建出完整的 CI/CD 流程。

2. GitHub Actions 工作流设计：把检查门嵌入每次提交

步骤 1：创建第一个 lint & test 工作流

在项目根目录下创建 .github/workflows/ci.yml：

name: Skills CI
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}  # 1️⃣ 从 Secrets 注入密钥
    steps:
      - uses: actions/checkout@v4

      - name: Lint Skills 文件格式
        run: |
          # 使用自定义脚本检查 md 头信息、必填字段等
          python scripts/lint_skills.py ./skills/*.md

      - name: 运行评估测试
        run: |
          # 2️⃣ 调用 Claude API，用上一章的评估指标验证新 Skills
          python scripts/evaluate.py --skills-dir ./skills --output results.json

      - name: 上传评估报告
        uses: actions/upload-artifact@v4
        with:
          name: eval-results
          path: results.json

预期结果：提交一个 PR 后，Actions 自动执行 lint 检查与评估测试，数分钟内你就能在 PR 页面看到 ✅ 或 ❌ 的状态。如果评估指标低于阈值，PR 会被阻止合并。

⚠️ 注意：API 密钥安全
务必在仓库 Settings → Secrets and variables → Actions 中添加 ANTHROPIC_API_KEY（勾选 “Masked”）。管道日志中不会显示该值，避免泄露。

步骤 2：构建并发布到 Skills 市场

评估通过只是第一步，我们还需要把 Skills 打包并推送到市场（或内部 Artifact Registry）。扩展 ci.yml，在 test 成功后添加构建与发布任务：

  build-and-release:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'   # 3️⃣ 仅在 main 分支合并后执行
    steps:
      - uses: actions/checkout@v4

      - name: 打包 Skills
        run: |
          mkdir build
          cp -r skills/ build/
          # 生成版本清单
          git describe --tags > build/version.txt

      - name: 发布到市场
        run: |
          # 假设市场 CLI 工具为 `skills-cli`
          skills-cli publish \
            --api-key ${{ secrets.MARKET_API_KEY }} \
            --source build \
            --strategy canary   # 4️⃣ 指定金丝雀发布策略

预期结果：任何合并到 main 的代码都会自动触发构建，并将新版本推送至 Skills 市场，同时标注为“金丝雀候选”。整个发布过程从数小时压缩到几分钟，不再需要人工登录服务器。

3. 金丝雀发布与回滚策略：守好最后一道防线

即使在评估测试中表现良好，真实生产流量仍可能暴露隐藏的边界情况。金丝雀发布通过逐步切换流量并实时监控异常来降低风险。

步骤 3：定义金丝雀部署流程

我们将金丝雀逻辑与 GitHub Actions 分离，交给一个轻量级部署脚本（例如 scripts/rollout.sh），便于在管道中复用，也允许手动触发回滚。

#!/bin/bash
# rollout.sh - 控制流量权重

STAGE=${1:-canary}   # canary | full
VERSION_TAG=${2:-latest}

if [ "$STAGE" == "canary" ]; then
  echo "将 10% 流量指向新版本..."
  # 假设使用 Cloudflare Workers 或其他网关修改路由
  wrangler dns-weight --version $VERSION_TAG --weight 10
  # 启动监控进程，60s 内检查错误率
  monitor --duration 60 --max-error-rate 0.01
  if [ $? -ne 0 ]; then
    echo "错误率超标，自动回滚！"
    wrangler dns-weight --version $VERSION_TAG --weight 0
    exit 1
  fi
else
  echo "金丝雀验证通过，全量发布..."
  wrangler dns-weight --version $VERSION_TAG --weight 100
fi

在 .github/workflows/ci.yml 的发布任务中调用该脚本：

      - name: 金丝雀发布
        run: |
          bash scripts/rollout.sh canary ${{ github.sha }}
          bash scripts/rollout.sh full ${{ github.sha }}

预期结果：新版本先获得 10% 的流量，如果 1 分钟内错误率低于 1%，则自动全量；反之立即回滚，并通知开发者。整个回滚决策在 2 分钟内完成，用户几乎无感知。

💡 踩坑提示
流量切换因所用网关而异（NGINX、Traefik、AWS Application Load Balancer 等）。上述示例用 wrangler 只是示意，实际落地时请替换为你的网关 CLI。关键点：发布管道中要内置监控和自动回滚能力，而不是发布后再人工观察。

4. 基础设施即代码：管理 Skills 运行环境

前面的管道解决了“软件”交付问题，但 Skills 运行所依赖的计算实例、网络配置、密钥等“硬件”也需要版本化，否则开发、预发、生产环境可能产生“雪花”差异，导致测试通过的 Skills 在生产中崩溃。

步骤 4：用 Terraform 声明基础设施

创建一个 infra/ 目录，编写 main.tf：

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

variable "environment" {
  description = "部署环境"
  type        = string
  default     = "dev"
}

# Skills 运行时（如 AWS Lambda）
resource "aws_lambda_function" "skills_runtime" {
  function_name = "skills-${var.environment}"
  runtime       = "python3.12"
  handler       = "runtime.handler"
  filename      = "../skills.zip"  # 由 CI 提前构建产出

  environment {
    variables = {
      ANTHROPIC_API_KEY_SECRET = var.anthropic_api_key_secret
    }
  }

  tags = {
    Environment = var.environment
    ManagedBy   = "Terraform"
  }
}

然后在 CI 管道中添加 IaC 阶段（例如使用 Terraform Cloud 或 GitHub Actions 的 hashicorp/setup-terraform），确保每次部署 main 时自动执行 terraform apply。

预期结果：无论你重建多少次开发环境，Skills 的运行基底完全一致；生产环境的每一次变更都记录在 Terraform state 中，杜绝手动调整配置。

回顾

至此，你完成了一套面向 Claude Skills 的 CI/CD 闭环：

从提交代码到安全上线，反馈时间从过去的数天缩短到 20 分钟以内，且每一步都有可重复、可审计的自动化保证。

下一步行动清单

1. 初始化仓库：在 GitHub 中创建 Skills 项目，复制上面的 ci.yml 示例。
2. 注入密钥：添加 ANTHROPIC_API_KEY 和 MARKET_API_KEY 到 Secrets。
3. 编写评估脚本：基于第八章的指标实现 evaluate.py，并确保它在本地通过。
4. 实现流量控制：根据你的网关类型重写 rollout.sh，并测试自动回滚逻辑。
5. 声明基础设施：用 Terraform 描述 Skills 运行时，并运行一次 apply 生成开发环境。

当你完成这五步后，一个能够自我保护的 Skills 迭代流就真正运转起来了。不过，自动化管道虽好，Skills 的服务形态同样决定交付质量——接下来，我们将进入第十章《部署模式的选择决定了 Skills 的服务形态》，对比 CLI、API、Web 三种部署方式的选型标准与实现方法，帮你在自动化基础之上做出最合适的产品决策。