软件技术分享

关于电子游戏的方方面面

Codex：出 PR 说明之前，用 diff 生成变更摘要的固定提示

作者

出 PR 说明前，先自己取出相对 base 的完整分支 diff，再用固定提示让 Codex 只写标题和正文。官方没有这一条独立命令。人审后再用网页或 gh 开 PR。

要点

正文

场景

分支改完了。中间又跟了两轮“再补一个边界条件”。你随口让 Codex 写一份 PR 说明，准备去开单。

标题先回来。有时只写了最后那处拼写修正；公开工单里还出现过更离谱的题目，比如把聊天里一句拒绝写进了标题。正文看起来结构完整，Testing 一段却写“全部检查已通过”。你点开才想起来，这些检查这轮根本没跑。还有一种更烦的：Settings 里写过的指示原文，被整段贴在 PR 正文末尾。

这是范围跑偏的示意，不是某次逐字实测。模型在写说明时，很容易只盯着最近一句对话，或把“生成说明”理解成“顺便把 PR 也开了”。

这篇只攻一件事：改动已经在分支上了，怎么先用 diff 生成变更摘要和 PR 说明，并且尽量只出文字。审查代码，按 CI 日志修失败，或把测试文件写成完成定义，这里都不展开。

可跟做步骤／可抄工作流

下面这几步，把官方零散能力和公开反例拼成一条“先出说明、不动代码”的路径。官方目前没有单独的“用 diff 写 PR 说明”向导，也没有叫 /pr 的现用命令。

先选定入口，开 PR 留给网页或 gh

官方入口是 ChatGPT 桌面应用里的 Codex、Codex IDE 扩展，以及 Codex CLI（包括 codex exec）。在 Cursor 里用时，走的是 Codex 扩展的聊天框，不要和 Cursor 自带的 Agent 混成一个按钮。

真正开 PR 时，用 GitHub 网页或 GitHub CLI 的 gh pr create。gh 是 GitHub CLI。用法建议是人来执行，或另开一条已经明确授权的任务，不要和“只写说明”捆在同一轮。

自己先取出要摘要的那一段 diff

不要把“帮我写个 PR”丢给按钮去猜。用法建议（这是 Git 常规）：已经暂存的改动用 git diff --cached；相对主分支用三点语法 git diff ...HEAD，只覆盖 merge base 到当前头的净变更。两点语法 git diff main，或只 diff 最新一次 commit，可能混进无关历史，也可能漏掉中途的跟进。

2026 年 5 月，有用户在 openai/codex 工单 #10757 里写：PR 标题和说明“should be generated from the full branch diff against the base branch, not from only the last user message”。同一张工单还提到，对话里对格式的要求，创建按钮不一定会遵守。这是公开经验。但它足够提醒你：完整分支 diff 要自己准备好，再交给模型。

在 CLI 里如果只是想先核对改了什么，可以用官方 /diff。它会列出已暂存、未暂存和未跟踪文件。这只是查看，不会写出 PR body。

用固定提示把任务锁成只写文字

官方提示指南建议把边界写进 prompt：什么必须保持不变，什么要先问你。下面这段是用法建议的提示骨架，吸收了可测 PR 用例里的产出字段，以及“未跑过的检查不要写成已通过”。官方没有现成模板，也没有独立产品命令。

把 ...HEAD 的 diff 贴进提示，或让它读取你指定的 diff 文件。路径和模板名按仓库替换。

Use only the branch diff I provide (or git diff <base>...HEAD).
Write a PR title and a Markdown PR body. Stop after the text.

Do not modify any files. Do not stage, commit, or push.
Do not call gh, do not open a pull request, and do not create a branch.

The summary must cover the net change of this branch against the base,
not just the last chat message or the most recent follow-up commit.

Body sections:
- One-line summary
- What changed
- Why
- How to test
- Risks / checks that were not run

Never describe an unrun check as passing. If I did not paste a command
result, list that check as unverified.

If the repo has a pull request template, fill in that template.
Do not paste the template source, and do not append the raw text of
any Settings instructions, into the PR body.

“Never describe an unrun check as passing.” 出自官方《Turn an issue into a tested pull request》的收尾要求。那一页的 Starter prompt 还会让模型先写短计划再实现，并在授权后尝试开 draft PR。本篇只借这一句纪律，不要把整页用例当成今天这条“只出文字”路径。

担心它改文件，就加上官方只读约束

提示写了“不要改文件”，仍可能被可写沙箱里的一次“顺便整理”打破。官方把 sandbox 和 approval 做成单独旋钮，就是为了这事。

