---
name: repair-markdown-citations
description: Use when a Markdown export from ChatGPT Deep Research or another LLM contains broken citation tokens such as `citeturn34view0turn20search2` that need to be converted into standard Markdown footnotes and a deduplicated `## 参考资料` section. Use for repairing turn-ID citations, cleaning citation mojibake, preserving source links, and safely degrading when metadata is missing.
---

# Repair Markdown Citations

## Purpose

Repair ChatGPT/Deep Research Markdown citation tokens into readable Markdown. Use the bundled script for deterministic edits instead of rewriting the document by prompt.

The primary rule is exact ID mapping: treat `turn34view0`, `turn20search2`, and similar IDs as citation primary keys. Do not assume the citation token order matches `safe_urls`, a footer link list, or source appearance order.

## Capability Levels

Level 1: no metadata cleanup.

- Remove malformed `cite...` tokens outside fenced code blocks.
- Preserve existing links from an old `## 参考资料` section as ordinary source links.
- Add a warning that逐句脚注映射 could not be recovered.

Level 2: `content_references` metadata.

- Build a citation map from metadata refs keyed by turn ID.
- Replace citation tokens in正文 with Markdown footnote markers such as `[^1][^2]`.
- Generate a deduplicated `## 参考资料` section in first-citation order.

Level 3: complete Deep Research export.

- Prefer exact `ref_id` / `turn_index` / `ref_type` / `ref_index` fields wherever available.
- Use richer fields such as title, attribution, source, and site name when present.
- Treat source grouping, dates, snippets, and risk checks as future enrichment, not required first-pass behavior.

## Workflow

1. Confirm the input is a Markdown file exported from ChatGPT/Deep Research or converted from a report containing citation tokens.
2. Prefer an explicit metadata JSON file. If the user has one, pass it with `--metadata`.
3. If no metadata file is available, let the script look for an embedded HTML comment block named `deep-research-metadata`.
4. Choose output mode:
   - Use `--output` for a non-destructive repaired copy.
   - Use `--in-place` only when the user wants the original file rewritten.
   - Use `--dry-run` before editing important files.
5. Inspect the resulting `## 参考资料` section and any `未解析引用 ID` warnings.

## Commands

```powershell
conda run -n skills-vault python .\scripts\repair_markdown_citations.py "C:\path\report.md" --metadata "C:\path\report.metadata.json" --output "C:\path\report.fixed.md"
conda run -n skills-vault python .\scripts\repair_markdown_citations.py "C:\path\report.md" --metadata "C:\path\report.metadata.json" --in-place
conda run -n skills-vault python .\scripts\repair_markdown_citations.py "C:\path\report.md" --dry-run
```

## Embedded Metadata

The script can read a Markdown HTML comment block:

```md
<!-- deep-research-metadata
{"content_references":[...]}
-->
```

Use embedded metadata only when an external JSON file is unavailable or when the report intentionally carries its own citation map.

## Safety Rules

- Do not map citations by `safe_urls` order or by footer link order.
- Do not fabricate footnotes when a turn ID has no URL in the citation map.
- Do not rewrite citation-like text inside fenced code blocks.
- Do not delete user-authored prose or non-reference sections.
- If metadata is missing or incomplete, preserve recoverable source links and clearly mark the output as degraded.

## Validation

Run the Skill tests after modifying behavior:

```powershell
conda run -n skills-vault python -m unittest discover -s skills/repair-markdown-citations/tests -v
```