baoyu-format-markdown

Markdown 格式化工具

将纯文本或 Markdown 转换为结构清晰、易于阅读的 Markdown。目标是帮助读者快速掌握要点、亮点和结构——不改变任何原始内容。

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

用户输入工具

当此技能提示用户时，遵循以下工具选择规则（按优先级）：

1. 优先使用当前代理运行时提供的内置用户输入工具——例如 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 处理中日韩强调）
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	仅跳过摘要选择
其他	—	—	默认格式化选项、排版偏好

使用方法

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

工作流程

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

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

指示符	分类
包含 --- YAML frontmatter	Markdown
包含 #、##、### 标题	Markdown
包含 **bold**、*italic*、列表、代码块、块引用	Markdown
以上均无	纯文本

如果检测到 Markdown，使用 AskUserQuestion 询问：

检测到现有 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 的蓝图。使用以下格式：

# 内容分析：{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 个候选标题

通过 AskUserQuestion 呈现：

选择一个标题：

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

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

将最强的钩子放在第一位并标记为 (recommended)。参见 references/title-formulas.md 了解原则和禁止模式。

如果第一行是 H1，则将其提取到 frontmatter 并从正文中移除。如果 frontmatter 已有 title，将其作为上下文包含，但仍需生成新的候选标题——现有标题可能较弱。

跳过行为：如果 auto_select: true 或 auto_select_title: true，则跳过用户提示，直接使用最佳候选。

摘要生成

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

字段	长度	用途
summary	一句话，约 50-80 字符	简洁钩子——用于信息流、社交分享、SEO 元数据
description	2-3 句话，约 100-200 字符	更丰富的上下文——用于文章预览、新闻简报摘要

原则：

• 传达对读者的核心价值，而不仅仅是主题
• 使用具体细节（数字、结果、具体方法）而非模糊描述
• summary 应简洁有力且自包含；description 可扩展补充细节
• 如果 frontmatter 已有 summary 或 description，保留现有字段，仅生成缺失的字段

禁止模式：

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

一旦标题放入 frontmatter，正文中不应包含 H1（避免重复）。

步骤 4：格式化内容

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

格式化工具集：

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

格式化原则——禁止事项：

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

格式化原则——应做事项：

• 保留作者的风格、语气和每一个字
• 加粗关键结论和核心要点——读者会高亮的句子
• 仅当结构明确时，将段落中的平行项提取为列表
• 在主题确实转换时添加标题——优先使用生动具体的标题而非通用标题（例如“3 天搞定 vs 传统方案”优于“方案对比”）
• 对散落在段落中的比较或结构化数据使用表格
• 对金句、令人难忘的陈述或重要警告使用块引用
• 修复明显错别字（基于步骤 2 的发现）

步骤 5：保存格式化文件

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

备份现有文件：

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

步骤 6：执行排版脚本

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

${BUN_X} {baseDir}/scripts/main.ts {output-file-path} [options]

脚本选项：

选项	短选项	描述	默认值
--quotes	-q	将 ASCII 引号替换为全角引号 "..."	false
--no-quotes		不替换引号
--spacing	-s	通过 autocorrect 添加中日韩/英文间距	true
--no-spacing		不添加中日韩/英文间距
--emphasis	-e	修复中日韩强调标点问题	true
--no-emphasis		不修复中日韩强调问题

示例：

# 默认：间距 + 强调启用，引号禁用
${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. 格式化 frontmatter YAML（始终启用）

步骤 7：完成报告

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

**格式化完成**

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

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

**应用的更改：**
- Frontmatter：[添加/更新]（标题、slug、摘要）
- 添加标题：X 个（##: N, ###: N）
- 添加加粗标记：X 个
- 创建列表：X 个（从段落 → 列表转换）
- 创建表格：X 个
- 添加代码标记：X 个
- 添加块引用：X 个
- 修复错别字：X 个 [列出每个：“原始” → “更正”]

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

根据实际更改调整报告——省略未进行更改的类别。

注意事项

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

扩展支持

通过 EXTEND.md 进行自定义配置。参见偏好设置部分了解路径和支持的选项。