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

## 元信息
```yaml
类型: 优化
方案类型: implementation
优先级: P1
状态: 已确认
创建: 2026-04-16
```

---

## 1. 需求

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

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

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

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

---

## 2. 方案

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

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

### 影响范围
```yaml
涉及模块:
  - 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

### 技术约束
- **可访问性**: N/A
- **响应式**: N/A