manage-refs

管理参考文献技能

从决策树中选择工具；不要另行设计流程。参考文献列表绝不能手动输入：始终通过 pandoc citeproc + 期刊 CSL 或 Zotero Word 插件（CWYW）生成。此技能负责写入（渲染、注入、转换）；与 PubMed/CrossRef 核对书目信息是否正确的工作由 /verify-refs 负责——一个只读审计器，一个写入器。

决策树

情况	工具	原因
验证 [@bibkey] ↔ refs.bib（UNDEFINED / UNUSED 键）	scripts/check_citation_keys.py	硬性构建门禁，几秒内即可运行
单作者投稿锁定，输出冻结	scripts/render_pandoc.sh -j <journal>	可复现，适合 CI
连续被拒稿（例如 ER → JVIR → CVIR）	使用新的 -j 运行 render_pandoc.sh	几秒内通过切换 CSL 重新格式化参考文献
验证期刊 CSL 是否按作者指南实际要求呈现文内格式 / DOI / 期刊名称样式	scripts/check_csl_render.py --csl <x>.csl --bib refs.bib --journal <key> --md manuscript.md	存根 /“依赖型” CSL 会继承其父级的格式，而父级格式可能与指南不同（括号式还是上标式、是否保留 DOI、是否使用完整期刊名称）。--md 只检查 pandoc 读取为已引用的键（nocite: '@*' = 整个文献库）；作为期刊名称的预印本服务器（journal = {arXiv}）不受缩写检查限制；未提供 --journal/--expect-* 时，运行结果为 NOT_ASSESSED（退出码 2），绝不会是 PASS。规格键及检查范围之外的内容见：references/REFERENCE_STYLE_SPECS.md。请在投稿前运行，而不是收到校样 PDF 后再运行
参考文献列表显示完整期刊名称，但期刊要求 NLM 缩写	scripts/fill_journal_abbrev.py --bib refs.bib --out refs_abbrev.bib	从 PubMed 填入 shortjournal（PMID，若无则通过 DOI → PMID），再使用 CrossRef 的 short-container-title，按条目命名（通常是带句点的 ISO 4，并非 NLM：请检查）。在条目中按其自身缩进插入到期刊字段之后，不覆盖现有内容，写入前重新解析；退出码 1 = 部分查询失败。对于由 Better BibTeX 管理的 bib，请改为填写 Zotero 的“Journal Abbr”
审稿人要求修改：在合作者同时编辑的 Word 文档中添加 1–2 条参考文献	Zotero Word 插件（用户 GUI）	尽量减少对修订跟踪流程的干扰
审稿人要求修改：批量更改参考文献	编辑 markdown SSOT，然后重新运行 render_pandoc.sh	保持一致，避免挑拣提交的风险
将 [N] 数字标记迁移为 pandoc 使用的 [@key]	scripts/md_marker_convert.py --to-keys	由映射驱动，可安全进行部分转换
将 [@key] 转换为 [N]，用于往返转换 / 调试	scripts/md_marker_convert.py --to-numbers	使用同一映射，方向相反
将原生 Zotero CWYW 域代码写入 .docx（可在 Word 中实时刷新）	scripts/inject_zotero_cwyw.py	适用于合作者的 Word 工作流，并支持流转后的编辑
对照稿件 ↔ 已渲染 DOCX 进行交叉引用质检	scripts/check_xref.py --strict	投稿门禁（不匹配时为 P0 阻断项）
图表作为独立附件提交（放射学及大多数医学期刊）	check_xref.py --strict --allow-separate-attachments	将 MISSING_DOCX 降级为 WARN；MISSING_BODY/MISMATCH 仍为 P0
v_(N+1) DOCX 构建时重新生成检查	check_xref.py --vN-docx-md5 <prev>.docx [--vN-md <prev>.md]	一致性 = 未修改的种子副本；缺少差异行 = 正文未重新生成
构建产物中的重复参考文献列表	scripts/check_reference_duplication.py --docx <built>.docx（或 --text <rendered>.md）	DUP_REF_HEADING / REF_NUMBER_RESTART / REF_SIGNATURE_DUP（Major）。可检测手动输入的 ## References 列表与 pandoc 的 --citeproc 自动生成的参考文献列表同时存在的情况，这会渲染出两个列表（第二个通常位于图例之后）。任何 citeproc 构建后都应运行
.bib 标题中的出版商标记（渲染为乱码）	scripts/check_bib_title_markup.py --bib refs.bib --strict	CrossRef 标题包含 <scp>WHO</scp> / <i>IDH</i>；BBT 会将其转义为 {$<$}scp{$>$}，或移除标记却不恢复空格（andTERTPromoter）。verify_refs 可证明参考文献真实；此检查可证明它能正确打印。TITLE_MARKUP / TITLE_FUSION（Major）
投稿前主门禁（建议在任何投稿前运行）	scripts/pre_submission_gate.sh	依次运行 check_citation_keys → check_bib_title_markup → verify_refs --strict → render_pandoc（可选）→ check_xref --strict；单一产物为 qc/pre_submission_gate.json
直接渲染并进行内置参考文献审计	scripts/render_pandoc.sh（先通过 /verify-refs 审计 .bib；遇到 FABRICATED/MISMATCH/重复项时阻止渲染；将 UNVERIFIED 条目标记为未通过，但不阻止渲染；渲染后警告已引用但没有 shortjournal 的期刊条目，这类条目会由样式以完整名称打印）	尽力执行（若同目录下没有 /verify-refs，则跳过并发出警告）；使用 -S 可选择退出。主门禁会传入 -S，因为它在第 3 阶段运行 verify_refs
对照 PubMed / CrossRef 进行书目审计	委托给 /verify-refs	仅用于审计——保持撰写者与审计者分离

