@opentiny/next-sdk 0.2.6 → 0.2.8

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

@@ -0,0 +1,101 @@
+import { ZodRawShape } from 'zod';
+import { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import { WebMcpServer } from '../WebMcpServer';
+import { ToolInvokeEffectConfig } from './effects';
+
+/** 页面卸载广播，供 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;
+    /**
+     * 是否在调用该工具时启用页面级调用提示效果。
+     *
+     * - false / 未配置：不启用任何额外效果（保持现有行为）
+     * - true：使用默认提示文案（优先取工具标题，其次为工具名）
+     * - 对象：可自定义提示文案
+     */
+    invokeEffect?: boolean | ToolInvokeEffectConfig;
+};
+export type { ToolInvokeEffectConfig };
+/**
+ * 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 与页面通信
+ */
+export declare function withPageTools(server: WebMcpServer): PageAwareServer;
+/**
+ * 在目标页面激活工具处理器（框架无关的纯 JS 函数）。
+ *
+ * 调用后立即：
+ * - 将路由注册到 activePages（标记页面已激活）
+ * - 添加 message 监听，处理来自 buildPageHandler 的工具调用
+ * - 广播 page-ready 信号，通知正在等待导航完成的工具
+ *
+ * 返回 cleanup 函数，页面销毁时调用。
+ */
+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;

package/dist/page-tools/effects.d.ts

@@ -0,0 +1,36 @@
+/**
+ * page-tools/effects - 页面工具调用提示效果模块（框架无关）
+ *
+ * 作用：
+ * - 在调用通过 withPageTools 注册的页面工具时，显示页面级的调用状态提示
+ * - 以左下角小 tip 形式展示“当前正在调用的工具”文案，尽量不打扰用户操作
+ * - 纯 DOM + CSS 实现，不依赖 Vue/React 等框架
+ */
+export type ToolInvokeEffectConfig = {
+    /**
+     * 自定义提示文案，默认使用“工具标题 || 工具名称”
+     * 例如："正在为你整理订单数据"
+     */
+    label?: string;
+};
+type RuntimeEffectConfig = {
+    label: string;
+};
+/**
+ * 在页面上显示工具调用提示效果。
+ * - 若当前已有其他工具在执行，仅更新文案，不重复创建 DOM
+ * - 会增加 activeCount 计数，需配对调用 hideToolInvokeEffect
+ */
+export declare function showToolInvokeEffect(config: RuntimeEffectConfig): void;
+/**
+ * 隐藏工具调用提示效果。
+ * - 使用引用计数：只有当所有调用结束后才真正移除 Overlay
+ */
+export declare function hideToolInvokeEffect(): void;
+/**
+ * 将 RouteConfig 中的 invokeEffect 配置编译成运行时效果配置。
+ * - boolean / undefined：关闭或开启默认文案
+ * - 对象：允许自定义 label
+ */
+export declare function resolveRuntimeEffectConfig(toolName: string, toolTitle: string | undefined, value: boolean | ToolInvokeEffectConfig | undefined): RuntimeEffectConfig | undefined;
+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;
@@ -74,6 +74,8 @@ declare class FloatingBlock {
     private hideModal;
     private addStyles;
     destroy(): void;
+    hide(): void;
+    show(): void;
 }
 export declare const createRemoter: (options?: FloatingBlockOptions) => FloatingBlock;
 export {};

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,18 @@ 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 与目录名一致）
+ * 根据技能 name 查找其主 SKILL.md 的路径
+ * 支持匹配目录名（如 ecommerce）或 SKILL.md 内 frontmatter 定义的 name
+ * - 依赖 getMainSkillPaths，内部已做 normalize
  */
 export declare function getMainSkillPathByName(modules: Record<string, string>, name: string): string | undefined;
 /** AI SDK Tool 类型，用于 extraTools 合并，不写死泛型避免与 ai 包版本强绑定 */