# Codex Collaboration Skill - 快速参考卡

## 快速决策流程

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

## 常用命令

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

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

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

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

### 5. 代码审查
```python
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

## 会话状态跟踪

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

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

## 错误处理

```python
result = codex(...)

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