yinjianm
129 lines
4.6 KiB
Markdown
129 lines
4.6 KiB
Markdown
# 变更提案: create-git-merge-preserve-local-skill
|
||
|
||
## 元信息
|
||
```yaml
|
||
类型: 新功能
|
||
方案类型: implementation
|
||
优先级: P1
|
||
状态: 已确认
|
||
创建: 2026-04-16
|
||
```
|
||
|
||
---
|
||
|
||
## 1. 需求
|
||
|
||
### 背景
|
||
本次已在 `Xboard-new` 仓库中完成一次“以 `upstream/master` 为基线、保留本地改动优先”的真实合并。
|
||
这类需求在多仓协作中出现频率高，且容易踩到 dirty worktree、`modify/delete` 冲突、子模块 gitlink
|
||
冲突、错误远端基线等问题，适合沉淀成一个可复用 skill。
|
||
|
||
### 目标
|
||
- 在全局技能目录创建一个可自动发现的 skill。
|
||
- 让 skill 能指导 Codex 安全地把远端最新代码合并到当前分支，同时尽量保住本地改动并在冲突时偏向本地实现。
|
||
- 覆盖常见高风险场景，包括未提交改动、`modify/delete` 冲突、子模块冲突和合并后核验。
|
||
|
||
### 约束条件
|
||
```yaml
|
||
时间约束: 当前回合内完成创建、校验和可用性说明
|
||
性能约束: N/A
|
||
兼容性约束: skill 需放在 C:/Users/xiaohuli/.codex/skills 下以便全局自动发现
|
||
业务约束: 说明必须体现“保本地优先”语义，避免把 merge 写成 rebase/reset/强推流程
|
||
```
|
||
|
||
### 验收标准
|
||
- [ ] `C:/Users/xiaohuli/.codex/skills/git-merge-preserve-local/` 下存在完整 skill 目录
|
||
- [ ] `SKILL.md` 明确描述触发场景、工作流和关键风险点
|
||
- [ ] 至少有一份参考文档沉淀具体命令模板与冲突处理要点
|
||
- [ ] skill 通过 `quick_validate.py` 校验
|
||
|
||
---
|
||
|
||
## 2. 方案
|
||
|
||
### 技术方案
|
||
创建一个轻量级 workflow skill：
|
||
|
||
1. 用 `init_skill.py` 在全局技能目录初始化 `git-merge-preserve-local`。
|
||
2. 将核心触发条件和执行骨架写入 `SKILL.md`，保持内容精炼。
|
||
3. 将具体命令模板、冲突配方和核验清单下沉到 `references/merge-playbook.md`。
|
||
4. 用 `generate_openai_yaml.py` 生成 `agents/openai.yaml`，补齐 UI 元数据。
|
||
5. 运行 `quick_validate.py` 做结构校验。
|
||
|
||
### 影响范围
|
||
```yaml
|
||
涉及模块:
|
||
- 全局 Codex skills: 新增 git-merge-preserve-local skill
|
||
- 当前仓库 .helloagents: 新增本次方案包与执行记录
|
||
预计变更文件: 4-6
|
||
```
|
||
|
||
### 风险评估
|
||
| 风险 | 等级 | 应对 |
|
||
|------|------|------|
|
||
| 说明过长、触发词不清，导致 skill 不易命中或上下文成本过高 | 中 | 将流程骨架留在 `SKILL.md`，把命令细节下沉到 references |
|
||
| 将“保本地优先”误写成 `reset`、`rebase` 或 `push --force` | 高 | 明确写出推荐 merge 路径与禁用路径 |
|
||
| 忽略子模块 gitlink 冲突，导致 skill 在真实仓库里误导操作 | 高 | 单独增加子模块冲突章节和验证清单 |
|
||
|
||
---
|
||
|
||
## 3. 技术设计（可选）
|
||
|
||
> 本次为全局 skill 创建，不涉及业务系统架构/API/数据模型设计。
|
||
|
||
### 架构设计
|
||
N/A
|
||
|
||
### API设计
|
||
N/A
|
||
|
||
### 数据模型
|
||
N/A
|
||
|
||
---
|
||
|
||
## 4. 核心场景
|
||
|
||
> 该 skill 面向 Git 合并流程复用，不同步项目业务模块文档。
|
||
|
||
### 场景: 将上游最新代码合并到当前分支且保留本地优先
|
||
**模块**: 全局技能 / Git 工作流
|
||
**条件**: 用户要求同步远端最新代码，但不希望丢失本地改动，且冲突时偏向本地实现
|
||
**行为**: 先识别真实上游基线、保护现场，再执行 merge、处理冲突并核验
|
||
**结果**: 能在真实仓库中复用一套较稳健的“保本地优先合并”操作流程
|
||
|
||
---
|
||
|
||
## 5. 技术决策
|
||
|
||
> 本方案涉及的技术决策，归档后成为决策的唯一完整记录
|
||
|
||
### create-git-merge-preserve-local-skill#D001: 采用“SKILL.md + references”而非附带脚本自动执行 merge
|
||
**日期**: 2026-04-16
|
||
**状态**: ✅采纳
|
||
**背景**: 这类 Git 合并任务高度依赖现场状态，直接自动执行脚本容易因远端、分支、dirty worktree、子模块结构差异而误伤仓库。
|
||
**选项分析**:
|
||
| 选项 | 优点 | 缺点 |
|
||
|------|------|------|
|
||
| A: `SKILL.md + references` | 复用性高，允许结合现场状态判断，适合不同仓库差异 | 不是一键脚本，需要代理自己执行命令 |
|
||
| B: 直接附自动 merge 脚本 | 执行更快 | 风险高，容易在错误远端/错误分支/脏工作树下误操作 |
|
||
**决策**: 选择方案 A
|
||
**理由**: 该问题的关键不是缺少命令，而是缺少“什么时候用什么命令”的判断框架；skill 更适合作为操作协议而不是盲目自动化脚本。
|
||
**影响**: skill 主要由说明文档构成，强调流程判断、冲突配方和验证步骤
|
||
|
||
---
|
||
|
||
## 6. 成果设计
|
||
|
||
> 含视觉产出的任务由 DESIGN Phase2 填充。非视觉任务整节标注"N/A"。
|
||
|
||
### 设计方向
|
||
- N/A
|
||
|
||
### 视觉要素
|
||
- N/A
|
||
|
||
### 技术约束
|
||
- **可访问性**: N/A
|
||
- **响应式**: N/A
|