doc-beautify

name	doc-beautify
description	当用户要美化已有 Obsidian 笔记的排版与可读性时使用（如「帮我美化这篇笔记」「整理一下这篇的排版」）——笔记语法不规范、结构混乱、代码裸奔、长篇抽象文字堆砌、缺可视化时尤其该用。美化同时审查内容正确性，发现疑似错误（讲错的 API / 有 bug 的代码 / 事实或术语错）先存疑、问你确认再改，不自行改。本 skill 只负责把「已有正文」加工成好读的成品——不创建新笔记、不管笔记归属与目录分类、不做内容拆分迁移。

美化与格式化笔记

把一篇已经写了正文、但凌乱难读的笔记，整理成结构清晰、语法规范、代码 + 插图配合得当的成品。本 skill 是一条加工流水线，按以下顺序执行（工序 2 / 3 / 4 可穿插，但工序 0 必须先做、工序 3 建项目须用户同意）：

• 定范围（前置门）：用户没指定章节 → 整篇；指定了 → 只改那部分。
• 工序 0　读全文：先 Read 整篇做诊断（含内容正确性审查），再动手——不边读边改。
• 工序 1　Markdown 规范化：调 obsidian-markdown，修语法 / 排版 / frontmatter；标题取舍以 TOC 为复习提纲。
• 工序 2　代码与表格化：抽象描述 → 代码 + 注释；并列罗列 → 表格；why / 体会保留文字。
• 工序 3　代码块组织：能建 demo 的（先问用户）在 code/ 建项目用 Snippets 引用；SQL / shell 等内联。
• 工序 4　配图：按判定表决定，Mermaid 优先，不凑数。
• 收尾：通读确认渲染无误；报告本次改了哪些部分、哪些模糊点 / 内容疑点是问过用户后定的。

先诊断，按需改造：工序 0 诊断完后，已合格的部分直接跳过——很多笔记已部分或全部美化过，不要为了"走完流水线"把用户已满意的代码 / 表格 / 图重造一遍，只动真正需要优化的点。

为什么有这条 skill：用户的笔记多是学习时快速记下的文字和图片，常常不符合基本 markdown 语法、结构混乱、长篇抽象文字堆砌、缺少可视化。目标是把它变成「好读、好查、好理解」的成品。

核心约束：只优化现有内容，不擅自增删（最高优先级）

只优化现有内容——不扩写（不加原文没有的知识），也不擅自删段（删 / 合并用户写过的整段或章节要先问）。

这是本 skill 的最高约束，凌驾于其它工序之上：

• ✅ 可以做（内容边界不动）：修改、重组、删重复（同一条信息在两处出现，合并删其一）、抽象文字转代码/表格、加结构、加配图、清理语法——这些都是对现有内容的优化。
• ❌ 禁止做：补充笔记里没有的知识点、加原文没写的背景/原理/对比、扩展未提及的 API/配置/示例、"为了让笔记更完整"而添油加醋；以及擅自删除 / 合并用户写过的整段或章节。

为什么：这是用户的学习笔记，记录的是用户当时学到/记下的东西。自行扩写会污染笔记的真实性——分不清"哪些是我当时学的"和"哪些是 AI 后来加的"；自行删段则会丢掉用户当时记下的东西。用户要"更完整"会自己学自己补，或明确要求补；要删某段也会自己删，或让你删。美化只管把已有内容变得好读，不替用户做增删决策。

两条边界判定：

• 扩写判定：改写后问一句「这段信息，原文里有吗？」——有（哪怕散落、隐含、表达差）就允许优化重组；没有就不许凭空加。
• 删段判定：删之前问一句「这一段是用户写过的知识点吗？」——是，就不能擅自删或合并，要先用 AskUserQuestion 问用户；只有纯重复（同一信息两处）可直接删其一。
• 占位空章节：遇到只有标题、没有正文的章节（用户的 WIP 规划，如 ## 控制语句 下什么都没有），默认保留不动——不填充（不扩写）、不删除（要删必须问）。占位是用户还没写，不是你要补的。

拿不准某段算"优化"还是"扩写 / 删减"时，问用户。

正确性审查：内容写错先「存疑」、问用户，不自行改（与核心约束并列的最高约束）

