tuzi-format-markdown

Markdown 格式化工具

将纯文本或 Markdown 文件转换为结构清晰的 Markdown，添加规范的 frontmatter、格式和排版。

脚本目录

脚本位于 scripts/ 子目录中。将 ${SKILL_DIR} 替换为此 SKILL.md 所在的目录路径。

脚本	用途
scripts/main.ts	主入口，包含 CLI 选项（使用 remark-cjk-friendly 处理 CJK 强调）
scripts/quotes.ts	将 ASCII 引号替换为全角引号
scripts/autocorrect.ts	通过 autocorrect 添加中日韩文字与英文之间的空格

偏好设置（EXTEND.md）

使用 Bash 按优先级顺序检查 EXTEND.md 是否存在：

# Check project-level first
test -f .tuzi-skills/tuzi-format-markdown/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.tuzi-skills/tuzi-format-markdown/EXTEND.md" && echo "user"

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

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

EXTEND.md 支持：默认格式选项 | 摘要长度偏好

用法

Claude 执行内容分析和格式化（步骤 1-6），然后运行脚本修正排版（步骤 7）。

工作流

步骤 1：读取源文件

读取用户指定的 Markdown 或纯文本文件。

步骤 1.5：检测内容类型并确认

内容类型检测：

指标	分类
包含 --- YAML frontmatter	Markdown
包含 #、##、### 标题	Markdown
包含 **粗体**、*斜体*	Markdown
包含 - 或 1. 列表	Markdown
包含 ``` 代码块	Markdown
包含 > 引用块	Markdown
以上均不包含	纯文本

决策流程：

┌─────────────────┬────────────────────────────────────────────────┐ │ 内容类型 │ 操作 │ ├─────────────────┼────────────────────────────────────────────────┤ │ 纯文本 │ 继续步骤 2（转换为 Markdown） │ ├─────────────────┼────────────────────────────────────────────────┤ │ Markdown │ 使用 AskUserQuestion 确认是否优化 │ └─────────────────┴────────────────────────────────────────────────┘

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

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

1. Optimize formatting (Recommended)
   - Add/improve frontmatter, headings, bold, lists
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

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

根据用户选择：

• 优化：继续执行步骤 2-8（完整工作流）
• 保留原文：跳过步骤 2-5，复制文件 → 步骤 6-8（对副本运行脚本）
• 仅调整排版：跳过步骤 2-6，直接对原文件执行步骤 7

步骤 2：分析内容结构

识别：

• 现有标题（H1 #）
• 段落分隔
• 适合加粗的关键词
• 可转换为列表的并列内容
• 代码片段
• 引文

第 3 步：检查／创建 Frontmatter

检查是否存在 YAML frontmatter（--- 块）。如果缺失，则创建。

Meta 字段处理：

字段	处理方式
title	参见第 4 步
slug	根据文件路径推断（例如，posts/2026/01/10/vibe-coding/ → vibe-coding），或根据标题生成
summary	生成吸引人的摘要（100-150 个字符）
coverImage	检查同一目录中是否存在 imgs/cover.png；如果存在，则使用相对路径（也接受：featureImage）

第 4 步：标题处理

逻辑：

1. 如果 frontmatter 已有 title → 使用该标题，正文中不放 H1
2. 如果第一行是 H1 → 提取到 frontmatter 的 title 中，并从正文中移除 H1
3. 如果两者都不存在 → 生成候选标题

标题生成流程：

1. 根据内容生成 3 个候选标题
2. 使用 AskUserQuestion 工具：

Select a title:

1. [Title A] (Recommended)
2. [Title B]
3. [Title C]

3. 如果几秒内没有选择，则使用推荐项（选项 1）

标题原则：

• 简洁，不超过 20 个字符
• 准确传达核心信息
• 吸引人，激发阅读兴趣
• 内容准确，避免标题党

重要： 标题放入 frontmatter 后，正文中不应再有 H1（避免重复）

第 5 步：格式处理

格式规则：

元素	格式
标题	使用 #、##、### 层级
要点	使用 **粗体**
并列项	转换为 - 无序列表或 1. 有序列表
代码／命令	使用 `行内代码` 或 ```代码块```
引语／格言	使用 > 引用块
分隔线	适当使用 ---

格式原则：

• 保留原始内容和观点
• 仅添加格式，不修改文本
• 格式应提升可读性
• 避免过度格式化

第 6 步：保存格式化后的文件

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

示例：

• final.md → final-formatted.md
• draft-v1.md → draft-v1-formatted.md

如果用户选择了“保留原始格式”（第 1.5 步）：

• 将原始文件复制到 {filename}-formatted.md，不做任何修改
• 继续执行第 7 步，仅修正排版

备份现有文件：

如果 {filename}-formatted.md 已存在，覆盖前先备份：

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

示例：

• final-formatted.md 已存在 → 备份为 final-formatted.backup-20260128-143052.md

第 7 步：运行文本格式化脚本

保存后，必须运行格式化脚本：

npx -y bun ${SKILL_DIR}/scripts/main.ts {output-file-path} [options]

脚本选项：

选项	简写	描述	默认值
--quotes	-q	将 ASCII 引号替换为全角引号 "..."	false
--no-quotes		不替换引号
--spacing	-s	使用 autocorrect 添加中日韩文字与英文之间的空格	true
--no-spacing		不添加中日韩文字与英文之间的空格
--emphasis	-e	修正中日韩文字的强调标点问题	true
--no-emphasis		不修正中日韩文字的强调标点问题
--help	-h	显示帮助信息

示例：

# Default: spacing + emphasis enabled, quotes disabled
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md

# Enable all features including quote replacement
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --quotes

# Only fix emphasis issues, skip spacing
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing

# Disable all processing except frontmatter formatting
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing --no-emphasis

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

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

第 8 步：显示结果

**Formatting complete**

File: posts/2026/01/09/example/final-formatted.md

Changes:
- Added title: [title content]
- Added X bold markers
- Added X lists
- Added X code blocks

格式示例

之前：

This is plain text. First point is efficiency improvement. Second point is cost reduction. Third point is experience optimization. Use npm install to install dependencies.

之后：

---
title: Three Core Advantages
slug: three-core-advantages
summary: Discover the three key benefits that drive success in modern projects.
---

This is plain text.

**Main advantages:**
- Efficiency improvement
- Cost reduction
- Experience optimization

Use `npm install` to install dependencies.

注意事项

• 保留原有的写作风格和语气
• 为代码块指定正确的语言（例如，python、javascript）
• 遵循中日韩文字与英文之间的空格规范
• 不要添加原文中没有的内容

扩展支持

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