hfpclawer 引用审计
验证引用的学术论文是否实际存在，使用一个三层管道，当本地数据或远程 API 不可用时，会降级处理。
谁可以使用：需要检查引用是否指向真实论文的研究人员、审稿人和文献综述作者。
概述
审计引擎按照顺序尝试三个来源，停止在第一个确认：
┌──────────────────────────┐
用户：│ hfpclawer audit verify │ "这篇论文 │ "Fourier Neural Operator"│ 是否真实？"
└─────────────┬────────────┘
│ ┌─────────────┼─────────────┐
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────┐
│ L1： │ │ L2： │ │ L3： │
│ 本地 │→ │ Semantic │→ │ OpenAlex │
│ FTS5 DB │ │ Scholar │ │
│ (1ms) │ │ (200ms) │ │ (200ms) │
└─────────┘ └──────────┘ └──────────┘
每个来源独立报告四种状态之一：
VERIFIED — 论文在此来源中存在
SUSPECTED — 可能匹配（标题相似，但不完全匹配）
NOT_FOUND — 没有找到匹配
ERROR — 来源不可用（无本地 DB / API 限速）
何时使用
用户引用了一篇你找不到的论文 — 验证其存在
你的团队正在撰写综述 / 文献综述 — 批量审计参考列表
你下载了一个 LLM 生成的论文，需要事实核查其引用
你想知道一篇论文是否是已知的 arXiv 预印本或不存在的幻觉
先决条件
pip install hfpclawer>=0.5.0
无需 API 密钥即可进行基本使用（S2 + OpenAlex 使用匿名层）
可选：设置 S2_API_KEY 环境变量以实现 10 倍更快的 Semantic Scholar 查询
可选：设置 OPENALEX_POLITE_EMAIL 环境变量以实现 10 倍更快的 OpenAlex 查询
可选：克隆 arxiv-metadata-service 仓库以实现 L1 本地 FTS5（参见 references/local-db-setup.md）
快速开始
# 自动模式：先尝试本地 DB，然后尝试 Semantic Scholar，最后尝试 OpenAlex
hfpclawer audit verify "Fourier Neural Operator for Parametric Partial Differential Equations"
# 短标题也可以 — 包括子字符串回退
hfpclawer audit verify "Fourier Neural Operator"
# 精确的 arXiv ID
hfpclawer audit verify --arxiv-id 2010.08895
# 只使用本地 FTS5（需要 arxiv_meta.db）
hfpclawer audit verify "Attention Is All You Need" --source local
# 只使用 Semantic Scholar
hfpclawer audit verify "Attention Is All You Need" --source s2
# 只使用 OpenAlex
hfpclawer audit verify "Attention Is All You Need" --source openalex
# 将引用保存在文本文件中，每个段落一个
cat > refs.txt << 'EOF'
FNO 论文（arXiv:2010.08895）显示出有希望的结果。
PINNs 由 Raissi 等人（2019 年）引入“物理信息神经网络”。
EOF
hfpclawer audit --refs refs.txt
输出格式
每个结果显示：
[OK] VERIFIED — 论文确认；包括标题、作者、来源
[?] SUSPECTED — 可能但不确定；显示顶级匹配
[NF] NOT_FOUND — 没有找到这篇论文的证据
[ERR] ERROR — 来源不可用（DB 未找到、限速）
[OK] VERIFIED
标题：Fourier Neural Operator
作者：Zongyi Li, Nikola Kovachki, Kamyar Azizzadenesheli, ...
来源：openalex：VERIFIED
如何确定状态
本地 DB Semantic Scholar OpenAlex
VERIFIED FTS5 匹配，标题相似度 >= 0.70 标题搜索 >= 0.70 标题搜索 >= 0.70
SUSPECTED FTS5 匹配，评分 0.40-0.69 — —
NOT_FOUND 无 FTS5 结果 无 >=0.70 匹配 无 >=0.70 匹配
ERROR DB 未找到 / 损坏 429/5xx / 网络 429/5xx / 网络
标题匹配：标题相似度使用 difflib.SequenceMatcher 在归一化（小写、去除标点符号）的标题上。
短标题如果是较长标题的子字符串，也可以通过 0.70 阈值。
批量模式
从文本文件
hfpclawer audit --refs references.txt
解析器检测：
arXiv:XXXX.XXXXX 标识符
"标题"（作者，年份）模式
作者（年份）"标题" 模式
通过 Python API
from hfpclawer.citation_audit import check_citation
result = check_citation(
"Fourier Neural Operator",
authors_hint="Li",
year_hint=2020,
source="auto", # 或 "local" / "s2" / "openalex"
)
print(result["status"]) # VERIFIED | NOT_FOUND | ERROR
print(result.get("authors", "N/A"))
print(result.get("per_source", {})) # 每个来源的细分
常见陷阱
短 / 两个字的查询可能会因为 FTS5 的 porter stemmer 需要实际内容词而失败。
使用至少 3-4 个重要词语进行本地 DB 查询。
Semantic Scholar 在没有 API 密钥的情况下会激进地限速（~1 req/s，~100 req/day 匿名）。
设置 S2_API_KEY 以用于生产环境。
OpenAlex 礼貌池是免费的，提供 10 req/s — 设置 OPENALEX_POLITE_EMAIL 到你的机构邮箱。
没有 L1 而没有 arxiv-metadata-service：本地 FTS5 DB 需要克隆单独的 arxiv-metadata-service 仓库。
by