美化之外，本 skill 同时审查笔记内容的正确性——不只看排版对不对，也看写的东西对不对。学习笔记常有记错处：讲错某个 API 的行为、代码逻辑有 bug、事实 / 概念表述有误、术语用混（如「并发」写成「并行」）、前后自相矛盾。

铁律：发现疑似错误，一律先「存疑」——原样保留、先不动它，停下来用 AskUserQuestion 把疑点交给用户，确认后才改。 这是一类决策点（复用下文「安全重组 vs 决策点」的问法），询问时给足三样信息：

1. 在哪——具体位置（哪一节 / 哪行 / 哪段代码）。
2. 为什么疑——你判断它可能有误的依据。
3. 应是什么——你认为正确的说法，摆出来给用户定夺（不是替他拍板）。

用户确认「确实错了」后，才按确认结果修正；用户说「保持原样 / 是你理解错了」就不动。

为什么不自行改：这是用户的学习笔记，而 AI 的「纠正」本身可能是幻觉——静默改动会（1）可能把对的改成错的，（2）抹掉「这里被质疑过」的信号，（3）替用户做了本该他做的判断。对错由用户定，你只负责把疑点摆到台面上。

和其它规则的边界（三者各管一段，别混）：

• 核心约束管「增删」，正确性审查管「对错」：核心约束禁止扩写 / 擅自删段（管内容多少）；正确性审查处理已有内容写错了（管内容对错）。美化本身从不改语义，唯一改语义的情形就是「修正用户确认过的错误」，且必须走存疑 → 问 → 改。
• 和「机械笔误」区分：输入法乱码、无意义字符、未闭合代码围栏这类一眼就坏、不涉及知识对错判断的坏字，仍属安全重组、直接修；一旦要判断某个知识点写得对不对，就是存疑、走询问。

作用范围：整篇 vs 指定章节（影响效率的关键约定）

先确定本次要改的范围，再动手——避免对已经整理过的部分重复扫描、重复优化。

• 用户未指定章节 / 段落 → 默认对整篇笔记扫描和美化。
• 用户指定了章节（如「只优化「垃圾回收」这一节」「整理一下第三节」）→ 只在指定范围内改造，其余部分保持原样，不要扫描、不要顺手改。

判定原则：

用户说法	作用范围
「美化这篇笔记」「整理一下排版」「格式化它」（无指向）	整篇
「优化 X 章节」「整理第 N 节」「只看 ## XXX 这块」	仅指定章节
「除了 X 部分，其它整理一下」	整篇排除 X

为什么：同一篇笔记可能上次已经美化过前几节。如果不区分范围、每次都整篇重扫，既浪费 token 又可能把用户已经满意的段落改坏。指定了范围就严格守住边界，别越界。

边界处理细节：

• 章节模式不做 TOC 结构优化：TOC 标题编排（标题取舍、层级深浅、新增 / 合并标题）是整篇级别的操作，只在「优化整篇」时触发。指定了章节时，保持该章节既有的标题层级，只在章节内做语法规范化与内容美化，不为了调 TOC 去新增 / 删除 / 合并标题。
• 指定章节时，frontmatter 不在本次改动范围内（除非用户明确要求），因为 frontmatter 是笔记级元数据，不是某一节的内容。
• 指定章节的改造可能涉及代码块组织（工序 3）、配图（工序 4），这些都在章节内进行；Snippets 引用的 code/ 项目创建规则（先问用户）不变。
• 改完告诉用户「本次只改了 X 章节，其余未动」，让用户清楚发生了什么。

工序 0：先读，再动手

开工前必须完整读一遍目标笔记原文（用 Read 读全文，不要只读片段），搞清楚：

• 笔记到底在讲什么、当前结构是什么样
• 哪里语法坏掉了（缺闭合的代码块、错位的标题层级、散乱的图片引用）
• 哪些地方在用大段抽象文字描述本可以用代码或图说明的东西（这些是重点改造对象）
• 哪些图片已存在（引用方式对不对）、哪些地方缺图但适合加图
• 核对资源：核对正文引用的图片是否真实落在 附件/——缺失的图片引用要修或问。
• 顺带审查正确性：读的同时留意内容有没有写错（API 行为、代码逻辑、事实 / 术语、前后矛盾），把疑点先记下来、这一遍先不改——收尾前按「正确性审查」存疑、问用户。

读完再开始改。不要边读边改、看一段改一段——容易把笔记的整体结构改散。

