@roll-agent/browser-use-agent 0.14.0 → 0.16.0

package/SKILL.md

@@ -15,8 +15,9 @@ metadata:
 - 通过 Roll 调用本 Agent 时，先用 `roll skills get browser-use-agent --include-references --json` 读取当前说明和 `references/*`，再用 `roll agent tools browser-use-agent --json` 读取真实 schema。
 - 完整 `inputSchema` 以 `roll agent tools browser-use-agent --json` 为准。
 - 多账号/多 profile 场景下，Roll 会从 `browser.instances` 注入 `BROWSER_INSTANCES_JSON`；所有 browser-use tool 都支持可选 `browserInstance` 输入，用于选择目标 `profile/userDataDir + cdpPort + sessionsDir`。未传时按 `browser.defaultInstance`，再按单实例自动选择；多实例且无默认值时会返回 `needs_input`。
-- 多个 `managed-cdp` 实例首次启动时会自动把 Chrome profile 展示名设为实例 ID，并按声明顺序自适应平铺窗口：2–3 个实例横向并列并撑满桌面可用高度；4 个实例 2×2 铺满屏幕；5 个及以上按「最多 4 列、每行撑满宽度」均衡排列（5→3+2、6→3+3、8→4+4、10→4+3+3）。macOS 使用只读 `system_profiler SPDisplaysDataType` 探测逻辑分辨率；Windows 使用只读 PowerShell/.NET `PrimaryScreen.WorkingArea` 探测扣除任务栏后的工作区；探测不到时回退默认工作区；也可通过 `ROLL_BROWSER_WORK_AREA=x,y,width,height` 覆盖。需要固定布局时在实例上配置 `profile-name` / `window-bounds`。
+- 多个 `managed-cdp` 实例首次启动时会自动把 Chrome profile 展示名设为实例 ID，并按声明顺序分配 profile 颜色和自适应平铺窗口：2–3 个实例横向并列并撑满桌面可用高度；4 个实例 2×2 铺满屏幕；5 个及以上按「最多 4 列、每行撑满宽度」均衡排列（5→3+2、6→3+3、8→4+4、10→4+3+3）。macOS 使用只读 `system_profiler SPDisplaysDataType` 探测逻辑分辨率；Windows 使用只读 PowerShell/.NET `PrimaryScreen.WorkingArea` 探测扣除任务栏后的工作区；探测不到时回退默认工作区；也可通过 `ROLL_BROWSER_WORK_AREA=x,y,width,height` 覆盖。需要固定展示时在实例上配置 `profile-name` / `profile-color` / `window-bounds`。
 - 浏览器实例采用 **lazy start**：agent 启动不会立刻拉起全部 Chrome，首次访问某个 `browserInstance` 时才启动对应 profile/CDP runtime。
+- 实例级关闭使用 `roll browser stop <browserInstance...>` 或 `roll browser stop --all`；它只关闭当前 `browser-use-agent` 托管的浏览器 runtime，不停止 agent 服务进程，也不删除 `userDataDir` / `sessionsDir` 数据。停止整个服务仍使用 `roll agent stop browser-use-agent`。
 - `browser_status` 是无副作用诊断工具；它不会为了查询状态而启动尚未启动的 Chrome。需要启动某个实例时，调用带 `browserInstance` 的业务工具，例如 `open_platform({ browserInstance, platform:"zhipin" })`。
 - `browser_status.primaryInstanceId` 表示顶层 `running/headless/mode/security` 所采用的 primary bundle；多实例详情请看 `instances[]`。
 - `REPLY_AUTHORITY_URL` / `REPLY_AUTHORITY_BEARER_TOKEN` 是生成智能回复预览的必填环境变量；`REPLY_AUTHORITY_KEYS_URL` 是发送预备回复前验签的必填环境变量。`roll doctor` 会通过 `references/env.yaml` 和 `browser_status.effectiveEnvSources` 检查它们是否声明并在运行态生效。
@@ -54,6 +55,7 @@ browser:
       cdp-port: 9222
       user-data-dir: ~/.roll-agent/browser/profiles/boss-a
       sessions-dir: ~/.roll-agent/browser/sessions/boss-a
+      profile-color: "#2563EB"
       # window-bounds 可选；省略时按实例数量自动平铺
       tracking-agent-id: zhipin-boss-a
     boss-b:
@@ -62,6 +64,7 @@ browser:
       cdp-port: 9223
       user-data-dir: ~/.roll-agent/browser/profiles/boss-b
       sessions-dir: ~/.roll-agent/browser/sessions/boss-b
