citation-diversifier

引用多样化器（以预算为约束）[NO NEW FACTS]

触发条件与路由

• 触发条件：提升引用、引用预算、独特引用太少、添加更多引用、提高参考文献密度、引用太少、增加引用、引用密度。

用途：修复常见的综述失败模式：

• 草稿中的引用不足（或反复在各处使用同几条引用）
• 流程未能通过全局独特引用门槛

此技能本身不会修改正文。 它会生成一份约束清单：output/CITATION_BUDGET_REPORT.md。

输入

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

输出

• output/CITATION_BUDGET_REPORT.md

不容妥协的要求（NO NEW FACTS）

• 仅建议 citations/ref.bib 中存在的引用键。
• 仅建议目标 H3 适用范围内的引用键（优先使用小节级范围；仅在确实适用于多个部分时使用章节级/全局范围）。
• 不要建议需要添加新观点或新数据的“凑数引用”。

优质预算报告的样式（规范）

报告应像一份约束清单，而不是随意罗列：

• 说明阻断性策略目标和距目标的差距（还缺少多少个独特引用键；策略默认值为 recommended）。
• 针对每个 H3，提出范围安全、足以弥补差距的预算：
  • 差距较小时，每个 H3 通常 3-6 个引用键就足够
  • 对于 course_paper，每个 H3 的建议数量上限为 3-6 个引用键，并以该配置的全局预算 24/32 为目标
  • 对于 A150++，计划每个 H3 约 6-12 个引用键（并避免不同 H3 预算之间出现重复）
• 提供位置建议（指出如何在不添加新事实的前提下，将这些引用键嵌入小节）

必须包含以下标准（可解析）行（下游验证器依赖这些内容）：

• 目标取自 queries.md:citation_target（A150++ 默认为 recommended）。
• - Global target (policy; blocking): >= <N> ...
• - Gap: <K>（距目标的差距；若为 0，则注入操作可以不做任何更改并通过）

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

• - Global recommended target: >= <N> ...
• - Gap to recommended: <K>

建议的优先级（确保范围安全）：

• allowed_bibkeys_selected → allowed_bibkeys_mapped → allowed_bibkeys_chapter
• allowed_bibkeys_global 仅用于：
  • 基准测试/协议论文
  • 广泛使用的数据集/套件
  • 在多个章节中引用的跨领域综述/方法论文

与写作流程的衔接（以 LLM 为先）

生成预算报告后：

• 使用 citation-injector 应用报告（由 LLM 修改 output/DRAFT.md，NO NEW FACTS）。
• 然后运行 draft-polisher，去除任何“预算清单式”的语气，同时保持引用键不变。

重要提示：citation-injector 以 LLM 为先。其脚本仅用于验证。

工作流

1. 诊断全局情况

• 阅读 output/DRAFT.md 并估算“独特引用键差距”（或使用 pipeline-auditor 的 FAIL 原因）。

2. 按 H3 分配预算（范围优先）

• 使用 outline/outline.yml 按论文顺序列出 H3。
• 对每个 H3，从 outline/writer_context_packs.jsonl 中读取其允许的引用键集合。
• 选取一组少量的未使用引用键，在不需要新观点的前提下增强论述定位。

3. 编写 output/CITATION_BUDGET_REPORT.md 必需结构：

• - Status: PASS|FAIL
• - Global target (policy; blocking): >= <N> ...
• - Gap: <K>
• ## Summary（差距 + 策略）
• ## Per-subsection budgets（H3 标识符/标题 → 建议引用键 → 位置提示）

脚本（可选；确定性报告生成器）

如果需要确定性的初版预算报告，请运行辅助脚本。将其视为基线，并根据需要完善方案。

快速开始

• 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>

完成标准

• output/CITATION_BUDGET_REPORT.md 存在，且包含可执行、范围内的预算。
• 通过 citation-injector 应用计划后，pipeline-auditor 不再因全局唯一引用而 FAIL。