@routerhub/agent-rules 1.5.59 → 1.5.61

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 +10 -7
  2. package/package.json +1 -1
  3. package/rules/global.md +10 -7
package/AGENTS.base.md CHANGED
@@ -25,10 +25,7 @@
25
25
  - ⚠️ **强制要求：所有 PR 的 Title、Description、Test Plan 等全部文字内容必须使用中文编写**，方便团队成员阅读理解，禁止使用英文撰写 PR 内容。
26
26
  - ⚠️ **强制要求：所有 PR 必须附上相关截图作为可视化证据**，无论是否涉及 UI 改动。截图需包含：功能效果截图、测试结果截图、关键代码变更对比截图等，让 reviewer 无需拉取代码即可直观理解改动内容与验证结果。
27
27
  - PR 的目标是让审阅者在不依赖私下沟通的情况下独立理解、验证并放心 Approve；一个好的 PR 必须自解释。
28
- - 一个 PR 只做一件事（One logical change per PR），必须是完整、独立、可审阅的逻辑改动，禁止把重构、修 bug、加功能混在同一个 PR。
29
- - PR 应保持小而聚焦，尽量控制在约 200 行以内，超过 500 行应优先拆分；小 PR 审得快、回滚风险低、`git bisect` 定位更精准。
30
- - 大改动必须拆成 Stacked PRs（例如 PR1 → PR2 → PR3），每个 PR 都要能独立 review、独立合入；底层先合，上层后合。
31
- - 每个 PR 必须能独立通过编译与测试，禁止出现“这个 PR 编译不过，要等下一个 PR 才能跑”的状态；每一层都应是绿色可发布状态。
28
+ - 每个 PR 必须能独立通过编译与测试，禁止出现”这个 PR 编译不过，要等下一个 PR 才能跑”的状态。
32
29
  - PR Title 必须用祈使句、现在时态描述“做了什么”，建议加模块/组件前缀，保持简洁且一行说清。
