@opentiny/next-sdk 0.3.3 → 0.4.1

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

@@ -0,0 +1,175 @@
+import { initializeBuiltinWebMCP } from './initialize-builtin-WebMCP'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+import pageAgentPrompt from './page-agent-prompt.md?raw'
+import { PageController } from '@page-agent/page-controller'
+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 { DEFAULT_ERROR_SELECTORS, DEFAULT_DIALOG_SELECTORS, type PageAgentToolOptions } from './constants'
+import { inputSchema, type PageAgentToolInput } from './schema'
+import type { ActionContext } from './context'
+import { detectPageDialog, detectValidationErrors } from './utils/dom'
+
+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(options: PageAgentToolOptions = {}) {
+  initializeBuiltinWebMCP()
+
+  // 默认启用元素高亮
+  if (typeof options.enableHighlight === 'undefined') {
+    options.enableHighlight = true
+  }
+
+  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
+
+  // 保留 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()
+
+  // 当前 ref 索引 → HTMLElement 映射（每次 buildA11yTree 后更新）
+  let currentRefMap: RefMap = new Map()
+
+  // ─── 辅助：构建错误响应 ───────────────────────────────────────────────────
+  async function errContent(msg: string) {
+    await pageController.hideMask()
+    return { content: [{ type: 'text' as const, text: msg }] }
+  }
+
+  // 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: '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[]
+    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(', ')
+    })
+    currentRefMap = refMap
+
+    // 高亮交互元素，且增加全局移除高亮的监听
+    if (options?.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 = ''
+    if (responseMode === 'full') {
+      displayContent = yaml
+    } else if (responseMode === 'diff') {
+      displayContent = diff.isFullRefresh ? yaml : diff.diffText
+    } else if (responseMode === 'both') {
+      displayContent = `【全量页面树】:\n${yaml}\n\n【增量差异】:\n${diff.isFullRefresh ? '（首次/刷新，无增量差异）' : diff.diffText}`
+    }
+
+    // 拼装 JSON 格式状态，与 webmcp-cli 的 state 提取逻辑对齐
+    const stateObj = {
+      url,
+      title,
+      content: displayContent
+    }
+    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
+  }
+
+  // ─── 工具注册（名称与 inputSchema 与原版完全一致）────────────────────────
+  ;(document as any).modelContext.registerTool({
+    name: 'page-agent-tool',
+    description: pageAgentPrompt,
+    // @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}` }] }
+        }
+      } catch (error) {
+        await pageController.hideMask()
+        return { content: [{ type: 'text', text: `异常: ${String(error)}` }] }
+      }
+    }
+  })
+}

package/page-tools/page-state-cache.ts

@@ -0,0 +1,78 @@
+/**
+ * page-state-cache.ts
+ *
+ * 页面状态 Diff 缓存模块
+ * - 缓存上一次 buildA11yTree 生成的 YAML 文本
+ * - 每次操作后计算 diff，只返回 +/- 变化行，大幅节省 Token
+ */
+
+import { diffLines } from 'diff'
+
+export interface PageSnapshot {
+  url: string
+  yaml: string
+}
+
+export interface DiffResult {
+  /** 是否为全量刷新（首次加载或 URL 变化） */
+  isFullRefresh: boolean
+  /** 上一次的 URL（用于拼接 URL 变化提示） */
+  prevUrl: string
+  /** 新增行数 */
+  addedLines: number
+  /** 删除行数 */
+  removedLines: number
+  /** 只含 +/- 行的 diff 文本（不含相同行，节省 Token） */
+  diffText: string
+}
+
+export class PageStateCache {
+  private prev: PageSnapshot | null = null
+
+  /** URL 变化或首次调用时，需要全量输出 */
+  isFullRefresh(currentUrl: string): boolean {
+    return !this.prev || this.prev.url !== currentUrl
+  }
+
+  /**
+   * 更新缓存并返回 diff 结果
+   * @param url 当前页面 URL
+   * @param yaml 当前 YAML 树文本
+   */
+  update(url: string, yaml: string): DiffResult {
+    const isFullRefresh = this.isFullRefresh(url)
+    const prevUrl = this.prev?.url ?? ''
+
+    let addedLines = 0
+    let removedLines = 0
+    let diffText = ''
+
+    if (!isFullRefresh && this.prev) {
+      const changes = diffLines(this.prev.yaml, yaml)
+      const buf: string[] = []
+      changes.forEach(part => {
+        // 跳过相同行，只保留变化行，大幅节省传给 AI 的 Token 数量
+        if (!part.added && !part.removed) return
+        const lines = part.value.split('\n').filter(Boolean)
+        if (part.added) {
+          addedLines += lines.length
+          lines.forEach(l => buf.push(`+ ${l}`))
+        } else {
+          removedLines += lines.length
+          lines.forEach(l => buf.push(`- ${l}`))
+        }
+      })
+      diffText = buf.join('\n')
+    }
+
+    // 更新缓存
+    this.prev = { url, yaml }
+
+    return { isFullRefresh, prevUrl, addedLines, removedLines, diffText }
+  }
+
+  /** 强制清空缓存（页面刷新 / 手动重置场景） */
+  invalidate(): void {
+    this.prev = null
+  }
+}

