@nocobase/flow-engine 2.1.0-alpha.4 → 2.1.0-alpha.45

package/src/models/__tests__/flowModel.test.ts

@@ -370,15 +370,17 @@ describe('FlowModel', () => {
         };
 
         TestFlowModel.registerFlow(exitFlow);
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
-        const result = await model.applyFlow('exitFlow');
-
-        expect(result).toBeInstanceOf(FlowExitAllException);
-        expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
-        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        try {
+          const result = await model.applyFlow('exitFlow');
 
-        consoleSpy.mockRestore();
+          expect(result).toBeInstanceOf(FlowExitAllException);
+          expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
+          expect(loggerSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        } finally {
+          loggerSpy.mockRestore();
+        }
       });
 
       test('should handle ctx.exit() as FlowExitAllException in beforeRender dispatch', async () => {
@@ -474,15 +476,17 @@ describe('FlowModel', () => {
         };
 
         TestFlowModel.registerFlow(exitFlow);
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
-        const result = await model.applyFlow('exitFlow');
-
-        expect(result).toBeInstanceOf(FlowExitAllException);
-        expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
-        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        try {
+          const result = await model.applyFlow('exitFlow');
 
-        consoleSpy.mockRestore();
+          expect(result).toBeInstanceOf(FlowExitAllException);
+          expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
+          expect(loggerSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        } finally {
+          loggerSpy.mockRestore();
+        }
       });
 
       test('should propagate step execution errors', async () => {
@@ -546,6 +550,34 @@ describe('FlowModel', () => {
 
         loggerSpy.mockRestore();
       });
+
+      test('should warn and skip step when use and handler are both missing', async () => {
+        const warnSpy = vi.spyOn(model.context.logger, 'warn').mockImplementation(() => {});
+        const errorSpy = vi.spyOn(model.context.logger, 'error').mockImplementation(() => {});
+
+        TestFlowModel.registerFlow({
+          key: 'settingsOnlyFlow',
+          steps: {
+            edit: {
+              title: 'Edit',
+              uiSchema: {},
+            },
+          },
+        });
+
+        const result = await model.applyFlow('settingsOnlyFlow');
+
+        expect(result).toEqual({});
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining("Step 'edit' in flow 'settingsOnlyFlow' has neither 'use' nor 'handler'"),
+        );
+        expect(errorSpy).not.toHaveBeenCalledWith(
+          expect.stringContaining("Step 'edit' in flow 'settingsOnlyFlow' has neither 'use' nor 'handler'"),
+        );
+
+        warnSpy.mockRestore();
+        errorSpy.mockRestore();
+      });
     });
 
     describe('beforeRender flows', () => {
@@ -768,7 +800,7 @@ describe('FlowModel', () => {
         const eventFlow = createEventFlowDefinition('testEvent');
         TestFlowModel.registerFlow(eventFlow);
 
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.dispatchEvent('testEvent', { data: 'payload' });
@@ -776,7 +808,7 @@ describe('FlowModel', () => {
           // Use a more reliable approach than arbitrary timeout
           await new Promise((resolve) => setTimeout(resolve, 0));
 
-          expect(consoleSpy).toHaveBeenCalledWith(
+          expect(loggerSpy).toHaveBeenCalledWith(
             expect.stringContaining('[FlowModel] dispatchEvent: uid=test-model-uid, event=testEvent'),
           );
           expect(eventFlow.steps.eventStep.handler).toHaveBeenCalledWith(
@@ -786,7 +818,7 @@ describe('FlowModel', () => {
             expect.any(Object),
           );
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
 
@@ -1597,7 +1629,7 @@ describe('FlowModel', () => {
         fork1.dispose = vi.fn();
         fork2.dispose = vi.fn();
 
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.clearForks();
@@ -1606,19 +1638,19 @@ describe('FlowModel', () => {
           expect(fork2.dispose).toHaveBeenCalled();
           expect(model.forks.size).toBe(0);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
 
       test('should handle empty forks collection when clearing', () => {
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.clearForks();
 
           expect(model.forks.size).toBe(0);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
     });
@@ -1746,7 +1778,7 @@ describe('FlowModel', () => {
       test('should clean up resources on remove', () => {
         model.createFork();
         model.createFork();
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         // Mock removeModel to simulate proper fork cleanup
         flowEngine.removeModel = vi.fn().mockImplementation(() => {
@@ -1763,7 +1795,7 @@ describe('FlowModel', () => {
           expect(model.forks.size).toBe(0);
           expect(flowEngine.removeModel).toHaveBeenCalledWith(model.uid);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
     });
@@ -1840,22 +1872,17 @@ describe('FlowModel', () => {
       });
 
       test('should rerender triggers beforeRender without cache', async () => {
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
         model.dispatchEvent = vi.fn().mockResolvedValue(undefined) as any;
 
-        try {
-          await expect(model.rerender()).resolves.not.toThrow();
-          expect(model.dispatchEvent).toHaveBeenCalledWith('beforeRender', undefined, {
-            useCache: false,
-          });
-        } finally {
-          consoleSpy.mockRestore();
-        }
+        await expect(model.rerender()).resolves.not.toThrow();
+        expect(model.dispatchEvent).toHaveBeenCalledWith('beforeRender', undefined, {
+          useCache: false,
+        });
       });
     });
 
     describe('serialization', () => {
-      test('should serialize basic model data, excluding props and flowEngine', () => {
+      test('should serialize basic model data with the latest props, excluding flowEngine', () => {
         model.sortIndex = 5;
         model.setProps({ name: 'Test Model', value: 42 });
         model.setStepParams({
@@ -1867,13 +1894,12 @@ describe('FlowModel', () => {
         expect(serialized).toEqual(
           expect.objectContaining({
             uid: model.uid,
+            props: expect.objectContaining({ name: 'Test Model', value: 42 }),
             stepParams: expect.objectContaining({ flow1: { step1: { param1: 'value1' } } }),
             sortIndex: 5,
             subModels: expect.any(Object),
           }),
         );
-        // props should be excluded from serialization
-        expect(serialized.props).toBeUndefined();
         expect(serialized.flowEngine).toBeUndefined();
       });
 
@@ -1892,6 +1918,7 @@ describe('FlowModel', () => {
         expect(serialized).toEqual(
           expect.objectContaining({
             uid: 'empty-model',
+            props: expect.objectContaining({ foo: 'bar' }),
             stepParams: expect.any(Object),
             sortIndex: expect.any(Number),
             subModels: expect.any(Object),
@@ -1899,6 +1926,22 @@ describe('FlowModel', () => {
         );
         expect(serialized.flowEngine).toBeUndefined();
       });
+
+      test('should serialize the latest props after multiple updates', () => {
+        model.setProps({ fieldNames: { title: 'name' }, searchable: true });
+        model.setProps({ fieldNames: { title: 'age' } });
+        model.setProps('defaultExpandAll', false);
+
+        const serialized = model.serialize();
+
+        expect(serialized.props).toEqual(
+          expect.objectContaining({
+            fieldNames: { title: 'age' },
+            searchable: true,
+            defaultExpandAll: false,
+          }),
+        );
+      });
     });
   });
 
@@ -2874,7 +2917,7 @@ describe('FlowModel', () => {
   describe('Edge Cases & Error Handling', () => {
     test('should handle model destruction gracefully', () => {
       const model = new FlowModel(modelOptions);
-      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
       model.createFork();
       model.setProps({ testProp: 'value' });
@@ -2882,7 +2925,7 @@ describe('FlowModel', () => {
       try {
         expect(() => model.remove()).not.toThrow();
       } finally {
-        consoleSpy.mockRestore();
+        loggerSpy.mockRestore();
       }
     });
 

package/src/models/flowModel.tsx

@@ -11,8 +11,6 @@ import { batch, define, observable, observe } from '@formily/reactive';
 import _ from 'lodash';
 import React from 'react';
 import { uid } from 'uid/secure';
-import { openRequiredParamsStepFormDialog as openRequiredParamsStepFormDialogFn } from '../components/settings/wrappers/contextual/StepRequiredSettingsDialog';
-import { openStepSettingsDialog as openStepSettingsDialogFn } from '../components/settings/wrappers/contextual/StepSettingsDialog';
 import { Emitter } from '../emitter';
 import { InstanceFlowRegistry } from '../flow-registry/InstanceFlowRegistry';
 import { FlowContext, FlowModelContext, FlowRuntimeContext } from '../flowContext';
@@ -36,7 +34,9 @@ import type {
 import { IModelComponentProps, ReadonlyModelProps } from '../types';
 import { isInheritedFrom, setupRuntimeContextSteps } from '../utils';
 // import { FlowExitAllException } from '../utils/exceptions';
-import { Typography } from 'antd/lib';
+import { Typography } from 'antd';
+import type { MenuProps } from 'antd';
+import { observer } from '..';
 import { ModelActionRegistry } from '../action-registry/ModelActionRegistry';
 import { buildSubModelItem } from '../components/subModel/utils';
 import { ModelEventRegistry } from '../event-registry/ModelEventRegistry';
@@ -46,8 +46,6 @@ import { FlowSettingsOpenOptions } from '../flowSettings';
 import type { ScheduleOptions } from '../scheduler/ModelOperationScheduler';
 import type { DispatchEventOptions, EventDefinition } from '../types';
 import { ForkFlowModel } from './forkFlowModel';
-import type { MenuProps } from 'antd';
-import { observer } from '..';
 
 // 使用 WeakMap 为每个类缓存一个 ModelActionRegistry 实例
 const classActionRegistries = new WeakMap<typeof FlowModel, ModelActionRegistry>();
@@ -62,16 +60,22 @@ const modelMetas = new WeakMap<typeof FlowModel, FlowModelMeta>();
 const modelGlobalRegistries = new WeakMap<typeof FlowModel, GlobalFlowRegistry>();
 
 type BaseMenuItem = NonNullable<MenuProps['items']>[number];
-type MenuLeafItem = Exclude<BaseMenuItem, { children: MenuProps['items'] }>;
+type MenuBaseItem = Omit<Exclude<BaseMenuItem, null>, 'key' | 'children'>;
 
-export type FlowModelExtraMenuItem = Omit<MenuLeafItem, 'key'> & {
+export type FlowModelExtraMenuItem = MenuBaseItem & {
   key: React.Key;
   group?: string;
   sort?: number;
+  label?: React.ReactNode;
+  disabled?: boolean;
   onClick?: () => void;
+  children?: FlowModelExtraMenuItem[];
 };
 
-type FlowModelExtraMenuItemInput = Omit<FlowModelExtraMenuItem, 'key'> & { key?: React.Key };
+type FlowModelExtraMenuItemInput = Omit<FlowModelExtraMenuItem, 'key' | 'children'> & {
+  key?: React.Key;
+  children?: FlowModelExtraMenuItemInput[];
+};
 
 type ExtraMenuItemEntry = {
   group?: string;
@@ -88,6 +92,66 @@ type ExtraMenuItemEntry = {
 
 const classMenuExtensions = new WeakMap<typeof FlowModel, Set<ExtraMenuItemEntry>>();
 
+const sortExtraMenuItems = (items: FlowModelExtraMenuItem[]) => {
+  return [...items].sort((a, b) => (a.sort ?? 0) - (b.sort ?? 0));
+};
+
+const isFlowModelExtraMenuItem = (item: FlowModelExtraMenuItem | null): item is FlowModelExtraMenuItem => {
+  return item !== null;
+};
+
+const normalizeExtraMenuItem = (
+  item: FlowModelExtraMenuItemInput,
+  {
+    group,
+    sort,
+    prefix,
+    path,
+  }: {
+    group: string;
+    sort: number;
+    prefix: string;
+    path: string;
+  },
+): FlowModelExtraMenuItem | null => {
+  if (!item) {
+    return null;
+  }
+
+  const normalizedGroup = item.group || group;
+  const normalizedSort = typeof item.sort === 'number' ? item.sort : sort;
+  const normalizedChildren = sortExtraMenuItems(
+    (item.children || [])
+      .map((child, index) =>
+        normalizeExtraMenuItem(child, {
+          group: normalizedGroup,
+          sort: normalizedSort,
+          prefix,
+          path: `${path}-${index}`,
+        }),
+      )
+      .filter(isFlowModelExtraMenuItem),
+  );
+
+  return {
+    ...item,
+    key: item.key ?? `${prefix}-${normalizedGroup}-${path}`,
+    group: normalizedGroup,
+    sort: normalizedSort,
+    children: normalizedChildren.length ? normalizedChildren : undefined,
+  };
+};
+
+async function loadOpenStepSettingsDialog() {
+  const mod = await import('../components/settings/wrappers/contextual/StepSettingsDialog');
+  return mod.openStepSettingsDialog;
+}
+
+async function loadOpenRequiredParamsStepFormDialog() {
+  const mod = await import('../components/settings/wrappers/contextual/StepRequiredSettingsDialog');
+  return mod.openRequiredParamsStepFormDialog;
+}
+
 export enum ModelRenderMode {
   ReactElement = 'reactElement',
   RenderFunction = 'renderFunction',
@@ -208,11 +272,14 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
       if (changed.type === 'set' && _.isEqual(changed.value, changed.oldValue)) {
         return;
       }
+      const hasLastAutoRun = !!this._lastAutoRunParams;
 
       if (this.flowEngine) {
         this.invalidateFlowCache('beforeRender');
       }
-      this._rerunLastAutoRun();
+      if (hasLastAutoRun) {
+        this._rerunLastAutoRun();
+      }
       this.forks.forEach((fork) => {
         fork.rerender();
       });
@@ -695,6 +762,8 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     } else {
       this.props = { ...this.props, ...props };
     }
+
+    this._options.props = { ...this.props };
   }
 
   getProps(): ReadonlyModelProps {
@@ -754,7 +823,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     }
     const isFork = (this as any).isFork === true;
     const target = this;
-    console.log(
+    currentFlowEngine.logger.debug(
       `[FlowModel] applyFlow: uid=${this.uid}, flowKey=${flowKey}, isFork=${isFork}, cleanRun=${
         this.cleanRun
       }, targetIsFork=${(target as any)?.isFork === true}`,
@@ -774,7 +843,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     }
     const isFork = (this as any).isFork === true;
     const target = this;
-    console.log(
+    currentFlowEngine.logger.debug(
       `[FlowModel] dispatchEvent: uid=${this.uid}, event=${eventName}, isFork=${isFork}, cleanRun=${
         this.cleanRun
       }, targetIsFork=${(target as any)?.isFork === true}`,
@@ -858,6 +927,11 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     }
   }, 100);
 
+  private resetAutoRunState(): void {
+    this._rerunLastAutoRun?.cancel?.();
+    this._lastAutoRunParams = null;
+  }
+
   /**
    * 通用事件分发钩子：开始
    * 子类可覆盖；beforeRender 事件可通过抛出 FlowExitException 提前终止。
@@ -951,7 +1025,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
       }
 
       // 创建缓存的响应式包装器组件工厂（只创建一次）
-      const createReactiveWrapper = (modelInstance: any) => {
+      const createReactiveWrapper = (modelInstance: FlowModel) => {
         const ReactiveWrapper = observer(() => {
           // 触发响应式更新的关键属性访问（读取 run/渲染目标的 props）
           const renderTarget = modelInstance;
@@ -977,6 +1051,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
               model: renderTarget,
             });
             return () => {
+              renderTarget.resetAutoRunState();
               if (typeof renderTarget.onUnmount === 'function') {
                 renderTarget.onUnmount();
               }
@@ -1177,17 +1252,17 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     return model;
   }
 
-  filterSubModels<K extends keyof Structure['subModels'], R>(
+  filterSubModels<K extends keyof NonNullable<Structure['subModels']>, R>(
     subKey: K,
-    callback: (model: ArrayElementType<Structure['subModels'][K]>, index: number) => boolean,
-  ): ArrayElementType<Structure['subModels'][K]>[] {
+    callback: (model: ArrayElementType<NonNullable<Structure['subModels']>[K]>, index: number) => boolean,
+  ): ArrayElementType<NonNullable<Structure['subModels']>[K]>[] {
     const model = (this.subModels as any)[subKey as string];
 
     if (!model) {
       return [];
     }
 
-    const results: ArrayElementType<Structure['subModels'][K]>[] = [];
+    const results: ArrayElementType<NonNullable<Structure['subModels']>[K]>[] = [];
 
     _.castArray(model)
       .sort((a, b) => (a.sortIndex || 0) - (b.sortIndex || 0))
@@ -1201,9 +1276,9 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     return results;
   }
 
-  mapSubModels<K extends keyof Structure['subModels'], R>(
+  mapSubModels<K extends keyof NonNullable<Structure['subModels']>, R>(
     subKey: K,
-    callback: (model: ArrayElementType<Structure['subModels'][K]>, index: number) => R,
+    callback: (model: ArrayElementType<NonNullable<Structure['subModels']>[K]>, index: number) => R,
   ): R[] {
     const model = (this.subModels as any)[subKey as string];
 
@@ -1223,7 +1298,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     return results;
   }
 
-  hasSubModel<K extends keyof Structure['subModels']>(subKey: K) {
+  hasSubModel<K extends keyof NonNullable<Structure['subModels']>>(subKey: K) {
     const subModel = (this.subModels as any)[subKey as string];
     if (!subModel) {
       return false;
@@ -1231,10 +1306,10 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     return _.castArray(subModel).length > 0;
   }
 
-  findSubModel<K extends keyof Structure['subModels'], R>(
+  findSubModel<K extends keyof NonNullable<Structure['subModels']>, R>(
     subKey: K,
-    callback: (model: ArrayElementType<Structure['subModels'][K]>) => R,
-  ): ArrayElementType<Structure['subModels'][K]> | null {
+    callback: (model: ArrayElementType<NonNullable<Structure['subModels']>[K]>) => R,
+  ): ArrayElementType<NonNullable<Structure['subModels']>[K]> | null {
     const model = (this.subModels as any)[subKey as string];
 
     if (!model) {
@@ -1244,7 +1319,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     return (
       (_.castArray(model).find((item) => {
         return (callback as (model: any) => R)(item);
-      }) as ArrayElementType<Structure['subModels'][K]> | undefined) || null
+      }) as ArrayElementType<NonNullable<Structure['subModels']>[K]> | undefined) || null
     );
   }
 
@@ -1304,7 +1379,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
   }
 
   clearForks() {
-    console.log(`FlowModel ${this.uid} clearing all forks.`);
+    this.flowEngine.logger.debug(`FlowModel ${this.uid} clearing all forks.`);
     // 主动使所有 fork 失效
     if (this.forks?.size) {
       this.forks.forEach((fork) => fork.dispose());
@@ -1369,7 +1444,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
    * @param {string} stepKey 步骤的唯一标识符
    * @returns {void}
    */
-  openStepSettingsDialog(flowKey: string, stepKey: string) {
+  async openStepSettingsDialog(flowKey: string, stepKey: string) {
     // 创建流程运行时上下文
     const flow = this.getFlow(flowKey);
     const step = flow?.steps?.[stepKey];
@@ -1383,7 +1458,9 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     setupRuntimeContextSteps(ctx, flow.steps, this, flowKey);
     ctx.defineProperty('currentStep', { value: step });
 
-    return openStepSettingsDialogFn({
+    const openStepSettingsDialog = await loadOpenStepSettingsDialog();
+
+    return openStepSettingsDialog({
       model: this,
       flowKey,
       stepKey,
@@ -1399,7 +1476,9 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
    * @returns {Promise<any>} 返回表单提交的值
    */
   async configureRequiredSteps(dialogWidth?: number | string, dialogTitle?: string) {
-    return openRequiredParamsStepFormDialogFn({
+    const openRequiredParamsStepFormDialog = await loadOpenRequiredParamsStepFormDialog();
+
+    return openRequiredParamsStepFormDialog({
       model: this,
       dialogWidth,
       dialogTitle,
@@ -1432,6 +1511,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     const data = {
       uid: this.uid,
       ..._.omit(this._options, ['flowEngine']),
+      props: { ...this.props },
       stepParams: this.stepParams,
       sortIndex: this.sortIndex,
       flowRegistry: {},
@@ -1586,6 +1666,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
       seen.add(Cls);
       const reg = classMenuExtensions.get(Cls);
       if (reg) {
+        let entryIndex = 0;
         for (const entry of reg) {
           if (entry.matcher && !entry.matcher(model)) continue;
           const items =
@@ -1593,16 +1674,21 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
           const group = entry.group || 'common-actions';
           const sort = entry.sort ?? 0;
           const prefix = entry.keyPrefix || Cls.name || 'extra';
-          (items || []).forEach((it, idx: number) => {
-            if (!it) return;
-            const key = it.key ?? `${prefix}-${group}-${idx}-${Math.random().toString(36).slice(2, 6)}`;
-            collected.push({
-              ...it,
-              key,
-              group: it.group || group,
-              sort: typeof it.sort === 'number' ? it.sort : sort,
-            });
+          sortExtraMenuItems(
+            (items || [])
+              .map((it, idx: number) =>
+                normalizeExtraMenuItem(it, {
+                  group,
+                  sort,
+                  prefix,
+                  path: `${entryIndex}-${idx}`,
+                }),
+              )
+              .filter(isFlowModelExtraMenuItem),
+          ).forEach((it) => {
+            collected.push(it);
           });
+          entryIndex += 1;
         }
       }
       const ParentClass = Object.getPrototypeOf(Cls) as typeof FlowModel;

package/src/provider.tsx

@@ -45,34 +45,50 @@ export const FlowEngineGlobalsContextProvider: React.FC<{ children: React.ReactN
   const engine = useFlowEngine();
   const config = useContext(ConfigProvider.ConfigContext);
   const { token } = theme.useToken();
+  const isDarkTheme = React.useMemo(() => {
+    const algorithm = config?.theme?.algorithm;
+    if (Array.isArray(algorithm)) {
+      return algorithm.includes(theme.darkAlgorithm);
+    }
+    return algorithm === theme.darkAlgorithm;
+  }, [config]);
 
-  useEffect(() => {
-    const context = {
-      antdConfig: config,
-      // themeToken 改为可观察的 getter，在下方单独 define
-      modal,
-      message,
-      notification,
-    };
-    engine.context.defineProperty('viewer', {
-      cache: false,
-      get: (ctx) => new FlowViewer(ctx, { drawer, embed, popover, dialog }),
-    });
-    for (const item of Object.entries(context)) {
-      const [key, value] = item;
-      if (value) {
-        engine.context.defineProperty(key, { value });
-      }
+  // 这些全局能力需要在 children 首次渲染前就可读，不能等到 effect 后再挂到上下文。
+  engine.context.defineProperty('viewer', {
+    cache: false,
+    get: (ctx) => new FlowViewer(ctx, { drawer, embed, popover, dialog }),
+  });
+  for (const item of Object.entries({
+    antdConfig: config,
+    modal,
+    message,
+    notification,
+  })) {
+    const [key, value] = item;
+    if (value) {
+      engine.context.defineProperty(key, { value });
     }
-    // 将 themeToken 定义为 observable, 使组件能够响应主题的变更
-    // NOTE: 必须在 antdConfig 写入后再更新 themeToken；否则会读取到旧 antdConfig 的值。
-    engine.context.defineProperty('themeToken', {
-      get: () => token,
-      observable: true,
-      cache: true,
-    });
+  }
+  // 将 themeToken 定义为 observable, 使组件能够响应主题的变更。
+  engine.context.defineProperty('themeToken', {
+    get: () => token,
+    observable: true,
+    cache: true,
+  });
+  // 统一把暗色模式暴露到 Flow 上下文，避免 flow 侧继续依赖 global-theme。
+  engine.context.defineProperty('isDarkTheme', {
+    get: () => isDarkTheme,
+    observable: true,
+    cache: true,
+    info: {
+      description: 'Whether current theme algorithm is dark mode.',
+      detail: 'boolean',
+    },
+  });
+
+  useEffect(() => {
     engine.reactView.refresh();
-  }, [engine, drawer, modal, message, notification, config, popover, token, dialog, embed]);
+  }, [engine, drawer, modal, message, notification, config, popover, token, dialog, embed, isDarkTheme]);
 
   return (
     <ConfigProvider {...config} locale={engine.context.locales?.antd} popupMatchSelectWidth={false}>