doc-create-category

name	doc-create-category
description	在 Obsidian 笔记仓库中创建一个分类——即同时创建分类目录、该目录内部与目录同名的「文件夹笔记」（目录即分类）、一篇用于汇总参考资源的「相关资源」笔记骨架，并同步配置 Notebook Navigator 的文件夹图标与颜色，使新分类在导航栏立即可见可辨。当用户要新建分类、新建目录、新增主题分区、加一个学习板块、加一个主题时使用，例如「在 03-Java 下加一个并发分类」「在 其它 下建一个电子印章管理平台分类」。分类不限于 `01-编程笔记/`，vault 内任意内容目录（如 `11-其它/`）都能建。创建前必须先确认分类名和明确的相对位置（父目录），用户未指定位置时必须询问，绝不凭猜测创建。本 skill 只建分类骨架；若要在分类下写普通内容笔记，改用 doc-create-note。

创建分类（目录 + 文件夹笔记）

本仓库采用「目录即分类 + 文件夹笔记」的组织方式（配合 Notebook Navigator 插件），主要用在 01-编程笔记/，但也适用于 vault 内的其它内容目录（如 11-其它/）。创建一个分类 = 同时创建四样东西：

1. 一个目录
2. 该目录内部一个与目录同名的 .md 文件夹笔记（且文件夹笔记内嵌通用 base ![[分类索引.base]]，作为该分类的动态索引页）
3. 该目录内部一个名为「相关资源」的 .md 笔记骨架，用于集中罗列该分类的参考资源（官方文档、书籍、教程文章、视频、代码示例、网页裁剪等）。只生成骨架（frontmatter + 一级标题 + 资源分类的二级标题框架），正文留空由用户后续整理。
4. 在 Notebook Navigator 配置里登记该目录的图标与颜色（写入 .obsidian/plugins/notebook-navigator/data.json），让新分类一建好就在导航栏有辨识度

铁律：必须先拿到明确位置

这是本 skill 最核心的约束。创建分类会改变目录树结构，位置一旦错了，后续所有子笔记的目录归属、文件夹笔记层级都会跟着错，回溯成本高。因此：

开始任何写操作之前，必须先明确两件事：

1. 分类名（= 目录名 = 文件夹笔记文件名）
2. 相对位置：新分类作为哪个目录的子目录。位置以相对于仓库根的路径表达，如「01-编程笔记/03-Java/ 下」或「11-其它/ 下」。分类不限于 01-编程笔记/——vault 内任意已存在的内容目录（01-编程笔记/、11-其它/ 等）都能建分类。用户说「在 X 目录下」时，先确认 X 的实际路径（用 find / Glob 查实，它可能在 01-编程笔记/ 之外），不要默认它一定挂在 01-编程笔记/ 下；找不到就问用户。

如果用户只给了分类名、没给明确位置，停下来询问，不要根据分类主题猜测它该归到哪个顶层分类下。用 AskUserQuestion 列出可选父目录，或直接请用户指定。

为什么：新分类挂在哪一支下面，是用户的分类决策，不是 agent 能推断的。这一步省事的代价是后面一连串的错误归属。

工作流

1. 确认分类名与位置（缺一不可，缺则询问）。
   • 分类名用中文；目录是否带编号前缀由用户决定（如 01-基础 或 并发），不要擅自加编号。
2. 克制开层（软指引，无硬上限）：优先在文件夹笔记下用子页 + 正文 wikilink 表达细分；只在主题确实需要独立目录时才开新层。学科结构本身有深有浅（如 01-编程笔记/03-Java/01-基础/01-JavaSE/基本语法.md 是 4 层），跟随主题，不预设深度数字——别为凑层数把自然细分拍扁，也别为开层而开层。
3. 推导 分类 属性（图谱归属边）：
   • 父目录是某个内容域的根（即该域的顶层分类，如 01-编程笔记/01-基础知识/、11-其它/电子印章管理平台/）→ 分类 留空（它就是该域分类树的根）。内容域 = vault 顶层的内容目录（01-编程笔记/、11-其它/ 等），其直接子目录都是各自域的顶层分类，规则与 01-编程笔记/ 下一致。
   • 否则 → 分类 指向父目录的文件夹笔记（= 父目录名）。例：在 01-编程笔记/03-Java/ 下创建 并发，文件夹笔记的 分类 写 - "[[03-Java]]"。
   • ⚠️ 前提是父目录要有文件夹笔记。若父目录是裸目录（无文件夹笔记，例如刚建好还没结构化的 11-其它/）：要么先给父目录补一个文件夹笔记、再让本分类指向它；要么把本分类当作该域的顶层分类（分类 留空）。二选一，拿不准问用户。
   • 为什么填 分类：base 用物理位置聚合、不依赖它，但关系图谱只看 wikilink、不看路径——分类 是让分类树在图谱可见的归属边，必须填。
