将源文件路径映射到测试。在实际项目中，你可能需要解析导入图。

mapping = { "app/app.py": ["tests/test_app.py"] }

changed_json = sys.stdin.read() changed = json.loads(changed_json)["changed"] selected = set()

for path in changed: if path in mapping: for t in mapping[path]: if Path(t).exists(): selected.add(t)

如果没有匹配到任何内容，则回退到完整测试套件

if not selected: selected = {"tests"}

print(" ".join(sorted(selected)))

scripts/build_image.sh
```bash
#!/usr/bin/env bash
set -euo pipefail

APP_NAME="opt-pipeline-demo"
IMAGE="{IMAGE:-ghcr.io/{GITHUB_REPOSITORY}/${APP_NAME}}"
TAG="{TAG:-{GITHUB_SHA::7}}"

echo "[build] 正在构建 $IMAGE:$TAG （使用缓存）"
docker build \
    --file - \
    --tag "$IMAGE:$TAG" \
    --tag "$IMAGE:latest" \
    --cache-from "$IMAGE:latest" \
    . <<'DOCKER'
FROM python:3.11-slim
WORKDIR /app
COPY app/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ .
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
DOCKER

.github/workflows/ci.yml

name: 优化的 CI
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  workflow_dispatch: {}
concurrency:
  group: opt-ci-${{ github.ref }}
  cancel-in-progress: true
env:
  PYTHON_VERSION: "3.11"
  CLAUDE_MODEL: claude-3.5-sonnet
  CLAUDE_BUDGET_USD: "0.05"
  EXPECTED_OUTPUT_TOKENS: "1800"
jobs:
  prepare:
    runs-on: ubuntu-latest
    outputs:
      changed: ${{ steps.diff.outputs.changed }}
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - id: diff
        run: |
          python3 scripts/changed_paths.py > changed.json
          echo "changed=$(catchanged.json|jq-c.changed)">>$GITHUB_OUTPUT
  test:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-python@v5
        with: { python-version: ${{ env.PYTHON_VERSION }} }
      - name: 缓存 pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: pip-$runner.os-${{ env.PYTHON_VERSION }}-${{ hashFiles('app/requirements.txt') }}
          restore-keys: pip-$runner.os-${{ env.PYTHON_VERSION }}-
      - name: 安装依赖 + pytest
        run: |
          python -m pip install --upgrade pip
          pip install -r app/requirements.txt pytest
      - name: 选择性测试列表
        id: select
        run: |
          echo '${needs.prepare.outputs.changed}^{\prime }|jq-n--argjsonchange{d}^{\prime }${{ needs.prepare.outputs.changed }}' '{changed:$changed}' \
          | python scripts/selective_tests.py > tests_to_run.txt
          echo "tests=$(cattest{s}_t{o}_{r}un.txt)">>$GITHUB_OUTPUT
      - name: 运行测试
        run: |
          echo "正在运行: ${{ steps.select.outputs.tests }}"
          pytest -q ${{ steps.select.outputs.tests }}
  build:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - name: 登录 GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: 拉取最新镜像以供缓存使用
        run: |
          docker pull ghcr.io/${{ github.repository }}/opt-pipeline-demo:latest || true
      - name: 使用缓存构建并推送
        env:
          GITHUB_REPOSITORY: ${{ github.repository }}
          GITHUB_SHA: ${{ github.sha }}
        run: |
          bash scripts/build_image.sh
          docker push ghcr.io/${{ github.repository }}/opt-pipeline-demo:latest
          docker push ghcr.io/$github.repository/opt-pipeline-demo:${GITHUB_SHA::7}
  docs_with_claude:
    needs: [test]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 准备提示词
        run: |
          cat > .prompt.txt <<'PROMPT'
          总结 FastAPI 服务并生成一个简洁的 README 章节，内容包括：
          - 用途和接口
          - 本地运行说明
          - 健康检查示例
          PROMPT
      - name: 估算 Claude 成本并执行门控
        id: estimate
        env:
          CLAUDE_MODEL: ${{ env.CLAUDE_MODEL }}
          CLAUDE_BUDGET_USD: ${{ env.CLAUDE_BUDGET_USD }}
          EXPECTED_OUTPUT_TOKENS: ${{ env.EXPECTED_OUTPUT_TOKENS }}
        run: |
          python3 scripts/estimate_tokens.py .prompt.txt > estimate.json || exit_code=$?
          cat estimate.json
          echo "decision=$(jq-r.decisionestimate.json)">>$GITHUB_OUTPUT
          echo "model=$(jq-r.modelestimate.json)">>$GITHUB_OUTPUT
          echo "est_cost=$(jq-r.estimate{d}_{c}ostestimate.json)">>$GITHUB_OUTPUT
          exit ${exit_code:-0}
      - name: 使用 Claude 生成文档（模拟）
        if: steps.estimate.outputs.decision == 'allow'
        run: |
          echo "## README（自动生成）" > README.md
          echo "" >> README.md
          echo "- 模型: ${{ steps.estimate.outputs.model }}" >> README.md
          echo "- 预估成本: $${{ steps.estimate.outputs.est_cost }}" >> README.md
          echo "" >> README.md
          echo "### 服务" >> README.md
          echo "FastAPI 应用暴露 /health 接口，并使用 Uvicorn 运行。" >> README.md
      - name: 回退到更便宜的模型结果（模拟）
        if: steps.estimate.outputs.decision == 'switch'
        run: |
          echo "## README（自动生成，预算回退至 Haiku）" > README.md
          echo "FastAPI 应用暴露 /health 接口，并使用 Uvicorn 运行。" >> README.md
      - uses: actions/upload-artifact@v4
        with:
          name: 生成的 README
          path: README.md

此工作流展示了组合优化：

• 基于 requirements.txt 哈希的确定性依赖缓存。
• 在构建前拉取 :latest 镜像并确定性打标签，以实现 Docker 层复用。
• 基于变更的测试选择，必要时回退到完整测试套件。
• Token 成本估算，自动限流或降级 Claude 使用。
• 并发取消机制，确保只有最新提交的流水线能运行完成。

说明表格：优化、机制与效果

通过将缓存复用、路径感知执行、Docker 层缓存、并行化以及 Claude token 门控层层叠加，你把一条既昂贵又缓慢的流水线转变成了一个可预测、速度快且尊重预算的系统。该方法具备可扩展性：可以添加更多映射以细化选择性测试、将镜像缓存提升到远程注册表缓存，或扩展成本门控以在多个 Claude 模型及最大输出大小之间进行选择。借助这些模式，你的 CI 既对开发者友好，又对财务友好，同时保持代码和文档的相同质量标准。

第 13 章 – Claude Code 故障排查与调优