@routerhub/agent-rules 1.5.51 → 1.5.53

package/AGENTS.base.md

@@ -108,7 +108,7 @@ Closes #456
   1. 打开 PR 页面，逐一查看 Copilot review 提出的每一条问题。
   2. 逐条判断问题是否有道理：确实存在的代码缺陷、逻辑错误、安全风险、性能问题等 → 必须修复；误报、与需求不符、风格偏好无实质影响等 → 在评论中回复解释为何不改，然后 Resolve。
   3. 对于有道理的问题，直接修改代码、提交并推送到该 PR 分支。
-  4. 在 PR 评论中回复该问题（如”已修复”或简要说明修改内容），然后点击 Resolve conversation。
+  4. ⚠️ **强制步骤：修改代码并推送后，必须在 GitHub PR 页面上逐条点击 Resolve conversation。** 此步骤不可跳过——即使已回复评论、已推送修复代码，只要未点 Resolve，该条评论仍处于”未解决”状态，reviewer 无法判断是否已处理完毕。每修复一条，立即 Resolve 一条，不要等所有问题修完再批量操作。
   5. 所有问题处理完毕后，重新请求 Copilot review。
   6. 重复以上步骤，直到 Copilot review 不再提出新问题为止。
 - 每一条 Copilot review 评论处理完毕后，必须点击 **Resolve conversation**，不能只回复不 Resolve。不点 Resolve 会导致该评论一直处于未解决状态，无法判断是否已完成处理。
@@ -240,6 +240,55 @@ Closes #456
 - 用 `console.error` 记录错误（含函数名/模块名上下文），禁止 `console.log` 输出错误。
 - 提交前移除调试日志和临时代码。
 
+## Modal 内 Tooltip 规范
+
+在 Modal/弹窗内实现 tooltip 时，必须遵守以下规则，避免被 Modal 容器裁剪和消失太快两个问题。
+
+### 1. Tooltip 必须用 Portal 渲染到 document.body
+
+**问题**：Modal 容器通常有 `overflow: hidden` 或 `overflow-y: auto`，用 CSS `position: absolute/fixed` 的 tooltip 会被裁掉。
+
+**解决**：用 React Portal（`createPortal`）把 tooltip 气泡渲染到 `document.body`，完全绕开 Modal 的 overflow 裁剪。
+
+- 用 `getBoundingClientRect()` 获取触发元素（`?` 图标）的屏幕坐标
+- 气泡用 `position: fixed` + `transform: translate(...)` 精确定位在触发元素上方
+- `z-index` 至少 10000，确保在所有弹窗层之上
+
+### 2. 延迟隐藏 + 气泡可 hover
+
+**问题**：鼠标离开触发元素时 tooltip 立即消失，用户来不及把鼠标移到气泡上阅读内容。
+
+**解决**：
+- 隐藏加 200ms 延迟（`setTimeout`），给用户反应时间
+- 气泡本身绑定 `onMouseEnter`（取消隐藏定时器）和 `onMouseLeave`（触发同样的延迟隐藏）
+- CSS 上气泡容器必须 `pointer-events: auto`（不能是 `none`），否则鼠标事件不触发
+
+### 3. 参考实现
+
+实现一个可复用的 `FieldTooltip` 组件，核心结构：
+
+```tsx
+import { createPortal } from 'react-dom';
+
+function FieldTooltip({ text }: { text: string }) {
+  const iconRef = useRef<HTMLSpanElement>(null);
+  const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [visible, setVisible] = useState(false);
+  const [pos, setPos] = useState({ top: 0, left: 0 });
+
+  // show() → 取消定时器 → getBoundingClientRect 更新坐标 → setVisible(true)
+  // hide() → 200ms setTimeout → setVisible(false)
+  // clearHideTimer() → clearTimeout
+
+  // ? 图标: onMouseEnter={show}  onMouseLeave={hide}
+  // Portal 气泡: onMouseEnter={clearHideTimer}  onMouseLeave={hide}
+  //              position: fixed, z-index: 10000, pointer-events: auto
+}
+```
+
+- 禁止在 Modal 内用纯 CSS `position: absolute` 的 hover tooltip
+- 写完 tooltip 后必须实际验证：弹窗内滚动时气泡不被裁剪，鼠标能从图标移到气泡上阅读
+
 <!-- @domain: go-backend -->
 
 ## Go 语言规则

package/merge.js

@@ -48,6 +48,26 @@ function ensureParentDir(filePath) {
   fs.mkdirSync(parentDir, { recursive: true });
 }
 
