@routerhub/agent-rules 1.5.122 → 1.5.124

package/AGENTS.base.md

@@ -18,6 +18,7 @@
 
 - 始终使用中文回答，代码注释使用中文。
 - 页面 UI 内容（按钮、字段名、提示等）全部英文；如需中文在 `AGENTS.private.md` 中声明。
+- ⚠️ **解释代码或技术概念时，必须通俗易懂，优先用生活中的真实例子类比，禁止纯学术式讲解。** 例：解释缓存命中——「就像冰箱里已经放好了可乐，想喝直接拿，不用每次都跑楼下超市；冰箱里没有才需要跑一趟（缓存未命中，回源数据库）。」目标是让不熟悉该领域的人也能听懂，不要只堆术语、贴定义。
 
 ## 需求实现原则
 
@@ -112,8 +113,8 @@
 - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
 - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
 - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
-- ⚠️ **创建 PR 后，必须先检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。
-- ⚠️ **创建 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
+- ⚠️ **每次修改 PR 后（含创建 PR、push 新提交、响应 review 意见重新推送等所有改动 PR 的动作之后），都必须检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。主分支随时可能前进，一个创建时无冲突的 PR 可能在后续 push 后悄悄变冲突，因此每次改动 PR 后都必须重新检查，禁止只在创建时查一次就以为高枕无忧。
+- ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
   1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
   2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
   3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.124] - 2026-08-12
+
+### Added
+
+- 新增「代码解释通俗化」规则（语言与内容）：解释代码或技术概念时必须通俗易懂，优先用生活中的真实例子类比（如「缓存命中就像冰箱里放好了可乐，想喝直接拿，不用每次跑楼下超市」），禁止纯学术式讲解、只堆术语贴定义。目标：让不熟悉该领域的人也能听懂。
+
+## [1.5.123] - 2026-08-12
+
+### Changed
+
+- 强化「创建 PR 后冲突检查」规则为「每次修改 PR 后都必须检查与主分支冲突」：原先只在创建 PR 时查一次 `gh pr view <PR> --json mergeable -q .mergeable`，现在 push 新提交、响应 review 意见重新推送等每次改动 PR 后都必须重新检查并解决冲突。原因：主分支随时可能前进，创建时无冲突的 PR 可能在后续 push 后悄悄变冲突。同步更新 `create-pr` skill 第 7 步与「重要规则」章节。
+
 ## [1.5.122] - 2026-08-11
 
 ### Added

package/package.json

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

package/rules/global.md

@@ -18,6 +18,7 @@ name: "通用规则"
 
 - 始终使用中文回答，代码注释使用中文。
 - 页面 UI 内容（按钮、字段名、提示等）全部英文；如需中文在 `AGENTS.private.md` 中声明。
+- ⚠️ **解释代码或技术概念时，必须通俗易懂，优先用生活中的真实例子类比，禁止纯学术式讲解。** 例：解释缓存命中——「就像冰箱里已经放好了可乐，想喝直接拿，不用每次都跑楼下超市；冰箱里没有才需要跑一趟（缓存未命中，回源数据库）。」目标是让不熟悉该领域的人也能听懂，不要只堆术语、贴定义。
 
 ## 需求实现原则
 
@@ -112,8 +113,8 @@ name: "通用规则"
 - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
 - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
 - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
-- ⚠️ **创建 PR 后，必须先检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。
-- ⚠️ **创建 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
+- ⚠️ **每次修改 PR 后（含创建 PR、push 新提交、响应 review 意见重新推送等所有改动 PR 的动作之后），都必须检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。主分支随时可能前进，一个创建时无冲突的 PR 可能在后续 push 后悄悄变冲突，因此每次改动 PR 后都必须重新检查，禁止只在创建时查一次就以为高枕无忧。
+- ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
   1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
   2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
   3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。

package/skills/create-pr/SKILL.md

@@ -94,11 +94,11 @@ gh pr create \
 - 关联 issue：如有
 - Milestone：如有
 
-### 7. 创建 PR 后收尾检查（冲突 + 静态编译 + 发版本）
+### 7. 每次修改 PR 后收尾检查（冲突 + 静态编译 + 发版本）
 
-⚠️ 创建 PR 后，三步收尾缺一不可，禁止创建完 PR 就直接抛给 reviewer。
+⚠️ 创建 PR 后、以及每次 push 新提交/响应 review 意见重新推送后，三步收尾缺一不可，禁止改完 PR 就直接抛给 reviewer 或当作完事。
 
-**① 与主分支冲突检查**：
+**① 与主分支冲突检查**（每次修改 PR 后都要重新执行，禁止只在创建时查一次）：
 ```bash
 gh pr view <PR> --json mergeable -q .mergeable
 ```
@@ -125,6 +125,6 @@ gh pr checks <PR>
 - ⚠️ 必须附截图作为可视化证据
 - ⚠️ 截图禁止提交到 Git 仓库
 - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
-- ⚠️ 创建 PR 后必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 7）
+- ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 7）
 - 先开 Draft PR，准备好再标记 Ready for review
 - 作者不能 Approve 自己的 PR