工序 1：Markdown 语法规范化

调用 obsidian-markdown skill（**REQUIRED SUB-SKILL**）获取完整语法参考，然后按下列要点规范化全文。这一步只动语法和排版，不重写内容含义。

必做清单

• frontmatter 完整化：按 模版/普通笔记模版.md 对齐基础字段（描述 / 排序 / 分组 / 创建时间）。保留原有字段值，不要清空用户已填的内容；用户按需扩展的额外字段（如 来源、更新时间）予以保留，不要删。

安全重组 vs 决策点：什么直接做、什么先问用户

美化时每个动作先归一类，全 skill 通用：

• 安全重组——纯排版、语法、结构重组这类动了不会错（不改语义）的，直接做，收尾报告里说明改了什么。
• 决策点——动了可能改错语义的，一律停下用 AskUserQuestion 先问，不替用户决定。code/ 项目只是其中一个触发点。

常见决策点：

决策点	要问什么
占位文件名（如「测试笔记」「新建笔记」「无标题」）	是否改名？改成什么？（改名影响已有 wikilink）
术语策略（满篇中英括注）	保留中英对照还是只留中文？
内容疑似有错（技术 / 事实 / 代码逻辑 / 术语，见「正确性审查」）	存疑：指出位置与依据、给出你认为正确的说法，问是否更正
任何你看不准、改了可能改错含义的地方	直接把疑问抛给用户

标题层级与 TOC：TOC 即复习提纲（重要）

Obsidian 的大纲 / 目录（TOC）由标题自动生成——每一个 ##/###/#### 都会变成目录里的一条。对学习笔记来说，这个目录不是排版装饰，而是日后复习的提纲：复习时不用重读全文，只扫 TOC 就该能回忆起全篇讲了什么、难点在哪——唤不起知识点细节的 TOC 是失败的。所以标题不是"让这里字号大一点"的工具，而是知识模块的边界标记——这条认知决定所有标题取舍。TOC 标题要同时满足三条：进得了 TOC 的才是独立知识点（疑难点 / 易错点 / 对比辨析尤该进，细枝末节不进）、层级别太深、文字要精简。

TOC 结构取舍（标题 vs 粗体降级、疑难点升标题、层级深浅、标题精简、合并碎片标题）只在整篇模式做，判定细则见 reference/toc-headings.md——降级粗体属安全重组（可直接做）、合并/增删标题属决策点（先问用户）；章节模式不做 TOC 结构优化，跳过不读。

其余标题硬规则（机械执行，不用判断）：全文有且只有一个一级标题（与文件名一致）；修掉跳级（如 H1 直接到 H4）、多重 H1、用标题当样式（纯粹为放大字号而套 ###）；标题内禁用行内代码块（反引号）——铁律：所有级别的标题（# 到 ######）一律不用反引号包裹术语。原因：反引号会污染 TOC / 大纲 / 锚点的纯文本显示（目录里出现 `skill名` 极难看），且标题本身已是醒目元素、无需再用代码强调；要强调的术语放正文用反引号，标题保持纯文本。明显的笔误 / 乱码标题（输入法错误、无意义字符，如 算数匀速阿福→算术运算符）可直接修正、收尾报告里说明——这类是坏掉的标题，不是用户有意命名。

其余语法清单

