Codex Skill

核心用法

Codex Agent Skill 是一套完整的自动化编码工作流系统，围绕 OpenAI Codex CLI 构建，提供从任务初始化、代码生成、质量检查到 PR 合并的闭环管理。

执行模式：

• Quick Mode：适用于单文件修复、简单分析等小型任务，使用 codex exec --full-auto 非交互式执行，通过 background=true + pty=true 实现后台运行与输出捕获，采用轮询机制（每5分钟）替代硬超时，避免长任务被误杀
• Full Mode：适用于功能开发、复杂重构，通过 git worktree 创建隔离分支，配合 tmux 会话实现持久化运行，支持 mid-task steering（任务中实时干预）

关键工作流步骤：
1. 工作树隔离：每个任务独立分支与目录，避免冲突
2. tmux 会话管理：pipe-pane + stdbuf -oL 实现全量日志捕获与实时 tail 监控，解决 capture-pane 滚动缓冲区限制（仅约2000行）
3. 任务注册：JSON 格式的 active-tasks.json 持久化跟踪任务状态、重试次数、检查项
4. 智能监控：检测重复错误（循环检测）、文件变更停滞（疑似卡住）、12小时无输出自动告警
5. 质量门禁：PR 创建、无冲突、CI 通过、AI 交叉审查、UI 截图（如适用）
6. 多模型审查：强制使用不同模型（如 Claude 审 Codex）发现安全漏洞与过度工程
7. 智能重试：分析失败类型（上下文溢出/方向错误/信息缺失/CI失败），针对性调整提示词，最多3次后人工升级

高级特性：

• 推理 effort 控制（low/medium/high）匹配任务复杂度
• 分级沙盒：read-only → workspace-write → danger-full-access
• JSON Lines 结构化输出与文件重定向
• resume --last 会话恢复

显著优点

• 生产级可靠性：日志持久化 + 退出码捕获 + 工作树隔离，避免状态污染与输出丢失
• 长任务友好：轮询扩展机制支持数小时任务，不依赖硬超时猜测
• 可干预性：tmux send-keys 支持实时纠正方向、补充上下文、聚焦文件范围，无需重启代理
• 质量闭环：多模型交叉审查强制发现单模型盲区，DoD 检查清单防止半成品 PR
• 并行扩展：多 worktree + 多 tmux 会话天然支持并发开发

潜在局限

• 基础设施依赖：需要预装 codex CLI、tmux、gh CLI，且对工作流工具有深度依赖
• 容器/沙盒假设：--dangerously-bypass-approvals-and-sandbox 模式依赖运行环境已隔离，裸机运行存在安全风险
• 输出截断风险：Quick Mode 内存输出受 PI_BASH_MAX_OUTPUT_CHARS 限制，长日志可能丢失早期内容
• Agent 范围限制：process 会话隔离，多 Agent 场景下需额外协调任务可见性
• 重试复杂度：失败分析依赖正则/模式匹配，复杂故障仍需人工介入

适合人群

• 需要批量处理独立编码任务的平台/工具团队
• 追求端到端自动化、愿意投入工作流基础设施建设的工程组织
• 已有容器化/沙盒化 CI 环境，可安全开放文件系统写权限的团队

常规风险

| 风险类别 | 具体表现 | 缓解措施 |

|---------|---------|---------|

| 权限滥用 | `danger-full-access` 或 bypass 模式下的网络/系统操作 | 严格限制在隔离容器/VM，禁止裸机使用 |

| 代码质量衰退 | 自动化生成代码未经审查直接合并 | 强制多模型审查 + CI 门禁 |

| 资源泄漏 | tmux 会话、worktree、临时文件未清理 | Registry 跟踪 + Step 8 清理流程 |

| 无限循环 | 智能重试策略失效，token 浪费 | 硬限制3次重试 + 12小时无输出告警 |

| 敏感信息泄露 | 错误日志中捕获的环境变量、密钥 | 日志过滤 + 沙盒网络隔离 |