@nocobase/flow-engine 2.1.0-alpha.14 → 2.1.0-alpha.15

package/lib/data-source/index.js

@@ -461,6 +461,12 @@ const _Collection = class _Collection {
   }
   get titleCollectionField() {
     const titleFieldName = this.options.titleField || this.filterTargetKey;
+    if (Array.isArray(titleFieldName)) {
+      if (titleFieldName.length !== 1) {
+        return void 0;
+      }
+      return this.getField(titleFieldName[0]);
+    }
     const titleCollectionField = this.getField(titleFieldName);
     return titleCollectionField;
   }

package/lib/flowContext.js

@@ -57,6 +57,7 @@ __export(flowContext_exports, {
 });
 module.exports = __toCommonJS(flowContext_exports);
 var import_reactive = require("@formily/reactive");
+var import_axios = __toESM(require("axios"));
 var antd = __toESM(require("antd"));
 var import_lodash = __toESM(require("lodash"));
 var import_qs = __toESM(require("qs"));
@@ -81,6 +82,28 @@ var import_dayjs = __toESM(require("dayjs"));
 var import_runjsLibs = require("./runjsLibs");
 var import_runjsModuleLoader = require("./utils/runjsModuleLoader");
 var _proxy, _FlowContext_instances, createChildNodes_fn, findMetaByPath_fn, findMetaInDelegatesDeep_fn, findMetaInProperty_fn, resolvePathInMeta_fn, resolvePathInMetaAsync_fn, buildParentTitles_fn, toTreeNode_fn;
+function normalizePathname(pathname) {
+  return pathname.endsWith("/") ? pathname : `${pathname}/`;
+}
+__name(normalizePathname, "normalizePathname");
+function shouldBypassApiClient(url, app) {
+  try {
+    const requestUrl = new URL(url);
+    if (!["http:", "https:"].includes(requestUrl.protocol)) {
+      return false;
+    }
+    if (!(app == null ? void 0 : app.getApiUrl)) {
+      return true;
+    }
+    const apiUrl = new URL(app.getApiUrl());
+    const apiPath = normalizePathname(apiUrl.pathname);
+    const requestPath = normalizePathname(requestUrl.pathname);
+    return requestUrl.origin !== apiUrl.origin || !requestPath.startsWith(apiPath);
+  } catch {
+    return false;
+  }
+}
+__name(shouldBypassApiClient, "shouldBypassApiClient");
 function isRecordRefLike(val) {
   return !!(val && typeof val === "object" && "collection" in val && "filterByTk" in val);
 }
