@nocobase/flow-engine 2.0.0-alpha.7 → 2.0.0-alpha.71

package/src/flowContext.ts

@@ -11,14 +11,16 @@ import { ISchema } from '@formily/json-schema';
 import { observable } from '@formily/reactive';
 import { APIClient } from '@nocobase/sdk';
 import type { Router } from '@remix-run/router';
-import * as antd from 'antd';
 import { MessageInstance } from 'antd/es/message/interface';
+import * as antd from 'antd';
 import type { HookAPI } from 'antd/es/modal/useModal';
 import { NotificationInstance } from 'antd/es/notification/interface';
 import _ from 'lodash';
 import pino from 'pino';
 import qs from 'qs';
 import React, { createRef } from 'react';
+import * as ReactDOMClient from 'react-dom/client';
+import { ElementProxy } from './ElementProxy';
 import type { Location } from 'react-router-dom';
 import { ACL } from './acl/Acl';
 import { ContextPathProxy } from './ContextPathProxy';
@@ -26,33 +28,32 @@ import { DataSource, DataSourceManager } from './data-source';
 import { FlowEngine } from './flowEngine';
 import { FlowI18n } from './flowI18n';
 import { JSRunner, JSRunnerOptions } from './JSRunner';
-import { createJSRunnerWithVersion } from './runjs-context';
-import { FlowModel, ForkFlowModel } from './models';
-import {
-  APIResource,
-  BaseRecordResource,
-  FlowResource,
-  FlowSQLRepository,
-  MultiRecordResource,
-  SingleRecordResource,
-  SQLResource,
-} from './resources';
+import type { FlowModel } from './models/flowModel';
+import type { ForkFlowModel } from './models/forkFlowModel';
+import { FlowResource, FlowSQLRepository } from './resources';
 import type { ActionDefinition, EventDefinition, ResourceType } from './types';
 import {
-  createSafeDocument,
-  createSafeWindow,
   escapeT,
   extractPropertyPath,
   extractUsedVariablePaths,
   FlowExitException,
+  isCssFile,
+  prepareRunJsCode,
   resolveDefaultParams,
   resolveExpressions,
+  resolveModuleUrl,
 } from './utils';
 import { FlowExitAllException } from './utils/exceptions';
 import { enqueueVariablesResolve, JSONValue } from './utils/params-resolvers';
 import type { RecordRef } from './utils/serverContextParams';
 import { buildServerContextParams as _buildServerContextParams } from './utils/serverContextParams';
+import { inferRecordRef } from './utils/variablesParams';
 import { FlowView, FlowViewer } from './views/FlowView';
