@opentiny/next-sdk 0.2.7 → 0.2.8

package/{page-tool-bridge.ts → page-tools/bridge.ts}

@@ -1,5 +1,5 @@
 /**
- * page-tool-bridge - Web MCP 页面工具桥接模块（框架无关）
+ * page-tools/bridge - Web MCP 页面工具桥接模块（框架无关）
  *
  * 解决 Web-MCP 工具动态加载问题：工具定义（mcp-servers/）不直接写业务逻辑，
  * 而是通过 window.postMessage 将调用转发给目标页面，页面处理后返回结果。
@@ -10,61 +10,15 @@
  *                         包装 WebMcpServer，让 registerTool 第三个参数
  *                         同时支持原始回调函数和路由配置对象（RouteConfig）
  *   - registerPageTool()  在目标页面激活工具处理器，返回 cleanup 函数
- *
- * 使用方式：
- *   // mcp-servers/index.ts
- *   const server = withPageTools(new WebMcpServer())
- *
- *   // mcp-servers/product-guide/tools.ts
- *   server.registerTool('product-guide', { title, description, inputSchema },
- *     { route: '/comprehensive', timeout: 15000 }  // ← 路由配置：route 必填，timeout 可选（ms，默认 30000）
- *   )
- *   // 或仍然使用普通回调（完全兼容）
- *   server.registerTool('simple-tool', { ... }, async (input) => { ... })
- *
- *   // 目标页面（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({ handlers }), [])
- *
- *   // 目标页面（Angular）
- *   export class MyComponent implements OnInit, OnDestroy {
- *     private cleanupPageTool!: () => void
- *     ngOnInit() { this.cleanupPageTool = registerPageTool({ handlers }) }
- *     ngOnDestroy() { this.cleanupPageTool() }
- *   }
- *
- * setNavigator 在不同框架中的注册方式：
- *   // Vue（main.ts）
- *   const router = createRouter(...)
- *   app.use(router)
- *   setNavigator((route) => router.push(route))
- *
- *   // React（App.tsx，使用 react-router-dom）
- *   function AppNavigator() {
- *     const navigate = useNavigate()
- *     useEffect(() => { setNavigator((route) => navigate(route)) }, [navigate])
- *     return null
- *   }
- *
- *   // Angular（AppComponent，使用 @angular/router）
- *   export class AppComponent {
- *     constructor(private router: Router) {
- *       setNavigator((route) => this.router.navigateByUrl(route))
- *     }
- *   }
  */
