@routerhub/agent-rules 1.5.192 → 1.5.194

package/AGENTS.base.md

@@ -161,6 +161,15 @@ 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 对踢」机制链，不给「来回踢的窗口里你点的登录被吞了」这版人话——用户每个词都认识，却无法确认「对，就是我遇到的那个」。
+  - 自查：报这类根因前先自问——「把这段文字只发给用户、不附任何口头解释，他能复现并确认『对，就是它』吗？」能 = 合格；不能 = 先补人话版再发。
 
 ## Git 规范
 

package/README.md

@@ -1,49 +1,45 @@
 # @routerhub/agent-rules
 
-帮你自动生成给AI看的提示文件，这样每次AI都会参考你的规则
+给项目生成一套 AI 协作规则文件，让 Claude Code / Cursor / GitHub Copilot 在项目里都按同一套规则干活。
 
-## 安装
+## 它能干什么
 
-在你的项目里安装即可：
+安装后自动生成/同步：
 
-```bash
-pnpm i -D @routerhub/agent-rules
-```
-
-## 使用
-
-安装完成后，只在当前项目的 `AGENTS.private.md` 中编写项目私有规则。
-
-如果需要修改公共规则，请在 `agent-rules` 项目中维护，不要写到业务项目的 `AGENTS.private.md` 里。
+| 层级 | 文件 | 说明 |
+|---|---|---|
+| 个人级 | `CLAUDE.md` / `AGENTS.md` | 本机 AI 自动读取，**默认停用**（见下「按人启停」） |
+| 团队级 | `.github/copilot-instructions.md`、`.github/instructions/*`、`PULL_REQUEST_TEMPLATE.md`、skills | 随仓库入库，始终生成，不受个人启停影响 |
 
-写完 `AGENTS.private.md` 后，工具会自动生成项目可用的 `AGENTS.md` 和 `.github/copilot-instructions.md`。
+## 怎么用
 
-首次执行 `pnpm i -D @routerhub/agent-rules` 时，会自动执行初始化：
-
-- 自动生成 `AGENTS.md`
-- 自动生成 `CLAUDE.md`
-- 自动生成 `.github/copilot-instructions.md`
-- 自动生成 `.github/instructions/*.instructions.md`
-- 如果当前项目还没有 `AGENTS.private.md`，会自动创建模板文件
-
-## 更新
-
-当 `@routerhub/agent-rules` 有新版本时，锁文件不会自动追最新，需要手动更新：
+在项目里安装，装完自动初始化生成规则文件：
 
 ```bash
-pnpm update @routerhub/agent-rules --latest
+pnpm i -D @routerhub/agent-rules
 ```
 
-更新后 `postinstall` 脚本会自动运行，重新同步规则文件。
+常用命令：
 
-> 直接 `pnpm i` 会按 `pnpm-lock.yaml` 中的锁定版本安装，必须加 `--latest` 才能拿到最新版本。
+| 命令 | 作用 |
+|---|---|
+| `pnpm exec agent-rules init` | 初始化 / 生成规则文件 |
+| `pnpm exec agent-rules sync` | 改完规则后手动同步一次 |
+| `pnpm exec agent-rules watch` | 监听，改规则后自动重新生成 |
+| `pnpm update @routerhub/agent-rules --latest` | 升级规则包到最新版 |
 
----
+项目私有规则写在仓库根 `AGENTS.private.md`（没有会自动建模板）；公共规则在 agent-rules 仓库维护，别写进业务项目。
 
-注意：`pnpm i` 只会自动执行一次初始化或同步，不会常驻启动 watch。
+## 按人启停（默认停用）
 
-如果你希望修改 `AGENTS.private.md` 后自动重新生成规则文件，需要手动执行：
+个人级 `CLAUDE.md` / `AGENTS.md` 只给命中白名单的人生成。白名单在包内 `enabled-users.json`，管理员维护；判断用**本机 git 身份**：
 
 ```bash
-pnpm exec agent-rules watch
+git config user.name
+git config user.email
 ```
+
+name 或 email 包含白名单里任一字符串即启用；不在名单的人默认不生成（团队级规则照常生效）。
+
+- 想启用：把上面的身份告诉管理员加白名单发版；想立即试用：`AGENT_RULES_ENABLED=1 pnpm exec agent-rules init`
+- 想停用：`AGENT_RULES_ENABLED=0 pnpm exec agent-rules init`（只删 agent-rules 生成的个人文件，不碰你写的内容）

package/enabled-users.json

