文档撰写约定

状态：本文档已被 meta/writing-style 取代。请前往新范式查看 4 个 Type、frontmatter schema、视觉规范等。

历史

本文档是 2026-06-22 项目初始化时写的第一版"文档约定"，定义了：

• 文件命名（小写英文 + 连字符）
• frontmatter（title、status 等）
• 文档结构模板（"它是什么 / 关键属性 / 怎么用 / 误区 / 相关链接"）
• 视觉约束（表格优先、mermaid 优先、置信度标注等）
• 禁用项（不写"什么不是"、不写大段引用等）
• 交叉链接（每篇末尾"相关链接"至少 3 条）

随着 Phase 1 蒸馏完成和 4 篇方法论 + 5 个 L 概览的实际撰写，发现本文档有几个不足：

1. 没有 Type 分类——所有文档都套同一模板，导致概览页和概念页结构雷同
2. frontmatter 不够机器可读——缺 type、layer、group 必填字段
3. 没有"双轨 frontmatter"兼容——stub 文档要不要 frontmatter 没规定

升级方案：见 meta/writing-style/，包含 4 个 Type + 完整 frontmatter schema + 视觉规范。

仍然有效的内容

下面这些规范未被新范式取代，仍然适用：

• 不用 emoji 装饰正文（sidebar 的 emoji 已经是装饰）
• 中文为主，专有名词保留英文
• 跨 L 层引用要谨慎：L1 → L2 是"输出关系"，L2 → L1 是"输入关系"

相关链接

• meta/writing-style/（新范式，取代本文档）
• 首页
• meta/evolution-log/（本次升级记录）