Markdown 文档整理（md-doc-cleanup）

将结构混乱的长 Markdown 文档整理为层级清晰、列表规整、带可跳转目录的规范文档。

适用场景

• 文档标题被平铺在同一个级别（几乎全是 ##），但正文带有清晰的数字编号大纲（1. / 1.1 / 1.1.1）。
• 同一行内用 ； 连写多个编号项：1）…；2）…；3）…。。
• 要点用 ● 标题：内容 形式，未加粗、未断行、未缩进。
• 没有目录，或目录链接在目标渲染器里无法点击跳转。

处理流程（4 步，按顺序执行）

脚本 scripts/cleanup_markdown.py 按固定顺序串起全部步骤，每步读入上一步的结果：

1. 重建标题层级 fix_headings：依据数字编号的「点」数映射层级——N.→H2（章节），N.N→H3（节），N.N.N→H4（子节）；全文第一个无编号标题升为 H1（主标题）；## ● 要点： 这类 ● 子标题降为 H5 并去掉 ●；带冒号的内联子标题（## 2. 检索策略：）降为 H5。
2. 拆分列表 + 标题空行 fmt_list_blanks：在 ；/。 后、数字） 前插入换行，把连写编号拆成逐行；确保每个标题行与其后正文之间有一个空行（标题后已是空行或紧跟另一个标题则不插）。
3. 格式化要点 fmt_bullets：把 ● 标题：内容 转为 * **标题**： 并换行，内容缩进为子项 * 内容；若内容（或紧随的后续行）含 数字） 编号，则把后续编号行一并收为同级缩进子项；无冒号的纯 ● 行仅把 ● 换成 *。
4. 生成目录 gen_toc：在 H1 标题之后插入 ## 目录 + 说明 + TOC 列表 + --- 分隔线。TOC 默认提取到 H3（章节+节），H4/H5 不进目录。链接风格由 --toc-style 决定。

脚本用法

# 默认：重建层级 + 拆分列表 + 格式化要点 + 生成 wiki-link 风格目录（到 H3）
python scripts/cleanup_markdown.py article.md

# 生成 GitHub 标准锚点链接的目录
python scripts/cleanup_markdown.py article.md --toc-style github

# 目录细化到子节（H4）
python scripts/cleanup_markdown.py article.md --toc-depth 4

# 只做其中某几步（用 --skip-* 关闭其余步骤）
python scripts/cleanup_markdown.py article.md --skip-toc          # 不生成目录
python scripts/cleanup_markdown.py article.md --skip-headings     # 标题已正确时跳过层级重建

参数

注意事项 / 边界情况

• 幂等与适用范围：本流程针对「标题平铺 + 编号大纲」这类混乱文档设计。对层级已经正确的文档重复运行 fix_headings 可能破坏结构，此时用 --skip-headings。
• 目录防重复：若文档前 50 行已存在 ## 目录，gen_toc 会自动跳过，不重复插入。
• wiki-link 兼容性：[[## 标题]] 是部分笔记/渲染器（如支持双链的工具）的语法；若目标平台是 GitHub / VS Code 预览，请用 --toc-style github。
• 中文锚点：github 风格下锚点按 GitHub 规则生成（小写、去标点、空格转 -、中文保留），与渲染器默认跳转一致。
• 执行前建议备份：脚本就地修改原文件，处理重要文档前先 git stash 或复制一份。