SkillSentry持续集成接入完整指南：每次代码变动自动触发质量门禁

CI 集成分两层：触发层决定何时启动测评（SKILL.md 变更时），门禁层决定测评结果如何控制 PR 合并（FAIL 阻断合并）。只做触发层不做门禁层，测评只是装饰品。两层都到位，质量门禁才能真正生效。

本文将提供：

• GitHub Actions 完整 workflow 配置
• exit code 设计与 CI 状态映射
• Branch Protection 配置
• 历史趋势数据的积累方法

一、为什么 CI 里可以用 --dangerously-skip-permissions

很多人初次见到这个 flag 都会质疑：“名字这么危险，真敢用？”先说结论：在 CI 环境中，这个 flag 安全且应该使用；在本地则不应使用。

根本原因在权限模型差异：

CI 容器是一次性隔离环境——每次 workflow 运行都是全新容器，无持久状态，操作不触及真实生产环境，运行完即销毁。因此 --dangerously-skip-permissions 在 CI 中的真实含义是：“在此一次性容器内，跳过权限确认，让测评全自动化无需人工介入。” 危险的是“绕过生产系统的权限控制”，而非“跳过 AI 工具调用确认”。

二、GitHub Actions 完整配置

基础配置：SKILL.md 变更时触发

# .github/workflows/skill-eval.yml
name: SkillSentry Evaluation
on:
  pull_request:
    paths:
      - 'skills/*/SKILL.md' # 任意 Skill 的 SKILL.md 变更时触发
  push:
    branches: [main]
    paths:
      - 'skills/*/SKILL.md'

jobs:
  skill-eval:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 2 # 需要对比前一个版本
      - name: Detect changed skills
        id: changed-skills
        run: |
          CHANGED=$(git diff --name-only HEAD~1 HEAD -- 'skills/*/SKILL.md' | sed 's|skills/||' | sed 's|/SKILL.md||' | tr '\n' ',')
          echo "skills=${CHANGED}" >> $GITHUB_OUTPUT
          echo "Changed skills: ${CHANGED}"
      - name: Install Claude Code
        run: |
          npm install -g @anthropic-ai/claude-code
          # 验证安装
          claude --version
      - name: Run SkillSentry evaluation
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 对每个变更的 Skill 运行 smoke 测评
          IFS=',' read -ra SKILLS <<< "${{ steps.changed-skills.outputs.skills }}"
          OVERALL_EXIT=0
          for SKILL in "${SKILLS[@]}"; do
            if [ -z "$SKILL" ]; then continue; fi
            echo "=== Evaluating: $SKILL ==="
            claude --dangerously-skip-permissions \
              -p "smoke 测评 ${SKILL} 自动" \
              --output-format stream-json | tee "eval-${SKILL}.log"
            EXIT_CODE=${PIPESTATUS[0]}
            if [ $EXIT_CODE -ne 0 ]; then
              echo "::error::Skill ${SKILL} evaluation FAILED (exit code: ${EXIT_CODE})"
              OVERALL_EXIT=1
            fi
          done
          exit $OVERALL_EXIT
      - name: Upload evaluation reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: skill-eval-reports-${{ github.run_id }}
          path: |
            **/*.eval-report.html
            **/sessions/**/*.html
          retention-days: 30

完整门禁配置：standard 测评 + 发布等级检查

