next-flow-interface 0.24.13 → 0.24.18

package/index.d.ts

@@ -29,6 +29,7 @@ import {
   WebGPUEngine,
 } from '@babylonjs/core'
 import { WebXRDefaultExperience } from '@babylonjs/core/XR/webXRDefaultExperience'
+import OSS from 'ali-oss'
 import { EmptyProps, InputNumberProps, SelectProps, SwitchProps } from 'antd'
 import { Color, ColorPickerProps } from 'antd/es/color-picker'
 import { DefaultOptionType } from 'antd/es/select'
@@ -335,13 +336,102 @@ export declare enum AttributeType {
 }
 
 /**
+ * 自动播放服务
+ *
+ * 负责管理场景的自动播放功能，按照设定的时间间隔自动切换场景步骤（Step）。
+ * 支持循环播放模式，并根据会议状态和页面浏览状态自动控制播放行为。
+ *
+ * @remarks
+ * - 单例模式，通过 `AutoPlayService.instance` 获取实例
+ * - 自动播放会受到以下条件限制：
+ *   - 用户正在跟随访客时不播放
+ *   - 页面不在浏览状态时不播放
+ *   - 项目设置中未开启自动播放时不播放
+ * - 播放间隔和循环模式由 `RvProjectService.state.playing` 配置决定
+ *
+ * @example
+ * ```typescript
+ * // 获取服务实例
+ * const autoPlayService = AutoPlayService.instance
+ *
+ * // 检查是否有下一个步骤
+ * const hasNext = autoPlayService.hasNextStep(true)
+ *
+ * // 尝试跳转到下一个步骤
+ * const success = autoPlayService.tryNextStep(false)
+ *
+ * // 手动启动下一次自动播放（通常由服务内部调用）
+ * autoPlayService.next(3000, true) // 3秒后切换，循环播放
+ * ```
+ *
  * @public
  */
 export declare class AutoPlayService {
+  /**
+   * 获取服务单例实例
+   *
+   * @returns AutoPlayService 单例实例
+   *
+   * @public
+   */
   static get instance(): AutoPlayService
+  /**
+   * 私有构造函数
+   *
+   * 确保单例模式，外部无法直接实例化。
+   * 构造时会自动调用初始化方法。
+   *
+   * @private
+   */
   private constructor()
+  /**
+   * 启动下一次自动播放
+   *
+   * 设置一个定时器，在指定的时间间隔后自动切换到下一个场景步骤。
+   * 如果有下一个步骤，会递归调用自己继续下一轮播放。
+   *
+   * @param interval - 播放间隔时间（毫秒）
+   * @param loop - 是否循环播放，true 表示播放到最后一个步骤后回到第一个
+   *
+   * @remarks
+   * 此方法会持续递归调用直到没有下一个步骤或被 stopAutoPlay 中断。
+   * 定时器 ID 会存储在 currentTimeoutId 中，用于后续取消操作。
+   *
+   * @public
+   */
   next(interval: number, loop: boolean): void
+  /**
+   * 检查是否有下一个步骤
+   *
+   * 判断当前场景是否可以切换到下一个步骤。
+   *
+   * @param loop - 是否循环播放模式
+   * @returns true 表示有下一个步骤可以切换，false 表示已经是最后一个步骤且不循环
+   *
+   * @remarks
+   * 循环模式下，如果至少有2个步骤，则始终返回 true（可以循环回第一个）。
+   * 非循环模式下，只有当前步骤不是最后一个时才返回 true。
+   *
+   * @public
+   */
   hasNextStep(loop: boolean): boolean
+  /**
+   * 尝试切换到下一个步骤
+   *
+   * 根据当前步骤位置和循环模式，切换到下一个场景步骤。
+   *
+   * @param loop - 是否循环播放模式
+   * @returns true 表示成功切换到下一个步骤，false 或 undefined 表示切换失败
+   *
+   * @remarks
+   * - 如果当前不是最后一个步骤，切换到顺序中的下一个步骤
+   * - 如果已经是最后一个步骤且开启了循环模式，切换到第一个步骤
+   * - 循环模式至少需要2个步骤才能生效
+   *
+   * 实际的步骤切换通过修改 `SpaceService.instance.page.sid` 实现。
+   *
+   * @public
+   */
   tryNextStep(loop: boolean): true | undefined
 }
 
@@ -422,6 +512,12 @@ export declare interface BasePlugin {
   onUninstall?: () => Promise<void>
 }
 
+export declare class BasicAttribute extends NodeAttribute<RvBasic> {
+  path: string[]
+  defaultValue: RvBasic
+  generate(sid?: string, nid?: string): RvBasic
+}
+
 /**
  * @public
  */
