pr

PR 技能

创建一个草稿 PR，标题清晰，并明确说明变更内容，然后通过多轮 CI 审查，直至达到可合并状态。

说明

1. 分析分支变更：了解自与 main 分叉以来的所有提交
2. 推送到远程：确保所有提交均已推送
3. 创建草稿 PR：始终先以草稿形式提交审查，之后再合并
4. 推动审查轮次：在草稿 PR 上触发 CI 审查，只有所有审查结论都通过后才将其标记为可合并（参见下文“审查轮次”）

PR 标题格式

PR 标题遵循约定式提交格式：

<type>: <description>

类型

• feat：新功能或能力
• fix：错误修复
• refactor：代码重构
• docs：文档变更
• chore：维护任务
• perf：性能改进

标题规则

• 少于 70 个字符
• 使用小写和祈使语气
• 末尾不加句号
• 如果修改了 *_ee.rs 文件，需加上 [ee] 前缀：[ee] <type>: <description>

PR 正文格式

正文必须明确说明变更内容。结构如下：

## Summary
<Clear description of what this PR does and why>

## Changes
- <Specific change 1>
- <Specific change 2>
- <Specific change 3>

## Test plan
- [ ] <How to verify change 1>
- [ ] <How to verify change 2>

调用此技能的 harness/tooling 可能会添加自己的署名尾注；此技能本身不规定尾注格式。

截图（前端变更必需）

如果 git diff main...HEAD --name-only 匹配 ^frontend/，PR 正文必须包含受影响 UI 的截图。只有在不会产生可见 UI 效果（类型、测试、构建配置）时才可跳过，并须在正文中说明。

1. 在浏览器中验证变更（参阅 frontend/AGENTS.md →“验证前端变更”）。

2. 使用 mcp__playwright__browser_take_screenshot 截取每个受影响页面的截图（保存到文件）。

3. 将每张图片上传，并获取其 Markdown 嵌入代码：推送到公开的 windmill-labs/agent-screenshots-internal 仓库。通过 stdin 传入 base64 — 使用 -f content=… 会在实际图片上因 argument list too long 而失败：

   REPO=windmill-labs/agent-screenshots-internal
   IMG=screenshot.png                                          # repeat per page
   DEST="shots/$(git branch --show-current)/$(date +%s)-$(basename "$IMG")"
   base64 -w0 "$IMG" | jq -Rs --arg m "add $DEST" '{message:$m, content:.}' \
     | gh api -X PUT "repos/$REPO/contents/$DEST" --input - >/dev/null
   echo "![$(basename "$IMG" .png)](https://raw.githubusercontent.com/$REPO/main/$DEST)"
   

   根据文件名推导 $DEST（如上所示），确保不同页面不会发生冲突——使用固定名称会导致同一秒内上传时复用同一路径，第二次 PUT 会返回 422（Contents API 需要现有文件的 sha 才能覆盖）。

4. 将输出的 ![…](…) 行放在 PR 正文的 ## Screenshots 标题下。

需要 gh（repo scope）、jq、base64——这些都包含在 devShell 中。托管仓库是公开的（因此原始 URL 无需令牌即可在审查者界面中显示），其历史记录会永久保留——绝不要截取显示机密或敏感值的页面（工作区变量、资源值、实例设置、OAuth/SMTP 配置）；删除文件无法撤销意外截图。（GitHub 的拖放上传器需要浏览器会话，无法通过令牌驱动。）

如果 gh 无法推送到托管仓库（例如 CI 令牌的权限范围仅限于 windmill），不要因此中止 PR，也不要默默跳过——请将上传任务交给有推送权限的用户，并在对方确认完成后继续。

执行步骤

1. 运行 git status，检查是否有未提交的更改

2. 运行 git log main..HEAD --oneline，查看此分支中的所有提交

3. 运行 git diff main...HEAD，查看相对于 main 的完整差异

4. 创建 PR 前先审查差异——两项审查都要运行，不要跳过：

   • local-review — Claude 原生的分支差异审查器（在 Claude Code 中使用 /local-review，在 Codex 中使用 $local-review，在 Pi 中使用 pi --skill local-review / /skill:local-review）。
   • local-review-codex — 由 Codex 独立执行的审查，与 CI 运行的审查相同，可提供 Claude 审查未发现问题的独立视角（在 Claude Code 中使用 /local-review-codex，或运行 bash .agents/skills/local-review-codex/run.sh）。如果缺少 codex CLI，或其版本低于此技能要求的版本，请在总结中注明并继续——切勿因无法使用 codex 而阻止 PR。

   两项都要运行——它们能发现不同的问题。如果任一项发现问题，请先修复并提交，然后再继续。

