@cocos/pink-types 0.0.0-bootstrap.0 → 0.0.12-beta.1

package/pink.d.ts

@@ -0,0 +1,1509 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) SUD. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+/*---------------------------------------------------------------------------------------------
+ *  AUTO-GENERATED by build/lib/pink-dts-generator.ts — DO NOT EDIT
+ *  Regenerate with: npx gulp generate-pink-dts
+ *--------------------------------------------------------------------------------------------*/
+
+/// <reference path="./pink.vscode.d.ts" />
+
+declare module 'pink' {
+	/** @internal */
+	namespace _cli {
+	// ── Inlined from @cocos/cocos-cli-types/engine ──
+
+	export interface ModuleRenderConfig {
+	    $schema?: string;
+	
+	    /**
+	     * The modules info
+	     */
+	    features: Features;
+	
+	    /**
+	     * The categories info
+	     */
+	    categories: { [category: string]: CategoryInfo };
+	
+	    version: string;
+	
+	    /**
+	     * The script to migrate, this script should export a const migrations: Migration[]`.
+	     */
+	    migrationScript?: string;
+	}
+
+	export interface CategoryInfo {
+	    label?: string;
+	    description?: string;
+	    checkable?: boolean;
+	    required?: boolean;
+	}
+
+	export interface Features {
+	    [feature: string]: IModuleItem;
+	}
+
+	export type IModuleItem = IFeatureItem | IFeatureGroup;
+
+	export interface IFeatureGroup extends BaseItem {
+	    options: { [feature: string]: IFeatureItem };
+	}
+
+	export interface IFeatureItem extends BaseItem {
+	    /**
+	     * @zh 是否默认以及允许包含在上传的各个小游戏引擎插件内，目前由于部分引擎模块包体较大，默认不会打包在官方的微信引擎分离插件内。（临时方案）
+	     * @en Whether it is included in the upload of the various engine plugins by default. Currently, because some engine modules are packaged in a large package, the official WeChat engine separation plugin does not package them by default. (Temporary solution)
+	     */
+	    enginePlugin?: boolean;
+	
+	    /**
+	     * @zh 限定的使用环境，允许宏的组合条件判断，默认为空支持任意环境，配置后限定为指定环境。如设置为 "$NATIVE || $HTML5" 则仅在 native 和 html5 环境下生效。
+	     * @en The restricted usage environment allows for conditional judgments using macro combinations. By default, it supports any environment, but once configured, it is limited to the specified environment. For example, if set to "$NATIVE || $HTML5", it will only take effect in native and HTML5 environments.
+	     */
+	    envCondition?: string;
+	
+	    /**
+	     * @zh 当环境不符合限定的使用环境时，自动回退的模块名称。仅当 `envCondition` 配置后才有效。
+	     * @en The name of the engine feature to automatically fall back to when the environment does not meet the restricted usage conditions. This is only effective when `envCondition` is configured.
+	     */
+	    fallback?: string;
+	
+	    /**
+	     * @zh 当选择了某个模块时，可以做些附加的配置
+	     * @en When a module is selected, additional configurations can be made
+	     */
+	    flags: { [k: string]: Pick<BaseItem, 'default' | 'label' | 'description'> & { 'ui-type': 'checkbox' | 'select' } }
+	
+	    /**
+	     * @zh 是否为原生模块，这部分模块的编译模式可能是 wasm 也可能是共存或只有 asmjs，为 true 的模块，如果模块勾选构建面板上才会显示原生代码打包模式的配置。
+	     * @en Whether it is a native module. This part of the module may be compiled as wasm or asmjs, and the module with this attribute will be displayed in the packaging mode configuration in the build panel if it is selected.
+	     */
+	    isNativeModule?: boolean;
+	
+	    /**
+	     * @zh 在原生引擎的模块宏配置，如果在原生端有原生实现，在此处补充对应字段，后续根据项目设置的配置情况，会将选择值设置到 `cmake` 配置内。
+	     * @en The macro configuration of the native module in the native engine. If there is a native implementation in the native engine, please fill in the corresponding fields here. The value will be set to `cmake` configuration according to the project settings.
+	     */
+	    cmakeConfig?: string;
+	}
+
+	export interface BaseItem {
+	    /**
+	     * @zh 在项目设置上显示的模块名称，支持 i18n 格式
+	     * @en the module name displayed on the project settings, can be configured in i18n format.
+	     */
+	    label?: string;
+	
+	    /**
+	     * @zh 模块详细描述，将会显示在模块鼠标上移后的提示，支持 `i18n` 的格式
+	     * @en the detailed description of the module, which will be displayed in the tooltip when the mouse is moved over the module, can be configured in i18n format.
+	     */
+	    description?: string;
+	
+	    /**
+	     * @zh 是否默认包含该模块
+	     * @en whether the module is included by default.
+	     */
+	    default: boolean;
+	
+	    /**
+	     * @zh 标识是否为只读模块，设为 `true` 后用户无法开启或关闭该模块。
+	     * @en whether the module is read-only. If set to true, users cannot modify this module.
+	     */
+	    readonly?: boolean;
+	
+	    /**
+	     * @zh 是否在项目设置上隐藏该模块，设为 `true` 后将不会显示在项目设置中。
+	     * @en Whether to hide the module in the project settings. If set to true, it will not be displayed in the project settings.
+	     */
+	    hidden?: boolean;
+	
+	    /**
+	     * @zh 默认的模块分组归属，对应 `features` 字段同级的 `categories` 中配置的目录。
+	     * @en The default module group belongs to, corresponding to the directory configured under the `categories` field at the same level of the `features` field.
+	     */
+	    category?: string;
+	
+	    /**
+	     * @zh 是否为必选模块，新增模块为必选模块时，旧版本升级后会强制选择此模块，否则不会选择。
+	     * @en Whether it is a required module. When adding a new module, the old version will be forced to select this module after the upgrade, otherwise it will not be selected.
+	     */
+	    required?: boolean;
+	
+	    /**
+	     * @zh 该模块依赖的其他模块，如果依赖了其他模块，则此模块勾选后，依赖模块也会被自动勾选。反过来，依赖的模块被移除勾选，此模块也会被一并移除。
+	     * @en The other modules that this module depends on. If the module depends on other modules, the dependent modules will be automatically selected. In addition, if the dependent module is removed, this module will also be removed.
+	     */
+	    dependencies?: string[];
+	}
+
+	export interface IEngineConfig extends IEngineModuleConfig {
+	    physicsConfig: IPhysicsConfig;
+	    macroConfig?: Record<string, string | number | boolean>;
+	    graphics?: IEngineGraphicsConfig;
+	    sortingLayers: { id: number, name: string, value: number }[];
+	    customLayers: { name: string, value: number }[];
+	    renderPipeline?: string;
+	    // 是否使用自定义管线，如与其他模块配置不匹配将会以当前选项为准
+	    customPipeline?: boolean;
+	    highQuality: boolean;
+	
+	    macroCustom: MacroItem[];
+	
+	    customJointTextureLayouts: ICustomJointTextureLayout[];
+	    designResolution: IDesignResolution;
+	    splashScreen: ISplashSetting;
+	    downloadMaxConcurrency: number;
+	}
+
+	export interface ISplashSetting {
+	    displayRatio: number;
+	    totalTime: number;
+	    watermarkLocation: 'default' | 'topLeft' | 'topRight' | 'topCenter' | 'bottomLeft' | 'bottomCenter' | 'bottomRight';
+	    autoFit: boolean;
+	
+	    logo?: {
+	        type: 'default' | 'none' | 'custom';
+	        image?: string;
+	        base64?: string;
+	    }
+	    background?: {
+	        type: 'default' | 'color' | 'custom';
+	        color?: ISplashBackgroundColor;
+	        image?: string;
+	        base64?: string;
+	    }
+	}
+
+	export interface ISplashBackgroundColor {
+	    x: number;
+	    y: number;
+	    z: number;
+	    w: number;
+	}
+
+	/**
+	 * 构建使用的设计分辨率数据
+	 */
+	export interface IDesignResolution {
+	    height: number;
+	    width: number;
+	    fitWidth?: boolean;
+	    fitHeight?: boolean;
+	    policy?: number;
+	}
+
+	export interface ICustomJointTextureLayout {
+	    textureLength: number;
+	    contents: IChunkContent[];
+	}
+
+	export interface IChunkContent {
+	    skeleton: null | string;
+	    clips: string[];
+	}
+
+	export type MacroItem = {
+	    key: string;
+	    value: boolean;
+	}
+
+	export interface IEngineGraphicsConfig {
+	    pipeline?: IEngineGraphicsPipeline;
+	    'custom-pipeline-post-process'?: boolean;
+	}
+
+	export type IEngineGraphicsPipeline = 'custom-pipeline' | 'legacy-pipeline';
+
+	export interface IPhysicsConfig {
+	    gravity: IVec3Like; // （0，-10， 0）
+	    allowSleep: boolean; // true
+	    sleepThreshold: number; // 0.1，最小 0
+	    autoSimulation: boolean; // true
+	    fixedTimeStep: number; // 1 / 60 ，最小 0
+	    maxSubSteps: number; // 1，最小 0
+	    defaultMaterial?: string; // 物理材质 uuid
+	    useNodeChains: boolean; // true
+	    collisionMatrix: ICollisionMatrix;
+	    physicsEngine: string;
+	    physX?: {
+	        notPackPhysXLibs: boolean;
+	        multiThread: boolean;
+	        subThreadCount: number;
+	        epsilon: number;
+	    };
+	}
+
+	export interface ICollisionMatrix {
+	    [x: string]: number;
+	}
+
+	export interface IVec3Like {
+	    x: number;
+	    y: number;
+	    z: number;
+	}
+
+	export interface IEngineModuleConfig {
+	    // ---- 模块配置相关 ----
+	    includeModules: string[];
+	    flags?: IFlags;
+	    noDeprecatedFeatures?: { value: boolean, version: string };
+	}
+
+	export type IFlags = Record<string, boolean | number>;
+
+	export interface EngineInfo {
+	    typescript: {
+	        type: 'builtin' | 'custom'; // 当前使用的引擎类型（内置或自定义)
+	        builtin: string, // 内置引擎地址
+	        path: string; // 当前使用的 ts 引擎路径
+	    },
+	    native: {
+	        type: 'builtin' | 'custom'; // 当前使用的引擎类型（内置或自定义)
+	        builtin: string, // 内置引擎地址
+	        path: string; // 当前使用的原生引擎路径
+	    },
+	    tmpDir: string;
+	    version: string;
+	}
+
+	// ── Inlined from @cocos/cocos-cli-types/assets ──
+
+	export interface IAssetInfo {
+	    name: string; // 资源名字
+	    source: string; // url 地址
+	    loadUrl: string; // loader 加载的层级地址
+	    url: string; // loader 加载地址会去掉扩展名，这个参数不去掉
+	    file: string; // 绝对路径
+	    uuid: string; // 资源的唯一 ID
+	    importer: AssetHandlerType; // 使用的导入器名字
+	    imported: boolean; // 是否结束导入过程
+	    invalid: boolean; // 是否导入成功
+	    type: IAssetType; // 类型
+	    isDirectory: boolean; // 是否是文件夹
+	    library: { [key: string]: string }; // 导入资源的 map
+	
+	    // dataKeys 作用范围
+	    isBundle?: boolean; // 是否是文件夹
+	    displayName?: string; // 资源用于显示的名字
+	    readonly?: boolean; // 是否只读
+	    visible?: boolean; // 是否显示
+	    subAssets?: { [key: string]: IAssetInfo }; // 子资源 map
+	    // 虚拟资源可以实例化成实体的话，会带上这个扩展名
+	    instantiation?: string;
+	    redirect?: IRedirectInfo; // 跳转指向资源
+	    meta?: IAssetMeta,
+	    parent?: {
+	        source: string;
+	        library: { [key: string]: string };
+	        uuid: string;
+	    };
+	    extends?: string[]; // 资源的继承链信息
+	    mtime?: number; // 资源文件的 mtime
+	    depends?: string[]; // 依赖的资源 uuid 信息
+	    dependeds?: string[]; // 被依赖的资源 uuid 信息
+	    temp?: string; // 资源临时文件目录
+	}
+
+	export interface IAssetMeta<T extends ISupportCreateType | 'unknown' = 'unknown'> {
+	    ver: string;
+	    importer: AssetHandlerType;
+	    imported: boolean;
+	    uuid: string;
+	    files: string[];
+	    subMetas: {
+	        [index: string]: IAssetMeta<'unknown'>;
+	    };
+	    userData: AssetUserDataMap[T extends keyof AssetUserDataMap ? T : 'unknown'];
+	    displayName?: string;
+	    id?: string;
+	    name?: string;
+	}
+
+	export interface AssetUserDataMap {
+	    'animation-clip': AnimationClipAssetUserData;
+	    'auto-atlas': AutoAtlasAssetUserData;
+	    'label-atlas': LabelAtlasAssetUserData;
+	    'render-texture': RenderTextureAssetUserData;
+	    'directory': DirectoryAssetUserData;
+	    'texture-cube': TextureCubeAssetUserData;
+	    'erp-texture-cube': TextureCubeAssetUserData;
+	    'image': ImageAssetUserData;
+	    'sprite-frame': SpriteFrameAssetUserData;
+	    'texture': Texture2DAssetUserData;
+	    'spine-data': SpineAssetUserData;
+	    'javascript': JavaScriptAssetUserData;
+	    'gltf-animation': GltfAnimationAssetUserData;
+	    'particle': ParticleAssetUserData;
+	    'json': JsonAssetUserData;
+	    'prefab': PrefabAssetUserData;
+	    'scene': PrefabAssetUserData;
+	    'effect': EffectAssetUserData;
+	    'audio-clip': AudioClipAssetUserData;
+	    'bitmap-font': BitmapFontAssetUserData;
+	    'gltf-skeleton': GltfSkeletonAssetUserData;
+	    'gltf-embeded-image': GltfEmbededImageAssetUserData;
+	    'gltf-mesh': IVirtualAssetUserData;
+	    'gltf-material': IVirtualAssetUserData;
+	    'gltf-scene': IVirtualAssetUserData;
+	    'gltf': GlTFUserData;
+	    'fbx': GlTFUserData;
+	    'sprite-atlas': SpriteAtlasAssetUserData;
+	    'rt-sprite-frame': RtSpriteFrameAssetUserData;
+	    'sign-image': ImageAssetUserData;
+	    'alpha-image': ImageAssetUserData;
+	
+	    // 无特定 userData 的资源类型（仅保留 unknown）
+	    'unknown': any;
+	}
+
+	/** 渲染纹理精灵帧的 userData */
+	export interface RtSpriteFrameAssetUserData {
+	    /** 图片 UUID 或数据库 URI */
+	    imageUuidOrDatabaseUri: string;
+	    /** 宽度 */
+	    width?: number;
+	    /** 高度 */
+	    height?: number;
+	}
+
+	/** 精灵图集资源的 userData */
+	export interface SpriteAtlasAssetUserData {
+	    /** 图集纹理名称 */
+	    atlasTextureName: string;
+	    /** 纹理 UUID */
+	    textureUuid: string | null;
+	    /** 精灵帧列表 */
+	    frames: SpriteFrameAssetUserData[];
+	    /** 资源 UUID */
+	    uuid: string;
+	    /** 格式版本 */
+	    format: number;
+	}
+
+	export interface SpriteFrameAssetUserData extends SpriteFrameBaseAssetUserData {
+	    isUuid?: boolean;
+	    imageUuidOrDatabaseUri: string;
+	}
+
+	export interface SpriteFrameBaseAssetUserData {
+	    trimType?: string;
+	    trimThreshold: number;
+	    rotated: boolean;
+	    offsetX: number;
+	    offsetY: number;
+	    trimX: number;
+	    trimY: number;
+	    width: number;
+	    height: number;
+	    rawWidth: number;
+	    rawHeight: number;
+	    borderTop: number;
+	    borderBottom: number;
+	    borderLeft: number;
+	    borderRight: number;
+	    packable?: boolean;
+	    pixelsToUnit: number;
+	    pivotX: number;
+	    pivotY: number;
+	    meshType: number;
+	    vertices: SpriteFrameVertices;
+	}
+
+	export interface SpriteFrameVertices {
+	    rawPosition: number[];
+	    indexes: number[];
+	    uv: number[];
+	    nuv: number[];
+	    triangles?: number[];
+	    minPos: number[];
+	    maxPos: number[];
+	}
+
+	export interface GlTFUserData {
+	    assetFinder?: SerializedAssetFinder;
+	
+	    imageMetas: ImageMeta[];
+	
+	    // Normal import settings
+	    // @default required
+	    normals?: NormalImportSetting;
+	
+	    // Tangent import settings;
+	    // @default required
+	    tangents?: TangentImportSetting;
+	
+	    /**
+	     * Controls how to import morph normals.
+	     * @default Exclude.
+	     */
+	    morphNormals?: NormalImportSetting.exclude | NormalImportSetting.optional;
+	
+	    // Whether to extract material assets out of embedded (sub)assets,
+	    // so that the assets become editable.
+	    // @default false
+	    dumpMaterials?: boolean;
+	
+	    // only for chat avatar
+	    redirectMaterialMap?: Record<string, string>;
+	
+	    // The directory to dump the materials.
+	    // Default to a direct sub-folder prefixed with 'Materials_' under current path.
+	    materialDumpDir?: string;
+	
+	    /**
+	     * Whether to use vertex colors(if valid) in material.
+	     * @default false
+	     */
+	    useVertexColors?: boolean;
+	
+	    /**
+	     * Whether to enable depth-write if the material specify the `BLEND` mode.
+	     * See https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#alpha-coverage
+	     * @default false
+	     */
+	    depthWriteInAlphaModeBlend?: boolean;
+	
+	    // @default true
+	    skipValidation?: boolean;
+	
+	    /**
+	     * 整个数组由导入器创建。`name` 和 `duration` 也都由导入器写入修改，外部不允许修改。
+	     * `splits` 是允许用户配置的。
+	     */
+	    animationImportSettings?: AnimationImportSetting[];
+	
+	    /**
+	     * 是否将所有动画挂载到生成的预制体上。
+	     * @default false
+	     */
+	    mountAllAnimationsOnPrefab?: boolean;
+	
+	    /**
+	     * 使用旧的 FBX 导入器。（在非 FBX 导入器上是 `undefined`）
+	     */
+	    legacyFbxImporter?: boolean;
+	
+	    /**
+	     * 禁用 Mesh 分割，默认勾选
+	     */
+	    disableMeshSplit?: boolean;
+	
+	    /**
+	     * 允许数据访问。
+	     */
+	    allowMeshDataAccess?: boolean;
+	
+	    /**
+	     * 是否添加填充顶点色
+	     * @default false
+	     */
+	    addVertexColor?: boolean;
+	
+	    /**
+	     * 若开启并且模型场景顶部仅有一个节点，那么以该节点作为根节点转换为 Prefab。
+	     * 否则，以场景为根节点转换为 Prefab。见 cocos/cocos-engine#11858 。
+	     */
+	    promoteSingleRootNode?: boolean;
+	    /*
+	    * 若开启则自动生成 Lightmap UV，并将 UV 写入第二个通道（若第二个通道有 UV ， 则该 UV 会被覆盖）
+	    * 否则，使用默认 UV 。
+	    */
+	    generateLightmapUVNode?: boolean;
+	
+	    /**
+	     * 关于 FBX 的配置。仅当 `legacyFbxImporter === false` 时有效。
+	     */
+	    fbx?: IFbxSetting;
+	
+	    /**
+	     * 减面配置
+	     */
+	    meshOptimizer?: MeshOptimizerOption;
+	
+	    /**
+	     * mesh 优化配置
+	     */
+	    meshOptimize?: MeshOptimizeOptions;
+	
+	    /**
+	     * 是否开启 mesh 减面
+	     */
+	    meshSimplify?: MeshSimplifyOptions;
+	
+	    /**
+	     * MeshCluster Options
+	     */
+	    meshCluster?: MeshClusterOptions;
+	
+	    /**
+	     * Mesh compression options
+	     */
+	    meshCompress?: MeshCompressOptions;
+	
+	    lods?: {
+	        // 是否开启 LODS
+	        enable: boolean;
+	        // fbx 是否自带 LOD
+	        hasBuiltinLOD: boolean;
+	        // fbx 各层级 lod 的配置
+	        options: LODsOption[];
+	    };
+	}
+
+	export interface LODsOption {
+	    // 屏占比
+	    screenRatio: number;
+	    // 和 lod0 的减面比
+	    faceCount: number;
+	}
+
+	export interface MeshCompressOptions {
+	    enable: boolean;
+	    encode?: boolean;
+	    compress?: boolean;
+	    quantize?: boolean;
+	}
+
+	export interface MeshClusterOptions {
+	    enable: boolean;
+	    coneCluster?: boolean;
+	}
+
+	export interface MeshSimplifyOptions {
+	    enable: boolean;
+	    targetRatio?: number;
+	    autoErrorRate?: boolean;
+	    errorRate?: number;
+	    lockBoundary?: boolean;
+	}
+
+	export interface MeshOptimizeOptions {
+	    enable: boolean;
+	    vertexCache?: boolean;
+	    vertexFetch?: boolean;
+	    overdraw?: boolean;
+	}
+
+	export interface MeshOptimizerOption {
+	    // 是否启用此功能
+	    enable: boolean;
+	    // 减面算法，默认 simplify
+	    algorithm?: 'gltfpack' | 'simplify';
+	    simplifyOptions?: SimplifyOptions;
+	    // 已废弃，仅做简单记录
+	    gltfpackOptions?: GltfpackOptions;
+	}
+
+	export type GltfpackOptions = Record<string, any>;
+
+	export interface SimplifyOptions {
+	    // 压缩比例
+	    targetRatio?: number;
+	    // 防止破面
+	    enableSmartLink?: boolean;
+	    // 误差距离
+	    agressiveness?: number;
+	    // 计算迭代次数
+	    maxIterationCount?: number;
+	}
+
+	export interface IFbxSetting {
+	    /**
+	     * https://github.com/cocos-creator/FBX-glTF-conv/pull/26
+	     */
+	    unitConversion?: 'geometry-level' | 'hierarchy-level' | 'disabled';
+	
+	    /**
+	     * 动画烘焙速率。单位为 FPS。
+	     * 一般来说有以下几种 FPS 选项。
+	     * - NTSC video 30/60
+	     * - PAL video 25
+	     * - Film 24
+	     * 见 https://knowledge.autodesk.com/support/3ds-max/learn-explore/caas/CloudHelp/cloudhelp/2020/ENU/3DSMax-Reference/files/GUID-92B75FD6-C112-44D6-AB89-DB50D11AE0DE-htm.html 。
+	     * 为了以后的拓展性，我们目前仅支持用户从这几种选项中选择。
+	     * @default 24
+	     */
+	    animationBakeRate?: 0 | 24 | 25 | 30 | 60;
+	
+	    /**
+	     * 在导出动画时，是否优先使用 FBX 内记录的时间范围。
+	     * @default true
+	     */
+	    preferLocalTimeSpan?: boolean;
+	
+	    /**
+	     * 是否为导入的材质匹配DCC的光照模型.
+	     * 在导入时,若此字段为 `undefined` 时,该字段将被初始化为当前配置的"是否开启智能材质转换".
+	     */
+	    smartMaterialEnabled?: boolean;
+	
+	    /**
+	     * 匹配 DCC 原始模型名称。
+	     */
+	    matchMeshNames?: boolean;
+	}
+
+	export interface AnimationImportSetting {
+	    /**
+	     * glTf 中原始动画资源的名称。
+	     */
+	    name: string;
+	
+	    /**
+	     * 原始动画的长度，单位为秒。
+	     */
+	    duration: number;
+	
+	    /**
+	     * 用户查看、切割原始动画时的 FPS 设定。
+	     */
+	    fps: number;
+	
+	    /**
+	     * 对原始动画的划分，由用户配置。
+	     * 若此资源存在，所有划分出的动画成为 glTf 资源下的独立动画并将被导出；
+	     * 否则，直接导入原始动画资源。
+	     */
+	    splits: Array<{
+	        /**
+	         * 以前的 ID。如果存在，优先使用这个 ID 来创建子资源，以防止改名后 UUID 变化。
+	         */
+	        previousId?: string;
+	
+	        /**
+	         * 划分出的动画的名称。
+	         */
+	        name: string;
+	
+	        /**
+	         * 划分的起始时刻，单位为秒。
+	         */
+	        from: number;
+	
+	        /**
+	         * 划分的终止时刻，单位为秒。
+	         */
+	        to: number;
+	
+	        /**
+	         * 用户查看划分出的子动画时的 FPS 设定。
+	         */
+	        fps?: number;
+	
+	        /**
+	         * 速度。
+	         */
+	        speed?: number;
+	
+	        /**
+	         * 动画循环模式。
+	         */
+	        wrapMode?: number;
+	
+	        /**
+	         * 额外的动画辅助曲线信息。
+	         */
+	        auxiliaryCurves?: Record<
+	        string,
+	            {
+	            /**
+	             * 序列化后的曲线。
+	             */
+	            curve: unknown;
+	        }
+	        >;
+	
+	        /**
+	         * 加性动画导入设置。
+	         */
+	        additive?: {
+	            /**
+	             * 是否将动画导入为加性动画。
+	             */
+	            enabled: boolean;
+	
+	            /**
+	             * 参考动画。
+	             * 若设置，将参考该动画第 0 帧的姿势计算加性动画；
+	             * 否则，则将参考第动画本身第 0 帧的姿势进行计算。
+	             */
+	            refClip?: string;
+	        };
+	    }>;
+	}
+
+	export enum TangentImportSetting {
+	    /**
+	     * 不在导出的网格中包含正切信息。
+	     */
+	    exclude = 0,
+	    /**
+	     * 如果模型文件中包含正切信息则导出正切，否则不导出正切。
+	     */
+	    optional = 1,
+	    /**
+	     * 如果模型文件中包含正切信息则导出正切，否则若纹理坐标存在则重新计算并导出正切。
+	     */
+	    require = 2,
+	    /**
+	     * 不管模型文件中是否包含正切信息，直接重新计算并导出正切。
+	     */
+	    recalculate = 3
+	}
+
+	export enum NormalImportSetting {
+	    /**
+	     * 如果模型文件中包含法线信息则导出法线，否则不导出法线。
+	     */
+	    optional = 0,
+	    /**
+	     * 不在导出的网格中包含法线信息。
+	     */
+	    exclude = 1,
+	    /**
+	     * 如果模型文件中包含法线信息则导出法线，否则重新计算并导出法线。
+	     */
+	    require = 2,
+	    /**
+	     * 不管模型文件中是否包含法线信息，直接重新计算并导出法线。
+	     */
+	    recalculate = 3
+	}
+
+	export interface ImageMeta {
+	    /**
+	     * 图片名字。
+	     */
+	    name?: string;
+	
+	    /**
+	     * 模型文件中该图片的 URI，可能是以下形式：
+	     *   - Database URL，这种路径的图片存在项目目录中；
+	     *   - uuid URI，这种路径的图片已经作为子资源导入，路径代表子资源的 uuid。
+	     * 如果未定义，表示此图片未指定源或指定的源无法解析。
+	     */
+	    uri?: string;
+	
+	    /**
+	     * 用户设置的图片对象。
+	     * 3.8.0 以前使用路径，3.8.0 之后使用 UUID。
+	     */
+	    remap?: string;
+	}
+
+	export interface SerializedAssetFinder {
+	    meshes?: Array<string | null>;
+	    animations?: Array<string | null>;
+	    skeletons?: Array<string | null>;
+	    textures?: Array<string | null>;
+	    materials?: Array<string | null>;
+	    scenes?: Array<string | null>;
+	}
+
+	/** glTF 虚拟子资源的通用 userData */
+	export interface IVirtualAssetUserData {
+	    /** 在 glTF 文件中的索引 */
+	    gltfIndex?: number;
+	    /** mesh 资源的面数 */
+	    triangleCount?: number;
+	    /** mesh 所在 lod 层级 */
+	    lodLevel?: number;
+	    /** 根据 lod 配置自动生成 */
+	    lodOptions?: {
+	        /** 自动生成的 mesh 占原 mesh 的百分比 */
+	        faceCount: number;
+	    };
+	    [key: string]: any;
+	}
+
+	/** glTF 嵌入图片子资源的 userData */
+	export interface GltfEmbededImageAssetUserData extends IVirtualAssetUserData {
+	    /** 是否修复 Alpha 透明度瑕疵 */
+	    fixAlphaTransparencyArtifacts?: boolean;
+	}
+
+	/** glTF Skeleton 子资源的 userData */
+	export interface GltfSkeletonAssetUserData extends IVirtualAssetUserData {
+	    /** 骨骼数量 */
+	    jointsLength?: number;
+	}
+
+	/** 位图字体资源的 userData */
+	export interface BitmapFontAssetUserData {
+	    /** 字体配置 */
+	    _fntConfig: any;
+	    /** 字体大小 */
+	    fontSize: number;
+	    /** 纹理 UUID */
+	    textureUuid: string;
+	}
+
+	/** 音频资源的 userData */
+	export interface AudioClipAssetUserData {
+	    /** 下载模式：0-Web Audio, 1-DOM Audio */
+	    downloadMode: number;
+	}
+
+	/** Effect 着色器资源的 userData */
+	export interface EffectAssetUserData {
+	    /** 预编译组合 */
+	    combinations?: any;
+	    /** 编辑器相关数据 */
+	    editor?: any;
+	}
+
+	/** 场景/预制体资源的 userData */
+	export interface PrefabAssetUserData {
+	    /** 是否为持久节点 */
+	    persistent?: boolean;
+	    /** 同步节点名称 */
+	    syncNodeName?: string;
+	}
+
+	/** JSON 资源的 userData */
+	export interface JsonAssetUserData {
+	    /** 是否启用 JSON5 解析 */
+	    json5?: boolean;
+	}
+
+	/** 粒子资源的 userData */
+	export interface ParticleAssetUserData {
+	    totalParticles: number;
+	    life: number;
+	    lifeVar: number;
+	    emissionRate: number;
+	    duration: number;
+	    srcBlendFactor: number;
+	    dstBlendFactor: number;
+	    startColor: any;
+	    startColorVar: any;
+	    endColor: any;
+	    endColorVar: any;
+	    startSize: number;
+	    startSizeVar: number;
+	    endSize: number;
+	    endSizeVar: number;
+	    positionType: number;
+	    sourcePos: any;
+	    posVar: any;
+	    angle: number;
+	    angleVar: number;
+	    startSpin: number;
+	    startSpinVar: number;
+	    endSpin: number;
+	    endSpinVar: number;
+	    emitterMode: number;
+	    gravity: any;
+	    speed: number;
+	    speedVar: number;
+	    radialAccel: number;
+	    radialAccelVar: number;
+	    tangentialAccel: number;
+	    tangentialAccelVar: number;
+	    rotationIsDir: boolean;
+	    startRadius: number;
+	    startRadiusVar: number;
+	    endRadius: number;
+	    endRadiusVar: number;
+	    rotatePerS: number;
+	    rotatePerSVar: number;
+	    spriteFrameUuid: string;
+	}
+
+	/** glTF 动画资源的 userData */
+	export interface GltfAnimationAssetUserData {
+	    gltfIndex: number;
+	    events: Array<{
+	        frame: number;
+	        func: string;
+	        params: string[];
+	    }>;
+	    editorExtras?: unknown;
+	    embeddedPlayers?: Array<{
+	        editorExtras?: unknown;
+	        begin: number;
+	        end: number;
+	        reconciledSpeed: boolean;
+	        playable:
+	        | {
+	            type: 'animation-clip';
+	            path: string;
+	            clip: string;
+	        }
+	        | {
+	            type: 'particle-system';
+	            path: string;
+	        };
+	    }>;
+	    auxiliaryCurves?: Record<string, { curve: any }>;
+	    wrapMode: number;
+	    speed?: number;
+	    sample?: number;
+	    span?: {
+	        from: number;
+	        to: number;
+	    };
+	    additive?: any;
+	}
+
+	/** JavaScript 资源的 userData */
+	export type JavaScriptAssetUserData = ScriptModuleUserData | PluginScriptUserData;
+
+	/** JavaScript 插件脚本的 userData */
+	export interface PluginScriptUserData {
+	    isPlugin: true;
+	    /** 界面没有开放给用户。默认开启 */
+	    experimentalHideCommonJs?: boolean;
+	    /** 界面没有开放给用户。默认开启 */
+	    experimentalHideAmd?: boolean;
+	    /** 仅当 executionScope 为 enclosed 时有效。指定了要模拟的全局变量 */
+	    simulateGlobals?: string[];
+	    /** 执行作用域 */
+	    executionScope?: 'enclosed' | 'global';
+	    /** 插件执行时机 */
+	    loadPluginInEditor?: boolean;
+	    loadPluginInWeb?: boolean;
+	    loadPluginInMiniGame?: boolean;
+	    loadPluginInNative?: boolean;
+	}
+
+	/** JavaScript 脚本模块的 userData */
+	export interface ScriptModuleUserData {
+	    isPlugin: false;
+	}
+
+	/** Spine 资源的 userData */
+	export interface SpineAssetUserData {
+	    /** 图集资源的 UUID */
+	    atlasUuid: string;
+	}
+
+	export interface Texture2DAssetUserData extends TextureBaseAssetUserData {
+	    isUuid?: boolean;
+	    imageUuidOrDatabaseUri?: string;
+	}
+
+	export interface TextureBaseAssetUserData {
+	    wrapModeS: WrapMode;
+	    wrapModeT: WrapMode;
+	    minfilter: Filter;
+	    magfilter: Filter;
+	    mipfilter: Filter;
+	    anisotropy: number;
+	}
+
+	export type Filter = 'none' | 'nearest' | 'linear';
+
+	export type WrapMode = 'repeat' | 'clamp-to-edge' | 'mirrored-repeat';
+
+	/** 图片资源的 userData  */
+	export interface ImageAssetUserData {
+	    /** 图片类型 */
+	    type: ImageImportType;
+	    /** 垂直翻转 */
+	    flipVertical?: boolean;
+	    /** 消除透明伪影 */
+	    fixAlphaTransparencyArtifacts?: boolean;
+	    /** 是否为 RGBE */
+	    isRGBE?: boolean;
+	    /** 这个图片是不是拥有 alpha 通道 */
+	    hasAlpha?: boolean;
+	    /** 重定向的 uuid */
+	    redirect?: string;
+	    visible?: boolean;
+	    /** 是否翻转绿通道 */
+	    flipGreenChannel?: boolean;
+	
+	    /**
+	     * 部分资源导入后可能产生多张图像资源
+	     */
+	    sign?: string;
+	    alpha?: string;
+	}
+
+	export type ImageImportType = 'raw' | 'texture' | 'normal map' | 'sprite-frame' | 'texture cube';
+
+	export interface TextureCubeAssetUserData extends TextureBaseAssetUserData {
+	    imageDatabaseUri?: string;
+	    isRGBE: boolean;
+	
+	    mipBakeMode: number;
+	    /**
+	     * `0` 意味着默认。见 https://github.com/cocos-creator/3d-tasks/issues/2253
+	     */
+	    faceSize?: number;
+	    // 符号资源 uuid
+	    sign?: string;
+	
+	    // 六个面的 UUID
+	    front?: string;
+	    back?: string;
+	    left?: string;
+	    right?: string;
+	    top?: string;
+	    bottom?: string;
+	}
+
+	/** 文件夹资源的 userData */
+	export interface DirectoryAssetUserData {
+	    /** 是否是资源包 */
+	    isBundle?: boolean;
+	    /** 资源包配置 ID */
+	    bundleConfigID?: string;
+	    /** 资源包名称 */
+	    bundleName?: string;
+	    /** 优先级 */
+	    priority?: number;
+	}
+
+	/** 渲染纹理资源的 userData */
+	export interface RenderTextureAssetUserData extends TextureBaseAssetUserData {
+	    width: number;
+	    height: number;
+	}
+
+	/** 标签图集资源的 userData */
+	export interface LabelAtlasAssetUserData {
+	    itemWidth: number;
+	    itemHeight: number;
+	    startChar: string;
+	    fontSize: number;
+	    spriteFrameUuid: string;
+	    _fntConfig: FntData;
+	}
+
+	export interface FntData {
+	    commonHeight?: number;
+	    fontSize?: number;
+	    atlasName?: string;
+	    fontDefDictionary?: FontDefDictionary;
+	    kerningDict?: KerningDict;
+	}
+
+	export interface KerningDict {
+	    [key: number]: number;
+	}
+
+	export interface FontDefDictionary {
+	    [charId: number]: FontDef;
+	}
+
+	export interface FontDef {
+	    rect: {
+	        x: number;
+	        y: number;
+	        width: number;
+	        height: number;
+	    };
+	    xOffset: number;
+	    yOffset: number;
+	    xAdvance: number;
+	}
+
+	/** 自动图集资源的 userData */
+	export interface AutoAtlasAssetUserData {
+	    compressed: boolean;
+	    dest: any;
+	    /** 打包图像的尺寸 */
+	    maxWidth: number;
+	    maxHeight: number;
+	    /** 图像的边距 */
+	    padding: number;
+	    allowRotation: boolean;
+	    forceSquared: boolean;
+	    powerOfTwo: boolean;
+	    algorithm: string;
+	    format: string;
+	    quality: number;
+	    contourBleed: boolean;
+	    paddingBleed: boolean;
+	    filterUnused: boolean;
+	    removeTextureInBundle: boolean;
+	    removeImageInBundle: boolean;
+	    removeSpriteAtlasInBundle: boolean;
+	    platformSettings: any;
+	    textureSetting: any;
+	}
+
+	/// <reference types="node" />
+	
+	/** 动画剪辑资源的 userData */
+	export interface AnimationClipAssetUserData {
+	    /** 动画名称 */
+	    name: string;
+	}
+
+	/** Asset handler types include built-in values and extension-registered importer names. */
+	export type AssetHandlerType =
+	| typeof ASSET_HANDLER_TYPES[number]
+	| (string & {});
+
+	/** 所有资源处理器类型的常量数组（用于 Zod enum 和 TypeScript type） */
+	export const ASSET_HANDLER_TYPES: readonly ["directory", "unknown", "text", "json", "spine-data", "dragonbones", "dragonbones-atlas", "terrain", "javascript", "typescript", "scene", "prefab", "sprite-frame", "tiled-map", "buffer", "image", "sign-image", "alpha-image", "texture", "texture-cube", "erp-texture-cube", "render-texture", "texture-cube-face", "rt-sprite-frame", "gltf", "gltf-mesh", "gltf-animation", "gltf-skeleton", "gltf-material", "gltf-scene", "gltf-embeded-image", "fbx", "material", "physics-material", "effect", "effect-header", "audio-clip", "animation-clip", "animation-graph", "animation-graph-variant", "animation-mask", "ttf-font", "bitmap-font", "particle", "sprite-atlas", "auto-atlas", "label-atlas", "render-pipeline", "render-stage", "render-flow", "instantiation-material", "instantiation-mesh", "instantiation-skeleton", "instantiation-animation", "video-clip", "*", "database"];
+
+	/** 支持创建的资源类型（从常量数组派生） */
+	export type ISupportCreateType = typeof SUPPORT_CREATE_TYPES[number];
+
+	/** 支持创建的资源类型常量数组（用于 Zod enum 和 TypeScript type） */
+	export const SUPPORT_CREATE_TYPES: readonly ["animation-clip", "typescript", "auto-atlas", "effect", "scene", "prefab", "material", "texture-cube", "terrain", "physics-material", "label-atlas", "render-texture", "directory", "effect-header"];
+
+	export interface IRedirectInfo {
+	    // 跳转资源的类型
+	    type: string;
+	    // 跳转资源的 uuid
+	    uuid: string;
+	}
+
+	export type IAssetType =
+	| ISupportCreateCCType
+	| 'cc.Asset'               // 基础资源类型（instantiation-asset）
+	| 'cce.Database'           // 数据库资源
+	| 'cce.EffectHeader'       // 着色器头文件
+	| 'cc.VideoClip'           // 视频剪辑
+	| 'cc.TiledMapAsset'       // 瓦片地图
+	| 'cc.TTFFont'             // TTF 字体
+	| 'cc.Texture2D'           // 2D 纹理
+	| 'cc.SpriteFrame'         // 精灵帧（sprite-frame、rt-sprite-frame）
+	| 'cc.ImageAsset'          // 图片资源（image、gltf/image、image/alpha、image/sign、texture-cube-face）
+	| 'cc.TextAsset'           // 文本资源
+	| 'cc.JsonAsset'           // JSON 资源
+	| 'cc.AudioClip'           // 音频剪辑
+	| 'cc.BitmapFont'          // 位图字体
+	| 'cc.BufferAsset'         // 缓冲区资源
+	| 'cc.ParticleAsset'       // 粒子资源
+	| 'cc.RenderPipeline'     // 渲染管线
+	| 'cc.Skeleton'            // 骨骼（gltf/skeleton、instantiation-asset/skeleton）
+	| 'cc.Mesh'                // 网格（gltf/mesh、instantiation-asset/mesh）
+	| 'sp.SkeletonData'        // Spine 骨骼数据
+	| 'dragonBones.DragonBonesAsset'      // DragonBones 资源
+	| 'dragonBones.DragonBonesAtlasAsset' // DragonBones 图集资源
+	| 'RenderStage'            // 渲染阶段
+	| 'RenderFlow';
+
+	export type ISupportCreateCCType =
+	| 'cc.AnimationClip'        // 动画剪辑
+	| 'cc.Script'               // 脚本（TypeScript/JavaScript）
+	| 'cc.SpriteAtlas'          // 精灵图集（自动图集）
+	| 'cc.EffectAsset'          // 着色器效果
+	| 'cc.SceneAsset'           // 场景
+	| 'cc.Prefab'               // 预制体
+	| 'cc.Material'             // 材质
+	| 'cc.TextureCube'          // 立方体贴图
+	| 'cc.TerrainAsset'         // 地形
+	| 'cc.PhysicsMaterial'      // 物理材质
+	| 'cc.LabelAtlas'           // 标签图集
+	| 'cc.RenderTexture'        // 渲染纹理
+	| 'cc.animation.AnimationGraph'       // 动画图
+	| 'cc.AnimationMask'        // 动画遮罩
+	| 'cc.animation.AnimationGraphVariant';
+
+	export interface QueryAssetsOption {
+	    ccType?: string | string[], // 'cc.ImageAsset' 这类，多个用数组
+	    isBundle?: boolean, // 筛选 asset bundle 信息，搜索子包只能与 pattern 选项共存
+	    importer?: string | string[], // 导入名称，多个用数组
+	    pattern?: string, // 路径匹配，globs 格式
+	    extname?: string | string[], // 扩展名匹配，多个用数组
+	
+	    // 筛选一些符合 userData 配置的资源
+	    userData?: Record<string, boolean | string | number>;
+	
+	    /**
+	     * @deprecated use ccType instead
+	     */
+	    type?: string;
+	}
+	}
+
+
+
+
+	export interface Thenable<T> extends Promise<T> { }
+
+	/**
+	 * 表示一个可被监听的事件。
+	 * @template T 事件回调参数类型
+	 */
+	export interface Event<T> {
+		(listener: (e: T) => void, thisArgs?: any): Disposable;
+	}
+
+	/**
+	 * 表示一个可被释放的资源。
+	 */
+	export interface Disposable {
+		dispose(): void;
+	}
+
+	// ==================== Engine API ====================
+
+	/**
+	 * 引擎配置 API 命名空间。
+	 */
+	export namespace engine {
+		/**
+		 * 获取引擎基本信息。
+		 * @returns 引擎信息；未加载时返回 `undefined`
+		 */
+		export function getInfo(): Thenable<EngineInfo | undefined>;
+
+		/**
+		 * 获取引擎配置映射表。
+		 * @returns 引擎配置；未加载时返回 `undefined`
+		 */
+		export function getConfig(): Thenable<EngineConfig | undefined>;
+
+		/**
+		 * 获取引擎模块渲染配置（已本地化）。
+		 * @returns 模块渲染配置；未加载时返回 `undefined`
+		 */
+		export function getRenderConfig(): Thenable<ModuleRenderConfig | undefined>;
+
+		/** 引擎基本信息类型 */
+		export type EngineInfo = _cli.EngineInfo & {
+			/** 引擎来源类型：'official'（官方引擎）或 'custom'（自定义引擎路径） */
+			type: 'official' | 'custom';
+		};
+		/** 引擎配置类型 */
+		export type EngineConfig = _cli.IEngineConfig;
+		/** 引擎模块渲染配置类型 */
+		export type ModuleRenderConfig = _cli.ModuleRenderConfig;
+	}
+
+	// ==================== Assets API ====================
+
+	/**
+	 * 资源管理 API 命名空间。
+	 */
+	export namespace assets {
+		/**
+		 * 根据查询条件批量获取资源信息。
+		 * 支持按资源类型、导入器、路径模式、扩展名等条件筛选。
+		 *
+		 * @param options - 可选的查询选项：
+		 *   - `ccType`   — 资源类型，如 `'cc.ImageAsset'`，可为单个或数组
+		 *   - `isBundle` — 是否筛选 Asset Bundle
+		 *   - `importer` — 导入器名称，可为单个或数组
+		 *   - `pattern`  — 路径匹配模式（支持 globs 格式）
+		 *   - `extname`  — 扩展名匹配，可为单个或数组
+		 * @param dataKeys - 可选，需要返回的 `IAssetInfo` 可选字段名列表。
+		 *   如 `['meta', 'subAssets', 'depends']`。不传则返回默认字段（`subAssets` 和 `displayName`）。
+		 * @returns 符合条件的资源信息列表
+		 */
+		export function queryAssetInfos(options?: QueryAssetsOption, dataKeys?: AssetInfoDataKey[]): Thenable<IAssetInfo[]>;
+
+		/**
+		 * 当有新资源被添加到项目时触发。
+		 */
+		export const onAssetAdd: Event<IAssetInfo>;
+
+		/**
+		 * 当项目中的资源被修改时触发。
+		 */
+		export const onAssetChange: Event<IAssetInfo>;
+
+		/**
+		 * 当项目中的资源被删除时触发。
+		 */
+		export const onAssetDelete: Event<IAssetInfo>;
+
+		/** 资源查询选项类型 */
+		export type QueryAssetsOption = _cli.QueryAssetsOption;
+		/** 资源信息类型 */
+		export type IAssetInfo = _cli.IAssetInfo;
+		/** 资源信息可选字段名类型 */
+		export type AssetInfoDataKey = keyof _cli.IAssetInfo;
+	}
+
+	// ==================== Configuration API ====================
+
+	/**
+	 * Namespace for Pink configuration APIs.
+	 * Pink 配置系统与 VSCode 原生配置完全隔离，仅操作通过 Pink 注册表注册的配置项。
+	 */
+	export namespace configuration {
+
+		/** 配置作用域 */
+		export type ConfigScope = 'cocos' | 'folder' | 'global';
+
+		/**
+		 * 获取配置项的值。
+		 * 仅返回通过 Pink 注册表注册的配置，VSCode 原生配置不可通过此 API 获取。
+		 * @param section 配置键名，如 'scene.gizmoSize'
+		 * @param scope 显式指定作用域，不指定时按 schema.scope 决定读取 cocos 或 folder，再 global > default
+		 */
+		export function get<T>(section: string, scope?: ConfigScope): Thenable<T | undefined>;
+
+		/**
+		 * 更新配置项的值。
+		 * @param section 配置键名，如 'scene.gizmoSize'
+		 * @param value 新的配置值
+		 * @param scope 写入的作用域，默认 'folder'
+		 */
+		export function update(section: string, value: unknown, scope?: ConfigScope): Thenable<void>;
+
+		/**
+		 * 配置变更事件。
+		 * 仅在 Pink 注册表内的配置变更时触发，VSCode 原生配置变更不会触发此事件。
+		 */
+		export const onDidChangeConfiguration: Event<ConfigurationChangeEvent>;
+	}
+
+	export interface ConfigurationChangeEvent {
+		/** 发生变化的配置键 */
+		readonly section: string;
+		/** 变化发生的作用域 */
+		readonly scope: configuration.ConfigScope;
+		/** 变化后的值，undefined 表示已删除 */
+		readonly value: unknown;
+		affectsConfiguration(section: string): boolean;
+	}
+
+	// ======================== Lifecycle API ========================
+
+	export namespace lifecycle {
+
+		export enum PinkState {
+			/** Pink 未启动 */
+			NotReady = 'notReady',
+			/** Pink 正在初始化 */
+			Initializing = 'initializing',
+			/** Pink 已就绪，所有 API 可用 */
+			Ready = 'ready',
+			/** Pink 启动失败 */
+			Failed = 'failed',
+		}
+
+		export enum DisposeReason {
+			/** 窗口关闭 */
+			WindowClose = 'windowClose',
+			/** 窗口内切换项目 */
+			ProjectSwitch = 'projectSwitch',
+		}
+
+		/** 模块状态变更事件 */
+		export interface ModuleStateChangeEvent {
+			/** 模块标识 */
+			readonly module: string;
+			/** 新状态 */
+			readonly state: PinkState;
+		}
+
+		/** 模块阶段性进度事件（信息性） */
+		export interface ModuleProgressEvent {
+			/** 模块标识：'base' | 'assets' | 'scripting' | 'scene' | ... */
+			readonly module: string;
+			/** 可读的进度描述 */
+			readonly message: string;
+		}
+
+		/** 项目即将被销毁/切换前触发 */
+		export interface WillDisposeEvent {
+			readonly projectPath: string;
+			/** 触发原因 */
+			readonly reason: DisposeReason;
+			/** 当前项目是否还有其他窗口在使用（进程不会销毁） */
+			readonly hasOtherWindows: boolean;
+			/**
+			 * 阻止/延迟项目销毁。
+			 * - `true` — 取消切换
+			 * - `Promise<boolean>` — 等待用户决定（如"是否保存？"对话框）
+			 */
+			veto(value: boolean | Promise<boolean>): void;
+		}
+
+		/** 当前 Pink 整体状态 */
+		export const state: PinkState;
+
+		/**
+		 * 查询指定模块的当前状态。
+		 * 仅参与生命周期上报的 Cocos 依赖模块有状态，
+		 * 未接入模块或未知模块返回 `undefined`。
+		 */
+		export function getModuleState(module: string): PinkState | undefined;
+
+		/** Pink 整体状态变更事件 */
+		export const onDidChangeState: Event<PinkState>;
+
+		/**
+		 * 模块状态变更事件。
+		 * 当 Cocos 依赖模块的状态发生变化时触发。
+		 */
+		export const onDidChangeModuleState: Event<ModuleStateChangeEvent>;
+
+		/**
+		 * 模块阶段性进度事件。
+		 * 只有耗时模块才会上报（如 assets 数据库加载、scripting 编译）。
+		 * 这是信息性事件，不代表 API 可用性。
+		 *
+		 * @param module 可选的模块过滤。传入时仅接收该模块的进度事件；
+		 *               如果该模块不支持进度上报，则抛出错误。
+		 *               不传则接收所有模块的进度事件。
+		 * @throws 当 `module` 参数指定的模块不支持进度上报时抛出错误。
+		 */
+		export function onModuleProgress(listener: (e: ModuleProgressEvent) => void): Disposable;
+		export function onModuleProgress(module: string, listener: (e: ModuleProgressEvent) => void): Disposable;
+
+		/**
+		 * 当前窗口即将脱离当前 Pink 项目时触发（窗口关闭 / 切换项目）。
+		 * 此时旧项目的 pink.* API 仍可用，可执行保存/清理操作。
+		 */
+		export const onWillDispose: Event<WillDisposeEvent>;
+	}
+
+	// ======================== System API ========================
+
+	/**
+	 * 系统信息 API 命名空间。
+	 */
+	export namespace system {
+		/** PinK 版本号（如 `'0.0.1.29'`）。 */
+		const pinkVersion: string;
+		/** 运行平台。 */
+		const platform: 'win32' | 'darwin' | 'linux';
+	}
+
+	// ======================== Window API ========================
+
+	/**
+	 * 窗口管理 API 命名空间。
+	 */
+	export namespace window {
+
+		/**
+		 * 紧凑窗口选项。
+		 */
+		export interface CompactWindowOptions {
+			/** 以紧凑模式显示窗口，隐藏标签栏等非必要 UI 元素。 */
+			compact?: boolean;
+			/** 辅助窗口的初始尺寸。 */
+			bounds?: { width?: number; height?: number };
+			/** 为 `true` 时面板不会获取焦点。 */
+			preserveFocus?: boolean;
+			/** 为 `true` 时窗口始终置于其他窗口（如编辑器主窗口）之上。 */
+			alwaysOnTop?: boolean;
+		}
+
+		/**
+		 * 在紧凑辅助窗口中创建一个 webview 面板。
+		 *
+		 * @param viewType webview 面板的类型标识。
+		 * @param title 面板标题。
+		 * @param options 紧凑窗口选项。
+		 * @param webviewOptions webview 设置。
+		 * @returns 一个标准的 vscode WebviewPanel，拥有完整的生命周期支持。
+		 */
+		export function createWebviewPanel(
+			viewType: string,
+			title: string,
+			options?: CompactWindowOptions,
+			webviewOptions?: import('vscode').WebviewPanelOptions & import('vscode').WebviewOptions
+		): import('vscode').WebviewPanel;
+	}
+
+}