dsh-browser-verify 0.1.1 → 0.1.3

package/README.md

@@ -18,7 +18,7 @@ verification is just tool calls.
 ## Quick start
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.1
+dsh plugin --profile web add dsh-browser-verify@0.1.3
 ```
 
 1. **Install** with the command above (or see [Install](#install)).
@@ -44,7 +44,7 @@ state?"; add `browser_screenshot` when you need to see the layout, or
 
 | Tool | Purpose |
 |---|---|
-| `browser_open` | Open a URL in a fresh scenario (headless Chromium, default viewport 390×844 @2x) and report title / HTTP status / visible-text summary / console errors. Optional `waitSelector` waits for a key element before returning, and optional inline `mocks` intercept APIs **before** the first navigation — for pages that boot against mocked data. |
+| `browser_open` | Open a URL in a fresh scenario (headless Chromium, default viewport 390×844 @2x) and report title / HTTP status / visible-text summary / console errors. Without `waitSelector` it waits for the page to render-settle (two identical consecutive visible-text samples, capped at ~3s) before snapshotting, so it never returns the boot/skeleton frame; loading-state noise (`加载中...` etc.) is filtered out of the summary. Optional `waitSelector` waits for a key element before returning, and optional inline `mocks` intercept APIs **before** the first navigation — for pages that boot against mocked data. |
 | `browser_mock` | Register a playwright-glob route (`**/api/*.do*`) returning your JSON, then auto-reload the page to show the mocked state — the quickest way to verify empty / error / abnormal states without touching the backend. Duplicate patterns are rejected with a hint. |
 | `browser_assert` | The cheapest and most precise check: wait for a CSS selector, verify its count and contained text, return `{pass, count, actualText, elapsedMs}`. A mismatch is `pass:false` (with the diff), never a throw — so failure is a first-class result, not an error you debug. |
 | `browser_screenshot` | Capture the current page (viewport or full page) and **auto-project the image block into the model context** — the model sees the layout without any file handling. Reports dimensions, sha256, and `identicalToPrevious:true` when the shot is byte-identical to the previous one (page probably not refreshed). |
@@ -69,7 +69,7 @@ browser_screenshot
 ## Install
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.1
+dsh plugin --profile web add dsh-browser-verify@0.1.3
 ```
 
 The version is pinned on purpose: pnpm 11 holds back packages published in the
@@ -92,17 +92,6 @@ or point the plugin at an existing binary via `DSH_BROWSER_VERIFY_CHROMIUM`
 (see [Environment variables](#environment-variables)). Without either, the
 first `browser_open` fails with an actionable install hint.
 
-### From a source checkout
-
-```sh
-pnpm install && pnpm build && pnpm pack     # → dsh-browser-verify-<version>.tgz
-dsh plugin --profile web add ./dsh-browser-verify-<version>.tgz
-# or: dsh plugin --profile web add /path/to/dsh-browser-verify   (build first — lib/ is gitignored)
-```
-
-The tarball ships a prebuilt `lib/`, so no build step runs on the installing
-machine.
-
 ## Environment variables
 
 | Variable | Default | Meaning |
@@ -131,7 +120,7 @@ machine.
 
 ## Testing status
 
-39 unit tests (fully offline — no browser needed), strict typecheck, and a
+41 unit tests (fully offline — no browser needed), strict typecheck, and a
 per-file ≥90% statement coverage gate. Verified **end-to-end in the real DSH
 web GUI** on dsh 0.1.2-alpha.4: a two-state loop (empty + normal) against a
 live uni-app H5 (hhhweb) in 6 tool calls, with screenshots auto-projected and
@@ -163,6 +152,11 @@ CLI (harness-free debug path): `node lib/cli.js --url <u> [--mock <file.json>]
 [--wait-selector <sel>] [--assert <sel>] [--screenshot] [--persist <dir>]
 [--viewport <WxH>]`.
 
+Contributors can install the local build with
+`dsh plugin --profile web add ./dsh-browser-verify-<version>.tgz` after
+`pnpm build`; the tarball ships a prebuilt `lib/`, so no build step runs on
+the installing machine.
+
 ## License & attribution
 
 Apache-2.0. Architecture and implementation notes for agents and

package/README.zh.md

@@ -3,7 +3,7 @@
 [English](README.md) | 中文
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D22-blue.svg)](package.json)
+[![Node](<https://img.shields.io/badge/node-%3E%3D22-blue.svg>)](package.json)
 
 **给你的 DeepSeek Harness 一双看网页的眼睛** —— 只读浏览器验证，≤4 次工具调用完成：打开、mock、断言、截图。
 
@@ -12,7 +12,7 @@
 ## 快速上手
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.1
+dsh plugin --profile web add dsh-browser-verify@0.1.3
 ```
 
 1. **安装**（更多方式见 [安装](#安装)）。
@@ -34,12 +34,12 @@ browser_assert  selector=".empty-wrap" text="暂无可用缴费服务"
 
 ## 它做什么
 
-| 工具 | 用途 |
-|---|---|
-| `browser_open` | 在全新场景中打开 URL（无头 Chromium，默认视口 390×844 @2x），返回 title / HTTP 状态 / 可见文本摘要 / console 错误。可选 `waitSelector` 等待关键元素出现后再返回；可选内联 `mocks` 在**首次导航前**拦截接口——用于一启动就依赖 mock 数据的页面。 |
-| `browser_mock` | 注册 playwright glob 路由（如 `**/api/*.do*`）返回指定 JSON，并自动 reload 页面展示 mock 状态——不碰后端最快验证空态/异常态。重复 pattern 会提示报错。 |
-| `browser_assert` | 最省 token 也最精确的验证：等待 CSS 选择器出现，校验数量与包含文本，返回 `{pass, count, actualText, elapsedMs}`。不满足时返回 `pass:false`（附差异），**绝不抛错**——失败是一等公民的结果，而不是要调试的异常。 |
-| `browser_screenshot` | 截取当前页面（视口或整页），**自动以 image block 投影到模型上下文**——模型直接"看见"版式，无需任何文件处理。返回尺寸、sha256；与上一张完全一致时 `identicalToPrevious:true`（疑似页面未刷新）。 |
+| 工具                   | 用途                                                                                                                                                                                                                                                       |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `browser_open`       | 在全新场景中打开 URL（无头 Chromium，默认视口 390×844 @2x），返回 title / HTTP 状态 / 可见文本摘要 / console 错误。不传 `waitSelector` 时默认等待页面**渲染稳定**后再采样（连续两次相同可见文本即稳定，上限约 3s），不会采到启动骨架帧；`加载中...` 等加载态文案自动过滤。可选 `waitSelector` 等待关键元素出现后再返回；可选内联 `mocks` 在**首次导航前**拦截接口——用于一启动就依赖 mock 数据的页面。 |
+| `browser_mock`       | 注册 playwright glob 路由（如`**/api/*.do*`）返回指定 JSON，并自动 reload 页面展示 mock 状态——不碰后端最快验证空态/异常态。重复 pattern 会提示报错。                                                                                                   |
+| `browser_assert`     | 最省 token 也最精确的验证：等待 CSS 选择器出现，校验数量与包含文本，返回`{pass, count, actualText, elapsedMs}`。不满足时返回 `pass:false`（附差异），**绝不抛错**——失败是一等公民的结果，而不是要调试的异常。                                  |
+| `browser_screenshot` | 截取当前页面（视口或整页），**自动以 image block 投影到模型上下文**——模型直接"看见"版式，无需任何文件处理。返回尺寸、sha256；与上一张完全一致时 `identicalToPrevious:true`（疑似页面未刷新）。                                                   |
 
 先 `browser_assert` 再 `browser_screenshot`：断言更便宜，截图留给必须判断
 渲染效果的时刻。
@@ -61,11 +61,10 @@ browser_screenshot
 ## 安装
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.1
+dsh plugin --profile web add dsh-browser-verify@0.1.3
 ```
 
-版本故意钉死：pnpm 11 会暂缓 24 小时内新发布的包，裸写 `add
-dsh-browser-verify`（latest）会在发布当天装到上一个版本。`--profile web`
+版本故意钉死：pnpm 11 会暂缓 24 小时内新发布的包，裸写 `add dsh-browser-verify`（latest）会在发布当天装到上一个版本。`--profile web`
 是本部署的 GUI profile——如果不同请换成你自己的 profile 名。
 
 要求 **dsh ≥ 0.1.2-alpha.1**。
@@ -81,23 +80,13 @@ npx playwright install chromium     # 需要 playwright-core@1.62.0
 或通过 `DSH_BROWSER_VERIFY_CHROMIUM` 指向已有二进制（见
 [环境变量](#环境变量)）。两者都没有时，第一次 `browser_open` 会给出可操作的安装提示。
 
-### 源码 checkout 安装
-
-```sh
-pnpm install && pnpm build && pnpm pack     # → dsh-browser-verify-<version>.tgz
-dsh plugin --profile web add ./dsh-browser-verify-<version>.tgz
-# 或：dsh plugin --profile web add /path/to/dsh-browser-verify  （需先 build——lib/ 不入库）
-```
-
-tgz 内已含预构建 `lib/`，安装机无需再构建。
-
 ## 环境变量
 
-| 变量 | 默认 | 含义 |
-|---|---|---|
-| `DSH_BROWSER_VERIFY_CHROMIUM` | *(未设置)* | Chromium 完整路径；优先于缓存探测。路径错误时启动即报可操作提示。 |
-| `DSH_BROWSER_VERIFY_TIMEOUT` | `10000` | `browser_open` 页面加载路径的墙钟预算（ms），含 wait-selector 与 mock reload。 |
-| `DSH_BROWSER_VERIFY_IDLE_MS` | `600000` | 空闲回收窗口（ms），超时后浏览器实例自动关闭；插件 dispose 时强制清理。 |
+| 变量                            | 默认         | 含义                                                                             |
+| ------------------------------- | ------------ | -------------------------------------------------------------------------------- |
+| `DSH_BROWSER_VERIFY_CHROMIUM` | *(未设置)* | Chromium 完整路径；优先于缓存探测。路径错误时启动即报可操作提示。                |
+| `DSH_BROWSER_VERIFY_TIMEOUT`  | `10000`    | `browser_open` 页面加载路径的墙钟预算（ms），含 wait-selector 与 mock reload。 |
+| `DSH_BROWSER_VERIFY_IDLE_MS`  | `600000`   | 空闲回收窗口（ms），超时后浏览器实例自动关闭；插件 dispose 时强制清理。          |
 
 ## 可靠性与清理
 
@@ -108,12 +97,11 @@ tgz 内已含预构建 `lib/`，安装机无需再构建。
   ```sh
   rm -rf "$(node -p 'require("os").tmpdir()')/dsh-browser-verify-*"
   ```
-
 - **错误即接口**——所有错误以 `browser-verify: ` 前缀开头、以可操作建议结尾；验证"失败"是结果（`pass:false`），不是异常。
 
 ## 测试状态
 
-39 个单测（完全离线，无需浏览器）、严格 typecheck、每文件 ≥90% 语句覆盖率闸门。已在 **dsh 0.1.2-alpha.4 真实 GUI 端到端验证**：对一个真实 uni-app H5（hhhweb），空态+正常态两态闭环共 6 次调用，截图自动投影，无临时目录残留、无僵尸进程。
+41 个单测（完全离线，无需浏览器）、严格 typecheck、每文件 ≥90% 语句覆盖率闸门。已在 **dsh 0.1.2-alpha.4 真实 GUI 端到端验证**：对一个真实 uni-app H5（hhhweb），空态+正常态两态闭环共 6 次调用，截图自动投影，无临时目录残留、无僵尸进程。
 
 ## 已知限制
 
@@ -133,9 +121,11 @@ pnpm vitest run --coverage   # discover / cleanup / attachments 每文件 ≥90%
 scripts/smoke.sh      # 两态端到端；需要参考应用 dev server 在 :5173
 ```
 
-CLI（免 harness 的调试路径）：`node lib/cli.js --url <u> [--mock <file.json>]
-[--wait-selector <sel>] [--assert <sel>] [--screenshot] [--persist <dir>]
-[--viewport <WxH>]`。
+CLI（免 harness 的调试路径）：`node lib/cli.js --url <u> [--mock <file.json>] [--wait-selector <sel>] [--assert <sel>] [--screenshot] [--persist <dir>] [--viewport <WxH>]`。
+
+贡献者可本地构建后安装：`pnpm build` 后
+`dsh plugin --profile web add ./dsh-browser-verify-<version>.tgz`——tgz 内已含
+预构建 `lib/`，安装机无需再构建。
 
 ## 许可与署名
 

package/cordis.patch.yml

@@ -1,17 +1,11 @@
-# dsh-browser-verify bundle patch: inserts the four browser verification
-# tools into the web profile roster. Applied as a profile bundle layer (the
-# dsh.bundle.patch manifest field).
+# dsh-browser-verify bundle patch: registers the four read-only browser
+# verification tools (browser_open / browser_mock / browser_assert /
+# browser_screenshot) in the profile's tool roster. Applied automatically as a
+# profile bundle layer (dsh.bundle.patch in package.json).
 #
-# Install (from a source checkout; tarball name follows the current version):
-#   pnpm install && pnpm build && pnpm pack
-#   dsh plugin --profile web add ./dsh-browser-verify-<version>.tgz
-#   # or, during development, add the checkout directory directly (pnpm link):
-#   dsh plugin --profile web add <path-to-this-directory>
-#
-# Host half only: the node half (exports ".") registers browser_open /
-# browser_mock / browser_assert / browser_screenshot. No client half, no
-# settings card. Configuration is env-var only (DSH_BROWSER_VERIFY_*); do NOT
-# add a `config:` block here.
+# Install: dsh plugin --profile web add dsh-browser-verify@<version>
+# Host half only — no client half, no settings card. Configuration is env-var
+# only (DSH_BROWSER_VERIFY_*); do NOT add a `config:` block here.
 - insert:
     - id: browser-verify
       name: 'dsh-browser-verify'

package/lib/cli.js

@@ -1,4 +1,4 @@
-import { t as BrowserDriver } from "./driver-DxMldTYf.js";
+import { t as BrowserDriver } from "./driver-Dwuu4MgP.js";
 import { readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";

package/lib/{driver-DxMldTYf.js → driver-Dwuu4MgP.js}

@@ -91,6 +91,19 @@ const MAX_VISIBLE = 8;
 const MAX_VISIBLE_LEN = 40;
 const MAX_ERRORS = 5;
 const MAX_ERROR_LEN = 120;
+/** Poll interval and cap for the default render-settled wait (no waitSelector). */
+const SETTLE_INTERVAL_MS = 250;
+const SETTLE_CAP_MS = 3e3;
+/**
+* Loading-state noise (uni-app showLoading / boot toasts) filtered out of the
+* visible summary. Anchored full-string patterns only, so business states like
+* 加载失败 / 加载更多 are never affected.
+*/
+const NOISE_TEXT_PATTERN = /^(加载中|正在加载|请稍候|loading)[.…]{0,3}$/i;
+/** True for transient loading-state text that should not pollute the summary. */
+function isNoiseText(text) {
+	return NOISE_TEXT_PATTERN.test(text);
+}
 function assertNoMockConflict(patterns, next) {
 	if (patterns.includes(next)) throw new Error(`browser-verify: 拦截 pattern 已存在: ${next}（已有: ${patterns.join(", ")}）。请先 browser_open 重开场景或用不同的 urlPattern。`);
 }
