少见的模板升级机制full-stack-ai-agent-template的make upgrade三方合并原理深度解析【免费下载链接】full-stack-ai-agent-templateFull-stack AI app generator — FastAPI Next.js with AI Agents, RAG, streaming, auth, and 20 integrations out of the box.项目地址: https://gitcode.com/gh_mirrors/fu/full-stack-ai-agent-templatefull-stack-ai-agent-template 是一个开箱即用的全栈 AI 应用模板FastAPI Next.js内置 AI Agent、RAG、流式对话与 20 集成而它最少见的能力是内置的模板升级机制一条make upgrade命令就能把模板的新版本变更合并进你已生成的项目——通过真正的git 三方合并3-way merge自动更新模板改过的文件、完整保留你的自定义代码冲突则留给你手工解决全程可预览、可回滚。为什么模板项目需要模板升级机制 普通脚手架生成完就断联了模板持续迭代你的项目只能手动追。full-stack-ai-agent-template 把升级变成了一等公民——生成项目后你随时可以跑make upgrade-dry-run # 预览会有什么变化不改动任何文件 make upgrade # 真正执行升级结果落在独立 git 分支上 make upgrade-finalize # 解决完冲突后把版本清单升级到新版这些目标由模板生成项目时写入 Makefile见 Makefile底层调用的是fastapi-fullstack upgradeCLI。三方合并的核心原理BASE / OURS / THEIRS整个机制的灵魂在 merge.py 中的merge_trees函数它不自己发明合并算法而是在一个临时 bare 仓库里调用 git 原生的merge-tree --write-tree合并引擎。合并需要三个版本的完整文件树角色含义从哪来BASE你当初生成项目时的模板版本用你当年的答案重新渲染出来的OURS你当前的项目含全部自定义代码从你项目的 git HEAD 提取THEIRS目标新版本的模板用你当年的答案重新渲染出来的只要三个树同时存在git 就能精确区分哪些差异是你改的BASE↔OURS哪些是模板改的BASE↔THEIRS互不覆盖。合并结果落在专用分支template-upgrade/v版本上你的主干历史和未提交内容分毫未动。合并前的 3 个关键准备步骤1️⃣ 用你当年的答案重新渲染新旧模板关键在一个小小的清单文件.fastapi-fullstack.json由 manifest.py 的build_manifest生成它记录了生成时的模板版本和全部配置答案是否开启 RAG、选哪个任务队列等不含任何密钥安全可提交。有了它工具就能把旧版模板和新版模板分别渲染render.py 中的render_template再对比你的项目。渲染时会用一批空壳命令替换 uv、ruff、bun 等外部工具调用跳过耗时的安装步骤只取文件结构——历史版本怎么渲染新树就怎么渲染保证可复现。如果两个版本之间模板重命名了某个配置项比如use_pgvector改名为vector_storereconcile.py 的reconcile_context会按元数据把旧答案映射到新键名避免合并时误判你删掉了一堆功能。2️⃣ 格式归一化消灭假差异BASE、OURS、THEIRS 三棵树必须格式完全一致否则缩进和换行差异会被误读成代码编辑。normalize.py 会在三棵树上跑同一套 ruff / Prettier且只格式化渲染出来的树绝不动你自己的代码并把迁移文件里易变的生成时间戳统一抹平——这样合并引擎看到的每一处差异都是真差异。3️⃣ UPGRADES.yaml内容 diff 看不到的结构变更文件被移动/重命名是纯内容对比的盲区会被读成删一个 加一个导致你在旧路径上的编辑丢失。仓库根目录的 UPGRADES.yaml 由维护者按版本记录这些事实renames文件/目录迁移记录合并前在 BASE 和 OURS 上预先搬移让你的编辑跟随文件到新路径variable_renames模板配置项改名映射breaking/manual_steps跨版本聚合后展示在升级报告里例如合并后请运行make db-upgrade。make upgrade 实战预览、执行、报告第一步永远是预览make upgrade-dry-run只打印分组报告不改动任何文件。确认没问题后执行make upgrade工具会创建升级分支、应用所有安全变更并在结尾打印精确的回滚命令。升级报告由 report.py 渲染把每个文件按 classify.py 的分类矩阵归组。新手只需记住这张速查表报告分组含义你要做什么New files / New migrations模板新增文件 / 新增 Alembic 迁移已自动加入迁移记得跑make db-upgradeAuto-updates模板改了、你没改已自动更新无需处理Auto-merged双方都改了但没撞行已自动合并扫一眼即可Kept your changes你改了、模板没改原样保留你的版本Conflicts双方改了同一处打开 IDE 三方合并编辑器手工解决Your files你自己新建的文件永不触碰Changed migrations模板重写了你已运行的迁移重点核对必要时回退该文件冲突解决、finalize 确认与安全回滚冲突文件会留下标准 git 冲突标记 ours/ theirs用 VS Code 或 PyCharm 的三方合并编辑器解决后git add。然后运行make upgrade-finalize——它会校验当前分支正确、且没有任何未解决冲突才把清单文件中的版本号升到目标版本runner.py 中的run_finalize。这个安全网保证清单永远不会谎报你的版本。想放弃整个升级升级分支本来就是隔离的一条命令即可还原git checkout -f 原分支 git branch -D template-upgrade/v…命令会在升级结束时自动打印。另外工具对.env密钥文件、锁文件、node_modules等永不合并.env.example这类样例文件则正常合并确保新版新增的配置项能传达到你手里。动手体验 克隆仓库生成一个项目即可亲手体验完整的生成 → 自定义 → 升级闭环git clone https://gitcode.com/gh_mirrors/fu/full-stack-ai-agent-template完整的操作手册含无清单老项目的upgrade recover恢复流程、故障排查见官方指南 docs/guides/version-upgrade.md想看整体架构可继续读 architecture.md。小结full-stack-ai-agent-template 的make upgrade把追模板更新这件脏活变成了一次可预览、可合并、可回滚的标准 git 操作清单文件让历史可复现格式归一化消灭假差异UPGRADES.yaml 补上重命名盲区最后交给 git 三方合并引擎完成最后一公里。对于在模板上构建生产项目的团队来说这大概是同类全栈 AI 模板里少见的长期主义设计。【免费下载链接】full-stack-ai-agent-templateFull-stack AI app generator — FastAPI Next.js with AI Agents, RAG, streaming, auth, and 20 integrations out of the box.项目地址: https://gitcode.com/gh_mirrors/fu/full-stack-ai-agent-template创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考