docs(agents): 上游同步 - 补充指定基线的快照合并流程与实测记录

AGENTS.md

@@ -240,19 +240,25 @@ cd web && bun run dev
 上游在 `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
+  # 1. 记下上一次同步对应的上游 tip（作为本次三方合并的基线）
+  git rev-parse --short upstream/main          # 例如 37b44444
   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
+  # 2. 指定基线做三方合并。不要直接用 git merge：重写后与上游的共同祖先太远
+  #    （准确说是文件引入前的老提交），git 会误报上百个冲突。
+  git merge-recursive 37b44444 -- main upstream/main
+  # 3. 解冲突（通常 0~2 个，只落在本仓库改过的文件上）
+  # 4. 确认大文件没有被加回：git ls-files backend/server 应为空
+  # 5. 提交：merge-recursive 不写 MERGE_HEAD，因此是单父提交，历史不接上游血缘
   git add -A
-  git commit -m "chore(sync): 上游同步 - 快照导入 upstream/main <sha> 并重放本项目差异"
+  git commit -m "chore(sync): 上游同步 - 快照导入 upstream/main@<新 tip> 并重放本项目差异"
   ```
 
+- 首次实操记录（2026-10-12，同步 `37b44444` → `e70fe1b9`，15 个上游提交）：指定基线后仅 1 个冲突（`canvas-project-top-bar.tsx` 的图标 import，取上游清单并保留本仓库仍在用的 `Settings`），167 个文件变更；用默认 `git merge` 则误报约 140 个冲突。
+- 不要用 `git diff --binary` 生成差异补丁：本仓库相对上游包含 `backend/server` 的删除，二进制补丁会把 62.7 MB 内容整段写进补丁文件（实测 43.8 MB）。
+
 - 与远端 `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`。