@routerhub/agent-rules 1.5.118 → 1.5.120

package/AGENTS.base.md

@@ -33,6 +33,18 @@
 - ⚠️ **上述来源都找不到的，就写「待确认」或留空，禁止自行补全。** 错误的推断值比留空危害更大——留空会在运行时报错、立刻暴露；错误的推断值可能静默运行数月后才被发现（如请求打到了错误的环境），排查成本极高。
 - ⚠️ **代码中使用环境变量占位符（如 `process.env.XXX`）时，必须同时确认测试/生产部署脚本（或配置中心）已提供该变量的具体值。** 禁止只写占位符不落地——代码能编译不代表部署后取值非空。具体值的存放规则：敏感值（密钥、Token 等）必须配到 Nacos 配置中心，禁止写进部署脚本；非敏感值（域名、地址、端口、外部服务 URL 等）写入测试/生产各自的部署脚本。部署脚本中找不到的值仍按本规则写「待确认」或留空，禁止自行补全。
 
+## ⚠️ 可部署性自包含铁律（写代码之前考虑）
+
+- ⚠️ **写任何逻辑、用任何环境变量/配置值之前，必须先把"这个改动上线后部署怎么办"想清楚**：能直接写死的就写死，该放部署脚本的就放部署脚本，该配配置中心的就配配置中心。所有环境准备（建表、迁移、字段变更、初始化/导入数据、配置下发）一律内嵌到部署脚本自动完成。**达成的效果：上线时只需执行部署脚本，数据库迁移、人工改配置等一切操作全部免掉，上线后零操心。**
+- ⚠️ **触发时机是写代码之前，不是部署的时候。** 禁止先写代码、等要部署了再补部署脚本。每写一个涉及环境准备的改动，部署逻辑必须随之一起落地，不允许"代码完成、部署待办"的中间态。
+- ⚠️ **写完涉及环境准备的改动，必须当场自查三问**（参考 DELETE 铁律格式；任一答案为「是」而部署脚本无对应逻辑 → **该改动不算完成**）：
+  1. **改数据库了吗？** 新增/修改表、字段或数据 → 部署脚本必须有幂等 schema 确保逻辑（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`ensure_xxx()` 前置函数），加列/建表失败即停止部署。
+  2. **改配置了吗？** 新增/修改环境变量、Nacos 配置、部署脚本值 → 具体值必须已落地部署脚本或配置中心，禁止只写占位符或"待确认"。
+  3. **要初始化/搬运数据吗？** 需要初始化、导入、转换数据 → 必须脚本化进部署流程自动完成。
+- ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是上线遗漏的根源**（测试环境做了、生产环境容易忘）。
+- ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
+- ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
+
 ## ⚠️ 排查与协作铁律
 
 - ⚠️ **排查「以前能用、现在不行」类问题时禁止用绕过手段掩盖问题**（改配置屏蔽报错、写同步脚本搬数据、临时禁用校验等），必须先定位根因再修复。
@@ -83,6 +95,10 @@
 - ⚠️ **截图必须通过 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 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
