@opentiny/next-sdk 0.2.7 → 0.2.9

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,16 @@
  *                         包装 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 { 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'
-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'
@@ -80,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
@@ -159,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 对应的页面并通过消息通信执行。
@@ -168,8 +162,19 @@ export type RouteConfig = {
   route: string
   /** 等待页面响应的超时时间（ms），默认 30000 */
   timeout?: number
+  /**
+   * 是否在调用该工具时启用页面级调用提示效果。
+   *
+   * - false / 未配置：不启用任何额外效果（保持现有行为）
+   * - true：使用默认提示文案（优先取工具标题，其次为工具名）
+   * - 对象：可自定义提示文案
+   */
+  invokeEffect?: boolean | ToolInvokeEffectConfig
 }
 
+// 对外暴露调用提示配置类型，便于业务方在 RouteConfig 外单独复用
+export type { ToolInvokeEffectConfig }
+
 /**
  * PageAwareServer 的 registerTool 配置对象类型，与 WebMcpServer.registerTool 保持一致。
  */
@@ -198,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 函数。
  * 调用流程：
@@ -205,7 +304,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 +324,10 @@ function buildPageHandler(name: string, route: string, timeout = 30000) {
         if (readyHandler) {
           window.removeEventListener('message', readyHandler)
         }
+        // 工具调用完成（成功 / 失败 / 超时 / 导航异常）后，无论结果如何都需要关闭调用提示效果
+        if (effectConfig) {
+          hideToolInvokeEffect()
+        }
       }
 
       // 超时兜底，防止页面永远不响应
@@ -255,6 +363,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 +415,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 +429,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 +449,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 +513,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
+  }
+}
+