+      profile-color: "#DC2626"
       tracking-agent-id: zhipin-boss-b
 ```
 
@@ -76,6 +79,22 @@ orchestrator 规则：
 7. 每个账号首次托管时，需要人工在对应 Chrome 窗口完成 BOSS 登录；之后 session 跟随对应 `userDataDir` 和 `sessionsDir`。
 8. Chrome 原生 tab group 只通过扩展 API 暴露，browser-use 不注入扩展；用 profile 名称和窗口并排布局作为稳定识别方式。
 
+浏览器生命周期命令：
+
+| 目的 | 命令 | 行为 |
+| --- | --- | --- |
+| 关闭一个或多个实例窗口/runtime | `roll browser stop boss-a boss-b` | 只关闭指定 browser runtime；`browser-use-agent` 保持运行；`userDataDir` / `sessionsDir` 保留，后续调用会 lazy start。 |
+| 关闭全部已启动实例 | `roll browser stop --all` | 关闭当前 agent 托管的所有已启动 browser runtime；不停止服务进程，不删除数据。 |
+| 停止整个服务进程 | `roll agent stop browser-use-agent` | 停止 `browser-use-agent`；后续 tool 调用不可用，直到重新 `roll agent start browser-use-agent`。 |
+| 清理 profile/session 数据 | `roll browser clear-data [browserInstance] --yes` | 删除声明的 `userDataDir` / `sessionsDir`；先用无 `--yes` dry-run 确认范围，运行中的实例需先 stop，除非显式使用 force。 |
+
+规则：
+
+1. 人类或上层编排器做生命周期控制时优先使用 `roll browser stop`；`browser_stop` tool 主要服务 MCP/agent 内部集成。
+2. 只想重启某个浏览器窗口或释放 runtime 时，不要用 `roll agent stop browser-use-agent`。
+3. `remote-cdp` / `existing-session` 实例关闭时只断开 Roll 侧连接；不会关闭外部浏览器进程。
+4. 不扫描系统 Chrome 进程，也不按端口或目录强杀未由当前 agent 托管的浏览器。
+
 启动/检查流程：
 
 ```text
@@ -85,6 +104,7 @@ roll doctor --json
   -> roll run browser-use-agent open_platform --input-json '{"browserInstance":"boss-a","platform":"zhipin"}' --json
   -> 人工确认 boss-a 窗口登录
   -> roll run browser-use-agent zhipin_get_username --input-json '{"browserInstance":"boss-a"}' --json
