AI Agent Skill 工程化06:CI里的Skill门禁实战

作者:菠萝爱吃肉2026.11.17 03:35浏览量:0

简介:本文围绕 AI Agent Skill 工程化中的 Eval 自动化,讲解如何把手工回归升级为 CI 门禁:通过 PR 触发、风险分层、自动判定和报告可视化,让每次修改 Skill 都自动回归,regression 失败即阻止合并,并给出可落地的目录结构、流水线示例与注意事项。

如果你已经为 Agent Skill 建立了 Eval,却还在每次修改 SKILL.md、工具配置或编排逻辑后手动执行回归,那么下一步应该把 Eval 接入 CI 门禁。目标很明确:PR 触发、风险分层、自动判定、结果可视化,regression 失败就阻止合并。若 Eval 中需要调用大模型,建议先通过 百度智能云词元所 了解模型能力、价格与统一 API 接入方式,再决定回归环境中使用哪个模型。

一、为什么手跑 Eval 不够

很多团队在 Skill 建设初期都会遇到类似问题:Skill 包已经建好,Eval 也写了几条,但每次改动后仍靠人工执行。短期看似乎可行,一旦 Skill 数量增加、协作人数变多,问题会迅速放大。

痛点 典型表现 后果
忘记跑 改了 SKILL.md,没有跑 regression 合入后发现旧能力损坏
跑不全 只跑新增用例,不跑历史用例 新功能通过,但旧能力退化
判定靠人 rule、structure 类结果本可自动判断,却靠人工看 效率低,容易漏判
结果不透明 results.tsv 手工维护,团队成员不同步 不知道是谁改坏了,回滚靠猜

Skill 并不是单个提示词,而是提示词、工具调用、知识策略、编排逻辑和输出约束的组合。任何一个部分变化,都可能影响最终效果。因此,Eval 门禁的本质不是“多跑几次测试”,而是把 Skill 的质量控制变成自动化、强制化、可视化的工程流程。

二、Eval 门禁的三阶段设计

一个成熟的 Skill CI 门禁,通常分为三个阶段。

阶段 触发时机 执行范围 失败动作
PR 门禁 每次提交 Pull Request high risk 全跑,medium risk 抽样或按 diff 跑 regression 失败阻止合并
发布门禁 合并到主分支或准备发布 全量 Eval regression 全绿才允许发布
定期回归 定时任务或低峰期 spot check、季度全量 发现退化后创建修复任务

这里最重要的是区分“新增 Eval”和“回归 Eval”。新增 Eval 用于验证新能力,回归 Eval 用于确认旧能力没有被破坏。CI 门禁必须优先保证 regression 通过,否则 Skill 很容易陷入“新功能上线,旧功能悄悄坏掉”的状态。

三、推荐的工程目录结构

为了让 CI 能稳定执行,建议把 Skill、Eval 用例和门禁脚本纳入同一套工程结构。

  1. skills/
  2. order-assistant/
  3. SKILL.md
  4. evals/
  5. cases.yaml
  6. baseline.tsv
  7. ci/
  8. eval-gate.yml
  9. scripts/
  10. run_eval.py
  11. check_gate.py
  12. requirements.txt

其中,cases.yaml 用于描述 Eval 用例,baseline.tsv 用于记录历史通过状态,run_eval.py 负责执行 Eval,check_gate.py 负责根据结果决定是否阻断流水线。

一个简化的用例配置示例:

  1. - id: 002_missing_body
  2. risk: high
  3. type: regression
  4. input: "帮我生成一个缺少正文的订单通知"
  5. assertions:
  6. - type: contains
  7. value: "订单号"
  8. - type: not_contains
  9. value: "BLOCKED"
  10. - id: 018_tool_call_format
  11. risk: medium
  12. type: structure
  13. input: "查询最近三笔订单并总结异常"
  14. assertions:
  15. - type: json_schema
  16. value: "schemas/order_summary.json"

通过 risk 字段,可以把用例分为 high、medium、low 三个等级。high 用例每次 PR 都跑,medium 用例按改动范围抽样,low 用例可以进入季度全量回归。

四、GitHub Actions 门禁示例

下面是一个最小可用的 GitHub Actions 门禁示例。它会在 Pull Request 触发时执行 Eval,并上传结果文件。

  1. name: skill-eval-gate
  2. on:
  3. pull_request:
  4. jobs:
  5. eval:
  6. runs-on: ubuntu-latest
  7. steps:
  8. - name: Checkout
  9. uses: actions/checkout@v4
  10. - name: Setup Python
  11. uses: actions/setup-python@v5
  12. with:
  13. python-version: "3.11"
  14. - name: Install dependencies
  15. run: |
  16. pip install -r requirements.txt
  17. - name: Run Skill Eval
  18. run: |
  19. python scripts/run_eval.py \
  20. --skill skills/order-assistant \
  21. --risk high medium \
  22. --report results.tsv
  23. - name: Check Eval Gate
  24. run: |
  25. python scripts/check_gate.py \
  26. --report results.tsv \
  27. --fail-on regression
  28. - name: Upload Eval Report
  29. uses: actions/upload-artifact@v4
  30. with:
  31. name: skill-eval-report
  32. path: results.tsv

