admin/Xboard

Fork 0

Files

T

yinjianm cbb46aca69 chore(helloagents): archive merge workflow proposals and tasks

2026-04-16 17:29:40 +08:00

5.9 KiB

Raw Blame History

变更提案: merge-upstream-preserve-local

元信息

类型: 优化
方案类型: implementation
优先级: P1
状态: 已确认
创建: 2026-04-16

1. 需求

背景

当前工作分支位于 master，本地相对 upstream/master 领先 15 个提交、落后 47 个提交。用户要求在保留所有本地改动与本地功能优先级的前提下，将 https://github.com/cedar2025/Xboard 的最新代码合并到当前分支。现场还存在未跟踪的 .helloagents/ 目录，以及 public/assets/admin 子模块指针与 upstream/master 不一致，需要在合并时避免误覆盖。

目标

将 upstream/master 的最新提交合并到当前分支。
保留当前分支已有提交与本地工作树内容，不做重置、不强推、不丢改动。
当出现文本冲突时优先保留当前分支的实现。
当出现子模块指针冲突时，显式保留当前分支所指向的子模块版本，并完成核对。

约束条件

时间约束: 当前回合内完成保护、合并、冲突处理和结果核验
性能约束: N/A
兼容性约束: 不改变当前分支名称，不破坏已有 Git 历史，避免影响未跟踪的本地目录
业务约束: 发生冲突时以用户本地功能优先；不使用 reset --hard 或覆盖式同步

验收标准

已成功抓取并合并 upstream/master 到当前分支，且本地 15 个领先提交仍保留在历史中
工作树中的本地未跟踪内容未丢失，合并冲突已处理完毕
若产生冲突，文本文件优先保留当前分支实现；public/assets/admin 子模块指针按当前分支版本保留并确认
合并后完成基本核验，包括分叉变化、工作树状态、子模块状态与冲突标记清零

2. 方案

技术方案

采用“保护现场 + 常规 merge + 冲突偏向当前分支 + 显式核对子模块”的方案：

记录当前现场，包括分支、工作树、与 upstream/master 的分叉和子模块指针。
创建本地安全锚点（备份分支或标签），确保任何一步异常都可回到操作前状态。
视需要暂存未跟踪内容，避免合并期间被意外干扰。
执行 git merge -X ours upstream/master，让文本冲突默认偏向当前分支。
如出现子模块指针冲突，手工恢复为当前分支所引用的子模块提交，而不是盲目接受上游版本。
完成后检查 git status、分叉计数、merge commit、子模块状态和冲突残留，确认结果满足“本地优先”要求。

影响范围

涉及模块:
  - Git 历史: 当前分支将新增一次来自 upstream/master 的合并结果
  - 根仓工作树: 可能因上游更新而变更多个跟踪文件
  - public/assets/admin: 子模块指针可能出现冲突，需要显式保留本地版本
  - .helloagents/plan: 新增本次操作的方案包与执行记录
预计变更文件: 多文件，数量取决于 upstream/master 与当前分支差异

风险评估

风险	等级	应对
`-X ours` 仅对文本冲突生效，无法自动正确处理子模块指针	高	合并后单独检查 `public/assets/admin`，必要时显式 checkout 当前分支的子模块提交
未跟踪的 `.helloagents/` 内容在操作中被误干扰	中	先记录现场，必要时仅暂存未跟踪内容，不删除任何本地文件
上游 47 个提交引入的结构变化与本地 15 个提交存在深度冲突	中	保留备份锚点，逐项处理冲突并在结果核验中确认本地功能仍存在
误把 `origin/master` 当作基线导致合并方向错误	低	固定以 `upstream/master` 为唯一上游基线执行本次合并

3. 技术设计（可选）

本次为 Git 合并操作，无架构/API/数据模型设计变更。

架构设计

N/A

API设计

N/A

数据模型

N/A

4. 核心场景

本次为仓库合并操作，不涉及业务模块文档同步场景。

场景: 当前分支合并 upstream/master

模块: Git 仓库 / 子模块条件: 当前分支存在本地领先提交，且用户要求本地实现优先行为: 拉取 upstream 最新提交并合并到当前分支，冲突时优先保留当前分支内容，子模块指针冲突显式保留当前指针结果: 当前分支吸收上游更新，同时保住本地提交和本地优先实现

5. 技术决策

本方案涉及的技术决策，归档后成为决策的唯一完整记录

merge-upstream-preserve-local#D001: 采用 merge 而非 reset、rebase 或手工摘取提交

日期: 2026-04-16 状态: ✅采纳背景: 用户要求“保留所有本地更改”并把远端最新代码合并到当前项目，同时冲突时本地功能优先。需要选择一种既能保留历史又便于冲突处理的更新方式。 选项分析:

选项	优点	缺点
A: `git merge -X ours upstream/master`	保留分支历史，适合把上游更新并入当前分支，文本冲突可偏向本地实现	不能自动正确处理子模块指针，需要额外检查
B: `git rebase upstream/master`	历史更线性	会重写当前分支提交，冲突重放次数可能更多，不符合“尽量保留现状”
C: `git reset --hard upstream/master` 后再回放本地改动	操作简单	高风险，会直接破坏当前现场，不符合需求
决策: 选择方案 A
理由: 常规 merge 最符合“保留本地提交和现场”的要求，结合 `-X ours` 能让文本冲突尽量偏向当前分支；剩余的子模块冲突可控且可显式核验。
影响: 影响当前分支历史、根仓工作树状态，以及 `public/assets/admin` 子模块指针处理方式

6. 成果设计

含视觉产出的任务由 DESIGN Phase2 填充。非视觉任务整节标注"N/A"。

设计方向

视觉要素

技术约束

可访问性: N/A
响应式: N/A

5.9 KiB Raw Blame History