@xiaozhi-client/endpoint 1.9.7-beta.3

package/dist/index.d.ts

@@ -0,0 +1,542 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { EventEmitter } from 'node:events';
+
+/**
+ * 工具调用结果接口
+ */
+interface ToolCallResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * 工具调用参数接口
+ */
+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>;
+}
+/**
+ * 连接状态枚举
+ */
+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. Streamable HTTP: { type?: "streamable-http"; url: string; headers?: Record<string, string> }
+ */
+type MCPServerConfig = LocalMCPServerConfig | SSEMCPServerConfig | StreamableHTTPMCPServerConfig;
+/**
+ * 本地 MCP 服务器配置
+ */
+interface LocalMCPServerConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+/**
+ * SSE MCP 服务器配置
+ */
+interface SSEMCPServerConfig {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Streamable HTTP MCP 服务器配置
+ */
+interface StreamableHTTPMCPServerConfig {
+    type?: "streamable-http";
+    url: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Endpoint 配置接口
+ * 用于新 API：直接在构造函数中传入 MCP 服务器配置
+ */
+interface EndpointConfig {
+    /** MCP 服务器配置（声明式） */
+    mcpServers: Record<string, MCPServerConfig>;
+    /** 可选：重连延迟（毫秒），默认 2000 */
+    reconnectDelay?: number;
+    /** 可选：ModelScope API Key（全局） */
+    modelscopeApiKey?: string;
+}
+/**
+ * EndpointManager 配置接口（新 API 简化版）
+ */
+interface EndpointManagerConfig {
+    /** 可选：默认重连延迟（毫秒） */
+    defaultReconnectDelay?: number;
+}
+
+/**
+ * Endpoint 类（新 API）
+ * 管理单个小智接入点的 WebSocket 连接
+ * 实现 MCP (Model Context Protocol) 协议通信
+ *
+ * 与 EndpointConnection 的区别：
+ * - 构造函数直接传入 mcpServers 配置，不需要单独调用 setServiceManager()
+ * - 配置更简洁直观
+ */
+
+/**
+ * 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 config - Endpoint 配置（包含 mcpServers）
+     */
+    constructor(endpointUrl: string, config: EndpointConfig);
+    /**
+     * 获取 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(): void;
+    /**
+     * 重连小智接入点
+     */
+    reconnect(): Promise<void>;
+    /**
+     * 处理工具调用请求
+     */
+    private handleToolCall;
+    /**
+     * 带超时控制的工具执行
+     */
+    private executeToolWithTimeout;
+    /**
+     * 处理工具调用错误
+     */
+    private handleToolCallError;
+    /**
+     * 发送错误响应
+     */
+    private sendErrorResponse;
+}
+
+/**
+ * EndpointManager（新 API）
+ * 管理多个小智接入点的连接，每个小智接入点独立运行
+ *
+ * 与旧 EndpointManager 的区别：
+ * - 使用 addEndpoint(endpoint) 添加 Endpoint 实例
+ * - 不需要 initialize() 和 setServiceManager()
+ * - 配置更简洁直观
+ */
+
+/**
+ * 小智接入点管理器（新 API）
+ * 负责管理多个小智接入点的连接
+ */
+declare class EndpointManager extends EventEmitter {
+    private config?;
+    private endpoints;
+    private connectionStates;
+    /**
+     * 构造函数
+     *
+     * @param config - 可选的配置
+     */
+    constructor(config?: EndpointManagerConfig | undefined);
+    /**
+     * 添加 Endpoint 实例
+     *
+     * @param endpoint - Endpoint 实例
+     */
+    addEndpoint(endpoint: Endpoint): void;
+    /**
+     * 移除 Endpoint 实例
+     *
+     * @param endpoint - Endpoint 实例
+     */
+    removeEndpoint(endpoint: Endpoint): void;
+    /**
+     * 连接所有 Endpoint
+     */
+    connect(): Promise<void>;
+    /**
+     * 断开所有连接
+     */
+    disconnect(): 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;
+    /**
+     * 重连所有端点
+     */
+    reconnectAll(): Promise<void>;
+    /**
+     * 重连指定的端点
+     *
+     * @param url - 要重连的端点 URL
+     */
+    reconnectEndpoint(url: string): Promise<void>;
+    /**
+     * 清除所有端点
+     */
+    clearEndpoints(): Promise<void>;
+    /**
+     * 清理资源
+     */
+    cleanup(): Promise<void>;
+    /**
+     * 连接单个端点
+     */
+    private connectSingleEndpoint;
+    /**
+     * 重连单个端点
+     */
+    private reconnectSingleEndpoint;
+}
+
+/**
+ * 工具函数模块
+ *
+ * 内联的必要工具函数，确保包的独立性
+ */
+
+/**
+ * 截断端点 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 合并后的对象
+ */
+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;
+
+/**
+ * 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 ReconnectResult, type SSEMCPServerConfig, type SimpleConnectionStatus, type StreamableHTTPMCPServerConfig, ToolCallError, ToolCallErrorCode, type ToolCallParams, type ToolCallResult, type ValidatedToolCallParams, deepMerge, ensureToolJSONSchema, formatErrorMessage, isValidEndpointUrl, sleep, sliceEndpoint, validateToolCallParams };