@opentiny/next-sdk 0.4.0 → 0.4.2

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)
+}

package/page-tools/constants.ts

@@ -0,0 +1,12 @@
+/** 校验错误默认选择器：ARIA 标准 + 主流 UI 框架（唯一来源为 a11y/constants.ts，此处重新导出保持旧路径可用） */
+export { DEFAULT_ERROR_SELECTORS, DEFAULT_DIALOG_SELECTORS } from './a11y/constants'
+
+/** registerPageAgentTool(options) 的入参类型，定义见 tool-config.ts（与运行期 setPageAgentToolConfig 的补丁类型一致） */
+export type { PageAgentToolOptions } from './tool-config'
+
+declare global {
+  interface Window {
+    /** 指定网站可覆盖该函数，在每次 getBrowserState 之前调用，常用于配合 setPageAgentToolConfig 动态调整当前页面的配置 */
+    __webmcpcli_beforeGetBrowserState?: (() => void) | null
+  }
+}

package/page-tools/context.ts

@@ -0,0 +1,50 @@
+import type { PageController } from '@page-agent/page-controller'
+import type { PageStateCache } from './page-state-cache'
+import type { RefMap } from './a11y-tree'
+
+export type PageAgentToolContentResult = {
+  content: Array<{ type: 'text'; text: string }>
+}
+
+export type PageAgentToolErrorResult = PageAgentToolContentResult & {
+  isError: true
+  error: string
+}
+
+export async function createActionErrorResult(
+  message: string,
+  buildBrowserStateResponse: ActionContext['buildBrowserStateResponse']
+): Promise<PageAgentToolErrorResult> {
+  try {
+    const browserState = await buildBrowserStateResponse('full')
+    return {
+      isError: true,
+      error: message,
+      content: [{ type: 'text', text: `${message}\n\n${browserState.content[0].text}` }]
+    }
+  } catch (error) {
+    return {
+      isError: true,
+      error: message,
+      content: [
+        {
+          type: 'text',
+          text: `${message}\n\n获取最新浏览器状态失败: ${error instanceof Error ? error.message : String(error)}`
+        }
+      ]
+    }
+  }
+}
+
+export interface ActionContext {
+  pageController: PageController
+  stateCache: PageStateCache
+  getRefMap: () => RefMap
+  setRefMap: (map: RefMap) => void
+  buildBrowserStateResponse: (
+    mode?: 'full' | 'diff' | 'both'
+  ) => Promise<{ content: Array<{ type: 'text'; text: string }> }>
+  refreshOnStaleRef: (action: string, index: number) => Promise<{ content: Array<{ type: 'text'; text: string }> }>
+  errContent: (msg: string) => Promise<{ content: Array<{ type: 'text'; text: string }> }>
+  actionError: (msg: string) => Promise<PageAgentToolErrorResult>
+}

package/page-tools/handlers/browserState.ts

@@ -0,0 +1,12 @@
+import type { ActionContext } from '../context'
+
+export async function handleBrowserState(args: any, ctx: ActionContext) {
+  if (window.__webmcpcli_beforeGetBrowserState) {
+    try {
+      window.__webmcpcli_beforeGetBrowserState()
+    } catch (e) {
+      console.warn('__webmcpcli_beforeGetBrowserState error:', e)
+    }
+  }
+  return ctx.buildBrowserStateResponse(args.responseMode ?? 'diff')
+}

package/page-tools/handlers/click.ts

