Dual Agent Collaboration

Codex × Claude 双模型协作

把当前模型设为 primary，把另一个 CLI 模型设为 peer reviewer。Primary 对结果负责；peer 提供独立判断，不共同编辑同一工作树。

核心不变量：

先验证“做的是不是用户真正要的”，再验证“方案和代码是否正确”。两个模型对同一份错误合同达成一致，不算成功。

这里的“协作”默认指：primary 完成研究、实现与自测，peer 读取同一批原始证据做独立挑战和校核，primary 再按 finding 修正。Peer 不在共享工作树直接编码；这正是本 Skill 对既有“Codex 主做、Claude Code 独立校核”流程的通用化。若用户明确要双模型分工编码，必须使用独立 worktree，并把合并审查另列为任务，不能复用默认模式偷偷并行写。

0. 完整性与效率边界

“所有产品都能使用”指 Skill 可跨项目发现和运行，不表示每个琐碎任务都强制双模型。按比例触发：

• 用户明确要求两个模型协作、交叉校核或“修到 ACK”：完整使用本 Skill。
• 复杂方案、跨模块开发、迁移、安全、重要重构、发布前验收：主动使用本 Skill。
• 低风险、边界明确、容易回退的小修：默认由单模型完成；除非用户点名，不为形式感增加四轮模型调用。

一旦触发本 Skill，就完整走 Intent、Plan、Implementation、Final 四个 gate，不以“提速”为由省略。高效率来自：

• 自动识别 primary 并选择另一 CLI；
• 统一 handoff、schema 与命令，不让每个项目重新发明提示词；
• Intent/Plan 尽早阻止做错需求或走错方案；
• Plan 续接 Intent、修复轮续接 Implementation，只在需要去锚定时冷启动；
• 结构化 fail-closed，避免对半截输出反复人工判断；
• 用 state file 自动判断下一 gate，减少人工记 session 和漏审。

默认 max reasoning 是完整协作的质量基线；只有用户明确优先成本/时延时才用环境变量下调，并在最终结果中披露。30 分钟是失败上限，不是预期耗时。

1. 选择角色

使用本 Skill 的 scripts/invoke_peer.py。脚本使用 argv + stdin 调 CLI，不使用 shell 拼接；peer 运行在只读模式，并设置递归保护。

先做命令构造预检：

python3 <skill-dir>/scripts/invoke_peer.py \
  --peer auto \
  --phase intent \
  --cwd <project-root> \
  --task-id <stable-project-task-id> \
  --add-dir <external-evidence-dir> \
  --prompt-file <handoff.md> \
  --dry-run

若 CLI 不存在、未认证、超时或未返回结构化结论，视为 BLOCKED，禁止假装已经双模型审查。

--dry-run 只证明参数已组装，不能证明 CLI 能启动、权限正确或输出可解析。任何 gate 的完成证据必须来自真实调用。

推荐用 --task-id，由 wrapper 按“项目路径 hash + task id”把 state 放入持久的用户状态目录：macOS 使用 ~/Library/Application Support/CodePal/dual-agent-workflows/，Linux 使用 $XDG_STATE_HOME/codepal/dual-agent-workflows/ 或 ~/.local/state/...。同一任务所有 gate 复用稳定 task id；不同任务不得复用。这样不污染仓库，也不会因系统清理 /tmp 或重启而丢掉 gate。只有集成方已有自己的状态存储时才显式用 --state-file。State 只存 verdict、session ID 和报告 hash，不存 handoff 正文。

2. 准备完整 handoff

读取 references/handoff-template.md，为每个门禁提供一份自包含 handoff。必须包含：

• 用户原话与后续纠正，放进 <raw_user_request> 标记，必须逐字引用，不能只给 primary 的总结。
• 期望业务结果、可观察行为、范围外事项。
• 当前事实和证据路径；区分事实、推断、假设。
• 项目协议、相关代码/文档、dirty worktree 和权限边界。
• 当前阶段的产物：方案、diff、测试结果、迁移演练或截图。
• 仍未验证的内容和需要 peer 挑战的问题。

把绝对路径或仓库内路径交给 peer，让它直接读原始材料。Artifact manifest 至少包含一个真实存在的绝对路径。不要只贴结论，也不要在 handoff 中暗示“预期 ACK”或泄露你怀疑的 bug。

