Skip to content

基础文档政策

文档属性 值
版本 0.1
日期 2026-03-22
状态 Current canonical
关联文档 文档导航首页, 01-product-scope.md

1. 目的

本文档定义 Gaia 基础文档应如何编写、更新、拆分和废止。

其目标是解决两个反复出现的问题：

  • 新旧设计混入同一文件
  • 文档层次混乱，导致高层文档过于详细，低层文档不够精确

本政策是本仓库中文档结构的规范性规则集。

2. 核心原则

2.1 一个文档，一个主要职责

一个文档不应同时充当：

  • 当前规范性规格
  • 目标设计提案
  • 实现笔记
  • 历史记录

如果一个文件试图承担多个职责，请拆分它。

2.2 一个概念，一个规范性归属

一个概念可以在多个文档中被提及，但它应只有一个定义它的规范性位置。

示例：

  • 科学对象类别属于本体论文档
  • 编写包语法属于语言规格
  • 结构图形状属于 Gaia IR
  • 包审查/策展工作流属于审查文档

其他文档应引用规范性归属，而非悄悄重新定义它。

2.3 当前、目标和历史必须分离

不要将时间线混淆编码到单一叙事中。

  • Current canonical 文档描述当前的信息源
  • Target design 文档描述预期的目标状态
  • Transitional 文档显式地将当前运行时与目标语义分开
  • 退役或历史材料属于归档/规格历史，不属于规范性文档

2.4 产品文档和参考文档需要不同的精细度

一些文档应引导读者。另一些应精确指定结构。

不要强迫一个文档同时做这两件事。

3. 文档维度

Gaia 基础文档应沿三个维度分类：

  • Level：文档运作在什么精细度
  • Status：它是 current canonical、target design 还是 transitional
  • Scope：它是仓库级、子系统级还是组件级

最重要的规则是保持这些维度分离。项目规模扩大时通常应扩展范围，而非发明更多层次。

4. 层次

Gaia 基础文档应归入以下四个主要层次之一。

概述

回答：

  • Gaia 是什么
  • Gaia 不是什么
  • 产品面向谁
  • 产品边界是什么

不应包含：

  • 逐字段的 schema
  • 当前运行时变通方案的细节
  • 低层存储或 BP 的具体实现

示例：

  • 01-product-scope.md

基础

回答：

  • 存在哪些类型的对象
  • 哪些对象具有真值性
  • 哪些对象进入 BP
  • 哪些区分是本体论层面的 vs 仅工作流层面的

不应包含：

  • API 细节
  • 存储表
  • 命令调用机制

示例：

  • theory/06-factor-graphs.md
  • theory/theoretical-foundation.md

架构

回答：

  • 子系统负责什么
  • 子系统不负责什么
  • 制品如何在子系统之间流转
  • 相邻服务/层之间的边界是什么

不应包含：

  • 完整的字段参考表
  • 低层实现细节，除非明确标记为 transitional

示例：

  • system-overview.md
  • review/service-boundaries.md
  • ecosystem/02-decentralized-architecture.md

规格

回答：

  • 包 / IR / schema / 命令合约的确切形状
  • 字段含义
  • 不变量
  • 允许和不允许的情况

应足够精确，使实现者能将其用作参考。

示例：

  • language/gaia-language-spec.md
  • gaia-ir.md
  • cli/registration.md
  • cli/command-lifecycle.md

5. 范围

每个重要文档还应有明确的范围。

推荐值：

  • Repo-wide
  • Subsystem
  • Component

当 Gaia 增长时，这个维度通常承担扩展工作。例如：

  • 01-product-scope.md 是 Repo-wide
  • foundations/cli/workflow.md 是 Subsystem
  • 未来的存储摄取设计文档可能是 Component

6. 状态标签

每个重要的基础文档应有明确的状态。

推荐值：

  • Current canonical
  • Target design
  • Transitional

如果一个文件无法清楚地陈述其状态，它可能在混合角色。

Transitional 文档

一些文档需要同时描述当前实现和预期目标。

这些文档应保持上述四个主要层次之一，但设置 Status: Transitional。

典型示例：

  • bp-on-graph-ir.md

历史文档

历史或 ADR 风格的文档不应充当当前语义的主要信息源。

它们通常应优先通过位置处理，而非活跃状态标签：

  • docs/archive/ 用于归档的历史文档
  • docs/specs/ 用于带日期的提案和设计记录

默认情况下，退役文档应完全离开 docs/foundations/。如果旧路径必须因兼容性保留，只保留一个简短的重定向说明，而非在活跃规范性区域维护一长段历史正文。

示例：

  • docs/specs/ 中的带时间戳的规格
  • 归档的历史文档

7. 受众与超出范围

对于主要文档，应明确陈述：

  • 目标受众
  • 文档定义什么
  • 文档不定义什么