工作流

A. Pandoc citeproc（适用于单人作者和最终提交）

用户提供包含 [@bibkey] 引用的 manuscript.md 和 refs.bib。

1. 检查：python3 "${CLAUDE_SKILL_DIR}/scripts/check_citation_keys.py" manuscript.md refs.bib — 如果存在未定义的键，则以非零状态码退出。修正后重新运行。/write-paper 中的 [@NEW:topic_slug] 草稿占位符也会报告为未定义：将每个占位符对应的引用添加到 Zotero（/lit-sync 随后会刷新 refs.bib），并将占位符替换为真实的 [@bibkey]。绝不要让 [@NEW:...] 出现在渲染后的 DOCX 中。
2. 渲染：

   "${CLAUDE_SKILL_DIR}/scripts/render_pandoc.sh" \
     -j european-radiology \
     -i manuscript.md \
     -b refs.bib \
     -o manuscript_final.docx
   

   当前支持的样式及各样式的渲染效果，请参阅 citation_styles/README.md — 该表是样式注册表。若 -j 指定的样式不存在，render_pandoc.sh 也会列出磁盘上的样式，因此请询问脚本，而不要依赖此处列出的清单。两个固定备用方案：RYAI 使用 radiology，JVIR 使用 vancouver（两者都没有专用 CSL）。 .bib 中不存在的引用键会导致渲染以状态码 5 退出并显示该键：pandoc 会在输出中将其显示为 (key?)，但自身不会报错退出。
3. 质量检查：

   python3 "${CLAUDE_SKILL_DIR}/scripts/check_xref.py" \
     --md manuscript.md --docx manuscript_final.docx \
     --out qc/xref_audit.json --strict
   

   将 submission_safe: false 视为必须停止。根据症状处理修复 — 参阅 references/check_xref_symptoms.md 中的表格。
4. 审计交接：签字确认前，调用 /verify-refs 执行 PubMed/CrossRef 审计。

B. Zotero CWYW（合著者 Word 工作流）

用户有一份 Markdown 单一事实来源（SSOT），希望审稿人直接在 Word 中编辑引用。每条参考文献都必须已存在于 Zotero 中；用户需提供 [N] → ZoteroKey 映射。

1. 转换标记：

   python3 "${CLAUDE_SKILL_DIR}/scripts/md_marker_convert.py" \
     --input manuscript.md --output manuscript_keys.md \
     --map ref_map.json --to-keys
   

   转换过程不会为数字猜测 Zotero 键：未映射的标记会保留为 [N]，在 stderr 中报告，并使脚本以状态码 1 退出（仍会写入部分输出；传入 --allow-partial 可接受该输出）。类似 [1-3] 的范围会展开。任何方括号中的数字都会被视为标记，因此方括号中的年份（[2019-2021]）也会报告为未映射。也可以先使用 --active-ns 1,2,3,4,19 进行样例构建（调试时，5 条参考文献的样例可缩小 Word Refresh 的影响范围）。
2. 使用 pandoc 渲染为 .docx（工作流 A），使正文包含纯文本 [@key] 标记；或者以其他方式预先构建 .docx，但其中仍须包含纯文本 [@key]。
3. 注入 CWYW：

   python3 "${CLAUDE_SKILL_DIR}/scripts/inject_zotero_cwyw.py" \
     --input manuscript_keys.docx --output manuscript_cwyw.docx \
     --user-id <zotero-user-id> --keys-from keys.txt
   

   脚本会从本地 Zotero 连接器（端口 23119）实时获取条目元数据，因此 Zotero 必须在本机运行；不支持 Web API 备用方案。任何 HTTP 请求失败都会导致脚本以非零状态码中止，因此不完整的参考文献列表绝不会传给用户。绝不要编造 Zotero 元数据。