+  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`）。
 - ⚠️ **私有仓库的 PR/Issue 正文中插入截图，禁止使用 `raw.githubusercontent.com` 链接，必须使用 `github.com/OWNER/REPO/blob/BRANCH/path?raw=true` 格式。** 原因：`raw.githubusercontent.com` 不识别 GitHub 网页端的登录态（session cookie），GitHub 渲染 PR/Issue 正文图片时走的是 camo 图片代理服务器端匿名拉取——对私有仓库该链接返回 404，导致图片框显示为普通文字链接而非图片；`github.com/.../blob/...?raw=true` 走的是 github.com 主域名，能通过登录态正确鉴权，图片才能正常渲染。凡是「先 `git add -f` 把截图提交进 `screenshots/` 目录、再在 PR 描述里用 Markdown 引用」的流程，图片链接一律拼接为后一种格式。
 
 ## 安全
@@ -233,10 +249,7 @@
 
 ## 部署规则
 
-- 发版统一执行 `./release.sh`。
-- ⚠️ **部署流程必须自包含、可直接使用**：开发过程中涉及的任何环境准备工作（数据迁移、建表、字段变更、初始化数据、配置下发等），都必须内嵌到部署流程中自动完成。部署到测试环境 / 生产环境后，功能应直接可用，**不依赖任何人记得在部署前后手动补做步骤**。
-- ⚠️ **发现「需要手动补做的步骤」= 部署流程有缺口**：若某次部署发现还需要人工执行迁移、导数据、改配置等额外步骤功能才能用，说明该步骤未被自动化——应把它纳入部署流程，而不是继续靠记性每次手动补。**人为手动步骤是上线遗漏的根源**（测试环境做了、生产环境容易忘）。
-- ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
+- 发版统一执行 `./release.sh`。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节）
 - ⚠️ 部署测试环境必须使用 `/deploy-test` skill。任何包含「部署测试」「发布测试」「上线测试」「部署test」「推到test」「部署到测试环境」等表述的需求，必须先调用 `Skill` 工具加载 `deploy-test`，严禁跳过 skill 直接执行部署操作。
 - ⚠️ 部署测试环境的正确流程是：当前分支 → 合并到 test 分支 → 推送 test → 触发部署 → 切回原分支。禁止直接在 test 分支上提交代码，禁止跳过合并步骤直接部署功能分支。
 

package/package.json

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

package/rules/global.md

@@ -33,6 +33,18 @@ name: "通用规则"
 - ⚠️ **上述来源都找不到的，就写「待确认」或留空，禁止自行补全。** 错误的推断值比留空危害更大——留空会在运行时报错、立刻暴露；错误的推断值可能静默运行数月后才被发现（如请求打到了错误的环境），排查成本极高。
 - ⚠️ **代码中使用环境变量占位符（如 `process.env.XXX`）时，必须同时确认测试/生产部署脚本（或配置中心）已提供该变量的具体值。** 禁止只写占位符不落地——代码能编译不代表部署后取值非空。具体值的存放规则：敏感值（密钥、Token 等）必须配到 Nacos 配置中心，禁止写进部署脚本；非敏感值（域名、地址、端口、外部服务 URL 等）写入测试/生产各自的部署脚本。部署脚本中找不到的值仍按本规则写「待确认」或留空，禁止自行补全。
 
+## ⚠️ 可部署性自包含铁律（写代码之前考虑）
+
+- ⚠️ **写任何逻辑、用任何环境变量/配置值之前，必须先把"这个改动上线后部署怎么办"想清楚**：能直接写死的就写死，该放部署脚本的就放部署脚本，该配配置中心的就配配置中心。所有环境准备（建表、迁移、字段变更、初始化/导入数据、配置下发）一律内嵌到部署脚本自动完成。**达成的效果：上线时只需执行部署脚本，数据库迁移、人工改配置等一切操作全部免掉，上线后零操心。**
+- ⚠️ **触发时机是写代码之前，不是部署的时候。** 禁止先写代码、等要部署了再补部署脚本。每写一个涉及环境准备的改动，部署逻辑必须随之一起落地，不允许"代码完成、部署待办"的中间态。
+- ⚠️ **写完涉及环境准备的改动，必须当场自查三问**（参考 DELETE 铁律格式；任一答案为「是」而部署脚本无对应逻辑 → **该改动不算完成**）：
+  1. **改数据库了吗？** 新增/修改表、字段或数据 → 部署脚本必须有幂等 schema 确保逻辑（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`ensure_xxx()` 前置函数），加列/建表失败即停止部署。
+  2. **改配置了吗？** 新增/修改环境变量、Nacos 配置、部署脚本值 → 具体值必须已落地部署脚本或配置中心，禁止只写占位符或"待确认"。
+  3. **要初始化/搬运数据吗？** 需要初始化、导入、转换数据 → 必须脚本化进部署流程自动完成。
+- ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是上线遗漏的根源**（测试环境做了、生产环境容易忘）。
+- ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
+- ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
+
 ## ⚠️ 排查与协作铁律
 
 - ⚠️ **排查「以前能用、现在不行」类问题时禁止用绕过手段掩盖问题**（改配置屏蔽报错、写同步脚本搬数据、临时禁用校验等），必须先定位根因再修复。
@@ -83,6 +95,10 @@ name: "通用规则"
 - ⚠️ **截图必须通过 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 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
+  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`）。
 - ⚠️ **私有仓库的 PR/Issue 正文中插入截图，禁止使用 `raw.githubusercontent.com` 链接，必须使用 `github.com/OWNER/REPO/blob/BRANCH/path?raw=true` 格式。** 原因：`raw.githubusercontent.com` 不识别 GitHub 网页端的登录态（session cookie），GitHub 渲染 PR/Issue 正文图片时走的是 camo 图片代理服务器端匿名拉取——对私有仓库该链接返回 404，导致图片框显示为普通文字链接而非图片；`github.com/.../blob/...?raw=true` 走的是 github.com 主域名，能通过登录态正确鉴权，图片才能正常渲染。凡是「先 `git add -f` 把截图提交进 `screenshots/` 目录、再在 PR 描述里用 Markdown 引用」的流程，图片链接一律拼接为后一种格式。
 
 ## 安全
