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类），结构遵循对应模板，提交前按对应校验清单检查：

类型	定位	模板	校验清单
算法词条	陈述性知识：是什么 / 原理 / 性质 / 关联	01_quantization_glossary_template	01_quantization_glossary_checklist
流程指南	过程性知识：适用范围 / 输入交付件 / 操作步骤	02_process_guide_template	02_process_guide_checklist
案例参考	实践案例：背景 / 环境 / 步骤 / 结果 / 经验	03_general_case_template	03_general_case_checklist
量化配置文档	配置接口参考	04_quantization_config_document_template	04_quantization_config_document_checklist
CLI文档	命令与接口契约	05_cli_api_contract_template	05_cli_api_contract_checklist

受众与详略：使用指南（流程指南）面向入门者，以详细步骤引导选择参数、填写配置并执行；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/ 目录，使用相对路径引用，并控制显示尺寸。
• 链接：内部链接使用相对路径，锚文本使用目标文档标题（对应 CW-02）。
• 书名号：正文引用文档标题时以《》括起（对应《公共校验清单》CE-05）。
• 数字单位：数字与量词/单位间不留空格（对应《公共校验清单》CE-06）。
• 敏感信息：不得包含密钥、令牌、内网地址、个人路径（对应 CE-03）。

4.2 分类编写要求

各类型的章节结构、必填 / 选填要求见对应模板，校验要点见对应校验清单（见第6章），本文档不重复。

5. 文档导航

文档导航规定文档之间的链接关联方式，使知识（词条）、流程（使用指南）、接口（API 文档）三类文档通过链接互相贯通。导航关系分为两类：业务流程关系（5.1）与知识关联关系（5.2）。

5.1 业务流程图

业务流程图是一个嵌套图：每个节点都是流程文档，且业务作业流程本身也是一篇流程文档。所有流程文档均遵循《流程指南模板》。

规则

1. 节点即流程文档：流程图的每个节点都是一篇流程文档——业务作业流程、子流程、工具使用流程——均遵循流程指南模板。
2. 业务作业流程是一篇文档：业务作业流程是独立的流程指南文档，而非虚拟分组；其子节点是工具使用流程。
3. 子流程以链接引用：业务作业流程通过「操作步骤」章节以超链接引用其工具使用流程（子流程）文档；工具使用流程同样遵循流程模板。
4. 非流程内容不入图：术语（词条）、API / 配置文档、案例不属于流程图节点，由流程文档通过「术语」「接口文档列表」「案例列表」章节（见流程指南模板）以链接形式引用。
5. 链接必须可解析：流程图中每个节点的链接指向仓库内真实存在的流程文档；规划中尚未发布的子流程不放入流程图。

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	首次发布。