命令行 API 文档 Checklist

本文用于校验基于《命令行 API 文档模板》新建或整改的文档。提交文档前，应逐项确认。

编号	严重级别	校验条目	校验方法	失败处理建议
C01	ERROR	文件中不允许残留模板占位符 {{ ... }}。	全文检索 {{ 与 }}	将占位符替换为实际内容
C02	ERROR	文件中不允许残留模板注释（以 > **注释：** 开头的块引用中包含“将 xxx 替换为”“必填”“选填”等指导性文字）。	检索 > **注释：** 之后的指导性关键词	删除模板注释，或替换为正式说明
C03	WARN	[OPTIONAL] 前缀仅用于模板定义的可选章节；发布文档时已删除不适用的可选章节及前缀。	比对模板章节列表，检查保留章节的标题	删除不适用的 [OPTIONAL] 章节，保留的章节去掉前缀
C04	ERROR	文档标题中的命令名称与实际可执行命令一致。	比对标题与 --help 中的命令名	修正标题中的命令名称
C05	ERROR	“功能说明”已填写，准确描述命令的能力、适用场景和边界，非占位符或空。	检查章节内容是否为有效描述文本	补充或修正功能说明
C06	ERROR	“命令格式”给出完整的语法摘要，正确使用方括号（可选）和尖括号（需替换的值），未被表述为可直接复制的命令。	比对 --help 输出，检查括号使用	修正语法摘要，确保与 --help 一致
C07	ERROR	“参数列表”覆盖 --help 和实现代码中对用户开放的全部参数，无遗漏或多余项。	逐项比对 --help 输出与参数表	补齐缺失参数，删除不存在或内部参数
C08	ERROR	每个参数的名称、别名、类型、必选/可选状态、默认值与实现一致；布尔参数明确区分无值开关和显式值传入方式。	比对解析代码与参数表	修正不一致的字段
C09	WARN	“参数关系”已说明互斥、依赖、优先级等规则；没有参数关系时已明确填写“无”。	检查章节是否为空或仍为占位符	补充参数关系或填写“无”
C10	WARN	“引用的配置”仅在命令通过参数加载 YAML 配置或量化方案时保留；链接指向配置文档而非仅指向源码。	核对命令实现中是否存在配置加载逻辑	删除不适用章节，或修正链接目标
C11	WARN	“环境变量”仅在存在命令专属环境变量时保留；全局环境变量未重复说明；不包含真实凭据。	核对环境变量章节内容	删除不适用章节，或移除敏感信息
C12	WARN	“使用示例”存在时，第一条为最小可跑场景；示例使用大写 shell 变量代替具体值；不包含真实密钥或内部地址。	检查代码块中的变量命名和安全内容	精简示例参数，替换敏感值为变量
C13	WARN	“退出码与异常处理”保持轻量；未定义稳定退出码时仅说明 0/非 0 含义。	检查章节长度和退出码定义	精简或补充退出码说明
C14	ERROR	文档不包含密钥、令牌、内部地址、个人路径或其他敏感信息。	全文检索敏感关键词模式	移除敏感信息，替换为占位说明
C15	WARN	Markdown 表格、标题层级、代码块语言标记和换行渲染正确；内联文档链接有效。	渲染预览 + 逐链点检	修正格式错误或失效链接
C16	WARN	已识别相对上一稳定版本的破坏性变更（参数增删、默认值变化、行为变化等）。	与上一稳定版本 diff 比对	在文档中补充变更说明