@angelky7/dsh-browser-control 1.7.6 → 1.7.7

package/README.md

@@ -240,7 +240,7 @@ curl -X POST http://127.0.0.1:9777/api/command \
 |---|---|
 | `browser_navigate` | 导航到 URL |
 | `browser_read` | 读取页面文本/HTML，正文直接给模型（`offset`/`limit` 窗口，长文分页） |
-| `browser_snapshot` | 页面快照 → 逐条列出 ref 的交互树（`mode:"ax"` 走 Chrome 无障碍树，拿 role + 可访问名） |
+| `browser_snapshot` | 页面快照 → 逐条列出 ref 的交互树（`mode:"ax"` 走 Chrome 无障碍树，拿 role + 可访问名）；v1.7.7 起支持 `offset` **分页**：页头写明「第几到第几 / 页面总数 / 下一页 offset」，超出扩展 200 条窗口的部分如实说明用 find/read 补齐 |
 | `browser_click` | 点击元素（by ref / selector） |
 | `browser_type` | 在输入框填入文本 |
 | `browser_press` | 模拟键盘按键（回车、Tab、方向键，以及 "Ctrl+A" / "Shift+ArrowRight" 这类组合键；一次按键只插入一次） |

package/lib/index.js

@@ -2032,9 +2032,13 @@ function applyBrowserTools(ctx, controller) {
 				type: "number",
 				description: "Target tab; defaults to the active tab."
 			},
