提出方：Mukiik
最后更新：2026-11-01
适用范围
框架类文档用于让读者理解一个主题的核心概念、分类、边界及相互关系，并通过链接进入具体设计。
命名、存放位置、提出方和更新日期遵循策划文档规范。框架类文档使用本规范的章节结构，不套用具体设计的五章结构。
主题目录、入口导航及跨主题引用遵循文档存储与管理规范。
涉及字段、数值、完整交互流程和功能验收时，拆分为具体设计文档，并建立引用。
推荐结构
目的与范围
简要说明框架帮助读者理解什么，以及讨论边界。不要将尚未决定的内容写成既定规则。
核心关系图
以图为主体呈现主要概念及关系。按信息结构选择关系图、思维导图或其他合适形式，不强制使用某一种图。
- 图的布局应体现概念关系。例如两类实体的交互优先采用左右布局。
- 说明箭头、连线和交集的含义，区分交互方向与概念归属。
- 图中仅保留框架层信息，具体交互名称可以作为示例，不展开配置与数量规则。
- 可使用 Mermaid；需要精确布局时可使用 draw.io，并保留可编辑源文件及便于阅读的导出图。
概念与原则
用简短文字解释图中的术语、特殊情况和必要约束。图文保持一致，不重复展开整套流程。
少量例子可以放在相关概念旁，帮助理解即可，不单独凑“实际路径与示例”章节。
关联文档
提供继续阅读的入口，每个链接同时说明目标文档与当前框架的关系，例如上层框架、下层详细设计、依赖定义或相邻系统。
没有可引用的相关设计时可省略本节。不为填满章节而链接无关文件、重复本文路径，或创建空白文档。
尚未编写的专题如确有必要记录，另列“待补充专题”，写明需要解决的问题；不伪装成已有链接。
文档引用规则
- 使用标准 Markdown 链接：
[文档标题](相对路径.md)。路径相对于当前文档，使用/，保留.md扩展名。 - 在概念首次依赖其他文档时就近引用；集中导航放在“关联文档”。不要用代码格式包裹路径来代替可点击链接。
- 例如，从本规范引用现有框架：场景对象与物品关系框架。该文档是本规范的应用示例。
- 一个概念应有明确的定义来源。引用方用简短说明加链接，不复制整段规则以免维护时产生分歧。
- 详细设计应链接其所属框架；框架应链接重要的详细设计。只维护有阅读价值的导航，不要求手工列出所有引用者。
- 必须定位某一节时可使用标题锚点，并检查目标阅读器中的跳转效果；标题变更时同步修正引用。
- 移动、重命名文件或修改标题后检查相关链接。不要假定在编辑器外修改文件也会自动更新引用。
与 Obsidian 的配合
Obsidian 同时支持 [[文档名]] 和标准 Markdown 链接。本项目统一采用后者，保持跨工具可读性。Obsidian 可在“文件与链接”设置中关闭 Wikilinks，并选择相对于当前文件的链接路径。
反向链接可以查看哪些文档引用了当前文档，无需手工维护完整引用者清单。关系图谱展示文档之间的链接网络，不能替代框架正文中表达业务含义的关系图。
检查要点
- 读者能通过主图理解主要概念与关系，正文能解释特殊情况。
- 图文定义一致，已确认原则与待讨论内容清楚区分。
- 不包含只为套模板而存在的空章节，也不展开具体实现细节。
- 关联链接指向真实文件，并说明为什么需要阅读它们。