33
30
  - 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`。
34
31
  - PR Title 禁止使用 `fix bug`、`update code`、`改了一下` 等无法表达实际改动的标题。
@@ -86,8 +83,8 @@ Closes #456
86
83
  - 作者不能 Approve 自己的 PR。
87
84
  - PR 其他元数据必须完整：Assignees 填负责人，Labels 填类型/优先级/模块，Linked Issues/Projects 关联需求来源与项目看板，Milestone 按需关联发布里程碑。
88
85
  - 尚未准备好审阅时必须先开 Draft PR，准备好后再标记 `Ready for review`。
89
- - 作者提交审阅前必须完成自查：PR 只做一件事；没有夹带格式化、顺手改动等无关改动；Title 清晰；Description 写明 What/Why/How；Test Plan 完整且带证据；已自审 `Files changed`；已移除调试代码、注释代码和无效 TODO；没有泄露密钥、token、内部地址、PII 等敏感信息；已指定合适 reviewer；已关联 issue；本地编译、lint、测试通过；CI status checks 全绿。
90
- - 满足以下全部条件才允许 Merge：至少一名 reviewer 已 Approve；`CODEOWNERS` required review（如有）已通过；所有 required status checks（构建、单测、lint、静态分析等）全部绿色；所有 review 评论和 `Request changes` 均已解决并 Resolve conversation；分支与目标分支无冲突且已更新到最新；Stacked PR 的所有底层依赖已先行合入。
86
+ - 作者提交审阅前必须完成自查：没有夹带格式化、顺手改动等无关改动；Title 清晰；Description 写明 What/Why/How；Test Plan 完整且带证据；已自审 `Files changed`；已移除调试代码、注释代码和无效 TODO；没有泄露密钥、token、内部地址、PII 等敏感信息；已指定合适 reviewer；已关联 issue；本地编译、lint、测试通过；CI status checks 全绿。
87
+ - 满足以下全部条件才允许 Merge：至少一名 reviewer 已 Approve；`CODEOWNERS` required review（如有）已通过；所有 required status checks（构建、单测、lint、静态分析等）全部绿色；所有 review 评论和 `Request changes` 均已解决并 Resolve conversation；分支与目标分支无冲突且已更新到最新。
91
88
  - 建议开启 Branch protection 强制合入门禁，并开启 `Require branches to be up to date`。
92
89
  - 团队应统一 Merge 方式，多数情况用 `Squash and merge` 保持主干历史干净；需要保留完整提交历史时再用 merge commit。
93
90
  - Reviewer 收到 review 请求后应尽量在 1 个工作日内给出首次反馈。
@@ -99,7 +96,7 @@ Closes #456
99
96
  - 有分歧时优先在 PR 上公开讨论，结论必须写回 PR，避免私聊后无记录。
100
97
  - 较大方案分歧可以升级为线下或会议讨论，但最终结论必须回写到 PR。
101
98
  - 改动后必须使用 `Re-request review` 重新请求审阅，并在评论里简述本次更新改了什么。
102
- - 必须避免以下反模式：Test Plan 只写“测了没问题”；一个 PR 改 2000 行且跨多个模块；Description 只有“fix bug”；CI 红着或跳过检查直接合；把格式化/重命名和逻辑改动混在一起；评论不回复、不 Resolve 就直接重提 review。
99
+ - 必须避免以下反模式：Test Plan 只写”测了没问题”；Description 只有”fix bug”；CI 红着或跳过检查直接合；把格式化/重命名和逻辑改动混在一起；评论不回复、不 Resolve 就直接重提 review。
103
100
  - PR 规范可按团队约定微调字段，但”充分的 Description + 带证据的 Test Plan + 至少一人 Approve + 状态检查全绿才能 Merge”是不可妥协的核心要求。
104
101
 
105
102
  ## Copilot PR Review 自动循环
@@ -180,6 +177,12 @@ Closes #456
180
177
  - 涉及配置、官网或其他系统联动时，需同时打开所有相关页面，并按实际操作路径展示联动结果，方便直接验证。
181
178
  - 若客观上无法可视化展示，需说明原因，并补充截图、录屏、日志或请求响应作为替代证据。
182
179
 
180
+ ## 外部文档查看（Notion / 需登录页面）
181
+
182
+ - 查看 Notion 文档或其他需要登录态的外部页面时，必须使用 Chrome DevTools MCP（`navigate_page` + `take_snapshot` / `evaluate_script`），禁止使用 WebFetch。WebFetch 无法处理需要登录的页面，会直接报错看不到内容；浏览器 MCP 可复用用户已有的登录态。
183
+ - 页面 snapshot 太大无法直接读取时，用 `evaluate_script` 执行 `document.body.innerText` 或更精准的选择器提取文本内容，再分段读取。
184
+ - 提取到的外部文档内容涉及项目关键规范/数据时，应保存为长期记忆（`memory/` 目录）方便后续引用。
185
+
183
186
  <!-- @domain: frontend -->
184
187
 
185
188
  ## Figma 还原规范
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@routerhub/agent-rules",
3
- "version": "1.5.59",
3
+ "version": "1.5.61",
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
@@ -25,10 +25,7 @@ name: "通用规则"
25
25
  - ⚠️ **强制要求：所有 PR 的 Title、Description、Test Plan 等全部文字内容必须使用中文编写**，方便团队成员阅读理解，禁止使用英文撰写 PR 内容。
26
26
  - ⚠️ **强制要求：所有 PR 必须附上相关截图作为可视化证据**，无论是否涉及 UI 改动。截图需包含：功能效果截图、测试结果截图、关键代码变更对比截图等，让 reviewer 无需拉取代码即可直观理解改动内容与验证结果。
27
27
  - PR 的目标是让审阅者在不依赖私下沟通的情况下独立理解、验证并放心 Approve；一个好的 PR 必须自解释。
28
- - 一个 PR 只做一件事（One logical change per PR），必须是完整、独立、可审阅的逻辑改动，禁止把重构、修 bug、加功能混在同一个 PR。
29
- - PR 应保持小而聚焦，尽量控制在约 200 行以内，超过 500 行应优先拆分；小 PR 审得快、回滚风险低、`git bisect` 定位更精准。
30
- - 大改动必须拆成 Stacked PRs（例如 PR1 → PR2 → PR3），每个 PR 都要能独立 review、独立合入；底层先合，上层后合。
31
- - 每个 PR 必须能独立通过编译与测试，禁止出现“这个 PR 编译不过，要等下一个 PR 才能跑”的状态；每一层都应是绿色可发布状态。
28
+ - 每个 PR 必须能独立通过编译与测试，禁止出现”这个 PR 编译不过，要等下一个 PR 才能跑”的状态。
32
29
  - PR Title 必须用祈使句、现在时态描述“做了什么”，建议加模块/组件前缀，保持简洁且一行说清。
33
30
  - 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`。
34
31
  - PR Title 禁止使用 `fix bug`、`update code`、`改了一下` 等无法表达实际改动的标题。
@@ -86,8 +83,8 @@ Closes #456
86
83
  - 作者不能 Approve 自己的 PR。
87
84
  - PR 其他元数据必须完整：Assignees 填负责人，Labels 填类型/优先级/模块，Linked Issues/Projects 关联需求来源与项目看板，Milestone 按需关联发布里程碑。
