docs(agents): 上游同步 - 改为基于上游血缘的正常 merge 策略，废弃快照同步

AGENTS.md

@@ -235,31 +235,25 @@ cd web && bun run dev
 - 无法确认归属的进程一律不动，交回用户处理。同机存在多个同类工程时尤其要区分（例如 `infinite-canvas/web/.../vite.js` 与本项目的 `vite.js`）。
 - 误杀非本项目进程时，必须立即如实告知用户，说明进程名、可能影响与恢复方式，不要轻描淡写。
 
-## E. 上游大文件与同步方式（backend/server）
+## 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/`。由此有一条硬约束：
+上游在 `9727656b`（2026-09-14）提交了 `backend/server` —— 一个 62.7 MB 的可执行构建产物（blob `cfba15a0`），且至今仍保留在 `upstream/main` 中。
 
-- **不要把上游提交并入 `main`**。`git merge upstream/main`、`git rebase upstream/main`、以及 `git pull origin main`（把重写前的旧远端历史拉回来）都会让该 blob 重新进入可达集合（`git rev-list --objects main` 会再次列出 `backend/server`），克隆体积复原。三种情况都已实测复现。
-- 需要跟进上游内容时用「指定基线 + 快照提交」，不建立上游父提交：
+本仓库曾用 `git filter-repo --path backend/server --invert-paths` 把它从全部历史移除，代价是本地历史与上游彻底断开血缘（不能用 `git merge`，只能「指定基线 + 快照提交」）。2026-10-13 起改为**以上游为基底、保留上游血缘**：`main` 重建为 `upstream/main@e70fe1b9` 的子提交（`d6d6eab5`，内容取当时工作树），随后正常合并 `upstream/main`。旧的「快照同步」规则随之作废。
+
+现状与约束：
+
+- `main` 是 `upstream/main` 的后代，**可以正常 `git merge upstream/main`**。日常同步：
 
   ```powershell
-  # 1. 记下上一次同步对应的上游 tip（作为本次三方合并的基线）
-  git rev-parse --short upstream/main          # 例如 37b44444
   git fetch upstream
-  # 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@<新 tip> 并重放本项目差异"
+  git merge upstream/main          # 常规三方合并；冲突优先保留上游实现，本仓库差异应集中在 B~D 三项
+  git ls-files backend/server      # 必须为空；若因上游改动而重新出现，执行 git rm backend/server 后再提交
+  git push origin main
   ```
 
-- 首次实操记录（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`。
-- 根本解法是上游清理该文件。上游清理后，`git reset --hard upstream/main` 再重放本项目差异即可两全。
+- **`backend/server` 的 blob 常驻历史**（因为它在上游祖先里），克隆与推送体积会包含它；这是换取上游血缘的必然代价。它已被 `.gitignore` 的 `/backend/server` 忽略，也不在 `main` 的工作树与索引中（`git ls-files backend/server` 为空），因此本地不会被检出。上游将来清理该文件后，直接正常合并即可两全。
+- **不要再次运行 `git filter-repo` 或任何历史重写**：那会重新切断与上游的血缘，回到旧的快照同步模式。
+- 每次合并后检查 `git ls-files backend/server`；只有上游确实改动该文件时它才会重新进入索引，用 `git rm backend/server` 处理并提交，不要改回 `.gitignore` 的忽略规则。
+- 不要用 `git diff --binary` 生成差异补丁：二进制补丁会把该 blob 整段写进补丁文件（实测 43.8 MB）。
+- 重建前的旧（filter-repo）历史备份在分支 `backup/pre-rebase-2026-10-13` 与 `.local/backup/ttstd-main-before-rebase-20261013.bundle`，仅作应急，不再用于同步。