frontmatter schema
解决什么问题：所有文档 frontmatter 字段统一——机器可读、最小必填集、向后兼容。
它是什么
每篇 .md 文件第一段（--- 包围）是 frontmatter。它是文档的元数据——侧边栏生成、全文搜索、骨架自举都靠它。
必填字段（4 个）
yaml
---
title: 文档标题 # 人类可读
type: overview | concept | case | stub # 决定结构模板
layer: L1 | L2 | L3 | L4 | L5 | meta # 顶层分区
group: strategic | tactical | ... # 二级 group
---字段含义：
| 字段 | 用途 | 取值 |
|---|---|---|
title | 侧边栏显示、<title> 标签 | 任意字符串 |
type | 决定写作模板（见 index） | overview / concept / case / stub |
layer | 顶层分区，影响 nav 和搜索 | L1 / L2 / L3 / L4 / L5 / meta |
group | sidebar 分组，影响 sidebar 结构 | 各 layer 自定义 |
选填字段（5 个）
yaml
status: stub | draft | mature # 文档成熟度
confidence: ★★★★☆ # 1-5 星
source: 钱学森 IDDD Ch.2 # 内容来源
last_updated: 2026-06-22 # ISO 日期
related: # 反向链接
- /path/to/related-doc/
- /another/path/字段含义：
| 字段 | 用途 | 何时填 |
|---|---|---|
status | stub=待填 / draft=写了一半 / mature=实质完成 | 默认 stub，成熟后改 mature |
confidence | 内容置信度（用于评估可靠性） | 源典转述必填，AI 推断必填 |
source | 内容来源标注 | 引用源典或他人观点时必填 |
last_updated | 最后修改日期 | 修改后必填 |
related | 反向链接（其他文档引用这里） | 写完时填，2 条起步 |
字段命名约束
- 全部小写英文 +
-连字符（kebab-case） - 例：
status,last_updated,confidence - 不用驼峰、不用下划线单独分隔词
完整示例
Type B 概念页（成熟）：
yaml
---
title: 限界上下文
type: concept
layer: L1
group: strategic
status: mature
confidence: ★★★★★
source: Vernon IDDD Ch.2
last_updated: 2026-06-22
related: /l1-modeling/02-strategic/
---Type D stub：
yaml
---
title: 限界上下文
type: stub
layer: L1
group: strategic
status: stub
---怎么用
新建文档时：
- 先决定 Type → 选对应模板
- 复制模板的 frontmatter + 结构
- 改 title + 路径相关的 group/layer
修改现有文档时：
- 改 last_updated 字段
- 如果是 stub→mature，把 status 改了
常见误区
- 省略 type 字段——type 缺了就无法套用模板，导致结构混乱
- layer 写成 "第一层" 而不是 "L1"——layer 必须是英文代号
- related 字段填 0 条——每篇至少 2 条反向链接，否则 wiki 变成"孤岛"
关键洞察
frontmatter = 文档的身份证
标题、正文是"文档的肉体"，frontmatter 是"文档的身份"。身份不完整，机器就认不出你是谁、该用什么模板、该链给谁。