executor-capability-gate

---
name: executor-capability-gate
description: "Fork Overlay：外部模型调用前置检查门控。调用 Codex/Gemini 之前运行五项检查，防止调用失败浪费时间。使用时机：任何调用外部模型（Codex [C]、Gemini [G]）之前自动运行。"
---

# Executor Capability Gate — 外部调用前置检查

> **Codex 洞察（P8，新增项）**：调用外部模型前做前置检查比"自动路由"更实用。
> 5 项检查防止无效调用，是 P7 Codex-first Executor 的前置依赖。

---

## 五项前置检查

### Check 1: CLI 安装检查

```bash
# Codex
command -v codex &>/dev/null
echo "exit: $?"  # 0=已安装, 1=未安装

# Gemini
command -v gemini &>/dev/null
```

**失败处理**：
```
❌ Codex CLI 未安装
   安装命令：npm install -g @openai/codex
   或：bun install -g @openai/codex
```

### Check 2: 登录状态检查

```bash
# Codex - 检查凭据文件是否存在（codex --version 无需登录，不能用于验证）
[ -f ~/.codex/auth.json ] && echo "OK" || echo "NOT_LOGGED_IN"

# Gemini
gemini --version 2>&1 | grep -q "version" && echo "OK" || echo "NOT_LOGGED_IN"
```

**失败处理**：
```
❌ Codex 未登录（~/.codex/auth.json 不存在）
   登录命令：codex  (首次运行引导登录)
```

### Check 3: 网络连通性检查

```bash
# 检查网络可达性（仅连通性，不含认证——凭据走 auth.json，非 OPENAI_API_KEY）
curl -s --max-time 5 "https://api.openai.com" -o /dev/null -w "%{http_code}"
# 非 000 = 网络可达（包括 401 均表示网络通）
# 000 = 网络不可达
```

**失败处理**：
```
❌ 网络不可达（curl 返回 000）
   跳过 Codex 调用，退回 Claude 执行
```

### Check 4: Rate Limit 检查

```bash
# 检查最近 Codex 调用记录（简单本地记录）
# 注意：~/.codex/.last_call 由本 gate 在调用通过后写入（见门控输出格式末尾）
LAST_CALL=$(cat ~/.codex/.last_call 2>/dev/null || echo "0")
NOW=$(date +%s)
ELAPSED=$((NOW - LAST_CALL))

if [ $ELAPSED -lt 60 ]; then
  echo "RATE_LIMITED: 距上次调用 ${ELAPSED}s，建议等待至少 60s"
fi

# 调用通过后，写入时间戳（防止频繁调用）：
# echo $(date +%s) > ~/.codex/.last_call
```

**重要**：调用 Codex 成功完成后，必须执行 `echo $(date +%s) > ~/.codex/.last_call` 以更新记录，否则 rate limit 检查永远通过（文件不存在时 ELAPSED 极大）。

### Check 5: 任务适配性检查

根据任务特征快速判断（详细决策逻辑见 `codex-first-executor` skill）：

| 任务特征 | Codex 适合？ |
|---------|------------|
| 大量机械 patch（格式化、重命名） | ✅ 适合 |
| 高风险改动（auth、payment、migration） | ❌ 不适合 |
| 纯分析/research 任务 | ✅ 适合 |
| 视觉/UI 任务 | ❌ 不适合 |
| 需要项目上下文的重构 | ⚠️ 谨慎 |

---

## 门控输出格式

每次外部调用前输出检查结果：

```
🔍 Executor Capability Gate — Codex 检查

  ✅ CLI 已安装 (codex v0.1.x)
  ✅ 已登录
  ✅ 网络正常 (API 200)
  ✅ Rate limit 正常 (距上次 120s)
  ✅ 任务适合 Codex（批量 patch）

  → 允许调用 Codex
```

或：

```
🔍 Executor Capability Gate — Codex 检查

  ✅ CLI 已安装
  ❌ Rate limit（距上次仅 30s）
  ⚠️  任务高风险（涉及 auth/payment）

  → 跳过 Codex，由 Claude 执行
     理由：rate limit + 高风险任务不适合外部执行器
```

---

## 与 [C] [G] 参数的集成

当 `ce:review [C]` 或 `ce:brainstorm [C]` 被调用时，在派发 Codex 任务前自动运行本 gate：

```
用户调用 ce:review [C]
    ↓
Executor Capability Gate 检查 Codex
    ├─ 全部通过 → 正常派发 Codex 审核
    ├─ 部分失败 → 提示原因，询问是否降级到 Claude-only
    └─ 全部失败 → 自动降级，告知用户
```

---

## 检查缓存

Gate 结果缓存 5 分钟（同一会话内）：

```bash
GATE_CACHE=~/.codex/.gate_cache
# stat -c %Y 仅 Linux 有效；macOS 用 -f %m；用两者 fallback 实现跨平台
CACHE_MOD=$(stat -c %Y "$GATE_CACHE" 2>/dev/null || stat -f %m "$GATE_CACHE" 2>/dev/null || echo 0)
CACHE_AGE=$(( $(date +%s) - CACHE_MOD ))

if [ $CACHE_AGE -lt 300 ]; then
  # 使用缓存结果，不重新检查
  cat $GATE_CACHE
else
  # 重新检查并写入缓存
  run_gate_checks > $GATE_CACHE
fi
```