@opentiny/next-sdk 0.3.3 → 0.4.1

package/dist/utils/builtinProxy.d.ts

@@ -2,6 +2,6 @@ import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 
 /**
  * 建立原生的 JSON-RPC 拦截层：
- * 将发向 remote 的 MCP 请求拦截，代理给所在浏览器的 navigator.modelContextTesting 上执行。
+ * 将发向 remote 的 MCP 请求拦截，代理给所在浏览器的 document.modelContext 上执行。
  */
 export declare const setupBuiltinProxy: (transport: Transport) => void;

package/index.ts

@@ -21,11 +21,6 @@ export type * from '@modelcontextprotocol/sdk/server/mcp.js'
 export * from './WebMcpServer'
 export * from './WebMcpClient'
 
-// 浏览器扩展自定义传输层
-export * from './transport/ExtensionClientTransport'
-export * from './transport/ExtensionPageServerTransport'
-export * from './transport/ExtensionContentServerTransport'
-
 // 快速创建一个悬浮图标和菜单，是扫码和聊天框的入口
 export * from './remoter/createRemoter'
 
@@ -57,17 +52,5 @@ export {
 
 export * from '@mcp-b/webmcp-polyfill'
 
-import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill'
-import { setupModelContextBridge } from './page-tools/bridge'
-import { isBrowser } from './utils/env'
-
-export const initializeBuiltinWebMCP = () => {
-  if (isBrowser()) {
-    try {
-      initializeWebMCPPolyfill()
-      setupModelContextBridge()
-    } catch (err) {
-      console.warn('[next-sdk] 自动注入 modelContext polyfill 和桥接同步失败:', err)
-    }
-  }
-}
+export { initializeBuiltinWebMCP } from './page-tools/initialize-builtin-WebMCP'
+export { registerPageAgentTool } from './page-tools/page-agent-tool'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentiny/next-sdk",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "type": "module",
   "homepage": "https://docs.opentiny.design/next-sdk/guide/",
   "repository": {
@@ -40,36 +40,32 @@
     "@ai-sdk/deepseek": "1.0.30",
     "@ai-sdk/provider": "^3.0.0",
     "@ai-sdk/mcp": "^1.0.0",
-    "@mcp-b/webmcp-polyfill": "^2.2.0",
+    "@mcp-b/webmcp-polyfill": "^3.0.0",
+    "@page-agent/page-controller": "^1.10.0",
     "qrcode": "^1.5.4",
     "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.25.2",
     "ajv": "^8.17.1",
-    "ai": "^6.0.0"
+    "ai": "^6.0.0",
+    "dom-accessibility-api": "^0.6.3",
+    "aria-query": "^5.3.2",
+    "tabbable": "^6.2.0",
+    "diff": "^7.0.0",
+    "ai-motion": "^0.4.8"
   },
   "devDependencies": {
     "typescript": "~5.9.3",
     "vite": "^7.1.7",
     "vite-plugin-dts": "^3.9.1",
     "@types/qrcode": "^1.5.5",
-    "@types/node": "^24.3.0"
+    "@types/node": "^24.6.0",
+    "@types/diff": "^7.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build:all": "pnpm build:cdn && pnpm build:cdn:dev && pnpm build",
-    "build": "vite build --config vite-build-tsc.ts",
-    "build:cdn": "vite build && pnpm build:webAgent && pnpm build:webMcp && pnpm build:mcpSdk && pnpm build:zod && pnpm build:webMcpFull",
-    "build:cdn:dev": "vite build --mode dev && pnpm build:webAgent:dev && pnpm build:webMcp:dev && pnpm build:mcpSdk:dev && pnpm build:zod:dev && pnpm build:webMcpFull:dev",
-    "build:webAgent": "vite build --config vite.config.webAgent.ts",
-    "build:webAgent:dev": "vite build --config vite.config.webAgent.ts --mode dev",
-    "build:webMcp": "vite build --config vite.config.webMcp.ts",
-    "build:webMcp:dev": "vite build --config vite.config.webMcp.ts --mode dev",
-    "build:mcpSdk": "vite build --config vite.config.mcpSdk.ts",
-    "build:mcpSdk:dev": "vite build --config vite.config.mcpSdk.ts --mode dev",
-    "build:zod": "vite build --config vite.config.zod.ts",
-    "build:zod:dev": "vite build --config vite.config.zod.ts --mode dev",
-    "build:webMcpFull": "vite build --config vite.config.webMcpFull.ts",
-    "build:webMcpFull:dev": "vite build --config vite.config.webMcpFull.ts --mode dev"
+    "build": "vite build && vite build --config vite.config.runtime.ts",
+    "build:runtime": "vite build --config vite.config.runtime.ts"
   }
 }

