feat: 完成 issue #47 Prompt 版本管理 + 幻觉校验中间件（版本库联动 + 评测报告脚本）

core/llm-gateway/hallucination.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""iAOP-Core · LLM 网关 —— 幻觉/事实性校验中间件（EPIC #6 主体，Issue #47 雏形）。
+"""iAOP-Core · LLM 网关 —— 幻觉/事实性校验中间件（Issue #47 完成交付）。
 
 对应 PRD 5.4「④ LLM 网关 + RAG」：
 - **事实性校验**：RAG 答案强制**引用溯源**（返回命中文档片段+来源）；
@@ -12,12 +12,13 @@
   （无源引用 = 幻觉嫌疑）；
 - **信度阈值**：对高利害输出（处置建议 / 报警解释）要求信度 ≥ 阈值，
   低于阈值返回 `human_review`（转人工确认，PRD 5.4 异常时转人工）；
-- **评测集检验**：`evaluate()` 对 (prompt, answer, expected_sources) 样本
-  批量评估事实一致性（供"定期评测"脚本调用）。
-
-设计说明（供子任务 #47 继续细化）：
-- 本版实现校验核心（溯源 + 信度阈值 + 评测入口）；
-- 子任务 #47 将在此基础上补齐与 Prompt 版本库的联动与评测报告脚本。
+- **与 Prompt 版本库联动**：`check()` / `evaluate()` 可携带
+  `prompt_name` / `prompt_version`（运行时绑定，可复现），评测报告按
+  `name@version` 分解——Prompt 变更后可用同一评测集对比各版本事实一致性，
+  定位"版本升级导致幻觉率上升"（PRD 5.4 定期评测）；
+- **评测报告**：`evaluate()` 产出结构化报告，`render_evaluation_report()`
+  渲染 Markdown 报告，配套 CLI 脚本 `evaluate_hallucination.py`
+  （评测集 JSON + 版本库配置 → 报告文件）。
 
 测试：`python -m unittest discover -s tests -v`（在 core/llm-gateway 目录下执行）。
 """
@@ -43,6 +44,8 @@ class GuardVerdict:
     threshold: float                   # 本次校验使用的信度阈值
     action: str                        # pass / human_review / unsupported
     missing_sources: List[str] = field(default_factory=list)
+    prompt_name: Optional[str] = None  # 生成本次答案的 Prompt 模板名（版本库联动）
+    prompt_version: Optional[str] = None  # 运行时绑定的模板版本（可复现）
     verdict_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
     created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
 
@@ -55,6 +58,8 @@ class GuardVerdict:
             "threshold": self.threshold,
             "action": self.action,
             "missing_sources": self.missing_sources,
+            "prompt_name": self.prompt_name,
+            "prompt_version": self.prompt_version,
             "answer": self.answer,
         }
 
@@ -77,8 +82,14 @@ class HallucinationGuard:
     def check(self, answer: str, sources: Sequence[str],
               confidence: float = 1.0,
               high_stakes: bool = False,
-              threshold: Optional[float] = None) -> GuardVerdict:
-        """校验一条模型输出。返回结论（不修改输出，由调用方决定如何处置）。"""
+              threshold: Optional[float] = None,
+              prompt_name: Optional[str] = None,
+              prompt_version: Optional[str] = None) -> GuardVerdict:
+        """校验一条模型输出。返回结论（不修改输出，由调用方决定如何处置）。
+
+        `prompt_name` / `prompt_version`：生成本次答案的 Prompt 模板与其
+        运行时绑定版本（与 PromptRegistry 联动，可复现，随审计落库）。
+        """
         th = threshold if threshold is not None else self.default_threshold
         # 1) 引用溯源：输出中声明的来源必须真实存在
         declared = _SOURCE_REF_RE.findall(answer)
@@ -97,40 +108,165 @@ class HallucinationGuard:
         verdict = GuardVerdict(
             answer=answer, supported=supported, confidence=confidence,
             threshold=th, action=action, missing_sources=missing,
+            prompt_name=prompt_name, prompt_version=prompt_version,
         )
         self._audit.append(verdict.to_dict())
         return verdict
 
     # -- 评测集检验（定期事实一致性评测入口） ------------------------------
 
-    def evaluate(self, samples: List[Dict[str, object]]) -> Dict[str, object]:
-        """批量评估事实一致性。
+    def evaluate(self, samples: List[Dict[str, object]],
+                 registry: Optional[object] = None,
+                 threshold: Optional[float] = None) -> Dict[str, object]:
+        """批量评估事实一致性，产出结构化评测报告。
 
