antigravity-skills-reference/docs_zh-CN/maintainers/audit.md

仓库一致性和正确性审计

本文档总结了在 apps/ + tools/ + 分层 docs/ 重构后执行的仓库一致性审计。

范围

• 计数和数字（README、package.json、CATALOG）
• 技能验证（frontmatter、风险、"When to Use"、链接）
• 交叉引用（workflows.json、bundles.json、docs/users/bundles.md）
• 文档（docs/contributors/quality-bar.md、docs/contributors/skill-anatomy.md、安全/许可证）
• 脚本和构建（validate、index、readme、catalog、test）
• 关于 data/ 和测试 YAML 的说明

结果

1. 计数

• README.md、package.json 和生成的工件与当前集合大小（1,204+ 技能）保持一致。
• npm run sync:all 和 npm run catalog 是保持计数和生成文件同步的规范命令。

2. 技能验证

• npm run validate 是操作性的贡献者关卡。
• npm run validate:strict 目前是一个诊断强化通道：它仍然会在许多旧技能中显示仓库范围的遗留元数据/内容缺口。
• 验证器接受 risk: unknown 用于遗留/未分类的技能，同时仍然希望新技能具有具体的风险值。

3. 交叉引用

• 添加了 tools/scripts/validate_references.py（也作为 npm run validate:references 公开），它验证：
  • data/workflows.json 中的每个 recommendedSkills 都存在于 skills/ 中
  • 每个 relatedBundles 都存在于 data/bundles.json 中
  • data/bundles.json 中的每个 slug（技能列表）都存在于 skills/ 中
  • docs/users/bundles.md 中的每个技能链接都指向现有技能。
• 执行：npm run validate:references。结果：所有引用有效。

4. 文档

• 规范的贡献者文档现在位于 docs/contributors/。
• 规范的维护者文档现在位于 docs/maintainers/。
• README、安全文档、许可证和内部 markdown 链接在重构后已重新检查。

5. 脚本和构建

• npm run test 和 npm run app:build 在重构的布局上成功完成。
• validate_skills_headings.test.js 充当轻量级回归/冒烟测试，而不是完整元数据合规性的真实来源。
• 维护者文档现在需要与根 package.json 和重构的 tools/scripts/* 路径保持一致。

6. 可交付成果

• 计数与当前生成的注册表一致。
• 引用验证连接到重构的路径。
• 用户和维护者文档在布局更改后检查了路径漂移。
• 后续工作仍开放：需要仓库范围的清理以使 validate:strict 完全通过。

有用命令

npm run validate          # 技能验证（软）
npm run validate:strict   # 强化/诊断通道
npm run validate:references  # workflow、bundle 和 docs/users/bundles.md 引用
npm run build             # chain + catalog
npm test                  # 测试套件

未解决的问题/后续工作

• 逐步清理旧技能，以便 npm run validate:strict 可以在未来成为严格的 CI 关卡。
• 在规范英语文档稳定后，在单独的通道中保持翻译文档的一致性。