Markdown 格式化

技能文档

---
name: baoyu-format-markdown
title: Markdown 格式化
category: 内容创作
description: 将纯文本或 Markdown 文件格式化为结构清晰、易于阅读的文档，自动添加 frontmatter、标题、摘要、层级标题、加粗、列表、代码块等。当用户请求「格式化 Markdown」「美化文章排版」「添加格式」「改善文章结构」「排版优化」时触发。
---

# Markdown 格式化器

将纯文本或 Markdown 转化为结构清晰、对读者友好的文档。目标是帮助读者快速把握要点、亮点和结构——不改变任何原始内容。

**核心原则**：仅调整格式和修正明显错别字，不增删或改写内容。

## 用户输入工具

当技能需要向用户提问时，按以下优先级选择工具：

1. **优先使用当前 Agent 运行时内置的用户输入工具**——如 `AskUserQuestion`、`request_user_input`、`clarify`、`ask_user` 或任何等效工具。
2. **回退方案**：若无此类工具，输出编号文本消息，请用户回复编号或答案。
3. **批量提问**：若工具支持单次多问，合并所有问题为一次调用；若仅支持单问，按优先级逐个提问。

下文中的 `AskUserQuestion` 引用仅为示例，请替换为当前运行时的等效工具。

## 脚本目录

脚本位于 `scripts/` 子目录。`{baseDir}` = 本 SKILL.md 所在目录路径。解析 `${BUN_X}` 运行时：若安装了 `bun` 则用 `bun`；若 `npx` 可用则用 `npx -y bun`；否则建议安装 bun。将 `{baseDir}` 和 `${BUN_X}` 替换为实际值。

| 脚本 | 用途 |
|------|------|
| `scripts/main.ts` | 主入口，含 CLI 选项（使用 remark-cjk-friendly 处理 CJK 强调符号） |
| `scripts/quotes.ts` | 将 ASCII 引号替换为全角引号 |
| `scripts/autocorrect.ts` | 通过 autocorrect 添加中英文间距 |

## 偏好配置（EXTEND.md）

按优先级检查 EXTEND.md——首个命中即生效：

| 优先级 | 路径 | 作用域 |
|--------|------|--------|
| 1 | `.baoyu-skills/baoyu-format-markdown/EXTEND.md` | 项目级 |
| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-format-markdown/EXTEND.md` | XDG 配置 |
| 3 | `$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md` | 用户主目录 |

若均未找到，使用默认值——本技能无需首次安装设置。

**EXTEND.md 支持的配置项**：

| 配置项 | 可选值 | 默认值 | 说明 |
|--------|--------|--------|------|
| `auto_select` | `true`/`false` | `false` | 跳过标题和摘要选择，自动选取最优 |
| `auto_select_title` | `true`/`false` | `false` | 仅跳过标题选择 |
| `auto_select_summary` | `true`/`false` | `false` | 仅跳过摘要选择 |
| 其他 | — | — | 默认格式化选项、排版偏好 |

## 使用方式

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

## 技能工作流

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

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

| 特征 | 分类 |
|------|------|
| 含 `---` YAML frontmatter | Markdown |
| 含 `#`、`##`、`###` 标题 | Markdown |
| 含 `**加粗**`、`*斜体*`、列表、代码块、引用 | Markdown |
| 以上均无 | 纯文本 |

**若检测到 Markdown，使用用户输入工具询问：**

```
检测到已有 Markdown 格式。请选择操作：

1. 优化格式（推荐）
   - 分析内容，改善标题、加粗、列表以提升可读性
   - 运行排版脚本（间距、强调符号修正）
   - 输出：{filename}-formatted.md

2. 保留原始格式
   - 保持现有 Markdown 结构
   - 仅运行排版脚本
   - 输出：{filename}-formatted.md

3. 仅排版修正
   - 对原始文件就地运行排版脚本
   - 不创建副本，直接修改原文件
```

**根据用户选择：**
- **优化格式**：继续步骤 2（完整工作流）
- **保留原始格式**：跳到步骤 5，复制文件后运行步骤 6
- **仅排版修正**：跳到步骤 6，直接对原文件运行

### 步骤2：分析内容（读者视角）

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

产出以下维度的分析：

**2.1 亮点与核心洞察**
- 作者的核心论点或结论
- 令人惊讶的事实、数据或反直觉的观点
- 令人印象深刻的金句或精彩表述

**2.2 结构评估**
- 内容是否有清晰的逻辑脉络？是什么？
- 是否有缺少标题的自然段落分界？
- 是否有大段文字需要视觉分隔？

