csh/playbook

Files

T

ci[bot] a225b70c17 📦 deps(thirdparty): update snapshots

2026-06-25 16:06:49 +00:00

2.6 KiB

Raw Blame History

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` 上修复

在本地运行规范维护者同步：
```
npm run sync:repo-state
```
检查是否仍有脏工作树：
```
git status
git diff
```

如果同步只产生规范/生成文件更改，请暂存并提交它们。优先使用生成文件契约，而不是手写文件列表：

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

如果 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 生成。