@opentiny/next-sdk 0.2.8 → 0.2.10

package/package.json

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

package/page-tools/bridge.ts

@@ -13,6 +13,7 @@
  */
 
 import type { ZodRawShape } from 'zod'
+import { z } from 'zod'
 import type { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js'
 import type { WebMcpServer } from '../WebMcpServer'
@@ -34,6 +35,9 @@ export const MSG_ROUTE_STATE_INITIAL = 'next-sdk:route-state-initial'
 // 已激活页面注册表：路由路径 → 是否已挂载
 const activePages = new Map<string, boolean>()
 
+// 路由路径规范化：去除尾部斜杠，空路径兜底为 '/'
+const normalizeRoute = (value: string) => value.replace(/\/+$/, '') || '/'
+
 type BroadcastTarget = { win: Window; origin: string }
 
 // 跨窗口广播目标：同窗口默认 [window]，iframe 场景下会加入 remoter 的 contentWindow
@@ -113,6 +117,42 @@ export function setNavigator(fn: (route: string) => void | Promise<void>) {
   _navigator = fn
 }
 
+/**
+ * 等待指定路由页面完成挂载并广播 page-ready。
+ * - 仅在浏览器环境下生效（window 存在时）
+ * - 使用与 registerPageTool 相同的路由规范化规则
+ * - 内置兜底超时，防止 Promise 永远不 resolve
+ */
+function waitForPageReady(path: string, timeoutMs = 1500): Promise<void> {
+  if (typeof window === 'undefined') {
+    return Promise.resolve()
+  }
+
+  const target = normalizeRoute(path)
+
+  return new Promise<void>((resolve) => {
+    let done = false
+
+    const cleanup = () => {
+      if (done) return
+      done = true
+      window.removeEventListener('message', handleMessage)
+      resolve()
+    }
+
+    const handleMessage = (event: MessageEvent) => {
+      if (event.source !== window || event.data?.type !== MSG_PAGE_READY) return
+      const route = normalizeRoute(String(event.data.route ?? ''))
+      if (route === target) {
+        cleanup()
+      }
+    }
+
+    window.addEventListener('message', handleMessage)
+    setTimeout(cleanup, timeoutMs)
+  })
+}
+
 /**
  * registerTool 第三个参数的路由配置对象类型。
  * 当传入此类型时，工具调用会自动跳转到 route 对应的页面并通过消息通信执行。
@@ -163,6 +203,100 @@ export type PageAwareServer = Omit<WebMcpServer, 'registerTool'> & {
   ): RegisteredTool
 }
 
+/**
+ * 注册一个通用的页面跳转工具（navigate_to_page），供大模型在需要时主动跳转到指定路由。
+ *
+ * 要求：
+ * - 业务侧在应用入口通过 setNavigator 注册导航函数（如 router.push 或 navigateByUrl）
+ * - 前端页面在目标路由下调用 registerPageTool，确保 page-ready 能正确广播
+ *
+ * 工具行为：
+ * - 输入 path（如 "/orders"、"/price-protection"），调用 setNavigator 注册的函数执行跳转
+ * - 等待目标页面完成挂载并广播 page-ready（或在超时时间到达时兜底返回）
+ * - 返回简单的文本说明，提示跳转结果
+ */
+export type NavigateToolOptions = {
+  /** 工具名称，默认 'navigate_to_page' */
+  name?: string
+  /** 工具标题，默认 '页面跳转' */
+  title?: string
+  /** 工具描述 */
+  description?: string
+  /** 等待 page-ready 的超时时间（ms），默认 1500 */
+  timeoutMs?: number
+}
+
+export function registerNavigateTool(server: WebMcpServer, options?: NavigateToolOptions): RegisteredTool {
+  const name = options?.name ?? 'navigate_to_page'
+  const title = options?.title ?? '页面跳转'
+  const description =
+    options?.description ??
+    '当需要的工具在当前页面不可用时，使用此工具跳转到特定页面。例如：要查询订单时跳转到 "/orders"，要创建价保时跳转到 "/price-protection"。'
+  const timeoutMs = options?.timeoutMs ?? 1500
+
+  return server.registerTool(
+    name,
+    {
+      title,
+      description,
+      inputSchema: {
+        path: z.string().describe('目标页面的路由地址，例如 "/orders"、"/inventory"、"/price-protection" 等。')
+      }
+    },
+    async ({ path }: { path: string }) => {
+      if (typeof window === 'undefined') {
+        return {
+          content: [{ type: 'text', text: '当前环境不支持页面跳转（window 不存在）。' }]
+        }
+      }
+
+      if (!_navigator) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: '页面跳转失败：尚未在应用入口调用 setNavigator 注册导航函数，无法执行路由跳转。'
+            }
+          ]
+        }
+      }
+
+      try {
+        const target = normalizeRoute(path)
+        // 若当前已在目标路由上，直接返回成功，避免不必要的跳转。
+        // 兼容子路径部署（如 base: '/ai-vue/'）：pathname 可能为 /ai-vue/orders，而 path 为 /orders，需判断 pathname 是否“以目标路由结尾”
+        const current = normalizeRoute(window.location.pathname)
+        const isAlreadyOnTarget =
+          current === target ||
+          (current.endsWith(target) && (current.length === target.length || current[current.lastIndexOf(target) - 1] === '/'))
+        if (isAlreadyOnTarget) {
+          return {
+            content: [{ type: 'text', text: `当前已在页面：${path}。请继续你的下一步操作。` }]
+          }
+        }
+
+        // 先注册 page-ready 监听再触发导航，避免极快导航下事件先于监听器触发而漏收（与 buildPageHandler 中的顺序一致）
+        const readyPromise = waitForPageReady(path, timeoutMs)
+        await _navigator(path)
+        await readyPromise
+
+        return {
+          content: [{ type: 'text', text: `已成功跳转至页面：${path}。请继续你的下一步操作。` }]
+        }
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `页面跳转失败：${err instanceof Error ? err.message : String(err)}。`
+            }
+          ]
+        }
+      }
+    }
+  )
+}
+
 /**
  * 内部：根据 name/route/timeout 生成转发给页面的 handler 函数。
  * 调用流程：

package/remoter/createRemoter.ts

@@ -146,30 +146,33 @@ class FloatingBlock {
 
   /**
    * 合并菜单项配置。
-   * - 有 sessionId：使用默认菜单 + 用户配置（可定制每一项的 show/text/icon 等）
-   * - 无 sessionId：不渲染任何下拉菜单，仅保留点击浮标打开对话框的能力
+   * - 用户明确传入 menuItems：直接使用用户配置，不受 sessionId 限制；未传 icon 时自动补充默认图标
+   * - 有 sessionId 且未传 menuItems：使用默认菜单
+   * - 无 sessionId 且未传 menuItems：不渲染任何下拉菜单，仅保留点击浮标打开对话框的能力
    */
   private mergeMenuItems(userMenuItems?: MenuItemConfig[]): MenuItemConfig[] {
-    // 无 sessionId：完全关闭下拉菜单（包括 ai-chat 项），只保留点击浮标触发 onShowAIChat
-    if (!this.options.sessionId) {
-      return []
+    // 各 action 对应的默认图标映射
+    const defaultIcons: Partial<Record<ActionType, string>> = {
+      'qr-code': qrCode,
+      'ai-chat': chat,
+      'remote-url': link,
+      'remote-control': scan
     }
 
-    if (!userMenuItems) {
-      return getDefaultMenuItems(this.options)
+    // 用户明确传入了 menuItems，直接使用，并补充缺失的图标
+    if (userMenuItems) {
+      return userMenuItems.map((item) => ({
+        ...item,
+        icon: item.icon ?? defaultIcons[item.action]
+      }))
     }
 
-    return getDefaultMenuItems(this.options).map((defaultItem) => {
-      const userItem = userMenuItems.find((item) => item.action === defaultItem.action)
-      if (userItem) {
-        return {
-          ...defaultItem,
-          ...userItem,
-          show: userItem.show !== undefined ? userItem.show : defaultItem.show
-        }
-      }
-      return defaultItem
-    })
+    // 无 sessionId 且无用户菜单：完全关闭下拉菜单，只保留点击浮标触发 onShowAIChat
+    if (!this.options.sessionId) {
+      return []
+    }
+
+    return getDefaultMenuItems(this.options)
   }
 
   private init(): void {
@@ -220,7 +223,7 @@ class FloatingBlock {
           <div class="tiny-remoter-dropdown-item__content">
             <div title="${item.tip}">${item.text}</div>
             <div class="tiny-remoter-dropdown-item__desc-wrapper">
-              <div class="tiny-remoter-dropdown-item__desc ${item.active ? 'tiny-remoter-dropdown-item__desc--active' : ''} ${item.know ? 'tiny-remoter-dropdown-item__desc--know' : ''}">${item.desc}</div>
+              <div class="tiny-remoter-dropdown-item__desc ${item.active ? 'tiny-remoter-dropdown-item__desc--active' : ''} ${item.know ? 'tiny-remoter-dropdown-item__desc--know' : ''}">${item.desc ?? ''}</div>
               <div>
                 ${
                   item.showCopyIcon
@@ -357,13 +360,31 @@ class FloatingBlock {
   }
 
   private copyRemoteControl(): void {
-    if (!this.options.sessionId) return
-    this.copyToClipboard(this.options.sessionId.slice(-6))
+    // 优先使用用户菜单项中的 desc/text（支持自定义识别码），回退到 sessionId 末 6 位
+    const menuItem = this.menuItems.find((item) => item.action === 'remote-control')
+    const codeToCopy =
+      menuItem?.desc || menuItem?.text || (this.options.sessionId ? this.options.sessionId.slice(-6) : '')
+    if (codeToCopy) {
+      this.copyToClipboard(codeToCopy)
+    }
   }
 
   private copyRemoteURL(): void {
-    if (!this.options.sessionId) return
-    this.copyToClipboard(this.options.remoteUrl + this.sessionPrefix + this.options.sessionId)
+    const menuItem = this.menuItems.find((item) => item.action === 'remote-url')
+
+    // 构造带 sessionId 的完整遥控链接（默认行为）
+    const sessionUrl = this.options.sessionId
+      ? this.options.remoteUrl + this.sessionPrefix + this.options.sessionId
+      : ''
+
+    // 仅当 desc 是用户真正自定义的值（不同于裸 remoteUrl）时才优先使用，
+    // 否则回退到带 sessionId 的完整链接，避免默认菜单场景复制裸域名
+    const customDesc = menuItem?.desc && menuItem.desc !== this.options.remoteUrl ? menuItem.desc : undefined
+    const urlToCopy = customDesc || sessionUrl || menuItem?.text || ''
+
+    if (urlToCopy) {
+      this.copyToClipboard(urlToCopy)
+    }
   }
 
   // 实现复制到剪贴板功能