SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场codex-implementation

codex-implementation

编程与开发

查看项目

更新于 10-16 04:23

技能介绍

Codex Implementation 是一个面向脚本或智能体编排框架的技能，用来把 OpenAI Codex CLI 当作会改动代码的智能体来驱动。它的核心约定是：显式范围、显式验收标准、显式验证、显式输出格式，最后由使用者自己核对 diff。

适用场景

适合规格清晰的批量或机械性实现任务，例如迁移、重构、定义明确的功能开发；适合用户或模型路由策略明确要求交给 gpt-5.6 / Codex 的工作；也适合并行实现的多条工作线中由 Codex 承担其中一条的场景。不适合需要使用者自身会话上下文、而 Codex 无法看到的任务（此时应改写成自包含的提示词），也不适合对品味要求高的 UI 或文案工作，除非路由策略明确指向它。

运行前检查

  • codex --version：确认 CLI 已安装；缺失则停止并报告。
  • git status --short：了解起始状态。
  • git switch -c codex/<task-slug>：当改动并非小事时，在新分支上工作。

标准调用形式

codex
-a never
exec
-m gpt-5.6-sol
-c model_reasoning_effort='"high"'
-s workspace-write
-C "$PWD"
--output-last-message /tmp/codex-final.txt
"<implementation prompt — see contract below>"
</dev/null 2>/tmp/codex-progress.log

关键机制

  • 参数位置很重要。-a（审批策略）和 --search 是全局参数，必须放在 exec 之前；0.142.5 会拒绝 codex exec -a never。等价的 exec 后写法为：-c approval_policy='"never"'、-c web_search='"live"'。-s 在全局和 exec 上都可用，但像 exec review 这样的子命令只接受全局形式。
  • stdin 陷阱。codex exec 会读取 stdin，若 stdin 处于打开但为空的状态，可能永久挂起（零输出、零 CPU）。除非有意通过管道传入数据，否则始终追加 </dev/null。
  • stdout 与 stderr。最终智能体消息输出到 stdout；进度、思考、工具活动输出到 stderr。可用 2>/dev/null 抑制，或重定向到日志。
  • --full-auto 已弃用（在 0.142.5 帮助中已隐藏）。应改为显式写出 -s workspace-write 加 -a never。
  • Git 检查。Codex 拒绝在 git 仓库之外运行。--skip-git-repo-check 仅用于可丢弃的临时目录。

参数参考

  • 模型：-m gpt-5.6-sol。codex debug models 可列出目录。纯 gpt-5.6 无效；变体包括 -sol（前沿、默认）、-terra（均衡）、-luna（快速/低成本）。
  • 推理强度：-c model_reasoning_effort='"low|medium|high|xhigh"'，TOML 字符串需要加引号。
  • 沙箱：-s read-only / -s workspace-write / -s danger-full-access，实现任务用 workspace-write。
  • 关闭审批：codex -a never exec …，全局参数，放在 exec 前。
  • 工作目录：-C /path/to/repo，设置智能体根目录。
  • 额外可写目录：--add-dir /path，与工作区并列。
  • 网页搜索：codex --search exec … 或 -c web_search='"live"'，全局参数，放在 exec 前。
  • 图像输入：-i /tmp/shot.png，可重复。
  • 最终消息写入文件：-o file / --output-last-message file，确定性捕获。
  • 受 schema 约束的输出：--output-schema schema.json，为最终响应指定 JSON Schema。
  • JSONL 事件流：--json，在 stdout 上输出生命周期事件而非格式化输出。
  • 不保留会话：--ephemeral，禁止后续 resume。
  • 配置档：-p <name>，加载 $CODEX_HOME/<name>.config.toml。
  • 仓库之外运行：--skip-git-repo-check，仅用于临时目录。

沙箱模式

  • read-only：只允许检查，用于试运行与分析。
  • workspace-write：可编辑工作区、运行本地命令，网络仍然受限，是实现任务的默认模式。
  • danger-full-access：无文件系统/网络限制，只能在一次性 VM/容器中使用。

workspace-write 内的网络：可通过 -c sandbox_workspace_write.network_access=true 开启，或在运行前预先安装依赖。

推理强度选择与超时预算

  • low：机械性编辑、已知修复，3–15 分钟。
  • medium：常规实现，5–30 分钟。
  • high：多文件工作、并发、迁移，10–60 分钟。
  • xhigh：困难调试、架构、高风险变更，20–120 分钟。

Codex 不产生中间 stdout——过早被终止就意味输出静默为空。应在后台以宽裕的超时运行，或用如下方式包装：/usr/bin/perl -e 'alarm shift; exec @ARGV' 3600 codex …。

提示词契约

GPT-5 级别 Codex 模型对可操作的明确性反应良好。每个实现提示词都应说明四件事：

  1. 实现 <任务，或“./task.md 中描述的变更”>。
  2. 范围：
    • 仅编辑 <路径/通配符>。不要触碰 <排除项>。
    • 不要改动 <公共 API / schema / 生成文件>。
  3. 验收标准：
    • <可观察行为 1>
    • <可观察行为 2>
  4. 验证：
    • 运行 <确切测试命令>。
    • 若测试无法运行，说明确切的阻碍。
  5. 最终消息：
    • 仅用项目符号列出——变更文件、运行的测试、残留风险。

反例：Fix the auth bug.（没有症状、范围、测试或输出契约。）

如需机器可解析结果，添加 --output-schema 并要求“最终响应必须匹配该 schema”，然后解析 --output-last-message 文件。

传入上下文

  • 指向路径，不要粘贴文件："Read ./docs/api.md and ./src/server. Implement the described behavior."
  • 当不可变性重要时通过管道传入快照：git diff | codex exec "…"（stdin 会作为 <stdin> 块追加）。
  • 从文件读取整个提示词：codex exec - < task.txt。
  • 图像：-i mockup.png（可重复）。
  • AGENTS.md 会自动发现：先 ~/.codex/AGENTS.md（全局），再从项目根目录向下到 cwd；每一层级 AGENTS.override.md 优先。

会话恢复

codex exec resume --last "fix the race conditions you found" </dev/null codex exec resume <SESSION_ID> "continue; run the narrowest relevant tests" </dev/null

--last 选择当前 cwd 的最新会话（--all 可选任意目录）。对话上下文和此前的工具观察会延续；shell 状态和环境变量变更不会延续——需重新声明关键约束。恢复时不要添加配置参数；会话保留其模型/强度/沙箱。

运行之后——始终验证

  • 检查退出码；非零则先检查 stderr 日志再信任任何东西。
  • git diff --stat && git diff：阅读改动，确认范围得到遵守。
  • 自己运行测试；不要只听 Codex 的说法。
  • 如实报告：把已验证的内容与 Codex 声称的内容分开。

故障排查

  • 挂起、零输出、零 CPU：原因是 stdin 打开但为空；追加 </dev/null。
  • 完成后 stdout 为空：可能输出到了 --output-last-message，或运行失败；检查退出码与 stderr 日志。
  • unexpected argument '-a' / '--search'：全局参数被放在了 exec 之后；移到 exec 前，或改用 -c 等价形式。
  • npm/网络被沙箱拒绝：workspace-write 限制网络；预先安装依赖，或用 -c sandbox_workspace_write.network_access=true。
  • 拒绝运行：不在 git 仓库中；git init 或使用 --skip-git-repo-check（仅限临时目录）。
  • 模型/强度被拒绝：目录不匹配；使用 codex debug models。