**2.3 读者重要信息**
- 可执行的建议或要点
- 关键概念的定义和解释
- 散落在正文中的列表或枚举
- 用表格展示会更清晰的对比或对照

**2.4 格式问题**
- 缺失或不一致的标题层级
- 混合多个主题的段落
- 用散文而非列表呈现的并列项
- 未标记为代码的命令、文件路径或技术术语
- 明显的错别字或格式错误

**将分析保存到文件**：`{original-filename}-analysis.md`

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

```markdown
# 内容分析：{filename}

## 亮点与核心洞察
- [列出发现]

## 结构评估
- 当前脉络：[描述]
- 建议分节：[列出标题候选及简要理由]

## 读者重要信息
- [列出可执行项、关键概念、隐藏列表、潜在表格]

## 格式问题
- [列出具体问题及位置引用]

## 发现的错别字
- [列出明显错别字及修正，或"未发现"]
```

### 步骤3：检查/创建 Frontmatter、标题与摘要

检查是否有 YAML frontmatter（`---` 代码块）。若缺失则创建。

| 字段 | 处理方式 |
|------|----------|
| `title` | 见下方**标题生成** |
| `slug` | 从文件路径推断或从标题生成 |
| `summary` | 一句话简洁摘要（见**摘要生成**） |
| `description` | 较长的描述性摘要（见**摘要生成**） |
| `coverImage` | 检查同目录下是否存在 `imgs/cover.png`；若有则使用相对路径 |

#### 标题生成

无论标题是否已存在，除非设置了 `auto_select_title`，否则都运行标题优化流程。

**准备**——通读全文并提取：
- 核心论点（一句话：「这篇文章讲什么？」）
- 最有冲击力的观点或结论
- 读者痛点或好奇心触发点
- 最令人印象深刻的比喻或金句

**生成候选标题**，使用 `references/title-formulas.md` 中的公式：

1. 根据文章内容、语气和结构选择 **2-3 个最匹配的钩子公式**
2. 生成 **1-2 个直述式标题**（描述性或陈述性，不用公式——清晰准确）
3. 若用户指定了方向（如「制造悬念」），优先该方向
4. 总计：**4-5 个候选**

通过用户输入工具展示：

```
选择一个标题：

1. [钩子标题 A] —（推荐）[公式名]
2. [钩子标题 B] — [公式名]
3. [钩子标题 C] — [公式名]
4. [直述标题 D] — 直述式
5. [直述标题 E] — 直述式

输入编号，或输入自定义标题：
```

将最强钩子放在首位并标记 `(推荐)`。参见 `references/title-formulas.md` 了解原则和禁用模式。

若首行为 H1，将其提取到 frontmatter 并从正文移除。若 frontmatter 已有 `title`，将其作为上下文参考，但仍生成新候选——现有标题可能不够好。

**跳过行为**：若 `auto_select: true` 或 `auto_select_title: true`，跳过用户提示，直接使用最优候选。

#### 摘要生成

直接生成两个版本（无需用户选择），均存入 frontmatter：

| 字段 | 长度 | 用途 |
|------|------|------|
| `summary` | 1 句话，约 50-80 字 | 简洁钩子——用于信息流、社交分享、SEO 元描述 |
| `description` | 2-3 句话，约 100-200 字 | 更丰富的上下文——用于文章预览、通讯摘要 |

**原则**：

- 传达对读者的**核心价值**，而非仅描述主题
- 使用具体细节（数字、成果、具体方法）而非模糊描述
- `summary` 应简洁独立；`description` 可展开补充细节
- 若 frontmatter 已有 `summary` 或 `description`，保留已有的，仅生成缺失字段

**禁用模式**：

- 「本文介绍……」「本文探讨……」
- 纯主题描述而无价值主张
- 用不同措辞重复标题

标题进入 frontmatter 后，正文不应再包含 H1（避免重复）。

### 步骤4：格式化内容

以步骤 2 的分析为指导进行格式化。目标是让内容可快速扫读，关键要点不会被遗漏。

**格式化工具箱：**