package/page-tools/a11y/build.ts

@@ -0,0 +1,70 @@
+/**
+ * a11y/build.ts
+ *
+ * 暴露生成整棵无障碍树的主逻辑方法。
+ */
+
+import type { A11yTreeOptions, A11yTreeResult, RefMap } from './types'
+import { DEFAULT_ERROR_SELECTORS, DEFAULT_WARNING_SELECTORS } from './constants'
+import { buildVNode, serializeVNode } from './vnode'
+import { getComposedChildren } from './utils'
+import { HIGHLIGHT_CONTAINER_ID } from '../page-agent-highlight'
+
+const DEFAULT_OPTIONS: Required<A11yTreeOptions> = {
+  pruneUnnamed: true,
+  preserveRoles: [],
+  exposedAttributes: [],
+  errorSelectors: DEFAULT_ERROR_SELECTORS,
+  warningSelectors: DEFAULT_WARNING_SELECTORS
+}
+
+/**
+ * 生成当前页面的语义化 ARIA YAML 树
+ *
+ * @param root 遍历起点，默认 document.body
+ * @param blacklist 需要跳过的元素（用户自定义黑名单）
+ * @param whitelist 需要识别为可交互的白名单元素列表
+ * @param options 过滤选项
+ */
+export function buildA11yTree(
+  root: Element = document.body,
+  blacklist: Element[] = [],
+  whitelist: Element[] = [],
+  options?: A11yTreeOptions
+): A11yTreeResult {
+  const opts: Required<A11yTreeOptions> = { ...DEFAULT_OPTIONS, ...options }
+  // 使用对象引用避免全局可变状态，消除并发调用隐患
+  const refCounter = { value: 0 }
+  const refMap: RefMap = new Map()
+  const blacklistSet = new Set(blacklist)
+  const whitelistSet = new Set(whitelist)
+  const lines: string[] = []
+
+  // 永远过滤高亮容器
+  blacklistSet.add(document.getElementById(HIGHLIGHT_CONTAINER_ID)!)
+
+  for (const child of getComposedChildren(root)) {
+    const vnode = buildVNode(
+      child,
+      refCounter,
+      refMap,
+      blacklistSet,
+      whitelistSet,
+      opts.exposedAttributes,
+      opts.errorSelectors,
+      opts.warningSelectors
+    )
+    if (vnode) {
+      lines.push(...serializeVNode(vnode, 0, opts))
+    }
+  }
+
+  const yaml = '```yaml\n' + lines.join('\n') + '\n```'
+
+  return {
+    yaml,
+    refMap,
+    interactiveCount: refMap.size,
+    lines
+  }
+}

package/page-tools/a11y/constants.ts

