citation-verifier

引用核验器

触发条件与路由

• 触发词：citation、BibTeX、ref.bib、verified.jsonl、references、引用、参考文献。
• 适用场景：已有 papers/paper_notes.jsonl，需要为 prose/LaTeX 准备可追溯的引用（每条引用都有 url/date/title 核验记录）。

生成 citations/ref.bib，并确保每个条目在 citations/verified.jsonl 中都有可追溯的核验记录。

网络访问受限时，优先采用“先记录，后核验”的工作流：保持 URL/title 一致，并留下清晰的核验说明。

输入

• papers/paper_notes.jsonl

输出

• citations/ref.bib
• citations/verified.jsonl

工作流（启发式）

1. 从 papers/paper_notes.jsonl 中收集 bibkey、title、url、year、authors。
2. 编写或更新 citations/ref.bib：
   • 存在 arxiv_id / primary_category 时，优先使用 arXiv 风格字段（eprint、archivePrefix、primaryClass）。
3. 为每个 BibTeX 条目在 citations/verified.jsonl 中写入一条核验记录，至少包含：
   • bibkey、title、url、date
4. 如果无法通过网络核验，请记录清晰的 notes 字段（例如：“自动生成；需要人工核验”），并根据你的策略请求人工确认。

质量检查清单

• 每个 BibTeX 条目都有对应的 verified.jsonl 记录。
• 核验记录中的 url / date / title 均不缺失。

离线模式

网络访问受限时，使用离线模式立即生成可审计的记录，之后再进行核验。

• 生成离线记录：verification_status: offline_generated
• 稍后核验（网络可用时）：--verify-only

verification_status

• offline_generated：记录是在未经网络核验的情况下生成的（之后需要核验）
• verified_online：脚本已成功核验 URL/title
• verify_failed：尝试核验但失败（网络错误或标题不匹配）
• needs_manual_verification：字段缺失或含义不明确（例如，url / title 为空）

脚本

快速入门

• uv run python .codex/skills/citation-verifier/scripts/run.py --help
• 离线模式（先记录，后核验）：uv run python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace> --offline

所有选项

• --offline：不尝试网络核验；写入 verification_status=offline_generated
• --verify-only：核验现有的 citations/verified.jsonl 记录（不会重写 BibTeX）
• --verification-note <text>：将说明存储在 citations/verified.jsonl 的 notes 字段中

示例

• 生成 BibTeX 和离线核验记录：
  • uv run python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace> --offline --verification-note "auto-generated; needs manual verification"
• 稍后仅核验（网络可用时）：
  • uv run python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace> --verify-only

备注

• 每条核验记录的最低要求：url、date、title。
• 脚本会清理标题中多余或不配对的 {}，以确保 bibtex 能可靠解析。
• 脚本会对文本字段中的 LaTeX 特殊字符（& % $ # _）进行转义，并将 X^N 或 X$^N$ 等上标形式改写为 X\textsuperscript{N}，以确保 LaTeX 构建稳定。
• BibTeX 的 url 字段中会保留原始 URL（BibTeX 样式会使用 \url{...} 包装）；@misc 使用 howpublished=\url{...}。
• 离线模式下的记录并未经过真正核验；请将 offline_generated 视为待办事项，后续由人工或通过网络核验。

故障排除

常见问题

问题：缺少 bibkey / 笔记中缺少 url

症状：

• citations/ref.bib 缺少条目，或 verified.jsonl 中的 url/title 为空。

原因：

• papers/paper_notes.jsonl 缺少 bibkey / url 字段。

解决方案：

• 确保每篇核心论文的笔记都有稳定的 bibkey 和规范的 url。
• 修复笔记后，重新生成引用。

问题：verification_status=offline_generated

症状：

• 存在记录，但并未真正验证。

原因：

• 使用了 --offline，或无法进行网络验证。

解决方案：

• 网络可用时，运行 --verify-only 以升级记录。
• 或手动验证，并在 citations/verified.jsonl 中更新记录并添加备注。

恢复检查清单

• 每个 BibTeX 条目都有对应的 citations/verified.jsonl 记录。
• 验证记录包含 url、date、title。