| name | citation-verifier |
| description | Generate and verify BibTeX entries from paper notes, writing `citations/ref.bib` and `citations/verified.jsonl`.
**Trigger**: citation, BibTeX, ref.bib, verified.jsonl, references, 引用, 参考文献.
**Use when**: 已有 `papers/paper_notes.jsonl`，需要为 prose/LaTeX 准备可追溯的引用（每条都有 url/date/title 验证记录）。
|
Citation Verifier
Generate citations/ref.bib and ensure every entry has a traceable verification record in citations/verified.jsonl.
When network access is restricted, prefer a “record now, verify later” workflow: keep URLs/titles consistent and leave a clear verification note.
Input
Outputs
citations/ref.bibcitations/verified.jsonl
Workflow (heuristic)
- Collect
bibkey, title, url, year, authors from papers/paper_notes.jsonl.
- Write/refresh
citations/ref.bib:
- Prefer arXiv-style fields when
arxiv_id / primary_category exist (eprint, archivePrefix, primaryClass).
- Write one verification record per BibTeX entry to
citations/verified.jsonl with at least:
- If you cannot verify via network, record a clear
notes field (e.g., “auto-generated; needs manual verification”) and/or request human confirmation depending on your policy.
Quality checklist
Offline Mode
When network access is restricted, run in offline mode to produce auditable records now, then verify later.
- Generate offline records:
verification_status: offline_generated
- Verify later (when network is available):
--verify-only
verification_status
offline_generated: record was generated without network verification (needs later verification)verified_online: URL/title verified successfully by the scriptverify_failed: verification was attempted but failed (network error or title mismatch)needs_manual_verification: missing/ambiguous fields (e.g., empty url/title)
Script
Quick Start
uv run python .codex/skills/citation-verifier/scripts/run.py --help- Offline (record now, verify later):
uv run python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace> --offline
All Options
--offline: do not attempt network verification; write verification_status=offline_generated--verify-only: verify existing citations/verified.jsonl records (does not rewrite BibTeX)--verification-note <text>: stored in citations/verified.jsonl notes
Examples
- Generate BibTeX + offline verification records:
uv run python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace> --offline --verification-note "auto-generated; needs manual verification"
- Later, verify-only (when network is available):
uv run python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace> --verify-only
Notes
- Minimal requirement for every verification record:
url, date, title.
- The script sanitizes stray/unbalanced
{} in titles to keep bibtex parsing robust.
- The script escapes LaTeX special chars in text fields (
& % $ # _) and rewrites superscript patterns like X^N or X$^N$ as X\textsuperscript{N} to keep LaTeX builds stable.
- URLs are kept raw in BibTeX
url fields (BibTeX styles wrap them with \url{...}); @misc uses howpublished=\url{...}.
- In offline mode, records are not truly verified; treat
offline_generated as a to-do for human/network verification.
Troubleshooting
Common Issues
Issue: Missing bibkey / missing url in notes
Symptom:
citations/ref.bib is missing entries, or verified.jsonl has empty url/title.
Causes:
papers/paper_notes.jsonl lacks bibkey/url fields.
Solutions:
- Ensure each core paper note has a stable
bibkey and a canonical url.
- Rerun citation generation after fixing notes.
Issue: verification_status=offline_generated
Symptom:
- Records exist but are not truly verified.
Causes:
--offline was used, or network verification was unavailable.
Solutions:
- When network is available, run
--verify-only to upgrade records.
- Or manually verify and update
citations/verified.jsonl with notes.
Recovery Checklist
