@routerhub/agent-rules 1.5.193 → 1.5.195

package/AGENTS.base.md

@@ -161,6 +161,22 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   5. **就近嵌入（位置铁律）**：分步演示必须紧跟在「该操作对应概念/证据在报告中第一次出现、读者正要问『那到底怎么操作』」的地方之后（如展示「账户挂映射删除被 400 拒绝」的证据图 → 该图下方紧跟「先解绑再删除」的完整演示），禁止把演示单独堆到报告末尾或附录里——读者在定义处看不到演示、不知道下文还有、得自己翻到最后去找，等于没配演示。
   - **类比**：交付报告像给菜谱——一道菜（一个功能）从备料到出锅（完整操作流程）必须给出「第 1 步切什么、第 2 步放多少油」的步骤图，读者照做能做出同一道菜；只贴一张成品照让读者猜过程，等于没教。
   - 反面示例：演示「删不掉挂着映射的账户」，只贴「删除被拒」和「最终删除成功」两张图、不展示中间「打开 Models → Remove(Unbind) → 确认」的顺序，读者仍不知道卡住时该点哪里。
+- ⚠️ **时序抢跑类 bug（表象像「坏了」、根因是「两个动作抢同一个瞬间被吞」）：测试中要能嗅出来，解释要先翻成人话。** 这类 bug 的表象（如「登录转圈 / 点按钮没反应 / 偶发失败」）离根因隔着好几层抽象——AI 测试功能过程中碰到此类现象，必须按时序根因去查，禁止当「偶发 / 环境问题」放掉；定位到根因后向用户解释时，必须先给一版「人话」（读者能顺着走一遍、能当场确认「对，就是它」），再附机制细节（路由守卫 / persist / token 生命周期……），禁止只甩机制清单、让用户自己翻译根因。识别指纹（命中越多越是这类）：
+  1. **现象离根因好几层**——「登录转圈」与「persist 残留」之间隔着路由守卫、状态管理、token 生命周期，不翻到底层根本对不上号；
+  2. **复现依赖时序**——不是每次都发生，要「恰好在这个窗口里操作」才触发，单靠截图永远复现不了，得拉浏览器时间线（store/URL 状态）钉出「哪一瞬发生了什么」；
+  3. **双方各说各话**——后端日志一切正常（200、token 也清了）、前端也「以为在正常跳转」，谁都没报错，错在两者之间没人认领的窗口；
+  4. **观感反直觉**——越「谁都没错」的 bug，越容易被误判成偶发/环境问题放掉。
+  - **翻译模板**：解释一律以「不是 X 坏了，是两个动作在抢同一个瞬间，抢输的那次被吞了/被推后了」打底，讲成用户能顺着走一遍的故事（「你改完密码被踢回登录页，但页面还当你登录着、又把你弹回主页，主页发现你登录已失效、再把你踢回登录页——就在这一来一回的当口你点了登录，点击被打断、请求根本没发出去，所以按钮永远转圈」），再附机制细节。禁止先给机制清单、让人自己在脑子里翻译。
+  - **类比：一扇推拉门，两个人同时从两边推——门没坏、两个人也都没错，可在同一个瞬间两边同时用力，谁也推不开。表面像「门卡住了」，其实是时序撞上了；解决办法不是修门，是让两边错开时间。**
+  - 反面示例：解释「强制改密后登录卡死」只报「PublicRoute 弹回 + persist 残留 + handle401 对踢」机制链，不给「来回踢的窗口里你点的登录被吞了」这版人话——用户每个词都认识，却无法确认「对，就是我遇到的那个」。
+  - 自查：报这类根因前先自问——「把这段文字只发给用户、不附任何口头解释，他能复现并确认『对，就是它』吗？」能 = 合格；不能 = 先补人话版再发。
+- ⚠️ **带「状态切换 + 跳转」的流程，验证必须主动演练「前置强制状态」与「切换后不等落定立即抢操作」两条时序路径，禁止只走正常路径就算验证完成。** 上一条（时序抢跑识别）解决「撞上了要认出」，本条解决「根本没机会撞上」——凡流程含改密 / 强制改密 / 强制下线 / 登出 / 会话过期自动重登 / 被踢等「状态一变、页面就跳走」的环节，功能验证清单不能只测 happy path，必须额外覆盖两条时序路径，缺一不算验证完成：
+  1. **前置强制状态**：先造出「运营强制置出来的状态」（如 `must_change_password=1` 的账号）再走完整流程——happy path 测不到的，恰恰是这些被置出的状态触发的分支；
+  2. **切换后立即抢操作**：状态切换（改密成功 / 登出 / 被踢 / token 失效）后**不等页面与请求落定，马上点下一步**（立即点登录 / 快速连点 / 立刻刷新）——时序类 bug 就藏在「过渡没完成就抢」的那一下，等页面稳定再点永远踩不中。
+  - **验证顺序**：先正常路径（证明功能能用）→ 再两条时序路径（证明过渡态不卡、不残留、不被吞）；时序路径复现不出问题时，才可判定验证通过。
+  - **类比：验证「两个人同时过一扇门会不会撞上」，不能让测试每次都只让一个人过门——必须专门安排「两个人同时过」这一下，才可能撞出问题；只验单人次 = 门永远不撞 = 问题测不出来。**
+  - 反面示例：验证「强制改密后重新登录」，只测「改密成功 → 页面稳定 → 输入新密码登录」正常路径，不造 `must_change_password=1` 账号、不在改密成功被弹回的 1.5s 窗口里抢点登录——bug 永远复现不了，上线后用户一操作就卡在 Signing in…。
+  - 自查：验证这类流程前先自问——「前置的『被强制状态』我造了吗？切换后的『不等落定立即抢』我试了吗？」任一为否 = 时序路径没测全，先补再交付。
 
 ## Git 规范
 

