baoyu-format-markdown实战：不改原意地整理中文技术草稿

把一篇草稿排得更容易读，不等于替作者重写。baoyu-format-markdown 通过 Agent 分析内容，再调整标题层级、强调、列表和代码块，最后用脚本处理中文排版细节。它的基本约束是只改格式与明显错字，不擅自增删正文观点。

本文基于固定提交源码核对；案例为操作示例，非付费服务、账号或实际排版任务实测。没有调用技能处理用户草稿，也没有安装依赖。

一、适用场景与边界

适合纯文本技术笔记、段落冗长但内容已经定稿的博客、混合中英文的教程，以及存在中文强调解析问题的 Markdown。它可以把原有并列关系整理成列表，把自然主题边界变成小标题，把已经出现的命令标为代码，而不是替文章补充没写过的结论。

不适合把“润色、重构论点、扩写案例”都塞进排版任务。想修改语气、删减篇幅或解释新概念，应先做独立编辑，再排版。如果只想修中英文空格，更不应启动完整标题优化和结构分析。

要区分两层能力：Agent 负责理解全文、选择标题和安排结构；scripts/main.ts 负责 Markdown 解析、中文强调、引号和间距等机械修复。单独运行脚本不会自动生成内容分析、重写标题或创建 -formatted.md 副本。

二、按需安装与前置依赖

本系列总教程已核实 skills CLI 1.7.2 的按技能与 Agent 选择参数，可以只安装此技能：

1	npx skills add jimliu/baoyu-skills --skill baoyu-format-markdown --agent codex

需要 Node.js/npx，脚本运行优先 Bun，也允许 npx -y bun。安装命令获取的是当前仓库内容，最新安装不等于固定快照；本文以提交 1567581c26ec29f4216c6e6835415bf30343b0e3 为准。若项目里已有技能，先检查实际版本，避免同时加载重复目录。

源码 package.json 包含 remark-cjk-friendly、unified、YAML 等依赖，完整技能目录必须保留。间距修复的 autocorrect.ts 还会调用 npx autocorrect-node --fix，Windows 使用 npx.cmd。所以“已安装 Bun”不代表所有间距能力都离线可用，网络或包解析失败时应单独报告。

若已明确只处理一份工作副本，可以使用源码核实的命令：

1	npx -y bun "{baseDir}/scripts/main.ts" "article-formatted.md"

{baseDir} 为实际技能目录。这条脚本命令会原地修改传入文件，不是输出到另一个新文件。新副本与备份要由 Agent 的工作流先准备好。

三、输入、输出与三种选择

输入为一个纯文本或 Markdown 文件。检测到已有 YAML、标题、强调、列表等 Markdown 结构后，技能要求用户选择处理方式：

选择	实际行为	适用情况
优化格式	分析正文、调整结构，再运行脚本	内容已定，结构需要整理
保留原格式	创建副本，只运行排版脚本	标题与章节已稳定
只修排版	在原文件上运行脚本	明确允许原地修改

完整流程通常产生 {filename}-analysis.md 与 {filename}-formatted.md。已有排版输出时先备份，备份文件名含时间戳；但“只修排版”会跳过副本创建，因此不能把默认工作流的备份保证套给直接调用脚本的场景。

完整流程会考虑 frontmatter 的 title、slug、summary、description。已有 summary 或 description 会保留，只补缺项。标题则即使已经存在也可能进入优化候选流程，不能误认为“有标题就绝不会动”。如果正文首行是一级标题，可能被提取到 frontmatter，并从正文移除以避免重复。

四、可复制的自然语言 Agent 请求

请使用 baoyu-format-markdown 整理 [文件绝对路径]。
先检测它是否已有 Markdown，并让我确认“优化格式”还是“保留原格式”。
保持原文观点、每段事实、数字、引用和代码不变，只修格式与明显错字。
不要新增案例、删减段落或替作者扩展观点。
完整优化时保留分析文件；输出为 -formatted.md，旧输出先备份。
标题候选先让我选；保留已有 slug、abbrlink、publish、date 与 description，
不要添加封面。最后列出修改类别、错字清单和脚本各阶段真实结果，不发布。

只想保护已发布文章结构时：

1
2
3

这篇文章已有稳定标题和站点元数据，请选择“保留原格式”的副本流程。
仅修复中英文间距与中文强调，不启用引号替换，不调整标题层级。
不要直接改原文件。完成后逐项对比代码、URL、数字和 YAML 字段。

这些是 Agent 请求，不是未经核实的 CLI 参数；保护自定义站点字段属于用户任务约束，需要 Agent 在保存前复查。

五、操作案例：整理一篇数据库排错笔记

假设你已有一篇三千字笔记：第一部分描述现象，第二部分列出三种原因，第三部分给出验证命令。内容正确，但第二部分全挤在一个长段落里，中英文紧贴，命令也没有代码围栏。下面展示工作流程，不声称已经处理了某份实际笔记。

读全文后选择模式。 由于原文已有一级标题和少量列表，先确认使用“优化格式”，而不是默认覆盖。
形成分析。 分析文件说明核心结论、自然分节、适合强调的句子、可转列表的并列项，以及确有依据的错字。分析不是新增观点的草稿，更不能当作最终正文。
确认标题。 完整流程通常提供四到五个候选，包含直接说明主题的标题。技术排错笔记宜选准确描述问题的版本，不为点击率把推测写成“终极解决”。
做结构排版。 将原文的三种原因拆成列表，把命令加正确语言的围栏，关键结论适度加粗。作者未说“必然有效”的地方，不能借小标题强化为确定结论。
保存副本再跑脚本。 输出副本存在则先备份。默认启用间距与中文强调修复，关闭 ASCII 引号替换；需要时再显式决定是否替换引号。
对比和预览。 核对原文命令参数、错误码、文件路径和数字，检查 YAML。然后分别在 Obsidian 与 Hexo 实际渲染器中预览；Markdown 解析器不同，不能只看某一个平台加粗正常就宣称双端完全兼容。

六、配置与脚本细节

EXTEND.md 按项目、XDG、用户目录优先顺序查找。与翻译和网页采集不同，这个技能找不到配置时可以使用默认值，不需要强制首次设置。

1
2
3

auto_select: false
auto_select_title: false
auto_select_summary: false

auto_select 或 auto_select_title 可影响标题选择是否询问。但固定版本文档存在一处应注意的差异：配置表还列着摘要选择开关，而具体流程明确要求直接生成摘要、不让用户选择。所以不要设计一个依赖“摘要候选弹窗必然出现”的流程；最终以具体输出规则和本次请求为准。

脚本默认 quotes: false、spacing: true、emphasis: true。已核实 --quotes、--no-spacing、--no-emphasis 等选项，但没有一个“保持所有字节不变”的模式。即使关闭这些修复，脚本仍会解析并重新序列化 Markdown，YAML 也会格式化，因此行间空白、标记样式可能变化。

间距修复结果需单独关注：源码将 applyAutocorrect 的布尔返回值记入结果，外部命令失败时不一定导致整个格式函数失败。看到“Formatted”日志还要检查间距阶段有没有真正完成。