@nocobase/flow-engine 2.1.0-alpha.1 → 2.1.0-alpha.10

package/src/flowContext.ts

@@ -9,11 +9,10 @@
 
 import { ISchema } from '@formily/json-schema';
 import { observable } from '@formily/reactive';
-import { APIClient } from '@nocobase/sdk';
+import { APIClient, RequestOptions } from '@nocobase/sdk';
 import type { Router } from '@remix-run/router';
 import { MessageInstance } from 'antd/es/message/interface';
 import * as antd from 'antd';
-import * as antdIcons from '@ant-design/icons';
 import type { HookAPI } from 'antd/es/modal/useModal';
 import { NotificationInstance } from 'antd/es/notification/interface';
 import _ from 'lodash';
@@ -28,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';
@@ -38,17 +37,26 @@ import {
   extractPropertyPath,
   extractUsedVariablePaths,
   FlowExitException,
+  FLOW_ENGINE_NAMESPACE,
+  isCtxDatePathPrefix,
+  isCssFile,
+  prepareRunJsCode,
+  resolveCtxDatePath,
   resolveDefaultParams,
   resolveExpressions,
+  resolveModuleUrl,
 } from './utils';
 import { FlowExitAllException } from './utils/exceptions';
 import { enqueueVariablesResolve, JSONValue } from './utils/params-resolvers';
 import type { RecordRef } from './utils/serverContextParams';
 import { buildServerContextParams as _buildServerContextParams } from './utils/serverContextParams';
+import { inferRecordRef } from './utils/variablesParams';
 import { FlowView, FlowViewer } from './views/FlowView';
-import { RunJSContextRegistry, getModelClassName } from './runjs-context/registry';
+import { RunJSContextRegistry, getModelClassName, type RunJSVersion } from './runjs-context/registry';
 import { createEphemeralContext } from './utils/createEphemeralContext';
 import dayjs from 'dayjs';
