codex-pair

当前目录对应 v1.3.1 发行候选；真实双 CLI 验收仍需在用户指定窗口中单独完成。能力、检查范围与未完成项见开发状态。

让你已经打开的 Codex CLI 窗口共同完成一个项目。A 负责分工和协调，B 接受邀请后执行任务；需要时可邀请已有的 C、D 窗口加入。各窗口保留自己的会话、账号配置、模型和权限，通过本地消息桥接收任务、提问和交付结果。

本说明适用于 v1.3.1 及当前仓库源码：支持最多四个可见成员、独立审核和范围收尾。v1.3.1 发行版 已提供 ZIP 安装包和 SHA256 校验文件。旧发行包保持原样。

这是个人维护项目，并非 OpenAI 官方项目。

按当前用户选择，仅使用官方发布的 Codex CLI。候选补充了官方支持范围内的队列开始检查、自动接续控制和原后台终端查询；完整原生工具拦截仍不能保证，实际范围见官方CLI控制。

适合需要明确分工、相互核验和保留交付记录的项目。普通单窗口 Git 操作无需启动协作。

• 当前以 Windows 为主要验证环境，需要 Python 3.10+、Git，以及支持 queue / app-server 的官方 Codex CLI。本次有 CLI 0.166.0-alpha.5.1 的实际证据，不保证任意版本兼容。
• 先打开 A、B 两个 CLI 窗口。扩展时由 A 邀请用户选定的已有 C、D，最多四个可见成员。
• 可见成员支持 OpenAI 官方账号，或原 CLI 已配置的 DeepSeek API。工具不替你配置 API，不复制登录信息或 Key。
• 独立审核可由 A 管理的一个 OpenAI 官方 GPT 隐藏审核会话承担；它不替代可见成员，不负责审批或普通开发。同一时刻只保留一个有效审核者。
• 同一个工作树的业务串行执行；确有需要时使用明确登记的独立工作树。不会为了并行自动重建你的可见窗口。

以下源码安装方式适用于仓库中已完成整合的版本。安装前确认你取得的是目标版本，不把旧下载包当成最新源码。

git clone https://github.com/naxianjin/codex-pair.git
Set-Location codex-pair
$pairAccountRoot = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' }
python scripts/install_skill.py --source . --home $pairAccountRoot

使用实际的 Python 可执行程序，避免 WindowsApps 占位入口。安装器将技能写入当前配置的 skills/codex-pair，备份旧版并核对文件摘要；不会修改认证或模型配置。其他成员使用各自真实的配置环境，不要为了协作把几个窗口改到同一个账号目录。

已有仓库先检查未提交改动，再获取更新。已有协作升级时，先核实在途任务和结果、保存现场，再安全停止旧桥并从新入口恢复；不要直接覆盖正在运行的副本，也不要用旧版打开新数据库。磁盘安装完成不代表已有窗口或消息桥已经加载新版：窗口要读取新的 SKILL.md，桥也要确认实际运行入口。

在 A 的原 CLI 窗口调用 $codex-pair，说明项目、目标和允许改动范围。技能会核对仓库及当前会话，并使用安装目录中的入口执行：

python <技能目录>/scripts/pair.py start --project <项目绝对路径> --goal <本轮目标> --json

把返回的完整邀请交给已经打开的 B。B 在自己的窗口执行邀请中的 accept 命令，并按返回的 after_join 完成握手、上下文读取与确认。不要自行填写别人的会话信息，也不要在普通终端冒充成员窗口。

下一版候选的新协作默认在项目 .codex-pair/worktrees/ 给成员分配独立工作树，原CLI会话目录不变。业务文件操作使用返回的workspace，协议命令仍使用actor_cwd。已有合适的项目内独立树可沿用；共用模式须由A显式选择 --workspace-mode shared --workspace-reason <原因>。工作树创建失败时保留原文件、分支及创建记录，不自动退回共享模式。本项尚未动态验收，已安装版不会因此改变。

本地消息桥自动启动或复用。queued / accepted 只说明请求已被接收；双方业务回执及模型回合完成、通信验证通过后，才开始后续业务。

需要第三、第四个成员时，让 A 使用 invite-member，将返回的加入指令交给选定的原窗口；新成员不要再次执行 start。不按窗口标题、配置目录名或最近一次会话猜成员。

A 登记小任务、允许路径、依赖和必要检查。复杂工作按可以独立交付的阶段拆分；相同接口、锁文件或数据库结构由一人负责。

下面是分派命令的参数形式，具体值由 A 按本轮返回信息填写：

python <技能目录>/scripts/pair.py assign --pair <协作ID> --state-root <共享状态根目录> --task <任务ID> --title <标题> --to B --allow <仓库相对目录/> --body-file <UTF-8任务文件> --json

固定原成员执行的工作使用 --pin-member；独立核验用 --independent-of <被核验任务ID> 登记约束。需要必要检查时，A 在任务中明确验收条件及准确命令。