@@ -0,0 +1,30 @@
+import { clickElement } from '@page-agent/page-controller'
+import { waitForDomSettled } from '../utils/dom'
+import type { ActionContext } from '../context'
+
+export async function handleClick(args: any, ctx: ActionContext) {
+  const mode = args.responseMode ?? 'diff'
+  if (args.index === undefined) return ctx.actionError('点击结果: 缺少元素索引')
+  const el = ctx.getRefMap().get(args.index)
+  if (!el) {
+    return ctx.actionError(
+      `点击失败: ref 索引 ${args.index} 已失效（页面可能已刷新），已自动重新加载页面状态，请使用新的 ref 索引重试。`
+    )
+  }
+
+  // 若 ref 指向 shadow host，解析其内部真正的可点击元素
+  let targetEl = el as HTMLElement
+  if (el.shadowRoot && !(el instanceof HTMLButtonElement) && !(el instanceof HTMLAnchorElement)) {
+    const innerClickable = el.shadowRoot.querySelector(
+      'button, a, [role="button"], [role="link"]'
+    ) as HTMLElement | null
+    if (innerClickable) {
+      targetEl = innerClickable
+    }
+  }
+  await clickElement(targetEl)
+  // 等待框架异步插入的校验错误/条件渲染内容稳定后再采集状态
+  await waitForDomSettled()
+  // 操作成功后自动返回 diff/both/full
+  return ctx.buildBrowserStateResponse(mode)
+}

package/page-tools/handlers/executeJavascript.ts

@@ -0,0 +1,22 @@
+import type { ActionContext } from '../context'
+
+export async function handleExecuteJavascript(args: any, ctx: ActionContext) {
+  if (!args.script) return ctx.errContent('脚本执行异常: 缺少javascript代码')
+  // eslint-disable-next-line no-new-func
+  // 方式1：将脚本包裹在 async IIFE 中执行，允许 return 语句
+  let result = await new Function(`return (async () => { ${args.script} })()`)()
+  // 方式2：若 result 为 undefined（脚本没有 return），降级尝试以表达式方式求值
+  // 场景：Agent 写了 "Array.from(...).map(...)" 但没有 return 关键字
+  if (result === undefined) {
+    try {
+      // eslint-disable-next-line no-new-func
+      result = await new Function(`return (async () => (${args.script}))()`)()
+    } catch {
+      // 表达式求值也失败（如含 await/let/const 等语句），保持 undefined
+    }
+  }
+  await ctx.pageController.hideMask()
+  return {
+    content: [{ type: 'text' as const, text: `脚本执行结果: ${JSON.stringify(result)}` }]
+  }
+}

package/page-tools/handlers/fill.ts

@@ -0,0 +1,65 @@
+import { inputTextElement } from '@page-agent/page-controller'
+import { dispatchComposedEvents, isInShadowDom, waitForDomSettled } from '../utils/dom'
+import type { ActionContext } from '../context'
+
+export async function handleFill(args: any, ctx: ActionContext) {
+  const mode = args.responseMode ?? 'diff'
+  if (args.index === undefined || typeof args.text !== 'string')
+    return ctx.actionError('填写结果: 缺少元素索引或文本内容')
+  const el = ctx.getRefMap().get(args.index)
+  if (!el) {
+    return ctx.actionError(
+      `填写失败: ref 索引 ${args.index} 已失效（页面可能已刷新），已自动重新加载页面状态，请使用新的 ref 索引重试。`
+    )
+  }
+
+  let targetEl = el
+  if (!(targetEl instanceof HTMLInputElement) && !(targetEl instanceof HTMLTextAreaElement)) {
+    // querySelector 不穿透 shadow boundary，对 shadow host 补查其 shadowRoot
+    const innerInput =
+      el.querySelector('input, textarea') ?? (el.shadowRoot?.querySelector('input, textarea') as HTMLElement | null)
+    if (innerInput) {
+      targetEl = innerInput as HTMLElement
+    }
+  }
+
+  if (targetEl instanceof HTMLInputElement && targetEl.readOnly) {
+    targetEl.value = args.text
+    // composed:true 确保事件穿透 shadow boundary，事件委托框架可捕获
+    dispatchComposedEvents(targetEl, 'input', 'change', 'blur')
+  } else {
+    // 优先尝试标准方式（支持 contenteditable、普通 input/textarea）
+    let fillSuccess = false
+    try {
+      await inputTextElement(targetEl, args.text)
+      fillSuccess = true
+    } catch (fillErr) {
+      // inputTextElement 失败时（如 Angular/React 组件包装的密码框），
+      // 降级使用原生 input value 描述符触发框架变更检测
+      const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+        (targetEl instanceof HTMLTextAreaElement ? HTMLTextAreaElement : HTMLInputElement).prototype,
+        'value'
+      )?.set
+      if (nativeInputValueSetter && (targetEl instanceof HTMLInputElement || targetEl instanceof HTMLTextAreaElement)) {
+        nativeInputValueSetter.call(targetEl, args.text)
+        // 发送完整事件序列，触发 Angular ngModel / React 合成事件的变更检测
+        targetEl.dispatchEvent(new Event('focus', { bubbles: true, composed: true }))
+        targetEl.dispatchEvent(new Event('input', { bubbles: true, composed: true }))
+        targetEl.dispatchEvent(new Event('change', { bubbles: true, composed: true }))
+        targetEl.dispatchEvent(new Event('blur', { bubbles: true, composed: true }))
+        fillSuccess = true
+      }
+    }
+    if (!fillSuccess) {
+      return ctx.actionError(`填写结果: 无法填写元素 ${args.index}，元素不是 input、textarea 或 contenteditable`)
+    }
+    // shadow DOM 内元素：inputTextElement 派发的合成事件 composed:false，
+    // 补发 composed:true 事件确保事件委托框架（如 React）能收到
+    if (isInShadowDom(targetEl)) {
+      dispatchComposedEvents(targetEl, 'input', 'change')
+    }
+  }
+  // 等待框架异步插入的校验错误/条件渲染内容稳定后再采集状态
+  await waitForDomSettled()
+  return ctx.buildBrowserStateResponse(mode)
+}