@@ -0,0 +1,110 @@
+/**
+ * a11y/constants.ts
+ *
+ * 存放无障碍树依赖的静态常量配置、默认选择器及角色映射表。
+ */
+
+// ─── 默认校验错误/警告选择器（ARIA 标准 + 主流 UI 框架） ──────────────────
+
+export const DEFAULT_ERROR_SELECTORS = [
+  '[role="alert"]', '[aria-invalid="true"]',
+  '.ti3-unifyvalid-error', '.ti3-error', '.ti-error',
+  '.lego-text-error', '.lego-error',
+  '.el-form-item__error',
+  '.ant-form-item-explain-error',
+  '.is-invalid', '.invalid-feedback',
+  '.ng-invalid',
+  '.error-msg', '.error-message', '.error-text',
+  '.field-error', '.form-error',
+  '.is-error', '.has-error',
+  '.validate-error', '.valid-error',
+]
+
+export const DEFAULT_WARNING_SELECTORS = [
+  '.ti3-warning', '.ti-warning', '.lego-text-warning',
+  '.warning-msg', '.warning-text', '.is-warning', '.has-warning',
+]
+
+// ─── ARIA 隐式角色静态映射表（覆盖页面 95%+ 的常用标签）───────────────────────
+
+export const TAG_ROLE_MAP: Record<string, string> = {
+  a: 'link',
+  article: 'article',
+  aside: 'complementary',
+  button: 'button',
+  caption: 'caption',
+  cell: 'cell',
+  checkbox: 'checkbox',
+  code: 'code',
+  columnheader: 'columnheader',
+  combobox: 'combobox',
+  datalist: 'listbox',
+  dd: 'definition',
+  details: 'group',
+  dialog: 'dialog',
+  dt: 'term',
+  em: 'emphasis',
+  fieldset: 'group',
+  figure: 'figure',
+  footer: 'contentinfo',
+  form: 'form',
+  h1: 'heading',
+  h2: 'heading',
+  h3: 'heading',
+  h4: 'heading',
+  h5: 'heading',
+  h6: 'heading',
+  header: 'banner',
+  hr: 'separator',
+  img: 'img',
+  input: 'textbox',         // 默认，具体 type 下面会覆盖
+  li: 'listitem',
+  link: 'link',
+  main: 'main',
+  mark: 'mark',
+  math: 'math',
+  menu: 'list',
+  menuitem: 'menuitem',
+  meter: 'meter',
+  nav: 'navigation',
+  ol: 'list',
+  option: 'option',
+  output: 'status',
+  p: 'paragraph',
+  progress: 'progressbar',
+  rowheader: 'rowheader',
+  search: 'search',
+  section: 'region',
+  select: 'listbox',
+  strong: 'strong',
+  summary: 'button',
+  table: 'table',
+  tbody: 'rowgroup',
+  td: 'cell',
+  textarea: 'textbox',
+  tfoot: 'rowgroup',
+  th: 'columnheader',
+  thead: 'rowgroup',
+  time: 'time',
+  tr: 'row',
+  ul: 'list',
+}
+
+// input[type=*] 的角色覆盖
+export const INPUT_TYPE_ROLE: Record<string, string> = {
+  button: 'button',
+  checkbox: 'checkbox',
+  color: 'textbox',
+  email: 'textbox',
+  file: 'textbox',
+  image: 'button',
+  number: 'spinbutton',
+  radio: 'radio',
+  range: 'slider',
+  reset: 'button',
+  search: 'searchbox',
+  submit: 'button',
+  tel: 'textbox',
+  text: 'textbox',
+  url: 'textbox',
+}

package/page-tools/a11y/search.ts

