用途:判断一套文档是否覆盖了它应当覆盖的内容。做法是先建立“应存在”的文档清单,再与已有文档比对,最终产出一份按优先级排序的缺口报告,而不是新的文档。
主要能力:四阶段工作流——阶段1盘点,阶段2映射,阶段3按受众影响分类打分,阶段4产出缺口报告。盘点来源包括:公共代码表面(内置 scripts/inventory.py 可提取六类信息:env_vars 环境变量、cli_commands 命令与标志、config_keys 配置键、http_endpoints 路由、public_exports 公共导出、error_types 自定义错误类型)、面向用户的功能(TUI 界面、CLI 工作流、集成点、认证流程等)、运维表面(安装、升级迁移、备份恢复、故障排查等)、现有文档中的交叉引用缺口(失效链接、Coming soon、目录缺页),以及通过子代理推断的架构/运维/迁移类隐式主题。映射阶段先做批量 grep 建立候选匹配,再对每个候选文档文件派发子代理判定为 Documented、Shallow、Misplaced 或无真实匹配。缺口按 P0–P4 优先级并结合受众权重(新用户1.5x、日常用户1.0x、高级用户/贡献者0.8x、内部运维0.7x)排序。
使用方式:调用内置盘点脚本,例如 python3 skills/doc-completeness-audit/scripts/inventory.py --root . --json > inventory.json(亦支持人类可读输出及 --detectors env_vars,cli_commands 指定检测器),随后按阶段推进并产出报告。报告含摘要、按受众的覆盖率表、P0–P4 缺口表、浅覆盖详情、位置不当文档表以及已覆盖主题清单,并可将缺口整改分派给对应文档技能。
适用场景:功能上线后核查、发布前检查公开 API/CLI 标志/配置项、用户反馈找不到文档时、定期文档覆盖健康检查。
限制:不生成新文档;不审计归档目录(如 docs/archive/);不应为内部实现细节要求文档;不把每个函数都当作需要独立文档页;不把“未记录”等同于“需要记录”。其余收费、平台等信息暂未提供。