@routerhub/agent-rules 1.5.121 → 1.5.123

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 (5) hide show
  1. package/AGENTS.base.md +10 -2
  2. package/CHANGELOG.md +12 -0
  3. package/package.json +1 -1
  4. package/rules/global.md +10 -2
  5. package/skills/create-pr/SKILL.md +4 -4
package/AGENTS.base.md CHANGED
@@ -45,6 +45,14 @@
45
45
  - ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
46
46
  - ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
47
47
 
48
+ ## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
49
+
50
+ - ⚠️ **在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。** 测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建。跳过这一步直接验证，报出的缺表/缺字段错误是环境问题，不是代码问题，极易误判。
51
+ - ⚠️ **验证前必须显式执行以下任一前置动作，禁止跳过：**
52
+ 1. **临时打开 AutoMigrate 开关**，启动/重启服务完成建表后，恢复默认关闭；
53
+ 2. **手动执行幂等建表/加字段 SQL**（`CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`），并确认目标表/字段已存在。
54
+ - ⚠️ **遇到缺表/缺字段类报错时，第一优先级检查表结构是否就绪，禁止直接定性为代码 bug。** 特征报错：`relation "..." does not exist`、`table ... does not exist`、`column ... does not exist`、`Unknown column`、`Unrecognized name` 等。先查表（`\d 表名` / `DESCRIBE` / `information_schema`）确认就绪后再排查代码。
55
+
48
56
  ## ⚠️ 排查与协作铁律
49
57
 
50
58
  - ⚠️ **排查「以前能用、现在不行」类问题时禁止用绕过手段掩盖问题**（改配置屏蔽报错、写同步脚本搬数据、临时禁用校验等），必须先定位根因再修复。
@@ -104,8 +112,8 @@
104
112
  - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
105
113
  - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
106
114
  - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
107
- - ⚠️ **创建 PR 后，必须先检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。
108
- - ⚠️ **创建 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
115
+ - ⚠️ **每次修改 PR 后（含创建 PR、push 新提交、响应 review 意见重新推送等所有改动 PR 的动作之后），都必须检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。主分支随时可能前进，一个创建时无冲突的 PR 可能在后续 push 后悄悄变冲突，因此每次改动 PR 后都必须重新检查，禁止只在创建时查一次就以为高枕无忧。
116
+ - ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
109
117
  1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
110
118
  2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
111
119
  3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。
package/CHANGELOG.md CHANGED
@@ -2,6 +2,18 @@
2
2
 
3
3
  所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
4
4
 
5
+ ## [1.5.123] - 2026-08-12
6
+
7
+ ### Changed
8
+
9
+ - 强化「创建 PR 后冲突检查」规则为「每次修改 PR 后都必须检查与主分支冲突」：原先只在创建 PR 时查一次 `gh pr view <PR> --json mergeable -q .mergeable`，现在 push 新提交、响应 review 意见重新推送等每次改动 PR 后都必须重新检查并解决冲突。原因：主分支随时可能前进，创建时无冲突的 PR 可能在后续 push 后悄悄变冲突。同步更新 `create-pr` skill 第 7 步与「重要规则」章节。
10
+
11
+ ## [1.5.122] - 2026-08-11
12
+
13
+ ### Added
14
+
15
+ - 新增「测试环境功能验证前置铁律」（防止缺表报错误判为代码问题）：在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。原因：测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建，跳过前置检查直接验证，报出的缺表/缺字段错误是环境问题而非代码问题，极易误判。验证前必须显式二选一：① 临时打开 AutoMigrate 开关（用后恢复默认关闭）② 手动执行幂等建表/加字段 SQL（`CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`）；遇到缺表/缺字段类报错（`relation ... does not exist`、`column ... does not exist`、`Unrecognized name` 等）时，第一优先级检查表结构是否就绪，禁止直接定性为代码 bug。
16
+
5
17
  ## [1.5.121] - 2026-08-10
6
18
 
7
19
  ### Added
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@routerhub/agent-rules",
3
- "version": "1.5.121",
3
+ "version": "1.5.123",
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
@@ -45,6 +45,14 @@ name: "通用规则"
45
45
  - ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
46
46
  - ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
47
47
 
48
+ ## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
49
+
50
+ - ⚠️ **在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。** 测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建。跳过这一步直接验证，报出的缺表/缺字段错误是环境问题，不是代码问题，极易误判。
51
+ - ⚠️ **验证前必须显式执行以下任一前置动作，禁止跳过：**
52
+ 1. **临时打开 AutoMigrate 开关**，启动/重启服务完成建表后，恢复默认关闭；
53
+ 2. **手动执行幂等建表/加字段 SQL**（`CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`），并确认目标表/字段已存在。
54
+ - ⚠️ **遇到缺表/缺字段类报错时，第一优先级检查表结构是否就绪，禁止直接定性为代码 bug。** 特征报错：`relation "..." does not exist`、`table ... does not exist`、`column ... does not exist`、`Unknown column`、`Unrecognized name` 等。先查表（`\d 表名` / `DESCRIBE` / `information_schema`）确认就绪后再排查代码。
55
+
48
56
  ## ⚠️ 排查与协作铁律
49
57
 
50
58
  - ⚠️ **排查「以前能用、现在不行」类问题时禁止用绕过手段掩盖问题**（改配置屏蔽报错、写同步脚本搬数据、临时禁用校验等），必须先定位根因再修复。
@@ -104,8 +112,8 @@ name: "通用规则"
104
112
  - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
105
113
  - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
106
114
  - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
107
- - ⚠️ **创建 PR 后，必须先检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。
108
- - ⚠️ **创建 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
115
+ - ⚠️ **每次修改 PR 后（含创建 PR、push 新提交、响应 review 意见重新推送等所有改动 PR 的动作之后），都必须检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。主分支随时可能前进，一个创建时无冲突的 PR 可能在后续 push 后悄悄变冲突，因此每次改动 PR 后都必须重新检查，禁止只在创建时查一次就以为高枕无忧。
116
+ - ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
109
117
  1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
110
118
  2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
111
119
  3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。
package/skills/create-pr/SKILL.md CHANGED
@@ -94,11 +94,11 @@ gh pr create \
94
94
  - 关联 issue：如有
95
95
  - Milestone：如有
96
96
 
97
- ### 7. 创建 PR 后收尾检查（冲突 + 静态编译 + 发版本）
97
+ ### 7. 每次修改 PR 后收尾检查（冲突 + 静态编译 + 发版本）
98
98
 
99
- ⚠️ 创建 PR 后，三步收尾缺一不可，禁止创建完 PR 就直接抛给 reviewer。
99
+ ⚠️ 创建 PR 后、以及每次 push 新提交/响应 review 意见重新推送后，三步收尾缺一不可，禁止改完 PR 就直接抛给 reviewer 或当作完事。
100
100
 
101
- **① 与主分支冲突检查**：
101
+ **① 与主分支冲突检查**（每次修改 PR 后都要重新执行，禁止只在创建时查一次）：
102
102
  ```bash
103
103
  gh pr view <PR> --json mergeable -q .mergeable
104
104
  ```
@@ -125,6 +125,6 @@ gh pr checks <PR>
125
125
  - ⚠️ 必须附截图作为可视化证据
126
126
  - ⚠️ 截图禁止提交到 Git 仓库
127
127
  - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
128
- - ⚠️ 创建 PR 后必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 7）
128
+ - ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 7）
129
129
  - 先开 Draft PR，准备好再标记 Ready for review
130
130
  - 作者不能 Approve 自己的 PR