+import { RunJSContextRegistry, getModelClassName } from './runjs-context/registry';
+import { createEphemeralContext } from './utils/createEphemeralContext';
+import dayjs from 'dayjs';
+import { externalReactRender, setupRunJSLibs } from './runjsLibs';
+import { runjsImportAsync, runjsImportModule, runjsRequireAsync } from './utils/runjsModuleLoader';
 
 // Helper: detect a RecordRef-like object
 function isRecordRefLike(val: any): boolean {
@@ -75,6 +76,61 @@ function filterBuilderOutputByPaths(built: any, neededPaths: string[]): any {
   return undefined;
 }
 
+// Helper: extract top-level segment of a subpath (e.g. 'a.b' -> 'a', 'tags[0].name' -> 'tags')
+function topLevelOf(subPath: string): string | undefined {
+  if (!subPath) return undefined;
+  const m = String(subPath).match(/^([^.[]+)/);
+  return m?.[1];
+}
+
+// Helper: infer selects (fields/appends) from usage paths (mirrors server-side inferSelectsFromUsage)
+function inferSelectsFromUsage(paths: string[] = []): { generatedAppends?: string[]; generatedFields?: string[] } {
+  if (!Array.isArray(paths) || paths.length === 0) {
+    return { generatedAppends: undefined, generatedFields: undefined };
+  }
+
+  const appendSet = new Set<string>();
+  const fieldSet = new Set<string>();
+
+  const normalizePath = (raw: string): string => {
+    if (!raw) return '';
+    let s = String(raw);
+    // remove numeric indexes like [0]
+    s = s.replace(/\[(?:\d+)\]/g, '');
+    // normalize string indexes like ["name"] / ['name'] into .name
+    s = s.replace(/\[(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)')\]/g, (_m, g1, g2) => `.${(g1 || g2) as string}`);
+    s = s.replace(/\.\.+/g, '.');
+    s = s.replace(/^\./, '').replace(/\.$/, '');
+    return s;
+  };
+
+  for (let path of paths) {
+    if (!path) continue;
+    // drop leading numeric index like [0].name
+    while (/^\[(\d+)\](\.|$)/.test(path)) {
+      path = path.replace(/^\[(\d+)\]\.?/, '');
+    }
+    const norm = normalizePath(path);
+    if (!norm) continue;
+    const segments = norm.split('.').filter(Boolean);
+    if (segments.length === 0) continue;
+
+    if (segments.length === 1) {
+      fieldSet.add(segments[0]);
+      continue;
+    }
+
+    for (let i = 0; i < segments.length - 1; i++) {
+      appendSet.add(segments.slice(0, i + 1).join('.'));
+    }
+    fieldSet.add(segments.join('.'));
+  }
+
+  const generatedAppends = appendSet.size ? Array.from(appendSet) : undefined;
+  const generatedFields = fieldSet.size ? Array.from(fieldSet) : undefined;
+  return { generatedAppends, generatedFields };
+}
+
 type Getter<T = any> = (ctx: FlowContext) => T | Promise<T>;
 
 export interface MetaTreeNode {
@@ -82,11 +138,14 @@ export interface MetaTreeNode {
   title: string;
   type: string;
   interface?: string;
+  options?: any;
   uiSchema?: ISchema;
   render?: (props: any) => JSX.Element;
   // display?: 'default' | 'flatten' | 'none'; // 显示模式：默认、平铺子菜单、完全隐藏, 用于简化meta树显示层级
   paths: string[];
   parentTitles?: string[]; // 父级标题数组，不包含自身title，第一层可省略
+  // 显示控制：当 hidden 为 true（或函数返回 true）时，不在变量选择器中展示该节点
+  hidden?: boolean | (() => boolean);
   // 变量禁用状态与原因（用于变量选择器 UI 展示）
   disabled?: boolean | (() => boolean);
   disabledReason?: string | (() => string | undefined);
@@ -97,6 +156,7 @@ export interface PropertyMeta {
   type: string;
   title: string;
   interface?: string;
+  options?: any;
   uiSchema?: ISchema; // TODO: 这个是不是压根没必要啊？
   render?: (props: any) => JSX.Element; // 自定义渲染函数
   // 用于 VariableInput 的排序：数值越大，显示越靠前；相同值保持稳定顺序
@@ -107,6 +167,8 @@ export interface PropertyMeta {
   disabled?: boolean | (() => boolean);
   // 禁用原因（用于 UI 小问号提示），可为函数
   disabledReason?: string | (() => string | undefined);
+  // 显示控制：当 hidden 为 true（或函数返回 true）时，不在变量选择器中展示该节点
+  hidden?: boolean | (() => boolean);
   // 变量解析参数构造器（用于 variables:resolve 的 contextParams，按属性名归位）。
   // 支持返回 RecordRef 或任意嵌套对象（将被 buildServerContextParams 扁平化，例如 { record: RecordRef } -> 'view.record'）。
   buildVariablesParams?: (
@@ -142,6 +204,10 @@ export interface PropertyOptions {
   // - boolean: true 表示整个顶层变量交给服务端；false 表示仅前端解析
   // - function: 根据子路径决定是否交给服务端（子路径示例：'record.roles[0].name'、'id'、''）
   resolveOnServer?: boolean | ((subPath: string) => boolean);
+  // 优化：当需要服务端解析但本属性在 buildVariablesParams 返回空时，是否跳过调用服务端。
+  // - 典型场景：formValues / currentObject 仅在“已选关联值”存在时才需要服务端；否则没有必要请求。
+  // - 默认 false：保持兼容，其他变量即使没有 contextParams 也可选择调用服务端。
+  serverOnlyWhenContextParams?: boolean;
 }
 
 type RouteOptions = {
@@ -658,12 +724,13 @@ export class FlowContext {
 
     let node: MetaTreeNode;
 
-    // 计算禁用状态与原因的帮助函数
-    const computeDisabledFromMeta = (m: PropertyMeta): { disabled: boolean; reason?: string } => {
-      if (!m) return { disabled: false };
+    // 计算禁用/隐藏状态与原因的帮助函数
+    const computeStateFromMeta = (m: PropertyMeta): { disabled: boolean; reason?: string; hidden: boolean } => {
+      if (!m) return { disabled: false, hidden: false };
       const disabledVal = typeof m.disabled === 'function' ? m.disabled() : m.disabled;
       const reason = typeof m.disabledReason === 'function' ? m.disabledReason() : m.disabledReason;
-      return { disabled: !!disabledVal, reason };
+      const hiddenVal = typeof m.hidden === 'function' ? m.hidden() : m.hidden;
+      return { disabled: !!disabledVal, reason, hidden: !!hiddenVal };
     };
 
     if (typeof metaOrFactory === 'function') {
@@ -674,18 +741,24 @@ export class FlowContext {
         title: metaOrFactory.title || initialTitle, // 初始使用 name 作为 title
         type: 'object', // 初始类型
         interface: undefined,
+        options: undefined,
         uiSchema: undefined,
         paths,
         parentTitles: parentTitles.length > 0 ? parentTitles : undefined,
         disabled: () => {
           const maybe = metaOrFactory();
           if (maybe && typeof maybe['then'] === 'function') return false;
-          return computeDisabledFromMeta(maybe as PropertyMeta).disabled;
+          return computeStateFromMeta(maybe as PropertyMeta).disabled;
         },
         disabledReason: () => {
           const maybe = metaOrFactory();
           if (maybe && typeof maybe['then'] === 'function') return undefined;
-          return computeDisabledFromMeta(maybe as PropertyMeta).reason;
+          return computeStateFromMeta(maybe as PropertyMeta).reason;
+        },
+        hidden: () => {
+          const maybe = metaOrFactory();
+          if (maybe && typeof maybe['then'] === 'function') return false;
+          return computeStateFromMeta(maybe as PropertyMeta).hidden;
         },
         // 注意：即便 hasChildren === false，也只是“没有子节点”的 UI 提示；
         // 节点自身依然通过 meta 工厂保持惰性特性（需要时可解析出 title/type 等）。
@@ -700,6 +773,7 @@ export class FlowContext {
                   node.title = finalTitle;
                   node.type = meta?.type;
                   node.interface = meta?.interface;
+                  node.options = meta?.options;
                   node.uiSchema = meta?.uiSchema;
                   // parentTitles 保持不变，因为它不包含自身 title
 
@@ -726,17 +800,19 @@ export class FlowContext {
     } else {
       // 同步 meta：直接创建节点
       const nodeTitle = metaOrFactory.title;
-      const { disabled, reason } = computeDisabledFromMeta(metaOrFactory);
+      const { disabled, reason, hidden } = computeStateFromMeta(metaOrFactory);
       node = {
         name,
         title: nodeTitle,
         type: metaOrFactory.type,
         interface: metaOrFactory.interface,
+        options: metaOrFactory.options,
         uiSchema: metaOrFactory.uiSchema,
         paths,
         parentTitles: parentTitles.length > 0 ? parentTitles : undefined,
         disabled,
         disabledReason: reason,
+        hidden,
         children: metaOrFactory.properties
           ? this.#createChildNodes(metaOrFactory.properties, paths, [...parentTitles, nodeTitle], metaOrFactory)
           : undefined,
@@ -890,33 +966,86 @@ export class FlowContext {
     }
     return this._findPropertyInDelegates(this._delegates, key);
   }
-}
 
-export class FlowRunjsContext extends FlowContext {
-  constructor(delegate: FlowContext) {
-    super();
-    this.addDelegate(delegate);
-    // Expose React and antd only within runjs context
-    // This keeps the scope minimal while enabling React/AntD rendering in scripts
-    this.defineProperty('React', { value: React });
-    this.defineProperty('antd', { value: antd });
-    this.defineMethod(
-      'dispatchModelEvent',
-      async (modelOrUid: FlowModel | string, eventName: string, inputArgs?: Record<string, any>) => {
-        let model: FlowModel | null = null;
-        if (typeof modelOrUid === 'string') {
-          model = await this.engine.loadModel({ uid: modelOrUid });
-        } else if (modelOrUid instanceof FlowModel) {
-          model = modelOrUid;
+  /**
+   * 获取当前上下文可用的顶层 API 信息（主要用于编辑器补全/工具）。
+   *
+   * 注意：
+   * - 目前返回值以“尽量可用”为目标，允许不完整。
+   * - 该方法不会展开变量 meta（变量结构应由 `getPropertyMetaTree()`/VariableInput 等机制负责）。
+   */
+  async getApiInfos(options: { version?: string } = {}): Promise<Record<string, any>> {
+    const version = (options as any)?.version || ('v1' as any);
+    const modelClass = getModelClassName(this as any);
+    const Ctor =
+      RunJSContextRegistry.resolve(version as any, modelClass) || RunJSContextRegistry.resolve(version as any, '*');
+    const locale = (this as any)?.api?.auth?.locale || (this as any)?.i18n?.language || (this as any)?.locale;
+
+    let doc: any = {};
+    try {
+      if ((Ctor as any)?.getDoc?.length) doc = (Ctor as any).getDoc(locale) || {};
+      else doc = (Ctor as any)?.getDoc?.() || {};
+    } catch (_) {
+      doc = {};
+    }
+
+    const isPrivateKey = (key: string) => typeof key === 'string' && key.startsWith('_');
+    const out: Record<string, any> = {};
+    const visited = new WeakSet<any>();
+
+    const walk = (ctx: any) => {
+      if (!ctx || visited.has(ctx)) return;
+      visited.add(ctx);
+
+      try {
+        for (const key of Object.keys(ctx._props || {})) {
+          if (isPrivateKey(key)) continue;
+          if (typeof out[key] === 'undefined') out[key] = { type: 'property' };
         }
-        if (model) {
-          model.context.addDelegate(this);
-          model.dispatchEvent(eventName, { navigation: false, ...this.model?.['getInputArgs']?.(), ...inputArgs });
-        } else {
-          this.message.error(this.t('Model with ID {{uid}} not found', { uid: modelOrUid }));
+      } catch (_) {
+        // ignore
+      }
+
+      try {
+        for (const key of Object.keys(ctx._methods || {})) {
+          if (isPrivateKey(key)) continue;
+          if (typeof out[key] === 'undefined') out[key] = { type: 'function' };
         }
-      },
-    );
+      } catch (_) {
+        // ignore
+      }
+
+      try {
+        const delegates = Array.isArray(ctx._delegates) ? ctx._delegates : [];
+        for (const d of delegates) walk(d);
+      } catch (_) {
+        // ignore
+      }
+    };
+
+    walk(this);
+
+    return {
+      ...out,
+      ...(doc?.properties || {}),
+      ...(doc?.methods || {}),
+    };
+  }
+
+  /**
+   * 变量结构信息（保留给编辑器/工具使用）。
+   * 当前实现为保底空对象，避免 RunJS doc 中补全到该方法时调用报错。
+   */
+  async getVarInfos(_options: { path?: string | string[]; maxDepth?: number } = {}): Promise<Record<string, any>> {
+    return {};
+  }
+
+  /**
+   * 运行时环境信息（保留给编辑器/工具使用）。
+   * 当前实现为保底空对象，避免 RunJS doc 中补全到该方法时调用报错。
+   */
+  async getEnvInfos(): Promise<Record<string, any>> {
+    return {};
   }
 }
 
@@ -924,14 +1053,16 @@ class BaseFlowEngineContext extends FlowContext {
   declare router: Router;
   declare dataSourceManager: DataSourceManager;
   declare requireAsync: (url: string) => Promise<any>;
-  declare createJSRunner: (options?: JSRunnerOptions) => JSRunner;
+  declare importAsync: (url: string) => Promise<any>;
+  declare createJSRunner: (options?: JSRunnerOptions) => Promise<JSRunner>;
+  declare pageInfo: { version?: 'v1' | 'v2' };
   /**
    * @deprecated use `resolveJsonTemplate` instead
    */
   declare renderJson: (template: JSONValue) => Promise<any>;
   declare resolveJsonTemplate: (template: JSONValue) => Promise<any>;
+  declare getVar: (path: string) => Promise<any>;
   declare runjs: (code: string, variables?: Record<string, any>, options?: JSRunnerOptions) => Promise<any>;
-  declare copyToClipboard: (text: string) => Promise<void>;
   declare getAction: <TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>(
     name: string,
   ) => ActionDefinition<TModel, TCtx> | undefined;
@@ -955,6 +1086,25 @@ class BaseFlowEngineContext extends FlowContext {
   declare location: Location;
   declare sql: FlowSQLRepository;
   declare logger: pino.Logger;
+
+  constructor() {
+    super();
+    this.defineMethod(
+      'runjs',
+      async function (code: string, variables?: Record<string, any>, options?: JSRunnerOptions) {
+        const { preprocessTemplates, ...runnerOptions } = options || {};
+        const mergedGlobals = { ...(runnerOptions?.globals || {}), ...(variables || {}) };
+        const runner = await this.createJSRunner({
+          ...(runnerOptions || {}),
+          globals: mergedGlobals,
+        });
+        // Enable by default; use `preprocessTemplates: false` to explicitly disable.
+        const shouldPreprocessTemplates = preprocessTemplates !== false;
+        const jsCode = await prepareRunJsCode(String(code ?? ''), { preprocessTemplates: shouldPreprocessTemplates });
+        return runner.run(jsCode);
+      },
+    );
+  }
 }
 
 class BaseFlowModelContext extends BaseFlowEngineContext {
@@ -994,7 +1144,8 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       value: this.engine,
     });
     this.defineProperty('sql', {
-      get: () => new FlowSQLRepository(this),
+      get: (ctx) => new FlowSQLRepository(ctx),
+      cache: false,
     });
     this.defineProperty('dataSourceManager', {
       value: dataSourceManager,
@@ -1003,14 +1154,6 @@ export class FlowEngineContext extends BaseFlowEngineContext {
     this.defineMethod('t', (keyOrTemplate: string, options?: any) => {
       return i18n.translate(keyOrTemplate, options);
     });
-    this.defineMethod('runjs', async (code, variables, options?: JSRunnerOptions) => {
-      const mergedGlobals = { ...(options?.globals || {}), ...(variables || {}) };
-      const runner = this.createJSRunner({
-        ...(options || {}),
-        globals: mergedGlobals,
-      });
-      return runner.run(code);
-    });
     this.defineMethod('renderJson', function (template: any) {
       return this.resolveJsonTemplate(template);
     });
@@ -1046,6 +1189,22 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       const needServer = Object.keys(serverVarPaths).length > 0;
       let serverResolved = template;
       if (needServer) {
+        const inferRecordRefWithMeta = (ctx: any): RecordRef | undefined => {
+          const ref = inferRecordRef(ctx as any);
+          if (ref) return ref as RecordRef;
+          try {
+            const tk = ctx?.resource?.getMeta?.('currentFilterByTk');
+            if (typeof tk === 'undefined' || tk === null) return undefined;
+            const collection =
+              ctx?.collection?.name || ctx?.resource?.getResourceName?.()?.split?.('.')?.slice?.(-1)?.[0];
+            if (!collection) return undefined;
+            const dataSourceKey = ctx?.collection?.dataSourceKey || ctx?.resource?.getDataSourceKey?.();
+            return { collection, dataSourceKey, filterByTk: tk } as RecordRef;
+          } catch (_) {
+            return undefined;
+          }
+        };
+
         const collectFromMeta = async (): Promise<Record<string, any>> => {
           const out: Record<string, any> = {};
           try {
@@ -1085,11 +1244,77 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         };
 
         const inputFromMeta = await collectFromMeta();
-        const autoInput = { ...inputFromMeta };
+        const autoInput = { ...inputFromMeta } as Record<string, any>;
+
+        // Special-case: formValues
+        // If server needs to resolve some formValues paths but meta params only cover association anchors
+        // (e.g. formValues.customer) and some top-level paths are missing (e.g. formValues.status),
+        // inject a top-level record anchor (formValues -> { collection, filterByTk, fields/appends }) so server can fetch DB values.
+        // This anchor MUST be selective (fields/appends derived from serverVarPaths['formValues']) to avoid server overriding
+        // client-only values for configured form fields in the same template.
+        try {
+          const varName = 'formValues';
+          const neededPaths = serverVarPaths[varName] || [];
+          if (neededPaths.length) {
+            const requiredTop = new Set<string>();
+            for (const p of neededPaths) {
+              const top = topLevelOf(p);
+              if (top) requiredTop.add(top);
+            }
+            const metaOut = inputFromMeta?.[varName];
+            const builtTop = new Set<string>();
+            if (metaOut && typeof metaOut === 'object' && !Array.isArray(metaOut) && !isRecordRefLike(metaOut)) {
+              Object.keys(metaOut).forEach((k) => builtTop.add(k));
+            }
+
+            const missing = [...requiredTop].filter((k) => !builtTop.has(k));
+            if (missing.length) {
+              const ref = inferRecordRefWithMeta(this);
+              if (ref) {
+                const { generatedFields, generatedAppends } = inferSelectsFromUsage(neededPaths);
+                const recordRef: RecordRef = {
+                  ...ref,
+                  fields: generatedFields,
+                  appends: generatedAppends,
+                };
+
+                // Preserve existing association anchors by lifting them to dotted keys before overwriting formValues
+                const existing = autoInput[varName];
+                if (
+                  existing &&
+                  typeof existing === 'object' &&
+                  !Array.isArray(existing) &&
+                  !isRecordRefLike(existing)
+                ) {
+                  for (const [k, v] of Object.entries(existing)) {
+                    autoInput[`${varName}.${k}`] = v;
+                  }
+                  delete autoInput[varName];
+                }
+
+                autoInput[varName] = recordRef;
+              }
+            }
+          }
+        } catch (_) {
+          // ignore
+        }
+
         const autoContextParams = Object.keys(autoInput).length
           ? _buildServerContextParams(this, autoInput)
           : undefined;
 
+        // 优化：若所有需要服务端解析的变量都声明了 “仅当有 contextParams 时才请求服务端”，
+        // 且本次未能构建出任何 contextParams，则跳过服务端请求，回退到前端解析。
+        if (!autoContextParams) {
+          const keys = Object.keys(serverVarPaths);
+          const allOptional =
+            keys.length > 0 && keys.every((k) => this.getPropertyOptions(k)?.serverOnlyWhenContextParams);
+          if (allOptional) {
+            return resolveExpressions(template, this);
+          }
+        }
+
         if (this.api) {
           try {
             serverResolved = await enqueueVariablesResolve(this as FlowRuntimeContext<FlowModel>, {
@@ -1105,6 +1330,23 @@ export class FlowEngineContext extends BaseFlowEngineContext {
 
       return resolveExpressions(serverResolved, this);
     });
+
+    // Helper: resolve a single ctx expression value via resolveJsonTemplate behavior.
+    // Example: await ctx.getVar('ctx.record.id')
+    this.defineMethod(
+      'getVar',
+      async function (this: BaseFlowEngineContext, varPath: string) {
+        const raw = typeof varPath === 'string' ? varPath : String(varPath ?? '');
+        const s = raw.trim();
+        if (!s) return undefined;
+        // Preferred input: 'ctx.xxx.yyy' (expression), consistent with envs.getVar outputs.
+        if (s !== 'ctx' && !s.startsWith('ctx.')) {
+          throw new Error(`ctx.getVar(path) expects an expression starting with "ctx.", got: "${s}"`);
+        }
+        return this.resolveJsonTemplate(`{{ ${s} }}` as any);
+      },
+      'Resolve a ctx expression value by path (expression starts with "ctx.").',
+    );
     this.defineProperty('requirejs', {
       get: () => this.app?.requirejs?.requirejs,
     });
@@ -1186,7 +1428,8 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         user: this.user,
       }),
     });
-    this.defineMethod('loadCSS', async (url: string) => {
+    this.defineMethod('loadCSS', async (href: string) => {
+      const url = resolveModuleUrl(href);
       return new Promise((resolve, reject) => {
         // Check if CSS is already loaded
         const existingLink = document.querySelector(`link[href="${url}"]`);
@@ -1204,64 +1447,34 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       });
     });
     this.defineMethod('requireAsync', async (url: string) => {
-      return new Promise((resolve, reject) => {
-        if (!this.requirejs) {
-          reject(new Error('requirejs is not available'));
-          return;
-        }
-        this.requirejs(
-          [url],
-          (...args: any[]) => {
-            resolve(args[0]);
-          },
-          reject,
-        );
-      });
+      const u = resolveModuleUrl(url, { raw: true });
+      return await runjsRequireAsync(this.requirejs, u);
     });
-    this.defineMethod('createJSRunner', function (options?: JSRunnerOptions) {
-      // return createJSRunnerWithVersion.call(this, options as any);
-      const runCtx = new FlowRunjsContext(this.createProxy());
-      return new JSRunner({
-        ...options,
-        globals: {
-          ctx: runCtx,
-          window: createSafeWindow(),
-          document: createSafeDocument(),
-          ...options?.globals,
-        },
-      });
+    // 动态按 URL 加载 ESM 模块
+    // - 使用 Vite / Webpack ignore 注释，避免被预打包或重写
+    // - 返回模块命名空间对象（包含 default 与命名导出）
+    this.defineMethod('importAsync', async function (this: any, url: string) {
+      // 判断是否为 CSS 文件（支持 example.css?v=123 等形式）
+      if (isCssFile(url)) {
+        return this.loadCSS(url);
+      }
+
+      return await runjsImportModule(this, url, { importer: runjsImportAsync });
     });
-    // 复制文本到剪贴板（优先使用 Clipboard API，降级到 execCommand）
-    this.defineMethod('copyToClipboard', async (text: string) => {
-      const content = String(text ?? '');
+    this.defineMethod('createJSRunner', async function (options?: JSRunnerOptions) {
       try {
-        if (typeof navigator !== 'undefined' && navigator.clipboard && navigator.clipboard.writeText) {
-          await navigator.clipboard.writeText(content);
-          return;
-        }
-      } catch (e) {
-        // 忽略，尝试降级方案
+        const mod: any = await import('./runjs-context/setup');
+        if (typeof mod?.setupRunJSContexts === 'function') await mod.setupRunJSContexts();
+      } catch (_) {
+        // ignore if setup is not available
       }
-
-      // 降级方案：创建临时 textarea + execCommand('copy')
-      return new Promise<void>((resolve, reject) => {
-        try {
-          const ta = document.createElement('textarea');
-          ta.value = content;
-          ta.setAttribute('readonly', '');
-          ta.style.position = 'fixed';
-          ta.style.top = '-9999px';
-          document.body.appendChild(ta);
-          ta.focus();
-          ta.select();
-          const ok = document.execCommand('copy');
-          document.body.removeChild(ta);
-          if (ok) resolve();
-          else reject(new Error('execCommand copy failed'));
-        } catch (err) {
-          reject(err);
-        }
-      });
+      const version = options?.version || 'v1';
+      const modelClass = getModelClassName(this);
+      const Ctor: new (delegate: any) => any = RunJSContextRegistry.resolve(version, modelClass) || FlowRunJSContext;
+      const runCtx = new Ctor(this);
+      const globals: Record<string, any> = { ctx: runCtx, ...(options?.globals || {}) };
+      const { timeoutMs } = options || {};
+      return new JSRunner({ globals, timeoutMs });
     });
     // Helper: build server contextParams for variables:resolve
     this.defineMethod('buildServerContextParams', function (this: BaseFlowEngineContext, input?: any) {
@@ -1332,7 +1545,8 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       'runAction',
       async function (this: BaseFlowEngineContext, actionName: string, params?: Record<string, any>) {
         const def = this.engine.getAction<FlowModel, FlowEngineContext>(actionName);
-        const ctx = this.createProxy() as unknown as FlowEngineContext;
+        // 使用“临时作用域”上下文，避免将临时定义污染到引擎级上下文，并在创建时应用定义
+        const ctx = await createEphemeralContext(this as unknown as FlowEngineContext, def);
         if (!def) {
           throw new Error(`Action '${actionName}' not found.`);
         }
@@ -1346,7 +1560,7 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         }
         if (!useRawParams) {
           // 先服务端解析，再前端补齐
-          combinedParams = await (ctx as any).resolveJsonTemplate(combinedParams);
+          combinedParams = await ctx.resolveJsonTemplate(combinedParams);
         }
 
         if (!def.handler) {
@@ -1369,12 +1583,25 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         context: this.createProxy(),
       });
     });
+    // Provide useResource in base engine context so RunJS can call it directly
+    this.defineMethod(
+      'useResource',
+      function (
+        this: BaseFlowEngineContext,
+        className: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource',
+      ) {
+        if (this.has('resource')) return;
+        this.defineProperty('resource', {
+          get: () => this.createResource(className),
+        });
+      },
+    );
   }
 }
 
 export class FlowModelContext extends BaseFlowModelContext {
   constructor(model: FlowModel) {
-    if (!(model instanceof FlowModel)) {
+    if (!model || typeof model !== 'object') {
       throw new Error('Invalid FlowModel instance');
     }
     super();
@@ -1382,13 +1609,6 @@ export class FlowModelContext extends BaseFlowModelContext {
     this.defineMethod('onRefReady', (ref, cb, timeout) => {
       this.engine.reactView.onRefReady(ref, cb, timeout);
     });
-    this.defineMethod('runjs', async (code, variables, options?: { version?: string }) => {
-      const runner = this.createJSRunner({
-        globals: variables,
-        version: options?.version,
-      });
-      return runner.run(code);
-    });
     this.defineProperty('model', {
       value: model,
     });
@@ -1402,12 +1622,22 @@ export class FlowModelContext extends BaseFlowModelContext {
     });
     this.defineMethod('openView', async function (uid: string, options) {
       const opts = { ...options };
-      if (opts.defineProperties || opts.defineMethod) {
+      // NOTE: when custom context is passed, route navigation must be disabled to avoid losing it after refresh.
+      if (opts.defineProperties || opts.defineMethods) {
         opts.navigation = false; // 强制不使用路由导航, 避免刷新页面时丢失上下文
       }
       let model: FlowModel | null = null;
       model = await this.engine.loadModel({ uid });
       if (!model) {
+        const pickDefined = (src: Record<string, any>, keys: string[]) => {
+          const res: Record<string, any> = {};
+          for (const k of keys) {
+            if (typeof src?.[k] !== 'undefined') {
+              res[k] = src[k];
+            }
+          }
+          return res;
+        };
         model = this.engine.createModel({
           uid, // 注意： 新建的 model 应该使用 ${parentModel.uid}-xxx 形式的 uid
           use: 'PopupActionModel',
@@ -1417,23 +1647,16 @@ export class FlowModelContext extends BaseFlowModelContext {
           stepParams: {
             popupSettings: {
               openView: {
-                ..._.pick(opts, ['dataSourceKey', 'collectionName', 'associationName']),
+                // 仅在创建时持久化一份默认配置；运行时以本次 opts 为准，避免多个 opener 互相覆盖。
+                ...pickDefined(opts, ['dataSourceKey', 'collectionName', 'associationName', 'mode', 'size']),
               },
             },
           },
         });
         await model.save();
       }
-      if (model.getStepParams('popupSettings')?.openView?.dataSourceKey) {
-        model.setStepParams('popupSettings', {
-          openView: {
-            ...model.getStepParams('popupSettings')?.openView,
-            ..._.pick(opts, ['dataSourceKey', 'collectionName', 'associationName']),
-          },
-        });
-        await model.save();
-      }
 
+      model.setParent(this.model);
       // 路由层级的 viewUid：优先使用 routeViewUid（仅用于路由展示）；
       // 否则回退到 opts.viewUid；再否则沿用原有规则（若子模型具备弹窗配置则使用子模型 uid，否则使用发起者 uid）。
       const viewUid =
@@ -1456,13 +1679,26 @@ export class FlowModelContext extends BaseFlowModelContext {
         engineCtx: this.engine.context,
       };
       model.context.defineProperty('view', { value: pendingView });
-      await model.dispatchEvent('click', {
-        // navigation: false, // TODO: 路由模式有bug，不支持多层同样viewId的弹窗，因此这里默认先用false
-        // ...this.model?.['getInputArgs']?.(), // 避免部分关系字段信息丢失, 仿照 ClickableCollectionField 做法
-        ...opts,
-      });
-      // 清理 pending view，避免污染子模型 context（例如后续直接点击该模型按钮时被遗留 viewUid 干扰）
-      model.context.defineProperty('view', { value: undefined });
+      // 默认按 click 打开，但兼容 popupSettings 绑定到其他事件（例如 DuplicateActionModel 监听 openDuplicatePopup）。
+      const popupFlow = model.getFlow?.('popupSettings');
+      const on = (popupFlow as any)?.on;
+      let openEventName = 'click';
+      if (typeof on === 'string' && on) {
+        openEventName = on;
+      } else if (on && typeof on === 'object' && typeof (on as any).eventName === 'string' && (on as any).eventName) {
+        openEventName = (on as any).eventName;
+      }
+      await model.dispatchEvent(
+        openEventName,
+        {
+          // navigation: false, // TODO: 路由模式有bug，不支持多层同样viewId的弹窗，因此这里默认先用false
+          // ...this.model?.['getInputArgs']?.(), // 避免部分关系字段信息丢失, 仿照 ClickableCollectionField 做法
+          ...opts,
+        },
+        {
+          debounce: true,
+        },
+      );
     });
     this.defineMethod('getEvents', function (this: BaseFlowModelContext) {
       return this.model.getEvents();
@@ -1477,7 +1713,8 @@ export class FlowModelContext extends BaseFlowModelContext {
       'runAction',
       async function (this: BaseFlowModelContext, actionName: string, params?: Record<string, any>) {
         const def = this.model.getAction<FlowModel, FlowModelContext>(actionName);
-        const ctx = this.createProxy() as unknown as FlowModelContext;
+        // 使用“临时作用域”上下文，避免将临时定义污染到模型级上下文，并在创建时应用定义
+        const ctx = await createEphemeralContext(this as unknown as FlowModelContext, def);
         if (!def) {
           throw new Error(`Action '${actionName}' not found.`);
         }
@@ -1490,7 +1727,7 @@ export class FlowModelContext extends BaseFlowModelContext {
           useRawParams = await useRawParams(ctx);
         }
         if (!useRawParams) {
-          combinedParams = await (ctx as any).resolveJsonTemplate(combinedParams);
+          combinedParams = await ctx.resolveJsonTemplate(combinedParams);
         }
 
         if (!def.handler) {
@@ -1507,11 +1744,11 @@ export class FlowForkModelContext extends BaseFlowModelContext {
     public master: FlowModel,
     public fork: ForkFlowModel,
   ) {
-    if (!(master instanceof FlowModel)) {
+    if (!master || typeof master !== 'object') {
       throw new Error('Invalid FlowModel instance');
     }
     super();
-    this.addDelegate((this.master as any).context);
+    this.addDelegate(this.master.context);
     this.defineMethod('onRefReady', (ref, cb, timeout) => {
       this.engine.reactView.onRefReady(ref, cb, timeout);
     });
@@ -1526,13 +1763,6 @@ export class FlowForkModelContext extends BaseFlowModelContext {
         return stableRef;
       },
     });
-    this.defineMethod('runjs', async (code, variables, options?: { version?: string }) => {
-      const runner = this.createJSRunner({
-        globals: variables,
-        version: options?.version,
-      });
-      return runner.run(code);
-    });
   }
 }
 
@@ -1587,13 +1817,6 @@ export class FlowRuntimeContext<
     this.defineMethod('onRefReady', (ref, cb, timeout) => {
       this.engine.reactView.onRefReady(ref, cb, timeout);
     });
-    this.defineMethod('runjs', async (code, variables, options?: { version?: string }) => {
-      const runner = this.createJSRunner({
-        globals: variables,
-        version: options?.version,
-      });
-      return runner.run(code);
-    });
   }
 
   protected _getOwnProperty(key: string): any {
@@ -1641,3 +1864,268 @@ export class FlowRuntimeContext<
 
 // 类型别名，方便使用
 export type FlowSettingsContext<TModel extends FlowModel = FlowModel> = FlowRuntimeContext<TModel, 'settings'>;
+
+export type FlowContextDocRef = string | { url: string; title?: string };
+
+export type FlowDeprecationDoc =
+  | boolean
+  | {
+      message?: string;
+      replacedBy?: string | string[];
+      since?: string;
+      removedIn?: string;
+      ref?: FlowContextDocRef;
+    };
+
+export type FlowContextDocParam = {
+  name: string;
+  description?: string;
+  type?: string;
+  optional?: boolean;
+  default?: JSONValue;
+};
+
+export type FlowContextDocReturn = {
+  description?: string;
+  type?: string;
+};
+
+export type RunJSDocCompletionDoc = {
+  insertText?: string;
+};
+
+export type RunJSDocHiddenDoc = boolean | ((ctx: any) => boolean | Promise<boolean>);
+
+// `hidden` is the single visibility entrypoint for RunJSDoc property docs:
+// - boolean: hide the whole node and its subtree
+// - string[]: hide specific subpaths under the node (relative dot-paths)
+export type RunJSDocHiddenOrPathsDoc =
+  | boolean
+  | string[]
+  | ((ctx: any) => boolean | string[] | Promise<boolean | string[]>);
+
+export type RunJSDocPropertyDoc =
+  | string
+  | {
+      description?: string;
+      detail?: string;
+      type?: string;
+      examples?: string[];
+      completion?: RunJSDocCompletionDoc;
+      ref?: FlowContextDocRef;
+      deprecated?: FlowDeprecationDoc;
+      params?: FlowContextDocParam[];
+      returns?: FlowContextDocReturn;
+      properties?: Record<string, RunJSDocPropertyDoc>;
+      hidden?: RunJSDocHiddenOrPathsDoc;
+      disabled?: boolean | ((ctx: any) => boolean | Promise<boolean>);
+      disabledReason?: string | ((ctx: any) => string | undefined | Promise<string | undefined>);
+    };
+
+export type RunJSDocMethodDoc =
+  | string
+  | {
+      description?: string;
+      detail?: string;
+      examples?: string[];
+      completion?: RunJSDocCompletionDoc;
+      ref?: FlowContextDocRef;
+      deprecated?: FlowDeprecationDoc;
+      params?: FlowContextDocParam[];
+      returns?: FlowContextDocReturn;
+      hidden?: RunJSDocHiddenDoc;
+      disabled?: boolean | ((ctx: any) => boolean | Promise<boolean>);
+      disabledReason?: string | ((ctx: any) => string | undefined | Promise<string | undefined>);
+    };
+
+export type RunJSDocMeta = {
+  label?: string;
+  properties?: Record<string, RunJSDocPropertyDoc>;
+  methods?: Record<string, RunJSDocMethodDoc>;
+  snippets?: Record<string, any>;
+};
+
+const __runjsClassDefaultMeta = new WeakMap<Function, RunJSDocMeta>();
+const __runjsClassLocaleMeta = new WeakMap<Function, Map<string, RunJSDocMeta>>();
+const __runjsDocCache = new WeakMap<Function, Map<string, RunJSDocMeta>>();
+
+function __runjsDeepMerge(base: any, patch: any) {
+  if (patch === null) return undefined;
+  if (Array.isArray(base) || Array.isArray(patch) || typeof base !== 'object' || typeof patch !== 'object') {
+    return patch ?? base;
+  }
+  const out: any = { ...base };
+  for (const k of Object.keys(patch)) {
+    const v = __runjsDeepMerge(base?.[k], patch[k]);
+    if (typeof v === 'undefined') delete out[k];
+    else out[k] = v;
+  }
+  return out;
+}
+
+export class FlowRunJSContext extends FlowContext {
+  constructor(delegate: FlowContext) {
+    super();
+    this.addDelegate(delegate);
+    this.defineProperty('React', { value: React });
+    this.defineProperty('antd', { value: antd });
+    this.defineProperty('dayjs', { value: dayjs });
+    // 为 JS 运行时代码提供带有 antd/App/ConfigProvider 包裹的 React 根
+    // 保持与 ReactDOMClient 接口一致，优先覆盖 createRoot，其余方法透传
+    const ReactDOMShim: any = {
+      ...ReactDOMClient,
+      createRoot: (container: Element | DocumentFragment, options?: any) => {
+        // 兼容 ElementProxy：若传入的是代理对象，取其底层原生元素
+        const realContainer: any = (container as any)?.__el || container;
+        // 使用引擎自带的 reactView.createRoot，以继承应用内的 ConfigProvider/App 上下文与主题
+        return this.engine.reactView.createRoot(realContainer as HTMLElement, options);
+      },
+    };
+    ReactDOMShim.__nbRunjsInternalShim = true;
+    this.defineProperty('ReactDOM', { value: ReactDOMShim });
+
+    setupRunJSLibs(this);
+
+    // Convenience: ctx.render(<App />[, container])
+    // - container defaults to ctx.element if available
+    // - internally uses engine.reactView.createRoot to inherit app context
+    // - caches root per container via global WeakMap
+    this.defineMethod(
+      'render',
+      function (
+        this: any,
+        vnode: React.ReactElement | Node | DocumentFragment | string,
+        container?: Element | DocumentFragment,
+      ) {
+        const el = (container as any) || (this.element as any);
+        if (!el) throw new Error('ctx.render: container not provided and ctx.element is not available');
+        const containerEl: any = (el as any)?.__el || el; // unwrap ElementProxy
+        const globalRef: any = globalThis as any;
+        globalRef.__nbRunjsRoots = globalRef.__nbRunjsRoots || new WeakMap<any, any>();
+        const rootMap: WeakMap<any, any> = globalRef.__nbRunjsRoots;
+
+        const disposeEntry = (entry: any) => {
+          if (!entry) return;
+          if (entry.disposeTheme && typeof entry.disposeTheme === 'function') {
+            try {
+              entry.disposeTheme();
+            } catch (_) {
+              // ignore
+            }
+            entry.disposeTheme = undefined;
+          }
+          const root = entry.root || entry;
+          if (root && typeof root.unmount === 'function') {
+            try {
+              root.unmount();
+            } catch (_) {
+              // ignore
+            }
+          }
+        };
+
+        const unmountContainerRoot = () => {
+          const existing = rootMap.get(containerEl);
+          if (existing) {
+            disposeEntry(existing);
+            rootMap.delete(containerEl);
+          }
+        };
+
+        // If vnode is string (HTML), unmount react root and set sanitized HTML
+        if (typeof vnode === 'string') {
+          unmountContainerRoot();
+          const proxy: any = new ElementProxy(containerEl);
+          proxy.innerHTML = String(vnode ?? '');
+          return null;
+        }
+
+        // If vnode is a DOM Node or DocumentFragment, unmount and replace content
+        if (
+          vnode &&
+          (vnode as any).nodeType &&
+          ((vnode as any).nodeType === 1 || (vnode as any).nodeType === 3 || (vnode as any).nodeType === 11)
+        ) {
+          unmountContainerRoot();
+          while (containerEl.firstChild) containerEl.removeChild(containerEl.firstChild);
+          containerEl.appendChild(vnode as any);
+          return null;
+        }
+
+        // 注意：rootMap 是“全局按容器复用”的（key=containerEl）。
+        // 若不同 RunJS ctx 复用同一个 containerEl，且 ReactDOM 实例引用也相同，
+        // 则会复用到旧 entry，进而复用旧 ctx 创建的 autorun（闭包捕获旧 ctx），造成：
+        // 1) 旧 ctx 的 reaction 继续驱动新渲染（跨 ctx 复用风险）
+        // 2) 新 ctx 的主题变化不再触发 rerender
+        // 3) 旧 ctx 被 entry/autorun 间接持有，无法被 GC（内存泄漏）
+        // 因此这里把 ownerKey（当前 ctx）也纳入复用判断；owner 变化时必须重建 entry。
+        const rendererKey = this.ReactDOM;
+        const ownerKey = this;
+        let entry = rootMap.get(containerEl);
+        if (!entry || entry.rendererKey !== rendererKey || entry.ownerKey !== ownerKey) {
+          if (entry) {
+            disposeEntry(entry);
+            rootMap.delete(containerEl);
+          }
+          const root = this.ReactDOM.createRoot(containerEl);
+          entry = { rendererKey, ownerKey, root, disposeTheme: undefined, lastVnode: undefined };
+          rootMap.set(containerEl, entry);
+        }
+
+        return externalReactRender({
+          ctx: this,
+          entry,
+          vnode,
+          containerEl,
+          rootMap,
+          unmountContainerRoot,
+          internalReact: React,
+          internalAntd: antd,
+        });
+      },
+    );
+  }
+  static define(meta: RunJSDocMeta, options?: { locale?: string }) {
+    const locale = options?.locale;
+    if (locale) {
+      const map = __runjsClassLocaleMeta.get(this) || new Map<string, RunJSDocMeta>();
+      const prev = map.get(locale) || {};
+      map.set(locale, __runjsDeepMerge(prev, meta));
+      __runjsClassLocaleMeta.set(this, map);
+    } else {
+      const prev = __runjsClassDefaultMeta.get(this) || {};
+      __runjsClassDefaultMeta.set(this, __runjsDeepMerge(prev, meta));
+    }
+    __runjsDocCache.delete(this);
+  }
+  static getDoc(locale?: string): RunJSDocMeta {
+    const self = this as any as Function;
+    let cacheForClass = __runjsDocCache.get(self);
+    const cacheKey = String(locale || 'default');
+    if (cacheForClass && cacheForClass.has(cacheKey)) return cacheForClass.get(cacheKey) as RunJSDocMeta;
+    const chain: Function[] = [];
+    let cur: any = self;
+    while (cur && cur.prototype) {
+      chain.unshift(cur);
+      cur = Object.getPrototypeOf(cur);
+    }
+    let merged: RunJSDocMeta = {};
+    for (const cls of chain) {
+      merged = __runjsDeepMerge(merged, __runjsClassDefaultMeta.get(cls) || {});
+    }
+    if (locale) {
+      for (const cls of chain) {
+        const lmap = __runjsClassLocaleMeta.get(cls);
+        if (lmap && lmap.has(locale)) {
+          merged = __runjsDeepMerge(merged, lmap.get(locale));
+        }
+      }
+    }
+    if (!cacheForClass) {
+      cacheForClass = new Map<string, RunJSDocMeta>();
+      __runjsDocCache.set(self, cacheForClass);
+    }
+    cacheForClass.set(cacheKey, merged);
+    return merged;
+  }
+}