@opentiny/next-sdk 0.2.6 → 0.2.7

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

@@ -0,0 +1,132 @@
+import { ZodRawShape } from 'zod';
+import { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import { WebMcpServer } from './WebMcpServer';
+
+/** 页面卸载广播，供 pageToolsOnDemand 模式监听 */
+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）
+ */
+export declare function setNavigator(fn: (route: string) => void | Promise<void>): void;
+/**
+ * registerTool 第三个参数的路由配置对象类型。
+ * 当传入此类型时，工具调用会自动跳转到 route 对应的页面并通过消息通信执行。
+ */
+export type RouteConfig = {
+    /** 目标路由路径，如 '/comprehensive' */
+    route: string;
+    /** 等待页面响应的超时时间（ms），默认 30000 */
+    timeout?: number;
+};
+/**
+ * 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>, handlerOrRoute: ((...args: any[]) => any) | RouteConfig): RegisteredTool;
+};
+/**
+ * 包装 WebMcpServer，使 registerTool 第三个参数支持 RouteConfig。
+ *
+ * - 第三个参数为**回调函数**：与原始 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 declare function withPageTools(server: WebMcpServer): PageAwareServer;
+/**
+ * 在目标页面激活工具处理器（框架无关的纯 JS 函数）。
+ *
+ * 调用后立即：
+ * - 将路由注册到 activePages（标记页面已激活）
+ * - 添加 message 监听，处理来自 buildPageHandler 的工具调用
+ * - 广播 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 declare function registerPageTool(options: {
+    /**
+     * 目标路由路径，与 RouteConfig.route 保持一致。
+     * 省略时自动读取 window.location.pathname。
+     * 当页面路由与 pathname 不一致时（如 hash 路由、子路径前缀等），需手动传入。
+     */
+    route?: string;
+    /**
+     * 工具名 → 处理函数的映射表。
+     *
+     * 此处 handler 的 input 参数类型保留 any：
+     * 若改为 unknown，TypeScript 函数参数逆变规则会导致用户的具名解构写法
+     *（如 `async ({ productId }: { productId: string }) => ...`）无法通过类型检查，
+     * 破坏现有调用方代码的开发体验。运行时输入由 MCP inputSchema 保证类型安全。
+     */
+    handlers: Record<string, (input: any) => Promise<any>>;
+}): () => void;
+export {};

package/dist/remoter/createRemoter.d.ts

@@ -25,8 +25,8 @@ export interface FloatingBlockOptions {
     onShowAIChat?: () => void;
     /** 遥控端页面地址，默认为： https://ai.opentiny.design/next-remoter */
     qrCodeUrl?: string;
-    /** 被遥控页面的 sessionId, 必填 */
-    sessionId: string;
+    /** 被遥控页面的 sessionId；无 sessionId 时仅显示「打开对话框」菜单，不显示二维码、识别码、遥控器链接 */
+    sessionId?: string;
     /** 菜单项配置 */
     menuItems?: MenuItemConfig[];
     /** 遥控端页面地址，默认为： https://chat.opentiny.design */
@@ -48,9 +48,9 @@ declare class FloatingBlock {
     private getImageUrl;
     private renderItem;
     /**
-     * 合并菜单项配置
-     * @param userMenuItems 用户自定义菜单项配置
-     * @returns 合并后的菜单项配置
+     * 合并菜单项配置。
+     * - 有 sessionId：使用默认菜单 + 用户配置（可定制每一项的 show/text/icon 等）
+     * - 无 sessionId：不渲染任何下拉菜单，仅保留点击浮标打开对话框的能力
      */
     private mergeMenuItems;
     private init;

package/dist/skills/index.d.ts

@@ -21,10 +21,12 @@ export declare function parseSkillFrontMatter(content: string): {
 } | null;
 /**
  * 获取所有「主 SKILL.md」的路径（一级子目录下的 SKILL.md）
+ * - 对传入的 modules 先做 normalize，兼容任意 import.meta.glob 写法
  */
 export declare function getMainSkillPaths(modules: Record<string, string>): string[];
 /**
  * 获取所有技能的概况列表（name、description、path），用于 systemPrompt 或列表展示
+ * - 内部统一对 modules 做 normalize，避免调用方关心路径细节
  */
 export declare function getSkillOverviews(modules: Record<string, string>): SkillMeta[];
 /**
@@ -34,14 +36,17 @@ export declare function getSkillOverviews(modules: Record<string, string>): Skil
 export declare function formatSkillsForSystemPrompt(skills: SkillMeta[]): string;
 /**
  * 获取所有已加载的技能文件路径（含主 SKILL.md 与 reference 下的 .md/.json/.xml 等）
+ * - 对 modules 做 normalize 后再返回 key 列表
  */
 export declare function getSkillMdPaths(modules: Record<string, string>): string[];
 /**
  * 根据相对路径获取某个技能文档的原始内容（支持 .md、.json、.xml 等文本格式）
+ * - 自动对 modules 做 normalize，再按 path 查找
  */
 export declare function getSkillMdContent(modules: Record<string, string>, path: string): string | undefined;
 /**
  * 根据技能 name 查找其主 SKILL.md 的路径（name 与目录名一致）
+ * - 依赖 getMainSkillPaths，内部已做 normalize
  */
 export declare function getMainSkillPathByName(modules: Record<string, string>, name: string): string | undefined;
 /** AI SDK Tool 类型，用于 extraTools 合并，不写死泛型避免与 ai 包版本强绑定 */