vtkviewer-vue 0.1.0

package/lib/types/plugins/PluginBase.d.ts

@@ -0,0 +1,131 @@
+import { CommandHandler, ToolbarExtensionItem, ToolbarInfoItem, ViewerContext } from '../core';
+import { IViewerPlugin, PluginConfig, PluginMetadata, ToolbarPluginGroup } from './types';
+/**
+ * 插件基类
+ */
+export declare abstract class PluginBase<TConfig extends PluginConfig = PluginConfig> implements IViewerPlugin<TConfig> {
+    abstract readonly metadata: PluginMetadata;
+    readonly dependencies?: string[];
+    readonly initOrder?: number;
+    readonly defaultConfig?: TConfig;
+    protected ctx: ViewerContext;
+    protected config: TConfig;
+    /** 事件清理追踪列表（通过 onEvent 注册的事件自动入队） */
+    private _eventCleanups;
+    /** 点击外部监听器引用，dispose 时自动清理 */
+    private _outsideClickHandler;
+    private _outsideClickCapture;
+    /** 已注册的 infoPanel 项 ID */
+    private _infoPanelId;
+    /** 已注册的扩展区项 ID */
+    private _extensionId;
+    /** 已注册的命令 ID 列表 */
+    private _commandIds;
+    /**
+     * 初始化插件
+     * 自动合并 defaultConfig 和外部 config
+     */
+    init(ctx: ViewerContext, config?: TConfig): void;
+    /**
+     * 子类重写此方法进行初始化
+     * 在 config 合并完成后调用
+     */
+    protected onInit(): void;
+    /**
+     * 释放插件资源。
+     * 基类默认实现：自动清理事件监听、点击外部监听器、infoPanel、扩展区，
+     * 再调用 onDispose() 钩子。
+     * 子类不覆写 dispose()，通过 onDispose() 扩展自定义清理。
+     */
+    dispose(): void;
+    /**
+     * 子类扩展清理钩子
+     * 用于释放 VTK 对象、注销命令、移除 DOM 监听器、重置状态等
+     */
+    protected onDispose(): void;
+    /**
+     * 插件是否可见。
+     * 子类可重写此方法实现自定义可见性逻辑。
+     * 默认行为：若 hideWhenNoModel 为 true 则无模型时隐藏。
+     */
+    isVisible(): boolean;
+    /**
+     * 注册事件并自动追踪（推荐替代直接调用 ctx.events.on）
+     * 注册的事件会在 dispose() 中统一清理
+     * @param event 事件名称
+     * @param callback 回调函数
+     */
+    protected onEvent(event: string, callback: (...args: any[]) => void): void;
+    /**
+     * 清理所有通过 onEvent() 注册的事件监听
+     */
+    private cleanupEventListeners;
+    /**
+     * 设置点击外部监听器，dispose() 时自动清理
+     * @param handler 点击处理函数
+     * @param useCapture 是否使用捕获阶段，默认 true
+     */
+    protected setupOutsideClickListener(handler: (e: MouseEvent) => void, useCapture?: boolean): void;
+    /** 内部清理点击外部监听 */
+    private _teardownOutsideClickListener;
+    /**
+     * 注册信息面板项。dispose() 时自动注销。
+     * @param item 信息面板配置（id 默认为插件 metadata.id，priority 默认为插件 order）
+     */
+    protected registerInfoPanelItem(item: Omit<ToolbarInfoItem, 'id'> & {
+        id?: string;
+    }): void;
+    /** 注销信息面板项 */
+    protected unregisterInfoPanel(): void;
+    /**
+     * 注册扩展区项。dispose() 时自动注销。
+     * @param item 扩展区配置（id 默认为插件 metadata.id，priority 默认为插件 order）
+     */
+    protected registerExtensionItem(item: Omit<ToolbarExtensionItem, 'id'> & {
+        id?: string;
+    }): void;
+    /** 注销扩展区项 */
+    protected unregisterExtension(): void;
+    /**
+     * 注册命令并自动追踪，dispose() 时自动注销
+     * @param id 命令 ID
+     * @param handler 命令处理器
+     */
+    protected registerCommand<T = void>(id: string, handler: CommandHandler<T>): void;
+    /** 注销所有通过 registerCommand 注册的命令 */
+    private unregisterAllCommands;
+    /**
+     * 获取配置值
+     * @param key 配置键
+     * @returns 配置值
+     */
+    protected getConfig<K extends keyof TConfig>(key: K): TConfig[K];
+    /**
+     * 获取完整配置（浅拷贝）
+     */
+    protected getConfigAll(): TConfig;
+    /**
+     * 检查配置中是否包含指定键
+     */
+    protected hasConfig(key: keyof TConfig): boolean;
+    /**
+     * 获取 hideWhenNoModel 配置值
+     * 默认 false（没有模型时也显示）
+     */
+    getHideWhenNoModel(): boolean;
+    /**
+     * 获取分组标识（从 config.group 读取）
+     * 工具栏插件可通过配置 `{ group: 'core' }` 指定分组
+     */
+    getGroup(): ToolbarPluginGroup | undefined;
+    /**
+     * 调试日志：仅当 debug=true 时输出 console.log
+     * @param args 日志参数
+     */
+    protected debugLog(...args: any[]): void;
+    /**
+     * 调试警告：仅当 debug=true 时输出 console.warn
+     * @param args 警告参数
+     */
+    protected debugWarn(...args: any[]): void;
+}

