@opentiny/next-sdk 0.4.0 → 0.4.2

package/page-tools/page-agent-tool.ts

@@ -1,29 +1,46 @@
 import { initializeBuiltinWebMCP } from './initialize-builtin-WebMCP'
-import { z } from 'zod'
 import { zodToJsonSchema } from 'zod-to-json-schema'
 import pageAgentPrompt from './page-agent-prompt.md?raw'
-import { PageController, clickElement, inputTextElement, selectOptionElement } from '@page-agent/page-controller'
-import { buildA11yTree, searchA11yTree, type RefMap } from './a11y-tree'
+import { PageController } from '@page-agent/page-controller'
+import { buildA11yTree, type RefMap } from './a11y-tree'
 import { PageStateCache } from './page-state-cache'
-
-declare global {
-  interface Window {
-    __webmcpcli_interactiveWhitelist?: Element[]
-    __webmcpcli_interactiveBlacklist?: Element[]
-    __webmcpcli_beforeGetBrowserState?: (() => void) | null
-  }
-}
+import { SimulatorMask } from './page-agent-mask/SimulatorMask'
+import { highlight, unhighlight, globalRemoveListener } from './page-agent-highlight'
+import { setupPageAgentToolEventBridge } from './page-agent-tool-event'
+
+import type { PageAgentToolOptions } from './constants'
+import { inputSchema, type PageAgentToolInput } from './schema'
+import { createActionErrorResult, type ActionContext } from './context'
+import { detectPageDialog, detectValidationErrors } from './utils/dom'
+import { getPageAgentToolConfig, setPageAgentToolConfig } from './tool-config'
+
+import { handleBrowserState } from './handlers/browserState'
+import { handleClick } from './handlers/click'
+import { handleFill } from './handlers/fill'
+import { handleSelect } from './handlers/select'
+import { handleScroll } from './handlers/scroll'
+import { handleExecuteJavascript } from './handlers/executeJavascript'
+import { handleSearchTree } from './handlers/searchTree'
 
 /** 在浏览器页面中注册 page-agent-tool, 用于页面的内容获取和操作，页面的动效 */
