Pr

它的作用¶

pr 定义了 PR 正文的格式：一个展示变更的摘要、一个证明它有效的证据，以及一个关于合并风险有多大的合并风险判断。它是一个格式参考，而不是工作流。它不会推送分支、打开 PR，或决定其中包含什么。它告诉智能体在编写正文时应该采用什么格式。

摘要是一个可视化，而不是一个段落。默认的 PR 正文用文字描述 diff。这个正文会选择能让关键点清晰的最小视图（伪代码、调用树、组件树、文件树、Mermaid 图或结构化 diff），并保持周围的文字简短。评审者已经打开了 diff，因此正文会在他们阅读之前先展示它的形状。

何时使用¶

输入 /pr，或者智能体在编写 PR 正文时会自动使用它。

模板¶

三个部分，按此顺序：

• 摘要：一个或多个小型可视化，每个都放在它所支持的简短文字旁边。通常用一个，有时用几个，很少全部使用。只保留评审者需要的调用、文件、props 和边界。
• 证据：前后对比。当变更是视觉性的，且环境可以截图时，截图是最有力的证据。否则，使用之前失败、现在通过的精确测试，以伪代码形式写出；或使用发生变化的控制台输出。
• 合并风险：该变更是单向门还是双向门，以及它的影响范围。双向门容易回滚；单向门（破坏性迁移、移除公共 API、难以逆转的决定）则不容易。影响范围指出如果变更出错，哪些东西可能损坏：布局偏移、API 的使用方、移动端响应式。

门判断是核心思想。它把“这能安全合并吗？”从一种直觉变成评审者可以反对的明确声明。它也告诉评审者应该把人工审查花在哪里。对于影响范围小的双向门，可以快速浏览；对于单向门，要慢慢读。

常见问题¶

我能相信智能体自己的门判断吗？

不要盲目相信，而明确写出来正是重点。编写变更的智能体也是给变更打分的智能体，所以当它说“双向，影响范围小”时，要最保持怀疑。diff 也常常掩盖变更是否可以回滚。正如一位用户所说：“回滚一个 commit 并不能取消发送一批邮件”，而一个被标记的发布只有在第一次写入落入新格式之前，才保持双向。该技能给智能体一个定义（破坏性操作和难以逆转的决定是单向），而不是一份检查清单，因此要最仔细地检查合并风险一行。有两点有帮助：确保智能体面前有工单或规格，而不仅仅是 diff，并在智能体做出判断之前会读到的地方，写下你的仓库始终视为单向的变更（schema 迁移、任何向外发布或删除的内容）。

它会替我打开 PR 吗？

不会。pr 只覆盖正文。implement 以提交到当前分支结束。要求打开 PR 的技能或选项（例如 /to-pr，或让 implement 打开 PR 而不是提交）目前仍是开放提案。一位用户的变通方法是用一句话本地覆盖 implement，告诉它打开 PR。implement-spec 是例外：当你的 issue tracker 通过 PR 关闭工作，或当你要求时，它会打开一个草稿 PR。由于 pr 由模型调用，只要你要求它打开 PR，智能体就会用这种格式写正文。

它不会只是产生另一堵文字和图表墙吗？

该技能旨在防止这种情况，但仍可能发生。用户对智能体 PR 正文的抱怨是一致的：“摘要很长，但我需要知道的只是改了什么、如何验证、什么可能损坏，以及是否安全合并。”该技能告诉智能体跳过前言，保持文字简短，并选择最小视图，通常是一个可视化，很少全部使用。如果你仍然得到一堆图表，说明智能体忽略了这一点。如果正文巨大是因为 diff 巨大，问题在于 PR 的大小，pr 不会替你拆分它。

我的仓库已经有 PR 模板。哪一个生效？

默认情况下，两者都不占优。pr 有自己的模板，不会查找 .github/pull_request_template.md 或类似文件。多位用户要求该技能使用仓库的模板。如果你什么都不做，智能体对同一文档会有两条相互冲突的指令。请在你的仓库智能体文档中解决它，例如填写仓库模板，并在其下放置摘要、证据和合并风险。

输出是 HTML 吗？为什么 Mermaid 图不渲染？

输出是 markdown PR 正文，而不是 HTML 页面。GitHub 和 GitLab 会在 PR 描述中渲染 Mermaid 代码块，但终端不会，因此在智能体仍在本地向你展示时，图表看起来像原始文本。使用 CLI harness 的用户通过 ASCII Mermaid 渲染器，或让智能体将 HTML 版本附加到 PR 来绕过这一点。Mermaid 是六种视图之一。调用树、文件树或结构化 diff 在任何地方读起来都一样。

它能整理返回的评审意见吗？

不能。它写完正文就停止。用户不止一次要求一种方式来分诊来自其他开发者或评审机器人的评论（哪些值得处理，哪些不是问题）。该技能不会这样做。

它会在 PR 变化时保持正文最新吗？

不会。它只在某个时间点写入正文，而正在评审中发生变化的 PR 会使该正文变得过时。在发生重大更改后，要求智能体重写正文。智能体是在再次编写 PR 正文，因此会使用相同的结构。

我的更改没有 UI。Evidence 里应该放什么？

除截图外的一切。只有当更改是视觉性的时，截图才是最有力的证据。对于迁移、后台任务或重构，证据是之前失败而现在通过的具体测试，或发生变化的控制台输出。单独的“测试是绿色的”只是一个声明，而不是前后对比。

它能否将正文标记为由 LLM 编写？

它本身不能。一位用户的做法是在仓库的智能体文档中设置一条常设指令：智能体编写的每个 issue、评论和 PR 都以一行披露结尾。该规则应放在仓库中，以覆盖智能体发布的所有内容，而不是放在某一种文档的模板中。

如果它正在起作用¶

• 仅从 Summary 视觉，就能在打开 diff 之前看出 PR 更改了什么。
• 正文没有前言：它从 Summary 标题开始。
• Evidence 部分展示了之前和之后，而不是测试通过的声明。
• 每个 PR 都说明了一个门和影响范围，而单向门是你需要放慢脚步的那些。

它在哪里适用¶

当构建以 PR 形式发布时，pr 位于 review 和 retro 之间：to-spec → to-tickets → implement → code-review → pr → retro。它是由模型调用的，因此每当智能体在该链路之外编写 PR 正文时，它也会自动触发。

• code-review 在它之前运行，因为 PR 正文应描述一个已经过评审的 diff。
• implement 生成正文所描述的提交。

ask-matt 在你不确定情况需要哪个技能时，在整个技能集合中路由。