本文说明：当扫描结果出现“识别幻觉/误判/无证据结论”时，如何定位问题并逐步调优。
- 缺少文件误判：明明目录里有文件，却被判定“缺少目标交付物文件”
- 错配文件：规则命中了明显不相关的文件（例如测试报告命中迁移方案）
- 内容误判：结论不符合但证据摘录与原因对不上，或证据为空
- 过度推断：模型输出了文件中不存在的内容/结论/数据
扫描链路可以拆成 4 段：
- 项目编号/阶段识别（文件归属是否正确）
- 候选文件推导（规则应该检查哪些文件）
- 正文提取（候选文件是否能提取到有效文本）
- 大模型判断（结论/原因/证据是否可复核）
你看到的“幻觉”，通常来自 2/3/4 任意一段不稳。
- 补充交付物信号：在检查要点中写清《交付物名称》或“必须提供/需提交/交付”
- 限定后缀：用
.docx,.xlsx等降低误匹配空间 - 降低歧义：一个规则只检查一个交付物/一个主题
- 不需要内容的检查改为
scope=文件名（存在性/签字盖章/命名规范等）
效果：减少候选集，减少模型自由发挥空间，是性价比最高的调优手段。
缺少文件的判定优先基于后端候选推导接口 /api/scan/candidates。
排查步骤：
- 看规则是否设置了不合理的阶段/后缀（导致阶段过滤后没有文件，或后缀过滤后为空）
- 看命名技能是否命中：如果规则要点较泛，命名/关键词推导会不稳定
调优手段：
- 在要点中用《...》明确交付物名称（会触发更严格的缺失口径）
- 给规则加后缀或补充更明确的关键词
- 对企业特有命名，扩充后端
NAMING_SKILL（关键词 → 命名模式）
错配通常是候选推导阶段没有足够的“互斥知识”，导致把同阶段文件误当目标交付物。
调优手段（推荐在 fork 仓库里做）：
- 在后端
forbidden_overlap(rule_text, file_text)增加互斥对（规则关键词 vs 文件关键词） - 在
allow_file_for_rule(file_text)增加行业/企业特有的文件类别约束
原则：越早排除，越不依赖大模型，越稳定。
如果候选文件存在，但“正文不可读”，内容检查无法执行，就容易出现不稳定输出。
排查与调优：
- 优先检查后端
/api/extract/text是否可用、依赖是否安装齐全（pdf/docx/xlsx 等） - 对扫描对象控制：大文件/图片型 PDF 往往难提取，必要时改为
scope=文件名或要求提供可检索版本
可复核的基本要求是：reason 与 evidence 一致，且 evidence 能在文件中定位。
调优手段：
- 在规则提示词中强制：不允许无证据结论；证据必须包含文件名与原文摘录
- 保持温度为 0（本系统默认 0），减少随机性
- 控制上下文：候选文件数量与每个文件内容长度要有限（本系统已做截断）
- 先定位是哪一类问题：缺少文件/错配/提取失败/结论不可复核
- 优先用“规则层调优”：补交付物名、补后缀、改 scope
- 再用“匹配层调优”：扩充命名技能库、增加互斥规则
- 最后再用“提示词层调优”：强调证据、禁止无证据推断