阶段4（上）：LangGraph、Function Calling、MCP（SDK 2.x）、Agent 评测与运维、Agent 设计专题；run_examples 设置 RUN_EXAMPLES=1

topics/ai/agent-ops/scenarios/agent-quality-gate.md

@@ -0,0 +1,90 @@
+---
+id: ai.agent-ops.scenario.agent-quality-gate
+title: 客服 Agent 上线流程：评测集、质量门禁、灰度和线上 Bad Case 闭环
+type: scenario
+domain: ai
+stack: [agent-ops, cicd, langgraph]
+tags: [质量门禁, 灰度发布, Bad Case, 评测集, 线上监控]
+level: advanced
+prerequisites: [ai.agent-ops.eval-quality-gate]
+est_hours: 3
+related: [ai.agent-ops.interview, devops.cicd.release-rollback]
+week: [13]
+---
+
+# 客服 Agent 上线流程：评测集、质量门禁、灰度和线上 Bad Case 闭环
+
+## 业务背景与问题
+
+客服 Agent 已经上线，团队每周都在改提示词、换模型、调检索参数。最近两次事故：
+
+1. 改了一句提示词，退款类问题开始答错，三天后才被客服发现；
+2. 换了一个更便宜的模型，整体满意度没变，但越权查询类问题开始被回答。
+
+业务方要求：任何改动上线前要证明“没有变差”，上线后出问题要能快速发现和回滚。
+
+## 约束
+
+- 每周至少发布一次。
+- 没有专职的标注团队，人工评审资源有限。
+
+## 方案设计
+
+```mermaid
+flowchart LR
+  A[改动：提示词 / 模型 / 检索参数] --> B[CI：评测集 + 质量门禁]
+  B -->|不通过| A
+  B -->|通过| C[灰度 5% 流量]
+  C --> D{线上指标正常?}
+  D -->|否| R[回滚]
+  D -->|是| E[全量]
+  E --> F[线上 Bad Case 收集] --> G[分类 + 修复] --> H[加入评测集] --> B
+```
+
+1. **提示词、模型配置、检索参数都放进 Git**，和代码一样走评审和 CI。
+2. **评测集分组**：正常问答、拒答、越权、工具调用、多轮、注入，每组有最低通过率；安全组零容忍；基线通过的用例不允许回归。
+3. **打分**：规则判断优先；答案质量用 LLM 评分，每月用 50 条人工标注样本校准评分标准。
+4. **灰度**：按用户哈希分流 5%，对比新旧版本的转人工率、点踩率、拒答率、成本、P95 延迟。
+5. **线上 Bad Case 闭环**：点踩、转人工、客服标记的对话自动进入待分析队列；每周分析并按失败环节分类；修复后加入评测集。
+
+## 关键代码
+
+CI 中的门禁步骤（GitHub Actions 写法，平台不同语法不同）：
+
+```yaml
+agent-eval:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - uses: astral-sh/setup-uv@v6
+    - run: uv sync --frozen
+    - name: 评测 + 质量门禁（失败时退出码非 0，阻止合并）
+      run: uv run python eval/agent_eval.py --ci --baseline eval/baseline.json
+      env:
+        LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+    - uses: actions/upload-artifact@v4
+      if: always()
+      with: { name: eval-report, path: eval/report.json }
+```
+
+门禁逻辑的可运行示例：[examples/eval-gate](../examples/eval-gate/)。
+
+## 取舍
+
+| 选择 | 优点 | 缺点 |
+| --- | --- | --- |
+| **每次改动跑全量评测（本方案）** | 回归能被发现 | 每次运行有模型调用成本；评测集要控制规模（几百条） |
+| 只做人工抽检 | 不需要建设 | 慢、不稳定、覆盖少 |
+| 只看线上指标 | 真实 | 发现时已经影响用户 |
+| LLM 评分代替人工 | 便宜、快 | 需要定期校准，安全类用规则判断 |
+
+## 易错点
+
+- 提示词放在数据库后台随时修改，绕过了评审和门禁。
+- 评测用例长期不更新，和线上问题分布偏离。
+- 灰度只看错误率：大模型应用的“错误”往往是答错而不是报错，要看业务指标。
+- 回滚只回滚了代码，没有回滚模型配置或检索索引。
+
+## 面试怎么讲
+
+> “我们把提示词、模型配置和检索参数都放进 Git，每次改动在 CI 里跑评测集。评测集按类型分组，安全类零容忍，基线通过的用例不允许回归——有一次换模型总分没变，但门禁发现越权类用例失败，就拦下了。通过后灰度 5%，看转人工率、点踩率和成本；线上点踩的对话进入 Bad Case 队列，每周按失败环节分类，修复后加入评测集。”