@tmagic/editor 1.8.0-beta.7 → 1.8.0-beta.9

package/src/theme/history-list-panel.scss

@@ -330,6 +330,20 @@
     font-weight: 400; // 防止被合并组头部的粗体继承
   }
 
+  // 「操作人」徽标：浅蓝描边胶囊，弱化展示操作人，仅在 step.operator 有值时渲染。
+  .m-editor-history-list-item-operator {
+    flex: 0 0 auto;
+    padding: 0 6px;
+    border: 1px solid #c6e2ff;
+    border-radius: 8px;
+    font-size: 10px;
+    line-height: 14px;
+    color: #409eff;
+    background-color: #ecf5ff;
+    white-space: nowrap;
+    font-weight: 400; // 防止被合并组头部的粗体继承
+  }
+
   // 「已保存」徽标：绿色实心胶囊，标记最近一次保存对应的历史记录（与 historyService.markSaved 对应）。
   .m-editor-history-list-item-saved {
     flex: 0 0 auto;

package/src/type.ts

@@ -16,7 +16,7 @@
  * limitations under the License.
  */
 
-import type { Component } from 'vue';
+import type { AppContext, Component } from 'vue';
 import type EventEmitter from 'events';
 import type * as Monaco from 'monaco-editor';
 import type { default as Sortable, Options, SortableEvent } from 'sortablejs';
@@ -33,7 +33,7 @@ import type {
   MPage,
   MPageFragment,
 } from '@tmagic/core';
-import type { ChangeRecord, FormConfig, TableColumnConfig, TypeFunction } from '@tmagic/form';
+import type { ChangeRecord, FormConfig, FormState, TableColumnConfig, TypeFunction } from '@tmagic/form';
 import type StageCore from '@tmagic/stage';
 import type {
   CanDropIn,
@@ -780,13 +780,18 @@ export interface StepDiffItem<T = unknown> {
  *
  * 泛型 `T` 为 `diff` 中变化内容的快照类型（页面节点 `MNode` / 代码块 `CodeBlockContent` / 数据源 `DataSourceSchema`）。
  */
-export interface BaseStepValue<T = unknown> {
+export interface BaseStepValue<T = unknown, U extends Record<string, any> = {}> {
   /**
    * 历史记录唯一标识（uuid）。入栈时自动写入（若调用方未指定），
    * 用于精确定位 / 引用某一条历史记录（如 revert、埋点、跨端同步等）。
-   * 注意与各自的 `id`（关联的页面 / 代码块 / 数据源 id）区分。
+   * 注意与 `data.id`（关联的页面 / 代码块 / 数据源 id）区分。
    */
   uuid: string;
+  /**
+   * 关联目标信息：`id` 为关联的页面 / 代码块 / 数据源等资源 id（也是历史栈的分组 key），
+   * `name` 为展示名。所有历史类型统一携带。
+   */
+  data: { name: string; id: Id };
   /** 操作类型：新增 / 删除 / 更新（三类历史记录统一携带）。 */
   opType: HistoryOpType;
   /**
@@ -820,64 +825,96 @@ export interface BaseStepValue<T = unknown> {
    * 避免源码反复保存 / 外部重设 DSL 时堆积多条 root 记录。
    */
   rootStep?: boolean;
+  /** 操作人 */
+  operator?: string;
+  /** 扩展信息 */
+  extra?: U;
 }
 // #endregion BaseStepValue
 
-// #region StepValue
-export interface StepValue extends BaseStepValue<MNode> {
-  /** 页面信息 */
-  data: { name: string; id: Id };
-  /** 操作前选中的节点 ID，用于撤销后恢复选择状态 */
-  selectedBefore: Id[];
-  /** 操作后选中的节点 ID，用于重做后恢复选择状态 */
-  selectedAfter: Id[];
-  modifiedNodeIds: Map<Id, Id>;
+// #region StepExtra
+/**
+ * 历史记录的扩展上下文（{@link BaseStepValue.extra}）。
+ * 内置字段供 `page` 类型在撤销 / 重做时恢复选区与受影响节点；扩展类型可自由附加其它键。
+ */
+export interface StepExtra {
+  /** 操作前选中的节点 ID，用于撤销后恢复选择状态（page 类型） */
+  selectedBefore?: Id[];
+  /** 操作后选中的节点 ID，用于重做后恢复选择状态（page 类型） */
+  selectedAfter?: Id[];
+  /** 本次操作涉及的节点 id 集合（page 类型） */
+  modifiedNodeIds?: Map<Id, Id>;
+  [key: string]: any;
 }
+// #endregion StepExtra
+
+// #region StepValue
+/**
+ * 页面节点历史记录条目（`diff` 内容为 {@link MNode}）。结构已与代码块 / 数据源统一收敛到
+ * {@link BaseStepValue}：关联 id 见 `data.id`，选区等上下文见 `extra`。
+ */
+export type StepValue = BaseStepValue<MNode, StepExtra>;
 // #endregion StepValue
 
 // #region CodeBlockStepValue
 /**
- * 代码块历史记录条目。按 codeBlock.id 分组保存到 historyState.codeBlockState。
- * 变更内容统一由 `diff`（单项）表达，每项见 {@link StepDiffItem}：
- * - 新增（opType 'add'）：仅 `newSchema`（新内容）；
- * - 更新（opType 'update'）：`oldSchema` + `newSchema`，并可带 `changeRecords` 做局部更新；
- * - 删除（opType 'remove'）：仅 `oldSchema`（删除前内容）。
+ * 代码块历史记录条目（`diff` 内容为 {@link CodeBlockContent}），按 `data.id`（codeBlock.id）
+ * 分组保存到 historyState.steps.codeBlock。结构与 {@link StepValue} / {@link DataSourceStepValue}
+ * 一致，仅 `diff` 快照类型不同。
  */
-export interface CodeBlockStepValue extends BaseStepValue<CodeBlockContent> {
-  /** 关联的代码块 id */
-  id: Id;
-}
+export type CodeBlockStepValue = BaseStepValue<CodeBlockContent>;
 // #endregion CodeBlockStepValue
 
 // #region DataSourceStepValue
 /**
- * 数据源历史记录条目。按 dataSource.id 分组保存到 historyState.dataSourceState。
- * 变更内容统一由 `diff`（单项）表达，每项见 {@link StepDiffItem}：
- * - 新增（opType 'add'）：仅 `newSchema`（新 schema）；
- * - 更新（opType 'update'）：`oldSchema` + `newSchema`，并可带 `changeRecords` 做局部更新；
- * - 删除（opType 'remove'）：仅 `oldSchema`（删除前 schema）。
+ * 数据源历史记录条目（`diff` 内容为 {@link DataSourceSchema}），按 `data.id`（dataSource.id）
+ * 分组保存到 historyState.steps.dataSource。结构与 {@link StepValue} / {@link CodeBlockStepValue}
+ * 一致，仅 `diff` 快照类型不同。
  */
-export interface DataSourceStepValue extends BaseStepValue<DataSourceSchema> {
-  /** 关联的数据源 id */
-  id: Id;
-}
+export type DataSourceStepValue = BaseStepValue<DataSourceSchema>;
 // #endregion DataSourceStepValue
 
+// #region HistorySteps
+/**
+ * 历史记录类型标识：内置 `page` / `codeBlock` / `dataSource`，并允许业务扩展自定义类型。
+ * `(string & {})` 保留对内置字面量的智能提示，同时不限制扩展取值。
+ */
+export type HistoryStepType = 'page' | 'codeBlock' | 'dataSource' | (string & {});
+
+/**
+ * 全部历史栈的统一容器，按「类型 -> id -> UndoRedo 栈」两级分组。
+ *
+ * - `page`：页面历史栈，按 page.id 分组（每页一份 UndoRedo）；
+ * - `codeBlock`：代码块历史栈，按 codeBlock.id 分组；
+ * - `dataSource`：数据源历史栈，按 dataSource.id 分组；
+ * - 其余键：业务通过 {@link HistoryService.registerStepType} 注册的自定义历史类型。
+ *
+ * 所有类型（含扩展类型）一视同仁：均按 id 独立分栈、独立 undo/redo，且都可通过
+ * {@link HistoryService.setMarker} 在 index 0 种入 `initial` 基线（撤销 / 回滚不会越过该基线）。
+ */
+export interface HistorySteps {
+  page: Record<Id, UndoRedo<StepValue>>;
+  codeBlock: Record<Id, UndoRedo<CodeBlockStepValue>>;
+  dataSource: Record<Id, UndoRedo<DataSourceStepValue>>;
+  /** 扩展历史类型：按 id 分组的 UndoRedo 栈。 */
+  [stepType: string]: Record<Id, UndoRedo<any>>;
+}
+// #endregion HistorySteps
+
 export interface HistoryState {
-  pageId?: Id;
-  pageSteps: Record<Id, UndoRedo<StepValue>>;
-  canRedo: boolean;
-  canUndo: boolean;
   /**
-   * 代码块历史栈，按 codeBlock.id 分组（每个代码块独立一份 UndoRedo）。
-   * 与页面/节点无关，支持独立 undo/redo。
+   * 全部历史栈的统一容器（页面 / 代码块 / 数据源 / 扩展类型），见 {@link HistorySteps}。
+   * 各类型互不影响，支持按 id 独立 undo/redo；是否可撤销 / 重做改用 {@link HistoryService.canUndo} /
+   * {@link HistoryService.canRedo}（按 stepType + id 查询）替代旧的全局 canUndo / canRedo 字段。
    */
-  codeBlockState: Record<Id, UndoRedo<CodeBlockStepValue>>;
+  steps: HistorySteps;
   /**
-   * 数据源历史栈，按 dataSource.id 分组（每个数据源独立一份 UndoRedo）。
-   * 与页面/节点无关，支持独立 undo/redo。
+   * 各历史类型的展示名称，用于历史面板（{@link HistorySteps} 的 tab / 分组标题等）。
+   * 内置 `page` / `codeBlock` / `dataSource` 有默认中文名（页面 / 代码块 / 数据源），
+   * 扩展类型可通过 {@link HistoryService.registerStepType} 的 `name` 选项或
+   * {@link HistoryService.setStepName} 登记；读取请用 {@link HistoryService.getStepName}。
    */
-  dataSourceState: Record<Id, UndoRedo<DataSourceStepValue>>;
+  stepNames: Record<string, string>;
 }
 
 // #region PersistedHistoryState
@@ -888,14 +925,16 @@ export interface HistoryState {
 export interface PersistedHistoryState {
   /** 快照结构版本号，便于后续兼容升级。 */
   version: number;
-  /** 保存时的活动页 id。 */
-  pageId?: Id;
-  /** 各页面历史栈的序列化快照，按 pageId 分组。 */
-  pageSteps: Record<Id, SerializedUndoRedo<StepValue>>;
-  /** 各代码块历史栈的序列化快照，按 codeBlockId 分组。 */
-  codeBlockState: Record<Id, SerializedUndoRedo<CodeBlockStepValue>>;
-  /** 各数据源历史栈的序列化快照，按 dataSourceId 分组。 */
-  dataSourceState: Record<Id, SerializedUndoRedo<DataSourceStepValue>>;
+  /**
+   * 全部历史栈的序列化快照，按「类型 -> id」两级分组，与 {@link HistorySteps} 对应。
+   * 内置 `page` / `codeBlock` / `dataSource`，并包含业务注册的扩展类型。
+   */
+  steps: {
+    page: Record<Id, SerializedUndoRedo<StepValue>>;
+    codeBlock: Record<Id, SerializedUndoRedo<CodeBlockStepValue>>;
+    dataSource: Record<Id, SerializedUndoRedo<DataSourceStepValue>>;
+    [stepType: string]: Record<Id, SerializedUndoRedo<any>>;
+  };
   /** 保存时间戳（毫秒）。 */
   savedAt: number;
 }
@@ -923,9 +962,9 @@ export interface HistoryPersistOptions {
 /**
  * 历史面板用：当前页面的一条历史步骤（包含位置和是否已应用）。
  */
-export interface PageHistoryStepEntry {
+export interface HistoryStepEntry<T> {
   /** 步骤内容 */
-  step: StepValue;
+  step: T;
   /** 在所属栈中的索引（0 为最早） */
   index: number;
   /** 是否处于"已应用"段（即位于栈游标之前）。撤销后变为 false。 */
@@ -935,55 +974,37 @@ export interface PageHistoryStepEntry {
 }
 
 /**
- * 页面历史面板分组。
- * - 连续修改同一目标节点（updatedItems[0].oldNode.id 一致）的 'update' 步骤合并成一组；
- * - 多节点更新 / add / remove 始终独立成组（无法明确归属单一目标）。
- * - targetId 为 undefined 表示"无明确目标"（如 add/remove/多节点 update），不参与合并。
+ * 历史面板分组（页面 / 数据源 / 代码块 / 扩展类型统一结构）。
+ *
+ * 把指定历史栈的步骤列表按"目标"做相邻合并：
+ * - 连续修改同一目标（单实体 update，targetId 一致）的多步合并成一组，组内可展开查看每步；
+ * - add / remove / 多实体 update 始终独立成组（无法明确归属单一目标）；
+ * - targetId 为 undefined 表示"无明确目标"，不参与合并。
+ *
+ * 各类型仅 `kind` 与 step 快照类型不同，统一由泛型描述：
+ * - 页面：`HistoryGroup<StepValue>`，`kind: 'page'`，`id` 为 pageId，`targetId` 为被改节点 id；
+ * - 数据源：`HistoryGroup<DataSourceStepValue>`，`kind: 'data-source'`，`id` 为 dataSource.id；
+ * - 代码块：`HistoryGroup<CodeBlockStepValue>`，`kind: 'code-block'`，`id` 为 codeBlock.id。
  */
-export interface PageHistoryGroup {
-  kind: 'page';
-  /** 所属页面 id */
-  pageId: Id;
-  /** 该分组的操作类型 */
+export interface HistoryGroup<T extends BaseStepValue = BaseStepValue> {
+  /** 历史类型标识：page / code-block / data-source（扩展类型同理）。 */
+  kind: string;
+  /** 所属栈 id（page 为 pageId，代码块 / 数据源为对应资源 id）。 */
+  id: Id;
+  /** 该分组的操作类型。 */
   opType: HistoryOpType;
   /**
-   * 合并的目标节点 id；只有"单节点 update"才有值，并按此 id 与相邻同 id 的 update 合并。
-   * undefined 表示该分组不可被合并（add / remove / 多节点 update）。
+   * 合并的目标 id：仅"单实体 update"有值，并按此与相邻同 id 的 update 合并。
+   * undefined 表示该分组不可被合并（add / remove / 多实体 update）。
    */
   targetId?: Id;
-  /** 目标节点的可读名（取最后一步的 newNode.name/type/id） */
+  /** 目标可读名（取最后一步快照的 name/type/id）。 */
   targetName?: string;
-  /** 组内所有步骤，按时间正序 */
-  steps: PageHistoryStepEntry[];
-  /** 组内最后一步是否已应用 */
-  applied: boolean;
-  /** 是否为当前所在的分组（包含栈中最近一次已应用步骤的那一组）。 */
-  isCurrent?: boolean;
-}
-
-/**
- * 数据源 / 代码块历史面板分组（按 id 分栈展示）。
- * 二者结构完全一致，仅 `kind` 与 step 类型不同，统一由该泛型描述：
- * - 数据源：`StackHistoryGroup<DataSourceStepValue, 'data-source'>`；
- * - 代码块：`StackHistoryGroup<CodeBlockStepValue, 'code-block'>`。
- *
- * 每条操作记录独立成组，不做相邻合并（与页面历史 {@link PageHistoryGroup} 不同），故 `steps` 恒为单元素。
- */
-export interface StackHistoryGroup<
-  T extends BaseStepValue = BaseStepValue,
-  K extends 'code-block' | 'data-source' = 'code-block' | 'data-source',
-> {
-  /** 区分代码块 / 数据源。 */
-  kind: K;
-  /** 关联的代码块 / 数据源 id。 */
-  id: Id;
-  /** 该分组的操作类型。 */
-  opType: HistoryOpType;
-  /** 组内所有步骤，按时间正序（不做相邻合并，恒为单元素）。 */
+  /** 组内所有步骤，按时间正序。 */
   steps: { step: T; index: number; applied: boolean; isCurrent?: boolean }[];
-  /** 组内最后一步是否已应用，用于整组的状态展示。 */
+  /** 组内最后一步是否已应用。 */
   applied: boolean;
-  /** 是否为当前所在的分组（包含该栈最近一次已应用步骤的那一组）。 */
+  /** 是否为当前所在的分组（包含栈中最近一次已应用步骤的那一组）。 */
   isCurrent?: boolean;
 }
 // #endregion HistoryListEntry
@@ -1199,6 +1220,21 @@ export interface EditorEvents {
   'history-change': [data: MPage | MPageFragment];
 }
 
+export interface HistoryEvents {
+  change: [
+    state: BaseStepValue | StepValue | CodeBlockStepValue | DataSourceStepValue,
+    stepType: HistoryStepType,
+    id: Id,
+  ];
+  'code-block-history-change': [id: Id, state: CodeBlockStepValue];
+  'data-source-history-change': [id: Id, state: DataSourceStepValue];
+  'restore-from-indexed-db': [snapshot: PersistedHistoryState | null];
+  'save-to-indexed-db': [snapshot: PersistedHistoryState];
+  'mark-saved': [{ kind: HistoryStepType; id?: Id }];
+  clear: [{ id: Id; stepType: HistoryStepType }];
+  'marker-change': [{ id: Id; marker: StepValue; stepType: HistoryStepType }];
+}
+
 export const canUsePluginMethods = {
   async: [
     'getLayout',
@@ -1318,3 +1354,60 @@ export interface HistoryBucketConfig<T extends BaseStepValue = BaseStepValue> ex
   /** 是否支持「跳转到该记录」(goto)，默认 true。 */
   gotoEnabled?: boolean;
 }
+
+export interface UseHistoryRevertOptions {
+  /**
+   * 父级应用上下文，用于让动态挂载的「差异确认弹窗」继承全局组件 / 指令 / provide / 插件
+   * （Element Plus、@tmagic/form 字段组件等）。未显式传入时，会自动取调用方所在组件的 appContext
+   * （`getCurrentInstance()?.appContext`）。业务方若在组件 setup 之外调用，需手动传入（如 `editorApp._context`）。
+   */
+  appContext?: AppContext | null;
+  /**
+   * 透传给差异确认弹窗的 `extendState`（即 Editor 的 `extendFormState`），
+   * 使对比表单中依赖业务上下文的 `display` / `disabled` 等 filterFunction 正常工作。
+   */
+  extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+  /**
+   * 返回 PropsPanel 主属性表单（FormPanel -> MForm）的 formState。
+   * 仅页面历史「查看差异 / 回滚确认」场景会使用该 formState 覆盖 CompareForm 中同名扩展字段，
+   * 以保证两处 filterFunction 读取到一致的运行态上下文。
+   */
+  getPropsPanelFormState?: () => FormState | undefined;
+}
+
+/**
+ * 业务自有历史（如管理台「模块」）做差异对比时所需的额外渲染入参。
+ * 内置的页面 / 数据源 / 代码块按 `category` 自动取表单配置，无需传这些；
+ * 业务自有类别可通过 `loadConfig` 注入自定义表单配置加载逻辑。
+ */
+export interface CustomDiffFormOptions {
+  /**
+   * 自定义差异表单配置加载逻辑（如「模块」按 c_type 重建表单配置），
+   * 透传给弹窗内部的 CompareForm；缺省时按 `category` 走内置加载。
+   */
+  loadConfig?: CompareFormLoadConfig;
+  /** 需要走 self diff 的字段类型（如模块的 mod-cond）。 */
+  selfDiffFieldTypes?: string[];
+  /**
+   * 可选：外部提供的 formState（通常来自 PropsPanel 主表单），
+   * 对比弹窗会用它覆盖 CompareForm 中同名扩展字段，避免上下文不一致。
+   */
+  compareFormState?: FormState;
+}
+
+/**
+ * 业务自有历史复用「单步回滚」交互（{@link useHistoryRevert} 的 `confirmAndRevert`）的入参。
+ * 与内置页面 / 数据源 / 代码块回滚共用「目标校验 → 差异/二次确认弹窗 → 反向回滚」流程，
+ * 业务方只需提供：差异弹窗入参（可选）、表单配置加载（可选）、实际回滚执行函数。
+ */
+export interface ConfirmAndRevertOptions<T = unknown> extends CustomDiffFormOptions {
+  /**
+   * 差异确认弹窗入参；可对比的步骤（单实体 update）传入后弹差异确认弹窗，
+   * 传 null / 省略则退化为普通二次确认框（add / remove / 不可对比）。
+   */
+  diffPayload?: DiffDialogPayload | null;
+  /** 回滚前置校验：返回 true 表示目标数据已删除等不可回滚，给出统一提示并中止。 */
+  isTargetMissing?: () => boolean;
+  /** 用户确认后执行的实际回滚逻辑。 */
+  revert: () => T | Promise<T>;
+}

package/src/utils/history.ts

@@ -23,15 +23,7 @@ import type { Id } from '@tmagic/core';
 import type { ChangeRecord } from '@tmagic/form';
 import { guid } from '@tmagic/utils';
 
-import type {
-  BaseStepValue,
-  HistoryOpSource,
-  PageHistoryGroup,
-  PageHistoryStepEntry,
-  StackHistoryGroup,
-  StepDiffItem,
-  StepValue,
-} from '@editor/type';
+import type { BaseStepValue, HistoryGroup, StepDiffItem } from '@editor/type';
 
 import { UndoRedo } from './undo-redo';
 
@@ -71,17 +63,20 @@ export const detectStackOpType = (oldVal: unknown, newVal: unknown): 'add' | 're
  *
  * - `add`：oldValue = null；`remove`：newValue = null；`update`：两者都有，可带 changeRecords 做局部更新。
  * - 内容会做 cloneDeep 防止后续被外部引用篡改；opType 依据 old/new 是否为 null 推断。
- * - 仅负责构造 step 并返回，入栈与事件 emit 由各公共方法（pushCodeBlock / pushDataSource）自行处理。
+ * - 仅负责构造 step 并返回，入栈与事件 emit 由统一的 history.push(stepType, step, id) 处理。
  * - 不直接驱动业务 service，调用方负责实际写回。
  */
-export const createStackStep = <T, S extends BaseStepValue<T> & { id: Id }>(
+export const createStackStep = <T, S extends BaseStepValue<T>>(
   id: Id,
-  payload: {
+  // payload 以 {@link BaseStepValue} 为基础：透传字段（historyDescription / source / operator / rootStep / extra）
+  // 随 BaseStepValue 演进自动同步，原样写入 step；自动生成字段（uuid / data / opType / diff / timestamp / saved）
+  // 从 payload 中排除，由本方法内部构造。oldValue / newValue / changeRecords / name 为构造 diff 与 data 用的输入。
+  payload: Omit<BaseStepValue<T>, 'uuid' | 'data' | 'opType' | 'diff' | 'timestamp' | 'saved'> & {
     oldValue: T | null;
     newValue: T | null;
     changeRecords?: ChangeRecord[];
-    historyDescription?: string;
-    source?: HistoryOpSource;
+    /** 展示名（缺省时从快照 name / title 推断）。 */
+    name?: string;
   },
 ): S | null => {
   if (!id) return null;
@@ -90,10 +85,13 @@ export const createStackStep = <T, S extends BaseStepValue<T> & { id: Id }>(
   const newSchema = payload.newValue ? cloneDeep(payload.newValue) : null;
   const changeRecords = payload.changeRecords?.length ? cloneDeep(payload.changeRecords) : undefined;
   const opType = detectStackOpType(payload.oldValue, payload.newValue);
+  // 展示名：代码块取 name，数据源取 title，取不到则留空（不影响 undo/redo，仅用于展示）。
+  const schema = (payload.newValue ?? payload.oldValue) as { name?: string; title?: string } | null;
+  const name = payload.name ?? schema?.name ?? schema?.title ?? '';
 
-  const step: BaseStepValue<T> & { id: Id } = {
+  const step: BaseStepValue<T> = {
     uuid: guid(),
-    id,
+    data: { name, id },
     opType,
     diff: [
       {
@@ -104,7 +102,10 @@ export const createStackStep = <T, S extends BaseStepValue<T> & { id: Id }>(
     ],
     historyDescription: payload.historyDescription,
     source: payload.source,
+    operator: payload.operator,
+    rootStep: payload.rootStep,
     timestamp: Date.now(),
+    extra: payload.extra,
   };
 
   return step as S;
@@ -121,61 +122,41 @@ export const markStackSaved = <S extends { saved?: boolean }>(undoRedo?: UndoRed
 };
 
 /**
- * 把单个「按 id 分栈」的历史栈（代码块 / 数据源）拆成若干 group：
- * 每条操作记录独立成组，不做相邻 update 合并（与页面历史的合并策略不同）。
+ * 把单个历史栈（页面 / 代码块 / 数据源 / 扩展类型）的步骤列表按"目标"做相邻合并：
+ * - 单实体的 'update' 按 targetId 与相邻同 targetId 的 update 合并到一个 group，组内可展开查看每步；
+ * - 'add' / 'remove' 始终独立成组（语义上是结构变更，不应被收纳进单实体修改组）；
+ * - 多实体 'update'（如页面批量改属性）也独立成组（无明确单一目标，避免误合并）。
  *
- * 代码块与数据源除 `kind` 外结构完全一致，统一由本方法处理；`kind` 决定返回的具体分组类型。
+ * 各类型行为完全一致，仅 `kind` 与 step 快照类型不同，统一由本方法处理。
  */
-export const mergeStackSteps = <S extends BaseStepValue, K extends 'code-block' | 'data-source'>(
-  kind: K,
+export const mergeSteps = <T extends BaseStepValue>(
+  kind: string,
   id: Id,
-  list: S[],
+  list: T[],
   cursor: number,
-): StackHistoryGroup<S, K>[] => {
-  const currentIndex = cursor - 1;
-  return list.map((step, index) => {
-    const applied = index < cursor;
-    const isCurrent = index === currentIndex;
-    return {
-      kind,
-      id,
-      opType: step.opType,
-      steps: [{ step, index, applied, isCurrent }],
-      applied,
-      isCurrent,
-    };
-  });
-};
-
-/**
- * 把页面栈拆成若干 group：
- * - 单节点的 'update' 按 targetId 与相邻同 targetId 的 update 合并到一个 group；
- * - 'add' / 'remove' 始终独立成组（语义上是结构变更，不应被收纳进单节点修改组）；
- * - 多节点 'update'（如批量改属性）也独立成组（无明确单一目标，避免误合并）。
- */
-export const mergePageSteps = (pageId: Id, list: StepValue[], cursor: number): PageHistoryGroup[] => {
-  const groups: PageHistoryGroup[] = [];
-  let current: PageHistoryGroup | null = null;
+): HistoryGroup<T>[] => {
+  const groups: HistoryGroup<T>[] = [];
+  let current: HistoryGroup<T> | null = null;
   const currentIndex = cursor - 1;
   list.forEach((step, index) => {
     const applied = index < cursor;
     const isCurrent = index === currentIndex;
-    const targetId = detectPageTargetId(step);
-    const targetName = detectPageTargetName(step);
-    const entry: PageHistoryStepEntry = { step, index, applied, isCurrent };
+    const targetId = detectTargetId(step);
+    const targetName = detectTargetName(step);
+    const entry = { step, index, applied, isCurrent };
 
-    // 仅"单节点 update"参与合并；其它情形（add/remove/多节点 update）始终独立成组。
+    // 仅"单实体 update"参与合并；其它情形（add/remove/多实体 update）始终独立成组。
     const mergeable = step.opType === 'update' && targetId !== undefined;
     if (mergeable && current?.opType === 'update' && current.targetId === targetId) {
       current.steps.push(entry);
       current.applied = applied;
       if (isCurrent) current.isCurrent = true;
-      // 保持目标名为最近一次的（节点重命名时也能反映）
+      // 保持目标名为最近一次的（重命名时也能反映）
       if (targetName) current.targetName = targetName;
     } else {
       current = {
-        kind: 'page',
-        pageId,
+        kind,
+        id,
         opType: step.opType,
         targetId: mergeable ? targetId : undefined,
         targetName,
@@ -190,37 +171,40 @@ export const mergePageSteps = (pageId: Id, list: StepValue[], cursor: number): P
 };
 
 /**
- * 解析 StepValue 中的"目标节点 id"用于合并：
- * - 单节点 update：取唯一一项 updatedItems 的节点 id；
- * - 其它情形（多节点 update / add / remove）：返回 undefined，表示不参与合并。
+ * 解析 step 中的"目标 id"用于合并：
+ * - 单实体 update：取唯一一项 diff 的快照 id；快照无 id 时（如 CodeBlockContent）回退到 `step.data.id`
+ *   （即资源 id），使代码块 / 数据源同样能按资源合并相邻 update；
+ * - 其它情形（多实体 update / add / remove）：返回 undefined，表示不参与合并。
  */
-export const detectPageTargetId = (step: StepValue): Id | undefined => {
+export const detectTargetId = (step: BaseStepValue): Id | undefined => {
   if (step.opType !== 'update') return undefined;
   const items = step.diff;
   if (items?.length !== 1) return undefined;
-  return items[0].newSchema?.id ?? items[0].oldSchema?.id;
+  const newSchema = items[0].newSchema as { id?: Id } | undefined;
+  const oldSchema = items[0].oldSchema as { id?: Id } | undefined;
+  return newSchema?.id ?? oldSchema?.id ?? step.data?.id;
 };
 
-/** 解析 StepValue 中的目标节点可读名（用于 UI 展示）。 */
-export const detectPageTargetName = (step: StepValue): string | undefined => {
+/** 解析 step 中的目标可读名（用于 UI 展示）。 */
+export const detectTargetName = (step: BaseStepValue): string | undefined => {
   const items = step.diff;
   if (step.opType === 'update') {
     if (items?.length === 1) {
-      const node = items[0].newSchema || items[0].oldSchema;
+      const node = (items[0].newSchema || items[0].oldSchema) as { name?: string; type?: string; id?: Id } | undefined;
       return (node?.name as string) || (node?.type as string) || (node?.id !== undefined ? `${node.id}` : undefined);
     }
     return items?.length ? `${items.length} 个节点` : undefined;
   }
   if (step.opType === 'add') {
     if (items?.length === 1) {
-      const n = items[0].newSchema;
+      const n = items[0].newSchema as { name?: string; type?: string; id?: Id } | undefined;
       return (n?.name as string) || (n?.type as string) || `${n?.id}`;
     }
     return items?.length ? `${items.length} 个节点` : undefined;
   }
   if (step.opType === 'remove') {
     if (items?.length === 1) {
-      const n = items[0].oldSchema;
+      const n = items[0].oldSchema as { name?: string; type?: string; id?: Id } | undefined;
       return (n?.name as string) || (n?.type as string) || `${n?.id}`;
     }
     return items?.length ? `${items.length} 个节点` : undefined;
@@ -290,10 +274,11 @@ export const getOrCreateStack = <T>(stacks: Record<Id, UndoRedo<T>>, id: Id): Un
 };
 
 /**
- * 撤销下限：当页面栈 index 0 是 `opType: 'initial'` 的基线 step 时为 1（基线不可被撤销），否则为 0。
- * 用于把 cursor 钉在基线之上，保证 undo / canUndo / goto 都不会越过初始基线。
+ * 撤销下限：当栈 index 0 是 `opType: 'initial'` 的基线 step 时为 1（基线不可被撤销），否则为 0。
+ * 适用于所有历史类型（page / codeBlock / dataSource / 扩展），把 cursor 钉在基线之上，
+ * 保证 undo / canUndo / goto 都不会越过初始基线。
  */
-export const undoFloor = (undoRedo: UndoRedo<StepValue>): number => {
+export const undoFloor = (undoRedo: UndoRedo<any>): number => {
   return undoRedo.getElementList()[0]?.opType === 'initial' ? 1 : 0;
 };