package/lib/types/plugins/PluginRegistry.d.ts

@@ -0,0 +1,67 @@
+import { Ref } from 'vue';
+import { EventBusImpl, ViewerContext } from '../core';
+import { IFormatPlugin, IViewerPlugin, PluginConfig, PluginsConfig } from './types';
+export declare class PluginRegistry {
+    private plugins;
+    private initialized;
+    private configs;
+    private registrationOrder;
+    private events;
+    /** useViewer 默认插件配置（最低优先级） */
+    private _defaultPluginConfig;
+    /** 响应式就绪标记：所有插件初始化完成后为 true，replaceAll/disposeAll 后为 false */
+    readonly pluginsReady: Ref<boolean>;
+    /** 格式插件索引缓存（懒构建，插件变更时失效） */
+    private _formatCache;
+    constructor(events?: EventBusImpl);
+    /**
+     * 清除所有已注册插件并重新注册
+     * 用于 VtkViewer props.plugins 覆盖 useViewer 默认插件的场景
+     * @param plugins 要注册的插件列表（扁平格式）
+     * @param configs 插件配置映射
+     */
+    replaceAll(plugins: IViewerPlugin[], configs?: Map<string, any>): void;
+    /**
+     * 设置 useViewer 默认插件配置（最低优先级）
+     * VtkViewer 可通过 getDefaultPluginConfig() 读取并合并
+     */
+    setDefaultPluginConfig(config: PluginsConfig): void;
+    /** 获取 useViewer 默认插件配置 */
+    getDefaultPluginConfig(): PluginsConfig;
+    register(plugin: IViewerPlugin, config?: PluginConfig): void;
+    unregister(id: string): void;
+    /**
+     * 初始化所有已注册的插件
+     * @param ctx 查看器上下文（必须提供，用于插件初始化）
+     */
+    initAll(ctx: ViewerContext): Promise<void>;
+    disposeAll(): void;
+    get<T extends IViewerPlugin>(id: string): T | undefined;
+    has(id: string): boolean;
+    getAll(): IViewerPlugin[];
+    /**
+     * 构建格式名称 → 格式插件的索引映射（O(1) 查找）
+     * 结果被缓存，插件变更时自动失效重建。
+     * 同一格式被多个插件支持时，priority 高的胜出。
+     */
+    getFormatPluginIndex(): Map<string, IFormatPlugin>;
+    /**
+     * 获取所有支持的扩展名列表（去重、排序，缓存结果）
+     */
+    getSupportedExtensions(): string[];
+    /** 失效格式缓存，下次访问时懒重建 */
+    private _invalidateFormatCache;
+    /** 懒构建格式缓存 */
+    private _ensureFormatCache;
+    isInitialized(id: string): boolean;
+    /**
+     * 解析插件初始化顺序
+     * 排序规则：依赖关系（拓扑排序） > initOrder > 注册顺序
+     */
+    private resolveInitOrder;
+    /**
+     * 带优先级的拓扑排序
+     * 保证依赖关系的同时，同层插件按 initOrder 和注册顺序排序
+     */
+    private topologicalSortWithOrder;
+}