@@ -0,0 +1,129 @@
+/**
+ * a11y/search.ts
+ *
+ * 在无障碍树内执行基于文本或引用的搜索操作。
+ */
+
+import type { SearchA11yTreeOptions, SearchA11yTreeResult, A11ySearchMatch } from './types'
+import { buildA11yTree } from './build'
+
+/**
+ * 在无障碍树中按关键词搜索，返回带行号的匹配结果和上下文
+ *
+ * 支持的搜索维度（均对同一个 query 字符串做包含匹配）：
+ *   - role：如 `button`、`link`、`heading`
+ *   - accessible name：节点的语义化名称（引号内文本）
+ *   - state token：如 `checked`、`disabled`、`expanded`
+ *   - ref 索引：如 `#5`
+ *
+ * @example
+ *   searchA11yTree('button')    // 找全部按钮
+ *   searchA11yTree('提交')      // 找名称含"提交"的节点
+ *   searchA11yTree('#3')        // 找 ref #3
+ */
+export function searchA11yTree(
+  query: string,
+  root: Element = document.body,
+  blacklist: Element[] = [],
+  whitelist: Element[] = [],
+  options?: SearchA11yTreeOptions,
+): SearchA11yTreeResult {
+  const {
+    contextLines = 2,
+    caseInsensitive = true,
+    maxMatches = 20,
+    ...treeOptions
+  } = options ?? {}
+
+  const safeContextLines = Math.max(0, contextLines)
+  const safeMaxMatches = Math.max(1, maxMatches)
+
+  // 复用 buildA11yTree 生成完整树，直接取 lines 数组（不重复构建 DOM 遍历）
+  const { lines, refMap, yaml } = buildA11yTree(root, blacklist, whitelist, treeOptions)
+
+  const needle = caseInsensitive ? query.toLowerCase() : query
+  const totalLines = lines.length
+
+  const isRefQuery = /^#\d+$/.test(query)
+  const refRegex = isRefQuery ? new RegExp(`\\s${query}(?:\\s|[\\[]|$)`) : null
+
+  // 找出所有命中行的下标（0-based）
+  const hitIndices: number[] = []
+  for (let i = 0; i < lines.length; i++) {
+    let matched = false
+    if (refRegex) {
+      matched = refRegex.test(lines[i])
+    } else {
+      const haystack = caseInsensitive ? lines[i].toLowerCase() : lines[i]
+      matched = haystack.includes(needle)
+    }
+    if (matched) {
+      hitIndices.push(i)
+    }
+  }
+
+  // 合并重叠的上下文区间，避免重复输出行
+  const mergedRanges: Array<{ start: number; end: number; hits: number[] }> = []
+  let isTruncated = false
+  for (const idx of hitIndices) {
+    const start = Math.max(0, idx - safeContextLines)
+    const end = Math.min(totalLines - 1, idx + safeContextLines)
+    const last = mergedRanges[mergedRanges.length - 1]
+    if (last && start <= last.end + 1) {
+      // 区间重叠或紧邻，合并
+      last.end = Math.max(last.end, end)
+      last.hits.push(idx)
+    } else {
+      if (mergedRanges.length >= safeMaxMatches) {
+        isTruncated = true
+        break
+      }
+      mergedRanges.push({ start, end, hits: [idx] })
+    }
+  }
+
+  // 构建结构化结果
+  const matches: A11ySearchMatch[] = mergedRanges.map((range) => ({
+    lineNumber: range.hits[0] + 1,
+    line: lines[range.hits[0]],
+    context: Array.from({ length: range.end - range.start + 1 }, (_, k) => ({
+      lineNumber: range.start + k + 1,
+      line: lines[range.start + k],
+    })),
+  }))
+
+  // 格式化为可读文本（模仿 grep -n -C 风格，便于 LLM 直接理解）
+  const textParts: string[] = [
+    `无障碍树搜索结果 — 关键词: "${query}" | 总行数: ${totalLines} | 命中: ${hitIndices.length} 行 | 返回分组: ${matches.length}`,
+    '',
+  ]
+
+  if (matches.length === 0) {
+    textParts.push('（未找到匹配项）')
+  } else {
+    matches.forEach((match, m) => {
+      const range = mergedRanges[m]
+      textParts.push(`── 分组 ${m + 1}（第 ${range.start + 1}–${range.end + 1} 行）──`)
+      match.context.forEach(({ lineNumber, line }) => {
+        const isHit = range.hits.includes(lineNumber - 1)
+        const ln = String(lineNumber).padStart(4)
+        // 命中行用 >>> 标记，上下文行用普通行号前缀
+        textParts.push(isHit ? `>>>${ln} | ${line}` : `   ${ln} | ${line}`)
+      })
+      textParts.push('')
+    })
+    if (isTruncated) {
+      textParts.push(`⚠️ 命中过多，已截断至前 ${safeMaxMatches} 个分组，建议缩小搜索范围`)
+    }
+    textParts.push(`提示：如需操作命中元素，使用其 #N 索引；如需查看完整树，请使用 browserState。`)
+  }
+
+  return {
+    text: textParts.join('\n'),
+    matches,
+    totalLines,
+    matchCount: hitIndices.length,
+    refMap,
+    yaml,
+  }
+}

package/page-tools/a11y/types.ts