@@ -437,24 +533,219 @@ export declare interface BatchApplyProps extends DivProps {
 }
 
 /**
+ * 批量应用服务
+ *
+ * @remarks
+ * 该服务用于管理多场景批量编辑功能。允许用户选择多个场景（step），
+ * 并对选中的场景批量应用相同的属性变更。
+ *
+ * 主要功能：
+ * - 管理选中场景列表
+ * - 提供全选/取消全选功能
+ * - 支持订阅选中状态变化
+ * - 提供批量遍历和应用操作的方法
+ *
+ * @example
+ * ```typescript
+ * // 获取服务实例
+ * const batchService = BatchApplyService.instance
+ *
+ * // 订阅选中状态变化
+ * const unsubscribe = batchService.subscribe((selected) => {
+ *   console.log('当前选中的场景:', selected)
+ * })
+ *
+ * // 选择所有场景
+ * batchService.selectAll()
+ *
+ * // 批量修改场景属性
+ * batchService.forEach((rvStep) => {
+ *   rvStep.name.set('新场景名称')
+ * })
+ *
+ * // 取消订阅
+ * unsubscribe()
+ * ```
+ *
  * @public
  */
 export declare class BatchApplyService {
+  /**
+   * 获取 BatchApplyService 的单例实例
+   *
+   * @returns BatchApplyService 的单例实例
+   *
+   * @public
+   */
   static get instance(): BatchApplyService
-  _selected: string[]
   private constructor()
+  /**
+   * 获取当前选中的场景ID数组
+   *
+   * @returns 选中的场景ID数组
+   *
+   * @public
+   */
   get selected(): string[]
+  /**
+   * 设置当前选中的场景ID数组
+   *
+   * @param selected - 要设置的场景ID数组
+   *
+   * @remarks
+   * 设置选中状态后，会自动通知所有订阅者
+   *
+   * @public
+   */
   set selected(selected: string[])
+  /**
+   * 选中所有场景
+   *
+   * @remarks
+   * 将当前项目中所有场景的ID添加到选中列表中
+   *
+   * @example
+   * ```typescript
+   * BatchApplyService.instance.selectAll()
+   * ```
+   *
+   * @public
+   */
   selectAll(): void
+  /**
+   * 取消选中所有场景
+   *
+   * @remarks
+   * 清空选中列表，不再选中任何场景
+   *
+   * @example
+   * ```typescript
+   * BatchApplyService.instance.unselectAll()
+   * ```
+   *
+   * @public
+   */
   unselectAll(): void
+  /**
+   * 判断是否已选中所有场景
+   *
+   * @returns 如果所有场景都已选中返回 true，否则返回 false
+   *
+   * @example
+   * ```typescript
+   * if (BatchApplyService.instance.isAllSelected()) {
+   *   console.log('已选中所有场景')
+   * }
+   * ```
+   *
+   * @public
+   */
   isAllSelected(): boolean
+  /**
+   * 订阅选中状态变化
+   *
+   * @param subscriber - 订阅回调函数，当选中状态变化时会被调用
+   * @returns 取消订阅的函数，调用后将移除该订阅者
+   *
+   * @remarks
+   * 当选中的场景列表发生变化时，所有订阅者都会收到通知
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = BatchApplyService.instance.subscribe((selected) => {
+   *   console.log('选中场景数量:', selected.length)
+   *   console.log('选中场景ID:', selected)
+   * })
+   *
+   * // 需要取消订阅时调用
+   * unsubscribe()
+   * ```
+   *
+   * @public
+   */
   subscribe(subscriber: BatchApplySubscriber): () => void
+  /**
+   * 取消订阅选中状态变化
+   *
+   * @param subscriber - 要取消的订阅回调函数
+   *
+   * @remarks
+   * 从订阅列表中移除指定的订阅者
+   *
+   * @public
+   */
   unsubscribe(subscriber: BatchApplySubscriber): void
+  /**
+   * 遍历所有选中的场景并执行操作
+   *
+   * @param f - 对每个场景执行的回调函数，接收场景的 RhineVar 对象
+   *
+   * @throws 如果场景数据获取失败会抛出错误
+   *
+   * @remarks
+   * 遍历所有选中的场景，对每个场景执行指定的操作。
+   * 这是批量修改场景属性的核心方法。
+   *
+   * @example
+   * ```typescript
+   * // 批量修改所有选中场景的名称
+   * BatchApplyService.instance.forEach((rvStep) => {
+   *   rvStep.name.set('统一场景名称')
+   * })
+   *
+   * // 批量修改场景的背景颜色
+   * BatchApplyService.instance.forEach((rvStep) => {
+   *   rvStep.background.color.set('#ffffff')
+   * })
+   * ```
+   *
+   * @public
+   */
   forEach(f: (rvStep: StoredRhineVar<RvStep>) => void): void
+  /**
+   * 遍历所有选中场景中当前选中节点的属性并执行操作
+   *
+   * @param f - 对每个节点执行的回调函数，接收节点的 RhineVar 对象
+   *
+   * @throws 如果节点属性数据获取失败会抛出错误
+   *
+   * @remarks
+   * 该方法结合了场景批量选择和节点选择。它会遍历所有选中的场景，
+   * 在每个场景中找到当前选中的节点（由 RsSelectionService 管理），
+   * 然后对这些节点执行指定的操作。
+   *
+   * 使用场景：当需要在多个场景中同时修改相同节点的属性时使用此方法。
+   * 例如：在多个场景中同时修改某个模型的颜色、位置等属性。
+   *
+   * @example
+   * ```typescript
+   * // 在所有选中场景中，修改当前选中节点的可见性
+   * BatchApplyService.instance.forEachAttributes((rvNode) => {
+   *   rvNode.visible.set(false)
+   * })
+   *
+   * // 在所有选中场景中，修改当前选中节点的位置
+   * BatchApplyService.instance.forEachAttributes((rvNode) => {
+   *   rvNode.position.x.set(100)
+   *   rvNode.position.y.set(200)
+   * })
+   *
+   * // 在所有选中场景中，修改当前选中节点的材质颜色
+   * BatchApplyService.instance.forEachAttributes((rvNode) => {
+   *   rvNode.material.color.set('#ff0000')
+   * })
+   * ```
+   *
+   * @public
+   */
   forEachAttributes(f: (rvNode: StoredRhineVar<RvNode>) => void): void
 }
 
 /**
+ * 批量应用订阅者回调函数类型
+ *
+ * @param selected - 当前选中的场景ID数组
+ *
  * @public
  */
 export declare type BatchApplySubscriber = (selected: string[]) => void
