iKun API 使用文档

Appearance

用 Git Worktree 让 Codex 并行开发 ​

Git Worktree 可以为同一个仓库创建多个独立工作目录。每个目录使用不同分支或 detached HEAD，因此多个 Codex 任务可以同时修改代码，而不会把未提交改动混在一起。

一句话理解 ​

Worktree 隔离任务现场，Codex 并行执行，测试和代码审查负责最终验收。

适合并行的任务包括：

  • 开发新功能时插入一个紧急 Bug 修复；
  • 同时推进两个互不依赖的功能；
  • 在两个目录中验证同一问题的不同解决方案；
  • 不影响当前工作目录地审查 PR 或复现问题。

如果两个任务会频繁修改同一批文件，Worktree 仍然可以隔离开发过程，但最终合并时很可能出现冲突，并不会自动消除协调成本。

Worktree 隔离什么 ​

每个 Worktree 都有自己的：

  • 工作目录和检出文件；
  • HEAD 与当前分支状态；
  • 暂存区；
  • 未提交改动。

同一仓库的 Worktree 会共享对象数据库、提交历史、分支引用和远程仓库配置。因此，一个 Worktree 创建的提交和分支，其他 Worktree 可以通过 Git 命令看到。

Worktree 不会隔离：

  • 服务端口；
  • 数据库、Redis 和消息队列；
  • 浏览器登录状态；
  • Docker 容器名和其他系统级资源；
  • 被 .gitignore 忽略的本地文件如何初始化。

WARNING

普通 git worktree add 不会把主目录里的未跟踪 .env、本地数据库或 node_modules 复制过去。每个新目录通常需要重新安装依赖并准备自己的本地配置。

推荐方式：使用 Codex App 原生 Worktree ​

Codex App 已经原生支持 Worktree，不必手工创建目录和分支：

  1. 新建 Codex 任务；
  2. 在输入框下方选择 Worktree；
  3. 选择任务的起始分支；
  4. 提交任务描述；
  5. 为另一个独立任务重复以上步骤。

Codex 默认会在 $CODEX_HOME/worktrees 下创建受管理的 Worktree，并以 detached HEAD 开始工作。任务完成后，可以：

  • 点击 Create branch here 创建分支，然后提交、推送并创建 PR；
  • 使用 Hand off 把任务和改动移回 Local，在常用 IDE 和本地环境中继续验证。

Codex 管理的 Worktree 不会自动带入所有忽略文件。如果任务需要 .env、.env.local 等文件，可以在仓库根目录创建 .worktreeinclude：

text
# .worktreeinclude
.env
.env.local
config/local.json

.worktreeinclude 只适用于 Codex App 管理的本地 Worktree。不要把生产密钥或不应扩散的凭证列入其中。

手工方式：使用 Git 命令 ​

假设主仓库位于 D:\Project\github\aurora-web，需要并行处理登录 Bug 和深色模式：

text
cd D:\Project\github\aurora-web
git fetch origin

git worktree add -b fix/password-validate `
  ..\aurora-fix-password origin/main

git worktree add -b feat/dark-mode `
  ..\aurora-dark-mode origin/main

现在三个目录共享 Git 历史，但分别拥有独立工作文件：

text
D:\Project\github\
├── aurora-web\
├── aurora-fix-password\
└── aurora-dark-mode\

分别进入两个 Worktree 启动 Codex：

text
cd D:\Project\github\aurora-fix-password
codex

cd D:\Project\github\aurora-dark-mode
codex

给每个任务写清楚范围和验收条件。例如：

text
修复登录页密码校验跳过长度检查的问题。
只修改登录校验相关模块，补充特殊字符场景的单元测试；
全部相关测试通过后再报告结果。

另一个任务可以使用不同的 Codex 窗口或终端独立执行。

为运行环境做隔离 ​

如果两个任务要同时启动应用，需要为它们分配不同资源：

text
# Worktree A
$env:PORT="3000"
$env:SQLITE_PATH="$PWD\local.db"
npm run dev

