skills/codex-collab/QUICK_REF.md

Codex Collaboration Skill - 快速参考卡

快速决策流程

                    ┌─────────────────┐
                    │   用户需求      │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  是查找/定位？  │
                    └────────┬────────┘
                      是/    │   \否
                       /     │    \
                      ▼      │     ▼
            ┌──────────┐    │    ┌──────────────┐
            │ 调 Codex │    │    │ 评估复杂度   │
            │ 搜索定位 │    │    └──────┬───────┘
            └──────────┘    │           │
                            │     ┌─────┴─────┐
                            │     ▼           ▼
                            │   简单      中等/复杂
                            │     │           │
                            │     ▼           ▼
                            │  直接执行  ┌─────────┐
                            │           │ 调 Codex│
                            │           │ 分析方案│
                            │           └─────────┘
                            │

常用命令

1. 代码搜索/定位

codex(
    PROMPT="搜索与【功能描述】相关的代码",
    cd="/project",
    sandbox="read-only"
)

2. 需求分析

codex(
    PROMPT="分析需求：{用户需求}",
    cd="/project",
    sandbox="read-only"
)
# 保存 SESSION_ID

3. 继续讨论

codex(
    PROMPT="关于你的方案，{疑问/讨论点}",
    cd="/project",
    SESSION_ID="上次的SESSION_ID",
    sandbox="read-only"
)

4. 请求代码原型

codex(
    PROMPT="提供代码原型（unified diff patch）：{功能说明}",
    cd="/project",
    SESSION_ID="上次的SESSION_ID",
    sandbox="read-only"
)

5. 代码审查

codex(
    PROMPT="审查代码：{改动说明}",
    cd="/project",
    SESSION_ID="之前的SESSION_ID"
)

参数速查表

参数	常用值	说明
cd	项目路径	必选，必须指向存在的目录
sandbox	"read-only"	推荐，最安全
SESSION_ID	之前的ID	多轮对话必传
return_all_messages	True/False	是否需要详细推理过程

安全检查清单

调用 Codex 前检查：

• cd 参数是否正确
• 是否需要使用 SESSION_ID 继续
• sandbox 是否设置为 "read-only"
• 是否明确要求 unified diff patch

调用 Codex 后检查：

• 是否保存了返回的 SESSION_ID
• success 字段是否为 true
• 是否需要验证 Codex 的建议

常见场景

场景	调用 Codex	Claude Code
查找代码	✅ 搜索定位	-
理解代码	✅ 分析解释	-
Bug定位	✅ 调试分析	-
需求分析	✅ 分析方案	-
功能设计	✅ 设计方案	讨论完善
代码实现	❌ 不用	✅ 编写代码
代码审查	✅ 审查代码	根据意见调整

最佳实践

DO ✅

• 始终追踪 SESSION_ID
• 使用 sandbox="read-only"
• 保持批判性思维
• 完成编码后立即审查
• 明确要求 unified diff

DON'T ❌

• 盲目接受建议
• 让 Codex 直接改代码
• 忘记保存 SESSION_ID
• 跳过审查环节
• 使用 danger-full-access

会话状态跟踪

# 建议在会话开始时创建变量
codex_session = {
    "session_id": None,
    "stage": "init",  # init | analysis | design | review
    "context": {}
}

# 每次调用后更新
def update_session(result):
    codex_session["session_id"] = result.get("SESSION_ID")
    # ...

错误处理

result = codex(...)

if not result.get("success"):
    # 处理错误
    print(f"Error: {result.get('error')}")
    # 可能的恢复策略：
    # 1. 检查 cd 路径
    # 2. 检查 Codex 是否安装
    # 3. 尝试不传 SESSION_ID 重新开始