@routerhub/agent-rules 1.5.66 → 1.5.68

package/AGENTS.base.md

@@ -1,5 +1,9 @@
 # Copilot Agent Rules - Base
 
+## 🚨 元规则（最高优先级）
+
+**本文件中的每一条规则都是强制规则，不存在"建议"或"可选"。** 所有带 ⚠️ 标记的规则不可协商，不可因"上下文压缩""注意力分散""对话太长"等任何原因遗漏或跳过。
+
 以下为始终生效的核心规则。各项目可通过 `AGENTS.private.md` 添加项目特定规则。
 
 ## ⚠️ 规则修改入口（必读）
@@ -32,6 +36,7 @@
 - ⚠️ **强制要求：所有 PR 必须附上相关截图作为可视化证据**，无论是否涉及 UI 改动。截图需包含：功能效果截图、测试结果截图、关键代码变更对比截图等，让 reviewer 无需拉取代码即可直观理解改动内容与验证结果。
 - PR 的目标是让审阅者在不依赖私下沟通的情况下独立理解、验证并放心 Approve；一个好的 PR 必须自解释。
 - 每个 PR 必须能独立通过编译与测试，禁止出现”这个 PR 编译不过，要等下一个 PR 才能跑”的状态。
+- ⚠️ **强制要求：一个 PR 只做一件事**。每个 PR 必须聚焦单一功能改动，按功能维度划分，禁止将多个不相关的功能、修复或重构混在同一个 PR 中。PR 的拆分粒度以”功能”为单位：一个完整的功能点（如新增用户登录、修复支付回调 bug、重构缓存模块）对应一个 PR；不属于同一功能的改动必须拆分为独立 PR。判断标准：如果一个 PR 的 Description 需要用”和”、”以及”、”同时”等连接词来描述多项不相关的改动，说明该 PR 应该拆分。
 - PR Title 必须用祈使句、现在时态描述“做了什么”，建议加模块/组件前缀，保持简洁且一行说清。
 - PR Title 示例：`[auth] Fix token refresh race condition on concurrent requests`、`[payments] Add idempotency key to charge API`、`[infra] Migrate cache layer from Redis 6 to Redis 7`。
 - PR Title 禁止使用 `fix bug`、`update code`、`改了一下` 等无法表达实际改动的标题。
@@ -334,10 +339,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.66",
+  "version": "1.5.68",
   "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 时被覆盖丢失。
@@ -32,6 +38,7 @@ name: "通用规则"
 - ⚠️ **强制要求：所有 PR 必须附上相关截图作为可视化证据**，无论是否涉及 UI 改动。截图需包含：功能效果截图、测试结果截图、关键代码变更对比截图等，让 reviewer 无需拉取代码即可直观理解改动内容与验证结果。
 - PR 的目标是让审阅者在不依赖私下沟通的情况下独立理解、验证并放心 Approve；一个好的 PR 必须自解释。
 - 每个 PR 必须能独立通过编译与测试，禁止出现”这个 PR 编译不过，要等下一个 PR 才能跑”的状态。
+- ⚠️ **强制要求：一个 PR 只做一件事**。每个 PR 必须聚焦单一功能改动，按功能维度划分，禁止将多个不相关的功能、修复或重构混在同一个 PR 中。PR 的拆分粒度以”功能”为单位：一个完整的功能点（如新增用户登录、修复支付回调 bug、重构缓存模块）对应一个 PR；不属于同一功能的改动必须拆分为独立 PR。判断标准：如果一个 PR 的 Description 需要用”和”、”以及”、”同时”等连接词来描述多项不相关的改动，说明该 PR 应该拆分。
 - PR Title 必须用祈使句、现在时态描述“做了什么”，建议加模块/组件前缀，保持简洁且一行说清。
 - PR Title 示例：`[auth] Fix token refresh race condition on concurrent requests`、`[payments] Add idempotency key to charge API`、`[infra] Migrate cache layer from Redis 6 to Redis 7`。
 - PR Title 禁止使用 `fix bug`、`update code`、`改了一下` 等无法表达实际改动的标题。