@cocos/cocos-cli-types 0.0.1-alpha.21.1 → 0.0.1-alpha.22.1

package/configuration.d.ts

@@ -23,6 +23,7 @@ export declare interface IBaseConfiguration extends EventEmitterMethods {
      * 默认配置数据
      */
     getDefaultConfig(): Record<string, any> | undefined;
+    mergeDefaultConfig(defaultConfig?: Record<string, any>): void;
     /**
      * 获取配置值
      * @param key 配置键名，支持点号分隔的嵌套路径
@@ -61,26 +62,21 @@ export declare interface ICocosConfigurationNode {
     properties: Record<string, ICocosConfigurationPropertySchema>;
 }
 
-/**
- * Cocos 配置元数据定义。
- *
- * 基于 COCOS_CONFIG 类型（@types/cocos.config.d.ts）展开，
- * 按 group(顶级模块) → node(二级字段) 组织。
- *
- * 供 Pink 配置面板渲染使用，通过 CocosHostConfiguration.getMetadata() 返回。
- */
 export declare interface ICocosConfigurationPropertySchema {
     type: 'string' | 'number' | 'boolean' | 'object' | 'array';
     default?: unknown;
     title?: string;
     description?: string;
-    scope: string[];
-    enum?: any[];
+    enum?: Array<string | number | boolean>;
     enumDescriptions?: string[];
     minimum?: number;
     maximum?: number;
     step?: number;
     order?: number;
+    properties?: Record<string, ICocosConfigurationPropertySchema>;
+    items?: ICocosConfigurationPropertySchema | ICocosConfigurationPropertySchema[];
+    additionalProperties?: boolean | ICocosConfigurationPropertySchema;
+    required?: string[];
 }
 
 /**
@@ -99,6 +95,13 @@ export declare function migrate(): Promise<void>;
 
 export declare function migrateFromProject(): Promise<IConfiguration>;
 
+/**
+ * 注册 configurationManager 保存事件的监听器
+ * 每次 cocos.config.json 被写入磁盘时触发
+ * @returns 取消监听的函数
+ */
+export declare function onDidSave(callback: () => void): () => void;
+
 export declare function reload(): Promise<void>;
 
 export declare function remove(key: string, scope?: ConfigurationScope): Promise<boolean>;

package/index.d.ts

@@ -2,6 +2,14 @@
 
 import { ChunkInfo } from '@cocos/creator-programming-quick-pack/lib/loader';
 import { EventEmitter } from 'events';
+import { NextFunction } from 'express';
+import { Request as Request_2 } from 'express';
+import { Response as Response_2 } from 'express';
+
+/**
+ * Add component to node // 添加组件到节点
+ */
+declare function addComponent(options: IAddComponentOptions): Promise<IComponent>;
 
 /** 动画剪辑资源的 userData */
 declare interface AnimationClipAssetUserData {
@@ -443,6 +451,19 @@ declare type CCEModuleMap = {
 
 declare function close_2(): Promise<void>;
 
+export declare namespace Component {
+    export {
+        addComponent,
+        createComponent,
+        removeComponent,
+        queryComponent,
+        resetComponent,
+        setProperty,
+        executeComponentMethod,
+        queryAllComponent
+    };
+}
+
 export declare namespace Configuration {
     export {
         init_3 as init,
@@ -453,6 +474,7 @@ export declare namespace Configuration {
         set,
         remove,
         save,
+        onDidSave,
         getMetadata,
         IConfiguration,
         ConfigurationScope,
@@ -514,6 +536,11 @@ declare interface CreateAssetOptions {
     customOptions?: Record<string, any>;
 }
 
+/**
+ * Add component to node // 添加组件到节点
+ */
+declare function createComponent(options: IAddComponentOptions): Promise<boolean>;
+
 /**
  * Delete Asset // 删除资源
  */
@@ -608,6 +635,8 @@ declare interface ExecuteAssetDBScriptMethodOptions {
     args?: any[];
 }
 
+declare function executeComponentMethod(options: IExecuteComponentMethodOptions): Promise<boolean>;
+
 declare interface Features {
     [feature: string]: IModuleItem;
 }
@@ -669,13 +698,27 @@ declare function getMetadata(): Promise<ICocosConfigurationNode[]>;
 declare function getProgrammingFacet(): Promise<ProgrammingFacet>;
 
 /**
- * Get the MCP server status.
+ * Get the MCP registration status.
  */
 declare function getStatus(): {
+    registered: boolean;
+    url?: string;
+};
+
+/**
+ * Get the server running status.
+ */
+declare function getStatus_2(): {
     running: boolean;
     url?: string;
 };
 
+/**
+ * Get the current server base URL.
+ * Returns undefined if the server is not running.
+ */
+declare function getUrl(): string | undefined;
+
 /** glTF 动画资源的 userData */
 declare interface GltfAnimationAssetUserData {
     gltfIndex: number;
@@ -857,6 +900,14 @@ declare interface GlTFUserData {
     };
 }
 
+/**
+ * 创建/添加组件
+ */
+declare interface IAddComponentOptions {
+    nodePathOrUuid: string;
+    component: string;
+}
+
 declare interface IAssetConfig {
     displayName?: string;
     description?: string;
@@ -964,6 +1015,7 @@ declare interface IBaseConfiguration extends EventEmitterMethods {
      * 默认配置数据
      */
     getDefaultConfig(): Record<string, any> | undefined;
+    mergeDefaultConfig(defaultConfig?: Record<string, any>): void;
     /**
      * 获取配置值
      * @param key 配置键名，支持点号分隔的嵌套路径
@@ -1007,32 +1059,62 @@ declare interface ICocosConfigurationNode {
     properties: Record<string, ICocosConfigurationPropertySchema>;
 }
 
-/**
- * Cocos 配置元数据定义。
- *
- * 基于 COCOS_CONFIG 类型（@types/cocos.config.d.ts）展开，
- * 按 group(顶级模块) → node(二级字段) 组织。
- *
- * 供 Pink 配置面板渲染使用，通过 CocosHostConfiguration.getMetadata() 返回。
- */
 declare interface ICocosConfigurationPropertySchema {
     type: 'string' | 'number' | 'boolean' | 'object' | 'array';
     default?: unknown;
     title?: string;
     description?: string;
-    scope: string[];
-    enum?: any[];
+    enum?: Array<string | number | boolean>;
     enumDescriptions?: string[];
     minimum?: number;
     maximum?: number;
     step?: number;
     order?: number;
+    properties?: Record<string, ICocosConfigurationPropertySchema>;
+    items?: ICocosConfigurationPropertySchema | ICocosConfigurationPropertySchema[];
+    additionalProperties?: boolean | ICocosConfigurationPropertySchema;
+    required?: string[];
 }
 
 declare interface ICollisionMatrix {
     [x: string]: number;
 }
 
+/**
+ * 代表组件属性信息
+ */
+declare interface IComponent extends IComponentIdentifier {
+    properties: {
+        [key: string]: IPropertyValueType;
+    };
+    prefab: ICompPrefabInfo | null;
+}
+
+declare interface IComponentForPinK extends IProperty {
+    value: {
+        enabled: IPropertyValueType;
+        uuid: IPropertyValueType;
+        name: IPropertyValueType;
+    } & Record<string, IPropertyValueType>;
+    mountedRoot?: string;
+}
+
+/**
+ * 代表一个组件
+ */
+declare interface IComponentIdentifier {
+    cid: string;
+    path: string;
+    uuid: string;
+    name: string;
+    type: string;
+    enabled: boolean;
+}
+
+declare interface ICompPrefabInfo {
+    fileId: string;
+}
+
 /**
  * 配置的格式
  */
@@ -1165,6 +1247,15 @@ declare interface IEngineProjectConfig extends Exclude<IEngineConfig, 'includeMo
     globalConfigKey?: string;
 }
 
+/**
+ * 执行组件方法选项
+ */
+declare interface IExecuteComponentMethodOptions {
+    uuid: string;
+    name: string;
+    args: any[];
+}
+
 declare interface IFbxSetting {
     /**
      * https://github.com/cocos-creator/FBX-glTF-conv/pull/26
@@ -1247,6 +1338,11 @@ declare type IFlags = Record<string, boolean | number>;
 
 declare type IFlags_2 = Record<string, boolean | number>;
 
+declare interface IGetPostConfig {
+    url: string | RegExp;
+    handler: (req: Request_2, res: Response_2, next?: NextFunction) => Promise<void>;
+}
+
 declare interface IInitEngineInfo {
     importBase: string;
     nativeBase: string;
@@ -1302,6 +1398,13 @@ declare interface ImageMeta {
     remap?: string;
 }
 
+declare interface IMiddlewareContribution {
+    get?: IGetPostConfig[];
+    post?: IGetPostConfig[];
+    staticFiles?: IStaticFileConfig[];
+    socket?: ISocketConfig;
+}
+
 declare interface IModuleConfig {
     moduleTreeDump: {
         default: IModules;
@@ -1458,6 +1561,78 @@ declare interface IProject {
     updateInfo<T>(keyOrValue: string | ProjectInfo, value?: T): Promise<boolean>;
 }
 
+/**
+ * 组件的 dump 数据，以 IProperty 格式编码组件信息
+ * 与 IComponent 不同，所有属性（包括 uuid, name, enabled）都通过 encodeObject 编码为 IProperty
+ */
+declare interface IProperty {
+    value: { [key: string]: IPropertyValueType } | IPropertyValueType;
+    default?: any; // 默认值
+
+    // 多选节点之后，这里存储多个数据，用于自行判断多选后的显示效果，无需更新该数据
+    values?: ({ [key: string]: IPropertyValueType } | IPropertyValueType)[];
+
+    lock?: { [key in keyof Vec4]?: IPropertyLock };
+
+    cid?: string;
+    type?: string;
+    ui?: { name: string; data?: any }; // 是否用指定的 UI 组件，name 是组件的名称
+    readonly?: boolean;
+    visible?: boolean;
+    name?: string;
+
+    elementTypeData?: IProperty; // 数组里的数据的默认值 dump
+
+    path?: string; // 数据的搜索路径，这个是由使用方填充的
+
+    isArray?: boolean;
+    invalid?: boolean;
+    extends?: string[]; // 继承链
+    displayName?: string; // 显示到界面上的名字
+    displayOrder?: number; // 显示排序
+    help?: string; // 帮助文档的 url 地址
+    group?: IPropertyGroupOptions; // tab
+    tooltip?: string; // 提示文本
+    editor?: any; // 组件上定义的编辑器数据
+    animatable?: boolean; // 是否可以在动画中编辑
+    radioGroup?: boolean; // 是否渲染为 RadioGroup
+
+    // Enum
+    enumList?: any[]; // enum 类型的 list 选项数组
+
+    bitmaskList?: any[];
+
+    // Number
+    min?: number; // 数值类型的最小值
+    max?: number; // 数值类型的最大值
+    step?: number; // 数值类型的步进值
+    slide?: boolean; // 数组是否显示为滑块
+    unit?: string; // 显示的单位
+    radian?: boolean; // 标识是否为角度
+
+    // Label
+    multiline?: boolean; // 字符串是否允许换行
+    // nullable?: boolean; 属性是否允许为空
+
+    optionalTypes?: string[]; // 对属性是 object 且是可变类型的数据的支持，比如 render-pipeline
+
+    userData?: { [key: string]: any }; // 用户透传的数据
+}
+
+declare interface IPropertyGroupOptions {
+    id: string // 默认 'default'
+    name: string,
+    displayOrder: number, // 默认 Infinity, 排在最后面
+    style: string // 默认为 'tab'
+}
+
+declare type IPropertyLock = { 
+    default: number; 
+    message: string 
+};
+
+declare type IPropertyValueType = IProperty | IProperty[] | null | undefined | number | boolean | string | Vec4 | Vec3 | Vec2 | Mat4 | any | Array<unknown>
+
 declare interface IRedirectInfo {
     // 跳转资源的类型
     type: string;
@@ -1465,6 +1640,25 @@ declare interface IRedirectInfo {
     uuid: string;
 }
 
+/**
+ * 删除组件
+ */
+declare interface IRemoveComponentOptions {
+    pathOrUuidOrUrl: string;
+}
+
+declare interface ISetPropertyOptionsForPink {
+    uuid: string;
+    path: string;
+    dump: IProperty;
+    record?: boolean;
+}
+
+declare interface ISocketConfig {
+    connection: (socket: any) => void;
+    disconnect: (socket: any) => void;
+}
+
 declare interface ISplashBackgroundColor {
     x: number;
     y: number;
@@ -1491,6 +1685,11 @@ declare interface ISplashSetting {
     }
 }
 
+declare interface IStaticFileConfig {
+    url: string;
+    path: string;
+}
+
 declare type ISupportCreateCCType =
 | 'cc.AnimationClip'        // 动画剪辑
 | 'cc.Script'               // 脚本（TypeScript/JavaScript）
@@ -1600,10 +1799,32 @@ declare type MacroItem = {
 
 declare type MakeRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
 
+declare interface Mat4 {
+    m00: number;
+    m01: number;
+    m02: number;
+    m03: number;
+
+    m04: number;
+    m05: number;
+    m06: number;
+    m07: number;
+
+    m08: number;
+    m09: number;
+    m10: number;
+    m11: number;
+
+    m12: number;
+    m13: number;
+    m14: number;
+    m15: number;
+}
+
 export declare namespace Mcp {
     export {
-        startServer,
-        stopServer,
+        register,
+        unregister,
         getStatus
     };
 }
@@ -1763,6 +1984,13 @@ declare function onAssetRemoved(listener: (info: IAssetInfo) => void): () => voi
  */
 declare function onDBReady(listener: (dbInfo: IAssetDBInfo) => void): () => void;
 
+/**
+ * 注册 configurationManager 保存事件的监听器
+ * 每次 cocos.config.json 被写入磁盘时触发
+ * @returns 取消监听的函数
+ */
+declare function onDidSave(callback: () => void): () => void;
+
 /**
  * Register listener for initialization progress.
  *
@@ -2030,6 +2258,11 @@ declare interface ProjectInfo {
  */
 declare type ProjectType = '2d' | '3d';
 
+/**
+ * Query all component names // 查询所有组件名称
+ */
+declare function queryAllComponent(): Promise<string[]>;
+
 /**
  * Query Asset Config Map // 查询资源配置映射表
  */
@@ -2088,6 +2321,11 @@ declare function queryAssetUserDataConfig(urlOrUuidOrPath: string): Promise<fals
  */
 declare function queryAssetUsers(uuidOrUrl: string, type?: QueryAssetType): Promise<string[]>;
 
+/**
+ * Query component info // 查询组件信息
+ */
+declare function queryComponent(uuid: string): Promise<IComponentForPinK | null>;
+
 /**
  * Query Creatable Asset Map // 查询可创建资源映射表
  */
@@ -2118,6 +2356,36 @@ declare function queryUUID(urlOrPath: string): Promise<string | null>;
  */
 declare function refresh(dir: string): Promise<number>;
 
+/**
+ * MCP Facade Module
+ *
+ * Called by the cocos-code utility process to register MCP middleware
+ * in an already-initialized environment.
+ * Prerequisite: the Server module must be started before calling this module.
+ * This module only handles MCP-specific work: populating the toolRegistry
+ * and registering MCP routes on the running server.
+ */
+/**
+ * Register MCP middleware on the running server.
+ *
+ * Note: the Express server must already be started via the Server module.
+ * This function only:
+ * 1. Imports API modules to populate the toolRegistry (@tool decorator side-effects)
+ * 2. Creates McpMiddleware and registers routes on the server
+ *
+ * @returns MCP endpoint URL (e.g. http://localhost:9527/mcp)
+ */
+declare function register(): Promise<string>;
+
+/**
+ * Register a middleware contribution (routes, static files, sockets)
+ * on the running server.
+ *
+ * @param name   Middleware identifier
+ * @param module Middleware contribution config
+ */
+declare function register_2(name: string, module: IMiddlewareContribution): Promise<void>;
+
 /**
  * Reimport Asset // 重新导入资源
  */
@@ -2127,6 +2395,11 @@ declare function reload(): Promise<void>;
 
 declare function remove(key: string, scope?: ConfigurationScope): Promise<boolean>;
 
+/**
+ * Remove component from node // 移除节点上的组件
+ */
+declare function removeComponent(options: IRemoveComponentOptions): Promise<boolean>;
+
 /**
  * Rename Asset // 重命名资源
  */
@@ -2138,6 +2411,8 @@ declare interface RenderTextureAssetUserData extends TextureBaseAssetUserData {
     height: number;
 }
 
+declare function resetComponent(uuid: string): Promise<void>;
+
 /** 渲染纹理精灵帧的 userData */
 declare interface RtSpriteFrameAssetUserData {
     /** 图片 UUID 或数据库 URI */
@@ -2188,8 +2463,23 @@ declare interface SerializedAssetFinder {
     scenes?: Array<string | null>;
 }
 
+export declare namespace Server {
+    export {
+        start_2 as start,
+        stop_2 as stop,
+        getUrl,
+        register_2 as register,
+        getStatus_2 as getStatus
+    };
+}
+
 declare function set<T>(key: string, value: T, scope?: ConfigurationScope): Promise<boolean>;
 
+/**
+ * Set component property // 设置组件属性
+ */
+declare function setProperty(options: ISetPropertyOptionsForPink): Promise<boolean>;
+
 declare interface SharedSettings {
     useDefineForClassFields: boolean;
     allowDeclareFields: boolean;
@@ -2282,37 +2572,26 @@ declare interface SpriteFrameVertices {
 declare function start(): Promise<void>;
 
 /**
- * 在独立的子进程中运行项目脚本编译
- * 以避免阻塞主进程
- */
-declare function startCompileScript(assetChanges?: AssetChangeInfo[]): Promise<void>;
-
-declare function startEngineCompilation(force?: boolean): Promise<void>;
-
-/**
- * MCP Server Facade Module
+ * Server Facade Module
  *
- * Called by the cocos-code utility process to start the MCP server
- * in an already-initialized environment.
- * Prerequisite: core modules (project/engine/assets/scripting/builder)
- * have been initialized via their respective lib modules.
- * This module only handles MCP-specific work: populating the toolRegistry,
- * starting Express, and registering MCP routes.
+ * Provides a simplified interface for managing the Express HTTP server.
+ * Wraps the core server service with startup guards and status tracking.
  */
 /**
- * Start the MCP server.
- *
- * Note: does NOT call CocosAPI.startup() / Launcher because
- * core modules are already initialized by the utility process.
- * This function only:
- * 1. Imports API modules to populate the toolRegistry (@tool decorator side-effects)
- * 2. Starts the Express HTTP server
- * 3. Creates McpMiddleware and registers routes
+ * Initialize and start the Express HTTP server.
  *
  * @param port Optional port number; auto-selected if omitted
- * @returns MCP server URL (e.g. http://localhost:9527/mcp)
+ * @returns The server base URL (e.g. http://localhost:9527)
+ */
+declare function start_2(port?: number): Promise<string>;
+
+/**
+ * 在独立的子进程中运行项目脚本编译
+ * 以避免阻塞主进程
  */
-declare function startServer(port?: number): Promise<string>;
+declare function startCompileScript(assetChanges?: AssetChangeInfo[]): Promise<void>;
+
+declare function startEngineCompilation(force?: boolean): Promise<void>;
 
 /**
  * Start the scene worker process.
@@ -2322,9 +2601,9 @@ declare function startServer(port?: number): Promise<string>;
 declare function startupWorker(projectPath: string): Promise<void>;
 
 /**
- * Stop the MCP server.
+ * Stop the Express HTTP server.
  */
-declare function stopServer(): Promise<void>;
+declare function stop_2(): Promise<void>;
 
 /** 支持创建的资源类型常量数组（用于 Zod enum 和 TypeScript type） */
 declare const SUPPORT_CREATE_TYPES: readonly ['animation-clip', 'typescript', 'auto-atlas', 'effect', 'scene', 'prefab', 'material', 'terrain', 'physics-material', 'label-atlas', 'render-texture', 'directory', 'effect-header'];
@@ -2388,6 +2667,12 @@ declare interface ThumbnailInfo {
     value: string; // 具体 icon 名字或者 image 路径，image 路径支持绝对路径、 db:// 、 project:// 、和 packages:// 下的路径
 }
 
+/**
+ * Clean up MCP state.
+ * Note: does NOT stop the Express server — use the Server module for that.
+ */
+declare function unregister(): Promise<void>;
+
 /**
  * Update Asset User Data // 更新资源用户数据
  */
@@ -2398,6 +2683,24 @@ declare function updateAssetUserData(urlOrUuidOrPath: string, path: string, valu
  */
 declare function updateDefaultUserData(handler: string, path: string, value: any): Promise<void>;
 
+declare interface Vec2 {
+    x: number;
+    y: number;
+}
+
+declare interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+
+declare interface Vec4 {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+
 declare type WrapMode = 'repeat' | 'clamp-to-edge' | 'mirrored-repeat';
 
 export { };

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.21.1",
+    "version": "0.0.1-alpha.22.1",
     "main": "index.d.ts",
     "types": "index.d.ts",
     "exports": {