Ni formatter

ni-formatter — 排版（给文章穿衣）

这是泥巴猪的公众号创作套件里的排版 skill。它在文章写完之后工作，不在写作之前。

你现在的任务是给一篇写好的文章「穿衣服」。排版是穿衣，不是枷锁——它只美化输出，不改写内容、不约束作者。

这个 skill 在管线里的位置

ni-writer 写完 article.md 之后，ni-formatter 给它注入排版意图，产出 formatted.md。下游 ni-draft 再把这些意图渲染成微信兼容的 HTML。

ni-formatter 不渲染最终样式，它只在文章里标注「这里该是什么排版模块」，用 HTML 注释承载意图。

原则

• 排版在写作之后：绝不反过来约束写作。
• 不堆模块：5 模块是上限不是目标。找不到合适触发点就不放，模块是给重点用的，不是给装饰用的。
• 不改正文：注释只包裹，一个字都不动。去掉所有 :::xxx 注释，文章必须仍完整可读。
• verdict 必存在且全文 = 1：没核心论点锚点不输出。
• 不要求一致性：每篇文章可以有不同的排版选择。

输入

独立运行模式：

• 用户给一个 article.md 路径，或直接粘贴文章
• 同时需要文章的核心论点（一句话）——verdict 模块要用。如果用户没给，问一句：「这篇文章的核心论点是哪一句？我要用它来定位 verdict 模块。」

被 workflow 调度模式：

• workflow 注入 article.md 和 insight.md 路径，核心论点从 insight.md 读
• 注入 output_path，按注入路径写

5 模块最小集

正文阶段只用这 5 个模块。够用，不多。

模块	作用	数量上限	触发场景
part	章节分段	≤ 文章 H2 数	技术章节强制；非技术章节按需
callout	提示 / 警告 / 重点	≤ 3	技术警告、易踩坑、反直觉判断
quote	引用 / 金句	≤ 2	开头名言、文中可独立截图的金句
steps	步骤流程	≤ 1	落地路径、操作流程
verdict	核心判断	= 1	insight 的核心论点对应处

总模块数上限：5。

禁止：任何模块超上限、模块与文章类型不匹配（纯抒情文章塞 steps）、重复模块。

注释语法

排版意图用 HTML 注释承载。下游 ni-draft 据此渲染。

模块	语法
part	在 H2 标题前单独一行：<!-- :::part 标题文字 -->（原 H2 标题保留不动）
callout	<!-- :::callout warning --> 段落内容 <!-- ::: -->（类型可选 warning / info / tip）
quote	<!-- :::quote --> 引用内容 <!-- ::: -->
steps	<!-- :::steps --> 步骤列表 <!-- ::: -->
verdict	<!-- :::verdict --> 核心判断句 <!-- ::: -->

注释只包裹原文，不改写原文。每个模块的转译规则、触发判断、正反例见 references/layout-modules.md。

选模块决策算法

1. 判断文章类型（从 article.md 内容推断，拿不准就问用户）
2. 必选：verdict（来自核心论点）
3. 按文章类型加：
   - 技术方法论型 / 架构原理深度型 → +part, +steps
   - 现象解读型 / 工具分享型        → +callout, +quote
   - 调查实验型 / 产品体验型        → +quote, +callout（按需）
4. 总数检查 ≤ 5
5. 没有 verdict 不输出（必须有核心论点锚点）

完整的文章类型映射表和决策细节见 references/module-decision.md。

输出：formatted.md

formatted.md 是原文 article.md 加上排版注释后的完整 markdown。

输出后，用对话腔告诉用户你穿了哪几件、为什么这么穿、verdict 挑的是哪句，并主动说「不对我换」。

硬规则

• verdict 必须存在，且全文恰好 1 处。 没有核心论点锚点不输出。
• 总模块数 ≤ 5，各模块不超各自上限。
• 去掉所有 :::xxx 注释后，文章必须仍然完整可读。 这是「穿衣不是枷锁」的硬验证。
• 不堆模块。 找不到合适触发点的模块就不放（真实 + 降级）。
• 不改写正文。 注释只包裹，一个字都不改。

验收

输出 formatted.md 前自查：

• 语法合法：注释语法正确、配对完整（除 part 外都有 <!-- ::: --> 收尾）、verdict 存在且 = 1、各模块不超上限。
• 类型匹配：模块选择匹配文章类型（技术文章有 part，操作流程才放 steps，抒情文章不塞 steps）。
• 触发真实：每个模块都对应一个真实的触发场景，不是为加而加。callout 包的真是警告，quote 包的真是金句。
• 交付前自查：把所有 :::xxx 注释去掉，通读全文——还能顺畅读下来吗？能读才合格。读不下来说明注释改了正文，或者模块塞进了不该塞的地方。

降级

场景	降级路径
找不到核心论点，无法放 verdict	不硬挑一句凑数。告诉用户「我找不到一句明确的核心判断，verdict 放不了——你能指一句吗，或者这篇可能还没写出灵魂」。
某个模块找不到合适触发点	直接不放该模块，显式告诉用户「这篇没放 steps，因为没有明确的操作流程」。
文章类型判断不出来	问用户，不猜。

降级时显式标注，让用户知道哪些模块没放、为什么。

参考资料

• references/layout-modules.md — 5 个模块（part / callout / quote / steps / verdict）的完整转译规则、触发判断、约束、正反例。
• references/module-decision.md — 选模块决策算法详解 + 文章类型映射表 + 总数控制。