메뉴
当用户要美化已有 Obsidian 笔记的排版与可读性时使用（如「帮我美化这篇笔记」）——笔记语法不规范、结构混乱、代码裸奔、长篇抽象文字堆砌、缺可视化。面向「已有正文」的加工；新建空骨架笔记用 doc-create-note，新建分类用 doc-create-category。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | doc-beautify |
| description | 当用户要美化已有 Obsidian 笔记的排版与可读性时使用（如「帮我美化这篇笔记」）——笔记语法不规范、结构混乱、代码裸奔、长篇抽象文字堆砌、缺可视化。面向「已有正文」的加工；新建空骨架笔记用 doc-create-note，新建分类用 doc-create-category。 |
把一篇已经写了正文、但凌乱难读的笔记，整理成结构清晰、语法规范、代码 + 插图配合得当的成品。本 skill 是一条加工流水线，按以下顺序执行（工序 2 / 3 / 4 可穿插，但工序 0 必须先做、工序 3 建项目须用户同意）：
obsidian-markdown，修语法 / 排版 / frontmatter；标题取舍以 TOC 为复习索引。code/ 建项目用 Snippets 引用；SQL / shell 等内联。先诊断，按需改造：工序 0 诊断完后，已合格的部分直接跳过——很多笔记已部分或全部美化过，不要为了"走完流水线"把用户已满意的代码 / 表格 / 图重造一遍，只动真正需要优化的点。
为什么有这条 skill：用户的笔记多是学习时快速记下的文字和图片，常常不符合基本 markdown 语法、结构混乱、长篇抽象文字堆砌、缺少可视化。目标是把它变成「好读、好查、好理解」的成品。
只优化现有内容——不扩写（不加原文没有的知识），也不擅自删段（删 / 合并用户写过的整段或章节要先问）。
这是本 skill 的最高约束，凌驾于其它工序之上：
为什么：这是用户的学习笔记，记录的是用户当时学到/记下的东西。自行扩写会污染笔记的真实性——分不清"哪些是我当时学的"和"哪些是 AI 后来加的"；自行删段则会丢掉用户当时记下的东西。用户要"更完整"会自己学自己补，或明确要求补；要删某段也会自己删，或让你删。美化只管把已有内容变得好读，不替用户做增删决策。
两条边界判定：
## 控制语句 下什么都没有），默认保留不动——不填充（不扩写）、不删除（要删必须问）。占位是用户还没写，不是你要补的。拿不准某段算"优化"还是"扩写 / 删减"时，问用户。
先确定本次要改的范围，再动手——避免对已经整理过的部分重复扫描、重复优化。
判定原则：
| 用户说法 | 作用范围 |
|---|---|
| 「美化这篇笔记」「整理一下排版」「格式化它」（无指向） | 整篇 |
「优化 X 章节」「整理第 N 节」「只看 ## XXX 这块」 | 仅指定章节 |
| 「除了 X 部分，其它整理一下」 | 整篇排除 X |
为什么：同一篇笔记可能上次已经美化过前几节。如果不区分范围、每次都整篇重扫，既浪费 token 又可能把用户已经满意的段落改坏。指定了范围就严格守住边界，别越界。
边界处理细节：
code/ 项目创建规则（先问用户）不变。开工前必须完整读一遍目标笔记原文（用 Read 读全文，不要只读片段），搞清楚：
ls 核对 frontmatter 分类 指向的文件夹笔记是否真实存在——不存在即「非标准位置」，按工序 1 的规则要问用户是否移入分类树；同时核对正文引用的图片是否真实落在 附件/，缺失的图片引用要修或问。读完再开始改。不要边读边改、看一段改一段——容易把笔记的整体结构改散。
调用 obsidian-markdown skill（**REQUIRED SUB-SKILL**）获取完整语法参考，然后按下列要点规范化全文。这一步只动语法和排版，不重写内容含义。
模版/普通笔记模版.md 对齐字段（分类/关联笔记/描述/排序/分组/创建时间）。保留原有字段值，不要清空用户已填的内容。分类 是图谱归属边（指向父文件夹笔记，让分类树在关系图谱可见），按位置填好。分类 必须先问用户分类 必须指向所在目录的文件夹笔记（参见 AGENTS.md 的「笔记分类机制」）。但很多需要美化的笔记不在标准分类树下——放在仓库根目录、附件/ 等没有文件夹笔记的位置，此时 分类 无法合法填写。
遇到这种情况，一律停下来用 AskUserQuestion 问用户是否移入分类树（用户选项 A：默认选 A），不要静默处理：
01-编程笔记/ 分类树——请用户确认目标分类目录（如 01-编程笔记/04-专项研究/Ai/），移动文件后，分类 指向该目录的文件夹笔记。分类 留空，并在回复里说明「该笔记不在分类树下，分类 暂留空」。为什么：位置错了，
分类双链和分类树归属全错，回溯成本高。笔记归入哪个分类是用户的决策，不能猜。即使在「美化」过程中发现位置不对，也要先问、不要顺手移。
判定「非标准位置」：笔记所在目录没有同名文件夹笔记（即目录下没有 目录名.md），就是非标准位置。（网页裁剪/ 是另一套独立体系，由 defuddle 管理，美化时遇到不要改它的 分类。）
code/ 项目）美化不是闷头改——遇到任何会影响笔记归属或语义的模糊决策，先问用户，不要替用户决定。下面这些都要问：
| 模糊点 | 要问什么 |
|---|---|
笔记位置 / 分类（见上） | 是否移入分类树？目标目录？ |
| 占位文件名（如「测试笔记」「新建笔记」「无标题」） | 是否改名？改成什么？（改名影响已有 wikilink） |
| 来源不明（疑似网页裁剪内容混在01-编程笔记里） | 是否该挪到 网页裁剪/？是否补来源链接？ |
| 术语策略（满篇中英括注） | 保留中英对照还是只留中文？ |
| 任何你看不准、改了可能改错含义的地方 | 直接把疑问抛给用户 |
这是把「先问」从仅
code/项目泛化开——code/项目只是其中一个触发点，凡是"动了可能改错归属/语义"的决策都要问。纯排版、语法、结构重组这种"动了不会错"的可以直接做。
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、用标题当样式（纯粹为放大字号而套 ###）；明显的笔误 / 乱码标题（输入法错误、无意义字符，如 算数匀速阿福→算术运算符）可直接修正、收尾报告里说明——这类是坏掉的标题，不是用户有意命名。
[[笔记名]]、[[笔记名|显示文本]]）；只有外部网址用 [文本](https://...)。把原文里写成普通文本的笔记引用改成 wikilink。附件/，正文用 ![[图片名.png]] 引用；可带宽度 ![[图片名.png|500]]。修掉写成 markdown 外链的本地图片、错路径的引用。==高亮==、加粗用 **...**；不要滥用、不要整段高亮。> [!note] / > [!warning] / > [!tip] 等 callout，提升扫读效率：
> [!tip] 或 > [!note] 收纳比裸列表更醒目。判断标准：这段内容是「想让读者一眼记住的要点」而非「普通信息罗列」，就适合 callout。`强调` 着重（如「字面量是源代码中值的直接表示…确定其 类型 和 值」）。识别特征：一句话陈述、以术语本身开头、回答「这是什么」而非「怎么用」——回答「怎么用」的走代码/表格，不归入此类。这一步产出的是一篇「语法干净、结构规整、但还是原内容」的笔记。后面三道工序才动内容的表达方式。
原则：能用代码或表格说清楚的，就别用大段抽象文字。 代码展示「怎么做」，表格展示「并列项的对比」。
这是本 skill 区别于普通「排版工具」的关键。学习笔记里最常见的毛病是：用三五段文字解释一个 API、一段配置、罗列一堆并列项——读者读完还是不知道实际长什么样。改造方向有三：
| ❌ 抽象文字描述（避免） | ✅ 代码 + 注释（提倡） |
|---|---|
「forEach 接收一个 Consumer，会对每个元素执行该函数」 | 直接给一段 Java 代码，在 forEach 调用处写注释解释 |
| 「需要在 application.yml 里配置数据源 url、用户名、密码」 | 直接给一段 yaml，关键字段上行内注释 |
「先用 add 添加元素，再用 poll 取出队首」 | 给一段连贯的可运行代码，注释标出每一步 |
要点：
// 设置 name 这种废话），要解释意图、原理、坑点。当笔记在罗列多个并列的事物（多个 API 对比、多平台安装方式、多个配置项及其作用、多个命令及用途），优先用表格汇总，而不是一长串段落或散落的列表项。表格让读者一眼定位、便于对照。
| ❌ 散落段落 / 裸列表（避免） | ✅ 表格（提倡） |
|---|---|
| 十个平台的安装命令分散在十段文字里 | 一张「平台 / 安装命令 / 备注」表格 |
「forEach 用来遍历，map 用来映射，filter 用来过滤…」 | 「方法 / 作用 / 示例」三列表 |
| 配置项混在正文解释里 | 「配置项 / 类型 / 默认值 / 说明」表 |
要点：表格列名要具体、可对照；一行一个项；适合 3 项以上的并列。少量（1-2 项）直接写文字即可，不必硬凑表格。
概念性解释、方案对比、用户的体会总结，不要硬转成代码或表格——这些是文字的本职。方向 A/B 只针对「描述操作 / 并列罗列」。
⚠️ 三种方向都受「核心约束：只优化，不扩写」管辖：代码化/表格化是把原文已有的散落信息重新组织，不是凭空生成新内容。原文没提到的 API、没写的配置项，不许"为了完整"而补充。
仓库用 Pymdown Snippets 在笔记里嵌入 code/ 目录的真实文件。两条路线按「能否建可运行项目」分流：
code/，用 Snippets 引用凡是 Java、Node、Spring、前端工程这类能搭起可运行 demo 的代码，优先：
code/ 下创建一个可运行的小项目（命名遵循 AGENTS.md 的「code/ 代码示例目录约定」：全英文、kebab-case、无编号、-demo 后缀，目录树与 01-编程笔记/ 同构）。Snippets 引用语法（在代码围栏内写 --8<-- 指向文件，渲染时该文件内容被嵌入代码块）：
```java
--8<-- "code/java/basics/collection-demo/src/main/java/com/example/ForEachDemo.java"
```
code/ 里跑得通的代码，不会和示例脱节。code/ 项目前必须先问用户在 code/ 下创建任何新项目之前，必须停下来用 AskUserQuestion 征得用户同意，并确认放置位置。 不要静默创建项目。
询问时给出：
-demo 后缀）和建议路径（按 01-编程笔记/ 同构推导，例如笔记在 01-编程笔记/03-Java/01-基础/ 下 → 建议 code/java/basics/<name>-demo/）。为什么：
code/项目的位置归用户管，错位置会破坏「中文笔记 ↔ 英文代码」的同构对应；而且建项目是有成本的写操作，必须用户点头才做。用户说「先别建项目」时，就改走路线 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 内联。
在合适的位置调用三个图表 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 |
| 纯指令型文档、并列罗列、线性步骤、无结构关系 | ❌ 不加图 | 用标题 / 表格 / 代码解决 |
三条铁律：
调用方式：识别出适合配图的位置后，逐个调用对应 skill 生成。Excalidraw / Canvas 文件存到合适位置（放 附件/ 或与笔记同目录，按用户习惯确认），在笔记中用 ![[文件名]] 嵌入，并配一句话说明这张图在看什么。拿不准要不要加图、用哪种，问用户。
code/ 项目、占位文件名、来源不明——都问过用户了，没静默处理？Extract clean markdown content from web pages using Defuddle CLI, attach a unified Obsidian frontmatter, auto-translate English content into academic Chinese, download images to the local 附件/ folder (rewriting references to Obsidian ![[file]] embeds), and save to the 网页裁剪/ directory. Always dedupes first — before fetching any URL it greps the 网页裁剪/ directory's frontmatter 来源 field to check whether that page was already clipped; if so it reuses the existing note as-is (never re-fetches or alters it) and only builds a wikilink to it. Use instead of WebFetch when the user provides a URL to read, clip, archive, or to batch-clip the sub-links of an index/trail page — for online documentation, articles, blog posts, GitHub READMEs, or any standard web page. Do NOT use for URLs ending in .md — those are already markdown, use WebFetch directly.
在 Obsidian 笔记仓库中创建一个分类——即同时创建分类目录、该目录内部与目录同名的「文件夹笔记」（目录即分类）、一篇用于汇总参考资源的「相关资源」笔记骨架，并同步配置 Notebook Navigator 的文件夹图标与颜色，使新分类在导航栏立即可见可辨。当用户要新建分类、新建目录、新增主题分区、加一个学习板块、加一个主题时使用，例如「在 03-Java 下加一个并发分类」「在 其它 下建一个电子印章管理平台分类」。分类不限于 `01-编程笔记/`，vault 内任意内容目录（如 `11-其它/`）都能建。创建前必须先确认分类名和明确的相对位置（父目录），用户未指定位置时必须询问，绝不凭猜测创建。本 skill 只建分类骨架；若要在分类下写普通内容笔记，改用 doc-create-note。
在 Obsidian 笔记仓库中创建一篇普通笔记的骨架（frontmatter + 一级标题，不含正文）。当用户要新建笔记、写一篇笔记、记录某个知识点、加一篇学习笔记时使用，例如「在 Spring 下写一篇 IOC 笔记」「记录一下 JVM 垃圾回收」。创建前必须先确认笔记名和明确的相对位置（放在哪个分类目录下），用户未指定位置时必须询问，绝不凭猜测创建。如果是要新建一个分类目录（目录 + 文件夹笔记），改用 doc-create-category。
Generate Excalidraw diagrams from text content for Obsidian. Use when user asks to create diagrams, flowcharts, mind maps, or visual representations in Excalidraw format. Triggers on "Excalidraw", "画图", "流程图", "思维导图", "可视化", "diagram".
Transform text content into professional Mermaid diagrams for presentations and documentation. Use when users ask to visualize concepts, create flowcharts, or make diagrams from text. Supports process flows, system architectures, comparisons, mindmaps, and more with built-in syntax error prevention.
Create Obsidian Canvas files from text content, supporting both MindMap and freeform layouts. Use this skill when users want to visualize content as an interactive canvas, create mind maps, or organize information spatially in Obsidian format.