windmill 仓库本地 Codex 代码审查local-review-codex Skill 使用与原理全解析【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill导读本文围绕 windmill 仓库中面向 Codex CLI 的本地代码审查技能 .agents/skills/local-review-codex/SKILL.md 展开讲解如何在本机、在 push 之前用与 CI 中codex-pr-reviewGitHub Action 完全一致的审查策略与推理强度对你尚未推送的改动已提交 未提交执行一次独立的 Codex 审查。读完本文你将掌握该技能的前置条件、运行命令、run.sh脚本的实现原理、共享审查策略REVIEW.md的裁决与分级规则以及如何把审查结果无失真地转述给团队成员。一、背景CI 中的 Codex 自动 PR 审查windmill 仓库在 CI 中部署了 Codex 自动审查流水线定义于 .github/workflows/codex-pr-review.yml。该工作流在 PR 满足条件时ready_for_review/opened/synchronize事件非 draft、非 fork执行以下关键步骤配置认证优先使用OPENAI_API_KEY其次使用CODEX_AUTH_JSON二者都未配置则跳过审查检出 PR merge 分支并在非 fork 场景下通过 backend/substitute_ee_code.sh 注入 EE 私有代码安装openai/codex0.153.4并写入CODEX_HOME/config.toml由 Node 脚本生成pr-review-context.md内含仓库名、PR 号、Base/Head SHA、PR 标题与正文、变更提交与变更文件命令git log --oneline、git diff --stat、git diff --unified0以及最多 20 条历史评论调用codex exec使用模型gpt-5.6-sol、model_reasoning_effortxhigh非 fork 场景沙箱为danger-full-accessfork 场景降级为workspace-write并在无网络沙箱中运行最后通过actions/github-script将审查输出以 PR 评论形式发布并做凭据脱敏对 API Key、auth JSON 中的嵌套 token 做[REDACTED]处理。CI 侧的提示词由 REVIEW.md共享策略与 .github/codex/pr-review.prompt.md输出格式拼接而成。这条流水线的问题在于它只在 PR 创建之后运行发现问题时修改成本已较高。二、local-review-codex把 CI 审查搬到 push 之前local-review-codex技能正是为解决上述痛点而设计它在本地运行与 CI 完全相同的审查但范围限定为你尚未推送的工作从而在 PR 存在之前就捕获 CI 会标记的问题。正如 AGENTS.md 中 Code review 一节所述对于「镜像codex-pr-reviewGitHub Action、针对未推送工作已提交 未提交的 Codex 审查」应使用/local-review-codex技能它与 CI Action 共用同一份REVIEW.md策略与xhigh推理强度模型为gpt-6-astra而非 Action 的gpt-5.6-sol且要求codexCLI 0.153.4。该技能在技能目录中有两个等价入口.agents/skills/local-review-codex/SKILL.md与 .claude/skills/local-review-codex/SKILL.md后者为符号链接指向前者Claude Code 与 Codex 各自按目录自动发现同一份技能。2.1 与 CI 完全一致的部分技能文档明确列出了与 CI 的「一致性」这是它价值的前提策略使用仓库根目录的 REVIEW.md严重性分级、公开表面检查清单、AGENTS.md 合规、测试覆盖评估推理强度model_reasoning_effortxhigh输出格式以## Codex Review开头的 Markdown每条发现以 P0 / P1 / P2 分级并携带 file:line 定位。2.2 与 CI 的差异本地独有维度CIcodex-pr-review.yml本地local-review-codex模型gpt-5.6-solgpt-6-astra审查范围已推送的 PR diff当前分支 vs main 的 merge-base包含未提交改动沙箱danger-full-access临时 runnerread-only只读不修改工作区上下文冷启动的 GitHub Action 进程codex exec独立冷进程不锚定当前对话模型差异并非疏漏gpt-6-astra已确认在codex login使用的 ChatGPT 认证上可用而 CI 使用OPENAI_API_KEY认证codex-pr-review.yml 中它优先于CODEX_AUTH_JSON该认证层级对gpt-6-astra尚未验证因此 CI 继续使用gpt-5.6-sol待 API 访问确认后再迁移。CLI 版本两边相同均为 0.153.4只有模型不同。三、前置条件运行该技能前需要满足codexCLI 0.153.4并通过codex login完成认证。注意环境中若存在OPENAI_API_KEY其优先级高于codex login存储的 ChatGPT 凭据可能无法触达gpt-6-astra详见下文脚本原理。旧版 CLI 会以 requires a newer version of Codex 拒绝该模型run.sh会在执行前先做版本检查。升级命令npm install --global openai/codex0.153.4全局安装可能需要在前面加sudo。该版本号与 .github/workflows/codex-pr-review.yml 中的 pin 保持一致。git fetch基础分支如果 base ref 已过期先拉取确保 merge-base 计算准确。四、运行方法bash .agents/skills/local-review-codex/run.sh # 默认以 main 为基准审查 bash .agents/skills/local-review-codex/run.sh base # 以其他 base ref 为基准审查两个必须注意的细节必须用bash调用或直接执行脚本本身因为脚本依赖set -o pipefail在 Debian/Ubuntu 上sh实际是 Dash会导致脚本失败。main不是本地分支时的回退在全新的单分支检出例如 CI 检出的工作区中通常只有origin/main而没有本地mainrunner 会自动回退到origin/main。脚本整体流程计算BASE_SHA git merge-base HEAD base将REVIEW.md连同指向git diff BASE_SHA的 diff 上下文会折叠进未提交的编辑喂给 Codex输出审查结果。脚本只写临时文件工作区不留任何痕迹。五、run.sh 脚本实现原理实现位于 .agents/skills/local-review-codex/run.sh约 114 行 Bash以下按执行顺序拆解其关键设计。5.1 版本前置检查CODEX_VER$(codex --version 2/dev/null | grep -oE [0-9]\.[0-9]\.[0-9] | head -1 || true) if [ -n $CODEX_VER ] [ $(printf %s\n%s\n $CODEX_MIN $CODEX_VER | sort -V | head -1) ! $CODEX_MIN ]; then echo codex $CODEX_VER is too old for $MODEL (need $CODEX_MIN)... 2 exit 1 fi旧版 CLI 拒绝模型时的报错信息从不点名「CLI 版本过旧」这一真实原因因此脚本在 exec 之前先做版本检查避免错误以难以诊断的形式暴露。|| true的用意是当--version输出格式无法解析时此时无法判断版本必须放行到 exec 而不是在set -e下中止整个审查。5.2 OPENAI_API_KEY 冲突警告if [ -n ${OPENAI_API_KEY:-} ]; then echo warning: OPENAI_API_KEY is set and takes priority over codex login credentials; $MODEL may be unavailable on that tier. 2 ficodex优先使用OPENAI_API_KEY而非codex login存储的 ChatGPT 凭据而该认证层级对gpt-6-astra未确认可用——失败信息会指向模型而不是真正选中它的认证方式所以脚本提前给出显式警告。5.3 base ref 解析与 merge-baseif git rev-parse --verify --quiet ${BASE_REF}^{commit} /dev/null; then BASE_COMMITISH$BASE_REF elif git rev-parse --verify --quiet origin/${BASE_REF}^{commit} /dev/null; then BASE_COMMITISHorigin/${BASE_REF} else echo Base ref $BASE_REF not found as $BASE_REF or origin/$BASE_REF. Try: git fetch origin $BASE_REF 2 exit 1 fi优先解析本地 ref回退到 remote-tracking ref两者都不存在时提示先git fetch origin base。BASE_SHA$(git merge-base HEAD $BASE_COMMITISH) HEAD_SHA$(git rev-parse HEAD) UNTRACKED$(git ls-files --others --exclude-standard)从 merge-base 计算 diff保证只审查本分支的改动。使用 base SHA 配合单 ref 的git diff会把未提交的工作区编辑一并纳入——但git diff永远看不到未跟踪文件因此脚本单独通过git ls-files --others --exclude-standard收集未跟踪文件避免整个新模块、新技能目录被静默跳过。5.4 无变更短路if [ $BASE_SHA $HEAD_SHA ] git diff --quiet $BASE_SHA [ -z $UNTRACKED ]; then echo No changes vs $BASE_REF — nothing to review. 2 exit 0 fi基准与 HEAD 相同、无已跟踪改动、且无未跟踪文件时直接宣告「无变更可审查」并正常退出。5.5 提示词组装与执行脚本用mktemp创建临时文件并用trap ... EXIT保证清理。提示词由三部分组成cat REVIEW.md共享审查策略全文内联追加的「Codex output format」段说明这是 PR 之前的本地审查、未跟踪文件不出现在git diff中需逐个cat阅读、输出必须以## Codex Review开头、每条发现标注 P0/P1/P2 与 file:line「Review context」段base/head SHA以及三条审查命令——git log --oneline $BASE_SHA..HEAD变更提交、git diff --stat $BASE_SHA变更文件、git diff --unified0 $BASE_SHA完整审查 diff含未提交编辑最后列出所有未跟踪文件路径。CI 侧这些内容来自生成的 context 文件本地采用内联追加的方式保证工作区干净——没有任何草稿文件落入仓库。执行调用codex exec \ -C $REPO_ROOT \ -m $MODEL \ -c model_reasoning_effortxhigh \ -s read-only \ -o $OUT \ - $PROMPT参数含义-C指定仓库根目录、-m指定模型gpt-6-astra、-c传入推理强度配置、-s read-only声明只读沙箱Codex 可以读 diff 和文件但不能修改工作区、-o指定输出文件、-从 stdin 读入提示词。最后把审查结果原样打印到 stdout。六、共享审查策略 REVIEW.mdREVIEW.md 是 CI 与本地共用的策略文件值得单独理解因为它决定了 Codex 的输出形态与分级标准。6.1 首行裁决审查必须从单行裁决开始三选一Good to merge无阻断问题且无值得提出的 nitMergeable, but should ideally address nits: 短列表无阻断项但有值得一看的 P2Should address issues before merging: 短列表至少一个 P0 或 P1。列表中的每一项必须与正文中的发现一一对应不得虚构、不得把阻断项只埋在正文里。6.2 严重性分级P0RCE、认证绕过、数据丢失、代码中的密钥、SQL 注入、路径穿越、公开表面上的认证破坏P1显著 bug、新公开表面缺少认证/授权检查、可能在异步路径上阻塞 I/O、竞态条件、对调用方可控参数缺少输入校验、可观察的性能回退P2模块放置错误、文档与代码不一致、半成品公开抽象pub fn#[allow(dead_code)]TODO、AGENTS.md 风格违规、命名与函数行为相悖。P0/P1 必须报告P2 仅在 diff「邀请」时报告新pub fn、新模块、新导出组件、有意义的重构。6.3 新公开表面检查清单对于 PR 引入的新pub fn/pub async fn/ 导出的 Svelte 组件 / 导出 prop需逐项核验认证/授权期望是否在文档注释中说明或在函数体内强制模块定位是否与其职责匹配检查//!模块注释是否半成品每个可能由调用方控制的参数是否有注入/穿越/溢出/NUL 字节防护。6.4 测试覆盖评估审查以「Test coverage」小节收尾按 diff 实际触碰的层级校准后端backend/下 Rust新逻辑期待 Rust 单元测试新增/修改 API handler、worker 步骤、队列/cron 行为或 DB 访问时还期待或注明集成测试的缺失前端frontend/下 Svelte/TS仓库一般不为 Svelte 组件写测试不要索要组件测试仅对新增纯逻辑工具类已有*.test.ts兄弟文件的类型如flowDiff、previousResults、copilot 逻辑标记测试缺失CI / 工作流 / 文档 / 纯配置不期待自动化测试并应明说让读者知道你考虑过这一点。随后说明合并前仍需哪些手动验证以段落描述场景与可观察结果若 diff 无可操作的应用内表面则如实说明。七、结果转述原则技能文档强调原样打印 Codex 输出不要重新总结或过滤——冷启动 Codex 一轮的价值恰恰在于浮现当前对话会话会「理性化掉」的问题。然后与用户共同决定是否在 push 之前处理发现。若需要 Claude 原生的审查视角可改用local-review技能.agents/skills/local-review/SKILL.md使用 branch-diff-reviewer 子代理本技能是其 Codex 对应物两者可以各跑一遍以获得相互独立的视角。local-review强调审查必须在全新上下文的子代理中运行而非当前会话内联执行其子代理提示词模板同样要求先读 REVIEW.md 与相关AGENTS.md再取 diffgh pr diff或git diff main...branch最后按固定输出格式给出## Code review与 P0/P1/P2 列表——与 local-review-codex 的输出约定同源便于两侧结果相互对照。八、最佳实践小结在非平凡改动上、push 之前运行bash .agents/skills/local-review-codex/run.sh让 CI 在 PR 阶段会标记的问题在提交前暴露。确认认证层可达模型以codex login的 ChatGPT 认证为主若环境变量中存在OPENAI_API_KEY留意脚本警告并确认该层级能访问gpt-6-astra。保持 base ref 新鲜必要时先git fetch origin main确保 merge-base 准确单分支检出下脚本会自动回退到origin/main。原样转述、独立决策将## Codex Review输出逐字呈现不替 Codex 过滤结论再与用户共同决策需要不同视角时与local-reviewClaude 子代理并行运行。通过本地提前审查配合 CI 中 codex-pr-review.yml 的双保险可以让每次 PR 进入人工评审前就已通过一致策略的机器审查显著压缩评审轮次与返工成本。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考