WIZARD 使用指南

WIZARD 是基于 VitePress 1.6.4 构建的个人知识库与技术笔记站。本文档说明如何写作、组织内容，以及各项 frontmatter 字段的用途。

工作目录：所有 npm run 命令均在 d:\wizard\site\ 下执行。源文件位于 site/docs/，构建产物输出到 dist/。

目录结构

站点分为四个内容区，职责明确互不干扰：

site/docs/
├── kb/                   # 知识库（本指南重点）
│   ├── index.md          # 知识库首页
│   ├── cipher/           # 大类（8 个）
│   │   ├── index.md
│   │   └── crypto/       # 域（共 27 个）
│   │       ├── index.md
│   │       └── hash-mac/ # 簇（叶子，共 311 个）← 写作位置
│   │           └── index.md
├── archive/              # 归档列表页（文章由 archive frontmatter 标记）
│   └── index.md
├── spec/                 # 设计与使用手册
└── about/, demo/         # 其他页面

知识库层次

层级	示例路径	作用	深度
根	kb/index.md	知识库首页，展示 8 大类总览	1
大类	kb/cipher/index.md	大类索引，展示域列表	2
域	kb/cipher/crypto/index.md	主题域，展示簇列表	3
簇（叶子）	kb/cipher/crypto/hash-mac/index.md	主要写作位置	4

在任意簇下新建子目录即可自动扩展层次。kb-scan 递归扫描，侧栏、导航、进度统计全部自动更新，无需修改任何配置文件。

常用命令

命令	用途
npm run dev	启动开发服务器（localhost:5173），热重载
npm run check	全站模板检查：检测裸 插值、未闭合标签、裸尖括号
npm run build	静态构建，产物输出到 dist/，同时生成 dist/kb-tree.json
npm run preview	预览构建产物

写作前先跑 check：裸 {{ someVar }} 会被 Vue 当插值处理，build 成功但内容静默消失。建议每次写完运行一次。

知识库文章

知识库文章就是各个簇目录下的 index.md。找到对应主题的簇，直接编辑即可。

新建簇

1. 在对应域下新建目录，目录名使用小写连字符，如 kb/cipher/crypto/my-topic/

2. 创建 index.md 并写 frontmatter：

---
title: 我的主题
summary: 一句话说明这个簇的内容
order: 5
---

正文内容...

3. 写完后标记完成（可选）：

---
title: 我的主题
summary: ...
order: 5
complete: true
---

父页的进度统计会自动更新。

新建大类或域

同样新建目录 + index.md，非叶子目录需要加 tree: true 才会显示子目录表格：

---
title: 新域名称
summary: 这个域是关于什么的
order: 3
tree: true
---

可选的说明段落。

调整顺序

修改 order 字段。数字小的排在前面，缺省时按目录名字典序排到末尾。

正文格式

用途	写法
参考链接	<p class="kb-ref">参考：<a href="...">RFC 2104</a></p>
行内提示	<p class="kb-note-inline">练习：实现 X。</p>
注意块	<div class="kb-note">...</div>
数学公式	行内 $E=mc^2$，块级 $$...$$
流程图	代码块语言设为 mermaid

归档文章

归档是文档级标记，不要求文章放在 docs/archive/。在任意可发布文档的 frontmatter 中加入 archive 日期即可进入归档列表；docs/archive/ 只提供归档列表页。

---
title: "Git 远程自建服务器完整指南"
archive: 2026-05-29
tags: ["Git", "Linux", "SSH", "服务器"]
---

正文...

字段	类型	必填	说明
title	string	必填	归档列表标题、页面标题
date	YYYY-MM-DD	必填	归档列表按此降序排列
tags	string[]	可选	归档页标签筛选按钮
draft	boolean	可选	true 时不编译、不出现在归档列表

原子知识单元

当你认为某篇文章是一个可独立判断对错的单一知识点，可以在 frontmatter 中加 atomic: true 标注。系统会在页面底部注入元数据面板，并在父页的子目录表格中显示 ⚛ 徽章。

这是可选标注，不需要为所有文章标注。当内容自然满足"一句话能说清楚"且"会被多处引用"时再标。

标注方式

---
title: HMAC 的嵌套结构
summary: HMAC 的 ipad/opad 双层嵌套构造
order: 3
atomic: true
claim: HMAC 通过嵌套两次哈希把密钥混入内外两层，使攻击者无法通过延伸内层哈希伪造 MAC。
keywords: [HMAC, ipad, opad, MAC, 长度扩展攻击]
requires: [crypto.hash-mac.merkle-damgard]
---

正文...

字段说明

字段	类型	说明
atomic	boolean	唯一触发条件，非 true 时其余字段不生效
claim	string	核心断言，一句话说清楚这个知识点
keywords	string[]	别名、缩写、工具名、报错文本，提高搜索命中率
requires	string[]	前置知识的原子 ID，格式 域.簇.slug，仅展示不生成链接

粒度自检

测试	通过标准	不通过说明
单断言测试	claim 能用一句话写完，不用「并且」	太大，需要拆分
独立检验测试	能设计出一个明确的验证动作	太虚，细化或并入邻近条目
复用测试	能想到至少两处会引用它	只被一处引用，并入那处

Frontmatter 完整参考

知识库页（kb/）

字段	类型	必填	效果
title	string	必填	侧栏名称、页面标题、子目录表格名称列
summary	string	推荐	子目录表格说明列；非根节点页面的描述段落
order	number	推荐	兄弟目录排列顺序，升序，缺省排末尾
tree	boolean	非叶子必填	true 时注入子目录表格
complete	boolean	可选	仅叶子有效，计入父页进度 done 计数
atomic	boolean	可选	true 时注入原子元数据面板，父页显示 ⚛
claim	string	原子推荐	面板「核心断言」，atomic: true 时展示
keywords	string[]	原子推荐	面板「关键词」标签列表
requires	string[]	可选	面板「前置知识」ID 列表

归档标记（archive frontmatter）

字段	类型	必填	效果
title	string	必填	归档列表标题、页面标题
archive	YYYY-MM-DD	必填	标记该文档进入归档，并按日期降序排列
tags	string[]	可选	归档页标签筛选按钮
draft	boolean	可选	独立的草稿标记；docs/kb/draft/ 目录本身也是草稿区，两者互不替代

常见错误

裸 Vue 插值

正文中写了 {{ someVar }}，build 成功但那段文字消失。VitePress 把 Markdown 渲染为 Vue 组件，{{ }} 被当作插值表达式求值。

修复： 用反引号包裹 ``，或写在代码块里。npm run check 会检测并报出。

裸尖括号

写了 Vector<int> 或 a < b > c，build 报 Element is missing end tag。

修复： 写在代码块或 inline code 里，或用 HTML 实体 < / >。

YAML 语法错误

frontmatter 里有未闭合的引号或缩进错误，整站构建失败，报 YAMLException。

修复： 检查最近修改过的文件的 frontmatter，错误信息里的行号是该文件内的行号。

非叶子目录缺 tree: true

新建了非叶子目录的 index.md，但页面没有子目录表格。

修复： 在该目录的 index.md frontmatter 中加 tree: true。

目录名带空格

目录名含空格，部分浏览器无法访问。

修复： 目录名统一使用小写连字符，如 my-topic/。