citation-verifier

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Citation Verifier

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.

生成

citations/ref.bib

文件，并确保每个条目在

citations/verified.jsonl

中都有可追溯的验证记录。

当网络受限，优先采用“先记录，后验证”的工作流：保持URL和标题一致，并留下清晰的验证说明。

Input

输入

```
papers/paper_notes.jsonl
```

```
papers/paper_notes.jsonl
```

Outputs

输出

```
citations/ref.bib
```
```
citations/verified.jsonl
```

```
citations/ref.bib
```
```
citations/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:
- ```
bibkey
```
  ,
```
title
```
  ,
```
url
```
  ,
```
date
```
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.

从

papers/paper_notes.jsonl

中提取

bibkey

、

title

、

url

、

year

、

authors

信息。

写入/更新
```
citations/ref.bib
```
：
- 当存在
```
arxiv_id
```
  /
```
primary_category
```
  时，优先使用arXiv风格字段（
```
eprint
```
  、
```
archivePrefix
```
  、
```
primaryClass
```
  ）。
为每个BibTeX条目在
```
citations/verified.jsonl
```
中写入一条验证记录，至少包含：
- ```
bibkey
```
  、
```
title
```
  、
```
url
```
  、
```
date
```
若无法通过网络验证，需在
```
notes
```
字段中留下清晰说明（例如：“自动生成；需手动验证”），或根据策略请求人工确认。

Quality checklist

质量检查清单

Every BibTeX entry has a corresponding
```
verified.jsonl
```
record.
No missing
```
url
```
/
```
date
```
/
```
title
```
in verification records.

每个BibTeX条目都有对应的
```
verified.jsonl
```
记录。
验证记录中无缺失的
```
url
```
/
```
date
```
/
```
title
```
。

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
```
后续验证（网络可用时）：
```
--verify-only
```

verification_status

verification_status

状态说明

```
offline_generated
```
: record was generated without network verification (needs later verification)
```
verified_online
```
: URL/title verified successfully by the script
```
verify_failed
```
: verification was attempted but failed (network error or title mismatch)
```
needs_manual_verification
```
: missing/ambiguous fields (e.g., empty
```
url
```
/
```
title
```
)

```
offline_generated
```
：记录生成时未进行网络验证（需后续验证）
```
verified_online
```
：脚本已成功验证URL/标题
```
verify_failed
```
：尝试验证但失败（网络错误或标题不匹配）
```
needs_manual_verification
```
：字段缺失/模糊（例如：
```
url
```
/
```
title
```
为空）

Script

脚本

Quick Start

快速开始

python .codex/skills/citation-verifier/scripts/run.py --help

Offline (record now, verify later):

python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace_dir> --offline

python .codex/skills/citation-verifier/scripts/run.py --help

离线模式（先记录后验证）：

python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace_dir> --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

--offline

：不尝试网络验证；写入

verification_status=offline_generated

```
--verify-only
```
：验证已有的
```
citations/verified.jsonl
```
记录（不会重写BibTeX）

--verification-note <text>

：将说明存储在

citations/verified.jsonl

的

notes

字段中

Examples

示例

Generate BibTeX + offline verification records:

python .codex/skills/citation-verifier/scripts/run.py --workspace <ws> --offline --verification-note "auto-generated; needs manual verification"

Later, verify-only (when network is available):

python .codex/skills/citation-verifier/scripts/run.py --workspace <ws> --verify-only

生成BibTeX + 离线验证记录：

python .codex/skills/citation-verifier/scripts/run.py --workspace <ws> --offline --verification-note "auto-generated; needs manual verification"

后续网络可用时，仅执行验证：

python .codex/skills/citation-verifier/scripts/run.py --workspace <ws> --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.

每条验证记录的最低要求：包含
```
url
```
、
```
date
```
、
```
title
```
。
脚本会清理标题中多余/不匹配的
```
{}
```
，确保BibTeX解析的稳定性。
脚本会转义文本字段中的LaTeX特殊字符（
```
& % $ # _
```
），并将
```
X^N
```
或
```
X$^N$
```
这类上标格式重写为
```
X\textsuperscript{N}
```
，保证LaTeX编译稳定。
URL在BibTeX的
```
url
```
字段中保持原始格式（BibTeX样式会用
```
\url{...}
```
包裹）；
```
@misc
```
类型会使用
```
howpublished=\url{...}
```
。
离线模式下生成的记录并未真正经过验证；需将
```
offline_generated
```
视为待完成的人工/网络验证任务。

Troubleshooting

故障排除

Common Issues

常见问题

Issue: Missing

bibkey

/ missing

url

in notes

问题：笔记中缺失

bibkey

/ 缺失

url

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.

症状：

citations/ref.bib

缺少条目，或

verified.jsonl

中的

url/title

为空。

原因：

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

解决方案：

确保每篇核心论文笔记都有稳定的
```
bibkey
```
和标准的
```
url
```
。
修复笔记后重新运行引用生成脚本。

Issue:

verification_status=offline_generated

问题：

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.

症状：

记录已存在但未经过真正验证。

原因：

使用了
```
--offline
```
参数，或网络验证不可用。

解决方案：

网络可用时，运行
```
--verify-only
```
参数升级记录状态。
或手动验证并更新
```
citations/verified.jsonl
```
中的说明。

Recovery Checklist

恢复检查清单

Every BibTeX entry has a matching
```
citations/verified.jsonl
```
record.
Verification records include
```
url
```
,
```
date
```
,
```
title
```
.

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

citation-verifier

Original

Translation

Citation Verifier

Citation Verifier（引用验证工具）

Input

输入

Outputs

输出

Workflow (heuristic)

工作流（启发式规则）

Quality checklist

质量检查清单

Offline Mode

离线模式

`verification_status`

`verification_status`
状态说明

Script

脚本

Quick Start

快速开始

All Options

所有选项

Examples

示例

Notes

注意事项

Troubleshooting

故障排除

Common Issues

常见问题

Issue: Missing
`bibkey`
/ missing
`url`
in notes

问题：笔记中缺失
`bibkey`
/ 缺失
`url`

Issue:
`verification_status=offline_generated`

问题：
`verification_status=offline_generated`

Recovery Checklist

恢复检查清单

citation-verifier

Original

Translation

Citation Verifier

Citation Verifier（引用验证工具）

Input

输入

Outputs

输出

Workflow (heuristic)

工作流（启发式规则）

Quality checklist

质量检查清单

Offline Mode

离线模式

verification_status

verification_status 状态说明

Script

脚本

Quick Start

快速开始

All Options

所有选项

Examples

示例

Notes

注意事项

Troubleshooting

故障排除

Common Issues

常见问题

Issue: Missing bibkey / missing url in notes

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

Issue: verification_status=offline_generated

问题：verification_status=offline_generated

Recovery Checklist

恢复检查清单

`verification_status`

`verification_status`
状态说明

Issue: Missing
`bibkey`
/ missing
`url`
in notes

问题：笔记中缺失
`bibkey`
/ 缺失
`url`

Issue:
`verification_status=offline_generated`

问题：
`verification_status=offline_generated`