MBE 文档治理与结构规范

版本: v2.0
生效日期: 2026-02-11
适用范围: Mises 全仓库（docs/、mises-behavior-engine/docs/、mbe-desktop/docs/）

一、文档目录总览

1.1 三级目录定位

1.2 目录结构标准

docs/（Mises 根）

docs/
├── README.md                    # 文档中心索引（入口）
├── DOCS_GOVERNANCE_AND_STRUCTURE.md  # 本文件：治理规范
├── business/                    # 商业计划
├── features/                    # 功能文档
├── guides/                      # 使用指南
├── reference/                   # 快速参考
├── workflows/                   # 工作流
├── archive/                     # 归档（见第四章）
│   ├── cli-optimization/
│   ├── client-plans/
│   ├── completed-plans/
│   ├── dev-analysis/
│   ├── dev-logs/
│   ├── graph-implementation/
│   └── update-summaries/
└── (其他长期文档 *.md)

mises-behavior-engine/docs/（引擎）

mises-behavior-engine/docs/
├── Readme.md                    # 引擎文档中心索引
├── GETTING_STARTED.md           # 统一入门指南
├── VERSIONS.md                  # 版本对照表
├── architecture/                # 技术架构设计
├── product/                     # 产品文档（能力说明、路线图、System Card）
│   ├── business/                # 投资人材料
│   └── comparison/              # 竞品对比
├── developer/                   # 开发者文档（API Reference、Agent 框架、Tool 指南）
├── guides/                      # 操作指南（入门、评估方法论、Prompt 工程、安全合规）
├── cookbook/                     # 可复现示例（5 篇）
├── en/                          # 英文国际化文档
├── business/                    # 定价与计费
├── legal/                       # 法律合规（隐私政策）
├── reference/                   # 术语表等参考
├── deployment/                  # 部署指南
├── testing/                     # 生产级测试指南
├── workflows/                   # 引擎工作流
├── xiaozhi/                     # 小智集成
├── archive/                     # 归档
└── (其他子目录)

mbe-desktop/docs/（Desktop）

mbe-desktop/docs/
├── domain-applications/         # 领域应用文档
│   ├── capability/              # 能力方法应用
│   ├── industry/                # 行业应用
│   │   ├── legal/
│   │   ├── finance/
│   │   └── marketing/
│   └── integration/             # 集成对接
├── archive/                     # 归档
└── (其他生产文档 *.md)

二、文档分类体系

2.1 生命周期分类

2.2 判断规则：保留 vs 归档

保留（生产目录）的文档必须满足：

1. 仍有读者参考价值（用户、开发者、运维人员）
2. 内容反映当前系统状态（非历史快照）
3. 不是一次性的调试/修复/实施记录

应当归档的文档：

1. 标题或内容包含具体日期（如 *_20260202.md）——属于历史快照
2. 标题包含 FIX_、_DEBUG、_DIAGNOSIS、_COMPLETE——属于一次性开发记录
3. PHASE*_TEST_REPORT、*_API_CHECK——属于阶段性测试报告
4. 已完成的优化计划/改进计划——核心内容已融入生产文档
5. 实现状态跟踪文档——功能已上线，状态无需继续跟踪

三、文档命名与版本规范

3.1 命名约定

3.2 版本号规范

每个生产文档应在页眉或页脚包含：

**文档版本**: vX.Y  
**更新日期**: YYYY-MM-DD

• 版本号应与系统版本保持一致（当前 v3.1.0）
• 内容更新时必须同步更新版本号和日期
• 索引文件（README.md）使用独立版本号

3.3 内链规范

1. 引用生产文档：使用相对路径 ./ 或 ../
2. 引用归档文档：路径必须包含 archive/，并在链接说明中标注「已归档」
3. 禁止：引用不存在的文件、使用绝对路径
4. 移动文件后必须全局搜索更新所有引用

四、归档体系

4.1 归档目录结构

每个 docs 目录下的 archive/ 按内容类别组织：

4.2 归档操作规范

# 归档单个文件
Move-Item "docs/OLD_FILE.md" "docs/archive/分类/" -Force

# 归档后必须：
# 1. 全局搜索并更新引用该文件的所有链接
# 2. 重建文档站点验证无断链：npm run docs:build

4.3 归档统计（截至 2026-02-11）

五、文档站点构建

5.1 构建方式

# 在 Mises 根目录执行
npm run docs:build

构建脚本 scripts/build-unified-docs-site.js 扫描四个目录：

• docs/
• mbe-desktop/docs/
• mises-behavior-engine/docs/
• mbe-monorepo/docs/

产出到 docs-site/，包含 overview.html（总览）和 index.html（索引）。

5.2 构建时机

5.3 .gitignore 建议

# 文档站点生成物
docs-site/*.html
docs-site/pages/
docs-site/style.css
docs-site/app.js

六、文档新增流程

6.1 新增生产文档

1. 确定归属目录：根据第一章定位判断放入哪个 docs 目录
2. 选择子目录：参照 1.2 目录结构标准
3. 命名规范：遵循第三章命名约定
4. 添加版本信息：页眉/页脚注明版本号和日期
5. 更新索引：在对应 README.md 中添加条目
6. 重建站点：npm run docs:build

6.2 新增开发/调试文档

开发过程中产生的临时文档（修复记录、调试日志、阶段报告）：

1. 可临时存放在对应 docs 目录
2. 开发完成后立即归档到 archive/对应分类/
3. 不应在生产目录中长期保留

6.3 文档更新检查清单

每次发布新版本时，检查以下文档是否需要同步更新：

• MBE_ROADMAP.md — 路线图版本号和完成状态
• MBE_CAPABILITIES.md — 能力说明是否覆盖新功能
• MBE_PRODUCT_INTRO.md — 产品介绍是否反映最新架构
• MBE_BUSINESS_FLOW.md — 业务流程是否有变化
• MBE_COMPLETE_SYSTEM_ARCHITECTURE.md — 架构文档版本号
• GETTING_STARTED.md / en/GETTING_STARTED.md — 入门指南
• API_COMPLETE_REFERENCE.md / en/API_REFERENCE.md — API 文档
• docs/README.md — 文档中心索引
• VERSIONS.md — 版本对照表
• llms.txt — AI 可读文档索引

七、发布审查流程

7.1 审查清单

7.2 定期维护建议

八、变更日志

文档版本: v2.0
更新日期: 2026-02-11