philo-veritas Codex 协作 Skill
核心理念
在任何编码过程中，始终思考当前任务是否可以借助 codex 获得更全面、更客观的分析。Claude 负责架构设计与全局把控，Codex 负责代码生成细节和独立审查视角——两个独立推理路径交叉验证，暴露单一视角的盲区。
前置要求
- Python 3.12+
- Codex CLI 已安装且
codex命令可用（版本 >= v0.61.0）
调用 Codex
通过 Bash 执行内置脚本 scripts/codex_exec.py，脚本路径相对于此 SKILL.md 所在目录。
python <skill-dir>/scripts/codex_exec.py \
--prompt "你的指令" \
--cd /path/to/repo \
[--sandbox read-only] \
[--session-id <uuid>] \
[--all-messages]
参数
| 参数 | 必选 | 默认值 | 说明 |
|---|---|---|---|
--prompt |
是 | - | 发送给 codex 的任务指令 |
--cd |
是 | - | 工作目录根路径（必须存在，否则静默失败） |
--sandbox |
否 | read-only |
read-only / workspace-write / danger-full-access |
--session-id |
否 | 空（新会话） | 传入上次返回的 session_id 可继续对话 |
--all-messages |
否 | false | 包含完整推理过程（用于追踪 codex 的推理和工具调用） |
--model |
否 | 空 | 仅在用户明确指定时使用 |
--profile |
否 | 空 | 仅在用户明确指定时使用 |
--yolo |
否 | false | 跳过沙箱，慎用 |
--image |
否 | 空 | 逗号分隔的图片路径 |
安全约束
默认且推荐使用 --sandbox read-only。严禁 codex 对代码进行实际修改——需要代码时只让它给出 unified diff patch。这是整个协作模式的安全基石：codex 提供思路，你来执行。
返回值
脚本输出 JSON 到 stdout：
{"success": true, "session_id": "uuid-string", "agent_messages": "codex 的回复"}
{"success": false, "error": "错误描述"}
每次调用后检查 success 字段做错误处理。
会话管理
每次成功调用都会返回 session_id。在对话中维护一个变量 CODEX_SESSION_ID：
- 首次调用：不传
--session-id，从返回值中提取并记住session_id - 后续调用：传入
--session-id <CODEX_SESSION_ID>以延续上下文 - 切换到不相关的新任务时：丢弃旧 session_id，开启新会话
始终追踪 CODEX_SESSION_ID，避免会话混乱。
协作工作流
1. 需求分析 — 让 codex 补充你的盲区
对用户需求形成初步分析后，将需求和初始思路告知 codex，要求它完善需求分析和实施计划。
示例 prompt：
用户需求：{需求描述}
我的初步分析：{你的分析}
请从以下角度补充：
1. 我的分析是否有遗漏的边界情况？
2. 实施计划是否合理？有什么更优方案？
3. 有哪些潜在风险？
2. Plan 审查 — 让 codex 审查实施计划
在 plan mode 下生成计划后，可以让 codex 从独立视角审查。codex 运行在独立进程中，无法访问你的对话上下文，所以发送给 codex 的 prompt 必须内嵌完整的 plan 内容，不能只说"请审查当前计划"。
构建 prompt 的步骤：
- 从当前对话上下文中提取完整的 plan 文本
- 将 plan 文本嵌入 prompt，连同项目背景一起发送
- 明确要求 codex 从哪些角度审查
示例 prompt：
请审查以下实施计划，给出你的评估和改进建议。
## 项目背景
{项目简要描述和当前需求}
## 实施计划
{完整的 plan 内容，逐条列出}
## 审查要点
1. 步骤顺序是否合理？是否有依赖关系被忽略？
2. 是否有遗漏的关键步骤？
3. 各步骤的技术方案是否恰当？有无更优选择？
4. 是否存在潜在的风险或副作用？
5. 预估的改动范围是否准确？
codex 反馈后，批判性地评估其意见，合理的建议更新到 plan 中，不合理的说明理由忽略。
3. 代码原型 — 用 codex 的实现作为参考（可选）
编码前向 codex 索要代码实现原型。这不是"让 codex 写代码然后直接用"，而是获取一个独立的实现思路，然后你重写为生产级代码。
- 要求 codex 仅给出 unified diff patch，严禁对代码做任何真实修改
- 使用
--sandbox read-only确保安全 - 拿到原型后，以此为逻辑参考，重写为高可读性、高可维护性的生产代码
示例 prompt：
请为以下需求给出代码实现原型，仅输出 unified diff patch，不要做任何真实修改：
{需求描述}
涉及文件：{文件列表}
4. 代码审查 — 编码完成后立即执行
每次完成编码后，立即让 codex 审查改动。独立的 AI 审查视角能捕获你自己不容易发现的问题。
通过 Bash 执行内置包装脚本 scripts/codex_review.py 调用 codex review。脚本会自动过滤 codex 输出中 2000+ 行的工具日志和中间推理，只返回审查摘要和 "Full review comments" 区块。审查标准参考 references/review_guidelines.md。
codex review 通常需要 2-5 分钟。调用时务必设置 Bash timeout 为 300000（5 分钟），避免被自动转为后台任务。
常用命令：
# 审查未提交改动（staged + unstaged + untracked）
python <skill-dir>/scripts/codex_review.py --uncommitted
# 审查指定项目的未提交改动
python <skill-dir>/scripts/codex_review.py --cd /path/to/repo --uncommitted
# 审查相对于某分支的改动
python <skill-dir>/scripts/codex_review.py --base main
# 审查某次提交
python <skill-dir>/scripts/codex_review.py --commit <sha>
所有参数直接透传给 codex review。当前 codex review 版本的 help 可能仍显示可传 prompt，但实测 --uncommitted 与 positional prompt 不能同用；审查未提交改动时不要追加自定义 prompt。
codex review vs codex exec 的区别：
codex review（通过scripts/codex_review.py调用）是专用审查命令，自动获取 diff 内容，输出已过滤codex review不返回session_id，不支持多轮对话- 需要多轮讨论审查意见时，仍用
codex exec（通过codex_exec.py脚本）继续对话
续接审查讨论：
拿到审查结果后，如需追问细节，用 codex_exec.py 开启新会话，将审查结论嵌入 prompt：
以下是 codex review 对本次改动的审查意见：
{粘贴 review 输出}
我想针对以下问题深入讨论：
{具体问题}
5. 独立思考 — 尽信书则不如无书
codex 只能给出参考，你必须有自己的判断，甚至需要对 codex 的回答提出质疑。你与 codex 的最终使命是达成全面、精准的意见，所以要通过不断争辩来逼近更好的方案：
- 批判性评估每一条建议——它可能遗漏了上下文，也可能过度谨慎
- 不同意就说明理由，把你的反驳再发给 codex 继续讨论（利用 session_id 保持上下文）
- 最终决策权在你这里
何时主动建议使用 Codex
不必等用户开口。在以下场景应主动提议：
- 复杂架构决策：涉及多模块的改动、API 设计、数据模型变更
- Plan 审查：在 plan mode 下完成计划后，建议让 codex 审查步骤完整性和技术方案
- 编码完成后的审查：任何超过 50 行的代码改动都值得让 codex 看一眼
- 数据密集型脚本：包含大量硬编码数据、统计数字或测试 fixture 的文件——人容易对数字脱敏，AI 不会
- 棘手的 bug：单独排查无果时，让 codex 从不同角度分析
- 精准定位问题：需要快速缩小排查范围时
- 代码原型快速获取：需要在多种实现方案中做选择时
主动建议时简洁说明原因，比如："这个改动涉及 3 个模块的联动，建议让 codex 从另一个角度审查一下，要不要试试？"
错误处理
- 如果脚本返回
success: false，检查error字段并告知用户 - 常见问题：codex CLI 未安装、API key 未配置、网络超时
- 遇到
session_id获取失败时，不要重试同一个 session，直接开新会话