AUAggy/hallcheck

# hallcheck `hallcheck` 是一个用于在 PDF 报告中查找幻觉引用的命令行工具。 它只解决一个狭隘的问题：被引用的来源是否存在？它不判断报告中的每一个断言是否真实。 ## 为何存在 引用是一个小小的信任机器。它告诉读者："你不必只信我的话。来源就在那里。" 当来源不存在时，这种信任就破裂了。 咨询报告、安全简报、政策文件和人工智能辅助的白皮书经常引用普通网页而非稳定的学术标识符。一个虚假的引用可能看起来很真实，因为出版商存在、作者存在，URL 的格式也正确。 [GPTZero 对 Ernst & Young Canada 网络安全报告的调查](https://gptzero.me/news/investigations/ey) 清楚地展示了这种模式：虚假的福布斯文章、不存在的麦肯锡报告、失效的 URL，以及从其他人工智能生成的文本中回收的参考文献。 这不仅仅是开发者的问题。不准确的引用会影响新闻业、安全研究、法律审查、政策工作和内部风险决策。 `hallcheck` 将这种审计转变为本地工具。它从 PDF 中提取引用 URL，根据公共证据进行检查，并记录每个判定的原因。 该工具生成 SQLite、JSON、Markdown 和自包含的 HTML 卷宗。这使得审计师、记者、研究人员和内部审查团队都能用得上。 幻觉检测器本身也需要是可审计的。公开代码让人们能够阅读评分逻辑、防护措施、证据处理和限制条件。一个封闭的检测器要求用户"信任检测器"，这重复了同样的信任问题。 现有工具大多专注于学术引用、期刊标识符、arXiv 记录或广泛的断言验证。`hallcheck` 则针对咨询报告和网页引用审计：裸 URL、发布者名称、标签页面、付费墙和看似合理的文章路径。 误报是主要风险。更多人关注规则、阈值和边缘情况，应该能比私密开发更快地发现脆弱的假设。 难点在于文档多样性和真实标签。公开仓库为人们提供了一个贡献报告、边缘案例和修正的地方。 ## 试图解决什么问题 伪造的引用肉眼难以识别。标题听起来正常。出版商是熟悉的。URL 甚至可能使用了一个真实的域名。 安全的应对方式不是询问另一个模型报告是否感觉真实。安全的应对方式是检查证据： - URL 是否能解析？ - 它是否重定向到了其他地方？ - 它是否被付费墙屏蔽或阻止了？ - 引用的标题在搜索结果中能找到吗？ - URL 的主机名是否与声称的出版商匹配？ - 路径看起来像一个真实的文章，还是只是一个主页或标签页面？ - Wayback Machine 有没有记录过这个 URL？ `hallcheck` 的范围限定在引用是否存在，因为这个问题有证据可循。它避免一般性的真理检测，不做出最终的法律或编辑判断，并将不确定性视为一个真实的结果。 它明确说明了自己不做哪些事情： - 不做一般性的真理检测 - 不做断言验证 - 不做引文验证 - 不做最终的法律或编辑判断 - 不保证校准语料库中的每一篇公共报告引用都有效 这降低了过度宣称的风险。 ## 工作原理 v1 流程有意设计得很小： ``` PDF -> citation URLs -> URL check -> Wayback -> title search -> publisher check -> score -> guardrails -> reports ``` 对于每个引用，`hallcheck` 会记录它使用的证据。HTTP 状态码、重定向目标、响应哈希值、搜索查询、时间戳和验证信号都会写入 SQLite 和 JSON。 分类器是保守的。单单一个失效的 URL 不足以判定为 `HALLUCINATED`。 一个 `HALLUCINATED` 判定需要： - 加权得分 >= 0.7 - 至少 3 个独立的阳性信号 - 无误报中止开关 付费墙、机器人屏蔽、链接失效和搜索失败通常会变成 `UNVERIFIABLE`。这是故意的。 ## 为什么不直接让 AI 来判断引用？ 因为核心产品不是"问一个 AI 另一个 AI 是否产生了幻觉"。那样很快会变成循环论证。 这里最有力的证据是枯燥的证据： - URL 返回 404。 - 找不到该标题。 - 出版商路径是一个标签页面。 - 引用的 URL 指向一个不同的主题。 - Wayback 没有该来源的记录。 - 付费墙或机器人屏蔽阻止了做出安全判定。 这些证据是可复现的。如果 `hallcheck` 指控一份报告使用了幻觉引用，该报告需要提供凭据：HTTP 跟踪、搜索查询、响应哈希值、时间戳，以及触发的确切信号。 当问题是语义性的但范围有限时，LLM 是有用的： - 这两个标题指的是同一篇文章吗？ - 这个 URL 路径段是否与声称的标题匹配？ - 这些收集到的搜索结果是否支持所声称的引用？ - 这些收集到的结果是否支持这个署名指的是同一个人？ 当问题范围广泛时，它们就是有风险的： - 这个来源真实吗？ - 这个断言是真的吗？ - 这个作者在那里工作过吗？ 模型可能会凭记忆自信地回答，而这正是 `hallcheck` 试图检测的失败模式。 因此，v1 保留了基于规则的核心。AI 只用于狭窄的灰色地带，并且提示词可以与工具已收集的证据相关联。 ## 判定结果 | 判定 | 含义 | | :--- | :--- | | `VERIFIED` | 该引用具有活跃或强合法性信号。 | | `UNVERIFIABLE` | 工具无法安全判定。付费墙、机器人屏蔽和链接失效通常归入此类。 | | `SUSPECT` | 部分信号表明引用有问题，但不足以称之为幻觉。 | | `HALLUCINATED` | 多个独立信号表明该引用是伪造或严重"洗稿"的。 | ## 产出 每次扫描都会生成一个小型证据包： ``` ./hallcheck-reports// ├── report.json ├── report.md ├── report.html └── raw/ ``` `report.json` 是规范的机器可读报告。 `report.html` 是一个自包含的卷宗。它包含内联 CSS，无外部资源，带有证据抽屉和打印样式。 SQLite 证据数据库默认存放于此： ``` ~/.local/share/hallcheck/hallcheck.db ``` ## 安装 需要 Go 1.24 或更新版本以及 Poppler 的 `pdftotext`。 macOS： ``` brew install poppler go install github.com/AUAggy/hallcheck/cmd/hallcheck@latest ``` Ubuntu 或 Debian： ``` sudo apt-get install poppler-utils go install github.com/AUAggy/hallcheck/cmd/hallcheck@latest ``` 从检出代码构建： ``` make build ./bin/hallcheck version ``` ## 扫描 PDF ``` hallcheck scan report.pdf ``` 从检出代码运行： ``` ./bin/hallcheck scan report.pdf ``` 扫描后打开 HTML 报告： ``` ./bin/hallcheck scan report.pdf --open ``` 仅写入 JSON 和 HTML： ``` ./bin/hallcheck scan report.pdf --formats json,html ``` 将报告写入其他位置： ``` ./bin/hallcheck scan report.pdf --reports-dir ./reports ``` 使用不同的 SQLite 数据库： ``` ./bin/hallcheck scan report.pdf --db ./hallcheck.db ``` ## Venice API 密钥 大多数扫描不需要调用 LLM。Venice 仅在标题匹配落入模糊灰色地带时使用。 如果希望启用该路径，请设置密钥： ``` export VENICE_API_KEY=... ``` v1 仅支持 Venice。模型为 `deepseek-v4-pro`。 ## 校准 `calibrate` 是为维护者和贡献者准备的。普通用户不需要。 运行当前语料库： ``` ./bin/hallcheck calibrate --dataset tests/calibration ``` 该语料库结合了一份手工标注的幻觉 EY 文档和弱的、预设为干净的公共报告。这些公共报告标签对于捕获错误的 `HALLUCINATED` 判定很有用，但它们不是经过手工验证的真值。 校准使用实时网络检查，因此当搜索引擎、出版商或 archive.org 对运行进行速率限制时，精确数字可能会有所不同。 ## 技术栈 - Go 1.24+ - Cobra 用于命令行界面 - SQLite 使用 `modernc.org/sqlite` - Poppler 的 `pdftotext -layout` 用于 PDF 文本提取 - DuckDuckGo HTML 搜索使用 `goquery` 解析 - Venice `deepseek-v4-pro` 用于罕见的标题匹配灰色地带 v1 中没有 Python 运行时，没有 Docker 要求，也没有备用的 LLM 提供商。 ## 已知限制 - 仅支持 PDF 输入。Markdown 伴随文件用于校准固定数据。 - 工具验证 URL 引用。它不验证无支持的断言或引文。 - 有些 PDF 没有可提取的引用 URL。它们会产生零引用报告。 - DuckDuckGo 可能会屏蔽爬虫。搜索失败会保守处理。 - 付费墙和机器人屏蔽的来源通常会变成 `UNVERIFIABLE`。 - 弱的清洁校准标签并不能证明每一篇公共报告引用都是有效的。 ## 项目文档 - [`docs/dev/MVP_PLAN.md`](./docs/dev/MVP_PLAN.md)：v1 范围和产品决策。 - [`docs/dev/IMPLEMENTATION.md`](./docs/dev/IMPLEMENTATION.md)：实现状态和验证说明。 - [`docs/dev/2026-05-17-hallucination-check-tool-design.md`](./docs/dev/2026-05-17-hallucination-check-tool-design.md)：最初的更广泛设计。 - [`docs/dev/V1_1_ROADMAP.md`](./docs/dev/V1_1_ROADMAP.md)：下一版本中有界 LLM 证据解释器的想法。 - [`docs/dev/VENICE_LIVE_TESTING.md`](./docs/dev/VENICE_LIVE_TESTING.md)：手动 Venice 冒烟测试说明。 - [`AGENTS.md`](./AGENTS.md)：贡献者和编码智能体上下文。 ## 许可证 MIT。参见 [`LICENSE`](./LICENSE)。

标签：API安全, EVTX分析, Go语言, HTML报告, JSON输出, Markdown报告, meg, PDF处理, SQLite, URL健康检查, Wayback Machine查询, 信息安全, 出版商归因, 审计工具, 幻影引用检测, 引用验证, 政策分析, 文档审计, 文档真实性, 日志审计, 杀软绕过, 模糊标题搜索, 研究工具, 程序破解, 虚假引用检查, 记者工具