| 元素 | 使用时机 | 格式 |
|------|----------|------|
| 标题 | 自然主题分界、章节分隔 | `##`、`###` 层级 |
| 加粗 | 关键结论、重要术语、核心要点 | `**加粗**` |
| 无序列表 | 并列项、特性列表、示例 | `- 项目` |
| 有序列表 | 顺序步骤、排名项、流程 | `1. 项目` |
| 表格 | 对比、结构化数据、选项矩阵 | Markdown 表格 |
| 代码 | 命令、文件路径、技术术语、变量名 | `` `行内` `` 或围栏代码块 |
| 引用 | 金句、重要警告、引用文本 | `> 引用` |
| 分隔线 | 重大主题转换 | `---` |

**格式化原则——不应做的事：**
- 不要添加句子、解释或评论
- 不要删除或缩短任何内容
- 不要改写或重写作者的文字
- 不要添加带有编辑色彩的标题（如「惊人发现」——用中性描述性标题）
- 不要过度格式化：不是每句话都需要加粗，不是每段都需要标题

**格式化原则——应该做的事：**
- 保留作者的语气、风格和每一个词
- **加粗关键结论和核心要点**——读者会高亮的那些句子
- 仅在结构明显存在时，将散文中的并列项提取为列表
- 在主题真正转换时添加标题——偏好生动具体的标题而非泛泛的（如「3 天搞定 vs 传统方案」优于「方案对比」）
- 对散落在正文中的对比或结构化数据使用表格
- 对金句、精彩表述或重要警告使用引用
- 修正明显错别字（基于步骤 2 的发现）

### 步骤5：保存格式化文件

保存为 `{original-filename}-formatted.md`

**备份已有文件：**

```bash
if [ -f "{filename}-formatted.md" ]; then
  mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"
fi
```

### 步骤6：执行排版脚本

对输出文件运行排版脚本：

```bash
${BUN_X} {baseDir}/scripts/main.ts {output-file-path} [选项]
```

**脚本选项：**

| 选项 | 缩写 | 说明 | 默认值 |
|------|------|------|--------|
| `--quotes` | `-q` | 将 ASCII 引号替换为全角引号 `"..."` | false |
| `--no-quotes` | | 不替换引号 | |
| `--spacing` | `-s` | 通过 autocorrect 添加中英文间距 | true |
| `--no-spacing` | | 不添加中英文间距 | |
| `--emphasis` | `-e` | 修正 CJK 强调标点问题 | true |
| `--no-emphasis` | | 不修正 CJK 强调问题 | |

**示例：**

```bash
# 默认：启用间距 + 强调修正，禁用引号替换
${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. 修正 CJK 强调/加粗标点问题（默认：启用）
2. 通过 autocorrect 添加中英文混排间距（默认：启用）
3. 将 ASCII 引号替换为全角引号（默认：禁用）
4. 格式化 frontmatter YAML（始终启用）

### 步骤7：完成报告

显示汇总所有变更的报告：

```
**格式化完成**

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

**内容分析摘要：**
- 发现亮点：X 个核心洞察
- 金句：X 个精彩表述
- 修正格式问题：X 项

**应用的变更：**
- Frontmatter：[新增/更新]（title、slug、summary）
- 新增标题：X 个（##: N 个，###: N 个）
- 新增加粗：X 处
- 新建列表：X 个（从散文转为列表）
- 新建表格：X 个
- 新增代码标记：X 处
- 新增引用：X 处
- 修正错别字：X 处 [逐一列出："原文" → "修正"]

**排版脚本：**
- 中英文间距：[已应用/已跳过]
- 强调修正：[已应用/已跳过]
- 引号替换：[已应用/已跳过]
```

根据实际变更调整报告——省略未发生变更的类别。

## 注意事项

- 保留原始写作风格和语气
- 为代码块指定正确的语言（如 `python`、`javascript`）
- 维护中英文混排间距标准
- 分析文件是工作文档——有助于保持分析发现与格式化结果的一致性

## 扩展支持

通过 EXTEND.md 自定义配置。参见**偏好配置**章节了解路径和支持的选项。

使用说明

# Markdown 格式化

将纯文本或 Markdown 文件格式化为结构清晰、易于阅读的文档，自动添加 frontmatter、标题、摘要、层级标题、加粗、列表等排版元素。

## 使用

在对话中发送需要格式化的文件路径：

```text
帮我格式化这篇文章 article.md
```

或直接粘贴文本内容请求排版优化。

## 工作原理

1. 自动检测内容类型（纯文本 / Markdown）
2. 从读者视角分析内容亮点、结构和格式问题
3. 生成候选标题供选择，自动撰写摘要
4. 应用格式化：标题层级、加粗要点、列表提取、表格转换
5. 运行排版脚本修正中英文间距和标点
6. 输出格式化文件并生成变更报告

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。