@opentiny/next-sdk 0.4.1 → 0.4.2

package/page-tools/a11y/vnode.ts

@@ -5,20 +5,52 @@
  */
 
 import { computeAccessibleName } from 'dom-accessibility-api'
-import { isFocusable, isTabbable } from 'tabbable'
-import type { VNode, RefMap, A11yTreeOptions } from './types'
-import { isHidden, inferRole, getStateTokens, collectDescendantText, getComposedChildren } from './utils'
+import { isTabbable } from 'tabbable'
+import type { VNode, RefMap, A11yTreeShapeOptions } from './types'
+import type { ResolvedA11yConfig } from './config'
+import { resolveA11yInfo } from './config'
+import {
+  isHidden,
+  isNonContentElement,
+  collectDescendantText,
+  collectTitleLabel,
+  getComposedChildren,
+  hasOwnPointerCursor,
+} from './utils'
+
+/**
+ * 语义上即为可操作控件的 ARIA 角色。
+ * jsdom 下部分带 tabindex 的自定义控件 isTabbable 可能为 false，
+ * 若不强制分配 ref，Static-Lift 会把它们误判为静态分支并吸收进父 name。
+ */
+const INTERACTIVE_ROLES = new Set([
+  'button',
+  'link',
+  'textbox',
+  'searchbox',
+  'combobox',
+  'listbox',
+  'checkbox',
+  'radio',
+  'switch',
+  'slider',
+  'spinbutton',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'tab',
+  'treeitem',
+])
 
 /**
  * 递归将 DOM 元素转换为 VNode 中间表示
  * @param el 当前 DOM 元素
  * @param refCounter 引用计数器（使用对象引用避免全局可变状态）
  * @param refMap ref 索引 → 元素映射
- * @param blacklistSet 用户自定义黑名单
- * @param whitelistSet 用户自定义白名单
- * @param exposedAttributes 需要暴露的自定义属性
- * @param errorSelectors 错误选择器
- * @param warningSelectors 警告选择器
+ * @param blacklistSet 已解析的黑名单元素集合
+ * @param whitelistSet 已解析的白名单元素集合
+ * @param config 已与默认值合并的统一无障碍配置
+ * @param hoverPointerSet 只在 :hover/:focus/:active 下声明 cursor:pointer 的元素集合（静止态读不到手势，靠样式表扫描兜底）
  */
 export function buildVNode(
   el: Element,
@@ -26,22 +58,26 @@ export function buildVNode(
   refMap: RefMap,
   blacklistSet: Set<Element>,
   whitelistSet: Set<Element>,
-  exposedAttributes?: string[],
-  errorSelectors?: string | string[],
-  warningSelectors?: string | string[],
-  /** 祖先节点是否已是可交互节点（已分配 ref）。为 true 时，纯 CSS 继承的 cursor=pointer 不再额外分配 ref */
-  ancestorIsInteractive = false,
+  config: ResolvedA11yConfig,
+  hoverPointerSet: Set<Element> = new Set(),
 ): VNode | null {
-  if (isHidden(el) || blacklistSet.has(el)) return null
+  // style/script 等非内容节点：不进树（避免 @font-face base64 等被当成 name）
+  if (isNonContentElement(el) || isHidden(el) || blacklistSet.has(el)) return null
+
+  const { role, tokens } = resolveA11yInfo(el, config)
 
-  const role = inferRole(el)
-  const tokens = getStateTokens(el, exposedAttributes, errorSelectors, warningSelectors)
-  
   let name = computeAccessibleName(el as HTMLElement)
   const isTrulyInteractive = isTabbable(el as HTMLElement)
+  // computed cursor 为 pointer（含继承）——仅用于「无文本时是否值得兜底收集名字」等宽松场景
   const isVisuallyClickable = tokens.includes('cursor=pointer')
-  // 包含白名单属性的节点也视为白名单节点（确保不被剪枝并分配 ref 操作索引）
-  const isWhitelisted = whitelistSet.has(el) || (exposedAttributes?.some(attr => el.hasAttribute(attr)) ?? false)
+  // 真正的"可点击边界元素"判定（用于是否分配 ref）：
+  // 1) 元素自身在静止态声明了 cursor:pointer（父级不是 pointer），排除 CSS 继承传染；
+  // 2) 或元素命中了 :hover/:focus/:active 下声明 cursor:pointer 的规则（hoverPointerSet）——
+  //    大量卡片只在 hover 时才显示手势，静止态 getComputedStyle 读到 auto，需靠样式表扫描兜底。
+  const hasClickableCursor = hasOwnPointerCursor(el) || hoverPointerSet.has(el)
+  // 白名单：仅由显式 whitelist 配置驱动，与 exposedAttributes（属性 token 输出）解耦，
+  // 避免把 data-qa-id 等追踪属性误当成「强制可交互」信号污染无障碍树。
+  const isWhitelisted = whitelistSet.has(el)
   // <label for="..."> 原生可点击：浏览器将点击转发到关联的表单控件（checkbox/radio 等）
   // Angular/React 自定义组件常隐藏原生 input，仅暴露 label 文本和自定义 skin
   const isLabelFor = el.tagName.toLowerCase() === 'label' && el.hasAttribute('for')
@@ -54,12 +90,27 @@ export function buildVNode(
     const isDropdown = tag === 'select' || role === 'combobox' || role === 'listbox'
     if (!isDropdown) {
       const isInteractiveTag = ['button', 'a', 'input', 'textarea', 'li', 'label'].includes(tag)
-      if (isTrulyInteractive || isWhitelisted || isVisuallyClickable || isInteractiveTag || role === 'listitem' || role === 'option') {
-        name = collectDescendantText(el)
+      if (isTrulyInteractive || isWhitelisted || isVisuallyClickable || hasClickableCursor || isInteractiveTag || role === 'listitem' || role === 'option') {
+        name = collectDescendantText(el, config)
       }
     }
   }
 
+  // 图标按钮常见：可点击容器本身无文本，title/aria 挂在子节点上（如控制台服务列表按钮）
+  if (!name.trim() && (isTrulyInteractive || isWhitelisted || isVisuallyClickable || hasClickableCursor || role === 'button')) {
+    name = collectTitleLabel(el)
+  }
+
+  // 结构性交互角色（tab/menuitem 等）的标签文字常落在可聚焦子节点内，
+  // collectDescendantText 会因“遇交互子节点即停”而拿不到 name；
+  // 此处用「跳过 style/script」的文本收集，禁止 textContent 把内联 CSS/base64 吸进来
+  if (
+    !name.trim() &&
+    ['tab', 'menuitem', 'option', 'treeitem', 'button'].includes(role)
+  ) {
+    name = collectVisiblePlainText(el)
+  }
+
   // 最终兜底：非交互元素（如错误提示 ti-error-msg、状态信息）的纯文本捕获。
   // 仅当元素没有有价值的子元素时触发，避免与子节点文本重复：
   // - 叶子 span（只有文本节点）→ 捕获文本作为 name
@@ -67,35 +118,43 @@ export function buildVNode(
   if (!name.trim()) {
     const hasElementChildren = getComposedChildren(el).length > 0
     if (!hasElementChildren) {
-      const text = collectDescendantText(el)
+      const text = collectDescendantText(el, config)
       if (text) {
         name = text
       }
     }
   }
 
-  // generic 无 name 时，即使有 cursor=pointer 也不分配 ref：
-  // cursor 通常是 CSS 继承传播的，这类 div 本身无法被有意义地操作。
-  // 此外，当祖先节点已是可交互节点时，子节点仅凭 isVisuallyClickable（CSS 继承）
-  // 不再额外分配 ref，避免父节点 cursor:pointer 传染给所有子孙导致高亮泛滥。
+  // cursor:pointer 是业界公认的"视觉可点击"通用信号（browser-use 等 DOM 提取器均以此为核心兜底判据）。
+  // 但 CSS 的 cursor 会向子孙继承，若直接以 computed cursor 判定，可点击容器（<a>、卡片等）会把
+  // ref "传染"给所有子孙，导致高亮泛滥。因此改用 hasClickableCursor（自身声明手势 + hover 态手势）来
+  // 定位真正的可点击边界元素：这样既能覆盖 <div class="card-wrapper" (click)=...> 这类无语义、无
+  // tabindex 的自定义可点击卡片（包括只在 hover 时显示手势的卡片），又能自然排除仅靠继承拿到 pointer
+  // 的内部子孙，无需再依赖祖先传播标记。
   //
-  // 例外：<a>/<button>/<input> 等语义性交互标签，无论祖先是否已有 ref，
-  // 始终强制分配 ref，因为它们在 HTML 语义上就是独立的操作单元。
+  // 例外：<a>/<button>/<input> 等语义性交互标签始终强制分配 ref，因为它们在 HTML 语义上
+  // 就是独立的操作单元，即使外层容器同样可点击也应各自暴露。
   const tagName = el.tagName.toLowerCase()
   const isSemanticInteractiveTag =
     (tagName === 'a' && el.hasAttribute('href')) ||
     (['button', 'input', 'select', 'textarea'].includes(tagName) && !el.hasAttribute('disabled'))
 
-  // 虽然有些元素有 tabindex="0" (isTrulyInteractive)，但如果它是 generic 且没有 cursor:pointer，
+  // 虽然有些元素有 tabindex="0" (isTrulyInteractive)，但如果它是 generic 且没有可点击手势，
   // 往往是开发者加的结构化 focus 容器（如 tp-card），而非真正的可交互按钮，我们在此过滤掉它们。
-  const isMeaningfullyInteractive = isTrulyInteractive && !(role === 'generic' && !isVisuallyClickable)
+  const isMeaningfullyInteractive = isTrulyInteractive && !(role === 'generic' && !hasClickableCursor)
+
+  const isDisabled = tokens.includes('disabled')
 
   const interactive =
-    isMeaningfullyInteractive ||
+    (!isDisabled && isMeaningfullyInteractive) ||
     isWhitelisted ||
     isLabelFor ||
     isSemanticInteractiveTag ||
-    (!ancestorIsInteractive && isVisuallyClickable && (role !== 'generic' || name !== ''))
+    (!isDisabled && INTERACTIVE_ROLES.has(role)) ||
+    // hasClickableCursor 已排除 CSS 继承（hasOwnPointerCursor）并覆盖 hover 态手势，
+    // 无需再要求 role≠generic 或 name≠''——否则无文本的图标按钮（tp-icon.common-icon 等）
+    // 虽是真正的可点击边界，仍会因 generic+空名被漏判。
+    (!isDisabled && hasClickableCursor)
 
   let ref: number | undefined
   if (interactive) {
@@ -112,16 +171,107 @@ export function buildVNode(
       refMap,
       blacklistSet,
       whitelistSet,
-      exposedAttributes,
-      errorSelectors,
-      warningSelectors,
-      // 将当前节点的交互性向下传递，子节点据此决定是否抑制 cursor=pointer
-      interactive || ancestorIsInteractive,
+      config,
+      hoverPointerSet,
     )
     if (childVNode) children.push(childVNode)
   }
 
-  return { role, name, tokens, ref, el: el as HTMLElement, children }
+  const vnode: VNode = { role, name, tokens, ref, el: el as HTMLElement, children }
+
+  // 有可交互子孙时：清空 AccName 内容汇总，仅保留自身声明名。
+  // 静态子树文案的上提（Static-Lift）改由 serializeVNode 负责，避免与交互文案混进父 name。
+  if (hasInteractiveDescendant(vnode)) {
+    vnode.name = getOwnDeclaredName(el as HTMLElement)
+  }
+
+  return vnode
+}
+
+/**
+ * 仅取元素自身声明的可访问名，不含内容汇总（name from contents）。
+ */
+function getOwnDeclaredName(el: HTMLElement): string {
+  if (el.hasAttribute('aria-label') || el.hasAttribute('aria-labelledby')) {
+    return computeAccessibleName(el).trim()
+  }
+  return ''
+}
+
+/** 子节点自身无 ref，且子树无可交互子孙 → 纯静态分支（可上提文案） */
+function isStaticBranch(vnode: VNode): boolean {
+  return vnode.ref === undefined && !hasInteractiveDescendant(vnode)
+}
+
+/**
+ * 收集元素可见纯文本，跳过 style/script 等非内容子树。
+ * 禁止使用 el.textContent：它会包含内联 @font-face base64，导致 token 爆炸。
+ */
+function collectVisiblePlainText(el: Element): string {
+  return collectDescendantText(el).replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * 收集纯静态分支的展示文案（保字用）。
+ * 优先 name，其次递归子节点，最后可见纯文本兜底（不含 style/script）。
+ */
+function getStaticDisplayText(vnode: VNode): string {
+  const childJoined =
+    vnode.children.length > 0
+      ? vnode.children
+          .map(getStaticDisplayText)
+          .filter(Boolean)
+          .join(' ')
+          .replace(/\s+/g, ' ')
+          .trim()
+      : ''
+  const plain = vnode.children.length === 0 ? collectVisiblePlainText(vnode.el) : ''
+  const named = vnode.name.trim()
+
+  const parts: string[] = []
+  if (named && !isNoiseAccessibleName(named)) parts.push(named)
+  if (childJoined && !isNoiseAccessibleName(childJoined)) {
+    const normNamed = named.replace(/\s+/g, ' ').trim()
+    const normChild = childJoined.replace(/\s+/g, ' ').trim()
+    // 声明名与子孙文案不同则合并保留，避免仅有 aria-label 时丢掉静态说明
+    if (!normNamed || (normChild !== normNamed && !normNamed.includes(normChild))) {
+      parts.push(childJoined)
+    }
+  }
+  if (parts.length === 0 && plain && !isNoiseAccessibleName(plain)) parts.push(plain)
+  return parts.join(' ').replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * 名称若像 CSS/字体资源噪声（常见于误吸收的 <style> 内容），视为无效，避免输出到 YAML。
+ */
+function isNoiseAccessibleName(name: string): boolean {
+  const n = name.trim()
+  if (!n) return false
+  if (/@font-face\b/i.test(n)) return true
+  if (/data:(?:font|application|image)\//i.test(n)) return true
+  if (/base64,[A-Za-z0-9+/=]{80,}/.test(n)) return true
+  return false
+}
+
+/**
+ * 静态子节点可否省略：仅当其文案已由父 outputName 完整承载（去重且不丢字）。
+ * - 父使用自身声明名：仅当子文案与声明名完全相同才可省略
+ * - 父使用上提拼接名：子文案作为片段已包含在父名中才可省略
+ */
+function canOmitStaticChild(
+  child: VNode,
+  parentOutputName: string,
+  parentUsesOwnDeclaredName: boolean,
+): boolean {
+  const text = getStaticDisplayText(child)
+  if (!text || !parentOutputName.trim()) return false
+  const parentNorm = parentOutputName.replace(/\s+/g, ' ').trim()
+  const textNorm = text.replace(/\s+/g, ' ').trim()
+  if (parentUsesOwnDeclaredName) {
+    return textNorm === parentNorm
+  }
+  return parentNorm.includes(textNorm)
 }
 
 /**
@@ -164,7 +314,7 @@ function findSingleRefDescendant(vnode: VNode): VNode | null {
  * - 去掉 generic/list/listitem 等纯布局噪音（无 name 时穿透）
  * - 保留有 name 的 listitem（有 name 时保留，兼顾内容理解场景）
  */
-export function shouldPassThrough(vnode: VNode, opts: Required<A11yTreeOptions>): boolean {
+export function shouldPassThrough(vnode: VNode, opts: A11yTreeShapeOptions): boolean {
   if (!opts.pruneUnnamed) return false
   // preserveRoles 中的角色强制保留
   if (opts.preserveRoles.includes(vnode.role)) return false
@@ -176,54 +326,114 @@ export function shouldPassThrough(vnode: VNode, opts: Required<A11yTreeOptions>)
   return true
 }
 
+/**
+ * 将节点 name 转义为 YAML 引号内文本；空名返回空串（调用方决定是否拼引号）。
+ */
+function formatNameAttr(name: string): string {
+  const safe = name.replace(/[\r\n]+/g, ' ').replace(/"/g, '\\"').trim()
+  return safe ? ` "${safe}"` : ''
+}
+
 /**
  * 将 VNode 序列化为 YAML 行数组
  * 穿透节点时，子节点在当前 depth 平铺输出（不增加缩进层级）
+ *
+ * 文本折叠规则（Static-Lift + Interactive-Keep，保字优先）：
+ * 1. 子树全静态 → 省略子节点，文字保留在父节点
+ * 2. 混合子树 → 静态文案上提到父 name（成功才省略静态子节点）；交互分支递归保留；
+ *    禁止把交互文案并入父 name；上提失败则静态子节点独立输出，绝不丢字
  */
 export function serializeVNode(
   vnode: VNode,
   depth: number,
-  opts: Required<A11yTreeOptions>,
+  opts: A11yTreeShapeOptions,
 ): string[] {
-  if (shouldPassThrough(vnode, opts)) {
-    // 透明穿透：跳过本节点，子节点保持当前 depth（层级不增加）
-    // 同时过滤掉整棵子树都无价値的空容器，避免输出无意义的嵌套
-    return vnode.children
-      .filter(c => hasValue(c))
-      .flatMap(c => serializeVNode(c, depth, opts))
-  }
-
+  const hasInteractive = hasInteractiveDescendant(vnode)
+  const forceKeepStructure = opts.preserveRoles.includes(vnode.role)
   const indent = '  '.repeat(depth)
   const refStr = vnode.ref !== undefined ? ` #${vnode.ref}` : ''
   const safeTokens = vnode.tokens.map(t => t.replace(/[\r\n]+/g, ' ').replace(/"/g, '\\"'))
   const tokenStr = safeTokens.length > 0 ? ` [${safeTokens.join(' ')}]` : ''
 
-  if (vnode.ref !== undefined) {
-    if (!hasInteractiveDescendant(vnode)) {
-      // 子树无任何 ref 节点 → 直接省略子节点
-      // 父节点的 name 已由 computeAccessibleName 汇总了子树文本，信息不会丢失
-      const safeName = vnode.name ? vnode.name.replace(/[\r\n]+/g, ' ').replace(/"/g, '\\"') : ''
-      const nameStr = safeName ? ` "${safeName}"` : ''
-      return [`${indent}- ${vnode.role}${refStr}${tokenStr}${nameStr}`]
+  // 规则 1：子树无可交互节点，且无需强制保留结构 → 折叠为一行（文字不丢）
+  if (!hasInteractive && !forceKeepStructure) {
+    if (shouldPassThrough(vnode, opts)) {
+      return vnode.children
+        .filter(c => hasValue(c))
+        .flatMap(c => serializeVNode(c, depth, opts))
     }
+    let displayName = vnode.name.trim()
+    if (!displayName && vnode.children.length > 0) {
+      displayName = collectVisiblePlainText(vnode.el)
+    }
+    if (isNoiseAccessibleName(displayName)) displayName = ''
+    return [`${indent}- ${vnode.role}${refStr}${tokenStr}${formatNameAttr(displayName)}`]
+  }
+
+  // preserveRoles 且无交互：保留结构，父级去掉 content name，子节点照常输出
+  if (!hasInteractive && forceKeepStructure) {
+    const outputName = getOwnDeclaredName(vnode.el)
+    const line = `${indent}- ${vnode.role}${refStr}${tokenStr}${formatNameAttr(outputName)}`
+    const childLines = vnode.children.flatMap(c => serializeVNode(c, depth + 1, opts))
+    return [line, ...childLines]
+  }
+
+  // ── 混合子树：Static-Lift + Interactive-Keep ──
+  const ownDeclaredName = getOwnDeclaredName(vnode.el)
+  const parentUsesOwnDeclaredName = ownDeclaredName !== ''
+  const staticChildren = vnode.children.filter(isStaticBranch)
+  const liftedStaticName = staticChildren
+    .map(getStaticDisplayText)
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+
+  // 父 name：声明名优先；否则上提静态子树文案（绝不吸收交互文案）
+  let outputName = parentUsesOwnDeclaredName ? ownDeclaredName : liftedStaticName
+  if (isNoiseAccessibleName(outputName)) outputName = ''
+  // vnode.name（声明名）若被污染同样丢弃
+  if (!parentUsesOwnDeclaredName && isNoiseAccessibleName(vnode.name)) {
+    outputName = liftedStaticName && !isNoiseAccessibleName(liftedStaticName) ? liftedStaticName : ''
+  }
+
+  const willEmitParent =
+    vnode.ref !== undefined ||
+    outputName !== '' ||
+    forceKeepStructure ||
+    !opts.pruneUnnamed
+
+  // 父节点不会输出时必须穿透，且不得省略静态子节点（保字）
+  if (!willEmitParent) {
+    return vnode.children
+      .filter(c => hasValue(c))
+      .flatMap(c => serializeVNode(c, depth, opts))
+  }
 
+  if (vnode.ref !== undefined) {
     // 子树中唯一一个 ref 节点且是无子 ref 的 generic 时，将其 name 提升到父节点，省略子节点输出。
-    // 场景：`listitem #22 [active]` 内部只有 `generic #23 "总览"`，
-    //       点击意义相同时，就展示为一行 `- listitem #22 [active] "总览"`。
     const singleChild = findSingleRefDescendant(vnode)
-    if (singleChild && singleChild.role === 'generic' && !hasInteractiveDescendant(singleChild)) {
-      const mergedName = (vnode.name.trim() || singleChild.name.trim())
-        .replace(/[\r\n]+/g, ' ')
-        .replace(/"/g, '\\"')
-      const nameStr = mergedName ? ` "${mergedName}"` : ''
-      return [`${indent}- ${vnode.role}${refStr}${tokenStr}${nameStr}`]
+    if (
+      singleChild &&
+      singleChild.role === 'generic' &&
+      !hasInteractiveDescendant(singleChild) &&
+      staticChildren.length === 0
+    ) {
+      const mergedName = outputName.trim() || singleChild.name.trim()
+      // 合并输出时使用子节点 ref，避免 refMap 中的 #N 在 YAML 里丢失
+      const mergedRefStr =
+        singleChild.ref !== undefined ? ` #${singleChild.ref}` : refStr
+      return [`${indent}- ${vnode.role}${mergedRefStr}${tokenStr}${formatNameAttr(mergedName)}`]
     }
   }
 
-  const safeName = vnode.name ? vnode.name.replace(/[\r\n]+/g, ' ').replace(/"/g, '\\"') : ''
-  const nameStr = safeName ? ` "${safeName}"` : ''
-  const line = `${indent}- ${vnode.role}${refStr}${tokenStr}${nameStr}`
+  // 仅省略「文案已由父 outputName 承载」的静态子节点；其余（含全部交互分支）按原序输出
+  const childrenToEmit = vnode.children.filter(c => {
+    if (!isStaticBranch(c)) return true
+    return !canOmitStaticChild(c, outputName, parentUsesOwnDeclaredName)
+  })
 
-  const childLines = vnode.children.flatMap(c => serializeVNode(c, depth + 1, opts))
+  const line = `${indent}- ${vnode.role}${refStr}${tokenStr}${formatNameAttr(outputName)}`
+  const childLines = childrenToEmit.flatMap(c => serializeVNode(c, depth + 1, opts))
   return [line, ...childLines]
 }

package/page-tools/a11y-tree.ts

@@ -7,6 +7,7 @@
 
 export * from './a11y/types'
 export * from './a11y/constants'
+export * from './a11y/config'
 export * from './a11y/utils'
 export * from './a11y/vnode'
 export * from './a11y/build'

package/page-tools/bridge.ts

@@ -613,14 +613,34 @@ export function registerPageTool(options: RegisterPageToolByHandlersOptions): ()
 // 供 content.ts 通过 window.__nextSdkRegisteredTools() 跨沙箱查询完整工具定义
 const _registeredTools = new Map<string, any>()
 
+/** 浏览器全局对象上可能挂载的 modelContext 接口 */
+interface ModelContextHost {
+  modelContext?: BridgeableModelContext
+}
+
+/** 可被 bridge 拦截的原生 modelContext 接口 */
+interface BridgeableModelContext {
+  registerTool?(config: unknown, options?: unknown): unknown
+  unregisterTool?(name: string): unknown
+  __isNextSdkBridgeSetup?: boolean
+}
+
 export function setupModelContextBridge() {
   if (typeof document === 'undefined') return
-  const doc = document as any
-  const nativeCtx = doc.modelContext
+  const doc = document as unknown as ModelContextHost
+  const nav = typeof navigator !== 'undefined' ? (navigator as unknown as ModelContextHost) : undefined
+
+  // 兼容 document.modelContext 与 navigator.modelContext（不同浏览器/polyfill 挂载位置不同）
+  const nativeCtx = doc.modelContext || nav?.modelContext
 
   // 如果不存在或者已经被拦截过，则不处理
   if (!nativeCtx || nativeCtx.__isNextSdkBridgeSetup) return
 
+  // 若 modelContext 仅存在于 navigator 上，同步挂载到 document 以保持向后兼容
+  if (!doc.modelContext && nav?.modelContext) {
+    doc.modelContext = nav.modelContext
+  }
+
   // 挂载全局查询函数，供 content script（隔离沙箱）访问
   // 注意：必须强制覆盖，不检查是否已存在。
   // init-webmcp.js 的 fallback polyfill 会提前注册一个基于内联 Map 的版本，

package/page-tools/configs/console-cloud.ts

@@ -0,0 +1,172 @@
+/**
+ * 云控制台（consoleCloud）专用 PageAgentToolOptions。
+ *
+ * 控制台基于 Tiny3（ti3-*）+ Angular，大量自定义组件缺少 role / aria-*：
+ * - Tab：`.ti3-tab-li` 无 role=tab，选中靠 `.ti3-tab-active`
+ * - 下拉：`.ti3-select-dominator-container` / `.selected-label` 无 combobox 语义
+ * - 图标按钮：仅有 `cf-uba` / 子节点 `title`，无 aria-label
+ * - 服务列表侧栏、区域选择等用 class 表达选中态
+ *
+ * 书写约定：优先 selector；仅当需要计算样式等复杂判断时再用 match。
+ * （roles 的 selector 为自身 matches；states 的 selector 为 closest）
+ */
+
+import { defineA11yConfig } from '../a11y/config'
+import type { PageAgentToolOptions } from '../tool-config'
+
+/** 云控制台 page-agent-tool 预设配置 */
+export const consoleCloudPageAgentToolOptions: PageAgentToolOptions = {
+  enableHighlight: false,
+  a11yConfig: defineA11yConfig({
+    roles: [
+      // Tiny3 Tabs：真正可聚焦/可点击的是内部 .ti3-tabs-text（tabindex=0）
+      { role: 'tablist', selector: 'ul.ti3-tabs' },
+      { role: 'tab', selector: '.ti3-tabs-text' },
+      { role: 'tabpanel', selector: ['ti-tab.ti3-tab-pane', '.ti3-tab-pane'] },
+
+      // 自定义下拉 / 区域选择触发器
+      {
+        role: 'combobox',
+        selector: [
+          '.ti3-select-dominator-container',
+          '.selected-label',
+          '.sort-select',
+          '.service-select',
+          '.region-select',
+          '[cf-uba="searchableRegion..open"]'
+        ]
+      },
+
+      // 图标型 / 无语义按钮
+      {
+        role: 'button',
+        selector: [
+          '.modules-service-list-menu-service-icon-container',
+          '.ti3-btn-only-icon-noborder',
+          '.ti3-select-dominator-dropdown-btn',
+          '.modules-right-sidebar-icon-item-wrapper',
+          '.modules-right-sidebar-hide-state-plugin',
+          '.components-service-list-container-service-list-input-service-close',
+          '.modules-searchable-region-region-panel-close',
+          '.modules-searchable-region-region-panel-search-btn',
+          '[cf-uba="rightSidebar..hideBtn"]',
+          // Tiny3 图标组件：帮助中心固定/全屏/关闭等（ti-icon / tp-icon 无原生 button 语义）
+          '.ti-global-help-panel-header-icon',
+          'ti-icon[name]',
+          'tp-icon[name]',
+          // 无 name 的箭头/操作图标（如 latest news 区 common-icon 展开箭头）
+          'tp-icon.common-icon',
+          'ti-icon.common-icon',
+          'ti-icon.ti3-icon-full-screen',
+          'ti-icon.ti3-icon-close',
+          'tp-icon.ti3-icon-full-screen',
+          'tp-icon.ti3-icon-close'
+        ]
+      },
+
+      // 服务列表侧栏分类 / 顶栏菜单项
+      {
+        role: 'menuitem',
+        selector: [
+          '.components-service-list-left-box-sidebar-visit-panel > li',
+          '.modules-menus-menu-item',
+          '.components-menu-wrapper-menu-text'
+        ]
+      },
+
+      // 区域筛选项 / 下拉选项
+      {
+        role: 'option',
+        selector: [
+          '.region-selector-item',
+          '.modules-searchable-region-project-item-region-item',
+          '.modules-searchable-region-region-panel-recent-region-item',
+          '.ti3-multiselect-box-cell'
+        ]
+      }
+    ],
+    states: {
+      // 选中态：挂在容器 class 上，用 selector + closest 即可命中内部交互节点
+      selected: [
+        { selector: 'li.ti3-tab-li.ti3-tab-active' },
+        // Tiny3 按钮组（计费模式等）：ti3-active 在 .ti3-btn-item-container 上，不在 button 上
+        { selector: '.ti3-btn-item-container.ti3-active' },
+        { selector: '.components-service-list-left-box-active' },
+        {
+          selector: [
+            '.modules-searchable-region-project-item-region-item-selected',
+            '.components-search-content-search-select-search-select-selected'
+          ]
+        }
+      ],
+      hasPopup: [
+        {
+          selector: [
+            '.ti3-select-dominator-container',
+            '.selected-label',
+            '.sort-select',
+            '.service-select',
+            '.region-select',
+            '[cf-uba="searchableRegion..open"]',
+            '[cf-uba="serviceList..open"]',
+            '[cf-uba="userinfo"]'
+          ]
+        }
+      ],
+      disabled: [{ selector: '.ti3-disabled' }],
+      // 展开态：需结合计算样式，选择器表达不了「可见」
+      expanded: [
+        {
+          match: (el) => {
+            try {
+              if (
+                !el.matches(
+                  '.modules-layout-module-sidebar-panel, .modules-searchable-region-region-panel, .ti3-dropdown-container'
+                )
+              ) {
+                return false
+              }
+              const style = window.getComputedStyle(el as HTMLElement)
+              return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0'
+            } catch {
+              return false
+            }
+          }
+        }
+      ]
+    },
+    // exposedAttributes 输出属性 token；带 name 的 ti-icon/tp-icon 可交互性由 roles/whitelist 中 ti-icon[name] 等规则判定。
+    exposedAttributes: ['cf-uba', 'data-qa-id', 'name'],
+    whitelist: [
+      '.modules-service-list-menu-service-icon-container',
+      '.ti3-tabs-text',
+      '[cf-uba="cloudShell"]',
+      '[cf-uba="messageBox"]',
+      '[cf-uba="helpFeedback"]',
+      '[cf-uba="globalMessage"]',
+      '[cf-uba="rightSidebar..hideBtn"]',
+      // 帮助中心等区域的 ti-icon / tp-icon 图标按钮
+      '.ti-global-help-panel-header-icon',
+      'ti-icon[name]',
+      'tp-icon[name]',
+      'tp-icon.common-icon',
+      'ti-icon.common-icon',
+      'ti-icon.ti3-icon-full-screen'
+    ],
+    blacklist: ['noscript', 'pan-gu', '#J_header'],
+    dialogSelectors: [
+      '[class*="ti3-modal"]',
+      '[class*="ti3-message-box"]',
+      '[class*="drawer"]',
+      '.modules-layout-module-sidebar-panel'
+    ]
+  })
+}
+
+/** 判断当前页面是否应使用云控制台（consoleCloud）预设 */
+export function isConsoleCloudHost(
+  hostname: string = typeof location !== 'undefined' ? location.hostname : ''
+): boolean {
+  // 要求 console 前为域名边界（开头或 `.`），避免误匹配 xconsole.huaweicloud.com
+  return /(^|\.)console\.huaweicloud\.com$/i.test(hostname)
+}