88
85
  - 尚未准备好审阅时必须先开 Draft PR，准备好后再标记 `Ready for review`。
89
- - 作者提交审阅前必须完成自查：PR 只做一件事；没有夹带格式化、顺手改动等无关改动；Title 清晰；Description 写明 What/Why/How；Test Plan 完整且带证据；已自审 `Files changed`；已移除调试代码、注释代码和无效 TODO；没有泄露密钥、token、内部地址、PII 等敏感信息；已指定合适 reviewer；已关联 issue；本地编译、lint、测试通过；CI status checks 全绿。
90
- - 满足以下全部条件才允许 Merge：至少一名 reviewer 已 Approve；`CODEOWNERS` required review（如有）已通过；所有 required status checks（构建、单测、lint、静态分析等）全部绿色；所有 review 评论和 `Request changes` 均已解决并 Resolve conversation；分支与目标分支无冲突且已更新到最新；Stacked PR 的所有底层依赖已先行合入。
86
+ - 作者提交审阅前必须完成自查：没有夹带格式化、顺手改动等无关改动；Title 清晰；Description 写明 What/Why/How；Test Plan 完整且带证据；已自审 `Files changed`；已移除调试代码、注释代码和无效 TODO；没有泄露密钥、token、内部地址、PII 等敏感信息；已指定合适 reviewer；已关联 issue；本地编译、lint、测试通过；CI status checks 全绿。
87
+ - 满足以下全部条件才允许 Merge：至少一名 reviewer 已 Approve；`CODEOWNERS` required review（如有）已通过；所有 required status checks（构建、单测、lint、静态分析等）全部绿色；所有 review 评论和 `Request changes` 均已解决并 Resolve conversation；分支与目标分支无冲突且已更新到最新。
91
88
  - 建议开启 Branch protection 强制合入门禁，并开启 `Require branches to be up to date`。
92
89
  - 团队应统一 Merge 方式，多数情况用 `Squash and merge` 保持主干历史干净；需要保留完整提交历史时再用 merge commit。
93
90
  - Reviewer 收到 review 请求后应尽量在 1 个工作日内给出首次反馈。
@@ -99,7 +96,7 @@ Closes #456
99
96
  - 有分歧时优先在 PR 上公开讨论，结论必须写回 PR，避免私聊后无记录。
100
97
  - 较大方案分歧可以升级为线下或会议讨论，但最终结论必须回写到 PR。
101
98
  - 改动后必须使用 `Re-request review` 重新请求审阅，并在评论里简述本次更新改了什么。
102
- - 必须避免以下反模式：Test Plan 只写“测了没问题”；一个 PR 改 2000 行且跨多个模块；Description 只有“fix bug”；CI 红着或跳过检查直接合；把格式化/重命名和逻辑改动混在一起；评论不回复、不 Resolve 就直接重提 review。
99
+ - 必须避免以下反模式：Test Plan 只写”测了没问题”；Description 只有”fix bug”；CI 红着或跳过检查直接合；把格式化/重命名和逻辑改动混在一起；评论不回复、不 Resolve 就直接重提 review。
103
100
  - PR 规范可按团队约定微调字段，但”充分的 Description + 带证据的 Test Plan + 至少一人 Approve + 状态检查全绿才能 Merge”是不可妥协的核心要求。
104
101
 
105
102
  ## Copilot PR Review 自动循环
@@ -179,3 +176,9 @@ Closes #456
179
176
  - 完成任务后的汇报优先提供可视化结果，能打开页面时就直接在集成浏览器中打开，并定位到相关区域后再汇报。
180
177
  - 涉及配置、官网或其他系统联动时，需同时打开所有相关页面，并按实际操作路径展示联动结果，方便直接验证。
181
178
  - 若客观上无法可视化展示，需说明原因，并补充截图、录屏、日志或请求响应作为替代证据。
179
+
180
+ ## 外部文档查看（Notion / 需登录页面）
181
+
182
+ - 查看 Notion 文档或其他需要登录态的外部页面时，必须使用 Chrome DevTools MCP（`navigate_page` + `take_snapshot` / `evaluate_script`），禁止使用 WebFetch。WebFetch 无法处理需要登录的页面，会直接报错看不到内容；浏览器 MCP 可复用用户已有的登录态。
183
+ - 页面 snapshot 太大无法直接读取时，用 `evaluate_script` 执行 `document.body.innerText` 或更精准的选择器提取文本内容，再分段读取。
184
+ - 提取到的外部文档内容涉及项目关键规范/数据时，应保存为长期记忆（`memory/` 目录）方便后续引用。