README 美化器

接收一份结构混乱或格式不统一的 README，输出结构清晰、格式一致、视觉专业的版本。

核心原则

• 内容不增不减：不编造信息，不删除有效内容，只做结构和格式层面的改善
• 忠于原意：保留作者的表达意图和语气，不做风格改写
• 最小改动：能小修的不大改，能调格式的不重写
• 尊重原文，不强行套用：原文已有的合理选择（章节顺序、是否加徽章/目录/中英文空格）一律保留，缺什么也不主动补——下面的检查清单据此判断，不再逐项重复这条原则

美化流程

1. 读取 README → 理解项目是什么、面向谁
2. 诊断问题 → 逐项检查下面的检查清单
3. 制定方案 → 列出要改什么、为什么改
4. 执行美化
5. 给出摘要

第 4、5 步按下面「输出格式」交付。

检查清单

按优先级从高到低排列。每项只在确实存在问题时才修复。

1. 标题层级

• h1 只出现一次，用于项目名
• 层级连续递增，不跳级（h1 → h3 是错的）
• 同级标题的粒度对齐（不要一个 h2 是"安装"，另一个 h2 是"如何在 Docker 里用 volume 挂载配置文件"）

2. 一句话描述

• 项目名下方紧跟一句话说清楚这个项目是什么、做什么
• 用 > 引用块或普通段落均可，但要有
• 如果原文已有但藏在中间，提到开头

3. 段落结构

• 每个章节有明确的职责，不混杂多个主题
• 常见的合理顺序：是什么 → 快速开始 → 用法 → 配置 → 目录结构 → 贡献 → 许可证
• 空章节（只有标题没有内容）删掉或补一句说明

4. 列表格式

• 同一个列表内的条目格式统一（全用 - 或全用 *，不混用）
• 嵌套缩进一致（2 空格或 4 空格，不混用）
• 有序列表用 1. 自动编号而非手动编号（避免插入条目后序号错乱）
• 列表前后有空行

5. 代码块

• 所有代码块标注语言（bash / yaml / ```text 等）
• 行内代码用反引号包裹：命令、文件名、变量名、包名
• 命令示例中去掉不必要的 $ 前缀（除非需要区分输入和输出）
• 多行命令用代码块而非行内代码

6. 表格

• 列对齐（不要求像素级对齐，但至少视觉上整齐）
• 表头有意义
• 如果表格只有两列且内容简短，考虑是否列表更合适
• 如果列表有三个以上平行维度的信息，考虑是否表格更合适

7. 链接与引用

• 链接文字有意义（不要 "点击这里"、"链接"）
• 检查明显的死链格式（[text]() 空链接、[text](TODO) 占位符）
• 相对路径与绝对路径的使用是否合理

8. 空白与分隔

• 标题前空一行
• 段落之间空一行
• 不要连续两个以上空行
• 中英文之间加空格（原文大部分已加则统一补齐，大部分没加则跟随原文）
• 列表和段落之间空一行
• 文件以单个换行符结尾（无多余空行，也不缺换行）

9. 徽章（Badges）

• 原文有徽章才整理：统一放在项目名下方、一句话描述上方
• 徽章之间用空格分隔，不换行

10. 目录（TOC）

• 章节超过 6 个时建议添加目录，6 个以内不加
• 目录用链接列表，指向对应标题的锚点
• 如果原文已有目录但锚点失效，修复而非删除

不做的事

• 不加装饰性元素：不加 emoji、分隔线、花哨的 ASCII art，除非原文已有
• 不改技术内容：不改命令、不改配置项、不改代码示例的逻辑
• 不翻译：不把中文翻成英文，也不反过来
• 不补内容：如果缺少"贡献指南"章节，不自动补一个——只在摘要里提一句"可以考虑补充"
• 不改文件名：输出的还是 README.md，不改成别的

换用别的技能

本技能只管格式和结构，不管内容对不对。用户说"检查我的 README"时要区分意图：

• 想确认 README 写的内容跟代码/配置/接口是否一致、有没有过时 → 用 hai-audit-docs-against-code
• 想做文档内部一致性 / 陈旧内容审查（不跟代码对比）→ 用 hai-audit-docs-internally
• 想美化排版、统一格式、理顺结构 → 就是本技能

输出格式

常规路径：直接输出美化后的完整 README 内容，然后附一段简短摘要。

<完整的美化后 README.md 内容>

---

**美化摘要**

改动了以下几点：
- ...

建议后续补充（不在本次改动范围内）：
- ...

README 已经规范、无需改动时的输出格式（检查摘要），见 references/output-template.md 末尾。两种完整交付模板都在该文件，定稿前对照一遍。

边界情况

• README 非常短（< 10 行）：只做格式修复，不人为撑篇幅
• README 非常长（> 300 行）：优先修复结构问题，格式问题只修最刺眼的
• 多语言 README：只美化当前文件，不动其他语言版本
• README 本身就很好：不强行改，按 references/output-template.md 末尾的「检查摘要」格式回复