用途：在不调用模型、不发起网络请求的前提下，衡量检索与引用契约。评估器基于显式文档 ID 比较，适合可重复的本地检查与 CI 门禁。
输入契约：每行一个 JSON 对象，含唯一字符串 id 与三个文档 ID 数组：{"id":"question-1","relevant_document_ids":["doc-a"],"retrieved_document_ids":["doc-b","doc-a"],"cited_document_ids":["doc-a"]}。空行忽略；无效 JSON、缺失数组、非字符串 ID、重复用例 ID 会报错并给出 JSONL 行号。相关性标签与引用 ID 需显式给出，不要从答案文本推断。
运行方式：设置已安装技能目录后运行仅用标准库的评估器：
SKILL_DIR="<absolute path to the installed rag-evaluation-harness skill>"
node "$SKILL_DIR/scripts/evaluate-rag.mjs" "$SKILL_DIR/examples/sample-evaluation.jsonl"
--k 3 --format markdown
用 --format json 供 CI 或下游工具使用。可选阈值（每个须在 0 到 1 之间）：--min-recall、--min-mrr、--min-context-precision、--min-citation-coverage、--min-citation-validity。全部阈值通过退出码 0，阈值失败为 1，参数或输入无效为 2；阈值失败写入 stderr，完整报告仍在 stdout。
指标解释：Recall@K 为前 K 个唯一检索 ID 中命中的相关 ID 数除以全部相关 ID；倒数排名为首个相关检索 ID 的排名倒数，未命中为 0；上下文精确率@K 为前 K 个唯一检索 ID 中相关 ID 数除以所考虑的检索 ID 数；引用覆盖率为被引用的相关 ID 数除以全部相关 ID；引用有效性为被引用且被检索到的 ID 数除以全部被引用 ID。汇总为宏平均；无相关 ID 的用例其 Recall 与引用覆盖率为 null 并排除出宏分母，其他空分母记为 0。诊断会指出空检索、缺失相关性标签、重复检索 ID、未被检索到的引用与缺失引用。
限制：这些是 ID 级代理指标，不能证明语义答案质量、蕴含、归因正确性或 groundedness；需要这些属性时应另配答案质量评估。验证可运行：node --test "$SKILL_DIR/scripts/evaluate-rag.test.mjs" 与 node scripts/validate-skills.js。评估器确定性且离线，只读取所给 JSONL，不执行检索内容、不调用 MCP 服务器、不访问凭据、不修改输入。