这防止抽象文档漂移到低层细节，也防止低层文档因理论而膨胀。

8. 更新决策规则

变更文档时，首先分类工作类型：

8.1 澄清

适用条件：

  • 语义未变
  • 文档已是正确的规范性归属
  • 仅改善措辞或示例

操作：

  • 编辑现有规范性文档

8.2 替换

适用条件：

  • 文档的核心职责已变
  • 本体论或合约已发生实质性变化
  • 保留旧正文会保存误导性的概念结构

操作：

  • 编写新的或大幅重写的规范性文档
  • 将旧文档从活跃规范性区域退役
  • 将历史内容移至 docs/archive/，或如果该历史仍有用则保留在带日期的规格中
  • 仅在兼容性值得认知成本时保留精简的重定向
  • 更新 README / 相关文档链接

8.3 提案

适用条件：

  • 设计尚未被接受
  • 实现有意尚未对齐
  • 目的是探索或决策

操作：

  • 在规范性流程之外编写规格 / ADR / 提案文档
  • 不要悄悄将提案文本变成当前规范性语言

9. 何时拆分文档

当以下一个或多个条件为真时拆分文档：

  • 当前运行时和目标设计已明显分歧
  • 文档的大约三分之一以上需要重写以保持准确性
  • 文件同时服务于多个层次
  • 一个概念在多个地方被规范性定义

典型拆分模式：

  • 当前运行时参考 vs 目标设计
  • 基础 vs 规格
  • 服务边界 vs 工作流细节
  • 规范性文档 vs 归档历史文档

10. 退役旧文档

当一个文档不再是正确的信息源时：

  1. 将其移出活跃规范性区域
  2. 明确指向其替代文档
  3. 在有用时将历史保存在 docs/archive/ 或带日期的规格中
  4. 仅对特别稳定或高流量的路径保留兼容性重定向
  5. 更新主要索引和相关文档章节

不要继续编辑一个已退役的概念模型，好像它仍然是活跃的。

11. 必要的伴随更新

当规范性基础文档被添加、替换或实质性重新界定范围时，也应更新相关索引页和指针。

典型伴随文件：

  • docs/README.md
  • docs/foundations/README.md
  • docs/foundations/README.zh-CN.md
  • 相邻规范性文档中的相关文档标题
  • 受变更影响的任何归档或兼容性重定向页面

12. 变更控制

部分基础层作为跨子系统的结构契约，变更影响范围大，需要显式审查。

层 保护级别 变更流程
theory/ 冻结 不应变更（外部定义）
gaia-ir/ 受保护 需要独立 PR + 负责人显式批准
ecosystem/ 受保护 语义变更需审查；措辞澄清可直接编辑
其他层 正常 遵循标准 PR 流程

受保护层的变更流程：

  1. 先以独立文档或 issue 形式提出变更提案
  2. 获得负责人显式批准后方可编辑规范性文件
  3. 以独立 PR 提交——不得与实现变更混合
  4. 合并后验证所有下游引用（bp/、cli/）仍然一致（LKM 文档在 gaia-lkm 仓库维护）

AI Agent 特别规则：

  • Agent 禁止直接修改 theory/ 和 gaia-ir/ 下的文件
  • 如需调整，必须停下来与用户沟通，说明当前定义、变更原因和提议内容

13. Gaia 特定的边界规则

以下在本仓库中尤为重要：

  1. 本体论不是语言语法。 对象类别属于本体论文档；表面声明属于语言文档。

  2. 语言、Gaia IR 和 BP 是不同的层。 一个术语不应在这些层之间悄悄改变含义。

  3. 审查和策展是不同的服务。 提交裁决属于 ReviewService；注册中心级的离线维护属于 CurationService。

  4. 正式的外部提交优先使用 Gaia 包。 包配置语义属于审查/工作流文档，不属于临时侧注。

  5. 只有封闭的、具有真值的科学断言是普通领域 BP 的参与者。 工作流制品、开放问题和内部策展输出默认不是普通领域 BP 变量。

14. 实用写作测试

测试 A：此文档是否过于粗略？

阅读后，读者能否用几句话回答：

  • 这个子系统用于什么
  • 它不用于什么
  • 它的边界在哪里

如果不能，文档可能过于纠缠于细节。

测试 B：此文档是否过于模糊？

阅读后，实现者能否回答：

  • 允许哪些字段/对象/接口
  • 什么是禁止的
  • 边界情况下会发生什么

如果不能，文档可能尚未成为真正的规格/参考。

15. 当前工作规则

在进行非琐碎的基础文档变更之前：

  1. 识别文档的层次
  2. 识别其状态
  3. 在相关时识别其范围
  4. 决定变更是澄清、替换还是提案
  5. 在同一分支中更新伴随索引和重定向

如果跳过此流程，文档漂移是默认结果。