hypo-verify

name	hypo-verify
description	Verify whether BibTeX references are real and whether their metadata is correct. Use this whenever the user wants to validate a .bib file, detect hallucinated references, check DOI/title/year/venue/author consistency, or confirm that cited papers actually exist on Semantic Scholar and OpenAlex. Run the verification script first to collect objective metadata evidence, then let the Agent judge whether citation context in the .tex file accurately describes the paper.
license	MIT

/hypo-verify — 引用验证

脚本负责联网核验引用是否存在、元数据是否匹配；Agent 负责解释 mismatch / not_found 的含义，并在提供 .tex 路径时判断引用上下文是否准确。

如果项目根目录存在 .hypo-research.toml，可直接读取 project.bib_files、verify.timeout、verify.skip_keys、verify.s2_api_key 等默认值。

参数

$ARGUMENTS

• bib: .bib 文件路径（必填）
• tex: .tex 文件或目录（可选，只验证被引用的条目）
• project_dir: 显式项目根目录（可选，可自动发现主文件和 .bib）
• keys: 只验证指定 cite key（可选，逗号分隔）
• fix: 是否自动修复可修复项（可选，布尔值）

工作流

1. 运行验证脚本：

uv run hypo-research verify --stats <bib>

如果用户给了 .tex 路径或 key 过滤：

uv run hypo-research verify --stats <bib> --tex <tex> --keys <keys>

多文件项目可自动发现 .bib：

uv run hypo-research verify --stats --tex main.tex
uv run hypo-research verify --stats --project-dir ./paper

也可以通过 .hypo-research.toml 预先配置默认 bib_files、timeout 和 skip_keys。

2. 解析 JSON 中的 results：

   • verified：记录为已确认，无需动作
   • mismatch：逐项检查 mismatches
   • not_found：高优先级警告，可能是幻觉论文
   • error：报告错误原因并建议补元数据

3. 如果提供了 .tex 路径：

   • 读取对应 \cite{key} 的上下文
   • 判断文字描述是否真的符合该论文内容
   • 这一步由 Agent 判断，不依赖脚本自动决策

4. 如果 fix=true：

   • 对年份 mismatch：可建议修改 .bib 中的 year
   • 对 verified 且本地缺 DOI：可补 doi
   • 对 not_found：不要自动删除，先提醒用户确认

5. 输出最终报告：

   • 验证摘要
   • mismatch / not_found / error 的详细问题
   • 如有 .tex，补充引用上下文判断

状态表

状态	含义	Agent 行为
verified	API 确认论文存在且信息匹配	汇总列出，无需操作
mismatch	论文存在但某些字段不匹配	逐项检查，建议修正
not_found	Semantic Scholar 和 OpenAlex 均未找到	高优先级警告，可能是幻觉论文
error	API 错误或元数据不足	报告错误，建议补充元数据

输出要求

• 优先报告 not_found 和严重 mismatch。
• 对年份 mismatch，说明本地值和远程值。
• 对 venue mismatch，先判断是不是简称 vs 全称差异，避免误报。
• 如果用户想修 .bib，只自动改明确无争议的字段；不要擅自删除条目。

Config Support

如果项目根目录存在 .hypo-research.toml，优先读取：

• project.bib_files
• verify.s2_api_key
• verify.timeout
• verify.skip_keys
• verify.max_concurrent