@fses/workbench-app 0.2.0 → 0.2.1

package/node_modules/@fses/workbench-card/src/renderers/chart/echarts-protocol/adapter.ts

@@ -0,0 +1,1349 @@
+/**
+ * @fileoverview ECharts 协议适配器 — 将协议配置和数据载荷转换为 ECharts option 的主入口类
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+import type { EChartsOption } from 'echarts';
+import { isProxy, toRaw } from 'vue';
+
+import type {
+  ProtocolConfigPayload,
+  ProtocolConverter,
+  ProtocolDataPayload,
+  ProtocolType,
+  TableDataPayload,
+} from './types';
+import { seriesConverter } from './converters/series.converter';
+import { tableConverter } from './converters/table.converter';
+import { tupleConverter } from './converters/tuple.converter';
+import { treeConverter } from './converters/tree.converter';
+import { networkConverter } from './converters/network.converter';
+import { geoConverter } from './converters/geo.converter';
+import { scene3DConverter } from './converters/scene3D.converter';
+import { timelineConverter } from './converters/timeline.converter';
+import { transitionConverter } from './converters/transition.converter';
+import { graphicConverter } from './converters/graphic.converter';
+import { layoutConverter } from './converters/layout.converter';
+import { compositeConverter } from './converters/composite.converter';
+import { configOnlyConverter } from './converters/configOnly.converter';
+import { deepMergeOption } from './merger';
+
+const OFFICIAL_ECHARTS_EXAMPLES_ROOT = 'https://echarts.apache.org/examples';
+const GL_REMOTE_TEXTURE_KEYS = new Set([
+  'baseTexture',
+  'heightTexture',
+  'texture',
+  'normalTexture',
+  'detailTexture',
+  'displacementTexture',
+  'roughnessTexture',
+  'metalnessTexture',
+  'emissionTexture',
+  'matcap',
+]);
+const GL_GLOBE_FALLBACK_COLOR = '#103b5d';
+const GL_ENVIRONMENT_FALLBACK_COLOR = '#000';
+
+/**
+ * 克隆 ECharts option 片段，兼容 Vue 响应式代理对象。
+ * @param value - 待克隆的 option 值
+ * @param seen - 循环引用缓存，避免递归复制时重复遍历
+ * @returns 已解除响应式代理的 option 值副本
+ */
+function cloneOptionValue<T>(value: T, seen = new WeakMap<object, unknown>()): T {
+  const rawValue = isProxy(value) ? toRaw(value) : value;
+
+  if (!rawValue || typeof rawValue !== 'object') return rawValue;
+
+  if (seen.has(rawValue)) return seen.get(rawValue) as T;
+
+  if (Array.isArray(rawValue)) {
+    const result: unknown[] = [];
+    seen.set(rawValue, result);
+    rawValue.forEach((item, index) => {
+      result[index] = cloneOptionValue(item, seen);
+    });
+    return result as T;
+  }
+
+  if (rawValue instanceof Date) {
+    return new Date(rawValue.getTime()) as T;
+  }
+
+  if (rawValue instanceof RegExp) {
+    return new RegExp(rawValue.source, rawValue.flags) as T;
+  }
+
+  const result: Record<string, unknown> = {};
+  seen.set(rawValue, result);
+  Object.entries(rawValue as Record<string, unknown>).forEach(([key, item]) => {
+    result[key] = cloneOptionValue(item, seen);
+  });
+  return result as T;
+}
+
+/**
+ * 判断给定值是否为普通对象。
+ * @param value - 待判断的值
+ * @returns 普通对象返回 true
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+/**
+ * 判断 option 字符串是否指向 ECharts 官方 GL 示例资源。
+ * @param value - option 字符串值
+ * @returns 指向官方远程 GL 资源时返回 true
+ */
+function isOfficialRemoteGlAssetUrl(value: string): boolean {
+  return value.startsWith(`${OFFICIAL_ECHARTS_EXAMPLES_ROOT}/data-gl/asset/`);
+}
+
+/**
+ * 读取 ECharts matrix 轴节点的叶子标签。
+ * @param value - matrix.x.data 或 matrix.y.data 中的节点数组
+ * @returns 叶子标签列表
+ */
+function matrixAxisLabels(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (typeof item === 'string' || typeof item === 'number') return [String(item)];
+    if (!isPlainObject(item)) return [];
+    if (Array.isArray(item.children)) return matrixAxisLabels(item.children);
+    const itemValue = item.value;
+    return typeof itemValue === 'string' || typeof itemValue === 'number' ? [String(itemValue)] : [];
+  });
+}
+
+/**
+ * 将 matrix 坐标的原始数据点转换为笛卡尔热力图索引坐标。
+ * @param value - series.data 候选值
+ * @param xLabels - x 轴叶子标签
+ * @param yLabels - y 轴叶子标签
+ * @returns 转换后的 series.data
+ */
+function downgradeMatrixSeriesData(value: unknown, xLabels: string[], yLabels: string[]): unknown {
+  if (!Array.isArray(value)) return value;
+  const xIndexByLabel = new Map(xLabels.map((label, index) => [label, index]));
+  const yIndexByLabel = new Map(yLabels.map((label, index) => [label, index]));
+
+  return value.map((item) => {
+    if (!Array.isArray(item) || item.length < 2) return item;
+    const xLabel = String(item[0] ?? '');
+    const yLabel = String(item[1] ?? '');
+    return [
+      xIndexByLabel.get(xLabel) ?? item[0],
+      yIndexByLabel.get(yLabel) ?? item[1],
+      ...item.slice(2),
+    ];
+  });
+}
+
+/**
+ * 判断 series 是否声明使用 matrix 坐标系。
+ * @param value - 候选 series 配置
+ * @returns matrix 坐标系返回 true
+ */
+function isMatrixSeries(value: unknown): value is Record<string, unknown> {
+  return isPlainObject(value) && value.coordinateSystem === 'matrix';
+}
+
+/**
+ * 从 transform 配置中读取 transform 类型。
+ * @param transform - ECharts dataset transform 配置
+ * @returns transform 类型；无法读取时返回空字符串
+ */
+function transformType(transform: unknown): string {
+  if (!isPlainObject(transform)) return '';
+  const type = transform.type;
+  return typeof type === 'string' ? type : '';
+}
+
+/**
+ * 判断 transform 是否依赖当前运行时未注册的外部插件。
+ * @param transform - ECharts dataset transform 配置
+ * @returns 依赖外部插件返回 true
+ */
+function isUnsupportedExternalTransform(transform: unknown): boolean {
+  const type = transformType(transform);
+  return type.startsWith('ecStat:') || type.startsWith('ecSimpleTransform:');
+}
+
+/**
+ * 判断 dataset 配置是否包含未注册的外部 transform。
+ * @param dataset - ECharts dataset 配置
+ * @returns 包含未注册 transform 返回 true
+ */
+function datasetHasUnsupportedTransform(dataset: unknown): boolean {
+  if (!isPlainObject(dataset)) return false;
+  const transform = dataset.transform;
+  if (Array.isArray(transform)) return transform.some(isUnsupportedExternalTransform);
+  return isUnsupportedExternalTransform(transform);
+}
+
+/**
+ * 清理 series 中对已移除 dataset transform 的引用。
+ * @param value - 候选 series 配置
+ * @returns 清理后的 series 配置
+ */
+function sanitizeSeriesDatasetReferences(value: unknown): unknown {
+  if (!Array.isArray(value)) return value;
+  return value.map((item) => {
+    if (!isPlainObject(item)) return item;
+    const {
+      datasetId: _datasetId,
+      datasetIndex: _datasetIndex,
+      encode: _encode,
+      ...rest
+    } = item;
+    return rest;
+  });
+}
+
+/**
+ * 清理没有 renderItem 的 custom series，避免 ECharts 抛出 render required。
+ * @param value - 候选 option 片段
+ * @returns 清理后的 option 片段
+ */
+function sanitizeCustomSeriesWithoutRenderer(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeCustomSeriesWithoutRenderer(item));
+  }
+  if (!isPlainObject(value)) return value;
+
+  const result: Record<string, unknown> = {};
+  Object.entries(value).forEach(([key, item]) => {
+    result[key] = sanitizeCustomSeriesWithoutRenderer(item);
+  });
+
+  if (result.type === 'custom' && !result.renderItem && !result.render) {
+    result.type = 'scatter';
+  }
+
+  return result;
+}
+
+/**
+ * 从 table 协议数据中读取第一组二维数值源数据。
+ * @param data - 协议数据载荷
+ * @returns 二维数值数组
+ */
+/**
+ * Removes empty inline data arrays from dataset-driven series patches.
+ * @param value - Candidate series option field.
+ * @returns Series option field without empty inline data arrays.
+ */
+function sanitizeEmptyDatasetDrivenSeriesData(value: unknown): unknown {
+  if (!Array.isArray(value)) return value;
+  return value.map((item) => {
+    if (!isPlainObject(item)) return item;
+    if (!Array.isArray(item.data) || item.data.length > 0) return item;
+    const { data: _data, ...rest } = item;
+    return rest;
+  });
+}
+
+function tableNumericSourceRows(data?: ProtocolDataPayload): number[][] {
+  if (!data || data.protocolType !== 'table') return [];
+  const tableData = data as TableDataPayload;
+  const source = tableData.datasets[0]?.source || [];
+  return source
+    .map((row) => Array.isArray(row) ? [Number(row[0]), Number(row[1])] : [Number.NaN, Number.NaN])
+    .filter(([x, y]) => Number.isFinite(x) && Number.isFinite(y));
+}
+
+/**
+ * 从 table 协议中读取第一组数据源，优先使用非空 rows。
+ * @param data - 协议数据载荷
+ * @returns 第一组 table 数据源
+ */
+function tableSource(data?: ProtocolDataPayload): unknown[] {
+  if (!data || data.protocolType !== 'table') return [];
+  const firstDataset = (data as TableDataPayload).datasets[0];
+  if (!firstDataset) return [];
+  return firstDataset.rows?.length ? firstDataset.rows : firstDataset.source;
+}
+
+/**
+ * 从 table 协议中读取维度声明。
+ * @param data - 协议数据载荷
+ * @returns 维度名数组
+ */
+function tableDimensions(data?: ProtocolDataPayload): string[] {
+  if (!data || data.protocolType !== 'table') return [];
+  return (data as TableDataPayload).datasets[0]?.dimensions || [];
+}
+
+/**
+ * 解线性方程组，用于多项式最小二乘拟合。
+ * @param matrix - 增广矩阵
+ * @returns 方程系数；无法求解时返回空数组
+ */
+function solveLinearSystem(matrix: number[][]): number[] {
+  const size = matrix.length;
+  const rows = matrix.map((row) => [...row]);
+
+  for (let column = 0; column < size; column += 1) {
+    let pivot = column;
+    for (let row = column + 1; row < size; row += 1) {
+      if (Math.abs(rows[row][column]) > Math.abs(rows[pivot][column])) pivot = row;
+    }
+    if (Math.abs(rows[pivot][column]) < 1e-12) return [];
+    [rows[column], rows[pivot]] = [rows[pivot], rows[column]];
+
+    const divisor = rows[column][column];
+    for (let item = column; item <= size; item += 1) rows[column][item] /= divisor;
+
+    for (let row = 0; row < size; row += 1) {
+      if (row === column) continue;
+      const factor = rows[row][column];
+      for (let item = column; item <= size; item += 1) {
+        rows[row][item] -= factor * rows[column][item];
+      }
+    }
+  }
+
+  return rows.map((row) => row[size]);
+}
+
+/**
+ * 计算一元线性拟合参数。
+ * @param points - 输入点集
+ * @returns 斜率和截距
+ */
+function fitLinear(points: number[][]): { slope: number; intercept: number } | null {
+  if (points.length < 2) return null;
+  const count = points.length;
+  const sumX = points.reduce((sum, [x]) => sum + x, 0);
+  const sumY = points.reduce((sum, [, y]) => sum + y, 0);
+  const sumXX = points.reduce((sum, [x]) => sum + x * x, 0);
+  const sumXY = points.reduce((sum, [x, y]) => sum + x * y, 0);
+  const denominator = count * sumXX - sumX * sumX;
+  if (Math.abs(denominator) < 1e-12) return null;
+  const slope = (count * sumXY - sumX * sumY) / denominator;
+  const intercept = (sumY - slope * sumX) / count;
+  return { slope, intercept };
+}
+
+/**
+ * 计算多项式拟合系数。
+ * @param points - 输入点集
+ * @param order - 多项式阶数
+ * @returns 从常数项开始的多项式系数
+ */
+function fitPolynomial(points: number[][], order: number): number[] {
+  const degree = Math.max(1, Math.min(6, Math.round(order || 2)));
+  if (points.length < degree + 1) return [];
+  const matrix = Array.from({ length: degree + 1 }, (_, row) => (
+    Array.from({ length: degree + 2 }, (_, column) => {
+      if (column === degree + 1) {
+        return points.reduce((sum, [x, y]) => sum + y * x ** row, 0);
+      }
+      return points.reduce((sum, [x]) => sum + x ** (row + column), 0);
+    })
+  ));
+  return solveLinearSystem(matrix);
+}
+
+/**
+ * 根据 ecStat regression 配置预计算回归线数据。
+ * @param data - 协议数据载荷
+ * @param config - regression transform config
+ * @returns ECharts dataset source；无法计算时返回空数组
+ */
+function materializeRegressionSource(data: ProtocolDataPayload | undefined, config: Record<string, unknown>): unknown[][] {
+  const points = tableNumericSourceRows(data).sort(([left], [right]) => left - right);
+  if (!points.length) return [];
+  const method = typeof config.method === 'string' ? config.method : 'linear';
+  const label = `y = ${method}`;
+
+  if (method === 'exponential') {
+    const positivePoints = points.filter(([, y]) => y > 0);
+    const fitted = fitLinear(positivePoints.map(([x, y]) => [x, Math.log(y)]));
+    if (!fitted) return points.map(([x, y]) => [x, y, label]);
+    return points.map(([x]) => [x, Math.exp(fitted.intercept + fitted.slope * x), label]);
+  }
+
+  if (method === 'logarithmic') {
+    const positivePoints = points.filter(([x]) => x > 0);
+    const fitted = fitLinear(positivePoints.map(([x, y]) => [Math.log(x), y]));
+    if (!fitted) return points.map(([x, y]) => [x, y, label]);
+    return points.map(([x]) => [x, fitted.slope * Math.log(x) + fitted.intercept, label]);
+  }
+
+  if (method === 'polynomial') {
+    const coefficients = fitPolynomial(points, Number(config.order) || 2);
+    if (!coefficients.length) return points.map(([x, y]) => [x, y, label]);
+    return points.map(([x]) => [
+      x,
+      coefficients.reduce((sum, coefficient, power) => sum + coefficient * x ** power, 0),
+      label,
+    ]);
+  }
+
+  const fitted = fitLinear(points);
+  if (!fitted) return points.map(([x, y]) => [x, y, label]);
+  return points.map(([x]) => [x, fitted.slope * x + fitted.intercept, label]);
+}
+
+/**
+ * 从 dataset transform 中提取 ecStat regression 配置。
+ * @param dataset - ECharts dataset 配置
+ * @returns regression 配置；不存在时返回 null
+ */
+function regressionTransformConfig(dataset: unknown): Record<string, unknown> | null {
+  if (!isPlainObject(dataset)) return null;
+  const transform = dataset.transform;
+  if (!isPlainObject(transform) || transform.type !== 'ecStat:regression') return null;
+  return isPlainObject(transform.config) ? transform.config : {};
+}
+
+/**
+ * 从 dataset transform 中提取 ecStat histogram 配置。
+ * @param dataset - ECharts dataset 配置
+ * @returns histogram 配置；不存在时返回 null
+ */
+function histogramTransformConfig(dataset: unknown): Record<string, unknown> | null {
+  if (!isPlainObject(dataset)) return null;
+  const transform = dataset.transform;
+  if (!isPlainObject(transform) || transform.type !== 'ecStat:histogram') return null;
+  return isPlainObject(transform.config) ? transform.config : {};
+}
+
+/**
+ * 读取 histogram 要统计的列下标。
+ * @param config - ecStat histogram 配置
+ * @returns 列下标
+ */
+function histogramDimensionIndex(config: Record<string, unknown>): number {
+  const dimensions = config.dimensions;
+  if (Array.isArray(dimensions) && typeof dimensions[0] === 'number') return dimensions[0];
+  if (typeof dimensions === 'number') return dimensions;
+  return 0;
+}
+
+/**
+ * 按给定分位位置读取排序数组中的值。
+ * @param values - 已排序数值
+ * @param ratio - 分位比例
+ * @returns 分位值
+ */
+function quantile(values: number[], ratio: number): number {
+  if (!values.length) return Number.NaN;
+  const index = (values.length - 1) * ratio;
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  if (lower === upper) return values[lower];
+  return values[lower] + (values[upper] - values[lower]) * (index - lower);
+}
+
+/**
+ * 根据 ecStat histogram 配置预计算直方图数据。
+ * @param data - 协议数据载荷
+ * @param config - histogram transform config
+ * @returns ECharts dataset source
+ */
+function materializeHistogramSource(data: ProtocolDataPayload | undefined, config: Record<string, unknown>): unknown[][] {
+  const dimensionIndex = histogramDimensionIndex(config);
+  const values = tableSource(data)
+    .map((row) => (Array.isArray(row) ? Number(row[dimensionIndex]) : Number.NaN))
+    .filter((value) => Number.isFinite(value))
+    .sort((left, right) => left - right);
+  if (!values.length) return [];
+
+  const min = values[0];
+  const max = values[values.length - 1];
+  const iqr = quantile(values, 0.75) - quantile(values, 0.25);
+  const autoBinWidth = iqr > 0 ? (2 * iqr) / Math.cbrt(values.length) : (max - min) / Math.sqrt(values.length);
+  const binWidth = Number.isFinite(autoBinWidth) && autoBinWidth > 0 ? autoBinWidth : 1;
+  const binCount = Math.max(1, Math.ceil((max - min || 1) / binWidth));
+  const normalizedBinWidth = (max - min || 1) / binCount;
+  const counts = Array.from({ length: binCount }, () => 0);
+
+  values.forEach((value) => {
+    const rawIndex = Math.floor((value - min) / normalizedBinWidth);
+    const index = Math.min(binCount - 1, Math.max(0, rawIndex));
+    counts[index] += 1;
+  });
+
+  return counts.map((count, index) => {
+    const start = min + index * normalizedBinWidth;
+    const end = index === binCount - 1 ? max : start + normalizedBinWidth;
+    const center = (start + end) / 2;
+    return [center, count, start, end, `${start.toFixed(2)} - ${end.toFixed(2)}`];
+  });
+}
+
+/**
+ * 将主 table 数据注入 dataset 数组首项，保留内置 sort/filter transform 的输入源。
+ * @param datasets - optionPatch 中的 dataset 数组
+ * @param data - 协议数据载荷
+ * @returns 注入后的 dataset 数组
+ */
+function hydratePrimaryTableDataset(datasets: unknown[], data?: ProtocolDataPayload): unknown[] {
+  const source = tableSource(data);
+  const dimensions = tableDimensions(data);
+  if (!source.length && !dimensions.length) return datasets;
+
+  return datasets.map((dataset, index) => {
+    if (index !== 0 || !isPlainObject(dataset)) return dataset;
+    return {
+      ...dataset,
+      ...(source.length ? { source } : {}),
+      ...(dimensions.length ? { dimensions } : {}),
+    };
+  });
+}
+
+/**
+ * 替换 ecStat histogram transform，避免运行时缺少 ecStat 插件。
+ * @param datasets - optionPatch 中的 dataset 数组
+ * @param data - 协议数据载荷
+ * @returns 替换后的 dataset 数组；没有 histogram 时返回 null
+ */
+function materializeHistogramDatasets(datasets: unknown[], data?: ProtocolDataPayload): unknown[] | null {
+  if (!datasets.some((dataset) => histogramTransformConfig(dataset))) return null;
+  return datasets.map((dataset, index) => {
+    const config = histogramTransformConfig(dataset);
+    if (!config) return index === 0 && isPlainObject(dataset) ? dataset : dataset;
+    if (!isPlainObject(dataset)) return dataset;
+    const { transform: _transform, ...rest } = dataset;
+    return {
+      ...rest,
+      source: materializeHistogramSource(data, config),
+    };
+  });
+}
+
+/**
+ * 判断 pattern 配置是否携带浏览器 createPattern 无法接受的图片对象。
+ * @param value - 候选 pattern 配置
+ * @returns 非法 pattern 返回 true
+ */
+function isInvalidCanvasPattern(value: unknown): boolean {
+  if (!isPlainObject(value) || value.type !== 'pattern') return false;
+  const image = value.image;
+  return Boolean(image && typeof image === 'object');
+}
+
+/**
+ * 清理从官方示例中抽取出的不可序列化 Canvas pattern。
+ * @param value - 候选 option 值
+ * @returns 清理后的 option 值
+ */
+function sanitizeInvalidCanvasPatterns(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeInvalidCanvasPatterns(item));
+  }
+  if (!isPlainObject(value)) return value;
+
+  const result: Record<string, unknown> = {};
+  Object.entries(value).forEach(([key, item]) => {
+    if (isInvalidCanvasPattern(item)) return;
+    result[key] = sanitizeInvalidCanvasPatterns(item);
+  });
+  return result;
+}
+
+/**
+ * 判断 option 片段是否为 ECharts 渐变色对象。
+ * @param value - 候选 option 值
+ * @returns 渐变色对象返回 true
+ */
+function isGradientColor(value: Record<string, unknown>): boolean {
+  return (value.type === 'linear' || value.type === 'radial') && Array.isArray(value.colorStops);
+}
+
+/**
+ * 将渐变 stop 偏移量限制为 CanvasGradient 可接受的有限数。
+ * @param stop - 候选 color stop
+ * @param index - stop 下标
+ * @param count - stop 总数
+ * @returns 归一化后的 color stop
+ */
+function normalizeGradientColorStop(stop: unknown, index: number, count: number): unknown {
+  if (!isPlainObject(stop)) return stop;
+  const fallbackOffset = count <= 1 ? 0 : index / (count - 1);
+  const rawOffset = Number(stop.offset);
+  const offset = Number.isFinite(rawOffset)
+    ? Math.min(1, Math.max(0, rawOffset))
+    : fallbackOffset;
+  return { ...stop, offset };
+}
+
+/**
+ * 清理渐变色 stop 中的 NaN/Infinity/缺失 offset，避免 CanvasGradient.addColorStop 抛错。
+ * @param value - 候选 option 值
+ * @returns 清理后的 option 值
+ */
+function sanitizeGradientColorStops(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeGradientColorStops(item));
+  }
+  if (!isPlainObject(value)) return value;
+
+  const result: Record<string, unknown> = {};
+  Object.entries(value).forEach(([key, item]) => {
+    result[key] = sanitizeGradientColorStops(item);
+  });
+
+  if (isGradientColor(result)) {
+    const colorStops = result.colorStops as unknown[];
+    result.colorStops = colorStops.map((stop, index) => normalizeGradientColorStop(stop, index, colorStops.length));
+  }
+
+  return result;
+}
+
+/**
+ * 判断 option 片段是否包含无法离线渲染的 bmap 坐标系。
+ * @param value - 候选 option 值
+ * @returns 命中 bmap 坐标系返回 true
+ */
+function optionUsesBmapCoordinateSystem(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(optionUsesBmapCoordinateSystem);
+  if (!isPlainObject(value)) return false;
+  return Object.entries(value).some(([key, item]) => (
+    (key === 'coordinateSystem' && item === 'bmap')
+    || key === 'bmap'
+    || optionUsesBmapCoordinateSystem(item)
+  ));
+}
+
+/**
+ * 判断 option 片段是否使用非笛卡尔二维坐标系。
+ * @param value - 候选 option 值
+ * @returns 使用 calendar 或 matrix 坐标系时返回 true
+ */
+function optionUsesNonCartesian2DCoordinateSystem(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(optionUsesNonCartesian2DCoordinateSystem);
+  if (!isPlainObject(value)) return false;
+  return Object.entries(value).some(([key, item]) => (
+    (key === 'coordinateSystem' && (item === 'calendar' || item === 'matrix'))
+    || key === 'calendar'
+    || key === 'matrix'
+    || optionUsesNonCartesian2DCoordinateSystem(item)
+  ));
+}
+
+/**
+ * 清理 calendar/matrix 官方示例中从 series 协议骨架继承来的笛卡尔轴。
+ * @param value - 候选 option 值
+ * @returns 去除不相关笛卡尔轴后的 option 值
+ */
+function sanitizeNonCartesian2DCoordinateAxes(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((item) => sanitizeNonCartesian2DCoordinateAxes(item));
+  if (!isPlainObject(value)) return value;
+
+  const shouldRemoveCartesianAxes = optionUsesNonCartesian2DCoordinateSystem(value);
+  const result: Record<string, unknown> = {};
+  Object.entries(value).forEach(([key, item]) => {
+    if (shouldRemoveCartesianAxes && (key === 'xAxis' || key === 'yAxis' || key === 'grid')) return;
+    result[key] = sanitizeNonCartesian2DCoordinateAxes(item);
+  });
+  return result;
+}
+
+/**
+ * 判断 series 是否不依赖笛卡尔坐标系。
+ * @param series - ECharts series 配置片段
+ * @returns 非坐标轴类 series 返回 true
+ */
+function isCoordinateFreeSeries(series: Record<string, unknown>): boolean {
+  return series.type === 'funnel'
+    || series.type === 'pie'
+    || series.type === 'radar'
+    || series.type === 'gauge';
+}
+
+/**
+ * 移除非坐标轴类 series 上继承到的笛卡尔坐标字段。
+ * @param series - ECharts series 配置片段
+ * @returns 清理后的 series 配置
+ */
+function sanitizeCoordinateFreeSeries(series: Record<string, unknown>): Record<string, unknown> {
+  if (!isCoordinateFreeSeries(series)) return series;
+  const {
+    coordinateSystem: _coordinateSystem,
+    xAxisIndex: _xAxisIndex,
+    yAxisIndex: _yAxisIndex,
+    gridIndex: _gridIndex,
+    ...rest
+  } = series;
+  return rest;
+}
+
+/**
+ * 运行时数据把多漏斗模板收敛为单漏斗时，将漏斗重新放回画布中心。
+ * @param series - 单个漏斗 series 配置
+ * @returns 居中后的漏斗 series 配置
+ */
+function normalizeSingleRuntimeFunnelLayout(series: Record<string, unknown>): Record<string, unknown> {
+  if (series.type !== 'funnel') return series;
+  const { right: _right, ...rest } = series;
+  return {
+    ...rest,
+    left: 'center',
+    width: '70%',
+  };
+}
+
+/**
+ * 清理运行时最终 option 中非坐标轴图表从模板继承到的坐标配置。
+ * @param option - 已合并真实数据的 ECharts option
+ * @returns 可安全交给 ECharts 渲染的 option
+ */
+function sanitizeRuntimeCoordinateFreeSeriesOption(option: EChartsOption): EChartsOption {
+  if (!isPlainObject(option)) return option;
+
+  const mutable = option as Record<string, unknown>;
+  const rawSeries = mutable.series;
+  const seriesItems = Array.isArray(rawSeries)
+    ? rawSeries.filter(isPlainObject)
+    : isPlainObject(rawSeries)
+      ? [rawSeries]
+      : [];
+  if (seriesItems.length === 0) return option;
+
+  let nextSeries = seriesItems.map(sanitizeCoordinateFreeSeries);
+  const hasOnlyCoordinateFreeSeries = nextSeries.every(isCoordinateFreeSeries);
+
+  if (nextSeries.length === 1 && nextSeries[0].type === 'funnel') {
+    nextSeries = [normalizeSingleRuntimeFunnelLayout(nextSeries[0])];
+  }
+
+  const nextOption: Record<string, unknown> = {
+    ...mutable,
+    series: Array.isArray(rawSeries) ? nextSeries : nextSeries[0],
+  };
+
+  if (hasOnlyCoordinateFreeSeries) {
+    delete nextOption.xAxis;
+    delete nextOption.yAxis;
+    delete nextOption.grid;
+  }
+
+  return nextOption as EChartsOption;
+}
+
+/**
+ * 将 ECharts 6 matrix 坐标模板降级为 ECharts 5 可渲染的类目坐标图。
+ * @param option - 待清洗的最终 option
+ * @returns 兼容 ECharts 5 的 option
+ */
+function downgradeMatrixCoordinateOption(option: EChartsOption): EChartsOption {
+  const mutable = option as Record<string, unknown>;
+  if (!isPlainObject(mutable.matrix)) return option;
+  const seriesItems = Array.isArray(mutable.series) ? mutable.series : mutable.series ? [mutable.series] : [];
+  if (!seriesItems.some(isMatrixSeries)) return option;
+
+  const matrix = mutable.matrix;
+  const xAxisConfig = isPlainObject(matrix.x) ? matrix.x : {};
+  const yAxisConfig = isPlainObject(matrix.y) ? matrix.y : {};
+  const xLabels = matrixAxisLabels(xAxisConfig.data);
+  const yLabels = matrixAxisLabels(yAxisConfig.data);
+  if (!xLabels.length || !yLabels.length) return option;
+
+  const { matrix: _matrix, ...rest } = mutable;
+  return {
+    ...rest,
+    grid: isPlainObject(mutable.grid)
+      ? { containLabel: true, ...mutable.grid }
+      : { left: 72, right: 32, top: 72, bottom: 48, containLabel: true },
+    xAxis: { type: 'category', ...(xAxisConfig.show === false ? { show: false } : {}), data: xLabels },
+    yAxis: { type: 'category', ...(yAxisConfig.show === false ? { show: false } : {}), data: yLabels },
+    series: seriesItems.map((item) => {
+      if (!isMatrixSeries(item)) return item;
+      const { coordinateSystem: _coordinateSystem, ...seriesRest } = item;
+      return {
+        ...seriesRest,
+        data: downgradeMatrixSeriesData(seriesRest.data, xLabels, yLabels),
+      };
+    }),
+  } as EChartsOption;
+}
+
+/**
+ * 将官方示例中的外部地图名和 bmap 坐标系降级为内置工作台地图。
+ * @param value - 候选 option 值
+ * @returns 不依赖外部地图资源或 bmap 插件的 option 值
+ */
+function sanitizeExternalGeoDependencies(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((item) => sanitizeExternalGeoDependencies(item));
+  if (!isPlainObject(value)) return value;
+
+  const result: Record<string, unknown> = {};
+  Object.entries(value).forEach(([key, item]) => {
+    if (key === 'bmap') return;
+    if ((key === 'map' || key === 'mapType') && typeof item === 'string') {
+      result[key] = 'workbench-regions';
+      return;
+    }
+    if (key === 'coordinateSystem' && item === 'bmap') {
+      result[key] = 'geo';
+      return;
+    }
+    result[key] = sanitizeExternalGeoDependencies(item);
+  });
+
+  if (
+    result.type === 'map'
+    && typeof result.map !== 'string'
+    && typeof result.mapType !== 'string'
+  ) {
+    result.map = 'workbench-regions';
+  }
+
+  return result;
+}
+
+/**
+ * 移除卡片中心会被 CORS 拦截的 ECharts 官方远程 GL 纹理。
+ * @param value - 待处理的 option 值
+ * @param parentKey - 当前值所属的父级 key
+ * @returns 不依赖远程 GL 纹理的 option 值
+ */
+function sanitizeOfficialRemoteGlAssets(value: unknown, parentKey = ''): unknown {
+  if (Array.isArray(value)) return value.map((item) => sanitizeOfficialRemoteGlAssets(item, parentKey));
+  if (!isPlainObject(value)) return value;
+
+  const result: Record<string, unknown> = {};
+  let removedGlobeTexture = false;
+
+  Object.entries(value).forEach(([key, item]) => {
+    if (typeof item === 'string' && isOfficialRemoteGlAssetUrl(item)) {
+      if (key === 'environment') {
+        result[key] = GL_ENVIRONMENT_FALLBACK_COLOR;
+        return;
+      }
+      if (key === 'baseTexture' || key === 'heightTexture') {
+        removedGlobeTexture = true;
+        return;
+      }
+      if (GL_REMOTE_TEXTURE_KEYS.has(key)) return;
+    }
+
+    result[key] = sanitizeOfficialRemoteGlAssets(item, key);
+  });
+
+  if (parentKey === 'globe' && removedGlobeTexture && !result.baseColor) {
+    result.baseColor = GL_GLOBE_FALLBACK_COLOR;
+  }
+
+  return result;
+}
+
+/**
+ * 移除模板补丁中的静态图例项，避免运行时数据合并后又被示例 legend 覆盖。
+ * @param legend - optionPatch.legend 候选值
+ * @returns 不含 data 字段的 legend 配置
+ */
+function stripRuntimeLegendData(legend: unknown): unknown {
+  if (Array.isArray(legend)) {
+    return legend.map((item) => stripRuntimeLegendData(item));
+  }
+  if (!isPlainObject(legend)) return legend;
+
+  const { data: _data, ...rest } = legend;
+  return rest;
+}
+
+/**
+ * 判断协议数据是否携带笛卡尔类目图的真实运行时数据。
+ * @param data - 协议数据载荷。
+ * @returns 有真实类目或序列数据时返回 true。
+ */
+function hasRuntimeCartesianSeriesData(data: ProtocolDataPayload | undefined): boolean {
+  if (!data || data.protocolType !== 'series') return false;
+  const categories = isPlainObject(data.categories) && Array.isArray(data.categories.xAxis)
+    ? data.categories.xAxis
+    : Array.isArray(data.categories)
+      ? data.categories
+      : [];
+  const series = Array.isArray(data.series) ? data.series : [];
+  return categories.length > 0 || series.some((item) => (
+    isPlainObject(item) && Array.isArray(item.data) && item.data.length > 0
+  ));
+}
+
+/**
+ * 将模板 dataZoom 初始窗口归一为全量范围，避免真实数据默认只显示前几条。
+ * @param item - 单个 dataZoom 配置项。
+ * @returns 不裁剪初始数据窗口的 dataZoom 配置。
+ */
+function normalizeRuntimeDataZoomItem(item: unknown): unknown {
+  if (!isPlainObject(item)) return item;
+  const {
+    startValue: _startValue,
+    endValue: _endValue,
+    ...rest
+  } = item;
+  return {
+    ...rest,
+    start: 0,
+    end: 100,
+  };
+}
+
+/**
+ * 归一化运行时 dataZoom 配置，保留缩放能力但默认展示完整真实数据。
+ * @param dataZoom - optionPatch.dataZoom 候选值。
+ * @returns 全量初始窗口的 dataZoom 配置。
+ */
+function normalizeRuntimeDataZoomWindow(dataZoom: unknown): unknown {
+  if (Array.isArray(dataZoom)) return dataZoom.map(normalizeRuntimeDataZoomItem);
+  return normalizeRuntimeDataZoomItem(dataZoom);
+}
+
+/**
+ * 对最终 ECharts option 应用 dataZoom 全量窗口归一化，覆盖模板、AI 注入、
+ * 用户改卡等所有来源的 dataZoom 配置，确保运行时全部数据默认可见。
+ * @param option - 已合并的最终 ECharts option
+ * @param data - 协议数据载荷，用于判定是否携带真实运行时数据
+ * @returns dataZoom 已被归一化的 option 副本
+ */
+function normalizeFinalDataZoom(
+  option: EChartsOption,
+  data?: ProtocolDataPayload,
+): EChartsOption {
+  if (!isPlainObject(option)) return option;
+  const mutable = option as Record<string, unknown>;
+  const dataZoom = mutable.dataZoom;
+  if (dataZoom === undefined) return option;
+  // 仅当携带真实运行时数据时才覆盖 dataZoom，避免误伤纯静态展示模板。
+  if (!hasRuntimeCartesianSeriesData(data)) return option;
+  return {
+    ...mutable,
+    dataZoom: normalizeRuntimeDataZoomWindow(dataZoom),
+  } as EChartsOption;
+}
+
+/**
+ * 清洗运行时不支持的官方 optionPatch 片段。
+ * @param patch - 原始 optionPatch
+ * @param data - 可选协议数据，用于预计算部分 transform
+ * @returns 可安全传给 ECharts 的 optionPatch
+ */
+function sanitizeRuntimeOptionPatch(
+  patch: Record<string, unknown>,
+  data?: ProtocolDataPayload,
+): Record<string, unknown> {
+  const usesBmap = optionUsesBmapCoordinateSystem(patch);
+  const sanitized = sanitizeExternalGeoDependencies(
+    sanitizeOfficialRemoteGlAssets(
+      sanitizeInvalidCanvasPatterns(
+        sanitizeGradientColorStops(
+          sanitizeCustomSeriesWithoutRenderer(cloneOptionValue(patch)),
+        ),
+      ),
+    ),
+  ) as Record<string, unknown>;
+
+  if (usesBmap && !sanitized.geo) {
+    sanitized.geo = {
+      map: 'workbench-regions',
+      roam: true,
+    };
+  }
+
+  if (data && sanitized.legend !== undefined) {
+    sanitized.legend = stripRuntimeLegendData(sanitized.legend);
+  }
+
+  if (sanitized.dataZoom !== undefined && hasRuntimeCartesianSeriesData(data)) {
+    sanitized.dataZoom = normalizeRuntimeDataZoomWindow(sanitized.dataZoom);
+  }
+
+  if (isRuntimeSeriesData(data)) {
+    sanitized.title = stripRuntimeTitleText(sanitized.title);
+    sanitized.tooltip = stripRuntimeTooltipFormatter(sanitized.tooltip);
+    const seriesPatch = stripRuntimeSeriesPatchSemantics(sanitized.series, data);
+    if (seriesPatch === undefined) {
+      delete sanitized.series;
+    } else {
+      sanitized.series = seriesPatch;
+    }
+  }
+
+  if (sanitized.dataset && Array.isArray(sanitized.series)) {
+    sanitized.series = sanitizeEmptyDatasetDrivenSeriesData(sanitized.series);
+  }
+
+  const datasetPatch = sanitized.dataset;
+  if (!Array.isArray(datasetPatch)) return sanitized;
+
+  const hydratedDatasets = hydratePrimaryTableDataset(datasetPatch, data);
+  const histogramDatasets = materializeHistogramDatasets(hydratedDatasets, data);
+  sanitized.dataset = histogramDatasets || hydratedDatasets;
+
+  const currentDatasets = sanitized.dataset as unknown[];
+  const regressionIndex = currentDatasets.findIndex((dataset) => regressionTransformConfig(dataset));
+  if (regressionIndex > 0) {
+    const regressionConfig = regressionTransformConfig(currentDatasets[regressionIndex]) || {};
+    sanitized.dataset = [
+      { source: tableNumericSourceRows(data) },
+      { source: materializeRegressionSource(data, regressionConfig) },
+    ];
+    return sanitized;
+  }
+
+  if (currentDatasets.some(datasetHasUnsupportedTransform)) {
+    const { dataset: _dataset, visualMap: _visualMap, ...rest } = sanitized;
+    return {
+      ...rest,
+      ...(Array.isArray(rest.series) ? { series: sanitizeSeriesDatasetReferences(rest.series) } : {}),
+    };
+  }
+
+  return sanitized;
+}
+
+/**
+ * 判断协议数据是否为可由运行时真实 series 接管语义的序列数据。
+ * @param data - 协议数据负载。
+ * @returns series 协议数据返回 true。
+ */
+function isRuntimeSeriesData(data: ProtocolDataPayload | undefined): data is ProtocolDataPayload {
+  return Boolean(data && data.protocolType === 'series');
+}
+
+/**
+ * 读取运行时 series 协议中的真实系列数量。
+ * @param data - series 协议数据。
+ * @returns 真实 series 数量。
+ */
+function runtimeSeriesCount(data: ProtocolDataPayload): number {
+  const record = data as unknown as Record<string, unknown>;
+  if (Array.isArray(record.series)) return record.series.filter(isPlainObject).length;
+  const dataset = isPlainObject(record.dataset) ? record.dataset : undefined;
+  return Array.isArray(dataset?.series) ? dataset.series.filter(isPlainObject).length : 0;
+}
+
+/**
+ * 去掉官方模板标题中的演示文本，只保留定位和样式。
+ * @param value - ECharts title 配置。
+ * @returns 不含 text/subtext 等展示文案的 title 配置。
+ */
+function stripRuntimeTitleText(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stripRuntimeTitleText);
+  if (!isPlainObject(value)) return value;
+  const {
+    text: _text,
+    subtext: _subtext,
+    link: _link,
+    sublink: _sublink,
+    target: _target,
+    subtarget: _subtarget,
+    ...rest
+  } = value;
+  return rest;
+}
+
+/**
+ * 去掉官方模板 tooltip formatter，避免 formatter 中的模板占位语义压过真实数据。
+ * @param value - ECharts tooltip 配置。
+ * @returns 不含 formatter 的 tooltip 配置。
+ */
+function stripRuntimeTooltipFormatter(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stripRuntimeTooltipFormatter);
+  if (!isPlainObject(value)) return value;
+  const { formatter: _formatter, ...rest } = value;
+  return rest;
+}
+
+/**
+ * 将官方模板 series patch 限定为视觉样式，真实 id/name/data 由协议数据提供。
+ * @param value - ECharts optionPatch.series。
+ * @param data - 运行时 series 协议数据。
+ * @returns 只包含样式字段且不新增 demo series 的 series patch。
+ */
+function stripRuntimeSeriesPatchSemantics(value: unknown, data: ProtocolDataPayload): unknown {
+  const count = runtimeSeriesCount(data);
+  if (count <= 0) return undefined;
+
+  if (!Array.isArray(value)) {
+    const firstSeriesPatch = stripOneRuntimeSeriesPatchSemantics(value);
+    return [firstSeriesPatch ?? {}];
+  }
+
+  const waterfallSeriesPatch = count === 1 ? legacyWaterfallRuntimeSeriesPatch(value) : undefined;
+  if (waterfallSeriesPatch) return waterfallSeriesPatch;
+
+  return Array.from({ length: count }, (_, index) => (
+    stripOneRuntimeSeriesPatchSemantics(value[index]) ?? {}
+  ));
+}
+
+/**
+ * 判断颜色值是否为透明色。
+ * @param value - 待判断的颜色值。
+ * @returns 透明色返回 true。
+ */
+function isTransparentColor(value: unknown): boolean {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase().replace(/\s+/gu, '') : '';
+  return normalized === 'transparent'
+    || normalized === 'rgba(0,0,0,0)'
+    || normalized === 'rgba(255,255,255,0)';
+}
+
+/**
+ * 判断 series patch 是否为瀑布图透明占位柱。
+ * @param value - 候选 series patch。
+ * @returns 透明占位柱返回 true。
+ */
+function isWaterfallHelperSeriesPatch(value: unknown): value is Record<string, unknown> {
+  if (!isPlainObject(value) || value.type !== 'bar' || typeof value.stack !== 'string') return false;
+  const itemStyle = isPlainObject(value.itemStyle) ? value.itemStyle : {};
+  const emphasis = isPlainObject(value.emphasis) ? value.emphasis : {};
+  const emphasisItemStyle = isPlainObject(emphasis.itemStyle) ? emphasis.itemStyle : {};
+  return isTransparentColor(itemStyle.color)
+    || isTransparentColor(itemStyle.borderColor)
+    || isTransparentColor(emphasisItemStyle.color)
+    || isTransparentColor(emphasisItemStyle.borderColor);
+}
+
+/**
+ * 从旧瀑布图模板 patch 中保留透明 helper 和真实可见柱两个结构 series。
+ * @param value - optionPatch.series 候选值。
+ * @returns 瀑布图两条结构 series patch；非瀑布图返回 undefined。
+ */
+function legacyWaterfallRuntimeSeriesPatch(value: unknown[]): Array<Record<string, unknown>> | undefined {
+  const helperIndex = value.findIndex(isWaterfallHelperSeriesPatch);
+  if (helperIndex < 0) return undefined;
+  const helper = value[helperIndex] as Record<string, unknown>;
+  const helperStack = typeof helper.stack === 'string' ? helper.stack : undefined;
+  const visibleIndex = value.findIndex((item, index) => (
+    index !== helperIndex
+    && isPlainObject(item)
+    && item.type === 'bar'
+    && typeof item.stack === 'string'
+    && item.stack === helperStack
+    && !isWaterfallHelperSeriesPatch(item)
+  ));
+  if (visibleIndex < 0) return undefined;
+  return [
+    stripOneRuntimeSeriesPatchSemantics(value[helperIndex]) ?? {},
+    stripOneRuntimeSeriesPatchSemantics(value[visibleIndex]) ?? {},
+  ];
+}
+
+/**
+ * 去掉单个模板 series 中会覆盖真实数据语义的字段。
+ * @param value - 模板 series patch。
+ * @returns 仅保留视觉和结构配置的 series patch。
+ */
+function stripOneRuntimeSeriesPatchSemantics(value: unknown): Record<string, unknown> | undefined {
+  if (!isPlainObject(value)) return undefined;
+  const {
+    id: _id,
+    name: _name,
+    data: _data,
+    ...rest
+  } = value;
+  return rest;
+}
+
+/**
+ * 在真实 series 数据完成合并后再次清理最终 option，防止基础配置标题等模板语义残留。
+ * @param option - 已合并 optionPatch 的 ECharts option。
+ * @param data - 可选协议数据。
+ * @returns 用户可见语义由运行时数据接管后的 option。
+ */
+function stripRuntimeOptionSemantics(option: EChartsOption, data?: ProtocolDataPayload): EChartsOption {
+  if (!isRuntimeSeriesData(data)) return option;
+  const next = { ...(option as Record<string, unknown>) };
+  next.title = stripRuntimeTitleText(next.title);
+  next.tooltip = stripRuntimeTooltipFormatter(next.tooltip);
+  return next as EChartsOption;
+}
+
+/**
+ * 协议类型到转换器的映射表，覆盖全部 13 种协议类型。
+ */
+const CONVERTER_MAP: Record<ProtocolType, ProtocolConverter> = {
+  series: seriesConverter,
+  table: tableConverter,
+  tuple: tupleConverter,
+  tree: treeConverter,
+  network: networkConverter,
+  geo: geoConverter,
+  scene3D: scene3DConverter,
+  timeline: timelineConverter,
+  transition: transitionConverter,
+  graphic: graphicConverter,
+  layout: layoutConverter,
+  composite: compositeConverter,
+  configOnly: configOnlyConverter,
+};
+
+/**
+ * ECharts 协议适配器 — 管理协议配置和数据的生命周期，
+ * 将协议载荷转换为 ECharts option 实例。
+ */
+export class EChartsProtocolAdapter {
+  /** 当前已生成的 ECharts option */
+  private currentOption: EChartsOption | null = null;
+
+  /** 当前保存的协议配置 */
+  private config: ProtocolConfigPayload | null = null;
+
+  /**
+   * 设置协议配置并生成初始 ECharts option。
+   * 若转换器构建 option 失败，会尝试回退到 config 中的 optionPatch。
+   *
+   * @param config - 协议配置载荷，定义图表的骨架结构
+   * @returns 生成的 ECharts option
+   * @throws 当转换器未找到或构建失败且无 optionPatch 可回退时抛出异常
+   */
+  setConfig(config: ProtocolConfigPayload): EChartsOption {
+    this.config = config;
+
+    try {
+      const converter = this.resolveConverter(config.protocolType);
+      this.currentOption = this.applyOptionPatch(converter.buildOption(this.configWithoutOptionPatch(config)));
+    } catch (error) {
+      // 构建 option 失败时，尝试回退到 optionPatch
+      if (config.optionPatch) {
+        this.currentOption = deepMergeOption({}, config.optionPatch);
+      } else {
+        throw error;
+      }
+    }
+
+    return this.currentOption;
+  }
+
+  /**
+   * 将数据载荷合并到当前 ECharts option 中。
+   * 必须先调用 setConfig 设置配置，否则无法合并数据。
+   * 若合并过程出错，会安全地返回当前未修改的 option。
+   *
+   * @param data - 协议数据载荷，包含图表展示所需的实际数据
+   * @returns 更新后的 ECharts option；若未设置配置或合并失败则返回当前 option
+   */
+  setData(data: ProtocolDataPayload): EChartsOption {
+    if (!this.config || !this.currentOption) {
+      return this.currentOption as EChartsOption;
+    }
+
+    try {
+      const converter = this.resolveConverter(this.config.protocolType);
+      // 先解除 Vue 响应式代理，避免 structuredClone 遇到 Proxy 后丢弃本次数据合并。
+      const currentOptionDataZoom = isPlainObject(this.currentOption)
+        ? (this.currentOption as Record<string, unknown>).dataZoom
+        : undefined;
+      const baseOption = converter.buildOption(this.configWithoutOptionPatch(this.config));
+      const patchedBaseOption = isRuntimeSeriesData(data)
+        ? this.config.optionPatch
+          ? deepMergeOption(baseOption, sanitizeRuntimeOptionPatch(this.config.optionPatch, data))
+          : baseOption
+        : baseOption;
+      // 真实数据刷新时从无模板 patch 的协议骨架重建，避免 setConfig 阶段的官方 demo series 残留。
+      const clonedOption = cloneOptionValue(patchedBaseOption);
+      const mergedOption = converter.mergeData(clonedOption, data);
+      const nextOption = isRuntimeSeriesData(data)
+        ? downgradeMatrixCoordinateOption(sanitizeRuntimeCoordinateFreeSeriesOption(
+            sanitizeNonCartesian2DCoordinateAxes(
+              sanitizeExternalGeoDependencies(stripRuntimeOptionSemantics(mergedOption, data)),
+            ) as EChartsOption,
+          ))
+        : this.applyOptionPatch(mergedOption, data);
+      const optionWithRuntimeDataZoom = currentOptionDataZoom !== undefined
+        && isPlainObject(nextOption)
+        && (nextOption as Record<string, unknown>).dataZoom === undefined
+        ? { ...(nextOption as Record<string, unknown>), dataZoom: currentOptionDataZoom } as EChartsOption
+        : nextOption;
+      // 最后再在最终 option 上做一次 dataZoom 归一化，覆盖所有来源（模板 optionPatch、
+      // converter 内联、AI 注入、用户改卡）的 dataZoom 配置，避免模板只露前几条。
+      this.currentOption = this.normalizeRuntimeDataZoom(optionWithRuntimeDataZoom, data);
+    } catch (error) {
+      // 合并数据失败时保持当前 option 不变，记录错误
+      console.warn(
+        `[EChartsProtocolAdapter] setData failed for protocol "${this.config.protocolType}":`,
+        error,
+      );
+    }
+
+    return this.currentOption as EChartsOption;
+  }
+
+  /**
+   * 获取当前 ECharts option。
+   *
+   * @returns 当前的 ECharts option，若尚未设置配置则返回 null
+   */
+  getOption(): EChartsOption | null {
+    return this.currentOption;
+  }
+
+  /**
+   * 重置适配器状态，清空配置和 option。
+   */
+  reset(): void {
+    this.currentOption = null;
+    this.config = null;
+  }
+
+  /**
+   * 根据协议类型从映射表中查找对应的转换器。
+   *
+   * @param protocolType - 协议类型标识
+   * @returns 对应的协议转换器实例
+   * @throws 当协议类型未注册时抛出错误
+   */
+  private resolveConverter(protocolType: ProtocolType): ProtocolConverter {
+    const converter = CONVERTER_MAP[protocolType];
+    if (!converter) {
+      throw new Error(
+        `[EChartsProtocolAdapter] No converter registered for protocol type: "${protocolType}"`,
+      );
+    }
+    return converter;
+  }
+
+  /**
+   * 移除配置中的 optionPatch，让各协议转换器只负责生成基础 option。
+   * @param config - 原始协议配置
+   * @returns 不含 optionPatch 的协议配置
+   */
+  private configWithoutOptionPatch(config: ProtocolConfigPayload): ProtocolConfigPayload {
+    const { optionPatch: _optionPatch, ...baseConfig } = config;
+    return baseConfig;
+  }
+
+  /**
+   * 将当前配置中的 optionPatch 深合并到 ECharts option。
+   * @param option - 转换器生成或刷新数据后的基础 option
+   * @returns 合并用户展示补丁后的 ECharts option
+   */
+  private applyOptionPatch(option: EChartsOption, data?: ProtocolDataPayload): EChartsOption {
+    const patchedOption = this.config?.optionPatch
+      ? deepMergeOption(option, sanitizeRuntimeOptionPatch(this.config.optionPatch, data))
+      : option;
+    const semanticSafeOption = stripRuntimeOptionSemantics(patchedOption, data);
+    const sanitizedOption = sanitizeNonCartesian2DCoordinateAxes(
+      sanitizeExternalGeoDependencies(semanticSafeOption),
+    ) as EChartsOption;
+    return downgradeMatrixCoordinateOption(
+      isRuntimeSeriesData(data)
+        ? sanitizeRuntimeCoordinateFreeSeriesOption(sanitizedOption)
+        : sanitizedOption,
+    );
+  }
+
+  /**
+   * 对最终 ECharts option 上的 dataZoom 做一次兜底归一化，覆盖模板 optionPatch 之外的
+   * dataZoom 来源（AI 注入、converter 内联、用户改卡等），保证运行时全量数据默认可见。
+   * @param option - 已合并的最终 ECharts option
+   * @param data - 协议数据载荷，用于判定是否存在真实运行时数据
+   * @returns dataZoom 已被归一化为 start:0,end:100 的 option
+   */
+  private normalizeRuntimeDataZoom(
+    option: EChartsOption,
+    data?: ProtocolDataPayload,
+  ): EChartsOption {
+    return normalizeFinalDataZoom(option, data);
+  }
+}