CLI 可这样启动：

codex --sandbox read-only --ask-for-approval on-request

已经在会话里，可以用 /permissions，选文档所称的 Read Only。桌面应用和 IDE 扩展则用权限菜单，文档示例里有 Ask for approval 这类选项，现页文案以登录后为准。只读只能降低写入，提示里仍要写清：这一轮只出标题和正文。

反复使用的格式，选对复用方式

官方现推荐 skills，Custom Prompts 已经弃用。以前示例里的 /prompts:draftpr 会建分支、提交，再开 draft PR。不要把它当成“只出文字”的模板，本篇也不用它。

个人常用的摘要提示，可以做成 skill 或一条会明确调用的短指令，正文里必须继续禁止 commit 和开 PR。仓库级格式可以写进 AGENTS.md，官方允许把开 PR 前的约定放进去，官方示例写的是跑 lint。若你要加格式，写清：仅在被要求写 PR 说明时使用，免得普通改动任务也被这份模板带着走。AGENTS.md 怎么写短模板，站内已有专文。

桌面应用如果走创建 PR 的按钮，可以先到 Settings > Git，设置用于生成 pull request descriptions 的 prompts。2026 年 4 月有用户在工单里把字段称作 Commit instructions 和 Pull request instructions；现页叫什么，以登录后为准。这条路径更省事，也更容易跑偏：社区报告过指示被原文追加，仓库模板被跳过，说明只覆盖最后一次改动。它不能替代“完整 diff + 固定提示 + 人审”。

人审过正文，再自己开 PR

先读标题和正文。对照你手里的 diff，看有没有把最后一次跟进写成全部变更，有没有把没跑过的检查写成已通过，有没有把指示原文或模板原文贴进去。

用法建议：把生成的 Markdown 交给 gh pr create --body-file，或在 GitHub 网页里粘贴。不要在同一轮对话里既要说明，又授权它改代码或开 PR，除非你另有明确目标。

真实用户诀窍／反例

  • 诀窍：先交完整的分支 diff，再让它写字。 只扔最后一句“再开个 PR”，标题可能只反映最后一次跟进。
  • 诀窍：提示里把“只写文字”写死。 生成说明和开 PR 是两步。后一步用网页或 gh，不要默认 Codex 有一条只出文字的官方命令。
  • 诀窍：Testing 段只写你真的跑过的检查。 没贴命令结果的，列为未验证。这是从官方可测 PR 用例借来的纪律。
  • 诀窍：有仓库模板就按空填，不要把模板或 Settings 指示整段贴进 body。 工单 #11342 记录过：App 在生成结果末尾追加了指示原文。
  • 反例：把 /review 或 @codex review 当成写说明。 官方写明这些是找问题、发审查意见；/review 还会走专门的 reviewer。审查清单见站内另一篇。
  • 反例：拿已弃用的 /prompts:draftpr 来“只出一份说明”。 它会改仓库并开 draft PR。
  • 反例：把《Turn an issue into a tested pull request》的整段 Starter prompt 拿来用。 那条路径会先实现，再试图开 draft PR。
  • 反例：点“Commit and Create PR”一类按钮，就当说明已经按模板写好。 工单 #13828 记录过正文留空、跳过 .github/pull_request_template.md 的情况。现页是否仍如此，未登录核实；开单前仍要人看一眼。
  • 反例：在默认可写的会话里说“先看看再写说明”。 没有只读约束时，它可能改文件。

适用边界

  • 这篇覆盖：在 ChatGPT 桌面应用的 Codex、Codex IDE 扩展或 Codex CLI 里，对已经存在的分支改动，用 diff 生成变更摘要和 PR 说明。不保证某一版本的按钮文案或设置字段名长期不变，以你登录后的现页和 codex --help 为准。
  • 不覆盖：本地或 GitHub 上的 code review，按 CI 日志限制改动范围，AGENTS.md 最小模板，以及把测试文件当成完成定义。那些题目站内已有专文。
  • Git 设置是否所有档位都有、创建 PR 按钮是否所有客户端都有，未登录现页，这里不写死门槛。帮助中心只写 Codex 随 ChatGPT 计划提供，用量因计划而异。
  • 社区工单是公开经验，不能当成官方保证已经修复或仍会复现。第三方教程里出现的 --full-auto、名为 suggest 的 approval mode，与本次打开的官方现名不一致，不要当成现用旗标。
  • 写了“不要改文件”，也不等于绝对不会改。只读沙箱和人审过的正文，仍是最后两道门。生产仓库的权限、密钥和合并，另走你们自己的审批。