package/page-tools/handlers/scroll.ts

@@ -0,0 +1,66 @@
+import { getScrollInfo, waitForScrollEnd } from '../utils/scroll'
+import type { ActionContext } from '../context'
+
+export async function handleScroll(args: any, ctx: ActionContext) {
+  const mode = args.responseMode ?? 'diff'
+  if (args.down === undefined && args.right === undefined) return ctx.errContent('滚动结果: 缺少滚动方向参数')
+
+  // 确定滚动目标（有 index 时滚动该元素容器，否则滚动整个文档）
+  let scrollTarget: Element | Window = window
+  if (args.index !== undefined) {
+    const el = ctx.getRefMap().get(args.index)
+    if (!el) return ctx.refreshOnStaleRef('滚动', args.index)
+    scrollTarget = el
+  }
+
+  // 滚动前快照
+  const before = getScrollInfo(scrollTarget)
+
+  if (args.right !== undefined) {
+    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' })
+  }
+
+  // 等待滚动动画完成后再采集状态（scrollend + 超时兜底）
+  await waitForScrollEnd(scrollTarget)
+
+  // 滚动后快照，计算实际位移
+  const after = getScrollInfo(scrollTarget)
+  const deltaY = Math.round(after.scrollY - before.scrollY)
+  const deltaX = Math.round(after.scrollX - before.scrollX)
+  const isHorizontal = args.right !== undefined
+
+  let scrollMsg: string
+  if (Math.abs(deltaY) < 1 && Math.abs(deltaX) < 1) {
+    // 实际未发生位移，说明已到达边界
+    if (isHorizontal) {
+      scrollMsg = args.right ? '⚠️ 已到达右边界，无法继续向右滚动' : '⚠️ 已到达左边界，无法继续向左滚动'
+    } else {
+      scrollMsg = args.down ? '⚠️ 已到达底部，无法继续向下滚动' : '⚠️ 已到达顶部，无法继续向上滚动'
+    }
+  } else {
+    const axis = isHorizontal ? `水平滚动 ${deltaX}px` : `垂直滚动 ${deltaY}px`
+    let boundary = ''
+    if (isHorizontal) {
+      if (args.right && after.atRight) boundary = '，已到达右边界'
+      else if (!args.right && after.atLeft) boundary = '，已到达左边界'
+    } else {
+      if (args.down && after.atBottom) boundary = '，已到达底部'
+      else if (!args.down && after.atTop) boundary = '，已到达顶部'
+    }
+    scrollMsg = `✅ ${axis}${boundary}`
+  }
+
+  // 附加位置信息（参考 page-agent getPageInfo 格式）
+  const posInfo = args.right !== undefined
+    ? `当前水平滚动位置: scrollX=${Math.round(after.scrollX)}px，左侧 ${after.pagesAbove.toFixed(1)} 屏，右侧 ${after.pagesBelow.toFixed(1)} 屏`
+    : `当前滚动位置: scrollY=${Math.round(after.scrollY)}px，上方 ${after.pagesAbove.toFixed(1)} 屏，下方 ${after.pagesBelow.toFixed(1)} 屏`
+  const scrollResult = `[滚动结果] ${scrollMsg}\n${posInfo}`
+
+  const stateResult = await ctx.buildBrowserStateResponse(mode)
+  stateResult.content[0].text = `${scrollResult}\n\n${stateResult.content[0].text}`
+  return stateResult
+}

