@xiaozhi-client/endpoint 1.10.8-beta.7 → 1.10.8-beta.8

package/dist/index.d.ts

@@ -0,0 +1,762 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { EventEmitter } from 'node:events';
+
+/**
+ * 工具调用结果接口
+ * 使用更宽松的类型定义以兼容不同来源的 ToolCallResult
+ */
+interface ToolCallResult {
+    content: Array<Record<string, unknown>>;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+    toolResult?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * 工具调用参数接口
+ */
+interface ToolCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+/**
+ * 验证后的工具调用参数
+ */
+interface ValidatedToolCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+/**
+ * 工具调用错误码枚举
+ */
+declare enum ToolCallErrorCode {
+    /** 无效参数 */
+    INVALID_PARAMS = -32602,
+    /** 工具不存在 */
+    TOOL_NOT_FOUND = -32601,
+    /** 服务不可用 */
+    SERVICE_UNAVAILABLE = -32001,
+    /** 调用超时 */
+    TIMEOUT = -32002,
+    /** 工具执行错误 */
+    TOOL_EXECUTION_ERROR = -32000
+}
+/**
+ * 工具调用错误类
+ */
+declare class ToolCallError extends Error {
+    code: ToolCallErrorCode;
+    data?: unknown | undefined;
+    constructor(code: ToolCallErrorCode, message: string, data?: unknown | undefined);
+}
+/**
+ * JSON Schema 类型定义
+ * 兼容 MCP SDK 的 JSON Schema 格式
+ */
+type JSONSchema = (Record<string, unknown> & {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+}) | Record<string, unknown>;
+/**
+ * 确保对象符合 MCP Tool JSON Schema 格式
+ * 返回类型兼容 MCP SDK 的 Tool 类型
+ */
+declare function ensureToolJSONSchema(schema: JSONSchema): {
+    type: "object";
+    properties?: Record<string, object>;
+    required?: string[];
+    additionalProperties?: boolean;
+};
+/**
+ * 增强的工具信息接口
+ * 包含工具的启用状态和使用统计信息
+ */
+interface EnhancedToolInfo {
+    /** 工具唯一标识符，格式为 "{serviceName}__{originalName}" */
+    name: string;
+    /** 工具描述信息 */
+    description: string;
+    /** 工具输入参数的 JSON Schema 定义 */
+    inputSchema: JSONSchema;
+    /** 工具所属的 MCP 服务名称 */
+    serviceName: string;
+    /** 工具在 MCP 服务中的原始名称 */
+    originalName: string;
+    /** 工具是否启用 */
+    enabled: boolean;
+    /** 工具使用次数统计 */
+    usageCount: number;
+    /** 工具最后使用时间 (ISO 8601 格式字符串) */
+    lastUsedTime: string;
+}
+/**
+ * MCP 服务管理器接口
+ * 用于工具调用，避免循环依赖
+ */
+interface IMCPServiceManager {
+    /** 获取所有工具列表 */
+    getAllTools(): EnhancedToolInfo[];
+    /** 调用工具 */
+    callTool(toolName: string, arguments_: Record<string, unknown>): Promise<ToolCallResult>;
+    /** 初始化 */
+    initialize(): Promise<void>;
+    /** 清理资源 */
+    cleanup(): Promise<void>;
+}
+/**
+ * 连接状态枚举
+ */
+declare enum ConnectionState {
+    DISCONNECTED = "disconnected",
+    CONNECTING = "connecting",
+    CONNECTED = "connected",
+    FAILED = "failed"
+}
+/**
+ * 连接选项接口
+ */
+interface ConnectionOptions {
+    /** 连接超时时间（毫秒），默认 10000 */
+    connectionTimeout?: number;
+    /** 重连延迟时间（毫秒），默认 2000 */
+    reconnectDelay?: number;
+}
+/**
+ * EndpointConnection 状态接口
+ */
+interface EndpointConnectionStatus {
+    /** 是否已连接 */
+    connected: boolean;
+    /** 是否已初始化 */
+    initialized: boolean;
+    /** 接入点 URL */
+    url: string;
+    /** 可用工具数量 */
+    availableTools: number;
+    /** 连接状态 */
+    connectionState: ConnectionState;
+    /** 最后一次错误信息 */
+    lastError: string | null;
+}
+/**
+ * 简单连接状态接口
+ */
+interface SimpleConnectionStatus {
+    /** 接入点地址 */
+    endpoint: string;
+    /** 是否已连接 */
+    connected: boolean;
+    /** 是否已初始化 */
+    initialized: boolean;
+    /** 最后连接时间 */
+    lastConnected?: Date;
+    /** 最后错误信息 */
+    lastError?: string;
+}
+/**
+ * 完整连接状态接口（扩展 SimpleConnectionStatus）
+ */
+interface ConnectionStatus extends SimpleConnectionStatus {
+}
+/**
+ * 配置变更事件类型
+ */
+interface ConfigChangeEvent {
+    type: "endpoints_added" | "endpoints_removed" | "endpoints_updated" | "options_updated";
+    data: {
+        added?: string[];
+        removed?: string[];
+        updated?: string[];
+        oldOptions?: Partial<ConnectionOptions>;
+        newOptions?: Partial<ConnectionOptions>;
+    };
+    timestamp: Date;
+}
+/**
+ * 重连结果接口
+ */
+interface ReconnectResult {
+    successCount: number;
+    failureCount: number;
+    results: Array<{
+        endpoint: string;
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * MCP 服务器配置类型
+ * 支持三种配置方式：
+ * 1. 本地命令 (stdio): { command: string; args: string[]; env?: Record<string, string> }
+ * 2. SSE: { type: "sse"; url: string; headers?: Record<string, string> }
+ * 3. HTTP: { type?: "http"; url: string; headers?: Record<string, string> }
+ *
+ * 向后兼容：自动将 streamable-http/streamable_http/streamableHttp 转换为 http
+ */
+type MCPServerConfig = LocalMCPServerConfig | SSEMCPServerConfig | HTTPMCPServerConfig;
+/**
+ * 本地 MCP 服务器配置
+ */
+interface LocalMCPServerConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+/**
+ * SSE MCP 服务器配置
+ */
+interface SSEMCPServerConfig {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+}
+/**
+ * HTTP MCP 服务器配置
+ * 使用 type: "http"
+ * 向后兼容 streamable-http 写法
+ */
+interface HTTPMCPServerConfig {
+    type?: "http" | "streamable-http";
+    url: string;
+    headers?: Record<string, string>;
+}
+/** @deprecated 使用 HTTPMCPServerConfig 代替 */
+type StreamableHTTPMCPServerConfig = HTTPMCPServerConfig;
+/**
+ * Endpoint 配置接口
+ * @deprecated 不再使用，Endpoint 构造函数改为接收 IMCPServiceManager
+ */
+interface EndpointConfig {
+    /** MCP 服务器配置（声明式） */
+    mcpServers: Record<string, MCPServerConfig>;
+    /** 可选：重连延迟（毫秒），默认 2000 */
+    reconnectDelay?: number;
+    /** 可选：ModelScope API Key（全局） */
+    modelscopeApiKey?: string;
+}
+/**
+ * EndpointManager 配置接口
+ */
+interface EndpointManagerConfig {
+    /** 可选：默认重连延迟（毫秒） */
+    defaultReconnectDelay?: number;
+}
+/**
+ * 小智平台 JWT Token Payload 接口
+ *
+ * @example
+ * ```typescript
+ * // 从 endpoint URL 解码得到的 payload
+ * const payload: XiaozhiTokenPayload = {
+ *   userId: 302720,
+ *   agentId: 1324149,
+ *   endpointId: "agent_1324149",
+ *   purpose: "mcp-endpoint",
+ *   iat: 1768480930,
+ *   exp: 1800038530
+ * };
+ * ```
+ */
+interface XiaozhiTokenPayload {
+    /** 用户 ID */
+    userId: number;
+    /** 代理 ID */
+    agentId: number;
+    /** 接入点 ID，格式为 "agent_{agentId}" */
+    endpointId: string;
+    /** Token 用途 */
+    purpose: string;
+    /** 签发时间（Unix 时间戳） */
+    iat: number;
+    /** 过期时间（Unix 时间戳） */
+    exp: number;
+}
+/**
+ * 解析后的 Endpoint URL 信息
+ */
+interface ParsedEndpointInfo {
+    /** 完整的 endpoint URL */
+    url: string;
+    /** 提取的 JWT Token */
+    token: string;
+    /** 解码后的 Token Payload */
+    payload: XiaozhiTokenPayload;
+    /** WebSocket 服务器地址（不含 token 参数） */
+    wsUrl: string;
+}
+
+/**
+ * Endpoint 类
+ * 管理单个小智接入点的 WebSocket 连接
+ * 实现 MCP (Model Context Protocol) 协议通信
+ *
+ * 使用方式：
+ * ```typescript
+ * const mcpManager = new SharedMCPAdapter(globalMCPManager);
+ * const endpoint = new Endpoint("ws://...", mcpManager);
+ * await endpoint.connect();
+ * ```
+ */
+
+/**
+ * Endpoint 类
+ * 负责管理单个小智接入点的 WebSocket 连接
+ * 使用新的配置方式：直接在构造函数中传入 mcpServers 配置
+ */
+declare class Endpoint {
+    private endpointUrl;
+    private ws;
+    private connectionStatus;
+    private serverInitialized;
+    private mcpAdapter;
+    private connectionState;
+    private lastError;
+    private connectionTimeout;
+    private toolCallTimeout;
+    private reconnectDelay;
+    /**
+     * 构造函数
+     *
+     * @param endpointUrl - 小智接入点 URL
+     * @param mcpManager - MCP 服务管理器（依赖注入）
+     * @param reconnectDelay - 可选的重连延迟（毫秒）
+     */
+    constructor(endpointUrl: string, mcpManager: IMCPServiceManager, reconnectDelay?: number);
+    /**
+     * 获取 Endpoint URL
+     */
+    getUrl(): string;
+    /**
+     * 获取当前所有工具列表
+     */
+    getTools(): Tool[];
+    /**
+     * 连接小智接入点
+     */
+    connect(): Promise<void>;
+    /**
+     * 尝试建立连接
+     */
+    private attemptConnection;
+    /**
+     * 处理连接成功
+     */
+    private handleConnectionSuccess;
+    /**
+     * 处理连接错误
+     */
+    private handleConnectionError;
+    /**
+     * 处理连接关闭
+     */
+    private handleConnectionClose;
+    /**
+     * 清理连接资源
+     */
+    private cleanupConnection;
+    /**
+     * 处理 MCP 消息
+     */
+    private handleMessage;
+    /**
+     * 发送响应消息
+     */
+    private sendResponse;
+    /**
+     * 获取服务器状态
+     */
+    getStatus(): EndpointConnectionStatus;
+    /**
+     * 检查连接状态
+     */
+    isConnected(): boolean;
+    /**
+     * 主动断开小智连接
+     */
+    disconnect(): Promise<void>;
+    /**
+     * 重连小智接入点
+     */
+    reconnect(): Promise<void>;
+    /**
+     * 处理工具调用请求
+     */
+    private handleToolCall;
+    /**
+     * 带超时控制的工具执行
+     */
+    private executeToolWithTimeout;
+    /**
+     * 处理工具调用错误
+     */
+    private handleToolCallError;
+    /**
+     * 发送错误响应
+     */
+    private sendErrorResponse;
+}
+
+/**
+ * EndpointManager
+ * 管理多个小智接入点的连接，共享外部传入的 MCPManager
+ *
+ * 使用方式：
+ * ```typescript
+ * // 1. 先创建并配置 MCPManager
+ * const mcpManager = new MCPManager();
+ * mcpManager.addServer("calculator", { command: "npx", args: ["-y", "calculator-mcp"] });
+ * await mcpManager.connect();
+ *
+ * // 2. 创建 EndpointManager 并设置 MCPManager
+ * const manager = new EndpointManager();
+ * manager.setMcpManager(mcpManager);
+ *
+ * // 3. 添加接入点
+ * manager.addEndpoint("ws://endpoint1");
+ * await manager.connect();
+ * ```
+ */
+
+/**
+ * 小智接入点管理器
+ * 负责管理多个小智接入点的连接，共享 MCP 服务
+ *
+ * 注意：MCPManager 必须通过 setMcpManager() 方法设置，且由外部管理其生命周期
+ */
+declare class EndpointManager extends EventEmitter {
+    private config?;
+    private endpoints;
+    private connectionStates;
+    private mcpManager;
+    private sharedMCPAdapter;
+    private mcpEventListeners;
+    /**
+     * 构造函数
+     *
+     * @param config - 可选的配置
+     */
+    constructor(config?: EndpointManagerConfig | undefined);
+    /**
+     * 设置 MCPManager 实例
+     *
+     * 注意：MCPManager 的生命周期由外部管理，EndpointManager 不负责连接和断开
+     *
+     * @param mcpManager - 外部创建并已连接的 MCPManager 实例
+     */
+    setMcpManager(mcpManager: IMCPServiceManager): void;
+    /**
+     * 添加 Endpoint（支持 URL 字符串或 Endpoint 实例）
+     *
+     * @param endpoint - Endpoint URL 字符串或 Endpoint 实例
+     */
+    addEndpoint(endpoint: string | Endpoint): void;
+    /**
+     * 内部添加 Endpoint 方法
+     */
+    private addEndpointInternal;
+    /**
+     * 移除 Endpoint 实例
+     *
+     * @param endpoint - Endpoint 实例
+     */
+    removeEndpoint(endpoint: Endpoint): void;
+    /**
+     * 连接 Endpoint
+     *
+     * 注意：此方法不负责连接 MCPManager，MCPManager 必须在调用此方法前已连接
+     *
+     * @param endpoint - 可选，指定要连接的端点 URL。如果不传入，则连接所有端点
+     */
+    connect(endpoint?: string): Promise<void>;
+    /**
+     * 断开连接
+     *
+     * 注意：此方法不断开 MCPManager，MCPManager 的生命周期由外部管理
+     *
+     * @param endpoint - 可选，指定要断开的端点 URL。如果不传入，则断开所有端点
+     */
+    disconnect(endpoint?: string): Promise<void>;
+    /**
+     * 获取所有 Endpoint URL
+     */
+    getEndpoints(): string[];
+    /**
+     * 获取指定 Endpoint 实例
+     *
+     * @param url - Endpoint URL
+     */
+    getEndpoint(url: string): Endpoint | undefined;
+    /**
+     * 获取所有连接状态
+     */
+    getConnectionStatus(): SimpleConnectionStatus[];
+    /**
+     * 检查是否有任何连接处于连接状态
+     */
+    isAnyConnected(): boolean;
+    /**
+     * 检查指定端点是否已连接
+     *
+     * @param url - 端点 URL
+     */
+    isEndpointConnected(url: string): boolean;
+    /**
+     * 获取指定端点的状态
+     *
+     * @param url - 端点 URL
+     */
+    getEndpointStatus(url: string): SimpleConnectionStatus | undefined;
+    /**
+     * 重连
+     *
+     * @param endpoint - 可选，指定要重连的端点 URL。如果不传入，则重连所有端点
+     * @param delay - 可选，disconnect 和 connect 之间的等待时间（毫秒），默认为 1000ms。
+     *               注意：此参数只控制断开和重新连接之间的等待时间，不影响底层 Endpoint 实例的重连延迟
+     */
+    reconnect(endpoint?: string, delay?: number): Promise<void>;
+    /**
+     * 重连所有端点
+     */
+    reconnectAll(): Promise<void>;
+    /**
+     * 重连指定的端点
+     *
+     * @param url - 要重连的端点 URL
+     */
+    reconnectEndpoint(url: string): Promise<void>;
+    /**
+     * 清除所有端点
+     *
+     * 注意：此方法不会清理 MCPManager，MCPManager 的生命周期由外部管理
+     */
+    clearEndpoints(): Promise<void>;
+    /**
+     * 清理资源
+     *
+     * 注意：此方法不会清理 MCPManager，MCPManager 的生命周期由外部管理
+     */
+    cleanup(): Promise<void>;
+    /**
+     * 连接单个端点
+     */
+    private connectSingleEndpoint;
+    /**
+     * 重连单个端点
+     */
+    private reconnectSingleEndpoint;
+}
+
+/**
+ * 共享 MCP 管理器适配器
+ *
+ * 接收全局 MCPManager 实例的引用，不创建独立连接
+ * 用于多个 Endpoint 共享同一个 MCPManager 实例
+ *
+ * @example
+ * ```typescript
+ * const globalMCPManager = new MCPManager();
+ * await globalMCPManager.connect();
+ *
+ * const adapter = new SharedMCPAdapter(globalMCPManager);
+ * const endpoint = new Endpoint("ws://...", adapter);
+ * ```
+ */
+
+/**
+ * 共享 MCP 管理器适配器
+ * 实现 IMCPServiceManager 接口，将操作委托给全局 MCPManager
+ */
+declare class SharedMCPAdapter implements IMCPServiceManager {
+    private globalMCPManager;
+    private isInitialized;
+    /**
+     * 构造函数
+     *
+     * @param globalMCPManager - 全局 MCPManager 实例
+     */
+    constructor(globalMCPManager: IMCPServiceManager);
+    /**
+     * 初始化适配器
+     *
+     * 注意：此方法不执行任何连接操作，仅标记初始化状态，因为全局 MCPManager 的生命周期由外部管理
+     */
+    initialize(): Promise<void>;
+    /**
+     * 获取所有工具列表
+     *
+     * 从全局 MCPManager 获取工具列表，并转换为增强格式
+     */
+    getAllTools(): EnhancedToolInfo[];
+    /**
+     * 调用工具
+     *
+     * 将工具调用委托给全局 MCPManager
+     *
+     * @param toolName - 工具名称（格式：serviceName__toolName）
+     * @param arguments_ - 工具调用参数
+     */
+    callTool(toolName: string, arguments_: Record<string, unknown>): Promise<ToolCallResult>;
+    /**
+     * 清理资源
+     *
+     * 注意：此方法不会断开全局 MCPManager，由创建者负责管理
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * 工具函数模块
+ *
+ * 内联的必要工具函数，确保包的独立性
+ */
+
+/**
+ * 截断端点 URL 用于日志显示
+ *
+ * @param endpoint - 完整的端点 URL
+ * @returns 截断后的 URL
+ *
+ * @example
+ * ```typescript
+ * sliceEndpoint("ws://very-long-endpoint-url-here.example.com/endpoint")
+ * // 返回: "ws://very-long-endpoint-u...e.com/endpoint"
+ * ```
+ */
+declare function sliceEndpoint(endpoint: string): string;
+/**
+ * 验证工具调用参数
+ *
+ * @param params - 待验证的参数
+ * @returns 验证后的参数
+ * @throws {Error} 如果参数无效
+ *
+ * @example
+ * ```typescript
+ * const params = validateToolCallParams({
+ *   name: "test_tool",
+ *   arguments: { foo: "bar" }
+ * });
+ * ```
+ */
+declare function validateToolCallParams(params: unknown): ValidatedToolCallParams;
+/**
+ * 验证端点 URL 格式
+ *
+ * @param endpoint - 待验证的端点 URL
+ * @returns 是否为有效的 WebSocket URL
+ */
+declare function isValidEndpointUrl(endpoint: string): boolean;
+/**
+ * 深度合并对象
+ *
+ * @param target - 目标对象
+ * @param sources - 源对象
+ * @returns 合并后的对象
+ *
+ * @example
+ * ```typescript
+ * const result = deepMerge(
+ *   { a: 1, b: { x: 1 } },
+ *   { b: { y: 2 }, c: 3 }
+ * );
+ * // 返回: { a: 1, b: { x: 1, y: 2 }, c: 3 }
+ * ```
+ */
+declare function deepMerge<T>(target: Partial<T>, ...sources: Array<Partial<T>>): T;
+/**
+ * 延迟执行
+ *
+ * @param ms - 延迟时间（毫秒）
+ * @returns Promise
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * 格式化错误消息
+ *
+ * @param error - 错误对象
+ * @returns 格式化后的错误消息
+ */
+declare function formatErrorMessage(error: unknown): string;
+/**
+ * 解码 JWT Token（仅解析 payload，不验证签名）
+ *
+ * @param token - JWT Token 字符串
+ * @returns 解码后的 Token Payload，解码失败返回 null
+ *
+ * @example
+ * ```typescript
+ * const payload = decodeJWTToken("eyJ...token...");
+ * if (payload) {
+ *   console.log(payload.endpointId); // "agent_1324149"
+ * }
+ * ```
+ */
+declare function decodeJWTToken(token: string): XiaozhiTokenPayload | null;
+/**
+ * 从 endpoint URL 中提取 token 参数
+ *
+ * @param url - 完整的 endpoint URL
+ * @returns 提取的 token 字符串，未找到返回 null
+ *
+ * @example
+ * ```typescript
+ * const token = extractTokenFromUrl(
+ *   "wss://api.xiaozhi.me/mcp/?token=eyJ..."
+ * );
+ * ```
+ */
+declare function extractTokenFromUrl(url: string): string | null;
+/**
+ * 解析 endpoint URL 获取完整信息
+ *
+ * @param url - 完整的 endpoint URL
+ * @returns 解析后的 endpoint 信息，解析失败返回 null
+ *
+ * @example
+ * ```typescript
+ * const info = parseEndpointUrl(
+ *   "wss://api.xiaozhi.me/mcp/?token=eyJ..."
+ * );
+ * if (info) {
+ *   console.log(info.payload.endpointId); // "agent_1324149"
+ *   console.log(info.wsUrl); // "wss://api.xiaozhi.me/mcp/"
+ * }
+ * ```
+ */
+declare function parseEndpointUrl(url: string): ParsedEndpointInfo | null;
+
+/**
+ * MCP 消息类型定义
+ *
+ * 定义最小化的 MCP 协议消息类型
+ */
+/**
+ * MCP 消息接口
+ */
+interface MCPMessage {
+    /** JSON-RPC 版本 */
+    jsonrpc: "2.0";
+    /** 方法名 */
+    method: string;
+    /** 参数 */
+    params?: unknown;
+    /** 请求 ID */
+    id: string | number;
+}
+/**
+ * 扩展的 MCP 消息接口（用于响应）
+ */
+interface ExtendedMCPMessage {
+    jsonrpc: "2.0";
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+
+export { type ConfigChangeEvent, type ConnectionOptions, ConnectionState, type ConnectionStatus, Endpoint, type EndpointConfig, type EndpointConnectionStatus, EndpointManager, type EndpointManagerConfig, type ExtendedMCPMessage, type IMCPServiceManager, type JSONSchema, type LocalMCPServerConfig, type MCPMessage, type MCPServerConfig, type ParsedEndpointInfo, type ReconnectResult, type SSEMCPServerConfig, SharedMCPAdapter, type SimpleConnectionStatus, type StreamableHTTPMCPServerConfig, ToolCallError, ToolCallErrorCode, type ToolCallParams, type ToolCallResult, type ValidatedToolCallParams, type XiaozhiTokenPayload, decodeJWTToken, deepMerge, ensureToolJSONSchema, extractTokenFromUrl, formatErrorMessage, isValidEndpointUrl, parseEndpointUrl, sleep, sliceEndpoint, validateToolCallParams };