+import { externalReactRender, setupRunJSLibs } from './runjsLibs';
+import { runjsImportAsync, runjsImportModule, runjsRequireAsync } from './utils/runjsModuleLoader';
 
 // Helper: detect a RecordRef-like object
 function isRecordRefLike(val: any): boolean {
@@ -71,13 +79,109 @@ function filterBuilderOutputByPaths(built: any, neededPaths: string[]): any {
   return undefined;
 }
 
+// Helper: extract top-level segment of a subpath (e.g. 'a.b' -> 'a', 'tags[0].name' -> 'tags')
+function topLevelOf(subPath: string): string | undefined {
+  if (!subPath) return undefined;
+  const m = String(subPath).match(/^([^.[]+)/);
+  return m?.[1];
+}
+
+// Helper: infer selects (fields/appends) from usage paths (mirrors server-side inferSelectsFromUsage)
+function inferSelectsFromUsage(paths: string[] = []): { generatedAppends?: string[]; generatedFields?: string[] } {
+  if (!Array.isArray(paths) || paths.length === 0) {
+    return { generatedAppends: undefined, generatedFields: undefined };
+  }
+
+  const appendSet = new Set<string>();
+  const fieldSet = new Set<string>();
+
+  const normalizePath = (raw: string): string => {
+    if (!raw) return '';
+    let s = String(raw);
+    // remove numeric indexes like [0]
+    s = s.replace(/\[(?:\d+)\]/g, '');
+    // normalize string indexes like ["name"] / ['name'] into .name
+    s = s.replace(/\[(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)')\]/g, (_m, g1, g2) => `.${(g1 || g2) as string}`);
+    s = s.replace(/\.\.+/g, '.');
+    s = s.replace(/^\./, '').replace(/\.$/, '');
+    return s;
+  };
+
+  for (let path of paths) {
+    if (!path) continue;
+    // drop leading numeric index like [0].name
+    while (/^\[(\d+)\](\.|$)/.test(path)) {
+      path = path.replace(/^\[(\d+)\]\.?/, '');
+    }
+    const norm = normalizePath(path);
+    if (!norm) continue;
+    const segments = norm.split('.').filter(Boolean);
+    if (segments.length === 0) continue;
+
+    if (segments.length === 1) {
+      fieldSet.add(segments[0]);
+      continue;
+    }
+
+    for (let i = 0; i < segments.length - 1; i++) {
+      appendSet.add(segments.slice(0, i + 1).join('.'));
+    }
+    fieldSet.add(segments.join('.'));
+  }
+
+  const generatedAppends = appendSet.size ? Array.from(appendSet) : undefined;
+  const generatedFields = fieldSet.size ? Array.from(fieldSet) : undefined;
+  return { generatedAppends, generatedFields };
+}
+
 type Getter<T = any> = (ctx: FlowContext) => T | Promise<T>;
 
+export type FlowContextDocRef = string | { url: string; title?: string };
+
+export type FlowDeprecationDoc =
+  | boolean
+  | {
+      /**
+       * 废弃说明（面向人/大模型）。
+       */
+      message?: string;
+      /**
+       * 推荐替代 API（例如 'ctx.resolveJsonTemplate'）。
+       */
+      replacedBy?: string | string[];
+      /**
+       * 开始废弃的版本号（可选）。
+       */
+      since?: string;
+      /**
+       * 预计移除的版本号（可选）。
+       */
+      removedIn?: string;
+      /**
+       * 参考链接（可选）。
+       */
+      ref?: FlowContextDocRef;
+    };
+
+export type FlowContextDocParam = {
+  name: string;
+  description?: string;
+  type?: string;
+  optional?: boolean;
+  default?: JSONValue;
+};
+
+export type FlowContextDocReturn = {
+  description?: string;
+  type?: string;
+};
+
 export interface MetaTreeNode {
   name: string;
   title: string;
   type: string;
   interface?: string;
+  options?: any;
   uiSchema?: ISchema;
   render?: (props: any) => JSX.Element;
   // display?: 'default' | 'flatten' | 'none'; // 显示模式：默认、平铺子菜单、完全隐藏, 用于简化meta树显示层级
@@ -95,6 +199,7 @@ export interface PropertyMeta {
   type: string;
   title: string;
   interface?: string;
+  options?: any;
   uiSchema?: ISchema; // TODO: 这个是不是压根没必要啊？
   render?: (props: any) => JSX.Element; // 自定义渲染函数
   // 用于 VariableInput 的排序：数值越大，显示越靠前；相同值保持稳定顺序
@@ -102,11 +207,11 @@ export interface PropertyMeta {
   // display?: 'default' | 'flatten' | 'none'; // 显示模式：默认、平铺子菜单、完全隐藏, 用于简化meta树显示层级
   properties?: Record<string, PropertyMeta> | (() => Promise<Record<string, PropertyMeta>>);
   // 变量禁用控制：若 disabled 为真（或函数返回真）则禁用
-  disabled?: boolean | (() => boolean);
+  disabled?: boolean | (() => boolean | Promise<boolean>);
   // 禁用原因（用于 UI 小问号提示），可为函数
-  disabledReason?: string | (() => string | undefined);
+  disabledReason?: string | (() => string | undefined | Promise<string | undefined>);
   // 显示控制：当 hidden 为 true（或函数返回 true）时，不在变量选择器中展示该节点
-  hidden?: boolean | (() => boolean);
+  hidden?: boolean | (() => boolean | Promise<boolean>);
   // 变量解析参数构造器（用于 variables:resolve 的 contextParams，按属性名归位）。
   // 支持返回 RecordRef 或任意嵌套对象（将被 buildServerContextParams 扁平化，例如 { record: RecordRef } -> 'view.record'）。
   buildVariablesParams?: (
@@ -138,16 +243,154 @@ export interface PropertyOptions {
   cache?: boolean;
   observable?: boolean; // 是否为 observable 属性
   meta?: PropertyMetaOrFactory; // 支持静态、函数和异步函数（工厂函数可带 title/sort）
+  /**
+   * 面向工具/大模型的静态文档信息（不影响变量选择器 UI）。
+   * - `getApiInfos()` 仅使用 RunJS doc + 这里的 `info`（不会读取/展开 `meta`）
+   * - 变量结构信息请使用 `getVarInfos()`（来源于 `meta`）
+   */
+  info?: FlowContextPropertyInfoOrFactory;
   // 标记该属性是否在服务端解析：
   // - boolean: true 表示整个顶层变量交给服务端；false 表示仅前端解析
   // - function: 根据子路径决定是否交给服务端（子路径示例：'record.roles[0].name'、'id'、''）
   resolveOnServer?: boolean | ((subPath: string) => boolean);
   // 优化：当需要服务端解析但本属性在 buildVariablesParams 返回空时，是否跳过调用服务端。
-  // - 典型场景：formValues / currentObject 仅在“已选关联值”存在时才需要服务端；否则没有必要请求。
+  // - 典型场景：formValues / item 仅在“已选关联值”存在时才需要服务端；否则没有必要请求。
   // - 默认 false：保持兼容，其他变量即使没有 contextParams 也可选择调用服务端。
   serverOnlyWhenContextParams?: boolean;
 }
 
+export type FlowContextMethodInfoInput = {
+  description?: string;
+  detail?: string;
+  examples?: string[];
+  completion?: RunJSDocCompletionDoc;
+  ref?: FlowContextDocRef;
+  deprecated?: FlowDeprecationDoc;
+  params?: FlowContextDocParam[];
+  returns?: FlowContextDocReturn;
+  hidden?: boolean | ((ctx: any) => boolean | Promise<boolean>);
+  disabled?: boolean | ((ctx: any) => boolean | Promise<boolean>);
+  disabledReason?: string | ((ctx: any) => string | undefined | Promise<string | undefined>);
+};
+
+export type FlowContextMethodInfo = {
+  description?: string;
+  detail?: string;
+  examples?: string[];
+  completion?: RunJSDocCompletionDoc;
+  ref?: FlowContextDocRef;
+  deprecated?: FlowDeprecationDoc;
+  params?: FlowContextDocParam[];
+  returns?: FlowContextDocReturn;
+  disabled?: boolean;
+  disabledReason?: string;
+};
+
+export type FlowContextPropertyInfoObjectInput = Omit<
+  FlowContextPropertyInfo,
+  'disabled' | 'disabledReason' | 'properties'
+> & {
+  properties?:
+    | Record<string, FlowContextPropertyInfoInput>
+    | (() => Promise<Record<string, FlowContextPropertyInfoInput>>);
+  hidden?: RunJSDocHiddenOrPathsDoc;
+  disabled?: boolean | ((ctx: any) => boolean | Promise<boolean>);
+  disabledReason?: string | ((ctx: any) => string | undefined | Promise<string | undefined>);
+};
+
+export type FlowContextPropertyInfoInput = string | FlowContextPropertyInfoObjectInput;
+
+export type FlowContextPropertyInfoFactory = {
+  (): FlowContextPropertyInfoInput | Promise<FlowContextPropertyInfoInput | null> | null;
+};
+
+export type FlowContextPropertyInfoOrFactory = FlowContextPropertyInfoInput | FlowContextPropertyInfoFactory;
+
+export type FlowContextPropertyInfo = {
+  title?: string;
+  type?: string;
+  interface?: string;
+  description?: string;
+  detail?: string;
+  examples?: string[];
+  completion?: RunJSDocCompletionDoc;
+  ref?: FlowContextDocRef;
+  deprecated?: FlowDeprecationDoc;
+  params?: FlowContextDocParam[];
+  returns?: FlowContextDocReturn;
+  disabled?: boolean;
+  disabledReason?: string;
+  properties?: Record<string, FlowContextPropertyInfo>;
+};
+
+export type FlowContextApiInfo = {
+  title?: string;
+  type?: string;
+  interface?: string;
+  description?: string;
+  examples?: string[];
+  completion?: RunJSDocCompletionDoc;
+  ref?: FlowContextDocRef;
+  deprecated?: FlowDeprecationDoc;
+  params?: FlowContextDocParam[];
+  returns?: FlowContextDocReturn;
+  disabled?: boolean;
+  disabledReason?: string;
+  properties?: Record<string, FlowContextApiInfo>;
+};
+
+export type FlowContextInfosEnvNode = {
+  /**
+   * 说明（面向人/大模型）。建议为一句话。
+   */
+  description?: string;
+  /**
+   * 可用于 `await ctx.getVar(getVar)` 的表达式字符串，推荐以 `ctx.` 开头。
+   * 例如：'ctx.popup'、'ctx.resource.collectionName'
+   */
+  getVar?: string;
+  /**
+   * 已解析/可序列化的静态值（用于 prompt 直接使用）。
+   * 注意：应保持小体积，避免放入 record 等大对象。
+   */
+  value?: JSONValue;
+  /**
+   * 子节点（用于表达 popup.resource.xxx 等层级结构）。
+   */
+  properties?: Record<string, FlowContextInfosEnvNode>;
+};
+
+export type FlowContextInfosEnvs = {
+  popup?: FlowContextInfosEnvNode;
+  block?: FlowContextInfosEnvNode;
+  currentViewBlocks?: FlowContextInfosEnvNode;
+  flowModel?: FlowContextInfosEnvNode;
+  resource?: FlowContextInfosEnvNode;
+  record?: FlowContextInfosEnvNode;
+};
+
+export type FlowContextGetApiInfosOptions = {
+  /**
+   * RunJS 文档版本（默认 v1）。
+   */
+  version?: RunJSVersion;
+};
+
+export type FlowContextGetVarInfosOptions = {
+  /**
+   * 最大展开层级（默认 3）。
+   * - 当不传 path 时，top-level property depth=1。
+   * - 当传 path 时，path 对应节点 depth=1。
+   */
+  maxDepth?: number;
+  /**
+   * 剪裁：仅收集指定 path 下的变量结构信息。
+   * - string 形式支持：'record'、'record.id'、'ctx.record'、'{{ ctx.record }}'
+   * - string[] 表示多个剪裁路径合并
+   */
+  path?: string | string[];
+};
+
 type RouteOptions = {
   name?: string; // 路由唯一标识
   path?: string; // 路由模板
@@ -158,6 +401,7 @@ type RouteOptions = {
 export class FlowContext {
   _props: Record<string, PropertyOptions> = {};
   _methods: Record<string, (...args: any[]) => any> = {};
+  _methodInfos: Record<string, FlowContextMethodInfoInput> = {};
   protected _cache: Record<string, any> = {};
   protected _observableCache: Record<string, any> = observable.shallow({});
   protected _delegates: FlowContext[] = [];
@@ -242,8 +486,15 @@ export class FlowContext {
     });
   }
 
-  defineMethod(name: string, fn: (...args: any[]) => any, des?: string) {
+  defineMethod(name: string, fn: (...args: any[]) => any, info?: string | FlowContextMethodInfoInput) {
     this._methods[name] = fn;
+    if (typeof info === 'string') {
+      this._methodInfos[name] = { description: info };
+    } else if (info && typeof info === 'object') {
+      this._methodInfos[name] = info;
+    } else {
+      delete this._methodInfos[name];
+    }
     Object.defineProperty(this, name, {
       configurable: true,
       enumerable: false,
@@ -421,6 +672,1821 @@ export class FlowContext {
     return sorted.map(([key, metaOrFactory]) => this.#toTreeNode(key, metaOrFactory, [key], []));
   }
 
+  /**
+   * 获取静态 API 文档信息（仅顶层一层）。
+   *
+   * - 输出仅来自 RunJS doc 与 defineProperty/defineMethod 的 info
+   * - 不读取/展开 PropertyMeta（变量结构）
+   * - 不自动展开深层 properties
+   * - 不返回自动补全字段（例如 completion）
+   */
+  async getApiInfos(options: FlowContextGetApiInfosOptions = {}): Promise<Record<string, FlowContextApiInfo>> {
+    const version = (options.version as RunJSVersion) || ('v1' as RunJSVersion);
+    const evalCtx = this.createProxy();
+
+    const isPrivateKey = (key: string) => typeof key === 'string' && key.startsWith('_');
+    // NOTE: These are variable-like roots documented in RunJS context doc, but should be served by `getVarInfos()`.
+    // `getApiInfos()` intentionally excludes them to keep static docs and variable meta separated.
+    const isVarRootKey = (key: string) => key === 'record' || key === 'formValues' || key === 'popup';
+
+    const isPromiseLike = (v: any): v is Promise<any> =>
+      !!v && (typeof v === 'object' || typeof v === 'function') && typeof (v as any).then === 'function';
+
+    const getRunJSDoc = (): any => {
+      const modelClass = getModelClassName(this);
+      const Ctor = RunJSContextRegistry.resolve(version, modelClass) || RunJSContextRegistry.resolve(version, '*');
+      if (!Ctor) return {};
+      const locale = (this as any)?.api?.auth?.locale || (this as any)?.i18n?.language || (this as any)?.locale;
+      try {
+        if ((Ctor as any)?.getDoc?.length) {
+          return (Ctor as any).getDoc(locale) || {};
+        }
+        return (Ctor as any)?.getDoc?.() || {};
+      } catch (_) {
+        return {};
+      }
+    };
+
+    const doc = getRunJSDoc();
+    const docMethods = __isPlainObject(doc?.methods) ? (doc.methods as Record<string, any>) : {};
+    const docProps = __isPlainObject(doc?.properties) ? (doc.properties as Record<string, any>) : {};
+
+    const toDocObject = (node: any): any | undefined => {
+      if (typeof node === 'string') return { description: node };
+      if (__isPlainObject(node)) return node;
+      return undefined;
+    };
+
+    const mapDocKeyToApiKey = (key: string, docNode: any): string => {
+      // Some libs are exposed as both `ctx.React` and `ctx.libs.React`. Prefer documenting them under `libs.*`.
+      const desc =
+        typeof docNode === 'string'
+          ? docNode
+          : __isPlainObject(docNode) && typeof (docNode as any).description === 'string'
+            ? String((docNode as any).description)
+            : undefined;
+      if (desc && desc.includes(`ctx.libs.${key}`)) return `libs.${key}`;
+      return key;
+    };
+
+    const pickMethodInfo = (obj: any): Partial<FlowContextApiInfo> => {
+      const src = toDocObject(obj);
+      if (!src) return {};
+      const out: any = {};
+      for (const k of ['description', 'examples', 'ref', 'params', 'returns']) {
+        const v = (src as any)[k];
+        if (typeof v !== 'undefined') out[k] = v;
+      }
+      if (Array.isArray(out.examples)) {
+        out.examples = out.examples.filter((x: any) => typeof x === 'string' && x.trim());
+      }
+      return out;
+    };
+
+    const pickPropertyInfo = (obj: any): Partial<FlowContextApiInfo> => {
+      const src = toDocObject(obj);
+      if (!src) return {};
+      const out: any = {};
+      for (const k of ['title', 'type', 'interface', 'description', 'examples', 'ref', 'params', 'returns']) {
+        const v = (src as any)[k];
+        if (typeof v !== 'undefined') out[k] = v;
+      }
+      if (Array.isArray(out.examples)) {
+        out.examples = out.examples.filter((x: any) => typeof x === 'string' && x.trim());
+      }
+      return out;
+    };
+
+    const getMethodInfoFromChain = (name: string): FlowContextMethodInfoInput | undefined => {
+      const visited = new WeakSet<any>();
+      const walk = (ctx: FlowContext): FlowContextMethodInfoInput | undefined => {
+        if (!ctx || typeof ctx !== 'object') return undefined;
+        if (visited.has(ctx as any)) return undefined;
+        visited.add(ctx as any);
+        if (Object.prototype.hasOwnProperty.call((ctx as any)._methodInfos || {}, name)) {
+          return (ctx as any)._methodInfos?.[name] as FlowContextMethodInfoInput;
+        }
+        const delegates = (ctx as any)._delegates;
+        if (Array.isArray(delegates)) {
+          for (const d of delegates) {
+            const found = walk(d);
+            if (found) return found;
+          }
+        }
+        return undefined;
+      };
+      return walk(this);
+    };
+
+    const resolvePropertyInfo = async (key: string): Promise<FlowContextPropertyInfoInput | undefined> => {
+      const opt = this.getPropertyOptions(key);
+      if (!opt?.info) return undefined;
+      try {
+        const v = typeof opt.info === 'function' ? (opt.info as any).call(evalCtx, evalCtx) : opt.info;
+        const resolved = isPromiseLike(v) ? await v : v;
+        return (resolved ?? undefined) as any;
+      } catch (_) {
+        return undefined;
+      }
+    };
+
+    const propKeys = new Set<string>();
+    const methodKeys = new Set<string>();
+    for (const k of Object.keys(docProps)) propKeys.add(k);
+    for (const k of Object.keys(docMethods)) methodKeys.add(k);
+
+    const collectInfoKeysDeep = (ctx: FlowContext, visited: WeakSet<any>) => {
+      if (!ctx || typeof ctx !== 'object') return;
+      if (visited.has(ctx as any)) return;
+      visited.add(ctx as any);
+
+      try {
+        const props = (ctx as any)._props;
+        if (props && typeof props === 'object') {
+          for (const [k, v] of Object.entries(props)) {
+            if ((v as any)?.info) propKeys.add(k);
+          }
+        }
+      } catch (_) {
+        // ignore
+      }
+
+      try {
+        const mi = (ctx as any)._methodInfos;
+        if (mi && typeof mi === 'object') {
+          for (const k of Object.keys(mi)) methodKeys.add(k);
+        }
+      } catch (_) {
+        // ignore
+      }
+
+      try {
+        const delegates = (ctx as any)._delegates;
+        if (Array.isArray(delegates)) {
+          for (const d of delegates) collectInfoKeysDeep(d, visited);
+        }
+      } catch (_) {
+        // ignore
+      }
+    };
+    collectInfoKeysDeep(this, new WeakSet<any>());
+
+    const out: Record<string, FlowContextApiInfo> = {};
+
+    for (const key of propKeys) {
+      if (isPrivateKey(key)) continue;
+      if (isVarRootKey(key)) continue;
+      const docNode = docProps[key];
+      const infoNode = await resolvePropertyInfo(key);
+      if (typeof docNode === 'undefined' && typeof infoNode === 'undefined') continue;
+
+      const docObj = toDocObject(docNode);
+      const infoObj = toDocObject(infoNode);
+      let node: FlowContextApiInfo = {};
+      node = { ...node, ...pickPropertyInfo(docObj) };
+      node = { ...node, ...pickPropertyInfo(infoObj) };
+      delete (node as any).properties;
+      delete (node as any).completion;
+      if (!Object.keys(node).length) continue;
+      const outKey = mapDocKeyToApiKey(key, docNode);
+      // Avoid exposing ctx.React/ctx.ReactDOM/ctx.antd in api docs when mapping to ctx.libs.*.
+      out[outKey] = out[outKey] ? { ...(out[outKey] || {}), ...(node || {}) } : node;
+    }
+
+    for (const key of methodKeys) {
+      if (isPrivateKey(key)) continue;
+      const docNode = docMethods[key];
+      const info = getMethodInfoFromChain(key);
+      if (typeof docNode === 'undefined' && typeof info === 'undefined') continue;
+
+      const docObj = toDocObject(docNode);
+      let node: FlowContextApiInfo = {};
+      node = { ...node, ...pickMethodInfo(docObj) };
+      node = { ...node, ...pickMethodInfo(info) };
+      delete (node as any).properties;
+      delete (node as any).completion;
+      if (!Object.keys(node).length) continue;
+      node.type = 'function';
+
+      if (!out[key]) out[key] = node;
+      else out[key] = { ...(out[key] || {}), ...(node || {}) };
+    }
+
+    // Flatten libs children (one-layer output, but allow `libs.xxx` keys).
+    // Prefer richer doc from root aliases (e.g. `React` mapped to `libs.React`) when available.
+    const libsDocObj = toDocObject(docProps.libs);
+    const libsChildren = __isPlainObject((libsDocObj as any)?.properties)
+      ? ((libsDocObj as any).properties as any as Record<string, any>)
+      : undefined;
+    if (libsChildren) {
+      for (const [k, v] of Object.entries(libsChildren)) {
+        if (isPrivateKey(k)) continue;
+        const outKey = `libs.${k}`;
+        if (out[outKey]) continue;
+        const childObj = toDocObject(v);
+        let node: FlowContextApiInfo = {};
+        node = { ...node, ...pickPropertyInfo(childObj) };
+        delete (node as any).properties;
+        delete (node as any).completion;
+        if (!node.description || !String(node.description).trim()) continue;
+        out[outKey] = node;
+      }
+    }
+
+    return out;
+  }
+
+  /**
+   * 获取运行时环境快照信息（小体积、可序列化）。
+   */
+  async getEnvInfos(): Promise<FlowContextInfosEnvs> {
+    const evalCtx = this.createProxy();
+
+    const isPromiseLike = (v: any): v is Promise<any> =>
+      !!v && (typeof v === 'object' || typeof v === 'function') && typeof (v as any).then === 'function';
+
+    const envs: FlowContextInfosEnvs = {};
+
+    type ResourceSnapshotKey = 'dataSourceKey' | 'collectionName' | 'associationName' | 'filterByTk' | 'sourceId';
+    type ResourceSnapshot = Partial<Record<ResourceSnapshotKey, JSONValue>>;
+    type ResourceLike = ResourceSnapshot & {
+      getDataSourceKey?: () => JSONValue;
+      getFilterByTk?: () => JSONValue;
+      getSourceId?: () => JSONValue;
+      getResourceName?: () => string;
+      getMeta?: (key: string) => unknown;
+    };
+    type ModelCtorLike = { name?: string; meta?: { label?: string } };
+    type ModelLike = { uid?: string; title?: string; resource?: unknown; constructor?: ModelCtorLike };
+    type PopupLike = { uid?: string; resource?: unknown; record?: unknown; sourceRecord?: unknown; parent?: unknown };
+
+    const getMaybe = <T = any>(fn: () => T): T | undefined => {
+      try {
+        return fn();
+      } catch (_) {
+        return undefined;
+      }
+    };
+
+    const hasSnapshotValue = <T>(v: T): v is Exclude<T, undefined | null> => {
+      if (typeof v === 'undefined' || v === null) return false;
+      if (typeof v === 'string') return v.trim().length > 0;
+      if (Array.isArray(v)) return v.length > 0;
+      return true;
+    };
+
+    const getResourceSnapshot = (res: unknown): ResourceSnapshot => {
+      const out: ResourceSnapshot = {};
+      if (!res) return out;
+      const r = res as ResourceLike;
+
+      // Direct fields (popup/view inputArgs style)
+      for (const k of [
+        'dataSourceKey',
+        'collectionName',
+        'associationName',
+        'filterByTk',
+        'sourceId',
+      ] as ResourceSnapshotKey[]) {
+        const v = r?.[k];
+        if (hasSnapshotValue(v)) out[k] = v;
+      }
+
+      // FlowResource-like methods (BaseRecordResource/SQLResource)
+      if (!('dataSourceKey' in out)) {
+        const v = r.getDataSourceKey?.();
+        if (hasSnapshotValue(v)) out.dataSourceKey = v;
+      }
+      if (!('filterByTk' in out)) {
+        const v = r.getFilterByTk?.();
+        if (hasSnapshotValue(v)) out.filterByTk = v;
+      }
+      if (!('filterByTk' in out)) {
+        const v = r.getMeta?.('currentFilterByTk') as JSONValue | undefined;
+        if (hasSnapshotValue(v)) out.filterByTk = v;
+      }
+      if (!('sourceId' in out)) {
+        const v = r.getSourceId?.();
+        if (hasSnapshotValue(v)) out.sourceId = v;
+      }
+
+      // Infer collection/association from resourceName when not provided
+      if (!('collectionName' in out) || !('associationName' in out)) {
+        const rn = r.getResourceName?.();
+        const resourceName = typeof rn === 'string' ? rn.trim() : '';
+        if (resourceName) {
+          const parts = resourceName
+            .split('.')
+            .map((x) => x.trim())
+            .filter(Boolean);
+          if (parts.length === 1) {
+            if (!('collectionName' in out)) out.collectionName = parts[0];
+          } else if (parts.length >= 2) {
+            if (!('collectionName' in out)) out.collectionName = parts[0];
+            if (!('associationName' in out)) out.associationName = parts.slice(1).join('.');
+          }
+        }
+      }
+
+      return out;
+    };
+
+    // Resolve popup (may be Promise)
+    const popup = await (async () => {
+      try {
+        const raw = (evalCtx as any).popup;
+        return isPromiseLike(raw) ? await raw : raw;
+      } catch (_) {
+        return undefined;
+      }
+    })();
+
+    const popupLike = popup as PopupLike | undefined;
+    const model = getMaybe(() => (evalCtx as any).model) as ModelLike | undefined;
+    const blockModel = getMaybe(() => (evalCtx as any).blockModel) as ModelLike | undefined;
+    const inputArgs = getMaybe(() => (evalCtx as any).view?.inputArgs) as
+      | (ResourceLike & { viewUid?: string })
+      | undefined;
+    const ctxResource = getMaybe(() => (evalCtx as any).resource) as ResourceLike | undefined;
+
+    const popupResource = popupLike?.resource;
+    const popupResourceSnap = getResourceSnapshot(popupResource);
+
+    const blockOwner = blockModel;
+    const blockOwnerExpr = blockModel ? 'ctx.blockModel' : undefined;
+    const blockResourceBaseExpr = blockOwnerExpr ? `${blockOwnerExpr}.resource` : undefined;
+    const blockResource = blockOwner?.resource;
+    const blockResourceSnap = getResourceSnapshot(blockResource);
+    const inputArgsSnap = getResourceSnapshot(inputArgs);
+    const ctxResourceSnap = getResourceSnapshot(ctxResource);
+
+    // Resource snapshot (for prompt)
+    const pickWithGetVar = <T>(
+      pairs: Array<{
+        value: T | undefined;
+        getVar: string;
+      }>,
+    ): { value: T; getVar: string } | undefined => {
+      for (const p of pairs) {
+        if (hasSnapshotValue(p.value)) return { value: p.value, getVar: p.getVar };
+      }
+      return undefined;
+    };
+
+    const hasAnyResourceValuesIn = (snap: ResourceSnapshot): boolean =>
+      hasSnapshotValue(snap.collectionName) ||
+      hasSnapshotValue(snap.dataSourceKey) ||
+      hasSnapshotValue(snap.associationName);
+
+    const resourceBaseExpr: string | undefined = hasAnyResourceValuesIn(popupResourceSnap)
+      ? 'ctx.popup.resource'
+      : hasAnyResourceValuesIn(blockResourceSnap)
+        ? blockResourceBaseExpr
+        : hasAnyResourceValuesIn(inputArgsSnap)
+          ? 'ctx.view.inputArgs'
+          : hasAnyResourceValuesIn(ctxResourceSnap)
+            ? 'ctx.resource'
+            : undefined;
+
+    const collectionNamePick = pickWithGetVar([
+      { value: popupResourceSnap?.collectionName, getVar: 'ctx.popup.resource.collectionName' },
+      { value: blockResourceSnap?.collectionName, getVar: `${blockResourceBaseExpr}.collectionName` },
+      { value: inputArgsSnap?.collectionName, getVar: 'ctx.view.inputArgs.collectionName' },
+      { value: ctxResourceSnap?.collectionName, getVar: 'ctx.resource.collectionName' },
+    ]);
+    const dataSourceKeyPick = pickWithGetVar([
+      { value: popupResourceSnap?.dataSourceKey, getVar: 'ctx.popup.resource.dataSourceKey' },
+      { value: blockResourceSnap?.dataSourceKey, getVar: `${blockResourceBaseExpr}.dataSourceKey` },
+      { value: inputArgsSnap?.dataSourceKey, getVar: 'ctx.view.inputArgs.dataSourceKey' },
+      { value: ctxResourceSnap?.dataSourceKey, getVar: 'ctx.resource.dataSourceKey' },
+    ]);
+    const associationNamePick = pickWithGetVar([
+      { value: popupResourceSnap?.associationName, getVar: 'ctx.popup.resource.associationName' },
+      { value: blockResourceSnap?.associationName, getVar: `${blockResourceBaseExpr}.associationName` },
+      { value: inputArgsSnap?.associationName, getVar: 'ctx.view.inputArgs.associationName' },
+      { value: ctxResourceSnap?.associationName, getVar: 'ctx.resource.associationName' },
+    ]);
+    const filterByTkPick = pickWithGetVar([
+      { value: popupResourceSnap?.filterByTk, getVar: 'ctx.popup.resource.filterByTk' },
+      { value: blockResourceSnap?.filterByTk, getVar: `${blockResourceBaseExpr}.filterByTk` },
+      { value: inputArgsSnap?.filterByTk, getVar: 'ctx.view.inputArgs.filterByTk' },
+      { value: ctxResourceSnap?.filterByTk, getVar: 'ctx.resource.filterByTk' },
+    ]);
+    const sourceIdPick = pickWithGetVar([
+      { value: popupResourceSnap?.sourceId, getVar: 'ctx.popup.resource.sourceId' },
+      { value: blockResourceSnap?.sourceId, getVar: `${blockResourceBaseExpr}.sourceId` },
+      { value: inputArgsSnap?.sourceId, getVar: 'ctx.view.inputArgs.sourceId' },
+      { value: ctxResourceSnap?.sourceId, getVar: 'ctx.resource.sourceId' },
+    ]);
+
+    const resourceProps: Record<string, FlowContextInfosEnvNode> = {};
+    let hasResourceValues = false;
+    const collectionNameValue = collectionNamePick?.value;
+    if (hasSnapshotValue(collectionNameValue)) {
+      resourceProps.collectionName = {
+        description: 'Collection name',
+        getVar: collectionNamePick?.getVar || (resourceBaseExpr ? `${resourceBaseExpr}.collectionName` : undefined),
+        value: collectionNameValue,
+      };
+      hasResourceValues = true;
+    }
+    const dataSourceKeyValue = dataSourceKeyPick?.value;
+    if (hasSnapshotValue(dataSourceKeyValue)) {
+      resourceProps.dataSourceKey = {
+        description: 'Data source key',
+        getVar: dataSourceKeyPick?.getVar || (resourceBaseExpr ? `${resourceBaseExpr}.dataSourceKey` : undefined),
+        value: dataSourceKeyValue,
+      };
+      hasResourceValues = true;
+    }
+    const associationNameValue = associationNamePick?.value;
+    if (hasSnapshotValue(associationNameValue)) {
+      resourceProps.associationName = {
+        description: 'Association name',
+        getVar: associationNamePick?.getVar || (resourceBaseExpr ? `${resourceBaseExpr}.associationName` : undefined),
+        value: associationNameValue,
+      };
+      hasResourceValues = true;
+    }
+
+    // Only include envs.resource when snapshot contains at least one resource value.
+    // Optional fields like filterByTk/sourceId are included (without value) only when envs.resource exists.
+    if (hasResourceValues) {
+      if (hasSnapshotValue(filterByTkPick?.value)) {
+        resourceProps.filterByTk = {
+          description: 'Record filterByTk',
+          getVar: filterByTkPick?.getVar || (resourceBaseExpr ? `${resourceBaseExpr}.filterByTk` : undefined),
+        };
+      }
+      if (hasSnapshotValue(sourceIdPick?.value)) {
+        resourceProps.sourceId = {
+          description: 'Source record ID (sourceId)',
+          getVar: sourceIdPick?.getVar || (resourceBaseExpr ? `${resourceBaseExpr}.sourceId` : undefined),
+        };
+      }
+
+      envs.resource = {
+        description: 'Resource information',
+        getVar: resourceBaseExpr,
+        properties: resourceProps,
+      };
+    }
+
+    // Record (only when filterByTk is available)
+    if (hasSnapshotValue(filterByTkPick?.value)) {
+      envs.record = {
+        description: 'Current record',
+        getVar: 'ctx.record',
+      };
+    }
+
+    const pickLabel = (obj: ModelLike | null | undefined): string | undefined => {
+      try {
+        const t = obj?.title;
+        if (typeof t === 'string' && t.trim()) return t;
+      } catch (_) {
+        // ignore
+      }
+      try {
+        const label = obj?.constructor?.meta?.label;
+        if (typeof label === 'string' && label.trim()) return label;
+      } catch (_) {
+        // ignore
+      }
+      return undefined;
+    };
+
+    // FlowModel (when ctx.model exists)
+    if (model) {
+      const modelLabel = pickLabel(model);
+      const modelUid = model.uid;
+      const modelClassName = model.constructor?.name;
+      const modelResourceSnap = getResourceSnapshot(model.resource);
+      const modelResourceProps: Record<string, FlowContextInfosEnvNode> = {};
+      let hasModelResourceValues = false;
+      const modelCollectionName = modelResourceSnap.collectionName;
+      if (hasSnapshotValue(modelCollectionName)) {
+        modelResourceProps.collectionName = {
+          description: 'Collection name',
+          getVar: 'ctx.model.resource.collectionName',
+          value: modelCollectionName,
+        };
+        hasModelResourceValues = true;
+      }
+      const modelDataSourceKey = modelResourceSnap.dataSourceKey;
+      if (hasSnapshotValue(modelDataSourceKey)) {
+        modelResourceProps.dataSourceKey = {
+          description: 'Data source key',
+          getVar: 'ctx.model.resource.dataSourceKey',
+          value: modelDataSourceKey,
+        };
+        hasModelResourceValues = true;
+      }
+      const modelAssociationName = modelResourceSnap.associationName;
+      if (hasSnapshotValue(modelAssociationName)) {
+        modelResourceProps.associationName = {
+          description: 'Association name',
+          getVar: 'ctx.model.resource.associationName',
+          value: modelAssociationName,
+        };
+        hasModelResourceValues = true;
+      }
+
+      envs.flowModel = {
+        description: 'Current FlowModel information',
+        getVar: 'ctx.model',
+        properties: {
+          ...(hasSnapshotValue(modelLabel) ? { label: { description: 'Flow model label', value: modelLabel } } : {}),
+          ...(hasSnapshotValue(modelClassName)
+            ? {
+                modelClass: {
+                  description: 'Flow model class name',
+                  value: modelClassName,
+                },
+              }
+            : {}),
+          ...(hasSnapshotValue(modelUid)
+            ? { uid: { description: 'Flow model uid', getVar: 'ctx.model.uid', value: modelUid } }
+            : {}),
+          ...(hasModelResourceValues
+            ? {
+                resource: {
+                  description: 'Flow model resource',
+                  getVar: 'ctx.model.resource',
+                  properties: modelResourceProps,
+                },
+              }
+            : {}),
+        },
+      };
+    }
+
+    // popup info (when ctx.popup exists)
+    if (popupLike?.uid) {
+      envs.popup = {
+        description: 'Current popup information',
+        getVar: 'ctx.popup',
+        properties: {
+          uid: { description: 'Popup uid', getVar: 'ctx.popup.uid', value: popupLike.uid },
+          ...(popupLike?.record ? { record: { description: 'Popup record', getVar: 'ctx.popup.record' } } : {}),
+          ...(popupLike?.sourceRecord
+            ? { sourceRecord: { description: 'Popup source record', getVar: 'ctx.popup.sourceRecord' } }
+            : {}),
+        },
+      };
+    }
+
+    // block (when ctx.blockModel exists)
+    if (blockOwner) {
+      const blockLabel = pickLabel(blockOwner);
+      const blockUid = blockOwner.uid;
+      const blockModelClass = blockOwner.constructor?.name;
+      const blockResourceProps: Record<string, FlowContextInfosEnvNode> = {};
+      let hasBlockResourceValues = false;
+      const blockCollectionName = blockResourceSnap.collectionName;
+      if (hasSnapshotValue(blockCollectionName)) {
+        blockResourceProps.collectionName = {
+          description: 'Collection name',
+          getVar: `${blockResourceBaseExpr}.collectionName`,
+          value: blockCollectionName,
+        };
+        hasBlockResourceValues = true;
+      }
+      const blockDataSourceKey = blockResourceSnap.dataSourceKey;
+      if (hasSnapshotValue(blockDataSourceKey)) {
+        blockResourceProps.dataSourceKey = {
+          description: 'Data source key',
+          getVar: `${blockResourceBaseExpr}.dataSourceKey`,
+          value: blockDataSourceKey,
+        };
+        hasBlockResourceValues = true;
+      }
+      const blockAssociationName = blockResourceSnap.associationName;
+      if (hasSnapshotValue(blockAssociationName)) {
+        blockResourceProps.associationName = {
+          description: 'Association name',
+          getVar: `${blockResourceBaseExpr}.associationName`,
+          value: blockAssociationName,
+        };
+        hasBlockResourceValues = true;
+      }
+
+      envs.block = {
+        description: 'Current block information',
+        getVar: blockOwnerExpr,
+        properties: {
+          ...(hasSnapshotValue(blockLabel) ? { label: { description: 'Block label', value: blockLabel } } : {}),
+          ...(hasSnapshotValue(blockModelClass)
+            ? { modelClass: { description: 'Block model class name', value: blockModelClass } }
+            : {}),
+          ...(hasSnapshotValue(blockUid)
+            ? { uid: { description: 'Block uid', getVar: `${blockOwnerExpr}.uid`, value: blockUid } }
+            : {}),
+          ...(hasBlockResourceValues
+            ? {
+                resource: {
+                  description: 'Block resource',
+                  getVar: blockResourceBaseExpr,
+                  properties: blockResourceProps,
+                },
+              }
+            : {}),
+        },
+      };
+    }
+
+    // Current view blocks snapshot (page view or current popup view)
+    const viewUid = (() => {
+      const popupUid = popupLike?.uid;
+      if (hasSnapshotValue(popupUid)) return String(popupUid).trim();
+      const v = (inputArgs as any)?.viewUid;
+      if (hasSnapshotValue(v)) return String(v).trim();
+      return undefined;
+    })();
+
+    const engine = getMaybe(() => (evalCtx as any).engine) as FlowEngine | undefined;
+    const viewModel = viewUid ? engine?.getModel(viewUid, true) : undefined;
+
+    type ViewTreeNode = {
+      uid: string;
+      subModels?: Record<string, unknown>;
+      context?: { blockModel?: unknown };
+      resource?: unknown;
+      constructor?: { name?: string };
+    };
+
+    const isBlockModelInstance = (m: ViewTreeNode): boolean => m.context?.blockModel === m;
+
+    if (viewModel) {
+      const queue: ViewTreeNode[] = [viewModel as unknown as ViewTreeNode];
+      const blocks: Array<Record<string, JSONValue>> = [];
+
+      for (let i = 0; i < queue.length; i++) {
+        const m = queue[i];
+
+        if (isBlockModelInstance(m)) {
+          const modelClass = m.constructor?.name || m.uid;
+          const label = pickLabel(m as any) || modelClass || m.uid;
+
+          const resSnap = getResourceSnapshot(m.resource);
+          const resource: Record<string, JSONValue> = {};
+          if (hasSnapshotValue(resSnap.dataSourceKey)) resource.dataSourceKey = resSnap.dataSourceKey;
+          if (hasSnapshotValue(resSnap.collectionName)) resource.collectionName = resSnap.collectionName;
+          if (hasSnapshotValue(resSnap.associationName)) resource.associationName = resSnap.associationName;
+
+          const block: Record<string, JSONValue> = {
+            uid: m.uid,
+            label,
+            modelClass,
+            ...(Object.keys(resource).length > 0 ? { resource } : {}),
+          };
+          blocks.push(block);
+        }
+
+        const subModels = m.subModels;
+        if (subModels && typeof subModels === 'object') {
+          for (const v of Object.values(subModels)) {
+            if (!v) continue;
+            if (Array.isArray(v)) queue.push(...(v as ViewTreeNode[]));
+            else queue.push(v as ViewTreeNode);
+          }
+        }
+      }
+
+      if (blocks.length) {
+        envs.currentViewBlocks = {
+          description: 'Current view blocks',
+          value: blocks,
+        };
+      }
+    }
+
+    return envs;
+  }
+
+  /**
+   * 获取变量结构信息（来源于 PropertyMeta）。
+   *
+   * - 返回静态 plain object（不包含函数）
+   * - 支持 maxDepth（默认 3）与 path 剪裁
+   */
+  async getVarInfos(options: FlowContextGetVarInfosOptions = {}): Promise<Record<string, FlowContextApiInfo>> {
+    const maxDepthRaw = options.maxDepth ?? 3;
+    const maxDepth = Number.isFinite(maxDepthRaw) ? Math.max(1, Math.floor(maxDepthRaw)) : 3;
+    const version = 'v1' as RunJSVersion;
+    const evalCtx = this.createProxy();
+
+    const isPrivateKey = (key: string) => typeof key === 'string' && key.startsWith('_');
+
+    const isPromiseLike = (v: any): v is Promise<any> =>
+      !!v && (typeof v === 'object' || typeof v === 'function') && typeof (v as any).then === 'function';
+
+    // Per-call cache for resolved PropertyMetaFactory nodes to avoid repeated async calls.
+    const metaFactoryCache = new WeakMap<Function, Promise<PropertyMeta | null>>();
+    const resolveMetaOrFactory = async (meta?: PropertyMetaOrFactory): Promise<PropertyMeta | undefined> => {
+      if (!meta) return undefined;
+      if (typeof meta !== 'function') return meta;
+      let pending = metaFactoryCache.get(meta);
+      if (!pending) {
+        pending = (async () => {
+          const v = (meta as any).call(evalCtx, evalCtx);
+          const resolved = isPromiseLike(v) ? await v : v;
+          return resolved || null;
+        })();
+        metaFactoryCache.set(meta, pending);
+      }
+      const resolved = await pending;
+      return resolved || undefined;
+    };
+
+    const buildEnvs = async (): Promise<FlowContextInfosEnvs> => {
+      const envs: FlowContextInfosEnvs = {};
+
+      type ResourceSnapshotKey = 'dataSourceKey' | 'collectionName' | 'associationName' | 'filterByTk' | 'sourceId';
+      type ResourceSnapshot = Partial<Record<ResourceSnapshotKey, JSONValue>>;
+      type ResourceLike = ResourceSnapshot & {
+        getDataSourceKey?: () => JSONValue;
+        getFilterByTk?: () => JSONValue;
+        getSourceId?: () => JSONValue;
+        getResourceName?: () => string;
+        getMeta?: (key: string) => unknown;
+      };
+      type ModelCtorLike = { name?: string; meta?: { label?: string } };
+      type ModelLike = { uid?: string; title?: string; resource?: unknown; constructor?: ModelCtorLike };
+      type PopupLike = { uid?: string; resource?: unknown; record?: unknown; sourceRecord?: unknown; parent?: unknown };
+
+      const getMaybe = <T = any>(fn: () => T): T | undefined => {
+        try {
+          return fn();
+        } catch (_) {
+          return undefined;
+        }
+      };
+
+      const hasSnapshotValue = <T>(v: T): v is Exclude<T, undefined | null> => {
+        if (typeof v === 'undefined' || v === null) return false;
+        if (typeof v === 'string') return v.trim().length > 0;
+        if (Array.isArray(v)) return v.length > 0;
+        return true;
+      };
+
+      const getResourceSnapshot = (res: unknown): ResourceSnapshot => {
+        const out: ResourceSnapshot = {};
+        if (!res) return out;
+        const r = res as ResourceLike;
+
+        // Direct fields (popup/view inputArgs style)
+        for (const k of [
+          'dataSourceKey',
+          'collectionName',
+          'associationName',
+          'filterByTk',
+          'sourceId',
+        ] as ResourceSnapshotKey[]) {
+          const v = r?.[k];
+          if (hasSnapshotValue(v)) out[k] = v;
+        }
+
+        // FlowResource-like methods (BaseRecordResource/SQLResource)
+        if (!('dataSourceKey' in out)) {
+          const v = r.getDataSourceKey?.();
+          if (hasSnapshotValue(v)) out.dataSourceKey = v;
+        }
+        if (!('filterByTk' in out)) {
+          const v = r.getFilterByTk?.();
+          if (hasSnapshotValue(v)) out.filterByTk = v;
+        }
+        if (!('filterByTk' in out)) {
+          const v = r.getMeta?.('currentFilterByTk') as JSONValue | undefined;
+          if (hasSnapshotValue(v)) out.filterByTk = v;
+        }
+        if (!('sourceId' in out)) {
+          const v = r.getSourceId?.();
+          if (hasSnapshotValue(v)) out.sourceId = v;
+        }
+
+        // Infer collection/association from resourceName when not provided
+        if (!('collectionName' in out) || !('associationName' in out)) {
+          const rn = r.getResourceName?.();
+          const resourceName = typeof rn === 'string' ? rn.trim() : '';
+          if (resourceName) {
+            const parts = resourceName
+              .split('.')
+              .map((x) => x.trim())
+              .filter(Boolean);
+            if (parts.length === 1) {
+              if (!('collectionName' in out)) out.collectionName = parts[0];
+            } else if (parts.length >= 2) {
+              if (!('collectionName' in out)) out.collectionName = parts[0];
+              if (!('associationName' in out)) out.associationName = parts.slice(1).join('.');
+            }
+          }
+        }
+
+        return out;
+      };
+
+      // Resolve popup (may be Promise)
+      const popup = await (async () => {
+        try {
+          const raw = (evalCtx as any).popup;
+          return isPromiseLike(raw) ? await raw : raw;
+        } catch (_) {
+          return undefined;
+        }
+      })();
+
+      const popupLike = popup as PopupLike | undefined;
+      const model = getMaybe(() => (evalCtx as any).model) as ModelLike | undefined;
+      const blockModel = getMaybe(() => (evalCtx as any).blockModel) as ModelLike | undefined;
+      const inputArgs = getMaybe(() => (evalCtx as any).view?.inputArgs) as
+        | (ResourceLike & { viewUid?: string })
+        | undefined;
+      const ctxResource = getMaybe(() => (evalCtx as any).resource) as ResourceLike | undefined;
+
+      const popupResource = popupLike?.resource;
+      const popupResourceSnap = getResourceSnapshot(popupResource);
+
+      const blockOwner = blockModel;
+      const blockOwnerExpr = blockModel ? 'ctx.blockModel' : undefined;
+      const blockResourceBaseExpr = blockOwnerExpr ? `${blockOwnerExpr}.resource` : undefined;
+      const blockResource = blockOwner?.resource;
+      const blockResourceSnap = getResourceSnapshot(blockResource);
+      const inputArgsSnap = getResourceSnapshot(inputArgs);
+      const ctxResourceSnap = getResourceSnapshot(ctxResource);
+
+      // Resource snapshot (for prompt)
+      const pickWithGetVar = <T>(
+        pairs: Array<{
+          value: T | undefined;
+          getVar: string;
+        }>,
+      ): { value: T; getVar: string } | undefined => {
+        for (const p of pairs) {
+          if (hasSnapshotValue(p.value)) return { value: p.value, getVar: p.getVar };
+        }
+        return undefined;
+      };
+
+      const hasAnyResourceValuesIn = (snap: ResourceSnapshot): boolean =>
+        hasSnapshotValue(snap.collectionName) ||
+        hasSnapshotValue(snap.dataSourceKey) ||
+        hasSnapshotValue(snap.associationName);
+
+      const resourceBaseExpr: string | undefined = hasAnyResourceValuesIn(popupResourceSnap)
+        ? 'ctx.popup.resource'
+        : hasAnyResourceValuesIn(blockResourceSnap)
+          ? blockResourceBaseExpr
+          : hasAnyResourceValuesIn(inputArgsSnap)
+            ? 'ctx.view.inputArgs'
+            : hasAnyResourceValuesIn(ctxResourceSnap)
+              ? 'ctx.resource'
+              : undefined;
+
+      const collectionNamePick = pickWithGetVar([
+        { value: popupResourceSnap?.collectionName, getVar: 'ctx.popup.resource.collectionName' },
+        { value: blockResourceSnap?.collectionName, getVar: `${blockResourceBaseExpr}.collectionName` },
+        { value: inputArgsSnap?.collectionName, getVar: 'ctx.view.inputArgs.collectionName' },
+        { value: ctxResourceSnap?.collectionName, getVar: 'ctx.resource.collectionName' },
+      ]);
+      const dataSourceKeyPick = pickWithGetVar([
+        { value: popupResourceSnap?.dataSourceKey, getVar: 'ctx.popup.resource.dataSourceKey' },
+        { value: blockResourceSnap?.dataSourceKey, getVar: `${blockResourceBaseExpr}.dataSourceKey` },
+        { value: inputArgsSnap?.dataSourceKey, getVar: 'ctx.view.inputArgs.dataSourceKey' },
+        { value: ctxResourceSnap?.dataSourceKey, getVar: 'ctx.resource.dataSourceKey' },
+      ]);
+      const associationNamePick = pickWithGetVar([
+        { value: popupResourceSnap?.associationName, getVar: 'ctx.popup.resource.associationName' },
+        { value: blockResourceSnap?.associationName, getVar: `${blockResourceBaseExpr}.associationName` },
+        { value: inputArgsSnap?.associationName, getVar: 'ctx.view.inputArgs.associationName' },
+        { value: ctxResourceSnap?.associationName, getVar: 'ctx.resource.associationName' },
+      ]);
+      const filterByTkPick = pickWithGetVar([
+        { value: popupResourceSnap?.filterByTk, getVar: 'ctx.popup.resource.filterByTk' },
+        { value: blockResourceSnap?.filterByTk, getVar: `${blockResourceBaseExpr}.filterByTk` },
+        { value: inputArgsSnap?.filterByTk, getVar: 'ctx.view.inputArgs.filterByTk' },
+        { value: ctxResourceSnap?.filterByTk, getVar: 'ctx.resource.filterByTk' },
+      ]);
+      const sourceIdPick = pickWithGetVar([
+        { value: popupResourceSnap?.sourceId, getVar: 'ctx.popup.resource.sourceId' },
+        { value: blockResourceSnap?.sourceId, getVar: `${blockResourceBaseExpr}.sourceId` },
+        { value: inputArgsSnap?.sourceId, getVar: 'ctx.view.inputArgs.sourceId' },
+        { value: ctxResourceSnap?.sourceId, getVar: 'ctx.resource.sourceId' },
+      ]);
+
+      const resourceProps: Record<string, FlowContextInfosEnvNode> = {};
+      let hasResourceValues = false;
+      const collectionNameValue = collectionNamePick?.value;
+      if (hasSnapshotValue(collectionNameValue)) {
+        resourceProps.collectionName = {
+          description: 'Collection name',
+          getVar: collectionNamePick?.getVar || (resourceBaseExpr ? `${resourceBaseExpr}.collectionName` : undefined),
+          value: collectionNameValue,
+        };
+        hasResourceValues = true;
+      }
+      const dataSourceKeyValue = dataSourceKeyPick?.value;
+      if (hasSnapshotValue(dataSourceKeyValue)) {
+        resourceProps.dataSourceKey = {
+          description: 'Data source key',
+          getVar: dataSourceKeyPick?.getVar || (resourceBaseExpr ? `${resourceBaseExpr}.dataSourceKey` : undefined),
+          value: dataSourceKeyValue,
+        };
+        hasResourceValues = true;
+      }
+      const associationNameValue = associationNamePick?.value;
+      if (hasSnapshotValue(associationNameValue)) {
+        resourceProps.associationName = {
+          description: 'Association name',
+          getVar: associationNamePick?.getVar || (resourceBaseExpr ? `${resourceBaseExpr}.associationName` : undefined),
+          value: associationNameValue,
+        };
+        hasResourceValues = true;
+      }
+
+      // Only include envs.resource when snapshot contains at least one resource value.
+      // Optional fields like filterByTk/sourceId are included (without value) only when envs.resource exists.
+      if (hasResourceValues) {
+        if (hasSnapshotValue(filterByTkPick?.value)) {
+          resourceProps.filterByTk = {
+            description: 'Record filterByTk',
+            getVar: filterByTkPick?.getVar || (resourceBaseExpr ? `${resourceBaseExpr}.filterByTk` : undefined),
+          };
+        }
+        if (hasSnapshotValue(sourceIdPick?.value)) {
+          resourceProps.sourceId = {
+            description: 'Source record ID (sourceId)',
+            getVar: sourceIdPick?.getVar || (resourceBaseExpr ? `${resourceBaseExpr}.sourceId` : undefined),
+          };
+        }
+
+        envs.resource = {
+          description: 'Resource information',
+          getVar: resourceBaseExpr,
+          properties: resourceProps,
+        };
+      }
+
+      // Record (only when filterByTk is available)
+      if (hasSnapshotValue(filterByTkPick?.value)) {
+        envs.record = {
+          description: 'Current record',
+          getVar: 'ctx.record',
+        };
+      }
+
+      const pickLabel = (obj: ModelLike | null | undefined): string | undefined => {
+        try {
+          const t = obj?.title;
+          if (typeof t === 'string' && t.trim()) return t;
+        } catch (_) {
+          // ignore
+        }
+        try {
+          const label = obj?.constructor?.meta?.label;
+          if (typeof label === 'string' && label.trim()) return label;
+        } catch (_) {
+          // ignore
+        }
+        return undefined;
+      };
+
+      // FlowModel (when ctx.model exists)
+      if (model) {
+        const modelLabel = pickLabel(model);
+        const modelUid = model.uid;
+        const modelClassName = model.constructor?.name;
+        const modelResourceSnap = getResourceSnapshot(model.resource);
+        const modelResourceProps: Record<string, FlowContextInfosEnvNode> = {};
+        let hasModelResourceValues = false;
+        const modelCollectionName = modelResourceSnap.collectionName;
+        if (hasSnapshotValue(modelCollectionName)) {
+          modelResourceProps.collectionName = {
+            description: 'Collection name',
+            getVar: 'ctx.model.resource.collectionName',
+            value: modelCollectionName,
+          };
+          hasModelResourceValues = true;
+        }
+        const modelDataSourceKey = modelResourceSnap.dataSourceKey;
+        if (hasSnapshotValue(modelDataSourceKey)) {
+          modelResourceProps.dataSourceKey = {
+            description: 'Data source key',
+            getVar: 'ctx.model.resource.dataSourceKey',
+            value: modelDataSourceKey,
+          };
+          hasModelResourceValues = true;
+        }
+        const modelAssociationName = modelResourceSnap.associationName;
+        if (hasSnapshotValue(modelAssociationName)) {
+          modelResourceProps.associationName = {
+            description: 'Association name',
+            getVar: 'ctx.model.resource.associationName',
+            value: modelAssociationName,
+          };
+          hasModelResourceValues = true;
+        }
+
+        envs.flowModel = {
+          description: 'Current FlowModel information',
+          getVar: 'ctx.model',
+          properties: {
+            ...(hasSnapshotValue(modelLabel) ? { label: { description: 'Flow model label', value: modelLabel } } : {}),
+            ...(hasSnapshotValue(modelClassName)
+              ? {
+                  modelClass: {
+                    description: 'Flow model class name',
+                    value: modelClassName,
+                  },
+                }
+              : {}),
+            ...(hasSnapshotValue(modelUid)
+              ? { uid: { description: 'Flow model uid', getVar: 'ctx.model.uid', value: modelUid } }
+              : {}),
+            ...(hasModelResourceValues
+              ? {
+                  resource: {
+                    description: 'Resource information',
+                    getVar: 'ctx.model.resource',
+                    properties: {
+                      ...modelResourceProps,
+                      ...(hasSnapshotValue(modelResourceSnap?.filterByTk)
+                        ? {
+                            filterByTk: {
+                              description: 'Record filterByTk',
+                              getVar: 'ctx.model.resource.filterByTk',
+                            },
+                          }
+                        : {}),
+                      ...(hasSnapshotValue(modelResourceSnap?.sourceId)
+                        ? {
+                            sourceId: {
+                              description: 'Source record ID (sourceId)',
+                              getVar: 'ctx.model.resource.sourceId',
+                            },
+                          }
+                        : {}),
+                    },
+                  },
+                }
+              : {}),
+          },
+        };
+      }
+
+      // Block (when ctx.blockModel exists)
+      if (blockOwner && blockOwnerExpr) {
+        const blockLabel = pickLabel(blockOwner);
+        const blockUid = blockOwner.uid;
+        const blockModelClass = blockOwner.constructor?.name;
+
+        const blockResourceProps: Record<string, FlowContextInfosEnvNode> = {};
+        let hasBlockResourceValues = false;
+        const blockCollectionName = blockResourceSnap.collectionName;
+        if (hasSnapshotValue(blockCollectionName)) {
+          blockResourceProps.collectionName = {
+            description: 'Collection name',
+            getVar: `${blockResourceBaseExpr}.collectionName`,
+            value: blockCollectionName,
+          };
+          hasBlockResourceValues = true;
+        }
+        const blockDataSourceKey = blockResourceSnap.dataSourceKey;
+        if (hasSnapshotValue(blockDataSourceKey)) {
+          blockResourceProps.dataSourceKey = {
+            description: 'Data source key',
+            getVar: `${blockResourceBaseExpr}.dataSourceKey`,
+            value: blockDataSourceKey,
+          };
+          hasBlockResourceValues = true;
+        }
+        const blockAssociationName = blockResourceSnap.associationName;
+        if (hasSnapshotValue(blockAssociationName)) {
+          blockResourceProps.associationName = {
+            description: 'Association name',
+            getVar: `${blockResourceBaseExpr}.associationName`,
+            value: blockAssociationName,
+          };
+          hasBlockResourceValues = true;
+        }
+
+        envs.block = {
+          description: 'Current block information',
+          getVar: 'ctx.blockModel',
+          properties: {
+            ...(hasSnapshotValue(blockLabel) ? { label: { description: 'Block label', value: blockLabel } } : {}),
+            ...(hasSnapshotValue(blockModelClass)
+              ? {
+                  modelClass: {
+                    description: 'Block model class name',
+                    value: blockModelClass,
+                  },
+                }
+              : {}),
+            ...(hasSnapshotValue(blockUid)
+              ? {
+                  uid: {
+                    description: 'Block uid',
+                    getVar: 'ctx.blockModel.uid',
+                    value: blockUid,
+                  },
+                }
+              : {}),
+            ...(hasBlockResourceValues
+              ? {
+                  resource: {
+                    description: 'Resource information',
+                    getVar: 'ctx.blockModel.resource',
+                    properties: {
+                      ...blockResourceProps,
+                      ...(hasSnapshotValue(blockResourceSnap?.filterByTk)
+                        ? {
+                            filterByTk: {
+                              description: 'Record filterByTk',
+                              getVar: 'ctx.blockModel.resource.filterByTk',
+                            },
+                          }
+                        : {}),
+                      ...(hasSnapshotValue(blockResourceSnap?.sourceId)
+                        ? {
+                            sourceId: {
+                              description: 'Source record ID (sourceId)',
+                              getVar: 'ctx.blockModel.resource.sourceId',
+                            },
+                          }
+                        : {}),
+                    },
+                  },
+                }
+              : {}),
+          },
+        };
+      }
+
+      // Popup (only when popup exists)
+      if (popupLike?.uid) {
+        const popupUid = popupLike.uid;
+        const popupResourceProps: Record<string, FlowContextInfosEnvNode> = {};
+        let hasPopupResourceValues = false;
+        const popupCollectionName = popupResourceSnap.collectionName;
+        if (hasSnapshotValue(popupCollectionName)) {
+          popupResourceProps.collectionName = {
+            description: 'Collection name',
+            getVar: 'ctx.popup.resource.collectionName',
+            value: popupCollectionName,
+          };
+          hasPopupResourceValues = true;
+        }
+        const popupDataSourceKey = popupResourceSnap.dataSourceKey;
+        if (hasSnapshotValue(popupDataSourceKey)) {
+          popupResourceProps.dataSourceKey = {
+            description: 'Data source key',
+            getVar: 'ctx.popup.resource.dataSourceKey',
+            value: popupDataSourceKey,
+          };
+          hasPopupResourceValues = true;
+        }
+        const popupAssociationName = popupResourceSnap.associationName;
+        if (hasSnapshotValue(popupAssociationName)) {
+          popupResourceProps.associationName = {
+            description: 'Association name',
+            getVar: 'ctx.popup.resource.associationName',
+            value: popupAssociationName,
+          };
+          hasPopupResourceValues = true;
+        }
+
+        envs.popup = {
+          description: 'Current popup information',
+          getVar: 'ctx.popup',
+          properties: {
+            uid: { description: 'Popup uid', getVar: 'ctx.popup.uid', value: popupUid },
+            record: {
+              description: 'Current popup record (object).',
+              getVar: 'ctx.popup.record',
+            },
+            sourceRecord: {
+              description: 'Current popup sourceRecord (object).',
+              getVar: 'ctx.popup.sourceRecord',
+            },
+            parent: {
+              description: 'Parent popup info (object).',
+              getVar: 'ctx.popup.parent',
+            },
+            ...(hasPopupResourceValues
+              ? {
+                  resource: {
+                    description: 'Resource information',
+                    getVar: 'ctx.popup.resource',
+                    properties: {
+                      ...popupResourceProps,
+                      ...(hasSnapshotValue(popupResourceSnap?.filterByTk)
+                        ? {
+                            filterByTk: {
+                              description: 'Record filterByTk',
+                              getVar: 'ctx.popup.resource.filterByTk',
+                            },
+                          }
+                        : {}),
+                      ...(hasSnapshotValue(popupResourceSnap?.sourceId)
+                        ? {
+                            sourceId: {
+                              description: 'Source record ID (sourceId)',
+                              getVar: 'ctx.popup.resource.sourceId',
+                            },
+                          }
+                        : {}),
+                    },
+                  },
+                }
+              : {}),
+          },
+        };
+      }
+
+      // Current view blocks snapshot (page or current popup)
+      const viewUid = (() => {
+        const popupUid = popupLike?.uid;
+        if (hasSnapshotValue(popupUid)) return popupUid.trim();
+        const v = inputArgs?.viewUid;
+        if (hasSnapshotValue(v)) return v.trim();
+        return undefined;
+      })();
+
+      const engine = getMaybe(() => (evalCtx as any).engine) as FlowEngine | undefined;
+      const viewModel = viewUid ? engine?.getModel(viewUid, true) : undefined;
+
+      type ViewTreeNode = {
+        uid: string;
+        subModels?: Record<string, unknown>;
+        context?: { blockModel?: unknown };
+        resource?: unknown;
+        constructor?: { name?: string };
+      };
+
+      const isBlockModelInstance = (m: ViewTreeNode): boolean => m.context?.blockModel === m;
+
+      if (viewModel) {
+        const queue: ViewTreeNode[] = [viewModel as unknown as ViewTreeNode];
+        const blocks: Array<Record<string, JSONValue>> = [];
+
+        for (let i = 0; i < queue.length; i++) {
+          const m = queue[i];
+
+          if (isBlockModelInstance(m)) {
+            const modelClass = m.constructor?.name || m.uid;
+            const label = pickLabel(m) || modelClass || m.uid;
+
+            const resSnap = getResourceSnapshot(m.resource);
+            const resource: Record<string, JSONValue> = {};
+            if (hasSnapshotValue(resSnap.dataSourceKey)) resource.dataSourceKey = resSnap.dataSourceKey;
+            if (hasSnapshotValue(resSnap.collectionName)) resource.collectionName = resSnap.collectionName;
+            if (hasSnapshotValue(resSnap.associationName)) resource.associationName = resSnap.associationName;
+
+            const block: Record<string, JSONValue> = {
+              uid: m.uid,
+              label,
+              modelClass,
+              ...(Object.keys(resource).length > 0 ? { resource } : {}),
+            };
+            blocks.push(block);
+          }
+
+          const subModels = m.subModels;
+          if (subModels && typeof subModels === 'object') {
+            for (const v of Object.values(subModels)) {
+              if (!v) continue;
+              if (Array.isArray(v)) queue.push(...(v as ViewTreeNode[]));
+              else queue.push(v as ViewTreeNode);
+            }
+          }
+        }
+
+        envs.currentViewBlocks = {
+          description: 'Current view blocks',
+          value: blocks,
+        };
+      }
+
+      return envs;
+    };
+
+    const normalizePath = (raw: string): string | undefined => {
+      if (typeof raw !== 'string') return undefined;
+      const s = raw.trim();
+      if (!s) return undefined;
+      const extracted = extractPropertyPath(s);
+      if (Array.isArray(extracted) && extracted.length > 0) {
+        return extracted.join('.');
+      }
+      if (s === 'ctx') return '';
+      if (s.startsWith('ctx.')) return s.slice(4).trim();
+      return s;
+    };
+
+    const paths = (() => {
+      const p = options.path;
+      const list = typeof p === 'string' ? [p] : Array.isArray(p) ? p : [];
+      return list
+        .map((x) => normalizePath(String(x)))
+        .filter((x): x is string => typeof x === 'string' && x.length > 0);
+    })();
+
+    const hasRootPath = (() => {
+      const p = options.path;
+      if (typeof p === 'string') return normalizePath(p) === '';
+      if (Array.isArray(p)) return p.some((x) => normalizePath(String(x)) === '');
+      return false;
+    })();
+
+    const collectKeysDeep = (ctx: FlowContext, out: Set<string>, key: '_props' | '_methods', visited: WeakSet<any>) => {
+      if (!ctx || typeof ctx !== 'object') return;
+      if (visited.has(ctx as any)) return;
+      visited.add(ctx as any);
+      try {
+        const bag = (ctx as any)[key];
+        if (bag && typeof bag === 'object') {
+          for (const k of Object.keys(bag)) out.add(k);
+        }
+      } catch (_) {
+        // ignore
+      }
+      try {
+        const delegates = (ctx as any)._delegates;
+        if (Array.isArray(delegates)) {
+          for (const d of delegates) collectKeysDeep(d, out, key, visited);
+        }
+      } catch (_) {
+        // ignore
+      }
+    };
+
+    const getRunJSDoc = (): any => {
+      const modelClass = getModelClassName(this);
+      const Ctor = RunJSContextRegistry.resolve(version, modelClass) || RunJSContextRegistry.resolve(version, '*');
+      if (!Ctor) return {};
+      const locale = (this as any)?.api?.auth?.locale || (this as any)?.i18n?.language || (this as any)?.locale;
+      try {
+        if ((Ctor as any)?.getDoc?.length) {
+          return (Ctor as any).getDoc(locale) || {};
+        }
+        return (Ctor as any)?.getDoc?.() || {};
+      } catch (_) {
+        return {};
+      }
+    };
+
+    const doc = getRunJSDoc();
+    const docMethods = __isPlainObject(doc?.methods) ? (doc.methods as Record<string, any>) : {};
+    const docProps = __isPlainObject(doc?.properties) ? (doc.properties as Record<string, any>) : {};
+
+    const toDocObject = (node: any): any | undefined => {
+      if (typeof node === 'string') return { description: node };
+      if (__isPlainObject(node)) return node;
+      return undefined;
+    };
+
+    const evalBool = async (raw: any, call: (fn: Function) => any): Promise<boolean | undefined> => {
+      if (typeof raw === 'undefined') return undefined;
+      if (typeof raw === 'boolean') return raw;
+      if (typeof raw === 'function') {
+        try {
+          const v = call(raw);
+          return isPromiseLike(v) ? !!(await v) : !!v;
+        } catch (_) {
+          return false;
+        }
+      }
+      return !!raw;
+    };
+
+    const evalString = async (raw: any, call: (fn: Function) => any): Promise<string | undefined> => {
+      if (typeof raw === 'undefined' || raw === null) return undefined;
+      if (typeof raw === 'string') return raw;
+      if (typeof raw === 'function') {
+        try {
+          const v = call(raw);
+          const resolved = isPromiseLike(v) ? await v : v;
+          if (typeof resolved === 'string') return resolved;
+          return typeof resolved === 'undefined' || resolved === null ? undefined : String(resolved);
+        } catch (_) {
+          return undefined;
+        }
+      }
+      return String(raw);
+    };
+
+    const evalRunJSHidden = async (
+      raw: any,
+    ): Promise<{
+      hideSelf: boolean;
+      hideSubpaths: string[];
+    }> => {
+      let hideSelf = false;
+      let list: any = [];
+      try {
+        if (typeof raw === 'boolean') hideSelf = raw;
+        else if (Array.isArray(raw)) list = raw;
+        else if (typeof raw === 'function') {
+          const v = raw(evalCtx);
+          const resolved = isPromiseLike(v) ? await v : v;
+          if (typeof resolved === 'boolean') hideSelf = resolved;
+          else if (Array.isArray(resolved)) list = resolved;
+        }
+      } catch (_) {
+        hideSelf = false;
+        list = [];
+      }
+
+      const hideSubpaths: string[] = [];
+      if (Array.isArray(list)) {
+        for (const p of list) {
+          if (typeof p !== 'string') continue;
+          const s = p.trim();
+          if (!s) continue;
+          // Only relative paths are supported. Ignore "ctx.xxx" absolute style to avoid ambiguity.
+          if (s === 'ctx' || s.startsWith('ctx.')) continue;
+          if (/\s/.test(s)) continue;
+          hideSubpaths.push(s);
+        }
+      }
+      return { hideSelf: !!hideSelf, hideSubpaths };
+    };
+
+    const isHiddenByPrefixes = (path: string, hiddenPrefixes: Set<string>) => {
+      if (!path) return false;
+      const parts = path.split('.').filter(Boolean);
+      while (parts.length) {
+        if (hiddenPrefixes.has(parts.join('.'))) return true;
+        parts.pop();
+      }
+      return false;
+    };
+
+    const pickMethodInfo = (obj: any): Partial<FlowContextApiInfo> => {
+      const src = toDocObject(obj);
+      if (!src) return {};
+      const out: any = {};
+      for (const k of ['description', 'examples', 'completion', 'ref', 'params', 'returns']) {
+        const v = (src as any)[k];
+        if (typeof v !== 'undefined') out[k] = v;
+      }
+      if (Array.isArray(out.examples)) {
+        out.examples = out.examples.filter((x: any) => typeof x === 'string' && x.trim());
+      }
+      return out;
+    };
+
+    const pickPropertyInfo = (obj: any): Partial<FlowContextApiInfo> => {
+      const src = toDocObject(obj);
+      if (!src) return {};
+      const out: any = {};
+      for (const k of [
+        'title',
+        'type',
+        'interface',
+        'description',
+        'examples',
+        'completion',
+        'ref',
+        'params',
+        'returns',
+      ]) {
+        const v = (src as any)[k];
+        if (typeof v !== 'undefined') out[k] = v;
+      }
+      if (Array.isArray(out.examples)) {
+        out.examples = out.examples.filter((x: any) => typeof x === 'string' && x.trim());
+      }
+      return out;
+    };
+
+    const getMethodInfoFromChain = (name: string): FlowContextMethodInfoInput | undefined => {
+      const visited = new WeakSet<any>();
+      const walk = (ctx: FlowContext): FlowContextMethodInfoInput | undefined => {
+        if (!ctx || typeof ctx !== 'object') return undefined;
+        if (visited.has(ctx as any)) return undefined;
+        visited.add(ctx as any);
+        if (Object.prototype.hasOwnProperty.call((ctx as any)._methodInfos || {}, name)) {
+          return (ctx as any)._methodInfos?.[name] as FlowContextMethodInfoInput;
+        }
+        const delegates = (ctx as any)._delegates;
+        if (Array.isArray(delegates)) {
+          for (const d of delegates) {
+            const found = walk(d);
+            if (found) return found;
+          }
+        }
+        return undefined;
+      };
+      return walk(this);
+    };
+
+    const hasMethodInChain = (name: string): boolean => {
+      const visited = new WeakSet<any>();
+      const walk = (ctx: FlowContext): boolean => {
+        if (!ctx || typeof ctx !== 'object') return false;
+        if (visited.has(ctx as any)) return false;
+        visited.add(ctx as any);
+        if (Object.prototype.hasOwnProperty.call((ctx as any)._methods || {}, name)) return true;
+        const delegates = (ctx as any)._delegates;
+        if (Array.isArray(delegates)) {
+          for (const d of delegates) {
+            if (walk(d)) return true;
+          }
+        }
+        return false;
+      };
+      return walk(this);
+    };
+
+    const buildMethodInfo = async (name: string): Promise<FlowContextApiInfo | undefined> => {
+      if (isPrivateKey(name)) return undefined;
+      const docNode = docMethods[name];
+      const info = getMethodInfoFromChain(name);
+      const exists = typeof docNode !== 'undefined' || typeof info !== 'undefined' || hasMethodInChain(name);
+      if (!exists) return undefined;
+
+      const docObj = toDocObject(docNode);
+      const docHidden = await evalBool((docObj as any)?.hidden, (fn) => fn(evalCtx));
+      const infoHidden = await evalBool(info?.hidden, (fn) => fn(evalCtx));
+      if (!!docHidden || !!infoHidden) return undefined;
+
+      const docDisabled = await evalBool((docObj as any)?.disabled, (fn) => fn(evalCtx));
+      const docDisabledReason = await evalString((docObj as any)?.disabledReason, (fn) => fn(evalCtx));
+      const infoDisabled = await evalBool(info?.disabled, (fn) => fn(evalCtx));
+      const infoDisabledReason = await evalString(info?.disabledReason, (fn) => fn(evalCtx));
+      const disabled = typeof infoDisabled !== 'undefined' ? infoDisabled : docDisabled;
+      const disabledReason = typeof infoDisabledReason !== 'undefined' ? infoDisabledReason : docDisabledReason;
+
+      let out: FlowContextApiInfo = {};
+      out = { ...out, ...pickMethodInfo(docObj) };
+      out = { ...out, ...pickMethodInfo(info) };
+      if (typeof disabled !== 'undefined') out.disabled = !!disabled;
+      if (typeof disabledReason !== 'undefined') out.disabledReason = disabledReason;
+      if (!Object.keys(out).length) return undefined;
+      // Mark as callable for tooling (e.g. code-editor completion).
+      out.type = 'function';
+      return out;
+    };
+
+    const buildPropertyInfoFromNodes = async (args: {
+      docNode?: any;
+      metaNode?: PropertyMetaOrFactory;
+      infoNode?: FlowContextPropertyInfoInput;
+      depth: number;
+      pathFromRoot: string[];
+      hiddenPrefixes: Set<string>;
+    }): Promise<FlowContextApiInfo | undefined> => {
+      const { docNode, metaNode, infoNode, depth, pathFromRoot, hiddenPrefixes } = args;
+      const relPath = pathFromRoot.join('.');
+      if (isHiddenByPrefixes(relPath, hiddenPrefixes)) return undefined;
+
+      const docObj = toDocObject(docNode);
+      const infoObj = toDocObject(infoNode);
+
+      const docHiddenDecision = await evalRunJSHidden((docObj as any)?.hidden);
+      if (docHiddenDecision.hideSelf) return undefined;
+      const infoHiddenDecision = await evalRunJSHidden((infoObj as any)?.hidden);
+      if (infoHiddenDecision.hideSelf) return undefined;
+
+      const resolvedMetaNode = await resolveMetaOrFactory(metaNode);
+      const metaHidden = await evalBool(resolvedMetaNode?.hidden, (fn) => (fn as any).call(resolvedMetaNode, evalCtx));
+      if (metaHidden) return undefined;
+
+      const childHiddenPrefixes = new Set(hiddenPrefixes);
+      for (const sub of [...docHiddenDecision.hideSubpaths, ...infoHiddenDecision.hideSubpaths]) {
+        const normalized = sub.trim();
+        if (!normalized) continue;
+        const stripped = normalized === 'ctx' ? '' : normalized.startsWith('ctx.') ? normalized.slice(4) : normalized;
+        if (!stripped) continue;
+        const abs = relPath ? `${relPath}.${stripped}` : stripped;
+        childHiddenPrefixes.add(abs);
+      }
+
+      const docDisabled = await evalBool((docObj as any)?.disabled, (fn) => fn(evalCtx));
+      const docDisabledReason = await evalString((docObj as any)?.disabledReason, (fn) => fn(evalCtx));
+      const metaDisabled = await evalBool(resolvedMetaNode?.disabled, (fn) =>
+        (fn as any).call(resolvedMetaNode, evalCtx),
+      );
+      const metaDisabledReason = await evalString(resolvedMetaNode?.disabledReason, (fn) =>
+        (fn as any).call(resolvedMetaNode, evalCtx),
+      );
+      const infoDisabled = await evalBool((infoObj as any)?.disabled, (fn) => fn(evalCtx));
+      const infoDisabledReason = await evalString((infoObj as any)?.disabledReason, (fn) => fn(evalCtx));
+      const disabled =
+        typeof infoDisabled !== 'undefined'
+          ? infoDisabled
+          : typeof metaDisabled !== 'undefined'
+            ? metaDisabled
+            : docDisabled;
+      const disabledReason =
+        typeof infoDisabledReason !== 'undefined'
+          ? infoDisabledReason
+          : typeof metaDisabledReason !== 'undefined'
+            ? metaDisabledReason
+            : docDisabledReason;
+
+      let out: FlowContextApiInfo = {};
+      out = { ...out, ...pickPropertyInfo(docObj) };
+      out = { ...out, ...pickPropertyInfo(resolvedMetaNode) };
+      out = { ...out, ...pickPropertyInfo(infoObj) };
+      if (typeof disabled !== 'undefined') out.disabled = !!disabled;
+      if (typeof disabledReason !== 'undefined') out.disabledReason = disabledReason;
+
+      if (depth >= maxDepth) return Object.keys(out).length ? out : undefined;
+
+      const docChildren = __isPlainObject((docObj as any)?.properties)
+        ? ((docObj as any).properties as any as Record<string, any>)
+        : undefined;
+
+      let metaChildren: Record<string, PropertyMetaOrFactory> | undefined;
+      if (resolvedMetaNode?.properties) {
+        try {
+          const props = resolvedMetaNode.properties;
+          if (typeof props === 'function') {
+            const resolved = await (props as any).call(resolvedMetaNode, evalCtx);
+            resolvedMetaNode.properties = resolved;
+            metaChildren = resolved as Record<string, PropertyMetaOrFactory>;
+          } else if (__isPlainObject(props)) {
+            metaChildren = props as Record<string, PropertyMetaOrFactory>;
+          }
+        } catch (_) {
+          metaChildren = undefined;
+        }
+      }
+
+      let infoChildren: Record<string, FlowContextPropertyInfoInput> | undefined;
+      if (__isPlainObject(infoObj) && (infoObj as any)?.properties) {
+        try {
+          const props = (infoObj as any).properties;
+          if (typeof props === 'function') {
+            const resolved = await (props as any).call(infoObj, evalCtx);
+            (infoObj as any).properties = resolved;
+            infoChildren = resolved as Record<string, FlowContextPropertyInfoInput>;
+          } else if (__isPlainObject(props)) {
+            infoChildren = props as Record<string, FlowContextPropertyInfoInput>;
+          }
+        } catch (_) {
+          infoChildren = undefined;
+        }
+      }
+
+      const keys = new Set<string>();
+      if (docChildren) for (const k of Object.keys(docChildren)) keys.add(k);
+      if (metaChildren) for (const k of Object.keys(metaChildren)) keys.add(k);
+      if (infoChildren) for (const k of Object.keys(infoChildren)) keys.add(k);
+      if (!keys.size) return Object.keys(out).length ? out : undefined;
+
+      const childrenOut: Record<string, FlowContextApiInfo> = {};
+      for (const k of keys) {
+        if (isPrivateKey(k)) continue;
+        const child = await buildPropertyInfoFromNodes({
+          docNode: docChildren?.[k],
+          metaNode: metaChildren?.[k],
+          infoNode: infoChildren?.[k],
+          depth: depth + 1,
+          pathFromRoot: [...pathFromRoot, k],
+          hiddenPrefixes: childHiddenPrefixes,
+        });
+        if (child) childrenOut[k] = child;
+      }
+      if (Object.keys(childrenOut).length) out.properties = childrenOut;
+      if (!Object.keys(out).length) return undefined;
+      return out;
+    };
+
+    const resolvePropertyMetaAtPath = async (segments: string[]): Promise<PropertyMetaOrFactory | undefined> => {
+      if (!segments.length) return undefined;
+      const [first, ...rest] = segments;
+      const opt = this.getPropertyOptions(first);
+      if (!opt?.meta) return undefined;
+      try {
+        // Fast path: when querying the root key only, return the meta (may be a factory) and let
+        // buildPropertyInfoFromNodes decide whether to resolve it based on maxDepth.
+        if (!rest.length) return opt.meta as PropertyMetaOrFactory;
+
+        let current = await resolveMetaOrFactory(opt.meta as PropertyMetaOrFactory);
+        if (!current) return undefined;
+
+        for (let i = 0; i < rest.length; i++) {
+          const key = rest[i];
+
+          let props: any = (current as any)?.properties;
+          if (!props) return undefined;
+          if (typeof props === 'function') {
+            const resolved = await props.call(current, evalCtx);
+            (current as any).properties = resolved;
+            props = resolved;
+          }
+          if (!props || typeof props !== 'object') return undefined;
+
+          const next = (props as any)?.[key] as PropertyMetaOrFactory | undefined;
+          if (!next) return undefined;
+
+          // Return the node at the requested path (may still be a factory).
+          if (i === rest.length - 1) return next;
+
+          const resolvedNext = await resolveMetaOrFactory(next);
+          if (!resolvedNext) return undefined;
+          current = resolvedNext;
+        }
+
+        return undefined;
+      } catch (_) {
+        return undefined;
+      }
+    };
+
+    const resolvePropertyInfoAtPath = async (segments: string[]): Promise<FlowContextPropertyInfoInput | undefined> => {
+      if (!segments.length) return undefined;
+      const [first, ...rest] = segments;
+      const opt = this.getPropertyOptions(first);
+      if (!opt?.info) return undefined;
+
+      try {
+        let cur: any = typeof opt.info === 'function' ? await (opt.info as any).call(evalCtx, evalCtx) : opt.info;
+        if (!rest.length) return cur as FlowContextPropertyInfoInput;
+
+        for (const key of rest) {
+          const obj = toDocObject(cur);
+          if (!__isPlainObject(obj)) return undefined;
+          let props: any = (obj as any)?.properties;
+          if (!props) return undefined;
+          if (typeof props === 'function') {
+            const resolved = await props.call(obj, evalCtx);
+            (obj as any).properties = resolved;
+            props = resolved;
+          }
+          if (!__isPlainObject(props)) return undefined;
+          cur = (props as any)[key];
+        }
+
+        return cur as FlowContextPropertyInfoInput;
+      } catch (_) {
+        return undefined;
+      }
+    };
+
+    const resolveDocNodeAtPath = (segments: string[]): any => {
+      if (!segments.length) return undefined;
+      let cur: any = docProps[segments[0]];
+      for (let i = 1; i < segments.length; i++) {
+        const obj = toDocObject(cur);
+        if (!__isPlainObject(obj)) return undefined;
+        const props = (obj as any).properties;
+        if (!__isPlainObject(props)) return undefined;
+        cur = (props as any)[segments[i]];
+      }
+      return cur;
+    };
+
+    // path 剪裁：每个 path 独立返回一个根节点（key 为 path 字符串）
+    if (!hasRootPath && paths.length) {
+      const out: Record<string, FlowContextApiInfo> = {};
+
+      for (const p of paths) {
+        const segments = p
+          .split('.')
+          .map((x) => x.trim())
+          .filter(Boolean);
+        if (segments.some((s) => isPrivateKey(s))) continue;
+        if (!segments.length) continue;
+
+        const metaNode = await resolvePropertyMetaAtPath(segments);
+        const pi = await buildPropertyInfoFromNodes({
+          docNode: undefined,
+          metaNode,
+          infoNode: undefined,
+          depth: 1,
+          pathFromRoot: [],
+          hiddenPrefixes: new Set(),
+        });
+        if (pi) out[p] = pi;
+      }
+
+      return out;
+    }
+
+    // 全量输出：仅基于 property meta（含委托链）
+    const metaMap = this._getPropertiesMeta();
+    const out: Record<string, FlowContextApiInfo> = {};
+    for (const [key, metaNode] of Object.entries(metaMap)) {
+      if (isPrivateKey(key)) continue;
+      const pi = await buildPropertyInfoFromNodes({
+        docNode: undefined,
+        metaNode,
+        infoNode: undefined,
+        depth: 1,
+        pathFromRoot: [key],
+        hiddenPrefixes: new Set(),
+      });
+      if (pi) out[key] = pi;
+    }
+
+    return out;
+  }
+
   #createChildNodes(
     properties: Record<string, PropertyMeta> | (() => Promise<Record<string, PropertyMeta>>),
     parentPaths: string[] = [],
@@ -666,9 +2732,16 @@ export class FlowContext {
     const computeStateFromMeta = (m: PropertyMeta): { disabled: boolean; reason?: string; hidden: boolean } => {
       if (!m) return { disabled: false, hidden: false };
       const disabledVal = typeof m.disabled === 'function' ? m.disabled() : m.disabled;
-      const reason = typeof m.disabledReason === 'function' ? m.disabledReason() : m.disabledReason;
+      const reasonVal = typeof m.disabledReason === 'function' ? m.disabledReason() : m.disabledReason;
       const hiddenVal = typeof m.hidden === 'function' ? m.hidden() : m.hidden;
-      return { disabled: !!disabledVal, reason, hidden: !!hiddenVal };
+      const disabledIsPromise = disabledVal && typeof (disabledVal as any).then === 'function';
+      const reasonIsPromise = reasonVal && typeof (reasonVal as any).then === 'function';
+      const hiddenIsPromise = hiddenVal && typeof (hiddenVal as any).then === 'function';
+      // getPropertyMetaTree 为同步 API：遇到 Promise 时 fail-open（不隐藏/不禁用）
+      const disabled = disabledIsPromise ? false : !!disabledVal;
+      const reason = reasonIsPromise ? undefined : (reasonVal as any);
+      const hidden = hiddenIsPromise ? false : !!hiddenVal;
+      return { disabled, reason, hidden };
     };
 
     if (typeof metaOrFactory === 'function') {
@@ -679,6 +2752,7 @@ export class FlowContext {
         title: metaOrFactory.title || initialTitle, // 初始使用 name 作为 title
         type: 'object', // 初始类型
         interface: undefined,
+        options: undefined,
         uiSchema: undefined,
         paths,
         parentTitles: parentTitles.length > 0 ? parentTitles : undefined,
@@ -710,6 +2784,7 @@ export class FlowContext {
                   node.title = finalTitle;
                   node.type = meta?.type;
                   node.interface = meta?.interface;
+                  node.options = meta?.options;
                   node.uiSchema = meta?.uiSchema;
                   // parentTitles 保持不变，因为它不包含自身 title
 
@@ -742,6 +2817,7 @@ export class FlowContext {
         title: nodeTitle,
         type: metaOrFactory.type,
         interface: metaOrFactory.interface,
+        options: metaOrFactory.options,
         uiSchema: metaOrFactory.uiSchema,
         paths,
         parentTitles: parentTitles.length > 0 ? parentTitles : undefined,
@@ -908,13 +2984,15 @@ class BaseFlowEngineContext extends FlowContext {
   declare dataSourceManager: DataSourceManager;
   declare requireAsync: (url: string) => Promise<any>;
   declare importAsync: (url: string) => Promise<any>;
-  declare createJSRunner: (options?: JSRunnerOptions) => JSRunner;
+  declare createJSRunner: (options?: JSRunnerOptions) => Promise<JSRunner>;
   declare pageInfo: { version?: 'v1' | 'v2' };
   /**
    * @deprecated use `resolveJsonTemplate` instead
    */
   declare renderJson: (template: JSONValue) => Promise<any>;
   declare resolveJsonTemplate: (template: JSONValue) => Promise<any>;
+  declare getVar: (path: string) => Promise<any>;
+  declare request: (options: RequestOptions) => Promise<any>;
   declare runjs: (code: string, variables?: Record<string, any>, options?: JSRunnerOptions) => Promise<any>;
   declare getAction: <TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>(
     name: string,
@@ -939,6 +3017,33 @@ class BaseFlowEngineContext extends FlowContext {
   declare location: Location;
   declare sql: FlowSQLRepository;
   declare logger: pino.Logger;
+
+  constructor() {
+    super();
+    this.defineMethod('getModel', (modelName: string, searchInPreviousEngines?: boolean) => {
+      return this.engine.getModel(modelName, searchInPreviousEngines);
+    });
+    this.defineMethod('request', (options: RequestOptions) => {
+      return this.api.request(options);
+    });
+    this.defineMethod(
+      'runjs',
+      async function (code: string, variables?: Record<string, any>, options?: JSRunnerOptions) {
+        const { preprocessTemplates, ...runnerOptions } = options || {};
+        const mergedGlobals = { ...(runnerOptions?.globals || {}), ...(variables || {}) };
+        const runner = await this.createJSRunner({
+          ...(runnerOptions || {}),
+          globals: mergedGlobals,
+        });
+        const shouldPreprocessTemplates = shouldPreprocessRunJSTemplates({
+          version: runnerOptions?.version,
+          preprocessTemplates,
+        });
+        const jsCode = await prepareRunJsCode(String(code ?? ''), { preprocessTemplates: shouldPreprocessTemplates });
+        return runner.run(jsCode);
+      },
+    );
+  }
 }
 
 class BaseFlowModelContext extends BaseFlowEngineContext {
@@ -956,7 +3061,16 @@ class BaseFlowModelContext extends BaseFlowEngineContext {
     EventDefinition<TModel, TCtx>
   >;
   declare runAction: (actionName: string, params?: Record<string, any>) => Promise<any> | any;
+  /**
+   * @deprecated use `makeResource` instead
+   */
   declare createResource: <T extends FlowResource = FlowResource>(resourceType: ResourceType<T>) => T;
+  /**
+   * Create a new resource instance without adding it to the context.
+   * @param resourceType - The resource type.
+   * @returns The resource instance.
+   */
+  declare makeResource: <T extends FlowResource = FlowResource>(resourceType: ResourceType<T>) => T;
 }
 
 export class FlowEngineContext extends BaseFlowEngineContext {
@@ -976,25 +3090,30 @@ export class FlowEngineContext extends BaseFlowEngineContext {
     dataSourceManager.addDataSource(mainDataSource);
     this.defineProperty('engine', {
       value: this.engine,
+      info: {
+        description: 'FlowEngine instance.',
+        detail: 'FlowEngine',
+      },
     });
     this.defineProperty('sql', {
-      get: () => new FlowSQLRepository(this),
+      get: (ctx) => new FlowSQLRepository(ctx),
+      cache: false,
+      info: {
+        description: 'SQL helper (FlowSQLRepository).',
+        detail: 'FlowSQLRepository',
+      },
     });
     this.defineProperty('dataSourceManager', {
       value: dataSourceManager,
+      info: {
+        description: 'DataSourceManager instance.',
+        detail: 'DataSourceManager',
+      },
     });
     const i18n = new FlowI18n(this);
     this.defineMethod('t', (keyOrTemplate: string, options?: any) => {
       return i18n.translate(keyOrTemplate, options);
     });
-    this.defineMethod('runjs', async (code, variables, options?: JSRunnerOptions) => {
-      const mergedGlobals = { ...(options?.globals || {}), ...(variables || {}) };
-      const runner = (await (this as any).createJSRunner({
-        ...(options || {}),
-        globals: mergedGlobals,
-      })) as JSRunner;
-      return runner.run(code);
-    });
     this.defineMethod('renderJson', function (template: any) {
       return this.resolveJsonTemplate(template);
     });
@@ -1030,6 +3149,22 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       const needServer = Object.keys(serverVarPaths).length > 0;
       let serverResolved = template;
       if (needServer) {
+        const inferRecordRefWithMeta = (ctx: any): RecordRef | undefined => {
+          const ref = inferRecordRef(ctx as any);
+          if (ref) return ref as RecordRef;
+          try {
+            const tk = ctx?.resource?.getMeta?.('currentFilterByTk');
+            if (typeof tk === 'undefined' || tk === null) return undefined;
+            const collection =
+              ctx?.collection?.name || ctx?.resource?.getResourceName?.()?.split?.('.')?.slice?.(-1)?.[0];
+            if (!collection) return undefined;
+            const dataSourceKey = ctx?.collection?.dataSourceKey || ctx?.resource?.getDataSourceKey?.();
+            return { collection, dataSourceKey, filterByTk: tk } as RecordRef;
+          } catch (_) {
+            return undefined;
+          }
+        };
+
         const collectFromMeta = async (): Promise<Record<string, any>> => {
           const out: Record<string, any> = {};
           try {
@@ -1069,7 +3204,62 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         };
 
         const inputFromMeta = await collectFromMeta();
-        const autoInput = { ...inputFromMeta };
+        const autoInput = { ...inputFromMeta } as Record<string, any>;
+
+        // Special-case: formValues
+        // If server needs to resolve some formValues paths but meta params only cover association anchors
+        // (e.g. formValues.customer) and some top-level paths are missing (e.g. formValues.status),
+        // inject a top-level record anchor (formValues -> { collection, filterByTk, fields/appends }) so server can fetch DB values.
+        // This anchor MUST be selective (fields/appends derived from serverVarPaths['formValues']) to avoid server overriding
+        // client-only values for configured form fields in the same template.
+        try {
+          const varName = 'formValues';
+          const neededPaths = serverVarPaths[varName] || [];
+          if (neededPaths.length) {
+            const requiredTop = new Set<string>();
+            for (const p of neededPaths) {
+              const top = topLevelOf(p);
+              if (top) requiredTop.add(top);
+            }
+            const metaOut = inputFromMeta?.[varName];
+            const builtTop = new Set<string>();
+            if (metaOut && typeof metaOut === 'object' && !Array.isArray(metaOut) && !isRecordRefLike(metaOut)) {
+              Object.keys(metaOut).forEach((k) => builtTop.add(k));
+            }
+
+            const missing = [...requiredTop].filter((k) => !builtTop.has(k));
+            if (missing.length) {
+              const ref = inferRecordRefWithMeta(this);
+              if (ref) {
+                const { generatedFields, generatedAppends } = inferSelectsFromUsage(neededPaths);
+                const recordRef: RecordRef = {
+                  ...ref,
+                  fields: generatedFields,
+                  appends: generatedAppends,
+                };
+
+                // Preserve existing association anchors by lifting them to dotted keys before overwriting formValues
+                const existing = autoInput[varName];
+                if (
+                  existing &&
+                  typeof existing === 'object' &&
+                  !Array.isArray(existing) &&
+                  !isRecordRefLike(existing)
+                ) {
+                  for (const [k, v] of Object.entries(existing)) {
+                    autoInput[`${varName}.${k}`] = v;
+                  }
+                  delete autoInput[varName];
+                }
+
+                autoInput[varName] = recordRef;
+              }
+            }
+          }
+        } catch (_) {
+          // ignore
+        }
+
         const autoContextParams = Object.keys(autoInput).length
           ? _buildServerContextParams(this, autoInput)
           : undefined;
@@ -1100,6 +3290,23 @@ export class FlowEngineContext extends BaseFlowEngineContext {
 
       return resolveExpressions(serverResolved, this);
     });
+
+    // Helper: resolve a single ctx expression value via resolveJsonTemplate behavior.
+    // Example: await ctx.getVar('ctx.record.id')
+    this.defineMethod(
+      'getVar',
+      async function (this: BaseFlowEngineContext, varPath: string) {
+        const raw = typeof varPath === 'string' ? varPath : String(varPath ?? '');
+        const s = raw.trim();
+        if (!s) return undefined;
+        // Preferred input: 'ctx.xxx.yyy' (expression), consistent with envs.getVar outputs.
+        if (s !== 'ctx' && !s.startsWith('ctx.')) {
+          throw new Error(`ctx.getVar(path) expects an expression starting with "ctx.", got: "${s}"`);
+        }
+        return this.resolveJsonTemplate(`{{ ${s} }}` as any);
+      },
+      'Resolve a ctx expression value by path (expression starts with "ctx.").',
+    );
     this.defineProperty('requirejs', {
       get: () => this.app?.requirejs?.requirejs,
     });
@@ -1181,71 +3388,79 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         user: this.user,
       }),
     });
-    this.defineMethod('loadCSS', async (url: string) => {
-      return new Promise((resolve, reject) => {
-        // Check if CSS is already loaded
-        const existingLink = document.querySelector(`link[href="${url}"]`);
-        if (existingLink) {
-          resolve(null);
-          return;
-        }
+    this.defineProperty('date', {
+      get: () => {
+        const createBranch = (prefix: string[]) => {
+          return new Proxy(
+            {},
+            {
+              get: (_target, prop) => {
+                if (typeof prop !== 'string') return undefined;
+                const nextPath = [...prefix, prop];
+                if (!isCtxDatePathPrefix(nextPath)) {
+                  return undefined;
+                }
+                const resolved = resolveCtxDatePath(nextPath);
+                if (typeof resolved !== 'undefined') {
+                  return resolved;
+                }
+                return createBranch(nextPath);
+              },
+            },
+          );
+        };
 
-        const link = document.createElement('link');
-        link.rel = 'stylesheet';
-        link.href = url;
-        link.onload = () => resolve(null);
-        link.onerror = () => reject(new Error(`Failed to load CSS: ${url}`));
-        document.head.appendChild(link);
-      });
+        return createBranch(['date']);
+      },
+      cache: false,
     });
+    this.defineMethod(
+      'loadCSS',
+      async (href: string) => {
+        const url = resolveModuleUrl(href);
+        return new Promise((resolve, reject) => {
+          // Check if CSS is already loaded
+          const existingLink = document.querySelector(`link[href="${url}"]`);
+          if (existingLink) {
+            resolve(null);
+            return;
+          }
+
+          const link = document.createElement('link');
+          link.rel = 'stylesheet';
+          link.href = url;
+          link.onload = () => resolve(null);
+          link.onerror = () => reject(new Error(`Failed to load CSS: ${url}`));
+          document.head.appendChild(link);
+        });
+      },
+      {
+        description: 'Load a CSS file by URL (browser only).',
+        params: [{ name: 'href', type: 'string', description: 'CSS URL.' }],
+        returns: { type: 'Promise<void>' },
+        completion: { insertText: "await ctx.loadCSS('https://example.com/style.css')" },
+        examples: ["await ctx.loadCSS('https://example.com/style.css');"],
+      },
+    );
     this.defineMethod('requireAsync', async (url: string) => {
-      return new Promise((resolve, reject) => {
-        if (!this.requirejs) {
-          reject(new Error('requirejs is not available'));
-          return;
-        }
-        this.requirejs(
-          [url],
-          (...args: any[]) => {
-            resolve(args[0]);
-          },
-          reject,
-        );
-      });
+      // 判断是否为 CSS 文件（支持 example.css?v=123 等形式）
+      if (isCssFile(url)) {
+        return this.loadCSS(url);
+      }
+      const u = resolveModuleUrl(url, { raw: true });
+      return await runjsRequireAsync(this.requirejs, u);
     });
     // 动态按 URL 加载 ESM 模块
     // - 使用 Vite / Webpack ignore 注释，避免被预打包或重写
-    // - 返回模块命名空间对象（包含 default 与命名导出）
-    this.defineMethod('importAsync', async (url: string) => {
-      if (!url || typeof url !== 'string') {
-        throw new Error('invalid url');
-      }
-      const u = url.trim();
-      const g = globalThis as any;
-      g.__nocobaseImportAsyncCache = g.__nocobaseImportAsyncCache || new Map<string, Promise<any>>();
-      const cache: Map<string, Promise<any>> = g.__nocobaseImportAsyncCache;
-      if (cache.has(u)) return cache.get(u)!;
-      // 尝试使用原生 dynamic import（加上 vite/webpack 的 ignore 注释）
-      const nativeImport = () => import(/* @vite-ignore */ /* webpackIgnore: true */ u);
-      // 兜底方案：通过 eval 在运行时构造 import，避免被打包器接管
-      const evalImport = () => {
-        const importer = (0, eval)('u => import(u)');
-        return importer(u);
-      };
-      const p = (async () => {
-        try {
-          return await nativeImport();
-        } catch (err: any) {
-          // 常见于打包产物仍然拦截了 dynamic import 或开发态插件未识别 ignore 注释
-          try {
-            return await evalImport();
-          } catch (err2) {
-            throw err2 || err;
-          }
-        }
-      })();
-      cache.set(u, p);
-      return p;
+    // - 通常返回模块命名空间对象（包含 default 与命名导出）；
+    //   若模块只有 default 一个导出，则会直接返回 default 值以提升易用性（无需再访问 .default）
+    this.defineMethod('importAsync', async function (this: any, url: string) {
+      // 判断是否为 CSS 文件（支持 example.css?v=123 等形式）
+      if (isCssFile(url)) {
+        return this.loadCSS(url);
+      }
+
+      return await runjsImportModule(this, url, { importer: runjsImportAsync });
     });
     this.defineMethod('createJSRunner', async function (options?: JSRunnerOptions) {
       try {
@@ -1254,17 +3469,24 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       } catch (_) {
         // ignore if setup is not available
       }
-      const version = (options?.version as any) || 'v1';
+      const version = options?.version || 'v1';
       const modelClass = getModelClassName(this);
-      const Ctor =
-        (RunJSContextRegistry.resolve(version, modelClass) as any) ||
-        (RunJSContextRegistry.resolve(version, '*') as any) ||
-        FlowRunJSContext;
-      let runCtx: any;
-      if (Ctor) {
-        runCtx = new Ctor(this);
-      }
-      const globals: Record<string, any> = { ctx: runCtx, ...(options?.globals || {}) };
+      const Ctor: new (delegate: any) => any = RunJSContextRegistry.resolve(version, modelClass) || FlowRunJSContext;
+      const runCtx = new Ctor(this);
+      runCtx.defineMethod('t', (key: string, options?: any) => {
+        return this.t(key, { ns: 'runjs', ...options });
+      });
+
+      let doc: RunJSDocMeta = {};
+      try {
+        const locale = (this as any)?.api?.auth?.locale || (this as any)?.i18n?.language || (this as any)?.locale;
+        if ((Ctor as any)?.getDoc?.length) doc = (Ctor as any).getDoc(locale) || {};
+        else doc = (Ctor as any)?.getDoc?.() || {};
+      } catch (_) {
+        doc = {};
+      }
+      const deprecatedCtx = createRunJSDeprecationProxy(runCtx, { doc });
+      const globals: Record<string, any> = { ctx: deprecatedCtx, ...(options?.globals || {}) };
       const { timeoutMs } = options || {};
       return new JSRunner({ globals, timeoutMs });
     });
@@ -1282,57 +3504,6 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       return this.engine.getEvents();
     });
 
-    // // Date variables (for variable selector meta tree)
-    // this.defineProperty('date', {
-    //   get: () => {
-    //     const vars = getDateVars() as Record<string, any>;
-    //     // align with client options: add dayBeforeYesterday
-    //     vars.dayBeforeYesterday = toUnit('day', -2);
-    //     const now = new Date().toISOString();
-    //     const out: Record<string, any> = {};
-    //     for (const [k, v] of Object.entries(vars)) {
-    //       try {
-    //         out[k] = typeof v === 'function' ? v({ now }) : v;
-    //       } catch (e) {
-    //         // ignore
-    //       }
-    //     }
-    //     return out;
-    //   },
-    //   meta: () => {
-    //     const title = this.t('Date variables');
-    //     const mk = (t: string) => ({ type: 'any', title: this.t(t) });
-    //     return {
-    //       type: 'object',
-    //       title,
-    //       properties: {
-    //         now: mk('Current time'),
-    //         dayBeforeYesterday: mk('Day before yesterday'),
-    //         yesterday: mk('Yesterday'),
-    //         today: mk('Today'),
-    //         tomorrow: mk('Tomorrow'),
-    //         lastIsoWeek: mk('Last week'),
-    //         thisIsoWeek: mk('This week'),
-    //         nextIsoWeek: mk('Next week'),
-    //         lastMonth: mk('Last month'),
-    //         thisMonth: mk('This month'),
-    //         nextMonth: mk('Next month'),
-    //         lastQuarter: mk('Last quarter'),
-    //         thisQuarter: mk('This quarter'),
-    //         nextQuarter: mk('Next quarter'),
-    //         lastYear: mk('Last year'),
-    //         thisYear: mk('This year'),
-    //         nextYear: mk('Next year'),
-    //         last7Days: mk('Last 7 days'),
-    //         next7Days: mk('Next 7 days'),
-    //         last30Days: mk('Last 30 days'),
-    //         next30Days: mk('Next 30 days'),
-    //         last90Days: mk('Last 90 days'),
-    //         next90Days: mk('Next 90 days'),
-    //       },
-    //     } as PropertyMeta;
-    //   },
-    // });
     this.defineMethod(
       'runAction',
       async function (this: BaseFlowEngineContext, actionName: string, params?: Record<string, any>) {
@@ -1375,17 +3546,34 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         context: this.createProxy(),
       });
     });
+    this.defineMethod('makeResource', function (this: BaseFlowEngineContext, resourceType) {
+      return this.engine.createResource(resourceType, {
+        context: this.createProxy(),
+      });
+    });
     // Provide useResource in base engine context so RunJS can call it directly
+    this.defineMethod(
+      'initResource',
+      function (
+        this: BaseFlowEngineContext,
+        className: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource',
+      ) {
+        if (!this.has('resource')) {
+          this.defineProperty('resource', {
+            get: () => this.createResource(className),
+          });
+        }
+        return this.resource;
+      },
+    );
+    // @deprecated use `initResource` instead
     this.defineMethod(
       'useResource',
       function (
         this: BaseFlowEngineContext,
         className: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource',
       ) {
-        if (this.has('resource')) return;
-        this.defineProperty('resource', {
-          get: () => this.createResource(className),
-        });
+        return this.initResource(className);
       },
     );
   }
@@ -1401,15 +3589,12 @@ export class FlowModelContext extends BaseFlowModelContext {
     this.defineMethod('onRefReady', (ref, cb, timeout) => {
       this.engine.reactView.onRefReady(ref, cb, timeout);
     });
-    this.defineMethod('runjs', async (code, variables, options?: { version?: string }) => {
-      const runner = await this.createJSRunner({
-        globals: variables,
-        version: options?.version,
-      });
-      return runner.run(code);
-    });
     this.defineProperty('model', {
       value: model,
+      info: {
+        description: 'Current FlowModel instance.',
+        detail: 'FlowModel',
+      },
     });
     // 提供稳定的 ref 实例，确保渲染端与运行时上下文使用同一对象
     const stableRef = createRef<HTMLDivElement>();
@@ -1418,6 +3603,10 @@ export class FlowModelContext extends BaseFlowModelContext {
         this.model['_refCreated'] = true;
         return stableRef;
       },
+      info: {
+        description: 'Stable React ref for the view container.',
+        detail: 'React.RefObject<HTMLDivElement>',
+      },
     });
     this.defineMethod('openView', async function (uid: string, options) {
       const opts = { ...options };
@@ -1478,8 +3667,17 @@ export class FlowModelContext extends BaseFlowModelContext {
         engineCtx: this.engine.context,
       };
       model.context.defineProperty('view', { value: pendingView });
+      // 默认按 click 打开，但兼容 popupSettings 绑定到其他事件（例如 DuplicateActionModel 监听 openDuplicatePopup）。
+      const popupFlow = model.getFlow?.('popupSettings');
+      const on = (popupFlow as any)?.on;
+      let openEventName = 'click';
+      if (typeof on === 'string' && on) {
+        openEventName = on;
+      } else if (on && typeof on === 'object' && typeof (on as any).eventName === 'string' && (on as any).eventName) {
+        openEventName = (on as any).eventName;
+      }
       await model.dispatchEvent(
-        'click',
+        openEventName,
         {
           // navigation: false, // TODO: 路由模式有bug，不支持多层同样viewId的弹窗，因此这里默认先用false
           // ...this.model?.['getInputArgs']?.(), // 避免部分关系字段信息丢失, 仿照 ClickableCollectionField 做法
@@ -1538,12 +3736,16 @@ export class FlowForkModelContext extends BaseFlowModelContext {
       throw new Error('Invalid FlowModel instance');
     }
     super();
-    this.addDelegate((this.master as any).context);
+    this.addDelegate(this.master.context);
     this.defineMethod('onRefReady', (ref, cb, timeout) => {
       this.engine.reactView.onRefReady(ref, cb, timeout);
     });
     this.defineProperty('model', {
       get: () => this.fork,
+      info: {
+        description: 'Current ForkFlowModel instance (as model).',
+        detail: 'ForkFlowModel',
+      },
     });
     // 提供稳定的 ref 实例，确保渲染端与运行时上下文使用同一对象
     const stableRef = createRef<HTMLDivElement>();
@@ -1552,13 +3754,10 @@ export class FlowForkModelContext extends BaseFlowModelContext {
         this.fork['_refCreated'] = true;
         return stableRef;
       },
-    });
-    this.defineMethod('runjs', async (code, variables, options?: { version?: string }) => {
-      const runner = await this.createJSRunner({
-        globals: variables,
-        version: options?.version,
-      });
-      return runner.run(code);
+      info: {
+        description: 'Stable React ref for the view container.',
+        detail: 'React.RefObject<HTMLDivElement>',
+      },
     });
   }
 }
@@ -1569,7 +3768,19 @@ export class FlowRuntimeContext<
 > extends BaseFlowModelContext {
   declare steps: Record<string, { params: Record<string, any>; uiSchema?: any; result?: any }>;
   stepResults: Record<string, any> = {};
-  declare useResource: (className: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource') => void;
+  /**
+   * @deprecated use `initResource` instead
+   */
+  declare useResource: (
+    className: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource',
+  ) => void;
+  /**
+   * Initialize a resource instance without adding it to the context.
+   * @param className - The resource class name.
+   */
+  declare initResource: (
+    className: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource',
+  ) => void;
   declare getStepParams: (stepKey: string) => Record<string, any>;
   declare setStepParams: (stepKey: string, params?: any) => void;
   declare getStepResults: (stepKey: string) => any;
@@ -1591,15 +3802,15 @@ export class FlowRuntimeContext<
       return _.get(this.steps, [stepKey, 'result']);
     });
     this.defineMethod(
-      'useResource',
+      'initResource',
       (className: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource') => {
         if (model.context.has('resource')) {
-          console.warn(`[FlowRuntimeContext] useResource - resource already defined in context: ${className}`);
+          console.log(`[FlowRuntimeContext] useResource - resource already defined in context: ${className}`);
           return;
         }
         model.context.defineProperty('resource', {
           get: () => {
-            return this.createResource(className);
+            return this.makeResource(className);
           },
         });
         if (!model['resource']) {
@@ -1607,6 +3818,13 @@ export class FlowRuntimeContext<
         }
       },
     );
+    // @deprecated use `initResource` instead
+    this.defineMethod(
+      'useResource',
+      (className: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource') => {
+        return this.initResource(className);
+      },
+    );
     this.defineProperty('resource', {
       get: () => model['resource'] || model.context['resource'],
       cache: false,
@@ -1614,13 +3832,6 @@ export class FlowRuntimeContext<
     this.defineMethod('onRefReady', (ref, cb, timeout) => {
       this.engine.reactView.onRefReady(ref, cb, timeout);
     });
-    this.defineMethod('runjs', async (code, variables, options?: { version?: string }) => {
-      const runner = await this.createJSRunner({
-        globals: variables,
-        version: options?.version,
-      });
-      return runner.run(code);
-    });
   }
 
   protected _getOwnProperty(key: string): any {
@@ -1654,7 +3865,7 @@ export class FlowRuntimeContext<
   }
 
   exit() {
-    throw new FlowExitException(this.flowKey, this.model.uid);
+    throw new FlowExitAllException(this.flowKey, this.model.uid);
   }
 
   exitAll() {
@@ -1673,6 +3884,16 @@ export type RunJSDocCompletionDoc = {
   insertText?: string;
 };
 
+export type RunJSDocHiddenDoc = boolean | ((ctx: any) => boolean | Promise<boolean>);
+
+// `hidden` is the single visibility entrypoint for RunJSDoc property docs:
+// - boolean: hide the whole node and its subtree
+// - string[]: hide specific subpaths under the node (relative dot-paths)
+export type RunJSDocHiddenOrPathsDoc =
+  | boolean
+  | string[]
+  | ((ctx: any) => boolean | string[] | Promise<boolean | string[]>);
+
 export type RunJSDocPropertyDoc =
   | string
   | {
@@ -1681,7 +3902,14 @@ export type RunJSDocPropertyDoc =
       type?: string;
       examples?: string[];
       completion?: RunJSDocCompletionDoc;
+      ref?: FlowContextDocRef;
+      deprecated?: FlowDeprecationDoc;
+      params?: FlowContextDocParam[];
+      returns?: FlowContextDocReturn;
       properties?: Record<string, RunJSDocPropertyDoc>;
+      hidden?: RunJSDocHiddenOrPathsDoc;
+      disabled?: boolean | ((ctx: any) => boolean | Promise<boolean>);
+      disabledReason?: string | ((ctx: any) => string | undefined | Promise<string | undefined>);
     };
 
 export type RunJSDocMethodDoc =
@@ -1691,6 +3919,13 @@ export type RunJSDocMethodDoc =
       detail?: string;
       examples?: string[];
       completion?: RunJSDocCompletionDoc;
+      ref?: FlowContextDocRef;
+      deprecated?: FlowDeprecationDoc;
+      params?: FlowContextDocParam[];
+      returns?: FlowContextDocReturn;
+      hidden?: RunJSDocHiddenDoc;
+      disabled?: boolean | ((ctx: any) => boolean | Promise<boolean>);
+      disabledReason?: string | ((ctx: any) => string | undefined | Promise<string | undefined>);
     };
 
 export type RunJSDocMeta = {
@@ -1717,13 +3952,518 @@ function __runjsDeepMerge(base: any, patch: any) {
   }
   return out;
 }
+
+function __isPlainObject(val: any): val is Record<string, any> {
+  return !!val && typeof val === 'object' && !Array.isArray(val);
+}
+
+type RunJSDeprecatedTreeNode = {
+  deprecated?: FlowDeprecationDoc;
+  children?: Record<string, RunJSDeprecatedTreeNode>;
+};
+
+function __isPromiseLike(v: any): v is Promise<any> {
+  return !!v && (typeof v === 'object' || typeof v === 'function') && typeof (v as any).then === 'function';
+}
+
+function __normalizeDeprecationDoc(v: any): FlowDeprecationDoc | undefined {
+  if (v === true) return true;
+  if (!v) return undefined;
+  if (__isPlainObject(v)) return v as any;
+  return undefined;
+}
+
+function __addDeprecatedPath(root: RunJSDeprecatedTreeNode, path: string[], deprecated: FlowDeprecationDoc) {
+  if (!Array.isArray(path) || !path.length) return;
+  let cur = root;
+  for (const seg of path) {
+    if (!seg) return;
+    cur.children = cur.children || {};
+    cur.children[seg] = cur.children[seg] || {};
+    cur = cur.children[seg];
+  }
+  cur.deprecated = deprecated;
+}
+
+function __mergeDeprecatedTree(base: RunJSDeprecatedTreeNode, patch: RunJSDeprecatedTreeNode) {
+  if (patch.deprecated !== undefined) base.deprecated = patch.deprecated;
+  const pChildren = patch.children || {};
+  const keys = Object.keys(pChildren);
+  if (!keys.length) return;
+  base.children = base.children || {};
+  for (const k of keys) {
+    base.children[k] = base.children[k] || {};
+    __mergeDeprecatedTree(base.children[k], pChildren[k]);
+  }
+}
+
+function __buildDeprecatedTreeFromRunJSDoc(doc?: RunJSDocMeta): RunJSDeprecatedTreeNode {
+  const root: RunJSDeprecatedTreeNode = {};
+  if (!doc) return root;
+
+  const walkProps = (props: any, parentPath: string[]) => {
+    if (!__isPlainObject(props)) return;
+    for (const [key, raw] of Object.entries(props)) {
+      if (!key) continue;
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
+      const node = raw as any;
+      const dep = __normalizeDeprecationDoc(node.deprecated);
+      if (dep) __addDeprecatedPath(root, [...parentPath, key], dep);
+      if (__isPlainObject(node.properties)) {
+        walkProps(node.properties, [...parentPath, key]);
+      }
+    }
+  };
+
+  const walkMethods = (methods: any) => {
+    if (!__isPlainObject(methods)) return;
+    for (const [key, raw] of Object.entries(methods)) {
+      if (!key) continue;
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
+      const node = raw as any;
+      const dep = __normalizeDeprecationDoc(node.deprecated);
+      if (dep) __addDeprecatedPath(root, [key], dep);
+    }
+  };
+
+  walkProps((doc as any).properties, []);
+  walkMethods((doc as any).methods);
+
+  return root;
+}
+
+function __buildDeprecatedTreeFromFlowContextInfos(ctx: any): RunJSDeprecatedTreeNode {
+  const root: RunJSDeprecatedTreeNode = {};
+  const visited = new WeakSet<any>();
+
+  const collectInfoProperties = (basePath: string[], props: any) => {
+    if (!__isPlainObject(props)) return;
+    for (const [key, raw] of Object.entries(props)) {
+      if (!key) continue;
+      if (typeof raw === 'string') continue;
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
+      const node = raw as any;
+      const dep = __normalizeDeprecationDoc(node.deprecated);
+      if (dep) __addDeprecatedPath(root, [...basePath, key], dep);
+      if (__isPlainObject(node.properties)) {
+        collectInfoProperties([...basePath, key], node.properties);
+      }
+    }
+  };
+
+  const walk = (c: any) => {
+    if (!c || (typeof c !== 'object' && typeof c !== 'function')) return;
+    if (visited.has(c)) return;
+    visited.add(c);
+
+    const methodInfos = (c as any)._methodInfos;
+    if (__isPlainObject(methodInfos)) {
+      for (const [name, info] of Object.entries(methodInfos)) {
+        if (!name) continue;
+        if (!info || typeof info !== 'object' || Array.isArray(info)) continue;
+        const dep = __normalizeDeprecationDoc((info as any).deprecated);
+        if (dep) __addDeprecatedPath(root, [name], dep);
+      }
+    }
+
+    const props = (c as any)._props;
+    if (__isPlainObject(props)) {
+      for (const [name, opt] of Object.entries(props)) {
+        if (!name) continue;
+        const info = (opt as any)?.info;
+        if (!info || typeof info !== 'object' || Array.isArray(info)) continue;
+        const dep = __normalizeDeprecationDoc((info as any).deprecated);
+        if (dep) __addDeprecatedPath(root, [name], dep);
+        if (__isPlainObject((info as any).properties)) {
+          collectInfoProperties([name], (info as any).properties);
+        }
+      }
+    }
+
+    const delegates = (c as any)._delegates;
+    if (Array.isArray(delegates)) {
+      for (const d of delegates) walk(d);
+    }
+  };
+
+  walk(ctx);
+  return root;
+}
+
+export function createRunJSDeprecationProxy(
+  ctx: any,
+  options: {
+    doc?: RunJSDocMeta;
+  } = {},
+) {
+  const fromDoc = __buildDeprecatedTreeFromRunJSDoc(options.doc);
+  const fromInfo = __buildDeprecatedTreeFromFlowContextInfos(ctx);
+  __mergeDeprecatedTree(fromDoc, fromInfo);
+
+  const warned = new Set<string>();
+  const proxyToTarget = new WeakMap<object, object>();
+  const objectProxyCache = new WeakMap<object, Map<string, any>>();
+  const functionProxyCache = new WeakMap<Function, Map<string, any>>();
+
+  const extractRunJSLocation = (
+    stack?: string,
+  ): { line?: number; column?: number; rawLine?: number; rawColumn?: number } => {
+    if (!stack || typeof stack !== 'string') return {};
+    const WRAPPER_PREFIX_LINES = 2; // JSRunner.run wraps user code with 2 lines before `${code}`
+    const lines = stack.split('\n');
+    for (const l of lines) {
+      if (!l) continue;
+      const m = l.match(/<anonymous>:(\d+):(\d+)/);
+      if (!m) continue;
+      const rawLine = Number(m[1]);
+      const rawColumn = Number(m[2]);
+      const line =
+        Number.isFinite(rawLine) && rawLine > WRAPPER_PREFIX_LINES ? rawLine - WRAPPER_PREFIX_LINES : rawLine;
+      const column = Number.isFinite(rawColumn) ? rawColumn : undefined;
+      return { line, column, rawLine, rawColumn };
+    }
+    return {};
+  };
+
+  const collectInfoProperties = (basePath: string[], props: any) => {
+    if (!__isPlainObject(props)) return;
+    for (const [key, raw] of Object.entries(props)) {
+      if (!key) continue;
+      if (typeof raw === 'string') continue;
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
+      const node = raw as any;
+      const dep = __normalizeDeprecationDoc(node.deprecated);
+      if (dep) __addDeprecatedPath(fromDoc, [...basePath, key], dep);
+      if (__isPlainObject(node.properties)) {
+        collectInfoProperties([...basePath, key], node.properties);
+      }
+    }
+  };
+
+  const updateTreeFromDefineProperty = (name: string, options: any) => {
+    if (!name) return;
+    const info = options?.info;
+    if (!info || typeof info !== 'object' || Array.isArray(info)) return;
+    const dep = __normalizeDeprecationDoc((info as any).deprecated);
+    if (dep) __addDeprecatedPath(fromDoc, [name], dep);
+    if (__isPlainObject((info as any).properties)) {
+      collectInfoProperties([name], (info as any).properties);
+    }
+  };
+
+  const updateTreeFromDefineMethod = (name: string, info: any) => {
+    if (!name) return;
+    if (!info || typeof info !== 'object' || Array.isArray(info)) return;
+    const dep = __normalizeDeprecationDoc((info as any).deprecated);
+    if (dep) __addDeprecatedPath(fromDoc, [name], dep);
+  };
+
+  const unwrapProxy = (val: any) => {
+    let cur = val;
+    while (cur && (typeof cur === 'object' || typeof cur === 'function')) {
+      const mapped = proxyToTarget.get(cur as any);
+      if (!mapped) break;
+      cur = mapped;
+    }
+    return cur;
+  };
+
+  const formatReplacedBy = (replacedBy: any): string | undefined => {
+    if (!replacedBy) return undefined;
+    if (typeof replacedBy === 'string') return replacedBy.trim() || undefined;
+    if (Array.isArray(replacedBy)) {
+      const parts = replacedBy.map((x) => (typeof x === 'string' ? x.trim() : '')).filter(Boolean);
+      return parts.length ? parts.join(', ') : undefined;
+    }
+    return undefined;
+  };
+
+  const warnOnce = (apiPath: string, deprecated: FlowDeprecationDoc, stack?: string) => {
+    if (!apiPath) return;
+    if (warned.has(apiPath)) return;
+    warned.add(apiPath);
+
+    const logger = (ctx as any)?.logger;
+    const t =
+      typeof (ctx as any)?.t === 'function'
+        ? (key: string, options?: any) =>
+            (ctx as any).t(key, { ns: [FLOW_ENGINE_NAMESPACE, 'client'], nsMode: 'fallback', ...options })
+        : (key: string, options?: any) => {
+            const fallback = options?.defaultValue ?? key;
+            if (typeof fallback !== 'string' || !options) return fallback;
+            // lightweight interpolation for fallback strings (i18next-style: {{var}})
+            return fallback.replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (_m, k) => {
+              const v = options?.[k];
+              return typeof v === 'string' || typeof v === 'number' ? String(v) : '';
+            });
+          };
+    const meta = typeof deprecated === 'object' && deprecated ? deprecated : {};
+    const replacedBy = formatReplacedBy((meta as any).replacedBy);
+    const since = typeof (meta as any).since === 'string' ? String((meta as any).since) : undefined;
+    const removedIn = typeof (meta as any).removedIn === 'string' ? String((meta as any).removedIn) : undefined;
+    const message = typeof (meta as any).message === 'string' ? String((meta as any).message) : '';
+
+    const loc = extractRunJSLocation(stack);
+
+    const locText = loc.line ? `（line ${loc.line}${loc.column ? `:${loc.column}` : ''}）` : '';
+
+    const msg = message.trim();
+    const mainText = msg
+      ? t('RunJS deprecated warning with message', {
+          defaultValue: '[RunJS][Deprecated] {{api}} {{message}}{{location}}',
+          api: apiPath,
+          message: msg,
+          location: locText,
+        })
+      : t('RunJS deprecated warning', {
+          defaultValue: '[RunJS][Deprecated] {{api}} is deprecated{{location}}',
+          api: apiPath,
+          location: locText,
+        });
+
+    const separator = t('RunJS deprecated separator', { defaultValue: '; ' });
+    const textParts: string[] = [mainText];
+    if (replacedBy)
+      textParts.push(t('RunJS deprecated replacedBy', { defaultValue: 'Use {{replacedBy}} instead', replacedBy }));
+    if (since) textParts.push(t('RunJS deprecated since', { defaultValue: 'since {{since}}', since }));
+    if (removedIn)
+      textParts.push(t('RunJS deprecated removedIn', { defaultValue: 'will be removed in {{removedIn}}', removedIn }));
+    const text = textParts.filter(Boolean).join(separator);
+
+    try {
+      if (logger && typeof logger.warn === 'function') {
+        logger.warn(text);
+      } else {
+        // fail-open: avoid breaking runjs execution when logger is missing
+        console.warn(text);
+      }
+    } catch (_) {
+      // ignore logger failures
+    }
+  };
+
+  const createFunctionProxy = (fn: Function, node: RunJSDeprecatedTreeNode, path: string) => {
+    const dep = node.deprecated;
+    if (!dep) return fn;
+
+    const cacheByPath = functionProxyCache.get(fn) || new Map<string, any>();
+    functionProxyCache.set(fn, cacheByPath);
+    if (cacheByPath.has(path)) return cacheByPath.get(path);
+
+    const proxied = new Proxy(fn, {
+      apply(target, thisArg, argArray) {
+        const stack = warned.has(path) ? undefined : new Error().stack;
+        warnOnce(path, dep, stack);
+        const realThis = unwrapProxy(thisArg);
+        return Reflect.apply(target, realThis, argArray);
+      },
+      get(target, key, receiver) {
+        return Reflect.get(target, key, receiver);
+      },
+    });
+
+    cacheByPath.set(path, proxied);
+    return proxied as any;
+  };
+
+  const createObjectProxy = (target: any, node: RunJSDeprecatedTreeNode, path: string): any => {
+    if (!target || (typeof target !== 'object' && typeof target !== 'function')) return target;
+    if (__isPromiseLike(target)) return target;
+    const hasChildren = !!node.children && Object.keys(node.children).length > 0;
+    if (!hasChildren && path !== 'ctx') return target;
+
+    const cacheByPath = objectProxyCache.get(target) || new Map<string, any>();
+    objectProxyCache.set(target, cacheByPath);
+    if (cacheByPath.has(path)) return cacheByPath.get(path);
+
+    const proxied = new Proxy(target, {
+      get(t, key, receiver) {
+        if (typeof key === 'symbol') {
+          return Reflect.get(t, key, unwrapProxy(receiver));
+        }
+        const prop = String(key);
+        const value = Reflect.get(t, key, unwrapProxy(receiver));
+
+        // Support dynamic deprecation registration via ctx.defineProperty/defineMethod during RunJS execution.
+        // - This is especially useful when the deprecated API is introduced after JSRunner is created.
+        if (path === 'ctx' && prop === 'defineProperty' && typeof value === 'function') {
+          return (...args: any[]) => {
+            const result = value(...args);
+            try {
+              updateTreeFromDefineProperty(String(args?.[0] ?? ''), args?.[1]);
+            } catch (_) {
+              // ignore
+            }
+            return result;
+          };
+        }
+        if (path === 'ctx' && prop === 'defineMethod' && typeof value === 'function') {
+          return (...args: any[]) => {
+            const result = value(...args);
+            try {
+              updateTreeFromDefineMethod(String(args?.[0] ?? ''), args?.[2]);
+            } catch (_) {
+              // ignore
+            }
+            return result;
+          };
+        }
+
+        const child = node.children?.[prop];
+        if (!child) return value;
+
+        const childPath = `${path}.${prop}`;
+        if (typeof value === 'function' && child.deprecated) {
+          return createFunctionProxy(value, child, childPath);
+        }
+        if (child.deprecated) {
+          // For non-callable APIs, "use" happens on access (there is no apply step).
+          const stack = warned.has(childPath) ? undefined : new Error().stack;
+          warnOnce(childPath, child.deprecated, stack);
+        }
+        if (value && (typeof value === 'object' || typeof value === 'function') && child.children) {
+          return createObjectProxy(value, child, childPath);
+        }
+        return value;
+      },
+      has(t, key) {
+        return Reflect.has(t, key);
+      },
+    });
+
+    proxyToTarget.set(proxied as any, target);
+    cacheByPath.set(path, proxied);
+    return proxied;
+  };
+
+  return createObjectProxy(ctx, fromDoc, 'ctx');
+}
+
+function __mergeRunJSDocDocRecord(base: any, patch: any, mergeDoc: (b: any, p: any) => any): any {
+  if (!__isPlainObject(patch)) return base;
+  // Important: preserve `null` markers when base is not an object (e.g. child class wants to delete parent keys).
+  // If we eagerly delete them here, the deletion intent is lost for later merges in the inheritance chain.
+  if (!__isPlainObject(base)) return patch;
+  const out: any = { ...base };
+  for (const k of Object.keys(patch)) {
+    const pv = patch[k];
+    if (pv === null) {
+      delete out[k];
+      continue;
+    }
+    const bv = __isPlainObject(base) ? base[k] : undefined;
+    const merged = mergeDoc(bv, pv);
+    if (typeof merged === 'undefined') delete out[k];
+    else out[k] = merged;
+  }
+  return out;
+}
+
+function __mergeRunJSDocPropertyDoc(base: any, patch: any): any {
+  if (patch === null) return undefined;
+
+  const baseIsObj = __isPlainObject(base);
+  const patchIsObj = __isPlainObject(patch);
+  const baseIsStr = typeof base === 'string';
+  const patchIsStr = typeof patch === 'string';
+
+  // Treat string docs as { description: string } when merging with object docs,
+  // to avoid "whole replacement" that drops base hidden/properties/completion.
+  if (patchIsStr) {
+    if (baseIsObj) {
+      return __mergeRunJSDocPropertyDoc(base, { description: patch });
+    }
+    return patch;
+  }
+
+  if (patchIsObj) {
+    const baseObj: any = baseIsObj ? base : baseIsStr ? { description: base } : undefined;
+    const out: any = { ...(baseObj || {}) };
+    for (const k of Object.keys(patch)) {
+      if (k === 'properties') {
+        const pv = (patch as any).properties;
+        if (pv === null) {
+          delete out.properties;
+          continue;
+        }
+        const mergedProps = __mergeRunJSDocDocRecord(baseObj?.properties, pv, __mergeRunJSDocPropertyDoc);
+        if (typeof mergedProps === 'undefined') delete out.properties;
+        else out.properties = mergedProps;
+        continue;
+      }
+      const mergedVal = __runjsDeepMerge(baseObj?.[k], (patch as any)[k]);
+      if (typeof mergedVal === 'undefined') delete out[k];
+      else out[k] = mergedVal;
+    }
+    return out;
+  }
+
+  return patch ?? base;
+}
+
+function __mergeRunJSDocMethodDoc(base: any, patch: any): any {
+  if (patch === null) return undefined;
+
+  const baseIsObj = __isPlainObject(base);
+  const patchIsObj = __isPlainObject(patch);
+  const baseIsStr = typeof base === 'string';
+  const patchIsStr = typeof patch === 'string';
+
+  if (patchIsStr) {
+    if (baseIsObj) {
+      return __mergeRunJSDocMethodDoc(base, { description: patch });
+    }
+    return patch;
+  }
+
+  if (patchIsObj) {
+    const baseObj: any = baseIsObj ? base : baseIsStr ? { description: base } : undefined;
+    const out: any = { ...(baseObj || {}) };
+    for (const k of Object.keys(patch)) {
+      const mergedVal = __runjsDeepMerge(baseObj?.[k], (patch as any)[k]);
+      if (typeof mergedVal === 'undefined') delete out[k];
+      else out[k] = mergedVal;
+    }
+    return out;
+  }
+
+  return patch ?? base;
+}
+
+function __mergeRunJSDocMeta(base: any, patch: any): RunJSDocMeta {
+  const baseObj: any = __isPlainObject(base) ? base : {};
+  const patchObj: any = __isPlainObject(patch) ? patch : {};
+  const out: any = { ...baseObj };
+
+  for (const k of Object.keys(patchObj)) {
+    if (k === 'properties') {
+      const mergedProps = __mergeRunJSDocDocRecord(baseObj.properties, patchObj.properties, __mergeRunJSDocPropertyDoc);
+      if (typeof mergedProps === 'undefined') delete out.properties;
+      else out.properties = mergedProps;
+      continue;
+    }
+    if (k === 'methods') {
+      const mergedMethods = __mergeRunJSDocDocRecord(baseObj.methods, patchObj.methods, __mergeRunJSDocMethodDoc);
+      if (typeof mergedMethods === 'undefined') delete out.methods;
+      else out.methods = mergedMethods;
+      continue;
+    }
+    const mergedVal = __runjsDeepMerge(baseObj[k], patchObj[k]);
+    if (typeof mergedVal === 'undefined') delete out[k];
+    else out[k] = mergedVal;
+  }
+
+  return out as RunJSDocMeta;
+}
 export class FlowRunJSContext extends FlowContext {
   constructor(delegate: FlowContext) {
     super();
     this.addDelegate(delegate);
     this.defineProperty('React', { value: React });
     this.defineProperty('antd', { value: antd });
-    this.defineProperty('dayjs', { value: dayjs });
+    this.defineProperty('dayjs', {
+      value: dayjs,
+    });
     // 为 JS 运行时代码提供带有 antd/App/ConfigProvider 包裹的 React 根
     // 保持与 ReactDOMClient 接口一致，优先覆盖 createRoot，其余方法透传
     const ReactDOMShim: any = {
@@ -1735,19 +4475,10 @@ export class FlowRunJSContext extends FlowContext {
         return this.engine.reactView.createRoot(realContainer as HTMLElement, options);
       },
     };
+    ReactDOMShim.__nbRunjsInternalShim = true;
     this.defineProperty('ReactDOM', { value: ReactDOMShim });
 
-    // 为第三方/通用库提供统一命名空间：ctx.libs
-    // - 新增库应优先挂载到 ctx.libs.xxx
-    // - 同时保留顶层别名（如 ctx.React / ctx.antd），以兼容历史代码
-    const libs = Object.freeze({
-      React,
-      ReactDOM: ReactDOMShim,
-      antd,
-      dayjs,
-      antdIcons,
-    });
-    this.defineProperty('libs', { value: libs });
+    setupRunJSLibs(this);
 
     // Convenience: ctx.render(<App />[, container])
     // - container defaults to ctx.element if available
@@ -1767,16 +4498,37 @@ export class FlowRunJSContext extends FlowContext {
         globalRef.__nbRunjsRoots = globalRef.__nbRunjsRoots || new WeakMap<any, any>();
         const rootMap: WeakMap<any, any> = globalRef.__nbRunjsRoots;
 
-        // If vnode is string (HTML), unmount react root and set sanitized HTML
-        if (typeof vnode === 'string') {
-          const existingRoot = rootMap.get(containerEl);
-          if (existingRoot && typeof existingRoot.unmount === 'function') {
+        const disposeEntry = (entry: any) => {
+          if (!entry) return;
+          if (entry.disposeTheme && typeof entry.disposeTheme === 'function') {
+            try {
+              entry.disposeTheme();
+            } catch (_) {
+              // ignore
+            }
+            entry.disposeTheme = undefined;
+          }
+          const root = entry.root || entry;
+          if (root && typeof root.unmount === 'function') {
             try {
-              existingRoot.unmount();
-            } finally {
-              rootMap.delete(containerEl);
+              root.unmount();
+            } catch (_) {
+              // ignore
             }
           }
+        };
+
+        const unmountContainerRoot = () => {
+          const existing = rootMap.get(containerEl);
+          if (existing) {
+            disposeEntry(existing);
+            rootMap.delete(containerEl);
+          }
+        };
+
+        // If vnode is string (HTML), unmount react root and set sanitized HTML
+        if (typeof vnode === 'string') {
+          unmountContainerRoot();
           const proxy: any = new ElementProxy(containerEl);
           proxy.innerHTML = String(vnode ?? '');
           return null;
@@ -1788,39 +4540,64 @@ export class FlowRunJSContext extends FlowContext {
           (vnode as any).nodeType &&
           ((vnode as any).nodeType === 1 || (vnode as any).nodeType === 3 || (vnode as any).nodeType === 11)
         ) {
-          const existingRoot = rootMap.get(containerEl);
-          if (existingRoot && typeof existingRoot.unmount === 'function') {
-            try {
-              existingRoot.unmount();
-            } finally {
-              rootMap.delete(containerEl);
-            }
-          }
+          unmountContainerRoot();
           while (containerEl.firstChild) containerEl.removeChild(containerEl.firstChild);
           containerEl.appendChild(vnode as any);
           return null;
         }
 
-        let root = rootMap.get(containerEl);
-        if (!root) {
-          root = this.ReactDOM.createRoot(containerEl);
-          rootMap.set(containerEl, root);
+        // 注意：rootMap 是“全局按容器复用”的（key=containerEl）。
+        // 若不同 RunJS ctx 复用同一个 containerEl，且 ReactDOM 实例引用也相同，
+        // 则会复用到旧 entry，进而复用旧 ctx 创建的 autorun（闭包捕获旧 ctx），造成：
+        // 1) 旧 ctx 的 reaction 继续驱动新渲染（跨 ctx 复用风险）
+        // 2) 新 ctx 的主题变化不再触发 rerender
+        // 3) 旧 ctx 被 entry/autorun 间接持有，无法被 GC（内存泄漏）
+        // 因此这里把 ownerKey（当前 ctx）也纳入复用判断；owner 变化时必须重建 entry。
+        const rendererKey = this.ReactDOM;
+        const ownerKey = this;
+        let entry = rootMap.get(containerEl);
+        if (!entry || entry.rendererKey !== rendererKey || entry.ownerKey !== ownerKey) {
+          if (entry) {
+            disposeEntry(entry);
+            rootMap.delete(containerEl);
+          }
+          const root = this.ReactDOM.createRoot(containerEl);
+          entry = { rendererKey, ownerKey, root, disposeTheme: undefined, lastVnode: undefined };
+          rootMap.set(containerEl, entry);
         }
-        root.render(vnode as any);
-        return root;
+
+        return externalReactRender({
+          ctx: this,
+          entry,
+          vnode,
+          containerEl,
+          rootMap,
+          unmountContainerRoot,
+          internalReact: React,
+          internalAntd: antd,
+        });
       },
     );
   }
+
+  exit() {
+    throw new FlowExitAllException(this.flowKey, this.model?.uid || 'runjs');
+  }
+
+  exitAll() {
+    throw new FlowExitAllException(this.flowKey, this.model?.uid || 'runjs');
+  }
+
   static define(meta: RunJSDocMeta, options?: { locale?: string }) {
     const locale = options?.locale;
     if (locale) {
       const map = __runjsClassLocaleMeta.get(this) || new Map<string, RunJSDocMeta>();
       const prev = map.get(locale) || {};
-      map.set(locale, __runjsDeepMerge(prev, meta));
+      map.set(locale, __mergeRunJSDocMeta(prev, meta));
       __runjsClassLocaleMeta.set(this, map);
     } else {
       const prev = __runjsClassDefaultMeta.get(this) || {};
-      __runjsClassDefaultMeta.set(this, __runjsDeepMerge(prev, meta));
+      __runjsClassDefaultMeta.set(this, __mergeRunJSDocMeta(prev, meta));
     }
     __runjsDocCache.delete(this);
   }
@@ -1828,7 +4605,7 @@ export class FlowRunJSContext extends FlowContext {
     const self = this as any as Function;
     let cacheForClass = __runjsDocCache.get(self);
     const cacheKey = String(locale || 'default');
-    if (cacheForClass && cacheForClass.has(cacheKey)) return cacheForClass.get(cacheKey)!;
+    if (cacheForClass && cacheForClass.has(cacheKey)) return cacheForClass.get(cacheKey) as RunJSDocMeta;
     const chain: Function[] = [];
     let cur: any = self;
     while (cur && cur.prototype) {
@@ -1837,13 +4614,13 @@ export class FlowRunJSContext extends FlowContext {
     }
     let merged: RunJSDocMeta = {};
     for (const cls of chain) {
-      merged = __runjsDeepMerge(merged, __runjsClassDefaultMeta.get(cls) || {});
+      merged = __mergeRunJSDocMeta(merged, __runjsClassDefaultMeta.get(cls) || {});
     }
     if (locale) {
       for (const cls of chain) {
         const lmap = __runjsClassLocaleMeta.get(cls);
         if (lmap && lmap.has(locale)) {
-          merged = __runjsDeepMerge(merged, lmap.get(locale));
+          merged = __mergeRunJSDocMeta(merged, lmap.get(locale));
         }
       }
     }