+/**
+ * 更新 .agent-rules-version 版本标记文件
+ * 供 postinstall 判断已安装版本是否与上次同步版本一致，避免重复同步
+ */
+function updateVersionMarker() {
+  try {
+    const currentVersion = JSON.parse(
+      fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8")
+    ).version;
+    fs.writeFileSync(
+      path.join(currentRoot, ".agent-rules-version"),
+      currentVersion,
+      "utf-8"
+    );
+  } catch (e) {
+    // 非关键操作，写入失败不阻塞主流程
+    console.warn("[agent-rules] 版本标记写入失败:", e.message);
+  }
+}
+
 function resolveOutputPaths(config) {
   if (Array.isArray(config.outputs) && config.outputs.length > 0) {
     return config.outputs;
@@ -517,6 +537,7 @@ function initAgents() {
   const privateOutputPath = path.join(currentRoot, "AGENTS.private.md");
 
   mergeAgents(getDefaultConfig());
+  updateVersionMarker();
 
   if (!fs.existsSync(privateOutputPath) && fs.existsSync(privateTemplatePath)) {
     fs.copyFileSync(privateTemplatePath, privateOutputPath);
@@ -656,6 +677,7 @@ function main() {
 
   if (command === "sync") {
     mergeAgents(getDefaultConfig());
+    updateVersionMarker();
     return;
   }
 

package/package.json

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

package/postinstall.js

@@ -59,17 +59,54 @@ if (projectRoot.includes("node_modules")) {
   process.exit(0);
 }
 
-// 确保下游项目 .npmrc 中关闭 frozen-lockfile，让 pnpm install 能直接在版本更新后执行
+// 确保下游项目 .npmrc 中关闭 frozen-lockfile + 启用依赖 pre/post 脚本
+// frozen-lockfile=false：让 pnpm install 能在版本更新后直接执行
+// enable-pre-post-scripts=true：让 pnpm 始终执行依赖包的 postinstall 生命周期脚本，
+//   否则 pnpm 默认不会运行依赖的 postinstall，导致 agent-rules 更新后规则文件不刷新
 const npmrcPath = path.join(projectRoot, ".npmrc");
 let npmrcContent = "";
 if (fs.existsSync(npmrcPath)) {
   npmrcContent = fs.readFileSync(npmrcPath, "utf-8");
 }
+const npmrcEntries = [];
 if (!npmrcContent.includes("frozen-lockfile")) {
-  const newEntry =
-    "\n# 允许 pnpm install 在依赖版本更新后直接执行（由 agent-rules 自动添加）\nfrozen-lockfile=false\n";
+  npmrcEntries.push("# 允许 pnpm install 在依赖版本更新后直接执行（由 agent-rules 自动添加）");
+  npmrcEntries.push("frozen-lockfile=false");
+}
+if (!npmrcContent.includes("enable-pre-post-scripts")) {
+  npmrcEntries.push("# 确保依赖包的 postinstall 生命周期脚本始终执行（由 agent-rules 自动添加）");
+  npmrcEntries.push("enable-pre-post-scripts=true");
+}
+if (npmrcEntries.length > 0) {
+  const newEntry = "\n" + npmrcEntries.join("\n") + "\n";
   fs.appendFileSync(npmrcPath, newEntry);
-  console.log("[agent-rules] 已配置 .npmrc: frozen-lockfile=false");
+  console.log("[agent-rules] 已配置 .npmrc: " + npmrcEntries.filter((e) => !e.startsWith("#")).join(", "));
+}
+
+// 版本标记机制：比较已安装版本与上次同步的版本
+//   相同 → 跳过同步（避免每次 pnpm install 都重复生成）
+//   不同/不存在 → 执行同步并更新版本标记
+const versionMarkerPath = path.join(projectRoot, ".agent-rules-version");
+const currentVersion = JSON.parse(
+  fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8")
+).version;
+let needsSync = true;
+
+if (fs.existsSync(versionMarkerPath)) {
+  const lastVersion = fs.readFileSync(versionMarkerPath, "utf-8").trim();
+  if (lastVersion === currentVersion) {
+    needsSync = false;
+    console.log("[agent-rules] 版本未变更 (" + currentVersion + ")，跳过同步");
+  } else {
+    console.log("[agent-rules] 版本变更: " + lastVersion + " → " + currentVersion + "，执行同步...");
+  }
+} else {
+  console.log("[agent-rules] 首次安装 (v" + currentVersion + ")，执行同步...");
+}
+
+if (!needsSync) {
+  console.log("");
+  process.exit(0);
 }
 
 console.log("");
@@ -83,7 +120,9 @@ const syncProcess = spawn("node", [mergeScriptPath, "init"], {
 
 syncProcess.on("close", (code) => {
   if (code === 0) {
-    console.log("[agent-rules] 规则文件初始化完成");
+    // 同步成功后写入版本标记，下次 postinstall 时比较版本号避免重复同步
+    fs.writeFileSync(versionMarkerPath, currentVersion, "utf-8");
+    console.log("[agent-rules] 规则文件初始化完成 (v" + currentVersion + ")");
     console.log("");
   } else {
     console.error("[agent-rules] 初始化失败，退出码:", code);

package/rules/frontend.md

@@ -64,3 +64,52 @@ outputName: "frontend"
 
 - 用 `console.error` 记录错误（含函数名/模块名上下文），禁止 `console.log` 输出错误。
 - 提交前移除调试日志和临时代码。
+
+## Modal 内 Tooltip 规范
+
+在 Modal/弹窗内实现 tooltip 时，必须遵守以下规则，避免被 Modal 容器裁剪和消失太快两个问题。
+
+### 1. Tooltip 必须用 Portal 渲染到 document.body
+
+**问题**：Modal 容器通常有 `overflow: hidden` 或 `overflow-y: auto`，用 CSS `position: absolute/fixed` 的 tooltip 会被裁掉。
+
+**解决**：用 React Portal（`createPortal`）把 tooltip 气泡渲染到 `document.body`，完全绕开 Modal 的 overflow 裁剪。
+
+- 用 `getBoundingClientRect()` 获取触发元素（`?` 图标）的屏幕坐标
+- 气泡用 `position: fixed` + `transform: translate(...)` 精确定位在触发元素上方
+- `z-index` 至少 10000，确保在所有弹窗层之上
+
+### 2. 延迟隐藏 + 气泡可 hover
+
+**问题**：鼠标离开触发元素时 tooltip 立即消失，用户来不及把鼠标移到气泡上阅读内容。
+
+**解决**：
+- 隐藏加 200ms 延迟（`setTimeout`），给用户反应时间
+- 气泡本身绑定 `onMouseEnter`（取消隐藏定时器）和 `onMouseLeave`（触发同样的延迟隐藏）
+- CSS 上气泡容器必须 `pointer-events: auto`（不能是 `none`），否则鼠标事件不触发
+
+### 3. 参考实现
+
+实现一个可复用的 `FieldTooltip` 组件，核心结构：
+
+```tsx
+import { createPortal } from 'react-dom';
+
+function FieldTooltip({ text }: { text: string }) {
+  const iconRef = useRef<HTMLSpanElement>(null);
+  const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [visible, setVisible] = useState(false);
+  const [pos, setPos] = useState({ top: 0, left: 0 });
+
+  // show() → 取消定时器 → getBoundingClientRect 更新坐标 → setVisible(true)
+  // hide() → 200ms setTimeout → setVisible(false)
+  // clearHideTimer() → clearTimeout
+
+  // ? 图标: onMouseEnter={show}  onMouseLeave={hide}
+  // Portal 气泡: onMouseEnter={clearHideTimer}  onMouseLeave={hide}
+  //              position: fixed, z-index: 10000, pointer-events: auto
+}
+```
+
+- 禁止在 Modal 内用纯 CSS `position: absolute` 的 hover tooltip
+- 写完 tooltip 后必须实际验证：弹窗内滚动时气泡不被裁剪，鼠标能从图标移到气泡上阅读

package/rules/global.md

@@ -108,7 +108,7 @@ Closes #456
   1. 打开 PR 页面，逐一查看 Copilot review 提出的每一条问题。
   2. 逐条判断问题是否有道理：确实存在的代码缺陷、逻辑错误、安全风险、性能问题等 → 必须修复；误报、与需求不符、风格偏好无实质影响等 → 在评论中回复解释为何不改，然后 Resolve。
   3. 对于有道理的问题，直接修改代码、提交并推送到该 PR 分支。
-  4. 在 PR 评论中回复该问题（如”已修复”或简要说明修改内容），然后点击 Resolve conversation。
+  4. ⚠️ **强制步骤：修改代码并推送后，必须在 GitHub PR 页面上逐条点击 Resolve conversation。** 此步骤不可跳过——即使已回复评论、已推送修复代码，只要未点 Resolve，该条评论仍处于”未解决”状态，reviewer 无法判断是否已处理完毕。每修复一条，立即 Resolve 一条，不要等所有问题修完再批量操作。
   5. 所有问题处理完毕后，重新请求 Copilot review。
   6. 重复以上步骤，直到 Copilot review 不再提出新问题为止。
 - 每一条 Copilot review 评论处理完毕后，必须点击 **Resolve conversation**，不能只回复不 Resolve。不点 Resolve 会导致该评论一直处于未解决状态，无法判断是否已完成处理。