sn-prepare-citations

sn-prepare-citations (citation rendering)

Process sn-deep-research's stitched.md: collect from evidence.json sources[], convert the [^source_id] in the body to [N] numbered citations, insert L0/TOC, and append the references.

Recommended usage (sn-deep-research v2)

python3 scripts/prepare_citations.py \
  --report <report_dir>/stitched.md \
  --evidence <report_dir>/sub_reports/d1.evidence.json <report_dir>/sub_reports/d2.evidence.json \
  --outline <report_dir>/outline.json \
  --output <report_dir>/report.md

Parameters

Parameter	Description
--report	Input markdown. In sn-deep-research this is usually stitched.md
--evidence	All d*.evidence.json, used to collect source metadata and fix claim-id leakage
--outline	Optional but recommended. Provides L0, TOC, and heading structure information
--output	Output markdown. In sn-deep-research this is usually report.md
--no-l0	Disable L0 summary layer rendering
--no-toc	Disable TOC rendering

Processing logic

1. From the sources[] of all evidence.json files, collect citation metadata.
2. Deduplicate by URL normalization; sources with the same URL are merged into the same number.
3. Detect [^dN.cM] claim-id citation leakage; when it can be mapped to claim evidence, replace it with the corresponding source_id; when it cannot be mapped, report it as unresolved.
4. Scan the [^source_id]in the body and assign numbers in order of first appearance.
5. Replace [^source_id] → [N], and remove footnote definition lines.
6. Insert or calibrate L0 / TOC according to the outline.
7. Append ## 参考文献。
8. Write out report.md and, in the same directory, citations.json。
9. stdout outputs structured JSON, including orphan citations, claim-id leakage, TOC, and L0 status.

Controller handling requirements

• orphan_citations is non-empty: do not deliver; go back to the writer/stitcher to fix the citations or delete unsupported content.
• claim_id_leakage.unresolved is non-empty: do not deliver; go back to the writer to fix [^dN.cM]。
• claim_id_leakage.resolved is non-empty but unresolved is empty: you may continue, but record it as a warning; the writer should subsequently output directly [^source_id]。

Legacy compatibility mode

When --outline / --output is not passed, the script overwrites the file pointed to by --report , performing only citation numbering and reference appending. The normal sn-deep-research workflow does not use this mode.