@lee-zg/melange 1.2.3 → 1.2.5

package/dist/generator-CEj5qxFh.d.cts

@@ -0,0 +1,1752 @@
+import { C as Container } from './container-B8n-ok8M.cjs';
+
+/**
+ * @fileoverview 语音模块类型定义
+ * @module melange/plugins/speech/types
+ * @description 语音合成和语音识别的类型定义
+ */
+/**
+ * 语音服务提供商类型
+ */
+type SpeechProviderType = 'browser' | 'azure' | 'google' | 'aws' | 'custom';
+/**
+ * 语音服务状态
+ */
+type SpeechServiceStatus = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * 语音服务错误
+ */
+interface SpeechError {
+    /** 错误代码 */
+    code: string;
+    /** 错误信息 */
+    message: string;
+    /** 原始错误对象 */
+    originalError?: Error;
+}
+/**
+ * 语音服务基础配置
+ */
+interface BaseSpeechConfig {
+    /** 语言代码 (如 'zh-CN', 'en-US') */
+    lang?: string;
+    /** 首选提供商 */
+    preferredProvider?: SpeechProviderType;
+    /** 是否自动降级 */
+    autoFallback?: boolean;
+    /** 降级提供商列表 */
+    fallbackProviders?: SpeechProviderType[];
+}
+/**
+ * 语音信息
+ */
+interface VoiceInfo {
+    /** 语音唯一标识 */
+    id: string;
+    /** 语音名称 */
+    name: string;
+    /** 语言代码 */
+    lang: string;
+    /** 是否为本地语音 */
+    localService: boolean;
+    /** 是否为默认语音 */
+    default: boolean;
+    /** 提供商类型 */
+    provider: SpeechProviderType;
+}
+/**
+ * 语音合成配置
+ */
+interface SynthesisConfig extends BaseSpeechConfig {
+    /** 语音对象或语音名称 */
+    voice?: VoiceInfo | string;
+    /** 音量 (0-1) */
+    volume?: number;
+    /** 语速 (0.1-10) */
+    rate?: number;
+    /** 音调 (0-2) */
+    pitch?: number;
+}
+/**
+ * 语音合成事件类型
+ */
+type SynthesisEventType = 'start' | 'end' | 'pause' | 'resume' | 'boundary' | 'mark' | 'error';
+/**
+ * 语音合成事件数据
+ */
+interface SynthesisEvent {
+    /** 事件类型 */
+    type: SynthesisEventType;
+    /** 当前字符索引 */
+    charIndex?: number;
+    /** 当前字符长度 */
+    charLength?: number;
+    /** 经过的时间（毫秒） */
+    elapsedTime?: number;
+    /** 边界名称 */
+    name?: string;
+    /** 错误信息 */
+    error?: SpeechError;
+}
+/**
+ * 语音合成事件处理器
+ */
+type SynthesisEventHandler = (event: SynthesisEvent) => void;
+/**
+ * 语音合成提供商接口
+ */
+interface SynthesisProvider {
+    /** 提供商类型 */
+    readonly type: SpeechProviderType;
+    /** 检查是否可用 */
+    isAvailable(): boolean;
+    /** 获取可用语音列表 */
+    getVoices(): Promise<VoiceInfo[]>;
+    /** 朗读文本 */
+    speak(text: string, config?: SynthesisConfig): Promise<void>;
+    /** 暂停 */
+    pause(): void;
+    /** 继续 */
+    resume(): void;
+    /** 取消 */
+    cancel(): void;
+    /** 是否正在朗读 */
+    isSpeaking(): boolean;
+    /** 是否已暂停 */
+    isPaused(): boolean;
+    /** 添加事件监听 */
+    on(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+    /** 移除事件监听 */
+    off(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+}
+/**
+ * 语音合成器接口
+ */
+interface SpeechSynthesizer {
+    /** 当前使用的提供商 */
+    readonly currentProvider: SpeechProviderType;
+    /** 服务状态 */
+    readonly status: SpeechServiceStatus;
+    /** 初始化 */
+    initialize(config?: SynthesisConfig): Promise<void>;
+    /** 获取可用语音列表 */
+    getVoices(): Promise<VoiceInfo[]>;
+    /** 朗读文本 */
+    speak(text: string, config?: SynthesisConfig): Promise<void>;
+    /** 暂停 */
+    pause(): void;
+    /** 继续 */
+    resume(): void;
+    /** 取消 */
+    cancel(): void;
+    /** 是否正在朗读 */
+    isSpeaking(): boolean;
+    /** 是否已暂停 */
+    isPaused(): boolean;
+    /** 添加事件监听 */
+    on(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+    /** 移除事件监听 */
+    off(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+    /** 销毁实例 */
+    dispose(): void;
+}
+/**
+ * 识别结果项
+ */
+interface RecognitionResultItem {
+    /** 识别的文本 */
+    transcript: string;
+    /** 置信度 (0-1) */
+    confidence: number;
+    /** 是否为最终结果 */
+    isFinal: boolean;
+}
+/**
+ * 识别结果
+ */
+interface RecognitionResult {
+    /** 结果列表 */
+    results: RecognitionResultItem[];
+    /** 最佳结果 */
+    bestTranscript: string;
+    /** 最佳置信度 */
+    bestConfidence: number;
+    /** 是否为最终结果 */
+    isFinal: boolean;
+}
+/**
+ * 语音识别配置
+ */
+interface RecognitionConfig extends BaseSpeechConfig {
+    /** 是否连续识别 */
+    continuous?: boolean;
+    /** 是否返回中间结果 */
+    interimResults?: boolean;
+    /** 最大备选结果数 */
+    maxAlternatives?: number;
+    /** 语法列表 (仅部分浏览器支持) */
+    grammars?: string[];
+}
+/**
+ * 语音识别事件类型
+ */
+type RecognitionEventType = 'start' | 'end' | 'result' | 'error' | 'soundstart' | 'soundend' | 'speechstart' | 'speechend' | 'audiostart' | 'audioend' | 'nomatch';
+/**
+ * 语音识别事件数据
+ */
+interface RecognitionEvent {
+    /** 事件类型 */
+    type: RecognitionEventType;
+    /** 识别结果 (仅 result 事件) */
+    result?: RecognitionResult;
+    /** 错误信息 (仅 error 事件) */
+    error?: SpeechError;
+}
+/**
+ * 语音识别事件处理器
+ */
+type RecognitionEventHandler = (event: RecognitionEvent) => void;
+/**
+ * 语音识别提供商接口
+ */
+interface RecognitionProvider {
+    /** 提供商类型 */
+    readonly type: SpeechProviderType;
+    /** 检查是否可用 */
+    isAvailable(): boolean;
+    /** 开始识别 */
+    start(config?: RecognitionConfig): Promise<void>;
+    /** 停止识别 */
+    stop(): void;
+    /** 中止识别 */
+    abort(): void;
+    /** 是否正在识别 */
+    isListening(): boolean;
+    /** 添加事件监听 */
+    on(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+    /** 移除事件监听 */
+    off(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+}
+/**
+ * 语音识别器接口
+ */
+interface SpeechRecognizer {
+    /** 当前使用的提供商 */
+    readonly currentProvider: SpeechProviderType;
+    /** 服务状态 */
+    readonly status: SpeechServiceStatus;
+    /** 初始化 */
+    initialize(config?: RecognitionConfig): Promise<void>;
+    /** 开始识别 */
+    start(config?: RecognitionConfig): Promise<void>;
+    /** 停止识别 */
+    stop(): void;
+    /** 中止识别 */
+    abort(): void;
+    /** 是否正在识别 */
+    isListening(): boolean;
+    /** 添加事件监听 */
+    on(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+    /** 移除事件监听 */
+    off(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+    /** 销毁实例 */
+    dispose(): void;
+}
+/**
+ * Azure 语音服务配置
+ */
+interface AzureSpeechConfig {
+    /** 订阅密钥 */
+    subscriptionKey: string;
+    /** 服务区域 */
+    region: string;
+    /** 自定义端点 */
+    endpoint?: string;
+}
+/**
+ * Google Cloud Speech 配置
+ */
+interface GoogleSpeechConfig {
+    /** API 密钥 */
+    apiKey: string;
+    /** 项目 ID */
+    projectId?: string;
+}
+/**
+ * AWS Polly/Transcribe 配置
+ */
+interface AWSSpeechConfig {
+    /** 访问密钥 ID */
+    accessKeyId: string;
+    /** 秘密访问密钥 */
+    secretAccessKey: string;
+    /** 区域 */
+    region: string;
+}
+/**
+ * 自定义提供商配置
+ */
+interface CustomProviderConfig {
+    /** 合成 API 端点 */
+    synthesisEndpoint?: string;
+    /** 识别 API 端点 */
+    recognitionEndpoint?: string;
+    /** 自定义请求头 */
+    headers?: Record<string, string>;
+    /** 认证令牌 */
+    authToken?: string;
+}
+/**
+ * 提供商配置联合类型
+ */
+type ProviderConfig = AzureSpeechConfig | GoogleSpeechConfig | AWSSpeechConfig | CustomProviderConfig;
+
+/**
+ * @fileoverview 语音合成 (TTS) 实现 - 商业级版本 v2.0
+ * @module melange/plugins/speech/synthesis
+ * @description 生产级 Web 语音合成插件
+ *
+ * 架构：
+ * [UI层] -> [SpeechSynthesizerImpl] -> [NativeStrategy / CloudStrategy]
+ *                                          |
+ *                                          +-> [音频核心]: AudioContext, 流式播放
+ *                                          +-> [适配器]: AzureAdapter, GoogleAdapter, TencentAdapter...
+ *
+ * 功能特性：
+ * 1. 多模式: 支持原生 Web Speech API & 云端 TTS 服务
+ * 2. 状态机: IDLE -> LOADING -> SPEAKING -> PAUSED
+ * 3. 插件化: 内置 Azure/Google/AWS/讯飞/腾讯/百度/阿里 适配器
+ * 4. 核心: AudioContext 流式播放 + 音频队列管理
+ * 5. 兼容性: 多浏览器支持 + 自动降级处理
+ */
+
+/**
+ * 合成器状态枚举
+ */
+declare enum SynthesisStatus {
+    /** 空闲状态 */
+    IDLE = "IDLE",
+    /** 加载中（获取语音/准备中） */
+    LOADING = "LOADING",
+    /** 正在播放 */
+    SPEAKING = "SPEAKING",
+    /** 已暂停 */
+    PAUSED = "PAUSED"
+}
+/**
+ * 合成引擎模式
+ */
+type SynthesisEngineMode = 'native' | 'cloud' | 'auto';
+/**
+ * 云端 TTS 音频格式
+ */
+type CloudAudioFormat = 'mp3' | 'wav' | 'ogg' | 'pcm';
+/**
+ * 云端合成结果接口
+ */
+interface ISynthesisResult {
+    /** 音频数据 */
+    audioData: ArrayBuffer;
+    /** 音频格式 */
+    format: CloudAudioFormat;
+    /** 音频时长 (ms) */
+    duration?: number;
+    /** 原始响应数据 */
+    original?: unknown;
+}
+/**
+ * 合成错误接口
+ */
+interface ISynthesisError {
+    /** 错误代码 */
+    code: 'NETWORK' | 'NOT_SUPPORTED' | 'INVALID_TEXT' | 'ADAPTER_ERROR' | 'PLAYBACK_ERROR' | 'UNKNOWN';
+    /** 错误信息 */
+    message: string;
+    /** 原始错误 */
+    originalError?: unknown;
+}
+/**
+ * 云端语音信息
+ */
+interface ICloudVoice {
+    /** 语音 ID */
+    id: string;
+    /** 语音名称 */
+    name: string;
+    /** 语言代码 */
+    lang: string;
+    /** 性别 */
+    gender?: 'male' | 'female' | 'neutral';
+    /** 提供商名称 */
+    provider: string;
+}
+/**
+ * 高级合成配置
+ */
+interface IAdvancedSynthesisConfig extends SynthesisConfig {
+    /** 合成引擎模式 */
+    mode?: SynthesisEngineMode;
+    /** 云端适配器 */
+    cloudAdapter?: ICloudSynthesisAdapter;
+    /** 音频格式偏好 */
+    audioFormat?: CloudAudioFormat;
+    /** 是否启用 SSML */
+    enableSSML?: boolean;
+    /** 是否预加载音频 */
+    preload?: boolean;
+    /** 音频缓存大小 */
+    cacheSize?: number;
+}
+/**
+ * 云端合成适配器接口
+ * 提供统一的第三方语音合成服务集成接口
+ */
+interface ICloudSynthesisAdapter {
+    /** 适配器名称 */
+    readonly name: string;
+    /**
+     * 合成语音
+     * @param text 要合成的文本
+     * @param config 合成配置
+     * @returns 合成结果（音频数据）
+     */
+    synthesize(text: string, config?: IAdvancedSynthesisConfig): Promise<ISynthesisResult>;
+    /**
+     * 获取可用语音列表
+     * @returns 语音列表
+     */
+    getVoices?(): Promise<ICloudVoice[]>;
+    /**
+     * 检查适配器是否可用
+     * @returns 是否可用
+     */
+    isAvailable?(): boolean;
+}
+/**
+ * 音频播放工具集
+ */
+declare const SynthesisAudioUtils: {
+    /**
+     * 创建 AudioContext
+     */
+    createAudioContext(): AudioContext;
+    /**
+     * ArrayBuffer 转 Base64
+     */
+    arrayBufferToBase64(buffer: ArrayBuffer): string;
+    /**
+     * Base64 转 ArrayBuffer
+     */
+    base64ToArrayBuffer(base64: string): ArrayBuffer;
+    /**
+     * 计算音频时长（粗略估算）
+     */
+    estimateDuration(byteLength: number, format: CloudAudioFormat): number;
+};
+/**
+ * 通用语音合成适配器。
+ *
+ * @description
+ * 这是生产推荐的 BFF 模式适配器。浏览器只向自有后端提交文本、语言、
+ * 语速、音色和输出格式，云厂商密钥、签名、限流、审计和错误映射必须由
+ * 后端完成。
+ *
+ * @remarks
+ * 默认协议：
+ * - `POST {baseUrl}/synthesize` 返回音频二进制；
+ * - `GET {baseUrl}/voices` 返回 `{ voices: ICloudVoice[] }`；
+ * - 错误响应建议映射为 `{ code, message, retryable, requestId? }`。
+ */
+declare class GenericSynthesisAdapter implements ICloudSynthesisAdapter {
+    private baseUrl;
+    readonly name = "Generic/BFF";
+    constructor(baseUrl: string);
+    synthesize(text: string, config?: IAdvancedSynthesisConfig): Promise<ISynthesisResult>;
+    getVoices(): Promise<ICloudVoice[]>;
+}
+/**
+ * Azure 语音服务直连适配器。
+ *
+ * @deprecated demo-only。该适配器会在浏览器请求中使用 subscription key，
+ * 仅适合本地验证 API 形态。生产环境请使用 `GenericSynthesisAdapter`
+ * 连接自有 BFF，由后端持有和使用 Azure 凭证。
+ */
+declare class AzureSynthesisAdapter implements ICloudSynthesisAdapter {
+    private subscriptionKey;
+    private region;
+    private defaultVoice;
+    readonly name = "Azure";
+    constructor(subscriptionKey: string, region: string, defaultVoice?: string);
+    synthesize(text: string, config?: IAdvancedSynthesisConfig): Promise<ISynthesisResult>;
+    getVoices(): Promise<ICloudVoice[]>;
+    private escapeXml;
+}
+/**
+ * Google Cloud TTS 直连适配器。
+ *
+ * @deprecated demo-only。该适配器会将 API key 放入浏览器请求 URL，
+ * 仅适合本地验证。生产环境请通过 BFF 代理调用 Google Cloud TTS。
+ */
+declare class GoogleSynthesisAdapter implements ICloudSynthesisAdapter {
+    private apiKey;
+    private defaultVoice;
+    readonly name = "Google";
+    constructor(apiKey: string, defaultVoice?: string);
+    synthesize(text: string, config?: IAdvancedSynthesisConfig): Promise<ISynthesisResult>;
+    getVoices(): Promise<ICloudVoice[]>;
+}
+/**
+ * AWS Polly 示例适配器。
+ *
+ * @deprecated demo-only。构造函数保留 AWS 长期凭证参数以兼容旧 API，
+ * 但生产环境不得在前端创建或保存这些凭证，应由 BFF 完成签名和调用。
+ */
+declare class AWSSynthesisAdapter implements ICloudSynthesisAdapter {
+    private accessKeyId;
+    private secretAccessKey;
+    private region;
+    private defaultVoice;
+    readonly name = "AWS";
+    constructor(accessKeyId: string, secretAccessKey: string, region: string, defaultVoice?: string);
+    synthesize(text: string, config?: IAdvancedSynthesisConfig): Promise<ISynthesisResult>;
+    getVoices(): Promise<ICloudVoice[]>;
+}
+/**
+ * 讯飞云示例适配器。
+ *
+ * @deprecated demo-only。仅用于展示参数映射和 BFF 请求形态。生产环境应在
+ * 后端完成讯飞 WebAPI 鉴权签名，不应在浏览器保存 apiKey/apiSecret。
+ */
+declare class XunfeiSynthesisAdapter implements ICloudSynthesisAdapter {
+    private appId;
+    private defaultVoice;
+    readonly name = "Xunfei";
+    constructor(appId: string, _apiKey?: string, _apiSecret?: string, defaultVoice?: string);
+    synthesize(text: string, config?: IAdvancedSynthesisConfig): Promise<ISynthesisResult>;
+    getVoices(): Promise<ICloudVoice[]>;
+}
+/**
+ * 腾讯云示例适配器。
+ *
+ * @deprecated demo-only。构造函数保留 secretId/secretKey 以兼容旧 API，
+ * 但生产环境必须在 BFF 完成 TC3-HMAC-SHA256 签名。
+ */
+declare class TencentSynthesisAdapter implements ICloudSynthesisAdapter {
+    private secretId;
+    private secretKey;
+    private defaultVoice;
+    readonly name = "Tencent";
+    constructor(secretId: string, secretKey: string, defaultVoice?: string);
+    synthesize(text: string, config?: IAdvancedSynthesisConfig): Promise<ISynthesisResult>;
+    getVoices(): Promise<ICloudVoice[]>;
+}
+/**
+ * 百度云示例适配器。
+ *
+ * @deprecated experimental。access token 不应由浏览器长期持有。生产环境请由
+ * BFF 管理 token 生命周期、限流和错误映射。
+ */
+declare class BaiduSynthesisAdapter implements ICloudSynthesisAdapter {
+    private accessToken;
+    private defaultVoice;
+    readonly name = "Baidu";
+    constructor(accessToken: string, defaultVoice?: string);
+    synthesize(text: string, config?: IAdvancedSynthesisConfig): Promise<ISynthesisResult>;
+    getVoices(): Promise<ICloudVoice[]>;
+}
+/**
+ * 阿里云示例适配器。
+ *
+ * @deprecated demo-only。构造函数保留 accessKeySecret 以兼容旧 API，
+ * 生产环境请通过 BFF 获取临时凭证或由后端直接调用阿里云服务。
+ */
+declare class AlibabaSynthesisAdapter implements ICloudSynthesisAdapter {
+    private accessKeyId;
+    private appKey;
+    private defaultVoice;
+    readonly name = "Alibaba";
+    constructor(accessKeyId: string, _accessKeySecret: string, appKey: string, defaultVoice?: string);
+    synthesize(text: string, config?: IAdvancedSynthesisConfig): Promise<ISynthesisResult>;
+    getVoices(): Promise<ICloudVoice[]>;
+}
+/**
+ * 语音合成器实现
+ * 统一封装原生合成和云端合成
+ */
+declare class SpeechSynthesizerImpl implements SpeechSynthesizer {
+    private strategy;
+    private config;
+    private _currentProvider;
+    private _status;
+    private eventHandlers;
+    private customProviders;
+    get currentProvider(): SpeechProviderType;
+    get status(): SpeechServiceStatus;
+    /**
+     * 获取当前合成状态
+     */
+    get synthesisStatus(): SynthesisStatus;
+    /**
+     * 初始化语音合成器
+     */
+    initialize(config?: SynthesisConfig): Promise<void>;
+    /**
+     * 初始化合成策略
+     */
+    private initializeStrategy;
+    /**
+     * 转发策略事件
+     */
+    private forwardStrategyEvents;
+    /**
+     * 获取可用语音列表
+     */
+    getVoices(): Promise<VoiceInfo[]>;
+    /**
+     * 朗读文本
+     */
+    speak(text: string, config?: SynthesisConfig): Promise<void>;
+    /**
+     * 暂停朗读
+     */
+    pause(): void;
+    /**
+     * 继续朗读
+     */
+    resume(): void;
+    /**
+     * 取消朗读
+     */
+    cancel(): void;
+    /**
+     * 是否正在朗读
+     */
+    isSpeaking(): boolean;
+    /**
+     * 是否已暂停
+     */
+    isPaused(): boolean;
+    /**
+     * 添加事件监听
+     */
+    on(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+    /**
+     * 移除事件监听
+     */
+    off(event: SynthesisEventType, handler: SynthesisEventHandler): void;
+    /**
+     * 触发事件
+     */
+    private emit;
+    /**
+     * 销毁实例
+     */
+    dispose(): void;
+    /**
+     * 注册自定义提供商
+     */
+    registerProvider(type: SpeechProviderType, provider: SynthesisProvider): void;
+    /**
+     * 使用云端适配器
+     */
+    useCloudAdapter(adapter: ICloudSynthesisAdapter): void;
+}
+/**
+ * 创建语音合成器实例
+ * @param config - 可选的合成配置
+ * @returns 语音合成器实例
+ *
+ * @example
+ * ```typescript
+ * // 使用原生合成
+ * const synthesizer = await createSpeechSynthesizer({
+ *   lang: 'zh-CN',
+ *   rate: 1.0,
+ * });
+ *
+ * // 使用云端合成 (Azure)
+ * const azureAdapter = new AzureSynthesisAdapter('key', 'eastasia');
+ * const cloudSynthesizer = await createSpeechSynthesizer({
+ *   mode: 'cloud',
+ *   cloudAdapter: azureAdapter,
+ * });
+ *
+ * await synthesizer.speak('你好，世界！');
+ * ```
+ */
+declare function createSpeechSynthesizer(config?: SynthesisConfig | IAdvancedSynthesisConfig): Promise<SpeechSynthesizer>;
+/**
+ * 检查当前环境是否支持语音合成
+ * @returns 是否支持语音合成
+ */
+declare function isSpeechSynthesisSupported(): boolean;
+/**
+ * 快速朗读文本（一次性使用）
+ * @param text - 要朗读的文本
+ * @param config - 可选的合成配置
+ *
+ * @example
+ * ```typescript
+ * // 快速朗读
+ * await speak('你好，世界！');
+ *
+ * // 带配置的朗读
+ * await speak('Hello World', { lang: 'en-US', rate: 0.8 });
+ * ```
+ */
+declare function speak(text: string, config?: SynthesisConfig | IAdvancedSynthesisConfig): Promise<void>;
+/**
+ * 快速朗读文本（云端模式）
+ * @param text - 要朗读的文本
+ * @param adapter - 云端适配器
+ * @param config - 可选配置
+ */
+declare function speakWithCloud(text: string, adapter: ICloudSynthesisAdapter, config?: SynthesisConfig): Promise<void>;
+
+/**
+ * @fileoverview 语音识别 (STT) 实现 - 商业级版本 v2.0
+ * @module melange/plugins/speech/recognition
+ * @description 生产级 Web 语音识别插件
+ *
+ * 架构：
+ * [UI层] -> [SpeechRecognizerImpl] -> [NativeStrategy / CloudStrategy]
+ *                                          |
+ *                                          +-> [音频核心]: Worklet, VAD, Resample
+ *                                          +-> [适配器]: BaiduAdapter, XunfeiAdapter, TencentAdapter...
+ *
+ * 功能特性：
+ * 1. 多模式: 支持 WebSocket 流式识别 & HTTP 短语音识别
+ * 2. 状态机: IDLE -> CONNECTING -> RECORDING -> PROCESSING
+ * 3. 插件化: 内置 讯飞/腾讯/百度/阿里/Google/Azure 适配器
+ * 4. 核心: AudioWorklet + VAD + 自动重采样 + WAV编码
+ * 5. 兼容性: 自动降级处理 (ScriptProcessor) + 断网缓冲队列
+ */
+
+declare global {
+    interface Window {
+        SpeechRecognition?: unknown;
+        webkitSpeechRecognition?: unknown;
+        webkitAudioContext?: typeof AudioContext;
+    }
+}
+/**
+ * 识别器状态枚举
+ */
+declare enum RecognitionStatus {
+    /** 空闲状态 */
+    IDLE = "IDLE",
+    /** 连接中 */
+    CONNECTING = "CONNECTING",
+    /** 录音中 */
+    RECORDING = "RECORDING",
+    /** 处理中/上传中 */
+    PROCESSING = "PROCESSING"
+}
+/**
+ * 识别引擎模式
+ */
+type RecognitionEngineMode = 'native' | 'cloud' | 'auto';
+/**
+ * 云端传输协议类型
+ */
+type CloudTransportType = 'websocket' | 'http';
+/**
+ * 识别结果接口
+ */
+interface IRecognitionResult {
+    /** 识别文本 */
+    transcript: string;
+    /** 是否为最终结果 */
+    isFinal: boolean;
+    /** 置信度 (0-1) */
+    confidence: number;
+    /** 原始响应数据 */
+    original?: unknown;
+}
+/**
+ * 识别错误接口
+ */
+interface IRecognitionError {
+    /** 错误代码 */
+    code: 'NETWORK' | 'NOT_ALLOWED' | 'NO_SPEECH' | 'NOT_SUPPORTED' | 'VAD_TIMEOUT' | 'ADAPTER_ERROR' | 'UNKNOWN';
+    /** 错误信息 */
+    message: string;
+    /** 原始错误 */
+    originalError?: unknown;
+}
+/**
+ * 音频配置接口
+ */
+interface IAudioConfig {
+    /** 目标采样率 (默认 16000) */
+    sampleRate?: number;
+    /** VAD 阈值 (0.01 ~ 0.5) */
+    vadThreshold?: number;
+    /** VAD 静音超时 (ms) */
+    vadDuration?: number;
+    /** 是否启用回声消除 */
+    echoCancellation?: boolean;
+    /** 是否启用噪声抑制 */
+    noiseSuppression?: boolean;
+    /** 是否启用自动增益控制 */
+    autoGainControl?: boolean;
+}
+/**
+ * 高级识别配置
+ */
+interface IAdvancedRecognitionConfig extends RecognitionConfig {
+    /** 识别引擎模式 */
+    mode?: RecognitionEngineMode;
+    /** 云端适配器 */
+    cloudAdapter?: ICloudRecognitionAdapter;
+    /** 传输协议 */
+    transport?: CloudTransportType;
+    /** 音频配置 */
+    audioConfig?: IAudioConfig;
+    /** 是否启用自动重连 */
+    autoReconnect?: boolean;
+    /** 最大重连次数 */
+    maxReconnectAttempts?: number;
+    /** 重连间隔 (ms) */
+    reconnectInterval?: number;
+}
+/**
+ * 云端识别适配器接口
+ * 提供统一的第三方语音识别服务集成接口
+ */
+interface ICloudRecognitionAdapter {
+    /** 适配器名称 */
+    readonly name: string;
+    /**
+     * 获取 WebSocket 连接地址
+     * @returns WebSocket URL
+     */
+    getConnectUrl?(): Promise<string> | string;
+    /**
+     * 获取握手参数
+     * @returns 握手消息
+     */
+    getHandshakeParams?(): unknown;
+    /**
+     * HTTP 短语音识别
+     * @param audioData WAV/PCM 二进制数据
+     * @returns 识别结果
+     */
+    recognizeShortAudio?(audioData: ArrayBuffer): Promise<IRecognitionResult>;
+    /**
+     * 转换音频数据格式
+     * @param pcmData PCM 原始数据
+     * @returns 转换后的数据
+     */
+    transformAudioData?(pcmData: ArrayBuffer): ArrayBuffer | string;
+    /**
+     * 解析识别结果
+     * @param data 原始响应数据
+     * @returns 识别结果
+     */
+    parseResult(data: unknown): IRecognitionResult | null;
+    /**
+     * 检查适配器是否可用
+     * @returns 是否可用
+     */
+    isAvailable?(): boolean;
+}
+/**
+ * 音频处理工具集
+ */
+declare const AudioUtils: {
+    /**
+     * 重采样音频数据
+     * @param data 原始音频数据
+     * @param inputRate 输入采样率
+     * @param outputRate 输出采样率
+     * @returns 重采样后的数据
+     */
+    resample(data: Float32Array, inputRate: number, outputRate: number): Float32Array;
+    /**
+     * Float32 转 Int16 PCM
+     * @param input Float32 数据
+     * @returns Int16 PCM 数据
+     */
+    floatTo16BitPCM(input: Float32Array): Int16Array;
+    /**
+     * 计算音量 RMS
+     * @param data 音频数据
+     * @returns RMS 值
+     */
+    calculateRMS(data: Float32Array): number;
+    /**
+     * 合并 PCM 片段
+     * @param buffers PCM 缓冲区数组
+     * @param totalLength 总采样数
+     * @returns 合并后的 Int16 数组
+     */
+    mergeBuffers(buffers: ArrayBuffer[], totalLength: number): Int16Array;
+    /**
+     * PCM 转 WAV 封装
+     * @param samples PCM 采样数据
+     * @param sampleRate 采样率
+     * @param channels 声道数
+     * @returns WAV 格式 ArrayBuffer
+     */
+    encodeWAV(samples: Int16Array, sampleRate?: number, channels?: number): ArrayBuffer;
+    /**
+     * ArrayBuffer 转 Base64
+     * @param buffer ArrayBuffer
+     * @returns Base64 字符串
+     */
+    arrayBufferToBase64(buffer: ArrayBuffer): string;
+};
+/**
+ * 通用语音识别适配器。
+ *
+ * @description
+ * 这是生产推荐的 BFF 模式适配器。浏览器只上传用户授权后的短音频或连接
+ * 自有 WebSocket 网关，云厂商密钥、签名、大小限制、超时、审计和错误码
+ * 必须由后端完成。
+ *
+ * @remarks
+ * 默认协议：
+ * - `GET/WS {baseUrl}` 用于流式识别；
+ * - `POST {baseUrl}/recognize` 使用 `multipart/form-data` 字段 `file` 上传 WAV；
+ * - JSON 结果支持 `{ text, score }` 或 `{ transcript, confidence }`；
+ * - 错误响应建议映射为 `{ code, message, retryable, requestId? }`。
+ */
+declare class GenericAdapter implements ICloudRecognitionAdapter {
+    private baseUrl;
+    readonly name = "Generic/BFF";
+    constructor(baseUrl: string);
+    getConnectUrl(): string;
+    recognizeShortAudio(audioData: ArrayBuffer): Promise<IRecognitionResult>;
+    parseResult(data: Record<string, unknown>): IRecognitionResult | null;
+}
+/**
+ * 讯飞云示例适配器。
+ *
+ * @deprecated demo-only。该适配器只展示讯飞听写协议结构。生产环境应由 BFF
+ * 生成鉴权 URL 和请求签名，前端不得保存 apiKey/apiSecret。
+ */
+declare class XunfeiAdapter implements ICloudRecognitionAdapter {
+    private appId;
+    readonly name = "Xunfei";
+    /** API Key - 生产环境应在后端使用 */
+    readonly apiKey: string | undefined;
+    /** API Secret - 生产环境应在后端使用 */
+    readonly apiSecret: string | undefined;
+    constructor(appId: string, apiKey?: string, apiSecret?: string);
+    getConnectUrl(): string;
+    getHandshakeParams(): Record<string, unknown>;
+    recognizeShortAudio(audioData: ArrayBuffer): Promise<IRecognitionResult>;
+    parseResult(data: Record<string, unknown>): IRecognitionResult | null;
+}
+/**
+ * 腾讯云示例适配器。
+ *
+ * @deprecated demo-only。生产环境必须在 BFF 完成 TC3-HMAC-SHA256 签名，
+ * 不应在浏览器保存 secretId/secretKey。
+ */
+declare class TencentAdapter implements ICloudRecognitionAdapter {
+    readonly name = "Tencent";
+    /** Secret ID - 生产环境应在后端使用 */
+    readonly secretId: string;
+    /** Secret Key - 生产环境应在后端使用 */
+    readonly secretKey: string;
+    constructor(secretId: string, secretKey: string);
+    recognizeShortAudio(audioData: ArrayBuffer): Promise<IRecognitionResult>;
+    parseResult(data: Record<string, unknown>): IRecognitionResult | null;
+}
+/**
+ * 百度云示例适配器。
+ *
+ * @deprecated experimental。access token、appId 和 appKey 不应由浏览器长期持有。
+ * 生产环境请通过 BFF 管理 token、音频大小限制、超时和错误映射。
+ */
+declare class BaiduAdapter implements ICloudRecognitionAdapter {
+    private accessToken;
+    private appId?;
+    private appKey?;
+    private devPid;
+    readonly name = "Baidu";
+    constructor(accessToken: string, appId?: string | undefined, appKey?: string | undefined, devPid?: number);
+    getConnectUrl(): string;
+    getHandshakeParams(): Record<string, unknown>;
+    recognizeShortAudio(audioData: ArrayBuffer): Promise<IRecognitionResult>;
+    parseResult(data: Record<string, unknown>): IRecognitionResult | null;
+}
+/**
+ * 阿里云示例适配器。
+ *
+ * @deprecated demo-only。构造函数保留 accessKeySecret 以兼容旧 API，
+ * 生产环境应通过 BFF 获取临时凭证或由后端直接调用阿里云服务。
+ */
+declare class AlibabaAdapter implements ICloudRecognitionAdapter {
+    private accessKeyId;
+    private appKey;
+    readonly name = "Alibaba";
+    /** Access Key Secret - 生产环境应在后端使用 */
+    readonly accessKeySecret: string;
+    constructor(accessKeyId: string, accessKeySecret: string, appKey: string);
+    getConnectUrl(): string;
+    getHandshakeParams(): Record<string, unknown>;
+    recognizeShortAudio(audioData: ArrayBuffer): Promise<IRecognitionResult>;
+    parseResult(data: Record<string, unknown>): IRecognitionResult | null;
+    private generateUUID;
+}
+/**
+ * Google Cloud Speech 直连适配器。
+ *
+ * @deprecated demo-only。该适配器会将 API key 放入浏览器请求 URL，
+ * 生产环境请通过 BFF 代理调用 Google Cloud Speech。
+ */
+declare class GoogleAdapter implements ICloudRecognitionAdapter {
+    private apiKey;
+    private languageCode;
+    readonly name = "Google";
+    constructor(apiKey: string, languageCode?: string);
+    recognizeShortAudio(audioData: ArrayBuffer): Promise<IRecognitionResult>;
+    parseResult(data: Record<string, unknown>): IRecognitionResult | null;
+}
+/**
+ * Azure Speech 直连适配器。
+ *
+ * @deprecated demo-only。该适配器会在浏览器请求中使用 subscription key，
+ * 生产环境请通过 BFF 代理调用 Azure Speech。
+ */
+declare class AzureAdapter implements ICloudRecognitionAdapter {
+    private subscriptionKey;
+    private region;
+    private language;
+    readonly name = "Azure";
+    constructor(subscriptionKey: string, region: string, language?: string);
+    getConnectUrl(): string;
+    getHandshakeParams(): Record<string, unknown>;
+    recognizeShortAudio(audioData: ArrayBuffer): Promise<IRecognitionResult>;
+    parseResult(data: Record<string, unknown>): IRecognitionResult | null;
+}
+/**
+ * 语音识别器实现
+ * 统一封装原生识别和云端识别
+ */
+declare class SpeechRecognizerImpl implements SpeechRecognizer {
+    private strategy;
+    private config;
+    private _currentProvider;
+    private _status;
+    private eventHandlers;
+    private customProviders;
+    get currentProvider(): SpeechProviderType;
+    get status(): SpeechServiceStatus;
+    /**
+     * 获取当前识别状态
+     */
+    get recognitionStatus(): RecognitionStatus;
+    /**
+     * 初始化语音识别器
+     */
+    initialize(config?: RecognitionConfig): Promise<void>;
+    /**
+     * 初始化识别策略
+     */
+    private initializeStrategy;
+    /**
+     * 转发策略事件
+     */
+    private forwardStrategyEvents;
+    /**
+     * 转换识别结果格式
+     */
+    private convertResult;
+    /**
+     * 开始识别
+     */
+    start(config?: RecognitionConfig): Promise<void>;
+    /**
+     * 停止识别
+     */
+    stop(): void;
+    /**
+     * 中止识别
+     */
+    abort(): void;
+    /**
+     * 是否正在识别
+     */
+    isListening(): boolean;
+    /**
+     * 添加事件监听
+     */
+    on(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+    /**
+     * 移除事件监听
+     */
+    off(event: RecognitionEventType, handler: RecognitionEventHandler): void;
+    /**
+     * 触发事件
+     */
+    private emit;
+    /**
+     * 销毁实例
+     */
+    dispose(): void;
+    /**
+     * 注册自定义提供商
+     */
+    registerProvider(type: SpeechProviderType, provider: RecognitionProvider): void;
+    /**
+     * 使用云端适配器
+     */
+    useCloudAdapter(adapter: ICloudRecognitionAdapter): void;
+}
+/**
+ * 创建语音识别器实例
+ * @param config 识别配置
+ * @returns 语音识别器实例
+ *
+ * @example
+ * ```typescript
+ * // 使用原生识别
+ * const recognizer = await createSpeechRecognizer({
+ *   lang: 'zh-CN',
+ *   continuous: true,
+ * });
+ *
+ * // 使用云端识别 (百度)
+ * const baiduAdapter = new BaiduAdapter('your-access-token');
+ * const cloudRecognizer = await createSpeechRecognizer({
+ *   mode: 'cloud',
+ *   cloudAdapter: baiduAdapter,
+ *   transport: 'http',
+ * });
+ *
+ * recognizer.on('result', (event) => {
+ *   console.log('识别结果:', event.result?.bestTranscript);
+ * });
+ *
+ * await recognizer.start();
+ * ```
+ */
+declare function createSpeechRecognizer(config?: RecognitionConfig | IAdvancedRecognitionConfig): Promise<SpeechRecognizer>;
+/**
+ * 检查当前环境是否支持语音识别
+ * @returns 是否支持
+ */
+declare function isSpeechRecognitionSupported(): boolean;
+/**
+ * 快速进行一次语音识别
+ * @param config 识别配置
+ * @returns 识别结果
+ *
+ * @example
+ * ```typescript
+ * const result = await listen({ lang: 'zh-CN' });
+ * console.log('识别结果:', result.bestTranscript);
+ * ```
+ */
+declare function listen(config?: RecognitionConfig | IAdvancedRecognitionConfig): Promise<RecognitionResult>;
+/**
+ * 创建带超时的语音识别
+ * @param config 识别配置
+ * @param timeout 超时时间 (ms)
+ * @returns 识别结果
+ */
+declare function listenWithTimeout(config?: RecognitionConfig | IAdvancedRecognitionConfig, timeout?: number): Promise<RecognitionResult>;
+
+/**
+ * @fileoverview 指纹识别模块类型定义
+ * @module melange/plugins/fingerprint/types
+ * @description
+ * 定义指纹识别插件对外暴露的配置、结果、组件和采集器类型。
+ *
+ * 本模块的类型设计参考 FingerprintJS 的“组件集合 -> 稳定哈希”模型，
+ * 但默认语义偏向隐私保护：组件值必须可序列化、可解释，并且鼓励调用方
+ * 使用低敏、低熵信号，不采集音频、Canvas 像素、字体枚举、浏览历史等
+ * 可能超出用户预期的内容。
+ */
+/**
+ * 内置指纹组件键。
+ *
+ * @description
+ * 这些键对应 `defaultFingerprintCollectors` 中提供的默认采集器。
+ * 调用方可以在 `FingerprintOptions.include` 或 `FingerprintOptions.exclude`
+ * 中使用这些键来精确控制组件范围。
+ *
+ * @remarks
+ * 内置键只覆盖低敏浏览器环境信息和能力检测信息。若业务需要新增字段，
+ * 应通过 `FingerprintCollector` 注册自定义采集器，并确保已获得合规授权。
+ */
+type FingerprintComponentKey = 
+/** 浏览器 User-Agent。默认会归一化补丁版本和构建号。 */
+'userAgent'
+/** 操作系统或浏览器平台标识，例如 Win32、MacIntel。 */
+ | 'platform'
+/** 浏览器首选语言，例如 zh-CN。 */
+ | 'language'
+/** 浏览器语言偏好列表，strict 模式下仅保留首选语言。 */
+ | 'languages'
+/** IANA 时区名称，strict 模式下仅记录是否可用。 */
+ | 'timezone'
+/** 当前时区偏移量，单位为分钟。 */
+ | 'timezoneOffset'
+/** 屏幕尺寸信息，balanced 模式下按桶归一化。 */
+ | 'screen'
+/** 屏幕色深。 */
+ | 'colorDepth'
+/** 设备像素比，默认按 0.25 桶归一化。 */
+ | 'pixelRatio'
+/** 硬件线程数，默认按区间分桶。 */
+ | 'hardwareConcurrency'
+/** 设备内存，默认按区间分桶。 */
+ | 'deviceMemory'
+/** 最大触摸点数量。 */
+ | 'maxTouchPoints'
+/** Cookie 是否可用。 */
+ | 'cookiesEnabled'
+/** localStorage/sessionStorage 能力检测结果。 */
+ | 'storage'
+/** IndexedDB 是否可用。 */
+ | 'indexedDB'
+/** 浏览器 Do Not Track 偏好。 */
+ | 'doNotTrack';
+/**
+ * 指纹组件来源。
+ *
+ * @description
+ * 来源用于解释组件的敏感度和用途，便于调用方在日志、审计或调试界面中
+ * 判断某个组件为什么会进入指纹计算。
+ */
+type FingerprintComponentSource = 
+/** 低熵环境信息，如语言、平台、分桶后的屏幕尺寸。 */
+'low-entropy'
+/** 能力检测信息，如存储能力、Cookie 可用性。 */
+ | 'capability'
+/** 调用方通过 `collectors` 传入的业务自定义组件。 */
+ | 'custom';
+/**
+ * 指纹隐私模式。
+ *
+ * @description
+ * 隐私模式会影响默认采集器如何处理可能带来唯一性的字段。
+ * 模式越严格，组件值越粗粒度，visitorId 的稳定性和区分度也会相应下降。
+ */
+type FingerprintPrivacyMode = 
+/** 最小化模式：尽量只保留可用性或首选项，适合隐私优先场景。 */
+'strict'
+/** 平衡模式：默认模式，保留低敏信号并对高波动字段分桶/归一化。 */
+ | 'balanced'
+/** 调试模式：保留更多原始值，便于定位环境差异，不建议生产默认启用。 */
+ | 'debug';
+/**
+ * 指纹哈希算法。
+ *
+ * @description
+ * `fnv1a64` 体积小、速度快，适合本地非安全标识生成。
+ * `sha256` 会优先使用 Web Crypto API，在不可用时自动降级到 `fnv1a64`。
+ *
+ * @remarks
+ * 指纹哈希不是加密身份凭证，不应作为鉴权、风控唯一依据或秘密值使用。
+ */
+type FingerprintHashAlgorithm = 
+/** 64 位 FNV-1a 非加密哈希，默认算法。 */
+'fnv1a64'
+/** SHA-256 哈希，依赖 `globalThis.crypto.subtle`。 */
+ | 'sha256';
+/**
+ * 可序列化的指纹组件值。
+ *
+ * @description
+ * 组件值必须可以稳定序列化，才能保证相同组件集合在不同执行时机生成相同
+ * 的哈希输入。这里刻意限制为 JSON 兼容值，避免函数、DOM 节点、错误对象、
+ * Map/Set 等不可预测结构进入指纹计算。
+ */
+type FingerprintValue = 
+/** 字符串组件值。 */
+string
+/** 数字组件值。应优先使用分桶后的粗粒度数值。 */
+ | number
+/** 布尔组件值，常用于能力检测。 */
+ | boolean
+/** 明确表示采集不到或环境不支持。 */
+ | null
+/** 由可序列化值组成的只读数组。 */
+ | readonly FingerprintValue[]
+/** 键为字符串、值为可序列化值的只读对象。 */
+ | {
+    readonly [key: string]: FingerprintValue;
+};
+/**
+ * 单个指纹组件。
+ *
+ * @template T - 组件值类型，必须是可稳定序列化的 `FingerprintValue`
+ *
+ * @description
+ * 组件是指纹计算的最小单元。每个组件包含值、来源、采集耗时和稳定性权重。
+ * 生成器只会将 `value` 写入哈希输入，其余字段用于调试、审计和置信度计算。
+ */
+interface FingerprintComponent<T extends FingerprintValue = FingerprintValue> {
+    /**
+     * 组件值。
+     *
+     * @remarks
+     * 该值会参与 `visitorId` 计算。请勿放入直接身份信息、精确位置、账号 ID、
+     * 设备序列号或其他可单独识别个人的数据。
+     */
+    readonly value: T;
+    /**
+     * 组件来源。
+     *
+     * @remarks
+     * 来源不会参与哈希计算，只用于解释该组件来自内置低熵采集、能力检测，
+     * 还是调用方提供的自定义采集器。
+     */
+    readonly source: FingerprintComponentSource;
+    /**
+     * 组件采集耗时，单位毫秒。
+     *
+     * @remarks
+     * 该字段用于性能分析，不参与哈希计算。耗时由 `context.now()` 计算，
+     * 在浏览器中通常来自 `performance.now()`。
+     */
+    readonly duration: number;
+    /**
+     * 组件稳定性权重，范围 0-1。
+     *
+     * @remarks
+     * 数值越高表示该组件越稳定、越适合参与“同一浏览器环境”的粗略判断。
+     * 它只参与 `confidence.score` 计算，不会改变组件值或哈希算法。
+     */
+    readonly confidence: number;
+}
+/**
+ * 指纹组件集合。
+ *
+ * @description
+ * 以组件键为索引的映射。生成哈希前会按键名排序，以避免对象插入顺序影响
+ * `visitorId`。
+ */
+type FingerprintComponentMap = Record<string, FingerprintComponent>;
+/**
+ * 指纹置信度说明。
+ *
+ * @description
+ * 置信度是一个可解释的质量指标，用于告诉调用方本次结果包含多少组件、
+ * 跳过了多少组件，以及组件稳定性的大致水平。
+ *
+ * @remarks
+ * 置信度不是概率，不代表识别某个自然人的准确率，也不应作为风控阈值的
+ * 唯一依据。
+ */
+interface FingerprintConfidence {
+    /**
+     * 置信度分数，范围 0-1。
+     *
+     * @remarks
+     * 当前实现会结合组件平均权重和采集覆盖率，并将最高值限制在 0.99，
+     * 避免表达“绝对确定”的含义。
+     */
+    readonly score: number;
+    /**
+     * 参与哈希的组件数量。
+     *
+     * @remarks
+     * 仅统计成功采集且没有超时/抛错的组件。
+     */
+    readonly componentCount: number;
+    /**
+     * 被跳过的组件数量。
+     *
+     * @remarks
+     * 组件可能因为 include/exclude 过滤、采集异常、超时或返回 `undefined`
+     * 被跳过。
+     */
+    readonly skippedCount: number;
+}
+/**
+ * 指纹生成结果。
+ *
+ * @description
+ * 与 FingerprintJS 类似，结果包含稳定标识 `visitorId` 和组件详情
+ * `components`。Melange 额外提供 `confidence`、`duration` 和版本信息，
+ * 方便业务侧做性能监控和兼容判断。
+ */
+interface FingerprintResult {
+    /**
+     * 生成的访问者标识。
+     *
+     * @remarks
+     * 这是组件值稳定序列化后计算出的哈希。它不是用户 ID，也不是安全令牌；
+     * 不建议跨业务、跨站点或无限期保存。
+     */
+    readonly visitorId: string;
+    /**
+     * 参与生成指纹的组件。
+     *
+     * @remarks
+     * 只包含成功采集的组件。被 include/exclude 过滤、超时或抛错的组件不会出现。
+     */
+    readonly components: FingerprintComponentMap;
+    /**
+     * 本次指纹结果的质量说明。
+     */
+    readonly confidence: FingerprintConfidence;
+    /**
+     * 指纹模块版本。
+     *
+     * @remarks
+     * 当默认采集器、归一化策略或哈希输入格式变化时，版本可用于帮助调用方
+     * 做兼容处理。
+     */
+    readonly version: string;
+    /**
+     * 本次生成总耗时，单位毫秒。
+     *
+     * @remarks
+     * 包括组件采集、序列化和哈希计算耗时。
+     */
+    readonly duration: number;
+    /**
+     * 生成时间戳，来自 `Date.now()`。
+     */
+    readonly generatedAt: number;
+}
+/**
+ * 指纹组件采集上下文。
+ *
+ * @description
+ * 生成器会把上下文传给每个内置或自定义采集器。上下文中包含已合并默认值
+ * 的配置，以及统一的时间函数，方便采集器根据隐私模式调整返回值。
+ */
+interface FingerprintCollectorContext {
+    /**
+     * 当前已解析配置。
+     *
+     * @remarks
+     * 这里的配置已合并生成器默认配置和本次调用覆盖配置，不包含 `undefined`。
+     */
+    readonly options: RequiredFingerprintOptions;
+    /**
+     * 当前时间函数，返回毫秒级时间。
+     *
+     * @returns 当前高精度或普通时间戳
+     */
+    now(): number;
+}
+/**
+ * 自定义指纹组件采集器。
+ *
+ * @template T - 采集器返回值类型，必须是 `FingerprintValue`
+ *
+ * @description
+ * 业务可以通过 `FingerprintOptions.collectors` 传入自定义采集器，将自身
+ * 已合法获得、低敏且可解释的状态纳入指纹。采集器可以同步或异步返回。
+ *
+ * @remarks
+ * 采集器返回 `undefined` 会被视为跳过组件；返回 `null` 则表示“明确无值”，
+ * 会参与哈希计算。采集器抛错或超时也会被跳过，不会中断整体指纹生成。
+ */
+interface FingerprintCollector<T extends FingerprintValue = FingerprintValue> {
+    /**
+     * 组件键。
+     *
+     * @remarks
+     * 键名会出现在 `components` 中，并参与稳定排序。建议使用业务内唯一、
+     * 语义清晰的 camelCase 名称，避免覆盖内置组件，除非明确需要替换。
+     */
+    readonly key: string;
+    /**
+     * 组件来源。
+     *
+     * @defaultValue `'custom'`
+     */
+    readonly source?: FingerprintComponentSource;
+    /**
+     * 组件稳定性权重，范围 0-1。
+     *
+     * @defaultValue `0.4`
+     *
+     * @remarks
+     * 权重只影响置信度，不影响哈希。自定义低敏业务状态通常建议给较低权重。
+     */
+    readonly confidence?: number;
+    /**
+     * 采集组件值。
+     *
+     * @param context - 指纹组件采集上下文，包含隐私模式、超时配置和时间函数
+     * @returns 可序列化组件值；返回 Promise 时生成器会等待其完成或超时
+     */
+    collect(context: FingerprintCollectorContext): T | Promise<T>;
+}
+/**
+ * 指纹生成配置。
+ *
+ * @description
+ * 配置既可以传给 `createFingerprintGenerator` 作为实例默认值，也可以传给
+ * `get` 或 `getFingerprint` 作为本次调用覆盖值。本次调用配置优先级更高。
+ */
+interface FingerprintOptions {
+    /**
+     * 命名空间盐值，用于隔离不同业务域的指纹结果。
+     *
+     * @defaultValue `'melange'`
+     *
+     * @remarks
+     * 建议每个产品、租户或用途使用不同盐值，避免不同业务之间的 visitorId
+     * 可以直接关联。
+     */
+    readonly salt?: string;
+    /**
+     * 是否启用内存缓存。
+     *
+     * @defaultValue `true`
+     *
+     * @remarks
+     * 缓存只存在于当前生成器实例内，不写入 localStorage、Cookie 或 IndexedDB。
+     */
+    readonly cache?: boolean;
+    /**
+     * 内存缓存有效期，单位毫秒。
+     *
+     * @defaultValue `300000`
+     */
+    readonly cacheTtl?: number;
+    /**
+     * 单个组件采集超时时间，单位毫秒。
+     *
+     * @defaultValue `80`
+     *
+     * @remarks
+     * 超时的组件会被跳过，避免慢组件拖累首屏或交互流程。
+     */
+    readonly componentTimeout?: number;
+    /**
+     * 指纹隐私模式。
+     *
+     * @defaultValue `'balanced'`
+     */
+    readonly privacyMode?: FingerprintPrivacyMode;
+    /**
+     * 指纹哈希算法。
+     *
+     * @defaultValue `'fnv1a64'`
+     */
+    readonly hashAlgorithm?: FingerprintHashAlgorithm;
+    /**
+     * 屏幕尺寸分桶大小。
+     *
+     * @defaultValue `100`
+     *
+     * @remarks
+     * 仅影响非 debug 模式下的屏幕尺寸组件。值越大，隐私越强，区分度越低。
+     */
+    readonly screenBucketSize?: number;
+    /**
+     * 是否归一化 User-Agent。
+     *
+     * @defaultValue
+     * `balanced` 和 `strict` 模式为 `true`，`debug` 模式为 `false`。
+     */
+    readonly normalizeUserAgent?: boolean;
+    /**
+     * 只采集指定组件。
+     *
+     * @remarks
+     * 为空数组或未提供时表示不限制。若同时提供 `include` 和 `exclude`，
+     * 会先判断 include，再应用 exclude。
+     */
+    readonly include?: readonly string[];
+    /**
+     * 排除指定组件。
+     *
+     * @remarks
+     * 可用于关闭业务不希望采集的内置组件，例如 `userAgent` 或 `screen`。
+     */
+    readonly exclude?: readonly string[];
+    /**
+     * 自定义低敏组件采集器。
+     *
+     * @remarks
+     * 自定义采集器会追加到内置采集器之后，并受 include/exclude 和超时配置控制。
+     */
+    readonly collectors?: readonly FingerprintCollector[];
+}
+/**
+ * 内部已填充默认值的配置。
+ *
+ * @description
+ * 生成器内部使用的配置形态。与 `FingerprintOptions` 不同，这里所有字段都
+ * 已经有确定值，便于采集器和内部函数直接读取。
+ */
+interface RequiredFingerprintOptions {
+    /** 命名空间盐值。 */
+    readonly salt: string;
+    /** 是否启用当前生成器实例内的内存缓存。 */
+    readonly cache: boolean;
+    /** 缓存有效期，单位毫秒。 */
+    readonly cacheTtl: number;
+    /** 单组件采集超时时间，单位毫秒。 */
+    readonly componentTimeout: number;
+    /** 已解析隐私模式。 */
+    readonly privacyMode: FingerprintPrivacyMode;
+    /** 已解析哈希算法。 */
+    readonly hashAlgorithm: FingerprintHashAlgorithm;
+    /** 已解析屏幕尺寸分桶大小。 */
+    readonly screenBucketSize: number;
+    /** 已解析 User-Agent 归一化开关。 */
+    readonly normalizeUserAgent: boolean;
+    /** 已解析 include 列表。 */
+    readonly include: readonly string[];
+    /** 已解析 exclude 列表。 */
+    readonly exclude: readonly string[];
+    /** 已解析自定义采集器列表。 */
+    readonly collectors: readonly FingerprintCollector[];
+}
+/**
+ * 指纹生成器接口。
+ *
+ * @description
+ * 生成器封装默认配置和内存缓存，适合在应用启动时创建一次并通过依赖注入
+ * 或模块单例复用。
+ */
+interface FingerprintGenerator {
+    /**
+     * 获取指纹结果。
+     *
+     * @param options - 本次调用的覆盖配置
+     * @returns 指纹生成结果
+     */
+    get(options?: FingerprintOptions): Promise<FingerprintResult>;
+    /**
+     * 清除当前生成器实例的内存缓存。
+     *
+     * @remarks
+     * 该方法不会清除浏览器存储，因为本模块默认不会写入持久化存储。
+     */
+    clearCache(): void;
+}
+
+/**
+ * @fileoverview 隐私友好的浏览器/设备指纹生成器
+ * @module melange/plugins/fingerprint/generator
+ * @description
+ * 参考 FingerprintJS 的组件化指纹模型：采集组件、稳定序列化、计算哈希并
+ * 返回 `visitorId`。与常见高熵指纹方案不同，本实现默认只采集低敏信号，
+ * 并通过分桶、归一化、超时保护和内存缓存降低隐私与性能风险。
+ */
+
+/**
+ * 指纹模块版本。
+ *
+ * @description
+ * 版本用于标识当前指纹生成策略。默认采集器、归一化规则或哈希输入结构
+ * 发生不兼容变化时，应同步调整版本。
+ */
+declare const FINGERPRINT_VERSION = "1.0.0";
+/**
+ * 指纹生成器 DI 令牌。
+ *
+ * @description
+ * 用于在 Melange 的 `Container` 中注册和解析 `FingerprintGenerator`。
+ *
+ * @example
+ * ```typescript
+ * registerFingerprintPlugin(container);
+ * const generator = container.resolve<FingerprintGenerator>(FINGERPRINT_GENERATOR);
+ * ```
+ */
+declare const FINGERPRINT_GENERATOR: unique symbol;
+/**
+ * 浏览器/设备指纹生成器实现。
+ *
+ * @description
+ * 生成器持有默认配置和一次内存缓存。它会并发执行内置采集器和自定义采集器，
+ * 对组件结果做稳定序列化后计算 `visitorId`。
+ *
+ * @example
+ * ```typescript
+ * const generator = new FingerprintGeneratorImpl({ salt: 'my-app' });
+ * const result = await generator.get();
+ * ```
+ */
+declare class FingerprintGeneratorImpl implements FingerprintGenerator {
+    private readonly baseOptions;
+    /**
+     * 当前生成器实例的内存缓存。
+     *
+     * @remarks
+     * 只缓存最后一次匹配配置的结果，不持久化。
+     */
+    private cacheEntry;
+    /**
+     * 创建指纹生成器。
+     *
+     * @param baseOptions - 生成器默认配置；后续 `get(options)` 可覆盖这些配置
+     */
+    constructor(baseOptions?: FingerprintOptions);
+    /**
+     * 获取指纹结果。
+     *
+     * @description
+     * 生成流程：
+     * 1. 合并默认配置和本次调用配置；
+     * 2. 命中内存缓存时直接返回；
+     * 3. 并发采集组件并跳过失败组件；
+     * 4. 稳定序列化组件值并计算哈希；
+     * 5. 返回 visitorId、组件详情、置信度和耗时。
+     *
+     * @param options - 本次生成配置，会覆盖构造函数中的同名默认配置
+     * @returns 指纹生成结果
+     */
+    get(options?: FingerprintOptions): Promise<FingerprintResult>;
+    /**
+     * 清除内存缓存。
+     *
+     * @description
+     * 下次调用 `get()` 时会重新采集组件。该方法不会清理任何浏览器存储，
+     * 因为本插件默认不会写入持久化存储。
+     */
+    clearCache(): void;
+}
+/**
+ * 创建指纹生成器实例。
+ *
+ * @description
+ * 适合需要多次生成指纹、复用默认配置或通过 DI 管理生命周期的场景。
+ *
+ * @param options - 生成器默认配置
+ * @returns 指纹生成器实例
+ */
+declare function createFingerprintGenerator(options?: FingerprintOptions): FingerprintGenerator;
+/**
+ * 快速获取一次指纹。
+ *
+ * @description
+ * 便捷函数。内部会创建临时生成器并立即调用 `get()`，适合一次性使用。
+ * 如果需要复用缓存，请使用 `createFingerprintGenerator()`。
+ *
+ * @param options - 指纹生成配置
+ * @returns 指纹生成结果
+ */
+declare function getFingerprint(options?: FingerprintOptions): Promise<FingerprintResult>;
+/**
+ * 将指纹生成器注册到依赖注入容器。
+ *
+ * @description
+ * 使用 Melange 的容器将 `FingerprintGenerator` 注册为单例，方便应用服务
+ * 通过 `FINGERPRINT_GENERATOR` 令牌解析。
+ *
+ * @param container - 目标容器；默认使用 `globalContainer`
+ * @param options - 注册到容器中的生成器默认配置
+ * @returns 传入的容器实例，便于链式调用
+ */
+declare function registerFingerprintPlugin(container?: Container, options?: FingerprintOptions): Container;
+/**
+ * 检查当前环境是否具备基础指纹采集能力。
+ *
+ * @description
+ * 只要存在 `navigator` 或 `screen`，就认为具备基础采集能力。Node 环境通常
+ * 返回 false，测试或 SSR 场景可据此跳过浏览器相关逻辑。
+ *
+ * @returns 当前环境是否支持基础指纹采集
+ */
+declare function isFingerprintSupported(): boolean;
+
+export { type AzureSpeechConfig as $, AzureSynthesisAdapter as A, BaiduSynthesisAdapter as B, type SpeechProviderType as C, type SpeechServiceStatus as D, type SpeechError as E, FingerprintGeneratorImpl as F, GenericSynthesisAdapter as G, type BaseSpeechConfig as H, type SynthesisConfig as I, type SynthesisEventType as J, type SynthesisEvent as K, type SynthesisEventHandler as L, type SynthesisProvider as M, type SpeechSynthesizer as N, type RecognitionResultItem as O, type RecognitionResult as P, type RecognitionConfig as Q, RecognitionStatus as R, SynthesisStatus as S, TencentSynthesisAdapter as T, type RecognitionEventType as U, type VoiceInfo as V, type RecognitionEvent as W, XunfeiSynthesisAdapter as X, type RecognitionEventHandler as Y, type RecognitionProvider as Z, type SpeechRecognizer as _, SynthesisAudioUtils as a, type GoogleSpeechConfig as a0, type AWSSpeechConfig as a1, type CustomProviderConfig as a2, type ProviderConfig as a3, type SynthesisEngineMode as a4, type CloudAudioFormat as a5, type ISynthesisResult as a6, type ISynthesisError as a7, type ICloudVoice as a8, type IAdvancedSynthesisConfig as a9, type ICloudSynthesisAdapter as aa, type RecognitionEngineMode as ab, type CloudTransportType as ac, type IRecognitionResult as ad, type IRecognitionError as ae, type IAudioConfig as af, type IAdvancedRecognitionConfig as ag, type ICloudRecognitionAdapter as ah, type FingerprintComponentKey as ai, type FingerprintComponentSource as aj, type FingerprintPrivacyMode as ak, type FingerprintHashAlgorithm as al, type FingerprintValue as am, type FingerprintComponent as an, type FingerprintComponentMap as ao, type FingerprintConfidence as ap, type FingerprintResult as aq, type FingerprintCollectorContext as ar, type FingerprintCollector as as, type FingerprintOptions as at, type FingerprintGenerator as au, FINGERPRINT_VERSION as av, FINGERPRINT_GENERATOR as aw, GoogleSynthesisAdapter as b, AWSSynthesisAdapter as c, AlibabaSynthesisAdapter as d, SpeechSynthesizerImpl as e, createSpeechSynthesizer as f, speakWithCloud as g, SpeechRecognizerImpl as h, isSpeechSynthesisSupported as i, createSpeechRecognizer as j, isSpeechRecognitionSupported as k, listen as l, listenWithTimeout as m, AudioUtils as n, GenericAdapter as o, XunfeiAdapter as p, TencentAdapter as q, BaiduAdapter as r, speak as s, AlibabaAdapter as t, GoogleAdapter as u, AzureAdapter as v, createFingerprintGenerator as w, getFingerprint as x, registerFingerprintPlugin as y, isFingerprintSupported as z };