package/lib/types/plugins/defaults.d.ts

@@ -0,0 +1,3 @@
+import { PluginsConfig } from './types';
+/** 内置默认插件配置 */
+export declare const DEFAULT_PLUGIN_CONFIG: PluginsConfig;

package/lib/types/plugins/format/DrcPlugin.d.ts

@@ -0,0 +1,30 @@
+import { IFormatPlugin, FormatParseResult, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+/**
+ * DRC格式插件
+ * 支持 Draco 压缩格式
+ */
+export declare class DrcPlugin extends PluginBase<PluginConfig> implements IFormatPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "format";
+        description: string;
+    };
+    readonly formats: string[];
+    readonly priority = 10;
+    dispose(): void;
+    canHandle(format: string): boolean;
+    parse(arrayBuffer: ArrayBuffer, _format: string, _options?: Record<string, any>): Promise<FormatParseResult>;
+    /**
+     * 确保 Draco 解码器已初始化
+     *
+     * 解码器加载顺序：
+     * 1. 检查 vtkDracoReader 是否已有解码器
+     * 2. 从 ctx.decoders.draco 读取路径（如有），通过 <script> 动态加载
+     * 3. 尝试动态 import('draco3d') 使用 npm 包
+     */
+    private ensureDracoDecoderReady;
+    private initDecoder;
+    private loadFromScript;
+}

package/lib/types/plugins/format/GlbPlugin.d.ts

@@ -0,0 +1,23 @@
+import { IFormatPlugin, FormatParseResult, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+/** GLB格式插件配置 */
+export interface GlbPluginConfig extends PluginConfig {
+}
+/**
+ * GLB格式插件
+ * 仅支持 GLB 二进制格式
+ */
+export declare class GlbPlugin extends PluginBase<GlbPluginConfig> implements IFormatPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "format";
+        description: string;
+    };
+    readonly formats: string[];
+    readonly priority = 10;
+    readonly defaultConfig: GlbPluginConfig;
+    dispose(): void;
+    canHandle(format: string): boolean;
+    parse(arrayBuffer: ArrayBuffer, format: string, _options?: Record<string, any>): Promise<FormatParseResult>;
+}

package/lib/types/plugins/format/ObjPlugin.d.ts

@@ -0,0 +1,23 @@
+import { IFormatPlugin, FormatParseResult, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+/** OBJ格式插件配置 */
+export interface ObjPluginConfig extends PluginConfig {
+}
+/**
+ * OBJ格式插件
+ * 支持 OBJ 格式
+ */
+export declare class ObjPlugin extends PluginBase<ObjPluginConfig> implements IFormatPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "format";
+        description: string;
+    };
+    readonly formats: string[];
+    readonly priority = 10;
+    readonly defaultConfig: ObjPluginConfig;
+    dispose(): void;
+    canHandle(format: string): boolean;
+    parse(arrayBuffer: ArrayBuffer, _format: string, _options?: Record<string, any>): Promise<FormatParseResult>;
+}

package/lib/types/plugins/format/PdbPlugin.d.ts

@@ -0,0 +1,33 @@
+import { IFormatPlugin, FormatParseResult, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+/** PDB格式插件配置 */
+export interface PdbPluginConfig extends PluginConfig {
+    /** 原子半径缩放因子 */
+    atomicRadiusScaleFactor?: number;
+    /** 化学键半径 */
+    bondRadius?: number;
+}
+/**
+ * PDB格式插件
+ * 支持 Protein Data Bank 分子格式
+ *
+ * 渲染管线：
+ * PDBReader → Molecule → MoleculeToRepresentation → SphereMapper + StickMapper
+ */
+export declare class PdbPlugin extends PluginBase<PdbPluginConfig> implements IFormatPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "format";
+        description: string;
+    };
+    readonly formats: string[];
+    readonly priority = 10;
+    readonly defaultConfig: PdbPluginConfig;
+    canHandle(format: string): boolean;
+    parse(arrayBuffer: ArrayBuffer, _format: string, _options?: Record<string, any>): Promise<FormatParseResult>;
+    /**
+     * 检查是否包含氢原子
+     */
+    private checkForHydrogen;
+}

