@spacex110/core 0.1.11

package/dist/index.d.ts

@@ -0,0 +1,620 @@
+export declare class AIChannelManager {
+    private storageAdapter;
+    private channels;
+    private activeChannelId;
+    private storagePrefix;
+    private activeChannelKey;
+    private proxyUrl?;
+    private listeners;
+    constructor(options?: ChannelManagerOptions);
+    /** 监听事件 */
+    on(event: ChannelEventType, listener: ChannelEventListener): () => void;
+    /** 取消监听 */
+    off(event: ChannelEventType, listener: ChannelEventListener): void;
+    private emit;
+    private getStorageKey;
+    private loadChannels;
+    private loadActiveChannel;
+    private saveChannel;
+    private deleteChannelFromStorage;
+    private saveActiveChannel;
+    /** 添加通道 */
+    addChannel(config: AIConfig, name?: string): Promise<ChannelConfig>;
+    /** 删除通道 */
+    deleteChannel(id: string): void;
+    /** 更新通道 */
+    updateChannel(id: string, config: Partial<AIConfig>, name?: string): Promise<ChannelConfig>;
+    /** 获取所有通道 */
+    getChannels(): ChannelConfig[];
+    /** 根据 ID 获取通道 */
+    getChannel(id: string): ChannelConfig | undefined;
+    /** 按 Provider ID 过滤通道 */
+    getChannelsByProvider(providerId: string): ChannelConfig[];
+    /** 按模型能力过滤通道（如 vision, reasoning, audio） */
+    getChannelsByCapability(capability: ModelCapability): ChannelConfig[];
+    /** 按 API 格式过滤通道（如 openai, anthropic, gemini） */
+    getChannelsByFormat(format: ApiFormat): ChannelConfig[];
+    /** 按连接状态过滤通道 */
+    getChannelsByStatus(status: ChannelConfig['status']): ChannelConfig[];
+    /** 综合条件查询通道 */
+    queryChannels(filter: ChannelFilter): ChannelConfig[];
+    /** 获取通道数量 */
+    getChannelCount(): number;
+    /** 获取当前激活的通道 */
+    getActiveChannel(): ChannelConfig | undefined;
+    /** 设置当前激活的通道 */
+    setActiveChannel(id: string): void;
+    /** 清除当前激活的通道 */
+    clearActiveChannel(): void;
+    /** 获取 Provider 的可用模型列表（动态获取 + 静态兜底） */
+    getProviderModels(providerId: string, apiKey?: string, baseUrl?: string): Promise<Model[]>;
+    /** 获取通道对应的 Provider 的模型列表 */
+    getChannelModels(id: string): Promise<Model[]>;
+    /** 获取 Provider 的静态模型列表（不发起网络请求） */
+    getStaticModelList(providerId: string): Model[];
+    /** 按能力过滤模型列表 */
+    getModelsByCapability(models: Model[], capability: ModelCapability): Model[];
+    /** 获取所有已配置的模型摘要列表 */
+    getConfiguredModels(): Array<{
+        channelId: string;
+        providerId: string;
+        providerName: string;
+        model: string;
+        modelName: string;
+        apiFormat: ApiFormat;
+        capabilities: ModelCapability[];
+        status: ChannelConfig['status'];
+    }>;
+    /** 更新通道的 API Key */
+    updateApiKey(id: string, apiKey: string): Promise<ChannelConfig>;
+    /** 验证 API Key 格式（简单校验，非空且长度合理） */
+    validateApiKey(providerId: string, apiKey: string): {
+        valid: boolean;
+        message?: string;
+    };
+    /** 脱敏显示 API Key（如 sk-••••••••J4xK） */
+    maskApiKey(apiKey: string): string;
+    /** 获取通道的脱敏 API Key */
+    getMaskedApiKey(id: string): string;
+    /** 使用当前激活的通道发送聊天请求 */
+    chat(message: string, options?: {
+        messages?: Array<{
+            role: string;
+            content: string;
+        }>;
+        maxTokens?: number;
+    }): Promise<ChatResult>;
+    /** 使用指定通道发送聊天请求 */
+    chatWith(channelId: string, message: string, options?: {
+        messages?: Array<{
+            role: string;
+            content: string;
+        }>;
+        maxTokens?: number;
+    }): Promise<ChatResult>;
+    /** 使用当前激活通道发送流式聊天。onDelta 每次收到「累计完整文本」。 */
+    chatStream(message: string, options: {
+        messages?: Array<{
+            role: string;
+            content: string;
+        }>;
+        maxTokens?: number;
+        onDelta: (full: string) => void;
+        signal?: AbortSignal;
+    }): Promise<ChatResult>;
+    /** 使用指定通道发送流式聊天。onDelta 每次收到「累计完整文本」。 */
+    chatWithStream(channelId: string, message: string, options: {
+        messages?: Array<{
+            role: string;
+            content: string;
+        }>;
+        maxTokens?: number;
+        onDelta: (full: string) => void;
+        signal?: AbortSignal;
+    }): Promise<ChatResult>;
+    /** 测试指定通道的连接 */
+    testChannel(id: string): Promise<{
+        success: boolean;
+        latencyMs?: number;
+        message?: string;
+    }>;
+    /** 测试所有通道连接 */
+    testAllChannels(): Promise<Array<{
+        id: string;
+        channel: ChannelConfig;
+        result: {
+            success: boolean;
+            latencyMs?: number;
+            message?: string;
+        };
+    }>>;
+    /** 获取所有可用的 Provider */
+    getAvailableProviders(): Provider[];
+    /** 获取单个 Provider 信息 */
+    getProvider(providerId: string): Provider | undefined;
+    /** 按 API 格式获取 Provider 列表 */
+    getProvidersByFormat(format: ApiFormat): Provider[];
+    /** 导出所有通道配置（不包含 API Key 明文） */
+    exportChannels(includeApiKeys?: boolean): string;
+    /** 导入通道配置 */
+    importChannels(json: string, merge?: boolean): Promise<ChannelConfig[]>;
+    /** 清空所有通道 */
+    clearAllChannels(): void;
+    /** 批量删除通道 */
+    deleteChannels(ids: string[]): void;
+    /** 获取统计信息 */
+    getStats(): {
+        total: number;
+        byStatus: Record<string, number>;
+        byFormat: Record<string, number>;
+        byProvider: Record<string, number>;
+        byCapability: Record<string, number>;
+    };
+}
+
+export declare interface AIConfig {
+    providerId: string;
+    apiKey: string;
+    model: string;
+    modelName?: string;
+    baseUrl?: string;
+}
+
+/** AIConfigForm 组件的 Props */
+export declare interface AIConfigFormProps {
+    /**
+     * 自定义请求处理器
+     * 用于接管获取模型列表和连通性测试的请求
+     * 如果提供此函数，proxyUrl 在这两种操作中将被忽略
+     */
+    modelFetcher?: ModelFetcher;
+    /** 后端代理地址（必需，除非提供了 modelFetcher） */
+    proxyUrl?: string;
+    /** Provider 配置（可选，默认使用全部内置 Providers） */
+    config?: ProviderConfig;
+    /** 初始配置（可选，用于编辑已有配置） */
+    initialConfig?: Partial<AIConfig>;
+    /** 表单标题 */
+    title?: string;
+    /** 是否显示配置预览区域 */
+    showPreview?: boolean;
+    /** 保存按钮文本 */
+    saveButtonText?: string;
+    /** 是否禁用整个表单 */
+    disabled?: boolean;
+}
+
+/**
+ * AI Provider Selector - Core Types
+ * Framework-agnostic type definitions
+ */
+export declare type ApiFormat = 'openai' | 'anthropic' | 'gemini' | 'cohere';
+
+/** 通道配置（扩展 AIConfig，包含更多元数据） */
+export declare interface ChannelConfig extends AIConfig {
+    /** 通道唯一标识 */
+    id: string;
+    /** 通道名称（用户自定义） */
+    name?: string;
+    /** Provider 名称 */
+    providerName: string;
+    /** 模型显示名称 */
+    modelName: string;
+    /** API 格式 */
+    apiFormat: ApiFormat;
+    /** 模型能力列表 */
+    capabilities?: ModelCapability[];
+    /** 上下文窗口大小 */
+    contextLength?: number;
+    /** 创建时间 */
+    createdAt: number;
+    /** 最后使用时间 */
+    lastUsedAt?: number;
+    /** 连接状态 */
+    status?: 'untested' | 'connected' | 'error';
+    /** 最后错误信息 */
+    lastError?: string;
+}
+
+declare type ChannelEventListener = (data: any) => void;
+
+/** 事件类型 */
+export declare type ChannelEventType = 'add' | 'update' | 'delete' | 'activate' | 'chat' | 'test' | 'clear';
+
+/** 通道查询过滤条件 */
+export declare interface ChannelFilter {
+    /** 按 Provider ID 过滤 */
+    providerId?: string;
+    /** 按 API 格式过滤 */
+    apiFormat?: ApiFormat;
+    /** 按模型能力过滤 */
+    capability?: ModelCapability;
+    /** 按连接状态过滤 */
+    status?: ChannelConfig['status'];
+    /** 关键字搜索（匹配名称、模型名、Provider 名） */
+    keyword?: string;
+}
+
+/** 通道管理器配置选项 */
+export declare interface ChannelManagerOptions {
+    /** 存储适配器（默认使用加密存储） */
+    storageAdapter?: StorageAdapter;
+    /** 存储键名前缀 */
+    storagePrefix?: string;
+    /** 当前激活通道的存储键 */
+    activeChannelKey?: string;
+    /** 后端代理地址（可选，用于解决 CORS 问题） */
+    proxyUrl?: string;
+}
+
+/** 聊天结果 */
+export declare interface ChatResult {
+    success: boolean;
+    content?: string;
+    message?: string;
+    latencyMs?: number;
+    channelId?: string;
+    model?: string;
+}
+
+export declare function createConfigStorage(adapter?: StorageAdapter, options?: StorageOptions): {
+    /**
+     * Save AI config
+     */
+    save(config: AIConfig): void;
+    /**
+     * Load AI config
+     */
+    load(): AIConfig | null;
+    /**
+     * Clear AI config
+     */
+    clear(): void;
+};
+
+/** 自定义 Provider 定义 */
+export declare interface CustomProviderDefinition {
+    name: string;
+    baseUrl: string;
+    needsApiKey: boolean;
+    apiFormat: ApiFormat;
+    supportsModelsApi?: boolean;
+    icon?: string;
+    /** 静态模型列表（当不支持 /models API 时使用） */
+    models?: Model[];
+}
+
+/** 默认存储适配器（加密） */
+export declare const defaultStorageAdapter: StorageAdapter;
+
+export declare interface DirectChatOptions {
+    apiFormat: string;
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+    maxTokens?: number;
+}
+
+export declare interface DirectChatResult {
+    success: boolean;
+    content?: string;
+    message?: string;
+    latencyMs?: number;
+}
+
+export declare interface DirectChatStreamOptions extends DirectChatOptions {
+    /** 每收到增量文本时回调，参数为「累计完整文本」 */
+    onDelta: (full: string) => void;
+    /** 可选 AbortSignal */
+    signal?: AbortSignal;
+}
+
+/**
+ * 加密存储适配器（默认）
+ * 使用 AES 加密存储，防止 API Key 明文泄露
+ */
+export declare const encryptedStorageAdapter: StorageAdapter;
+
+export declare type FetcherActionType = 'fetchModels' | 'checkConnection';
+
+export declare interface FetcherParams {
+    type: FetcherActionType;
+    providerId: string;
+    baseUrl: string;
+    apiKey?: string;
+    modelId?: string;
+}
+
+/**
+ * Fetch available models from a provider
+ */
+export declare function fetchModels(options: FetchModelsOptions): Promise<Model[]>;
+
+export declare interface FetchModelsOptions {
+    provider: Provider;
+    apiKey?: string;
+    baseUrl?: string;
+    proxyUrl?: string;
+    fallbackToStatic?: boolean;
+}
+
+/**
+ * Get all providers as an array
+ */
+export declare function getAllProviders(): Provider[];
+
+/**
+ * Get a provider by ID
+ */
+export declare function getProvider(id: string): Provider | undefined;
+
+/**
+ * Get a single provider by ID from config
+ */
+export declare function getProviderFromConfig(providerId: string, config?: ProviderConfig): Provider | null;
+
+/**
+ * Get providers by API format
+ */
+export declare function getProvidersByFormat(format: Provider['apiFormat']): Provider[];
+
+/**
+ * Get static models for a provider
+ */
+export declare function getStaticModels(providerId: string): Model[];
+
+export declare function getStrategy(format: string): ProviderStrategy;
+
+export declare const I18N: {
+    readonly zh: {
+        readonly save: "保存配置";
+        readonly saved: "保存成功";
+        readonly providerLabel: "Provider";
+        readonly modelLabel: "Model";
+        readonly selectProvider: "选择 Provider...";
+        readonly customBaseUrl: "自定义 Base URL";
+        readonly apiKeyLabel: "API Key";
+        readonly apiKeyPlaceholder: "输入 API Key...";
+        readonly testConnection: "测试模型连接";
+        readonly testing: "测试中...";
+        readonly testSuccess: "连接成功";
+        readonly testFailed: "测试连通性失败";
+        readonly selectModel: "选择 Model...";
+        readonly searchModel: "搜索或自定义模型...";
+        readonly useCustom: "使用自定义";
+        readonly noModels: "暂无模型数据";
+        readonly apiKeyTip: "输入 API Key 后可获取完整模型列表";
+        readonly fetchModelsFailed: "拉取模型列表失败，已使用离线模型列表";
+        readonly refreshingModels: "列表刷新中...";
+        readonly modelListUpdated: "模型列表已刷新";
+        readonly preview: "配置预览";
+        readonly unselected: "(未选择)";
+        readonly customProvider: "自定义 (Custom)";
+        readonly baseUrlRequired: "请输入 Base URL";
+        readonly baseUrlPlaceholder: "输入 API 地址，如 http://localhost:11434/v1";
+        readonly apiKeyOptional: "API Key（可选）";
+        readonly modelAllTypes: "全部";
+        readonly modelCount: "个";
+    };
+    readonly en: {
+        readonly save: "Save Config";
+        readonly saved: "Saved";
+        readonly providerLabel: "Provider";
+        readonly modelLabel: "Model";
+        readonly selectProvider: "Select Provider...";
+        readonly customBaseUrl: "Custom Base URL";
+        readonly apiKeyLabel: "API Key";
+        readonly apiKeyPlaceholder: "Enter API Key...";
+        readonly testConnection: "Test Model Connection";
+        readonly testing: "Testing...";
+        readonly testSuccess: "Connection Successful";
+        readonly testFailed: "Connection Failed";
+        readonly selectModel: "Select Model...";
+        readonly searchModel: "Search or custom models...";
+        readonly useCustom: "Use custom";
+        readonly noModels: "No models found";
+        readonly apiKeyTip: "Enter API Key to fetch full model list";
+        readonly fetchModelsFailed: "Failed to fetch model list, using offline models";
+        readonly refreshingModels: "Refreshing models...";
+        readonly modelListUpdated: "Model list updated";
+        readonly preview: "Config Preview";
+        readonly unselected: "(Unselected)";
+        readonly customProvider: "自定义 (Custom)";
+        readonly baseUrlRequired: "Base URL is required";
+        readonly baseUrlPlaceholder: "Enter API URL, e.g. http://localhost:11434/v1";
+        readonly apiKeyOptional: "API Key (optional)";
+        readonly modelAllTypes: "All";
+        readonly modelCount: "";
+    };
+};
+
+export declare type I18NKeys = keyof typeof I18N['zh'];
+
+export declare type Language = keyof typeof I18N;
+
+/** @deprecated 使用 encryptedStorageAdapter 或 plainStorageAdapter */
+export declare const localStorageAdapter: StorageAdapter;
+
+export declare interface Model {
+    id: string;
+    name: string;
+    /** 模型能力列表（如 text, vision, audio） */
+    capabilities?: ModelCapability[];
+    /** 上下文窗口大小 */
+    contextLength?: number;
+}
+
+export declare const MODEL_CAPABILITIES: Record<ModelCapability, ModelCapabilityMeta>;
+
+/** 模型能力类型 */
+export declare type ModelCapability = 'text' | 'vision' | 'audio' | 'video' | 'embedding' | 'reasoning';
+
+/** 能力标签配置 */
+declare interface ModelCapabilityMeta {
+    type: ModelCapability;
+    label: string;
+    labelZh: string;
+    icon: string;
+}
+
+/**
+ * Custom fetcher for retrieving models and checking connection.
+ * If provided, this will bypass internal fetch logic.
+ *
+ * - type='fetchModels': returns Promise<Model[]>
+ * - type='checkConnection': returns Promise<{ success: boolean; latency?: number; message?: string }>
+ */
+export declare type ModelFetcher = (params: FetcherParams) => Promise<any>;
+
+/**
+ * 明文存储适配器（不推荐）
+ */
+export declare const plainStorageAdapter: StorageAdapter;
+
+export declare interface Provider {
+    id: string;
+    name: string;
+    baseUrl: string;
+    needsApiKey: boolean;
+    apiFormat: ApiFormat;
+    supportsModelsApi: boolean;
+    icon?: string;
+}
+
+export declare const PROVIDER_ID: {
+    readonly OPENAI: "openai";
+    readonly ANTHROPIC: "anthropic";
+    readonly GEMINI: "gemini";
+    readonly DEEPSEEK: "deepseek";
+    readonly OPENROUTER: "openrouter";
+    readonly GROQ: "groq";
+    readonly MISTRAL: "mistral";
+    readonly MOONSHOT: "moonshot";
+    readonly QWEN: "qwen";
+    readonly ZHIPU: "zhipu";
+    readonly SILICONFLOW: "siliconflow";
+    readonly XAI: "xai";
+    readonly TOGETHER: "together";
+    readonly FIREWORKS: "fireworks";
+    readonly DEEPINFRA: "deepinfra";
+    readonly PERPLEXITY: "perplexity";
+    readonly COHERE: "cohere";
+    readonly OLLAMA: "ollama";
+    readonly DOUBAO: "doubao";
+    readonly MINIMAX: "minimax";
+    readonly CUSTOM: "custom";
+};
+
+/** Provider 配置 JSON */
+export declare interface ProviderConfig {
+    /** 模式：default=内置+自定义，customOnly=只用自定义 */
+    mode: 'default' | 'customOnly';
+    /** 白名单：只显示这些内置 provider（仅 mode=default） */
+    include?: string[];
+    /** 黑名单：隐藏这些内置 provider（仅 mode=default） */
+    exclude?: string[];
+    /** 自定义 Providers */
+    custom?: Record<string, CustomProviderDefinition>;
+}
+
+export declare type ProviderId = typeof PROVIDER_ID[keyof typeof PROVIDER_ID];
+
+export declare const PROVIDERS: Record<string, Provider>;
+
+export declare interface ProviderStrategy {
+    format: string;
+    getModelsEndpoint?: (baseUrl: string, apiKey: string) => string;
+    parseModelsResponse?: (data: any) => Model[];
+    getChatEndpoint: (baseUrl: string, apiKey: string, model: string) => string;
+    buildChatPayload: (model: string, messages: Array<{
+        role: string;
+        content: string;
+    }>, maxTokens?: number) => Record<string, unknown>;
+    parseChatResponse: (data: any) => string;
+    /** 从一个 SSE data 块中提取增量文本（流式）。返回空字符串表示无内容。 */
+    parseStreamChunk?: (data: any) => string;
+    buildHeaders: (apiKey: string) => Record<string, string>;
+}
+
+export declare interface ResolvedConfig {
+    providers: Provider[];
+    getModels: (providerId: string) => Model[];
+}
+
+/**
+ * Resolve a ProviderConfig into usable providers and models
+ */
+export declare function resolveProviderConfig(config?: ProviderConfig): ResolvedConfig;
+
+/**
+ * 纯前端直连 AI 厂商进行聊天
+ * 注意: 这会将 API Key 暴露在浏览器中，仅适用于 Demo/测试场景
+ */
+export declare function sendDirectChat(options: DirectChatOptions): Promise<DirectChatResult>;
+
+/**
+ * 纯前端直连流式聊天。逐增量回调 onDelta(累计文本)，返回最终完整文本。
+ * 注意: 与 sendDirectChat 一样会把 API Key 暴露在浏览器，仅适用于 Demo/本地场景。
+ */
+export declare function sendDirectChatStream(options: DirectChatStreamOptions): Promise<DirectChatResult>;
+
+export declare const STATIC_MODELS: Record<string, Model[]>;
+
+export declare interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+
+/**
+ * Create a config storage instance
+ */
+declare interface StorageOptions {
+    serialize?: (data: any) => string;
+    deserialize?: (data: string) => any;
+}
+
+export declare const strategyRegistry: Record<string, ProviderStrategy>;
+
+/**
+ * Test connection to an AI provider
+ */
+export declare function testConnection(options: TestConnectionOptions): Promise<TestConnectionResult>;
+
+export declare interface TestConnectionOptions {
+    provider: Provider;
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    proxyUrl?: string;
+}
+
+declare interface TestConnectionOptions_2 {
+    apiFormat: string;
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+}
+
+export declare interface TestConnectionResult {
+    success: boolean;
+    latencyMs?: number;
+    message?: string;
+}
+
+declare interface TestConnectionResult_2 {
+    success: boolean;
+    latencyMs?: number;
+    message?: string;
+}
+
+/**
+ * 测试 AI 厂商连接 (通过发送一个简单的聊天请求)
+ */
+export declare function testDirectConnection(options: TestConnectionOptions_2): Promise<TestConnectionResult_2>;
+
+export { }