发送证据前先检查项目根的 AGENTS.md、CLAUDE.md、安全/隐私文档和用户约束：

• 用户本次明确要求 Claude 与 Codex 协作，视为允许在当前任务范围内调用两端，但仍要排除 token、cookie、凭证和无关个人数据。
• 若是 primary 主动触发，发现禁止外部模型、单一供应商、保密或数据驻留要求时，必须先问用户；未获授权就不调用 peer。
• Handoff 保持“足以完整审查的最小数据集”，优先给受控路径，不复制无关仓库内容。

Claude 的读取边界默认是 --cwd。任何证据在 cwd 外时，必须显式传入其父目录：

--add-dir /absolute/read-only/evidence-directory

Claude 仍只开放 Read/Grep/Glob，所以 add-dir 不授予写能力。Peer 如果读不到 manifest 中的材料，必须 BLOCKED；不得忽略后继续 ACK。

Codex 的 read-only sandbox 限制写入但允许读取 manifest 中的绝对路径，因此没有 --add-dir 参数。首次安装或 Codex CLI 版本变化时，必须用 cwd 外临时证据做一次真实读取探针；读不到就 BLOCKED，不得假设行为不变。

Wrapper 会强制检查四段机器标记：

<raw_user_request>...</raw_user_request>
<artifact_manifest>...</artifact_manifest>
<validation_evidence>...</validation_evidence>
<known_gaps>...</known_gaps>

标记只能防遗漏，不能判断内容是否诚实；primary 仍必须保证其中是原始事实。

以下任一缺失时不得获得最终 ACK：

• 用户原话；
• 可验收的产品结果；
• 关键产物路径；
• 实现阶段的 diff 与验证证据；
• 已知限制和未完成项。

3. 运行四个门禁

Gate A：Intent

在设计或编码前，让 peer 独立回答：

1. 用户真正想得到什么，而不是字面要求了什么？
2. 哪些产品假设未经验证？
3. 当前边界是否会造成“技术正确、业务无效”？
4. 哪些验收必须使用真实数据或用户可见行为？

python3 <skill-dir>/scripts/invoke_peer.py \
  --peer auto --phase intent --cwd <project-root> \
  --task-id <stable-project-task-id> \
  --prompt-file <intent-handoff.md>

NOT_ACK 时先修正需求合同。不要开始实现。若 primary 不同意 finding，用原始证据反驳并续审，不要因 peer 权威而盲从。

Gate B：Plan

Intent ACK 后，把已接受的需求合同、技术调研和完整计划交给同一 peer session 续审：

python3 <skill-dir>/scripts/invoke_peer.py \
  --peer <peer> --phase plan --cwd <project-root> \
  --task-id <stable-project-task-id> \
  --session-id <intent-session-id> \
  --prompt-file <plan-handoff.md>

Plan 必须覆盖正常路径、失败路径、迁移/回滚、隐私、安全、性能、真实数据验证和测试矩阵。Peer 必须重新对照用户原话，不能只检查计划内部自洽。

Gate C：Implementation

Primary 独立编码、测试和记录证据。Peer 默认不修改文件，避免共享工作树冲突和责任模糊。Claude peer 只开放 Read/Grep/Glob；Codex peer 使用 sandbox_mode=read-only + approval_policy=never。需要 git diff 时由 primary 预先生成只读文件并加入 artifact manifest。

实现完成后开启一个新的冷审 session，不要续接 Plan session，降低锚定效应。Handoff 必须包含：

• 原始需求与已接受合同；
• 计划和变更文件；
• 完整 git diff 可读路径；
• 测试命令、通过数和失败输出；
• 真实数据/视觉/迁移证据；
• 没做什么及原因。

python3 <skill-dir>/scripts/invoke_peer.py \
  --peer auto --phase implementation --cwd <project-root> \
  --task-id <stable-project-task-id> \
  --add-dir <diff-or-evidence-dir> \
  --prompt-file <implementation-handoff.md>

Peer 按 P0/P1/P2/note 报告 finding。Primary 修复后，用该 implementation session ID 续审，逐项关闭旧 finding，同时要求 fresh scan，不能只确认补丁表面存在。