幻觉检测模块（hallucin）

memex.hallucin 是 2026-07 新增的异步幻觉治理模块，负责 Wiki 页面的幻觉检测、分析和修复任务调度。

设计原则

引擎与 Harness 的分工

层	职责
引擎（MEMEX_ROOT）	定义 W7 幻觉控制框架（H1-H5 分类）、提供 gene（QUO/FIX/COR）、工具脚本（corpus_search.py、check_citations.py、pn_format_lint.py）、PN 索引（pn-source.json）
Harness（memex.hallucin）	异步触发检测、编排引擎工具调用、路由发现到修复队列、管理两层检测流水线

引擎零改动：信号来源是引擎已写的 actions.jsonl，Harness 只读不改引擎文件。

确定性优先

零 token 确定性层（秒级）─────────────────── 只把灰色地带交 LLM
       ↓                                              ↓
  check_citations.py     coverage 0.1~0.3 → /hallucin-sweep skill
  pn_format_lint.py         （UNCERTAIN）        （按需触发）
  pn-source.json 覆盖率

最严重的幻觉（coverage < 0.1，几乎无关键词命中）被确定性层直接抓住，LLM 只处理模糊地带。

异步解耦

主建站流程（grow/butler 建页）不等待幻觉检测，检测通过队列文件异步执行，不阻塞建站速度。

架构

引擎                          Harness（memex-server）
───────────────────────────   ──────────────────────────────────────
grow/butler 建页
└─ record_action.py →
   logs/butler/actions.jsonl  ←── HallucinQueue.harvest_from_actions()
   （引擎已写，Harness 读）          ↓ 攒批 N 页
                                  logs/harness/hallucin_pending.jsonl
                                        ↓ scheduler_tick
                                  HallucinSweep.run()（零 LLM）
                                  ├─ CitationScanner → check_citations.py
                                  ├─ PnScanner → pn_format_lint.py
                                  └─ Quo23Scanner → pn-source.json 覆盖率
                                        ├─ coverage < 0.1
                                        │   → citation_issues.jsonl（CRITICAL）
                                        │   → queue.md P2（FIX9/COR9）
                                        └─ 0.1~0.3 UNCERTAIN
                                            → hallucin_deep_pending.jsonl
                                                ↓ run_deep()（按需）
                                        /hallucin-sweep skill（LLM）
                                        └─ confirmed → queue.md P2
                                        └─ cleared → 误报，放行

两层检测详解

Phase 1：确定性层（零 LLM）

三个检测器依次运行，全部通过则跳过 Phase 2：

CitationScanner

调用引擎 check_citations.py，验证 blockquote 可在语料中搜到原文（字符级模糊匹配）。

产出分类：FABRICATED（无命中）/ NEAR_MATCH（内容被改写）/ WRONG_PN（PN 偏移）

PnScanner

调用引擎 pn_format_lint.py，检测 PN 格式错误（括号类型/多PN合并等）。

产出：FORMAT_ERROR

Quo23Scanner

直接读引擎产物 data/pn-source.json，对每个行内 PN 断言计算关键词覆盖率：

关键词覆盖率 = 断言中出现在 PN 原文段的 token 数 / 断言总 token 数
（token = CJK 单字 + 3字母以上英文词）

coverage < 0.10  → NOT_IN_CORPUS（确定性幻觉，直接标红）
0.10 ≤ coverage < 0.30  → UNCERTAIN（路由到 deep queue 等 LLM 复核）
coverage ≥ 0.30  → OK，跳过

Phase 2：LLM 语义深核（按需）

仅当 hallucin_deep_pending.jsonl 有 uncertain 条目时触发，调用 /hallucin-sweep skill。

每个 UNCERTAIN 条目已预取语料段（passage 字段），LLM 只做二元判断：

confirmed：断言核心语义在语料段中无支撑 → 升级为幻觉，写 P2 修复任务
cleared：合理概括/同义替换 → 误报，放行

修复闭环

citation_issues.jsonl（status=open）
    ↓ RepairWriter
queue.md P2（FIX9 / COR9 / QUO24 / FIX10…）
    ↓ butler 下一轮接力执行
    ↓ HallucinSweep.verify_repaired()
citation_issues.jsonl（status=fixed）

RepairWriter 直接使用引擎 gene 代码作为任务动词（如 COR9-offline-citation-integrity），butler 读 queue.md 时直接执行，无需额外映射。

队列文件布局

所有队列文件位于 wiki 目录内，Harness 写，引擎不感知：

logs/harness/
├─ hallucin_pending.jsonl      # 待确定性扫描的页面（HallucinQueue）
├─ hallucin_watermark.json     # actions.jsonl 读取水位线
└─ hallucin_deep_pending.jsonl # 待 LLM 语义复核的断言（HallucinDeepQueue）

logs/butler/
└─ citation_issues.jsonl       # 检测产物（W7 H1 标准格式，与引擎共享）

扩展点

新增检测器

继承 PageScanner，实现 name 和 scan()，注册到 ScannerRegistry：

class MyScanner(PageScanner):
    name = "my_check"
    def scan(self, slug: str, wiki_dir: Path) -> list[ScanFinding]: ...

DEFAULT_SCANNERS.register(MyScanner())

补全 H2-H5

W7 框架预留了 H2（事实一致性）、H3（实体真实性）、H4（时间一致性）、H5（结构性幻觉），IssueType 已有对应枚举槽位，新增对应 scanner 即可接入流水线。

文件	说明
`src/memex/hallucin/`	幻觉检测模块主目录
`src/memex/agent/hallucin.py`	job 入口（确定性 + LLM 深核）
`config/harness/hallucin-sweep/SKILL.md`	LLM 深核 skill 定义
`src/memex/api/scheduler.py`	`sweep_hallucin_queue()` 调度集成点
`MEMEX_ROOT/skills/SKILL_W7_Butler幻觉控制.md`	引擎幻觉控制框架（H1-H5 分类）
`MEMEX_ROOT/wiki/scripts/butler/check_citations.py`	引擎 H1 出处核验脚本
`MEMEX_ROOT/wiki/scripts/butler/pn_format_lint.py`	引擎 PN 格式检查脚本

设计原则​

引擎与 Harness 的分工​

确定性优先​

异步解耦​

架构​

两层检测详解​

Phase 1：确定性层（零 LLM）​

CitationScanner​

PnScanner​

Quo23Scanner​

Phase 2：LLM 语义深核（按需）​

修复闭环​

队列文件布局​

扩展点​

新增检测器​

补全 H2-H5​

相关文件​