@opentiny/next-sdk 0.2.6 → 0.2.8

package/index.ts

@@ -39,6 +39,9 @@ export { getAISDKTools } from './agent/utils/getAISDKTools'
 export { QrCode, type QrCodeOption } from './remoter/QrCode'
 export type * from './agent/type'
 
+// Web MCP 页面工具桥接：工具调用自动导航 + 页面消息通信
+export * from './page-tools/bridge'
+
 // Web 端 Skill 公共能力：解析 skill 文档、生成 systemPrompt、内置 list_skills / get_skill_content 工具
 export {
   getSkillOverviews,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentiny/next-sdk",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "type": "module",
   "homepage": "https://docs.opentiny.design/next-sdk/guide/",
   "repository": {

package/page-tools/bridge.ts

@@ -0,0 +1,382 @@
+/**
+ * page-tools/bridge - Web MCP 页面工具桥接模块（框架无关）
+ *
+ * 解决 Web-MCP 工具动态加载问题：工具定义（mcp-servers/）不直接写业务逻辑，
+ * 而是通过 window.postMessage 将调用转发给目标页面，页面处理后返回结果。
+ *
+ * 核心 API：
+ *   - setNavigator(fn)    在应用入口注册导航函数
+ *   - withPageTools(server)
+ *                         包装 WebMcpServer，让 registerTool 第三个参数
+ *                         同时支持原始回调函数和路由配置对象（RouteConfig）
+ *   - registerPageTool()  在目标页面激活工具处理器，返回 cleanup 函数
+ */
+
+import type { ZodRawShape } from 'zod'
+import type { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js'
+import type { WebMcpServer } from '../WebMcpServer'
+import { randomUUID } from '../utils/uuid'
+import type { ToolInvokeEffectConfig } from './effects'
+import { hideToolInvokeEffect, resolveRuntimeEffectConfig, showToolInvokeEffect } from './effects'
+
+// 消息类型常量，使用命名空间前缀避免冲突
+const MSG_TOOL_CALL = 'next-sdk:tool-call'
+const MSG_TOOL_RESPONSE = 'next-sdk:tool-response'
+const MSG_PAGE_READY = 'next-sdk:page-ready'
+/** 页面卸载广播，供 pageToolsOnDemand 模式监听 */
+export const MSG_PAGE_LEAVE = 'next-sdk:page-leave'
+/** iframe 内 Remoter 就绪后向父窗口发送，父窗口回传 route-state-initial */
+export const MSG_REMOTER_READY = 'next-sdk:remoter-ready'
+/** 父窗口向 iframe Remoter 回传的初始路由状态（toolRouteMap + activeRoutes） */
+export const MSG_ROUTE_STATE_INITIAL = 'next-sdk:route-state-initial'
+
+// 已激活页面注册表：路由路径 → 是否已挂载
+const activePages = new Map<string, boolean>()
+
+type BroadcastTarget = { win: Window; origin: string }
+
+// 跨窗口广播目标：同窗口默认 [window]，iframe 场景下会加入 remoter 的 contentWindow
+const broadcastTargets = new Set<BroadcastTarget>()
+
+function initBroadcastTargets() {
+  if (typeof window !== 'undefined') {
+    broadcastTargets.add({ win: window, origin: window.location.origin || '*' })
+  }
+}
+initBroadcastTargets()
+
+/** 向所有广播目标发送路由变更消息（同窗口 + iframe 均能收到） */
+function broadcastRouteChange(type: string, route: string) {
+  const msg = { type, route }
+  broadcastTargets.forEach(({ win, origin }) => {
+    try {
+      win.postMessage(msg, origin)
+    } catch {
+      // 跨域 iframe 可能抛错，忽略
+    }
+  })
+}
+
+/** 监听 iframe 内 Remoter 的 remoter-ready，回传初始路由状态并加入广播目标 */
+function setupIframeRemoterBridge() {
+  if (typeof window === 'undefined') return
+  window.addEventListener('message', (event: MessageEvent) => {
+    if (event.data?.type !== MSG_REMOTER_READY || !event.source) return
+    // 仅接受与当前页面同源的 remoter，避免潜在的 XSS 风险
+    if (event.origin !== window.location.origin) return
+    const target = event.source as Window
+    broadcastTargets.add({ win: target, origin: event.origin || '*' })
+    const payload = {
+      type: MSG_ROUTE_STATE_INITIAL,
+      toolRouteMap: Array.from(toolRouteMap.entries()),
+      activeRoutes: Array.from(activePages.keys())
+    }
+    try {
+      target.postMessage(payload, event.origin || '*')
+    } catch {
+      // 忽略跨域错误
+    }
+  })
+}
+setupIframeRemoterBridge()
+
+// withPageTools 注册的工具路由映射表：工具名 → 目标路由
+const toolRouteMap = new Map<string, string>()
+
+/**
+ * 获取通过 withPageTools + RouteConfig 注册的全部工具路由映射。
+ * 返回的是内部 Map 的只读快照，可安全遍历。
+ * @returns toolName → route 的只读 Map
+ */
+export function getToolRouteMap(): ReadonlyMap<string, string> {
+  return new Map(toolRouteMap)
+}
+
+/**
+ * 获取当前已激活（已挂载）的路由集合。
+ * 即调用了 registerPageTool 且尚未执行 cleanup 的页面路由。
+ * @returns 当前激活路由的 Set 快照
+ */
+export function getActiveRoutes(): Set<string> {
+  return new Set(activePages.keys())
+}
+
+// 应用注册的导航函数，由 setNavigator 设置
+let _navigator: ((route: string) => void | Promise<void>) | null = null
+
+/**
+ * 注册应用的导航函数，通常在应用入口（如 main.ts）调用一次。
+ * @param fn 导航函数，接收路由路径并执行跳转（如 router.push）
+ */
+export function setNavigator(fn: (route: string) => void | Promise<void>) {
+  _navigator = fn
+}
+
+/**
+ * registerTool 第三个参数的路由配置对象类型。
+ * 当传入此类型时，工具调用会自动跳转到 route 对应的页面并通过消息通信执行。
+ */
+export type RouteConfig = {
+  /** 目标路由路径，如 '/comprehensive' */
+  route: string
+  /** 等待页面响应的超时时间（ms），默认 30000 */
+  timeout?: number
+  /**
+   * 是否在调用该工具时启用页面级调用提示效果。
+   *
+   * - false / 未配置：不启用任何额外效果（保持现有行为）
+   * - true：使用默认提示文案（优先取工具标题，其次为工具名）
+   * - 对象：可自定义提示文案
+   */
+  invokeEffect?: boolean | ToolInvokeEffectConfig
+}
+
+// 对外暴露调用提示配置类型，便于业务方在 RouteConfig 外单独复用
+export type { ToolInvokeEffectConfig }
+
+/**
+ * PageAwareServer 的 registerTool 配置对象类型，与 WebMcpServer.registerTool 保持一致。
+ */
+type RegisterToolConfig<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape> = {
+  title?: string
+  description?: string
+  inputSchema?: InputArgs
+  outputSchema?: OutputArgs
+  annotations?: ToolAnnotations
+}
+
+/**
+ * 包装 WebMcpServer 后的类型：registerTool 第三个参数额外支持 RouteConfig。
+ * 泛型签名与 WebMcpServer.registerTool 对齐，保持完整的类型推导能力。
+ * 原有的回调函数写法完全兼容，无需改动。
+ */
+export type PageAwareServer = Omit<WebMcpServer, 'registerTool'> & {
+  registerTool<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape>(
+    name: string,
+    config: RegisterToolConfig<InputArgs, OutputArgs>,
+    // handler 不引入 ToolCallback<InputArgs>：该类型含 MCP SDK 深层泛型，
+    // 叠加 ZodRawShape 推断链后会触发"类型实例化过深"。
+    // 实际类型安全由 Proxy 内部透传给 WebMcpServer.registerTool 保证。
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handlerOrRoute: ((...args: any[]) => any) | RouteConfig
+  ): RegisteredTool
+}
+
+/**
+ * 内部：根据 name/route/timeout 生成转发给页面的 handler 函数。
+ * 调用流程：
+ * 1. 若目标路由已激活 → 直接 postMessage 发送工具调用
+ * 2. 若未激活 → 调用导航函数跳转，等待 page-ready 信号后再发送
+ * 3. 页面处理后回传结果，Promise resolve
+ */
+function buildPageHandler(
+  name: string,
+  route: string,
+  timeout = 30000,
+  effectConfig?: ReturnType<typeof resolveRuntimeEffectConfig>
+) {
+  return (input: any): Promise<any> => {
+    const callId = randomUUID()
+
+    return new Promise<any>((resolve, reject) => {
+      let timer: ReturnType<typeof setTimeout>
+      // readyHandler 需在 cleanup 中一并移除，避免导航失败时泄漏监听器
+      let readyHandler: ((event: MessageEvent) => void) | undefined
+
+      const cleanup = () => {
+        clearTimeout(timer)
+        window.removeEventListener('message', responseHandler)
+        if (readyHandler) {
+          window.removeEventListener('message', readyHandler)
+        }
+        // 工具调用完成（成功 / 失败 / 超时 / 导航异常）后，无论结果如何都需要关闭调用提示效果
+        if (effectConfig) {
+          hideToolInvokeEffect()
+        }
+      }
+
+      // 超时兜底，防止页面永远不响应
+      timer = setTimeout(() => {
+        cleanup()
+        reject(new Error(`工具 [${name}] 调用超时 (${timeout}ms)，请检查目标页面是否正确调用了 registerPageTool`))
+      }, timeout)
+
+      // 通过 callId 精确匹配响应，避免并发调用互相串扰
+      const responseHandler = (event: MessageEvent) => {
+        if (event.source === window && event.data?.type === MSG_TOOL_RESPONSE && event.data.callId === callId) {
+          cleanup()
+          event.data.error ? reject(new Error(event.data.error)) : resolve(event.data.result)
+        }
+      }
+      window.addEventListener('message', responseHandler)
+
+      const sendCall = () => {
+        window.postMessage({ type: MSG_TOOL_CALL, callId, toolName: name, route, input }, window.location.origin || '*')
+      }
+
+      // 单次发送守卫：readyHandler 与导航后 activePages 补充检查均可触发 sendCall，
+      // 用此 flag 确保同一次工具调用只发送一条消息，防止工具被重复执行。
+      let callSent = false
+      const sendCallOnce = () => {
+        if (callSent) return
+        callSent = true
+        sendCall()
+      }
+
+      // 将异步导航逻辑提取为独立 run 函数并用 void 调用，
+      // 避免在 Promise executor 中直接使用 async（Biome noAsyncPromiseExecutor 规则）。
+      // 导航失败时显式 reject，防止外层 Promise 永远挂起。
+      const run = async () => {
+        try {
+          // 一旦真正发起工具调用（无论页面是否已激活），优先开启页面调用提示效果
+          if (effectConfig) {
+            showToolInvokeEffect(effectConfig)
+          }
+
+          if (activePages.get(route)) {
+            // 页面已激活，直接发送
+            sendCallOnce()
+            return
+          }
+
+          // ⚠️ 必须先注册 readyHandler 再触发导航：
+          // 若先导航再注册，极快的导航（同步或微任务）可能导致
+          // 目标页面已广播 page-ready 而监听器尚未挂载，从而错过信号。
+          readyHandler = (event: MessageEvent) => {
+            if (event.source === window && event.data?.type === MSG_PAGE_READY && event.data.route === route) {
+              window.removeEventListener('message', readyHandler!)
+              sendCallOnce()
+            }
+          }
+          window.addEventListener('message', readyHandler)
+
+          if (_navigator) {
+            await _navigator(route)
+          }
+
+          // 导航 await 完成后，再次检查 activePages：
+          // 若页面在注册监听器与导航之间极短间隙内已激活（极端竞态），
+          // message 事件已被 handleMessage 消费但 readyHandler 未执行，
+          // 此处补充检查确保不会永久等待。
+          // sendCallOnce 保证即使两条路径都触发，消息也只发送一次。
+          if (activePages.get(route)) {
+            window.removeEventListener('message', readyHandler)
+            sendCallOnce()
+          }
+        } catch (err) {
+          // 导航本身抛出异常时，确保 Promise 被 reject 而非永远挂起
+          cleanup()
+          reject(err instanceof Error ? err : new Error(String(err)))
+        }
+      }
+      void run()
+    })
+  }
+}
+
+/**
+ * 包装 WebMcpServer，使 registerTool 第三个参数支持 RouteConfig。
+ *
+ * - 第三个参数为**回调函数**：与原始 registerTool 完全一致，直接透传
+ * - 第三个参数为 **RouteConfig 对象**：自动生成转发 handler，工具调用时
+ *   先导航到目标路由，再通过 postMessage 与页面通信
+ */
+export function withPageTools(server: WebMcpServer): PageAwareServer {
+  return new Proxy(server, {
+    get(target, prop, receiver) {
+      if (prop === 'registerTool') {
+        return (name: string, config: any, handlerOrRoute: ((...args: any[]) => any) | RouteConfig) => {
+          // 第三个参数是函数 → 直接透传，行为与原始 registerTool 完全相同
+          // 通过 (target as any) 避免 WebMcpServer.registerTool 深层泛型触发"类型实例化过深"
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const rawRegister = (target as any).registerTool.bind(target)
+          if (typeof handlerOrRoute === 'function') {
+            return rawRegister(name, config, handlerOrRoute)
+          }
+          // 第三个参数是路由配置对象 → 自动生成转发 handler，并记录 tool → route 映射
+          const { route, timeout, invokeEffect } = handlerOrRoute
+          toolRouteMap.set(name, route)
+          const effectConfig = resolveRuntimeEffectConfig(name, config?.title, invokeEffect)
+          return rawRegister(name, config, buildPageHandler(name, route, timeout, effectConfig))
+        }
+      }
+      return Reflect.get(target, prop, receiver)
+    }
+  }) as unknown as PageAwareServer
+}
+
+/**
+ * 在目标页面激活工具处理器（框架无关的纯 JS 函数）。
+ *
+ * 调用后立即：
+ * - 将路由注册到 activePages（标记页面已激活）
+ * - 添加 message 监听，处理来自 buildPageHandler 的工具调用
+ * - 广播 page-ready 信号，通知正在等待导航完成的工具
+ *
+ * 返回 cleanup 函数，页面销毁时调用。
+ */
+export function registerPageTool(options: {
+  /**
+   * 目标路由路径，与 RouteConfig.route 保持一致。
+   * 省略时自动读取 window.location.pathname。
+   * 当页面路由与 pathname 不一致时（如 hash 路由、子路径前缀等），需手动传入。
+   */
+  route?: string
+  /**
+   * 工具名 → 处理函数的映射表。
+   *
+   * 此处 handler 的 input 参数类型保留 any：
+   * 若改为 unknown，TypeScript 函数参数逆变规则会导致用户的具名解构写法
+   *（如 `async ({ productId }: { productId: string }) => ...`）无法通过类型检查，
+   * 破坏现有调用方代码的开发体验。运行时输入由 MCP inputSchema 保证类型安全。
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  handlers: Record<string, (input: any) => Promise<any>>
+}): () => void {
+  const { route: routeOption, handlers } = options
+  // 规范化路由：去除尾部斜杠，空路径兜底为 '/'，确保与 buildPageHandler 侧一致
+  // 优先使用用户传入的 route，否则回退到 window.location.pathname
+  const normalizeRoute = (value: string) => value.replace(/\/+$/, '') || '/'
+  const route = normalizeRoute(routeOption ?? window.location.pathname)
+
+  const handleMessage = async (event: MessageEvent) => {
+    // 同时校验 route 字段，防止多页面注册同名工具时发生跨路由串扰
+    // 对消息携带的 route 同样规范化，避免因尾部斜杠等差异导致匹配失败
+    if (
+      event.source !== window ||
+      event.data?.type !== MSG_TOOL_CALL ||
+      normalizeRoute(String(event.data?.route ?? '')) !== route ||
+      !(event.data.toolName in handlers)
+    ) {
+      return
+    }
+    const { callId, toolName, input } = event.data
+    try {
+      const result = await handlers[toolName](input)
+      window.postMessage({ type: MSG_TOOL_RESPONSE, callId, result }, window.location.origin || '*')
+    } catch (err) {
+      window.postMessage(
+        {
+          type: MSG_TOOL_RESPONSE,
+          callId,
+          error: err instanceof Error ? err.message : String(err)
+        },
+        window.location.origin || '*'
+      )
+    }
+  }
+
+  // 注册页面为已激活状态并广播就绪信号（同窗口 + iframe Remoter 均能收到）
+  activePages.set(route, true)
+  window.addEventListener('message', handleMessage)
+  broadcastRouteChange(MSG_PAGE_READY, route)
+
+  // 返回 cleanup，由各框架在页面销毁时调用
+  return () => {
+    activePages.delete(route)
+    window.removeEventListener('message', handleMessage)
+    broadcastRouteChange(MSG_PAGE_LEAVE, route)
+  }
+}
+