技能介绍

它解决什么问题

团队里常见的一类麻烦：Markdown 文件来自不同编辑器、不同提交历史，列表缩进、标题前后空行、链接写法、代码围栏的语言标注常常不统一。这类差异本身不影响渲染结果，却会让每次 PR 的 diff 夹杂大量无意义的空白和标点改动，把真正的改动淹没掉。在做仓库迁移、文档批量清理或引入 CI 校验时情况更糟：同一批文件在不同人手里会得到不同结果，diff 不可预测，review 退化成"又格式化了一遍"。

mdformat 的价值在于把这件事变成确定性的：同样的输入，永远得到同样的输出。

技能如何工作

这个技能把上述能力封装成一步可复用的操作，核心流程很直接：

圈定目标文件：在审查或迁移前，扫描仓库内的 .md 文件，明确这次要覆盖的范围。
统一重写：调用 mdformat 把每个文件重排为一致的 CommonMark 风格布局，包括标题间距、列表缩进、段落间空行与行尾空白。
检查模式：以 check 方式运行，只在格式不符时报告差异而不落盘；这一形态可以直接接进 CI 流水线，作为合并前的守门步骤。
产出可预期的 diff：重排后的改动纯属格式化，reviewer 看到的边界清晰，可以据此判断"是否发生了真实内容变更"。

它同时是一个命令行工具和 Python 库，依赖 Python 3 环境。

适用边界与注意点

不是内容生成工具：它只重排已有文本，不会补全段落、改写措辞，也不能拿来搭建文档站点。
扩展需要显式启用：GFM 的表格、删除线等特性不在 CommonMark 范围内，必须显式 require 并启用对应的 extension 插件；若要顺带规整代码块内部，还需要 code formatter 插件。两者都不会静默生效。
它会改动源码文件：这正是本技能的目的，但在迁移前建议先在本地跑一次，把格式化改动与业务改动拆成两个 commit。
只处理 Markdown：嵌入的 HTML 片段或其他非 Markdown 内容不在处理范围内。