From c9979a4a2b5f0b4ae1c1982d959a9ed2a6776209 Mon Sep 17 00:00:00 2001 From: tongtongstudio Date: Sat, 10 Oct 2026 10:00:24 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E4=B8=8A=E6=B8=B8=E5=90=8C?= =?UTF-8?q?=E6=AD=A5=20-=20=E8=AE=B0=E5=BD=95=20backend/server=20=E5=A4=A7?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E6=9D=A5=E5=8E=86=E4=B8=8E=E5=BF=AB=E7=85=A7?= =?UTF-8?q?=E5=BC=8F=E5=90=8C=E6=AD=A5=E6=B5=81=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 670e66d13..c438d2b70 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -234,3 +234,26 @@ cd web && bun run dev - 需要批量清理时，**先只打印**匹配结果（PID、进程名、完整命令行）供人工确认，确认后另起一步执行终止；不要在同一条命令里「查完即杀」。 - 无法确认归属的进程一律不动，交回用户处理。同机存在多个同类工程时尤其要区分（例如 `infinite-canvas/web/.../vite.js` 与本项目的 `vite.js`）。 - 误杀非本项目进程时，必须立即如实告知用户，说明进程名、可能影响与恢复方式，不要轻描淡写。 + +## E. 上游大文件与同步方式（backend/server） + +上游在 `9727656b`（2026-09-14）提交了 `backend/server` —— 一个 62.7 MB 的构建产物（blob `cfba15a0`），且一直保留在 `upstream/main` 中；本仓库已在 `8cbc11e2` 之后用 `git filter-repo --path backend/server --invert-paths` 把它从自己的全部历史里移除，`git filter-repo` 单文件脚本与重写前的完整 bundle 备份放在本机 `.local/backup/`。由此有一条硬约束： + +- **不要把上游提交并入 `main`**。`git merge upstream/main`、`git rebase upstream/main`、以及 `git pull origin main`（把重写前的旧远端历史拉回来）都会让该 blob 重新进入可达集合（`git rev-list --objects main` 会再次列出 `backend/server`），克隆体积复原。三种情况都已实测复现。 +- 需要跟进上游内容时用「快照导入 + 重放差异」，不建立上游父提交： + + ```powershell + git fetch upstream + git diff upstream/main main --binary > .local/upstream-fork-diff.patch + git rm -rq --cached . + git checkout upstream/main -- . + git rm -q -f --cached backend/server + git apply --3way .local/upstream-fork-diff.patch + git add -A + git commit -m "chore(sync): 上游同步 - 快照导入 upstream/main 并重放本项目差异" + ``` + +- 与远端 `origin/main` 的对齐只能用强推（`git push --force-with-lease=main:<旧值> origin main`），不要 `git pull`：Gitea 上仍是重写前的历史，pull 必然冲突且把 blob 带回来。 +- `git fetch upstream` 会把该 blob 拉进本地对象库（只在对象库，不进历史与工作区）。要回收本地空间：`git update-ref -d refs/remotes/upstream/main` 后再 `git gc --prune=now`。 +- 若将来决定改回常规 `merge` 同步（换取上游血缘的合并体验），则必须在**每次合并提交里**执行 `git rm --cached backend/server`，并接受该 blob 常驻历史与克隆体积。`.gitignore` 已加 `/backend/server`，防止它被再次 `git add`。 +- 根本解法是上游清理该文件。上游清理后，`git reset --hard upstream/main` 再重放本项目差异即可两全。