4. 首次构建说明（必需）：脚本会写入一个空的 ADDIN ZOTERO_BIBL 占位项，Word 的 Zotero Refresh 会将其视为用户自定义内容并拒绝填充。请在 Word 中打开输出文件 → Zotero 选项卡 → 点击一次 Add/Edit Bibliography。之后，作者编辑时使用 Refresh 即可保持引用和参考文献列表同步。
5. 不应进行局部修补：后续轮次新增参考文献时，应编辑 Markdown 单一事实来源并重新构建整个 .docx，而不是用正则表达式修补 CWYW 处理后的文件。Zotero 渲染出的 [N] 上标可能与纯文本 [N] 标记冲突并破坏域代码。

C. 级联拒稿后的重新渲染（find-journal 交接）

用户被期刊 A 拒稿，且 /find-journal 推荐了期刊 B。

1. 确认 citation_styles/ 中存在新的 CSL（或从 https://citationstyles.org/styles 获取并放入该目录）。
2. 使用相同的 manuscript.md 和 refs.bib，重新运行 render_pandoc.sh -j <new-csl>。
3. 重新运行 check_xref.py --strict。
4. 如果期刊间修订期间新增了任何参考文献，则重新运行 /verify-refs。

D. 仅进行交叉引用 QC

用户已提交一份稿件，审稿人指出表格／图件不匹配。

1. 对当前的 manuscript.md 和 .docx 运行 check_xref.py --strict。

2. 检查 qc/xref_audit.json。正文图注是 SSOT——修复 manuscript.md 并重新构建，切勿手动修改 .docx。

3. 有关 MISSING_BODY / MISSING_DOCX / MISMATCH 的分类处理表，请参阅 references/check_xref_symptoms.md。

4. 对于接受将图件和表格作为单独附件文件的期刊（European Radiology、Radiology、AJR、JVIR、KJR 以及大多数医学期刊），请传入 --allow-separate-attachments。此选项会降低两类问题的严重级别；由于证据不同，两者会分别报告：

   • MISSING_DOCX — 已提供 --docx，并证实该浮动对象不在渲染后的主文档中。这就是单独附件的情况。
   • 未提供 --docx 时出现 MISSING_BODY — 尚未进行任何检查。根据你的声明予以豁免， 标记为 EXCUSED WITHOUT EVIDENCE，并计入 summary.downgraded_unchecked。

   MISMATCH 仍为 P0。浮动对象确实存在于渲染后的 DOCX 中时，MISSING_BODY 也仍为 P0——这是 SSOT 不一致，任何附件政策都不能豁免。

   **提交前，至少使用 --docx 运行一次。**此标志仅用于声明，并不代表验证；只有提供 DOCX，才能将豁免转化为证据。

D'. v_(N+1) docx 重新生成检查（构建时配套检查）

从冻结的 v_N 构建 v_(N+1) 时，v_(N+1) docx 的内容 MUST 与 v_N docx 不同——字节完全相同的副本意味着静默复制了种子文件，同行评审时会导致 Markdown 编辑内容被还原。check_xref.py 提供两个标志，作为 /sync-submission 中提交时检查 scripts/verify_package_integrity.py --assert-vN-docx-changed 的构建时配套检查：

python3 "${CLAUDE_SKILL_DIR}/scripts/check_xref.py" \
    --md manuscript_v2.md \
    --docx manuscript_v2.docx \
    --vN-docx-md5 manuscript_v1.docx \
    --vN-md manuscript_v1.md \
    --strict

• 仅使用 --vN-docx-md5：检查 MD5 是否一致。字节相同 = FAIL。
• 使用 --vN-docx-md5 + --vN-md：此外还会提取 v_N 与 v_(N+1) 之间仅针对 Markdown 的差异， 并验证每条长度 ≥40 个字符的差异行是否逐字出现在新 docx 的正文 XML 中（空白规范化后，不区分大小写）。缺少差异行 = 正文未包含 Markdown 编辑内容。

结果会记录在 qc/xref_audit.json 的 vN_docx_check 下。 无论出现哪种失败，即使未使用 --strict，退出代码也会非零。

E. 提交前主检查关卡（推荐的端到端链路）

这是结合工作流 A 和 D 以及 /verify-refs 的单一入口；任何环节失败都会中止。请在提交前，或在向资深合著者传阅 v_N 软件包前，立即运行。

