文档开发规范

本规范面向所有文档贡献者，确保文档集的长期可维护性和一致性。

---

纲领一：信息不重复

每条信息只在一处文档中详细描述，其他文档通过超链接引用。这样修改时只需改一处，不会出现多处不一致。

• platform-overview.md 只做跨项目的全局描述，各项目细节链接到对应子目录
• 各项目 intro.md 只做概要级别描述，深入内容链接到对应的专题文档
• 如果发现两篇文档有重复段落，请将详细内容保留在更专题的那篇，另一篇改为链接

纲领二：不内联复杂代码

代码是高速变化的产物，文档中不内联具体的代码片段，避免文档与代码不同步。

• 可以写：高度抽象的伪代码或极简示意，用于解释设计思路和技术原理
• 可以写：文件路径、类名/函数名作为导航索引，用超链接指向源文件
• 不要写：多行真实代码块、具体的函数实现、带行号的代码引用
• 原则：文档讲「是什么 / 为什么 / 怎么设计的」，代码讲「怎么实现的」。读者看完文档后知道去哪个文件读代码即可

纲领三：文档结构约定

• 每个子目录（backend/、frontend/、metagpt/、engineering/）对应一个项目或领域
• 每个子目录的 intro.md 是该领域的入口文档
• 深度技术专题放在 tech-deep-dive/ 子目录下
• 新增文档后须同步更新 .vitepress/config.mts 中的 sidebar 配置和 navigation.md 中的导航表

纲领四：写作风格

• 使用中文撰写，专有名词保留英文原文（如 MetaGPT、Socket.IO、gRPC）
• 标题层级从 #（h1）开始，每篇文档只有一个 h1
• 善用 Mermaid 图表来描述架构和流程，避免纯文字描述复杂交互
• 表格适合做对照和索引，流程适合用有序列表或 Mermaid 时序图