@@ -110,7 +123,7 @@ function summarizeVisibleText(texts) {
 	const out = [];
 	for (const raw of texts) {
 		const trimmed = raw.trim();
-		if (trimmed === "") continue;
+		if (trimmed === "" || isNoiseText(trimmed)) continue;
 		const reduced = trimmed.length > MAX_VISIBLE_LEN ? trimmed.slice(0, MAX_VISIBLE_LEN) : trimmed;
 		if (seen.has(reduced)) continue;
 		seen.add(reduced);
@@ -159,6 +172,7 @@ var Scenario = class {
 			timeout
 		});
 		if (opts.waitSelector !== void 0) await this.page.waitForSelector(opts.waitSelector, { timeout });
+		else await this.waitUntilRendered(timeout);
 		const texts = await this.page.evaluate(VISIBLE_TEXT_SCRIPT);
 		return {
 			title: await this.page.title(),
@@ -169,6 +183,26 @@ var Scenario = class {
 			elapsedMs: Date.now() - started
 		};
 	}
+	/**
+	* Default settle wait: two consecutive identical non-empty visible-text
+	* samples (250ms apart) mean the render stopped changing. Bounded by
+	* min(timeoutMs, 3s) — pages that never settle (polling/animations) fall
+	* through to the current snapshot instead of burning the whole budget.
+	*/
+	async waitUntilRendered(timeoutMs) {
+		const cap = Math.min(timeoutMs, SETTLE_CAP_MS);
+		const deadline = Date.now() + cap;
+		let prev = null;
+		for (;;) {
+			const sig = (await this.page.evaluate(VISIBLE_TEXT_SCRIPT)).join("\0");
+			if (sig !== "") {
+				if (prev !== null && sig === prev) return;
+				prev = sig;
+			}
+			if (Date.now() >= deadline) return;
+			await new Promise((resolve) => setTimeout(resolve, SETTLE_INTERVAL_MS));
+		}
+	}
 	async addMock(rule) {
 		assertNoMockConflict([...this.mocks.keys()], rule.urlPattern);
 		const status = rule.status ?? 200;

package/lib/index.js

@@ -1,4 +1,4 @@
-import { t as BrowserDriver } from "./driver-DxMldTYf.js";
+import { t as BrowserDriver } from "./driver-Dwuu4MgP.js";
 import { exec } from "node:child_process";
 import { readdir, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -111,7 +111,7 @@ function registerBrowserTools(ctx) {
 	});
 	ctx.tools.register(defineTool({
 		name: "browser_open",
-		description: "在无头浏览器中打开一个页面并返回页面状态（标题/状态码/可见文本摘要/console 错误）用于验证前端页面；可选 waitSelector 等待关键元素出现，默认视口 390×844 @2x（移动端形态）。可传 mocks 在打开时拦截接口（用于启动即依赖接口数据的页面）。验证顺序：先 browser_assert 做 DOM 断言，确需看版式再 browser_screenshot。",
+		description: "在无头浏览器中打开一个页面并返回页面状态（标题/状态码/可见文本摘要/console 错误）用于验证前端页面；可选 waitSelector 等待关键元素出现（不传时自动等待页面渲染稳定后返回，加载态文案如「加载中...」自动过滤），默认视口 390×844 @2x（移动端形态）。可传 mocks 在打开时拦截接口（用于启动即依赖接口数据的页面）。验证顺序：先 browser_assert 做 DOM 断言，确需看版式再 browser_screenshot。",
 		parameters: {
 			url: {
 				type: "string",
@@ -165,7 +165,7 @@ function registerBrowserTools(ctx) {
 			},
 			waitSelector: {
 				type: "string",
-				description: "可选：等待该选择器出现后再返回（优先于固定等待）"
+				description: "可选：等待该选择器出现后再返回；不传则自动等待页面渲染稳定后返回（最多数秒）"
 			},
 			timeoutMs: {
 				type: "number",

package/lib/types/browser/scenario.d.ts

@@ -23,6 +23,8 @@ export interface AssertResult {
     actualText: string | null;
     elapsedMs: number;
 }
+/** True for transient loading-state text that should not pollute the summary. */
+export declare function isNoiseText(text: string): boolean;
 export declare function assertNoMockConflict(patterns: string[], next: string): void;
 export declare function normalizeCountSpec(count: number | {
     min: number;
@@ -48,6 +50,13 @@ export declare class Scenario {
         waitSelector?: string;
         timeoutMs?: number;
     }): Promise<OpenResult>;
+    /**
+     * Default settle wait: two consecutive identical non-empty visible-text
+     * samples (250ms apart) mean the render stopped changing. Bounded by
+     * min(timeoutMs, 3s) — pages that never settle (polling/animations) fall
+     * through to the current snapshot instead of burning the whole budget.
+     */
+    private waitUntilRendered;
     addMock(rule: {
         urlPattern: string;
         json: unknown;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-browser-verify",
   "description": "Read-only browser verification tools for the DeepSeek Harness web GUI: browser_open / browser_mock / browser_assert / browser_screenshot — verify a page (H5/desktop) in ≤4 tool calls with mock interception, DOM assertions, and screenshots that auto-project into the model context.",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {
@@ -31,6 +31,10 @@
   "dependencies": {
     "playwright-core": "1.62.0"
   },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.4"
+  },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.4",

package/src/browser/scenario.ts

@@ -34,6 +34,20 @@ const MAX_VISIBLE_LEN = 40
 const MAX_ERRORS = 5
 const MAX_ERROR_LEN = 120
 const MAX_DIFF_LEN = 120
+/** Poll interval and cap for the default render-settled wait (no waitSelector). */
+const SETTLE_INTERVAL_MS = 250
+const SETTLE_CAP_MS = 3000
+/**
+ * Loading-state noise (uni-app showLoading / boot toasts) filtered out of the
+ * visible summary. Anchored full-string patterns only, so business states like
+ * 加载失败 / 加载更多 are never affected.
+ */
+const NOISE_TEXT_PATTERN = /^(加载中|正在加载|请稍候|loading)[.…]{0,3}$/i
+
+/** True for transient loading-state text that should not pollute the summary. */
+export function isNoiseText(text: string): boolean {
+  return NOISE_TEXT_PATTERN.test(text)
+}
 
 export function assertNoMockConflict(patterns: string[], next: string): void {
   if (patterns.includes(next)) {
@@ -52,7 +66,7 @@ export function summarizeVisibleText(texts: string[]): string[] {
   const out: string[] = []
   for (const raw of texts) {
     const trimmed = raw.trim()
-    if (trimmed === '') continue
+    if (trimmed === '' || isNoiseText(trimmed)) continue
     const reduced = trimmed.length > MAX_VISIBLE_LEN ? trimmed.slice(0, MAX_VISIBLE_LEN) : trimmed
     if (seen.has(reduced)) continue
     seen.add(reduced)
@@ -106,6 +120,11 @@ export class Scenario {
     const response = await this.page.goto(opts.url, { waitUntil: 'domcontentloaded', timeout })
     if (opts.waitSelector !== undefined) {
       await this.page.waitForSelector(opts.waitSelector, { timeout })
+    } else {
+      // No explicit selector: wait for the page to render-settle instead of
+      // snapshotting the boot frame (SPAs like uni-app show skeleton/loading
+      // right after domcontentloaded — a 500ms snapshot reads empty).
+      await this.waitUntilRendered(timeout)
     }
     const texts = await this.page.evaluate(VISIBLE_TEXT_SCRIPT) as string[]
     return {
@@ -118,6 +137,27 @@ export class Scenario {
     }
   }
 
+  /**
+   * Default settle wait: two consecutive identical non-empty visible-text
+   * samples (250ms apart) mean the render stopped changing. Bounded by
+   * min(timeoutMs, 3s) — pages that never settle (polling/animations) fall
+   * through to the current snapshot instead of burning the whole budget.
+   */
+  private async waitUntilRendered(timeoutMs: number): Promise<void> {
+    const cap = Math.min(timeoutMs, SETTLE_CAP_MS)
+    const deadline = Date.now() + cap
+    let prev: string | null = null
+    for (;;) {
+      const sig = (await this.page.evaluate(VISIBLE_TEXT_SCRIPT) as string[]).join('\u0000')
+      if (sig !== '') {
+        if (prev !== null && sig === prev) return
+        prev = sig
+      }
+      if (Date.now() >= deadline) return
+      await new Promise(resolve => setTimeout(resolve, SETTLE_INTERVAL_MS))
+    }
+  }
+
   async addMock(rule: { urlPattern: string; json: unknown; status?: number; reload?: boolean; timeoutMs?: number }): Promise<string[]> {
     assertNoMockConflict([...this.mocks.keys()], rule.urlPattern)
     const status = rule.status ?? 200

package/src/tools/index.ts

@@ -24,7 +24,7 @@ export function registerBrowserTools(ctx: Context): void {
 
   ctx.tools.register(defineTool({
     name: 'browser_open',
-    description: '在无头浏览器中打开一个页面并返回页面状态（标题/状态码/可见文本摘要/console 错误）用于验证前端页面；可选 waitSelector 等待关键元素出现，默认视口 390×844 @2x（移动端形态）。可传 mocks 在打开时拦截接口（用于启动即依赖接口数据的页面）。验证顺序：先 browser_assert 做 DOM 断言，确需看版式再 browser_screenshot。',
+    description: '在无头浏览器中打开一个页面并返回页面状态（标题/状态码/可见文本摘要/console 错误）用于验证前端页面；可选 waitSelector 等待关键元素出现（不传时自动等待页面渲染稳定后返回，加载态文案如「加载中...」自动过滤），默认视口 390×844 @2x（移动端形态）。可传 mocks 在打开时拦截接口（用于启动即依赖接口数据的页面）。验证顺序：先 browser_assert 做 DOM 断言，确需看版式再 browser_screenshot。',
     parameters: {
       url: { type: 'string', required: true, description: '页面地址，如 http://localhost:5173/hweb/pages/...' },
       viewport: {
@@ -50,7 +50,7 @@ export function registerBrowserTools(ctx: Context): void {
         },
         description: '可选：页面启动前注册的接口拦截（glob urlPattern + json，如 [{urlPattern: "**/api/*.do*", json: {...}}]）',
       },
-      waitSelector: { type: 'string', description: '可选：等待该选择器出现后再返回（优先于固定等待）' },
+      waitSelector: { type: 'string', description: '可选：等待该选择器出现后再返回；不传则自动等待页面渲染稳定后返回（最多数秒）' },
       timeoutMs: { type: 'number', description: `加载超时，默认 ${envTimeoutMs()}ms` },
     },
     output: {