第十四章：Agent 知识调用质量评估

本章采用的三个治理概念

VTRCE 是本指南用 Validity、Timeliness、Relevance、Cost 与 Error Cost 五个维度裁决系统取舍的统一验证框架。

Evaluation Gate（评估门禁）是缺少指定数据集、阈值、负例或回执时阻断成熟度升级或发布声明的可检查条件。

Evidence Maturity 约束本章的表述：只有可复现运行和明确验收回执，才能从方案继续升级。

本章在全书中的角色

读完本章你能做到：用三层评估体系（检索层/生成层/业务层）量化知识库质量，设计能发现系统不知道自己不知道的对抗性测试，建立评估集保鲜机制防止 Goodhart 定律生效。

核心认知：好的评估不是把平均分做高，而是更早发现高代价错误。本章从"为什么感觉对不够用"出发，提供一套可直接落地的评估工具链。

统一评价框架：本章的所有指标最终都可以纳入附录 A 的 VTRCE 五维框架（Validity/Timeliness/Relevance/Cost/Error Cost）做跨章节统一裁决。

核心问题：你的知识库建完之后，怎么知道它真的有用？这一章给出可量化的评估方法、幻觉检测机制、以及基准测试设计原则。

验收证据门槛

验收至少需要版本化固定评估集、负例、阈值和可比较的回归回执。页面中的方法、代码和目标数字本身不能替代这些产物。

截至 2026-08-01，本章新增了一个三用例、零外部调用的最小 mock provider fixture，并能比较基线与退化候选；但它不是获授权业务评估集，也没有批准阈值、真实模型版本或最终接受回执，因此 frontmatter 继续保持 maturity: solution 与 verification: pending。

---

12.1 为什么"感觉对"不够用？

很多团队的评估方式是：问 Agent 几个问题，感觉回答不错，就上线了。

这个方法有三个根本缺陷：

1. 选择性偏差：你倾向于问自己熟悉的问题，而 Agent 最容易失败的是边界问题
2. 无法发现幻觉：LLM 生成的内容看起来永远很流畅，即使内容是错的
3. 无法追踪退化：上周还好用，这周更新了 Skill 后悄悄变差了

评估体系的第一性原理：不是"Agent 说了什么"，而是"Agent 说的内容能否被知识库的原始来源所支撑"。

---

12.2 三层评估体系

参照 2026 年 ACL Anthology 的 SoK 框架，Agent 知识调用的评估必须在三个层面同时进行：

流程图

图表接近视口时加载…

查看 Mermaid 源码

flowchart TD
    L1[Layer 1: 组件级评估<br/>每个单独的环节正确吗？]
    L2[Layer 2: 轨迹级评估<br/>整个推理链路合理吗？]
    L3[Layer 3: 系统级评估<br/>端到端结果对用户有价值吗？]

    L1 --> L2 --> L3

    subgraph L1_detail [Layer 1 组件]
        C1[检索精确度<br/>Precision@K]
        C2[幻觉检测<br/>Faithfulness Score]
        C3[Skill触发准确率<br/>Trigger Accuracy]
    end

    subgraph L2_detail [Layer 2 轨迹]
        T1[推理步骤合理性<br/>Progress Rate]
        T2[工具调用正确率<br/>Tool Use F1]
        T3[中间结果一致性<br/>Step Coherence]
    end

    subgraph L3_detail [Layer 3 系统]
        S1[任务完成率<br/>Task Success Rate]
        S2[用户满意度<br/>CSAT]
        S3[成本效率<br/>Token per Success]
    end

---

12.3 幻觉检测：最重要的评估维度

幻觉是知识库系统最危险的失效模式。Agent 说出了听起来合理但知识库里不存在的内容。

幻觉分类

类型	描述	危险级别
内在幻觉	Agent 生成的内容与检索到的上下文矛盾	[P0] 高
外在幻觉	内容听起来合理但无法在任何来源中找到	[P0] 高
引用幻觉	引用了不存在的"来源"或"研究"	[P0] 极高
数值幻觉	数字/日期/版本号不正确	[P1] 中
实体幻觉	人名/产品名/公司名不正确	[P1] 中

幻觉检测实现