package/page-tools/schema.ts

@@ -0,0 +1,51 @@
+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>

package/page-tools/utils/dom.ts

@@ -0,0 +1,155 @@
+import { DEFAULT_DIALOG_SELECTORS, DEFAULT_ERROR_SELECTORS } from '../constants'
+
+// ─── 辅助：Shadow DOM 事件穿透 ───────────────────────────────────────────
+// 外部包 inputTextElement/selectOptionElement 派发的合成事件 composed:false，
+// 无法穿透 shadow boundary，导致事件委托框架（如 React）收不到 shadow 内元素的
+// input/change 事件。这里对 shadow DOM 内元素补发 composed:true 事件。
+export function isInShadowDom(el: Element): boolean {
+  return el.getRootNode() instanceof ShadowRoot
+}
+
+export function dispatchComposedEvents(el: Element, ...types: string[]) {
+  for (const type of types) {
+    el.dispatchEvent(new Event(type, { bubbles: true, composed: true }))
+  }
+}
+
+// ─── 辅助：穿透 Shadow DOM 的查询 ─────────────────────────────────────────
+export function deepQuerySelectorAll(selector: string, root: Document | Element | ShadowRoot = document): Element[] {
+  const elements = Array.from(root.querySelectorAll(selector))
+  
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, null)
+  let currentNode: Node | null = walker.currentNode
+  while (currentNode) {
+    if ((currentNode as Element).shadowRoot) {
+      elements.push(...deepQuerySelectorAll(selector, (currentNode as Element).shadowRoot!))
+    }
+    currentNode = walker.nextNode()
+  }
+  return elements
+}
+
+// ─── 辅助：等待 DOM 变更稳定 ────────────────────────────────────────────
+// click/fill/select 操作后，框架（Angular/React/Vue）可能异步插入校验错误、
+// 条件渲染选项等动态内容。用 MutationObserver 监听 DOM 变更，等待变更平息后
+// 再构建 A11y 树，确保动态插入的内容（如 ng-star-inserted 校验提示）被捕获。
+export function waitForDomSettled(timeout = 600, settleTime = 150): Promise<void> {
+  return new Promise<void>((resolve) => {
+    let settled = false
+    let settleTimer: ReturnType<typeof setTimeout> | undefined
+    const finish = () => {
+      if (settled) return
+      settled = true
+      observer.disconnect()
+      if (settleTimer) clearTimeout(settleTimer)
+      resolve()
+    }
+    // 每次有 DOM 变更时重置 settle 计时器；变更平息 settleTime 后视为稳定
+    const observer = new MutationObserver(() => {
+      if (settleTimer) clearTimeout(settleTimer)
+      settleTimer = setTimeout(finish, settleTime)
+    })
+    // 若无任何变更，settleTime 后直接结束
+    settleTimer = setTimeout(finish, settleTime)
+    // 超时保护：timeout 后强制结束，避免无限等待
+    setTimeout(finish, timeout)
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['class', 'style', 'hidden'],
+    })
+  })
+}
+
+// ─── 辅助：检测页面级模态弹窗/遮罩层 ────────────────────────────────────
+// 仅检测真正阻塞交互的模态弹窗（确认框、提交对话框等），
+// 不检测顶部通知横幅、站内消息等非模态提示，避免误报导致 AI 循环
+export function detectPageDialog(): string {
+  const seen = new Set<Element>()
+  const dialogs: string[] = []
+  // 仅匹配明确的模态弹窗选择器，避免宽泛子串匹配误报
+  const selectors = (window.__webmcpcli_dialogSelectors ?? DEFAULT_DIALOG_SELECTORS)
+
+  for (const selector of selectors) {
+    try {
+      for (const el of deepQuerySelectorAll(selector)) {
+        if (seen.has(el)) continue
+        // 跳过 SDK 自身遮罩
+        if (el.id?.includes('page-agent-runtime')) continue
+        if (el.closest('#page-agent-runtime_simulator-mask')) continue
+
+        const rect = el.getBoundingClientRect()
+        if (rect.width < 50 || rect.height < 50) continue
+        const style = window.getComputedStyle(el as HTMLElement)
+        if (style.display === 'none' || style.visibility === 'hidden') continue
+
+        // 模态性验证：必须是 fixed/absolute 且 z-index 较高
+        const isFixed = style.position === 'fixed' || style.position === 'absolute'
+        const zIndex = parseInt(style.zIndex || '0', 10)
+        if (!isFixed || zIndex < 100) continue
+
+        // 必须覆盖视口中心区域（真正的模态弹窗会遮挡页面中心）
+        const vw = window.innerWidth
+        const vh = window.innerHeight
+        const coversCenter = rect.left < vw * 0.6 && rect.right > vw * 0.4 &&
+                             rect.top < vh * 0.6 && rect.bottom > vh * 0.4
+        if (!coversCenter) continue
+
+        seen.add(el)
+        const text = (el.textContent || '').trim().replace(/\s+/g, ' ')
+        if (text.length > 5) {
+          // 提取弹窗内的可交互按钮，帮助 AI 快速决策
+          const btns = el.querySelectorAll('button, [role="button"], a')
+          const btnTexts = Array.from(btns)
+            .map(b => (b.textContent || '').trim())
+            .filter(t => t.length > 0 && t.length < 20)
+            .slice(0, 5)
+          const btnInfo = btnTexts.length ? ` [可操作按钮: ${btnTexts.join(' / ')}]` : ''
+          dialogs.push(`${text.substring(0, 300)}${btnInfo}`)
+        }
+      }
+    } catch {
+      // 忽略选择器异常
+    }
+  }
+
+  if (dialogs.length === 0) return ''
+  return `\n[页面弹窗检测] 检测到 ${dialogs.length} 个模态弹窗，请优先处理:\n${dialogs.map((d, i) => `${i + 1}. ${d}`).join('\n')}\n`
+}
+
+// ─── 辅助：检测页面可见的表单校验错误 ──────────────────────────────────
+// 操作后自动扫描页面中的校验错误提示，提取文本并提醒 AI，
+// 避免 AI 卡住时不知道是因为有校验错误未处理
+export function detectValidationErrors(): string {
+  const seen = new Set<Element>()
+  const errors: string[] = []
+  // 校验错误选择器：ARIA 标准 + 主流 UI 框架（可配置）
+  const selectors = (window.__webmcpcli_errorSelectors ?? DEFAULT_ERROR_SELECTORS)
+
+  for (const selector of selectors) {
+    try {
+      for (const el of deepQuerySelectorAll(selector)) {
+        if (seen.has(el)) continue
+        // 跳过嵌套在已收集的错误元素内的子元素，避免重复
+        if (Array.from(seen).some(s => s.contains(el))) continue
+
+        const rect = el.getBoundingClientRect()
+        if (rect.width < 1 || rect.height < 1) continue
+        const style = window.getComputedStyle(el as HTMLElement)
+        if (style.display === 'none' || style.visibility === 'hidden') continue
+
+        const text = (el.textContent || '').trim().replace(/\s+/g, ' ')
+        if (text.length > 2 && text.length < 200) {
+          seen.add(el)
+          errors.push(text)
+        }
+      }
+    } catch {
+      // 忽略选择器异常
+    }
+  }
+
+  if (errors.length === 0) return ''
+  return `\n[校验提示] 检测到 ${errors.length} 个表单校验错误，请先修复后再继续:\n${errors.map((e, i) => `${i + 1}. ${e}`).join('\n')}\n`
+}

