80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
---
|
|
name: repair-markdown-citations
|
|
description: Use when a Markdown export from ChatGPT Deep Research or another LLM contains broken citation tokens such as `citeturn34view0turn20search2` 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
|
|
```
|