@nocobase/flow-engine 2.0.0-beta.2 → 2.0.0-beta.20

package/src/scheduler/ModelOperationScheduler.ts

@@ -36,6 +36,8 @@ export interface LifecycleEvent {
   error?: any;
   inputArgs?: Record<string, any>;
   result?: any;
+  flowKey?: string;
+  stepKey?: string;
 }
 
 type ScheduledItem = {
@@ -162,37 +164,37 @@ export class ModelOperationScheduler {
     const emitter = this.engine.emitter;
     if (!emitter || typeof emitter.on !== 'function') return;
 
-    const onCreated = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'created' });
+    const onCreated = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'created' });
     };
     emitter.on('model:created', onCreated);
     this.unbindHandlers.push(() => emitter.off('model:created', onCreated));
 
-    const onMounted = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'mounted' });
+    const onMounted = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'mounted' });
     };
     emitter.on('model:mounted', onMounted);
     this.unbindHandlers.push(() => emitter.off('model:mounted', onMounted));
 
-    const onGenericBeforeStart = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:start' });
+    const onGenericBeforeStart = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:start' });
     };
     emitter.on('model:event:beforeRender:start', onGenericBeforeStart);
     this.unbindHandlers.push(() => emitter.off('model:event:beforeRender:start', onGenericBeforeStart));
 
-    const onGenericBeforeEnd = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:end' });
+    const onGenericBeforeEnd = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:end' });
     };
     emitter.on('model:event:beforeRender:end', onGenericBeforeEnd);
     this.unbindHandlers.push(() => emitter.off('model:event:beforeRender:end', onGenericBeforeEnd));
 
-    const onUnmounted = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'unmounted' });
+    const onUnmounted = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'unmounted' });
     };
     emitter.on('model:unmounted', onUnmounted);
     this.unbindHandlers.push(() => emitter.off('model:unmounted', onUnmounted));
 
-    const onDestroyed = (e: LifecycleEvent) => {
+    const onDestroyed = async (e: LifecycleEvent) => {
       const targetBucket = this.itemsByTargetUid.get(e.uid);
       const event = { ...e, type: 'destroyed' as const };
       if (targetBucket && targetBucket.size) {
@@ -201,7 +203,7 @@ export class ModelOperationScheduler {
           const it = this.itemsById.get(id);
           if (!it) continue;
           if (this.shouldTrigger(it.options.when, event)) {
-            void this.tryExecuteOnce(id, event);
+            await this.tryExecuteOnce(id, event);
           } else {
             this.internalCancel(id);
           }
@@ -220,14 +222,14 @@ export class ModelOperationScheduler {
     if (this.subscribedEventNames.has(name)) return;
     this.subscribedEventNames.add(name);
     const emitter = this.engine.emitter;
-    const onStart = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:start` as const });
+    const onStart = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:start` as LifecycleType });
     };
-    const onEnd = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:end` as const });
+    const onEnd = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:end` as LifecycleType });
     };
-    const onError = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:error` as const });
+    const onError = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:error` as LifecycleType });
     };
     emitter.on(`model:event:${name}:start`, onStart);
     emitter.on(`model:event:${name}:end`, onEnd);
