@nocobase/flow-engine 2.1.0-beta.1 → 2.1.0-beta.11

package/lib/utils/index.js

@@ -30,6 +30,7 @@ __export(utils_exports, {
   BLOCK_TYPES: () => import_constants.BLOCK_TYPES,
   FLOW_ENGINE_NAMESPACE: () => import_constants.FLOW_ENGINE_NAMESPACE,
   FlowCancelSaveException: () => import_exceptions.FlowCancelSaveException,
+  FlowExitAllException: () => import_exceptions.FlowExitAllException,
   FlowExitException: () => import_exceptions.FlowExitException,
   MENU_KEYS: () => import_constants.MENU_KEYS,
   buildRecordMeta: () => import_variablesParams.buildRecordMeta,
@@ -86,6 +87,7 @@ __export(utils_exports, {
   serializeCtxDateValue: () => import_dateVariable.serializeCtxDateValue,
   setAutoFlowError: () => import_autoFlowError.setAutoFlowError,
   setupRuntimeContextSteps: () => import_setupRuntimeContextSteps.setupRuntimeContextSteps,
+  shouldHideEventInSettings: () => import_schema_utils.shouldHideEventInSettings,
   shouldHideStepInSettings: () => import_schema_utils.shouldHideStepInSettings,
   tExpr: () => import_translation.tExpr
 });
@@ -119,6 +121,7 @@ var import_resolveModuleUrl = require("./resolveModuleUrl");
   BLOCK_TYPES,
   FLOW_ENGINE_NAMESPACE,
   FlowCancelSaveException,
+  FlowExitAllException,
   FlowExitException,
   MENU_KEYS,
   buildRecordMeta,
@@ -175,6 +178,7 @@ var import_resolveModuleUrl = require("./resolveModuleUrl");
   serializeCtxDateValue,
   setAutoFlowError,
   setupRuntimeContextSteps,
+  shouldHideEventInSettings,
   shouldHideStepInSettings,
   tExpr
 });

package/lib/utils/parsePathnameToViewParams.js

@@ -92,7 +92,7 @@ const parsePathnameToViewParams = /* @__PURE__ */ __name((pathname) => {
             } catch (_) {
               parsed = decoded;
             }
-          } else if (decoded && decoded.includes("=") && decoded.includes("&")) {
+          } else if (decoded && /^[^=&]+=[^=&]*(?:&[^=&]+=[^=&]*)*$/.test(decoded)) {
             parsed = parseKeyValuePairs(decoded);
           }
           currentView.filterByTk = parsed;

package/lib/utils/schema-utils.d.ts

@@ -9,7 +9,7 @@
 import type { ISchema } from '@formily/json-schema';
 import type { FlowModel } from '../models';
 import { FlowRuntimeContext } from '../flowContext';
-import type { StepDefinition, StepUIMode } from '../types';
+import type { EventDefinition, StepDefinition, StepUIMode } from '../types';
 /**
  * 解析 uiMode，支持静态值和函数形式
  * 函数可以接收 FlowRuntimeContext
@@ -38,6 +38,12 @@ export declare function compileUiSchema(scope: Record<string, any>, uiSchema: an
  * @returns 合并后的uiSchema对象，如果为空则返回null
  */
 export declare function resolveStepUiSchema<TModel extends FlowModel = FlowModel>(model: TModel, flow: any, step: StepDefinition): Promise<Record<string, ISchema> | null>;