package/page-tools/handlers/searchTree.ts

@@ -0,0 +1,27 @@
+import { searchA11yTree } from '../a11y-tree'
+import { detectPageDialog, detectValidationErrors } from '../utils/dom'
+import { getPageAgentToolConfig } from '../tool-config'
+import type { ActionContext } from '../context'
+import type { PageAgentToolInput } from '../schema'
+
+export async function handleSearchTree(args: PageAgentToolInput, ctx: ActionContext) {
+  if (!args.query) return ctx.errContent('搜索失败: 缺少 query 参数')
+  const result = searchA11yTree(args.query, document.body, {
+    ...getPageAgentToolConfig().a11yConfig,
+    contextLines: args.contextLines,
+    maxMatches: args.maxMatches,
+  })
+
+  ctx.setRefMap(result.refMap)
+  ctx.stateCache.update(window.location.href, result.yaml)
+
+  await ctx.pageController.hideMask()
+  // 检测页面弹窗/遮罩层，帮助 AI 发现可能遮挡目标的确认弹窗
+  const dialogAlert = detectPageDialog()
+  // 检测表单校验错误，提醒 AI 优先修复
+  const validationErrors = detectValidationErrors()
+  const alerts = `${dialogAlert}${validationErrors}`
+  return {
+    content: [{ type: 'text' as const, text: alerts ? `${alerts}\n${result.text}` : result.text }]
+  }
+}

package/page-tools/handlers/select.ts

@@ -0,0 +1,39 @@
+import { selectOptionElement } from '@page-agent/page-controller'
+import { dispatchComposedEvents, isInShadowDom, waitForDomSettled } from '../utils/dom'
+import type { ActionContext } from '../context'
+
+export async function handleSelect(args: any, ctx: ActionContext) {
+  const mode = args.responseMode ?? 'diff'
+  if (args.index === undefined || typeof args.text !== 'string')
+    return ctx.actionError('选择结果: 缺少元素索引或文本内容')
+  let el = ctx.getRefMap().get(args.index) as HTMLSelectElement | HTMLElement | undefined
+  if (!el) {
+    return ctx.actionError(
+      `选择失败: ref 索引 ${args.index} 已失效（页面可能已刷新），已自动重新加载页面状态，请使用新的 ref 索引重试。`
+    )
+  }
+  // 若 ref 指向 shadow host，解析其内部真正的 <select>（与 fill 一致）
+  let targetSelect: HTMLSelectElement | null = null
+  if (el instanceof HTMLSelectElement) {
+    targetSelect = el
+  } else {
+    const innerSelect =
+      el.querySelector('select') ?? (el.shadowRoot?.querySelector('select') as HTMLSelectElement | null)
+    if (innerSelect) {
+      targetSelect = innerSelect
+    }
+  }
+
+  if (!targetSelect) {
+    return ctx.actionError(`选择结果: 无法选择元素 ${args.index}，未找到对应的 <select> 元素`)
+  }
+
+  await selectOptionElement(targetSelect, args.text)
+  // shadow DOM 内元素：补发 composed:true 的 change 事件
+  if (isInShadowDom(targetSelect)) {
+    dispatchComposedEvents(targetSelect, 'change')
+  }
+  // 等待框架异步插入的校验错误/条件渲染内容稳定后再采集状态
+  await waitForDomSettled()
+  return ctx.buildBrowserStateResponse(mode)
+}