@@ -0,0 +1,108 @@
+/**
+ * a11y/types.ts
+ *
+ * 定义无障碍树模块（A11y Tree）的核心接口和类型。
+ */
+
+/** ref 索引 → HTMLElement 映射，供 click/fill/select 操作使用 */
+export type RefMap = Map<number, HTMLElement>
+
+/** 内部中间态节点，与 DOM 解耦，便于剪枝和序列化 */
+export interface VNode {
+  /** 节点的 ARIA 角色 (如 'button', 'link', 'textbox') */
+  role: string
+  /** W3C AccName 算法计算出的语义化名称 */
+  name: string
+  /** 元素相关的状态和属性标记 (如 'checked', 'disabled', 'value="xxx"') */
+  tokens: string[]
+  /** 只有交互节点才有 ref (内部索引，用于标识可在其上执行交互动作的元素) */
+  ref?: number
+  /** 关联的 DOM 元素实例 */
+  el: HTMLElement
+  /** 包含的子节点列表 */
+  children: VNode[]
+}
+
+/** 构建无障碍树时的配置选项 */
+export interface A11yTreeOptions {
+  /**
+   * 是否启用剪枝：无 ref 且无 accessible name 的节点透明穿透
+   * 默认 true（推荐）
+   */
+  pruneUnnamed?: boolean
+  /**
+   * 强制保留的角色列表，即使无 name 也不穿透（优先级最高）
+   * 例如：['table', 'row'] 用于保留表格结构
+   */
+  preserveRoles?: string[]
+  /**
+   * 允许在无障碍树节点中作为 token 额外输出的 DOM 属性白名单
+   * 包含这些属性的节点会被自动视为需要暴露/交互的节点（分配 ref 并保留），
+   * 且属性及其值会显示在节点的 token 列表中，如 [cf-uba="cloudShell"]
+   */
+  exposedAttributes?: string[]
+  /**
+   * 校验错误元素 CSS 选择器（逗号分隔或选择器数组），用于在 token 中标记 [error]
+   * 默认覆盖 ARIA 标准 + 主流 UI 框架
+   */
+  errorSelectors?: string | string[]
+  /**
+   * 校验警告元素 CSS 选择器（逗号分隔或选择器数组）
+   */
+  warningSelectors?: string | string[]
+}
+
+/** 构建无障碍树的返回结果 */
+export interface A11yTreeResult {
+  /** 语义化 YAML 文本（供 AI 阅读和 Diff 计算） */
+  yaml: string
+  /** ref 索引 → HTMLElement 映射（供后续操作使用） */
+  refMap: RefMap
+  /** 可交互元素总数 */
+  interactiveCount: number
+  /** 原始行数组（不含 yaml 代码块包裹），供搜索使用 */
+  lines: string[]
+}
+
+/** 关键词搜索选项 */
+export interface SearchA11yTreeOptions extends A11yTreeOptions {
+  /**
+   * 每个匹配行前后保留的上下文行数（类似 grep -C N）
+   * 默认 2
+   */
+  contextLines?: number
+  /**
+   * 是否大小写不敏感，默认 true
+   */
+  caseInsensitive?: boolean
+  /**
+   * 最大返回匹配分组数（防止命中过多撑爆上下文），默认 20
+   */
+  maxMatches?: number
+}
+
+/** 单个搜索匹配的分组结构 */
+export interface A11ySearchMatch {
+  /** 主命中行行号（1-based） */
+  lineNumber: number
+  /** 主命中行内容 */
+  line: string
+  /** 含上下文的行列表（带行号） */
+  context: Array<{ lineNumber: number; line: string }>
+}
+
+/** searchA11yTree 函数的返回结果 */
+export interface SearchA11yTreeResult {
+  /** 格式化后可直接发给 LLM 的文本 */
+  text: string
+  /** 结构化匹配列表 */
+  matches: A11ySearchMatch[]
+  /** 无障碍树总行数 */
+  totalLines: number
+  /** 原始命中行数（去重前） */
+  matchCount: number
+  /** 返回搜索时的 ref 映射 */
+  refMap: RefMap
+  /** 返回搜索时的 yaml 状态，用于更新缓存 */
+  yaml: string
+}