@xiaozhi-client/config 1.9.4-beta.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 shenjingnan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,580 @@
+interface LocalMCPServerConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+interface SSEMCPServerConfig {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+}
+interface StreamableHTTPMCPServerConfig {
+    type?: "streamable-http";
+    url: string;
+    headers?: Record<string, string>;
+}
+type MCPServerConfig = LocalMCPServerConfig | SSEMCPServerConfig | StreamableHTTPMCPServerConfig;
+interface MCPToolConfig {
+    description?: string;
+    enable: boolean;
+    usageCount?: number;
+    lastUsedTime?: string;
+}
+interface MCPServerToolsConfig {
+    tools: Record<string, MCPToolConfig>;
+}
+interface ConnectionConfig {
+    heartbeatInterval?: number;
+    heartbeatTimeout?: number;
+    reconnectInterval?: number;
+}
+interface ModelScopeConfig {
+    apiKey?: string;
+}
+interface WebUIConfig {
+    port?: number;
+    autoRestart?: boolean;
+}
+interface ToolCallLogConfig {
+    maxRecords?: number;
+    logFilePath?: string;
+}
+interface ProxyHandlerConfig {
+    type: "proxy";
+    platform: "coze" | "openai" | "anthropic" | "custom";
+    config: {
+        workflow_id?: string;
+        bot_id?: string;
+        api_key?: string;
+        base_url?: string;
+        timeout?: number;
+        retry_count?: number;
+        retry_delay?: number;
+        headers?: Record<string, string>;
+        params?: Record<string, unknown>;
+    };
+}
+interface HttpHandlerConfig {
+    type: "http";
+    url: string;
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    headers?: Record<string, string>;
+    timeout?: number;
+    retry_count?: number;
+    retry_delay?: number;
+    auth?: {
+        type: "bearer" | "basic" | "api_key";
+        token?: string;
+        username?: string;
+        password?: string;
+        api_key?: string;
+        api_key_header?: string;
+    };
+    body_template?: string;
+    response_mapping?: {
+        success_path?: string;
+        error_path?: string;
+        data_path?: string;
+    };
+}
+interface FunctionHandlerConfig {
+    type: "function";
+    module: string;
+    function: string;
+    timeout?: number;
+    context?: Record<string, unknown>;
+}
+interface ScriptHandlerConfig {
+    type: "script";
+    script: string;
+    interpreter?: "node" | "python" | "bash";
+    timeout?: number;
+    env?: Record<string, string>;
+}
+interface ChainHandlerConfig {
+    type: "chain";
+    tools: string[];
+    mode: "sequential" | "parallel";
+    error_handling: "stop" | "continue" | "retry";
+}
+interface MCPHandlerConfig {
+    type: "mcp";
+    config: {
+        serviceName: string;
+        toolName: string;
+    };
+}
+type HandlerConfig = ProxyHandlerConfig | HttpHandlerConfig | FunctionHandlerConfig | ScriptHandlerConfig | ChainHandlerConfig | MCPHandlerConfig;
+interface CustomMCPTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: HandlerConfig;
+    stats?: {
+        usageCount?: number;
+        lastUsedTime?: string;
+    };
+}
+interface CustomMCPConfig {
+    tools: CustomMCPTool[];
+}
+interface WebServerInstance {
+    broadcastConfigUpdate(config: AppConfig): void;
+}
+interface PlatformsConfig {
+    [platformName: string]: PlatformConfig;
+}
+interface PlatformConfig {
+    token?: string;
+}
+/**
+ * 扣子平台配置接口
+ */
+interface CozePlatformConfig extends PlatformConfig {
+    /** 扣子 API Token */
+    token: string;
+}
+interface AppConfig {
+    mcpEndpoint: string | string[];
+    mcpServers: Record<string, MCPServerConfig>;
+    mcpServerConfig?: Record<string, MCPServerToolsConfig>;
+    customMCP?: CustomMCPConfig;
+    connection?: ConnectionConfig;
+    modelscope?: ModelScopeConfig;
+    webUI?: WebUIConfig;
+    platforms?: PlatformsConfig;
+    toolCallLog?: ToolCallLogConfig;
+}
+/**
+ * 配置管理类
+ * 负责管理应用配置，提供只读访问和安全的配置更新功能
+ */
+declare class ConfigManager {
+    private static instance;
+    private defaultConfigPath;
+    private config;
+    private currentConfigPath;
+    private json5Writer;
+    private statsUpdateLocks;
+    private statsUpdateLockTimeouts;
+    private readonly STATS_UPDATE_TIMEOUT;
+    private eventCallbacks;
+    private constructor();
+    /**
+     * 注册事件监听器
+     */
+    on(eventName: string, callback: (data: unknown) => void): void;
+    /**
+     * 发射事件
+     */
+    private emitEvent;
+    /**
+     * 获取配置文件路径（动态计算）
+     * 支持多种配置文件格式：json5 > jsonc > json
+     */
+    private getConfigFilePath;
+    /**
+     * 获取配置文件格式
+     */
+    private getConfigFileFormat;
+    /**
+     * 获取配置管理器单例实例
+     */
+    static getInstance(): ConfigManager;
+    /**
+     * 检查配置文件是否存在
+     */
+    configExists(): boolean;
+    /**
+     * 初始化配置文件
+     * 从 config.default.json 复制到 config.json
+     * @param format 配置文件格式，默认为 json
+     */
+    initConfig(format?: "json" | "json5" | "jsonc"): void;
+    /**
+     * 加载配置文件
+     */
+    private loadConfig;
+    /**
+     * 验证配置文件结构
+     */
+    validateConfig(config: unknown): void;
+    /**
+     * 获取配置（只读）
+     */
+    getConfig(): Readonly<AppConfig>;
+    /**
+     * 获取可修改的配置对象（内部使用，保留注释信息）
+     */
+    private getMutableConfig;
+    /**
+     * 获取 MCP 端点（向后兼容）
+     * @deprecated 使用 getMcpEndpoints() 获取所有端点
+     */
+    getMcpEndpoint(): string;
+    /**
+     * 获取所有 MCP 端点
+     */
+    getMcpEndpoints(): string[];
+    /**
+     * 获取 MCP 服务配置
+     */
+    getMcpServers(): Readonly<Record<string, MCPServerConfig>>;
+    /**
+     * 获取 MCP 服务工具配置
+     */
+    getMcpServerConfig(): Readonly<Record<string, MCPServerToolsConfig>>;
+    /**
+     * 获取指定服务的工具配置
+     */
+    getServerToolsConfig(serverName: string): Readonly<Record<string, MCPToolConfig>>;
+    /**
+     * 检查工具是否启用
+     */
+    isToolEnabled(serverName: string, toolName: string): boolean;
+    /**
+     * 更新 MCP 端点（支持字符串或数组）
+     */
+    updateMcpEndpoint(endpoint: string | string[]): void;
+    /**
+     * 添加 MCP 端点
+     */
+    addMcpEndpoint(endpoint: string): void;
+    /**
+     * 移除 MCP 端点
+     */
+    removeMcpEndpoint(endpoint: string): void;
+    /**
+     * 更新 MCP 服务配置
+     */
+    updateMcpServer(serverName: string, serverConfig: MCPServerConfig): void;
+    /**
+     * 删除 MCP 服务配置
+     */
+    removeMcpServer(serverName: string): void;
+    /**
+     * 批量更新配置（由 Handler 调用）
+     */
+    updateConfig(newConfig: Partial<AppConfig>): void;
+    /**
+     * 更新服务工具配置
+     */
+    updateServerToolsConfig(serverName: string, toolsConfig: Record<string, MCPToolConfig>): void;
+    /**
+     * 删除指定服务器的工具配置
+     */
+    removeServerToolsConfig(serverName: string): void;
+    /**
+     * 清理无效的服务器工具配置
+     * 删除在 mcpServerConfig 中存在但在 mcpServers 中不存在的服务配置
+     */
+    cleanupInvalidServerToolsConfig(): void;
+    /**
+     * 设置工具启用状态
+     */
+    setToolEnabled(serverName: string, toolName: string, enabled: boolean, description?: string): void;
+    /**
+     * 保存配置到文件
+     * 保存到原始配置文件路径，保持文件格式一致性
+     */
+    private saveConfig;
+    /**
+     * 重新加载配置（清除缓存）
+     */
+    reloadConfig(): void;
+    /**
+     * 获取配置文件路径
+     */
+    getConfigPath(): string;
+    /**
+     * 获取默认配置文件路径
+     */
+    getDefaultConfigPath(): string;
+    /**
+     * 获取连接配置（包含默认值）
+     */
+    getConnectionConfig(): Required<ConnectionConfig>;
+    /**
+     * 获取心跳检测间隔（毫秒）
+     */
+    getHeartbeatInterval(): number;
+    /**
+     * 获取心跳超时时间（毫秒）
+     */
+    getHeartbeatTimeout(): number;
+    /**
+     * 获取重连间隔（毫秒）
+     */
+    getReconnectInterval(): number;
+    /**
+     * 更新连接配置
+     */
+    updateConnectionConfig(connectionConfig: Partial<ConnectionConfig>): void;
+    /**
+     * 更新工具使用统计信息（MCP 服务工具）
+     * @param serverName 服务名称
+     * @param toolName 工具名称
+     * @param callTime 调用时间（ISO 8601 格式）
+     */
+    updateToolUsageStats(serverName: string, toolName: string, callTime: string): Promise<void>;
+    /**
+     * 更新工具使用统计信息（CustomMCP 工具）
+     * @param toolName 工具名称（customMCP 工具名称）
+     * @param incrementUsageCount 是否增加使用计数，默认为 true
+     */
+    updateToolUsageStats(toolName: string, incrementUsageCount?: boolean): Promise<void>;
+    /**
+     * 更新 MCP 服务工具统计信息（重载方法）
+     * @param serviceName 服务名称
+     * @param toolName 工具名称
+     * @param callTime 调用时间（ISO 8601 格式）
+     * @param incrementUsageCount 是否增加使用计数，默认为 true
+     */
+    updateMCPServerToolStats(serviceName: string, toolName: string, callTime: string, incrementUsageCount?: boolean): Promise<void>;
+    /**
+     * 设置心跳检测间隔
+     */
+    setHeartbeatInterval(interval: number): void;
+    /**
+     * 设置心跳超时时间
+     */
+    setHeartbeatTimeout(timeout: number): void;
+    /**
+     * 设置重连间隔
+     */
+    setReconnectInterval(interval: number): void;
+    /**
+     * 获取 ModelScope 配置
+     */
+    getModelScopeConfig(): Readonly<ModelScopeConfig>;
+    /**
+     * 获取 ModelScope API Key
+     * 优先从配置文件读取，其次从环境变量读取
+     */
+    getModelScopeApiKey(): string | undefined;
+    /**
+     * 更新 ModelScope 配置
+     */
+    updateModelScopeConfig(modelScopeConfig: Partial<ModelScopeConfig>): void;
+    /**
+     * 设置 ModelScope API Key
+     */
+    setModelScopeApiKey(apiKey: string): void;
+    /**
+     * 获取 customMCP 配置
+     */
+    getCustomMCPConfig(): CustomMCPConfig | null;
+    /**
+     * 获取 customMCP 工具列表
+     */
+    getCustomMCPTools(): CustomMCPTool[];
+    /**
+     * 验证 customMCP 工具配置
+     */
+    validateCustomMCPTools(tools: CustomMCPTool[]): boolean;
+    /**
+     * 验证处理器配置
+     */
+    private validateHandlerConfig;
+    /**
+     * 验证代理处理器配置
+     */
+    private validateProxyHandler;
+    /**
+     * 验证 HTTP 处理器配置
+     */
+    private validateHttpHandler;
+    /**
+     * 验证函数处理器配置
+     */
+    private validateFunctionHandler;
+    /**
+     * 验证脚本处理器配置
+     */
+    private validateScriptHandler;
+    /**
+     * 验证链式处理器配置
+     */
+    private validateChainHandler;
+    /**
+     * 验证 MCP 处理器配置
+     */
+    private validateMCPHandler;
+    /**
+     * 检查是否配置了有效的 customMCP 工具
+     */
+    hasValidCustomMCPTools(): boolean;
+    /**
+     * 添加自定义 MCP 工具
+     */
+    addCustomMCPTool(tool: CustomMCPTool): void;
+    /**
+     * 批量添加自定义 MCP 工具
+     * @param tools 要添加的工具数组
+     */
+    addCustomMCPTools(tools: CustomMCPTool[]): Promise<void>;
+    /**
+     * 删除自定义 MCP 工具
+     */
+    removeCustomMCPTool(toolName: string): void;
+    /**
+     * 更新单个自定义 MCP 工具配置
+     * @param toolName 工具名称
+     * @param updatedTool 更新后的工具配置
+     */
+    updateCustomMCPTool(toolName: string, updatedTool: CustomMCPTool): void;
+    /**
+     * 更新自定义 MCP 工具配置
+     */
+    updateCustomMCPTools(tools: CustomMCPTool[]): void;
+    /**
+     * 获取 Web UI 配置
+     */
+    getWebUIConfig(): Readonly<WebUIConfig>;
+    /**
+     * 获取 Web UI 端口号
+     */
+    getWebUIPort(): number;
+    /**
+     * 通知 Web 界面配置已更新
+     * 如果 Web 服务器正在运行，通过 WebSocket 广播配置更新
+     */
+    private notifyConfigUpdate;
+    /**
+     * 更新 Web UI 配置
+     */
+    updateWebUIConfig(webUIConfig: Partial<WebUIConfig>): void;
+    /**
+     * 设置 Web UI 端口号
+     */
+    setWebUIPort(port: number): void;
+    updatePlatformConfig(platformName: string, platformConfig: PlatformConfig): void;
+    /**
+     * 获取扣子平台配置
+     */
+    getCozePlatformConfig(): CozePlatformConfig | null;
+    /**
+     * 获取扣子 API Token
+     */
+    getCozeToken(): string | null;
+    /**
+     * 设置扣子平台配置
+     */
+    setCozePlatformConfig(config: CozePlatformConfig): void;
+    /**
+     * 检查扣子平台配置是否有效
+     */
+    isCozeConfigValid(): boolean;
+    /**
+     * 更新 mcpServerConfig 中的工具使用统计信息（内部实现）
+     * @param serverName 服务名称
+     * @param toolName 工具名称
+     * @param callTime 调用时间（ISO 8601 格式）
+     * @param incrementUsageCount 是否增加使用计数
+     * @private
+     */
+    private _updateMCPServerToolStats;
+    /**
+     * 更新 customMCP 中的工具使用统计信息（服务名+工具名版本）
+     * @param serverName 服务名称
+     * @param toolName 工具名称
+     * @param callTime 调用时间（ISO 8601 格式）
+     * @private
+     */
+    private updateCustomMCPToolStats;
+    /**
+     * 获取统计更新锁（确保同一工具的统计更新串行执行）
+     * @param toolKey 工具键
+     * @private
+     */
+    private acquireStatsUpdateLock;
+    /**
+     * 释放统计更新锁
+     * @param toolKey 工具键
+     * @private
+     */
+    private releaseStatsUpdateLock;
+    /**
+     * 带并发控制的工具统计更新（CustomMCP 工具）
+     * @param toolName 工具名称
+     * @param incrementUsageCount 是否增加使用计数
+     */
+    updateToolUsageStatsWithLock(toolName: string, incrementUsageCount?: boolean): Promise<void>;
+    /**
+     * 带并发控制的工具统计更新（MCP 服务工具）
+     * @param serviceName 服务名称
+     * @param toolName 工具名称
+     * @param callTime 调用时间
+     * @param incrementUsageCount 是否增加使用计数
+     */
+    updateMCPServerToolStatsWithLock(serviceName: string, toolName: string, callTime: string, incrementUsageCount?: boolean): Promise<void>;
+    /**
+     * 清理所有统计更新锁（用于异常恢复）
+     */
+    clearAllStatsUpdateLocks(): void;
+    /**
+     * 获取统计更新锁状态（用于调试和监控）
+     */
+    getStatsUpdateLocks(): string[];
+    /**
+     * 获取工具调用日志配置
+     */
+    getToolCallLogConfig(): Readonly<ToolCallLogConfig>;
+    /**
+     * 更新工具调用日志配置
+     */
+    updateToolCallLogConfig(toolCallLogConfig: Partial<ToolCallLogConfig>): void;
+    /**
+     * 获取配置目录路径（与配置文件同级目录）
+     */
+    getConfigDir(): string;
+}
+declare const configManager: ConfigManager;
+
+/**
+ * 配置适配器
+ * 将旧的配置格式转换为新的 MCPServiceConfig 格式，确保向后兼容性
+ */
+
+/**
+ * 配置验证错误类
+ */
+declare class ConfigValidationError extends Error {
+    readonly configName?: string | undefined;
+    constructor(message: string, configName?: string | undefined);
+}
+declare enum MCPTransportType {
+    STDIO = "stdio",
+    SSE = "sse",
+    STREAMABLE_HTTP = "streamable-http"
+}
+interface MCPServiceConfig {
+    name: string;
+    type: MCPTransportType;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+    modelScopeAuth?: boolean;
+}
+/**
+ * 将旧的 MCPServerConfig 转换为新的 MCPServiceConfig
+ */
+declare function convertLegacyToNew(serviceName: string, legacyConfig: MCPServerConfig): MCPServiceConfig;
+/**
+ * 批量转换配置
+ */
+declare function convertLegacyConfigBatch(legacyConfigs: Record<string, MCPServerConfig>): Record<string, MCPServiceConfig>;
+/**
+ * 检查是否为 ModelScope URL
+ * 使用 URL hostname 检查而非简单的字符串包含检查，防止安全绕过
+ */
+declare function isModelScopeURL(url: string): boolean;
+/**
+ * 获取配置类型描述
+ */
+declare function getConfigTypeDescription(config: MCPServerConfig): string;
+
+export { type AppConfig, type ChainHandlerConfig, ConfigManager, ConfigValidationError, type ConnectionConfig, type CozePlatformConfig, type CustomMCPConfig, type CustomMCPTool, type FunctionHandlerConfig, type HandlerConfig, type HttpHandlerConfig, type LocalMCPServerConfig, type MCPHandlerConfig, type MCPServerConfig, type MCPServerToolsConfig, type MCPServiceConfig, type MCPToolConfig, MCPTransportType, type ModelScopeConfig, type PlatformConfig, type PlatformsConfig, type ProxyHandlerConfig, type SSEMCPServerConfig, type ScriptHandlerConfig, type StreamableHTTPMCPServerConfig, type ToolCallLogConfig, type WebServerInstance, type WebUIConfig, configManager, convertLegacyConfigBatch, convertLegacyToNew, getConfigTypeDescription, isModelScopeURL };