class HallucinationDetector:
    """
    基于 NLI（自然语言推断）的幻觉检测
    判断 Agent 输出是否能被检索到的上下文支撑
    """

    def __init__(self):
        from openai import OpenAI
        self.llm = OpenAI()
        # 评估专用模型（必须与生成模型不同！）
        self.eval_model = "gpt-5.6"

    def check(self, query: str, context: str, response: str) -> dict:
        """
        检查 response 是否有幻觉

        Args:
            query: 用户问题
            context: 检索到的上下文
            response: Agent 的回答

        Returns:
            {
                "has_hallucination": bool,
                "faithfulness_score": float,  # 0-1，越高越好
                "unsupported_claims": list,   # 无法被 context 支撑的句子
                "severity": "none/low/medium/high"
            }
        """
        import json

        # 1. 将 response 分割为句子级别的声明
        sentences = [s.strip() for s in response.split('。') if s.strip()]

        # 2. 逐句检验是否被 context 支撑
        unsupported = []
        for sent in sentences:
            if len(sent) < 10:  # 跳过过短的句子
                continue

            resp = self.llm.responses.create(
                model=self.eval_model,
                input=[{
                    "role": "user",
                    "content": f"""判断以下声明是否能被上下文支撑。

上下文（来自知识库检索）：
{context[:2000]}

待验证的声明：
{sent}

判断标准：
- "支撑"：上下文中有直接或间接支撑这个声明的内容
- "部分支撑"：上下文暗示了这个方向，但不够明确
- "不支撑"：上下文没有提到，或与之矛盾

输出 JSON：
{{"verdict": "supported/partial/unsupported", "reason": "...", "confidence": 0.0-1.0}}"""
                }],
            )

            result = json.loads(resp.output_text)
            if result.get("verdict") == "unsupported" and result.get("confidence", 0) > 0.7:
                unsupported.append({
                    "sentence": sent,
                    "reason": result.get("reason", ""),
                    "confidence": result.get("confidence", 0),
                })

        faithfulness = 1.0 - len(unsupported) / max(len(sentences), 1)

        return {
            "has_hallucination": len(unsupported) > 0,
            "faithfulness_score": faithfulness,
            "unsupported_claims": unsupported,
            "severity": (
                "none" if faithfulness > 0.95
                else "low" if faithfulness > 0.85
                else "medium" if faithfulness > 0.7
                else "high"
            )
        }

---

12.4 基准测试设计

好的基准测试必须覆盖四类问题，缺一不可：

阈值边界

本章出现的目标分数与判定阈值全部是示意值。只有在绑定版本化数据集、模型、依赖、错误成本与审批责任人后，阈值才可以进入验收门禁。

四类测试问题设计原则

class BenchmarkDesigner:
    """
    为知识库设计四类基准测试问题
    """

    QUESTION_TYPES = {
        "factual": {
            "description": "单跳事实查找",
            "example": "什么是 Atomic Insight？",
            "evaluation": "答案是否正确且在知识库中有明确来源",
            "target_score": 0.90,
        },
        "multi_hop": {
            "description": "多跳推理",
            "example": "为什么 GraphRAG 在单跳查询上比 VectorRAG 差？",
            "evaluation": "答案是否正确连接了多个知识点",
            "target_score": 0.75,
        },
        "procedural": {
            "description": "流程/操作类",
            "example": "如何用 MinerU 处理带复杂表格的 PDF？",
            "evaluation": "步骤是否完整、可执行、有边界说明",
            "target_score": 0.85,
        },
        "adversarial": {
            "description": "对抗测试（诱饵题）",
            "example": "MinerU 能处理 MP4 视频文件吗？（答案是不能）",
            "evaluation": "Agent 是否正确拒绝/纠正错误前提",
            "target_score": 0.80,
        },
    }

    def generate_test_suite(self, skill_content: str, n_per_type: int = 5) -> list:
        """为 SKILL.md 自动生成测试套件"""
        from openai import OpenAI
        import json

        llm = OpenAI()
        all_tests = []

        for q_type, config in self.QUESTION_TYPES.items():
            resp = llm.responses.create(
                model="gpt-5.6",
                input=[{
                    "role": "user",
                    "content": f"""为以下 Skill 生成 {n_per_type} 个「{config['description']}」类型的测试问题。

Skill 内容：
{skill_content[:1500]}

要求：
1. 问题要能区分"真正理解这个Skill"和"只是模糊知道"的差异
2. 包含 1-2 个诱饵题（包含错误前提的问题）
3. 每个问题要有标准答案

输出 JSON：
{{"tests": [{{"question": "...", "expected": "...", "type": "{q_type}", "is_adversarial": false}}]}}"""
                }],
            )

            tests = json.loads(resp.output_text).get("tests", [])
            all_tests.extend(tests)

        return all_tests

