Markdown 格式化器

将纯文本或 markdown 转换为结构良好、对读者友好的 markdown。目标是帮助读者快速掌握关键点、重点和结构——不更改任何原始内容。

核心原则：仅调整格式并修复明显的拼写错误。绝不添加、删除或重写内容。

脚本目录

脚本位于 scripts/ 子目录中。{baseDir} = 此 SKILL.md 的目录路径。解析 ${BUN_X} 运行时：如果安装了 bun → 使用 bun；如果 npx 可用 → 使用 npx -y bun；否则建议安装 bun。用实际值替换 {baseDir} 和 ${BUN_X}。

首选项 (EXTEND.md)

检查 EXTEND.md 是否存在（优先级顺序）：

# macOS, Linux, WSL, Git Bash
test -f .baoyu-skills/baoyu-format-markdown/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-format-markdown/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md" && echo "user"

# PowerShell (Windows)
if (Test-Path .baoyu-skills/baoyu-format-markdown/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-format-markdown/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md") { "user" }

┌──────────────────────────────────────────────────────────┬───────────────────┐
│ 路径 │ 位置 │
├──────────────────────────────────────────────────────────┼───────────────────┤
│ .baoyu-skills/baoyu-format-markdown/EXTEND.md │ 项目目录 │
├──────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md │ 用户主目录 │
└──────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│ 结果 │ 操作 │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 找到 │ 读取、解析、应用设置 │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 未找到 │ 使用默认值 │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md 支持：

用法

工作流程分为两个阶段：分析（理解内容）然后格式化（应用格式）。Claude 执行内容分析和格式化（步骤 1-5），然后运行脚本进行排版修复（步骤 6）。

工作流程

步骤 1：读取与检测内容类型

读取用户指定的文件，然后检测内容类型：

如果检测到 Markdown，询问用户：

检测到现有的 markdown 格式。您想做什么？

1. 优化格式（推荐）
   - 分析内容，改进标题、粗体、列表以提高可读性
   - 运行排版脚本（间距、强调修复）
   - 输出：{文件名}-formatted.md

2. 保留原始格式
   - 保留现有的 markdown 结构
   - 仅运行排版脚本
   - 输出：{文件名}-formatted.md

3. 仅进行排版修复
   - 在原始文件上直接运行排版脚本
   - 不创建副本，直接修改原始文件

根据用户的选择：

• 优化：继续执行步骤 2（完整工作流程）
• 保留原始：跳到步骤 5，复制文件然后执行步骤 6
• 仅排版：跳到步骤 6，直接在原始文件上运行

步骤 2：分析内容（从读者角度）

仔细阅读整个内容。从读者的角度思考：什么能帮助他们快速理解和记住关键信息？

生成一份涵盖以下维度的分析：

2.1 重点与关键见解

• 作者提出的核心论点或结论
• 令人惊讶的事实、数据点或反直觉的断言
• 令人难忘的引述或措辞精妙的句子（金句）

2.2 结构评估

• 内容是否有清晰的逻辑流程？是什么？
• 是否存在自然的部分边界但缺少标题？
• 是否有长篇幅的文本块可以通过视觉分隔来改善？

2.3 对读者重要的信息

• 可操作的建议或要点
• 关键概念的定义、解释
• 隐藏在段落中的列表或枚举
• 用表格呈现会更清晰的比较或对比

2.4 格式问题

• 标题层级缺失或不一致
• 混杂了多个主题的段落
• 以段落形式编写的并列项，更适合作为列表
• 未标记为代码的代码、命令或技术术语
• 明显的拼写错误或格式错误

将分析保存到文件：{原始文件名}-analysis.md

分析文件作为步骤 3 的蓝图。使用此格式：

# 内容分析：{文件名}

## 重点与关键见解
- [列出发现]

## 结构评估
- 当前流程：[描述]
- 建议的章节：[列出标题候选及简要理由]

## 对读者重要的信息
- [列出可操作项、关键概念、埋藏的列表、潜在表格]

## 格式问题
- [列出具体问题及位置参考]

## 发现的拼写错误
- [列出任何明显的拼写错误及更正，或“未发现”]

步骤 3：检查/创建前置元数据、标题和摘要

检查 YAML 前置元数据（--- 块）。如果缺失则创建。

标题生成：

无论标题是否存在，始终运行标题优化流程（除非设置了 auto_select_title）。

准备工作 — 阅读全文并提取：

• 核心论点（一句话：“这篇文章是关于什么的？”）
• 最有影响力的观点或结论
• 读者的痛点或好奇心触发点
• 最令人难忘的隐喻或金句

生成 3-4 个风格各异的候选标题：

呈现给用户：

选择一个标题：

1. [标题 A] —（推荐）
2. [标题 B] — [风格说明]
3. [标题 C] — [风格说明]

输入数字，或键入自定义标题：

将最具吸引力的标题放在第一位并标记为（推荐）。

标题原则：

• 前 5 个字就抓住读者：制造信息缺口或认知冲突
• 具体优于抽象：“150 行”优于“一份文档”
• 否定优于肯定：“你一直做错了”优于“正确的方法”
• 口语化：像和朋友聊天，而不是论文题目
• 最多约 25 个字：过长的标题在信息流中会被截断
• 准确，非标题党：文章必须兑现标题的承诺

禁止的模式：

• “浅谈 XX”、“关于 XX 的思考”、“XX 的探索与实践”
• “震惊！”、“万字长文”、“建议收藏”
• 无方向的纯问题：“AI 写作的未来在哪里？”

如果第一行是 H1，将其提取到前置元数据并从正文中移除。如果前置元数据中已有 title，将其作为上下文包含进来，但仍需生成新的候选标题。

摘要生成：

生成 3 个不同角度的候选摘要。呈现给用户：

选择一个摘要：

1. [摘要 A] — [重点说明]
2. [摘要 B] — [重点说明]
3. [摘要 C] — [重点说明]

输入数字，或键入自定义摘要：

摘要原则：

• 80-150 个字符，精确且信息丰富
• 传达给读者的核心价值，而不仅仅是主题
• 角度多样化：问题驱动、结果驱动、见解驱动
• 吸引读者：让他们想要阅读全文
• 使用具体细节（数字、成果、具体方法）而非模糊描述

禁止的模式：

• “本文介绍了…”、“本文探讨了…”
• 仅描述主题而无价值主张
• 用不同的词重复标题

如果前置元数据中已有 summary，跳过选择直接使用。

EXTEND.md 跳过行为：如果在 EXTEND.md 中设置了 auto_select: true，则跳过标题和摘要的选择——直接生成最佳候选而不询问。用户也可以独立设置 auto_select_title: true 或 auto_select_summary: true。

一旦标题放入前置元数据，正文中不应再有 H1（避免重复）。

步骤 4：格式化内容

根据步骤 2 的分析指导应用格式。目标是让内容易于浏览，关键点一目了然。

格式化工具箱：

格式化原则——不要做：

• 不要添加句子、解释或评论
• 不要删除或缩短任何内容
• 不要改写或重述作者的词语
• 不要添加带有主观意见的标题（例如，“惊人发现”——使用中性描述性标题）
• 不要过度格式化：不是每个句子都需要加粗，不是每个段落都需要标题

格式化原则——要做：

• 保留作者的语气、风格和每一个字
• 将关键结论和核心要点加粗——读者会想要标记的那些句子
• 只有当段落结构明显存在并列项时，才将其提取为列表
• 在主题真正转变的地方添加标题——优先选择生动具体的标题，而不是通用的标题（例如，“3 天搞定 vs 传统方案”优于“方案对比”）
• 对隐藏在段落中的比较或结构化数据使用表格
• 对金句、令人难忘的陈述或重要警告使用引用块
• 修复明显的拼写错误（基于步骤 2 的发现）

步骤 5：保存格式化后的文件

保存为 {原始文件名}-formatted.md

备份现有文件：

if [ -f “{文件名}-formatted.md” ]; then
  mv “{文件名}-formatted.md” “{文件名}-formatted.backup-$(date +%Y%m%d-%H%M%S).md”
fi

步骤 6：执行排版脚本

在输出文件上运行格式化脚本：

${BUN_X} {baseDir}/scripts/main.ts {输出文件路径} [选项]

脚本选项：

示例：

# 默认：启用间距 + 强调，禁用引号替换
${BUN_X} {baseDir}/scripts/main.ts article.md

# 启用所有功能，包括引号替换
${BUN_X} {baseDir}/scripts/main.ts article.md --quotes

# 仅修复强调问题，跳过间距
${BUN_X} {baseDir}/scripts/main.ts article.md --no-spacing

脚本执行的操作（基于选项）：

1. 修复中日韩文字强调/加粗的标点问题（默认：启用）
2. 通过 autocorrect 工具添加中日韩文字/英文混合文本间距（默认：启用）
3. 将 ASCII 引号替换为全角引号（默认：禁用）
4. 格式化前置元数据 YAML（始终启用）

步骤 7：完成报告

显示一份总结所有更改的报告：

**格式化完成**

**文件：**
- 分析文件：{文件名}-analysis.md
- 格式化文件：{文件名}-formatted.md

**内容分析摘要：**
- 发现重点：X 个关键见解
- 金句：X 个令人难忘的句子
- 修复的格式问题：X 项

**应用的更改：**
- 前置元数据：[已添加/已更新]（标题、别名、摘要）
- 添加的标题：X 个（##：N 个， ###：N 个）
- 添加的粗体标记：X 个
- 创建的列表：X 个（从段落 → 列表转换）
- 创建的表格：X 个
- 添加的代码标记：X 个
- 添加的引用块：X 个
- 修复的拼写错误：X 个 [逐一列出：“原词” → “更正词”]

**排版脚本：**
- 中日韩文字间距：[已应用/已跳过]
- 强调修复：[已应用/已跳过]
- 引号替换：[已应用/已跳过]

调整报告以反映实际更改——省略未做更改的类别。

备注

• 保留原始写作风格和语气
• 为代码块指定正确的语言（例如，python、javascript）
• 维护中日韩文字/英文间距标准
• 分析文件是一个工作文档——它有助于保持已识别内容和已格式化内容之间的一致性

扩展支持

通过 EXTEND.md 进行自定义配置。有关路径和支持的选项，请参阅首选项部分。