@routerhub/agent-rules 1.5.196 → 1.5.198

package/AGENTS.base.md

@@ -695,6 +695,30 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 4. 一旦 `eval` / `snapshot` 返回的内容不是自己操作的页面（URL/内容不符），
    **第一反应是标签页被抢占**：切回自己的 tab id 后重试，禁止盲目重试同一条命令。
 
+## 🚨 agent-browser 内存收尾铁律（用完必须收摊）
+
+**根因**：agent-browser CLI 本体很轻，但它背后复用的 Chrome Profile 会保留标签页、
+Service Worker、登录态缓存和页面运行时。每次任务只打开不关闭，`9223` / `9226` 的
+Chrome Helper 会越积越多，表现为“agent-browser 用着用着越来越卡”。
+
+**必须遵守**：
+
+1. 每次 `agent-browser tab new` 后必须记录本次任务创建的 tab id；任务结束前，必须关闭
+    本任务打开的所有 tab，禁止把 Cloud Console、GitHub、Slack、Google 登录页等任务页面
+    长期留在 agent-browser Chrome 里。
+2. 每次浏览器自动化任务结束前，必须执行一次内存收尾检查：
+    `agent-browser-cleanup status`（或仓库源码内 `bash scripts/agent-browser-cleanup.sh status`）。
+3. `9226` 无头 Chrome 优先用于 agent 自动化；若 `9226` 的 tab 数 > 10，或 RSS > 1500MB，
+    必须执行 `agent-browser-cleanup auto` 或 `agent-browser-cleanup hard` 释放内存。释放后下次
+    需要浏览器时再重新启动，不要为了“可能等会用”长期占着内存。
+4. `9223` 有头 Chrome 只在需要用户手动登录、手动查看动态效果、或必须共享可见页面时启动；
+    任务结束且用户不再需要查看时，必须关闭本任务 tab，并在确认没有人工操作中的页面后再
+    `agent-browser-cleanup hard`。
+5. 禁止长期同时保留 `9223` + `9226` 两套 agent-browser Chrome 实例，除非当前任务明确需要。
+    多会话并行时也必须各自用 namespace 隔离，任务完成各自清理自己创建的 tab。
+6. 禁止用 `kill -9` / `pkill -9` 强杀 Chrome；清理只能使用 `agent-browser-cleanup`、
+    `chrome-bridge headless-stop`，或 `/bin/kill -TERM` 这类可让 Chrome 正常退出的方式。
+
 ## 优先级
 
 1. 项目私有规则（AGENTS.private.md）

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.198] - 2026-09-08
+
+### Added
+
+- **新增「agent-browser 内存收尾铁律」与 `agent-browser-cleanup` 命令**：要求每次 browser 自动化任务结束关闭本任务 tab，并检查 `9223` / `9226` 的 tab 数与 RSS；`9226` 超过 10 个 tab 或 1500MB 时必须释放，避免 Chrome Profile 长期堆积导致 agent-browser 越用越卡。新增 `scripts/agent-browser-cleanup.sh`，支持 `status` / `soft` / `auto` / `hard` 四种模式，默认只读状态，释放时使用正常退出方式，禁止 `kill -9` 强杀 Chrome。
+
 ## [1.5.164] - 2026-08-31
 
 ### Changed

package/merge.js

@@ -17,7 +17,7 @@
  *     AGENTS.md                                    全量合并（兼容 Cursor/Claude Code）
  *     CLAUDE.md                                    全量合并（Claude Code 自动加载）
  *   团队级（始终生成、随仓库分发共享）：
