@opentiny/next-sdk 0.2.6-beta.0 → 0.2.6-beta.2

package/dist/page-tool-bridge.d.ts

@@ -3,6 +3,24 @@ import { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { WebMcpServer } from './WebMcpServer';
 
+/** 页面卸载广播，供 routeBasedPageTools 模式监听 */
+export declare const MSG_PAGE_LEAVE = "next-sdk:page-leave";
+/** iframe 内 Remoter 就绪后向父窗口发送，父窗口回传 route-state-initial */
+export declare const MSG_REMOTER_READY = "next-sdk:remoter-ready";
+/** 父窗口向 iframe Remoter 回传的初始路由状态（toolRouteMap + activeRoutes） */
+export declare const MSG_ROUTE_STATE_INITIAL = "next-sdk:route-state-initial";
+/**
+ * 获取通过 withPageTools + RouteConfig 注册的全部工具路由映射。
+ * 返回的是内部 Map 的只读快照，可安全遍历。
+ * @returns toolName → route 的只读 Map
+ */
+export declare function getToolRouteMap(): ReadonlyMap<string, string>;
+/**
+ * 获取当前已激活（已挂载）的路由集合。
+ * 即调用了 registerPageTool 且尚未执行 cleanup 的页面路由。
+ * @returns 当前激活路由的 Set 快照
+ */
+export declare function getActiveRoutes(): Set<string>;
 /**
  * 注册应用的导航函数，通常在应用入口（如 main.ts）调用一次。
  * @param fn 导航函数，接收路由路径并执行跳转（如 router.push）
@@ -64,13 +82,17 @@ export declare function withPageTools(server: WebMcpServer): PageAwareServer;
  * 返回 cleanup 函数，页面销毁时调用。
  *
  * @example
- * // Vue（Composition API）
+ * // Vue（Composition API）— 省略 route，默认读 window.location.pathname
  * let cleanup: () => void
+ * onMounted(() => { cleanup = registerPageTool({ handlers: { ... } }) })
+ * onUnmounted(() => cleanup())
+ *
+ * // Vue — 当页面路由与 pathname 不一致时，手动指定 route
  * onMounted(() => { cleanup = registerPageTool({ route: '/comprehensive', handlers: { ... } }) })
  * onUnmounted(() => cleanup())
  *
  * // React（Hooks）
- * useEffect(() => registerPageTool({ route: '/comprehensive', handlers: { ... } }), [])
+ * useEffect(() => registerPageTool({ handlers: { ... } }), [])
  * // useEffect 直接返回 cleanup 函数，React 会在组件卸载时自动调用
  *
  * // Angular（实现 OnInit / OnDestroy 接口）
@@ -79,7 +101,6 @@ export declare function withPageTools(server: WebMcpServer): PageAwareServer;
  *
  *   ngOnInit(): void {
  *     this.cleanupPageTool = registerPageTool({
- *       route: '/price-protection',
  *       handlers: {
  *         'price-protection-query': async ({ status }) => { ... },
  *       }
@@ -92,6 +113,12 @@ export declare function withPageTools(server: WebMcpServer): PageAwareServer;
  * }
  */
 export declare function registerPageTool(options: {
+    /**
+     * 目标路由路径，与 RouteConfig.route 保持一致。
+     * 省略时自动读取 window.location.pathname。
+     * 当页面路由与 pathname 不一致时（如 hash 路由、子路径前缀等），需手动传入。
+     */
+    route?: string;
     /**
      * 工具名 → 处理函数的映射表。
      *

package/package.json

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

package/page-tool-bridge.ts

@@ -22,17 +22,21 @@
  *   // 或仍然使用普通回调（完全兼容）
  *   server.registerTool('simple-tool', { ... }, async (input) => { ... })
  *
- *   // 目标页面（Vue）
- *   onMounted(() => { cleanup = registerPageTool({ route, handlers }) })
+ *   // 目标页面（Vue）— route 可省略，默认取 window.location.pathname
+ *   onMounted(() => { cleanup = registerPageTool({ handlers }) })
+ *   onUnmounted(() => cleanup())
+ *
+ *   // 目标页面（Vue）— 当页面路由与 pathname 不一致时，手动指定 route
+ *   onMounted(() => { cleanup = registerPageTool({ route: '/my-page', handlers }) })
  *   onUnmounted(() => cleanup())
  *
  *   // 目标页面（React）
- *   useEffect(() => registerPageTool({ route, handlers }), [])
+ *   useEffect(() => registerPageTool({ handlers }), [])
  *
  *   // 目标页面（Angular）
  *   export class MyComponent implements OnInit, OnDestroy {
  *     private cleanupPageTool!: () => void
- *     ngOnInit() { this.cleanupPageTool = registerPageTool({ route, handlers }) }
+ *     ngOnInit() { this.cleanupPageTool = registerPageTool({ handlers }) }
  *     ngOnDestroy() { this.cleanupPageTool() }
  *   }
  *
@@ -66,10 +70,81 @@ import { randomUUID } from './utils/uuid'
 const MSG_TOOL_CALL = 'next-sdk:tool-call'
 const MSG_TOOL_RESPONSE = 'next-sdk:tool-response'
 const MSG_PAGE_READY = 'next-sdk:page-ready'
+/** 页面卸载广播，供 routeBasedPageTools 模式监听 */
+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>()
 
+// 跨窗口广播目标：同窗口默认 [window]，iframe 场景下会加入 remoter 的 contentWindow
+const broadcastTargets = new Set<Window>()
+
+function initBroadcastTargets() {
+  if (typeof window !== 'undefined') {
+    broadcastTargets.add(window)
+  }
+}
+initBroadcastTargets()
+
+/** 向所有广播目标发送路由变更消息（同窗口 + iframe 均能收到） */
+function broadcastRouteChange(type: string, route: string) {
+  const msg = { type, route }
+  const origin = window.location.origin || '*'
+  broadcastTargets.forEach((target) => {
+    try {
+      target.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
+    const target = event.source as Window
+    broadcastTargets.add(target)
+    const payload = {
+      type: MSG_ROUTE_STATE_INITIAL,
+      toolRouteMap: Array.from(toolRouteMap.entries()),
+      activeRoutes: Array.from(activePages.keys())
+    }
+    try {
+      target.postMessage(payload, window.location.origin || '*')
+    } catch {
+      // 忽略跨域错误
+    }
+  })
+}
+setupIframeRemoterBridge()
+
+// withPageTools 注册的工具路由映射表：工具名 → 目标路由
+const toolRouteMap = new Map<string, string>()
+
+/**
+ * 获取通过 withPageTools + RouteConfig 注册的全部工具路由映射。
+ * 返回的是内部 Map 的只读快照，可安全遍历。
+ * @returns toolName → route 的只读 Map
+ */
+export function getToolRouteMap(): ReadonlyMap<string, string> {
+  return 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
 
@@ -240,12 +315,16 @@ export function withPageTools(server: WebMcpServer): PageAwareServer {
       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 target.registerTool(name, config, handlerOrRoute as any)
+            return rawRegister(name, config, handlerOrRoute)
           }
-          // 第三个参数是路由配置对象 → 自动生成转发 handler
+          // 第三个参数是路由配置对象 → 自动生成转发 handler，并记录 tool → route 映射
           const { route, timeout } = handlerOrRoute
-          return target.registerTool(name, config, buildPageHandler(name, route, timeout) as any)
+          toolRouteMap.set(name, route)
+          return rawRegister(name, config, buildPageHandler(name, route, timeout))
         }
       }
       return Reflect.get(target, prop, receiver)
@@ -264,13 +343,17 @@ export function withPageTools(server: WebMcpServer): PageAwareServer {
  * 返回 cleanup 函数，页面销毁时调用。
  *
  * @example
- * // Vue（Composition API）
+ * // Vue（Composition API）— 省略 route，默认读 window.location.pathname
  * let cleanup: () => void
+ * onMounted(() => { cleanup = registerPageTool({ handlers: { ... } }) })
+ * onUnmounted(() => cleanup())
+ *
+ * // Vue — 当页面路由与 pathname 不一致时，手动指定 route
  * onMounted(() => { cleanup = registerPageTool({ route: '/comprehensive', handlers: { ... } }) })
  * onUnmounted(() => cleanup())
  *
  * // React（Hooks）
- * useEffect(() => registerPageTool({ route: '/comprehensive', handlers: { ... } }), [])
+ * useEffect(() => registerPageTool({ handlers: { ... } }), [])
  * // useEffect 直接返回 cleanup 函数，React 会在组件卸载时自动调用
  *
  * // Angular（实现 OnInit / OnDestroy 接口）
@@ -279,7 +362,6 @@ export function withPageTools(server: WebMcpServer): PageAwareServer {
  *
  *   ngOnInit(): void {
  *     this.cleanupPageTool = registerPageTool({
- *       route: '/price-protection',
  *       handlers: {
  *         'price-protection-query': async ({ status }) => { ... },
  *       }
@@ -292,6 +374,12 @@ export function withPageTools(server: WebMcpServer): PageAwareServer {
  * }
  */
 export function registerPageTool(options: {
+  /**
+   * 目标路由路径，与 RouteConfig.route 保持一致。
+   * 省略时自动读取 window.location.pathname。
+   * 当页面路由与 pathname 不一致时（如 hash 路由、子路径前缀等），需手动传入。
+   */
+  route?: string
   /**
    * 工具名 → 处理函数的映射表。
    *
@@ -303,16 +391,19 @@ export function registerPageTool(options: {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   handlers: Record<string, (input: any) => Promise<any>>
 }): () => void {
-  const { handlers } = options
-  // 路由路径由运行时自动取当前页面地址，无需调用方手动传入
-  const route = window.location.pathname
+  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 ||
-      event.data?.route !== route ||
+      normalizeRoute(String(event.data?.route ?? '')) !== route ||
       !(event.data.toolName in handlers)
     ) {
       return
@@ -333,14 +424,15 @@ export function registerPageTool(options: {
     }
   }
 
-  // 注册页面为已激活状态并广播就绪信号
+  // 注册页面为已激活状态并广播就绪信号（同窗口 + iframe Remoter 均能收到）
   activePages.set(route, true)
   window.addEventListener('message', handleMessage)
-  window.postMessage({ type: MSG_PAGE_READY, route }, window.location.origin || '*')
+  broadcastRouteChange(MSG_PAGE_READY, route)
 
   // 返回 cleanup，由各框架在页面销毁时调用
   return () => {
     activePages.delete(route)
     window.removeEventListener('message', handleMessage)
+    broadcastRouteChange(MSG_PAGE_LEAVE, route)
   }
 }