+			offset: {
+				type: "number",
+				description: "Skip this many items into the inventory (paging); default 0. Refs are valid for THIS call only — take the next page in the same breath if you need stable refs."
+			},
 			limit: {
 				type: "number",
-				description: "Max elements returned; defaults to 120, capped at 200."
+				description: "Page size: max items returned by this call; defaults to 120. The extension supplies up to a 200-item window per call."
 			},
 			mode: {
 				type: "string",
@@ -2060,6 +2064,17 @@ function applyBrowserTools(ctx, controller) {
 					},
 					mode: { type: "string" },
 					axFallback: { type: "string" },
+					offset: {
+						type: "number",
+						required: true
+					},
+					total: { type: "number" },
+					returned: { type: "number" },
+					nextOffset: { type: "number" },
+					hasMore: {
+						type: "boolean",
+						required: true
+					},
 					items: {
 						type: "array",
 						required: true,
@@ -2084,9 +2099,13 @@ function applyBrowserTools(ctx, controller) {
 				}
 			},
 			render: (_args, value) => {
+				const shown = value.items.length;
+				const start = value.offset + 1;
+				const end = value.offset + shown;
+				const totalText = value.total === void 0 ? `${value.returned ?? shown} available` : `${value.total} on the page`;
 				return [{
 					type: "text",
-					text: clampRendered([`${value.items.length} interactive elements on ${value.title} (mode ${value.mode ?? "dom"}); click or fill them by ref:` + (value.axFallback === void 0 ? "" : `\n(mode ax fell back to dom: ${value.axFallback})`), ...value.items.map((item) => {
+					text: clampRendered([`${shown === 0 ? `no items at offset ${value.offset}` : `items ${start}–${end} of ${totalText}`}${value.total !== void 0 && value.returned !== void 0 && value.total > value.returned ? ` (this extension returns at most ${value.returned}-item windows — use browser_find/browser_read to reach the rest)` : ""}${value.nextOffset === void 0 ? "" : `; next page: offset ${value.nextOffset}`} (mode ${value.mode ?? "dom"}); click or fill them by ref:` + (value.axFallback === void 0 ? "" : `\n(mode ax fell back to dom: ${value.axFallback})`), ...value.items.map((item) => {
 						const name = item.name === void 0 ? "" : ` "${flattenOneLine(item.name, 80)}"`;
 						const href = item.href === void 0 ? "" : ` -> ${flattenOneLine(item.href, 100)}`;
 						return `[${item.ref}] ${item.role ?? item.tag}${name}${href}`;
@@ -2100,20 +2119,33 @@ function applyBrowserTools(ctx, controller) {
 			kind: "other"
 		}),
 		async execute(args, exec) {
-			const params = { limit: Math.min(200, Math.max(1, args.limit ?? 120)) };
+			const offset = Math.max(0, Math.trunc(typeof args.offset === "number" && Number.isFinite(args.offset) ? args.offset : 0));
+			const limit = Math.min(200, Math.max(1, typeof args.limit === "number" && Number.isFinite(args.limit) ? Math.trunc(args.limit) : 120));
+			const params = { limit: 200 };
 			if (typeof args.tabId === "number") params.tabId = args.tabId;
 			if (typeof args.mode === "string") params.mode = args.mode;
 			const raw = await controller.execute("snapshot", params, exec.signal);
 			const requestedAx = args.mode === "ax";
 			const gotAx = raw.mode === "ax" || raw.ax !== void 0;
 			const axFallback = typeof raw.axFallback === "string" && raw.axFallback.length > 0 ? raw.axFallback : requestedAx && !gotAx ? "this extension ignored mode:\"ax\" and returned CSS-DOM matches (AX mode needs DSH Browser Control extension v1.0.11 or newer) — the names below are tag names, not accessible names" : void 0;
+			const window = Array.isArray(raw.items) ? raw.items : [];
+			const returned = window.length;
+			const reportedTotal = typeof raw.total === "number" && Number.isFinite(raw.total) ? Math.trunc(raw.total) : void 0;
+			const total = reportedTotal === void 0 ? void 0 : Math.max(returned, reportedTotal);
+			const page = window.slice(offset, offset + limit);
+			const hasMore = offset + page.length < returned;
 			return {
 				tabId: raw.tabId,
 				title: raw.title ?? "",
 				url: raw.url ?? "",
 				...raw.mode === void 0 ? {} : { mode: raw.mode },
 				...axFallback === void 0 ? {} : { axFallback },
-				items: (raw.items ?? []).map((item) => ({
+				offset,
+				...total === void 0 ? {} : { total },
+				returned,
+				hasMore,
+				...hasMore ? { nextOffset: offset + page.length } : {},
+				items: page.map((item) => ({
 					ref: item.ref,
 					tag: item.tag,
 					...item.role === void 0 ? {} : { role: item.role },

package/lib/types/index.js

@@ -809,7 +809,8 @@ function applyBrowserTools(ctx, controller) {
         description: 'Inventory the page\'s interactive elements with stable refs; pass a ref to browser_click/browser_type afterwards. mode:"ax" numbers them by Chrome\'s accessibility tree (role + accessible name), which survives a DOM redesign; the default mode matches CSS selectors.',
         parameters: {
             tabId: { type: 'number', description: 'Target tab; defaults to the active tab.' },
-            limit: { type: 'number', description: 'Max elements returned; defaults to 120, capped at 200.' },
+            offset: { type: 'number', description: 'Skip this many items into the inventory (paging); default 0. Refs are valid for THIS call only — take the next page in the same breath if you need stable refs.' },
+            limit: { type: 'number', description: 'Page size: max items returned by this call; defaults to 120. The extension supplies up to a 200-item window per call.' },
             mode: { type: 'string', description: '"ax" for the accessibility tree, "dom" (default) for the selector list. "ax" falls back to "dom" with axFallback set if the page gives no a11y tree.' },
         },
         output: {
@@ -822,6 +823,11 @@ function applyBrowserTools(ctx, controller) {
                     url: { type: 'string', required: true },
                     mode: { type: 'string' },
                     axFallback: { type: 'string' },
+                    offset: { type: 'number', required: true },
+                    total: { type: 'number' },
+                    returned: { type: 'number' },
+                    nextOffset: { type: 'number' },
+                    hasMore: { type: 'boolean', required: true },
                     items: {
                         type: 'array',
                         required: true,
@@ -840,7 +846,16 @@ function applyBrowserTools(ctx, controller) {
                 },
             },
             render: (_args, value) => {
-                const head = `${value.items.length} interactive elements on ${value.title}`
+                const shown = value.items.length;
+                const start = value.offset + 1;
+                const end = value.offset + shown;
+                const totalText = value.total === undefined ? `${value.returned ?? shown} available` : `${value.total} on the page`;
+                const range = shown === 0 ? `no items at offset ${value.offset}` : `items ${start}–${end} of ${totalText}`;
+                const capped = value.total !== undefined && value.returned !== undefined && value.total > value.returned
+                    ? ` (this extension returns at most ${value.returned}-item windows — use browser_find/browser_read to reach the rest)`
+                    : '';
+                const next = value.nextOffset === undefined ? '' : `; next page: offset ${value.nextOffset}`;
+                const head = `${range}${capped}${next}`
                     + ` (mode ${value.mode ?? 'dom'}); click or fill them by ref:`
                     + (value.axFallback === undefined ? '' : `\n(mode ax fell back to dom: ${value.axFallback})`);
                 const lines = value.items.map(item => {
@@ -853,8 +868,12 @@ function applyBrowserTools(ctx, controller) {
         },
         presentCall: () => ({ card: 'generic', title: 'Snapshot browser page', kind: 'other' }),
         async execute(args, exec) {
-            const limit = Math.min(200, Math.max(1, args.limit ?? 120));
-            const params = { limit };
+            const offset = Math.max(0, Math.trunc(typeof args.offset === 'number' && Number.isFinite(args.offset) ? args.offset : 0));
+            const limit = Math.min(200, Math.max(1, typeof args.limit === 'number' && Number.isFinite(args.limit) ? Math.trunc(args.limit) : 120));
+            // Ask for the largest window the extension offers (200) and page in the
+            // plugin: older surfaces never learned an offset parameter, and they do
+            // report `total`, so paging stays plugin-side (v1.7.7).
+            const params = { limit: 200 };
             if (typeof args.tabId === 'number')
                 params.tabId = args.tabId;
             if (typeof args.mode === 'string')
@@ -872,13 +891,24 @@ function applyBrowserTools(ctx, controller) {
                 : (requestedAx && !gotAx
                     ? 'this extension ignored mode:"ax" and returned CSS-DOM matches (AX mode needs DSH Browser Control extension v1.0.11 or newer) — the names below are tag names, not accessible names'
                     : undefined);
-            return {
+            const window = Array.isArray(raw.items) ? raw.items : [];
+            const returned = window.length;
+            const reportedTotal = typeof raw.total === 'number' && Number.isFinite(raw.total) ? Math.trunc(raw.total) : undefined;
+            const total = reportedTotal === undefined ? undefined : Math.max(returned, reportedTotal);
+            const page = window.slice(offset, offset + limit);
+            const hasMore = offset + page.length < returned;
+            const receipt = {
                 tabId: raw.tabId,
                 title: raw.title ?? '',
                 url: raw.url ?? '',
                 ...(raw.mode === undefined ? {} : { mode: raw.mode }),
                 ...(axFallback === undefined ? {} : { axFallback }),
-                items: (raw.items ?? []).map(item => ({
+                offset,
+                ...(total === undefined ? {} : { total }),
+                returned,
+                hasMore,
+                ...(hasMore ? { nextOffset: offset + page.length } : {}),
+                items: page.map(item => ({
                     ref: item.ref,
                     tag: item.tag,
                     ...(item.role === undefined ? {} : { role: item.role }),
@@ -886,6 +916,7 @@ function applyBrowserTools(ctx, controller) {
                     ...(item.href === undefined ? {} : { href: item.href }),
                 })),
             };
+            return receipt;
         },
     }));
     ctx.tools.register(defineTool({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@angelky7/dsh-browser-control",
   "description": "Local WebSocket bridge between dsh and the DSH Browser Control browser extension, with model-facing browser_* tools and a Settings-managed on/off switch",
-  "version": "1.7.6",
+  "version": "1.7.7",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -37,7 +37,7 @@
     "build": "tsc -p tsconfig.json && tsdown",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "check": "npm run typecheck && npm run build && publint",
-    "verify": "node verify/verify_config_patch.mjs && node verify/verify_peers.mjs && node verify/verify_surface.mjs && node verify/verify_tab_groups.mjs && node verify/verify_tabs_close_many.mjs && node verify/verify_cdp_retry.mjs && node verify/verify_snapshot_ax.mjs && node verify/verify_hard_lock.mjs && node verify/verify_policy.mjs && node verify/verify_cookies.mjs && node verify/verify_extension_e2e.mjs && node verify/verify_plugin.mjs legacy && node verify/verify_plugin.mjs conflict && node verify/verify_plugin.mjs new && node verify/verify_http.mjs && node verify/verify_errors.mjs && node verify/verify_hold.mjs && node verify/verify_protocol.mjs && node verify/verify_bundle_http.mjs && node verify/verify_nav_report.mjs && node verify/verify_nav_landing.mjs && node verify/verify_render_contract.mjs && node verify/verify_press_events.mjs && node verify/verify_nav_timeout.mjs && node verify/verify_nav_waituntil.mjs && node verify/verify_archive.mjs && node verify/verify_windows.mjs && node verify/verify_history_nav.mjs && node verify/verify_metrics_throttle.mjs && node verify/verify_drag.mjs && node verify/verify_audit.mjs && node verify/verify_journal.mjs && node verify/verify_sessions.mjs && node verify/verify_compat_matrix.mjs"
+    "verify": "node verify/verify_config_patch.mjs && node verify/verify_peers.mjs && node verify/verify_surface.mjs && node verify/verify_tab_groups.mjs && node verify/verify_tabs_close_many.mjs && node verify/verify_cdp_retry.mjs && node verify/verify_snapshot_ax.mjs && node verify/verify_hard_lock.mjs && node verify/verify_policy.mjs && node verify/verify_cookies.mjs && node verify/verify_extension_e2e.mjs && node verify/verify_plugin.mjs legacy && node verify/verify_plugin.mjs conflict && node verify/verify_plugin.mjs new && node verify/verify_http.mjs && node verify/verify_errors.mjs && node verify/verify_hold.mjs && node verify/verify_protocol.mjs && node verify/verify_bundle_http.mjs && node verify/verify_nav_report.mjs && node verify/verify_nav_landing.mjs && node verify/verify_render_contract.mjs && node verify/verify_press_events.mjs && node verify/verify_nav_timeout.mjs && node verify/verify_nav_waituntil.mjs && node verify/verify_archive.mjs && node verify/verify_windows.mjs && node verify/verify_history_nav.mjs && node verify/verify_metrics_throttle.mjs && node verify/verify_drag.mjs && node verify/verify_audit.mjs && node verify/verify_journal.mjs && node verify/verify_sessions.mjs && node verify/verify_snapshot_page.mjs && node verify/verify_compat_matrix.mjs"
   },
   "publishConfig": {
     "access": "public",