1实现原理 · 为什么它能做到

职责二分：内容层面的分析/重构由模型按 SKILL.md 的步骤做（Step 1-5），排版层面的确定性修复交给自带脚本（Step 6）。

skills/baoyu-format-markdown/SKILL.md

Claude performs content analysis and formatting (Steps 1-5), then runs the script for typography fixes (Step 6).

这里在做什么：把『不可验证的编辑判断』与『可脚本化的排版修复』分开，脚本不参与内容改写，因此模型越权的空间被步骤划分限制。

核心纪律是『只调格式、不碰内容』：不改写、不增删、不加评论性内容。

skills/baoyu-format-markdown/SKILL.md

**Core principle**: Only adjust formatting and fix obvious typos. Never add, delete, or rewrite content.

Step 4 把它展开为禁止清单（Do NOT add sentences/explanations、Do NOT rephrase…）与允许清单（保留作者语气、用加粗标出结论、把并列项提炼为列表/表格）。

脚本主体是 unified/remark 管线：解析 → 可选 CJK 友好强调修复 → GFM/frontmatter → stringify，然后原地写回文件。

skills/baoyu-format-markdown/scripts/main.ts

.use(options.emphasis ? remarkCjkFriendly : [])

frontmatter 由 YAML.parseDocument 重排（`doc.toString({ lineWidth: 0 })`），文本节点里若有引号需求则替换为全角引号；最终 `writeFileSync(filePath, formattedContent, "utf-8")` 覆盖原文件。

CJK/英文间距不是自己实现，而是运行时调用 npx autocorrect-node --fix 就地改文件。

skills/baoyu-format-markdown/scripts/autocorrect.ts

