upstream-sync-curator

name	upstream-sync-curator
description	用于这个仓库中“先分析 upstream 提交与代码变更，再按功能主题选择性引入 upstream 变更；所有操作在临时 worktree 中完成，并在难解冲突时优先保留当前 fork 实现”。当用户提到 upstream sync、同步源仓库、选择性合并 upstream、分析上游提交、挑功能合并等意图时使用。仅适用于 nervmor/codexui 与其上游 friuns2/codexUI。

Upstream Sync Curator

仅用于本仓库 nervmor/codexui 与上游 friuns2/codexUI 之间的选择性同步。

固定上游地址：

https://github.com/friuns2/codexUI.git

不要直接同步整个 upstream。 固定执行“两阶段”流程：先分析 upstream 提交与代码变更，按功能主题整理候选变更；再根据用户选中的功能主题做选择性引入。

触发条件

当用户提到以下意图时触发：

• upstream sync
• 同步源仓库
• 选择性合并 upstream
• 分析上游提交
• 挑功能合并

仅适用于本仓库及其 upstream friuns2/codexUI。

第 1 阶段：准备环境

1. 检查主工作区是否干净。 如果主工作区不干净，先停止并让用户决定如何处理，不要把已有修改卷入 upstream 同步流程。

git status --short

2. 检查 origin 是否指向当前 fork nervmor/codexui。

git remote -v

3. 配置或校验 upstream，并强制使用 HTTPS 地址，不要使用 SSH。

git remote get-url upstream
git remote remove upstream
git remote add upstream https://github.com/friuns2/codexUI.git

4. 创建带时间戳的临时分支和临时 worktree，避免污染主工作区。

ts="$(date +%Y%m%d-%H%M%S)"
tmp_branch="upstream-sync-${ts}"
tmp_dir="$(mktemp -d -t codexui-upstream-sync-XXXXXX)"
git worktree add -b "${tmp_branch}" "${tmp_dir}" main

5. 后续所有 fetch、log、diff、cherry-pick、merge 都只在临时 worktree 内执行。 不要在主工作区直接做任何 upstream 分析或引入操作。

第 2 阶段：分析 upstream 变更

1. 在临时 worktree 中获取最新的 origin/main 和 upstream/main。

cd "${tmp_dir}"
git fetch origin main
git fetch upstream main

2. 计算当前 fork 与 upstream 的 merge-base。

base_commit="$(git merge-base origin/main upstream/main)"
echo "${base_commit}"

3. 列出 upstream-only commits，并按时间顺序和改动范围整理。

git log --reverse --no-merges --oneline "${base_commit}..upstream/main"
git diff --stat "${base_commit}..upstream/main"

4. 按“功能主题”分组候选变更。每组至少输出以下内容：

• 功能主题名
• 涉及 commit 列表
• 主要改动文件或目录
• 风险等级
• 与当前 fork 可能冲突的区域
• 是否推荐引入

5. 分析完成后，必须先向用户给出分组结果和建议。 在用户明确选择功能主题之前，不得直接合并全部 upstream，也不得提前进入实际引入步骤。

建议输出格式：

功能主题：<name>
commits：<sha1>, <sha2>, ...
范围：<files/dirs>
风险：低 / 中 / 高
冲突点：<areas>
建议：推荐引入 / 可选 / 暂不建议

第 3 阶段：选择性引入策略

默认粒度是“功能主题”，而不是“整支 upstream”。

1. 首选实现方式：按主题对应的 commit 序列执行 cherry-pick。

git cherry-pick <commit-a> <commit-b> <commit-c>

2. 如果某个主题跨多个零散 commit，但文件边界清晰，则退化为按文件或目录从 upstream/main 引入。

git restore --source=upstream/main -- path/to/file path/to/dir
git add path/to/file path/to/dir
git commit -m "Selectively import upstream <theme-name>"

3. 只有在 commit 粒度和文件粒度都不适合时，才允许在临时 worktree 中做一次受控 merge，并把它当作最后手段。

git merge --no-ff upstream/main

不要把受控 merge 当成默认方案。

第 4 阶段：冲突处理策略

默认原则：尽量保留 upstream 的非冲突改动。

1. 普通冲突：优先保留当前 fork 的实现。
2. 难解冲突：直接选择 ours，放弃 upstream 在该冲突点上的改动。

可接受的处理方式示例：

git checkout --ours -- path/to/conflicted-file
git add path/to/conflicted-file

或在确实无法安全吸收时，保留当前 fork 实现并放弃对应冲突块。

明确禁止以下行为：

• 为了吃进 upstream 而重置、覆盖或回滚用户已有修改
• 在主工作区直接解决冲突
• 为了省事而默认整支 merge upstream

“以我的修改为准”的含义仅限冲突区域：没有冲突的 upstream 改动默认允许被吸收。

第 5 阶段：收口与报告

1. 在临时 worktree 中完成整理后，再决定是否合回 main。
2. 输出结果必须明确区分以下几类：

• 已分析但未引入的功能主题
• 已引入的功能主题
• 因冲突而保留本仓库实现的文件或区域
• 需要后续人工处理的残留风险

3. 如果用户尚未批准引入某些功能主题，只提交分析与建议，不要擅自继续。
4. 如果用户批准引入，再基于临时 worktree 中整理好的结果决定后续合并路径。

强制约束

• 上游仓库固定为 friuns2/codexUI
• upstream URL 固定为 https://github.com/friuns2/codexUI.git
• 每次操作都在临时 worktree 中完成
• 先分析，再让用户选择功能主题，再执行引入
• 优先 cherry-pick，其次文件级引入，最后才是受控 merge
• 冲突难解时优先保留当前 fork 实现
• 不要硬编码任何 commit hash；运行时获取最新 upstream 状态