@routerhub/agent-rules 1.5.62 → 1.5.65

package/AGENTS.base.md

@@ -14,6 +14,12 @@
 - 页面 UI 内容（按钮、字段名、提示等）全部英文；如需中文在 `AGENTS.private.md` 中声明。
 - 仅修改网站协议、条款、页面文案等文本内容时，必须保留原有结构、格式、样式和布局，只替换文字；只有用户明确要求调整样式时，才允许同步修改样式。
 
+## 需求实现原则
+
+- ⚠️ **严格按用户原话实现需求，禁止擅自添加用户未要求的限制、规则或约束。** 例如用户说"展示一个轮播图"，就只实现轮播图功能，不得自行添加"最多 6 个元素"、"必须自动播放"等用户没提的限制。
+- 只有代码安全/性能的硬性必要（如防止无限循环、防止内存泄漏、防止 XSS 等）才允许添加隐含约束，且必须在实现时向用户说明添加原因。
+- 不确定某个限制或规则是否必要时，必须先询问用户，禁止直接添加。
+
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
@@ -135,6 +141,7 @@ Closes #456
 - 编写 HTML 文档时，所有图片资源（包括截图、图表、插图等）必须以 base64 data URI 形式内嵌到 HTML 中，禁止引用或额外输出独立的 PNG、JPG、JPEG、SVG、WebP 等图片文件，确保他人只打开 HTML 文件即可看到全部内容并用于发版。
 - 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
+- ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
 
 ## 新需求与回归测试准入
 