@@ -1 +1 @@
-["Keifer"]
+["Keifer","rachelPomex","eason-qing"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.192",
+  "version": "1.5.194",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {
@@ -13,7 +13,6 @@
     "merge.js",
     "AGENTS.private.example.md",
     "PULL_REQUEST_TEMPLATE.md",
-    "README.zh-CN.md",
     "postinstall.js",
     "package.json",
     "CHANGELOG.md",

package/rules/global.md

@@ -14,6 +14,17 @@ name: "通用规则"
     - **Skill**：多步骤操作流程，需按需调用，如部署、发 PR、Figma 还原、TDD 流程。新建 `skills/技能名/SKILL.md`。
     - **判断标准**：「这件事每次写代码都要遵守吗？」→ 是 = 规则，否（只有特定场景才触发）= Skill。
 
+## ⚠️ 规则文件分层与个人级启停（机制说明）
+
+agent-rules 生成的规则文件分两层，行为与归属不同，评审/发版/接入时请勿混淆：
+
+- **个人级：`CLAUDE.md` / `AGENTS.md`（不入库，每机本地生成）**。这两个文件是「本地 AI 自动读取」的规则，agent-rules 只是文件生成器、不是运行时拦截器——文件一旦 git 入库，谁 clone 都带上，无法按人关掉。因此改为不入库（`.gitignore` 忽略），是否生成取决于**本机开发者的 git 身份**（`git config user.name` / `user.email` 任一包含包内 `enabled-users.json` 白名单字符串，忽略大小写）。白名单初始为空数组 = **默认停用**；停用 = 不生成 + 清理本机残留的带签名产物（头部 `# Copilot Agent Rules - Base`）+ 加入 `.gitignore`，只删 agent-rules 生成的、开发者自己的同名文件不动。
+- **团队级：`.github/*`、`.claude/skills/*`、`AGENTS.private.md`（入库，始终生成）**。供 GitHub 云端 PR review、团队共享，不参与个人启停。
+
+成员想启用/停用这套个人规则，只取决于「在不在白名单」，与具体项目无关。想启用的人把 `git config user.name` / `git config user.email` 的输出发给 agent-rules 管理员加入白名单即可。
+
+**发版/评审方注意**：升级 PR 中出现「`git rm --cached` 删除已跟踪的 CLAUDE.md / AGENTS.md + .gitignore 追加忽略」是本机制的存量迁移（个人文件从入库改为本地生成），属正常流程，禁止按「误删文件」报错；个人级文件不再入库，规则评审请以团队级产物 `.github/**` 为准。
+
 ## 语言与内容
 
 - 始终使用中文回答，代码注释使用中文。
@@ -150,6 +161,15 @@ name: "通用规则"
   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 对踢」机制链，不给「来回踢的窗口里你点的登录被吞了」这版人话——用户每个词都认识，却无法确认「对，就是我遇到的那个」。
+  - 自查：报这类根因前先自问——「把这段文字只发给用户、不附任何口头解释，他能复现并确认『对，就是它』吗？」能 = 合格；不能 = 先补人话版再发。
 
 ## Git 规范
 

package/README.zh-CN.md

@@ -1,140 +0,0 @@
-# @routerhub/agent-rules 中文说明
-
-`@routerhub/agent-rules` 用来把通用规则和项目私有规则合并成项目中可直接使用的规则文件。
-
-它提供两类能力：
-
-1. 按「个人级 / 团队级」两层生成项目可用的规则文件（详见下方「规则启停」章节）：`CLAUDE.md` / `AGENTS.md` 按本机 git 身份白名单本地生成、默认停用；`.github/*`、skills 等团队级文件始终生成
-2. 监听 `AGENTS.private.md` 变更并自动同步
-
-## 安装
-
-在目标项目中安装：
-
-```bash
-pnpm add -D concurrently @routerhub/agent-rules
-```
-
-## 初始化
-
-如果项目里还没有 `AGENTS.private.md`，可以执行：
-
-```bash
-pnpm exec agent-rules init
-```
-
-执行后会在项目根目录生成一份可编辑的私有规则模板。
-
-## 同步规则
-
-将基础规则与项目私有规则合并为 `AGENTS.md` 和 `.github/copilot-instructions.md`：
-
-```bash
-pnpm exec agent-rules sync
-```
-
-适合以下场景：
-
-- 首次接入后生成规则文件
-- 修改了 `AGENTS.private.md` 后手动重建
-- CI 或脚本中显式同步规则
-
-## 监听模式
-
-开发时建议通过监听模式自动保持规则文件最新：
-
-```json
-{
-  "scripts": {
-    "dev": "concurrently \"next dev\" \"agent-rules watch\""
-  }
-}
-```
-
-监听模式会：
-
-- 先执行一次同步，生成最新的 `AGENTS.md` 和 `.github/copilot-instructions.md`
-- 持续监听项目根目录下的 `AGENTS.private.md`
-- 在文件变更后自动重新同步
-
-## 规则来源
-
-- `AGENTS.base.md`：规则包内置的通用基础规则
-- `AGENTS.private.md`：项目自己的私有规则
-- `AGENTS.md`：最终合并结果，供项目中的 Agent 使用
-- `.github/copilot-instructions.md`：最终合并结果，供 GitHub Copilot 强制规则使用
-
-## 推荐用法
-
-项目接入时推荐保持以下流程：
-
-1. 安装 `@routerhub/agent-rules`
-2. 执行 `pnpm exec agent-rules init`
-3. 根据项目情况编辑 `AGENTS.private.md`
-4. 使用 `pnpm exec agent-rules sync` 或 `agent-rules watch` 生成最终的 `AGENTS.md`
-
-## 更新
-
-当 `@routerhub/agent-rules` 有新版本时，锁文件不会自动追最新，需要手动更新：
-
-```bash
-pnpm update @routerhub/agent-rules --latest
-```
-
-更新后 `postinstall` 脚本会自动运行，重新同步规则文件。
-
-> 直接 `pnpm i` 会按 `pnpm-lock.yaml` 中的锁定版本安装，必须加 `--latest` 才能拿到最新版本。
-
-## 规则启停（按人白名单）
-
-生成的规则文件分两层：
-
-| 层级 | 文件 | 是否入库 | 何时生成 |
-|---|---|---|---|
-| 个人级 | `CLAUDE.md` / `AGENTS.md`（本地 AI 自动读取） | **不入库**（`.gitignore` 忽略，随安装本地生成） | **仅当本机 git 身份命中白名单** |
-| 团队级 | `.github/copilot-instructions.md`、`.github/instructions/*`、`.github/PULL_REQUEST_TEMPLATE.md`、`.claude/skills/*`、`AGENTS.private.md` | 随仓库入库分发 | 始终生成，不受个人启停影响 |
-
-**为什么个人级文件要「不入库 + 每机生成」**：Claude Code / Cursor / Copilot 是「工作区里有这个文件就读」，agent-rules 只是文件生成器、不是运行时拦截器。若个人级文件写死在 git 仓库里，谁 clone 下来都有这套规则，无法按人关掉。所以 `CLAUDE.md` / `AGENTS.md` 改成由每台机器的安装过程按白名单决定「生成 / 不生成」。
-
-### 白名单判定规则
-
-- 白名单载体：npm 包内 `enabled-users.json`（发布到 `node_modules/@routerhub/agent-rules/enabled-users.json`），由 agent-rules 管理员维护。
-- 判定：**本机 git 身份 `user.name` 或 `user.email` 任一「包含」名单中任一字符串（不区分大小写、包含即命中）→ 启用**；未命中 → 默认停用。
-- 与仓库无关：只判断「这台电脑的开发者是谁」，不按项目 / git remote 判断，仓库分发逻辑不变。
-- **默认停用**：名单初始为空数组（先谁也不放）。不想用这套规则的人什么都不用做——只要不在名单里，个人级规则就不会生成（团队级 `.github` 云上 review 规则仍保留，属团队共享，不由个人启停控制）。
-- 逃生门：`AGENT_RULES_ENABLED=1` 强制启用 / `=0` 强制停用（测试与临时场景，环境变量级别，优先级高于白名单）。
-
-### 停用时的行为
-
-- 不生成 `CLAUDE.md` / `AGENTS.md`；
-- 自动把这两个文件加入项目 `.gitignore`，防止后续误提交入库；
-- 清理本机历史安装残留：只删除「存在 + 未被 git 跟踪 + 文件头为 `# Copilot Agent Rules - Base`」的 agent-rules 产物，**开发者自己的同名文件绝不删除**；仍被 git 跟踪的旧产物会提示等待仓库升级移除（升级时自动完成，见下文）。
-
-### 如何获取本机 git 身份（想启用的人自查用）
-
-在目标项目根目录（或任意能取到本机身份的目录）执行：
-
-```bash
-git config user.name
-git config user.email
-```
-
-- 不带 `--global` 时，显示**当前所在项目生效的值**（项目级 `user.name/email` 优先，项目没配则回退到全局 `~/.gitconfig`）。
-- 想确认自己机器全局配置的，再加 `--global`：
-
-```bash
-git config --global user.name
-git config --global user.email
-```
-
-把上面命令输出的字符串发给 agent-rules 管理员，管理员把其中之一（或其子串）加入 `enabled-users.json` 并发版；对方执行一次 `pnpm update @routerhub/agent-rules --latest`（或重新 `pnpm install`）后，个人级规则即在本机生效。
-
-### 存量仓库升级迁移
-
-此前版本 `CLAUDE.md` / `AGENTS.md` 是随仓库 git 跟踪分发的。升级到本版本后，agent-rules 的自动升级 PR（8 个下游仓库）会**一次完成迁移**：把这两个文件移出 git 跟踪（`git rm --cached`，工作区文件保留），并同步 `.gitignore`。合并升级 PR 后，个人规则即按本机身份启停。
-
-## 注意事项
-
-- 私有规则应只写项目特有的限制、接口地址、组件路径和业务规范
-- 通用规范应维护在规则包的 `AGENTS.base.md` 中
-- 若私有规则与基础规则冲突，以项目私有规则为准