---
name: create-pr
description: >-
  创建 / 提交 / 发起 Pull Request。触发场景包括但不限于：
  「提PR」「提个PR」「提一个PR」「提交PR」「创建PR」「发起PR」「开PR」「开个PR」「搞个PR」「弄个PR」「弄一个PR」「来一个PR」「帮我PR」「帮我提PR」「帮我提交PR」「帮我创建PR」「帮我开PR」「帮我弄PR」「帮我搞PR」「创建pull request」「提交pull request」「发起pull request」「新建PR」「新建pull request」「生成PR」「生成pull request」「做PR」「做个PR」「做一下PR」「做下PR」「整PR」「整个PR」「整一个PR」「出PR」「出个PR」「出一个PR」「搞PR」「来PR」「上PR」「上一下PR」「帮我上PR」。
  任何包含「PR」「Pull Request」「pull request」且表达创建/提交/发起语义的说法都应触发。
  以及：「把这个提交一下」「把这个提了」「提上去」「提交上去」「推到远程」「推到仓库」「发到仓库」「合到主线」「合入主线」「合并到main」「合并到master」「合并请求」「创建合并请求」「发起合并请求」「帮我合一下」「帮我合并」「帮我合了」「把这个合了」「合一下」「合了」。
  自动生成中文Title/Description/TestPlan、制作效果截图（前后对比）、上传到GitHub CDN、内嵌到Description中。
---

# 创建 Pull Request

⚠️ **本 Skill 已触发。在用户回复中第一句话必须输出：「🔧 已触发 `create-pr`，按流程创建 PR...」然后严格按照以下步骤执行，不得跳过。**

从当前分支创建 PR，自动完成：中文 Description、效果截图制作、GitHub CDN 上传。

## 核心流程

### 1. 收集改动信息

```bash
git diff origin/main...HEAD --stat
```

确认改动范围，判断 PR 类型（UI 改动 / 接口改动 / 修 bug / 新功能）。

### 2. 查找关联需求文档

自动搜索 `docs/` 目录下对应的需求文档（HTML 格式），匹配当前分支名关键词。

### 3. 生成 PR 内容（全部中文）

**Title**：`[模块] 动词 + 改了什么`，祈使句，一行说清。

**Description** 模板：
```markdown
## 背景
（为什么要改，解决什么问题）

## 改动
（改了什么，采用什么方案）

## 方案取舍
（为什么选这个方案，考虑过什么替代方案）

## 不在本 PR 范围
（有意不做的事、已知局限、后续 follow-up）

Closes #issue编号
```

**Test Plan**：写明验证步骤，禁止「测了没问题」类敷衍描述。

### 4. 制作效果截图

仅对有 UI 改动/修 bug 的 PR 执行：

1. **截修复后**：浏览器打开改动页面 → 滚动到改动区域 → 全页截图
2. **截修复前**：临时注释/回退改动代码 → 等 hot reload → 同位置截图 → 恢复代码
   - ⚠️ **若线上数据已变化，导致无法在真实页面复现"修复前"效果**：允许改用等价的纯逻辑对比代替（用新旧两版逻辑代码跑同样的输入数据，把输出结果差异渲染成对比图），但必须在 Description 里明确写清楚"为什么无法复现 + 用了什么替代方案"，禁止因此省略截图或假装能复现。
3. **生成对比图**：用 `annotate.js`（截图标注统一脚本，见 `/screenshot-annotate` skill）拼接并标注 → 上方红/绿色标注条（❌修复前 / ✅修复后）→ 下方左右并排截图 → 关键改动区域用坐标精确换算后的箭头 + 红/绿框圈选
4. **上传 GitHub CDN**（在 PR Description 编辑区直接上传）：
   - 打开目标 PR 页面 → 在 **Description 编辑区**直接上传图片（拖拽/粘贴，或定位 Description 编辑区的隐藏 `input[type=file]` 上传），GitHub 会自动把图片转成 `https://github.com/user-attachments/assets/...` 的 CDN 地址并插入 Description 正文，`![](CDN_URL)` 内嵌
   - ⚠️ **禁止走评论区上传再搬运 CDN URL**：评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多一步手动搬运容易出错
   - ⚠️ **禁止用 `gh gist create --public` 等公开托管服务代替**——这属于未经授权的公开发布
5. **保存 Description**：确认图片已内嵌进 Description 正文后，保存 PR Description 使图片持久化