@@ -309,6 +316,15 @@ function FieldTooltip({ text }: { text: string }) {
 - `DeletedAt` 字段必须使用 `gorm.DeletedAt` 类型，严禁使用 `*time.Time`。`*time.Time` 不会触发 GORM v2 的软删除机制，会导致 `Delete()` 执行物理删除（DELETE FROM）而非软删除（UPDATE SET deleted_at）。
 - 新建 Model 时，优先嵌入已有的公共基础结构体（如包含 ID、CreatedAt、UpdatedAt、DeletedAt 的 BaseModel），避免各 Model 独立定义这些字段导致类型不一致。
 
+## 数据库 Auto-Migrate 规范
+
+- ⚠️ **禁止在代码中无条件执行 GORM AutoMigrate**。AutoMigrate 的执行必须由一个显式的开关（如配置项、环境变量或 feature flag）控制，默认关闭。
+- 应用启动时，如果检测到数据库 schema 与 Model 定义不匹配且 auto-migrate 开关未开启，必须：
+  1. **明确报错并拒绝启动**，在日志中输出具体的 schema 差异信息（哪些表/字段缺失或不匹配）。
+  2. **提示运维手动开启 auto-migrate 开关**，给出开关名称和开启方式（例如「请将配置 `DB_AUTO_MIGRATE` 设为 `true` 后重新部署」），禁止静默挂掉或输出含糊错误。
+- auto-migrate 脚本必须随代码一起提交并部署（满足「部署自包含」要求），只是执行时机由开关控制，确保运维可审计、可控制。
+- 生产环境 auto-migrate 执行完毕后，建议运维立即关闭开关并重新部署，避免后续非预期的 DDL 操作。
+
 <!-- @domain: devops -->
 
 ## 部署规则
@@ -328,15 +344,3 @@ function FieldTooltip({ text }: { text: string }) {
 	  - **依赖更新**：涉及新的系统依赖（如新的中间件、新的外部服务地址、新的环境变量等）时，必须在部署脚本中自动检查依赖可用性，不存在时部署失败并明确报错，禁止静默跳过等人工发现。
 	  - **缓存/队列/索引重建**：涉及 Redis 缓存结构变更、消息队列 topic 新增、ES 索引 mapping 变更等，必须脚本化并自动执行。
 	  - 以上所有自动化脚本必须在 PR 的 Test Plan 中明确写出执行时机（部署前/部署中/部署后）、执行方式和验证方法，不得只写"部署后手动执行"。
-
-## 用户通知
-
-- ⚠️ **强制要求：任务完成或需要用户决策时，必须弹出 macOS 对话框提醒用户，不得静默结束。**
-- 通知场景：任务完成（代码写完、PR 创建、部署完成等）、需要用户决策（等待审批、需要确认、需要输入等）。
-- 通知方式（动态取当前工作目录，适配任意项目）：
-  ```bash
-  osascript -e 'display dialog "消息内容" with title "Claude Code" buttons {"按钮文字"} default button 1 with icon note' && code "$(pwd)" --reuse-window
-  ```
-- 对话框不得自动消失（不加 `giving up after` 参数），必须等用户手动点击。
-- `$(pwd)` 动态取当前会话的工作目录，确保多项目场景下点击按钮后能跳转到正确的 VS Code 窗口。
-- 按钮文字需清晰表明操作（如「收到 👌」「去看看 👀」等）。

package/package.json

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

package/rules/devops.md

@@ -21,15 +21,3 @@ outputName: "devops"
 	  - **依赖更新**：涉及新的系统依赖（如新的中间件、新的外部服务地址、新的环境变量等）时，必须在部署脚本中自动检查依赖可用性，不存在时部署失败并明确报错，禁止静默跳过等人工发现。
 	  - **缓存/队列/索引重建**：涉及 Redis 缓存结构变更、消息队列 topic 新增、ES 索引 mapping 变更等，必须脚本化并自动执行。
 	  - 以上所有自动化脚本必须在 PR 的 Test Plan 中明确写出执行时机（部署前/部署中/部署后）、执行方式和验证方法，不得只写"部署后手动执行"。
-
-## 用户通知
-
-- ⚠️ **强制要求：任务完成或需要用户决策时，必须弹出 macOS 对话框提醒用户，不得静默结束。**
-- 通知场景：任务完成（代码写完、PR 创建、部署完成等）、需要用户决策（等待审批、需要确认、需要输入等）。
-- 通知方式（动态取当前工作目录，适配任意项目）：
-  ```bash
-  osascript -e 'display dialog "消息内容" with title "Claude Code" buttons {"按钮文字"} default button 1 with icon note' && code "$(pwd)" --reuse-window
-  ```
-- 对话框不得自动消失（不加 `giving up after` 参数），必须等用户手动点击。
-- `$(pwd)` 动态取当前会话的工作目录，确保多项目场景下点击按钮后能跳转到正确的 VS Code 窗口。
-- 按钮文字需清晰表明操作（如「收到 👌」「去看看 👀」等）。

package/rules/global.md

@@ -14,6 +14,12 @@ name: "通用规则"
 - 页面 UI 内容（按钮、字段名、提示等）全部英文；如需中文在 `AGENTS.private.md` 中声明。
 - 仅修改网站协议、条款、页面文案等文本内容时，必须保留原有结构、格式、样式和布局，只替换文字；只有用户明确要求调整样式时，才允许同步修改样式。
 
+## 需求实现原则
+
+- ⚠️ **严格按用户原话实现需求，禁止擅自添加用户未要求的限制、规则或约束。** 例如用户说"展示一个轮播图"，就只实现轮播图功能，不得自行添加"最多 6 个元素"、"必须自动播放"等用户没提的限制。
+- 只有代码安全/性能的硬性必要（如防止无限循环、防止内存泄漏、防止 XSS 等）才允许添加隐含约束，且必须在实现时向用户说明添加原因。
+- 不确定某个限制或规则是否必要时，必须先询问用户，禁止直接添加。
+
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
@@ -135,6 +141,7 @@ Closes #456
 - 编写 HTML 文档时，所有图片资源（包括截图、图表、插图等）必须以 base64 data URI 形式内嵌到 HTML 中，禁止引用或额外输出独立的 PNG、JPG、JPEG、SVG、WebP 等图片文件，确保他人只打开 HTML 文件即可看到全部内容并用于发版。
 - 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
+- ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
 
 ## 新需求与回归测试准入
 

package/rules/go-backend.md

@@ -13,3 +13,12 @@ outputName: "go-backend"
 
 - `DeletedAt` 字段必须使用 `gorm.DeletedAt` 类型，严禁使用 `*time.Time`。`*time.Time` 不会触发 GORM v2 的软删除机制，会导致 `Delete()` 执行物理删除（DELETE FROM）而非软删除（UPDATE SET deleted_at）。
 - 新建 Model 时，优先嵌入已有的公共基础结构体（如包含 ID、CreatedAt、UpdatedAt、DeletedAt 的 BaseModel），避免各 Model 独立定义这些字段导致类型不一致。
+
+## 数据库 Auto-Migrate 规范
+
+- ⚠️ **禁止在代码中无条件执行 GORM AutoMigrate**。AutoMigrate 的执行必须由一个显式的开关（如配置项、环境变量或 feature flag）控制，默认关闭。
+- 应用启动时，如果检测到数据库 schema 与 Model 定义不匹配且 auto-migrate 开关未开启，必须：
+  1. **明确报错并拒绝启动**，在日志中输出具体的 schema 差异信息（哪些表/字段缺失或不匹配）。
+  2. **提示运维手动开启 auto-migrate 开关**，给出开关名称和开启方式（例如「请将配置 `DB_AUTO_MIGRATE` 设为 `true` 后重新部署」），禁止静默挂掉或输出含糊错误。
+- auto-migrate 脚本必须随代码一起提交并部署（满足「部署自包含」要求），只是执行时机由开关控制，确保运维可审计、可控制。
+- 生产环境 auto-migrate 执行完毕后，建议运维立即关闭开关并重新部署，避免后续非预期的 DDL 操作。