@routerhub/agent-rules 1.5.197 → 1.5.199

package/AGENTS.base.md

@@ -695,6 +695,32 @@ 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 必须自动运行** `agent-browser-cleanup auto`
+    （或仓库源码内 `bash scripts/agent-browser-cleanup.sh auto`），禁止把这一步交给用户手动判断。
+    用户只负责提出任务，Agent 负责判断是否该释放内存。
+3. `9226` 无头 Chrome 优先用于 agent 自动化；`agent-browser-cleanup auto` 会在 `9226` 的 tab 数
+    > 10，或 RSS > 1500MB 时自动释放它。释放后下次需要浏览器时再重新启动，不要为了“可能等会用”
+    长期占着内存。
+4. `9223` 有头 Chrome 只在需要用户手动登录、手动查看动态效果、或必须共享可见页面时启动；
+    任务结束且用户不再需要查看时，必须关闭本任务 tab；`auto` 默认不会关闭 `9223`，避免误关用户
+    正在看的页面。只有明确确认 `9223` 没有人工操作中的页面时，才允许设置
+    `AGENT_BROWSER_CLEANUP_INCLUDE_HEADED=1 agent-browser-cleanup auto` 或执行 `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,18 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.199] - 2026-09-08
+
+### Changed
+
+- **agent-browser 收尾从“手动命令”升级为“Agent 自动判断”**：规则明确要求每次浏览器自动化任务结束前，由执行任务的 Agent 自动运行 `agent-browser-cleanup auto`，禁止把判断交给用户。`auto` 模式同步调整为默认只自动释放超阈值的 `9226` 无头 Chrome；`9223` 有头 Chrome 默认只提示，需设置 `AGENT_BROWSER_CLEANUP_INCLUDE_HEADED=1` 才会自动关闭，避免误关用户正在看的页面。
+
+## [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.199",
   "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,159 @@
+#!/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}"
+INCLUDE_HEADED="${AGENT_BROWSER_CLEANUP_INCLUDE_HEADED:-0}"
+
+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    超阈值时自动释放 9226；9223 默认只提示，避免误关用户正在看的页面
+
+Env:
+  AGENT_BROWSER_TAB_LIMIT      默认 10
+  AGENT_BROWSER_RSS_LIMIT_MB   默认 1500
+  AGENT_BROWSER_CLEANUP_INCLUDE_HEADED=1 时，auto 也允许释放 9223
+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 profileArg=""
+  local processIds=""
+  profileDir=$(profileForPort "$portNumber")
+  profileArg="--user-data-dir=${profileDir}"
+  processIds=$(ps -axo pid=,command= | awk -v profileArg="$profileArg" '
+    {
+      hasProfile = 0
+      for (fieldIndex = 2; fieldIndex <= NF; fieldIndex++) {
+        if ($fieldIndex == profileArg) hasProfile = 1
+      }
+      if (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"
+}
+
+autoCleanup() {
+  while read -r portNumber tabCount rssMb; do
+    if (( tabCount <= TAB_LIMIT && rssMb <= RSS_LIMIT_MB )); then
+      continue
+    fi
+
+    echo "port ${portNumber}: over limit tabs=${tabCount}/${TAB_LIMIT} rssMB=${rssMb}/${RSS_LIMIT_MB}"
+    if [[ "$portNumber" == "9226" ]]; then
+      closeChromeByPort "$portNumber"
+      continue
+    fi
+
+    if [[ "$portNumber" == "9223" && "$INCLUDE_HEADED" == "1" ]]; then
+      closeChromeByPort "$portNumber"
+      continue
+    fi
+
+    echo "port ${portNumber}: headed Chrome skipped; set AGENT_BROWSER_CLEANUP_INCLUDE_HEADED=1 to close it automatically"
+  done < <(portStatus 9223 && portStatus 9226)
+}
+
+case "$MODE" in
+  status)
+    printStatus
+    ;;
+  soft)
+    softCleanup 9223
+    softCleanup 9226
+    printStatus
+    ;;
+  hard)
+    closeChromeByPort 9223
+    closeChromeByPort 9226
+    ;;
+  auto)
+    printStatus
+    autoCleanup
+    ;;
+esac