@routerhub/agent-rules 1.5.180 → 1.5.181

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.base.md +7 -7
  2. package/package.json +1 -1
  3. package/rules/global.md +7 -7
package/AGENTS.base.md CHANGED
@@ -27,7 +27,7 @@
27
27
 
28
28
  ## ⚠️ 环境配置禁止推断
29
29
 
30
- - ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交���确认：
30
+ - ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交叉确认：
31
31
  1. 项目内的部署脚本、Dockerfile、CI 配置
32
32
  2. 实际 DNS 解析（`dig`/`nslookup`）
33
33
  3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
@@ -43,8 +43,8 @@
43
43
  1. **改数据库了吗？** 新增/修改表、字段或数据 → 部署脚本必须有幂等 schema 确保逻辑（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`ensure_xxx()` 前置函数），加列/建表失败即停止部署。
44
44
  2. **改配置了吗？** 新增/修改环境变量、Nacos 配置、部署脚本值 → 具体值必须已落地部署脚本或配置中心，禁止只写占位符或"待确认"。
45
45
  3. **要初始化/搬运数据吗？** 需要初始化、导入、转换数据 → 必须脚本化进部署流程自动完成。
46
- - ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是��线遗漏的根源**（测试环境做了、生产环境容易忘）。
47
- - ⚠️ **部署完成的定义 = 脚本执行完 �� 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
46
+ - ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是上线遗漏的根源**（测试环境做了、生产环境容易忘）。
47
+ - ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
48
48
  - ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
49
49
 
50
50
  ## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
@@ -66,7 +66,7 @@
66
66
  - ⚠️ **验证功能是否修复时，要用真实存在的数据/路径去测试**，避免用虚构的测试数据得出「失败」的假结论。
67
67
  - ⚠️ **定位并修复根因后，必须清理诊断过程中留下的临时改动**（调试代码、临时开关、测试脚本），不要把绕过方案的残留物留在代码里。
68
68
  - **某个工具/脚本报错时，先检查是否有残留的锁文件、临时文件、缓存导致的问题**，清理后重试；仍失败再切换备用方案，不要一遇报错就直接换路子。
69
- - **长任务或涉及截图等大内容的操���，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
69
+ - **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
70
70
  - ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
71
71
  - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
72
72
  - ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
@@ -88,7 +88,7 @@
88
88
 
89
89
  ## ⚠️ 页面功能验证铁律（真实数据 + 真实交互）
90
90
 
91
- - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些���测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
91
+ - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
92
92
  - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
93
93
 
94
94
  ## ⚠️ 可视化验证铁律（默认不写测试用例，用证据说话）
@@ -111,7 +111,7 @@
111
111
  ## Git 规范
112
112
 
113
113
  - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
114
- - ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` ��在 main 上生成「发布 vX.Y.Z」提交）。
114
+ - ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` 会在 main 上生成「发布 vX.Y.Z」提交）。
115
115
  - ⚠️ **从主分支拉/建功能分支之前，必须先直接拉取远程主分支（`git pull origin main`）**，确保基于最新的远程主分支拉分支，禁止基于过期的本地主分支创建分支。
116
116
  - ⚠️ **可评审 PR 的合并目标永远是仓库默认分支（如 `main`/`master`），不是 `test`**。`test` 分支只用于部署测试环境，只能通过 `/deploy-test` skill 直接 `merge` 更新（见「部署规则」），不发 PR、不走 code review；`test` 分支同样禁止直接提交代码。commit 必须中文，禁止 `git push --force`。
117
117
  - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
@@ -150,7 +150,7 @@
150
150
  2. `git worktree add -b feature/<任务简称> ../<会话标识>-work origin/main`——从 `origin/main` 检出到独立目录并新建分支，当前工作区完全不动。目录名用英文小写中划线（含会话唯一标识），进入前先确认该路径不存在。
151
151
  3. 在 worktree 目录内完成改动 → 编译/验证通过 → `git commit` → `git push -u origin feature/<任务简称>`。
152
152
  4. 任务结束（提交完成 / PR 合并）后 `git worktree remove ../<会话标识>-work` 清理。一个会话全程只对应一个 worktree。
153
- - ⚠️ **多副本仓库（A-/B-/C-/M- 前缀）叠���生效**：worktree 建在当前会话所在副本内（选哪个副本由「⚠️ 处理其他项目/副本时统一用 worktree 隔离」规则决定），本条规则负责副本内部的会话隔离，两者不冲突。
153
+ - ⚠️ **多副本仓库（A-/B-/C-/M- 前缀）叠加生效**：worktree 建在当前会话所在副本内（选哪个副本由「⚠️ 处理其他项目/副本时统一用 worktree 隔离」规则决定），本条规则负责副本内部的会话隔离，两者不冲突。
154
154
  - ⚠️ **worktree 只隔离「文件与 git」这一层**：端口、数据库、构建缓存、浏览器标签页等外部资源仍按各自规则隔离（如 agent-browser `--namespace`）。两个会话若改同一批文件，编辑阶段互不可见，冲突会推迟到合并回主分支时显式暴露——改动明显重叠的任务应合成一个会话完成，不要拆成两个 worktree 并行。
155
155
 
156
156
  ## PR 核心要求
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@routerhub/agent-rules",
3
- "version": "1.5.180",
3
+ "version": "1.5.181",
4
4
  "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