+/**
+ * 判断事件在设置菜单中是否应被隐藏。
+ * - 支持 EventDefinition.hideInSettings。
+ * - hideInSettings 可为布尔值或函数（接收 FlowRuntimeContext）。
+ */
+export declare function shouldHideEventInSettings<TModel extends FlowModel = FlowModel>(model: TModel, flow: any, event: EventDefinition<TModel> | undefined): Promise<boolean>;
 /**
  * 判断步骤在设置菜单中是否应被隐藏。
  * - 支持 StepDefinition.hideInSettings 与 ActionDefinition.hideInSettings（step 优先）。

package/lib/utils/schema-utils.js

@@ -31,6 +31,7 @@ __export(schema_utils_exports, {
   resolveStepDisabledInSettings: () => resolveStepDisabledInSettings,
   resolveStepUiSchema: () => resolveStepUiSchema,
   resolveUiMode: () => resolveUiMode,
+  shouldHideEventInSettings: () => shouldHideEventInSettings,
   shouldHideStepInSettings: () => shouldHideStepInSettings
 });
 module.exports = __toCommonJS(schema_utils_exports);
@@ -195,6 +196,23 @@ async function resolveStepUiSchema(model, flow, step) {
   return resolvedStepUiSchema;
 }
 __name(resolveStepUiSchema, "resolveStepUiSchema");
+async function shouldHideEventInSettings(model, flow, event) {
+  if (!event) return true;
+  const { hideInSettings } = event;
+  if (typeof hideInSettings === "function") {
+    try {
+      const ctx = new import_flowContext.FlowRuntimeContext(model, flow.key, "settings");
+      (0, import_setupRuntimeContextSteps.setupRuntimeContextSteps)(ctx, flow.steps || {}, model, flow.key);
+      const result = await hideInSettings(ctx);
+      return !!result;
+    } catch (error) {
+      console.warn(`Error evaluating hideInSettings for event '${event.name || ""}' in flow '${flow.key}':`, error);
+      return false;
+    }
+  }
+  return !!hideInSettings;
+}
+__name(shouldHideEventInSettings, "shouldHideEventInSettings");
 async function shouldHideStepInSettings(model, flow, step) {
   var _a;
   if (!step) return true;
@@ -283,5 +301,6 @@ __name(resolveStepDisabledInSettings, "resolveStepDisabledInSettings");
   resolveStepDisabledInSettings,
   resolveStepUiSchema,
   resolveUiMode,
+  shouldHideEventInSettings,
   shouldHideStepInSettings
 });

package/lib/views/FlowView.d.ts

@@ -10,6 +10,11 @@
 import { PopoverProps as AntdPopoverProps } from 'antd';
 import { FlowContext } from '../flowContext';
 import { ViewNavigation } from './ViewNavigation';
+export type FlowViewBeforeClosePayload = {
+    result?: any;
+    force?: boolean;
+};
+export type FlowViewBeforeCloseHandler = (payload: FlowViewBeforeClosePayload) => Promise<boolean | void> | boolean | void;
 export type FlowView = {
     type: 'drawer' | 'popover' | 'dialog' | 'embed';
     inputArgs: any;
@@ -20,8 +25,9 @@ export type FlowView = {
     Footer: React.FC<{
         children?: React.ReactNode;
     }> | null;
-    close: (result?: any, force?: boolean) => void;
+    close: (result?: any, force?: boolean) => Promise<boolean | void> | boolean | void;
     update: (newConfig: any) => void;
+    beforeClose?: FlowViewBeforeCloseHandler;
     navigation?: ViewNavigation;
     /** 页面的销毁方法 */
     destroy?: () => void;

package/lib/views/runViewBeforeClose.d.ts

@@ -0,0 +1,10 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import type { FlowView, FlowViewBeforeClosePayload } from './FlowView';
+export declare function runViewBeforeClose(view: FlowView, payload: FlowViewBeforeClosePayload): Promise<boolean>;

package/lib/views/runViewBeforeClose.js

@@ -0,0 +1,45 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var runViewBeforeClose_exports = {};
+__export(runViewBeforeClose_exports, {
+  runViewBeforeClose: () => runViewBeforeClose
+});
+module.exports = __toCommonJS(runViewBeforeClose_exports);
+async function runViewBeforeClose(view, payload) {
+  var _a;
+  if (payload.force) {
+    return true;
+  }
+  const result = await ((_a = view.beforeClose) == null ? void 0 : _a.call(view, payload));
+  return result !== false;
+}
+__name(runViewBeforeClose, "runViewBeforeClose");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runViewBeforeClose
+});

package/lib/views/useDialog.d.ts

