sync: SHANGHAI-U9 2026-08-19 tools-sync 增 504 恢复工具 recover_commits_via_gitea_api.py 并写进阶段1处置

tools-sync/SKILL.md

@@ -54,6 +54,15 @@ powershell -File <skill目录>\scripts\sync_repos.ps1 -RepoUrl <origin_url>
 
 - **rebase 冲突**：逐个文件看冲突双方，skills 文本冲突通常保留两边语义合并；
   解不了就 `git rebase --abort` 并向用户报告冲突文件清单，让用户裁决。
+- **fetch / push 报 `RPC failed; HTTP 504`（服务端 pack 进程卡死）**：先分清哪一半坏了 ——
+  `git ls-remote` 与 Gitea HTTP API 正常、只有 `git-upload-pack` / `git-receive-pack` 504，
+  就不是认证也不是网络。**`--depth=1` 不能绕过，POST 体只有几十 KB 也照样 504**，所以
+  不要在"减小传输量"上浪费时间。此时若远端有本机没有的 commit（无法 rebase 就无法 push），
+  用 `scripts/recover_commits_via_gitea_api.py <repo_dir> <sha>...` 按**父在前**的顺序
+  经 API 逐字节重建那几个 commit：它只在重建对象的 SHA-1 与服务端报的 sha 完全一致时才
+  写入，所以是可证同一份历史，不是近似复制。重建后
+  `git update-ref refs/remotes/origin/main <sha>` + `git rebase <sha>`，本地历史就归位了，
+  服务恢复后一条 `git push` 即可。**任何情况下都不要 force push**（会丢掉别的机器的 commit）。
 - **push 被拒（认证）**：检查凭据管理器条目；新机器上用
   `git config --global credential.helper manager` 后重试一次，让 credential
   helper 弹窗或从 skills_env.md 读凭据拼一次性 URL 完成首次认证。