@@ -611,15 +902,142 @@ export declare interface ContextMenuCreateOptions {
 }
 
 /**
+ * 右键菜单管理服务
+ *
+ * @remarks
+ * 该服务提供了一个集中管理系统，用于创建、显示和控制右键菜单。
+ * 采用单例模式，确保整个应用程序中只存在一个实例。
+ *
+ * @example
+ * 基础用法：
+ * ```typescript
+ * const menuController = ContextMenuService.instance.create({
+ *   x: 100,
+ *   y: 200,
+ *   lines: [
+ *     {
+ *       text: '复制',
+ *       onClick: () => console.log('Copy clicked')
+ *     },
+ *     {
+ *       text: '粘贴',
+ *       onClick: () => console.log('Paste clicked')
+ *     }
+ *   ]
+ * })
+ * menuController.show()
+ * ```
+ *
  * @public
  */
 export declare class ContextMenuService {
+  /**
+   * 获取 ContextMenuService 的单例实例
+   *
+   * @returns 单例实例
+   *
+   * @public
+   */
   static get instance(): ContextMenuService
-  private constructor()
+  /**
+   * 包含所有活动右键菜单的响应式数组
+   *
+   * @remarks
+   * 该数组使用 Valtio proxy 包装以实现响应式更新。
+   * 当右键菜单被添加或移除时，UI 将自动反映这些变化。
+   *
+   * @public
+   */
   contextMenus: ContextMenu[]
+  /**
+   * 创建一个新的右键菜单
+   *
+   * @param options - 右键菜单的配置选项
+   * @returns 用于管理右键菜单生命周期的控制器对象
+   *
+   * @remarks
+   * 该方法使用指定的选项创建一个新的右键菜单。如果未提供 ID，
+   * 将自动生成一个唯一的 ID。返回的控制器可用于显示或销毁菜单。
+   *
+   * @example
+   * ```typescript
+   * const controller = ContextMenuService.instance.create({
+   *   x: event.clientX,
+   *   y: event.clientY,
+   *   closeOnOutsideClick: true,
+   *   lines: [
+   *     {
+   *       text: '删除',
+   *       icon: TrashIcon,
+   *       onClick: () => handleDelete()
+   *     }
+   *   ]
+   * })
+   * controller.show()
+   * ```
+   *
+   * @public
+   */
   create(options: ContextMenuCreateOptions): ContextMenuController
+  /**
+   * 根据 ID 获取右键菜单
+   *
+   * @param id - 右键菜单的唯一 ID
+   * @returns 如果找到则返回右键菜单实例，否则返回 undefined
+   *
+   * @example
+   * ```typescript
+   * const menu = ContextMenuService.instance.get('context-menu-0')
+   * if (menu) {
+   *   console.log('Found menu at:', menu.x, menu.y)
+   * }
+   * ```
+   *
+   * @public
+   */
   get(id: string): ContextMenu | undefined
+  /**
+   * 关闭指定的右键菜单
+   *
+   * @param contextMenu - 要关闭的右键菜单 ID 字符串或 ContextMenu 实例
+   * @returns 一个 Promise，如果菜单成功关闭则解析为 true，否则为 false
+   *
+   * @remarks
+   * 该方法从活动菜单列表中移除右键菜单。如果未找到菜单或菜单当前未显示，
+   * 则返回 false。
+   *
+   * @example
+   * ```typescript
+   * // 通过 ID 关闭
+   * await ContextMenuService.instance.close('context-menu-0')
+   *
+   * // 通过实例关闭
+   * const menu = ContextMenuService.instance.get('context-menu-0')
+   * if (menu) {
+   *   await ContextMenuService.instance.close(menu)
+   * }
+   * ```
+   *
+   * @public
+   */
   close(contextMenu: string | ContextMenu): Promise<boolean>
+  /**
+   * 关闭所有活动的右键菜单
+   *
+   * @returns 一个 Promise，解析为被关闭的菜单数量
+   *
+   * @remarks
+   * 该方法一次性从活动菜单列表中移除所有右键菜单。
+   * 适用于清理操作或需要重置菜单状态的场景。
+   *
+   * @example
+   * ```typescript
+   * const closedCount = await ContextMenuService.instance.closeAll()
+   * console.log(`Closed ${closedCount} menus`)
+   * ```
+   *
+   * @public
+   */
   closeAll(): Promise<number>
 }
 
@@ -649,6 +1067,18 @@ declare function degreesToQuaternion(v: V3): Quaternion
 
 declare function degreeToRadians(v: V3): V3
 
+/**
+ * 根据路径删除对象中的值
+ * @param source - 源对象
+ * @param path - 路径
+ * @example
+ * ```ts
+ * const obj = { a: { b: 1 } }
+ * RvUtils.setByRvPath(obj, "a.b") // obj === { a: {} }
+ * ```
+ */
+declare function deleteByRvPath(source: StoredRhineVar, path: string | RvPath): void
+
 /**
  * @public
  */
