文档编写与质量审计

本文是技术文档的强制写作规范。它适用于 docs/technical/ 下的架构、API、部署、AI、前端、数据和业务专题，也适用于从 docs/modules/ 迁移到正式入口的历史资料。

1. 文档最小结构

每篇长期维护的技术文档至少包含以下部分，按主题可以合并，但不能完全省略：

# 标题

> 状态：当前实现｜部署约定｜历史资料｜待确认
> 源码基线：仓库、模块、提交或扫描日期
> 适用范围：服务、页面、接口或运行场景
> 阅读对象：后端、前端、测试、SRE 或产品实施

## 1. 目的与边界
## 2. 源码与配置入口
## 3. 主流程或数据模型
## 4. 接口、配置和状态表
## 5. 失败、重试、幂等和恢复
## 6. 权限、安全和多租户边界
## 7. 验证命令与验收场景
## 8. 已知限制、差异和后续工作

部署专题必须补充依赖服务、启动顺序、持久化、探针、回滚和灾备；API 专题必须补充方法、路径、认证、请求/响应、错误码、幂等、流式媒体类型和兼容窗口；异步任务必须补充业务 ID、状态机、终态和刷新后的恢复方式。

2. 源码引用规则

类名、方法、配置键、环境变量和路径都必须能够在源码中定位。推荐格式：

类型	推荐写法
后端类	muotai-ai-biz/.../AiChatbotAgentController.java
前端文件	muotai-frontend-neo/src/lib/sse/runStatusSse.ts
配置	agent.session.persistence.enabled，同时注明配置类或 YAML 文件
API	POST /ai/v1/chatbot/{agentId}/general-chat，注明网关前缀是否参与
外部服务	服务名、调用方式、超时、失败策略和租户透传要求

源码事实应优先于注释、README 和历史设计稿。不能只写“系统会自动处理”，必须说明入口、状态写入、异步边界和失败补偿。

3. 事实、建议和历史的分层

• 事实：当前代码能定位并可通过命令或请求复现的行为；
• 约定：部署、运维或团队要求，即使不由代码强制，也要写明责任人和验证方式；
• 建议：改进方向，使用“建议”“应当”“可以考虑”等措辞；
• 历史：旧端口、旧包名、废弃接口或设计稿，必须放入历史/迁移章节；
• 待确认：存在冲突或无法在当前环境验证，必须记录影响和关闭条件。

不要把“计划支持”“设计上可以”“README 描述”写成“当前已支持”。

4. 表格和时序图要求

接口、配置、状态机和服务清单优先使用表格，至少包含来源、默认值/状态、失败处理和验证方式。时序图必须标出：调用方、认证边界、异步队列、持久化点、事件/回调和终态；不能只画成功路径。

状态机要明确初始态、可达迁移、终态、重复请求和过期事件处理。对于 SSE、MQ、Webhook 和轮询，要明确连接断开是否影响业务执行，以及客户端恢复依赖历史、快照、事件序号还是人工重试。

5. 安全和数据边界

文档不得写入真实密码、Token、模型 Key、私有 IP、生产对象键或真实用户数据。示例统一使用 <token>、<tenant-id>、<session-id> 等占位符。涉及文件、Markdown、HTML、工具、Skill、RAG 或外部网页时，要说明不可信输入、ACL、路径校验、下载签名和日志脱敏边界。

6. 变更同步规则

代码或配置变化后，按影响范围同步更新：

1. 专题正文；
2. 所属目录 index.md；
3. API、配置、服务或端口索引；
4. 侧边栏和导航；
5. docs/technical/changelog.md 或版本状态页。

删除接口、修改状态词、变更默认端口、改变 SSE 事件或迁移数据结构时，必须写兼容窗口、回滚方式和旧客户端行为。

7. 提交前审计

npm ci
npm run docs:check
npm run docs:build
git diff --check

此外应检查：

• 新增相对链接和侧边栏链接都能解析；
• 每个文件只有一个 H1，标题层级不跳级；
• 示例代码可执行或明确标记为伪代码；
• 端口、版本、状态词和接口路径与源码一致；
• Mermaid、表格、代码围栏和中文文件名能正常渲染；
• 构建警告已区分为可接受提示或必须修复的问题。

docs:check 是仓库提供的无额外依赖检查脚本；它会忽略代码围栏，避免把 DSL、JSON 或 shell 示例中的括号误判为 Markdown 链接。

当前审计记录见文档质量审计记录。