# Worktree B
$env:PORT="3010"
$env:SQLITE_PATH="$PWD\local.db"
npm run dev

具体环境变量取决于项目。某些前端工具不会读取 PORT，需要使用类似 npm run dev -- --port 3010 的参数。数据库 schema、Redis key 前缀、容器名和回调 URL 也要按项目实际情况隔离。

审查每个任务 ​

不要只看 Codex 的完成说明。进入对应 Worktree 检查真实状态：

text
git status --short
git log --oneline --decorate -5
git diff --stat origin/main
git diff origin/main

随后运行项目规定的格式化、静态检查、单元测试和端到端测试。对网页功能还应启动实际页面进行浏览器验证。

合并方式 ​

通过 PR 合并 ​

这是团队协作时更稳妥的方式：

text
git push -u origin fix/password-validate
git push -u origin feat/dark-mode

分别创建 PR，等待 CI 和审查通过，再根据仓库策略选择普通合并、Rebase 或 Squash and merge。

在本地 Squash ​

git merge --squash 会把目标分支的最终差异放入暂存区，但不会创建真实的 merge commit，也不会记录该分支已经合并：

text
cd D:\Project\github\aurora-web
git switch main
git pull --ff-only origin main

git merge --squash fix/password-validate
git commit -m "fix: 修复密码校验长度检查"

# 合并下一个任务前，先测试当前 main
git merge --squash feat/dark-mode
git commit -m "feat: 添加深色模式切换"

# 再运行完整测试，确认两个任务组合后仍然正常
git push origin main

IMPORTANT

两个分支都基于旧的 origin/main 开发时，第二次合并可能与第一次产生冲突。每合并一个任务都应解决冲突并重新测试，不能把“Worktree 互不干扰”理解为“合并时不会冲突”。

清理 Worktree ​

任务确认合并并推送后，在主目录执行：

text
git worktree list
git worktree remove ..\aurora-fix-password
git worktree remove ..\aurora-dark-mode

git worktree remove 默认会拒绝删除包含未提交改动或未跟踪文件的目录。先检查并保留需要的内容，不要为了省事直接使用 --force。

Squash 不会建立分支合并关系，因此下面的安全删除可能被 Git 拒绝：

text
git branch -d fix/password-validate

确认提交已经进入 main 且分支不再需要后，才使用 git branch -D。如果曾手动删除 Worktree 目录，可以运行 git worktree prune 清理失效的管理记录。

原文中需要修正的说法 ​

原说法更准确的结论
node_modules、.env 会被 Worktree 隔离目录彼此独立，但新 Worktree 通常没有这些忽略文件，需要安装、生成或通过 .worktreeinclude 复制
Worktree 通常比完整 Clone 少一半以上空间它不重复 Git 对象库，但依赖、构建缓存和工作文件仍可能占用大量空间，不能给固定比例
Squash 后可直接用 git branch -d 删除分支Squash 不记录合并关系，-d 可能拒绝；确认无误后才使用 -D
告诉 Codex 一句话后无需人工操作Codex 可以执行创建、开发和测试，但权限确认、任务边界、冲突处理、测试与代码审查仍需要人负责
同一个分支绝对不能出现在两个 WorktreeGit 默认禁止同一分支被重复检出，这是应遵守的安全约束；底层存在强制选项，但不应作为并行开发方案

最终建议 ​

日常使用时保持 2 至 3 个边界清晰的并行任务通常最容易管理。每个任务都应有：

  • 独立 Worktree 或 Codex 管理的工作区；
  • 明确的文件范围和验收条件；
  • 独立端口与测试数据；
  • 合并前代码审查；
  • 合并后的完整回归测试。

Worktree 解决的是开发现场隔离，不负责需求拆分、资源隔离和合并正确性。把这些边界写清楚，Codex 并行开发才会真正提高效率。

参考资料 ​

iKun API 使用、接入与故障排查文档

Powered by VitePress