5
5
  "main": "AGENTS.base.md",
6
6
  "bin": {
package/rules/global.md CHANGED
@@ -27,7 +27,7 @@ name: "通用规则"
27
27
 
28
28
  ## ⚠️ 环境配置禁止推断
29
29
 
30
- - ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交���确认：
30
+ - ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交叉确认：
31
31
  1. 项目内的部署脚本、Dockerfile、CI 配置
32
32
  2. 实际 DNS 解析（`dig`/`nslookup`）
33
33
  3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
@@ -43,8 +43,8 @@ name: "通用规则"
43
43
  1. **改数据库了吗？** 新增/修改表、字段或数据 → 部署脚本必须有幂等 schema 确保逻辑（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`ensure_xxx()` 前置函数），加列/建表失败即停止部署。
44
44
  2. **改配置了吗？** 新增/修改环境变量、Nacos 配置、部署脚本值 → 具体值必须已落地部署脚本或配置中心，禁止只写占位符或"待确认"。
45
45
  3. **要初始化/搬运数据吗？** 需要初始化、导入、转换数据 → 必须脚本化进部署流程自动完成。
46
- - ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是��线遗漏的根源**（测试环境做了、生产环境容易忘）。
47
- - ⚠️ **部署完成的定义 = 脚本执行完 �� 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
46
+ - ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是上线遗漏的根源**（测试环境做了、生产环境容易忘）。
47
+ - ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
48
48
  - ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
49
49
 
50
50
  ## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
@@ -66,7 +66,7 @@ name: "通用规则"
66
66
  - ⚠️ **验证功能是否修复时，要用真实存在的数据/路径去测试**，避免用虚构的测试数据得出「失败」的假结论。
67
67
  - ⚠️ **定位并修复根因后，必须清理诊断过程中留下的临时改动**（调试代码、临时开关、测试脚本），不要把绕过方案的残留物留在代码里。
68
68
  - **某个工具/脚本报错时，先检查是否有残留的锁文件、临时文件、缓存导致的问题**，清理后重试；仍失败再切换备用方案，不要一遇报错就直接换路子。
69
- - **长任务或涉及截图等大内容的操���，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
69
+ - **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
70
70
  - ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
71
71
  - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
72
72
  - ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
@@ -88,7 +88,7 @@ name: "通用规则"
88
88
 
89
89
  ## ⚠️ 页面功能验证铁律（真实数据 + 真实交互）
90
90
 
91
- - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些���测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
91
+ - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
92
92
  - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
93
93
 
94
94
  ## ⚠️ 可视化验证铁律（默认不写测试用例，用证据说话）
@@ -111,7 +111,7 @@ name: "通用规则"
111
111
  ## Git 规范
112
112
 
113
113
  - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
114
- - ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` ��在 main 上生成「发布 vX.Y.Z」提交）。
114
+ - ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` 会在 main 上生成「发布 vX.Y.Z」提交）。
115
115
  - ⚠️ **从主分支拉/建功能分支之前，必须先直接拉取远程主分支（`git pull origin main`）**，确保基于最新的远程主分支拉分支，禁止基于过期的本地主分支创建分支。
116
116
  - ⚠️ **可评审 PR 的合并目标永远是仓库默认分支（如 `main`/`master`），不是 `test`**。`test` 分支只用于部署测试环境，只能通过 `/deploy-test` skill 直接 `merge` 更新（见「部署规则」），不发 PR、不走 code review；`test` 分支同样禁止直接提交代码。commit 必须中文，禁止 `git push --force`。
117
117
  - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
@@ -150,7 +150,7 @@ name: "通用规则"
150
150
  2. `git worktree add -b feature/<任务简称> ../<会话标识>-work origin/main`——从 `origin/main` 检出到独立目录并新建分支，当前工作区完全不动。目录名用英文小写中划线（含会话唯一标识），进入前先确认该路径不存在。
151
151
  3. 在 worktree 目录内完成改动 → 编译/验证通过 → `git commit` → `git push -u origin feature/<任务简称>`。
152
152
  4. 任务结束（提交完成 / PR 合并）后 `git worktree remove ../<会话标识>-work` 清理。一个会话全程只对应一个 worktree。
153
- - ⚠️ **多副本仓库（A-/B-/C-/M- 前缀）叠���生效**：worktree 建在当前会话所在副本内（选哪个副本由「⚠️ 处理其他项目/副本时统一用 worktree 隔离」规则决定），本条规则负责副本内部的会话隔离，两者不冲突。
153
+ - ⚠️ **多副本仓库（A-/B-/C-/M- 前缀）叠加生效**：worktree 建在当前会话所在副本内（选哪个副本由「⚠️ 处理其他项目/副本时统一用 worktree 隔离」规则决定），本条规则负责副本内部的会话隔离，两者不冲突。
154
154
  - ⚠️ **worktree 只隔离「文件与 git」这一层**：端口、数据库、构建缓存、浏览器标签页等外部资源仍按各自规则隔离（如 agent-browser `--namespace`）。两个会话若改同一批文件，编辑阶段互不可见，冲突会推迟到合并回主分支时显式暴露——改动明显重叠的任务应合成一个会话完成，不要拆成两个 worktree 并行。
155
155
 
156
156
  ## PR 核心要求