@@ -802,14 +1232,123 @@ export declare interface DialogPlugin extends IconPlugin {
 }
 
 /**
+ * 对话框服务
+ *
+ * @remarks
+ * 用于管理应用中的所有对话框，提供创建、打开、关闭对话框的功能。
+ * 支持确认对话框和输入对话框两种常用类型。
+ *
+ * @example
+ * 创建确认对话框
+ * ```typescript
+ * const result = await DialogService.instance.confirm({
+ *   title: '删除确认',
+ *   content: '确定要删除这个文件吗？',
+ *   theme: ThemeColor.RED
+ * })
+ * if (result) {
+ *   // 用户点击了确认
+ * }
+ * ```
+ *
+ * @example
+ * 创建输入对话框
+ * ```typescript
+ * const name = await DialogService.instance.input({
+ *   title: '输入名称',
+ *   inputPlaceholder: '请输入文件名',
+ *   defaultValue: 'untitled'
+ * })
+ * console.log('用户输入:', name)
+ * ```
+ *
  * @public
  */
 export declare class DialogService {
+  /**
+   * 获取 DialogService 的单例实例
+   *
+   * @returns DialogService 实例
+   */
   static get instance(): DialogService
   private constructor()
+  /**
+   * 创建一个自定义对话框
+   *
+   * @remarks
+   * 根据提供的配置创建对话框实例。如果未指定 ID，会自动生成唯一 ID。
+   * 可以通过 show 参数控制是否立即显示对话框。
+   *
+   * @param options - 对话框配置选项
+   * @param show - 是否立即显示对话框，默认为 true
+   * @returns 返回创建的 Dialog 实例
+   *
+   * @example
+   * ```typescript
+   * const dialog = await DialogService.instance.create({
+   *   title: '自定义对话框',
+   *   contentView: MyCustomComponent,
+   *   confirmText: '确定',
+   *   cancelText: '取消'
+   * })
+   * ```
+   */
   create(options: DialogCreateOptions, show?: boolean): Promise<Dialog>
+  /**
+   * 当前所有对话框实例的数组
+   *
+   * @remarks
+   * 保存所有已创建的对话框实例，用于查询和管理
+   */
   dialogs: Dialog[]
+  /**
+   * 对话框渲染器实例
+   *
+   * @remarks
+   * 负责对话框的实际渲染和显示逻辑
+   */
   renderer: DialogViewRenderer
+  /**
+   * 创建确认对话框
+   *
+   * @remarks
+   * 显示一个带有确认和取消按钮的对话框，用户点击按钮后返回对应的布尔值。
+   * 适用于需要用户确认的操作场景，如删除、保存、提交等。
+   *
+   * @param options - 确认对话框配置选项
+   * @param options.title - 对话框标题
+   * @param options.titleIcon - 标题图标，可以是 React 组件或字符串
+   * @param options.content - 对话框文本内容
+   * @param options.contentView - 自定义内容视图组件
+   * @param options.icon - 对话框图标
+   * @param options.theme - 主题颜色，默认为蓝色
+   * @param options.confirmText - 确认按钮文本，默认为 'Confirm'
+   * @param options.cancelText - 取消按钮文本，默认为 'Cancel'
+   * @param options.leftMode - 是否左对齐模式
+   * @param options.className - 自定义 CSS 类名
+   * @param options.style - 自定义样式对象
+   * @param options.onConfirm - 确认按钮点击回调
+   * @param options.onCancel - 取消按钮点击回调
+   * @param options.onClose - 对话框关闭回调
+   * @param options.closeOnOutsideClick - 是否允许点击外部关闭
+   * @param options.enableCloseButton - 是否显示关闭按钮，默认为 false
+   * @param show - 是否立即显示对话框，默认为 true
+   * @returns Promise，resolve 为 true 表示用户点击确认，false 表示取消
+   *
+   * @example
+   * ```typescript
+   * const confirmed = await DialogService.instance.confirm({
+   *   title: '删除文件',
+   *   content: '此操作不可恢复，确定要删除吗？',
+   *   theme: ThemeColor.RED,
+   *   confirmText: '删除',
+   *   cancelText: '取消'
+   * })
+   * if (confirmed) {
+   *   // 执行删除操作
+   * }
+   * ```
+   */
   confirm(
     options: {
       title: string
@@ -831,6 +1370,56 @@ export declare class DialogService {
     },
     show?: boolean,
   ): Promise<boolean>
+  /**
+   * 创建输入对话框
+   *
+   * @remarks
+   * 显示一个带有输入框的对话框，用户可以输入文本内容。
+   * 支持默认值、占位符、输入验证等功能，适用于需要用户输入信息的场景。
+   *
+   * @param options - 输入对话框配置选项
+   * @param options.title - 对话框标题
+   * @param options.titleIcon - 标题图标，可以是 React 组件或字符串
+   * @param options.content - 对话框文本内容
+   * @param options.contentView - 自定义内容视图组件
+   * @param options.icon - 对话框图标
+   * @param options.theme - 主题颜色，默认为蓝色
+   * @param options.leftMode - 是否左对齐模式
+   * @param options.className - 自定义 CSS 类名
+   * @param options.style - 自定义样式对象
+   * @param options.confirmText - 确认按钮文本，默认为 'Confirm'
+   * @param options.cancelText - 取消按钮文本，默认为 'Cancel'
+   * @param options.defaultValue - 输入框默认值
+   * @param options.inputPlaceholder - 输入框占位符文本
+   * @param options.autoFocus - 是否自动聚焦输入框
+   * @param options.allowEmpty - 是否允许空输入
+   * @param options.onChange - 输入内容变化回调
+   * @param options.onCheck - 输入验证函数，返回 true 表示验证通过
+   * @param options.onConfirm - 确认按钮点击回调，接收输入的值
+   * @param options.onCancel - 取消按钮点击回调
+   * @param options.onClose - 对话框关闭回调
+   * @param options.closeOnOutsideClick - 是否允许点击外部关闭
+   * @param options.enableCloseButton - 是否显示关闭按钮，默认为 false
+   * @param show - 是否立即显示对话框，默认为 true
+   * @returns Promise，resolve 为用户输入的字符串，取消时返回空字符串
+   *
+   * @example
+   * ```typescript
+   * const name = await DialogService.instance.input({
+   *   title: '重命名文件',
+   *   inputPlaceholder: '请输入新文件名',
+   *   defaultValue: 'myfile.txt',
+   *   onCheck: (value) => {
+   *     // 验证文件名格式
+   *     return /^[a-zA-Z0-9._-]+$/.test(value)
+   *   }
+   * })
+   * if (name) {
+   *   // 使用用户输入的名称
+   *   console.log('新文件名:', name)
+   * }
+   * ```
+   */
   input(
     options: {
       title: string
@@ -858,9 +1447,82 @@ export declare class DialogService {
     },
     show?: boolean,
   ): Promise<string | undefined>
+  /**
+   * 根据 ID 获取对话框实例
+   *
+   * @param id - 对话框的唯一标识符
+   * @returns 对话框实例，如果未找到则返回 undefined
+   *
+   * @example
+   * ```typescript
+   * const dialog = DialogService.instance.get('dialog-1')
+   * if (dialog) {
+   *   console.log('找到对话框:', dialog.title)
+   * }
+   * ```
+   */
   get(id: string): Dialog | undefined
+  /**
+   * 打开对话框
+   *
+   * @remarks
+   * 显示指定的对话框。可以传入对话框实例或对话框 ID。
+   * 如果渲染器未加载或找不到指定的对话框，会抛出错误。
+   *
+   * @param dialog - 对话框实例或对话框 ID
+   * @returns Promise，resolve 为布尔值表示是否成功打开
+   * @throws 渲染器未加载时抛出 'Dialog renderer not loaded'
+   * @throws 找不到指定对话框时抛出 'Failed to find dialog'
+   *
+   * @example
+   * ```typescript
+   * // 通过实例打开
+   * const dialog = await DialogService.instance.create(options, false)
+   * await DialogService.instance.open(dialog)
+   *
+   * // 通过 ID 打开
+   * await DialogService.instance.open('dialog-1')
+   * ```
+   */
   open(dialog: Dialog | string): Promise<boolean>
+  /**
+   * 关闭对话框
+   *
+   * @remarks
+   * 关闭指定的对话框。可以传入对话框实例或对话框 ID。
+   * 如果渲染器未加载或找不到指定的对话框，会抛出错误。
+   *
+   * @param dialog - 对话框实例或对话框 ID
+   * @returns Promise，resolve 为布尔值表示是否成功关闭
+   * @throws 渲染器未加载时抛出 'Dialog renderer not loaded'
+   * @throws 找不到指定对话框时抛出 'Failed to find dialog'
+   *
+   * @example
+   * ```typescript
+   * // 通过实例关闭
+   * await DialogService.instance.close(dialog)
+   *
+   * // 通过 ID 关闭
+   * await DialogService.instance.close('dialog-1')
+   * ```
+   */
   close(dialog: Dialog | string): Promise<boolean>
+  /**
+   * 关闭所有对话框
+   *
+   * @remarks
+   * 关闭当前所有打开的对话框。会依次关闭 dialogs 数组中的每个对话框。
+   * 如果渲染器未加载，会抛出错误。
+   *
+   * @returns Promise，resolve 为成功关闭的对话框数量
+   * @throws 渲染器未加载时抛出 'Dialog renderer not loaded'
+   *
+   * @example
+   * ```typescript
+   * const closedCount = await DialogService.instance.closeAll()
+   * console.log(`已关闭 ${closedCount} 个对话框`)
+   * ```
+   */
   closeAll(): Promise<number>
 }
 
@@ -1046,22 +1708,179 @@ export declare enum FirstLoadModelServiceStatus {
 export declare type FirstLoadModelServiceSubscriber = (type: FirstLoadModelServiceEventType) => void
 
 /**
+ * 首次加载服务
+ *
+ * @remarks
+ * 负责管理项目首次打开时所有文件的下载和加载过程。
+ * 该服务会在项目初始化时自动下载 RhineVarData.files 中定义的所有文件，
+ * 并提供加载进度、状态监控和错误处理等功能。
+ *
+ * 采用单例模式设计，通过 `FirstLoadService.instance` 访问唯一实例。
+ *
+ * @example
+ * ```typescript
+ * // 启动首次加载
+ * FirstLoadService.instance.start()
+ *
+ * // 监听加载进度
+ * FirstLoadService.instance.subscribe((type) => {
+ *   if (type === FirstLoadServiceEventType.PROGRESS) {
+ *     console.log(`已加载: ${FirstLoadService.instance.loadedSize} / ${FirstLoadService.instance.totalSize}`)
+ *   }
+ * })
+ * ```
+ *
  * @public
  */
 export declare class FirstLoadService {
+  /**
+   * 获取 FirstLoadService 的单例实例
+   *
+   * @returns FirstLoadService 的唯一实例
+   *
+   * @public
+   */
   static get instance(): FirstLoadService
-  private constructor()
+  /**
+   * 当前加载服务的状态
+   *
+   * @remarks
+   * 可能的状态值:
+   * - WAITING: 等待开始
+   * - LOADING: 正在加载
+   * - LOADED: 加载完成
+   * - ERROR: 加载出错
+   * - CANCELED: 加载取消
+   *
+   * @public
+   */
   status: FirstLoadServiceStatus
+  /**
+   * 本地数据对象列表
+   *
+   * @remarks
+   * 包含所有正在加载或已加载的文件的本地数据对象，
+   * 每个 LocalData 对象包含文件的 fid、状态、进度等信息。
+   *
+   * @public
+   */
   localDataList: LocalData[]
+  /**
+   * 当前正在加载中的文件数量
+   *
+   * @remarks
+   * 包括状态为 LOADING、WAITING 或 PAUSED 的文件
+   *
+   * @public
+   */
   loadingNumber: number
+  /**
+   * 已成功加载的文件数量
+   *
+   * @public
+   */
   loadedNumber: number
+  /**
+   * 加载失败的文件数量
+   *
+   * @public
+   */
   errorNumber: number
+  /**
+   * 已取消加载的文件数量
+   *
+   * @public
+   */
   canceledNumber: number
+  /**
+   * 需要加载的文件总大小(字节)
+   *
+   * @public
+   */
   totalSize: number
+  /**
+   * 已加载的文件大小(字节)
+   *
+   * @remarks
+   * 根据每个文件的下载进度计算得出，用于显示整体加载进度
+   *
+   * @public
+   */
   loadedSize: number
+  /**
+   * 开始加载的时间戳(毫秒)
+   *
+   * @remarks
+   * 用于计算总加载耗时
+   *
+   * @public
+   */
   startTime: number
+  /**
+   * 开始加载所有文件
+   *
+   * @remarks
+   * 启动首次加载流程，会遍历 RvFileService.instance.files 中的所有文件并开始下载。
+   * 该方法会:
+   * 1. 检查是否有需要加载的文件
+   * 2. 跳过正在上传中的文件(uploading = true)
+   * 3. 计算文件总大小
+   * 4. 调用 LocalDataService 加载每个文件
+   * 5. 监听加载进度和状态变化
+   * 6. 在所有文件加载完成或出错时触发相应事件
+   *
+   * 如果加载过程中出现错误，会弹出对话框提示用户刷新页面重新加载。
+   *
+   * @example
+   * ```typescript
+   * // 在项目初始化时启动文件加载
+   * FirstLoadService.instance.start()
+   * ```
+   *
+   * @public
+   */
   start(): void
+  /**
+   * 订阅加载事件
+   *
+   * @remarks
+   * 注册一个回调函数来监听文件加载的各种事件:
+   * - START: 开始加载
+   * - PROGRESS: 加载进度更新
+   * - LOADED: 所有文件加载完成
+   * - ERROR: 加载出错
+   * - CANCELED: 加载取消
+   *
+   * @param subscriber - 事件回调函数
+   * @returns 取消订阅的函数，调用后将停止接收事件通知
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = FirstLoadService.instance.subscribe((type) => {
+   *   if (type === FirstLoadServiceEventType.PROGRESS) {
+   *     console.log('Loading progress:', FirstLoadService.instance.loadedSize)
+   *   } else if (type === FirstLoadServiceEventType.LOADED) {
+   *     console.log('All files loaded!')
+   *   }
+   * })
+   *
+   * // 取消订阅
+   * unsubscribe()
+   * ```
+   *
+   * @public
+   */
   subscribe(subscriber: FirstLoadServiceSubscriber): () => void
+  /**
+   * 取消订阅加载事件
+   *
+   * @remarks
+   * 从订阅者列表中移除指定的回调函数，移除后将不再接收事件通知
+   *
+   * @param subscriber - 要取消订阅的回调函数
+   *
+   * @public
+   */
   unsubscribe(subscriber: FirstLoadServiceSubscriber): void
 }
 
@@ -1563,34 +2382,225 @@ export declare interface LocalData {
 }
 
 /**
+ * 本地数据服务
+ *
+ * 负责管理所有本地数据，包括文件和一些模型内部的派生对象。
+ * 监听 RhineVar 文件系统的变化，实时加载文件到本地。
+ * 提供文件的加载、删除、状态管理和订阅功能。
+ *
  * @public
+ * @example
+ * ```typescript
+ * // 获取服务实例
+ * const localDataService = LocalDataService.instance
+ *
+ * // 加载文件
+ * await localDataService.load(fid, url, mime)
+ *
+ * // 订阅文件加载事件
+ * localDataService.afterLoaded(fid, (localData) => {
+ *   console.log('文件已加载:', localData)
+ * })
+ * ```
  */
 export declare class LocalDataService {
+  /**
+   * 获取 LocalDataService 单例实例
+   *
+   * @returns LocalDataService 实例
+   * @public
+   */
   static get instance(): LocalDataService
   private constructor()
+  /**
+   * 本地数据文件存储 Map
+   *
+   * 键为文件ID（fid），值为本地数据对象（LocalData）
+   *
+   * @public
+   */
   files: Map<string, LocalData>
+  /**
+   * 根据文件ID获取本地数据
+   *
+   * @param fid - 文件ID
+   * @returns 本地数据对象，如果不存在则返回 undefined
+   * @public
+   */
   get(fid: string): LocalData | undefined
+  /**
+   * 检查是否存在指定的本地数据
+   *
+   * @param fid - 文件ID
+   * @returns 如果存在返回 true，否则返回 false
+   * @public
+   */
   has(fid: string): boolean
+  /**
+   * 添加本地数据
+   *
+   * 如果指定的文件ID已存在，则返回已存在的本地数据。
+   * 否则创建新的本地数据对象，并发布 ADD 和 LOADED 事件。
+   *
+   * @param option - 添加本地数据的选项
+   * @returns 本地数据对象
+   * @public
+   */
   add(option: AddLocalDataOption): LocalData
   /**
    * 加载一个文件到本地
    *
-   * @param fid - 文件在rv中的fid
-   * @param url - 文件的直接下载链接或者oss链接
-   * @Param mime - 文件类型
+   * 根据提供的 URL 类型（blob、http/https、oss）下载文件到本地。
+   * 支持下载进度跟踪，下载完成后会自动处理文件内容（JSON、文本等）。
+   * 如果文件已存在且已加载完成，则直接返回已存在的本地数据。
+   *
+   * @param fid - 文件在 RhineVar 中的文件ID
+   * @param url - 文件的直接下载链接、Blob URL 或 OSS 链接
+   * @param mime - 文件 MIME 类型，默认为 UNKNOWN
+   * @returns Promise<LocalData> - 返回本地数据对象的 Promise
+   * @public
    */
   load(fid: string, url: string, mime?: string): Promise<LocalData>
+  /**
+   * 通过 File 对象加载文件到本地
+   *
+   * 直接使用浏览器 File 对象创建本地数据，适用于用户上传文件的场景。
+   * 加载完成后会自动处理文件内容（JSON、文本等）。
+   *
+   * @param fid - 文件ID
+   * @param file - 浏览器 File 对象
+   * @param mime - 文件 MIME 类型，默认为 UNKNOWN
+   * @returns Promise<LocalData> - 返回本地数据对象的 Promise
+   * @public
+   */
   loadByFile(fid: string, file: File, mime?: string): Promise<LocalData>
+  /**
+   * 处理文件加载完成后的操作
+   *
+   * 根据文件 MIME 类型自动解析文件内容：
+   * - 如果是 JSON 文件，解析为 JSON 对象并存储到 localData.json
+   * - 如果是文本文件，读取为文本字符串并存储到 localData.text
+   *
+   * @param localData - 本地数据对象
+   * @returns Promise<boolean> - 是否成功处理
+   * @public
+   */
   processAfterLoad(localData: LocalData): Promise<boolean>
+  /**
+   * 移除指定的本地数据
+   *
+   * 从本地数据 Map 中删除指定的文件数据，并发布 REMOVE 事件。
+   *
+   * @param fid - 文件ID
+   * @returns 如果成功移除返回 true，如果文件不存在返回 false
+   * @public
+   */
   remove(fid: string): boolean
+  /**
+   * 暂停文件下载
+   *
+   * @param fid - 文件ID
+   * @returns 是否成功暂停
+   * @public
+   * @throws 该方法尚未实现
+   */
   pause(fid: string): boolean
+  /**
+   * 恢复文件下载
+   *
+   * @param fid - 文件ID
+   * @returns 是否成功恢复
+   * @public
+   * @throws 该方法尚未实现
+   */
   resume(fid: string): boolean
+  /**
+   * 取消文件下载
+   *
+   * @param fid - 文件ID
+   * @returns 是否成功取消
+   * @public
+   * @throws 该方法尚未实现
+   */
   cancel(fid: string): boolean
+  /**
+   * 获取本地文件的 Blob URL
+   *
+   * 将本地数据转换为浏览器可用的 Blob URL，用于在浏览器中显示或下载文件。
+   * 如果数据类型是 BLOB，则创建 Blob URL；如果是 OBJECT，则创建 MediaSource URL。
+   *
+   * @param fid - 文件ID
+   * @returns Blob URL 字符串，如果文件不存在或未加载完成则返回空字符串
+   * @public
+   */
   getLocalUrl(fid: string): string
+  /**
+   * 释放本地文件的 Blob URL
+   *
+   * 释放之前通过 getLocalUrl 创建的 Blob URL，避免内存泄漏。
+   *
+   * @param fid - 文件ID
+   * @returns 如果成功释放返回 true，如果文件不存在或没有 URL 返回 false
+   * @public
+   */
   releaseLocalUrl(fid: string): boolean
+  /**
+   * 订阅所有本地数据的事件
+   *
+   * 订阅所有文件的加载、进度、错误等事件。
+   * 每当任何文件发生事件时，订阅回调函数都会被调用。
+   *
+   * @param subscriber - 订阅回调函数
+   * @returns 取消订阅的函数
+   * @public
+   * @example
+   * ```typescript
+   * const unsubscribe = LocalDataService.instance.subscribe((type, localData) => {
+   *   console.log('事件类型:', type)
+   *   console.log('本地数据:', localData)
+   * })
+   *
+   * // 取消订阅
+   * unsubscribe()
+   * ```
+   */
   subscribe(subscriber: LocalDataServiceSubscriber): () => void
+  /**
+   * 取消订阅所有本地数据的事件
+   *
+   * @param subscriber - 要取消的订阅回调函数
+   * @public
+   */
   unsubscribe(subscriber: LocalDataServiceSubscriber): void
+  /**
+   * 订阅单个文件的事件
+   *
+   * 只订阅指定文件ID的事件，不会接收其他文件的事件通知。
+   *
+   * @param fid - 文件ID
+   * @param subscriber - 订阅回调函数
+   * @returns 取消订阅的函数
+   * @public
+   * @example
+   * ```typescript
+   * const unsubscribe = LocalDataService.instance.subscribeSingle(fid, (type, localData) => {
+   *   if (type === LocalDataServiceEventType.LOADED) {
+   *     console.log('文件加载完成:', localData)
+   *   }
+   * })
+   *
+   * // 取消订阅
+   * unsubscribe()
+   * ```
+   */
   subscribeSingle(fid: string, subscriber: LocalDataServiceSubscriber): () => void
+  /**
+   * 取消订阅单个文件的事件
+   *
+   * @param fid - 文件ID
+   * @param subscriber - 要取消的订阅回调函数
+   * @public
+   */
   unsubscribeSingle(fid: string, subscriber: LocalDataServiceSubscriber): void
   publish(fid: string, type: LocalDataServiceEventType, localData: LocalData): void
   afterLoaded(fid: string, subscriber: (localData: LocalData) => void): void
@@ -1676,6 +2686,19 @@ declare function makeRvPath(path: string): RvPath
  */
 declare function makeRvPathString(path: RvPath): string
 
+export declare class MaterialNodeAttribute extends NodeAttribute<RvMaterialNode> {
+  path: string[]
+  defaultValue: RvMaterialNode
+  multiInitialize(nidList?: string[]): void
+}
+
+export declare class MaterialPbrAttribute extends NodeAttribute<RvMaterialPBR> {
+  path: string[]
+  defaultValue: RvMaterialPBR
+  multiInitialize(nidList?: string[]): void
+  generate(sid?: string, nid?: string): RvMaterialPBR
+}
+
 /**
  * @public
  */
@@ -2062,6 +3085,8 @@ export declare abstract class NodeAttribute<T extends object = never> extends Ba
   get targetNidList(): string[]
   generate(sid?: string, nid?: string): T
   multiGenerate(sidList?: string[], nidList?: string[]): Map<string, Map<string, T>>
+  readonly sameGenerateForStepsMode = true
+  readonly sameGenerateForNodesMode = false
   initialize(nid?: string): void
   isInitialized(nid?: string): boolean
   multiInitialize(nidList?: string[]): void
@@ -2172,25 +3197,245 @@ export declare enum OssUploadInstanceStatus {
 }
 
 /**
+ * OSS 上传服务
+ *
+ * @remarks
+ * 该服务负责管理所有 OSS 上传任务队列，提供文件上传、取消、状态监听等功能。
+ * 所有上传任务都会创建对应的 RvFile 记录，并在协同数据中标记 `uploading: true`。
+ * 上传完成后会自动更新 RvFile 的 URL 并移除上传标记。
+ *
+ * @example
+ * ```typescript
+ * // 上传文件
+ * const fid = await OssUploadService.instance.upload(file)
+ *
+ * // 监听上传进度
+ * OssUploadService.instance.subscribe((type, instance) => {
+ *   if (type === OssUploadServiceEventType.PROGRESS) {
+ *     console.log(`上传进度: ${instance.progress}%`)
+ *   }
+ * })
+ * ```
+ *
  * @public
  */
 export declare class OssUploadService {
+  /**
+   * 获取 OssUploadService 单例实例
+   *
+   * @returns OssUploadService 单例实例
+   *
+   * @public
+   */
   static get instance(): OssUploadService
-  private constructor()
+  /**
+   * 当前所有上传实例的集合
+   *
+   * @remarks
+   * 使用 Map 结构存储，key 为文件 ID (fid)，value 为上传实例对象。
+   * 上传完成后，实例会从集合中自动移除。
+   *
+   * @public
+   */
   instances: Map<string, OssUploadInstance>
+  /**
+   * 根据文件 ID 获取上传实例
+   *
+   * @param fid - 文件 ID
+   * @returns 上传实例对象，如果不存在则返回 undefined
+   *
+   * @public
+   */
   get(fid: string): OssUploadInstance | undefined
+  /**
+   * 检查是否存在指定 ID 的上传任务
+   *
+   * @param fid - 文件 ID
+   * @returns 如果存在返回 true，否则返回 false
+   *
+   * @public
+   */
   has(fid: string): boolean
+  /**
+   * 检查指定的 File 对象是否已经在上传队列中
+   *
+   * @param file - 要检查的 File 对象
+   * @returns 如果该文件已在上传队列中返回 true，否则返回 false
+   *
+   * @remarks
+   * 该方法通过遍历所有上传实例来比较 File 对象引用
+   *
+   * @public
+   */
   hasFile(file: File): boolean
+  /**
+   * 上传完成后从队列中移除的延迟时间（毫秒）
+   *
+   * @defaultValue 100
+   *
+   * @public
+   */
   REMOVE_INTERVAL_AFTER_COMPLETED: number
+  /**
+   * 上传文件到 OSS
+   *
+   * @param file - 要上传的文件对象
+   * @param fid - 文件 ID，如果不提供则自动生成
+   * @param mime - 文件 MIME 类型，如果不提供则自动检测
+   * @param hash - 文件哈希值（可选）
+   * @returns Promise，上传任务启动后返回
+   *
+   * @remarks
+   * 该方法会执行以下操作：
+   * 1. 创建 RvFile 记录，标记 `uploading: true`
+   * 2. 创建上传实例并加入队列
+   * 3. 开始上传并触发相关事件（START、PROGRESS、UPLOADED/FAILED）
+   * 4. 上传成功后更新 RvFile 的 URL 并移除 uploading 标记
+   * 5. 上传失败后自动删除 RvFile 记录
+   * 6. 将文件添加到本地数据服务
+   *
+   * @throws 如果创建 RvFile 失败，抛出 Error
+   *
+   * @example
+   * ```typescript
+   * // 基本用法
+   * await OssUploadService.instance.upload(file)
+   *
+   * // 指定文件 ID
+   * await OssUploadService.instance.upload(file, 'custom-fid')
+   *
+   * // 指定 MIME 类型和哈希值
+   * await OssUploadService.instance.upload(file, 'custom-fid', 'image/png', 'sha256-hash')
+   * ```
+   *
+   * @public
+   */
   upload(file: File, fid?: string, mime?: string, hash?: string): Promise<void>
+  /**
+   * 暂停指定的上传任务
+   *
+   * @param fid - 文件 ID
+   * @returns 暂停操作是否成功
+   *
+   * @remarks
+   * 该方法尚未实现，调用会抛出异常
+   *
+   * @throws 方法未实现错误
+   *
+   * @public
+   */
   pause(fid: string): boolean
+  /**
+   * 恢复指定的上传任务
+   *
+   * @param fid - 文件 ID
+   * @returns 恢复操作是否成功
+   *
+   * @remarks
+   * 该方法尚未实现，调用会抛出异常
+   *
+   * @throws 方法未实现错误
+   *
+   * @public
+   */
   resume(fid: string): boolean
+  /**
+   * 取消指定的上传任务
+   *
+   * @param fid - 文件 ID
+   * @returns 取消操作是否成功
+   *
+   * @remarks
+   * 取消上传后会发布 CANCELED 事件，无论取消是否成功都会发布该事件。
+   * 取消后上传实例仍会保留在队列中，直到超时或手动移除。
+   *
+   * @example
+   * ```typescript
+   * const fid = 'file-id'
+   * if (OssUploadService.instance.cancel(fid)) {
+   *   console.log('上传已取消')
+   * }
+   * ```
+   *
+   * @public
+   */
   cancel(fid: string): boolean
+  /**
+   * 订阅所有文件的上传事件
+   *
+   * @param subscriber - 订阅回调函数，当任何文件的上传状态改变时会被调用
+   * @returns 取消订阅的函数
+   *
+   * @remarks
+   * 该方法会监听所有文件的上传事件，包括：
+   * - START: 上传开始
+   * - PROGRESS: 上传进度更新
+   * - UPLOADED: 上传成功
+   * - FAILED: 上传失败
+   * - CANCELED: 上传取消
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = OssUploadService.instance.subscribe((type, instance) => {
+   *   console.log(`文件 ${instance.fid} 状态: ${type}, 进度: ${instance.progress}%`)
+   * })
+   *
+   * // 取消订阅
+   * unsubscribe()
+   * ```
+   *
+   * @public
+   */
   subscribe(subscriber: OssUploadServiceSubscriber): () => void
+  /**
+   * 取消订阅所有文件的上传事件
+   *
+   * @param subscriber - 要取消的订阅回调函数
+   *
+   * @remarks
+   * 从订阅列表中移除指定的订阅者
+   *
+   * @public
+   */
   unsubscribe(subscriber: OssUploadServiceSubscriber): void
+  /**
+   * 订阅指定文件的上传事件
+   *
+   * @param fid - 要订阅的文件 ID
+   * @param subscriber - 订阅回调函数，当该文件的上传状态改变时会被调用
+   * @returns 取消订阅的函数
+   *
+   * @remarks
+   * 该方法只监听指定文件的上传事件。相比 {@link subscribe}，这个方法更适合只关注单个文件的场景。
+   * 事件类型包括：START、PROGRESS、UPLOADED、FAILED、CANCELED
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = OssUploadService.instance.subscribeSingle('file-id', (type, instance) => {
+   *   if (type === OssUploadServiceEventType.UPLOADED) {
+   *     console.log('文件上传完成')
+   *   }
+   * })
+   *
+   * // 取消订阅
+   * unsubscribe()
+   * ```
+   *
+   * @public
+   */
   subscribeSingle(fid: string, subscriber: OssUploadServiceSubscriber): () => void
+  /**
+   * 取消订阅指定文件的上传事件
+   *
+   * @param fid - 文件 ID
+   * @param subscriber - 要取消的订阅回调函数
+   *
+   * @remarks
+   * 从指定文件的订阅列表中移除订阅者
+   *
+   * @public
+   */
   unsubscribeSingle(fid: string, subscriber: OssUploadServiceSubscriber): void
-  publish(fid: string, type: OssUploadServiceEventType, uploadInstance: OssUploadInstance): void
 }
 
 /**
@@ -3199,6 +4444,8 @@ export declare class RsNodeService {
    * ```
    */
   getNodeByNid(nid: string): Node_2 | null
+  getMeshByNid(nid: string): Mesh | null
+  getMaterialByNid(nid: string): Material | null
   /**
    * 根据 Babylon.js uniqueId 获取 nid
    *
@@ -3897,7 +5144,6 @@ export declare class RvLoopAttribute {
  */
 export declare interface RvMaterial {
   general: RvMaterialGeneral
-  preset: RvPresetType
   pbr?: RvMaterialPBR
   node?: RvMaterialNode
   texture: RvMaterialTexture
@@ -3963,6 +5209,7 @@ export declare interface RvMaterialGeneral {
   isExtracted: boolean
   transparencyMode: TransparencyMode
   needDepthPrePass: boolean
+  preset: RvPresetType
 }
 
 /**
@@ -4501,6 +5748,7 @@ export declare const RvUtils: {
   ensureRvPathString: typeof ensureRvPathString
   getByRvPath: typeof getByRvPath
   setByRvPath: typeof setByRvPath
+  deleteByRvPath: typeof deleteByRvPath
   checkRvPathOverlay: typeof checkRvPathOverlay
   checkRvPathStartWith: typeof checkRvPathStartWith
   checkAnyRvPathOverlay: typeof checkAnyRvPathOverlay
@@ -4827,6 +6075,7 @@ export declare abstract class StepAttribute<T extends object = never> extends Ba
   get targetSidList(): string[]
   generate(sid?: string): T
   multiGenerate(sidList?: string[]): Map<string, T>
+  readonly sameGenerateForStepsMode = true
   initialize(): void
   isInitialized(): boolean
   mark(path: string | RvPath, sid?: string): void