69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# 仓库一致性和正确性审计
|
||
|
||
本文档总结了在 `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` 完全通过。
|
||
|
||
## 有用命令
|
||
|
||
```bash
|
||
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 关卡。
|
||
- 在规范英语文档稳定后，在单独的通道中保持翻译文档的一致性。
|