成员收到消息后遵循信封中的步骤：

1. 在原窗口目录领取消息，只有 claimed=true 才执行。重复领取返回 false 时结束，不能重做业务。
2. 长正文按 next_offset 分页读完，任务范围也要完整读取。收到前置交付后，完整 read-delivery，再按该版本的摘要 ack-delivery。
3. 仅修改允许路径，完成适用检查，保存结果及未验证项，再用原领取令牌 complete。需要澄清时用 ask-question 交 A，保留原任务并结束回合。

工具调用身份的原窗口目录和业务文件所在工作树可以不同。领取、完成按信封指定的 actor_cwd 操作，文件与 Git 操作使用任务 workspace，不能虚称改变了原会话根目录。

业务交付不等于验收通过。固定提交或文件快照通过 submit-stage 送审，保留实际作者和模型来源、差异、检查结果与限制。独立审核结果绑定准确版本；修改代码或需求后，旧结论不能放行新版本。

DeepSeek 实际完成或实质修改的成果，在作为已验收依赖、整合或发布前，必须由经核实的 OpenAI 官方 GPT 独立审核。A 的实现与整合后具体版本也需独立检查。待审、缺必要验证和返修中的阶段均不作为已通过依赖。

A 按已审版本整合，核对最终差异及适用回归后统一发布。发布还需要用户明确授权，以及确认过的仓库、远端和分支。发布入口要求当前有效的已审整合版本与干净工作树，不允许用旧阶段借用新阶段的通过状态。远端前进或结果未知时先核对事实，不强推、不重复未知推送。

成员仍受自己 CLI 的权限约束。支持的原生审批请求交给 A 单次处理，不代表 A 可以授予自己没有的权限。Hook 首次信任须由目标窗口用户审阅；普通技术答复、任务通过和通信成功都不等于权限批准。

用户变更授权时先登记新的授权依据。超时或 granted / unknown 不证明操作未执行：先核实原回合及实际结果，再按协议重试。不要复制凭据或绕过拒绝。

低额度时在当前工具安全结束后保存检查点。恢复先 check-checkpoint，有交接则完整读取、核对现场并登记恢复计划后消费；没有交接不扫描历史。原任务仍用原令牌继续，不重新领取、重投或从头重做。

从本轮返回信息取得协作 ID 和共享状态根目录后，技能可使用：

python <技能目录>/scripts/pair.py status --pair <协作ID> --state-root <共享状态根目录> --probe 3 --json
python <技能目录>/scripts/pair.py pause --pair <协作ID> --state-root <共享状态根目录> --json
python <技能目录>/scripts/pair.py resume --pair <协作ID> --state-root <共享状态根目录> --json

上述pause/resume命令形式保留用于识别旧版操作。下一版候选中，暂停后不能靠旧resume直接恢复running；须通过request-resume登记明确继续，再由原A按reconcile-resume核查原执行、授权及控制证据。任务级暂停也进入准确回合对应的本地工具门禁，绑定不明时保留阻塞；这不代表官方CLI所有工具都可拦截。确实要停止桥时使用 bridge --action stop，它不关闭原CLI，也不删除状态、代码和工作树。进程存在不等于可响应，状态中的随机挑战响应才是桥可响应的证据。

当前源码包含 close-scope。 当用户只要求结束本轮明确范围时，A 从自己已领取的活动规划或协调任务调用该接口，登记用户依据、范围内的准确交付与摘要，以及逐项排除历史任务的原因。先确认交付已完整读取，范围内业务版本已审核，其他执行、审批、问答和检查点已收尾。

成功后再普通 complete 当前协调消息，不加 --goal-complete。这会停止当前窗口目标的自动规划，保留历史任务、审核结论和消息桥；不会把未通过的历史工作改成通过，也不等于所有长期目标已完成。完整目标完成仍使用原有严格检查。具体字段见 阶段命令。

已有真实证据覆盖原窗口邀请、分派、问答、交付、审核返修及保存恢复；修复后消息桥已处理实际小任务。回合终态与共享工作区排队、旧审核阶段发布门禁有定向测试及独立审核证据。范围收尾已有隔离检查与独立审核，不能替代真实多窗口收尾记录。

这些结果不表示历史 G01—G16 全矩阵完成，也不证明任意 CLI、平台、提供方组合均兼容。真实审批、长期使用稳定性、正常中断恢复和延期的持久化专项按 发布后测试 继续，不为凑齐历史统计重复整套测试。

更新内容见 CHANGELOG.md。使用细节见 SKILL.md、首次接入、阶段命令 与 协作协议。旧参考文档可能保留历史版本说明，适用范围应以当前源码和明确的版本说明为准。

反馈问题时提供脱敏版本、复现步骤及原始错误。不要上传认证文件、完整配置、会话日志、领取令牌或协作数据库。