# .github/workflows/skill-eval-full.yml
name: SkillSentry Full Evaluation (Pre-release)
on:
  push:
    branches: [release/*]
    paths:
      - 'skills/*/SKILL.md'

jobs:
  detect-skills:
    runs-on: ubuntu-latest
    outputs:
      skills: ${{ steps.changed-skills.outputs.skills }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 2
      - name: Detect changed skills
        id: changed-skills
        run: |
          SKILLS=$(git diff --name-only HEAD~1 HEAD -- 'skills/*/SKILL.md' | sed 's|skills/||' | sed 's|/SKILL.md||' | jq -R -s -c 'split("\n")[:-1]')
          echo "skills=${SKILLS}" >> "$GITHUB_OUTPUT"
          echo "Changed skills: ${SKILLS}"
  skill-eval-standard:
    needs: detect-skills
    if: needs.detect-skills.outputs.skills != '[]'
    runs-on: ubuntu-latest
    timeout-minutes: 60
    strategy:
      matrix:
        skill: ${{ fromJson(needs.detect-skills.outputs.skills) }}
      fail-fast: false # 一个 Skill FAIL 不影响其他 Skill 的测评继续
    steps:
      - uses: actions/checkout@v6
      - name: Install Claude Code
        run: |
          npm install -g @anthropic-ai/claude-code
          claude --version
      - name: Run standard evaluation
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --dangerously-skip-permissions -p "standard 测评 ${{ matrix.skill }} 自动" --output-format stream-json
      - name: Check release grade
        run: |
          # 从报告提取发布等级
          GRADE=$(find "sessions/${{ matrix.skill }}" -name "*.json" -print0 | xargs -0 -r grep -h -o '"release_grade":"[A-Z]*"' | tail -1 | sed 's/.*:"//;s/"$//' || true)
          echo "Release grade: ${GRADE}"
          echo "GRADE=${GRADE}" >> "$GITHUB_ENV"
          case "$GRADE" in
            "S"|"A"|"B"|"C")
              echo "Grade ${GRADE}: PASS"
              ;;
            "D"|"F"|"FAIL"|"")
              echo "::error::Skill ${{ matrix.skill }} did not pass (grade: ${GRADE})"
              exit 1
              ;;
            *)
              echo "::error::Unknown grade for ${{ matrix.skill }}: ${GRADE}"
              exit 1
              ;;
          esac
      - name: Sa ve trend data
        if: always()
        run: |
          # 记录历史趋势数据到 gh-pages 或 artifact
          DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
          echo "{\"date\":\"${DATE}\",\"skill\":\"${{ matrix.skill }}\",\"grade\":\"${GRADE}\",\"run\":${{ github.run_number }}}" >> trend-data.jsonl
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: eval-${{ matrix.skill }}-${{ github.run_id }}
          path: |
            sessions/${{ matrix.skill }}/**/*.html
            trend-data.jsonl
          retention-days: 90

三、exit code 设计

CI 系统依赖 exit code 判断步骤是否成功。SkillSentry 的 exit code 规范如下：

关键设计点：GitHub Actions 只认 0 和非 0。exit code 1（测评 FAIL）和 exit code 2（环境错误）必须阻止 PR 合并；exit code 3 若定义为“不稳定但不阻断”，就不能直接把 3 作为步骤退出码返回，而要在脚本里捕获后输出 warning，再由团队策略决定是否放行。

--output-format stream-json 和 --output-format json 用途不同：

前面的 workflow 使用 stream-json 是为了让 CI 页面实时显示执行进度；下面的示例使用 json 是为了演示如何从结构化结果解析 pass/fail。

等待 exit code 的方式：

# 方式一：直接检查 claude 命令的退出码
claude --dangerously-skip-permissions -p "smoke 测评 my-skill 自动"
if [ $? -ne 0 ]; then
  echo "Evaluation failed"
  exit 1
fi

# 方式二：从输出的 JSON 中解析结果
claude --dangerously-skip-permissions -p "smoke 测评 my-skill 自动" --output-format json > result.json
PASS=$(jq -r '.result.pass' result.json)
if [ "$PASS" != "true" ]; then
  echo "Evaluation failed: $(jq -r '.result.reason' result.json)"
  exit 1
fi

若想将“结果不稳定”标记为 warning 而非 failure，需显式处理：

set +e
claude --dangerously-skip-permissions -p "quick 测评 my-skill 自动"
EXIT_CODE=$?
set -e
case "$EXIT_CODE" in
  0)
    echo "Evaluation passed"
    ;;
  3)
    echo "::warning::Evaluation is unstable; mark as conditional pass and require follow-up"
    exit 0
    ;;
  *)
    echo "::error::Evaluation failed with exit code ${EXIT_CODE}"
    exit "$EXIT_CODE"
    ;;
esac

四、Branch Protection 配置

在 GitHub 仓库设置中配置 branch protection rule，让 CI 状态决定 PR 能否合并：

1. 进入仓库 Settings → Branches → Add branch protection rule
2. Branch name pattern：main（或你的主分支名）
3. 勾选 Require status checks to pass before merging
4. 在 Status checks 搜索框中添加：skill-eval / skill-eval
5. 勾选 Require branches to be up to date before merging

配置完成后效果：PR 中有 SKILL.md 变更 → 自动触发测评 → 测评 FAIL → PR 显示红色 × → 无法合并；测评通过 → PR 显示绿色 ✓ → 允许合并。

五、历史趋势数据

单次测评只能告诉你“当前通不过”，历史趋势能告诉你“质量在下降还是提升”。

数据收集方案

每次 CI 运行将测评结果写入 trend JSONL 文件：

{"date":"2026-04-10T09:00:00Z","skill":"em-reimbursement-v3","grade":"A","pass_rate":0.92,"delta":0.67,"run":142}
{"date":"2026-04-11T14:30:00Z","skill":"em-reimbursement-v3","grade":"A","pass_rate":0.91,"delta":0.65,"run":145}
{"date":"2026-04-12T11:00:00Z","skill":"em-reimbursement-v3","grade":"B","pass_rate":0.83,"delta":0.52,"run":148}

趋势预警规则

在 CI 中加入趋势分析：

