@opentiny/next-sdk 0.4.1 → 0.4.2

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

@@ -6,11 +6,13 @@ import { buildA11yTree, type RefMap } from './a11y-tree'
 import { PageStateCache } from './page-state-cache'
 import { SimulatorMask } from './page-agent-mask/SimulatorMask'
 import { highlight, unhighlight, globalRemoveListener } from './page-agent-highlight'
+import { setupPageAgentToolEventBridge } from './page-agent-tool-event'
 
-import { DEFAULT_ERROR_SELECTORS, DEFAULT_DIALOG_SELECTORS, type PageAgentToolOptions } from './constants'
+import type { PageAgentToolOptions } from './constants'
 import { inputSchema, type PageAgentToolInput } from './schema'
-import type { ActionContext } from './context'
+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'
@@ -24,19 +26,12 @@ import { handleSearchTree } from './handlers/searchTree'
 export function registerPageAgentTool(options: PageAgentToolOptions = {}) {
   initializeBuiltinWebMCP()
 
-  // 默认启用元素高亮
-  if (typeof options.enableHighlight === 'undefined') {
-    options.enableHighlight = true
-  }
+  // 完整工具配置（顶层选项 enableHighlight + 统一无障碍配置 a11yConfig）：与默认配置合并后
+  // 得到运行期唯一生效的配置（存于 window.__webmcpcli_toolConfig），后续可通过
+  // setPageAgentToolConfig 在运行期继续修改（追加式合并/函数式过滤/整体替换）
+  setPageAgentToolConfig(options, { mode: 'replace' })
 
-  window.__webmcpcli_interactiveWhitelist = window.__webmcpcli_interactiveWhitelist || [] // 白名单元素列表，存在则识别为交互元素
-  window.__webmcpcli_interactiveBlacklist = window.__webmcpcli_interactiveBlacklist || [] // 黑名单，反之
-  window.__webmcpcli_exposedAttributes = window.__webmcpcli_exposedAttributes || options?.exposedAttributes || [] // 额外暴露的自定义属性白名单
-  window.__webmcpcli_beforeGetBrowserState = window.__webmcpcli_beforeGetBrowserState || null // 指定网站覆盖该函数，用于设置当前网站的黑白名单
-  // 校验错误选择器：默认覆盖 ARIA 标准 + 主流框架，网站可通过 window.__webmcpcli_errorSelectors 覆盖
-  window.__webmcpcli_errorSelectors = window.__webmcpcli_errorSelectors || DEFAULT_ERROR_SELECTORS
-  // 模态弹窗选择器：同上
-  window.__webmcpcli_dialogSelectors = window.__webmcpcli_dialogSelectors || DEFAULT_DIALOG_SELECTORS
+  window.__webmcpcli_beforeGetBrowserState = window.__webmcpcli_beforeGetBrowserState || null // 指定网站覆盖该函数，可在其中调用 setPageAgentToolConfig 动态调整当前页面的配置
 
   // 保留 PageController ，先关闭内置mask, 再手工绑定当前项目的mask类
   const pageController = new PageController({ enableMask: false })
@@ -55,10 +50,15 @@ export function registerPageAgentTool(options: PageAgentToolOptions = {}) {
 
   // ─── 辅助：构建错误响应 ───────────────────────────────────────────────────
   async function errContent(msg: string) {
-    await pageController.hideMask()
     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) {
@@ -76,20 +76,12 @@ export function registerPageAgentTool(options: PageAgentToolOptions = {}) {
     const url = window.location.href
     const title = document.title
 
-    // 获取用户自定义黑名单与白名单及额外暴露的属性
-    const blacklist = (window.__webmcpcli_interactiveBlacklist ?? []) as Element[]
-    const whitelist = (window.__webmcpcli_interactiveWhitelist ?? []) as Element[]
-    const exposedAttributes = (window.__webmcpcli_exposedAttributes ?? []) as string[]
-
-    // 生成语义化 ARIA YAML 树 + 刷新 refMap
-    const { yaml, refMap } = buildA11yTree(document.body, blacklist, whitelist, {
-      exposedAttributes,
-      errorSelectors: (window.__webmcpcli_errorSelectors ?? DEFAULT_ERROR_SELECTORS).join(', ')
-    })
+    // 生成语义化 ARIA YAML 树 + 刷新 refMap（统一读取运行期生效的配置，支持 setPageAgentToolConfig 动态修改）
+    const { yaml, refMap } = buildA11yTree(document.body, getPageAgentToolConfig().a11yConfig)
     currentRefMap = refMap
 
-    // 高亮交互元素，且增加全局移除高亮的监听
-    if (options?.enableHighlight) {
+    // 高亮交互元素，且增加全局移除高亮的监听（读取运行期生效的配置，支持 setPageAgentToolConfig 动态修改）
+    if (getPageAgentToolConfig().enableHighlight) {
       highlight(refMap)
       globalRemoveListener()
     }
@@ -97,8 +89,6 @@ export function registerPageAgentTool(options: PageAgentToolOptions = {}) {
     // 计算 Diff
     const diff = stateCache.update(url, yaml)
 
-    await pageController.hideMask()
-
     // 检测页面弹窗/遮罩层（确认框、提示框等），让 AI 优先处理
     const dialogAlert = detectPageDialog()
     // 检测表单校验错误，提醒 AI 优先修复
@@ -134,7 +124,68 @@ export function registerPageAgentTool(options: PageAgentToolOptions = {}) {
     },
     buildBrowserStateResponse,
     refreshOnStaleRef,
-    errContent
+    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 与原版完全一致）────────────────────────
@@ -144,32 +195,13 @@ export function registerPageAgentTool(options: PageAgentToolOptions = {}) {
     // @ts-ignore
     inputSchema: zodToJsonSchema(inputSchema) as any,
     async execute(args: PageAgentToolInput) {
-      await pageController.showMask()
       try {
-        switch (args.action) {
-          case 'browserState':
-            return await handleBrowserState(args, actionContext)
-          case 'click':
-            return await handleClick(args, actionContext)
-          case 'fill':
-            return await handleFill(args, actionContext)
-          case 'select':
-            return await handleSelect(args, actionContext)
-          case 'scroll':
-            return await handleScroll(args, actionContext)
-          case 'executeJavascript':
-            return await handleExecuteJavascript(args, actionContext)
-          case 'searchTree':
-            return await handleSearchTree(args, actionContext)
-          default:
-            await pageController.hideMask()
-            // @ts-ignore
-            return { content: [{ type: 'text', text: `未知操作: ${args.action}` }] }
-        }
+        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

@@ -49,3 +49,4 @@ export const inputSchema = z.object({
 })
 
 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
+}

package/page-tools/utils/dom.ts

@@ -1,4 +1,5 @@
-import { DEFAULT_DIALOG_SELECTORS, DEFAULT_ERROR_SELECTORS } from '../constants'
+import { extractSelectors } from '../a11y/config'
+import { getPageAgentToolConfig } from '../tool-config'
 
 // ─── 辅助：Shadow DOM 事件穿透 ───────────────────────────────────────────
 // 外部包 inputTextElement/selectOptionElement 派发的合成事件 composed:false，
@@ -69,7 +70,8 @@ export function detectPageDialog(): string {
   const seen = new Set<Element>()
   const dialogs: string[] = []
   // 仅匹配明确的模态弹窗选择器，避免宽泛子串匹配误报
-  const selectors = (window.__webmcpcli_dialogSelectors ?? DEFAULT_DIALOG_SELECTORS)
+  // 统一取 getPageAgentToolConfig().a11yConfig.dialogSelectors（已含默认值 + 用户配置）
+  const selectors = getPageAgentToolConfig().a11yConfig.dialogSelectors
 
   for (const selector of selectors) {
     try {
@@ -125,7 +127,8 @@ export function detectValidationErrors(): string {
   const seen = new Set<Element>()
   const errors: string[] = []
   // 校验错误选择器：ARIA 标准 + 主流 UI 框架（可配置）
-  const selectors = (window.__webmcpcli_errorSelectors ?? DEFAULT_ERROR_SELECTORS)
+  // 统一取 getPageAgentToolConfig().a11yConfig.states.error（已含默认值 + 用户配置）
+  const selectors = extractSelectors(getPageAgentToolConfig().a11yConfig.states.error)
 
   for (const selector of selectors) {
     try {

package/runtime.ts

@@ -1,13 +1,44 @@
 import { initializeBuiltinWebMCP } from './page-tools/initialize-builtin-WebMCP'
 import { registerPageAgentTool } from './page-tools/page-agent-tool'
+import { getPageAgentToolConfig, setPageAgentToolConfig } from './page-tools/tool-config'
+import { defineA11yConfig } from './page-tools/a11y/config'
+import {
+  consoleCloudPageAgentToolOptions,
+  isConsoleCloudHost,
+} from './page-tools/configs/console-cloud'
+
+/**
+ * runtime IIFE 仅挂载可调用 API，不自动 registerPageAgentTool。
+ * 调用方需自行传入 enableHighlight / a11yConfig 等选项后再注册，例如：
+ *   registerPageAgentTool({ enableHighlight: true, a11yConfig: { exposedAttributes: ['cf-uba'] } })
+ *   registerPageAgentTool(consoleCloudPageAgentToolOptions)
+ */
+const runtimeApi = {
+  initializeBuiltinWebMCP,
+  registerPageAgentTool,
+  getPageAgentToolConfig,
+  setPageAgentToolConfig,
+  defineA11yConfig,
+  consoleCloudPageAgentToolOptions,
+  isConsoleCloudHost,
+}
 
 if (typeof window !== 'undefined') {
-  ;(window as any).initializeBuiltinWebMCP = initializeBuiltinWebMCP
-  ;(window as any).registerPageAgentTool = registerPageAgentTool
+  Object.assign(window, runtimeApi)
 
-  // 作为 IIFE 注入到页面 MAIN world 时自动注册 page-agent-tool
-  // 避免 content script 需要额外触发（会被 CSP 内联 script 限制拦截）
-  registerPageAgentTool()
+  // 之前版本存在 WebMCP.registerPageAgentTool，当前先临时兼容，后续再移除
+  if (!(window as any).WebMCP) {
+    ;(window as any).WebMCP = {}
+  }
+  Object.assign((window as any).WebMCP, runtimeApi)
 }
 
-export { initializeBuiltinWebMCP, registerPageAgentTool }
+export {
+  initializeBuiltinWebMCP,
+  registerPageAgentTool,
+  getPageAgentToolConfig,
+  setPageAgentToolConfig,
+  defineA11yConfig,
+  consoleCloudPageAgentToolOptions,
+  isConsoleCloudHost,
+}