@routerhub/agent-rules 1.5.197 → 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/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.197",
+  "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