@cocos/cocos-cli-types 0.0.1-alpha.24.1 → 0.0.1-alpha.24.2

package/cli.d.ts

@@ -485,7 +485,7 @@ export declare interface GlTFUserData {
  * 添加/创建组件的选项
  */
 export declare interface IAddComponentOptions {
-    nodePathOrUuid: string;
+    nodePath: string;
     component: string;
 }
 
@@ -689,31 +689,31 @@ export declare interface IComponentService extends IServiceEvents {
     /**
      * 添加组件到指定节点，返回添加后的组件信息
      * @param params - 添加组件选项
-     * @param params.nodePathOrUuid - 目标节点路径或 UUID
+     * @param params.nodePath - 目标节点路径
      * @param params.component - 组件类名，支持精确匹配（'cc.Label'）和模糊匹配（'label'）
      * @returns 添加成功后的组件信息
      *
      * @example
      * ```ts
      * // 通过节点路径 + 精确组件名
-     * const comp = await addComponent({ nodePathOrUuid: 'Canvas/MyNode', component: 'cc.Label' });
+     * const comp = await add({ nodePath: 'Canvas/MyNode', component: 'cc.Label' });
      *
-     * // 通过节点 UUID + 模糊组件名
-     * const comp = await addComponent({ nodePathOrUuid: 'abc-123-uuid', component: 'label' });
+     * // 通过节点路径 + 模糊组件名
+     * const comp = await add({ nodePath: 'Canvas/MyNode', component: 'label' });
      * ```
      */
-    addComponent(params: IAddComponentOptions): Promise<IComponent>;
+    add(params: IAddComponentOptions): Promise<IComponent>;
     /**
      * 删除指定组件
      * @param params - 删除组件选项
-     * @param params.path - 组件路径，支持路径、UUID 或资源 URL
+     * @param params.path - 组件路径
      * @returns 删除成功返回 true，失败返回 false
      */
-    removeComponent(params: IRemoveComponentOptions): Promise<boolean>;
+    remove(params: IRemoveComponentOptions): Promise<boolean>;
     /**
      * 设置组件属性
      * - CLI 调用时传入 ISetPropertyOptions，通过 componentPath 定位，属性为扁平键值对
-     * - 编辑器调用时传入 ISetPropertyOptionsForEditor，通过节点 UUID + dump 路径定位，属性为 IProperty 格式
+     * - 编辑器调用时传入 ISetPropertyOptionsForEditor，通过节点路径 + dump 路径定位，属性为 IProperty 格式
      *
      * @param params - 设置属性选项，根据调用方不同传入不同类型
      * @returns 设置成功返回 true，失败返回 false
@@ -726,9 +726,9 @@ export declare interface IComponentService extends IServiceEvents {
      *     properties: { string: 'Hello', fontSize: 32 },
      * });
      *
-     * // 编辑器方式：通过节点 UUID + dump 路径定位，传 IProperty 格式
+     * // 编辑器方式：通过节点路径 + dump 路径定位，传 IProperty 格式
      * await setProperty({
-     *     uuid: 'node-uuid',
+     *     nodePath: 'Canvas/MyNode',
      *     path: '__comps__.0.string',
      *     dump: { value: 'Hello', type: 'String' },
      * });
@@ -746,33 +746,33 @@ export declare interface IComponentService extends IServiceEvents {
      * @example
      * ```ts
      * CLI 模式：返回 IComponent（扁平属性）
-     * const comp = await queryComponent({ path: 'Canvas/cc.Label_1' }) as IComponent;
+     * const comp = await query({ path: 'Canvas/cc.Label_1' }) as IComponent;
      *
      * 编辑器模式：直接传 string，这里是uuid，因为与cli重复了，也支持 path 和 url
-     * const comp = await queryComponent('uuid') as IComponentForEditor;
+     * const comp = await query('uuid') as IComponentForEditor;
      * ```
      */
-    queryComponent(params: IQueryComponentOptions | string): Promise<IComponent | IComponentForEditor | null>;
+    query(params: IQueryComponentOptions | string): Promise<IComponent | IComponentForEditor | null>;
     /**
      * 获取所有已注册的组件类名，包含内置与自定义组件
      * @returns 组件类名数组，如 ['cc.Label', 'cc.Sprite', 'MyCustomComponent']
      */
-    queryAllComponent(): Promise<string[]>;
+    queryAll(): Promise<string[]>;
     /**
-     * 创建组件（编辑器使用），与 addComponent 不同的是仅返回是否成功
+     * 创建组件（编辑器使用），与 add 不同的是仅返回是否成功
      * @param params - 添加组件选项
-     * @param params.nodePathOrUuid - 目标节点路径或 UUID
+     * @param params.nodePath - 目标节点路径
      * @param params.component - 组件类名
      * @returns 创建成功返回 true，失败返回 false
      */
-    createComponent(params: IAddComponentOptions): Promise<boolean>;
+    create(params: IAddComponentOptions): Promise<boolean>;
     /**
      * 复位组件，将组件所有属性恢复为默认值
      * @param params - 查询组件选项，用于定位要复位的组件
-     * @param params.path - 组件路径，支持路径、UUID 或资源 URL
+     * @param params.path - 组件路径
      * @returns 复位成功返回 true，失败返回 false
      */
-    resetComponent(params: IQueryComponentOptions): Promise<boolean>;
+    reset(params: IQueryComponentOptions): Promise<boolean>;
     /**
      * 获取所有注册类名，支持按继承关系过滤
      * @param options - 过滤选项，不传则返回所有注册类
@@ -797,25 +797,25 @@ export declare interface IComponentService extends IServiceEvents {
     }[]>;
     /**
      * 查询指定节点上所有组件暴露的可调用函数
-     * @param uuid - 节点 UUID
+     * @param path - 节点路径
      * @returns 节点上组件的函数信息，节点不存在时返回空对象
      */
-    queryComponentFunctionOfNode(uuid: string): Promise<any>;
+    queryFunctionOfNode(path: string): Promise<any>;
     /**
      * 执行组件上的指定方法
      * @param options - 执行选项
-     * @param options.uuid - 组件实例的 UUID
+     * @param options.path - 组件路径，如 'Canvas/cc.Label_1'
      * @param options.name - 要执行的方法名，如 'onLoad'、'start'
      * @param options.args - 方法参数列表
      * @returns 执行成功返回 true，失败返回 false
      */
-    executeComponentMethod(options: IExecuteComponentMethodOptions): Promise<boolean>;
+    executeMethod(options: IExecuteComponentMethodOptions): Promise<any>;
     /**
      * 查询指定名称的组件是否已注册（是否存在对应脚本）
      * @param name - 组件类名，如 'cc.Label'
      * @returns 存在返回 true，不存在返回 false
      */
-    queryComponentHasScript(name: string): Promise<boolean>;
+    hasScript(name: string): Promise<boolean>;
     init(): void;
     unregisterCompMgrEvents(): void;
 }
@@ -921,7 +921,7 @@ export declare interface IEngineService extends IServiceEvents {
  * 执行组件方法的选项
  */
 export declare interface IExecuteComponentMethodOptions {
-    uuid: string;
+    path: string;
     name: string;
     args: any[];
 }
@@ -1057,6 +1057,31 @@ export declare interface INode extends INodeIdentifier {
     prefab: IPrefabInfo | null;
 }
 
+export declare interface INodeForEditor {
+    active: IProperty;
+    locked: IProperty;
+    name: IProperty;
+    position: IProperty;
+    /**
+     * 此为 dump 数据，非 node.rotation
+     * 实际指向 node.eulerAngles
+     * rotation 为了给用户更友好的文案
+     */
+    rotation: IProperty;
+    mobility: IProperty;
+    scale: IProperty;
+    layer: IProperty;
+    uuid: IProperty;
+    children: IProperty[];
+    parent: IProperty;
+    __comps__: IProperty[];
+    __type__: string;
+    __prefab__?: IPrefabForEditor;
+    _prefabInstance?: any;
+    removedComponents?: IRemovedComponentInfo[];
+    mountedRoot?: string;
+}
+
 export declare interface INodeIdentifier {
     nodeId: string;
     path: string;
@@ -1081,30 +1106,144 @@ export declare interface INodeService extends IServiceEvents {
      * 创建节点
      * @param params
      */
-    createNodeByType(params: ICreateByNodeTypeParams): Promise<INode | null>;
+    createByType(params: ICreateByNodeTypeParams): Promise<INode | null>;
     /**
      * 创建节点
      * @param params
      */
-    createNodeByAsset(params: ICreateByAssetParams): Promise<INode | null>;
+    createByAsset(params: ICreateByAssetParams): Promise<INode | null>;
     /**
      * 删除节点
      * @param params
      */
-    deleteNode(params: IDeleteNodeParams): Promise<IDeleteNodeResult | null>;
+    delete(params: IDeleteNodeParams): Promise<IDeleteNodeResult | null>;
     /**
      * 更新节点
      * @param params
      */
-    updateNode(params: IUpdateNodeParams): Promise<IUpdateNodeResult>;
+    update(params: IUpdateNodeParams): Promise<IUpdateNodeResult>;
     /**
-     * 查询节点
+     * 查询节点信息
+     * - 不传参数时，返回当前场景的 dump 数据（ISceneForEditor）
+     * - 传入 string 时，返回指定路径节点的 dump 数据（编辑器模式，返回 INodeForEditor 数据）
+     * - 传入 IQueryNodeParams 时，返回 INode（CLI 模式）
+     *
+     * @param params - 查询选项、节点路径字符串或不传
+     * @returns 如果传入 IQueryNodeParams 返回 INode，如果传入 string 或不传返回 INodeForEditor 或 ISceneForEditor，未找到返回 null
      */
-    queryNode(params: IQueryNodeParams): Promise<INode | null>;
+    query(params?: IQueryNodeParams | string): Promise<INode | INodeForEditor | ISceneForEditor | null>;
     /**
      * 查询节点树（层级管理器格式）
      */
     queryNodeTree(params: IQueryNodeTreeParams): Promise<INodeTreeItem | null>;
+    /**
+     * 预览设置节点属性，临时应用属性变更但不记录到 undo 栈
+     * 用于编辑器中拖拽滑块等实时预览场景，首次调用时会缓存原始值，
+     * 可通过 cancelPreviewSetProperty 恢复
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.path - 属性路径，如 'position'、'scale'
+     * @param options.dump - 属性的 dump 数据
+     * @returns 设置成功返回 true，节点或属性路径无效返回 false
+     *
+     * @example
+     * ```ts
+     * // 预览修改节点位置
+     * await previewSetProperty({
+     *     nodePath: 'Canvas/MyNode',
+     *     path: 'position',
+     *     dump: { value: { x: 100, y: 200, z: 0 }, type: 'cc.Vec3' },
+     * });
+     * ```
+     */
+    previewSetProperty(options: ISetPropertyOptionsForEditor): Promise<boolean>;
+    /**
+     * 取消预览设置，将节点属性恢复到 previewSetProperty 调用前的值
+     * 仅使用 options.nodePath 和 options.path，options.dump 不会被使用
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.path - 属性路径
+     * @returns 恢复成功返回 true，无缓存的预览数据或节点无效返回 false
+     */
+    cancelPreviewSetProperty(options: ISetPropertyOptionsForEditor): Promise<boolean>;
+    /**
+     * 设置节点属性，会记录到 undo 栈
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.path - 属性路径，如 'position'、'rotation'、'layer'
+     * @param options.dump - 属性的 dump 数据
+     * @returns 设置成功返回 true，节点不存在返回 false
+     *
+     * @example
+     * ```ts
+     * await setProperty({
+     *     nodePath: 'Canvas/MyNode',
+     *     path: 'position',
+     *     dump: { value: { x: 100, y: 200, z: 0 }, type: 'cc.Vec3' },
+     * });
+     * ```
+     */
+    setProperty(options: ISetPropertyOptionsForEditor): Promise<boolean>;
+    /**
+     * 重置节点的变换属性（position、rotation、scale、mobility）到默认值
+     *
+     * @param path - 节点路径
+     * @returns 重置成功返回 true，节点不存在返回 false
+     */
+    reset(path: string): Promise<boolean>;
+    /**
+     * 重置节点的单个属性到 CCClass 定义的默认值
+     * 仅使用 options.nodePath 和 options.path，options.dump 不会被使用
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.path - 属性路径，如 'position'、'scale'
+     * @returns 重置成功返回 true，节点不存在返回 false
+     */
+    resetProperty(options: ISetPropertyOptionsForEditor): Promise<boolean>;
+    /**
+     * 将节点上值为 null 的属性初始化为默认实例
+     * 当属性为 null 且有定义构造函数类型时，会创建该类型的新实例
+     * 仅使用 options.nodePath 和 options.path，options.dump 不会被使用
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.path - 属性路径
+     * @returns 初始化成功返回 true，节点不存在返回 false
+     *
+     * @example
+     * ```ts
+     * // 将节点上值为 null 的自定义属性初始化
+     * await updatePropertyFromNull({
+     *     nodePath: 'Canvas/MyNode',
+     *     path: 'customProperty',
+     *     dump: {} as IProperty,
+     * });
+     * ```
+     */
+    updatePropertyFromNull(options: ISetPropertyOptionsForEditor): Promise<boolean>;
+    /**
+     * 设置节点及其所有子节点的 layer 属性
+     * 递归将相同的 layer 值应用到整个节点子树
+     * 仅使用 options.nodePath 和 options.dump，options.path 不会被使用（内部固定为 'layer'）
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.dump - layer 属性的 dump 数据
+     *
+     * @example
+     * ```ts
+     * await setNodeAndChildrenLayer({
+     *     nodePath: 'Canvas/MyNode',
+     *     path: 'layer',
+     *     dump: { value: 1 << 25, type: 'Enum' },
+     * });
+     * ```
+     */
+    setNodeAndChildrenLayer(options: ISetPropertyOptionsForEditor): Promise<void>;
 }
 
 export declare interface INodeTreeComponent {
@@ -1155,6 +1294,16 @@ export declare interface IPrefab {
     persistent: boolean;
 }
 
+export declare interface IPrefabForEditor {
+    uuid: string;
+    fileId: string;
+    rootUuid: string;
+    sync: boolean;
+    prefabStateInfo: IPrefabStateInfo;
+    targetOverrides?: ITargetOverrideInfoForEditor[];
+    instance?: IProperty;
+}
+
 export declare interface IPrefabInfo {
     /** 关联的预制体资源信息 */
     asset?: IPrefab;
@@ -1348,6 +1497,11 @@ export declare interface IRemoveComponentOptions {
     path: string;
 }
 
+export declare interface IRemovedComponentInfo {
+    name: string;
+    fileID: string;
+}
+
 export declare interface IRevertToPrefabParams {
     nodePath: string;
 }
@@ -1369,6 +1523,20 @@ export declare interface IScene extends IBaseIdentifier {
     components: IComponentIdentifier[];
 }
 
+export declare interface ISceneForEditor {
+    name: IProperty;
+    active: IProperty;
+    locked: IProperty;
+    _globals: Record<string, IProperty>;
+    isScene: boolean;
+    autoReleaseAssets: IProperty;
+    uuid: IProperty;
+    children: IProperty[];
+    parent: string;
+    __type__: string;
+    targetOverrides?: ITargetOverrideInfoForEditor[];
+}
+
 export declare interface ISceneMouseEvent {
     x: number;
     y: number;
@@ -1447,10 +1615,9 @@ export declare interface IServiceEvents {
     onSetPropertyComponent?(comp: Component): void;
     onComponentAdded?(comp: Component): void;
     onComponentRemoved?(comp: Component): void;
+    onBeforeChangeComponent?(node: Node_2): void;
+    onBeforeAddComponent?(name: string, node: Node_2): void;
     onBeforeRemoveComponent?(comp: Component): void;
-    onComponentBeforeChanged?(node: Node_2): void;
-    onBeforeComponentAdded?(name: string, node: Node_2): void;
-    onComponentChanged?(name: string, opts: IChangeNodeOptions): void;
     onAssetDeleted?(uuid: string): void;
     onAssetChanged?(uuid: string): void;
     onAssetRefreshed?(uuid: string): void;
@@ -1491,7 +1658,7 @@ export declare interface ISetPropertyOptions {
  * 编辑器设置组件属性的选项
  */
 export declare interface ISetPropertyOptionsForEditor {
-    uuid: string;
+    nodePath: string;
     path: string;
     dump: IProperty;
     record?: boolean;
@@ -1529,6 +1696,14 @@ export declare interface ITargetOverrideInfo {
     targetInfo: ITargetInfo | null;
 }
 
+export declare interface ITargetOverrideInfoForEditor {
+    source: string;
+    sourceInfo?: string[];
+    propertyPath: string[];
+    target: string;
+    targetInfo?: string[];
+}
+
 export declare interface IUndoService {
     beginRecording(uuids: string[], options?: any): string;
     endRecording(commandId: string): void;

package/index.d.ts

@@ -975,7 +975,7 @@ export declare namespace i18n {
  * 添加/创建组件的选项
  */
 export declare interface IAddComponentOptions {
-    nodePathOrUuid: string;
+    nodePath: string;
     component: string;
 }
 
@@ -1274,31 +1274,31 @@ export declare interface IComponentService extends IServiceEvents {
     /**
      * 添加组件到指定节点，返回添加后的组件信息
      * @param params - 添加组件选项
-     * @param params.nodePathOrUuid - 目标节点路径或 UUID
+     * @param params.nodePath - 目标节点路径
      * @param params.component - 组件类名，支持精确匹配（'cc.Label'）和模糊匹配（'label'）
      * @returns 添加成功后的组件信息
      *
      * @example
      * ```ts
      * // 通过节点路径 + 精确组件名
-     * const comp = await addComponent({ nodePathOrUuid: 'Canvas/MyNode', component: 'cc.Label' });
+     * const comp = await add({ nodePath: 'Canvas/MyNode', component: 'cc.Label' });
      *
-     * // 通过节点 UUID + 模糊组件名
-     * const comp = await addComponent({ nodePathOrUuid: 'abc-123-uuid', component: 'label' });
+     * // 通过节点路径 + 模糊组件名
+     * const comp = await add({ nodePath: 'Canvas/MyNode', component: 'label' });
      * ```
      */
-    addComponent(params: IAddComponentOptions): Promise<IComponent>;
+    add(params: IAddComponentOptions): Promise<IComponent>;
     /**
      * 删除指定组件
      * @param params - 删除组件选项
-     * @param params.path - 组件路径，支持路径、UUID 或资源 URL
+     * @param params.path - 组件路径
      * @returns 删除成功返回 true，失败返回 false
      */
-    removeComponent(params: IRemoveComponentOptions): Promise<boolean>;
+    remove(params: IRemoveComponentOptions): Promise<boolean>;
     /**
      * 设置组件属性
      * - CLI 调用时传入 ISetPropertyOptions，通过 componentPath 定位，属性为扁平键值对
-     * - 编辑器调用时传入 ISetPropertyOptionsForEditor，通过节点 UUID + dump 路径定位，属性为 IProperty 格式
+     * - 编辑器调用时传入 ISetPropertyOptionsForEditor，通过节点路径 + dump 路径定位，属性为 IProperty 格式
      *
      * @param params - 设置属性选项，根据调用方不同传入不同类型
      * @returns 设置成功返回 true，失败返回 false
@@ -1311,9 +1311,9 @@ export declare interface IComponentService extends IServiceEvents {
      *     properties: { string: 'Hello', fontSize: 32 },
      * });
      *
-     * // 编辑器方式：通过节点 UUID + dump 路径定位，传 IProperty 格式
+     * // 编辑器方式：通过节点路径 + dump 路径定位，传 IProperty 格式
      * await setProperty({
-     *     uuid: 'node-uuid',
+     *     nodePath: 'Canvas/MyNode',
      *     path: '__comps__.0.string',
      *     dump: { value: 'Hello', type: 'String' },
      * });
@@ -1331,33 +1331,33 @@ export declare interface IComponentService extends IServiceEvents {
      * @example
      * ```ts
      * CLI 模式：返回 IComponent（扁平属性）
-     * const comp = await queryComponent({ path: 'Canvas/cc.Label_1' }) as IComponent;
+     * const comp = await query({ path: 'Canvas/cc.Label_1' }) as IComponent;
      *
      * 编辑器模式：直接传 string，这里是uuid，因为与cli重复了，也支持 path 和 url
-     * const comp = await queryComponent('uuid') as IComponentForEditor;
+     * const comp = await query('uuid') as IComponentForEditor;
      * ```
      */
-    queryComponent(params: IQueryComponentOptions | string): Promise<IComponent | IComponentForEditor | null>;
+    query(params: IQueryComponentOptions | string): Promise<IComponent | IComponentForEditor | null>;
     /**
      * 获取所有已注册的组件类名，包含内置与自定义组件
      * @returns 组件类名数组，如 ['cc.Label', 'cc.Sprite', 'MyCustomComponent']
      */
-    queryAllComponent(): Promise<string[]>;
+    queryAll(): Promise<string[]>;
     /**
-     * 创建组件（编辑器使用），与 addComponent 不同的是仅返回是否成功
+     * 创建组件（编辑器使用），与 add 不同的是仅返回是否成功
      * @param params - 添加组件选项
-     * @param params.nodePathOrUuid - 目标节点路径或 UUID
+     * @param params.nodePath - 目标节点路径
      * @param params.component - 组件类名
      * @returns 创建成功返回 true，失败返回 false
      */
-    createComponent(params: IAddComponentOptions): Promise<boolean>;
+    create(params: IAddComponentOptions): Promise<boolean>;
     /**
      * 复位组件，将组件所有属性恢复为默认值
      * @param params - 查询组件选项，用于定位要复位的组件
-     * @param params.path - 组件路径，支持路径、UUID 或资源 URL
+     * @param params.path - 组件路径
      * @returns 复位成功返回 true，失败返回 false
      */
-    resetComponent(params: IQueryComponentOptions): Promise<boolean>;
+    reset(params: IQueryComponentOptions): Promise<boolean>;
     /**
      * 获取所有注册类名，支持按继承关系过滤
      * @param options - 过滤选项，不传则返回所有注册类
@@ -1382,25 +1382,25 @@ export declare interface IComponentService extends IServiceEvents {
     }[]>;
     /**
      * 查询指定节点上所有组件暴露的可调用函数
-     * @param uuid - 节点 UUID
+     * @param path - 节点路径
      * @returns 节点上组件的函数信息，节点不存在时返回空对象
      */
-    queryComponentFunctionOfNode(uuid: string): Promise<any>;
+    queryFunctionOfNode(path: string): Promise<any>;
     /**
      * 执行组件上的指定方法
      * @param options - 执行选项
-     * @param options.uuid - 组件实例的 UUID
+     * @param options.path - 组件路径，如 'Canvas/cc.Label_1'
      * @param options.name - 要执行的方法名，如 'onLoad'、'start'
      * @param options.args - 方法参数列表
      * @returns 执行成功返回 true，失败返回 false
      */
-    executeComponentMethod(options: IExecuteComponentMethodOptions): Promise<boolean>;
+    executeMethod(options: IExecuteComponentMethodOptions): Promise<any>;
     /**
      * 查询指定名称的组件是否已注册（是否存在对应脚本）
      * @param name - 组件类名，如 'cc.Label'
      * @returns 存在返回 true，不存在返回 false
      */
-    queryComponentHasScript(name: string): Promise<boolean>;
+    hasScript(name: string): Promise<boolean>;
     init(): void;
     unregisterCompMgrEvents(): void;
 }
@@ -1638,7 +1638,7 @@ export declare interface IEngineService extends IServiceEvents {
  * 执行组件方法的选项
  */
 export declare interface IExecuteComponentMethodOptions {
-    uuid: string;
+    path: string;
     name: string;
     args: any[];
 }
@@ -1892,6 +1892,31 @@ export declare interface INode extends INodeIdentifier {
     prefab: IPrefabInfo | null;
 }
 
+export declare interface INodeForEditor {
+    active: IProperty;
+    locked: IProperty;
+    name: IProperty;
+    position: IProperty;
+    /**
+     * 此为 dump 数据，非 node.rotation
+     * 实际指向 node.eulerAngles
+     * rotation 为了给用户更友好的文案
+     */
+    rotation: IProperty;
+    mobility: IProperty;
+    scale: IProperty;
+    layer: IProperty;
+    uuid: IProperty;
+    children: IProperty[];
+    parent: IProperty;
+    __comps__: IProperty[];
+    __type__: string;
+    __prefab__?: IPrefabForEditor;
+    _prefabInstance?: any;
+    removedComponents?: IRemovedComponentInfo[];
+    mountedRoot?: string;
+}
+
 export declare interface INodeIdentifier {
     nodeId: string;
     path: string;
@@ -1916,30 +1941,144 @@ export declare interface INodeService extends IServiceEvents {
      * 创建节点
      * @param params
      */
-    createNodeByType(params: ICreateByNodeTypeParams): Promise<INode | null>;
+    createByType(params: ICreateByNodeTypeParams): Promise<INode | null>;
     /**
      * 创建节点
      * @param params
      */
-    createNodeByAsset(params: ICreateByAssetParams): Promise<INode | null>;
+    createByAsset(params: ICreateByAssetParams): Promise<INode | null>;
     /**
      * 删除节点
      * @param params
      */
-    deleteNode(params: IDeleteNodeParams): Promise<IDeleteNodeResult | null>;
+    delete(params: IDeleteNodeParams): Promise<IDeleteNodeResult | null>;
     /**
      * 更新节点
      * @param params
      */
-    updateNode(params: IUpdateNodeParams): Promise<IUpdateNodeResult>;
+    update(params: IUpdateNodeParams): Promise<IUpdateNodeResult>;
     /**
-     * 查询节点
+     * 查询节点信息
+     * - 不传参数时，返回当前场景的 dump 数据（ISceneForEditor）
+     * - 传入 string 时，返回指定路径节点的 dump 数据（编辑器模式，返回 INodeForEditor 数据）
+     * - 传入 IQueryNodeParams 时，返回 INode（CLI 模式）
+     *
+     * @param params - 查询选项、节点路径字符串或不传
+     * @returns 如果传入 IQueryNodeParams 返回 INode，如果传入 string 或不传返回 INodeForEditor 或 ISceneForEditor，未找到返回 null
      */
-    queryNode(params: IQueryNodeParams): Promise<INode | null>;
+    query(params?: IQueryNodeParams | string): Promise<INode | INodeForEditor | ISceneForEditor | null>;
     /**
      * 查询节点树（层级管理器格式）
      */
     queryNodeTree(params: IQueryNodeTreeParams): Promise<INodeTreeItem | null>;
+    /**
+     * 预览设置节点属性，临时应用属性变更但不记录到 undo 栈
+     * 用于编辑器中拖拽滑块等实时预览场景，首次调用时会缓存原始值，
+     * 可通过 cancelPreviewSetProperty 恢复
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.path - 属性路径，如 'position'、'scale'
+     * @param options.dump - 属性的 dump 数据
+     * @returns 设置成功返回 true，节点或属性路径无效返回 false
+     *
+     * @example
+     * ```ts
+     * // 预览修改节点位置
+     * await previewSetProperty({
+     *     nodePath: 'Canvas/MyNode',
+     *     path: 'position',
+     *     dump: { value: { x: 100, y: 200, z: 0 }, type: 'cc.Vec3' },
+     * });
+     * ```
+     */
+    previewSetProperty(options: ISetPropertyOptionsForEditor): Promise<boolean>;
+    /**
+     * 取消预览设置，将节点属性恢复到 previewSetProperty 调用前的值
+     * 仅使用 options.nodePath 和 options.path，options.dump 不会被使用
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.path - 属性路径
+     * @returns 恢复成功返回 true，无缓存的预览数据或节点无效返回 false
+     */
+    cancelPreviewSetProperty(options: ISetPropertyOptionsForEditor): Promise<boolean>;
+    /**
+     * 设置节点属性，会记录到 undo 栈
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.path - 属性路径，如 'position'、'rotation'、'layer'
+     * @param options.dump - 属性的 dump 数据
+     * @returns 设置成功返回 true，节点不存在返回 false
+     *
+     * @example
+     * ```ts
+     * await setProperty({
+     *     nodePath: 'Canvas/MyNode',
+     *     path: 'position',
+     *     dump: { value: { x: 100, y: 200, z: 0 }, type: 'cc.Vec3' },
+     * });
+     * ```
+     */
+    setProperty(options: ISetPropertyOptionsForEditor): Promise<boolean>;
+    /**
+     * 重置节点的变换属性（position、rotation、scale、mobility）到默认值
+     *
+     * @param path - 节点路径
+     * @returns 重置成功返回 true，节点不存在返回 false
+     */
+    reset(path: string): Promise<boolean>;
+    /**
+     * 重置节点的单个属性到 CCClass 定义的默认值
+     * 仅使用 options.nodePath 和 options.path，options.dump 不会被使用
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.path - 属性路径，如 'position'、'scale'
+     * @returns 重置成功返回 true，节点不存在返回 false
+     */
+    resetProperty(options: ISetPropertyOptionsForEditor): Promise<boolean>;
+    /**
+     * 将节点上值为 null 的属性初始化为默认实例
+     * 当属性为 null 且有定义构造函数类型时，会创建该类型的新实例
+     * 仅使用 options.nodePath 和 options.path，options.dump 不会被使用
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.path - 属性路径
+     * @returns 初始化成功返回 true，节点不存在返回 false
+     *
+     * @example
+     * ```ts
+     * // 将节点上值为 null 的自定义属性初始化
+     * await updatePropertyFromNull({
+     *     nodePath: 'Canvas/MyNode',
+     *     path: 'customProperty',
+     *     dump: {} as IProperty,
+     * });
+     * ```
+     */
+    updatePropertyFromNull(options: ISetPropertyOptionsForEditor): Promise<boolean>;
+    /**
+     * 设置节点及其所有子节点的 layer 属性
+     * 递归将相同的 layer 值应用到整个节点子树
+     * 仅使用 options.nodePath 和 options.dump，options.path 不会被使用（内部固定为 'layer'）
+     *
+     * @param options - 设置属性选项
+     * @param options.nodePath - 节点路径
+     * @param options.dump - layer 属性的 dump 数据
+     *
+     * @example
+     * ```ts
+     * await setNodeAndChildrenLayer({
+     *     nodePath: 'Canvas/MyNode',
+     *     path: 'layer',
+     *     dump: { value: 1 << 25, type: 'Enum' },
+     * });
+     * ```
+     */
+    setNodeAndChildrenLayer(options: ISetPropertyOptionsForEditor): Promise<void>;
 }
 
 export declare interface INodeTreeComponent {
@@ -2020,6 +2159,16 @@ export declare interface IPrefab {
     persistent: boolean;
 }
 
+export declare interface IPrefabForEditor {
+    uuid: string;
+    fileId: string;
+    rootUuid: string;
+    sync: boolean;
+    prefabStateInfo: IPrefabStateInfo;
+    targetOverrides?: ITargetOverrideInfoForEditor[];
+    instance?: IProperty;
+}
+
 export declare interface IPrefabInfo {
     /** 关联的预制体资源信息 */
     asset?: IPrefab;
@@ -2286,6 +2435,11 @@ export declare interface IRemoveComponentOptions {
     path: string;
 }
 
+export declare interface IRemovedComponentInfo {
+    name: string;
+    fileID: string;
+}
+
 export declare interface IRevertToPrefabParams {
     nodePath: string;
 }
@@ -2307,6 +2461,20 @@ export declare interface IScene extends IBaseIdentifier {
     components: IComponentIdentifier[];
 }
 
+export declare interface ISceneForEditor {
+    name: IProperty;
+    active: IProperty;
+    locked: IProperty;
+    _globals: Record<string, IProperty>;
+    isScene: boolean;
+    autoReleaseAssets: IProperty;
+    uuid: IProperty;
+    children: IProperty[];
+    parent: string;
+    __type__: string;
+    targetOverrides?: ITargetOverrideInfoForEditor[];
+}
+
 export declare interface ISceneMouseEvent {
     x: number;
     y: number;
@@ -2385,10 +2553,9 @@ export declare interface IServiceEvents {
     onSetPropertyComponent?(comp: Component): void;
     onComponentAdded?(comp: Component): void;
     onComponentRemoved?(comp: Component): void;
+    onBeforeChangeComponent?(node: Node_2): void;
+    onBeforeAddComponent?(name: string, node: Node_2): void;
     onBeforeRemoveComponent?(comp: Component): void;
-    onComponentBeforeChanged?(node: Node_2): void;
-    onBeforeComponentAdded?(name: string, node: Node_2): void;
-    onComponentChanged?(name: string, opts: IChangeNodeOptions): void;
     onAssetDeleted?(uuid: string): void;
     onAssetChanged?(uuid: string): void;
     onAssetRefreshed?(uuid: string): void;
@@ -2429,7 +2596,7 @@ export declare interface ISetPropertyOptions {
  * 编辑器设置组件属性的选项
  */
 export declare interface ISetPropertyOptionsForEditor {
-    uuid: string;
+    nodePath: string;
     path: string;
     dump: IProperty;
     record?: boolean;
@@ -2503,6 +2670,14 @@ export declare interface ITargetOverrideInfo {
     targetInfo: ITargetInfo | null;
 }
 
+export declare interface ITargetOverrideInfoForEditor {
+    source: string;
+    sourceInfo?: string[];
+    propertyPath: string[];
+    target: string;
+    targetInfo?: string[];
+}
+
 export declare interface IUerDataConfigItem {
     key?: string; // 唯一标识符
     // 配置显示的名字，如果需要翻译，则传入 i18n:${key}

package/package.json

@@ -2,7 +2,7 @@
     "name": "@cocos/cocos-cli-types",
     "description": "types for cocos cli",
     "author": "cocos cli",
-    "version": "0.0.1-alpha.24.1",
+    "version": "0.0.1-alpha.24.2",
     "main": "index.d.ts",
     "types": "index.d.ts",
     "exports": {