@@ -12,9 +12,10 @@ export declare function useDialog(): (React.JSX.Element | {
         type: "dialog";
         inputArgs: any;
         preventClose: boolean;
+        beforeClose: any;
         destroy: (result?: any) => void;
         update: (newConfig: any) => void;
-        close: (result?: any, force?: boolean) => void;
+        close: (result?: any, force?: boolean) => Promise<boolean>;
         Footer: React.FC<{
             children?: React.ReactNode;
         }>;

package/lib/views/useDialog.js

@@ -52,6 +52,7 @@ var import_viewEvents = require("./viewEvents");
 var import_provider = require("../provider");
 var import_ViewScopedFlowEngine = require("../ViewScopedFlowEngine");
 var import_variablesParams = require("../utils/variablesParams");
+var import_runViewBeforeClose = require("./runViewBeforeClose");
 let uuid = 0;
 function useDialog() {
   const holderRef = React.useRef(null);
@@ -103,12 +104,16 @@ function useDialog() {
     } else {
       ctx.addDelegate(flowContext.engine.context);
     }
+    let destroyed = false;
     const currentDialog = {
       type: "dialog",
       inputArgs: config.inputArgs || {},
       preventClose: !!config.preventClose,
+      beforeClose: void 0,
       destroy: /* @__PURE__ */ __name((result) => {
         var _a2, _b2, _c2, _d;
+        if (destroyed) return;
+        destroyed = true;
         (_a2 = config.onClose) == null ? void 0 : _a2.call(config);
         (_b2 = dialogRef.current) == null ? void 0 : _b2.destroy();
         closeFunc == null ? void 0 : closeFunc();
@@ -122,16 +127,21 @@ function useDialog() {
         var _a2;
         return (_a2 = dialogRef.current) == null ? void 0 : _a2.update(newConfig);
       }, "update"),
-      close: /* @__PURE__ */ __name((result, force) => {
+      close: /* @__PURE__ */ __name(async (result, force) => {
         var _a2, _b2;
         if (config.preventClose && !force) {
-          return;
+          return false;
+        }
+        const shouldClose = await (0, import_runViewBeforeClose.runViewBeforeClose)(currentDialog, { result, force });
+        if (!shouldClose) {
+          return false;
         }
         if (config.triggerByRouter && ((_b2 = (_a2 = config.inputArgs) == null ? void 0 : _a2.navigation) == null ? void 0 : _b2.back)) {
           config.inputArgs.navigation.back();
-          return;
+          return true;
         }
         currentDialog.destroy(result);
+        return true;
       }, "close"),
       Footer: FooterComponent,
       Header: HeaderComponent,
@@ -154,6 +164,13 @@ function useDialog() {
       get: /* @__PURE__ */ __name(() => currentDialog, "get"),
       resolveOnServer: (0, import_variablesParams.createViewRecordResolveOnServer)(ctx, () => (0, import_variablesParams.getViewRecordFromParent)(flowContext, ctx))
     });
+    scopedEngine.setDestroyView(() => {
+      var _a2, _b2;
+      if (config.triggerByRouter && ((_b2 = (_a2 = config.inputArgs) == null ? void 0 : _a2.navigation) == null ? void 0 : _b2.back)) {
+        config.inputArgs.navigation.back();
+      }
+      currentDialog.destroy();
+    });
     (0, import_createViewMeta.registerPopupVariable)(ctx, currentDialog);
     const DialogWithContext = (0, import__.observer)(
       () => {

package/lib/views/useDrawer.d.ts

@@ -13,9 +13,10 @@ export declare function useDrawer(): (React.JSX.Element | {
         type: "drawer";
         inputArgs: any;
         preventClose: boolean;
+        beforeClose: any;
         destroy: (result?: any) => void;
         update: (newConfig: any) => void;
-        close: (result?: any, force?: boolean) => void;
+        close: (result?: any, force?: boolean) => Promise<boolean>;
         Footer: React.FC<{
             children?: React.ReactNode;
         }>;

package/lib/views/useDrawer.js

@@ -52,6 +52,7 @@ var import_viewEvents = require("./viewEvents");
 var import_provider = require("../provider");
 var import_ViewScopedFlowEngine = require("../ViewScopedFlowEngine");
 var import_variablesParams = require("../utils/variablesParams");
+var import_runViewBeforeClose = require("./runViewBeforeClose");
 function useDrawer() {
   const holderRef = React.useRef(null);
   const drawerList = React.useMemo(() => import__.observable.shallow({ value: [] }), []);
@@ -122,12 +123,16 @@ function useDrawer() {
     } else {
       ctx.addDelegate(flowContext.engine.context);
     }
+    let destroyed = false;
     const currentDrawer = {
       type: "drawer",
       inputArgs: config.inputArgs || {},
       preventClose: !!config.preventClose,
+      beforeClose: void 0,
       destroy: /* @__PURE__ */ __name((result) => {
         var _a2, _b2, _c, _d;
+        if (destroyed) return;
+        destroyed = true;
         (_a2 = config.onClose) == null ? void 0 : _a2.call(config);
         (_b2 = drawerRef.current) == null ? void 0 : _b2.destroy();
         closeFunc == null ? void 0 : closeFunc();
@@ -141,16 +146,21 @@ function useDrawer() {
         var _a2;
         return (_a2 = drawerRef.current) == null ? void 0 : _a2.update(newConfig);
       }, "update"),
-      close: /* @__PURE__ */ __name((result, force) => {
+      close: /* @__PURE__ */ __name(async (result, force) => {
         var _a2, _b2;
         if (config.preventClose && !force) {
-          return;
+          return false;
+        }
+        const shouldClose = await (0, import_runViewBeforeClose.runViewBeforeClose)(currentDrawer, { result, force });
+        if (!shouldClose) {
+          return false;
         }
         if (config.triggerByRouter && ((_b2 = (_a2 = config.inputArgs) == null ? void 0 : _a2.navigation) == null ? void 0 : _b2.back)) {
           config.inputArgs.navigation.back();
-          return;
+          return true;
         }
         currentDrawer.destroy(result);
+        return true;
       }, "close"),
       Footer: FooterComponent,
       Header: HeaderComponent,
@@ -173,6 +183,13 @@ function useDrawer() {
       get: /* @__PURE__ */ __name(() => currentDrawer, "get"),
       resolveOnServer: (0, import_variablesParams.createViewRecordResolveOnServer)(ctx, () => (0, import_variablesParams.getViewRecordFromParent)(flowContext, ctx))
     });
+    scopedEngine.setDestroyView(() => {
+      var _a2, _b2;
+      if (config.triggerByRouter && ((_b2 = (_a2 = config.inputArgs) == null ? void 0 : _a2.navigation) == null ? void 0 : _b2.back)) {
+        config.inputArgs.navigation.back();
+      }
+      currentDrawer.destroy();
+    });
     (0, import_createViewMeta.registerPopupVariable)(ctx, currentDrawer);
     const DrawerWithContext = React.memo(
       (0, import__.observer)((props) => {

package/lib/views/usePage.d.ts

@@ -16,9 +16,10 @@ export declare function usePage(): (React.JSX.Element | {
         type: "embed";
         inputArgs: any;
         preventClose: boolean;
+        beforeClose: any;
         destroy: (result?: any) => void;
         update: (newConfig: any) => void;
-        close: (result?: any, force?: boolean) => void;
+        close: (result?: any, force?: boolean) => Promise<boolean>;
         Header: React.FC<{
             title?: React.ReactNode;
             extra?: React.ReactNode;

package/lib/views/usePage.js

@@ -54,6 +54,7 @@ var import_viewEvents = require("./viewEvents");
 var import_provider = require("../provider");
 var import_ViewScopedFlowEngine = require("../ViewScopedFlowEngine");
 var import_variablesParams = require("../utils/variablesParams");
+var import_runViewBeforeClose = require("./runViewBeforeClose");
 let uuid = 0;
 const GLOBAL_EMBED_CONTAINER_ID = "nocobase-embed-container";
 const EMBED_REPLACING_DATA_KEY = "nocobaseEmbedReplacing";
@@ -131,6 +132,7 @@ function usePage() {
       type: "embed",
       inputArgs: viewInputArgs,
       preventClose: !!config.preventClose,
+      beforeClose: void 0,
       destroy: /* @__PURE__ */ __name((result) => {
         var _a2, _b2, _c2, _d, _e;
         (_a2 = config.onClose) == null ? void 0 : _a2.call(config);
@@ -152,16 +154,21 @@ function usePage() {
         var _a2;
         return (_a2 = pageRef.current) == null ? void 0 : _a2.update(newConfig);
       }, "update"),
-      close: /* @__PURE__ */ __name((result, force) => {
+      close: /* @__PURE__ */ __name(async (result, force) => {
         var _a2, _b2;
         if (preventClose && !force) {
-          return;
+          return false;
+        }
+        const shouldClose = await (0, import_runViewBeforeClose.runViewBeforeClose)(currentPage, { result, force });
+        if (!shouldClose) {
+          return false;
         }
         if (config.triggerByRouter && ((_b2 = (_a2 = config.inputArgs) == null ? void 0 : _a2.navigation) == null ? void 0 : _b2.back)) {
           config.inputArgs.navigation.back();
-          return;
+          return true;
         }
         currentPage.destroy(result);
+        return true;
       }, "close"),
       Header: HeaderComponent,
       Footer: FooterComponent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.1.0-beta.1",
+  "version": "2.1.0-beta.11",
   "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.1.0-beta.1",
-    "@nocobase/shared": "2.1.0-beta.1",
+    "@nocobase/sdk": "2.1.0-beta.11",
+    "@nocobase/shared": "2.1.0-beta.11",
     "ahooks": "^3.7.2",
     "dayjs": "^1.11.9",
     "dompurify": "^3.0.2",
@@ -35,6 +35,6 @@
     "workflow"
   ],
   "author": "NocoBase Team",
-  "license": "AGPL-3.0",
-  "gitHead": "de3efeb357b6a98b813f1c14831afa832aed1780"
+  "license": "Apache-2.0",
+  "gitHead": "b02e78b928f476d848b88bc545d3acddca00fe3c"
 }

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/ViewScopedFlowEngine.ts

@@ -62,6 +62,10 @@ export function createViewScopedEngine(parent: FlowEngine): FlowEngine {
     '_nextEngine',
     // getModel 需要在本地执行以确保全局查找时正确遍历整个引擎栈
     'getModel',
+    // 视图销毁回调需要在本地存储，每个视图引擎有自己的销毁逻辑
+    '_destroyView',
+    'setDestroyView',
+    'destroyView',
   ]);
 
   const handler: ProxyHandler<FlowEngine> = {

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;