+
 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 { 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'
@@ -168,8 +122,19 @@ export type RouteConfig = {
   route: string
   /** 等待页面响应的超时时间（ms），默认 30000 */
   timeout?: number
+  /**
+   * 是否在调用该工具时启用页面级调用提示效果。
+   *
+   * - false / 未配置：不启用任何额外效果（保持现有行为）
+   * - true：使用默认提示文案（优先取工具标题，其次为工具名）
+   * - 对象：可自定义提示文案
+   */
+  invokeEffect?: boolean | ToolInvokeEffectConfig
 }
 
+// 对外暴露调用提示配置类型，便于业务方在 RouteConfig 外单独复用
+export type { ToolInvokeEffectConfig }
+
 /**
  * PageAwareServer 的 registerTool 配置对象类型，与 WebMcpServer.registerTool 保持一致。
  */
@@ -205,7 +170,12 @@ export type PageAwareServer = Omit<WebMcpServer, 'registerTool'> & {
  * 2. 若未激活 → 调用导航函数跳转，等待 page-ready 信号后再发送
  * 3. 页面处理后回传结果，Promise resolve
  */
-function buildPageHandler(name: string, route: string, timeout = 30000) {
+function buildPageHandler(
+  name: string,
+  route: string,
+  timeout = 30000,
+  effectConfig?: ReturnType<typeof resolveRuntimeEffectConfig>
+) {
   return (input: any): Promise<any> => {
     const callId = randomUUID()
 
@@ -220,6 +190,10 @@ function buildPageHandler(name: string, route: string, timeout = 30000) {
         if (readyHandler) {
           window.removeEventListener('message', readyHandler)
         }
+        // 工具调用完成（成功 / 失败 / 超时 / 导航异常）后，无论结果如何都需要关闭调用提示效果
+        if (effectConfig) {
+          hideToolInvokeEffect()
+        }
       }
 
       // 超时兜底，防止页面永远不响应
@@ -255,6 +229,11 @@ function buildPageHandler(name: string, route: string, timeout = 30000) {
       // 导航失败时显式 reject，防止外层 Promise 永远挂起。
       const run = async () => {
         try {
+          // 一旦真正发起工具调用（无论页面是否已激活），优先开启页面调用提示效果
+          if (effectConfig) {
+            showToolInvokeEffect(effectConfig)
+          }
+
           if (activePages.get(route)) {
             // 页面已激活，直接发送
             sendCallOnce()
@@ -302,15 +281,6 @@ function buildPageHandler(name: string, route: string, timeout = 30000) {
  * - 第三个参数为**回调函数**：与原始 registerTool 完全一致，直接透传
  * - 第三个参数为 **RouteConfig 对象**：自动生成转发 handler，工具调用时
  *   先导航到目标路由，再通过 postMessage 与页面通信
- *
- * @example
- * const server = withPageTools(new WebMcpServer())
- *
- * // 路由模式：第三个参数传路由配置（route 必填，timeout 可选，单位 ms，默认 30000）
- * server.registerTool('product-guide', { title, inputSchema }, { route: '/comprehensive', timeout: 15000 })
- *
- * // 普通模式：第三个参数传回调（兼容原有写法）
- * server.registerTool('simple-tool', { title }, async (input) => ({ content: [...] }))
  */
 export function withPageTools(server: WebMcpServer): PageAwareServer {
   return new Proxy(server, {
@@ -325,9 +295,10 @@ export function withPageTools(server: WebMcpServer): PageAwareServer {
             return rawRegister(name, config, handlerOrRoute)
           }
           // 第三个参数是路由配置对象 → 自动生成转发 handler，并记录 tool → route 映射
-          const { route, timeout } = handlerOrRoute
+          const { route, timeout, invokeEffect } = handlerOrRoute
           toolRouteMap.set(name, route)
-          return rawRegister(name, config, buildPageHandler(name, route, timeout))
+          const effectConfig = resolveRuntimeEffectConfig(name, config?.title, invokeEffect)
+          return rawRegister(name, config, buildPageHandler(name, route, timeout, effectConfig))
         }
       }
       return Reflect.get(target, prop, receiver)
@@ -344,37 +315,6 @@ export function withPageTools(server: WebMcpServer): PageAwareServer {
  * - 广播 page-ready 信号，通知正在等待导航完成的工具
  *
  * 返回 cleanup 函数，页面销毁时调用。
- *
- * @example
- * // 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({ handlers: { ... } }), [])
- * // useEffect 直接返回 cleanup 函数，React 会在组件卸载时自动调用
- *
- * // Angular（实现 OnInit / OnDestroy 接口）
- * export class PriceProtectionComponent implements OnInit, OnDestroy {
- *   private cleanupPageTool!: () => void
- *
- *   ngOnInit(): void {
- *     this.cleanupPageTool = registerPageTool({
- *       handlers: {
- *         'price-protection-query': async ({ status }) => { ... },
- *       }
- *     })
- *   }
- *
- *   ngOnDestroy(): void {
- *     this.cleanupPageTool()
- *   }
- * }
  */
 export function registerPageTool(options: {
   /**
@@ -439,3 +379,4 @@ export function registerPageTool(options: {
     broadcastRouteChange(MSG_PAGE_LEAVE, route)
   }
 }
+

package/page-tools/effects.ts

@@ -0,0 +1,343 @@
+/**
+ * page-tools/effects - 页面工具调用提示效果模块（框架无关）
+ *
+ * 作用：
+ * - 在调用通过 withPageTools 注册的页面工具时，显示页面级的调用状态提示
+ * - 以左下角小 tip 形式展示“当前正在调用的工具”文案，尽量不打扰用户操作
+ * - 纯 DOM + CSS 实现，不依赖 Vue/React 等框架
+ */
+
+export type ToolInvokeEffectConfig = {
+  /**
+   * 自定义提示文案，默认使用“工具标题 || 工具名称”
+   * 例如："正在为你整理订单数据"
+   */
+  label?: string
+}
+
+type RuntimeEffectConfig = {
+  label: string
+}
+
+let overlayElement: HTMLDivElement | null = null
+let labelElement: HTMLDivElement | null = null
+let styleElement: HTMLStyleElement | null = null
+let activeCount = 0
+
+const BODY_GLOW_CLASS = 'next-sdk-tool-body-glow'
+
+function ensureDomReady() {
+  return typeof window !== 'undefined' && typeof document !== 'undefined'
+}
+
+function ensureStyleElement() {
+  if (!ensureDomReady()) return
+  if (styleElement) return
+
+  const style = document.createElement('style')
+  style.textContent = `
+  .${BODY_GLOW_CLASS} {
+    position: relative;
+  }
+
+  .next-sdk-tool-overlay {
+    position: fixed;
+    inset: 0;
+    z-index: 999999;
+    pointer-events: none;
+    display: flex;
+    align-items: flex-end;
+    justify-content: flex-start;
+    padding: 0 0 18px 18px;
+    background: transparent;
+    animation: next-sdk-overlay-fade-in 260ms ease-out;
+  }
+
+  .next-sdk-tool-overlay--exit {
+    animation: next-sdk-overlay-fade-out 220ms ease-in forwards;
+  }
+
+  .next-sdk-tool-overlay__glow-ring {
+    display: none;
+  }
+
+  .next-sdk-tool-overlay__panel {
+    position: relative;
+    min-width: min(320px, 78vw);
+    max-width: min(420px, 82vw);
+    padding: 10px 14px;
+    border-radius: 999px;
+    background:
+      linear-gradient(135deg, rgba(15, 23, 42, 0.9), rgba(17, 24, 39, 0.9)),
+      radial-gradient(circle at top left, rgba(96, 165, 250, 0.25), transparent 55%),
+      radial-gradient(circle at bottom right, rgba(45, 212, 191, 0.22), transparent 60%);
+    box-shadow:
+      0 12px 28px rgba(15, 23, 42, 0.78),
+      0 0 0 1px rgba(148, 163, 184, 0.26);
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    pointer-events: none;
+    transform-origin: center;
+    animation: next-sdk-panel-pop-in 260ms cubic-bezier(0.18, 0.89, 0.32, 1.28);
+    color: #e5e7eb;
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+  }
+
+  .next-sdk-tool-overlay__indicator {
+    width: 26px;
+    height: 26px;
+    border-radius: 999px;
+    background: radial-gradient(circle at 30% 10%, #f9fafb, #93c5fd);
+    box-shadow:
+      0 0 0 1px rgba(191, 219, 254, 0.6),
+      0 8px 18px rgba(37, 99, 235, 0.8),
+      0 0 28px rgba(56, 189, 248, 0.9);
+    position: relative;
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+  }
+
+  .next-sdk-tool-overlay__indicator-orbit {
+    position: absolute;
+    inset: 2px;
+    border-radius: inherit;
+    border: 1px solid rgba(248, 250, 252, 0.6);
+    box-sizing: border-box;
+    opacity: 0.9;
+  }
+
+  .next-sdk-tool-overlay__indicator-orbit::before {
+    content: '';
+    position: absolute;
+    width: 6px;
+    height: 6px;
+    border-radius: 999px;
+    background: #f9fafb;
+    box-shadow:
+      0 0 12px rgba(248, 250, 252, 0.9),
+      0 0 24px rgba(250, 249, 246, 0.9);
+    top: 0;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    transform-origin: 50% 18px;
+    animation: next-sdk-indicator-orbit 1.4s linear infinite;
+  }
+
+  .next-sdk-tool-overlay__indicator-core {
+    width: 14px;
+    height: 14px;
+    border-radius: inherit;
+    background: radial-gradient(circle at 30% 20%, #f9fafb, #bfdbfe);
+    box-shadow:
+      0 0 12px rgba(248, 250, 252, 0.9),
+      0 0 32px rgba(191, 219, 254, 0.8);
+    opacity: 0.96;
+  }
+
+  .next-sdk-tool-overlay__content {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-width: 0;
+  }
+
+  .next-sdk-tool-overlay__title {
+    font-size: 11px;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: rgba(156, 163, 175, 0.96);
+    display: flex;
+    align-items: center;
+    gap: 6px;
+  }
+
+  .next-sdk-tool-overlay__title-dot {
+    width: 6px;
+    height: 6px;
+    border-radius: 999px;
+    background: #22c55e;
+    box-shadow:
+      0 0 8px rgba(34, 197, 94, 0.9),
+      0 0 14px rgba(22, 163, 74, 0.9);
+  }
+
+  .next-sdk-tool-overlay__label {
+    font-size: 12px;
+    font-weight: 500;
+    color: #e5e7eb;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    overflow: hidden;
+  }
+
+  @keyframes next-sdk-overlay-fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+
+  @keyframes next-sdk-overlay-fade-out {
+    from { opacity: 1; }
+    to { opacity: 0; }
+  }
+
+  @keyframes next-sdk-indicator-orbit {
+    from {
+      transform: translate(-50%, -50%) rotate(0deg) translateY(0);
+    }
+    to {
+      transform: translate(-50%, -50%) rotate(360deg) translateY(0);
+    }
+  }
+
+  @keyframes next-sdk-panel-pop-in {
+    0% {
+      opacity: 0;
+      transform: scale(0.92) translateY(10px);
+    }
+    100% {
+      opacity: 1;
+      transform: scale(1) translateY(0);
+    }
+  }
+  `
+
+  document.head.appendChild(style)
+  styleElement = style
+}
+
+function ensureOverlayElement() {
+  if (!ensureDomReady()) return
+  if (overlayElement) return
+
+  ensureStyleElement()
+
+  const overlay = document.createElement('div')
+  overlay.className = 'next-sdk-tool-overlay'
+
+  const glowRing = document.createElement('div')
+  glowRing.className = 'next-sdk-tool-overlay__glow-ring'
+
+  const panel = document.createElement('div')
+  panel.className = 'next-sdk-tool-overlay__panel'
+
+  const indicator = document.createElement('div')
+  indicator.className = 'next-sdk-tool-overlay__indicator'
+
+  const indicatorOrbit = document.createElement('div')
+  indicatorOrbit.className = 'next-sdk-tool-overlay__indicator-orbit'
+
+  const indicatorCore = document.createElement('div')
+  indicatorCore.className = 'next-sdk-tool-overlay__indicator-core'
+
+  const content = document.createElement('div')
+  content.className = 'next-sdk-tool-overlay__content'
+
+  const titleRow = document.createElement('div')
+  titleRow.className = 'next-sdk-tool-overlay__title'
+  titleRow.textContent = 'AI 正在调用页面工具'
+
+  const titleDot = document.createElement('span')
+  titleDot.className = 'next-sdk-tool-overlay__title-dot'
+
+  const label = document.createElement('div')
+  label.className = 'next-sdk-tool-overlay__label'
+
+  titleRow.prepend(titleDot)
+  content.appendChild(titleRow)
+  content.appendChild(label)
+
+  indicator.appendChild(indicatorOrbit)
+  indicator.appendChild(indicatorCore)
+  panel.appendChild(indicator)
+  panel.appendChild(content)
+  overlay.appendChild(glowRing)
+  overlay.appendChild(panel)
+
+  document.body.appendChild(overlay)
+
+  overlayElement = overlay
+  labelElement = label
+}
+
+function updateOverlay(config: RuntimeEffectConfig) {
+  if (!ensureDomReady()) return
+  ensureOverlayElement()
+  if (!overlayElement || !labelElement) return
+  overlayElement.classList.remove('next-sdk-tool-overlay--exit')
+  labelElement.textContent = config.label
+}
+
+function removeOverlayWithAnimation() {
+  if (!overlayElement) return
+  overlayElement.classList.add('next-sdk-tool-overlay--exit')
+  const localOverlay = overlayElement
+  let handled = false
+  let timerId: ReturnType<typeof setTimeout> | undefined
+  const handle = () => {
+    if (handled) return
+    handled = true
+    if (timerId !== undefined) {
+      clearTimeout(timerId)
+      timerId = undefined
+    }
+    if (localOverlay.parentNode) {
+      localOverlay.parentNode.removeChild(localOverlay)
+    }
+    if (overlayElement === localOverlay) {
+      overlayElement = null
+      labelElement = null
+    }
+    localOverlay.removeEventListener('animationend', handle)
+  }
+  localOverlay.addEventListener('animationend', handle)
+  // 兜底：若 animationend 未触发（如 prefers-reduced-motion 或样式被覆盖），确保清理
+  timerId = setTimeout(handle, 500)
+}
+
+/**
+ * 在页面上显示工具调用提示效果。
+ * - 若当前已有其他工具在执行，仅更新文案，不重复创建 DOM
+ * - 会增加 activeCount 计数，需配对调用 hideToolInvokeEffect
+ */
+export function showToolInvokeEffect(config: RuntimeEffectConfig) {
+  if (!ensureDomReady()) return
+  activeCount += 1
+  updateOverlay(config)
+}
+
+/**
+ * 隐藏工具调用提示效果。
+ * - 使用引用计数：只有当所有调用结束后才真正移除 Overlay
+ */
+export function hideToolInvokeEffect() {
+  if (!ensureDomReady() || activeCount <= 0) return
+  activeCount -= 1
+  if (activeCount === 0) {
+    removeOverlayWithAnimation()
+  }
+}
+
+/**
+ * 将 RouteConfig 中的 invokeEffect 配置编译成运行时效果配置。
+ * - boolean / undefined：关闭或开启默认文案
+ * - 对象：允许自定义 label
+ */
+export function resolveRuntimeEffectConfig(
+  toolName: string,
+  toolTitle: string | undefined,
+  value: boolean | ToolInvokeEffectConfig | undefined
+): RuntimeEffectConfig | undefined {
+  if (!value) return undefined
+  const baseLabel = toolTitle || toolName
+  if (typeof value === 'boolean') {
+    return value ? { label: baseLabel } : undefined
+  }
+  return {
+    label: value.label || baseLabel
+  }
+}
+

package/remoter/createRemoter.ts

@@ -159,18 +159,17 @@ class FloatingBlock {
       return getDefaultMenuItems(this.options)
     }
 
-    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 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
-      })
+      }
+      return defaultItem
+    })
   }
 
   private init(): void {
@@ -913,6 +912,21 @@ class FloatingBlock {
       this.dropdownMenu.parentNode.removeChild(this.dropdownMenu)
     }
   }
+
+  // 隐藏组件
+  public hide(): void {
+    if (this.floatingBlock) {
+      this.floatingBlock.style.display = 'none'
+    }
+    this.closeDropdown()
+  }
+
+  // 显示组件
+  public show(): void {
+    if (this.floatingBlock) {
+      this.floatingBlock.style.display = 'flex'
+    }
+  }
 }
 
 // 导出组件