---

12.5 评估仪表盘（可视化）

关键指标追踪

class EvaluationDashboard:
    """评估结果记录与展示"""

    def __init__(self, log_file: str = "eval_log.jsonl"):
        self.log_file = log_file

    def record(self, test_result: dict):
        """记录单次测试结果"""
        import json
        with open(self.log_file, 'a') as f:
            f.write(json.dumps({
                **test_result,
                "timestamp": __import__('datetime').datetime.now().isoformat()
            }, ensure_ascii=False) + '\n')

    def report(self, last_n_days: int = 7) -> dict:
        """生成评估报告"""
        import json
        from datetime import datetime, timedelta

        cutoff = datetime.now() - timedelta(days=last_n_days)
        results = []

        if not __import__('os').path.exists(self.log_file):
            return {"error": "暂无评估记录"}

        with open(self.log_file) as f:
            for line in f:
                r = json.loads(line)
                ts = datetime.fromisoformat(r["timestamp"])
                if ts > cutoff:
                    results.append(r)

        if not results:
            return {"error": f"过去 {last_n_days} 天没有评估记录"}

        # 计算关键指标
        faithfulness_scores = [r.get("faithfulness_score", 1.0) for r in results]
        task_success = [r.get("task_success", False) for r in results]
        hallucination_detected = [r.get("has_hallucination", False) for r in results]

        return {
            "period": f"过去 {last_n_days} 天",
            "total_evaluations": len(results),
            "metrics": {
                "avg_faithfulness": sum(faithfulness_scores) / len(faithfulness_scores),
                "task_success_rate": sum(task_success) / len(task_success),
                "hallucination_rate": sum(hallucination_detected) / len(hallucination_detected),
            },
            "status": "healthy" if sum(faithfulness_scores) / len(faithfulness_scores) > 0.9
                      else "warning",
        }

    def print_report(self):
        """打印人类可读的报告"""
        report = self.report()
        if "error" in report:
            print(f"[!] {report['error']}")
            return

        metrics = report["metrics"]
        status_icon = "(OK)" if report["status"] == "healthy" else "[!]"

        print(f"\n{'='*50}")
        print(f"知识库评估报告 ({report['period']})")
        print(f"{'='*50}")
        print(f"总评估次数: {report['total_evaluations']}")
        print(f"\n核心指标:")
        print(f"  忠实度 (Faithfulness):  {metrics['avg_faithfulness']:.1%} "
              f"{'(OK)' if metrics['avg_faithfulness'] > 0.9 else '[!]'}")
        print(f"  任务完成率:              {metrics['task_success_rate']:.1%} "
              f"{'(OK)' if metrics['task_success_rate'] > 0.8 else '[!]'}")
        print(f"  幻觉检出率:              {metrics['hallucination_rate']:.1%} "
              f"{'(OK)' if metrics['hallucination_rate'] < 0.1 else '[P0]'}")
        print(f"\n系统状态: {status_icon} {report['status'].upper()}")
        print(f"{'='*50}\n")

---

12.6 评估的三条铁律

铁律 1：评估模型必须与生成模型不同

LLM 自评准确率仅 46.4%（SkillLens 论文实证）。用同一个 LLM 既生成回答、又评估回答，等于用同一张嘴既说谎又判断自己是否在说谎。

# (X) 错误：用同一模型生成和评估
answer = gpt4o.generate(question)
score = gpt4o.evaluate(answer)  # 这个评分不可信

# (OK) 正确：用不同模型评估
answer = gpt4o_mini.generate(question)
score = gpt4o.evaluate(answer)  # 不同能力级别，更可信

铁律 2：幻觉检测必须在句子级别，不是文档级别

文档级别的评估会被"大部分正确"掩盖局部幻觉。一段回答中 90% 正确、10% 幻觉，如果只给一个整体分数，你永远不知道那 10% 在哪里。

铁律 3：每次知识库更新后必须跑完整基准测试

不能假设"只改了一个 Skill，其他应该没问题"。知识库中的知识是互相关联的，一个 Skill 的修改可能影响依赖它的其他 Skill 的触发逻辑。

