sn-prepare-citations

1# sn-prepare-citations（引用渲染）
2 
3处理 sn-deep-research 的 `stitched.md`：从 evidence.json 收集 `sources[]`，将正文中的 `[^source_id]` 转换为 `[N]` 编号引用，插入 L0/TOC，并追加参考文献。
4 
5## 推荐用法（sn-deep-research v2）
6 
7```bash
8python3 scripts/prepare_citations.py \
9  --report <report_dir>/stitched.md \
10  --evidence <report_dir>/sub_reports/d1.evidence.json <report_dir>/sub_reports/d2.evidence.json \
11  --outline <report_dir>/outline.json \
12  --output <report_dir>/report.md
13```
14 
15## 参数
16 
17| 参数 | 说明 |
18|---|---|
19| `--report` | 输入 markdown。sn-deep-research 中通常是 `stitched.md` |
20| `--evidence` | 全部 `d*.evidence.json`，用于收集 source 元数据和修复 claim-id 泄漏 |
21| `--outline` | 可选但推荐。提供 L0、TOC 和标题结构信息 |
22| `--output` | 输出 markdown。sn-deep-research 中通常是 `report.md` |
23| `--no-l0` | 关闭 L0 摘要层渲染 |
24| `--no-toc` | 关闭 TOC 渲染 |
25 
26## 处理逻辑
27 
281. 从所有 evidence.json 的 `sources[]` 收集引用元数据。
292. 按 URL 归一化去重，同 URL source 合并为同一编号。
303. 检测 `[^dN.cM]` claim-id 引用泄漏；能映射到 claim evidence 时替换为对应 `source_id`，不能映射则报告 unresolved。
314. 扫描正文中的 `[^source_id]`，按首次出现顺序分配编号。
325. 替换 `[^source_id]` → `[N]`，移除脚注定义行。
336. 根据 outline 插入或校准 L0 / TOC。
347. 追加 `## 参考文献`。
358. 写出 `report.md` 和同目录 `citations.json`。
369. stdout 输出结构化 JSON，包含 orphan citations、claim-id leakage、TOC 和 L0 状态。
37 
38## 控制器处理要求
39 
40- `orphan_citations` 非空：不要交付，回 writer/stitcher 修正引用或删除 unsupported 内容。
41- `claim_id_leakage.unresolved` 非空：不要交付，回 writer 修正 `[^dN.cM]`。
42- `claim_id_leakage.resolved` 非空但 unresolved 为空：可以继续，但记录为警告；writer 后续应直接输出 `[^source_id]`。
43 
44## 旧兼容模式
45…