MDBX RFC 结构与文档约定

版本：MDBX-1-DRAFT

本文用于把当前 docs/ 升级为更正式的 RFC 风格结构，便于后续长期维护、版本冻结、第三方实现和低端模型执行。

1. 目的

这份文档规定：

• 哪些文档属于规范性文档
• 哪些文档属于实现指导文档
• 每份文档应使用什么风格
• 版本升级时如何保持兼容性
• 低端模型在阅读和执行时应如何使用整套 spec

2. 文档分层

2.1 核心规范层

以下文档属于核心规范层，具有最高约束力：

• 00-agent-rules.zh-CN.md
• 01-product-spec.zh-CN.md
• 02-storage-sync-spec.zh-CN.md
• 03-security-spec.zh-CN.md
• 04-roadmap-acceptance.zh-CN.md
• 05-rfc-structure.zh-CN.md

核心规范层定义：

• 术语
• 不变量
• 架构边界
• 安全和兼容要求
• MVP 边界
• 拒收规则

如果实现与核心规范层冲突，以核心规范层为准。

2.2 实现指导层

以下文档属于实现指导层：

• 06-sqlite-schema-v1.zh-CN.md
• 07-low-end-model-task-breakdown.zh-CN.md
• 08-implementation-completion-plan.zh-CN.md
• 11-monica-pass-cli-development.zh-CN.md

实现指导层定义：

• 推荐表结构
• 任务拆解方式
• 当前实现完成计划
• CLI 与客户端接入策略

如果实现指导层与核心规范层冲突，必须修改实现指导层，而不是修改核心规范层。

2.3 状态总结层

状态总结层可由后续文档继续补充。

状态总结层用于说明：

• 当前完成度
• 当前风险
• 当前可执行任务
• 当前不建议做的事

3. 文档规范性等级

MDBX 文档使用三种等级：

• 规范性

  • 直接约束实现

• 指导性

  • 强烈建议，但在不违背规范的前提下可以调整

• 说明性

  • 用于解释背景、动机、状态，不直接定义行为

推荐对应关系：

• 00 到 05 主要是规范性
• 06 到 09 主要是指导性
• 10 主要是说明性

4. 每份 RFC 风格文档必须包含的要素

核心规范文档最好包含：

• 标题
• 版本号
• 文档目的
• 规范性关键词说明
• 明确章节结构
• 核心定义
• 必须行为
• 禁止行为
• 拒收规则

实现指导文档最好包含：

• 文档范围
• 输入前提
• 设计建议
• 约束条件
• 样例结构
• 验收条件

5. 关键词约定

以下关键词按 RFC 风格理解：

• MUST
• MUST NOT
• SHOULD
• SHOULD NOT
• MAY

如果某条规则会影响：

• 数据兼容性
• 安全性
• 恢复能力
• 同步语义
• project 主模型
• attachment 一等能力

那么它应优先写成 MUST 或 MUST NOT。

6. 编号约定

文档编号含义如下：

• 00
  • 执行规则
• 01
  • 产品规范
• 02
  • 存储与同步规范
• 03
  • 安全规范
• 04
  • 路线图与验收规范
• 05
  • RFC 结构和文档治理
• 06
  • SQLite 初版 schema
• 07
  • 低端模型任务拆解
• 08
  • 当前实现完成计划
• 09
  • 预留：Tiga 参数表或其他实现指导
• 10
  • 预留：状态总结
• 11
  • Monica Pass CLI 开发与接入说明

后续新增文档时：

• 12 以后可继续扩展
• 文件名必须稳定
• 编号一旦发布，最好不要重新洗牌

7. 兼容性治理规则

MDBX 的文档修订必须遵守以下规则：

• 不得在无迁移说明的情况下破坏旧数据可读性
• 不得把 project 降级成可选结构
• 不得把 attachment 降级成非原生结构
• 不得让新版本依赖服务器才能解释旧数据
• 不得用不透明实现细节替代规范文本

8. 规范更新流程

推荐更新流程：

1. 先确认变更影响的是哪一层文档
2. 先修改核心规范，再修改实现指导
3. 如影响兼容性，必须补迁移说明
4. 如影响安全参数，必须同步更新 03-security-spec*.md，必要时再补独立 Tiga 参数表
5. 如影响导入器，必须同步更新实现完成计划或新增 KDBX 映射表
6. 如影响开发顺序，必须同步更新任务拆解与状态总结

9. 低端模型执行顺序

低端模型执行任务时必须按以下顺序：

1. 读 00 到 05
2. 识别当前任务属于 06 以后哪一类
3. 先实现核心数据结构
4. 再实现读写路径
5. 再实现测试
6. 最后才实现 UI 或外围能力

10. 拒收规则

以下情况说明文档体系不够正式或不合格：

• 规范和建议混在一起，读者无法判断约束等级
• 文档没有说明哪部分是 source of truth
• 关键行为只存在于任务说明，不存在于规范文本
• 编号混乱，后续维护者无法定位主规范
• 安全、兼容、同步语义没有固定到规范层