-        `samples`：`[{"answer", "sources", "confidence", "high_stakes"}, ...]`。
-        返回支持率 / 人工复核率 / 未支持率。子任务 #47 将扩展为评测报告。
+        `samples`：`[{"answer", "sources", "confidence", "high_stakes",
+        "prompt_name", "prompt_version"}, ...]`；
+        `registry`：`PromptRegistry`（可选）——与 Prompt 版本库联动：
+        - 样本带 `prompt_name` 时，按 `prompt_version`（缺省取当前默认版本）
+          解析为 `name@version`，报告按此分解，便于对比各版本事实一致性；
+        - 版本库中不存在该模板时，样本记录 `prompt_error` 而非中断评测。
+
+        返回：`total` / `supported_rate` / `human_review_rate` /
+        `unsupported_rate`，以及 `prompts`（按 `name@version` 分解的明细，
+        无 prompt 样本时为 `{}`）与 `samples`（逐样本记录）。
         """
         total = len(samples)
+        base: Dict[str, object] = {"total": total}
         if total == 0:
-            return {"supported_rate": 0.0, "human_review_rate": 0.0, "total": 0}
+            base.update({"supported_rate": 0.0, "human_review_rate": 0.0,
+                         "unsupported_rate": 0.0, "prompts": {},
+                         "samples": []})
+            return base
+
+        per_prompt: Dict[str, Dict[str, object]] = {}
+        sample_records: List[Dict[str, object]] = []
         supported = 0
         human = 0
         for s in samples:
+            answer = str(s.get("answer", ""))
+            sources = [str(x) for x in s.get("sources", [])]
+            confidence = float(s.get("confidence", 1.0))
+            high_stakes = bool(s.get("high_stakes", False))
+            name = s.get("prompt_name")
+            version = s.get("prompt_version")
+            prompt_error: Optional[str] = None
+            label: Optional[str] = None
+
+            # 与 Prompt 版本库联动：解析运行时绑定版本（可复现）
+            if name and registry is not None:
+                try:
+                    if version is None:
+                        version = registry.current(str(name)).version
+                    else:
+                        registry.get(str(name), str(version))  # 校验存在性
+                    label = f"{name}@{version}"
+                except (KeyError, ValueError) as exc:
+                    prompt_error = f"{exc}"
+                    label = f"{name}@unknown"
+
             v = self.check(
-                answer=str(s.get("answer", "")),
-                sources=[str(x) for x in s.get("sources", [])],
-                confidence=float(s.get("confidence", 1.0)),
-                high_stakes=bool(s.get("high_stakes", False)),
+                answer=answer, sources=sources, confidence=confidence,
+                high_stakes=high_stakes, threshold=threshold,
+                prompt_name=str(name) if name else None,
+                prompt_version=str(version) if version else None,
             )
             if v.supported:
                 supported += 1
             if v.action == "human_review":
                 human += 1
-        return {
+
+            if label is not None:
+                group = per_prompt.setdefault(label, {
+                    "total": 0, "supported": 0, "human_review": 0,
+                    "missing_sources": [],
+                })
+                group["total"] += 1
+                if v.supported:
+                    group["supported"] += 1
+                if v.action == "human_review":
+                    group["human_review"] += 1
+                if v.missing_sources:
+                    group["missing_sources"].extend(v.missing_sources)
+
+            record = {
+                "answer": answer, "action": v.action, "supported": v.supported,
+                "confidence": confidence, "prompt": label,
+                "missing_sources": v.missing_sources,
+            }
+            if prompt_error:
+                record["prompt_error"] = prompt_error
+            sample_records.append(record)
+
+        # 补齐每组未支持数（total - supported 中可能含 human_review）
+        for g in per_prompt.values():
+            g["unsupported"] = g["total"] - g["supported"]
+            g["supported_rate"] = round(g["supported"] / g["total"], 4)
+            g["human_review_rate"] = round(g["human_review"] / g["total"], 4)
+            g["unsupported_rate"] = round(g["unsupported"] / g["total"], 4)
+
+        base.update({
             "supported_rate": round(supported / total, 4),
             "human_review_rate": round(human / total, 4),
             "unsupported_rate": round((total - supported) / total, 4),
-            "total": total,
-        }
+            "prompts": per_prompt,
+            "samples": sample_records,
+        })
+        return base
+
+    # -- 评测报告渲染 ------------------------------------------------------
+
+    def render_evaluation_report(self, report: Dict[str, object]) -> str:
+        """把 `evaluate()` 的结构化报告渲染为 Markdown 文本（评测报告脚本用）。"""
+        total = int(report.get("total", 0))
+        lines: List[str] = [
+            "# LLM 网关 · 幻觉/事实性校验评测报告",
+            "",
+            f"- 生成时间：{datetime.now(timezone.utc).isoformat(timespec='seconds')}",
+            f"- 样本总数：{total}",
+        ]
+        if total:
+            lines.append(
+                "- 支持率 {:.1%}｜人工复核率 {:.1%}｜未支持率 {:.1%}".format(
+                    float(report.get("supported_rate", 0.0)),
+                    float(report.get("human_review_rate", 0.0)),
+                    float(report.get("unsupported_rate", 0.0)),
+                )
+            )
+        lines.append("")
+
+        prompts = report.get("prompts") or {}
+        if prompts:
+            lines += [
+                "## 按 Prompt 版本分解",
+                "",
+                "| Prompt@版本 | 样本数 | 支持数 | 支持率 | 人工复核 | 未支持 |",
+                "|---|---|---|---|---|---|",
+            ]
+            for label in sorted(prompts):
+                g = prompts[label]
+                lines.append(
+                    "| {} | {} | {} | {:.1%} | {} | {} |".format(
+                        label, g["total"], g["supported"],
+                        float(g["supported_rate"]), g["human_review"],
+                        g["unsupported"],
+                    )
+                )
+            lines.append("")
+
+        bad = [r for r in report.get("samples", [])
+               if r.get("action") in ("unsupported", "human_review")]
+        if bad:
+            lines += ["## 未通过样本明细", ""]
+            for i, r in enumerate(bad, 1):
+                prompt = r.get("prompt") or "（未关联 Prompt 版本）"
+                lines.append(
+                    f"{i}. **[{r['action']}]** {prompt}\n"
+                    f"   - 答案：{r['answer']}\n"
+                    f"   - 缺失来源：{r.get('missing_sources') or '—'}"
+                )
+            lines.append("")
+        return "\n".join(lines)
 
     # -- 审计 --------------------------------------------------------------