package/lib/types/plugins/format/PlyPlugin.d.ts

@@ -0,0 +1,24 @@
+import { IFormatPlugin, FormatParseResult, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+/** PLY格式插件配置 */
+export interface PlyPluginConfig extends PluginConfig {
+}
+/**
+ * PLY格式插件
+ * 支持 PLY 格式（ASCII 和二进制）
+ * 支持顶点颜色和标量数据颜色映射
+ */
+export declare class PlyPlugin extends PluginBase<PlyPluginConfig> implements IFormatPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "format";
+        description: string;
+    };
+    readonly formats: string[];
+    readonly priority = 10;
+    readonly defaultConfig: PlyPluginConfig;
+    dispose(): void;
+    canHandle(format: string): boolean;
+    parse(arrayBuffer: ArrayBuffer, _format: string, _options?: Record<string, any>): Promise<FormatParseResult>;
+}

package/lib/types/plugins/format/StlPlugin.d.ts

@@ -0,0 +1,25 @@
+import { IFormatPlugin, FormatParseResult, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+/** STL格式插件配置 */
+export interface StlPluginConfig extends PluginConfig {
+    /** 是否合并重复点 */
+    mergePoints?: boolean;
+}
+/**
+ * STL格式插件
+ * 支持 STL/STLA/STLB 格式
+ */
+export declare class StlPlugin extends PluginBase<StlPluginConfig> implements IFormatPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "format";
+        description: string;
+    };
+    readonly formats: string[];
+    readonly priority = 10;
+    readonly defaultConfig: StlPluginConfig;
+    dispose(): void;
+    canHandle(format: string): boolean;
+    parse(arrayBuffer: ArrayBuffer, _format: string, _options?: Record<string, any>): Promise<FormatParseResult>;
+}

package/lib/types/plugins/format/VtiPlugin.d.ts

@@ -0,0 +1,60 @@
+import { IFormatPlugin, FormatParseResult, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+/** 体渲染传递函数控制点 */
+export interface VolumeTransferPoint {
+    /** 在数据范围中的位置 (0-1)，0=最小值，1=最大值 */
+    position: number;
+    /** 该位置的透明度 (0-1) */
+    opacity: number;
+}
+/** 体渲染颜色控制点 */
+export interface VolumeColorPoint extends VolumeTransferPoint {
+    /** RGB 颜色分量 (0-1) */
+    r: number;
+    g: number;
+    b: number;
+}
+/** 体渲染参数（可在插件注册时配置） */
+export interface VolumeRenderingConfig {
+    /** 采样距离缩放因子，越小越精细（性能开销越大），默认 0.7 */
+    sampleDistanceScale?: number;
+    /** 颜色控制点列表（按 position 排序），不传则用默认冷暖渐变 */
+    colorPoints?: VolumeColorPoint[];
+    /** 透明度控制点列表（按 position 排序），不传则用默认 S 型曲线 */
+    opacityPoints?: VolumeTransferPoint[];
+    /** 环境光强度 (0-1)，默认 0.2 */
+    ambient?: number;
+    /** 漫反射强度 (0-1)，默认 0.7 */
+    diffuse?: number;
+    /** 镜面反射强度 (0-1)，默认 0.3 */
+    specular?: number;
+    /** 镜面反射锐度，默认 8.0 */
+    specularPower?: number;
+    /** 是否启用光照着色，默认 true */
+    shade?: boolean;
+    /** 梯度透明度最大值的缩放因子（相对于数据范围），默认 0.05 */
+    gradientOpacityScale?: number;
+}
+/** VTI格式插件配置 */
+export interface VtiPluginConfig extends PluginConfig {
+    /** 体渲染参数 */
+    volumeRendering?: VolumeRenderingConfig;
+}
+/**
+ * VTI格式插件
+ * 支持 VTK ImageData 格式（体渲染）
+ */
+export declare class VtiPlugin extends PluginBase<VtiPluginConfig> implements IFormatPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "format";
+        description: string;
+    };
+    readonly formats: string[];
+    readonly priority = 10;
+    readonly defaultConfig: VtiPluginConfig;
+    dispose(): void;
+    canHandle(format: string): boolean;
+    parse(arrayBuffer: ArrayBuffer, _format: string, _options?: Record<string, any>): Promise<FormatParseResult>;
+}

