baoyu-format-markdown

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 处理中日韩文字强调）
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
存在 **粗体**、*斜体*、列表、代码块、引用块	Markdown
以上均无	纯文本

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

Detected existing markdown formatting. What would you like to do?

1. Optimize formatting (Recommended)
   - Analyze content, improve headings, bold, lists for readability
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run typography script only
   - Output: {filename}-formatted.md

3. Typography fixes only
   - Run typography script on original file in-place
   - No copy created, modifies original file directly

根据用户选择：

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

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

仔细阅读完整内容。从读者的角度思考：哪些信息能帮助他们快速理解并记住要点？

请从以下维度进行分析：

2.1 亮点与关键见解

• 作者提出的核心论点或结论
• 出人意料的事实、数据或反直觉的说法
• 令人印象深刻的引文或措辞精炼的句子（金句）

2.2 结构评估

• 内容的逻辑脉络是否清晰？具体是怎样的？
• 是否存在自然的章节分界，却缺少标题？
• 是否有大段文字墙，可以通过增加视觉间隔来改善？

2.3 对读者重要的信息

• 可执行的建议或要点
• 关键概念的定义和解释
• 隐藏在段落中的列表或枚举内容
• 哪些比较或对照改用表格会更清晰？

2.4 格式问题

• 标题层级是否缺失或不一致？
• 是否有段落混杂多个主题？
• 并列内容是否以段落形式呈现，而非列表？
• 代码、命令或技术术语是否未标记为代码？
• 是否存在明显的拼写错误或格式问题？

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

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

# Content Analysis: {filename}

## Highlights & Key Insights
- [list findings]

## Structure Assessment
- Current flow: [describe]
- Suggested sections: [list heading candidates with brief rationale]

## Reader-Important Information
- [list actionable items, key concepts, buried lists, potential tables]

## Formatting Issues
- [list specific issues with location references]

## Typos Found
- [list any obvious typos with corrections, or "None found"]

第 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 呈现：

Pick a title:

1. [Hook title A] — (recommended) [formula name]
2. [Hook title B] — [formula name]
3. [Hook title C] — [formula name]
4. [Straightforward title D] — straightforward
5. [Straightforward title E] — straightforward

Enter number, or type a custom title:

将最有吸引力的标题放在首位，并标记为 (recommended)。标题原则和禁止使用的模式参见 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 步的分析应用格式。目标是让内容易于浏览，并让重点一目了然。

格式工具：

元素	使用场景	格式
标题	自然的话题边界、章节分隔	##、### 层级
粗体	关键结论、重要术语、核心要点	**粗体**
无序列表	并列项目、功能列表、示例	- 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		不修正中日韩强调标点问题

示例：

# Default: spacing + emphasis enabled, quotes disabled
${BUN_X} {baseDir}/scripts/main.ts article.md

# Enable all features including quote replacement
${BUN_X} {baseDir}/scripts/main.ts article.md --quotes

# Only fix emphasis issues, skip spacing
${BUN_X} {baseDir}/scripts/main.ts article.md --no-spacing

脚本执行的操作（根据选项）：

1. 修正中日韩强调/粗体标点问题（默认：启用）
2. 通过 autocorrect 在中日韩文字与英文混排处添加空格（默认：启用）
3. 将 ASCII 引号替换为全角引号（默认：禁用）
4. 格式化 frontmatter YAML（始终启用）

步骤 7：完成报告

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

**Formatting Complete**

**Files:**
- Analysis: {filename}-analysis.md
- Formatted: {filename}-formatted.md

**Content Analysis Summary:**
- Highlights found: X key insights
- Golden quotes: X memorable sentences
- Formatting issues fixed: X items

**Changes Applied:**
- Frontmatter: [added/updated] (title, slug, summary)
- Headings added: X (##: N, ###: N)
- Bold markers added: X
- Lists created: X (from prose → list conversion)
- Tables created: X
- Code markers added: X
- Blockquotes added: X
- Typos fixed: X [list each: "original" → "corrected"]

**Typography Script:**
- CJK spacing: [applied/skipped]
- Emphasis fixes: [applied/skipped]
- Quote replacement: [applied/skipped]

根据实际更改调整报告——没有更改的类别应省略。

注意事项

• 保留原有的写作风格和语气
• 为代码块指定正确的语言（例如，python、javascript）
• 遵循中英文间距规范
• 分析文件是工作文档，有助于确保已识别的内容与格式化后的内容保持一致

扩展支持

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