@@ -239,12 +241,12 @@ export class ModelOperationScheduler {
 
   private parseEventWhen(when?: ScheduleWhen): { name: string; phase: 'start' | 'end' | 'error' } | null {
     if (!when || typeof when !== 'string') return null;
-    const m = /^event:([^:]+):(start|end|error)$/.exec(when);
+    const m = /^event:(.+):(start|end|error)$/.exec(when);
     if (!m) return null;
     return { name: m[1], phase: m[2] as 'start' | 'end' | 'error' };
   }
 
-  private processLifecycleEvent(targetUid: string, event: LifecycleEvent) {
+  private async processLifecycleEvent(targetUid: string, event: LifecycleEvent) {
     const targetBucket = this.itemsByTargetUid.get(targetUid);
     if (!targetBucket || targetBucket.size === 0) return;
     const ids = Array.from(targetBucket.keys());
@@ -253,7 +255,7 @@ export class ModelOperationScheduler {
       if (!item) continue;
       const should = this.shouldTrigger(item.options.when, event);
       if (!should) continue;
-      void this.tryExecuteOnce(id, event);
+      await this.tryExecuteOnce(id, event);
     }
   }
 

package/src/types.ts

@@ -213,12 +213,37 @@ export type FlowEventName =
   // fallback to any string for extensibility
   | (string & {});
 
+/**
+ * 事件流的执行时机（phase）。
+ *
+ * 说明：
+ * - 缺省（phase 未配置）表示保持现有行为；
+ * - 当配置了 phase 时，运行时会将其映射为 `scheduleModelOperation` 的 `when` 锚点；
+ * - phase 同时适用于动态事件流（实例级）与静态流（内置）。
+ */
+export type FlowEventPhase =
+  | 'beforeAllFlows'
+  | 'afterAllFlows'
+  | 'beforeFlow'
+  | 'afterFlow'
+  | 'beforeStep'
+  | 'afterStep';
+
 /**
  * Flow 事件类型（供 FlowDefinitionOptions.on 使用）。
  */
 export type FlowEvent<TModel extends FlowModel = FlowModel> =
   | FlowEventName
-  | { eventName: FlowEventName; defaultParams?: Record<string, any> };
+  | {
+      eventName: FlowEventName;
+      defaultParams?: Record<string, any>;
+      /** 动态事件流的执行时机（默认 beforeAllFlows） */
+      phase?: FlowEventPhase;
+      /** phase 为 beforeFlow/afterFlow/beforeStep/afterStep 时使用 */
+      flowKey?: string;
+      /** phase 为 beforeStep/afterStep 时使用 */
+      stepKey?: string;
+    };
 
 /**
  * 事件分发选项。

package/src/utils/__tests__/params-resolvers.test.ts

@@ -491,6 +491,46 @@ describe('resolveExpressions', () => {
         ],
       });
     });
+
+    test('should resolve dot-only path with dashed keys', async () => {
+      ctx.defineProperty('formValues', {
+        value: {
+          'oho-test': {
+            'o2m-users': [1, 2],
+          },
+        },
+      });
+
+      const params = '{{ctx.formValues.oho-test.o2m-users}}';
+
+      const result = await resolveExpressions(params, ctx);
+
+      expect(result).toEqual([1, 2]);
+    });
+
+    test('should resolve dashed keys inside template strings', async () => {
+      ctx.defineProperty('formValues', {
+        value: {
+          'oho-test': {
+            'o2m-users': 'X',
+          },
+        },
+      });
+
+      const params = 'prefix {{ctx.formValues.oho-test.o2m-users}} suffix';
+
+      const result = await resolveExpressions(params, ctx);
+
+      expect(result).toEqual('prefix X suffix');
+    });
+
+    test('should not treat subtraction as dashed key path', async () => {
+      const params = '{{ctx.aa.bb-ctx.cc}}';
+
+      const result = await resolveExpressions(params, ctx);
+
+      expect(result).toEqual(5);
+    });
   });
 
   // 测试高级功能：多表达式模板字符串

package/src/utils/__tests__/runjsRequireAsyncAutoWhitelist.test.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 { beforeEach, describe, expect, it } from 'vitest';
+import { runjsRequireAsync } from '../runjsModuleLoader';
+import { __resetRunJSSafeGlobalsRegistryForTests, createSafeWindow } from '../safeGlobals';
+
+beforeEach(() => {
+  __resetRunJSSafeGlobalsRegistryForTests();
+});
+
+describe('runjsRequireAsync auto whitelist', () => {
+  it('should allow safeWindow to access globals introduced during requireAsync', async () => {
+    const key = '__nb_require_async_added_global__';
+    delete (window as any)[key];
+
+    const safeWin: any = createSafeWindow();
+    expect(() => safeWin[key]).toThrow(/not allowed/);
+
+    const requirejs: any = (deps: string[], onLoad: (...args: any[]) => void) => {
+      // Simulate a remote library attaching itself to the real window.
+      (window as any)[key] = { ok: true };
+      onLoad(undefined);
+    };
+
+    await runjsRequireAsync(requirejs, 'https://example.com/fake-lib.js');
+
+    expect(safeWin[key]).toEqual({ ok: true });
+
+    delete (window as any)[key];
+  });
+});

package/src/utils/__tests__/runjsTemplateCompat.test.ts

@@ -0,0 +1,159 @@
+/**
+ * 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 { describe, it, expect, vi } from 'vitest';
+import * as jsxTransform from '../../utils/jsxTransform';
+import { prepareRunJsCode, preprocessRunJsTemplates } from '../runjsTemplateCompat';
+
+describe('runjsTemplateCompat', () => {
+  describe('preprocessRunJsTemplates', () => {
+    it('hoists bare {{ }} placeholders into top-level resolved vars', () => {
+      const src = `const a = {{ctx.user.id}};`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`const a = __runjs_ctx_tpl_0;`);
+    });
+
+    it('replaces string literals containing {{ }} via split/join, without injecting await into nested functions', () => {
+      const src = `const s = '{{ctx.user.id}}';`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`__runjs_templateValueToString(__runjs_ctx_tpl_0, "{{ctx.user.id}}")`);
+      expect(out).toContain(`.split("{{ctx.user.id}}").join(`);
+    });
+
+    it('does not transform arguments inside explicit ctx.resolveJsonTemplate(...) call', () => {
+      const src = `const v = await ctx.resolveJsonTemplate('{{ctx.user.id}}');\nconst s = '{{ctx.user.id}}';`;
+      const out = preprocessRunJsTemplates(src);
+      // inside call: keep raw
+      expect(out).toContain(`await ctx.resolveJsonTemplate('{{ctx.user.id}}')`);
+      // outside call: transform
+      expect(out).toContain(`__runjs_templateValueToString(__runjs_ctx_tpl_0, "{{ctx.user.id}}")`);
+    });
+
+    it('keeps template markers in comments unchanged', () => {
+      const src = `// {{ctx.user.id}}\nconst a = 1;`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toBe(src);
+    });
+
+    it('supports template literals containing {{ }}', () => {
+      const src = 'const s = `hi {{ctx.user.name}}`;';
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.name}}");`);
+      expect(out).toContain(`\`hi {{ctx.user.name}}\``);
+      expect(out).toContain(`.split("{{ctx.user.name}}").join(`);
+    });
+
+    it('does not rewrite non-ctx {{ }} patterns (e.g. JSX style object) while still rewriting ctx placeholders', () => {
+      const src = `const id = {{ctx.user.id}};\nctx.render(<div style={{ width: '100%' }} />);`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`style={{ width: '100%' }}`);
+      expect(out).not.toContain(`resolveJsonTemplate("{{ width: '100%' }}")`);
+    });
+
+    it('avoids injecting await into non-async nested function bodies', () => {
+      const src = `
+function f() {
+  return {{ctx.user.id}};
+}
+return f();
+`.trim();
+      const out = preprocessRunJsTemplates(src);
+      // The only await should be in the top-level preamble
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`return __runjs_ctx_tpl_0;`);
+      expect(out).not.toContain(`return (await ctx.resolveJsonTemplate`);
+    });
+
+    it('is tolerant to already-preprocessed code (idempotent heuristic)', () => {
+      const src =
+        `const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");\n` +
+        `const s = ("{{ctx.user.id}}").split("{{ctx.user.id}}").join(__runjs_templateValueToString(__runjs_ctx_tpl_0, "{{ctx.user.id}}"));`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toBe(src);
+    });
+
+    it('rewrites object literal string keys via computed property to keep syntax valid', () => {
+      const src = `const o = { '{{ctx.user.id}}': 1 };`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`{ [`);
+      expect(out).toContain(`]: 1 }`);
+      expect(out).toContain(`.split("{{ctx.user.id}}").join(`);
+    });
+  });
+
+  describe('prepareRunJsCode', () => {
+    it('preprocesses templates and compiles JSX', async () => {
+      const src = `
+const name = '{{ctx.user.name}}';
+ctx.render(<div className="x">{name}</div>);
+`.trim();
+      const out = await prepareRunJsCode(src, { preprocessTemplates: true });
+      expect(out).toMatch(/ctx\.React\.createElement/);
+      expect(out).toMatch(/ctx\.resolveJsonTemplate/);
+    });
+
+    it('injects ctx.libs ensure preamble for member access', async () => {
+      const src = `return ctx.libs.lodash;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`/* __runjs_ensure_libs */`);
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('injects ctx.libs ensure preamble for bracket access with string literal', async () => {
+      const src = `return ctx.libs['lodash'];`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('injects ctx.libs ensure preamble for object destructuring', async () => {
+      const src = `const { lodash } = ctx.libs;\nreturn lodash;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('does not inject ctx.libs preamble when ctx.libs only appears in string/comment', async () => {
+      const src = `// ctx.libs.lodash\nconst s = "ctx.libs.lodash";\nreturn s;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).not.toContain(`__runjs_ensure_libs`);
+    });
+
+    it('is idempotent for already-prepared code', async () => {
+      const src = `return ctx.libs['lodash'];`;
+      const out1 = await prepareRunJsCode(src, { preprocessTemplates: false });
+      const out2 = await prepareRunJsCode(out1, { preprocessTemplates: false });
+      expect(out2).toBe(out1);
+      expect(out2.match(/__runjs_ensure_libs/g)?.length ?? 0).toBe(1);
+    });
+
+    it('does not break JSX attribute string values when preprocessing templates', async () => {
+      const src = `ctx.render(<Input title="{{ctx.user.name}}" />);`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: true });
+      expect(out).toMatch(/ctx\.React\.createElement/);
+      expect(out).toMatch(/title:\s*\(/);
+      expect(out).toContain(`.split("{{ctx.user.name}}").join(`);
+    });
+
+    it('caches prepared code by source and preprocessTemplates option', async () => {
+      const spy = vi.spyOn(jsxTransform, 'compileRunJs');
+      const src = `/* cache-test */\nconst a = 1;\nreturn a;`;
+
+      await prepareRunJsCode(src, { preprocessTemplates: false });
+      await prepareRunJsCode(src, { preprocessTemplates: false });
+      await prepareRunJsCode(src, { preprocessTemplates: true });
+      await prepareRunJsCode(src, { preprocessTemplates: true });
+
+      expect(spy).toHaveBeenCalledTimes(2);
+      spy.mockRestore();
+    });
+  });
+});

package/src/utils/__tests__/safeGlobals.test.ts

@@ -7,8 +7,19 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, expect, it } from 'vitest';
-import { createSafeDocument, createSafeWindow, createSafeNavigator } from '../safeGlobals';
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  __resetRunJSSafeGlobalsRegistryForTests,
+  createSafeDocument,
+  createSafeNavigator,
+  createSafeWindow,
+  registerRunJSSafeDocumentGlobals,
+  registerRunJSSafeWindowGlobals,
+} from '../safeGlobals';
+
+beforeEach(() => {
+  __resetRunJSSafeGlobalsRegistryForTests();
+});
 
 describe('safeGlobals', () => {
   it('createSafeWindow exposes only allowed globals and extras', () => {
@@ -21,6 +32,24 @@ describe('safeGlobals', () => {
     expect(() => win.location.href).toThrow(/not allowed/);
   });
 
+  it('createSafeWindow allows writing new props and reading them back', () => {
+    const win: any = createSafeWindow();
+    win.someLib = { ok: true };
+    expect(win.someLib).toEqual({ ok: true });
+    expect('someLib' in win).toBe(true);
+  });
+
+  it('createSafeWindow can access dynamically registered globals from real window', () => {
+    const key = '__nb_safe_window_global__';
+    (window as any)[key] = { v: 1 };
+    registerRunJSSafeWindowGlobals([key]);
+
+    const win: any = createSafeWindow();
+    expect(win[key]).toEqual({ v: 1 });
+
+    delete (window as any)[key];
+  });
+
   it('createSafeDocument exposes whitelisted methods and extras', () => {
     const doc: any = createSafeDocument({ bar: true });
     expect(typeof doc.createElement).toBe('function');
@@ -28,6 +57,24 @@ describe('safeGlobals', () => {
     expect(() => doc.cookie).toThrow(/not allowed/);
   });
 
+  it('createSafeDocument allows writing new props and reading them back', () => {
+    const doc: any = createSafeDocument();
+    doc.someLib = { ok: true };
+    expect(doc.someLib).toEqual({ ok: true });
+    expect('someLib' in doc).toBe(true);
+  });
+
+  it('createSafeDocument can access dynamically registered globals from real document', () => {
+    const key = '__nb_safe_document_global__';
+    (document as any)[key] = 123;
+    registerRunJSSafeDocumentGlobals([key]);
+
+    const doc: any = createSafeDocument();
+    expect(doc[key]).toBe(123);
+
+    delete (document as any)[key];
+  });
+
   it('createSafeNavigator exposes limited props and guards others', () => {
     const nav: any = createSafeNavigator();
     // clipboard object should always exist

package/src/utils/createCollectionContextMeta.ts

@@ -88,6 +88,7 @@ function createMetaBaseProperties(field: CollectionField) {
   return {
     title: field.title || field.name,
     interface: field.interface,
+    options: field.options,
     uiSchema: field.uiSchema || {},
   };
 }

package/src/utils/index.ts

@@ -63,9 +63,15 @@ export { parsePathnameToViewParams, type ViewParam } from './parsePathnameToView
 // 安全全局对象（window/document）
 export { createSafeDocument, createSafeWindow, createSafeNavigator } from './safeGlobals';
 
+// RunJS 代码兼容预处理（{{ }}）与 JSX 编译
+export { prepareRunJsCode, preprocessRunJsTemplates } from './runjsTemplateCompat';
+
 // Ephemeral context helper（用于临时注入属性/方法，避免污染父级 ctx）
 export { createEphemeralContext } from './createEphemeralContext';
 
 // Filter helpers
 export { pruneFilter } from './pruneFilter';
 export { isBeforeRenderFlow } from './flows';
+
+// Module URL resolver
+export { resolveModuleUrl, isCssFile } from './resolveModuleUrl';

package/src/utils/params-resolvers.ts

@@ -409,8 +409,13 @@ export async function preprocessExpression(expression: string, ctx: FlowContext)
 async function compileExpression<TModel extends FlowModel = FlowModel>(expression: string, ctx: FlowContext) {
   // 仅点号路径匹配：ctx.a.b.c（不支持括号/函数/索引），用于数组聚合取值
   const matchDotOnly = (expr: string): string | null => {
-    const m = expr.trim().match(/^ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*(?:\.[a-zA-Z_$][a-zA-Z0-9_$]*)*)$/);
-    return m ? m[1] : null;
+    // 顶层变量名仍使用 JS 标识符规则（与 ctx.defineProperty 保持一致）；
+    // 子路径允许包含 '-'（例如 formValues.oho-test.o2m-users）。
+    const m = expr
+      .trim()
+      .match(/^ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\.([a-zA-Z_$][a-zA-Z0-9_$-]*(?:\.[a-zA-Z_$][a-zA-Z0-9_$-]*)*))?$/);
+    if (!m) return null;
+    return m[2] ? `${m[1]}.${m[2]}` : m[1];
   };
 
   // 基于 getValuesByPath 的聚合取值：支持数组扁平化，仅支持 '.' 访问
@@ -423,6 +428,20 @@ async function compileExpression<TModel extends FlowModel = FlowModel>(expressio
     return getValuesByPath(base as object, segs.join('.'));
   };
 
+  const resolveInnerExpression = async (innerExpr: string): Promise<any> => {
+    const dotPath = matchDotOnly(innerExpr);
+    if (dotPath) {
+      const resolved = await resolveDotOnlyPath(dotPath);
+      // 当 dotPath 含 '-' 时可能与减号运算符存在歧义，例如：ctx.aa.bb-ctx.cc。
+      // 若按 path 解析未取到值，则回退到 JS 表达式解析，尽量保持兼容。
+      if (resolved === undefined && dotPath.includes('-')) {
+        return await processExpression(innerExpr, ctx);
+      }
+      return resolved;
+    }
+    return await processExpression(innerExpr, ctx);
+  };
+
   /**
    * 单个表达式模式匹配
    *
@@ -443,11 +462,7 @@ async function compileExpression<TModel extends FlowModel = FlowModel>(expressio
   const singleMatch = expression.match(/^\s*\{\{\s*([^{}]+?)\s*\}\}\s*$/);
   if (singleMatch) {
     const inner = singleMatch[1];
-    const dotPath = matchDotOnly(inner);
-    if (dotPath) {
-      return await resolveDotOnlyPath(dotPath);
-    }
-    return await processExpression(inner, ctx);
+    return await resolveInnerExpression(inner);
   }
 
   /**
@@ -470,8 +485,7 @@ async function compileExpression<TModel extends FlowModel = FlowModel>(expressio
   let result = expression;
 
   for (const [fullMatch, innerExpr] of matches) {
-    const dotPath = matchDotOnly(innerExpr);
-    const value = dotPath ? await resolveDotOnlyPath(dotPath) : await processExpression(innerExpr, ctx);
+    const value = await resolveInnerExpression(innerExpr);
     if (value !== undefined) {
       const replacement = typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
       result = result.replace(fullMatch, replacement);

package/src/utils/resolveModuleUrl.ts

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+
+/**
+ * 解析模块 URL，将相对路径转换为完整的 CDN URL
+ *
+ * @param url - 模块地址（支持相对路径或完整 URL）
+ * @param options - 可选配置
+ * @param options.addSuffix - 是否添加 ESM_CDN_SUFFIX 后缀（如 `+esm`），默认为 `true`
+ * @returns 解析后的完整 URL
+ *
+ * @example
+ * ```ts
+ * // 相对路径会被拼接上 CDN 前缀和后缀（默认添加）
+ * // 如果使用 esm.sh（默认），不需要后缀
+ * resolveModuleUrl('vue@3.4.0')
+ * // => 'https://esm.sh/vue@3.4.0'
+ *
+ * // 如果使用 jsdelivr，需要配置 ESM_CDN_SUFFIX='/+esm'
+ * // resolveModuleUrl('vue@3.4.0') => 'https://cdn.jsdelivr.net/npm/vue@3.4.0/+esm'
+ *
+ * // 不添加后缀（适用于 UMD 库或 CSS 文件）
+ * resolveModuleUrl('vue@3.4.0', { addSuffix: false })
+ * // => 'https://esm.sh/vue@3.4.0' (即使配置了 suffix 也不会添加)
+ *
+ * // 原始 URL（适用于 UMD 库）
+ * resolveModuleUrl('lodash@4.17.21/lodash.js', { raw: true })
+ * // => 'https://esm.sh/lodash@4.17.21/lodash.js?raw' (即使配置了 suffix 也不会添加)
+ *
+ * // 完整 URL 保持不变
+ * resolveModuleUrl('https://cdn.jsdelivr.net/npm/vue@3.4.0')
+ * // => 'https://cdn.jsdelivr.net/npm/vue@3.4.0'
+ * ```
+ */
+export function resolveModuleUrl(url: string, options?: { addSuffix?: boolean; raw?: boolean }): string {
+  if (!url || typeof url !== 'string') {
+    throw new Error('invalid url');
+  }
+
+  const u = url.trim();
+
+  // 如果是完整 URL（http:// 或 https://），直接返回
+  if (u.startsWith('http://') || u.startsWith('https://')) {
+    return u;
+  }
+
+  // 相对路径：拼接 CDN 前缀和后缀
+  const ESM_CDN_BASE_URL = (window as any)['__esm_cdn_base_url__'] || 'https://esm.sh';
+  const ESM_CDN_SUFFIX = options?.addSuffix ? (window as any)['__esm_cdn_suffix__'] || '' : '';
+
+  // 移除 base URL 末尾的斜杠，移除相对路径开头的斜杠
+  const base = ESM_CDN_BASE_URL.replace(/\/$/, '');
+  const path = u.replace(/^\//, '');
+
+  if (options?.raw) {
+    const sep = path.includes('?') ? '&' : '?';
+    return `${base}/${path}${sep}raw`;
+  }
+
+  return `${base}/${path}${ESM_CDN_SUFFIX}`;
+}
+
+/**
+ * 判断 URL 是否为 CSS 文件
+ *
+ * @param url - 文件 URL（支持带 query 和 hash，如 `example.css?v=123`）
+ * @returns 如果是 CSS 文件返回 `true`，否则返回 `false`
+ *
+ * @example
+ * ```ts
+ * isCssFile('style.css') // => true
+ * isCssFile('style.css?v=123') // => true
+ * isCssFile('style.css#section') // => true
+ * isCssFile('script.js') // => false
+ * ```
+ */
+export function isCssFile(url: string): boolean {
+  if (!url || typeof url !== 'string') {
+    return false;
+  }
+
+  // 去掉 query 和 hash 后判断文件扩展名
+  const pathPart = url.split('?')[0].split('#')[0];
+  return pathPart.endsWith('.css');
+}