用途：rag-eval 用于调优 RAG 流水线，替代“改一改、眯眼看、换模型、烧额度”的循环。它通过单条命令在用户的金标集上运行一组评测变体，按成本感知评分排序，并返回关于架构、技术栈和可能问题的结构化反馈，同时参考基于证据的 RAG 实践并从历史运行中学习。
触发场景：用户提出“帮我测试 RAG”“调优我的 RAG”“我的 RAG 效果差”“比较检索提示词”“怎么做评测”“X 用哪个嵌入模型最好”“RAG 评测太贵”，或报告在 OpenRouter/OpenAI 上烧额度却看不到改进信号时。
运行前需收集：RAG 代码库根路径；至少 10 组问答对的金标集（缺失时可提议从数据集生成起始金标集，由 LLM 合成、人工复核）；检索所用数据集；每次运行的硬性预算上限（未指定默认 2 美元，运行前必须确认）；OPENROUTER_API_KEY 或 OPENAI_API_KEY（从环境变量读取）；向量库配置（集合名、嵌入模型、分块大小，从仓库读取，含糊时确认）；可选评测历史路径，默认仓库根目录下 .rag-eval/history.jsonl。
工作流：可选先摄取既往会话，运行 python scripts/session_ingest.py <session_id> 或 python scripts/session_ingest.py --path /path/to/transcript.jsonl，仅做正则提取，输出紧凑 JSON，避免把原始长转录喂给模型。随后审计技术栈，检查仓库与向量库配置，产出架构、技术栈、资源与风险报告。再提出 3–8 个变体的扫描计划，首次保持小网格（默认 2 提示词 × 2 模型 × 1 检索变体 = 4 格），估算成本并等待用户确认。之后用 scripts/eval_sweep.py 读取配置 YAML 运行扫描，记录每个变体的成本与答案质量并追加到 history.jsonl。最后按质量 × (1 / log(1 + 成本)) 排序，给出前三名、与上次最佳的差异及下一步实验，完整报告写入 .rag-eval/reports/<timestamp>.md。后续运行前读取 history.jsonl，避免重复测试已被否决的变体，并总结模式。
限制与护栏：成本是主要失败模式，未确认预算不得运行，达到上限即中止；不得修改用户仓库，所有产物写入 .rag-eval/ 并加入 gitignore；改动目标仓库任何文件前必须确认；不确定最佳实践时可做网络检索。可复用资源包括 scripts/eval_sweep.py、references/best-practices.md、references/evidence-base.md、assets/eval_config.template.yaml 与 assets/gold_set.template.jsonl。