@routerhub/agent-rules 1.5.65 → 1.5.67

package/AGENTS.base.md

@@ -1,5 +1,9 @@
 # Copilot Agent Rules - Base
 
+## 🚨 元规则（最高优先级）
+
+**本文件中的每一条规则都是强制规则，不存在"建议"或"可选"。** 所有带 ⚠️ 标记的规则不可协商，不可因"上下文压缩""注意力分散""对话太长"等任何原因遗漏或跳过。
+
 以下为始终生效的核心规则。各项目可通过 `AGENTS.private.md` 添加项目特定规则。
 
 ## ⚠️ 规则修改入口（必读）
@@ -139,6 +143,7 @@ Closes #456
 - 编写 HTML 文档时，文档标题、正文、章节、说明文字、图注、表格等内容必须使用中文；仅代码、命令、专有名词、接口字段或页面 UI 原文可保留英文。
 - 编写 HTML 文档时，核心内容必须优先用截图、图片、流程图、对比图、标注图等可视化形式表达；图片内需添加箭头、圈选和简短中文标注，尽量减少英文字段和长段文字，能用可视化表达的内容不得只用文字说明。
 - 编写 HTML 文档时，所有图片资源（包括截图、图表、插图等）必须以 base64 data URI 形式内嵌到 HTML 中，禁止引用或额外输出独立的 PNG、JPG、JPEG、SVG、WebP 等图片文件，确保他人只打开 HTML 文件即可看到全部内容并用于发版。
+- ⚠️ **HTML 报告/文档中的所有图片必须支持点击放大、全屏查看**：每张图片必须可点击，点击后弹出全屏遮罩层（lightbox），展示原图或放大版本，支持关闭（点击遮罩背景或关闭按钮）和键盘 ESC 关闭。实现方式：在 HTML 内嵌一段通用 JS 脚本，为所有图片绑定 click 事件，弹出全屏遮罩层展示该图片，遮罩层背景半透明黑色、图片居中自适应屏幕。
 - 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
 - ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