4. 创建目录：<父目录完整路径>/<分类名>/（如 01-编程笔记/03-Java/并发/ 或 11-其它/电子印章管理平台/）
5. 在目录内部创建文件夹笔记：<新目录>/<分类名>.md，内容用下方「文件夹笔记模版」（含 ![[分类索引.base]] 嵌入，使该分类成为动态索引页）。必须带 tags: 分类页（详见模板说明），否则图谱颜色规则失效。
6. 在目录内部创建「相关资源」笔记骨架：<新目录>/相关资源.md，内容用下方「相关资源笔记模版」。这是一篇普通笔记（不是文件夹笔记），其 分类 指向本分类的文件夹笔记（= 分类名）。只建骨架，不写正文/资源条目——资源内容由用户后续整理。
7. 配置 Notebook Navigator 图标与颜色：按下方「配置 Notebook Navigator 图标与颜色」章节确定图标和颜色，用 Edit 把新条目追加进 .obsidian/plugins/notebook-navigator/data.json 的 folderIcons 和 folderColors 两个 map。
8. 提示用户重载插件：配置写完后告诉用户在 Obsidian 里重载 Notebook Navigator（设置 → 第三方插件 → 关闭再开启，或 Ctrl+P → Reload app without saving）才可见效。

配置 Notebook Navigator 图标与颜色

Notebook Navigator 用 .obsidian/plugins/notebook-navigator/data.json 里的 folderIcons 和 folderColors 两个 map 控制文件夹外观。创建分类后必须同步登记，否则新分类在导航栏无图标无颜色。

key 格式（重要）

map 的 key = 新分类在仓库根的完整相对路径，无尾部斜杠。例：在 01-编程笔记/03-Java/ 下建 并发，key 是 01-编程笔记/03-Java/并发；在 11-其它/ 下建 电子印章管理平台，key 是 11-其它/电子印章管理平台（不是裸 分类名，也不带尾部 /）。

颜色：容器涂域色，叶子各涂一色

仓库用颜色兼顾两个目的：一眼看出归属、一眼分清兄弟。规则就两条：

• 容器/伞分类（自身含子分类，如 03-Java、01-基础、02-服务端开发、Ai）→ 涂所属域的代表色，表归属。容器沿域继承：子容器（如 03-Java/01-基础）和它的域根（03-Java）同色。
• 叶子分类（不再有子分类、直接放笔记的知识点，如 JavaSE、HTML、Claude Code）→ 同级兄弟各占一色，表区分。展开父目录时一眼能分辨每个知识点。

唯一硬约束：同一父目录下的叶子兄弟绝不同色。 全局是否唯一不作要求——跨层级、跨域偶有同色是允许的（例如两个不同分支下都各有自己的「绿」），只要在同一展开视图里不撞色即可。

⚠️ 反例警示（本规则的由来）：若按旧规则「Java 旗下细分全继承 Java 橙」，则展开 03-Java 时 JavaSE、JVM、Java日志、Maven、测试 10 个知识点全涂一色，颜色就丧失了区分作用。知识点越细，越要各涂一色——这正是从旧「继承父级色」改为「叶子各涂一色」的原因。

取色步骤：

1. 先判定新分类是容器还是叶子：看它会不会再含子分类。
   • 会含子分类（如新建一个 并发 大类，下面还要分「线程」「锁」等）→ 当容器处理，涂域代表色。
   • 直接放笔记、不再细分（如 Maven、测试、HTML）→ 当叶子处理。
2. 容器 → 找它所属域的根（向上找最近的容器/顶层分类），取该域代表色。不确定域色时读 folderColors 看祖先。
3. 叶子 → 读取 folderColors，列出同一父目录下所有兄弟，确认它们已占了哪些色；从下方调色板挑一个兄弟未占用的颜色。多个可选时挑语义最贴切的；拿不准时问用户，不要擅自定。
4. 新建顶层分类（父目录是某内容域的根，如 01-编程笔记/ 或 11-其它/ 本身）：从调色板挑一个未用色作该域/该分类的代表色。
5. 用户明确指定颜色时，以用户为准。

调色板（选色用；用前务必读 folderColors 核对实际占用，勿凭记忆）:

