Fabric md_callout Pattern 实战：将任意文本智能封装为 GitHub 风格 Callout 分类提示

导读

md_callout 是 Fabric 仓库中一个轻量而实用的内容格式化 Pattern，它的职责非常聚焦：读取你提供的任意文本，先由模型判断该内容最匹配的语义类型（普通说明、操作建议、关键信息、潜在风险还是负面后果），再将其封装为 GitHub Flavored Markdown（GFM）支持的 [!TYPE] 提示块（callout/alert）。本文以 data/patterns/md_callout/system.md 为骨架，结合 Fabric 的 Pattern 加载与变量替换源码，讲解 callout 五类的选用标准、完整的调用方式、输出纪律，并给出可直接复制运行的实战示例，让你在撰写 README、技术文档、博客和 Issue 时快速获得语义清晰、渲染美观的信息提示块。

一、Pattern 定位：Fabric 模式体系中的“格式化输出”工具

在 Fabric 的 data/patterns 目录下，绝大多数 Pattern 属于“分析/总结/创作”类（如 analyze_bill、create_summary、extract_insights），而 md_callout 是与众不同的一个：它不改变内容的语义，只改变内容的呈现结构——将一段散文本整理为标准的 callout 块。可以把它理解为一个“Markdown 语义样式器”：

• 输入：任意一段文本（可能是警告语、注意事项、补充说明、关键提示）。
• 输出：一个且仅一个符合 GFM alert 语法的 callout 块。
• 价值：让文档中的重点信息在 GitHub、GitCode 等支持 GFM 的平台上获得醒目的视觉区分，同时保持纯 Markdown 的跨平台可移植性。

从仓库结构可以推断，md_callout 是唯一以 md_ 前缀命名的 Pattern，其命名直接体现了“面向 Markdown 输出”的定位，与 create_mermaid_visualization、create_markmap_visualization 等“面向可视化输出”的 Pattern 形成互补。

二、完整继承：md_callout 的核心提示内容

原文档 data/patterns/md_callout/system.md 定义了完整的角色、步骤、选项和输出纪律。以下是其核心内容的忠实梳理与逐条解读。

2.1 角色设定（IDENTITY and GOAL）

Pattern 要求模型扮演：

You are an ultra-wise and brilliant classifier and judge of content. You create a markdown callout based on the provided text.

即：一个“内容分类器与裁判”，只负责根据输入文本选择最恰当的 callout 类型并完成封装。同时要求模型 Take a deep breath and think step by step（深呼吸、逐步思考），这是在提示模型先做分类推理再动手输出，避免不经判断直接套用同一种格式。

2.2 分类步骤（STEPS）

整个处理只有一步决策：

1. 判断类型：根据输入文本的内容性质，从下列五种 callout 类型中选择最合适的一种。

2.3 五种 Callout 类型（选择依据原样继承）

原文档给出了五个官方选项，每个都附带了官方语义说明：

> [!NOTE]
> This is a note callout for general information.

> [!TIP]
> Here's a helpful tip for users.

> [!IMPORTANT]
> This information is crucial for success.

> [!WARNING]
> Be cautious! This action has potential risks.

> [!CAUTION]
> This action may have negative consequences.

对应到实际选型，可以归纳为如下判断基准：

类型	语义	适用场景举例
[!NOTE]	一般性补充说明（general information）	背景知识、实现细节、名词解释、附带说明
[!TIP]	对用户有帮助的操作建议（helpful tip）	更优的用法、快捷键、性能建议、最佳实践
[!IMPORTANT]	对成败至关重要的信息（crucial for success）	必备前置条件、关键参数、必须遵守的约定
[!WARNING]	操作存在潜在风险，需要谨慎（potential risks）	数据不可逆、兼容性差异、实验性功能
[!CAUTION]	操作可能带来负面后果（negative consequences）	可能导致数据丢失、安全漏洞、法律风险

2.4 输出格式（OUTPUT / OUTPUT FORMAT）

封装结果必须严格遵循 GFM alert 语法，每个内容行都以 > 前缀开头：

> [!CHOSEN CALLOUT]
> The text I gave you goes here.

2.5 输出纪律（OUTPUT INSTRUCTIONS）

原文档特别强调三条硬性约束：

• ONLY generate the chosen callout：只生成所选的那一个 callout，禁止输出额外的解释、对比或备选项；
• ONLY OUTPUT THE MARKDOWN CALLOUT ABOVE：输出中只允许出现 callout 本身；
• **Do not output the md container. Just the markdown itself.**：不要输出包裹用的 ```` md ```` 代码块围栏，直接输出裸的 Markdown 块。

这三条纪律保证了输出可以被直接嵌入目标文档，无需二次清理。

三、实战调用：如何在 Fabric 中运行 md_callout

3.1 基本调用方式

Fabric 通过 -p / --pattern 参数指定 Pattern，通过 {{input}} 占位符注入你的文本（见 internal/cli/flags.go 中 Pattern 标志的定义）。最直接的用法是通过标准输入传文本：

echo "删除该目录前请确认没有未提交的改动。" | fabric --pattern md_callout

输出：

> [!WARNING]
> 删除该目录前请确认没有未提交的改动。

也可以把整段内容先写入文件再通过管道喂给 Pattern：

cat notice.txt | fabric -p md_callout

3.2 文本注入的底层机制

从源码看，Pattern 文本与用户输入是通过占位符拼接完成的（见 internal/plugins/db/fsdb/patterns.go）：