---

12.7 与 darwin-skill 的集成

评估系统和 darwin-skill 的棘轮机制必须协同工作：

# 完整的 Skill 迭代流程（集成评估）
def skill_iteration_with_eval(skill_path: str):
    evaluator = SkillEvaluator()       # darwin-skill 9维度评估
    hall_detector = HallucinationDetector()
    benchmark = BenchmarkDesigner()
    evolver = SkillEvolver()

    skill_content = Path(skill_path).read_text()

    # 1. 生成基准测试
    tests = benchmark.generate_test_suite(skill_content)

    # 2. 运行基准测试 + 幻觉检测
    for test in tests:
        response = agent.answer(test["question"])
        hall_result = hall_detector.check(
            query=test["question"],
            context=skill_content,
            response=response
        )
        if hall_result["severity"] in ["high", "medium"]:
            logger.warning(f"[!] 发现幻觉: {test['question'][:50]}...")

    # 3. 基线评估（9维度）
    baseline_score = evaluator.evaluate(skill_content)["total_score"]
    logger.info(f"基线评分: {baseline_score:.1f}")

    # 4. 棘轮优化（只有评分提升才保留）
    for dim in SkillEvaluator.DIMENSIONS.keys():
        result = evolver.evolve_one_dimension(skill_path, dim)
        if result["improved"]:
            logger.success(f"(OK) [{dim}] 提升: {result['old_score']:.1f} → {result['new_score']:.1f}")
        else:
            logger.info(f">> [{dim}] 未提升，跳过")

    logger.success(f"Skill 迭代完成: {skill_path}")

---

## 12.8 A/B 测试框架（评估驱动迭代）

:::tip 核心原则
不靠感觉判断哪个 Prompt 或架构更好——用标准测试集 + 统计显著性检验。
:::