check_gate.py 的核心逻辑可以很简单:

  1. import csv
  2. import sys
  3. report = "results.tsv"
  4. failed = []
  5. with open(report, newline="", encoding="utf-8") as f:
  6. reader = csv.DictReader(f, delimiter="\t")
  7. for row in reader:
  8. if row["type"] == "regression" and row["status"] != "PASS":
  9. failed.append(row["case_id"])
  10. if failed:
  11. print("Regression failed:", ", ".join(failed))
  12. sys.exit(1)
  13. print("Eval gate passed.")

这个脚本的关键不是复杂,而是明确:只要 regression 用例失败,CI 就返回非零状态,从而阻止合并。

五、门禁判定规则要清晰

Eval 门禁不能只写“跑一下”,还要明确判定规则。建议至少包含以下几条:

  1. regression 必须 PASS
    只要历史回归用例失败,就不允许合并。

  2. high risk 用例必须全部通过
    高风险用例通常涉及核心输出、工具调用、权限边界或关键业务流程。

  3. medium risk 用例按 diff 触发
    如果本次改动只影响某个工具或某个提示片段,可以只跑相关用例。

  4. low risk 用例进入定期回归
    低频或非核心能力不必阻塞每次 PR,但应定期执行。

  5. flaky 用例必须显式处理
    如果模型输出存在随机性,可以设置有限重试,但必须记录重试次数和最终状态,不能静默忽略。

  6. 新增 Eval 必须先建立 baseline
    新用例第一次运行时,应记录当前状态作为基线,避免后续无法判断是历史通过还是本次退化。

六、结果可视化与团队协作

CI 门禁的价值不只是“阻止错误合并”,还包括让结果透明。建议每次 Eval 都生成结构化报告,例如 results.tsv,字段可以包括:

  1. case_id risk type status duration model commit timestamp
  2. 002 high regression PASS 1.8s model-a abc123 2026-11-17T03:35:10Z
  3. 018 medium structure FAIL 2.3s model-a abc123 2026-11-17T03:35:12Z

在 GitHub Actions 中,可以把报告作为 artifact 上传,也可以在 PR 中输出摘要。这样团队成员不需要互相询问“刚才是不是你改坏了”,而是直接查看流水线结果。

如果 Eval 需要执行 AI 生成的代码或工具调用,建议把执行过程放进隔离沙箱,避免污染 CI 环境并提升安全性。对于 Code Agent 类 Skill,这一点尤其重要。

七、模型调用如何影响 Eval 门禁

很多 Skill Eval 并不是纯规则判断,而是会调用大模型。这时需要特别注意模型版本、调用参数和输出稳定性。

建议至少固定以下变量:

  • 模型名称或模型版本;
  • temperature、top_p 等生成参数;
  • 超时时间和重试策略;
  • system prompt 与 user prompt 模板;
  • 工具调用格式和返回结构;
  • 评测 rubric 或自动判定规则。

如果团队同时使用多个模型,或者需要在不同环境之间迁移 Eval,可以借助 词元所模型服务 进行模型能力、调用成本和接入方式的统一评估。这样在 CI 中选择回归模型时,能更清晰地判断成本、稳定性和可替换性,而不是临时拍脑袋决定。

八、常见坑与落地建议

在实际落地时,有几个问题经常出现:

  • 只跑新增用例,不跑 regression :这是最危险的,容易导致旧能力退化。
  • 断言太宽 :例如只判断“包含某个词”,会让错误输出也通过。
  • 断言太严 :例如要求模型输出逐字一致,容易因为正常波动导致误报。
  • 忽略环境差异 :本地通过不代表 CI 通过,尤其是涉及工具调用、文件读写或代码执行时。
  • 门禁过重 :所有用例都阻塞合并,会拖慢研发效率,应按 risk 分层。
  • 没有基线 :新增 Eval 后没有记录历史状态,后续无法判断是否退化。

一个可执行的落地顺序是:

  1. 先挑 5~10 条最核心的 regression 用例;
  2. 给每条用例标注 risk 和 type;
  3. 写一个最小可运行的 run_eval.py;
  4. 接入 GitHub Actions 或其他 CI 系统;
  5. 让 regression 失败自动阻止合并;
  6. 再逐步补充 medium、low 用例和定期回归任务。

当这套机制跑起来后,Skill 的迭代方式会发生变化:开发者不再依赖记忆和手工检查,而是依赖流水线反馈。每次修改都有 Eval 兜底,每次合并都有门禁保护,Skill 工程化才真正从“能跑”走向“可维护”。