const result = spawnSync(npxCmd, ["autocorrect-node", "--fix", filePath], {

spacing 默认 true，因此默认路径会从 npm registry 拉取 autocorrect-node；可用 --no-spacing 关闭。

可选的引号规范化：把成对 ASCII 双引号与「」替换为全角弯引号。

skills/baoyu-format-markdown/scripts/quotes.ts

.replace(/"([^"]+)"/g, "\u201c$1\u201d")

默认关闭（DEFAULT_OPTIONS.quotes=false），仅当传 --quotes 时对文本节点生效。

标题生成走可复用公式库：references/title-formulas.md 提供 8 个 hook 公式 + 直白型，输出 4-5 个候选交给用户选。

skills/baoyu-format-markdown/references/title-formulas.md

8 hook formulas + straightforward style for balanced title generation.

SKILL.md 要求：先抽核心论点/最强观点/读者痛点，选中 2-3 个最匹配公式生成 hook 标题、再补 1-2 个直白标题（`using formulas from `references/title-formulas.md``），最强 hook 放第一并标 (recommended)。

frontmatter 字段有固定加工规则：title/slug/summary/description/coverImage，summary 与 description 双版本且长度有指标。

skills/baoyu-format-markdown/SKILL.md

| `summary` | 1 sentence, ~50-80 chars | Concise hook — for feeds, social sharing, SEO meta |

同日禁止模式（禁用『This article introduces…』式开头）；已存在 title 仍会重新生成候选，但已存在的 summary/description 会保留、只补缺失项。

写盘纪律：输出 {filename}-formatted.md，覆盖前先按时间戳备份；分析文档 {original-filename}-analysis.md 作为改稿依据保留。

skills/baoyu-format-markdown/SKILL.md

mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"

Markdown 检测到格式时先问用户三选一（优化格式 / 保留原格式 / 仅排版修复），第三项会直接原地改原文件——这是本 skill 唯一直接修改用户源文件的分支。

2核心能力

01Markdown/纯文本分类与三条处理路径（优化/保留原格式/仅排版）

02读者视角内容分析：亮点/金句、结构、行动信息、排版问题四维，落盘为 -analysis.md

03frontmatter 生成与规范化（title/slug/summary/description/coverImage）

04公式驱动的多候选标题生成 + 用户选择（auto_select 可跳过）

05排版修复脚本：CJK/英文间距（autocorrect）、CJK 强调标点、全角引号、frontmatter YAML 重排

06偏好文件 EXTEND.md（项目/XDG/home 三级）控制 auto_select 等行为

3外部依赖

Kind	Dependency / Endpoint
cli	npx autocorrect-node --fix（CJK/英文间距修复）
package	remark-cjk-friendly
package	remark-parse / remark-stringify / remark-gfm / remark-frontmatter / unified / unist-util-visit / yaml
cli	bun（首选运行时；无 bun 时 npx -y bun）

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: bun {baseDir}/scripts/main.ts <file.md> [--quotes/--no-spacing/--no-emphasi
网络端点: 声明外部网络访问: registry.npmjs.org：npx 拉取 autocorrect-node（未在本仓锁定版本）；首跑后由 npm 缓存
本地工作目录: 文件读写与工件输出: 原地写回被处理的 .md（main.ts 的 writeFileSync，quotes/emphasis 阶段；『仅排版修复』路径直接改用户原文件）

审计说明： 。三段自证：① 判级对象是本 skill 目录（SKILL.md + scripts/{main,quotes,autocorrect}.ts + references/title-formulas.md）；② 目录内自身行为＝本地读写（原地改用户 md、写 -formatted.md/-analysis.md/备份），加一次固定公开端点外发：`skills/baoyu-format-markdown/scripts/autocorrect.ts` 的 `spawnSync(npxCmd, ["autocorrect-node", "--fix", filePath] …)` 会在默认 spacing 开启时从 registry.npmjs.org 拉取并执行该第三方 CLI；③ 无凭证/密钥读取、无用户内容出网、无逆向/冒充/绕过/安全降级，故为黄而非橙红。留意点：默认路径会原地修改用户源文件（第三条路径）与跑未锁定版本的 npx 包，已写入 verdict.risks。

5第二遍独立确认

[ok] 『模型做内容、脚本做排版』的两段式划分 — SKILL.md Workflow 段逐字：'Claude performs content analysis and formatting (Steps 1-5), then runs the script for typography fixes (Step 6).' 与脚本能力一致（脚本无内容改写逻辑）。
[ok] 脚本的确定性修复项与默认值 — main.ts DEFAULT_OPTIONS={quotes:false, spacing:true, emphasis:true}；--quotes/--no-spacing/--no-emphasis 均有对应分支；与 SKILL.md 选项表一致。
[ok] npx autocorrect-node 为唯一外部命令调用 — 全目录 grep spawn/exec/npx 仅 autocorrect.ts 命中一处；main.ts 只有 readFileSync/writeFileSync。
[ok] 外部依赖清单完整性 — package.json 声明 8 个包（remark 生态 + unified + yaml），另加运行时 npx 的 autocorrect-node；全目录无任何 http 端点/API 调用。
[ok] 无凭证读取 — 目录内 token 扫描 API_KEY/TOKEN/SECRET/.env/keychain 零命中；仅读取 EXTEND.md 偏好（路径在 SKILL.md 明列）。
[ok] 标题公式库内容与『8 个公式』一致 — references/title-formulas.md 首行 '8 hook formulas + straightforward style for balanced title generation.'，表格确为 8 行 hook（Subversive…Empathy）。
[ok] 『仅排版修复』会原地改用户文件 — SKILL.md 第三条路径写明 'Run typography script on original file in-place / No copy created, modifies original file directly'，与 main.ts writeFileSync(filePath…) 行为一致，已列为使用注意。
[ok] 元数据（license/stars/commit） — git HEAD=1567581c26ec29f4216c6e6835415bf30343b0e3；仓库根 LICENSE=MIT（Copyright (c) 2026 Jim Liu）；GitHub API stars=25926、pushed_at=2026-09-10T15:13:43Z。

6结论

流程分层清晰，脚本与模型职责不重叠：脚本只做可验证的排版修复，内容判断留给模型，降低『越权改写』风险。

标题与摘要生成有可复用的方法论（8 hook 公式 + 直白型 + 禁例），而不是让模型即兴发挥。

中小文风痛点（CJK 间距、CJK 强调标点、全角引号）有确定性修复，不依赖模型手感。

写盘有备份纪律，产物命名固定，便于版本对比与回滚。

适合： 适合把自己写的长文/访谈稿/公众号草稿交给 agent 做一遍『结构可扫读、重点可抓取』的排版重整，并顺手生成 frontmatter（title/slug/summary/description）的场景；也适合作为 markdown-to-html、post-to-wechat 等下游 skill 的前置清洗步骤（默认 spacing/emphasis 修复能避免微信端加粗解析失败）。

不适合： 不适合需要严格版式一致性（应使用固定模板/CI 校验）或不允许任何原文改动的合规文书；不适合把已有 Markdown 原文当唯一副本、且不接受原地改写的场景（第三条路径会直接覆盖）；也不适合期望脚本自身做内容改写/翻译的需求——本 skill 明确只调格式不碰内容。

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload baoyu-format-markdown.tar.gz

sha256: 6367312d8f2334bb…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 1567581c26.