+  -> roll browser stop boss-a  # 只关闭 boss-a 浏览器 runtime；agent 保持运行
 ```
 
 多账号批量示例：
@@ -121,10 +141,12 @@ zhipin_read_messages({ browserInstance, onlyUnread:true, limit:N })
 | Tool | 用途 |
 | --- | --- |
 | `browser_status()` | 查询浏览器 runtime、session、Reply Authority 公钥预加载状态、视觉反馈开关、安全策略和 env 指纹。 |
+| `browser_stop(browserInstance? / browserInstances? / all?)` | 关闭一个、多个或全部已启动 browser runtime；不停止 `browser-use-agent` 服务进程，未启动实例返回 `not_running`。 |
 | `open_platform(platform)` | 通过 native CDP 打开并聚焦招聘平台主页；登录前不触发 Playwright attach。 |
 | `list_pages(platform?)` | 通过 native CDP 列出浏览器页面和 `pageId`。 |
 | `select_page(platform, pageId)` | 将指定页面绑定为平台活跃页；登录前优先走 native target 激活。 |
 | `navigate_active_tab(url)` | 通过 native CDP 打开/导航页面；不触发 Playwright attach，不支持直接跳转 BOSS `/web/chat/*` 后台路径。 |
+| `browser_reload_active_tab(ignoreCache?, browserActionApproval?)` | 对当前 tracked native page 执行 CDP `Page.reload`，清空页面内 DOM 与 SPA 状态后等待文档换页；不触发 Playwright attach，走现有 actionPolicy / domainAllowlist 边界。reload 后所有 `@eN` / `candidateRef` 失效，必须重新 snapshot / 读列表。 |
 | `browser_snapshot(pageId?, maxDepth?, maxNodes?, interactiveOnly?)` | 读取当前或指定页面的 Accessibility Tree；默认只返回可交互节点，并为可交互节点生成 `@eN`；也会补充有限的非语义 DOM 可操作短文本，例如 `span` 渲染的 tab/filter 标签，并递归内联同 target iframe 中的可操作 AX 节点。 |
 | `click_ref(ref, pageId?, browserActionApproval?)` | 点击 `browser_snapshot` 返回的 `@eN`；优先用 `backendNodeId`，失效时用 `role/name/nth` fallback；iframe 子节点会携带并复用 `frameId`。 |
 | `type_ref(ref, text, clear?, pageId?, browserActionApproval?)` | 向 `browser_snapshot` 返回的 `@eN` 输入文本；`clear:true` 会先清空当前控件；iframe 子节点会携带并复用 `frameId`。 |
@@ -187,7 +209,7 @@ click_ref(@eN) 或 type_ref(@eN, text, clear?)
 | Tool | Backend | 说明 |
 | --- | --- | --- |
 | `zhipin_read_messages(limit?, onlyUnread?, sortBy?, autoScroll?, maxScrolls?)` | native CDP | 读取消息列表；默认 `autoScroll=true`，按 `conversationId` 去重。 |
-| `zhipin_open_chat_page()` | native CDP | 点击左侧导航切回「沟通」。 |
+| `zhipin_open_chat_page(forceReload?, browserActionApproval?)` | native CDP | 点击左侧导航切回「沟通」；`forceReload:true` 时只对当前沟通页执行 `Page.reload` 做长跑恢复，返回 `usedReload`；若实时页面已不是沟通页，会跳过 reload 并返回 `reloadSkippedReason`。 |
 | `zhipin_open_chat(conversationId?, candidateName?, index?, preferUnread?)` | native CDP | 打开目标聊天；匹配优先级为 `conversationId` > `candidateName` > `index`。 |
 | `zhipin_get_candidate_info(conversationId?, candidateName?, index?, maxMessages?)` | native CDP | 提取候选人资料、聊天记录、`conversationId`、`candidateId` 和页面职位信号。 |
 | `zhipin_generate_reply_preview(conversationId?, candidateName?, index?, maxMessages?, reasoning?)` | native CDP | 读取聊天上下文，调用 Reply Authority SSE 流式生成回复，并在浏览器内展示阶段与临时草稿；可用 `reasoning` 控制是否请求 thinking/reasoning；返回 `preparedReplyId`，不返回 `signedEnvelope`。 |
@@ -251,6 +273,10 @@ click_ref(@eN) 或 type_ref(@eN, text, clear?)
 27. 不要用 `navigate_active_tab` 直接跳转 `https://www.zhipin.com/web/chat/*`；聊天页用 `zhipin_open_chat_page()`，推荐页用 `zhipin_open_recommend_page()`。
 28. BOSS 已有专用工具能表达业务意图时，不要为了“看见按钮”而绕开专用工具改用 `click_ref` / `type_ref`。
 29. 对 BOSS 未建模按钮，例如新出现的“交换电话”，可以先用 `browser_snapshot` 找到对应 `@eN`，再 `click_ref`；弹窗确认类二次动作必须重新 snapshot 后再点击。
+30. 长跑同一 BOSS tab 出现「选中态丢失 / 列表错乱 / 依赖当前选中聊天的工具失败」时，做 periodic recovery 的边界：
+    - 优先 `zhipin_open_chat_page({ forceReload: true })`（或通用 `browser_reload_active_tab`）：等价手动 F5，清空当前 document 的 DOM 与页面内 SPA 状态，保留 Chrome 窗口与 profile 登录态；reload 后所有 `@eN` / `candidateRef` 失效，必须重新 snapshot / 读列表。
+    - 普通 `zhipin_open_chat_page()`（不带 forceReload）在已处于沟通页时只返回 `alreadyOnChat`，**不会**卸载 document，无法清状态。
+    - `roll browser stop` 才能回收 renderer 进程内存，但会关闭浏览器窗口；reload 只清 document 级状态，**不保证** renderer 100% 把内存归还 OS，杀进程仍由 `roll browser stop` 负责。
 
 ## 典型链路
 

package/dist/browser-instance-pool.d.ts

@@ -10,6 +10,14 @@ export interface BrowserRuntimeBundle {
     readonly sessionStore: SessionStore;
     readonly config: BrowserRuntimeConfig;
 }
+export declare const BROWSER_INSTANCE_STOP_STATUSES: readonly ["stopped", "not_running", "not_found", "failed"];
+export type BrowserInstanceStopStatus = (typeof BROWSER_INSTANCE_STOP_STATUSES)[number];
+export interface BrowserInstanceStopResult {
+    readonly browserInstance: string;
+    readonly status: BrowserInstanceStopStatus;
+    readonly mode?: BrowserRuntimeConfig["mode"];
+    readonly message?: string;
+}
 export declare class BrowserInstancePool {
     private readonly bundles;
     private readonly defaultInstanceId;
@@ -24,6 +32,8 @@ export declare class BrowserInstancePool {
     getBundle(browserInstance?: string): BrowserRuntimeBundle;
     getInstanceStatuses(): Promise<BrowserInstanceStatus[]>;
     closeAll(): Promise<void>;
+    closeInstances(instanceIds: readonly string[]): Promise<readonly BrowserInstanceStopResult[]>;
+    private closeInstance;
     private getOnlyInstanceId;
 }
 export declare function runWithBrowserInstance<T>(browserInstance: string | undefined, run: () => Promise<T>): Promise<T>;