citation-diversifier

用途

Citation Diversifier 用于解决综述写作中常见的引用失败模式：

草稿读起来引用不足，引用密度偏低；
全篇反复复用同样几篇文献，导致唯一引用数量不够；
写作流水线无法通过“全局唯一引用”门槛检查。

该技能不会自己改写正文，而是产出一份“约束表”——引用预算报告 output/CITATION_BUDGET_REPORT.md，用于指导后续的引用注入。

主要能力

诊断全局引用情况：读取 output/DRAFT.md，估算“唯一引用键差距”，或参考 pipeline-auditor 的失败原因。
按 H3 小节分配预算：使用 outline/outline.yml 按论文顺序枚举所有 H3，并从 outline/writer_context_packs.jsonl 读取每个 H3 允许的引用键集合（allowed_bibkeys_selected / mapped / chapter / global）。
给出范围安全的引用建议：只提议 citations/ref.bib 中存在的键，且优先使用当前小节范围内的键；仅在确实跨章节时才使用章节或全局范围内的键。
提供插入位置建议：说明这些引用键可以在小节的哪个位置嵌入，而无需新增论断或数字。
生成可被下游校验器解析的规范化行，例如全局目标与差距行。

使用方式

输入：

output/DRAFT.md
outline/outline.yml（H3 id/标题，用于按小节分配预算）
outline/writer_context_packs.jsonl（每个 H3 的 allowed_bibkeys_{selected,mapped,chapter,global} 来源）
citations/ref.bib

输出：

output/CITATION_BUDGET_REPORT.md

可选的确定性报告生成脚本：

uv run python .codex/skills/citation-diversifier/scripts/run.py --help
uv run python .codex/skills/citation-diversifier/scripts/run.py --workspace <workspace>

可用选项包括：

--workspace <dir>
--unit-id <U###>（可选）
--inputs <semicolon-separated>（较少使用，优先默认值）
--outputs <semicolon-separated>（较少使用，默认写入 output/CITATION_BUDGET_REPORT.md）
--checkpoint <C#>（可选）

示例（默认输入输出）：

uv run python .codex/skills/citation-diversifier/scripts/run.py --workspace <workspace>

触发词：cite boost、citation budget、unique citations too low、add more citations、improve reference density、引用太少、引用增加、引用密度。

报告应包含的内容

好报告应像一份约束表，而不是随机列表：

说明阻塞策略目标与目标差距（缺少多少唯一引用键；默认策略为 recommended）。
针对每个 H3 提出范围安全的预算，规模足以真正缩小差距：
- 小差距：每个 H3 通常 3–6 个键即可；
- course_paper：每个 H3 建议上限 3–6 个键，并建议面向该 profile 的 24/32 全局预算；
- A150++ 差距：计划每个 H3 约 6–12 个键，并避免在不同 H3 预算之间重复。
给出放置建议（在不新增事实的前提下可嵌入的位置）。

必需的规范化（可解析）行，下游校验器依赖这些行：

全局目标（策略；阻塞）：>= <N> …
Gap: <K>（差距；如果为 0，注入可以是 no-op PASS）

可选（始终报告；是否阻塞取决于 citation_target）：

Global recommended target: >= <N> …
Gap to recommended: <K>

推荐优先级（范围安全）：

allowed_bibkeys_selected
allowed_bibkeys_mapped
allowed_bibkeys_chapter

仅以下情况使用 allowed_bibkeys_global：基准/协议论文、广泛使用的数据集/套件、跨章节引用的横切综述/方法论文。

适用场景

综述或长文写作流水线中，草稿通过写作阶段后需要提升引用密度。
全局唯一引用数不达标、需要按小节系统规划引用补充。
需要把“补充引用”拆解为可按 H3 执行的可审计约束，而不擅自新增事实。

与其他技能的关系

生成预算报告后：

使用 citation-injector 将其应用到 output/DRAFT.md（由 LLM 编辑，不新增事实）。
再运行 draft-polisher 去除“预算倾倒式”语气，同时保持引用键不变。

注意：citation-injector 以 LLM 为主，其脚本仅用于校验。

限制

不可新增事实：只可提议 citations/ref.bib 中已存在的引用键。
不可引入需要新增论断或数字的“凑数引用”。
只提议目标 H3 范围内合规的键，优先小节范围。
技能本身不修改正文，只产出预算报告。
完成标准：output/CITATION_BUDGET_REPORT.md 存在且包含可执行的、范围安全的预算；在使用 citation-injector 应用计划后，pipeline-auditor 不再因全局唯一引用而 FAIL。