**截图硬性规范（PR 效果截图必须逐条满足，缺一不可，禁止跳过）**：
- ⚠️ **全页图用浏览器真实视口宽度（`window.innerWidth` 即截图宽，4K 屏自然宽 3840）**，用 agent-browser 时先 `set viewport <视口宽> <合适高度>` 固定视口，再 `screenshot --full` 截完整页面。⚠️ **禁止强制 `set viewport 3840 <h>` 把 CSS 视口拉宽到比屏幕还宽**（页面会缩小看不清、且 CSS 像素与截图像素缩放错位导致标注不准）；需要更高清晰度时用 `set viewport <W> <H> 2`（DPR 倍率，CSS 宽不变、像素更密）。
- ⚠️ **必须 `fullPage: true` 截完整页面**，不要只截视口的一部分。每个改动点都要覆盖到，禁止只截视口内一屏。
- ⚠️ **截图必须全面（多图覆盖多个角度）**：一张全页图 + 每个关键改动区域的局部放大图。只截一处、截局部、漏掉改动点都不算全。整份 PR Description 的效果截图要使 reviewer 不看代码就能看全本次改动。
- ⚠️ **每张截图必须用醒目箭头 + 简短文字标签标注关键改动区域/验证点**，让看的人一眼看懂这张图证明了什么；修复前用红框/红箭头，修复后用绿框/绿箭头，标注放在不遮挡原内容的位置。禁止只贴裸图不标注。⚠️ **标注坐标必须精确**：统一用 `/screenshot-annotate` skill（`getBoundingClientRect()` + `scrollX/scrollY` 换算到截图像素，用 `annotate.js` 脚本画箭头），禁止肉眼看图估坐标。
- ⚠️ **截图中必须能看到当前页面 URL**（浏览器地址栏，或页面顶部叠加 URL 标注），确保证据可追溯。
- ⚠️ 截图保存到本地磁盘 `docs/` 对应子目录（文件名「编号 + 英文描述」，如 `01-before.png` / `02-after.png`），上传 CDN 后按规则清理临时文件，禁止提交到 Git 仓库。
- ⚠️ 必须展示前后对比（修复前红框，修复后绿框），标注不遮挡页面内容。

### 5. 创建 PR

⚠️ **`--base` 必须是仓库默认分支，不能硬编码 `main`**——不同仓库默认分支名不同（如 `master`），且可评审 PR 的合并目标永远是默认分支，不是 `test`（`test` 只通过 `/deploy-test` skill 直接 merge 部署，不走 PR review）：

```bash
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)

gh pr create \
  --title "中文标题" \
  --body "中文 Description（含截图 CDN URL）" \
  --base "$DEFAULT_BRANCH" \
  --head "$(git branch --show-current)"
```

### 6. 补充元数据

- Assignees：填自己
- Labels：按类型/模块添加
- 关联 issue：如有
- Milestone：如有

### 6.5 创建完 PR 后自动走完整闭环流程（未走完不算完成）

⚠️ 创建完 PR 后，禁止只做完步骤 7 收尾就交付。必须自动依次走完下方闭环，全程自动执行，未走完不算完成：

1. **先做 CI 闸门检查**：创建 PR 后立即执行 `gh pr checks <PR>`（必要时轮询直到非 `pending`）。若存在任一 `failure`，必须先定位失败根因并修复，推送后复查到全部 `success`，再继续后续步骤；禁止带红 CI 进入下一步。
2. **自动走循环 review**：自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束。
3. **重新部署到测试环境**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。
4. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
5. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
6. **发新版本**：确认没问题后，回到下方步骤 7 完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。

### 7. 每次修改 PR 后收尾检查（冲突 + 静态编译 + 发版本）

⚠️ 创建 PR 后、以及每次 push 新提交/响应 review 意见重新推送后，三步收尾缺一不可，禁止改完 PR 就直接抛给 reviewer 或当作完事。

**① 与主分支冲突检查**（每次修改 PR 后都要重新执行，禁止只在创建时查一次）：
```bash
gh pr view <PR> --json mergeable -q .mergeable
```
- `MERGEABLE`=无冲突可合并
- `CONFLICTING`=存在冲突：`git merge origin/$DEFAULT_BRANCH`（或 `git rebase origin/$DEFAULT_BRANCH`）→ 解决冲突文件 → 测试通过 → 推送
- `UNKNOWN`=GitHub 尚未判定，稍后复查

**② GitHub 静态编译检查**：
```bash
gh pr checks <PR>
```
- `success`=通过，`failure`=失败，`pending`=进行中
- 存在失败项：定位失败根因 → 修改代码 → 重新推送，直到全部通过
- 禁止把静态编译未通过的 PR 抛给 reviewer

**③ 发新版本**：
- PR 合并后按项目发布流程发布新版本
- 本项目统一执行根目录 `./release.sh`（自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）

## 重要规则

- ⚠️ 一个 PR 只做一件事
- ⚠️ PR 所有文字内容必须中文
- ⚠️ 必须附截图作为可视化证据
- ⚠️ 截图禁止提交到 Git 仓库
- ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
- ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 7）
- ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 6.5）**：创建 PR → 先做 CI 闸门检查并修复失败项 → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注）→ 确认没问题 → 发新版本，六步缺一不可，未走完不算完成
- ⚠️ **直接创建正式 PR（非 Draft）**：PR 创建完成即进入可评审状态，可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review
- 作者不能 Approve 自己的 PR