5. 前端更改的截图：如果 git diff main...HEAD --name-only 的输出匹配 ^frontend/，请按照上文“截图”部分的说明，截取并嵌入受影响 UI 的截图，然后再撰写 PR 正文（仅当没有可见 UI 影响时才跳过）。

6. 检查远程分支是否存在且为最新：

   git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "no upstream"
   

7. 如有需要，将分支推送到远程：git push -u origin HEAD

8. 使用 gh CLI 创建草稿 PR：

   gh pr create --draft --title "<type>: <description>" --body "$(cat <<'EOF'
   ## Summary
   <description>
   
   ## Changes
   - <change 1>
   - <change 2>
   
   ## Test plan
   - [ ] <test 1>
   - [ ] <test 2>
   EOF
   )"
   

9. 将 PR URL 返回给用户

10. 按照 CI 审查轮次推进 PR，直至其就绪（请参阅下文“审查轮次”）

评审轮次（草稿 → 就绪）

只有在 CI 评审轮次干净通过后，PR 才能退出草稿状态。在此之前绝不要运行 gh pr ready。 此规则适用于所有模式，包括自主模式。干净的评审轮次是必要条件，但不一定充分——请参阅下文“切换就绪状态，还是先询问”。唯一的常设例外是明确要求将该 PR 保持为草稿（通常是为了先进行测试）——请对该 PR 遵照执行，不要将此要求延续到下一个 PR。

1. 触发一轮评审并等待完成：将等待器作为后台 Bash 任务启动（每轮需要 10–30 分钟；任务退出时会唤醒你——运行期间不要停止会话，也不要在前台轮询）：

   bash .agents/skills/pr/review-round.sh <PR_NUMBER>
   

   它会在 PR 上评论 /review——即使 PR 处于草稿状态，也会运行 Codex、Claude 和 Pi CI 评审器——等待已启动的 PR Review Commands 工作流运行完成，然后为每位评审器打印一行评审结论，并将完整评审评论保存到文件中。

   /review（以及 /codex）按 head SHA 幂等：如果当前 head 已有正在运行或已成功的评审覆盖，就会跳过该 Agent，不再发布新内容——等待器会读取该 head 已有的评审结论，因此被跳过的 Agent 不算缺失。已取消或失败的 head 运行会原地重跑；只有在没有任何运行覆盖该 head 时，才会启动新的运行。因此，对未变更 head 重新评审几乎不会产生任何新内容，并不算新一轮评审——请推送一个提交，以获取真正全新的评审。

2. 判定本轮评审。 Codex 必不可少；Claude、Pi 和 cubic 只要发布了评审，就都计入。每条评审都以 REVIEW.md 中的三种评审结论之一开头：

   • 缺少 Codex 评审结论 → 本轮无效：仅当 head 没有绿色的 Codex 运行时，等待器才会发出警告（运行已取消、失败或不存在——而不仅仅是因为已评审而跳过）。在 PR 上评论 /codex，这会原地重新运行被中断的运行（或在不存在运行时启动一个），按相同方式等待，然后重新判定。
   • 出现任何 “合并前应解决问题” → 修复 P0/P1 问题（顺便处理细枝末节），提交并推送，然后开始新一轮评审（步骤 1）。
   • 仅出现 “可以合并，但最好处理细枝末节” 和／或 “可以合并” → 也要处理细枝末节；如果某条细枝末节意见有误或确实不值得修复，可以回复该评审评论并说明理由，以此驳回。仅修复细枝末节时，推送修复即可，无需再启动完整评审轮次。

3. 发布标记评论，将 PR 切换为就绪状态。 如果 PR 作者发布了标明当前 head SHA 的标记，且 PR 最新一条 Codex 评审是在该标记之前发布的，并且结论不阻止合并（这是评审证据——没有对应评审轮次的单独标记，或其标记前最后一条 Codex 评审结论为“合并前应解决问题”，都不会跳过评审），评审工作流便会跳过由 ready_for_review 触发的冗余轮次。前缀必须完全一致，并使用要切换就绪状态的 head 的完整 40 位 SHA：

   • 所有评审结论均为“可以合并”（自本轮评审后 head 未变更）：

     ✅ Review round clean @ <head-sha>

   • 仅有细枝末节问题的评审轮次，且细枝末节问题随后已修复或驳回（head 可能已超出受评审的 SHA——请说明这一点）：

     ✅ Review round clean @ <head-sha> — nit-only verdicts at <round-sha>; nits addressed in <commit sha(s)> / dismissed in review replies

   gh pr comment <PR_NUMBER> --body "✅ Review round clean @ $(git rev-parse HEAD)"
   gh pr ready <PR_NUMBER>
   

   如果仍有任何未解决的 P0/P1 问题，或 head 的变更并非为了修复细枝末节，不要发布标记或切换就绪状态——请改为再运行一轮评审。

