qz-browser-agent 0.1.5 → 0.1.6

package/README.md

@@ -15,34 +15,11 @@ and step in from the side panel. Everything runs locally.
 
 ## Quick start
 
-Requires Node.js 22 or later.
-
-1. **Install the extension.** Click **Add to Chrome** on the
-   [Chrome Web Store](https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm).
-2. **Install the CLI.** Or use `npx qz-browser-agent@latest` in place of `qz`.
-
-   ```bash
-   npm install --global qz-browser-agent@latest
-   ```
-3. **Drive the browser.** No model setup is needed in qz.
-
-   ```bash
-   qz session create --title "Read example page"
-   qz script --session SESSION_ID - <<'JS'
-   const page = qz.tab(await qz.openTab({ url: "https://example.com" }));
-   return await page.read({ limit: 2000 });
-   JS
-   ```
-
-   The first command connects the browser automatically. To teach your agent the full workflow,
-   install the qz Skill with `npx skills add alibaba/qz-browser-agent -g`, or have it read `qz skill`.
-4. **Or hand qz the whole task.** Choose a provider and model in the side panel's **Settings**, then:
-
-   ```bash
-   qz create "Find this year's Nobel Prize winners in every category and put them in a table with source links." --stream
-   ```
-
-   `--stream` shows progress, any questions qz needs you to answer, and the final result.
+Use Node.js 22+ on the computer running your browser. Reuse `qz` if it is already on PATH; otherwise, install it once for ongoing use with `npm install -g qz-browser-agent`. Use `npx -y qz-browser-agent@latest` in place of `qz` only as a temporary fallback. Run `qz skill` with that same CLI and read its matching-version guide rather than copying instructions from another version.
+
+Start with `qz session create --title "Read a page" --json`. qz prepares its local service and reuses a responding browser connection, or opens a connection page in your default browser. Ask the user to review and accept the first-use data notice in the qz side panel and approve the connection when prompted. If the extension is missing, `qz install` opens the Chrome Web Store; the user adds the extension, completes setup, and you retry the session command if needed. If qz is installed in another browser profile, open the connection page’s copyable link there. This direct-drive path needs no manual port, service, or qz model setup.
+
+Use the returned `result.sessionId` in every `qz script --session ID task.js` call, following the guide and binding pages with `qz.tab(tabRef)`. You plan and drive the task; finish with `qz session cancel ID`. Use `qz create "TASK" --stream` only when the user wants qz’s built-in agent to plan and execute the task, including human–agent collaboration; that path uses the provider and model configured in qz.
 
 ## Drive the browser
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qz-browser-agent",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Local browser tools and MCP access for the qz extension",
   "type": "module",
   "engines": { "node": ">=22" },

package/src/catalog.json

