msModelSlim 资料规范
本文档定义 msModelSlim 文档（
docs/）的资料规范，包括文档体系、目录结构、文档类型、编写要求、文档间导航关系与校验要求。 各文档类型的模板与校验清单是本文档的细则；模板占位符等编写细节见各模板，本文档不重复。
1. 概述
1.1 编写目的
统一 msModelSlim 资料的规划、编写与维护标准，使资料体系满足三个目标：
- 完整：覆盖知识、使用、接口、支撑、治理五类文档，无缺失。
- 可导航：从用户业务出发，通过链接可到达所有相关文档。
- 可连接：知识（词条）、流程（使用指南）、接口（API 文档）三类文档通过链接互相贯通。
1.2 适用范围
- 适用于
docs/下全部资料，以docs/zh/中文树为基准。 - 不适用：代码注释、commit message（见《编码规范》）。
1.3 读者对象
- 资料编写人员、资料评审人员、资料维护人员。
2. 文档体系
2.1 文档分层
docs/zh 资料分为五层：
| 层级 | 目录 | 定位 |
|---|---|---|
| 知识层 | knowledge_base/ |
陈述性知识：模型与结构、量化算法、调优策略、量化格式等 |
| 使用层 | user_guide/、best_practices/ |
过程性知识：业务流程指南、工具使用指南、案例等 |
| 接口层 | api_reference/ |
命令行文档、配置文档等API文档 |
| 支撑层 | install_guide/、quick_start/、support/（FAQ）、release_notes/、legal/ |
安装指南、快速入门、FAQ、版本与法律声明等 |
| 治理层 | contributing/ |
贡献指南、设计文档、开发规范、资料规范等 |
2.2 文档类型
模板体系内文档（5类），结构遵循对应模板，提交前按对应校验清单检查：
| 类型 | 定位 | 模板 | 校验清单 |
|---|---|---|---|
| 术语词条 | 陈述性知识：是什么 / 原理 / 性质 / 关联 | 《术语词条模板》 | 《术语词条校验清单》 |
| 流程指南 | 过程性知识：适用范围 / 输入交付件 / 操作步骤 | 《流程指南模板》 | 《流程指南校验清单》 |
| 案例参考 | 实践案例：背景 / 环境 / 步骤 / 结果 / 经验 | 《通用案例模板》 | 《通用案例校验清单》 |
| 量化配置文档 | 配置接口参考 | 《量化配置文档模板》 | 《量化配置文档校验清单》 |
| CLI文档 | 命令与接口契约 | 《命令行 API 文档模板》 | 《命令行 API 文档校验清单》 |
受众与详略：使用指南（流程指南）面向入门者，以详细步骤引导选择参数、填写配置并执行；API / 配置文档面向高阶用户快速检索查阅，仅需明确命令名、参数与取值等参考信息，不展开步骤讲解。
模板体系外文档：安装指南、快速入门、FAQ、版本说明、法律声明、各目录 README 等，不套模板，遵循第4.1节，并至少满足《公共校验清单》的 ERROR 条目（占位符残留、模板注释残留、敏感信息、标题）。
2.3 文档类型选择
根据待编写内容的性质与用途确定文档类型：
| 内容特征 | 文档类型 |
|---|---|
| 概念或算法的定义、原理与性质说明 | 术语词条 |
| 任务的操作步骤与执行流程说明 | 流程指南（含使用指南） |
| 实践活动的背景、过程、结果与经验记录 | 案例参考 |
| 配置类接口的字段、约束与取值说明 | 量化配置文档 |
| 命令或接口的名称、参数与调用约定 | CLI文档 |
| 无固定结构的辅助性说明 | 模板体系外文档 |
3. 目录结构
3.1 docs/zh 目录结构
docs/zh/
├── install_guide/ # 安装指南
├── quick_start/ # 快速入门
├── user_guide/ # 使用层：业务流程指南、工具使用指南、V0框架文档等
├── knowledge_base/ # 知识层：model、quantization_algorithms、quantization_format、tuning_strategies、ptq、parallel
├── api_reference/ # 接口层：config（配置）、python_api_v0（Python API）
├── best_practices/ # 案例与调优指南
├── support/ # FAQ
├── release_notes/ # 版本说明
├── legal/ # 法律声明
└── contributing/ # 治理层
├── contributing_guide.md # 贡献指南
├── design/ # 设计文档
└── development_guide/ # 技术文档
3.2 命名规范
- 目录名、文件名使用英文小写，单词间以下划线或连字符连接。
- 模板体系内文档的文件名遵循对应模板 / 校验清单的要求。
4. 编写要求
4.1 通用编写要求
面向全部文档。本节要求与《公共校验清单》的可校验条目对应，编写与校验时冲突以校验清单为准：
- 占位符：不残留模板占位符
{{ ... }}（对应《公共校验清单》CE-01）。 - 模板注释：不残留模板注释（以
> **注释：**开头、含“将 xxx 替换为”“必填”“选填”等指导性文字，对应 CE-02）。 - 标题：每个文档仅一个
#一级标题；标题层级##→###逐级递进，不跳级（对应 CE-04）。 - 语言与句式：面向用户的中文技术文档；首次出现缩写给出全称；句子成分完整、语义明确。
- 术语一致：同一概念全文使用同一名称，不与其他含义混用。
- 代码块：标注语言；命令与路径使用环境变量泛化（对应 CW-02）。
- 公式：LaTeX 语法，行内
$...$、块级$$...$$；公式中变量须在公式下方列表说明。 - 图片：放入文档同级
figures/目录，使用相对路径引用，并控制显示尺寸。 - 链接：内部链接使用相对路径，锚文本为
《目标文档标题》（书名号内为目标文档正式标题，非文件路径名；对应《公共校验清单》CE-05、CW-02）。 - 书名号：正文引用文档标题时以《》括起（对应《公共校验清单》CE-05）。
- 数字单位：数字与量词/单位间不留空格（对应《公共校验清单》CE-06）。
- 敏感信息：不得包含密钥、令牌、内网地址、个人路径（对应 CE-03）。
4.2 分类编写要求
各类型的章节结构、必填 / 选填要求见对应模板，校验要点见对应校验清单（见第6章），本文档不重复。
5. 文档导航
文档导航规定文档之间的链接关联方式，使知识（词条）、流程（使用指南）、接口（API 文档）三类文档通过链接互相贯通。导航关系分为两类：业务流程关系（5.1）与知识关联关系（5.2）。
5.1 业务流程图
业务流程图是一个嵌套图：每个节点都是流程文档，且业务作业流程本身也是一篇流程文档。所有流程文档均遵循《流程指南模板》。
规则
- 节点即流程文档：流程图的每个节点都是一篇流程文档——业务作业流程、子流程、工具使用流程——均遵循《流程指南模板》。
- 业务作业流程是一篇文档：业务作业流程是独立的流程指南文档，而非虚拟分组；其子节点是工具使用流程。
- 子流程以链接引用：业务作业流程通过「操作步骤」章节以超链接引用其工具使用流程（子流程）文档；工具使用流程同样遵循流程模板。
- 非流程内容不入图：术语（词条）、API / 配置文档、案例不属于流程图节点，由流程文档通过「术语」「接口文档列表」「案例列表」章节（见《流程指南模板》）以链接形式引用。
- 链接必须可解析：流程图中每个节点的链接指向仓库内真实存在的流程文档；规划中尚未发布的子流程不放入流程图。
5.2 知识图谱
词条是知识图谱的节点，通过链接互相连接：
- 每个词条在
## 关联词条中以超链接列出相关词条，并标注关系类型。 - 每个词条在
## 关联流程中链接到相关流程 / 使用指南。 - 词条按所属类别组织；关系类型与分类取值见《术语词条模板》。
- 一致性要求：每个词条至少被其他1个词条反向引用（入度 ≥1），整体构成弱连通图；词条间不得孤立。链接必须可解析，规划中尚未创建的词条不放入知识图谱。
- 与业务流程图的衔接：词条是知识节点，流程 / 使用指南是使用节点，API 文档是接口节点；业务流程图横向串联它们，知识图谱纵向连接词条，两者互为补充。
6. 校验要求
6.1 校验依据
文档类型与校验清单的对应关系见第2.2节。编写前先读对应模板，提交前按对应校验清单逐项校验。
6.2 校验结论
- 校验清单条目分为必须满足与建议满足两类，级别定义见各校验清单。
- 任一必须满足条目未通过，文档校验不通过，须修复后重新校验，通过后方可提交。
- 仅建议满足条目未通过时，不阻塞提交，但须在评审中说明。
6.3 豁免机制
确有合理原因无法满足某条目时，可在文档顶部声明豁免（<!-- waiver: 编号 原因：xxx -->）；豁免不得用于规避 ERROR 条目超过2项，WARN 条目不设豁免数量限制。
7. 文档生命周期
- 新增：按第2.3节确定文档类型 → 套用对应模板 → 填写内容 → 按校验清单校验至通过。
- 变更：涉及功能 / 配置 / 接口变化时同步更新文档；变更后按校验清单复查。
- 废弃 / 下线：功能下线时在版本说明中声明，并处理指向该文档的链接（链接到替代文档或删除）。
8. 规范维护
- 同步演进：新增或调整模板时，须同步更新对应校验清单；本规范的文档类型表与目录结构同步维护。
- 评审：规范变更须经 SIG 评审 通过后合入，并记录变更原因。
- 例外：例外情况通过豁免机制记录（见第6.3节），在 SIG 评审中复核。
8.1 修订记录
| 日期 | 版本 | 变更说明 |
|---|---|---|
| 2026-08-05 | v1.0 | 首次发布。 |
| 2026-08-07 | v1.1 | 词条文档类型更名为「术语词条」，模板与校验清单文件更名 term_glossary；正文书名号与失效示例修正。 |
| 2026-08-12 | v1.2 | 书名号标题引用补链接（《流程指南模板》《术语词条模板》《公共校验清单》），与 CE-05/CW-02 对齐。 |
| 2026-08-12 | v1.3 | 书名号锚文本统一为《标题》形式，CE-05 示例收敛为单一规范形式。 |