package/lib/types/plugins/format/VtpPlugin.d.ts

@@ -0,0 +1,24 @@
+import { IFormatPlugin, FormatParseResult, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+/** VTP格式插件配置 */
+export interface VtpPluginConfig extends PluginConfig {
+}
+/**
+ * VTP格式插件
+ * 支持 VTK PolyData XML 格式
+ * 支持标量数据颜色映射（ColorBy 功能）
+ */
+export declare class VtpPlugin extends PluginBase<VtpPluginConfig> implements IFormatPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "format";
+        description: string;
+    };
+    readonly formats: string[];
+    readonly priority = 10;
+    readonly defaultConfig: VtpPluginConfig;
+    dispose(): void;
+    canHandle(format: string): boolean;
+    parse(arrayBuffer: ArrayBuffer, _format: string, _options?: Record<string, any>): Promise<FormatParseResult>;
+}

package/lib/types/plugins/format/VtuPlugin.d.ts

@@ -0,0 +1,25 @@
+import { IFormatPlugin, FormatParseResult, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+/** VTU格式插件配置 */
+export interface VtuPluginConfig extends PluginConfig {
+}
+/**
+ * VTU格式插件
+ * 支持 VTK UnstructuredGrid XML 格式
+ * 通过提取表面多边形转换为 PolyData 进行渲染
+ * 支持标量数据颜色映射（ColorBy 功能）
+ */
+export declare class VtuPlugin extends PluginBase<VtuPluginConfig> implements IFormatPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "format";
+        description: string;
+    };
+    readonly formats: string[];
+    readonly priority = 10;
+    readonly defaultConfig: VtuPluginConfig;
+    dispose(): void;
+    canHandle(format: string): boolean;
+    parse(arrayBuffer: ArrayBuffer, _format: string, _options?: Record<string, any>): Promise<FormatParseResult>;
+}

package/lib/types/plugins/format/ZipPlugin.d.ts

@@ -0,0 +1,38 @@
+import { IFormatPlugin, FormatParseResult, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+/** ZIP格式插件配置 */
+export interface ZipPluginConfig extends PluginConfig {
+}
+/**
+ * ZIP格式插件
+ * 聚合处理器，支持解压后自动识别内部格式
+ * 支持：通用 ZIP、VTK.js 原生 ZIP (.vtkjs)、OBJ+MTL+纹理 ZIP (.obz)
+ */
+export declare class ZipPlugin extends PluginBase<ZipPluginConfig> implements IFormatPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "format";
+        description: string;
+    };
+    readonly formats: string[];
+    readonly priority = 5;
+    readonly initOrder = 250;
+    readonly dependencies: string[];
+    readonly defaultConfig: ZipPluginConfig;
+    dispose(): void;
+    canHandle(format: string): boolean;
+    parse(arrayBuffer: ArrayBuffer, format: string, _options?: Record<string, any>): Promise<FormatParseResult>;
+    /**
+     * 处理 VTK.js 原生 ZIP 格式
+     */
+    private handleVtkJsZip;
+    /**
+     * 处理 OBJ+MTL+纹理的 ZIP 包
+     */
+    private handleObjBundleZip;
+    /**
+     * 处理通用 ZIP 格式
+     */
+    private handleGenericZip;
+}

package/lib/types/plugins/format/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 格式插件导出
+ */
+export * from './StlPlugin';
+export * from './ObjPlugin';
+export * from './PlyPlugin';
+export * from './VtpPlugin';
+export * from './VtuPlugin';
+export * from './VtiPlugin';
+export * from './GlbPlugin';
+export * from './DrcPlugin';
+export * from './PdbPlugin';
+export * from './ZipPlugin';