@@ -283,7 +283,7 @@
   },
   {
     "name": "qingzhou_list_tools",
-    "description": "List default direct-drive tool signatures; sessionId is optional. Query non-default or loaded Skill tools by exact name with qingzhou_get_tool (pass sessionId for loaded Skills). For full schemas, call tools.list_tools({names:[...]}) inside run_script. Never creates a session.",
+    "description": "List default direct-drive tool signatures; sessionId is optional. Query non-default or loaded Skill tools by exact name with qingzhou_get_tool (pass sessionId for loaded Skills). For full schemas, call qz.listTools({names:[...]}) inside run_script. Never creates a session.",
     "inputSchema": {
       "properties": {
         "sessionId": {"title": "Sessionid", "type": "string"},
@@ -381,7 +381,7 @@
   },
   {
     "name": "qingzhou_execute_tool",
-    "description": "在已连接的浏览器里执行现有工具。先调用 qingzhou_create_drive_session 创建会话，再传入该 sessionId（不会隐式创建会话）。单次调用传 name 与 args；已知参数的并发或顺序批次传 calls（每项含 id、name、args，id 仅用于关联结果，不支持跨项插值）；多步逻辑与条件编排可调用 name:\"run_script\"（页面外执行，支持顶层 await/return 与 tools.*，页面内 DOM 函数用 evaluate）。页面工具显式传 tabRef。逐项检查 isError，批次与脚本均非事务；run_script 的 result 为 {ok,result,trace} 回执，trace 按序记录报错与显式 trace()/console 输出。Execute browser tools in an explicitly created session (pass sessionId from qingzhou_create_drive_session). Supply name/args for one call, calls ([{id,name,args}]) for a static batch, or name:\"run_script\" for outer JS orchestration (use evaluate for in-page DOM functions). Page tools require an explicit tabRef. Check isError on each call; batches and scripts are not transactions. run_script returns {ok,result,trace}, where trace lists errors and explicit trace()/console diagnostics in order.",
+    "description": "在已连接的浏览器里执行现有工具。先调用 qingzhou_create_drive_session 创建会话，再传入该 sessionId（不会隐式创建会话）。单次调用传 name 与 args；已知参数的并发或顺序批次传 calls（每项含 id、name、args，id 仅用于关联结果，不支持跨项插值）；多步逻辑与条件编排可调用 name:\"run_script\"（页面外执行，支持顶层 await/return 与 qz SDK，原始工具用 qz.call(name,args)，页面内 DOM 函数用 page.evaluate）。页面工具显式传 tabRef。逐项检查 isError，批次与脚本均非事务；run_script 的 result 为 {ok,result,trace} 回执，trace 按序记录报错与显式 trace()/console 输出。Execute browser tools in an explicitly created session (pass sessionId from qingzhou_create_drive_session). Supply name/args for one call, calls ([{id,name,args}]) for a static batch, or name:\"run_script\" for outer JS orchestration with the qz SDK (qz.call(name,args) for raw tools; page.evaluate for in-page DOM functions). Page tools require an explicit tabRef. Check isError on each call; batches and scripts are not transactions. run_script returns {ok,result,trace}, where trace lists errors and explicit trace()/console diagnostics in order.",
     "inputSchema": {
       "properties": {
         "scriptApiVersion": {"type": "integer", "minimum": 1, "description": "Script API protocol version; must match the extension before executing the request."},

package/src/cli.mjs

@@ -22,10 +22,11 @@ export const HELP = renderHelp();
 async function stdinText({ signal } = {}) {
   signal?.throwIfAborted();
   const input = process.stdin;
-  if (input.readableEnded) return "";
   return new Promise((resolve, reject) => {
     const chunks = [];
+    let eof;
     const cleanup = () => {
+      clearImmediate(eof);
       input.removeListener("data", data);
       input.removeListener("end", end);
       input.removeListener("error", fail);
@@ -33,14 +34,21 @@ async function stdinText({ signal } = {}) {
       input.pause();
     };
     const data = chunk => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-    const end = () => { cleanup(); resolve(Buffer.concat(chunks).toString("utf8")); };
+    // npm may close this pipe before its forwarded signal callback runs. Keep
+    // cancellation live through that I/O turn instead of reporting empty input.
+    const end = () => { eof = setImmediate(() => {
+      cleanup();
+      if (signal?.aborted) reject(signal.reason);
+      else resolve(Buffer.concat(chunks).toString("utf8"));
+    }); };
     const fail = error => { cleanup(); reject(error); };
     const abort = () => fail(signal.reason);
     input.on("data", data);
     input.once("end", end);
     input.once("error", fail);
     signal?.addEventListener("abort", abort, { once: true });
-    input.resume();
+    if (input.readableEnded) end();
+    else input.resume();
   });
 }
 

package/src/commands.mjs

@@ -136,8 +136,8 @@ export const COMMANDS = {
     help: ["qz script --session ID [FILE|-] [--args JSON]", "Run JavaScript orchestration outside the page. stdout is {ok,result,trace}: execution status, the returned business value (or error), and ordered trace messages.",
       "--session ID is required. Create one session per task with qz session create --title TITLE and pass its sessionId.",
       "Read a local file or use - for stdin. Write top-level await and return; --args passes a JSON value as args (aliased as input).",
-      "Call browser tools via tools.<name>(...) with explicit tabRef values; awaited calls return business values directly and throw on failure. Use tools.evaluate({tabRef,code,args}) for in-page DOM/window access.",
-      "Discover compact signatures with tools.list_tools() and full schemas with tools.list_tools({names:[...]}).",
+      "Use the qz SDK: bind a page with qz.tab(tabRef), act through page.locator(targetOrQuery), and run in-page DOM/window code with page.evaluate(code,args). Awaited calls return business values directly and throw on failure.",
+      "Discover compact signatures with qz.listTools() and full schemas with qz.listTools({names:[...]}); call any listed tool with qz.call(name,args). Run qz skill for the full guide.",
       "--timeout sets the script timeout in seconds (0 < seconds <= 3600) and defaults to 120. The request waits 60 seconds longer.",
       "stdout is always {ok,result,trace}: ok reports execution success, result holds the returned value (null for undefined) or {code,message,hint?,details?}, and trace lists errors and explicit trace()/console output in order without levels. Exit codes: 0 success, 1 execution or connection failure, 2 invalid arguments.",
       "qz script --session ID task.js --args '{\"query\":\"example\"}'", "qz script --session ID - <<'JS'"],

package/src/qz-drive-SKILL.md

@@ -1,22 +1,14 @@
 ---
 name: qz-browser-agent
-description: Drive the connected browser through qz (轻舟) scripts. Create one titled session per task, pass its sessionId to every script, and bind each page with qz.tab(tabRef). Read qz skill for the installed CLI's guide. Read references/create-task.md only when the built-in agent should plan the task.
+description: Drive the connected browser through qz (轻舟) scripts. Create one titled session per task, pass its sessionId to every script, and bind each page with qz.tab(tabRef). Read references/create-task.md only when the built-in agent should plan the task.
 ---
 
-Use the installed `qz` command. If unavailable, use `npx -y qz-browser-agent@latest` in place of `qz` in the commands below. Run `qz skill` once at the start of a task for the matching guide. `qz --version` prints its version.
+Use Node.js 22+ on the computer running your browser. Reuse `qz` if it is already on PATH; otherwise, install it once for ongoing use with `npm install -g qz-browser-agent`. Use `npx -y qz-browser-agent@latest` in place of `qz` only as a temporary fallback.
 
 <!-- qz-drive-guide:en -->
-The external agent plans the work and drives the connected browser through qz (轻舟). Do not configure a qz model or call `qz create`. Read references/create-task.md only when the built-in agent should plan and execute the task.
+Start with `qz session create --title "Read a page" --json`. qz prepares its local service and reuses a responding browser connection, or opens a connection page in your default browser. Ask the user to review and accept the first-use data notice in the qz side panel and approve the connection when prompted. If the extension is missing, `qz install` opens the Chrome Web Store; the user adds the extension, completes setup, and you retry the session command if needed. If qz is installed in another browser profile, open the connection page’s copyable link there. This direct-drive path needs no manual port or service setup. Do not configure a qz model for direct-drive.
 
-## Connect
-
-Run commands with Node.js 22+ on the machine running the browser extension:
-
-```sh
-qz status --json
-```
-
-Session and script commands prepare the connection automatically: they reuse a responding online browser, or open the connection page once in the system default browser and wait for its extension to respond. Complete the extension's first-use notice and connection prompt when shown. If the extension is missing, `qz install` opens the store; ask the user to install it. When qz does not respond in that browser, the page offers the store and a copyable connection link, and a pending connection error carries the same link in `details.url`: ask the user which browser has qz installed, open the link there, and retry. Do not search browser profiles for the extension.
+Use the returned `result.sessionId` in every `qz script --session ID task.js` call, following the guide and binding pages with `qz.tab(tabRef)`. You plan and drive the task; finish with `qz session cancel ID`. Use `qz create "TASK" --stream` and read `references/create-task.md` only when the user wants qz’s built-in agent to plan and execute the task, including human–agent collaboration; that path uses the provider and model configured in qz.
 
 When multiple browsers are registered, run `qz browsers --json` and pass `--client CLIENT_UUID` to select a profile explicitly. Existing sessions are located via read-only queries before execution; ambiguous or unavailable ownership requires explicit selection. To pair a specific profile without launching a browser, run `qz connect uri --name work --json` and open `result.url` in that profile. An incompatible local service is restarted once before browser operations; an incompatible extension requires updating the CLI and extension together.
 
@@ -36,25 +28,26 @@ return await qz.tab(opened).read({ limit: 3000 });
 JS
 ```
 
-`qz.openTab({url,tabAlias?})` creates a page and returns a Tab `{tabRef,url,title,active}`; `qz.listTabs()` returns a list in `tabs`. `qz.tab(...)` binds an existing page using that Tab, its `tabRef`, or its optional alias. Aliases use 1–64 letters, digits, underscores, or hyphens (not all digits), and expire when the tab closes. Returned positive integers or numeric strings are valid references; never guess one. `active` marks the tab visible to the user and never selects an operation's target. Use `page.goto(url)` to navigate an existing task tab. `page.setMode("mobile")` switches to mobile mode (`"desktop"` restores it); a change reloads the page, so re-observe it afterward.
+`qz.openTab({url,tabAlias?})` creates a page and returns a Tab `{tabRef,url,title,active}`; `qz.listTabs()` returns `{tabs,count,foreign}`, where each Tab also has `ownership` and `foreign` counts tabs held by other sessions. `qz.tab(...)` binds an existing page using that Tab, its `tabRef`, or its optional alias. Aliases use 1–64 letters, digits, underscores, or hyphens (not all digits), and expire when the tab closes. Returned positive integers or numeric strings are valid references; never guess one. `active` marks the tab visible to the user and never selects an operation's target. Use `page.goto(url)` to navigate an existing task tab. `page.setMode("mobile")` switches to mobile mode (`"desktop"` restores it); a change reloads the page, so re-observe it afterward.
 
-One tab belongs to one session at a time. Use `qz.listTabs({scope:"all"})` for read-only inspection of other tabs, and a session-owned page for actions or evaluation. Binding a Page neither changes ownership nor selects the active tab.
+One tab belongs to one session at a time. `qz.listTabs()` lists this session's tabs (`ownership:"owned"`) and tabs no session holds (`"unclaimed"`), including the page the user is viewing when it is unclaimed. To work on a page the user already has open, bind its `tabRef` from this list instead of opening a duplicate. Listing never claims a tab: the first action, navigation, or `page.evaluate` on an unclaimed tab claims it for this session, and reads leave ownership unchanged. `qz.listTabs({scope:"owned"})` lists only this session's tabs. `qz.listTabs({scope:"all"})` adds tabs held by other sessions (`"foreign"`), which allow read-only inspection only. Binding a Page neither changes ownership nor selects the active tab.
 
 ## Scripts and the qz SDK
 
-`qz script --session ID [FILE|-] [--args JSON]` runs JavaScript orchestration outside web pages. Read a local file or `-` for stdin; `--args` passes a JSON value exposed as `args`. Use top-level `await` and `return`, starting with a short comment stating the script's purpose. The outer script survives page navigation and provides `qz`, `args`, `trace()`, and `console`, without `document`/`window`, Node.js, `fs`, `process`, `require`, or `import`. Awaited SDK calls return business values directly and throw on failure.
+`qz script --session ID [FILE|-] [--args JSON]` runs JavaScript orchestration outside web pages. Read a local file or `-` for stdin; `--args` passes a JSON value exposed as `args`. Use top-level `await` and `return`, starting with a short comment stating the script's purpose. Every `timeout` option is in seconds; a value outside a call's range fails instead of being clamped. The outer script survives page navigation and provides `qz`, `args`, `trace()`, and `console`, without `document`/`window`, Node.js, `fs`, `process`, `require`, or `import`. Awaited SDK calls return business values directly and throw on failure.
 
 Bind `const page = qz.tab(tabRef)` and use:
 
 | Purpose | SDK methods |
 | --- | --- |
 | Navigation and page mode | `page.goto(url, options?)`, `page.close()`, `page.setMode(mode)` |
-| Focused observations | `page.read({limit,...})`, `page.find({role:"link",...})`, `page.axTree(options)`, `page.screenshot(options)` |
+| Focused observations | `page.read({limit,...})`, `page.find(query)`, `page.axTree(options)`, `page.screenshot(options)` |
+| Page scrolling | `page.scroll({direction,pixels})` with direction `up`, `down`, `top`, or `bottom` |
 | Page JavaScript | `page.evaluate(code, args?, options?)` |
 | State waits | `page.waitForURL(pattern, options?)`, `page.waitForLoad(options?)`, `page.waitForFunction(code, args?, options?)` |
 | Element operations | `page.locator(targetOrQuery)` with the methods below |
 
-Use `qz.listTools()` for compact signatures of additional capabilities and `qz.listTools({names:["list_images"]})` for selected full schemas, including declared `outputSchema` fields and examples. Invoke those capabilities through `qz.call(name, args)`, using their catalog names and explicit `tabRef` for page calls. Read unfamiliar schemas before calling and use declared return fields.
+Use `qz.listTools()` for compact signatures of additional capabilities and `qz.listTools({names:["list_images"]})` for selected full schemas, including declared `outputSchema` fields and examples. Invoke those capabilities through `qz.call(name, args)`, using their catalog names and explicit `tabRef` for page calls. Read unfamiliar schemas before calling and use declared return fields; unknown fields are rejected. Raw tools that take an element accept `target` or `locator` (the query object below), and `within` limits a search to a container.
 
 `qz_skills` are browser workflows installed in the qz extension. `qz session create --json` returns their summaries in `result.qz_skills`, and each script receipt includes them in `context.qz_skills`: enabled user Global and Resident workflows, plus Site workflows matching sites visited by this task. Start a new site with a short observation script and check this catalog before further work. Global and Resident workflow tools are callable from session creation and appear in `qz.listTools()`; Site workflow tools become callable when the task visits a matching site. Load a relevant workflow with `return await qz.call("load_skill", {name:"skill-name"})`. Read its `content` and `tools`: each tool includes its exact calling `name`, description, input `parameters`, and declared `outputSchema` with examples. Loading activates those tools for the session immediately, so later calls in the same script can use them. Follow the workflow’s page prerequisites, then invoke `qz.call(name, args)` with those parameters and an explicit `tabRef` for page tools. After conversation compaction, reload the workflow if its instructions are missing. The catalog repeats on every receipt; full instructions are loaded on demand through qz, independently of the external agent's own Skill loader. Use `qz.call("list_skills", {url:"https://example.com"})` to query explicitly; omit `url` for all user workflows. Built-in Skills are hidden from discovery but remain loadable by name.
 
@@ -80,9 +73,9 @@ Observe the relevant controls and choose the result needed by the next step. Use
 
 Use search results as leads; verify key facts on the original pages. Include source URLs for key findings and make clear when evidence or coverage is incomplete.
 
-`page.locator(query)` stores a query and resolves it when an operation runs. Queries accept `target`, `role`, `name`, `text`, `exact`, `scope`, and `nth`; at least one of `target`, `role`, `name`, or `text` is required. The SDK accepts `{css:"#input"}` as shorthand for `{target:"css:#input"}`; use one form. CSS lists have one prefix for the whole expression (`"css:input, button"`). `name` matches the accessible name reported by `page.find` or `page.axTree`; `text` matches element text. Both normalize whitespace and match exactly, case-sensitively, by default; `exact:false` matches a substring. `scope` is an observed `uid:` or `css:` root, including a frame document reference. A pinned UID already identifies its scope; do not combine it with `scope`. Element operations require one match: narrow an ambiguous query or explicitly choose `locator.nth(index)` using a zero-based index.
+`page.locator(query)` stores a query and resolves it when an operation runs. Queries accept `target`, `role`, `name`, `text`, `exact`, `within`, `nth`, and `includeHidden`; at least one of `target`, `role`, `name`, or `text` is required. The SDK accepts `{css:"#input"}` as shorthand for `{target:"css:#input"}`; use one form. CSS lists have one prefix for the whole expression (`"css:input, button"`). `name` matches the accessible name reported by `page.find` or `page.axTree`; `text` matches element text. Both normalize whitespace and match exactly, case-sensitively, by default; `exact:false` matches a substring. `within` is an observed `uid:` or `css:` container, including a frame document reference. A pinned UID already identifies its container; do not combine it with `within`. Hidden elements match `role`/`name`/`text` queries, and count toward their `nth`, only with `includeHidden:true`, while a `target` always resolves, hidden or not. Element operations require one match: narrow an ambiguous query or explicitly choose `locator.nth(n)` using a zero-based index.
 
-Locator methods are `click(options?)`, `doubleClick(options?)`, `hover(options?)`, `fill(value, options?)`, `press(key, options?)`, `select(value, options?)`, `check(options?)`, `uncheck(options?)`, `scroll(options?)`, and `dragTo(destination, options?)` on the same tab. Actions locate and wait for a usable element within their shared `timeout` budget (seconds, default 20, maximum 120), then dispatch once. Call the next locator operation directly; it handles readiness. Dispatched actions are never automatically replayed. Ordinary success returns `{}`, with `navigated`/`url` or `navigationPending` when navigation is detected, and `popups` for observed new Tabs. If `confirmationRequired` is true, verify the field locally before continuing.
+Locator methods are `click(options?)`, `doubleClick(options?)`, `hover(options?)`, `fill(value, options?)`, `press(key, options?)`, `select(value, options?)`, `check(options?)`, `uncheck(options?)`, `scrollIntoView(options?)`, and `dragTo(destination, options?)` on the same tab. Action options are `timeout`, `expect`, `tabAlias` (with `expect:"popup"`), and `submit` (fill only). Actions locate and wait for a usable element within their shared `timeout` budget (default 20, maximum 120), then dispatch once. Call the next locator operation directly; it handles readiness. Dispatched actions are never automatically replayed. Ordinary success returns `{}`, with `navigated`/`url` or `navigationPending` when navigation is detected, and `popups` for observed new Tabs. If `confirmationRequired` is true, verify the field locally before continuing.
 
 ```js
 // Fill an observed form and choose its asynchronously appearing suggestion.
@@ -92,14 +85,14 @@ await page.locator({ role: "option", name: args.expectedOption }).click({ timeou
 return await page.locator(args.fieldTarget).inspect();
 ```
 
-Use `locator.inspect()` for current element state and `locator.read({limit})` for its text. `locator.wait({state:"visible",timeout:10})` waits for `attached`, `visible` (default), `hidden`, or `detached` state. Hidden includes removal or invisibility; detached requires removal. `locator.count()` reads the current attached match count, including hidden elements; `locator.wait({count:3,timeout:10})` waits for exactly that count, including zero. Use either `state` or `count` per wait. A match or count describes the current moment; it does not prove a dynamic list has finished updating.
+Use `locator.inspect()` for current element state, `locator.read({limit})` for its text, and `locator.axTree()` or `locator.screenshot()` for its subtree or pixels. `locator.wait({state:"visible",timeout:10})` waits for `attached`, `visible` (default), `hidden`, or `detached` state. Hidden includes removal or invisibility; detached requires removal. `locator.count()` reads the current match count; `locator.wait({count:3,timeout:10})` waits for exactly that count, including zero. Use either `state` or `count` per wait. A match or count describes the current moment; it does not prove a dynamic list has finished updating.
 
-When an action must cause navigation or a popup, pass `waitFor:"navigation"` or `waitFor:"popup"` in its options. This installs the listener before dispatch. Navigation returns its observation; popup returns a Tab `{tabRef,url,title,active}` directly. A failed wait never replays the action.
+When an action must cause navigation or a popup, pass `expect:"navigation"` or `expect:"popup"` in its options. This installs the listener before dispatch. Navigation returns its observation; popup returns a Tab `{tabRef,url,title,active}` directly. A failed wait never replays the action.
 
 ```js
 // Open a detail page and read it.
 const popup = await qz.tab("page").locator({ role: "link", name: "Details" })
-  .click({ waitFor: "popup", timeout: 10 });
+  .click({ expect: "popup", timeout: 10 });
 return await qz.tab(popup).read({ limit: 2000 });
 ```
 
@@ -119,7 +112,7 @@ return await page.waitForFunction(name => {
 
 Use selectors and fields observed on the page. If it retains previous values while loading, also wait for a completion signal that distinguishes the selected item's result.
 
-`page.find` returns an array of current element observations (up to `limit`), or `[]` when none match. Use normal array operations, e.g. `(await page.find({role:"link"})).slice(0,5)`; `waitFor:"match",timeout:10` waits for a candidate. Use `role`, `tag`, and `type` for single filters, or `roles`, `tags`, and `types` for multiple alternatives; use one form per filter. For example, `page.find({tag:"input",type:"search"})` finds search inputs. Its `pattern` accepts a regex string (case-insensitive by default) or a `RegExp`, as in `page.find({role:"link",pattern:/download/i})`; a `RegExp` supplies its own flags. Locator `name` and `text` match their specific fields. `page.axTree` uses `scope:"viewport"` or `"full"`; narrow `target` or `limit` when inspecting one control. Reserve screenshots for visual checks.
+`page.find(query)` accepts the same `role`, `name`, `text`, `exact`, and `within` fields as `page.locator(query)` and returns an array of every matching current element observation (`[]` when none match). Results are in the same order as `nth` for the same query: document order, except that `exact:false` or `pattern` lists whole `name`/`text` matches first, then prefix matches, then the rest. Use array operations on the result, e.g. `(await page.find({text:"Tomorrow",exact:false})).slice(0,5)`; `waitForMatch:true,timeout:10` waits for a candidate. Hidden elements are skipped unless `includeHidden:true`. Use `role`, `tag`, and `type` for single filters, or `roles`, `tags`, and `types` for multiple alternatives; use one form per filter. For example, `page.find({tag:"input",type:"search"})` finds search inputs. For a regular expression, pass `pattern` instead of `name`/`text`/`exact`: a regex string (case-insensitive by default) or a `RegExp`, as in `page.find({role:"link",pattern:/download/i})`; a `RegExp` supplies its own flags. `page.axTree` reads `scope:"viewport"` or `"full"`; use `locator.axTree()` or a smaller `limit` for one control. Reserve screenshots for visual checks.
 
 Run one `qz script` at a time per session. Within it, use `await` for dependencies and `Promise.all` for independent page workflows. Same-page actions serialize; the caller sees results when the script returns. `Promise.all` preserves input order and rejects on first failure without cancelling siblings; use `Promise.allSettled` to retain every outcome. Await all calls before returning: exit cancels unfinished calls.
 

package/src/tools.mjs

@@ -264,7 +264,7 @@ const GUIDE_TOOL = {
     properties: {},
   },
 };
-const DRIVE_INSTRUCTIONS = "先用 qingzhou_create_drive_session 或 qz session create --title TITLE 创建带可读标题的会话，后续每次执行工具或脚本都传入该 sessionId（CLI 必传 --session，缺失退出码为 2，不会自动建会话）；list_tools/get_tool 查询基础目录无需会话。页面工具必传 tabRef（open_tab 设置的可选 tabAlias，或 open_tab / list_tabs 返回的 tabRef）。通过 qingzhou_execute_tool（单工具、calls 批次或 run_script 外层编排）执行操作，页面内 DOM 求值使用 evaluate。Create a session with a readable title using qingzhou_create_drive_session or qz session create --title TITLE, then pass that sessionId on every tool or script execution (CLI calls require --session; omitting it exits 2 and does not create a session). list_tools/get_tool can inspect the base catalog without a session. Page tools require tabRef (an optional tabAlias from open_tab, or the tabRef returned by open_tab or list_tabs). Orchestrate with qingzhou_execute_tool (single tool, calls batch, or outer run_script) and use evaluate for in-page DOM execution.";
+const DRIVE_INSTRUCTIONS = "先用 qingzhou_create_drive_session 或 qz session create --title TITLE 创建带可读标题的会话，后续每次执行工具或脚本都传入该 sessionId（CLI 必传 --session，缺失退出码为 2，不会自动建会话）；list_tools/get_tool 查询基础目录无需会话。页面工具必传 tabRef（open_tab 设置的可选 tabAlias，或 open_tab / list_tabs 返回的 tabRef）。list_tabs 默认列出本会话的页面和未被占用的页面（active=true 是用户正在看的页面）；对未占用页面首次执行操作、导航或 evaluate 时由本会话占用。通过 qingzhou_execute_tool（单工具、calls 批次或 run_script 外层编排）执行操作，页面内 DOM 求值使用 evaluate。Create a session with a readable title using qingzhou_create_drive_session or qz session create --title TITLE, then pass that sessionId on every tool or script execution (CLI calls require --session; omitting it exits 2 and does not create a session). list_tools/get_tool can inspect the base catalog without a session. Page tools require tabRef (an optional tabAlias from open_tab, or the tabRef returned by open_tab or list_tabs). By default list_tabs lists this session's tabs and unclaimed tabs (active:true is the user's page); the first action, navigation, or evaluate on an unclaimed tab claims it for this session. Orchestrate with qingzhou_execute_tool (single tool, calls batch, or outer run_script) and use evaluate for in-page DOM execution.";
 
 export function mcpCatalogProfile({ clientName = "", profile = "" } = {}) {
   const explicit = String(profile || "").trim().toLowerCase();