• ensureInput：若 Pattern 内容中不存在 {{input}} 占位符，会自动在末尾追加 \n{{input}}；
• applyInput：将 {{input}} 全部替换为用户实际输入。

因此即使 md_callout 的 system.md 中没有显式写出 {{input}}，Fabric 也会自动把用户文本追加到 Pattern 之后，模型读到“INPUT:”之后的内容即为待封装的文本。这正是该 Pattern 可以“开箱即用”的原因。

3.3 辅助调试命令

在正式批量使用前，建议用以下命令确认 Pattern 内容与输出效果：

# 查看 md_callout 的完整提示内容
fabric --readpattern md_callout

# 列出当前已安装的所有 Pattern，确认 md_callout 存在
fabric --listpatterns

相关标志定义同样位于 internal/cli/flags.go。

3.4 关于变量替换的说明

如果输入文本中恰好包含 {{ 之类的模板语法，且不希望被 Fabric 的变量替换机制处理，可以使用 --no-variable-replacement 标志禁用变量替换（见 internal/cli/flags.go）。日常的普通文本不受影响，因为 applyVariables 会先以哨兵令牌保护 {{input}}，再处理其余模板变量（见 internal/plugins/db/fsdb/patterns.go）。

四、分类决策示例：同一段话的五种归宿

为了演示“分类器”的决策逻辑，下面用一组对照输入展示 md_callout 应如何选型（示例输出遵循原文档的格式要求）：

输入 1（背景信息）

Fabric 的 Pattern 是一组可复用的提示词模板，存放在 data/patterns 目录下。

> [!NOTE]
> Fabric 的 Pattern 是一组可复用的提示词模板，存放在 data/patterns 目录下。

输入 2（操作建议）

使用 --readpattern 先查看 Pattern 内容，再决定是否调用，可避免浪费 API 额度。

> [!TIP]
> 使用 --readpattern 先查看 Pattern 内容，再决定是否调用，可避免浪费 API 额度。

输入 3（关键前提）

运行前必须完成 fabric --setup 初始化并配置 API Key。

> [!IMPORTANT]
> 运行前必须完成 fabric --setup 初始化并配置 API Key。

输入 4（潜在风险）

升级版本可能覆盖你自定义的 Pattern，请提前备份。

> [!WARNING]
> 升级版本可能覆盖你自定义的 Pattern，请提前备份。

输入 5（负面后果）

若错误配置权限，将导致敏感数据对外可读。

> [!CAUTION]
> 若错误配置权限，将导致敏感数据对外可读。

五、为什么输出纪律如此重要

原文档反复强调“只输出 callout 本身”，这一点在工程上有实际价值：

1. 可直接落盘：无围栏、无前后缀的输出，可以被脚本直接追加进目标 Markdown 文件，无需二次清洗；
2. 保持渲染一致性：GFM alert 语法要求块首为 > [!TYPE]，任何多余字符都可能破坏 GitHub 的渲染识别；
3. 便于幂等处理：如果输出固定为单一 callout 块，批量处理大量段落时可以稳定拼接。

类似的“强输出纪律”在 Fabric 其他 Pattern 中也很常见（例如 analyze_prose_json 要求纯 JSON 输出），这是 Fabric Pattern 设计的一贯风格。

六、结合仓库资源的扩展用法

6.1 与自定义 Pattern 配合

如果你觉得五种类型不够用，或希望把某类文本固定映射到某一种 callout，可以参照 md_callout 的结构编写自己的 Pattern（例如只允许输出 [!TIP] 的变体），存入自定义 Pattern 目录后通过 -p 调用。Fabric 的 internal/tools/patterns_loader.go 会在更新时保留自定义 Pattern 不被覆盖，你可以在 README.md 的 Custom Patterns 章节找到完整的目录约定与示例。

6.2 在仓库文档中直接落地

md_callout 的输出格式正是 GFM alert 语法，与 GitHub、GitCode 的渲染规则一致。你可以在自己的 README、Release Notes 中直接使用：

> [!IMPORTANT]
> 从 v1.4.0 起，Pattern 目录已迁移至 data/patterns，旧路径 patterns 将自动迁移。

6.3 用 YAML 配置固化 Pattern

Fabric 支持通过 YAML 配置文件持久化常用参数（见 internal/cli/README.md），可以把 md_callout 设为默认 Pattern：

# ~/.config/fabric/config.yaml
pattern: md_callout
stream: true

之后直接执行 fabric "某段需要封装的文本" 即可复用该 Pattern；CLI 标志的优先级高于 YAML 配置，仍可随时用 -p 覆盖。

七、适用前提与限制

• md_callout 依赖 LLM 的分类能力，输出类型可能随模型理解略有波动；对分类要求严格的场景，建议在输入中显式指明期望类型；
• 该 Pattern 只负责格式封装，不会对原文进行摘要、改写或翻译，输入文本会被原样放入 callout 内容区；
• 输出的视觉效果依赖渲染平台对 GFM alert 语法的支持（GitHub、GitCode、Typora 等均支持）；纯文本环境退化为普通引用块，不影响内容可读性。

结语

md_callout 用最精简的提示结构（一段角色设定、一个分类步骤、五类选项、三条输出纪律）完成了一个高频且实用的文档工程任务。结合 data/patterns/md_callout/system.md 的完整提示文本与 internal/plugins/db/fsdb/patterns.go 的注入机制，你可以把它直接接入文档生成流水线，让每一处“重要提示”“风险警告”“补充说明”都以标准、醒目、可移植的形式呈现。