doc-beautify

name	doc-beautify
description	当用户要美化已有 Obsidian 笔记的排版与可读性时使用（如「帮我美化这篇笔记」）——笔记语法不规范、结构混乱、代码裸奔、长篇抽象文字堆砌、缺可视化。面向「已有正文」的加工；新建空骨架笔记用 doc-create-note，新建分类用 doc-create-category。

美化与格式化笔记

把一篇已经写了正文、但凌乱难读的笔记，整理成结构清晰、语法规范、代码 + 插图配合得当的成品。本 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 规划，如 ## 控制语句 下什么都没有），默认保留不动——不填充（不扩写）、不删除（要删必须问）。占位是用户还没写，不是你要补的。

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

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

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

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

判定原则：

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

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

边界处理细节：

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

工序 0：先读，再动手

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

• 笔记到底在讲什么、当前结构是什么样
• 哪里语法坏掉了（缺闭合的代码块、错位的标题层级、散乱的图片引用）
• 哪些地方在用大段抽象文字描述本可以用代码或图说明的东西（这些是重点改造对象）
• 哪些图片已存在（引用方式对不对）、哪些地方缺图但适合加图
• 验证归属与资源（决定后续要不要问）：用 ls 核对 frontmatter 分类 指向的文件夹笔记是否真实存在——不存在即「非标准位置」，按工序 1 的规则要问用户是否移入分类树；同时核对正文引用的图片是否真实落在 附件/，缺失的图片引用要修或问。

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

工序 1：Markdown 语法规范化

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

必做清单

• frontmatter 完整化：按 模版/普通笔记模版.md 对齐字段（分类/关联笔记/描述/排序/分组/创建时间）。保留原有字段值，不要清空用户已填的内容。分类 是图谱归属边（指向父文件夹笔记，让分类树在关系图谱可见），按位置填好。

⚠️ 非标准位置笔记：分类 必须先问用户

分类 必须指向所在目录的文件夹笔记（参见 AGENTS.md 的「笔记分类机制」）。但很多需要美化的笔记不在标准分类树下——放在仓库根目录、附件/ 等没有文件夹笔记的位置，此时 分类 无法合法填写。

遇到这种情况，一律停下来用 AskUserQuestion 问用户是否移入分类树（用户选项 A：默认选 A），不要静默处理：

• 选项 A（默认）：移入 01-编程笔记/ 分类树——请用户确认目标分类目录（如 01-编程笔记/04-专项研究/Ai/），移动文件后，分类 指向该目录的文件夹笔记。
• 选项 B：暂留原位——分类 留空，并在回复里说明「该笔记不在分类树下，分类 暂留空」。

为什么：位置错了，分类 双链和分类树归属全错，回溯成本高。笔记归入哪个分类是用户的决策，不能猜。即使在「美化」过程中发现位置不对，也要先问、不要顺手移。

判定「非标准位置」：笔记所在目录没有同名文件夹笔记（即目录下没有 目录名.md），就是非标准位置。（网页裁剪/ 是另一套独立体系，由 defuddle 管理，美化时遇到不要改它的 分类。）

美化时主动确认模糊点（不止 code/ 项目）

美化不是闷头改——遇到任何会影响笔记归属或语义的模糊决策，先问用户，不要替用户决定。下面这些都要问：

模糊点	要问什么
笔记位置 / 分类（见上）	是否移入分类树？目标目录？
占位文件名（如「测试笔记」「新建笔记」「无标题」）	是否改名？改成什么？（改名影响已有 wikilink）
来源不明（疑似网页裁剪内容混在01-编程笔记里）	是否该挪到 网页裁剪/？是否补来源链接？
术语策略（满篇中英括注）	保留中英对照还是只留中文？
任何你看不准、改了可能改错含义的地方	直接把疑问抛给用户

这是把「先问」从仅 code/ 项目泛化开——code/ 项目只是其中一个触发点，凡是"动了可能改错归属/语义"的决策都要问。纯排版、语法、结构重组这种"动了不会错"的可以直接做。

标题层级与 TOC：标题是复习索引（重要）

Obsidian 的大纲 / 目录（TOC）由标题自动生成——每一个 ##/###/#### 都会变成目录里的一条。对学习笔记来说，这个目录不是排版装饰，而是日后复习的知识索引：复习时不用重读全文，扫一眼目录就能纵观全篇的知识全貌，定位"我学过哪些大块、哪些小知识点"。所以标题不是"让这里字号大一点"的工具，而是知识模块的边界标记——这条认知决定所有标题取舍。TOC 标题要同时满足三条：进得了 TOC 的才是独立知识点、层级别太深、文字要精简（下文展开）。

由此推出标题 vs 粗体的判定（本节核心判断）：

