技能介绍

技术文档协作中常见的一种混乱：作者按 1. / 1.1 / 1.1.1 的数字大纲写作，但 Markdown 标题全部平铺成同一级 ##；正文里混着 ● 要点、用；连写的编号列表；最终渲染出来没有目录，或者目录链接点不动。这个技能针对这类「标题平铺 + 编号大纲」的文档做一次结构化清理，输出层级清晰、列表逐行、带可跳转目录的规范 Markdown。

核心能力

重建标题层级：按编号的「点」数映射层级——N. 映射为 H2（章节），N.N 映射为 H3（节），N.N.N 映射为 H4（子节）；全文第一个无编号标题升为 H1；● 子标题降为 H5 并去掉符号；带冒号的内联子标题同样降级。
拆分列表与补齐空行：在 ；/。 之后、数字） 之前插入换行，把连写的编号拆成逐行条目；确保每个标题行与其后正文之间有一个空行。
格式化要点：把 ● 标题：内容 拆成加粗标题加缩进子项；后续的数字编号行一并收为同级缩进子项；无冒号的纯 ● 行仅替换符号。
生成目录：在 H1 之后插入目录，默认提取到 H3，链接风格可选 wikilink 或 github。

处理流程

脚本 scripts/cleanup_markdown.py 把上述步骤串成固定顺序的 4 步流水线，每步读入上一步的结果，就地处理目标 .md 文件。目录深度、链接风格由参数控制，每个步骤也可通过 --skip-* 开关单独跳过。

适用边界

幂等性：流程专为「标题平铺 + 编号大纲」类文档设计，对层级已经正确的文档重复运行标题重建可能破坏结构。
目录防重复：若文档前 50 行已存在 ## 目录，生成步骤自动跳过。
链接风格：wikilink 双链语法只在部分笔记工具中可点击；目标平台是 GitHub 或 VS Code 预览时请改用 github 风格，其中文锚点按 GitHub 规则生成。
就地修改：脚本直接改写原文件，处理重要文档前先备份。