• 列表与代码块闭合：补齐未闭合的代码围栏、修正缩进错乱的嵌套列表、把「用空格/连字符当装饰」的地方改成真正的列表。
• 链接语法：内部引用一律用 wikilink（[[笔记名]]、[[笔记名|显示文本]]）；只有外部网址用 [文本](https://...)。把原文里写成普通文本的笔记引用改成 wikilink。
• 图片引用：图片放在 附件/，正文用 ![[图片名.png]] 引用；可带宽度 ![[图片名.png|500]]。修掉写成 markdown 外链的本地图片、错路径的引用。
• 强调与高亮：重点用 ==高亮==、加粗用 **...**；不要滥用、不要整段高亮。
• callout：把三类内容归并成 > [!note] / > [!warning] / > [!tip] 等 callout，提升扫读效率：
  • 「注意 / 警告 / 提示 / 总结」这类散落的提示性文字；
  • 核心要点、点睛结论、强调性的短列表（如「变量的作用」「XX 的意义」这类想突出的小节）——用 > [!tip] 或 > [!note] 收纳比裸列表更醒目。判断标准：这段内容是「想让读者一眼记住的要点」而非「普通信息罗列」，就适合 callout。
  • 术语定义句——形如「XX 是 …」、给某个概念下定义的陈述句（如「字面量是源代码中值的直接表示…」「变量是程序在运行期间可以改变其值的命名存储单元」）。这类句子是一节内容的「锚点」，用 callout 包裹让读者扫读时快速定位概念。固定格式：callout 标题统一填「定义」二字（不填术语名），正文放整句定义，并对定义中的关键术语用行内代码 `强调` 着重（如「字面量是源代码中值的直接表示…确定其 类型 和 值」）。识别特征：一句话陈述、以术语本身开头、回答「这是什么」而非「怎么用」——回答「怎么用」的走代码/表格，不归入此类。

这一步产出的是一篇「语法干净、结构规整、但还是原内容」的笔记。后面三道工序才动内容的表达方式。

工序 2：用代码与表格替代抽象文字（核心原则）

原则：能用代码或表格说清楚的，就别用大段抽象文字。 代码展示「怎么做」，表格展示「并列项的对比」。

这是本 skill 区别于普通「排版工具」的关键。学习笔记里最常见的毛病是：用三五段文字解释一个 API、一段配置、罗列一堆并列项——读者读完还是不知道实际长什么样。改造方向有三：

方向 A：抽象描述 → 代码 + 注释

❌ 抽象文字描述（避免）	✅ 代码 + 注释（提倡）
「forEach 接收一个 Consumer，会对每个元素执行该函数」	直接给一段 Java 代码，在 forEach 调用处写注释解释
「需要在 application.yml 里配置数据源 url、用户名、密码」	直接给一段 yaml，关键字段上行内注释
「先用 add 添加元素，再用 poll 取出队首」	给一段连贯的可运行代码，注释标出每一步

要点：

• 优先用代码承载解释：看到抽象描述，先想「这段话能不能换成一段带注释的代码」。能换就换。
• 注释解释「为什么」，代码展示「怎么做」：注释不要复述代码字面意思（// 设置 name 这种废话），要解释意图、原理、坑点。
• 不无脑消灭文字：概念性、对比性、why 类的内容（如「为什么要用 A 而不是 B」）仍需要文字。代码化针对的是「描述操作 / API / 配置」这类内容。
• 保留用户的理解：用户写的总结性、体会性文字是笔记的价值所在，不要因为「能写成代码」就删掉。删的是冗余抽象描述，不是用户的思考。
• ⚠️ 代码化是「替代」，不是「叠加」：一条信息既然已经用代码 + 注释表达清楚，就不要在代码块外部再用文字重复一遍。否则同一条规则出现在两处，既冗余又增加维护成本（改代码时忘了同步文字、或反之）。代码化时自检：「这段外部说明删掉，只靠代码注释还能读懂吗？」——能，就删掉外部说明；只有外部补充了代码无法承载的 why / 背景，才保留文字。

方向 B：并列项罗列 → 表格

当笔记在罗列多个并列的事物（多个 API 对比、多平台安装方式、多个配置项及其作用、多个命令及用途），优先用表格汇总，而不是一长串段落或散落的列表项。表格让读者一眼定位、便于对照。

❌ 散落段落 / 裸列表（避免）	✅ 表格（提倡）
十个平台的安装命令分散在十段文字里	一张「平台 / 安装命令 / 备注」表格
「forEach 用来遍历，map 用来映射，filter 用来过滤…」	「方法 / 作用 / 示例」三列表
配置项混在正文解释里	「配置项 / 类型 / 默认值 / 说明」表

要点：表格列名要具体、可对照；一行一个项；适合 3 项以上的并列。少量（1-2 项）直接写文字即可，不必硬凑表格。

方向 C：why / 对比 / 体会 → 保留文字

概念性解释、方案对比、用户的体会总结，不要硬转成代码或表格——这些是文字的本职。方向 A/B 只针对「描述操作 / 并列罗列」。

⚠️ 三种方向都受「核心约束：只优化，不扩写」管辖：代码化/表格化是把原文已有的散落信息重新组织，不是凭空生成新内容。原文没提到的 API、没写的配置项，不许"为了完整"而补充。

工序 3：代码块的组织——外部引用 vs 内联

仓库用 Pymdown Snippets 在笔记里嵌入 code/ 目录的真实文件。两条路线按「能否建可运行项目」分流：

路线 A：可建 demo 项目 → 创建到 code/，用 Snippets 引用

凡是 Java、Node、Spring、前端工程这类能搭起可运行 demo 的代码，优先：

1. 在 code/ 下创建一个可运行的小项目（命名遵循 CLAUDE.md 的「code/ 代码示例目录约定」：全英文、kebab-case、无编号、-demo 后缀，目录树与 01-编程笔记/ 同构）。
2. 在笔记里用 Pymdown Snippets 语法引用该项目的真实文件。

Snippets 引用语法（在代码围栏内写 --8<-- 指向文件，渲染时该文件内容被嵌入代码块）：

```java
--8<-- "code/java/basics/collection-demo/src/main/java/com/example/ForEachDemo.java"
```

• 引号内路径是相对仓库根的路径。
• 可以引用片段（按行号或命名区段），具体见 Pymdown Snippets 文档；最常用就是整文件引用。
• 这样做的好处：代码是真实可运行的，笔记里看到的就是 code/ 里跑得通的代码，不会和示例脱节。

⚠️ callout 内的 --8<-- 不渲染

--8<-- 放在 callout（> 引用块）内部不会渲染、只剩源码字面——要把整个代码块移到 callout 外侧上部。遇到 callout 内含 --8<-- 时，读 reference/callout-snippets.md 按前后对照示例处理（移动属安全重组，可直接做、收尾报告里说明）。

🚫 铁律：创建 code/ 项目前必须先问用户

在 code/ 下创建任何新项目之前，必须停下来用 AskUserQuestion 征得用户同意，并确认放置位置。 不要静默创建项目。

询问时给出：

1. 要创建的项目名（英文 kebab-case + -demo 后缀）和建议路径（按 01-编程笔记/ 同构推导，例如笔记在 01-编程笔记/Java/ 下 → 建议 code/java/<name>-demo/）。
2. 请用户确认 / 改名 / 改位置 / 或选择「这次不建项目，代码内联在笔记里」。

为什么：code/ 项目的位置归用户管，错位置会破坏「中文笔记 ↔ 英文代码」的同构对应；而且建项目是有成本的写操作，必须用户点头才做。用户说「先别建项目」时，就改走路线 B 内联。

路线 B：不便建项目 → 直接在笔记里写代码块

SQL、shell、单行命令、配置片段、伪代码这类搭不成可运行工程的代码，直接在笔记里写代码块，不要为它们建 code/ 项目：

```sql
-- 查询每个部门的平均薪资，只看平均大于 10000 的
SELECT department_id, AVG(salary) AS avg_salary
FROM employees
GROUP BY department_id
HAVING AVG(salary) > 10000;
```

判断标准：「这段代码脱离工程上下文还有意义吗 / 能不能搭个最小 demo 跑起来」。能搭 demo → 路线 A（先问）；不能（SQL、shell、纯命令、片段）→ 路线 B 内联。

被 --8<-- 引用的源码，也在优化范围内

笔记用 --8<-- 引用的 code/ 源文件，是这篇笔记的一部分、不是外部只读资源——美化时同样纳入优化范围（读者看到的就是它）。但它是 code/ 里的真实工程、还可能被多篇笔记共用，改动面比笔记正文更大，所以除纯排版外一律先问：

• 排版规范化 → 安全重组，直接做：按该语言约定统一缩进 / 空行 / 括号风格、清理跑偏对齐。前提是保证语义不变——不动代码逻辑、不增删改注释文字。这类纯格式化直接改，收尾报告说明。
• 其余一切改动 → 决策点，先用 AskUserQuestion 问、获准后才改（只要不是纯排版就先问）：
  • 注释增补与优化：沿用工序 2 方向 A 标准（讲意图 / 为什么 / 坑点，不复述字面；只解释代码已有行为，不描述它没有的功能，也不新增方法 / 示例）——把建议加 / 改的注释摆给用户看，同意再写。
  • 语法 / 编译错误（少括号、拼错关键字等）：即便一眼就坏也先指出、问过再修——这是 code/ 真实文件，不当「坏围栏」那样直接改。
  • 逻辑 / 行为错误（能编译但结果不对）：同「正确性审查」，给出位置 + 依据 + 你认为正确的写法，交用户定夺。
• 攒成一次问：同一文件的多处非排版改动（注释 + 语法 + 逻辑疑点）合并成一次询问，别逐条打断。获准改完后，若能低成本验证（编译 / 跑一下），确认 demo 仍跑得通、没改坏。

工序 4：配图增强——一图胜千言

在合适的位置调用三个图表 skill 生成插图，帮助理解。不是每篇都要加图、也不是每个 skill 都用——只在该用、能提升理解的地方加。

三个 skill 的选用

skill	形式	适合场景
mermaid-visualizer	Mermaid 代码块（笔记内）	流程、决策、状态机、时序、类关系等结构化图；改起来快、纯文本、Git 友好。默认优先用它
excalidraw-diagram	Excalidraw .md（手绘风）	需要更自由排版、手绘感、或要叠加批注的图；如架构示意、概念关系涂鸦。Mermaid 表达不了时再上
obsidian-canvas-creator	Obsidian Canvas .canvas（可交互）	想把多个笔记 / 概念空间化组织、做可交互的思维导图 / 依赖网络时用

加图 / 不加图：快速判定

先问一句：这段内容去掉图，纯文字读得懂吗？ 读得懂就不加；读着费劲、要反复来回看才理清结构的，才加。

内容特征	判定	用什么
多步流程 / 状态转换 / 分支决策	✅ 加图	Mermaid 流程图 / 状态图
多组件交互 / 调用时序	✅ 加图	Mermaid sequence
层级分类 / 知识结构（且层级 ≥ 2）	✅ 加图	Mermaid mindmap，或 Excalidraw
架构 / 拓扑，Mermaid 表达受限	✅ 加图	Excalidraw
想跨笔记空间化组织、可交互拖拽	✅ 加图	Canvas
纯指令型文档、并列罗列、线性步骤、无结构关系	❌ 不加图	用标题 / 表格 / 代码解决

三条铁律：

1. Mermaid 优先：纯文本、Git 友好、Obsidian 原生渲染。Mermaid 能表达的，不上 Excalidraw / Canvas。
2. 不凑数：一篇笔记不是必须配图；「凑齐三种图」是反信号。一张恰到好处的 Mermaid 胜过三张没必要的图。
3. 表格 / 标题能解决的，别用图：并列信息用表格，层级用标题——这些比图更易维护。只有「结构关系文字难表达」时才上图。

调用方式：识别出适合配图的位置后，逐个调用对应 skill 生成。Excalidraw / Canvas 文件存到合适位置（放 附件/ 或与笔记同目录，按用户习惯确认），在笔记中用 ![[文件名]] 嵌入，并配一句话说明这张图在看什么。拿不准要不要加图、用哪种，问用户。

收尾自检（完成前逐条过）

• 增删自检：改写后每段信息，原文里都有吗（不扩写）？删掉的都是纯重复、没把用户写过的知识点擅自删 / 合并吗（不擅自删段）？
• 正确性自检：审查中发现的每一处疑点都已存疑、问过用户了？除用户确认要改的错误外，没有静默改动任何内容含义？
• TOC 自检（仅整篇模式）：进 TOC 的标题都是独立知识模块（标签已降级粗体、疑难点已点名）、层级没超过三级、标题文字精简了吗？**只看 TOC 能回忆起这篇笔记讲了什么、难点在哪吗？**章节模式没动 TOC 结构吗？
• 标题内容自检：所有标题（# 到 ######）内都没有反引号（行内代码块）了吗？（标题禁用反引号——见上文「标题内禁用行内代码块」铁律）
• 范围自检：改的都在作用范围内？章节模式没动 frontmatter、没越界改其它节？
• 询问自检：code/ 项目、占位文件名——都问过用户了，没静默处理？
• 代码自检：代码 + 注释已讲清的，外部没有重复文字？没为 SQL / shell 误建项目？Snippets 路径是相对仓库根？callout 内没有遗留 --8<--（已移到 callout 外侧上部）？
• 引用源码自检：被 --8<-- 引用的 code/ 源文件，纯排版外的改动（注释 / 语法 / 逻辑）都问过用户、没静默改？改完确认过 demo 仍能运行？
• 配图自检：Mermaid 优先、没凑数、表格 / 标题能解决的没硬塞图？