# 检查最近 5 次的趋势
TREND=$(tail -5 trend-data.jsonl | jq -s '[.[].pass_rate] | (last - first)')
if (( $(echo "$TREND < -0.1" | bc -l) )); then
  echo "::warning::Pass rate has dropped by more than 10% in last 5 runs"
fi

报告持久化

将 HTML 报告上传到 GitHub Actions artifacts，保留 90 天：

- uses: actions/upload-artifact@v4
  with:
    name: skill-report-${{ github.run_number }}
    path: sessions/**/*.html
    retention-days: 90

配合 GitHub Pages，可将趋势数据可视化为折线图，在团队 wiki 中直接查看质量趋势。

六、常见 CI 问题与处理

七、分级门禁策略

并非所有 SKILL.md 改动都需要同等严格的测评。推荐分级策略：

定时健康检查可发现“Skill 未改但环境变了导致测评失败”的情况，例如 MCP Server 升级引发工具调用行为变化。

# 定时健康检查
on:
  schedule:
    - cron: '0 2 * * *' # 每天凌晨 2 点（UTC）
jobs:
  health-check:
    # ... 对所有已注册 Skill 运行 quick 测评
    # FAIL 不阻断，但通过 Slack/飞书通知

八、工程落地建议：CI 分成两条线

前面的 workflow 是门禁骨架。实际落地时，建议让 CI Runner 以结构化测评结果为准，读取 grading-summary.json / session.json / authoritative_pass_rate，再返回明确的 exit code。

推荐脚本分工：

• sentry_ci.py：核心判决脚本，读取 grading-summary.json / session.json / authoritative_pass_rate → PASS/FAIL 判决 → exit code
• update_history.py：追加 history.json 历史记录，支持趋势分析和回归检测
• report_to_checks.py：将结果推送为 GitHub Checks 注解，PR 页面直接可见

相比前面的 YAML 骨架，结构化 Runner 的改进：

CI 建议分成两条线，不要混成一条 workflow：

1. 业务 Skill 质量门禁：skill-eval.yml，用于评估被测 Skill 的 smoke / standard / full 结果，核心仍是让 FAIL 阻断合并。
2. SkillSentry 本体自检：skillsentry-self-test.yml，用于验证 SkillSentry 自身脚本、契约、模板和工作流未被改坏。

本体自检的推荐入口是确定性脚本，而非再次启动真实 LLM 测评：

python scripts/verify_deterministic.py --format json

手动触发深度自检时再打开 full：

python scripts/verify_deterministic.py --full --format json

GitHub Actions 示例应使用当前 Node 运行时兼容的 action 版本：

steps:
  - uses: actions/checkout@v6
  - uses: actions/setup-python@v6
    with:
      python-version: '3.11'

这类工程落地常见坑是：workflow 模板已升级到新 major，但仓库里的实际 workflow 仍停留在旧 major，容易触发运行时退役提醒或模板与线上不一致。后续 workflow 模板和仓库内实际 workflow 要保持一致，并用 verify_workflow_action_versions.py 扫描旧 major，避免模板修了、线上 workflow 没修。

另一个易忽略的点是 GitHub 权限。推送 .github/workflows/*.yml 不仅需要普通 repo 权限，还需要 token 带 workflow scope；否则代码改好了也会被远端拒绝。

九、实战补充：最小 CI Gate

若团队暂时跑不起 full 测评，至少应先做一个最小静态门禁：

PR 提交 -> 自动静态检查 -> 检查准入标准 -> PASS：允许进入后续流程 -> FAIL：阻断 + 通知 + 修复建议

最小准入标准可先设如下：

最小 GitHub Actions 结构：

name: Skill Static Gate
on:
  pull_request:
    paths:
      - "skills/*/SKILL.md"
jobs:
  static-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Run static check
        run: |
          for skill_dir in skills/*/; do
            skill_name=$(basename "$skill_dir")
            python tools/sentry-static.py "$skill_dir/SKILL.md" --format json > "static-${skill_name}.json"
          done

CI 失败时，通知里不要只写“失败”，要给出：

Skill 名称 | 总分 | 失败维度 | 修复建议 | 报告链接

这个最小 Gate 不替代完整测评，也不替代人工发布判断。它的价值是把低质量 Skill 挡在 review 之前。

总结

将 SkillSentry 接入 CI 的核心就是三件事：

1. 触发：paths: skills/*/SKILL.md → SKILL.md 变更时自动运行
2. 阻断：exit code 1/2 → CI 失败 → branch protection 阻止合并
3. 积累：每次结果写入 trend JSONL → 质量趋势可见

关键原则：测评不阻断发布 = 没有门禁。只有 FAIL 真能阻止 PR 合并，质量保证才是真实的，而非报表上的数字。

来源：互联网