@routerhub/agent-rules 1.5.58 → 1.5.60

package/AGENTS.base.md

@@ -180,6 +180,12 @@ Closes #456
 - 涉及配置、官网或其他系统联动时，需同时打开所有相关页面，并按实际操作路径展示联动结果，方便直接验证。
 - 若客观上无法可视化展示，需说明原因，并补充截图、录屏、日志或请求响应作为替代证据。
 
+## 外部文档查看（Notion / 需登录页面）
+
+- 查看 Notion 文档或其他需要登录态的外部页面时，必须使用 Chrome DevTools MCP（`navigate_page` + `take_snapshot` / `evaluate_script`），禁止使用 WebFetch。WebFetch 无法处理需要登录的页面，会直接报错看不到内容；浏览器 MCP 可复用用户已有的登录态。
+- 页面 snapshot 太大无法直接读取时，用 `evaluate_script` 执行 `document.body.innerText` 或更精准的选择器提取文本内容，再分段读取。
+- 提取到的外部文档内容涉及项目关键规范/数据时，应保存为长期记忆（`memory/` 目录）方便后续引用。
+
 <!-- @domain: frontend -->
 
 ## Figma 还原规范
@@ -318,3 +324,10 @@ function FieldTooltip({ text }: { text: string }) {
   2. **合并当前分支到 test**：将当前功能分支合并到 `test` 分支。
   3. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
   4. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
+	- ⚠️ **部署必须自包含，禁止部署后人工补操作**：后端代码写完并部署时，所有依赖该代码的准备工作必须一并完成并通过自动化方式执行，不允许部署完成后再由人工手动执行命令补救。常见必须自动化的事项包括：
+	  - **数据库 migration**：涉及 schema 变更（新增表、字段、索引、约束等）时，必须同时编写 migration 脚本，并集成到部署流程中自动执行（如应用启动时自动 migrate、CI/CD 中跑 migrate 命令等），禁止部署后人工登数据库手动执行 DDL。
+	  - **数据迁移/回填脚本**：涉及存量数据清洗、转换、回填时，脚本必须随代码一起提交，并在部署流程中自动执行或在 PR 中明确写出执行计划。
+	  - **配置变更**：涉及 Nacos 配置中心新增/修改配置项时，配置变更必须与代码部署同步完成，并在部署流程中自动同步或通过配置管理工具批量推送。
+	  - **依赖更新**：涉及新的系统依赖（如新的中间件、新的外部服务地址、新的环境变量等）时，必须在部署脚本中自动检查依赖可用性，不存在时部署失败并明确报错，禁止静默跳过等人工发现。
+	  - **缓存/队列/索引重建**：涉及 Redis 缓存结构变更、消息队列 topic 新增、ES 索引 mapping 变更等，必须脚本化并自动执行。
+	  - 以上所有自动化脚本必须在 PR 的 Test Plan 中明确写出执行时机（部署前/部署中/部署后）、执行方式和验证方法，不得只写"部署后手动执行"。

package/package.json

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

package/rules/devops.md

@@ -14,3 +14,10 @@ outputName: "devops"
   2. **合并当前分支到 test**：将当前功能分支合并到 `test` 分支。
   3. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
   4. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
+	- ⚠️ **部署必须自包含，禁止部署后人工补操作**：后端代码写完并部署时，所有依赖该代码的准备工作必须一并完成并通过自动化方式执行，不允许部署完成后再由人工手动执行命令补救。常见必须自动化的事项包括：
+	  - **数据库 migration**：涉及 schema 变更（新增表、字段、索引、约束等）时，必须同时编写 migration 脚本，并集成到部署流程中自动执行（如应用启动时自动 migrate、CI/CD 中跑 migrate 命令等），禁止部署后人工登数据库手动执行 DDL。
+	  - **数据迁移/回填脚本**：涉及存量数据清洗、转换、回填时，脚本必须随代码一起提交，并在部署流程中自动执行或在 PR 中明确写出执行计划。
+	  - **配置变更**：涉及 Nacos 配置中心新增/修改配置项时，配置变更必须与代码部署同步完成，并在部署流程中自动同步或通过配置管理工具批量推送。
+	  - **依赖更新**：涉及新的系统依赖（如新的中间件、新的外部服务地址、新的环境变量等）时，必须在部署脚本中自动检查依赖可用性，不存在时部署失败并明确报错，禁止静默跳过等人工发现。
+	  - **缓存/队列/索引重建**：涉及 Redis 缓存结构变更、消息队列 topic 新增、ES 索引 mapping 变更等，必须脚本化并自动执行。
+	  - 以上所有自动化脚本必须在 PR 的 Test Plan 中明确写出执行时机（部署前/部署中/部署后）、执行方式和验证方法，不得只写"部署后手动执行"。

package/rules/global.md

@@ -179,3 +179,9 @@ Closes #456
 - 完成任务后的汇报优先提供可视化结果，能打开页面时就直接在集成浏览器中打开，并定位到相关区域后再汇报。
 - 涉及配置、官网或其他系统联动时，需同时打开所有相关页面，并按实际操作路径展示联动结果，方便直接验证。
 - 若客观上无法可视化展示，需说明原因，并补充截图、录屏、日志或请求响应作为替代证据。
+
+## 外部文档查看（Notion / 需登录页面）
+
+- 查看 Notion 文档或其他需要登录态的外部页面时，必须使用 Chrome DevTools MCP（`navigate_page` + `take_snapshot` / `evaluate_script`），禁止使用 WebFetch。WebFetch 无法处理需要登录的页面，会直接报错看不到内容；浏览器 MCP 可复用用户已有的登录态。
+- 页面 snapshot 太大无法直接读取时，用 `evaluate_script` 执行 `document.body.innerText` 或更精准的选择器提取文本内容，再分段读取。
+- 提取到的外部文档内容涉及项目关键规范/数据时，应保存为长期记忆（`memory/` 目录）方便后续引用。