颜色	十六进制	语义联想（非强绑）
蓝	#3b82f6	基础/通用知识
青	#06b6d4	前端（域色）
橙	#ed8b00	Java（域色）
紫罗兰	#8b5cf6	专项研究（伞分类域色）
深紫	#7c3aed	Obsidian（域色）
翠绿	#10b981	AI（域色）
绿	#22c55e	工具/代码
琥珀	#f59e0b	服务端 / 运维 / 部署
粉	#ec4899	设计 / 杂项
灰蓝	#0891b2	数据 / 基础设施（容器、网络）
玫红	#f43f5e	（补充色，JavaSE 等用）
靛	#6366f1	（补充色，Claude Code / 计算机网络等用）
青绿	#14b8a6	（补充色，操作系统 / Java日志等用）
黄	#eab308	（补充色，JS / Maven 等）
橙红	#f97316	（补充色，HTML 等）
黄绿	#84cc16	（补充色，数据结构等）
天蓝	#0ea5e9	（补充色，JavaWeb / mysql 等）
红	#ef4444	待办 / 警示

图标：按语义选（lucide）

仓库约定图标保持差异化，图标表达「具体内容」。按分类名语义从下表选一个最贴切的图标；表里没有的用其它 lucide 图标名（全小写连字符）；实在拿不准时用兜底 folder，并提示用户可换。用户明确指定图标时，以用户为准。

主题关键词	图标
基础/通用知识、教程	book-open
前端、页面布局、UI	layout-template
HTML	file-code
CSS、样式、主题	palette
JavaScript、脚本	file-code-2
Java	coffee
后端、服务端	server
Web、网络、HTTP	globe
数据库、存储	database
Spring、IoC、框架核心	leaf
JVM、性能、运行时	cpu
日志、记录	scroll-text
研究、专题、探索	microscope
AI、智能、生成	sparkles
终端、CLI、命令行	terminal
GitHub、版本控制	github
插件、扩展、集成	puzzle
工具、配置、设置	wrench
测试、质量	bug / shield-check
安全	shield
数据结构、算法	binary / git-branch
Obsidian、笔记工具	gem
任务、待办	list-todo
图片、附件、资源	image
网页裁剪、抓取	clipboard-list
模版	templater-icon

写入方式

用 Edit 把一行新条目追加进对应 map，2 空格缩进，保持 JSON 合法。不要整文件重写，只动两个 map 里对应位置。

追加示例（在 01-编程笔记/03-Java/01-基础/ 下建 并发，作为叶子从兄弟未占色中挑一个，如玫红 #f43f5e）：

在 folderColors 里 01-编程笔记/03-Java/01-基础/测试 那一行之后插入：

    "01-编程笔记/03-Java/01-基础/并发": "#f43f5e",

在 folderIcons 里对应位置插入：

    "01-编程笔记/03-Java/01-基础/并发": "git-branch",

若新分类是容器（还会再含子分类，如 04-专项研究/Docker 若其下还要细分），涂所属域的代表色（Docker 属专项研究域 → 域色紫罗兰 #8b5cf6）；若是叶子则按「容器涂域色，叶子各涂一色」章节从兄弟未占色中挑一个。

写入顺序无所谓功能，但按字母/路径顺序插入更易维护。写完后用 node -e "JSON.parse(...)" 校验 JSON 合法性，避免缩进或逗号错误。

校验

写完两个条目后，必须跑一次 JSON 校验：

node -e "JSON.parse(require('fs').readFileSync('.obsidian/plugins/notebook-navigator/data.json','utf8')); console.log('JSON 格式正确')"

校验失败则修正后再继续。

文件夹笔记必须放在目录内部

⚠️ 文件夹笔记的路径必须是 目录/目录名.md（在目录内部）。

• ✅ 正确：01-编程笔记/03-Java/01-基础/01-基础.md
• ❌ 错误：01-编程笔记/03-Java/01-基础.md（放在父目录里）

放在父目录里会被 Notebook Navigator 当成普通笔记，无法绑定文件夹——这是最常犯的错误。

文件夹笔记模版

---
分类:          # 按工作流步骤 3 推导；顶层分类留空
关联笔记:
描述:
排序:
分组:
tags: 分类页    # 文件夹笔记专属：让图谱「分类页」颜色规则（tag:#分类页）识别本节点。普通笔记不要带此标签
创建时间: 2026年06月25日
---
# 分类名

## 本分类下的笔记

![[分类索引.base]]