@@ -2211,6 +2234,10 @@ const _BaseFlowEngineContext = class _BaseFlowEngineContext extends FlowContext
       return this.engine.getModel(modelName, searchInPreviousEngines);
     });
     this.defineMethod("request", (options) => {
+      const app = this.app;
+      if (typeof (options == null ? void 0 : options.url) === "string" && shouldBypassApiClient(options.url, app)) {
+        return import_axios.default.request(options);
+      }
       return this.api.request(options);
     });
     this.defineMethod(

package/lib/flowEngine.d.ts

@@ -8,7 +8,7 @@ import { FlowResource } from './resources';
 import { Emitter } from './emitter';
 import ModelOperationScheduler from './scheduler/ModelOperationScheduler';
 import type { ScheduleOptions, ScheduledCancel } from './scheduler/ModelOperationScheduler';
-import type { ActionDefinition, ApplyFlowCacheEntry, CreateModelOptions, EnsureBatchResult, EventDefinition, FlowModelLoaderMap, FlowModelOptions, IFlowModelRepository, ModelConstructor, PersistOptions, ResourceType } from './types';
+import type { ActionDefinition, ApplyFlowCacheEntry, CreateModelOptions, EnsureBatchResult, EventDefinition, FlowModelLoaderInputMap, FlowModelOptions, IFlowModelRepository, ModelConstructor, PersistOptions, ResourceType } from './types';
 /**
  * FlowEngine is the core class of the flow engine, responsible for managing flow models, actions, model repository, and more.
  * It provides capabilities for registering, creating, finding, persisting, replacing, and moving models.
@@ -262,16 +262,19 @@ export declare class FlowEngine {
     registerModels(models: Record<string, ModelConstructor | typeof FlowModel<any>>): void;
     /**
      * Register multiple model loader entries.
-     * @param {FlowModelLoaderMap} loaders Model loader entry map, key is model name, value is the model loader entry
+     * The `extends` field declares parent class(es) for async subclass discovery via `getSubclassesOfAsync`.
+     * It accepts `string | ModelConstructor | (string | ModelConstructor)[]` and is normalized to `string[]` internally.
+     * @param {FlowModelLoaderInputMap} loaders Model loader input map
      * @returns {void}
      * @example
      * flowEngine.registerModelLoaders({
      *   DemoModel: {
+     *     extends: 'BaseModel',
      *     loader: () => import('./models/DemoModel'),
      *   },
      * });
      */
-    registerModelLoaders(loaders: FlowModelLoaderMap): void;
+    registerModelLoaders(loaders: FlowModelLoaderInputMap): void;
     /**
      * Get a registered model class (constructor) asynchronously.
      * This will first ensure the model loader entry is resolved.
@@ -381,6 +384,15 @@ export declare class FlowEngine {
      * @returns {Map<string, ModelConstructor>} Model classes inherited from base class and passed the filter
      */
     getSubclassesOf(baseClass: string | ModelConstructor, filter?: (ModelClass: ModelConstructor, className: string) => boolean): Map<string, ModelConstructor>;
+    /**
+     * Asynchronously get all subclasses of a base class, including those registered via model loaders.
+     * Merges results from already-loaded classes (_modelClasses) and async loader entries with matching `extends` declarations.
+     * Loader-resolved classes are validated with `isInheritedFrom`; mismatches are warned and excluded.
+     * @param {string | ModelConstructor} baseClass Base class name or constructor
+     * @param {(ModelClass: ModelConstructor, className: string) => boolean} [filter] Optional filter function
+     * @returns {Promise<Map<string, ModelConstructor>>} Model classes that are subclasses of the base class
+     */
+    getSubclassesOfAsync(baseClass: string | ModelConstructor, filter?: (ModelClass: ModelConstructor, className: string) => boolean): Promise<Map<string, ModelConstructor>>;
     /**
      * Create and register a model instance.
      * If an instance with the same UID exists, returns the existing instance.

package/lib/flowEngine.js

@@ -418,21 +418,31 @@ const _FlowEngine = class _FlowEngine {
   }
   /**
    * Register multiple model loader entries.
-   * @param {FlowModelLoaderMap} loaders Model loader entry map, key is model name, value is the model loader entry
+   * The `extends` field declares parent class(es) for async subclass discovery via `getSubclassesOfAsync`.
+   * It accepts `string | ModelConstructor | (string | ModelConstructor)[]` and is normalized to `string[]` internally.
+   * @param {FlowModelLoaderInputMap} loaders Model loader input map
    * @returns {void}
    * @example
    * flowEngine.registerModelLoaders({
    *   DemoModel: {
+   *     extends: 'BaseModel',
    *     loader: () => import('./models/DemoModel'),
    *   },
    * });
    */
   registerModelLoaders(loaders) {
     let changed = false;
-    for (const [name, entry] of Object.entries(loaders)) {
+    for (const [name, input] of Object.entries(loaders)) {
       if (this._modelLoaders.has(name)) {
         console.warn(`FlowEngine: Model loader with name '${name}' is already registered and will be overwritten.`);
       }
+      const entry = {
+        loader: input.loader
+      };
+      if (input.extends != null) {
+        const raw = Array.isArray(input.extends) ? input.extends : [input.extends];
+        entry.extends = raw.map((item) => typeof item === "string" ? item : item.name);
+      }
       this._modelLoaders.set(name, entry);
       changed = true;
     }
@@ -737,6 +747,55 @@ const _FlowEngine = class _FlowEngine {
     }
     return result;
   }
+  /**
+   * Asynchronously get all subclasses of a base class, including those registered via model loaders.
+   * Merges results from already-loaded classes (_modelClasses) and async loader entries with matching `extends` declarations.
+   * Loader-resolved classes are validated with `isInheritedFrom`; mismatches are warned and excluded.
+   * @param {string | ModelConstructor} baseClass Base class name or constructor
+   * @param {(ModelClass: ModelConstructor, className: string) => boolean} [filter] Optional filter function
+   * @returns {Promise<Map<string, ModelConstructor>>} Model classes that are subclasses of the base class
+   */
+  async getSubclassesOfAsync(baseClass, filter) {
+    var _a;
+    const baseClassName = typeof baseClass === "string" ? baseClass : baseClass.name;
+    let parentModelClass;
+    if (typeof baseClass === "string") {
+      if (!this.getModelClass(baseClass)) {
+        await this.ensureModel(baseClass);
+      }
+      parentModelClass = this.getModelClass(baseClass);
+    } else {
+      parentModelClass = baseClass;
+    }
+    if (!parentModelClass) {
+      return /* @__PURE__ */ new Map();
+    }
+    const result = this.getSubclassesOf(parentModelClass, filter);
+    const loaderCandidates = [];
+    for (const [name, entry] of this._modelLoaders) {
+      if (result.has(name) || this._modelClasses.has(name)) continue;
+      if ((_a = entry.extends) == null ? void 0 : _a.includes(baseClassName)) {
+        loaderCandidates.push(name);
+      }
+    }
+    if (loaderCandidates.length > 0) {
+      await this.ensureModels(loaderCandidates);
+    }
+    for (const name of loaderCandidates) {
+      const ModelClass = this._modelClasses.get(name);
+      if (!ModelClass) continue;
+      if (!(0, import_utils.isInheritedFrom)(ModelClass, parentModelClass)) {
+        console.warn(
+          `FlowEngine: Model '${name}' declares extends '${baseClassName}' but does not actually inherit from it. Skipping.`
+        );
+        continue;
+      }
+      if (!filter || filter(ModelClass, name)) {
+        result.set(name, ModelClass);
+      }
+    }
+    return result;
+  }
   /**
    * Create and register a model instance.
    * If an instance with the same UID exists, returns the existing instance.

package/lib/locale/en-US.json

@@ -34,6 +34,7 @@
   "Failed to destroy model after creation error": "Failed to destroy model after creation error",
   "Failed to get action {{action}}": "Failed to get action {{action}}",
   "Failed to get configurable flows for model {{model}}": "Failed to get configurable flows for model {{model}}",
+  "Attributes are unavailable before selecting a record": "Attributes are unavailable before selecting a record",
   "Failed to import FormDialog": "Failed to import FormDialog",
   "Failed to import FormDialog or FormStep": "Failed to import FormDialog or FormStep",
   "Failed to import Formily components": "Failed to import Formily components",

package/lib/locale/index.d.ts

@@ -43,6 +43,7 @@ export declare const locales: {
         "Failed to destroy model after creation error": string;
         "Failed to get action {{action}}": string;
         "Failed to get configurable flows for model {{model}}": string;
+        "Attributes are unavailable before selecting a record": string;
         "Failed to import FormDialog": string;
         "Failed to import FormDialog or FormStep": string;
         "Failed to import Formily components": string;
@@ -120,6 +121,7 @@ export declare const locales: {
         "Failed to destroy model after creation error": string;
         "Failed to get action {{action}}": string;
         "Failed to get configurable flows for model {{model}}": string;
+        "Attributes are unavailable before selecting a record": string;
         "Failed to import FormDialog": string;
         "Failed to import FormDialog or FormStep": string;
         "Failed to import Formily components": string;

package/lib/locale/zh-CN.json

@@ -31,6 +31,7 @@
   "Failed to destroy model after creation error": "创建错误后销毁模型失败",
   "Failed to get action {{action}}": "获取 action '{{action}}' 失败",
   "Failed to get configurable flows for model {{model}}": "获取模型 '{{model}}' 的可配置 flows 失败",
+  "Attributes are unavailable before selecting a record": "选择记录之前，当前项属性不可用",
   "Failed to import FormDialog": "导入 FormDialog 失败",
   "Failed to import FormDialog or FormStep": "导入 FormDialog 或 FormStep 失败",
   "Failed to import Formily components": "导入 Formily 组件失败",

package/lib/reactive/observer.js

@@ -51,8 +51,31 @@ const observer = /* @__PURE__ */ __name((Component, options) => {
     const ctxRef = (0, import_react.useRef)(ctx);
     ctxRef.current = ctx;
     const pendingDisposerRef = (0, import_react.useRef)(null);
+    const pendingTimerRef = (0, import_react.useRef)(null);
+    const clearPendingDisposer = /* @__PURE__ */ __name(() => {
+      if (pendingDisposerRef.current) {
+        pendingDisposerRef.current();
+        pendingDisposerRef.current = null;
+      }
+    }, "clearPendingDisposer");
+    const clearPendingTimer = /* @__PURE__ */ __name(() => {
+      if (pendingTimerRef.current) {
+        clearTimeout(pendingTimerRef.current);
+        pendingTimerRef.current = null;
+      }
+    }, "clearPendingTimer");
+    const isContextActive = /* @__PURE__ */ __name(() => {
+      var _a, _b;
+      const pageActive = getPageActive(ctxRef.current);
+      const tabActive = (_b = (_a = ctxRef.current) == null ? void 0 : _a.tabActive) == null ? void 0 : _b.value;
+      return pageActive !== false && tabActive !== false;
+    }, "isContextActive");
     (0, import_react.useEffect)(() => {
       return () => {
+        if (pendingTimerRef.current) {
+          clearTimeout(pendingTimerRef.current);
+          pendingTimerRef.current = null;
+        }
         if (pendingDisposerRef.current) {
           pendingDisposerRef.current();
           pendingDisposerRef.current = null;
@@ -62,30 +85,37 @@ const observer = /* @__PURE__ */ __name((Component, options) => {
     const ObservedComponent = (0, import_react.useMemo)(
       () => (0, import_reactive_react.observer)(Component, {
         scheduler(updater) {
-          var _a, _b;
-          const pageActive = getPageActive(ctxRef.current);
-          const tabActive = (_b = (_a = ctxRef.current) == null ? void 0 : _a.tabActive) == null ? void 0 : _b.value;
-          if (pageActive === false || tabActive === false) {
-            setTimeout(() => {
+          if (!isContextActive()) {
+            if (pendingTimerRef.current || pendingDisposerRef.current) {
+              return;
+            }
+            pendingTimerRef.current = setTimeout(() => {
+              pendingTimerRef.current = null;
               if (pendingDisposerRef.current) {
                 return;
               }
-              const disposer = (0, import_reactive.autorun)(() => {
-                var _a2, _b2, _c, _d, _e, _f;
-                if (((_b2 = (_a2 = ctxRef.current) == null ? void 0 : _a2.pageActive) == null ? void 0 : _b2.value) && (((_d = (_c = ctxRef.current) == null ? void 0 : _c.tabActive) == null ? void 0 : _d.value) === true || ((_f = (_e = ctxRef.current) == null ? void 0 : _e.tabActive) == null ? void 0 : _f.value) === void 0)) {
+              if (isContextActive()) {
+                updater();
+                return;
+              }
+              pendingDisposerRef.current = (0, import_reactive.reaction)(
+                () => isContextActive(),
+                (active) => {
+                  if (!active) {
+                    return;
+                  }
+                  clearPendingDisposer();
                   updater();
-                  disposer == null ? void 0 : disposer();
-                  pendingDisposerRef.current = null;
+                },
+                {
+                  name: "FlowObserverPendingUpdate"
                 }
-              });
-              pendingDisposerRef.current = disposer;
+              );
             });
             return;
           }
-          if (pendingDisposerRef.current) {
-            pendingDisposerRef.current();
-            pendingDisposerRef.current = null;
-          }
+          clearPendingTimer();
+          clearPendingDisposer();
           updater();
         },
         ...options

package/lib/types.d.ts

@@ -316,17 +316,28 @@ export type FlowModelLoaderResult = ModelConstructor | {
  */
 export type FlowModelLoader = () => Promise<FlowModelLoaderResult>;
 /**
- * FlowModel loader entry.
- * Future contribution-style fields are intentionally kept as commented placeholders in phase A
- * and are not consumed by current runtime logic.
+ * FlowModel loader entry (normalized internal form).
  */
 export interface FlowModelLoaderEntry {
     loader: FlowModelLoader;
+    extends?: string[];
 }
 /**
- * FlowModel loader entry map.
+ * FlowModel loader input (user-facing form for registerModelLoaders).
+ * The `extends` field accepts flexible formats that will be normalized to `string[]` at registration time.
+ */
+export interface FlowModelLoaderInput {
+    loader: FlowModelLoader;
+    extends?: string | ModelConstructor | (string | ModelConstructor)[];
+}
+/**
+ * FlowModel loader entry map (normalized internal form).
  */
 export type FlowModelLoaderMap = Record<string, FlowModelLoaderEntry>;
+/**
+ * FlowModel loader input map (user-facing form for registerModelLoaders).
+ */
+export type FlowModelLoaderInputMap = Record<string, FlowModelLoaderInput>;
 /**
  * Batch ensure result.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.1.0-alpha.14",
+  "version": "2.1.0-alpha.15",
   "private": false,
   "description": "A standalone flow engine for NocoBase, managing workflows, models, and actions.",
   "main": "lib/index.js",
@@ -8,9 +8,10 @@
   "dependencies": {
     "@formily/antd-v5": "1.x",
     "@formily/reactive": "2.x",
-    "@nocobase/sdk": "2.1.0-alpha.14",
-    "@nocobase/shared": "2.1.0-alpha.14",
+    "@nocobase/sdk": "2.1.0-alpha.15",
+    "@nocobase/shared": "2.1.0-alpha.15",
     "ahooks": "^3.7.2",
+    "axios": "^1.7.0",
     "dayjs": "^1.11.9",
     "dompurify": "^3.0.2",
     "lodash": "^4.x",
@@ -36,5 +37,5 @@
   ],
   "author": "NocoBase Team",
   "license": "Apache-2.0",
-  "gitHead": "d8735b541de0ff9557bba704de49c799b4962672"
+  "gitHead": "7c86e75b0af4b9f532c8ebf5ef96a7423b0ab60e"
 }

package/src/__tests__/flow-engine.test.ts

@@ -189,4 +189,170 @@ describe('FlowEngine', () => {
       expect(mounted?.uid).toBe('c3');
     });
   });
+
+  describe('getSubclassesOfAsync', () => {
+    it('should return async-loaded subclasses matching extends declaration', async () => {
+      class AsyncSubModelD extends BaseModel {}
+      class AsyncSubModelE extends BaseModel {}
+
+      engine.registerModelLoaders({
+        AsyncSubModelD: {
+          extends: 'BaseModel',
+          loader: async () => ({ AsyncSubModelD }),
+        },
+        AsyncSubModelE: {
+          extends: 'BaseModel',
+          loader: async () => ({ AsyncSubModelE }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+
+      // Sync-registered subclasses
+      expect(result.has('SubModelA')).toBe(true);
+      expect(result.has('SubModelB')).toBe(true);
+      expect(result.has('SubModelC')).toBe(true);
+      // Async-loaded subclasses
+      expect(result.has('AsyncSubModelD')).toBe(true);
+      expect(result.has('AsyncSubModelE')).toBe(true);
+      // Base class excluded
+      expect(result.has('BaseModel')).toBe(false);
+    });
+
+    it('should merge sync-registered and async-loaded subclasses', async () => {
+      class AsyncSubModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        AsyncSubModel: {
+          extends: 'BaseModel',
+          loader: async () => ({ AsyncSubModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync('BaseModel');
+
+      // Sync: SubModelA, SubModelB, SubModelC
+      expect(result.has('SubModelA')).toBe(true);
+      expect(result.has('SubModelB')).toBe(true);
+      expect(result.has('SubModelC')).toBe(true);
+      // Async
+      expect(result.has('AsyncSubModel')).toBe(true);
+      expect(result.size).toBe(4);
+    });
+
+    it('should support extends as string array (multiple parents)', async () => {
+      class AnotherBase extends FlowModel {}
+      class MultiParentModel extends BaseModel {}
+
+      engine.registerModels({ AnotherBase });
+      engine.registerModelLoaders({
+        MultiParentModel: {
+          extends: ['BaseModel', 'AnotherBase'],
+          loader: async () => ({ MultiParentModel }),
+        },
+      });
+
+      const resultBase = await engine.getSubclassesOfAsync(BaseModel);
+      expect(resultBase.has('MultiParentModel')).toBe(true);
+
+      // Also found by AnotherBase (even though actual inheritance is from BaseModel, not AnotherBase)
+      // The extends declaration triggers loading, but isInheritedFrom validation will exclude it from AnotherBase results
+      const resultAnother = await engine.getSubclassesOfAsync(AnotherBase);
+      expect(resultAnother.has('MultiParentModel')).toBe(false);
+    });
+
+    it('should support extends as ModelConstructor', async () => {
+      class AsyncCtorSubModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        AsyncCtorSubModel: {
+          extends: BaseModel,
+          loader: async () => ({ AsyncCtorSubModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+      expect(result.has('AsyncCtorSubModel')).toBe(true);
+    });
+
+    it('should validate actual inheritance and warn on mismatch', async () => {
+      class UnrelatedModel extends FlowModel {}
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      engine.registerModelLoaders({
+        UnrelatedModel: {
+          extends: 'BaseModel',
+          loader: async () => ({ UnrelatedModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+      expect(result.has('UnrelatedModel')).toBe(false);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("declares extends 'BaseModel' but does not actually inherit from it"),
+      );
+
+      warnSpy.mockRestore();
+    });
+
+    it('should resolve base class from loaders if not in _modelClasses', async () => {
+      const freshEngine = new FlowEngine();
+
+      class LazyBase extends FlowModel {}
+      class LazySub extends LazyBase {}
+
+      freshEngine.registerModelLoaders({
+        LazyBase: {
+          loader: async () => ({ LazyBase }),
+        },
+        LazySub: {
+          extends: 'LazyBase',
+          loader: async () => ({ LazySub }),
+        },
+      });
+
+      const result = await freshEngine.getSubclassesOfAsync('LazyBase');
+      expect(result.has('LazySub')).toBe(true);
+      expect(result.size).toBe(1);
+    });
+
+    it('should return empty Map when base class cannot be found', async () => {
+      const result = await engine.getSubclassesOfAsync('NonExistentModel');
+      expect(result.size).toBe(0);
+    });
+
+    it('should support filter parameter on both sync and async sources', async () => {
+      class FilteredAsyncModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        FilteredAsyncModel: {
+          extends: 'BaseModel',
+          loader: async () => ({ FilteredAsyncModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel, (_ModelClass, name) => name.startsWith('SubModelA'));
+
+      // Only SubModelA passes the filter (SubModelB, SubModelC, FilteredAsyncModel excluded)
+      expect(result.has('SubModelA')).toBe(true);
+      expect(result.has('SubModelB')).toBe(false);
+      expect(result.has('SubModelC')).toBe(false);
+      expect(result.has('FilteredAsyncModel')).toBe(false);
+    });
+
+    it('should not include loaders without extends declaration', async () => {
+      class NoExtendsModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        NoExtendsModel: {
+          loader: async () => ({ NoExtendsModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+      // Only sync-registered subclasses; NoExtendsModel has no extends, so not discovered
+      expect(result.has('NoExtendsModel')).toBe(false);
+      expect(result.has('SubModelA')).toBe(true);
+    });
+  });
 });

package/src/__tests__/flowContext.test.ts

@@ -7,7 +7,8 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, expect, it, vi } from 'vitest';
+import axios from 'axios';
+import { describe, expect, it, vi, afterEach } from 'vitest';
 import { FlowContext, FlowRuntimeContext, FlowRunJSContext, type PropertyMetaFactory } from '../flowContext';
 import { FlowEngine } from '../flowEngine';
 import { FlowModel } from '../models/flowModel';
@@ -1630,6 +1631,69 @@ describe('runAction delegation from runtime context', () => {
   });
 });
 
+describe('FlowContext request defaults', () => {
+  class RequestModel extends FlowModel {}
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const createRequestContext = () => {
+    const engine = new FlowEngine();
+    engine.registerModels({ RequestModel });
+
+    const apiRequest = vi.fn(async (options) => options);
+    const app = {
+      getApiUrl(pathname = '') {
+        return 'https://app.example.com/api/'.replace(/\/$/g, '') + '/' + pathname.replace(/^\//g, '');
+      },
+    };
+
+    engine.context.defineProperty('api', { value: { request: apiRequest } as any });
+    engine.context.defineProperty('app', { value: app });
+
+    const model = engine.createModel({ use: 'RequestModel' });
+    const ctx = new FlowRuntimeContext(model, 'flow');
+    const directAxiosRequest = vi.spyOn(axios, 'request').mockResolvedValue({ data: {} } as any);
+
+    return { ctx, apiRequest, directAxiosRequest };
+  };
+
+  it.each([
+    ['apiClient', 'users:list', 'api'],
+    ['apiClient', '/api/users:list', 'api'],
+    ['apiClient', 'https://app.example.com/api/users:list', 'api'],
+    ['direct axios', 'https://app.example.com/custom-api/users', 'axios'],
+  ])('should use %s for %s', async (_target, url, expected) => {
+    const { ctx, apiRequest, directAxiosRequest } = createRequestContext();
+
+    await ctx.request({ url, method: 'get' });
+
+    if (expected === 'api') {
+      expect(apiRequest).toHaveBeenCalledTimes(1);
+      expect(directAxiosRequest).not.toHaveBeenCalled();
+      return;
+    }
+
+    expect(directAxiosRequest).toHaveBeenCalledTimes(1);
+    expect(apiRequest).not.toHaveBeenCalled();
+  });
+
+  it('should use direct axios for cross-origin absolute urls', async () => {
+    const { ctx, apiRequest, directAxiosRequest } = createRequestContext();
+
+    await ctx.request({ url: 'https://api.example.com/users', method: 'get', skipAuth: false });
+
+    expect(directAxiosRequest).toHaveBeenCalledTimes(1);
+    expect(apiRequest).not.toHaveBeenCalled();
+    expect(directAxiosRequest.mock.calls[0][0]).toMatchObject({
+      url: 'https://api.example.com/users',
+      method: 'get',
+      skipAuth: false,
+    });
+  });
+});
+
 describe('FlowContext delayed meta loading', () => {
   // 测试场景：属性定义时 meta 为异步函数，首次访问时延迟加载
   // 输入：属性带有异步 meta 函数

package/src/data-source/index.ts

@@ -501,6 +501,12 @@ export class Collection {
 
   get titleCollectionField() {
     const titleFieldName = this.options.titleField || this.filterTargetKey;
+    if (Array.isArray(titleFieldName)) {
+      if (titleFieldName.length !== 1) {
+        return undefined;
+      }
+      return this.getField(titleFieldName[0]);
+    }
     const titleCollectionField = this.getField(titleFieldName);
     return titleCollectionField;
   }

package/src/flowContext.ts

@@ -11,6 +11,7 @@ import { ISchema } from '@formily/json-schema';
 import { observable } from '@formily/reactive';
 import { APIClient, RequestOptions } from '@nocobase/sdk';
 import type { Router } from '@remix-run/router';
+import axios from 'axios';
 import { MessageInstance } from 'antd/es/message/interface';
 import * as antd from 'antd';
 import type { HookAPI } from 'antd/es/modal/useModal';
@@ -58,6 +59,31 @@ import dayjs from 'dayjs';
 import { externalReactRender, setupRunJSLibs } from './runjsLibs';
 import { runjsImportAsync, runjsImportModule, runjsRequireAsync } from './utils/runjsModuleLoader';
 
+function normalizePathname(pathname: string) {
+  return pathname.endsWith('/') ? pathname : `${pathname}/`;
+}
+
+function shouldBypassApiClient(url: string, app?: { getApiUrl?: (pathname?: string) => string }) {
+  try {
+    const requestUrl = new URL(url);
+    if (!['http:', 'https:'].includes(requestUrl.protocol)) {
+      return false;
+    }
+
+    if (!app?.getApiUrl) {
+      return true;
+    }
+
+    const apiUrl = new URL(app.getApiUrl());
+    const apiPath = normalizePathname(apiUrl.pathname);
+    const requestPath = normalizePathname(requestUrl.pathname);
+
+    return requestUrl.origin !== apiUrl.origin || !requestPath.startsWith(apiPath);
+  } catch {
+    return false;
+  }
+}
+
 // Helper: detect a RecordRef-like object
 function isRecordRefLike(val: any): boolean {
   return !!(val && typeof val === 'object' && 'collection' in val && 'filterByTk' in val);
@@ -3024,6 +3050,10 @@ class BaseFlowEngineContext extends FlowContext {
       return this.engine.getModel(modelName, searchInPreviousEngines);
     });
     this.defineMethod('request', (options: RequestOptions) => {
+      const app = this.app as { getApiUrl?: (pathname?: string) => string } | undefined;
+      if (typeof options?.url === 'string' && shouldBypassApiClient(options.url, app)) {
+        return axios.request(options);
+      }
       return this.api.request(options);
     });
     this.defineMethod(

package/src/flowEngine.ts

@@ -27,7 +27,7 @@ import type {
   EnsureBatchResult,
   EventDefinition,
   FlowModelLoaderEntry,
-  FlowModelLoaderMap,
+  FlowModelLoaderInputMap,
   FlowModelLoaderResult,
   FlowModelOptions,
   IFlowModelRepository,
@@ -483,21 +483,31 @@ export class FlowEngine {
 
   /**
    * Register multiple model loader entries.
-   * @param {FlowModelLoaderMap} loaders Model loader entry map, key is model name, value is the model loader entry
+   * The `extends` field declares parent class(es) for async subclass discovery via `getSubclassesOfAsync`.
+   * It accepts `string | ModelConstructor | (string | ModelConstructor)[]` and is normalized to `string[]` internally.
+   * @param {FlowModelLoaderInputMap} loaders Model loader input map
    * @returns {void}
    * @example
    * flowEngine.registerModelLoaders({
    *   DemoModel: {
+   *     extends: 'BaseModel',
    *     loader: () => import('./models/DemoModel'),
    *   },
    * });
    */
-  public registerModelLoaders(loaders: FlowModelLoaderMap): void {
+  public registerModelLoaders(loaders: FlowModelLoaderInputMap): void {
     let changed = false;
-    for (const [name, entry] of Object.entries(loaders)) {
+    for (const [name, input] of Object.entries(loaders)) {
       if (this._modelLoaders.has(name)) {
         console.warn(`FlowEngine: Model loader with name '${name}' is already registered and will be overwritten.`);
       }
+      const entry: FlowModelLoaderEntry = {
+        loader: input.loader,
+      };
+      if (input.extends != null) {
+        const raw = Array.isArray(input.extends) ? input.extends : [input.extends];
+        entry.extends = raw.map((item) => (typeof item === 'string' ? item : item.name));
+      }
       this._modelLoaders.set(name, entry);
       changed = true;
     }
@@ -845,6 +855,70 @@ export class FlowEngine {
     return result;
   }
 
+  /**
+   * Asynchronously get all subclasses of a base class, including those registered via model loaders.
+   * Merges results from already-loaded classes (_modelClasses) and async loader entries with matching `extends` declarations.
+   * Loader-resolved classes are validated with `isInheritedFrom`; mismatches are warned and excluded.
+   * @param {string | ModelConstructor} baseClass Base class name or constructor
+   * @param {(ModelClass: ModelConstructor, className: string) => boolean} [filter] Optional filter function
+   * @returns {Promise<Map<string, ModelConstructor>>} Model classes that are subclasses of the base class
+   */
+  public async getSubclassesOfAsync(
+    baseClass: string | ModelConstructor,
+    filter?: (ModelClass: ModelConstructor, className: string) => boolean,
+  ): Promise<Map<string, ModelConstructor>> {
+    const baseClassName = typeof baseClass === 'string' ? baseClass : baseClass.name;
+
+    // If baseClass is a string and not yet loaded, try to resolve it first
+    let parentModelClass: ModelConstructor | undefined;
+    if (typeof baseClass === 'string') {
+      if (!this.getModelClass(baseClass)) {
+        await this.ensureModel(baseClass);
+      }
+      parentModelClass = this.getModelClass(baseClass);
+    } else {
+      parentModelClass = baseClass;
+    }
+
+    if (!parentModelClass) {
+      return new Map();
+    }
+
+    // Step 1: Collect already-loaded subclasses from _modelClasses
+    const result = this.getSubclassesOf(parentModelClass, filter);
+
+    // Step 2: Find unloaded loaders whose extends includes baseClassName
+    const loaderCandidates: string[] = [];
+    for (const [name, entry] of this._modelLoaders) {
+      if (result.has(name) || this._modelClasses.has(name)) continue;
+      if (entry.extends?.includes(baseClassName)) {
+        loaderCandidates.push(name);
+      }
+    }
+
+    // Step 3: Resolve all matching loaders
+    if (loaderCandidates.length > 0) {
+      await this.ensureModels(loaderCandidates);
+    }
+
+    // Step 4: Validate resolved classes and add to result
+    for (const name of loaderCandidates) {
+      const ModelClass = this._modelClasses.get(name);
+      if (!ModelClass) continue;
+      if (!isInheritedFrom(ModelClass, parentModelClass)) {
+        console.warn(
+          `FlowEngine: Model '${name}' declares extends '${baseClassName}' but does not actually inherit from it. Skipping.`,
+        );
+        continue;
+      }
+      if (!filter || filter(ModelClass, name)) {
+        result.set(name, ModelClass);
+      }
+    }
+
+    return result;
+  }
+
   /**
    * Create and register a model instance.
    * If an instance with the same UID exists, returns the existing instance.

package/src/locale/en-US.json

@@ -34,6 +34,7 @@
   "Failed to destroy model after creation error": "Failed to destroy model after creation error",
   "Failed to get action {{action}}": "Failed to get action {{action}}",
   "Failed to get configurable flows for model {{model}}": "Failed to get configurable flows for model {{model}}",
+  "Attributes are unavailable before selecting a record": "Attributes are unavailable before selecting a record",
   "Failed to import FormDialog": "Failed to import FormDialog",
   "Failed to import FormDialog or FormStep": "Failed to import FormDialog or FormStep",
   "Failed to import Formily components": "Failed to import Formily components",

package/src/locale/zh-CN.json

@@ -31,6 +31,7 @@
   "Failed to destroy model after creation error": "创建错误后销毁模型失败",
   "Failed to get action {{action}}": "获取 action '{{action}}' 失败",
   "Failed to get configurable flows for model {{model}}": "获取模型 '{{model}}' 的可配置 flows 失败",
+  "Attributes are unavailable before selecting a record": "选择记录之前，当前项属性不可用",
   "Failed to import FormDialog": "导入 FormDialog 失败",
   "Failed to import FormDialog or FormStep": "导入 FormDialog 或 FormStep 失败",
   "Failed to import Formily components": "导入 Formily 组件失败",

package/src/reactive/__tests__/observer.test.tsx

@@ -208,4 +208,86 @@ describe('observer', () => {
     expect(screen.getByText('Count: 0')).toBeInTheDocument();
     expect(screen.queryByText('Count: 1')).not.toBeInTheDocument();
   });
+
+  it('should flush pending update without TDZ error when context becomes active before timer callback runs', async () => {
+    vi.useFakeTimers();
+
+    try {
+      const model = observable({ count: 0 });
+      const pageActive = observable.ref(false);
+      const tabActive = observable.ref(true);
+
+      const context = {
+        pageActive,
+        tabActive,
+      };
+
+      (useFlowContext as any).mockReturnValue(context);
+
+      const Component = observer(() => <div>Count: {model.count}</div>);
+
+      render(<Component />);
+
+      expect(screen.getByText('Count: 0')).toBeInTheDocument();
+
+      act(() => {
+        model.count++;
+        pageActive.value = true;
+      });
+
+      await act(async () => {
+        await vi.runAllTimersAsync();
+      });
+
+      expect(screen.getByText('Count: 1')).toBeInTheDocument();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('should cleanup pending timer and listener on unmount', async () => {
+    vi.useFakeTimers();
+
+    try {
+      const model = observable({ count: 0 });
+      const pageActive = observable.ref(false);
+      const tabActive = observable.ref(true);
+      const renderSpy = vi.fn();
+
+      const context = {
+        pageActive,
+        tabActive,
+      };
+
+      (useFlowContext as any).mockReturnValue(context);
+
+      const Component = observer(() => {
+        renderSpy(model.count);
+        return <div>Count: {model.count}</div>;
+      });
+
+      const { unmount } = render(<Component />);
+
+      expect(renderSpy).toHaveBeenCalledTimes(1);
+      expect(screen.getByText('Count: 0')).toBeInTheDocument();
+
+      act(() => {
+        model.count++;
+      });
+
+      unmount();
+
+      act(() => {
+        pageActive.value = true;
+      });
+
+      await act(async () => {
+        await vi.runAllTimersAsync();
+      });
+
+      expect(renderSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });

package/src/reactive/observer.tsx

@@ -10,7 +10,7 @@
 import { observer as originalObserver, IObserverOptions, ReactFC } from '@formily/reactive-react';
 import React, { useMemo, useEffect, useRef } from 'react';
 import { useFlowContext } from '../FlowContextProvider';
-import { autorun } from '@formily/reactive';
+import { reaction } from '@formily/reactive';
 import { FlowEngineContext } from '..';
 
 type ObserverComponentProps<P, Options extends IObserverOptions> = Options extends {
@@ -30,12 +30,67 @@ export const observer = <P, Options extends IObserverOptions = IObserverOptions>
     const ctxRef = useRef(ctx);
     ctxRef.current = ctx;
 
-    // Store the pending disposer to avoid creating multiple listeners
+    // 保存延迟更新的监听器，避免重复创建监听。
     const pendingDisposerRef = useRef<(() => void) | null>(null);
+    // 保存延迟创建监听器的定时器，避免组件卸载后仍继续调度。
+    const pendingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-    // Cleanup on unmount
+    /**
+     * 清理挂起的可见性监听器。
+     *
+     * @example
+     * ```typescript
+     * clearPendingDisposer();
+     * ```
+     */
+    const clearPendingDisposer = () => {
+      if (pendingDisposerRef.current) {
+        pendingDisposerRef.current();
+        pendingDisposerRef.current = null;
+      }
+    };
+
+    /**
+     * 清理挂起的定时器。
+     *
+     * @example
+     * ```typescript
+     * clearPendingTimer();
+     * ```
+     */
+    const clearPendingTimer = () => {
+      if (pendingTimerRef.current) {
+        clearTimeout(pendingTimerRef.current);
+        pendingTimerRef.current = null;
+      }
+    };
+
+    /**
+     * 判断当前页面与标签页是否允许立即更新。
+     *
+     * @returns 当前上下文是否处于可更新状态。
+     * @example
+     * ```typescript
+     * if (isContextActive()) {
+     *   updater();
+     * }
+     * ```
+     */
+    const isContextActive = () => {
+      const pageActive = getPageActive(ctxRef.current);
+      const tabActive = ctxRef.current?.tabActive?.value;
+
+      return pageActive !== false && tabActive !== false;
+    };
+
+    // 组件卸载时统一清理所有挂起任务，避免异步回调在卸载后继续运行。
     useEffect(() => {
       return () => {
+        if (pendingTimerRef.current) {
+          clearTimeout(pendingTimerRef.current);
+          pendingTimerRef.current = null;
+        }
+
         if (pendingDisposerRef.current) {
           pendingDisposerRef.current();
           pendingDisposerRef.current = null;
@@ -47,38 +102,45 @@ export const observer = <P, Options extends IObserverOptions = IObserverOptions>
       () =>
         originalObserver(Component, {
           scheduler(updater) {
-            const pageActive = getPageActive(ctxRef.current);
-            const tabActive = ctxRef.current?.tabActive?.value;
+            if (!isContextActive()) {
+              if (pendingTimerRef.current || pendingDisposerRef.current) {
+                return;
+              }
+
+              // 通过异步任务打断同步调度，避免连续触发时形成递归更新。
+              pendingTimerRef.current = setTimeout(() => {
+                pendingTimerRef.current = null;
 
-            if (pageActive === false || tabActive === false) {
-              // Avoid stack overflow
-              setTimeout(() => {
-                // If there is already a pending updater, do nothing
                 if (pendingDisposerRef.current) {
                   return;
                 }
 
-                // Delay the update until the page and tab become active
-                const disposer = autorun(() => {
-                  if (
-                    ctxRef.current?.pageActive?.value &&
-                    (ctxRef.current?.tabActive?.value === true || ctxRef.current?.tabActive?.value === undefined)
-                  ) {
+                if (isContextActive()) {
+                  updater();
+                  return;
+                }
+
+                // 只监听组合后的“是否可更新”状态，条件恢复后执行一次并立即销毁。
+                pendingDisposerRef.current = reaction(
+                  () => isContextActive(),
+                  (active) => {
+                    if (!active) {
+                      return;
+                    }
+
+                    clearPendingDisposer();
                     updater();
-                    disposer?.();
-                    pendingDisposerRef.current = null;
-                  }
-                });
-                pendingDisposerRef.current = disposer;
+                  },
+                  {
+                    name: 'FlowObserverPendingUpdate',
+                  },
+                );
               });
               return;
             }
 
-            // If we are updating immediately, clear any pending disposer
-            if (pendingDisposerRef.current) {
-              pendingDisposerRef.current();
-              pendingDisposerRef.current = null;
-            }
+            clearPendingTimer();
+            clearPendingDisposer();
 
             updater();
           },

package/src/types.ts

@@ -407,22 +407,34 @@ export type FlowModelLoaderResult =
 export type FlowModelLoader = () => Promise<FlowModelLoaderResult>;
 
 /**
- * FlowModel loader entry.
- * Future contribution-style fields are intentionally kept as commented placeholders in phase A
- * and are not consumed by current runtime logic.
+ * FlowModel loader entry (normalized internal form).
  */
 export interface FlowModelLoaderEntry {
   loader: FlowModelLoader;
-  // extends?: string;
+  extends?: string[];
   // meta?: Partial<FlowModelMeta>;
   // scenes?: string[];
 }
 
 /**
- * FlowModel loader entry map.
+ * FlowModel loader input (user-facing form for registerModelLoaders).
+ * The `extends` field accepts flexible formats that will be normalized to `string[]` at registration time.
+ */
+export interface FlowModelLoaderInput {
+  loader: FlowModelLoader;
+  extends?: string | ModelConstructor | (string | ModelConstructor)[];
+}
+
+/**
+ * FlowModel loader entry map (normalized internal form).
  */
 export type FlowModelLoaderMap = Record<string, FlowModelLoaderEntry>;
 
+/**
+ * FlowModel loader input map (user-facing form for registerModelLoaders).
+ */
+export type FlowModelLoaderInputMap = Record<string, FlowModelLoaderInput>;
+
 /**
  * Batch ensure result.
  */