外观
日志、测试、质量评估与成本
1. 解决什么问题
“最后生成了一个文件”不足以证明流程正确，更无法解释失败发生在哪一层。可观测记录帮助还原任务；自动化测试检查不变量；固定评测集衡量内容质量。三者要相互关联，不能混成一个通过率。
2. 原理与术语
trace 关联一次业务执行，事件记录阶段事实，metric 用于聚合比较。Recall@k 衡量候选覆盖；格式通过率衡量结构契约；内容问题检出率衡量评审覆盖。质量、调用次数、延迟和费用必须在同一实验条件下报告。
3. 输入输出与执行
节点通过 db.event 写入 events；模型调用记录角色、模型、context_hash、latency_ms 与 usage；教材与评审全文分别保存在 versions 和 reviews。任务详情接口聚合这些记录，方便从一个 job_id 回溯。
4. 容易混淆
事件 latency_ms 是单次模型调用或演示步骤耗时，不是整套教材端到端耗时。未知 token 或费用应保留为空；演示成本 0 只表示没有远程调用，不代表真实模型零成本。哈希也不能还原完整上下文，需联合来源快照。
5. 最小示例
python
# 人工标注样例，仅演示指标计算，不是项目评测结果。
gold = {"source-a", "source-b"}
retrieved = ["source-a", "source-c"]
recall = len(gold & set(retrieved)) / len(gold)
assert recall == 0.5指标分母来自明确标注，没有标准答案就不能随意报告召回率。
6. 实际实现
model_call、schema_repair、retrieved、reviewed、version_saved、task_finished、asset_reused 和 delivery_ready 描述关键过程。当前没有部署 Prometheus、OpenTelemetry 或 LangSmith；数据库事件是学习系统的主要观测入口。
7. 源码与数据结构
阅读 system/app/db.py::event、providers.py::run_model、worker.py::run_once、api.py::detail。详情接口返回最近 300 条事件，而数据库保留历史；长任务排查不能误以为页面没显示的早期事件不存在。
8. 设计取舍
小系统先用业务关联事件，减少额外组件。规模增长后可增加结构化指标和分布式追踪，但要保持版本与请求 ID 可关联。真实质量评测应将检索、生成和评审分开：检索错误不能全部记为生成错误，格式错误也不应算作审稿漏检。
9. 实验与验收
在 system 目录运行测试，并查询一个真实存在的任务：
bash
docker compose run --rm tests pytest -q tests
curl -s -H "X-API-Key: ${LAB_API_KEY:-}" \
"http://127.0.0.1:8000/api/jobs/$JOB_ID" | python -c \
'import json,sys; d=json.load(sys.stdin); print([(e["kind"],e["payload"].get("role")) for e in d["events"]])'验收要求能把一次错误对应到具体版本和事件，并分别记录测试结果、演示评测和真实评测。命令本身不是通过证据；实际执行结果以验收报告为准。
10. 故障排查
成本异常先核对调用轮次、修订次数和价格单位；耗时异常区分排队、模型、媒体与人工等待；质量下降固定资料版本和模型配置再复测。缓存命中会改变耗时，比较报告必须注明冷启动或复用情况。
11. 面试题与追问
问：怎样证明双角色评审有效？ 用标注错误集比较单次生成与复审结果，报告漏检、误报和代价。追问：演示通过能证明什么？ 只能证明已覆盖流程不变量。再追问：样本少怎么办？ 明确样本数与适用范围，逐例解释失败，不能把一次成功写成稳定生产指标。
STAR 应用：假设实验场景，R 为应核对的证据
| 对应 | S：情境 | T：目标 | A：行动 | R：验收证据 |
|---|---|---|---|---|
| 主问 | 需要验证双角色收益 | 给出可核对证据 | 用标注错误集比较漏检误报与调用代价 | 报告样本和失败例，不编造提升比例 |
| 追问一 | 演示流程全部通过 | 限定测试结论 | 将流程不变量和模型质量分开 | 不把模板结果写成真实效果 |
| 追问二 | 只有少量样本 | 避免过度泛化 | 逐例复盘并保留适用范围 | 结果注明样本量与未覆盖情形 |
这些是设计讨论的参考表达，实际执行前不能改写为已取得的历史成果。
12. 官方资料与版本
LangGraph 测试、模型优化与评测。项目 LangGraph 1.0.10；核验日期 2026-11-03。官方平台可用性与本地测试框架是不同问题，本项目评测不依赖在线评测平台。