@@ -233,10 +249,7 @@ name: "通用规则"
 
 ## 部署规则
 
-- 发版统一执行 `./release.sh`。
-- ⚠️ **部署流程必须自包含、可直接使用**：开发过程中涉及的任何环境准备工作（数据迁移、建表、字段变更、初始化数据、配置下发等），都必须内嵌到部署流程中自动完成。部署到测试环境 / 生产环境后，功能应直接可用，**不依赖任何人记得在部署前后手动补做步骤**。
-- ⚠️ **发现「需要手动补做的步骤」= 部署流程有缺口**：若某次部署发现还需要人工执行迁移、导数据、改配置等额外步骤功能才能用，说明该步骤未被自动化——应把它纳入部署流程，而不是继续靠记性每次手动补。**人为手动步骤是上线遗漏的根源**（测试环境做了、生产环境容易忘）。
-- ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
+- 发版统一执行 `./release.sh`。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节）
 - ⚠️ 部署测试环境必须使用 `/deploy-test` skill。任何包含「部署测试」「发布测试」「上线测试」「部署test」「推到test」「部署到测试环境」等表述的需求，必须先调用 `Skill` 工具加载 `deploy-test`，严禁跳过 skill 直接执行部署操作。
 - ⚠️ 部署测试环境的正确流程是：当前分支 → 合并到 test 分支 → 推送 test → 触发部署 → 切回原分支。禁止直接在 test 分支上提交代码，禁止跳过合并步骤直接部署功能分支。
 

package/skills/create-pr/SKILL.md

@@ -94,6 +94,30 @@ gh pr create \
 - 关联 issue：如有
 - Milestone：如有
 
+### 7. 创建 PR 后收尾检查（冲突 + 静态编译 + 发版本）
+
+⚠️ 创建 PR 后，三步收尾缺一不可，禁止创建完 PR 就直接抛给 reviewer。
+
+**① 与主分支冲突检查**：
+```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 只做一件事
@@ -101,5 +125,6 @@ gh pr create \
 - ⚠️ 必须附截图作为可视化证据
 - ⚠️ 截图禁止提交到 Git 仓库
 - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
+- ⚠️ 创建 PR 后必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 7）
 - 先开 Draft PR，准备好再标记 Ready for review
 - 作者不能 Approve 自己的 PR

package/skills/deploy-test/SKILL.md

@@ -87,7 +87,7 @@ git checkout "$ORIGINAL_BRANCH"
 
 - ⚠️ 推送 test 后必须立即执行 `git push origin test`
 - ⚠️ 部署完成后必须立即切回原功能分支
-- ⚠️ 部署必须自包含：migration、配置变更、依赖检查全部脚本化自动执行，禁止部署后人工补操作
+- ⚠️ 部署必须自包含：migration、配置变更、依赖检查全部脚本化自动执行，禁止部署后人工补操作（自包含铁律见 AGENTS.base.md「⚠️ 可部署性自包含铁律」章节，写代码之前就要考虑）
 - ⚠️ 合并到 test 发生冲突时，必须用 `-X theirs`（以当前功能分支为准），因为当前分支是最新代码，test 旧版本直接覆盖即可。
 - 禁止直接往 test 分支提交代码
 - 敏感信息（密钥、Token）必须从 Nacos 配置中心拉取，不得写死