@nocobase/flow-engine 2.0.0-alpha.2

package/src/runjs-context/contexts/FlowRunJSContext.ts

@@ -0,0 +1,190 @@
+/**
+ * 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 { FlowContext } from '../../flowContext';
+import * as antd from 'antd';
+import React from 'react';
+import * as ReactDOMClient from 'react-dom/client';
+
+export type RunJSVersion = 'v1' | (string & {});
+export type RunJSContextCtor = new (delegate: FlowContext) => FlowRunJSContext;
+
+export type RunJSDocMeta = {
+  label?: string;
+  properties?: Record<string, any>;
+  methods?: Record<string, any>;
+  snipastes?: Record<string, any>;
+};
+
+const classMeta = new WeakMap<Function, RunJSDocMeta>();
+const classDocCache = new WeakMap<Function, RunJSDocMeta>();
+
+function deepMerge(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 = deepMerge(base?.[k], patch[k]);
+    if (typeof v === 'undefined') delete out[k];
+    else out[k] = v;
+  }
+  return out;
+}
+
+export class FlowRunJSContext {
+  protected _delegate: FlowContext;
+  [key: string]: any;
+  static allow?: { keys?: ReadonlyArray<string>; facades?: Record<string, ReadonlyArray<string>> };
+
+  constructor(delegate: FlowContext) {
+    this._delegate = delegate;
+    const self = this as any;
+    // 常用前端依赖直接注入
+    self.React = React;
+    self.react = React;
+    self.antd = antd;
+    self.ReactDOM = ReactDOMClient;
+    // 公共方法：分发模型事件
+    self.dispatchModelEvent = async (modelOrUid: any, eventName: string, inputArgs?: Record<string, any>) => {
+      let model: any = null;
+      const engine = (this._delegate as any).engine;
+      if (typeof modelOrUid === 'string') {
+        model = await engine?.loadModel?.({ uid: modelOrUid });
+      } else if (modelOrUid && typeof modelOrUid === 'object' && typeof modelOrUid.dispatchEvent === 'function') {
+        model = modelOrUid;
+      }
+      if (model) {
+        model.context?.addDelegate?.(self);
+        model.dispatchEvent(eventName, {
+          navigation: false,
+          ...(self.model?.['getInputArgs']?.() || {}),
+          ...(inputArgs || {}),
+        });
+      } else {
+        self.message?.error?.(
+          self.t?.('Model with ID {{uid}} not found', { uid: String(modelOrUid) }) || 'Model not found',
+        );
+      }
+    };
+
+    // 显式暴露：基础属性（只读 getter 映射到委托）
+    this.#exposeProps([
+      'message',
+      'notification',
+      'logger',
+      'resource',
+      'urlSearchParams',
+      'token',
+      'role',
+      'auth',
+      'api',
+      'ref',
+      'model',
+    ]);
+    // 显式暴露：基础方法（绑定到委托）
+    this.#exposeMethods(['t', 'requireAsync', 'copyToClipboard', 'resolveJsonTemplate', 'runAction', 'onRefReady']);
+  }
+
+  // 供子类/外部一致使用的定义 API（与 FlowContext 的接口保持一致风格）
+  defineProperty(key: string, options: { get?: (ctx: any) => any; value?: any }) {
+    if (options && typeof options.get === 'function') {
+      Object.defineProperty(this, key, {
+        configurable: true,
+        enumerable: true,
+        get: () => options.get?.(this),
+      });
+      return;
+    }
+    Object.defineProperty(this, key, {
+      configurable: true,
+      enumerable: true,
+      writable: false,
+      value: options?.value,
+    });
+  }
+  defineMethod(name: string, fn: (...args: any[]) => any) {
+    Object.defineProperty(this, name, {
+      configurable: true,
+      enumerable: false,
+      writable: false,
+      value: fn.bind(this),
+    });
+  }
+
+  // 工具：将委托上的属性以 getter 暴露
+  #exposeProps(names: string[]) {
+    for (const k of names) {
+      if (Object.prototype.hasOwnProperty.call(this, k)) continue;
+      this.defineProperty(k, { get: () => (this._delegate as any)[k] });
+    }
+  }
+  // 工具：将委托上的同名方法绑定暴露
+  #exposeMethods(names: string[]) {
+    for (const k of names) {
+      if (Object.prototype.hasOwnProperty.call(this, k)) continue;
+      const src = (this._delegate as any)[k];
+      if (typeof src === 'function') {
+        this.defineMethod(k, src.bind(this._delegate));
+      }
+    }
+  }
+
+  static injectDefaultGlobals?(): { window?: any; document?: any } | void;
+
+  static define(meta: RunJSDocMeta) {
+    const prev = classMeta.get(this) || {};
+    classMeta.set(this, deepMerge(prev, meta));
+    classDocCache.delete(this);
+  }
+
+  static getDoc(): RunJSDocMeta {
+    const self = this as any;
+    if (classDocCache.has(self)) return classDocCache.get(self)!;
+    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 = deepMerge(merged, classMeta.get(cls) || {});
+    classDocCache.set(self, merged);
+    return merged;
+  }
+}
+
+// Define base doc on FlowRunJSContext itself
+FlowRunJSContext.define({
+  label: 'RunJS base',
+  properties: {
+    t: "国际化函数。示例：`ctx.t('Hello {name}', { name: 'World' })`",
+    logger: "Pino logger 子实例。`ctx.logger.info({ foo: 1 }, 'msg')`",
+    message: "AntD 全局消息。`ctx.message.success('done')`",
+    notification: "AntD 通知。`ctx.notification.open({ message: 'Hi' })`",
+    requireAsync: '异步加载外部库。`const x = await ctx.requireAsync(url)`',
+    copyToClipboard: '复制文本到剪贴板。`await ctx.copyToClipboard(text)`',
+    resolveJsonTemplate: '解析含 {{ }} 的模板/表达式',
+    runAction: '运行当前模型动作。`await ctx.runAction(name, params)`',
+    resource: '数据资源（按委托可见）',
+    urlSearchParams: 'URL 查询参数对象',
+    token: 'API Token',
+    role: '当前角色',
+    auth: '认证信息（locale/role/user/token）',
+    api: 'APIClient 实例',
+    React: 'React 命名空间（RunJS 环境可用）',
+    react: 'React 别名（小写）',
+    ReactDOM: 'ReactDOM 客户端（含 createRoot）',
+    antd: 'AntD 组件库（RunJS 环境可用）',
+  },
+  methods: {
+    dispatchModelEvent: "触发模型事件：`await ctx.dispatchModelEvent(modelUid, 'click', { ... })`",
+  },
+});

package/src/runjs-context/contexts/FormJSFieldItemRunJSContext.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { FlowRunJSContext } from './FlowRunJSContext';
+import { createSafeDocument, createSafeWindow } from '../../utils';
+
+export class FormJSFieldItemRunJSContext extends FlowRunJSContext {
+  static injectDefaultGlobals() {
+    return { window: createSafeWindow(), document: createSafeDocument() };
+  }
+  constructor(delegate: any) {
+    super(delegate);
+    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
+    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
+    this.defineProperty('value', { get: () => (this as any)._delegate['value'] });
+  }
+}
+
+FormJSFieldItemRunJSContext.define({
+  label: 'FormJSFieldItem RunJS context',
+  properties: {
+    element: 'ElementProxy，表单字段容器',
+    value: '字段值（读/受控场景需通过 setProps 修改）',
+    record: '当前记录（只读）',
+  },
+  methods: {
+    onRefReady: '容器就绪回调',
+    setProps: '设置表单项属性：`setProps(fieldModel, { value })`（由联动/表单上下文提供）',
+  },
+  snipastes: {
+    显示字段值: { $ref: 'scene/jsfield/innerHTML-value', prefix: 'sn-form-value' },
+  },
+});

package/src/runjs-context/contexts/JSBlockRunJSContext.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 { FlowRunJSContext } from './FlowRunJSContext';
+import { createSafeDocument, createSafeWindow } from '../../utils';
+
+export class JSBlockRunJSContext extends FlowRunJSContext {
+  static injectDefaultGlobals() {
+    return { window: createSafeWindow(), document: createSafeDocument() };
+  }
+  constructor(delegate: any) {
+    super(delegate);
+    // 显式暴露本场景所需属性
+    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
+    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
+    this.defineProperty('value', { get: () => (this as any)._delegate['value'] });
+  }
+}
+
+JSBlockRunJSContext.define({
+  label: 'JSBlock RunJS context',
+  properties: {
+    element: 'ElementProxy，安全 DOM 容器。支持 innerHTML/append 等',
+    record: '当前记录（只读，存在于数据块/详情等场景）',
+    value: '当前值（若存在）',
+    React: 'React（已注入）',
+    antd: 'AntD（已注入）',
+  },
+  methods: {
+    onRefReady: 'Container ref ready callback:\n```js\nctx.onRefReady(ctx.ref, el => { /* ... */ })\n```',
+    requireAsync: 'Load external library: `const lib = await ctx.requireAsync(url)`',
+  },
+  snipastes: {
+    'Render HTML': { $ref: 'scene/jsblock/render-basic', prefix: 'sn-jsb-html' },
+    'Render React': { $ref: 'scene/jsblock/render-react', prefix: 'sn-jsb-react' },
+    'Init ECharts': { $ref: 'libs/echarts-init', prefix: 'sn-echarts' },
+    'Render card': { $ref: 'scene/jsblock/render-card', prefix: 'sn-jsb-card' },
+    'Button handler': { $ref: 'scene/jsblock/render-button-handler', prefix: 'sn-jsb-button' },
+    'JSX mount': { $ref: 'scene/jsblock/jsx-mount', prefix: 'sn-jsx-mount' },
+    'JSX unmount': { $ref: 'scene/jsblock/jsx-unmount', prefix: 'sn-jsx-unmount' },
+    Notification: { $ref: 'global/notification-open', prefix: 'sn-notify' },
+    'Window open': { $ref: 'global/window-open', prefix: 'sn-window-open' },
+    'Add click listener': { $ref: 'scene/jsblock/add-event-listener', prefix: 'sn-jsb-click' },
+    'Append style': { $ref: 'scene/jsblock/append-style', prefix: 'sn-jsb-style' },
+  },
+});

package/src/runjs-context/contexts/JSCollectionActionRunJSContext.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { FlowRunJSContext } from './FlowRunJSContext';
+
+export class JSCollectionActionRunJSContext extends FlowRunJSContext {
+  constructor(delegate: any) {
+    super(delegate);
+    this.defineProperty('resource', { get: () => (this as any)._delegate['resource'] });
+  }
+}
+
+JSCollectionActionRunJSContext.define({
+  label: 'JSCollectionAction RunJS context',
+  properties: {
+    resource: '列表资源（选中行/分页等）',
+  },
+  methods: {
+    runAction: 'Run action',
+    message: 'Message API',
+  },
+  snipastes: {
+    'Selected count': { $ref: 'scene/actions/collection-selected-count', prefix: 'sn-act-selected-count' },
+    'Iterate selected rows': { $ref: 'scene/actions/iterate-selected-rows', prefix: 'sn-act-iterate' },
+  },
+});

package/src/runjs-context/contexts/JSFieldRunJSContext.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 { FlowRunJSContext } from './FlowRunJSContext';
+import { createSafeDocument, createSafeWindow } from '../../utils';
+
+export class JSFieldRunJSContext extends FlowRunJSContext {
+  static injectDefaultGlobals() {
+    return { window: createSafeWindow(), document: createSafeDocument() };
+  }
+  constructor(delegate: any) {
+    super(delegate);
+    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
+    this.defineProperty('value', { get: () => (this as any)._delegate['value'] });
+    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
+    this.defineProperty('collection', { get: () => (this as any)._delegate['collection'] });
+  }
+}
+
+JSFieldRunJSContext.define({
+  label: 'JSField RunJS context',
+  properties: {
+    element: 'ElementProxy，字段渲染容器',
+    value: '字段当前值（只读）',
+    record: '当前记录（只读）',
+    collection: '集合定义（只读）',
+  },
+  methods: {
+    onRefReady: 'Container ready callback',
+  },
+  snipastes: {
+    'Render value': { $ref: 'scene/jsfield/innerHTML-value', prefix: 'sn-jsf-value' },
+    'Message success': { $ref: 'global/message-success', prefix: 'sn-msg-ok' },
+    'Format number': { $ref: 'scene/jsfield/format-number', prefix: 'sn-jsf-num' },
+    'Color by value': { $ref: 'scene/jsfield/color-by-value', prefix: 'sn-jsf-color' },
+  },
+});

package/src/runjs-context/contexts/JSItemRunJSContext.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { FlowRunJSContext } from './FlowRunJSContext';
+import { createSafeDocument, createSafeWindow } from '../../utils';
+
+export class JSItemRunJSContext extends FlowRunJSContext {
+  static injectDefaultGlobals() {
+    return { window: createSafeWindow(), document: createSafeDocument() };
+  }
+  constructor(delegate: any) {
+    super(delegate);
+    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
+    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
+    this.defineProperty('resource', { get: () => (this as any)._delegate['resource'] });
+  }
+}
+
+JSItemRunJSContext.define({
+  label: 'JSItem RunJS context',
+  properties: {
+    element: 'ElementProxy，表单项渲染容器',
+    resource: '当前资源（只读）',
+    record: '当前记录（只读）',
+  },
+  methods: {
+    onRefReady: 'Container ready callback',
+    requireAsync: 'Load external library',
+  },
+  snipastes: {
+    'Render form item': { $ref: 'scene/jsitem/render-basic', prefix: 'sn-jsitem-basic' },
+  },
+});

package/src/runjs-context/contexts/JSRecordActionRunJSContext.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 { FlowRunJSContext } from './FlowRunJSContext';
+
+export class JSRecordActionRunJSContext extends FlowRunJSContext {
+  constructor(delegate: any) {
+    super(delegate);
+    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
+    this.defineProperty('filterByTk', { get: () => (this as any)._delegate['filterByTk'] });
+  }
+}
+
+JSRecordActionRunJSContext.define({
+  label: 'JSRecordAction RunJS context',
+  properties: {
+    record: '当前记录（只读）',
+    filterByTk: '主键/过滤键（只读）',
+  },
+  methods: {
+    runAction: 'Run action: `await ctx.runAction(name, params)`',
+    message: 'Message API',
+  },
+  snipastes: {
+    'Show record id': { $ref: 'scene/actions/record-id-message', prefix: 'sn-act-record-id' },
+    'Run action': { $ref: 'scene/actions/run-action-basic', prefix: 'sn-act-run' },
+  },
+});

package/src/runjs-context/contexts/LinkageRunJSContext.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 { FlowRunJSContext } from './FlowRunJSContext';
+
+export class LinkageRunJSContext extends FlowRunJSContext {
+  constructor(delegate: any) {
+    super(delegate);
+    this.defineProperty('model', { get: () => (this as any)._delegate['model'] });
+    this.defineProperty('fields', { get: () => (this as any)._delegate['fields'] });
+  }
+}
+
+LinkageRunJSContext.define({
+  label: 'Linkage RunJS context',
+  properties: {
+    model: '当前块/字段模型（只读访问）',
+    fields: '可访问的字段集合（只读）',
+  },
+  methods: {
+    message: 'Message API',
+  },
+  snipastes: {
+    'Set field value': { $ref: 'scene/linkage/set-field-value', prefix: 'sn-link-set' },
+    'Toggle visible': { $ref: 'scene/linkage/toggle-visible', prefix: 'sn-link-visibility' },
+    'Set disabled': { $ref: 'scene/linkage/set-disabled', prefix: 'sn-link-disable' },
+    'Set required': { $ref: 'scene/linkage/set-required', prefix: 'sn-link-required' },
+  },
+});

package/src/runjs-context/helpers.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { FlowContext } from '../flowContext';
+import { JSRunner } from '../JSRunner';
+import type { JSRunnerOptions } from '../JSRunner';
+import { FlowRunJSContext, RunJSVersion } from './contexts/FlowRunJSContext';
+import { RunJSContextRegistry, getModelClassName } from './registry';
+import { JSBlockRunJSContext } from './contexts/JSBlockRunJSContext';
+import { JSFieldRunJSContext } from './contexts/JSFieldRunJSContext';
+import { JSItemRunJSContext } from './contexts/JSItemRunJSContext';
+import { FormJSFieldItemRunJSContext } from './contexts/FormJSFieldItemRunJSContext';
+import { JSRecordActionRunJSContext } from './contexts/JSRecordActionRunJSContext';
+import { JSCollectionActionRunJSContext } from './contexts/JSCollectionActionRunJSContext';
+import { LinkageRunJSContext } from './contexts/LinkageRunJSContext';
+
+export function getRunJSDocFor(ctx: FlowContext, { version = 'v1' as RunJSVersion } = {}) {
+  const modelClass = getModelClassName(ctx);
+  const ctor =
+    RunJSContextRegistry.resolve(version, modelClass) ||
+    RunJSContextRegistry.resolve('latest' as RunJSVersion, modelClass) ||
+    FlowRunJSContext;
+  return (ctor as any).getDoc?.() || {};
+}
+
+export function createJSRunnerWithVersion(this: FlowContext, options?: JSRunnerOptions) {
+  const version = (options?.version as RunJSVersion) || ('v1' as RunJSVersion);
+  const modelClass = getModelClassName(this);
+  const Ctor =
+    RunJSContextRegistry.resolve(version, modelClass) ||
+    RunJSContextRegistry.resolve('latest' as RunJSVersion, modelClass) ||
+    FlowRunJSContext;
+  const runCtx = new Ctor((this as any).createProxy ? (this as any).createProxy() : (this as any));
+  const def = (Ctor as any).injectDefaultGlobals?.() || {};
+  const globals = { ctx: runCtx, ...def, ...(options?.globals || {}) };
+  // 透传 JSRunnerOptions 其余配置（如 timeoutMs）
+  const { timeoutMs } = options || {};
+  return new JSRunner({ globals, timeoutMs });
+}
+
+export function registerDefaultMappings() {
+  const v: RunJSVersion = 'v1';
+  RunJSContextRegistry.register(v, 'JSBlockModel', JSBlockRunJSContext);
+  RunJSContextRegistry.register(v, 'JSFieldModel', JSFieldRunJSContext);
+  RunJSContextRegistry.register(v, 'JSItemModel', JSItemRunJSContext);
+  RunJSContextRegistry.register(v, 'FormJSFieldItemModel', FormJSFieldItemRunJSContext);
+  RunJSContextRegistry.register(v, 'JSRecordActionModel', JSRecordActionRunJSContext);
+  RunJSContextRegistry.register(v, 'JSCollectionActionModel', JSCollectionActionRunJSContext);
+  RunJSContextRegistry.register(v, '*', FlowRunJSContext);
+}

package/src/runjs-context/index.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+
+export * from './registry';
+export * from './helpers';
+export * from './contexts/FlowRunJSContext';
+export * from './contexts/JSBlockRunJSContext';
+export * from './contexts/JSFieldRunJSContext';
+export * from './contexts/JSItemRunJSContext';
+export * from './contexts/FormJSFieldItemRunJSContext';
+export * from './contexts/JSRecordActionRunJSContext';
+export * from './contexts/JSCollectionActionRunJSContext';
+export * from './contexts/LinkageRunJSContext';
+export { engineSnippets } from './snippets';

package/src/runjs-context/registry.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 { RunJSVersion, RunJSContextCtor } from './contexts/FlowRunJSContext';
+import { FlowRunJSContext } from './contexts/FlowRunJSContext';
+import { JSBlockRunJSContext } from './contexts/JSBlockRunJSContext';
+import { JSFieldRunJSContext } from './contexts/JSFieldRunJSContext';
+import { JSItemRunJSContext } from './contexts/JSItemRunJSContext';
+import { FormJSFieldItemRunJSContext } from './contexts/FormJSFieldItemRunJSContext';
+import { JSRecordActionRunJSContext } from './contexts/JSRecordActionRunJSContext';
+import { JSCollectionActionRunJSContext } from './contexts/JSCollectionActionRunJSContext';
+
+export class RunJSContextRegistry {
+  private static map = new Map<string, RunJSContextCtor>();
+  private static defaultsRegistered = false;
+  private static ensureDefaults() {
+    if (this.defaultsRegistered) return;
+    // v1 默认映射（延迟注册：首次访问时再注册）
+    const v = 'v1' as RunJSVersion;
+    try {
+      const ensure = (model: string, ctor: RunJSContextCtor) => {
+        const key = `${v}:${model}`;
+        if (!this.map.has(key)) this.map.set(key, ctor);
+      };
+      ensure('JSBlockModel', JSBlockRunJSContext as any);
+      ensure('JSFieldModel', JSFieldRunJSContext as any);
+      ensure('JSItemModel', JSItemRunJSContext as any);
+      ensure('FormJSFieldItemModel', FormJSFieldItemRunJSContext as any);
+      ensure('JSRecordActionModel', JSRecordActionRunJSContext as any);
+      ensure('JSCollectionActionModel', JSCollectionActionRunJSContext as any);
+      ensure('*', FlowRunJSContext as any);
+    } finally {
+      this.defaultsRegistered = true;
+    }
+  }
+  static register(version: RunJSVersion, modelClass: string, ctor: RunJSContextCtor) {
+    this.map.set(`${version}:${modelClass}`, ctor);
+  }
+  static resolve(version: RunJSVersion, modelClass: string) {
+    this.ensureDefaults();
+    return this.map.get(`${version}:${modelClass}`) || this.map.get(`${version}:*`);
+  }
+}
+
+export function getModelClassName(ctx: any): string {
+  const model = ctx?.model;
+  if (!model) return '*';
+  // 1) 优先使用类 meta 中声明的 createModelOptions.use（构建后稳定，不受构造函数名压缩影响）
+  try {
+    const Ctor = model.constructor as any;
+    const use = Ctor?.meta?.createModelOptions?.use;
+    if (typeof use === 'string' && use) return use;
+  } catch (_) {
+    // ignore
+  }
+  // 2) 回退到构造函数名（开发模式可靠，生产模式可能被压缩）
+  const byName = model?.constructor?.name;
+  return byName || '*';
+}

package/src/runjs-context/snippets/global/api-request-get.snippet.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+
+export default {
+  contexts: ['*'],
+  prefix: 'sn-api-get',
+  label: 'GET request template',
+  description: 'Basic template to send a GET request via ctx.api',
+  content: `
+const res = await ctx.api.request({ url: '/your/api', method: 'get', params: { page: 1 } });
+ctx.message.success(ctx.t('GET request completed'));
+console.log(ctx.t('GET result:'), res);
+`,
+};

package/src/runjs-context/snippets/global/api-request-post.snippet.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+
+export default {
+  contexts: ['*'],
+  prefix: 'sn-api-post',
+  label: 'POST request template',
+  description: 'Basic template to send a POST request via ctx.api',
+  content: `
+const res = await ctx.api.request({ url: '/your/api', method: 'post', data: { name: 'NocoBase' } });
+ctx.message.success(ctx.t('POST request completed'));
+console.log(ctx.t('POST result:'), res);
+`,
+};