执行摘要
PR #7116 在 .agent/skills/pr/SKILL.md 的“撰写 PR 标题和正文”步骤中追加一段指导,要求 Agent 使用 GitHub-Flavored Markdown 格式撰写 PR 正文,避免硬折行导致渲染问题。该变更为纯文档说明,不影响任何代码逻辑。
功能与动机
pr skill 之前没有告知 Agent 如何格式化 PR 正文,导致 PR 正文有时被硬折行(固定列宽手动换行)。GitHub 将段落或列表项内的单个换行渲染为空格,导致手动折行后的 PR 正文出现意外的句中断裂。因此需要在 skill 中增加格式化指导。
实现拆解
变更仅涉及一个文件:.agent/skills/pr/SKILL.md。在第二步“Compose PR Title and Body”末尾追加一段指导性文字,内容要点如下:
- 使用 GitHub-Flavored Markdown 而非固定宽度纯文本。
- 每个段落和列表项保持一个逻辑行,块之间用空行分隔。
- 不要硬折行运行文本——GitHub 将段落内的单个换行渲染为空格。
- 指出两种易忽略的情况:
- 折行后下一行以
#<number> 开头(如 #7060)会在源码中读作标题,容易被拆开。
- 缩进的列表项续行应保持在同一逻辑行内。
- 让编辑器软换行,仅在新段落、新列表项、新表格行或围栏代码块时插入新行。
- 提交前重读正文,确认没有段落或列表项被跨行拆分。
在 SKILL.md 的“Compose PR Title and Body”步骤后追加的内容:
Write the body as GitHub-flavored Markdown, not fixed-width plain text. Keep each paragraph and each list item on a single logical line and separate blocks with blank lines. Do not hard-wrap running prose at a column limit: GitHub renders a single newline inside a paragraph or list item as a space, so a manually wrapped sentence turns into unintended mid-sentence breaks in the rendered PR. Watch two easy-to-miss cases: a wrapped line whose continuation starts with `#<number>` (e.g. an issue reference like `#7060`) reads as a heading in the source and is easy to leave split, and list-item continuations that are indented but should still join their item. Let the editor soft-wrap; only insert a newline to start a new paragraph, list item, table row, or fenced code block. Before submitting, re-read the body (or the round-tripped version fetched back from GitHub) and confirm no paragraph or list item is split across multiple source lines.
评论区精华
无重要讨论。审核员 wuxibin89 直接批准,无额外评论。
风险与影响
无技术风险。该变更为纯文档修改,不影响任何代码路径、配置、测试或部署行为。后续 Agent 在创建或更新 PR 时将按照新的格式指导撰写正文,从而提升 veRL 仓库 PR 正文的 Markdown 渲染一致性。
关联脉络
与近期历史 PR 无直接关联。该 PR 独立改善 PR 创建流程,属于仓库基础设施文档优化。
参与讨论