@nocobase/flow-engine 2.0.10 → 2.0.12

package/lib/JSRunner.d.ts

@@ -13,11 +13,20 @@ export interface JSRunnerOptions {
     version?: string;
     /**
      * Enable RunJS template compatibility preprocessing for `{{ ... }}`.
-     * When enabled via `ctx.runjs(code, vars, { preprocessTemplates: true })` (default),
+     * When enabled (or falling back to version default),
      * the code will be rewritten to call `ctx.resolveJsonTemplate(...)` at runtime.
      */
     preprocessTemplates?: boolean;
 }
+/**
+ * Decide whether RunJS `{{ ... }}` compatibility preprocessing should run.
+ *
+ * Priority:
+ * 1. Explicit `preprocessTemplates` option always wins.
+ * 2. Otherwise, `version === 'v2'` disables preprocessing.
+ * 3. Fallback keeps v1-compatible behavior (enabled).
+ */
+export declare function shouldPreprocessRunJSTemplates(options?: Pick<JSRunnerOptions, 'preprocessTemplates' | 'version'>): boolean;
 export declare class JSRunner {
     private globals;
     private timeoutMs;

package/lib/JSRunner.js

@@ -27,11 +27,53 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var JSRunner_exports = {};
 __export(JSRunner_exports, {
-  JSRunner: () => JSRunner
+  JSRunner: () => JSRunner,
+  shouldPreprocessRunJSTemplates: () => shouldPreprocessRunJSTemplates
 });
 module.exports = __toCommonJS(JSRunner_exports);
 var import_ses = require("ses");
 var import_exceptions = require("./utils/exceptions");
+function shouldPreprocessRunJSTemplates(options) {
+  if (typeof (options == null ? void 0 : options.preprocessTemplates) === "boolean") {
+    return options.preprocessTemplates;
+  }
+  return (options == null ? void 0 : options.version) !== "v2";
+}
+__name(shouldPreprocessRunJSTemplates, "shouldPreprocessRunJSTemplates");
+const BARE_CTX_TEMPLATE_RE = /(^|[=(:,[\s)])(\{\{\s*(ctx(?:\.|\[|\?\.)[^}]*)\s*\}\})/m;
+function extractDeprecatedCtxTemplateUsage(code) {
+  const src = String(code || "");
+  const m = src.match(BARE_CTX_TEMPLATE_RE);
+  if (!m) return null;
+  const placeholder = String(m[2] || "").trim();
+  const expression = String(m[3] || "").trim();
+  if (!placeholder || !expression) return null;
+  return { placeholder, expression };
+}
+__name(extractDeprecatedCtxTemplateUsage, "extractDeprecatedCtxTemplateUsage");
+function shouldHintCtxTemplateSyntax(err, usage) {
+  const isSyntaxError = err instanceof SyntaxError || String((err == null ? void 0 : err.name) || "") === "SyntaxError";
+  if (!isSyntaxError) return false;
+  if (!usage) return false;
+  const msg = String((err == null ? void 0 : err.message) || err || "");
+  return /unexpected token/i.test(msg);
+}
+__name(shouldHintCtxTemplateSyntax, "shouldHintCtxTemplateSyntax");
+function toCtxTemplateSyntaxHintError(err, usage) {
+  const hint = `"${usage.placeholder}" has been deprecated and cannot be used as executable RunJS syntax. Use await ctx.getVar("${usage.expression}") instead, or keep "${usage.placeholder}" as a plain string.`;
+  const out = new SyntaxError(hint);
+  try {
+    out.cause = err;
+  } catch (_) {
+  }
+  try {
+    out.__runjsHideLocation = true;
+    out.stack = `${out.name}: ${out.message}`;
+  } catch (_) {
+  }
+  return out;
+}
+__name(toCtxTemplateSyntaxHintError, "toCtxTemplateSyntaxHintError");
 const _JSRunner = class _JSRunner {
   globals;
   timeoutMs;
@@ -111,11 +153,13 @@ const _JSRunner = class _JSRunner {
       if (err instanceof import_exceptions.FlowExitAllException) {
         throw err;
       }
-      console.error(err);
+      const usage = extractDeprecatedCtxTemplateUsage(code);
+      const outErr = shouldHintCtxTemplateSyntax(err, usage) && usage ? toCtxTemplateSyntaxHintError(err, usage) : err;
+      console.error(outErr);
       return {
         success: false,
-        error: err,
-        timeout: err.message === "Execution timed out"
+        error: outErr,
+        timeout: (outErr == null ? void 0 : outErr.message) === "Execution timed out"
       };
     }
   }
@@ -124,5 +168,6 @@ __name(_JSRunner, "JSRunner");
 let JSRunner = _JSRunner;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  JSRunner
+  JSRunner,
+  shouldPreprocessRunJSTemplates
 });

