0xyxy/codex-collab

把 OpenAI Codex CLI 当成供应商而不是顾问——要产物，不要解释。

一套给 AI agent（或你自己）用的 PowerShell 脚本，解决同一个问题：怎么让 Codex 高效干活，而且干完能验收。

它解决什么

直接调 codex exec 的常见问题：

• 它给你一大段解释，你只想要代码
• 它写完不测，你不知道能不能用
• 改一个 bug 要来回五轮，每轮都重新交代背景
• 五个独立任务排队跑，等得心焦
• 出过的坑，下次又踩一遍

这套脚本把上面全包了：派活时强制附带验收标准 + 自测脚本，本地跑测试，失败把报错原文丢回去。

核心思路

你提需求
  ↓
派活（一次给足：文件名 + 验收标准 + 自测要求）
  ↓
Codex 写代码 + 写测试
  ↓
本地跑它写的测试 ── 绿 ──→ 补对抗性测试 ──→ 交付
  ↓ 红
把报错原文整段丢回去（续接同一会话）

两个关键点：

1. 它写的测试只能证明「它想到的都对了」，不证明「它没错」。所以必须补对抗性用例打它想不到的地方。
2. 失败时不要自己分析再转述，把测试报错原文原封不动丢回去，省一轮翻译。

安装

# 1. 装 Codex CLI 并登录
#    https://github.com/openai/codex

# 2. 把本仓库放到技能目录（可选，用于 DSH/agent 自动加载）
git clone https://github.com/<you>/codex-collab.git "$HOME/.dsh/skills/codex-collab"

# 或者直接用，不放到技能目录也行
git clone https://github.com/<you>/codex-collab.git
cd codex-collab/scripts

依赖：PowerShell 7+。Python 可选（只有桌面端会话挂载功能需要）。

快速开始

写个脚本（最常用）

./codex-build.ps1 `
  -Task "写一个日志分析脚本，统计访问最多的路径和状态码分布" `
  -Files "Log-Analyzer.ps1" `
  -TestScript "Test-Log-Analyzer.ps1" `
  -Acceptance "参数 -Path/-Top；退出码 0成功 1文件不存在 2无有效数据；输出JSON"

它会自动：

1. 组装派活单（含必交文件、验收标准、自测要求、只回一行的纪律）
2. 调 Codex 写代码，落盘
3. 跑 Test-Log-Analyzer.ps1，告诉你绿还是红

红了就按提示把报错丢回去。

批量跑多个任务

./codex-fanout.ps1 -Tasks @(
  "解释 PowerShell 里 $_ 和 $PSItem 的区别",
  "Get-ChildItem -Force 会不会列隐藏文件",
  "-ErrorAction Stop 和 try/catch 什么关系"
)

每个任务独立超时，答案从 -o 文件读，互不干扰。

早期版本给每个任务起隐藏窗口的 pwsh runner 并行跑。实测在本机不可用：子进程里的 codex 一律卡死到超时（同一时刻进程内直调 30–50 秒就成）。现在改成进程内顺序执行，-MaxParallel 仅为兼容保留。

多轮讨论

./codex-talk.ps1 -Message "我的判断是 X，你觉得呢"
./codex-talk.ps1 -Message "你说 Y，但我认为 Z"        # 自动续接同一会话
./codex-talk.ps1 -NewSession -Message "换个话题"      # 另起一条

用的是 codex exec resume——真正续接同一个 thread，历史在服务端，不用重发。

修 bug

./codex-build.ps1 `
  -Task "测试报错：FAILED: 状态码分布不符，期望 404:1 实际 404:0" `
  -Files "Log-Analyzer.ps1" -TestScript "Test-Log-Analyzer.ps1" `
  -KeepContext

-KeepContext 续接上一次会话，它记得之前写了什么。

脚本一览

脚本	用途	平台
codex-build.ps1	派活 + 强制自测 + 自动验收	全平台
codex-fanout.ps1	并行派活，多任务同时跑	全平台
codex-talk.ps1	真单会话多轮续接	全平台
codex-delegate.ps1	同步调用，快速取结果	全平台
codex-watch.ps1	看门狗：超时即杀 + 重试，防流式卡死	全平台
codex-review.ps1	代码审查：未提交 / 分支 / 单提交，落盘 md	全平台
codex-context.ps1	共享上下文：约定 + 自动时间线	全平台
codex-post.ps1	投递消息到桌面端会话	Windows
codex-send.ps1	UI 自动化直发（会抢焦点）	Windows
codex-on.ps1 / codex-off.ps1	代理开关 + 重启桌面端	Windows
_mount.py	会话挂到桌面端「最近」列表	Windows + Python

沙箱默认值（选错脚本 = 静默不落盘）

脚本	默认 Sandbox	能改文件吗
codex-build	workspace-write	✅
codex-delegate	workspace-write	✅
codex-talk	read-only	❌
codex-fanout	read-only	❌
codex-watch	read-only	❌ 除非 -AllowWrite

要它动文件：用 codex-build，或显式加 -Sandbox workspace-write / -AllowWrite。

共享上下文（跨会话，不用重复交代）

每个工作目录一份 .dsh/codex-context/<项目名>-<hash>.md：约定（手写）+ 时间线（自动记录做了什么 → 结果，注入最近 10 条）。

codex-talk / codex-build / codex-delegate 调用前自动注入，调用后自动记账；-NoContext / -NoRecord 可关。

./codex-context.ps1                              # 查看
./codex-context.ps1 -Action add -Text "本项目用 pnpm"
./codex-context.ps1 -Action clear                # 清空时间线（约定保留）

和 AGENTS.md 分工：那是进版本库的项目规范，这份是私有工作笔记（含试错记录）。

参数说明

所有调用 Codex 的脚本共有：

参数	默认	说明
-Model	gpt-6.1-sol	模型名
-Sandbox	read-only / workspace-write	沙箱级别，要落盘必须用 workspace-write
-Proxy	空（直连）	代理地址，如 http://127.0.0.1:7890

codex-talk 额外有 -NewSession（强制新建）、-Thread <id>（指定会话）、-Reset（清空本地记录）、-Full（关掉精简模式）。

codex-build 额外有 -KeepContext（续接上次会话）、-NoVerify（只派活不验收）。

成本参考

• 单次调用固定开销约 13-14K tokens，其中约 93% 是 Codex 内置系统提示（压不掉）
• 所以省额度靠减调用次数，不靠减字
• 默认精简模式：自动追加「正文 300 字以内，代码/命令/表格不计」
• -Full 关掉限制

实测：144 次调用共 41.6M 输入 tokens，其中 95.4% 命中缓存。

已知坑

踩过的都写进 SKILL.md 了，几个常见的：

• codex exec resume 不支持 -s，要用 -c "sandbox_mode=..."
• resume 不传 sandbox 会重置成 read-only，写文件前必须显式指定
• codex resume（TUI 版）需要真终端，脚本里用会报 stdin is not a terminal，要用 codex exec resume
• 从 stdout 提取答案在子进程里不稳定，改成从 rollout 文件读
• 出口 IP 被 Cloudflare 拦时报 403 且 cf-ray 结尾是 -HKG，需要代理
• 流式通道会间歇卡死（启动 3–5 秒后 jsonl 停止增长、CPU 归零），长任务基本必挂 —— 用 codex-watch.ps1 超时重试，或把任务拆小
• -Model 默认写死 gpt-6.1-sol，模型下线就报 404，用 -Model <可用模型> 覆盖

授权

MIT