📦 deps(thirdparty): update snapshots

antigravity-awesome-skills/docs_zh-CN/maintainers/ci-drift-fix.md

@@ -1,6 +1,6 @@
 # CI 漂移修复指南
 
-**问题**：失败的作业是由于在更新脚本运行后在 `README.md`、`skills_index.json` 或目录文件中检测到未提交的更改引起的。
+**问题**：失败的作业通常是因为 `main` 上的规范同步步骤运行后仍留下受跟踪的漂移。
 
 **错误**：
 
@@ -9,30 +9,54 @@
 ```
 
 **原因**：
-像 `tools/scripts/generate_index.py`、`tools/scripts/update_readme.py` 和 `tools/scripts/build-catalog.js` 这样的脚本会修改 `README.md`、`skills_index.json`、`data/catalog.json`、`data/bundles.json`、`data/aliases.json` 和 `CATALOG.md`。工作流期望这些文件在脚本运行后没有更改。任何差异意味着提交的仓库与生成脚本产生的内容不同步。
+规范同步契约不只覆盖根注册表文件。`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 资产
+- 生成的插件元数据和插件安全副本
 
-1. 在本地运行**完整的验证链**：
+工作流期望这些同步步骤结束后仓库是干净的。任何剩余的受跟踪或非托管更改都表示 `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 chain
-   npm run catalog
+   npm run sync:repo-state
    ```
 
-2. 检查更改：
+2. 检查是否仍有脏工作树：
 
    ```bash
    git status
    git diff
    ```
 
-3. 提交并推送任何更新：
+3. 如果同步只产生规范/生成文件更改，请暂存并提交它们。优先使用生成文件契约，而不是手写文件列表：
+
    ```bash
-   git add README.md skills_index.json data/catalog.json data/bundles.json data/aliases.json CATALOG.md
-   git commit -m "chore: sync generated registry files"
+   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 提交，这只对规范/生成子集是预期行为，不代表可以推送任意额外漂移。
+
 **总结**：
-始终提交并推送 registry、README 同步和 catalog 脚本产生的所有更改。这通过确保仓库和生成的工件与规范的 `tools/scripts/*` 管道保持同步，保持 CI 通过。
+只在 `main` 上把生成器漂移视为硬失败。对 PR 来说，契约更简单：审查 source-only 变更，生成输出仅作预览，最终规范工件由 `main` 生成。