@routerhub/agent-rules 1.5.183 → 1.5.185

package/AGENTS.base.md

@@ -158,7 +158,8 @@
 - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：
     - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
     - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。
-    - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：截图版 HTML → 无头 Chrome 转 PDF → push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 格式（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。生成统一走 `/create-doc` skill。
+    - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：截图版 HTML → 无头 Chrome 转 PDF → push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 格式（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。文档生成统一走 `/create-doc` skill，PR 创建统一走 `/create-pr` skill（内含本链接的制作与置顶步骤）。
+    - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：文档里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
     - **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。
 - ⚠️ PR Title / Description / Test Plan 全部中文。
 - ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.183",
+  "version": "1.5.185",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/global.md

@@ -158,7 +158,8 @@ name: "通用规则"
 - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：
     - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
     - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。
-    - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：截图版 HTML → 无头 Chrome 转 PDF → push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 格式（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。生成统一走 `/create-doc` skill。
+    - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：截图版 HTML → 无头 Chrome 转 PDF → push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 格式（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。文档生成统一走 `/create-doc` skill，PR 创建统一走 `/create-pr` skill（内含本链接的制作与置顶步骤）。
+    - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：文档里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
     - **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。
 - ⚠️ PR Title / Description / Test Plan 全部中文。
 - ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：

package/skills/create-pr/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   「提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中。
+  自动生成中文Title/Description/TestPlan、制作效果截图（前后对比）、上传到GitHub CDN、内嵌到Description中，并在 Description 顶部附截图版 HTML→PDF「详细实现文档」醒目链接（PR 正文快速浏览、链接展开每一步细节）。
 ---
 
 # 创建 Pull Request
@@ -74,7 +74,24 @@ Closes #issue编号
 - ⚠️ 截图保存到本地磁盘 `docs/` 对应子目录（文件名「编号 + 英文描述」，如 `01-before.png` / `02-after.png`），上传 CDN 后按规则清理临时文件，禁止提交到 Git 仓库。
 - ⚠️ 必须展示前后对比（修复前红框，修复后绿框），标注不遮挡页面内容。
 
-### 5. 创建 PR
+### 5. 制作详细实现文档（截图版 HTML→PDF）并置顶到 Description
+
+⚠️ **每个 PR 的 Description 顶部必须附一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：PR 正文只承载 What / Why / Test Plan 精华 + 关键效果截图（几十秒看懂这次改了什么）；链接指向的 PDF 承载「做了什么 + 为什么这样做 + 每一步怎么做的」完整过程，并配上带箭头标注的真实截图。想深入细节的 reviewer 点开链接即看；禁止在正文里翻流水账，也禁止只有正文、缺详细文档链接。
+
+1. **汇总素材**：本 PR 的「改了什么 + 为什么改 + 每一步怎么改/怎么验证」，以及步骤 4 产出的全部效果截图（含修复前后对比）。
+   - ⚠️ **素材取材优先级：前端可视化优先，纯逻辑才退而用代码/接口图**：讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明**——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
+2. **生成截图版 HTML → 转 PDF**：走 `/create-doc` skill 输出自包含 HTML——截图一律 `data:image/png;base64` 内嵌并自动加箭头标注（遵循「⚠️ 截图规范」「⚠️ HTML 文档截图与 curl 命令规范」），图文逐步说明每一步怎么做的；再经无头 Chrome 转 PDF。
+3. **托管到私有文档仓库**：push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支（仓库名从 git remote 推导：`git@github.com:<ORG>/<项目>.git` → 文档仓库 `<ORG>/<项目>-docs`），文件名用与 PR 主题相关的英文短名。
+4. **拿链接**：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf`（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。
+5. **拼到 Description 顶部**：把链接作为 Description **第一条、独占一行、加粗高亮**，放在任何正文段落之前：
+   ```
+   📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)
+   ```
+   reviewer 建议以新标签页打开，看完细节再回 PR 正文。
+
+**适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。后续步骤 6 创建 PR 时，此链接已作为 body 第一条。
+
+### 6. 创建 PR
 
 ⚠️ **`--base` 必须是仓库默认分支，不能硬编码 `main`**——不同仓库默认分支名不同（如 `master`），且可评审 PR 的合并目标永远是默认分支，不是 `test`（`test` 只通过 `/deploy-test` skill 直接 merge 部署，不走 PR review）：
 
@@ -88,25 +105,25 @@ gh pr create \
   --head "$(git branch --show-current)"
 ```
 
-### 6. 补充元数据
+### 7. 补充元数据
 
 - Assignees：填自己
 - Labels：按类型/模块添加
 - 关联 issue：如有
 - Milestone：如有
 
-### 6.5 创建完 PR 后自动走完整闭环流程（未走完不算完成）
+### 7.5 创建完 PR 后自动走完整闭环流程（未走完不算完成）
 
-⚠️ 创建完 PR 后，禁止只做完步骤 7 收尾就交付。必须自动依次走完下方闭环，全程自动执行，未走完不算完成：
+⚠️ 创建完 PR 后，禁止只做完步骤 8 收尾就交付。必须自动依次走完下方闭环，全程自动执行，未走完不算完成：
 
 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` 发新版本。
+6. **发新版本**：确认没问题后，回到下方步骤 8 完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
 
-### 7. 每次修改 PR 后收尾检查（冲突 + 静态编译 + 发版本）
+### 8. 每次修改 PR 后收尾检查（冲突 + 静态编译 + 发版本）
 
 ⚠️ 创建 PR 后、以及每次 push 新提交/响应 review 意见重新推送后，三步收尾缺一不可，禁止改完 PR 就直接抛给 reviewer 或当作完事。
 
@@ -135,9 +152,10 @@ gh pr checks <PR>
 - ⚠️ 一个 PR 只做一件事
 - ⚠️ PR 所有文字内容必须中文
 - ⚠️ 必须附截图作为可视化证据
+- ⚠️ **PR Description 顶部必须附「详细实现文档」链接（截图版 HTML→PDF，见步骤 5）**：PR 正文只承载快速浏览，链接展开「做了什么 + 为什么 + 每一步怎么做的」完整细节
 - ⚠️ 截图禁止提交到 Git 仓库
 - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
-- ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 7）
-- ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 6.5）**：创建 PR → 先做 CI 闸门检查并修复失败项 → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注）→ 确认没问题 → 发新版本，六步缺一不可，未走完不算完成
+- ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 8）
+- ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 7.5）**：创建 PR → 先做 CI 闸门检查并修复失败项 → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注）→ 确认没问题 → 发新版本，六步缺一不可，未走完不算完成
 - ⚠️ **直接创建正式 PR（非 Draft）**：PR 创建完成即进入可评审状态，可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review
 - 作者不能 Approve 自己的 PR