Imported from dunwu/skillbox (skills/markdown-doc-guide/SKILL.md). Install upstream with npx skills add dunwu/skillbox --skill markdown-doc-guide. Copyright stays with the author.

中文技术文档格式化规范

规范内容主要来自：阮一峰的项目 document-style-guide。

本 Skill 约束 AI 在编辑 Markdown 文档时的质量，确保所有输出符合统一的文档标准。

触发场景

当用户出现以下任一意图时，必须激活本 Skill：

• "格式化这篇 markdown" / "美化文档" / "按规范整理" / "按文档规范格式化"
• "编辑 .md 文件"
• 英文触发词：format markdown / beautify document / polish doc / edit .md
• 任何涉及修改 Markdown 文档内容的请求

核心原则

1. 段落边界神圣不可侵犯：禁止把由空行分隔的独立段落合并成一段连续文本。
2. 只做排版、不改语义：不增删原文含义，不替换同义词，不调整句子结构。
3. 链接路径原样保留：[文本](路径) 中 () 内的路径字符串必须原样保留。
4. 代码块内部只读：可以修正代码块的语言标注，但禁止改动代码块内的任何字符。
5. 结构只读：不增删章节标题、不删除注释、不改列表与段落的互相转换、不改 HTML/VuePress 特殊语法块的属性和结构。

执行工作流

Step 0：🔴 CHECKPOINT · 前置检查与失败处理

读取目标文件前，必须完成以下前置检查。任一检查失败时，按对应分支处理：

🛑 未通过本 CHECKPOINT，不得进入 Step 1。前置检查失败时必须向用户报告，不得静默跳过或猜测修复。

Step 1：读取并分区

输入：通过 Step 0 检查的文件原始内容。

读取目标文件后，先标记出以下区域，不同区域适用不同规则：

输出：分区标记完成后的文件结构图，供后续步骤按区域差异化处理。

Step 2：🔴 CHECKPOINT · 高风险扫描 + 按优先级应用规范

🔴 进入规则应用前，先扫描目标文件是否存在以下高风险元素。若存在，按对应策略处理后再继续。

未通过本 CHECKPOINT 扫描，不得进入规则应用。

通过扫描后，同一处文本同时命中多条规则时，按以下优先级执行：

1. 段落保护：soft line break 只能在段落内部归一化为空格，不能跨段落合并。
2. 标点符号：中文语句用全角标点；纯英文整句用半角标点；点号不出现在行首和标题末尾。
3. 字间距：
   • 全角中文与半角英文/数字之间加半角空格。
   • 英文与全角标点之间不加空格。
   • 行内代码、链接路径、命令参数中的空格保持原样。
4. 术语统一：将混用或不规范的术语改为规范形式（详见下文「术语统一表」）。
5. 代码块语言标注：
   • 命令行工具 / JVM 参数 / shell 脚本 → shell
   • 纯输出 / 日志 / thread dump → text
   • Java 代码 → java
   • 已有正确标注的，不重复修改。
6. 文件末尾：确保文件以单个换行符（\n）结尾。

Step 3：🔴 CHECKPOINT · 三不校验 + 结构校验（if-then fallback）

修改完成后，必须逐项确认。若校验失败，按以下三段式处理：

🛑 本 CHECKPOINT 为硬性门禁：所有校验项全部通过前，禁止进入 Step 4。

所有兜底操作执行后，必须重新从 Step 1 开始检查，确保修复没有引入新的违规。

Step 4：输出变更摘要

向用户汇报时包含：

• 修改的文件数量
• 主要变更类型（如：修复空格、统一术语、修正代码块语言标注）
• 明确说明"已保留段落边界、链接路径、代码块内容、章节标题、注释、列表结构和 HTML 属性"

Step 5：🔴 STOP · 歧义处理

遇到以下情况，必须 🛑 STOP 并询问用户，不得自主决定：

• 用户原文明显违反规范但可能是故意为之（如标题末尾的句号、艺术化排版）。
• 同一处存在多种规范解释且无法按"冲突裁决表"判定。
• 用户要求"只改某一部分"但范围不清晰。
• 无法判定某段文本属于"中文语句"还是"纯英文整句"（参见下文「语句类型判定规则」）。

红灯清单（禁止做）

以下行为绝对禁止：

语句类型判定规则

标点符号规则依赖"中文语句"和"纯英文整句"的判定。按下表执行：

判定模糊时，触发 Step 5 🛑 STOP 歧义处理，不得自行推断。

术语统一适用范围界定

术语统一仅适用于普通说明文字。按下表界定适用与不适用范围：

判定模糊时（如表格单元格同时包含行内代码和说明文字），仅对说明文字部分做术语替换，行内代码部分保持原样。

冲突裁决表

当规则冲突时，按以下优先级执行：

术语统一表

以下术语在普通说明文字中必须统一为右侧规范形式（代码块、行内代码、命令参数、链接路径除外）：

如需扩展术语表，参考 references/terminology.md。

自检清单

修改完成后，必须逐项确认：

• 没有合并由空行分隔的独立段落。
• 没有修改任何 [文本](路径) 或 ![alt](路径) 中的路径。
• 没有改动任何代码块或行内代码的内部字符。
• 没有新增或删除任何章节标题。
• 没有删除或修改任何 HTML 注释。
• 没有将列表改为段落或将段落改为列表。
• 没有修改 HTML 标签属性或 VuePress 守卫属性。
• 没有修改表格的列数或行数。
• 中文语句使用全角标点，纯英文整句使用半角标点。
• 中英文/数字之间已按规则添加或保持半角空格。
• 常见术语已按「术语统一表」统一（仅普通说明文字）。
• 代码块语言标注正确（shell / text / java 等）。
• 文件以单个换行符结尾。
• 已输出变更摘要。
• 文件结构完整性：仅 1 组 frontmatter（2 个 ---）、仅 1 个 # H1 标题、无旧内容拼接。
• Write 全量覆盖后已读回验证，确认旧内容未被追加到新内容尾部。

详细规约参考：

• 标题：references/title.md
• 文本：references/text.md
• 段落：references/paragraph.md
• 数值：references/number.md
• 标点符号：references/marks.md
• 文档体系：references/structure.md
• 术语表：references/terminology.md

文档模板

当用户需要从零创建某类中文技术文档时，优先使用对应模板。模板本身已符合本 Skill 的格式规范，生成后只需按实际内容填空，无需再整体格式化。

使用方式：

1. 根据目标文档类型选择对应模板。
2. 保留章节结构，删除示例占位内容，替换为实际内容。
3. 按本 Skill 规范检查空格、标点、术语和代码块语言标注。
4. 完成后执行「自检清单」。