无法开始的一轮通常是发生了冲突

无法合并的 PR 不会运行审查工作流，因此一轮没有给出结论，通常是与 main 发生了冲突，而不是 CI 故障。先检查，再假设哪里出了问题：

gh pr view <PR_NUMBER> --json mergeable,mergeStateStatus

通过合并而不是变基解决——变基会重写本轮结论和干净轮次标记所依据的 head SHA，使你已经付费完成的工作失效：

git fetch origin main
git merge origin/main

**如果合并更改了 backend/ee-repo-ref.txt，请让 EE 工作树与之匹配。**该文件固定了 CE 构建所依赖的 EE 提交，因此，推进该文件的合并会让 EE 检出版本落后于 CE 现在的预期，而 cargo check --features private 编译的将是一个你和 CI 都无意使用的代码树：

git -C <ee-worktree> merge "$(tr -d '[:space:]' < backend/ee-repo-ref.txt)"

推送两边，然后开始新一轮——head 已更改，因此先前的结论不再适用。

直接设为就绪，还是先询问

干净的一轮足以让 PR 设为就绪，但不总是足以让它在无人值守时设为就绪。先根据差异判断影响范围——git diff --name-only main...HEAD 可以回答大多数这类问题。

以下情况设为就绪前先询问：

• 涉及 *_ee.rs（它通过符号链接关联到 EE 仓库，并且有配套 PR）
• 在 backend/migrations/ 下新增迁移
• 更改 openapi.yaml、openflow.openapi.yaml 或生成的客户端
• 涉及身份验证、权限或令牌相关路径
• 更改共享工作器基础设施——作业轮询器、handle_child、执行器
• 触发 REVIEW.md 中的“新公共接口检查清单”

以下情况无需询问即可设为就绪：更改范围独立，例如单文件修复、仅测试、仅文档、单个调用点，且没有新增公共接口。

无人值守（一键运行）时没有人可以询问，因此判断标准不变，但操作方式需要调整：将范围独立的更改设为就绪；其余更改保持为干净的草稿，并在 PR 描述中说明原因——left in draft: adds a migration, wants a human look before ready。不要仅仅因为一轮结果干净，就将影响范围广的更改设为就绪；也不要提出无人会看到的问题。

AGENTS.local.md（已加入 gitignore，因此可能不存在）中有“PR 就绪度校准”一节，记录了过去对模糊情况的处理结果。决策前先阅读；如果仍确实难以判断，就先询问，再将答案附加到该文件中，让下次遇到类似情况时更明确。

多轮仍未收敛时

三轮或更多轮仍未得到干净结论，通常意味着更改的结构有问题，而不是还有无穷无尽的独立缺陷。以下迹象值得注意：

• 问题在一轮又一轮中反复出现在相同文件
• 修复一个问题又引出下一个问题
• 问题涉及耦合、重复，或在许多地方传递的状态，而非逻辑错误

出现这种模式时，请停止运行新一轮——每一轮都会消耗一次 CI 周期，而且无法收敛。明确说明剩余问题看起来是结构性的，而非偶发的，并指出它们集中在哪个模块或接口边界。有用户在场时，建议他们对该区域运行 /improve-codebase-architecture：它只能通过斜杠命令调用，因此你无法自行调用；而重塑代码属于范围变更，应由他们决定。无人值守时，将诊断写入 PR 描述，然后就此停止，不要继续机械地跑更多轮。

EE 配套 PR（修改了 *_ee.rs 文件时）

windmill 仓库中的 *_ee.rs 文件是指向 windmill-ee-private 的符号链接——在 windmill 仓库的 git diff 中不会显示这些更改。请改为检查 EE 仓库中是否有尚未提交或推送的更改。

请遵循 docs/enterprise.md 中完整的 EE PR 工作流。PR 相关要点如下：

1. 查找 EE 仓库／工作树：参见 docs/enterprise.md 中的“查找 EE 仓库”
2. 检查更改：git -C <ee-path> status --short
   • 如果 EE 仓库没有更改，请跳过本节
3. 遵循 docs/enterprise.md 中“EE PR 工作流”的步骤 1–5
4. 创建配套 PR（标题不要加 [ee] 前缀）：

   gh pr create --draft --repo windmill-labs/windmill-ee-private --title "<type>: <description>" --body "$(cat <<'EOF'
   Companion PR for windmill-labs/windmill#<PR_NUMBER>
   EOF
   )"
   

5. 提交 ee-repo-ref.txt 并推送更新后的 windmill 分支