package/page-tools/utils/scroll.ts

@@ -0,0 +1,58 @@
+// ─── 辅助：获取滚动目标的当前位置信息（仿 page-agent getPageInfo）────────
+// 同时支持 window（文档滚动）和任意 Element（容器滚动）
+export function getScrollInfo(target: Window | Element = window) {
+  if (target === window) {
+    const pageHeight = Math.max(document.documentElement.scrollHeight, document.body.scrollHeight)
+    const pageWidth = Math.max(document.documentElement.scrollWidth, document.body.scrollWidth)
+    const scrollY = window.scrollY
+    const scrollX = window.scrollX
+    const pixelsBelow = Math.max(0, pageHeight - (window.innerHeight + scrollY))
+    const pixelsRight = Math.max(0, pageWidth - (window.innerWidth + scrollX))
+    return {
+      scrollY, scrollX,
+      pixelsAbove: scrollY, pixelsBelow,
+      pixelsLeft: scrollX, pixelsRight,
+      pagesAbove: window.innerHeight > 0 ? scrollY / window.innerHeight : 0,
+      pagesBelow: window.innerHeight > 0 ? pixelsBelow / window.innerHeight : 0,
+      atTop: scrollY <= 1,
+      atBottom: pixelsBelow <= 1,
+      atLeft: scrollX <= 1,
+      atRight: pixelsRight <= 1,
+    }
+  } else {
+    const el = target as Element
+    const scrollTop = el.scrollTop
+    const scrollLeft = el.scrollLeft
+    const pixelsBelow = el.scrollHeight - el.clientHeight - scrollTop
+    const pixelsRight = el.scrollWidth - el.clientWidth - scrollLeft
+    return {
+      scrollY: scrollTop, scrollX: scrollLeft,
+      pixelsAbove: scrollTop, pixelsBelow: Math.max(0, pixelsBelow),
+      pixelsLeft: scrollLeft, pixelsRight: Math.max(0, pixelsRight),
+      pagesAbove: el.clientHeight > 0 ? scrollTop / el.clientHeight : 0,
+      pagesBelow: el.clientHeight > 0 ? Math.max(0, pixelsBelow) / el.clientHeight : 0,
+      atTop: scrollTop <= 1,
+      atBottom: pixelsBelow <= 1,
+      atLeft: scrollLeft <= 1,
+      atRight: pixelsRight <= 1,
+    }
+  }
+}
+
+// 等待 smooth scroll 结束：优先监听 scrollend，超时兜底（边界无位移时 scrollend 可能不触发）
+export function waitForScrollEnd(target: Window | Element, timeout = 2000): Promise<void> {
+  return new Promise((resolve) => {
+    let settled = false
+    const el = target === window ? document : (target as Element)
+    const finish = () => {
+      if (settled) return
+      settled = true
+      el.removeEventListener('scrollend', onScrollEnd)
+      clearTimeout(timer)
+      resolve()
+    }
+    const onScrollEnd = () => finish()
+    const timer = setTimeout(finish, timeout)
+    el.addEventListener('scrollend', onScrollEnd, { once: true })
+  })
+}