package/lib/components/settings/wrappers/contextual/StepSettingsDialog.js

@@ -126,6 +126,15 @@ const openStepSettingsDialog = /* @__PURE__ */ __name(async ({
     }
   };
   const openView = model.context.viewer[mode].bind(model.context.viewer);
+  const resolvedUiModeProps = (0, import_reactive.toJS)(uiModeProps) || {};
+  const { zIndex: uiModeZIndex, ...restUiModeProps } = resolvedUiModeProps;
+  const resolveDialogZIndex = /* @__PURE__ */ __name((rawZIndex) => {
+    var _a2, _b2;
+    const nextZIndex = typeof ((_a2 = model.context.viewer) == null ? void 0 : _a2.getNextZIndex) === "function" ? model.context.viewer.getNextZIndex() : (((_b2 = model.context.themeToken) == null ? void 0 : _b2.zIndexPopupBase) || 1e3) + 1;
+    const inputZIndex = Number(rawZIndex) || 0;
+    return Math.max(nextZIndex, inputZIndex);
+  }, "resolveDialogZIndex");
+  const mergedZIndex = resolveDialogZIndex(uiModeZIndex);
   const form = (0, import_core.createForm)({
     initialValues: (0, import_utils.compileUiSchema)(scopes, initialValues)
   });
@@ -141,7 +150,8 @@ const openStepSettingsDialog = /* @__PURE__ */ __name(async ({
     title: dialogTitle || t(title),
     width: dialogWidth,
     destroyOnClose: true,
-    ...(0, import_reactive.toJS)(uiModeProps),
+    ...restUiModeProps,
+    zIndex: mergedZIndex,
     // 透传 navigation，便于变量元信息根据真实视图栈推断父级弹窗
     inputArgs,
     onClose: /* @__PURE__ */ __name(() => {
@@ -155,7 +165,11 @@ const openStepSettingsDialog = /* @__PURE__ */ __name(async ({
         (0, import_react2.useEffect)(() => {
           return (0, import_reactive.autorun)(() => {
             const dynamicProps = (0, import_reactive.toJS)(uiModeProps);
-            currentDialog.update(dynamicProps);
+            const { zIndex, ...restDynamicProps } = dynamicProps || {};
+            currentDialog.update({
+              ...restDynamicProps,
+              zIndex: resolveDialogZIndex(zIndex)
+            });
           });
         }, []);
         const compiledFormSchema = (0, import_utils.compileUiSchema)(scopes, formSchema);

package/lib/flowContext.js

@@ -2222,7 +2222,10 @@ const _BaseFlowEngineContext = class _BaseFlowEngineContext extends FlowContext
           ...runnerOptions || {},
           globals: mergedGlobals
         });
-        const shouldPreprocessTemplates = preprocessTemplates !== false;
+        const shouldPreprocessTemplates = (0, import_JSRunner.shouldPreprocessRunJSTemplates)({
+          version: runnerOptions == null ? void 0 : runnerOptions.version,
+          preprocessTemplates
+        });
         const jsCode = await (0, import_utils.prepareRunJsCode)(String(code ?? ""), { preprocessTemplates: shouldPreprocessTemplates });
         return runner.run(jsCode);
       }

package/lib/runjs-context/registry.d.ts

@@ -6,7 +6,7 @@
  * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
-export type RunJSVersion = 'v1' | (string & {});
+export type RunJSVersion = 'v1' | 'v2' | (string & {});
 export type RunJSContextCtor = new (delegate: any) => any;
 export type RunJSContextMeta = {
     scenes?: string[];

package/lib/runjs-context/setup.js

@@ -67,19 +67,26 @@ async function setupRunJSContexts() {
     import("./contexts/JSRecordActionRunJSContext"),
     import("./contexts/JSCollectionActionRunJSContext")
   ]);
-  const v1 = "v1";
-  import_registry.RunJSContextRegistry.register(v1, "*", import_flowContext.FlowRunJSContext);
-  import_registry.RunJSContextRegistry.register(v1, "JSBlockModel", JSBlockRunJSContext, { scenes: ["block"] });
-  import_registry.RunJSContextRegistry.register(v1, "JSFieldModel", JSFieldRunJSContext, { scenes: ["detail"] });
-  import_registry.RunJSContextRegistry.register(v1, "JSEditableFieldModel", JSEditableFieldRunJSContext, { scenes: ["form"] });
-  import_registry.RunJSContextRegistry.register(v1, "JSItemModel", JSItemRunJSContext, { scenes: ["form"] });
-  import_registry.RunJSContextRegistry.register(v1, "JSColumnModel", JSColumnRunJSContext, { scenes: ["table"] });
-  import_registry.RunJSContextRegistry.register(v1, "FormJSFieldItemModel", FormJSFieldItemRunJSContext, { scenes: ["form"] });
-  import_registry.RunJSContextRegistry.register(v1, "JSRecordActionModel", JSRecordActionRunJSContext, { scenes: ["table"] });
-  import_registry.RunJSContextRegistry.register(v1, "JSCollectionActionModel", JSCollectionActionRunJSContext, { scenes: ["table"] });
-  await (0, import_contributions.applyRunJSContextContributions)(v1);
+  const registerBuiltins = /* @__PURE__ */ __name((version) => {
+    import_registry.RunJSContextRegistry.register(version, "*", import_flowContext.FlowRunJSContext);
+    import_registry.RunJSContextRegistry.register(version, "JSBlockModel", JSBlockRunJSContext, { scenes: ["block"] });
+    import_registry.RunJSContextRegistry.register(version, "JSFieldModel", JSFieldRunJSContext, { scenes: ["detail"] });
+    import_registry.RunJSContextRegistry.register(version, "JSEditableFieldModel", JSEditableFieldRunJSContext, { scenes: ["form"] });
+    import_registry.RunJSContextRegistry.register(version, "JSItemModel", JSItemRunJSContext, { scenes: ["form"] });
+    import_registry.RunJSContextRegistry.register(version, "JSColumnModel", JSColumnRunJSContext, { scenes: ["table"] });
+    import_registry.RunJSContextRegistry.register(version, "FormJSFieldItemModel", FormJSFieldItemRunJSContext, { scenes: ["form"] });
+    import_registry.RunJSContextRegistry.register(version, "JSRecordActionModel", JSRecordActionRunJSContext, { scenes: ["table"] });
+    import_registry.RunJSContextRegistry.register(version, "JSCollectionActionModel", JSCollectionActionRunJSContext, {
+      scenes: ["table"]
+    });
+  }, "registerBuiltins");
+  const versions = ["v1", "v2"];
+  for (const version of versions) {
+    registerBuiltins(version);
+    await (0, import_contributions.applyRunJSContextContributions)(version);
+    (0, import_contributions.markRunJSContextsSetupDone)(version);
+  }
   done = true;
-  (0, import_contributions.markRunJSContextsSetupDone)(v1);
 }
 __name(setupRunJSContexts, "setupRunJSContexts");
 // Annotate the CommonJS export names for ESM import in node:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.0.10",
+  "version": "2.0.12",
   "private": false,
   "description": "A standalone flow engine for NocoBase, managing workflows, models, and actions.",
   "main": "lib/index.js",
@@ -8,8 +8,8 @@
   "dependencies": {
     "@formily/antd-v5": "1.x",
     "@formily/reactive": "2.x",
-    "@nocobase/sdk": "2.0.10",
-    "@nocobase/shared": "2.0.10",
+    "@nocobase/sdk": "2.0.12",
+    "@nocobase/shared": "2.0.12",
     "ahooks": "^3.7.2",
     "dayjs": "^1.11.9",
     "dompurify": "^3.0.2",
@@ -36,5 +36,5 @@
   ],
   "author": "NocoBase Team",
   "license": "Apache-2.0",
-  "gitHead": "d7e58c47134e1921b2d65f2135e7c2f1f00c21bd"
+  "gitHead": "a96acd22a9b0744b567617e3a1f1d42cb7f72368"
 }

package/src/JSRunner.ts

@@ -16,12 +16,74 @@ export interface JSRunnerOptions {
   version?: string;
   /**
    * Enable RunJS template compatibility preprocessing for `{{ ... }}`.
-   * When enabled via `ctx.runjs(code, vars, { preprocessTemplates: true })` (default),
+   * When enabled (or falling back to version default),
    * the code will be rewritten to call `ctx.resolveJsonTemplate(...)` at runtime.
    */
   preprocessTemplates?: boolean;
 }
 
+/**
+ * Decide whether RunJS `{{ ... }}` compatibility preprocessing should run.
+ *
+ * Priority:
+ * 1. Explicit `preprocessTemplates` option always wins.
+ * 2. Otherwise, `version === 'v2'` disables preprocessing.
+ * 3. Fallback keeps v1-compatible behavior (enabled).
+ */
+export function shouldPreprocessRunJSTemplates(
+  options?: Pick<JSRunnerOptions, 'preprocessTemplates' | 'version'>,
+): boolean {
+  if (typeof options?.preprocessTemplates === 'boolean') {
+    return options.preprocessTemplates;
+  }
+  return options?.version !== 'v2';
+}
+
+// Heuristic: detect likely bare `{{ctx.xxx}}` usage in executable positions (not quoted string literals).
+const BARE_CTX_TEMPLATE_RE = /(^|[=(:,[\s)])(\{\{\s*(ctx(?:\.|\[|\?\.)[^}]*)\s*\}\})/m;
+
+function extractDeprecatedCtxTemplateUsage(code: string): { placeholder: string; expression: string } | null {
+  const src = String(code || '');
+  const m = src.match(BARE_CTX_TEMPLATE_RE);
+  if (!m) return null;
+  const placeholder = String(m[2] || '').trim();
+  const expression = String(m[3] || '').trim();
+  if (!placeholder || !expression) return null;
+  return { placeholder, expression };
+}
+
+function shouldHintCtxTemplateSyntax(err: any, usage: { placeholder: string; expression: string } | null): boolean {
+  const isSyntaxError = err instanceof SyntaxError || String((err as any)?.name || '') === 'SyntaxError';
+  if (!isSyntaxError) return false;
+  if (!usage) return false;
+  const msg = String((err as any)?.message || err || '');
+  return /unexpected token/i.test(msg);
+}
+
+function toCtxTemplateSyntaxHintError(
+  err: any,
+  usage: {
+    placeholder: string;
+    expression: string;
+  },
+): Error {
+  const hint = `"${usage.placeholder}" has been deprecated and cannot be used as executable RunJS syntax. Use await ctx.getVar("${usage.expression}") instead, or keep "${usage.placeholder}" as a plain string.`;
+  const out = new SyntaxError(hint);
+  try {
+    (out as any).cause = err;
+  } catch (_) {
+    // ignore
+  }
+  try {
+    // Hint-only error: avoid leaking internal bundle line numbers from stack parsers in preview UI.
+    (out as any).__runjsHideLocation = true;
+    out.stack = `${out.name}: ${out.message}`;
+  } catch (_) {
+    // ignore
+  }
+  return out;
+}
+
 export class JSRunner {
   private globals: Record<string, any>;
   private timeoutMs: number;
@@ -118,11 +180,13 @@ export class JSRunner {
       if (err instanceof FlowExitAllException) {
         throw err;
       }
-      console.error(err);
+      const usage = extractDeprecatedCtxTemplateUsage(code);
+      const outErr = shouldHintCtxTemplateSyntax(err, usage) && usage ? toCtxTemplateSyntaxHintError(err, usage) : err;
+      console.error(outErr);
       return {
         success: false,
-        error: err,
-        timeout: err.message === 'Execution timed out',
+        error: outErr,
+        timeout: (outErr as any)?.message === 'Execution timed out',
       };
     }
   }

package/src/__tests__/JSRunner.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { JSRunner } from '../JSRunner';
+import { JSRunner, shouldPreprocessRunJSTemplates } from '../JSRunner';
 import { createSafeWindow } from '../utils';
 
 describe('JSRunner', () => {
@@ -30,6 +30,18 @@ describe('JSRunner', () => {
     vi.restoreAllMocks();
   });
 
+  it('shouldPreprocessRunJSTemplates: explicit option has highest priority', () => {
+    expect(shouldPreprocessRunJSTemplates({ version: 'v2', preprocessTemplates: true })).toBe(true);
+    expect(shouldPreprocessRunJSTemplates({ version: 'v1', preprocessTemplates: false })).toBe(false);
+  });
+
+  it('shouldPreprocessRunJSTemplates: falls back to version policy', () => {
+    expect(shouldPreprocessRunJSTemplates({ version: 'v1' })).toBe(true);
+    expect(shouldPreprocessRunJSTemplates({ version: 'v2' })).toBe(false);
+    expect(shouldPreprocessRunJSTemplates({})).toBe(true);
+    expect(shouldPreprocessRunJSTemplates()).toBe(true);
+  });
+
   it('executes simple code and returns value', async () => {
     const runner = new JSRunner();
     const result = await runner.run('return 1 + 2 + 3');
@@ -152,6 +164,20 @@ describe('JSRunner', () => {
     expect((result.error as Error).message).toBe('Execution timed out');
   });
 
+  it('returns friendly hint when bare {{ctx.xxx}} appears in syntax error', async () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const runner = new JSRunner();
+    const result = await runner.run('const z = {{ctx.user.id}}');
+    expect(result.success).toBe(false);
+    expect(result.error).toBeInstanceOf(SyntaxError);
+    const msg = String((result.error as any)?.message || '');
+    expect(msg).toContain('"{{ctx.user.id}}" has been deprecated');
+    expect(msg).toContain('await ctx.getVar("ctx.user.id")');
+    expect(msg).not.toContain('(at ');
+    expect((result.error as any)?.__runjsHideLocation).toBe(true);
+    expect(spy).toHaveBeenCalled();
+  });
+
   it('skips execution when URL contains skipRunJs=true', async () => {
     // 模拟预览模式下通过 URL 参数跳过代码执行
     if (typeof window !== 'undefined' && typeof window.history?.pushState === 'function') {

package/src/__tests__/runjsContext.test.ts

@@ -29,6 +29,10 @@ describe('flowRunJSContext registry and doc', () => {
       expect(RunJSContextRegistry['resolve']('v1' as any, '*')).toBeTruthy();
     });
 
+    it('should register v2 mapping', () => {
+      expect(RunJSContextRegistry['resolve']('v2' as any, '*')).toBeTruthy();
+    });
+
     it('should register all context types', () => {
       const contextTypes = [
         'JSBlockModel',
@@ -44,12 +48,20 @@ describe('flowRunJSContext registry and doc', () => {
         const ctor = RunJSContextRegistry['resolve']('v1' as any, modelClass);
         expect(ctor).toBeTruthy();
       });
+
+      contextTypes.forEach((modelClass) => {
+        const ctor = RunJSContextRegistry['resolve']('v2' as any, modelClass);
+        expect(ctor).toBeTruthy();
+      });
     });
 
     it('should expose scene metadata for contexts', () => {
       expect(getRunJSScenesForModel('JSBlockModel', 'v1')).toEqual(['block']);
       expect(getRunJSScenesForModel('JSFieldModel', 'v1')).toEqual(['detail']);
+      expect(getRunJSScenesForModel('JSBlockModel', 'v2')).toEqual(['block']);
+      expect(getRunJSScenesForModel('JSFieldModel', 'v2')).toEqual(['detail']);
       expect(getRunJSScenesForModel('UnknownModel', 'v1')).toEqual([]);
+      expect(getRunJSScenesForModel('UnknownModel', 'v2')).toEqual([]);
     });
 
     it('should only execute once (idempotent)', async () => {
@@ -175,6 +187,7 @@ describe('flowRunJSContext registry and doc', () => {
       const ctx = new FlowContext();
       ctx.defineProperty('model', { value: { constructor: { name: 'JSColumnModel' } } });
       expect(getRunJSScenesForContext(ctx as any, { version: 'v1' })).toEqual(['table']);
+      expect(getRunJSScenesForContext(ctx as any, { version: 'v2' })).toEqual(['table']);
     });
 
     it('JSBlockModel context should have element property in doc', () => {

package/src/__tests__/runjsPreprocessDefault.test.ts

@@ -36,6 +36,29 @@ describe('ctx.runjs preprocessTemplates default', () => {
     expect(r.value).toBe('{{ctx.user.id}}');
   });
 
+  it('disables template preprocess by default for version v2', async () => {
+    const engine = new FlowEngine();
+    const ctx = engine.context as any;
+    ctx.defineProperty('user', { value: { id: 123 } });
+
+    const r = await ctx.runjs('return "{{ctx.user.id}}";', undefined, { version: 'v2' });
+    expect(r.success).toBe(true);
+    expect(r.value).toBe('{{ctx.user.id}}');
+  });
+
+  it('keeps explicit preprocessTemplates override higher priority than version', async () => {
+    const engine = new FlowEngine();
+    const ctx = engine.context as any;
+    ctx.defineProperty('user', { value: { id: 123 } });
+
+    const r = await ctx.runjs('return "{{ctx.user.id}}";', undefined, {
+      version: 'v2',
+      preprocessTemplates: true,
+    });
+    expect(r.success).toBe(true);
+    expect(r.value).toBe('123');
+  });
+
   it('does not double-preprocess already prepared code', async () => {
     const engine = new FlowEngine();
     const ctx = engine.context as any;

package/src/components/settings/wrappers/contextual/StepSettingsDialog.tsx

@@ -134,6 +134,17 @@ const openStepSettingsDialog = async ({
   };
 
   const openView = model.context.viewer[mode].bind(model.context.viewer);
+  const resolvedUiModeProps = toJS(uiModeProps) || {};
+  const { zIndex: uiModeZIndex, ...restUiModeProps } = resolvedUiModeProps;
+  const resolveDialogZIndex = (rawZIndex?: number) => {
+    const nextZIndex =
+      typeof model.context.viewer?.getNextZIndex === 'function'
+        ? model.context.viewer.getNextZIndex()
+        : (model.context.themeToken?.zIndexPopupBase || 1000) + 1;
+    const inputZIndex = Number(rawZIndex) || 0;
+    return Math.max(nextZIndex, inputZIndex);
+  };
+  const mergedZIndex = resolveDialogZIndex(uiModeZIndex);
 
   const form = createForm({
     initialValues: compileUiSchema(scopes, initialValues),
@@ -152,7 +163,8 @@ const openStepSettingsDialog = async ({
     title: dialogTitle || t(title),
     width: dialogWidth,
     destroyOnClose: true,
-    ...toJS(uiModeProps),
+    ...restUiModeProps,
+    zIndex: mergedZIndex,
     // 透传 navigation，便于变量元信息根据真实视图栈推断父级弹窗
     inputArgs,
     onClose: () => {
@@ -165,7 +177,11 @@ const openStepSettingsDialog = async ({
         useEffect(() => {
           return autorun(() => {
             const dynamicProps = toJS(uiModeProps);
-            currentDialog.update(dynamicProps);
+            const { zIndex, ...restDynamicProps } = dynamicProps || {};
+            currentDialog.update({
+              ...restDynamicProps,
+              zIndex: resolveDialogZIndex(zIndex),
+            });
           });
         }, []);
 

package/src/flowContext.ts

@@ -27,7 +27,7 @@ import { ContextPathProxy } from './ContextPathProxy';
 import { DataSource, DataSourceManager } from './data-source';
 import { FlowEngine } from './flowEngine';
 import { FlowI18n } from './flowI18n';
-import { JSRunner, JSRunnerOptions } from './JSRunner';
+import { JSRunner, JSRunnerOptions, shouldPreprocessRunJSTemplates } from './JSRunner';
 import type { FlowModel } from './models/flowModel';
 import type { ForkFlowModel } from './models/forkFlowModel';
 import { FlowResource, FlowSQLRepository } from './resources';
@@ -3035,8 +3035,10 @@ class BaseFlowEngineContext extends FlowContext {
           ...(runnerOptions || {}),
           globals: mergedGlobals,
         });
-        // Enable by default; use `preprocessTemplates: false` to explicitly disable.
-        const shouldPreprocessTemplates = preprocessTemplates !== false;
+        const shouldPreprocessTemplates = shouldPreprocessRunJSTemplates({
+          version: runnerOptions?.version,
+          preprocessTemplates,
+        });
         const jsCode = await prepareRunJsCode(String(code ?? ''), { preprocessTemplates: shouldPreprocessTemplates });
         return runner.run(jsCode);
       },

package/src/runjs-context/registry.ts

@@ -10,7 +10,7 @@
 // 为避免在模块初始化阶段引入 FlowContext（从而触发循环依赖），不要在顶层导入各类 RunJSContext。
 // 在需要默认映射时（首次 resolve）再使用 createRequire 同步加载对应模块。
 
-export type RunJSVersion = 'v1' | (string & {});
+export type RunJSVersion = 'v1' | 'v2' | (string & {});
 export type RunJSContextCtor = new (delegate: any) => any;
 export type RunJSContextMeta = {
   scenes?: string[];

package/src/runjs-context/setup.ts

@@ -41,17 +41,26 @@ export async function setupRunJSContexts() {
     import('./contexts/JSCollectionActionRunJSContext'),
   ]);
 
-  const v1 = 'v1';
-  RunJSContextRegistry.register(v1, '*', FlowRunJSContext);
-  RunJSContextRegistry.register(v1, 'JSBlockModel', JSBlockRunJSContext, { scenes: ['block'] });
-  RunJSContextRegistry.register(v1, 'JSFieldModel', JSFieldRunJSContext, { scenes: ['detail'] });
-  RunJSContextRegistry.register(v1, 'JSEditableFieldModel', JSEditableFieldRunJSContext, { scenes: ['form'] });
-  RunJSContextRegistry.register(v1, 'JSItemModel', JSItemRunJSContext, { scenes: ['form'] });
-  RunJSContextRegistry.register(v1, 'JSColumnModel', JSColumnRunJSContext, { scenes: ['table'] });
-  RunJSContextRegistry.register(v1, 'FormJSFieldItemModel', FormJSFieldItemRunJSContext, { scenes: ['form'] });
-  RunJSContextRegistry.register(v1, 'JSRecordActionModel', JSRecordActionRunJSContext, { scenes: ['table'] });
-  RunJSContextRegistry.register(v1, 'JSCollectionActionModel', JSCollectionActionRunJSContext, { scenes: ['table'] });
-  await applyRunJSContextContributions(v1);
+  const registerBuiltins = (version: 'v1' | 'v2') => {
+    RunJSContextRegistry.register(version, '*', FlowRunJSContext);
+    RunJSContextRegistry.register(version, 'JSBlockModel', JSBlockRunJSContext, { scenes: ['block'] });
+    RunJSContextRegistry.register(version, 'JSFieldModel', JSFieldRunJSContext, { scenes: ['detail'] });
+    RunJSContextRegistry.register(version, 'JSEditableFieldModel', JSEditableFieldRunJSContext, { scenes: ['form'] });
+    RunJSContextRegistry.register(version, 'JSItemModel', JSItemRunJSContext, { scenes: ['form'] });
+    RunJSContextRegistry.register(version, 'JSColumnModel', JSColumnRunJSContext, { scenes: ['table'] });
+    RunJSContextRegistry.register(version, 'FormJSFieldItemModel', FormJSFieldItemRunJSContext, { scenes: ['form'] });
+    RunJSContextRegistry.register(version, 'JSRecordActionModel', JSRecordActionRunJSContext, { scenes: ['table'] });
+    RunJSContextRegistry.register(version, 'JSCollectionActionModel', JSCollectionActionRunJSContext, {
+      scenes: ['table'],
+    });
+  };
+
+  const versions: Array<'v1' | 'v2'> = ['v1', 'v2'];
+  for (const version of versions) {
+    registerBuiltins(version);
+    await applyRunJSContextContributions(version);
+    markRunJSContextsSetupDone(version);
+  }
+
   done = true;
-  markRunJSContextsSetupDone(v1);
 }