```python
"""ab_test_framework.py — 知识库 A/B 测试"""
import hashlib
import json
from dataclasses import dataclass, field
from pathlib import Path
from scipy import stats as scipy_stats

GOLDEN_SET = [
    {"query": "美国市场性价比高的便携充电器", "expected_category": "便携充电器", "market": "US"},
    {"query": "日本宠物智能饮水机机会分析", "expected_category": "宠物用品", "market": "JP"},
    {"query": "德国户外露营灯具市场空白", "expected_category": "户外照明", "market": "DE"},
    # ... 扩展到20个覆盖各品类×市场的标准查询
]

@dataclass
class ABResult:
    variant: str
    hits_at_5: list[bool] = field(default_factory=list)
    latencies_ms: list[float] = field(default_factory=list)

    @property
    def hit_rate(self) -> float:
        return sum(self.hits_at_5) / len(self.hits_at_5) if self.hits_at_5 else 0

    @property
    def avg_latency(self) -> float:
        return sum(self.latencies_ms) / len(self.latencies_ms) if self.latencies_ms else 0

def assign_variant(query: str, salt: str = "v1") -> str:
    """按查询的哈希值稳定分流（同一查询始终走同一变体）"""
    h = int(hashlib.md5(f"{query}{salt}".encode()).hexdigest(), 16)
    return "B" if h % 2 == 0 else "A"

def run_ab_test(search_fn_a, search_fn_b, test_set=None) -> dict:
    """运行A/B测试，返回统计结果"""
    test_set = test_set or GOLDEN_SET
    result_a = ABResult("A")
    result_b = ABResult("B")

    import time
    for item in test_set:
        query, expected = item["query"], item["expected_category"]
        variant = assign_variant(query)

        t0 = time.time()
        if variant == "A":
            results = search_fn_a(query)
            r = result_a
        else:
            results = search_fn_b(query)
            r = result_b

        latency = (time.time() - t0) * 1000
        hit = any(expected in str(res) for res in results[:5])
        r.hits_at_5.append(hit)
        r.latencies_ms.append(latency)

    # 卡方检验（命中率差异是否显著）
    a_hits, b_hits = sum(result_a.hits_at_5), sum(result_b.hits_at_5)
    a_total, b_total = len(result_a.hits_at_5), len(result_b.hits_at_5)
    _, p_value = scipy_stats.chi2_contingency([
        [a_hits, a_total - a_hits],
        [b_hits, b_total - b_hits]
    ])[:2]

    report = {
        "A命中率": f"{result_a.hit_rate:.1%}",
        "B命中率": f"{result_b.hit_rate:.1%}",
        "A平均延迟": f"{result_a.avg_latency:.0f}ms",
        "B平均延迟": f"{result_b.avg_latency:.0f}ms",
        "p值": round(p_value, 4),
        "显著差异": p_value < 0.05,
        "建议": "上线B（命中率提升显著）" if b_hits > a_hits and p_value < 0.05
                else "保持A（差异不显著）"
    }
    print(json.dumps(report, ensure_ascii=False, indent=2))
    return report

12.9 ragas 集成：自动化 RAG 质量评估

代码验证边界

最小 mock provider 评估 fixture 已覆盖成功、拒答、解析失败与退化阻断，并产出机器可比较的本地结果对象；它不安装或运行 RAGAS，不调用真实模型，也不证明本章其他片段、业务数据集或阈值已经验收。

"""ragas_eval.py — 用 ragas 评估知识库检索质量"""
# pip install ragas langchain-openai
from ragas import evaluate
from ragas.metrics import (
    faithfulness,
    answer_relevancy,
    context_recall,
    context_precision,
)
from datasets import Dataset

def build_eval_dataset(questions: list[str], search_fn, answer_fn) -> Dataset:
    """构建 ragas 所需的评估数据集"""
    data = {"question": [], "answer": [], "contexts": [], "ground_truth": []}

    for q in questions:
        contexts = search_fn(q)          # 检索结果（文本列表）
        answer = answer_fn(q, contexts)  # LLM生成回答

        data["question"].append(q)
        data["answer"].append(answer)
        data["contexts"].append(contexts)
        data["ground_truth"].append("")  # 可选：提供标准答案提升评估精度

    return Dataset.from_dict(data)

def run_ragas_eval(dataset: Dataset) -> dict:
    """运行 ragas 评估，返回四维得分"""
    result = evaluate(
        dataset,
        metrics=[faithfulness, answer_relevancy, context_recall, context_precision]
    )
    scores = {
        "忠实度（无幻觉）": round(result["faithfulness"], 3),
        "答案相关性": round(result["answer_relevancy"], 3),
        "上下文召回率": round(result["context_recall"], 3),
        "上下文精准度": round(result["context_precision"], 3),
    }
    print("ragas 评估结果:")
    for k, v in scores.items():
        status = "(OK)" if v > 0.7 else ("[!]" if v > 0.5 else "(X)")
        print(f"  {status} {k}: {v}")
    return scores

12.10 对抗性评估：主动寻找系统不知道自己不知道的盲区

好的评估体系不只测试"已知的通过场景"，还要主动设计让系统失败的用例。

对抗性测试用例的四种类型

类型一：边界溢出测试 故意问在 Skill 的 scope_out 范围之内的问题，验证系统是否会拒绝回答而不是给出错误指导。

ADVERSARIAL_BOUNDARY = [
    {
        "question": "扫描版 PDF 应该用什么工具解析？",
        "expected_behavior": "拒绝，并指引使用 OCR 流程",
        "trap": "系统可能直接推荐 MinerU，但 MinerU 的最优路径是用于排版 PDF"
    }
]

类型二：知识版本攻击 故意询问已知已更新的历史信息，验证系统是否会用过期知识回答。

类型三：合成悖论 构造两条在知识库中都存在但相互矛盾的知识，验证系统如何处理冲突，是否会假装给出一个"综合"答案而不披露矛盾。

类型四：权威诱导 用听起来权威的虚假前提提问，验证系统是否会顺着错误前提推理（而不是纠正前提）。

# 错误前提诱导测试
{
    "question": "既然 GraphRAG 的准确率比 VectorRAG 高 40%，我们是不是所有场景都应该用 GraphRAG？",
    "trap": "前提是错误的，正确系统应该先纠正前提",
    "expected_behavior": "纠正前提：GraphRAG 在事实检索上通常低于 VectorRAG"
}

---

12.11 评估集的保鲜机制

评估集一旦固定，就有被"过拟合"的风险——系统在刻意或无意间，被优化成通过这批特定问题而不是真正提升质量。

三层保鲜策略

策略一：定期轮换（每季度） 每季度替换 20-30% 的黄金问题集，用新问题取代已被反复测试的老问题。旧问题归档但不删除，用于纵向趋势追踪。

策略二：盲测隔离 主评估集与调优集严格分离。调优时使用的问题不得出现在最终评估集里，防止 Goodhart 定律生效。

策略三：用户贡献注入 每月从真实用户查询日志中随机抽取 10-20 个"有意义的失败案例"，由人工标注后加入评估集。这些来自真实使用的失败案例，比人工设计的测试用例更能代表系统的真实弱点。

def refresh_evaluation_set(current_set: list[dict],
                            query_log_path: str,
                            refresh_ratio: float = 0.25) -> list[dict]:
    """
    季度评估集刷新
    1. 归档当前评估集
    2. 从查询日志中提取失败案例
    3. 替换 refresh_ratio 比例的旧问题
    """
    archive_path = f"eval_sets/archive_{datetime.now().strftime('%Y%m')}.json"
    with open(archive_path, "w") as f:
        json.dump(current_set, f, ensure_ascii=False, indent=2)

    # 从查询日志提取低分案例（score < 0.5）
    failed_queries = []
    for line in Path(query_log_path).read_text().split("\n"):
        if not line: continue
        record = json.loads(line)
        if record.get("user_rating") == "bad" or record.get("max_similarity", 1) < 0.4:
            failed_queries.append(record["query"])

    n_replace = int(len(current_set) * refresh_ratio)
    new_questions = [
        {"question": q, "type": "user_failure", "source": "query_log",
         "added_at": datetime.now().isoformat()}
        for q in failed_queries[:n_replace]
    ]

    retained = current_set[n_replace:]
    refreshed = retained + new_questions
    print(f"评估集刷新：保留 {len(retained)} 条，新增 {len(new_questions)} 条失败案例")
    return refreshed

评估体系的元问题

你的评估指标本身也需要被评估。每半年问一次：你现在追踪的指标，还能代表你真正关心的业务结果吗？ 如果发现追踪的是"可测量的"而不是"重要的"，及时调整。

---

下一章

评估体系建立后，高频使用的 Prompt 模板和工具调用可以进一步固化——详见 第十五章：Codex Prompts 速查。

---

12.12 错误成本分层与层间归因链路

错误成本分层评估

不同层次的错误，对应完全不同的修复方向和优先级。用错误层次决定"先修哪里"比用指标绝对值更有效。

评估层	典型错误	错误成本量级	修复路径
检索层	Top-K 召回了无关文档	低（影响单次回答质量）	调整 embedding 模型或重排序参数
生成层	模型根据正确文档给出了错误结论	中（影响用户信任）	加强事实锚定，引入二次验证
业务层	正确回答但用户做出了错误决策	高（直接业务损失）	重新定义回答格式，补充决策上下文
治理层	系统以错误的方式进化（评分器漂移）	极高（系统性偏移）	回滚评分器，重建校准基准

层间归因链路

当业务结果变差时，按以下顺序归因，从最低层开始排查：

def attribute_failure(failure_case: dict) -> str:
    """
    failure_case: {
        "user_complaint": str,
        "retrieved_docs": list,
        "generated_answer": str,
        "user_action": str,
        "business_outcome": str
    }
    返回：失败发生在哪一层
    """
    # 层1：检索层检查
    doc_relevance = check_doc_relevance(
        failure_case["retrieved_docs"],
        failure_case["user_complaint"]
    )
    if doc_relevance < 0.5:
        return "retrieval_layer: 召回文档与问题不相关，需优化检索策略"

    # 层2：生成层检查
    answer_faithfulness = check_faithfulness(
        failure_case["generated_answer"],
        failure_case["retrieved_docs"]
    )
    if answer_faithfulness < 0.7:
        return "generation_layer: 答案不忠实于检索文档，存在幻觉"

    # 层3：业务层检查
    answer_usefulness = check_usefulness(
        failure_case["generated_answer"],
        failure_case["user_action"],
        failure_case["business_outcome"]
    )
    if not answer_usefulness:
        return "business_layer: 答案技术正确但对决策无帮助，需重设回答格式"

    # 层4：治理层检查（需要历史对比）
    return "governance_layer: 单案例无法判断，需要统计多个案例的趋势"

归因后的修复优先级规则

检索层失败   → 优先调参（低成本，1-2天）
生成层失败   → 加强验证机制（中成本，1-2周）
业务层失败   → 重新定义问题（高成本，需要与业务方对齐）
治理层失败   → 系统性重建（极高成本，需要回滚）

跨层归因的常见错误

不要把业务层失败当成检索层失败来修复。 提升召回率解决不了"答案正确但用户不知道怎么用"的问题。层间归因必须从底往上逐层排查，确认低层没有问题后再往上看。

验收契约

ACC-EVALUATION-001 将回答、拒答和解析失败固定为 3 个可重放用例，其中 2 个是负例。当前 mock provider 复放为 3/3、相对基线差异为 0，但它没有业务授权数据、真实模型锁定、批准阈值、具名责任接受或最终回执，因此本章继续保持 solution / pending。

Acceptance gate · schema v1.0

本地复放通过，不等于最终接受

本地可复放

1/1

已验收

0/1

本注册表只裁决知识页面能否升级为本仓库的可验收内容，不证明生产部署、法律合规、预算批准或真实模型效果。 当前复核日期 2026-08-02。

14 · Agent 知识调用质量评估ACC-EVALUATION-001审批受阻

固定集合3 例2 个负例

本地复放100%L2 · 零外部调用

基线差异0.0 pp未观察到退化

责任接受0/4最终回执缺失

固定输入与回归身份

数据集

ADS-EVALUATION-LOCAL-V1 · v1.0.0

数据边界

合成 fixture，未获业务授权

基线回执

ACR-EVALUATION-LOCAL-V1

验收范围

仅仓库内容 · productionReady=false

阈值复放与批准状态

• 用例通过率 实测 1 · ≥ 1 本地通过 · 示意阈值
• 外部调用 实测 0 · = 0 本地通过 · 示意阈值
• 外部副作用 实测 0 · = 0 本地通过 · 示意阈值

当前阻断

• DATASET_NOT_BUSINESS_AUTHORIZED数据集尚非获授权业务样本
• THRESHOLDS_NOT_APPROVED阈值仍是示意值，未获批准
• OWNER_ACCEPTANCE_INCOMPLETE四类具名责任尚未全部接受
• FINAL_RECEIPT_MISSING最终仓库内容验收回执缺失

下一证据将三用例 mock 集替换为获授权版本化业务集，批准错误成本阈值并锁定真实模型版本，由四类具名责任人签发验收回执。

查看 14 章验收上下文

关键断言与证据

4 条试点断言 · 页面状态与断言证据分开计算

L0/L1/L2 只说明登记范围；不自动代表法律合规、生产可用或整章验收。

CLM-EVAL-001来源复核

MKD Guide 的章节验收至少需要版本化固定评估集、负例、明确阈值和可比较的回归回执。

证据等级

L1 · 一手公开 / 只读观察

类型 / 风险

方法契约 · 关键

截至日期

2026-08-01

责任链

4/4 角色已映射 · 0/4 已接受

查看适用范围、限制与证据

适用范围

适用于本仓库的内容成熟度与发布门禁，不是通用行业标准声明。

限制

这是仓库治理契约；它定义需要什么证据，但不证明证据已经产生。

下一动作

把本地回归合同迁移到获授权的版本化业务评估集，并由业务责任人批准阈值与错误成本。

责任链（角色映射）

• 内容维护质量评估内容负责人角色已映射 · 待具名认领
• 证据复核评估证据复核人角色已映射 · 待具名认领
• 测试维护评估回归测试负责人角色已映射 · 待具名认领
• 最终批准质量门禁最终批准人角色已映射 · 待具名认领

角色映射只解决职责归属；具名责任人接受并留下回执前，不能据此宣称已审批。

来源

• MKD Guide content audit · content-audit.md复核于 2026-08-01
• MKD Guide VTRCE validation framework · docs/knowledge/appendix-validation.md复核于 2026-08-01

本地证据

• G0/G1 repository content audit · content-audit.mdL1 · 一手公开 / 只读观察
• VTRCE source contract · docs/knowledge/appendix-validation.mdL1 · 一手公开 / 只读观察

CLM-EVAL-002来源复核

截至 2026-08-01，本章虽有最小 mock provider fixture，但缺少获授权的版本化业务评估集、批准阈值、真实模型回执和最终接受回执，因此仍不是可验收状态。

证据等级

L1 · 一手公开 / 只读观察

类型 / 风险

当前状态 · 关键

截至日期

2026-08-01

责任链

4/4 角色已映射 · 0/4 已接受

查看适用范围、限制与证据

适用范围

只描述当前仓库快照。

限制

本地三用例 fixture 只能证明回归合同可执行；后续数据、模型或批准状态变化时必须由门禁重新计算。

下一动作

由具名责任人接受角色，补获授权业务数据集、批准阈值、真实模型回执与最终接受证据后再审计。

责任链（角色映射）

• 内容维护质量评估内容负责人角色已映射 · 待具名认领
• 证据复核评估证据复核人角色已映射 · 待具名认领
• 测试维护评估回归测试负责人角色已映射 · 待具名认领
• 最终批准质量门禁最终批准人角色已映射 · 待具名认领

角色映射只解决职责归属；具名责任人接受并留下回执前，不能据此宣称已审批。

来源

• MKD Guide content audit · content-audit.md复核于 2026-08-01

本地证据

• G0/G1 repository content audit · content-audit.mdL1 · 一手公开 / 只读观察

CLM-EVAL-003来源复核

本章出现的目标分数和判定阈值在绑定数据集、模型、版本与审批前全部属于示意值。

证据等级

L1 · 一手公开 / 只读观察

类型 / 风险

控制要求 · 高

截至日期

2026-08-01

责任链

4/4 角色已映射 · 0/4 已接受

查看适用范围、限制与证据

适用范围

适用于本章所有未被独立证据登记的阈值。

限制

该标注防止误用，但没有验证任何阈值对真实业务错误成本是否合适。

下一动作

用固定数据集做阈值敏感性分析并由业务责任人批准错误成本边界。

责任链（角色映射）

• 内容维护质量评估内容负责人角色已映射 · 待具名认领
• 证据复核评估证据复核人角色已映射 · 待具名认领
• 测试维护评估回归测试负责人角色已映射 · 待具名认领
• 最终批准质量门禁最终批准人角色已映射 · 待具名认领

角色映射只解决职责归属；具名责任人接受并留下回执前，不能据此宣称已审批。

来源

• MKD Guide content audit · content-audit.md复核于 2026-08-01
• MKD Guide VTRCE validation framework · docs/knowledge/appendix-validation.md复核于 2026-08-01

本地证据

• G0/G1 repository content audit · content-audit.mdL1 · 一手公开 / 只读观察

CLM-EVAL-004Fixture 验证

仓库内最小 mock provider 评估 fixture 已覆盖有证据回答、证据不足拒答、解析失败和候选退化阻断，并生成机器可比较的本地结果对象。

证据等级

L2 · Fixture / Dry-run

类型 / 风险

当前状态 · 高

截至日期

2026-08-01

责任链

4/4 角色已映射 · 0/4 已接受

查看适用范围、限制与证据

适用范围

适用于本章当前 Markdown 代码块。

限制

该 fixture 不安装或运行 RAGAS，不调用真实模型，也不证明本章其他代码片段、业务数据集或阈值已经验收。

下一动作

具名责任人认领后，锁定 RAGAS 与模型版本，在获授权数据集上复放相同路径并保存独立回执。

责任链（角色映射）

• 内容维护质量评估内容负责人角色已映射 · 待具名认领
• 证据复核评估证据复核人角色已映射 · 待具名认领
• 测试维护评估回归测试负责人角色已映射 · 待具名认领
• 最终批准质量门禁最终批准人角色已映射 · 待具名认领

角色映射只解决职责归属；具名责任人接受并留下回执前，不能据此宣称已审批。

本地证据

• Deterministic mock-provider evaluation fixture · fixtures/evaluation-regression.mjsL2 · Fixture / Dry-run
• Evaluation regression Node tests · tests/content/evaluation-regression.test.mjsL2 · Fixture / Dry-run

来源与复核

• 本轮接口核对（截至 2026-08-01）：OpenAI Responses API quickstart；评估阈值仍需固定数据集与负例回归支持。
• 复核状态：待复核。任何易漂移的版本、价格、法律或性能结论，采用前都必须回到一手来源再次确认。
• 代码状态：混合边界。fixtures/evaluation-regression.mjs 及其测试为 L2 本地 fixture；RAGAS、真实模型与其余评估片段仍是示意代码。
• 证据边界：本页成熟度只描述内容形态，不代表部署、上线或生产验收已经完成。
• 下一验收动作：具名角色接受责任后，用获授权的版本化数据集、批准阈值和锁定模型复放同一回归合同。