sync-openai-codex-pr

name	sync-openai-codex-pr
description	在独立 worktree（从 main 迁出）同步 openai/codex main 到当前仓库：本地优先解决冲突；先做 code-review 评估改动范围与冲突性质；只有遇到“同功能两套实现必须二选一”才在 PR comment 阻塞并请求选择；CI 全绿后才允许 merge。

sync-openai-codex-pr（上游同步 PR）

目标

• 拉取 https://github.com/openai/codex.git 的 main 并同步到当前仓库。
• 在独立 git worktree 内完成合并、修冲突、推送、创建/更新 PR；不污染当前分支/工作区。
• 默认策略：本地代码/行为优先（除非你明确选择采纳上游实现）。
• 门禁：CI required checks 全绿 才能合并。

决策规则（先 code-review 再动手）

• 先做改动范围审计：哪些目录/模块变了、风险点在哪（比如多 agent/agent teams、hooks/cleanup、TUI 命令 /clear /theme 等）。
• 冲突分类（按优先级）：
  1. 机械冲突（format/import/rename/move/并行改同一段但语义一致）：直接合并，保持最小 diff。
  2. 逻辑可融合（两边改动互补，功能不重复）：融合到一个实现，默认保持本地行为不回退。
  3. 同功能双实现（必须二选一）：不要私自拍板；必须在 PR comment 里写清楚差异并 @你选择，然后阻塞流程等待决定。

工作流

1) 从 main 创建 worktree（不污染当前分支）

在仓库根目录执行：

ts="$(date +%Y%m%d-%H%M%S)"
branch="sync/openai-codex-$ts"
path=".worktrees/sync-openai-codex-$ts"
git fetch origin main
git worktree add -b "$branch" "$path" origin/main

进入 worktree：

cd "$path"

2) 拉取上游并确认最新 commit（再合并）

git remote add openai https://github.com/openai/codex.git 2>/dev/null || true
git fetch openai main
openai_sha="$(git rev-parse openai/main)"
echo "openai/codex main: $openai_sha"

3) 先做改动范围审计（冲突前/后都做一次）

git diff --name-status origin/main...openai/main
git diff --stat origin/main...openai/main

如果你怀疑某些用户可见能力被“同步时舍弃”，在这里就能直接定位文件范围（例如 /clear、/theme、agent teams 等）。

4) 合并上游并处理冲突

git merge --no-edit openai/main

如果出现冲突：

1. 先列出冲突文件：git status
2. 对每个冲突做快速 code-review 分类（机械 / 逻辑可融合 / 同功能二选一）
3. 机械冲突、逻辑可融合：直接解决并继续
4. 只有“同功能二选一”才进入下一节的 PR comment 阻塞流程

5) 仅在“同功能二选一”时写阻塞性 PR comment

当且仅当你确认两边是同一个功能的两套实现，且无法合理融合：

• 在 PR comment 里写清楚：
  • 文件路径 + 关键函数/结构体
  • 行为差异（接口、边界条件、失败模式）
  • trade-off（复杂度、可维护性、性能、安全性、测试覆盖）
  • 需要你拍板的选项：保留本地 / 采用上游
• 在你选择前，停止继续推进（避免“默认本地优先”把上游同功能实现静默删掉）。

6) 最小化修复 + 格式化 + 目标测试

Rust（改 Rust 代码后）：

cd codex-rs
just fmt

优先跑最窄的相关测试（例）：

cargo test -p codex-core

如果改了 Cargo.toml / Cargo.lock：

cd ..
just bazel-lock-update
just bazel-lock-check

7) 提交 + 推送

git status
git add -A
git commit -m "sync: openai/codex @ <sha>"
git push -u origin HEAD

8) 创建/更新 PR

创建 PR：

gh pr create --base main --head "$branch" --title "sync: openai/codex @ <sha>" --body "Sync upstream openai/codex main. Local code prioritized; see commit(s) for conflict resolutions."

PR 已存在时，直接 push 新 commit 即可触发更新。

9) CI 门禁（必须）

只在 required checks 全绿后才允许 merge：

gh pr checks --repo <owner/repo> --watch <PR>

如果出现同功能二选一的阻塞 comment：等你选择后再继续修复/重跑 CI。