package/package.json

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

package/rules/global.md

@@ -161,6 +161,22 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   5. **就近嵌入（位置铁律）**：分步演示必须紧跟在「该操作对应概念/证据在报告中第一次出现、读者正要问『那到底怎么操作』」的地方之后（如展示「账户挂映射删除被 400 拒绝」的证据图 → 该图下方紧跟「先解绑再删除」的完整演示），禁止把演示单独堆到报告末尾或附录里——读者在定义处看不到演示、不知道下文还有、得自己翻到最后去找，等于没配演示。
   - **类比**：交付报告像给菜谱——一道菜（一个功能）从备料到出锅（完整操作流程）必须给出「第 1 步切什么、第 2 步放多少油」的步骤图，读者照做能做出同一道菜；只贴一张成品照让读者猜过程，等于没教。
   - 反面示例：演示「删不掉挂着映射的账户」，只贴「删除被拒」和「最终删除成功」两张图、不展示中间「打开 Models → Remove(Unbind) → 确认」的顺序，读者仍不知道卡住时该点哪里。
+- ⚠️ **时序抢跑类 bug（表象像「坏了」、根因是「两个动作抢同一个瞬间被吞」）：测试中要能嗅出来，解释要先翻成人话。** 这类 bug 的表象（如「登录转圈 / 点按钮没反应 / 偶发失败」）离根因隔着好几层抽象——AI 测试功能过程中碰到此类现象，必须按时序根因去查，禁止当「偶发 / 环境问题」放掉；定位到根因后向用户解释时，必须先给一版「人话」（读者能顺着走一遍、能当场确认「对，就是它」），再附机制细节（路由守卫 / persist / token 生命周期……），禁止只甩机制清单、让用户自己翻译根因。识别指纹（命中越多越是这类）：
+  1. **现象离根因好几层**——「登录转圈」与「persist 残留」之间隔着路由守卫、状态管理、token 生命周期，不翻到底层根本对不上号；
+  2. **复现依赖时序**——不是每次都发生，要「恰好在这个窗口里操作」才触发，单靠截图永远复现不了，得拉浏览器时间线（store/URL 状态）钉出「哪一瞬发生了什么」；
+  3. **双方各说各话**——后端日志一切正常（200、token 也清了）、前端也「以为在正常跳转」，谁都没报错，错在两者之间没人认领的窗口；
+  4. **观感反直觉**——越「谁都没错」的 bug，越容易被误判成偶发/环境问题放掉。
+  - **翻译模板**：解释一律以「不是 X 坏了，是两个动作在抢同一个瞬间，抢输的那次被吞了/被推后了」打底，讲成用户能顺着走一遍的故事（「你改完密码被踢回登录页，但页面还当你登录着、又把你弹回主页，主页发现你登录已失效、再把你踢回登录页——就在这一来一回的当口你点了登录，点击被打断、请求根本没发出去，所以按钮永远转圈」），再附机制细节。禁止先给机制清单、让人自己在脑子里翻译。
+  - **类比：一扇推拉门，两个人同时从两边推——门没坏、两个人也都没错，可在同一个瞬间两边同时用力，谁也推不开。表面像「门卡住了」，其实是时序撞上了；解决办法不是修门，是让两边错开时间。**
+  - 反面示例：解释「强制改密后登录卡死」只报「PublicRoute 弹回 + persist 残留 + handle401 对踢」机制链，不给「来回踢的窗口里你点的登录被吞了」这版人话——用户每个词都认识，却无法确认「对，就是我遇到的那个」。
+  - 自查：报这类根因前先自问——「把这段文字只发给用户、不附任何口头解释，他能复现并确认『对，就是它』吗？」能 = 合格；不能 = 先补人话版再发。
+- ⚠️ **带「状态切换 + 跳转」的流程，验证必须主动演练「前置强制状态」与「切换后不等落定立即抢操作」两条时序路径，禁止只走正常路径就算验证完成。** 上一条（时序抢跑识别）解决「撞上了要认出」，本条解决「根本没机会撞上」——凡流程含改密 / 强制改密 / 强制下线 / 登出 / 会话过期自动重登 / 被踢等「状态一变、页面就跳走」的环节，功能验证清单不能只测 happy path，必须额外覆盖两条时序路径，缺一不算验证完成：
+  1. **前置强制状态**：先造出「运营强制置出来的状态」（如 `must_change_password=1` 的账号）再走完整流程——happy path 测不到的，恰恰是这些被置出的状态触发的分支；
+  2. **切换后立即抢操作**：状态切换（改密成功 / 登出 / 被踢 / token 失效）后**不等页面与请求落定，马上点下一步**（立即点登录 / 快速连点 / 立刻刷新）——时序类 bug 就藏在「过渡没完成就抢」的那一下，等页面稳定再点永远踩不中。
+  - **验证顺序**：先正常路径（证明功能能用）→ 再两条时序路径（证明过渡态不卡、不残留、不被吞）；时序路径复现不出问题时，才可判定验证通过。
+  - **类比：验证「两个人同时过一扇门会不会撞上」，不能让测试每次都只让一个人过门——必须专门安排「两个人同时过」这一下，才可能撞出问题；只验单人次 = 门永远不撞 = 问题测不出来。**
+  - 反面示例：验证「强制改密后重新登录」，只测「改密成功 → 页面稳定 → 输入新密码登录」正常路径，不造 `must_change_password=1` 账号、不在改密成功被弹回的 1.5s 窗口里抢点登录——bug 永远复现不了，上线后用户一操作就卡在 Signing in…。
+  - 自查：验证这类流程前先自问——「前置的『被强制状态』我造了吗？切换后的『不等落定立即抢』我试了吗？」任一为否 = 时序路径没测全，先补再交付。
 
 ## Git 规范