用途:审计设计系统的文档面是否跟得上组件变化。以代码为“存在什么组件”的真实来源,对照各文档面,输出三类结果:覆盖率缺口(代码中有组件但无文档)、过期(文档早于组件最近一次代码变更)、孤立文档(组件已不存在但仍有页面)。
主要能力:生成按严重程度分级的发现表,并对每条信号标注置信度。覆盖度是两个列表的连接(代码中的组件与文档面中的条目),连接可靠性取决于连接键,因此每个覆盖度发现都带置信度层级,模糊匹配不会被当作事实陈述。
使用方式:开始前需核对技能 frontmatter 中 references: 的每个路径是否存在,缺失时应停止并提示按 1-INSTALL.md 重装并运行 verify-install.sh;仅在用户明确允许时才在缺少参考资料的情况下继续,并在输出中说明。若存在 .ds-ops-config.yml,按配置与周期运行说明加载配置、集成回退与周期运行。
可读取配置项包括 system.framework(影响组件文件发现方式)、severity.*(严重程度覆盖)、integrations.storybook.static_path(本地 Storybook 构建目录,首选来源)、integrations.storybook.url、integrations.documentation(可选托管平台:platform、url、api_key_env,以及 Zeroheight 的 styleguide_id 或 Supernova 的 design_system_id)、integrations.github,以及 docs_coverage.staleness_threshold_days(默认 90 天)。
流程:先建立组件清单(优先用 .ai/index/ 输出,其次公共 barrel 导出,最后 glob components 目录);再建立各文档面清单(Storybook 优先读本地 storybook-static/index.json,否则拉取 /index.json,无构建也无 URL 时直接读 CSF 文件;Figma 组件描述、托管平台页面、用法指南各自记录);然后按 Tier A/B/C 可靠性层级连接两份清单并记录层级;接着分析覆盖度缺口与孤立文档,再做过期分析(用 git log 比较组件与文档的最后变更时间);最后产出报告。
报告包含总体结论句、按层级(guided / described / exists / undocumented,取最高达成层级、互斥计数)统计、发现(ID、严重程度、类别、置信度、证据、建议)、孤立文档列表、行动清单与 Scope 块(检查了什么、未检查什么、如何验证“未找到”、假设)。周期运行时增加“自上次审计的趋势”段落。结尾附说明:审计看不到省略文档或文档早于变更的原因,Tier C 匹配只是猜测。
限制:无需任何集成就可运行,托管平台(Zeroheight、Supernova、自定义站点)为可选层;Storybook 的 componentPath 为可选项且不保证存在,缺失时回退名称连接;v:3 的 stories.json 没有 type: 'docs' 条目,rung 2 应标为未知;git log 对无提交文件返回空,应记为未跟踪并把过期标为未知;浅克隆与未加 --follow 的重命名会给出误导日期,建议完整克隆;Figma 描述与用法指南等具体细节资料未完全提供,收费与价格暂未提供。