英文名：AI Quality Gate / EvalOps Workbench 状态：第一版已完成并在本地跑通（2026-09-22）；后续增量见下方「LearnQA Gate V2（2026-10-01）」与「Auto Judge 有边界升级（2026-10-15）」 首个场景：AI 应用输出的结构化质量检查与发布门禁（案例包以知识问答与短视频脚本为例）
一句话：把 AI 应用的一次输出变成可重放、可解释、可对比、可阻断发布的评测记录。
源码：https://github.com/egg666rafa/learnqa-gate（MIT）
- 不是「判断内容好不好」的个人偏好系统；
- 不是通用聊天机器人，也不是 Langfuse / Dify / Promptfoo 的低配复制；
- 不做模型训练或微调；
- 不用 LLM 评分冒充质量真值——2026-10-15 起有边界接入的裁判只输出建议，不参与 Gate 放行，也不作为语义真值；
- 没有真实用户、没有线上流量，所有数字都是离线固定案例的工程验收数字。
案例契约 → 版本运行 → 确定性检查 → 人工复核 → 回归对比 → 发布门禁 → 证据报告
# 1. 环境（venv 放在项目目录内，避免占用 C 盘）
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
# 2. 跑测试（当前 241 个，全部离线）
.venv\Scripts\python.exe -m pytest -q
# 3. 看一次完整演示（约 3 秒跑完，不需要浏览器）
.venv\Scripts\python.exe scripts\demo_3min.py
# 4. 启动本地服务，浏览器打开 http://127.0.0.1:8765
.venv\Scripts\python.exe -m app.cli serve --port 8765也可以直接用一键脚本：
powershell -ExecutionPolicy Bypass -File scripts\start.ps1 -Mode test
powershell -ExecutionPolicy Bypass -File scripts\start.ps1 -Mode demo
powershell -ExecutionPolicy Bypass -File scripts\start.ps1 -Mode evidence
powershell -ExecutionPolicy Bypass -File scripts\start.ps1 -Mode serve案例集：cases-1.0.0 的子集 demo10（10 条固定案例）
输出来源：mock_adapter（固定输出表） business_effect: not_measured
v1 prompt-v1 rules-1.0.0 通过 8/10 门禁 BLOCKED
v2 prompt-v2 rules-1.0.0 通过 9/10 门禁 BLOCKED
通过数 +1，blocker 1 → 5
新增 blocker：qa_case_002（v2 丢掉了「退款三个工作日到账」这条声明的来源绑定）
修复：qa_case_010（答案超长）、sc_case_004（缺少 scenes 字段）
候选版本发布结论：BLOCKED
结论：通过数提高不等于可以发布。只看平均分或通过率，会漏掉「修好一个、弄坏另一个」的回归。
这个场景由 scripts/demo_3min.py 复现，脚本内置断言，数字对不上就返回非 0 退出码。
前置校验失败 / 有案例 ERROR / 证据不完整 → BLOCKED
存在 blocker（案例级或回归引入） → BLOCKED
无 blocker 但存在 warning 级软问题 → REVIEW_REQUIRED
全部硬约束通过且无新增回归 → PASS
人工复核只能追加，不能覆盖自动结果，也不能解除 blocker 阻断，只能记录「已接受例外」。 报告里同时给出「自动结论」和「叠加复核后的派生结论」。
| 类型 | 案例 |
|---|---|
| 正常结构化输出 | qa_case_001 ~ qa_case_005、sc_case_001 ~ sc_case_003 |
| JSON 解析失败 | qa_case_006（输出被截断） |
| 必填字段缺失 | qa_case_007、sc_case_004 |
| 字段类型错误 | qa_case_008 |
| 禁止字段出现 | qa_case_009 |
| 字数/范围越界 | qa_case_010（软）、sc_case_005（硬） |
| 事实声明无来源 | qa_case_011 |
| 引用来源不存在 | qa_case_012 |
| 需要人工判断的软问题 | qa_case_013（措辞模糊） |
| 空输入 | qa_case_014 |
| 禁止用语 | sc_case_006（绝对化承诺） |
| v2 修复一个问题但引入另一个 | qa_case_002 |
全部为自编的合成样例，标注 synthetic_demo，不代表任何真实业务数据。
33 个 check_id，分四类，统一返回 check_id / status / severity / message / evidence：
- C1 Schema：能否解析、字段是否完整、类型、枚举、数值范围、数组与字符串长度、契约外字段；
- C2 格式与业务约束：长度、必备段落、禁止字段、禁止用语、分镜结构、措辞模糊、
status/verified与来源的一致性； - C3 引用证据：每条声明是否绑定来源、来源标识是否存在、引用片段能否在来源中定位、案例要求的证据是否被用到；
- C4 回归：新增失败、blocker 增加、引用绑定消失、软分变好但硬约束变差。
状态 PASS / FAIL / SKIPPED / ERROR，级别 info / warning / blocker。
SKIPPED 永远不等于通过：输出不可解析时 C2/C3 全部记 SKIPPED，门禁只认 FAIL / ERROR。
scripts/build_evidence.py 会一次性生成：
evidence/
├── ACCEPTANCE.md # 验收汇总（本次全部运行与对比的真实数字）
├── RUNS.json # 运行索引
├── junit.xml # pytest 真实结果
├── commands.jsonl # 执行过的命令清单
├── source_manifest.json # 全部源码的 SHA256
├── runs/<run_id>/ # 每次运行的 report.md + report.json
├── comparisons/<a>__vs__<b>/ # 三组版本对比报告
├── screenshots/ # 6 张浏览器验收截图（含失败详情页）
└── REVIEWS 记录 # 两次人工复核（见 ACCEPTANCE.md 第 3 节）
每个结论都能回到原始记录，例如：
| 结论 | 证据 |
|---|---|
| 20 条案例都能跑 | evidence/runs/<full-v1>/report.json 的 cases 长度 |
| 12 条故意失败样本存在 | 同一份报告的 summary.fail 与 cases[].status |
| blocker 真的能阻断发布 | summary 与 gate.status 同时为 BLOCKED |
| v1 → v2 有回归 | evidence/comparisons/demo10-v1__vs__demo10-v2/comparison.json 的 new_blockers |
| 规则版本变化会改结论 | evidence/comparisons/rules-1.0.0__vs__rules-1.1.0/comparison.json |
| 人工复核不改写自动结果 | 复核前后 cases[].failed_checks 完全一致（tests/test_api_blackbox.py） |
- 架构与数据模型：模块划分、数据流、五张表、33 个检查项、门禁与策略优先级
- 接口与命令清单：HTTP 接口、CLI、环境变量、页面路由
- 未实现与风险边界：本轮范围、已知限制、需要主控验收的问题、禁止事项自查
- Auto Judge 有边界升级：裁判、检索指标、校准、证据边界、写入位置与离线复现
- 项目立项讨论稿：立项时的范围与验证计划（设计稿）
- DeepSeek 实施文档：本轮任务的契约来源
- 开源参考调研：参考项目与借鉴边界
在获得主控验收前，本项目不表述为「已上线」「准确率提升」「成本下降」「解决幻觉」 「生产级稳定」「替代人工审核」。第一版的通过率是离线固定案例的工程验收数字。
- 运行结束后才整包落库，中途被杀不会留下记录；
- MockAdapter 只覆盖已登记的 case × prompt 组合，未登记组合直接报
ERROR； - 固定输出表由人工编写，只能证明规则与门禁按预期工作，不能代表真实模型行为；
- C3 不做事实真伪判断，只做引用存在性与片段定位。
完整清单见 docs/03_未实现与风险边界.md。
本项目已在旧 AI Quality Gate 之上增量加入 LearnQA Gate V2，首阶段聚焦“课程资料 / 公开教材 → 学习问答 → 自动检查 → 人工复核 → 版本回归 → 放行 / 复核 / 阻断”。旧版代码、旧证据和短视频脚本 legacy 案例保持可追溯，不自动并入 LearnQA 默认任务集。
启动旧服务后访问 http://127.0.0.1:8765/learnqa.html，可查看 LearnQA 任务、运行报告、失败检查、来源 ID 和 baseline/candidate 对比。页面只调用新增的 /api/learnqa/* 本地接口，不改变旧版四页流程。
# 资产、任务集、来源、规则和适配器自检
.venv\Scripts\python.exe -m app.learnqa.cli environment
# 运行确定性 Mock 回归
.venv\Scripts\python.exe -m app.learnqa.cli run --prompt-version learnqa-prompt-v1 --adapter-version learnqa-mock-1.0.0
.venv\Scripts\python.exe -m app.learnqa.cli run --prompt-version learnqa-prompt-v2 --adapter-version learnqa-mock-1.0.0
# 运行已捕获的真实模型输出（不发起新模型请求）
.venv\Scripts\python.exe -m app.learnqa.cli run --prompt-version learnqa-prompt-v1 --adapter-version learnqa-captured-codex-1.0.0
# 创建复核模板、校验记录、汇总分歧
.venv\Scripts\python.exe -m app.learnqa.cli review-template
.venv\Scripts\python.exe -m app.learnqa.cli review-validate --input evidence\learnqa_v2\review_records.jsonl
.venv\Scripts\python.exe -m app.learnqa.cli review-summary --input evidence\learnqa_v2\review_records.jsonl
# 生成正式 LearnQA 证据包并执行当前离线测试
.venv\Scripts\python.exe scripts\build_learnqa_evidence.py
# 或使用统一脚本：test / mock / captured / evidence / serve
powershell -ExecutionPolicy Bypass -File scripts\run_learnqa_v2.ps1 -Mode evidence证据包位于 evidence/learnqa_v2/。2026 年 10 月 1 日当前配置下的真实模型小样本捕获结果为：
- baseline：PASS 3 / REVIEW_REQUIRED 9 / BLOCKED 12，14 个 blocker；
- candidate：PASS 1 / REVIEW_REQUIRED 10 / BLOCKED 13，15 个 blocker；
- 新增 blocker：
learnqa_002、learnqa_014、learnqa_016；修复 blocker：learnqa_012、learnqa_013； - 两个版本最终都 BLOCKED。
这不是线上评测、用户研究、公开 API 基准或通用模型准确率。负结果保留，不通过放宽规则制造 PASS。
- P0：最终答案、课程材料一致性、引用可定位、无依据补充、不确定性表达和版本回归；
- P1 候选：刷题题目可作答性、答案唯一性、干扰项和解析质量，暂不完整实现；
- 不做：知识图谱、学习计划、班级管理、推荐、间隔重复、通用 AI 教师平台；
- 当前没有外部同学复核，
review_records.jsonl为空；模板中的structured_self_test不等于用户研究； - 不把 LearnQA 描述为“保证 AI 回答正确”或“生产级教育平台”。
详细实现见 docs/LEARNQA_V2_IMPLEMENTATION.md，证据边界见 docs/LEARNQA_V2_EVIDENCE.md。
新增独立 auto_judge/：四维结构化裁判、A/B 位置交换校验、实际来源检索指标、独立人工复核校准，并接入原 LearnQA 页面的 Live 区域。支持本轮临时密钥输入，无需设置环境变量；支持新生成或有来源记录的历史回答裁判。评测结果只给建议，原 Gate 策略保持原样。
本轮验收硬化补齐了几处会误导读数的实现：校准改为 (prompt_version, case_id) 组合键、弃权（REVIEW_REQUIRED）单列并给出 3×3 confusion matrix、P95 标注样本量（n ≤ 19 时等于样本最大值）、交互式运行改写 var/learnqa 工作区而不是冻结证据包、并发冲突返回 409、FastAPI 422 回显里的密钥字段脱敏。逐条改动与涉及文件见 CHANGELOG.md 的 2026-10-15 一节。
当前测试：pytest -q → 241 passed，0 failed。旧版回归子集（--ignore-glob=tests/test_auto_judge*.py 加 -k 排除条件，完整命令记录在 evidence/auto_judge/verification.json）→ 124 passed，7 deselected；2026-10-01 记录的 117 是同一子集更早的数字：本轮新增的 3 个硬化测试文件里，tests/test_auto_judge_hardening.py（12）属于 auto_judge 模块、被 --ignore-glob 排除，另外 2 个凭据/隔离测试文件（test_api_credential_hygiene.py 3 项 + test_learnqa_evidence_isolation.py 4 项 = 7 项）不属于该模块、留在子集内，因此子集数字从 117 变为 124。
使用方式、接口与限制见 AUTO_JUDGE_LIVE.md，实际检索、历史对比、新 API 成功与失败证据见 EVAL_BENCHMARK_REPORT.md，可推导的测试计数见 evidence/auto_judge/verification.json。
- 仓库：https://github.com/egg666rafa/learnqa-gate
- 本项目自身代码与文档：MIT。
- 例外：
sources/下的来源摘录来自 CPython 官方教程文档，遵循 PSF-2.0，不随本项目的 MIT 授权。每条来源都在sources/manifests/source_pack_python-3.14-tutorial-1.0.0.json里登记了owner_or_publisher、license_or_permission、license_url、locator和摘录正文的sha256，可逐条回查。 - 内置的
web/vendor/vue.global.prod.js是 Vue 3 的官方发行构建，遵循其自身的 MIT 许可。 fixtures/、datasets/与evidence/里的问答内容和模型输出均为合成样例或本项目自己的捕获记录，不含真实用户数据。