• tags: 分类页 是文件夹笔记的专属标记：仓库的 Obsidian 图谱配置里有一条颜色规则 tag:#分类页，专门把分类节点（文件夹笔记）涂成紫色。只有文件夹笔记带这个标签——普通笔记（包括「相关资源」笔记）不要写它，否则会被误当成分类节点着色。注意 Obsidian 的标签字段 key 必须是英文 tags（中文 key「标签」不会被识别为标签）。

• 嵌入 分类索引.base 是创建分类的标配：仓库里有一个通用 base 分类索引.base（位于 数据库/ 目录），它用 this.file.folder 自动筛选「与当前文件夹笔记同文件夹的所有笔记」（按物理位置聚合，不依赖任何 frontmatter 字段）。每个文件夹笔记都通过 ![[分类索引.base]] 嵌入它（按文件名解析，base 放哪个目录都不影响），从而成为该分类的动态索引页——新增子笔记只要放进该目录，就会自动出现在索引里，无需逐个分类维护、无需填任何归属字段。

• 索引只显示直接子笔记，自动排除文件夹笔记自身与子文件夹：base 通过 file.folder == this.file.folder（同文件夹）+ file.name != this.file.name（排除自身）过滤。子文件夹里的笔记属于它自己那层的索引，不会冒泡到父级——这是预期行为（子分类该在它自己的索引页里聚合它的笔记，而非挂在父级）。

• 分类 字段不参与 base 聚合，但必须照填：base 按物理位置工作，不需要 分类。但关系图谱只看 wikilink、不看文件夹路径——分类 双链是让分类树在图谱里可见的归属边。不填，图谱里分类树断裂、笔记成孤儿。所以 分类 照填（指向父文件夹笔记），和 base 各管一摊。

• 文件名、目录名、一级标题三者完全一致。

• 时间填当前时间，不要回填历史。格式统一为中文：创建时间写 YYYY年MM月DD日（如 2026年06月25日）。

• frontmatter 字段未用到可留空，但不要删除字段，保持结构一致。

完整字段语义与分类机制见项目根 AGENTS.md 的「笔记分类机制」「Frontmatter」两节。

相关资源笔记模版

「相关资源」是一篇普通笔记，用于集中汇总该分类的参考资源。只生成下方骨架（frontmatter + 一级标题 + 资源分类的二级标题框架），二级标题下留空，资源条目由用户后续自行整理，你不要代填任何链接或条目。

---
分类:          # 指向本分类的文件夹笔记，如 - "[[并发]]"（= 分类名）
关联笔记:
描述:
排序:
分组:
创建时间: 2026年06月25日
---
# 相关资源

## 官方文档

## 书籍

## 教程文章

## 视频

## 代码示例

## 网页裁剪

说明：

• 这是普通笔记，不是文件夹笔记：分类 指向本分类的文件夹笔记（= 分类名，作图谱归属边），但不要写 tags: 分类页——那个标签是文件夹笔记专属，普通笔记带了会被图谱误着色为分类节点。

• 一级标题固定为「相关资源」（与文件名一致），不要换成「XX 相关资源」之类。

• 二级标题是默认的资源分类框架：官方文档 / 书籍 / 教程文章 / 视频 / 代码示例 / 网页裁剪。这是建议的初始结构，用户后续可自行增删改名——你按这套默认生成即可，除非用户明确指定其它分类。

• 二级标题下留空：不写任何条目、不补占位符、不查资料代填。这是骨架，内容是用户的活。

• 分类 指向本分类的文件夹笔记（= 分类名），与该目录下其它普通笔记规则一致，作图谱归属边；不要指向「相关资源」自身。

• 「网页裁剪」一节用于用 wikilink 引用 网页裁剪/ 目录下的裁剪笔记（如 [[某篇文章]]），保持「01-编程笔记写整理、原始内容留在网页裁剪」的分离。

• 时间填当前时间（YYYY年MM月DD日），不要回填历史；frontmatter 字段未用到可留空，但不要删除字段。

铁律：相关资源只建骨架，不代填资源

与 doc-create-note 同理——「相关资源」笔记的正文（具体资源条目）是用户自行整理的成果，你不要代笔：

借口	现实
「我了解这个主题，顺手推荐几本书/几个链接」	禁止。资源取舍是用户的研究判断，不要代填
「官方文档网址我知道，填一下更完整」	禁止。哪怕一条也不写，骨架就是骨架
「二级标题下太空，补两行示例」	禁止。空标题框架就是交付物
「调 WebSearch / defuddle 找点参考资料填进去」	禁止。要查资料是另一个请求，不在本 skill 范围

红旗：一旦想在某条二级标题下写任何条目（链接、书名、TODO、占位符），停手——那已是越界。只交付骨架。