- *     .github/copilot-instructions.md              全局规则（VS Code Copilot）
+ *     .github/copilot-instructions.md              全局+完整私有规则（VS Code Copilot）
  *     .github/instructions/*.instructions.md       按域条件加载（VS Code Copilot applyTo）
  *     .github/PULL_REQUEST_TEMPLATE.md             统一 PR 模板（GitHub 新建 PR 时预填）
  *     .claude/skills/*                             同步 Skills 到项目本地
@@ -715,13 +715,20 @@ function mergeAgents(config) {
     .map((rule) => rule.content.trim())
     .join("\n\n");
 
-  // 4. 生成 .github/copilot-instructions.md（全局规则 + 私有全局部分）
+  // 4. 生成 .github/copilot-instructions.md
+  //    全局基础规则 + 完整私有规则（含各 @domain 段）。让任意 Agent（Claude Code /
+  //    VS Code Copilot / Cursor 等）读到同一份完整私有规则：只要 AGENTS.private.md 有
+  //    内容就整份追加，不再只取「私有全局段」——否则写在某个 @domain 段、或段落末尾
+  //    的私有规则会从 copilot-instructions.md 里静默缺失，造成「我加了规则但 Copilot
+  //    那边没同步到」的误解（与 AGENTS.md / CLAUDE.md 的全量注入保持一致）。
   let copilotContent = "# Copilot Agent Rules\n\n" + globalContent;
-  if (privateDomains.global) {
-    copilotContent += "\n\n---\n\n# 项目私有规则\n\n" + privateDomains.global;
+  if (privateContent) {
+    copilotContent +=
+      "\n\n---\n\n# 项目私有规则\n\n以下规则仅适用于本项目，会覆盖基础规则中的相同部分。\n\n" +
+      privateContent.trim();
   }
   writeFileIfChanged(copilotOutput, copilotContent);
-  console.log(`✅ 全局规则已生成: ${copilotOutput}`);
+  console.log(`✅ 全局规则已生成(含完整私有规则): ${copilotOutput}`);
 
   // 5. 生成 .github/instructions/*.instructions.md（各域规则）
   ensureParentDir(path.join(instructionsDir, "_placeholder"));
@@ -797,7 +804,7 @@ function initAgents() {
   console.log("   - CLAUDE.md / AGENTS.md（停用时不会生成，并清理本机残留）");
   console.log("     查看当前 git 身份：git config user.name  /  git config user.email");
   console.log("   团队级文件（始终生成、随仓库分发）:");
-  console.log("   - .github/copilot-instructions.md（全局规则）");
+  console.log("   - .github/copilot-instructions.md（全局规则 + 完整私有规则）");
   console.log("   - .github/instructions/*.instructions.md（按域条件加载）");
   console.log("   - .claude/skills/*（Claude Code Skills 技能文件）");
 }
@@ -954,7 +961,7 @@ function main() {
     );
     console.log("输出文件（团队级，始终生成）:");
     console.log(
-      "  .github/copilot-instructions.md              全局规则（VS Code Copilot）",
+      "  .github/copilot-instructions.md              全局+完整私有规则（VS Code Copilot）",
     );
     console.log(
       "  .github/instructions/*.instructions.md       按域条件加载（VS Code Copilot applyTo）",

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.196",
+  "version": "1.5.198",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {
-    "agent-rules": "merge.js"
+    "agent-rules": "merge.js",
+    "agent-browser-cleanup": "scripts/agent-browser-cleanup.sh"
   },
   "files": [
     "AGENTS.base.md",
     "rules/",
     "skills/",
+    "scripts/agent-browser-cleanup.sh",
     "merge.js",
     "AGENTS.private.example.md",
     "PULL_REQUEST_TEMPLATE.md",

package/scripts/agent-browser-cleanup.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+MODE="${1:-status}"
+TAB_LIMIT="${AGENT_BROWSER_TAB_LIMIT:-10}"
+RSS_LIMIT_MB="${AGENT_BROWSER_RSS_LIMIT_MB:-1500}"
+
+profileForPort() {
+  case "$1" in
+    9223) printf '%s\n' "$HOME/.agent-browser-profile" ;;
+    9226) printf '%s\n' "$HOME/.agent-browser-profile-headless" ;;
+    *) printf '' ;;
+  esac
+}
+
+usage() {
+  cat <<'USAGE'
+Usage: scripts/agent-browser-cleanup.sh [status|soft|hard|auto]
+
+Modes:
+  status  只查看 9223/9226 的标签页数量与内存占用
+  soft    关闭 about:blank、newtab、devtools 等无业务标签页
+  hard    优雅退出 agent-browser 专用 Chrome（9223/9226），释放内存
+  auto    tab 数或 RSS 超阈值时自动执行 hard，否则只输出状态
+
+Env:
+  AGENT_BROWSER_TAB_LIMIT      默认 10
+  AGENT_BROWSER_RSS_LIMIT_MB   默认 1500
+USAGE
+}
+
+if [[ "$MODE" == "-h" || "$MODE" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if [[ "$MODE" != "status" && "$MODE" != "soft" && "$MODE" != "hard" && "$MODE" != "auto" ]]; then
+  usage >&2
+  exit 2
+fi
+
+portStatus() {
+  local portNumber="$1"
+  local profileDir=""
+  local tabCount="0"
+  local rssMb="0"
+  local profileArg=""
+
+  profileDir=$(profileForPort "$portNumber")
+  profileArg="--user-data-dir=${profileDir}"
+  rssMb=$(ps -axo rss=,command= | awk -v profileArg="$profileArg" '
+    {
+      for (fieldIndex = 2; fieldIndex <= NF; fieldIndex++) {
+        if ($fieldIndex == profileArg) {
+          sum += $1
+          break
+        }
+      }
+    }
+    END {printf "%d", sum / 1024}
+  ')
+
+  if curl -sf "http://127.0.0.1:${portNumber}/json/list" >/tmp/agent-browser-tabs-${portNumber}.json 2>/dev/null; then
+    tabCount=$(jq 'length' "/tmp/agent-browser-tabs-${portNumber}.json" 2>/dev/null || echo "0")
+  fi
+
+  rm -f "/tmp/agent-browser-tabs-${portNumber}.json"
+  printf '%s %s %s\n' "$portNumber" "$tabCount" "$rssMb"
+}
+
+printStatus() {
+  printf 'port\ttabs\trssMB\n'
+  portStatus 9223 | awk '{printf "%s\t%s\t%s\n", $1, $2, $3}'
+  portStatus 9226 | awk '{printf "%s\t%s\t%s\n", $1, $2, $3}'
+}
+
+closeChromeByPort() {
+  local portNumber="$1"
+  local profileDir=""
+  local processIds=""
+  profileDir=$(profileForPort "$portNumber")
+  processIds=$(ps -axo pid=,command= | awk -v portArg="--remote-debugging-port=${portNumber}" -v profileArg="--user-data-dir=${profileDir}" '
+    {
+      hasPort = 0
+      hasProfile = 0
+      for (fieldIndex = 2; fieldIndex <= NF; fieldIndex++) {
+        if ($fieldIndex == portArg) hasPort = 1
+        if ($fieldIndex == profileArg) hasProfile = 1
+      }
+      if (hasPort && hasProfile) print $1
+    }
+  ')
+  if [[ -z "$processIds" ]]; then
+    echo "port ${portNumber}: no agent-browser Chrome process"
+    return
+  fi
+
+  echo "port ${portNumber}: graceful quit"
+  printf '%s\n' "$processIds" | xargs -n1 /bin/kill -TERM
+}
+
+softCleanup() {
+  local portNumber="$1"
+  if ! curl -sf "http://127.0.0.1:${portNumber}/json/list" >/tmp/agent-browser-tabs-${portNumber}.json 2>/dev/null; then
+    echo "port ${portNumber}: not reachable"
+    return
+  fi
+
+  jq -r '.[] | select(.url | test("^(about:blank|chrome://newtab|devtools://|chrome://)")).id' "/tmp/agent-browser-tabs-${portNumber}.json" |
+    while IFS= read -r tabId; do
+      [[ -z "$tabId" ]] && continue
+      curl -sf "http://127.0.0.1:${portNumber}/json/close/${tabId}" >/dev/null || true
+      echo "port ${portNumber}: closed idle tab ${tabId}"
+    done
+
+  rm -f "/tmp/agent-browser-tabs-${portNumber}.json"
+}
+
+needsHardCleanup() {
+  local overLimit="0"
+  while read -r portNumber tabCount rssMb; do
+    if (( tabCount > TAB_LIMIT || rssMb > RSS_LIMIT_MB )); then
+      echo "port ${portNumber}: over limit tabs=${tabCount}/${TAB_LIMIT} rssMB=${rssMb}/${RSS_LIMIT_MB}"
+      overLimit="1"
+    fi
+  done < <(portStatus 9223 && portStatus 9226)
+  [[ "$overLimit" == "1" ]]
+}
+
+case "$MODE" in
+  status)
+    printStatus
+    ;;
+  soft)
+    softCleanup 9223
+    softCleanup 9226
+    printStatus
+    ;;
+  hard)
+    closeChromeByPort 9223
+    closeChromeByPort 9226
+    ;;
+  auto)
+    printStatus
+    if needsHardCleanup; then
+      closeChromeByPort 9223
+      closeChromeByPort 9226
+    else
+      echo "agent-browser Chrome is below cleanup thresholds"
+    fi
+    ;;
+esac