feat: add ai run quality evaluation

project-docs/V2-ai-quality-evaluation-mvp-2026-06-23.md

@@ -0,0 +1,59 @@
+# V2 AI 质量评测 MVP 闭环记录
+
+日期：2026-06-23
+
+## 本轮目标
+
+给每次 AI 调用增加可复盘的质量标签，让管理员在 AI Trace 页直接看到本次回答是否引用依据、是否走 fallback、token/耗时是否异常、知识来源是否不足。
+
+## 已落地内容
+
+1. AI run 审计表新增质量字段。
+   - `quality_status`
+   - `quality_score`
+   - `quality_labels_json`
+   - `quality_summary`
+   - 新增迁移 `20260623_0007_add_ai_run_quality_fields.py`
+
+2. 法律问答主链路增加质量评测。
+   - 有引用依据：`citation_present`
+   - 缺少引用依据：`missing_citation`
+   - 知识来源不足：`source_insufficient`
+   - 知识来源偏少：`source_limited`
+   - 知识来源覆盖：`source_covered`
+   - 使用 fallback：`fallback_used`
+   - provider 失败：`provider_failed`
+   - token 缺失或过高：`token_missing` / `token_high`
+   - 耗时偏高或严重：`latency_high` / `latency_critical`
+
+3. 质量判定输出。
+   - `passed`：没有 error/warning。
+   - `needs_review`：存在 warning，需要人工复核。
+   - `failed`：存在 error，需要优先处理。
+   - `quality_score` MVP 规则：100 分起，error 每项扣 30 分，warning 每项扣 10 分。
+
+4. 契约和 SDK 同步。
+   - OpenAPI `AiRun` 新增质量字段。
+   - Python SDK `AiRunAudit` 新增质量字段。
+   - 新增 `AiQualityLabel` SDK 模型。
+
+5. AI Trace 后台展示。
+   - `/admin/ai-traces` 新增“质量待复核”指标。
+   - 调用列表新增质量状态和质量分。
+   - 支持按质量状态筛选：全部、质量通过、需要复核、质量失败、未评测。
+   - 展开详情新增“质量评测”区块，展示质量摘要和标签明细。
+
+## 验收重点
+
+- 执行一次法律问答后，`GET /api/v1/audit/ai-runs` 返回质量字段。
+- fallback 回答应标记 `needs_review`，并包含 `fallback_used`。
+- 缺少引用依据时应标记 `failed`。
+- AI Trace 页能按质量状态筛选，并能展开查看每个质量标签的原因。
+
+## 建议下一步
+
+进入 AI 质量评测规则后台化：
+
+- 把 token 阈值、耗时阈值、来源数量阈值做成后台可配置。
+- 给质量标签增加人工确认状态，例如“已复核”“误报”“已处理”。
+- 给管理首页增加 AI 质量异常趋势，形成运营级监控。