技术文档入口与编写规范

本组文档是墨台项目的技术事实库，服务对象包括后端、前端、AI、运维、测试和生态开发人员。文档以 muotai-backend、muotai-frontend、muotai-frontend-neo 的当前源码、配置、依赖和部署文件为基线；历史方案只作为背景资料，不替代当前实现。

文档分层

层级	内容	适用读者
架构与平台	服务边界、调用关系、公共基建和数据分层	架构师、后端、运维
AI 与业务	Agent、RAG、Skill、文件空间和业务服务	AI、业务后端、前端
API 与运维	对接契约、发布、监控、排障和恢复	前端、测试、SRE

事实优先级

同一主题出现多个来源时，按以下顺序判断：

1. 当前提交中的运行源码、Controller/DTO、配置类和资源文件；
2. 当前模块的 package.json、pom.xml、Dockerfile、Compose 和部署配置；
3. 当前 VitePress 文档中标注了源码路径和扫描日期的专题；
4. docs/modules/ 下的历史设计稿、修复记录和迁移材料。

如果高优先级来源之间存在冲突，文档必须保留冲突，标记“待确认”，写出影响范围、验证命令和关闭条件，不能选择一个值静默覆盖另一个值。

事实等级

• 源码事实：当前 Java、YAML、SQL、Compose 和 Dockerfile 可直接定位的行为。
• 部署约定：发布环境需要遵守的外部依赖、网络和密钥约束。
• 待确认项：代码、镜像或历史文档存在差异，发布前必须验证。

每篇专题至少应在开头给出：适用范围、源码基线、阅读对象、运行前提 和 状态。状态只使用以下词：当前实现、部署约定、历史资料、待确认。状态发生变化时应在更新日志或版本页登记。

推荐阅读顺序

1. 架构总览 和 服务地图
2. 本地开发 与 配置模型
3. AI 核心引擎 或对应业务服务
4. 接口基础约定 和 服务目录
5. 发布检查清单

完整写作、审阅和自动检查要求见文档编写与质量审计和文档质量审计记录。