-export function registerPageAgentTool() {
+export function registerPageAgentTool(options: PageAgentToolOptions = {}) {
   initializeBuiltinWebMCP()
 
-  window.__webmcpcli_interactiveWhitelist = [] // 白名单元素列表，存在则识别为交互元素
-  window.__webmcpcli_interactiveBlacklist = [] // 黑名单，反之
-  window.__webmcpcli_beforeGetBrowserState = null // 指定网站覆盖该函数，用于设置当前网站的黑白名单
+  // 完整工具配置（顶层选项 enableHighlight + 统一无障碍配置 a11yConfig）：与默认配置合并后
+  // 得到运行期唯一生效的配置（存于 window.__webmcpcli_toolConfig），后续可通过
+  // setPageAgentToolConfig 在运行期继续修改（追加式合并/函数式过滤/整体替换）
+  setPageAgentToolConfig(options, { mode: 'replace' })
 
-  // 保留 PageController 仅用于 showMask/hideMask（UX 遮罩层）
-  const pageController = new PageController({ enableMask: true })
+  window.__webmcpcli_beforeGetBrowserState = window.__webmcpcli_beforeGetBrowserState || null // 指定网站覆盖该函数，可在其中调用 setPageAgentToolConfig 动态调整当前页面的配置
+
+  // 保留 PageController ，先关闭内置mask, 再手工绑定当前项目的mask类
+  const pageController = new PageController({ enableMask: false })
+
+  // @ts-ignore
+  pageController.maskReady = (async () => {
+    // @ts-ignore
+    pageController.mask = new SimulatorMask()
+  })()
 
   // ─── 状态 Diff 缓存
   const stateCache = new PageStateCache()
@@ -31,60 +48,51 @@ export function registerPageAgentTool() {
   // 当前 ref 索引 → HTMLElement 映射（每次 buildA11yTree 后更新）
   let currentRefMap: RefMap = new Map()
 
-  // ─── inputSchema 与原版完全一致（对外 API 不变）──────────────────────────
-  const inputSchema = z.object({
-    action: z.enum(['browserState', 'click', 'fill', 'select', 'scroll', 'executeJavascript', 'searchTree'] as const)
-      .describe(`执行的动作名称, 每一次执行 'click', 'fill', 'select'动作之前，**必须**要先调用 'browserState' 去获取页面的最新状态。 
-        browserState: '查询整个页面的浏览器状态;返回页面的标题、URL、YAML格式的语义化页面树',
-        click: '根据元素索引点击;',
-        fill: '根据元素索引填写文本;'; 
-        select: '根据元素索引选择下拉框选项;'; 
-        scroll: '滚动页面的动作，可以指定水平滚动还是上下滚动; 不带元素索引时：滚动整个文档。带元素索引时：滚动该索引处的容器（或其最近的可滚动祖先元素）'
-        executeJavascript: '执行javascript代码'
-        searchTree: '按关键词搜索无障碍树，返回带行号的匹配节点及上下文，无需获取全量树。适合快速定位特定元素（如所有按钮、特定名称的链接等），显著减少上下文消耗。必须提供 query 参数。'
-    `),
-    index: z.number().min(0).optional().describe('执行动作 of the element index, 动作为 click,fill,select时，必须提供元素索引'),
-    text: z.string().optional().describe('执行动作的文本内容, 动作为 fill,select 时，必须提供文本内容'),
-    down: z.boolean().optional().describe('执行上下滚动时，必须提供down参数'),
-    right: z.boolean().optional().describe('执行水平滚动方向, 必须提供right参数'),
-    numPages: z
-      .number()
-      .optional()
-      .describe('执行动作的滚动页数, 动作为 scroll时，可以提供滚动页数，建议每次滚动0.1页，该值不要大于5.'),
-    pixels: z.number().int().min(0).optional().describe('执行动作的滚动像素数，动作为 scroll时，可以提供滚动像素数'),
-    script: z.string().optional().describe('执行的javascript代码，动作为 executeJavascript时，必须提供script参数'),
-    query: z.string().optional().describe('搜索关键词，动作为 searchTree 时必须提供。支持按 role（如 button、link）、节点名称、状态（如 checked）或 ref 索引（如 #3）搜索'),
-    contextLines: z.number().int().min(0).max(10).default(2).describe('searchTree 时每个命中行前后保留的上下文行数，默认 2'),
-    maxMatches: z.number().int().min(1).max(50).default(20).describe('searchTree 时最大返回分组数，默认 20'),
-    responseMode: z.enum(['full', 'diff', 'both'] as const)
-      .optional()
-      .default('diff')
-      .describe('返回浏览器状态的模式。full: 仅返回当前全量 A11y 树；diff: 仅返回与上一次状态的增量差异；both: 同时返回全量 A11y 树与增量差异。默认值为 diff。')
-  })
-
   // ─── 辅助：构建错误响应 ───────────────────────────────────────────────────
   async function errContent(msg: string) {
-    await pageController.hideMask()
-    return { content: [{ type: 'text', text: msg }] }
+    return { content: [{ type: 'text' as const, text: msg }] }
+  }
+
+  async function actionError(msg: string) {
+    const result = await createActionErrorResult(msg, buildBrowserStateResponse)
+    options.removeMaskAfterToolCall && (await pageController.hideMask())
+    return result
+  }
+
+  // AI 使用过期 ref 时，自动重建 A11y 树并返回全量状态，
+  // 避免 AI 额外往返调用 browserState，减少操作轮次
+  async function refreshOnStaleRef(action: string, index: number) {
+    const refreshResult = await buildBrowserStateResponse('full')
+    const warning = `⚠️ ${action}失败: ref 索引 ${index} 已失效（页面可能已刷新），已自动重新加载页面状态，请使用新的 ref 索引重试。\n`
+    return {
+      content: [{ type: 'text' as const, text: warning + refreshResult.content[0].text }]
+    }
   }
 
   // ─── 核心：构建 browserState 响应（全量 or 增量 Diff）────────────────────
-  async function buildBrowserStateResponse(responseMode: 'full' | 'diff' | 'both' = 'diff'): Promise<{ content: Array<{ type: string; text: string }> }> {
+  async function buildBrowserStateResponse(
+    responseMode: 'full' | 'diff' | 'both' = 'diff'
+  ): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
     const url = window.location.href
     const title = document.title
 
-    // 获取用户自定义黑名单与白名单
-    const blacklist = (window.__webmcpcli_interactiveBlacklist ?? []) as Element[]
-    const whitelist = (window.__webmcpcli_interactiveWhitelist ?? []) as Element[]
-
-    // 生成语义化 ARIA YAML 树 + 刷新 refMap
-    const { yaml, refMap } = buildA11yTree(document.body, blacklist, whitelist)
+    // 生成语义化 ARIA YAML 树 + 刷新 refMap（统一读取运行期生效的配置，支持 setPageAgentToolConfig 动态修改）
+    const { yaml, refMap } = buildA11yTree(document.body, getPageAgentToolConfig().a11yConfig)
     currentRefMap = refMap
 
+    // 高亮交互元素，且增加全局移除高亮的监听（读取运行期生效的配置，支持 setPageAgentToolConfig 动态修改）
+    if (getPageAgentToolConfig().enableHighlight) {
+      highlight(refMap)
+      globalRemoveListener()
+    }
+
     // 计算 Diff
     const diff = stateCache.update(url, yaml)
 
-    await pageController.hideMask()
+    // 检测页面弹窗/遮罩层（确认框、提示框等），让 AI 优先处理
+    const dialogAlert = detectPageDialog()
+    // 检测表单校验错误，提醒 AI 优先修复
+    const validationErrors = detectValidationErrors()
 
     // 根据 responseMode 组装 content
     let displayContent = ''
@@ -102,122 +110,98 @@ export function registerPageAgentTool() {
       title,
       content: displayContent
     }
-    const text = `浏览器状态: ${JSON.stringify(stateObj)}`
+    const text = `浏览器状态: ${JSON.stringify(stateObj)}${dialogAlert}${validationErrors}`
     return { content: [{ type: 'text', text }] }
   }
 
+  // 组装上下文传递给 handlers
+  const actionContext: ActionContext = {
+    pageController,
+    stateCache,
+    getRefMap: () => currentRefMap,
+    setRefMap: (map: RefMap) => {
+      currentRefMap = map
+    },
+    buildBrowserStateResponse,
+    refreshOnStaleRef,
+    errContent,
+    actionError
+  }
+
+  async function executePageAgentTool(args: PageAgentToolInput) {
+    try {
+      let ret: any
+
+      switch (args.action) {
+        case 'browserState':
+          ret = await handleBrowserState(args, actionContext)
+          break
+        case 'click':
+          await pageController.showMask()
+          pageController.mask.borderElement(currentRefMap.get(args.index))
+          ret = await handleClick(args, actionContext)
+          pageController.mask.removeBorderElement()
+          options.removeMaskAfterToolCall && (await pageController.hideMask())
+          break
+        case 'fill':
+          await pageController.showMask()
+          pageController.mask.borderElement(currentRefMap.get(args.index))
+          ret = await handleFill(args, actionContext)
+          pageController.mask.removeBorderElement()
+          options.removeMaskAfterToolCall && (await pageController.hideMask())
+          break
+        case 'select':
+          await pageController.showMask()
+          pageController.mask.borderElement(currentRefMap.get(args.index))
+          ret = await handleSelect(args, actionContext)
+          pageController.mask.removeBorderElement()
+          options.removeMaskAfterToolCall && (await pageController.hideMask())
+          break
+        case 'scroll':
+          await pageController.showMask()
+          ret = await handleScroll(args, actionContext)
+          options.removeMaskAfterToolCall && (await pageController.hideMask())
+          break
+        case 'executeJavascript':
+          ret = await handleExecuteJavascript(args, actionContext)
+          break
+        case 'searchTree':
+          ret = await handleSearchTree(args, actionContext)
+          break
+        default:
+          ret = { content: [{ type: 'text' as const, text: `未知操作: ${args.action}` }] }
+      }
+      return ret
+    } catch (error) {
+      const actionNames = {
+        click: '点击',
+        fill: '填写',
+        select: '选择'
+      } as const
+      if (args.action in actionNames) {
+        return actionError(
+          `${actionNames[args.action as keyof typeof actionNames]}执行异常: ${error instanceof Error ? error.message : String(error)}`
+        )
+      }
+      options.removeMaskAfterToolCall && (await pageController.hideMask())
+      throw error
+    }
+  }
+
   // ─── 工具注册（名称与 inputSchema 与原版完全一致）────────────────────────
   ;(document as any).modelContext.registerTool({
     name: 'page-agent-tool',
     description: pageAgentPrompt,
     // @ts-ignore
     inputSchema: zodToJsonSchema(inputSchema) as any,
-    async execute(args: any) {
-      await pageController.showMask()
-      const mode = args.responseMode ?? 'diff'
+    async execute(args: PageAgentToolInput) {
       try {
-        // ── browserState：生成语义化 YAML + Diff ──────────────────────────
-        if (args.action === 'browserState') {
-          if (window.__webmcpcli_beforeGetBrowserState) {
-            window.__webmcpcli_beforeGetBrowserState()
-          }
-          return buildBrowserStateResponse(mode)
-
-        // ── click：用底层 clickElement(el) 操作，操作后自动返回 diff ───────
-        } else if (args.action === 'click') {
-          if (args.index === undefined) return errContent('点击结果: 缺少元素索引')
-          const el = currentRefMap.get(args.index)
-          if (!el) return errContent(`点击结果: 无效的 ref 索引 ${args.index}，请先调用 browserState 刷新页面状态`)
-          await clickElement(el)
-          // 操作成功后自动返回 diff/both/full
-          return buildBrowserStateResponse(mode)
-
-        // ── fill：输入文本，操作后自动返回 diff ───────────────────────────
-        } else if (args.action === 'fill') {
-          if (args.index === undefined || !args.text) return errContent('填写结果: 缺少元素索引或文本内容')
-          const el = currentRefMap.get(args.index)
-          if (!el) return errContent(`填写结果: 无效的 ref 索引 ${args.index}，请先调用 browserState 刷新页面状态`)
-          
-          let targetEl = el
-          if (!(targetEl instanceof HTMLInputElement) && !(targetEl instanceof HTMLTextAreaElement)) {
-            const innerInput = el.querySelector('input, textarea')
-            if (innerInput) {
-              targetEl = innerInput as HTMLElement
-            }
-          }
-
-          if (targetEl instanceof HTMLInputElement && targetEl.readOnly) {
-            targetEl.value = args.text
-            targetEl.dispatchEvent(new Event('input', { bubbles: true }))
-            targetEl.dispatchEvent(new Event('change', { bubbles: true }))
-            targetEl.dispatchEvent(new Event('blur', { bubbles: true }))
-          } else {
-            await inputTextElement(targetEl, args.text)
-          }
-          return buildBrowserStateResponse(mode)
-
-        // ── select：选择下拉框，操作后自动返回 diff ───────────────────────
-        } else if (args.action === 'select') {
-          if (args.index === undefined || !args.text) return errContent('选择结果: 缺少元素索引或文本内容')
-          const el = currentRefMap.get(args.index) as HTMLSelectElement
-          if (!el) return errContent(`选择结果: 无效的 ref 索引 ${args.index}，请先调用 browserState 刷新页面状态`)
-          await selectOptionElement(el, args.text)
-          return buildBrowserStateResponse(mode)
-
-        // ── scroll：滚动页面，操作后自动返回 diff ─────────────────────────
-        } else if (args.action === 'scroll') {
-          if (!args.down && !args.right) return errContent('滚动结果: 缺少滚动方向参数')
-
-          // 确定滚动目标（有 index 时滚动该元素容器，否则滚动整个文档）
-          const scrollTarget = args.index !== undefined
-            ? (currentRefMap.get(args.index) ?? window)
-            : window
-
-          if (args.right) {
-            const pixels = args.pixels ?? 300
-            scrollTarget.scrollBy({ left: args.right ? pixels : -pixels, behavior: 'smooth' })
-          } else {
-            const pixels = args.pixels ?? Math.round((args.numPages ?? 1) * window.innerHeight)
-            scrollTarget.scrollBy({ top: args.down ? pixels : -pixels, behavior: 'smooth' })
-          }
-
-          // 等待滚动动画完成后再采集状态
-          await new Promise(r => setTimeout(r, 400))
-          return buildBrowserStateResponse(mode)
-        // ── executeJavascript：执行任意 JS ────────────────────────────────
-        } else if (args.action === 'executeJavascript') {
-          if (!args.script) return errContent('脚本执行异常: 缺少javascript代码')
-          // eslint-disable-next-line no-new-func
-          const result = await new Function(`return (async () => { ${args.script} })()`)()
-          await pageController.hideMask()
-          return {
-            content: [{ type: 'text', text: `脚本执行结果: ${JSON.stringify(result)}` }]
-          }
-
-        // ── searchTree：关键词搜索无障碍树，返回带行号的精准结果 ──────────
-        } else if (args.action === 'searchTree') {
-          if (!args.query) return errContent('搜索失败: 缺少 query 参数')
-          const blacklist = (window.__webmcpcli_interactiveBlacklist ?? []) as Element[]
-          const whitelist = (window.__webmcpcli_interactiveWhitelist ?? []) as Element[]
-          const { text } = searchA11yTree(
-            args.query,
-            document.body,
-            blacklist,
-            whitelist,
-            {
-              contextLines: args.contextLines,
-              maxMatches: args.maxMatches,
-            },
-          )
-          await pageController.hideMask()
-          return {
-            content: [{ type: 'text', text }]
-          }
-        }
+        return executePageAgentTool(args)
       } catch (error) {
-        await pageController.hideMask()
-        return { content: [{ type: 'text', text: `异常: ${String(error)}` }] }
+        return { content: [{ type: 'text' as const, text: `异常: ${String(error)}` }] }
       }
     }
   })
+
+  setupPageAgentToolEventBridge(executePageAgentTool, pageController)
 }

package/page-tools/schema.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod'
+
+export const inputSchema = z.object({
+  action: z.enum(['browserState', 'click', 'fill', 'select', 'scroll', 'executeJavascript', 'searchTree'] as const)
+    .describe(`执行的动作名称, 每一次执行 'click', 'fill', 'select'动作之前，**必须**要先调用 'browserState' 去获取页面的最新状态。 
+      browserState: '查询整个页面的浏览器状态;返回页面的标题、URL、YAML格式的语义化页面树',
+      click: '根据元素索引点击;',
+      fill: '根据元素索引填写文本;'; 
+      select: '根据元素索引选择下拉框选项;'; 
+      scroll: '滚动页面的动作，可以指定水平滚动还是上下滚动; 不带元素索引时：滚动整个文档。带元素索引时：滚动该索引处的容器（或其最近的可滚动祖先元素）'
+      executeJavascript: '执行javascript代码'
+      searchTree: '按关键词搜索无障碍树，返回带行号的匹配节点及上下文，无需获取全量树。适合快速定位特定元素（如所有按钮、特定名称的链接等），显著减少上下文消耗。必须提供 query 参数。'
+  `),
+  index: z
+    .number()
+    .min(0)
+    .optional()
+    .describe('执行动作 of the element index, 动作为 click,fill,select时，必须提供元素索引'),
+  text: z.string().optional().describe('执行动作的文本内容, 动作为 fill,select 时，必须提供文本内容'),
+  down: z.boolean().optional().describe('执行上下滚动时，必须提供down参数'),
+  right: z.boolean().optional().describe('执行水平滚动方向, 必须提供right参数'),
+  numPages: z
+    .number()
+    .optional()
+    .describe('执行动作的滚动页数, 动作为 scroll时，可以提供滚动页数，建议每次滚动0.1页，该值不要大于5.'),
+  pixels: z.number().int().min(0).optional().describe('执行动作的滚动像素数，动作为 scroll时，可以提供滚动像素数'),
+  script: z.string().optional().describe('执行的javascript代码，动作为 executeJavascript时，必须提供script参数'),
+  query: z
+    .string()
+    .optional()
+    .describe(
+      '搜索关键词，动作为 searchTree 时必须提供。支持按 role（如 button、link）、节点名称、状态（如 checked）或 ref 索引（如 #3）搜索'
+    ),
+  contextLines: z
+    .number()
+    .int()
+    .min(0)
+    .max(10)
+    .default(2)
+    .describe('searchTree 时每个命中行前后保留的上下文行数，默认 2'),
+  maxMatches: z.number().int().min(1).max(50).default(20).describe('searchTree 时最大返回分组数，默认 20'),
+  responseMode: z
+    .enum(['full', 'diff', 'both'] as const)
+    .optional()
+    .default('diff')
+    .describe(
+      '返回浏览器状态的模式。full: 仅返回当前全量 A11y 树；diff: 仅返回与上一次状态的增量差异；both: 同时返回全量 A11y 树与增量差异。默认值为 diff。'
+    )
+})
+
+export type PageAgentToolInput = z.infer<typeof inputSchema>
+export type PageAgentToolRawInput = z.input<typeof inputSchema>

package/page-tools/tool-config.ts

@@ -0,0 +1,100 @@
+/**
+ * tool-config.ts
+ *
+ * registerPageAgentTool 的完整运行期配置：顶层选项（enableHighlight 等）+ 统一无障碍配置（a11yConfig）。
+ * 两者合并到同一个配置对象里，提供唯一一套运行期读写 API（getPageAgentToolConfig/setPageAgentToolConfig）：
+ * 注册时初始化一次，之后可随时读取/修改，无需分别记住两套 get/set 函数。
+ */
+
+import type { A11yConfig, ResolvedA11yConfig } from './a11y/config'
+import { DEFAULT_A11Y_CONFIG, mergeA11yConfig, mergeA11yConfigs } from './a11y/config'
+
+export interface PageAgentToolConfig {
+  /** 是否启用元素高亮 */
+  enableHighlight: boolean
+  /** 是否在工具调用后移除遮罩， 默认值为 true 移除 */
+  removeMaskAfterToolCall?: boolean
+  /**
+   * 统一无障碍配置：按角色（roles）、状态（states：selected/disabled/error/warning 等）自定义规则，
+   * 以及白名单/黑名单/自定义暴露属性/弹窗选择器。已与默认配置合并（数组类字段是拼接结果）。
+   */
+  a11yConfig: ResolvedA11yConfig
+}
+
+/**
+ * 用于初始化（registerPageAgentTool 的入参）或运行期 setPageAgentToolConfig 的补丁对象：
+ * enableHighlight 为覆盖式更新；a11yConfig 为拼接式合并（数组类字段追加，不丢已有规则，语义见 a11y/config.ts）。
+ */
+export interface PageAgentToolConfigPatch {
+  /** 是否启用元素高亮 */
+  enableHighlight?: boolean
+  /** 是否在工具调用后移除遮罩， 默认值为 true 移除 */
+  removeMaskAfterToolCall?: boolean
+  /** 是否在工具调用后移除遮罩 */
+  /** 统一无障碍配置，会与当前生效的 a11yConfig 按数组拼接合并 */
+  a11yConfig?: A11yConfig
+}
+
+/** registerPageAgentTool(options) 的入参类型，与运行期补丁 {@link PageAgentToolConfigPatch} 完全一致 */
+export type PageAgentToolOptions = PageAgentToolConfigPatch
+
+/** 默认生效的完整工具配置 */
+export const DEFAULT_PAGE_AGENT_TOOL_CONFIG: PageAgentToolConfig = {
+  enableHighlight: false,
+  removeMaskAfterToolCall: true,
+  a11yConfig: DEFAULT_A11Y_CONFIG
+}
+
+declare global {
+  interface Window {
+    /** 运行期唯一生效的 page-agent-tool 完整配置（已与默认值合并），可通过 getPageAgentToolConfig/setPageAgentToolConfig 读写 */
+    __webmcpcli_toolConfig?: PageAgentToolConfig
+  }
+}
+
+/** 读取当前生效的完整工具配置（已与默认值合并）。未初始化时返回默认配置 */
+export function getPageAgentToolConfig(): PageAgentToolConfig {
+  if (typeof window !== 'undefined' && window.__webmcpcli_toolConfig) {
+    return window.__webmcpcli_toolConfig
+  }
+  return {
+    enableHighlight: DEFAULT_PAGE_AGENT_TOOL_CONFIG.enableHighlight,
+    removeMaskAfterToolCall: DEFAULT_PAGE_AGENT_TOOL_CONFIG.removeMaskAfterToolCall,
+    a11yConfig: mergeA11yConfig()
+  }
+}
+
+function resolvePatch(patch: PageAgentToolConfigPatch, base: PageAgentToolConfig): PageAgentToolConfig {
+  return {
+    enableHighlight: patch.enableHighlight ?? base.enableHighlight,
+    removeMaskAfterToolCall: patch.removeMaskAfterToolCall ?? base.removeMaskAfterToolCall,
+    a11yConfig: mergeA11yConfigs(base.a11yConfig, patch.a11yConfig ?? {})
+  }
+}
+
+/**
+ * 更新当前生效配置。
+ * - patch 为对象时：enableHighlight 覆盖式更新；a11yConfig 与当前配置按数组拼接合并（不丢已有规则）
+ * - patch 为函数时：入参为当前生效配置，返回值直接与默认配置合并（而不是再与 current 相加）。
+ *   这样函数体内可以对 current.a11yConfig 做任意过滤/裁剪（如按条件"移除"某条旧规则），
+ *   返回值即为最终生效的配置，不会因为再与 current 相加而让被过滤掉的旧规则"复活"
+ * - options.mode = 'replace' 时（仅影响对象类型的 patch）：不与"当前生效配置"合并，而是与默认配置重新合并
+ * 返回合并后的最新完整配置，并写回运行期存储供 buildBrowserStateResponse/buildA11yTree 等读取。
+ */
+export function setPageAgentToolConfig(
+  patch: PageAgentToolConfigPatch | ((current: PageAgentToolConfig) => PageAgentToolConfigPatch),
+  options?: { mode?: 'merge' | 'replace' }
+): PageAgentToolConfig {
+  const mode = options?.mode ?? 'merge'
+  const current = getPageAgentToolConfig()
+
+  const next =
+    typeof patch === 'function'
+      ? resolvePatch(patch(current), DEFAULT_PAGE_AGENT_TOOL_CONFIG)
+      : resolvePatch(patch, mode === 'replace' ? DEFAULT_PAGE_AGENT_TOOL_CONFIG : current)
+
+  if (typeof window !== 'undefined') {
+    window.__webmcpcli_toolConfig = next
+  }
+  return next
+}