内容特征	用什么	例子
有自己的实质内容（规则 / 原理 / 多段代码 / 独立讲解），值得作为一个知识模块单独复习	✅ 标题	#### 整数型、#### 浮点型——每种类型各自的赋值规则、代码、坑点，是一个完整的复习单元
只是父主题下的分类标签——下面挂一张表 / 一组并列项，本身没有独立讲解	❌ 粗体引导句 **分类名**	## 关键字 下的「数据类型 / 流程控制 / 异常处理」——只是给一张关键字表贴个分类标签，不是独立知识点

为什么：把分类标签也写成标题，TOC 会被"伪知识模块"塞满——例如 关键字 下平白多出八九个三级标题，目录从"我学了哪些大块"变成密密麻麻的分类清单，反而看不清知识主干。粗体（**分类名**）照样给出视觉分组，又不进 TOC，两全其美。

口诀：写标题前问两句——「这条进 TOC 后，复习时帮我定位到一个独立的知识模块 / 小知识点吗？」「标题文字一眼能看完吗？」第一句答不上（只是分组 / 标签 / 装饰）就降级粗体；第二句答不上就把标题精简成名词短语。

美化时如果发现笔记里已有这类"标签型标题"导致 TOC 杂乱，降级成粗体属于"动了不会错"的结构重组，可以直接做（不必逐个问），但要在收尾报告里告诉用户改了哪些标题、为什么。

TOC 别太深：标题层级一般控制在 ## / ### / #### 三级以内。TOC 面板宽度有限，深层节点缩进后会挤成一团，层级太深就失去了"一眼纵观全貌"的复习价值。某个点想进 TOC 但层级已经很深时，先回到上面的「标题 vs 粗体」判断——它是独立子知识点，还是父节点下的一个标签？标签降级粗体（不进 TOC），确实是子知识点才继续往下开一级。

标题文字精简：TOC 面板窄，长标题会折行 / 截断，扫读时反而看不清。标题写名词短语，不写整句，去掉"关于""的说明""详解""如何"等废话——能用 3-6 个字说清就别用一长串（整数型 优于 关于 Java 整数类型的详细说明，forEach 遍历 优于 如何使用 forEach 方法遍历集合）。

编排只针对现有内容：TOC 编排在笔记已有的文字上做取舍，不凭空造一个原文没有的章节（受核心约束「不扩写」管辖）。真遇到"这里拆一个标题 / 合并两节会更清楚"的结构性增删，按核心约束先问用户，不自动改——降级粗体不算删（内容还在，只是不进 TOC），可以直接做。

合并碎片标题（降级的姊妹招）：降级去「标签噪音」，合并去「碎片化」。当几个相邻小标题是同一知识点的并列子操作（互为逆运算、同类的几个步骤、同一事物的几个方面），合成一个标题、内部用粗体分子项，比各占一个标题更利于复习。例：十六进制转二进制 + 二进制转十六进制 → 合成一个 #### 与二进制互转，内部用 **十六进制 → 二进制** / **二进制 → 十六进制** 分方向——TOC 少一个节点，碎片收敛成一个可单独复习的知识点。合并动了标题边界、属结构重组，按核心约束先问用户、不自动合。

其余标题硬规则（机械执行，不用判断）：全文有且只有一个一级标题（与文件名一致）；修掉跳级（如 H1 直接到 H4）、多重 H1、用标题当样式（纯粹为放大字号而套 ###）；明显的笔误 / 乱码标题（输入法错误、无意义字符，如 算数匀速阿福→算术运算符）可直接修正、收尾报告里说明——这类是坏掉的标题，不是用户有意命名。

其余语法清单

• 列表与代码块闭合：补齐未闭合的代码围栏、修正缩进错乱的嵌套列表、把「用空格/连字符当装饰」的地方改成真正的列表。
• 链接语法：内部引用一律用 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/ 下创建一个可运行的小项目（命名遵循 AGENTS.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/ 里跑得通的代码，不会和示例脱节。

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

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

询问时给出：

1. 要创建的项目名（英文 kebab-case + -demo 后缀）和建议路径（按 01-编程笔记/ 同构推导，例如笔记在 01-编程笔记/03-Java/01-基础/ 下 → 建议 code/java/basics/<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 内联。

工序 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 结构吗？
• 范围自检：改的都在作用范围内？章节模式没动 frontmatter、没越界改其它节？
• 询问自检：非标准位置、code/ 项目、占位文件名、来源不明——都问过用户了，没静默处理？
• 代码自检：代码 + 注释已讲清的，外部没有重复文字？没为 SQL / shell 误建项目？Snippets 路径是相对仓库根？
• 配图自检：Mermaid 优先、没凑数、表格 / 标题能解决的没硬塞图？