admin/Xboard

Fork 0

Files

T

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

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

4.6 KiB

Raw Blame History

变更提案: create-git-merge-preserve-local-skill

元信息

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

1. 需求

背景

本次已在 Xboard-new 仓库中完成一次“以 upstream/master 为基线、保留本地改动优先”的真实合并。这类需求在多仓协作中出现频率高，且容易踩到 dirty worktree、modify/delete 冲突、子模块 gitlink 冲突、错误远端基线等问题，适合沉淀成一个可复用 skill。

目标

在全局技能目录创建一个可自动发现的 skill。
让 skill 能指导 Codex 安全地把远端最新代码合并到当前分支，同时尽量保住本地改动并在冲突时偏向本地实现。
覆盖常见高风险场景，包括未提交改动、modify/delete 冲突、子模块冲突和合并后核验。

约束条件

时间约束: 当前回合内完成创建、校验和可用性说明
性能约束: 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：

用 init_skill.py 在全局技能目录初始化 git-merge-preserve-local。
将核心触发条件和执行骨架写入 SKILL.md，保持内容精炼。
将具体命令模板、冲突配方和核验清单下沉到 references/merge-playbook.md。
用 generate_openai_yaml.py 生成 agents/openai.yaml，补齐 UI 元数据。
运行 quick_validate.py 做结构校验。

影响范围

涉及模块:
  - 全局 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

4.6 KiB Raw Blame History Unescape Escape