63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# CI 漂移修复指南
|
||
|
||
**问题**：失败的作业通常是因为 `main` 上的规范同步步骤运行后仍留下受跟踪的漂移。
|
||
|
||
**错误**：
|
||
|
||
```
|
||
❌ 检测到由 registry/readme/catalog 脚本产生的未提交更改。
|
||
```
|
||
|
||
**原因**：
|
||
规范同步契约不只覆盖根注册表文件。`generate_index.py`、`update_readme.py`、`build-catalog.js`、`setup_web.js` 和插件同步助手可能合法更新：
|
||
|
||
- `README.md`
|
||
- `CATALOG.md`
|
||
- `skills_index.json`
|
||
- `data/*.json`
|
||
- `apps/web-app/public/` 下受跟踪的 Web 资产
|
||
- 生成的插件元数据和插件安全副本
|
||
|
||
工作流期望这些同步步骤结束后仓库是干净的。任何剩余的受跟踪或非托管更改都表示 `main` 与生成管道实际产物不同步。
|
||
|
||
## Pull Request vs Main
|
||
|
||
- **Pull Request**：PR 现在应保持 **source-only**。贡献者不应提交派生注册表工件（`CATALOG.md`、`skills_index.json`、`data/*.json`）。CI 会阻止这些直接编辑，并将生成漂移作为信息性预览报告。
|
||
- **`main` push**：漂移仍是严格错误。`main` 必须在自动同步步骤后保持干净。
|
||
|
||
## 如何在 `main` 上修复
|
||
|
||
1. 在本地运行规范维护者同步：
|
||
|
||
```bash
|
||
npm run sync:repo-state
|
||
```
|
||
|
||
2. 检查是否仍有脏工作树：
|
||
|
||
```bash
|
||
git status
|
||
git diff
|
||
```
|
||
|
||
3. 如果同步只产生规范/生成文件更改，请暂存并提交它们。优先使用生成文件契约，而不是手写文件列表：
|
||
|
||
```bash
|
||
node tools/scripts/generated_files.js --include-mixed
|
||
git add $(node tools/scripts/generated_files.js --include-mixed)
|
||
git commit -m "chore: sync canonical artifacts"
|
||
git push
|
||
```
|
||
|
||
4. 如果 `sync:repo-state` 留下无关或非托管漂移，请停止并检查。`main` 上的 bot 只允许推送规范/生成子集；其他任何东西都应让工作流失败，而不是被静默自动提交。
|
||
|
||
## PR 维护者指南
|
||
|
||
- 验证源代码变更，而不是要求贡献者提交生成工件。
|
||
- 如果贡献者 PR 直接修改 `CATALOG.md`、`skills_index.json` 或 `data/*.json`，请要求他们从 PR 中删除这些文件，或在刷新分支时移除。
|
||
- 如果合并冲突涉及生成注册表文件，请保留 `main` 版本，并让 `main` 合并后自动同步最终生成物。
|
||
- 如果 `main` 上的 CI 后续创建带 `[ci skip]` 的 bot 提交，这只对规范/生成子集是预期行为，不代表可以推送任意额外漂移。
|
||
|
||
**总结**：
|
||
只在 `main` 上把生成器漂移视为硬失败。对 PR 来说，契约更简单：审查 source-only 变更，生成输出仅作预览，最终规范工件由 `main` 生成。
|