PMFlow/backend/evals/README.md

AI Steward Eval Gate

文件

• golden_qa_v1.jsonl: 50 条金标准问答（含追问链）。
• golden_feishu_replay_v1.jsonl: 飞书执行链路回放样本（执行/咨询/重复/噪音/多操作写库 split）。
• feishu_replay_eval.py: 飞书回放评测，断言 DB + route_status + reply_text。
• reports/: 评测结果归档目录，latest.json 指向最近一次结果。
• scripts/ai_steward_eval.py: 执行 lint/在线评测/门禁。
• scripts/ai_steward_eval_compare.py: 对比两版报告。
• backend/evals/rag_project_understanding_eval.py: 项目语义理解回归（功能目录/入口/API 命中率）。

本地执行

# 1) 校验金标准集
python3 scripts/ai_steward_eval.py --lint-only

# 2) 在线评测（需 JWT）
python3 scripts/ai_steward_eval.py \
  --api-url http://127.0.0.1:8000/rag/ask \
  --token '<JWT_TOKEN>' \
  --fail-on-threshold

# 3) 报告对比
python3 scripts/ai_steward_eval_compare.py \
  --base backend/evals/reports/ai_steward_eval_xxx.json \
  --target backend/evals/reports/latest.json

# 4) 项目语义理解回归
python3 backend/evals/rag_project_understanding_eval.py --tenant-id 1

# 5) 飞书回放样本 lint
PYTHONPATH=backend python3 backend/evals/feishu_replay_eval.py \
  --lint-only \
  --input backend/evals/golden_feishu_replay_v1.jsonl

# 5.1) PMFlow 本地路由层 路由矩阵 lint（L/H/S 覆盖校验）
python3 scripts/control_plane_routing_lint.py --input backend/.control_plane/pmflow-routing-rules.json

# 5.2) Operation Catalog lint（全系统写操作覆盖校验）
python3 scripts/operation_catalog_lint.py

# 6) 飞书回放执行（严格模式）
PYTHONPATH=backend python3 backend/evals/feishu_replay_eval.py \
  --strict \
  --tenant-id 9901 \
  --input backend/evals/golden_feishu_replay_v1.jsonl \
  --output-dir backend/evals/reports

# 7) 飞书链路 canary（4 场景）
bash scripts/feishu_canary_smoke.sh

注意：

• 回放默认 tenant 为 9901，并默认拒绝 tenant_id=1，避免误删主租户测试数据。
• 仅在隔离数据库中才可使用 --allow-tenant-1 强制放行。

该回归会输出：

• avg_keyword_hit_ratio：问题关键词命中率
• avg_feature_evidence_ratio：路由/页面/API 证据命中率

门禁阈值

• accuracy >= 0.80
• hallucination_rate <= 0.12
• followup_hit_rate >= 0.75
• query_type_hit_rate >= 0.80

任一指标不达标，--fail-on-threshold 会返回非 0 退出码，阻断发布。