# 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 命中率）。

## 本地执行
```bash
# 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 退出码，阻断发布。