bash "${CLAUDE_SKILL_DIR}/scripts/pre_submission_gate.sh" \
    --md manuscript/manuscript.md \
    --bib manuscript/_src/refs.bib \
    --docx submission/<journal>/manuscript.docx \
    --allow-separate-attachments    # omit if the journal accepts inline figures/tables

阶段顺序（首次失败即中止）：

1. check_citation_keys.py manuscript.md refs.bib — 检查未定义／未使用的键
2. check_bib_title_markup.py --strict — 检查 .bib 标题中的出版商标记／标签剥离导致的拼接问题
3. verify_refs.py refs.bib --strict — 逐条通过 PubMed / CrossRef 验证
4. render_pandoc.sh -S -j <csl> -i ... -b ... -o ... — 仅在省略 --docx 时调用 （--journal <csl>，默认为 vancouver）
5. check_xref.py --md ... --docx ... --strict [--allow-separate-attachments]

成功后，链路会写入 qc/pre_submission_gate.json（以及各阶段的产物 qc/bib_title_markup.json、qc/reference_audit.json 和 qc/xref_audit.json），其中包含 submission_safe: true。任何阶段失败时，JSON 都会记录失败阶段及退出代码，且脚本会以非零状态退出——在失败阶段通过之前，请勿提交。

此检查关卡不会重新实现任何检查；它会将现有脚本作为子进程调用。新增检查应添加到底层脚本中，检查关卡随后会自动调用该检查。

F. BibTeX 作者格式错误（检查渲染后的姓名）

以 author = {Surname AB and Surname2 CD}（姓氏 + 首字母缩写，没有逗号）格式编写的条目，会导致 BibTeX 将最后一个词视为姓氏，渲染为“AB S, CD S2”。请始终使用 author = {Family, Full Given} 格式。即使有逗号，拼接的首字母缩写（Family, AB）在 CSL initialize-with 下仍会折叠为一个首字母，因此请使用 PubMed efetch 中的完整名字。

/verify-refs 会将 bib 内容与 PubMed 进行比较，但无法看到渲染后的输出；请分别对渲染后的 docx 和 bib 执行 grep：

unzip -p out.docx word/document.xml | sed 's/<[^>]*>//g' | grep -oE "[A-Z]{2} [A-Z], [A-Z]{2} [A-Z]"   # corruption signature in output
grep -nE 'author\s*=\s*\{[A-Z][a-z]+ [A-Z]{1,3}( |\})' refs.bib                                          # no-comma source entries

质量关卡

此技能定义了 三个提交关卡和一个用户审批关卡：

• 关卡 1（citekey 完整性）：check_citation_keys.py 遇到未定义的键时会以非零状态码退出。流水线会停止；用户检查并修复。
• 关卡 2（交叉引用完整性）：check_xref.py --strict 遇到任何 MISSING_DOCX / MISSING_BODY / MISMATCH 行时会以状态码 1 退出（即使没有识别到其文内引用，markdown 中定义但 DOCX 中缺失的浮动对象也会标记为 MISSING_DOCX；HTML 注释或围栏代码中的图例不会被渲染，因此会保持为 UNCITED）。使用 --docx 且未安装 python-docx 时会以状态码 2 退出：DOCX 审计未运行。用户需检查 qc/xref_audit.json 并解决问题后再继续。在使用 --allow-separate-attachments 时，除了检查 submission_safe，还要检查 summary.downgraded_unchecked：非零计数意味着有些行未经检查便通过。
• 关卡 3（审计交接）：签署前，用户必须运行 /verify-refs 并确认 qc/reference_audit.json 中的 submission_safe: true。此技能不会自行将参考文献标记为已审计。
• 用户审批关卡（CWYW 首次构建）：首次运行 inject_zotero_cwyw.py 构建后，用户必须手动执行 Word → Zotero → Add/Edit Bibliography。此技能无法自动完成此操作，并会在 stderr 中警告此步骤为必需。

来源

scripts/_vendor_citation_writer.py 从 alisoroushmd/zotero-mcp @ ed5dfb71 引入，采用 MIT 许可。请参阅 NOTICE.md 和 LICENSE.zotero-mcp。

已知限制

• 网页 / 非期刊条目类型：由经过修补的 zotero_to_csl_json 处理，它会获取 Zotero 原生的 CSL-JSON；请勿绕过此修补。
• “Table 1 and 2”（单数类别词，数字列表）：check_xref.py 只会从中读取 Table 1；若在正文中解析 “and” 后的单个数字，就会将 “Table 1 and 2 patients” 误读为引用。markdown 中定义但 DOCX 中缺失的浮动对象仍会被标记为 MISSING_DOCX 并阻止提交；既未定义也未渲染的对象则不会被识别。请写作 “Tables 1 and 2” 或 “Table 1 and Table 2”。