package/runtime.ts

@@ -0,0 +1,13 @@
+import { initializeBuiltinWebMCP } from './page-tools/initialize-builtin-WebMCP'
+import { registerPageAgentTool } from './page-tools/page-agent-tool'
+
+if (typeof window !== 'undefined') {
+  ;(window as any).initializeBuiltinWebMCP = initializeBuiltinWebMCP
+  ;(window as any).registerPageAgentTool = registerPageAgentTool
+
+  // 作为 IIFE 注入到页面 MAIN world 时自动注册 page-agent-tool
+  // 避免 content script 需要额外触发（会被 CSP 内联 script 限制拦截）
+  registerPageAgentTool()
+}
+
+export { initializeBuiltinWebMCP, registerPageAgentTool }

package/utils/builtinProxy.ts

@@ -1,17 +1,45 @@
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
 
+/** 浏览器内置 WebMCP 原生上下文接口 */
+interface NativeModelContext {
+  getTools(): Promise<NativeTool[]> | NativeTool[]
+  executeTool(tool: NativeTool, argsStr: string): Promise<unknown>
+}
+
+/** 原生工具描述 */
+interface NativeTool {
+  name: string
+  description?: string
+  title?: string
+  inputSchema?: unknown
+}
+
+/** JSON-RPC 消息基础结构 */
+interface JsonRpcMessage {
+  jsonrpc: string
+  id?: string | number
+  method?: string
+  params?: {
+    name?: string
+    arguments?: Record<string, unknown>
+    [key: string]: unknown
+  }
+}
+
 /**
  * 建立原生的 JSON-RPC 拦截层：
- * 将发向 remote 的 MCP 请求拦截，代理给所在浏览器的 navigator.modelContextTesting 上执行。
+ * 将发向 remote 的 MCP 请求拦截，代理给所在浏览器的 document.modelContext 上执行。
  */
 export const setupBuiltinProxy = (transport: Transport) => {
-  const getNativeCtx = () => {
-    if (typeof navigator === 'undefined') return null
-    const nav = navigator as any
-    return nav.modelContextTesting || null
+  const getNativeCtx = (): NativeModelContext | null => {
+    let ctx: NativeModelContext | null = null
+    if (typeof document !== 'undefined') ctx = ctx || ((document as unknown as Record<string, unknown>).modelContext as NativeModelContext | null)
+    if (typeof navigator !== 'undefined') ctx = ctx || ((navigator as unknown as Record<string, unknown>).modelContext as NativeModelContext | null)
+    ctx = ctx || ((globalThis as unknown as Record<string, unknown>).modelContext as NativeModelContext | null)
+    return ctx || null
   }
 
-  transport.onmessage = async (message: any) => {
+  transport.onmessage = async (message: JsonRpcMessage) => {
     if (!message || typeof message !== 'object') return
     const id = message.id
     const method = message.method
@@ -36,8 +64,8 @@ export const setupBuiltinProxy = (transport: Transport) => {
         await transport.send({ jsonrpc: '2.0', id, result: {} })
       } else if (method === 'tools/list') {
         const nativeCtx = getNativeCtx()
-        if (nativeCtx && nativeCtx.listTools) {
-          const rawTools = await nativeCtx.listTools()
+        if (nativeCtx && nativeCtx.getTools) {
+          const rawTools = await nativeCtx.getTools()
           const tools = rawTools.map((t: any) => {
             let schemaObj: any = {}
             if (typeof t.inputSchema === 'string') {
@@ -67,19 +95,22 @@ export const setupBuiltinProxy = (transport: Transport) => {
         const nativeCtx = getNativeCtx()
         if (nativeCtx && nativeCtx.executeTool) {
           if (!message.params || typeof message.params !== 'object' || !message.params.name) {
-            const error: any = new Error('Invalid params: "name" is required and params must be an object')
+            const error: Error & { code?: number } = new Error('Invalid params: "name" is required and params must be an object')
             error.code = -32602 // Invalid params
             throw error
           }
           const { name, arguments: args } = message.params
-          const result = await nativeCtx.executeTool(name, JSON.stringify(args || {}))
+          const tools = await (nativeCtx.getTools ? nativeCtx.getTools() : [])
+          const toolObj = tools.find((t: any) => t.name === name)
+          if (!toolObj) throw new Error(`Tool ${name} not found`)
+          const result = await nativeCtx.executeTool(toolObj, JSON.stringify(args || {}))
           const finalResult =
             result && typeof result === 'object' && 'content' in result
               ? result
               : { content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }] }
           await transport.send({ jsonrpc: '2.0', id, result: finalResult })
         } else {
-          const error: any = new Error('executeTool not implemented in Browser built-in WebMCP')
+          const error: Error & { code?: number } = new Error('executeTool not implemented in Browser built-in WebMCP')
           error.code = -32601 // Method not found
           throw error
         }
@@ -99,12 +130,13 @@ export const setupBuiltinProxy = (transport: Transport) => {
           error: { code: -32601, message: `Method not found: ${method}` }
         })
       }
-    } catch (err: any) {
+    } catch (err: unknown) {
       if (id !== undefined) {
+        const errObj = err as { code?: number; message?: string }
         await transport.send({
           jsonrpc: '2.0',
           id,
-          error: { code: err.code || -32000, message: err.message || String(err) }
+          error: { code: errObj.code || -32000, message: errObj.message || String(err) }
         })
       }
     }

package/vite.config.runtime.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig(() => {
+  return {
+    define: {
+      'process.env.NODE_ENV': JSON.stringify('production')
+    },
+    build: {
+      emptyOutDir: false,
+      lib: {
+        entry: 'runtime.ts',
+        name: 'NextSDK',
+        formats: ['iife'] as any,
+        fileName: () => 'runtime.js'
+      },
+      rollupOptions: {
+        // 全量打包第三方依赖，便于浏览器中直接注入或运行
+        external: []
+      }
+    }
+  }
+})