package/lib/types/plugins/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 插件模块导出
+ */
+export * from './types';
+export * from './pluginUtils';
+export * from './PluginBase';
+export * from './PluginRegistry';
+export * from './injectionKeys';
+export * from './defaults';
+export * from './format';
+export * from './toolbar';
+export * from './ui';
+export * from './service';

package/lib/types/plugins/injectionKeys.d.ts

@@ -0,0 +1,22 @@
+import { InjectionKey } from 'vue';
+import { CommandRegistry, EventBus, IStateManager, ViewerContext } from '../core';
+/**
+ * 状态管理器注入键
+ * UI插件通过 inject(stateManagerKey) 访问核心状态和插件状态
+ */
+export declare const stateManagerKey: InjectionKey<IStateManager>;
+/**
+ * 命令注册表注入键
+ * 插件通过 inject(commandExecutorKey) 执行跨插件命令
+ */
+export declare const commandExecutorKey: InjectionKey<CommandRegistry>;
+/**
+ * 事件总线注入键
+ * 插件通过 inject(eventBusKey) 进行事件通信
+ */
+export declare const eventBusKey: InjectionKey<EventBus>;
+/**
+ * 查看器上下文注入键
+ * 提供完整的 ViewerContext，用于需要访问多个子系统的场景
+ */
+export declare const viewerContextKey: InjectionKey<ViewerContext>;

package/lib/types/plugins/pluginUtils.d.ts

@@ -0,0 +1,61 @@
+import { PluginItem, PluginsConfig } from './types';
+/**
+ * 将插件配置归一化为 PluginsConfig
+ */
+export declare function normalizePluginsConfig(plugins: PluginsConfig | undefined): PluginsConfig;
+/**
+ * 合并多个插件配置（按优先级从低到高）
+ *
+ * 规则：同一分类后者 **完全覆盖** 前者
+ *
+ * @param configs 按优先级从低到高排列的配置列表
+ * @returns 合并后的 PluginsConfig
+ */
+export declare function mergePluginsConfig(...configs: (PluginsConfig | undefined)[]): PluginsConfig;
+/**
+ * 将 PluginsConfig 展平为 PluginItem[]
+ * 顺序：format → toolbar → ui → service
+ */
+export declare function flattenPluginsConfig(config: PluginsConfig): PluginItem[];
+/**
+ * 检查 PluginsConfig 是否为空（无任何插件配置）
+ */
+export declare function isPluginsConfigEmpty(config: PluginsConfig): boolean;
+/**
+ * PluginConfigMerger — 统一的插件配置合并器
+ *
+ * 将分散的 normalizePluginsConfig / mergePluginsConfig / flattenPluginsConfig /
+ * isPluginsConfigEmpty 封装为单一入口，提供简洁的合并 API。
+ *
+ * 调用方只需：
+ *   const merger = new PluginConfigMerger()
+ *   const plugins = merger.merge(baseConfig, overrideConfig)  // => PluginItem[]
+ *
+ * 内部自动处理归一化、空配置检查、合并、展平。
+ *
+ * @example
+ * ```typescript
+ * const merger = new PluginConfigMerger()
+ * const merged = merger.merge(config.plugins, pluginsOverride)
+ * for (const item of merged) {
+ *   registry.register(item)
+ * }
+ * ```
+ */
+export declare class PluginConfigMerger {
+    /**
+     * 合并基础配置和覆盖配置，返回最终的 PluginItem[]
+     *
+     * @param base 基础配置（低优先级）— PluginsConfig | undefined
+     * @param override 覆盖配置（高优先级）— PluginsConfig | undefined
+     * @returns 合并并展平后的 PluginItem[]
+     */
+    merge(base?: PluginsConfig, override?: PluginsConfig): PluginItem[];
+    /**
+     * 合并配置，返回合并后的 PluginsConfig（未展平）
+     * 当调用方需要继续处理分类结构时使用
+     *
+     * 任一配置为空时，直接返回另一方，避免 mergePluginsConfig 清空有效配置。
+     */
+    mergeConfigs(base?: PluginsConfig, override?: PluginsConfig): PluginsConfig;
+}