@@ -333,10 +338,12 @@ function FieldTooltip({ text }: { text: string }) {
 - `.env` 文件中仅允许配置端口号（如 `PORT`、`API_PORT` 等），其余所有配置项（API 地址、数据库连接、第三方服务地址等）必须直接写死到代码中。
 - 密钥、Token、密码、证书等敏感信息不得写入 `.env` 或代码中，必须统一配置到 Nacos 配置中心，应用启动时从 Nacos 拉取。
 - 用户说「部署测试环境」时，必须按以下步骤执行：
-  1. **test 分支检查**：如果当前项目的 `test` 分支不存在，从主分支（`main` 或 `master`）创建 `test` 分支并推送到远程。
-  2. **合并当前分支到 test**：将当前功能分支合并到 `test` 分支。
-  3. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
-  4. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
+  1. **记录当前分支**：在切分支之前，先记录当前所在的功能分支名称（`git branch --show-current`），后续步骤需要用它切回来。
+  2. **test 分支检查**：如果当前项目的 `test` 分支不存在，从主分支（`main` 或 `master`）创建 `test` 分支并推送到远程。
+  3. **合并当前分支到 test**：将当前功能分支合并到 `test` 分支。
+  4. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
+  5. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
+  6. ⚠️ **切回原功能分支**：部署和发版全部完成后，必须立即切回步骤 1 记录的原功能分支（`git checkout <原分支名>`），确保 VS Code 当前所在的 Git 分支恢复到部署前的功能分支，而不是停留在 `test` 分支。如果忘记切回，用户后续的开发工作会在 `test` 分支上进行，违反「禁止直接在 test 分支上提交代码」的规则。
 	- ⚠️ **部署必须自包含，禁止部署后人工补操作**：后端代码写完并部署时，所有依赖该代码的准备工作必须一并完成并通过自动化方式执行，不允许部署完成后再由人工手动执行命令补救。常见必须自动化的事项包括：
 	  - **数据库 migration**：涉及 schema 变更（新增表、字段、索引、约束等）时，必须同时编写 migration 脚本，并集成到部署流程中自动执行（如应用启动时自动 migrate、CI/CD 中跑 migrate 命令等），禁止部署后人工登数据库手动执行 DDL。
 	  - **数据迁移/回填脚本**：涉及存量数据清洗、转换、回填时，脚本必须随代码一起提交，并在部署流程中自动执行或在 PR 中明确写出执行计划。

package/package.json

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

package/rules/devops.md

@@ -10,10 +10,12 @@ outputName: "devops"
 - `.env` 文件中仅允许配置端口号（如 `PORT`、`API_PORT` 等），其余所有配置项（API 地址、数据库连接、第三方服务地址等）必须直接写死到代码中。
 - 密钥、Token、密码、证书等敏感信息不得写入 `.env` 或代码中，必须统一配置到 Nacos 配置中心，应用启动时从 Nacos 拉取。
 - 用户说「部署测试环境」时，必须按以下步骤执行：
-  1. **test 分支检查**：如果当前项目的 `test` 分支不存在，从主分支（`main` 或 `master`）创建 `test` 分支并推送到远程。
-  2. **合并当前分支到 test**：将当前功能分支合并到 `test` 分支。
-  3. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
-  4. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
+  1. **记录当前分支**：在切分支之前，先记录当前所在的功能分支名称（`git branch --show-current`），后续步骤需要用它切回来。
+  2. **test 分支检查**：如果当前项目的 `test` 分支不存在，从主分支（`main` 或 `master`）创建 `test` 分支并推送到远程。
+  3. **合并当前分支到 test**：将当前功能分支合并到 `test` 分支。
+  4. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
+  5. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
+  6. ⚠️ **切回原功能分支**：部署和发版全部完成后，必须立即切回步骤 1 记录的原功能分支（`git checkout <原分支名>`），确保 VS Code 当前所在的 Git 分支恢复到部署前的功能分支，而不是停留在 `test` 分支。如果忘记切回，用户后续的开发工作会在 `test` 分支上进行，违反「禁止直接在 test 分支上提交代码」的规则。
 	- ⚠️ **部署必须自包含，禁止部署后人工补操作**：后端代码写完并部署时，所有依赖该代码的准备工作必须一并完成并通过自动化方式执行，不允许部署完成后再由人工手动执行命令补救。常见必须自动化的事项包括：
 	  - **数据库 migration**：涉及 schema 变更（新增表、字段、索引、约束等）时，必须同时编写 migration 脚本，并集成到部署流程中自动执行（如应用启动时自动 migrate、CI/CD 中跑 migrate 命令等），禁止部署后人工登数据库手动执行 DDL。
 	  - **数据迁移/回填脚本**：涉及存量数据清洗、转换、回填时，脚本必须随代码一起提交，并在部署流程中自动执行或在 PR 中明确写出执行计划。

package/rules/global.md

@@ -2,6 +2,12 @@
 name: "通用规则"
 ---
 
+## 🚨 元规则（最高优先级）
+
+**本文件中的每一条规则都是强制规则，不存在"建议"或"可选"。** 所有带 ⚠️ 标记的规则不可协商，不可因"上下文压缩""注意力分散""对话太长"等任何原因遗漏或跳过。
+
+以下为始终生效的核心规则。各项目可通过 `AGENTS.private.md` 添加项目特定规则。
+
 ## ⚠️ 规则修改入口（必读）
 
 - **所有规则的新增、修改、删除，必须改 `AGENTS.base.md`（源文件），禁止直接改 `CLAUDE.md` 或 `AGENTS.md`**。`CLAUDE.md` 和 `AGENTS.md` 是 `node merge.js sync` 自动生成的输出文件，直接改动会在下次 sync 时被覆盖丢失。
@@ -139,6 +145,7 @@ Closes #456
 - 编写 HTML 文档时，文档标题、正文、章节、说明文字、图注、表格等内容必须使用中文；仅代码、命令、专有名词、接口字段或页面 UI 原文可保留英文。
 - 编写 HTML 文档时，核心内容必须优先用截图、图片、流程图、对比图、标注图等可视化形式表达；图片内需添加箭头、圈选和简短中文标注，尽量减少英文字段和长段文字，能用可视化表达的内容不得只用文字说明。
 - 编写 HTML 文档时，所有图片资源（包括截图、图表、插图等）必须以 base64 data URI 形式内嵌到 HTML 中，禁止引用或额外输出独立的 PNG、JPG、JPEG、SVG、WebP 等图片文件，确保他人只打开 HTML 文件即可看到全部内容并用于发版。
+- ⚠️ **HTML 报告/文档中的所有图片必须支持点击放大、全屏查看**：每张图片必须可点击，点击后弹出全屏遮罩层（lightbox），展示原图或放大版本，支持关闭（点击遮罩背景或关闭按钮）和键盘 ESC 关闭。实现方式：在 HTML 内嵌一段通用 JS 脚本，为所有图片绑定 click 事件，弹出全屏遮罩层展示该图片，遮罩层背景半透明黑色、图片居中自适应屏幕。
 - 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
 - ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。