@dd-code/uni-tools 1.0.14 → 1.0.16

package/dist/index.mjs.js

@@ -627,6 +627,11 @@ var downloadProjectFiles = function (manifestList) { return __awaiter(void 0, vo
     });
 }); };
 
+/**
+ * 计算需要下载/更新的 Manifest 列表
+ * - 比较 node_modules 缓存中的 manifest 哈希与远端 manifest 哈希
+ * - 返回需要更新的清单（用于后续下载项目文件到本地缓存）
+ */
 var checkDownloadFilesIsExpired = function (manifestList) {
     var filterList = manifestList.filter(function (conf) {
         var targetPath = getNodeModulesEnvAppCodeFilePath(conf, MANIFEST_NAME);
@@ -636,6 +641,14 @@ var checkDownloadFilesIsExpired = function (manifestList) {
     });
     return filterList;
 };
+/**
+ * Manifest 管理器（构建态/运行态共享状态）
+ * - value：当前应用 Manifest（会随构建过程逐步填充）
+ * - setEnv：读取 cli/vite 环境，设置 isRoot/isServe/code/appCode/publicPath 等
+ * - setPagesJson/setFiles/setExposes：在插件流程中填充 pages 与产物清单与运行时暴露
+ * - saveFile：落盘 Manifest（计算 hash，剔除临时字段 isServe）
+ * - dependencies：记录其他应用的 Manifest（用于主应用合并）
+ */
 var createManifestManager = function () {
     var envObj = process.env;
     var row = {
@@ -688,25 +701,16 @@ var createManifestManager = function () {
         },
     };
 };
-var getRootMainManifestJson = function (code, mode) { return __awaiter(void 0, void 0, void 0, function () {
-    var pageManifest, nodeModulesManifest, cdnUrl, manifestJson;
+/**
+ * 从 CDN 获取主应用 Manifest（ROOT_APP_CODE）
+ * - 仅用于校验/兜底：优先使用本地 dist 或缓存 node_modules 的 Manifest
+ */
+var downloadMainAppManifestJson = function (currentManifest) { return __awaiter(void 0, void 0, void 0, function () {
+    var mode, code, cdnUrl, manifestJson;
     return __generator(this, function (_b) {
         switch (_b.label) {
             case 0:
-                try {
-                    pageManifest = uniReadFile(path.join(process.env.UNI_OUTPUT_DIR, MANIFEST_NAME));
-                    if (Object.keys(pageManifest).length !== 0) {
-                        return [2 /*return*/, pageManifest];
-                    }
-                }
-                catch (_c) { }
-                try {
-                    nodeModulesManifest = uniReadFile(path.join(SAVE_CDN_FILE_PATH, mode, ROOT_APP_CODE, MANIFEST_NAME));
-                    if (Object.keys(nodeModulesManifest).length !== 0) {
-                        return [2 /*return*/, nodeModulesManifest];
-                    }
-                }
-                catch (_d) { }
+                mode = currentManifest.mode, code = currentManifest.code;
                 _b.label = 1;
             case 1:
                 _b.trys.push([1, 3, , 4]);
@@ -718,19 +722,72 @@ var getRootMainManifestJson = function (code, mode) { return __awaiter(void 0, v
                 return [4 /*yield*/, fetchFileByPath(cdnUrl)];
             case 2:
                 manifestJson = _b.sent();
-                if (Object.keys(manifestJson).length !== 0) {
-                    return [2 /*return*/, manifestJson];
-                }
-                return [3 /*break*/, 4];
+                return [2 /*return*/, manifestJson];
             case 3:
                 _b.sent();
                 return [3 /*break*/, 4];
-            case 4: return [2 /*return*/, { exposes: {} }];
+            case 4: return [2 /*return*/, {}];
+        }
+    });
+}); };
+/**
+ * 读取根主应用 Manifest（优先级：dist > node_modules 缓存 > CDN）
+ * - 兼容不同构建场景：
+ *   - isServe（WS 联调）或内部构建（inner build）下无需校验哈希
+ *   - 其他场景严格校验本地与远端 Manifest 的 hash 一致性
+ * - 选择顺序：
+ *   1) 当前构建输出目录的 app.json（dist）
+ *   2) node_modules 缓存目录中的 app.json（save cdn file path）
+ *   3) 远端 CDN 拉取的 Manifest（兜底）
+ */
+var getRootMainManifestJson = function (currentManifest) { return __awaiter(void 0, void 0, void 0, function () {
+    var mode, isInnerBuild, isWsBuild, needCheckHash, originHostManifestJson, checkHash, distPagePath, pageManifest, nodeModulePath, nodeModulesManifest;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                mode = currentManifest.mode;
+                isInnerBuild = checkIsInnerBuild();
+                isWsBuild = currentManifest.isServe;
+                needCheckHash = !(isWsBuild || isInnerBuild);
+                return [4 /*yield*/, downloadMainAppManifestJson(currentManifest)];
+            case 1:
+                originHostManifestJson = _a.sent();
+                checkHash = function (target) {
+                    if ((originHostManifestJson === null || originHostManifestJson === void 0 ? void 0 : originHostManifestJson.hash) && needCheckHash && (originHostManifestJson === null || originHostManifestJson === void 0 ? void 0 : originHostManifestJson.hash) !== target.hash) {
+                        throw new Error("originHostManifestJson hash not equal");
+                    }
+                };
+                try {
+                    distPagePath = path.join(process.env.UNI_OUTPUT_DIR, MANIFEST_NAME);
+                    pageManifest = uniReadFile(distPagePath);
+                    checkHash(pageManifest);
+                    console.log("distPagePath done");
+                    if (Object.keys(pageManifest).length !== 0) {
+                        return [2 /*return*/, pageManifest];
+                    }
+                }
+                catch (_b) { }
+                try {
+                    nodeModulePath = path.join(SAVE_CDN_FILE_PATH, mode, ROOT_APP_CODE, MANIFEST_NAME);
+                    nodeModulesManifest = uniReadFile(nodeModulePath);
+                    checkHash(nodeModulesManifest);
+                    console.log("nodeModulePath done");
+                    if (Object.keys(nodeModulesManifest).length !== 0) {
+                        return [2 /*return*/, nodeModulesManifest];
+                    }
+                }
+                catch (_c) { }
+                console.log('origin done');
+                return [2 /*return*/, originHostManifestJson];
         }
     });
 }); };
 
 var num = 5;
+/**
+ * 从主应用 HTTP 服务拉取当前进程环境（含 UNI_OUTPUT_DIR）
+ * - serve 非联调模式下，子应用通过此接口获知主应用输出根目录
+ */
 var getMainProcess = function () { return __awaiter(void 0, void 0, void 0, function () {
     var URL, mainProcess, result;
     return __generator(this, function (_a) {
@@ -748,6 +805,10 @@ var getMainProcess = function () { return __awaiter(void 0, void 0, void 0, func
         }
     });
 }); };
+/**
+ * 简易重试（最多 5 次，每次 100ms）
+ * - 主应用 HTTP 服务启动可能有延迟，子应用循环尝试获取
+ */
 var getMainProcessLoop = function () { return __awaiter(void 0, void 0, void 0, function () {
     var mainProcess;
     return __generator(this, function (_a) {
@@ -803,6 +864,10 @@ var resetOutDir = function (currentManifestJson, config) { return __awaiter(void
                 process.env.MFE_ROOT_OUTPUT_DIR = (_a = process.env.MFE_SOURCE_OUTPUT_DIR) === null || _a === void 0 ? void 0 : _a.replace(exp, "/").replace(/\/$/, "");
                 // if (!currentManifestJson.value.isRoot)
                 // console.log(config);
+                /**
+                 * 非内部构建下，将 UNI_OUTPUT_DIR 统一指向主应用根输出目录
+                 * - 便于后续写入 app.json 与拷贝产物
+                 */
                 if (!checkIsInnerBuild()) {
                     // setTimeout(() => {
                     process.env.UNI_OUTPUT_DIR = process.env.MFE_ROOT_OUTPUT_DIR;
@@ -813,6 +878,11 @@ var resetOutDir = function (currentManifestJson, config) { return __awaiter(void
     });
 }); };
 
+/**
+ * 接管 uni 内置复制钩子
+ * - 通过 before/after 钩子记录从源到目标的拷贝行为
+ * - 便于在 Manifest 插件中收集运行期拷贝产生的文件清单
+ */
 var addUniCopyPluginHook = function (_a) {
     var before = _a.before, after = _a.after;
     var FileWatcher = require("@dcloudio/uni-cli-shared/dist/watcher").FileWatcher;
@@ -834,6 +904,11 @@ var copyFilesByTargetPath = function (sourcePath, targetPath) {
         fsExtra.ensureDirSync(targetDir);
     }
     catch (err) { }
+    /**
+     * 内容比较：
+     * - 仅当源/目标均为文件且内容完全一致时跳过，避免无效写入
+     * - 目录或不存在的目标不跳过
+     */
     var shouldSkip = function () {
         try {
             var s = fs.statSync(sourcePath);
@@ -842,6 +917,11 @@ var copyFilesByTargetPath = function (sourcePath, targetPath) {
                 return false;
             var sb = fs.readFileSync(sourcePath);
             var tb = fs.readFileSync(targetPath);
+            /**
+             * Buffer 比较：
+             * - 长度与内容完全一致时跳过
+             * - 保留二进制级别比较，适配图片/字体等非文本文件
+             */
             return sb.length === tb.length && sb.equals(tb);
         }
         catch (_a) {
@@ -930,6 +1010,13 @@ var initPrePagesJson = function () {
     var pagesPath = path.resolve(process.cwd(), "src/pages.json");
     return fs.readFileSync(pagesPath, "utf-8");
 };
+/**
+ * 解析并预处理 pages.json
+ * - 读取全局 preprocess 上下文（根据平台注入不同变量）
+ * - 使用 @dcloudio 的 preprocess 对 pages.json 做条件编译（如 #ifdef/#endif）
+ * - 返回 JS 对象形式的 pages 配置
+ * - isFormat=true 且平台为 mp-weixin 时，转换为微信特定格式（去除 globalStyle 并映射到 window/subPackages）
+ */
 var getPagesJson = function (jsonFile, isFormat) {
     if (isFormat === void 0) { isFormat = false; }
     var platform = process.env.UNI_PLATFORM;
@@ -942,6 +1029,12 @@ var getPagesJson = function (jsonFile, isFormat) {
     }
     return pagesConfig;
 };
+/**
+ * 将 Uni 的 pages.json 转换为微信小程序格式
+ * - window：映射 globalStyle，并兼容 mp-weixin 特定字段
+ * - subPackages：后续会在 app-json.ts 中由各子应用补充到主应用
+ * - usingComponents：保留全局组件声明
+ */
 var transformToWeixinFormat = function (uniPagesConfig) {
     var _a;
     var weixinConfig = __assign({ pages: [], window: {}, tabBar: null, subPackages: [], usingComponents: {} }, uniPagesConfig);
@@ -1007,6 +1100,19 @@ var transformToWeixinFormat = function (uniPagesConfig) {
 };
 
 // import { addRunningAppToSave } from "../running-core";
+/**
+ * Manifest 采集与产物清单插件
+ * - 目标：收集构建阶段产物与运行期拷贝的文件列表，生成可供主应用消费的文件清单
+ * - CollectFiles：
+ *   - emitted：bundle 产物与拷贝文件的统一索引（fileName -> fileUrl）
+ *   - callbackFiles：拦截 uni 的复制钩子，收集被拷贝的源与目标相对路径
+ *   - copyFilesToPublishDir：将 outDir 下的产物拷贝到 publish 目录，便于后续上载/分发
+ * - 插件钩子：
+ *   - config：记录 outDir，拦截 uni 拷贝行为
+ *   - renderStart：解析 pages.json，写入到 Manifest 状态
+ *   - writeBundle：收集本次打包输出的 chunk 信息
+ *   - closeBundle：汇总拷贝与产物，写入 Manifest 文件并拷贝到发布目录
+ */
 var CollectFiles = /** @class */ (function () {
     function CollectFiles() {
         this.callbackFiles = [];
@@ -1026,6 +1132,11 @@ var CollectFiles = /** @class */ (function () {
         Object.keys(bundles).forEach(function (key) {
             var boundle = bundles[key];
             var fileName = boundle.fileName, source = boundle.source, code = boundle.code;
+            /**
+             * code/source：
+             * - chunk 使用 code 字段，asset 使用 source 字段
+             * - 统一抽象为 fileInfo 行（包含 fileUrl 与大小哈希）
+             */
             var fileInfo = genreFileInfoRow({ fileName: fileName, source: code || source });
             _this.emitted.set(fileName, fileInfo);
         });
@@ -1120,6 +1231,12 @@ var createManifestPlugin = function (manifestJson) {
     };
 };
 
+/**
+ * 主应用 app.json 渲染与写入
+ * - renderPagesJsonByArray：将多个子应用的 pages.json 以分包形式合入主应用
+ * - genreFullMainAppJsonByManifestList：按 Manifest 列表生成完整的主应用 app.json
+ * - genreNewAppJson：内容比较后写入 app.json，避免无效写入导致的频繁重启
+ */
 var renderPagesJsonByArray = function (appPages, pageJson) {
     var _loop_1 = function (app) {
         var _a = getPagesJson(JSON.stringify((app === null || app === void 0 ? void 0 : app.pagesJson) || {}), true).pages, pages = _a === void 0 ? [] : _a;
@@ -1153,6 +1270,14 @@ var genreNewAppJson = function (outputPageJsonPath, appJson, manifestList) {
     }
 };
 
+/**
+ * 运行期联调核心
+ * - getAppsManifestList：在主应用非联调构建模式下，返回所有子应用的 Manifest 路径列表
+ * - startDistWatcher：监听子应用输出目录的父级变更，增量拷贝到主应用分包路径，并上报变更
+ * - 设计要点：
+ *   - 监听父级目录以覆盖新增/删除场景；通过 `isTargetFile` 过滤目标变化
+ *   - 拷贝时进行内容比较，避免触发无效写入
+ */
 var getAppsManifestList = function (mode) {
     var _a;
     var manifest = formatCliCommandConfig(mode);
@@ -1182,6 +1307,11 @@ var startDistWatcher = function (mainPwd, onReady, onChange) {
     var filePath = path.resolve(root);
     checkAndgenreDir(filePath);
     var parentDir = path.dirname(filePath);
+    /**
+     * 监听父级目录：
+     * - uni 输出目录在构建时可能新增/删除文件或目录，监听父级可捕捉到此类变化
+     * - 通过 isTargetFile 精确过滤与目标目录相关的事件
+     */
     var watcher = createFileWatcher(parentDir);
     var isTargetFile = function (p) {
         return p.startsWith(filePath + path.sep) || p === filePath;
@@ -1196,6 +1326,11 @@ var startDistWatcher = function (mainPwd, onReady, onChange) {
             var sourcePath = p;
             var targetPath = path.join(mainPwd, rel);
             if (["add", "change"].includes(evt)) {
+                /**
+                 * 增量拷贝：
+                 * - 目录结构保持一致，从子应用输出拷贝到主应用分包路径
+                 * - 通过 copyFilesByTargetPath 的内容比较避免重复写入
+                 */
                 copyFilesByTargetPath(sourcePath, targetPath);
             }
             onChange === null || onChange === void 0 ? void 0 : onChange({ type: evt, p: p, sourcePath: sourcePath, targetPath: targetPath });
@@ -1204,6 +1339,13 @@ var startDistWatcher = function (mainPwd, onReady, onChange) {
 };
 
 var app = null;
+/**
+ * 创建开发态 HTTP 服务
+ * - 单例复用：避免重复创建与重复监听
+ * - 路由：
+ *   - GET `${HTTP_PATH}/root-path`：返回当前进程的环境变量（主应用输出位置等）
+ * - 与 WS 服务配合：WSServer 绑定同一个 HTTP server 进行升级
+ */
 var createHttpServer = function () {
     if (app)
         return { server: app, start: function () { } };
@@ -1213,6 +1355,11 @@ var createHttpServer = function () {
         res.send(process.env);
     });
     app.use(cors({ origin: "*" }));
+    /**
+     * 返回：
+     * - server：HTTP Server 实例（供 WS 复用）
+     * - start(type)：启动监听并输出日志，type 用于日志区分（'http' | 'ws'）
+     */
     return {
         server: server,
         start: function (type) {
@@ -1230,6 +1377,10 @@ var WsServer = /** @class */ (function () {
         this.httpServer = createHttpServer();
         this.clientMap = new Map();
     }
+    /**
+     * 单例获取 WS 服务实例
+     * - 若已创建则复用并更新消息回调
+     */
     WsServer.getInstance = function (handleMessage) {
         if (!WsServer.instance) {
             WsServer.instance = new WsServer(handleMessage);
@@ -1257,12 +1408,18 @@ var WsServer = /** @class */ (function () {
             this.handleMessage = callback;
         }
     };
+    /**
+     * 向指定 appCode 的客户端发送消息
+     */
     WsServer.prototype.sendMessageToApp = function (appCode, message) {
         var ws = this.clientMap.get(appCode);
         if (ws) {
             ws.send(typeof message === "string" ? message : JSON.stringify(message));
         }
     };
+    /**
+     * 连接事件：建立客户端映射并下发初始化信息（主应用输出目录）
+     */
     WsServer.prototype.onConnection = function () {
         var _this = this;
         this.wss.on("connection", function (ws, request) {
@@ -1301,6 +1458,9 @@ var WsClientServer = /** @class */ (function () {
         this.ws = null;
         this.isConnected = false;
     }
+    /**
+     * 获取客户端单例
+     */
     WsClientServer.getInstance = function (handleMessage) {
         if (!WsClientServer.instance) {
             WsClientServer.instance = new WsClientServer(handleMessage);
@@ -1354,6 +1514,9 @@ var WsClientServer = /** @class */ (function () {
             this.handleMessage = callback;
         }
     };
+    /**
+     * 简单重试策略：一定时间后重新连接
+     */
     WsClientServer.prototype.retryConnect = function (appCode) {
         var _this = this;
         if (this.isConnected)
@@ -1378,6 +1541,20 @@ var WsClientServer = /** @class */ (function () {
 // export const mfeServer = new WsServer();
 // export const mfeClientServer = new WsClientServer();
 
+/**
+ * 主应用插件（Main App）
+ * - 服务端（根应用）：
+ *   - 启动 WS + HTTP 服务，向子应用广播初始化信息（主应用输出目录）
+ *   - 接收子应用文件变更事件，拉取对应子应用 Manifest 并增量更新主应用 app.json
+ * - 客户端（子应用）：
+ *   - 连接主应用 WS，接收初始化 pwd 后将自身构建产物增量拷贝到主应用分包路径
+ *   - 在构建完成后启动本地 DistWatcher，监控自身输出变更并通过 WS 通知主应用
+ * - 构建阶段：
+ *   - 合并所有依赖子应用的 pages.json，生成最终主应用 app.json，内容比较避免无效写入
+ * - 关键点：
+ *   - `isBuild`/`isServe`/`isRoot` 三态控制插件行为，避免生产与联调逻辑相互影响
+ *   - `copyFilesByTargetPath` 与 `genreNewAppJson` 均内置内容比较，防止频繁重启
+ */
 var filterManifestJsonListAndMainPageJson = function (manifestJsonList) {
     var outputPageJsonPath = getMainAppJsonPath();
     return {
@@ -1429,6 +1606,11 @@ var createMainAppPlugin = function (manifestJson) {
         startDistWatcher(state.mainPwd, function () {
             state.isWatcherReady = true;
         }, function (change) {
+            /**
+             * 通过 WS 将子应用的输出变更上报主应用
+             * - 包含事件类型、源/目标路径、相对路径等
+             * - 主应用端在收到 CHANGE 后增量更新 app.json
+             */
             state.fn = function () {
                 return state.mfeClientServer.sendMessage(E_WS_TYPE.CHANGE, __assign(__assign({}, change), { appCode: manifestJson.value.appCode }));
             };
@@ -1446,6 +1628,10 @@ var createMainAppPlugin = function (manifestJson) {
         copyFilesByTargetPath(sourcePath, targetPath);
     };
     var watchFile = function () {
+        /**
+         * 在非 serve + 主应用构建时，监听所有子应用 Manifest 文件变化
+         * - 变化时重算并写入 app.json，保持主应用 pages 配置最新
+         */
         var allManifest = getAppsManifestList(manifestJson.value.mode);
         var watchFileList = allManifest.map(function (item) { return item.filePath; });
         var watcher = createFileWatcher(watchFileList);
@@ -1471,13 +1657,16 @@ var createMainAppPlugin = function (manifestJson) {
                             start();
                             return [2 /*return*/];
                         }
+                        /**
+                         * 联调开发：启动根应用 WS 服务，负责给子应用下发初始化信息并接收变更事件
+                         */
                         createMainAppServer();
-                        // const subs = findLocalSubApps();
-                        // if (subs.length) {
-                        // startLocalSubApps(subs, "mp-weixin", manifestJson.value.mode);
-                        // }
                     }
                     else {
+                        /**
+                         * 子应用：作为 WS 客户端连接主应用
+                         * - 收到 INIT 后，将自身产物拷贝到主应用分包路径
+                         */
                         state.mfeClientServer = createMainAppClient(manifestJson, function (data) {
                             copyAppDistModule(data);
                         });
@@ -1547,10 +1736,35 @@ var createMainAppPlugin = function (manifestJson) {
     ];
 };
 
+/**
+ * 运行时暴露插件（Exposes）
+ * - 目标：在页面/模块中以 `@dd-code/runtime` 或 `@dd-code/runtime/<name>` 引用主应用的公共导出
+ * - 流程：
+ *   1) configResolved：从主应用 Manifest 读取 exposes 映射（'.'、'./axios' 等）
+ *   2) resolveId：拦截并识别 runtime 请求
+ *   3) load：按请求的子路径拼装 require 代码，指向主应用模块（使用相对路径计算）
+ *   4) buildStart：为每个 exposes 键发射独立的入口 chunk，确保输出到根目录
+ *   5) generateBundle：收集产物映射（fileName + exports），保存到当前 Manifest
+ * - 注意：
+ *   - `RUNTIME_NAME_REGEXP` 用于识别所有 runtime 形式，键以 '.' 开头并支持层级 './xxx'
+ *   - require 的相对路径通过 `renderRuntimeCode` 按当前 appCode + 构建位置计算，保持稳定
+ */
 var buildName = "mfe_runtime/__mfe_{template}_runtime__.js";
 var RUNTIME_NAME = "@dd-code/runtime";
 // const runtimeDir = 'mfe_runtime'
 var RUNTIME_NAME_REGEXP = new RegExp(RUNTIME_NAME + "(/.*)?");
+/**
+ * 生成 runtime 入口代码
+ * - 参数：
+ *   - moduleExpose：主应用 exposes 配置中指定的模块信息（{ path, exports }）
+ *   - appCode：当前应用代码，用于计算运行时代码与目标模块的相对路径
+ * - 相对路径计算：
+ *   - runtime 文件输出位置：mfe_runtime/__mfe_{template}_runtime__.js
+ *   - 运行时代码中 require 的相对路径需指向主应用根下的模块文件（如 store/index.js）
+ *   - deepPath = 相对路径（从 runtime 所在目录到项目根 "."），用于拼接 require('deepPath/<filePath>')
+ * - 导出约定：
+ *   - 仅支持命名导出列表（exports: string[]），以 `export const {name} = require(...)` 形式暴露
+ */
 var renderRuntimeCode = function (moduleExpose, appCode) {
     var deepPath = path.relative(path.join(appCode, path.dirname(buildName)), ".");
     var resultCode = "";
@@ -1568,12 +1782,19 @@ var createExposesPlugin = function (options, currentManifestJson) {
         {
             name: "@chagee:uni-exposes",
             enforce: "post",
+            /**
+             * 读取主应用的 exposes 配置
+             * - 来源：根应用构建时生成的 Manifest（含 exposes 映射）
+             * - 示例：
+             *   { '.': { path: 'store/index.js', exports: ['userStore'] },
+             *     './axios': { path: 'axios/index.js', exports: ['axios'] } }
+             */
             configResolved: function (config) {
                 return __awaiter(this, void 0, void 0, function () {
                     var manifestJson;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
-                            case 0: return [4 /*yield*/, getRootMainManifestJson(currentManifestJson.value.code, currentManifestJson.value.mode)];
+                            case 0: return [4 /*yield*/, getRootMainManifestJson(currentManifestJson.value)];
                             case 1:
                                 manifestJson = _a.sent();
                                 mainAppExposeCode = manifestJson.exposes || {};
@@ -1582,6 +1803,11 @@ var createExposesPlugin = function (options, currentManifestJson) {
                     });
                 });
             },
+            /**
+             * 统一拦截 runtime 引用
+             * - 支持 @dd-code/runtime 与 @dd-code/runtime/<name>
+             * - 返回原始 id，交由 load 钩子生成具体代码
+             */
             resolveId: function (id, importer) {
                 return __awaiter(this, void 0, void 0, function () {
                     return __generator(this, function (_a) {
@@ -1592,6 +1818,11 @@ var createExposesPlugin = function (options, currentManifestJson) {
                     });
                 });
             },
+            /**
+             * 生成运行时代码
+             * - 通过解析 id 获取子路径（'.' 或 './name'）
+             * - 按 exposes 映射找到对应模块与导出列表，拼装 require 代码
+             */
             load: function (id) {
                 return __awaiter(this, void 0, void 0, function () {
                     var matched, deepPath, moduleExpose;
@@ -1606,6 +1837,11 @@ var createExposesPlugin = function (options, currentManifestJson) {
                     });
                 });
             },
+            /**
+             * 为每个 exposes 键发射一个 runtime chunk
+             * - fileName 模板中 {template} 取键名，将非路径字符替换为可用形式（如 './axios' -> '_axios'）
+             * - 保证各入口在输出根目录下具有稳定文件名
+             */
             buildStart: function () {
                 return __awaiter(this, void 0, void 0, function () {
                     var _i, _a, _b, spec, r, id, fileName, fileNameWithoutExt;
@@ -1614,14 +1850,16 @@ var createExposesPlugin = function (options, currentManifestJson) {
                         switch (_c.label) {
                             case 0:
                                 // 显式发射 runtime chunk，确保它被打包到根目录
-                                Object.keys(mainAppExposeCode).forEach(function (key) {
-                                    var keyDir = key.replace(/\./g, "").replace(/\//g, "_");
-                                    _this.emitFile({
-                                        type: "chunk",
-                                        id: path.join(RUNTIME_NAME, key),
-                                        fileName: buildName.replace("{template}", keyDir),
+                                if (!currentManifestJson.value.isRoot) {
+                                    Object.keys(mainAppExposeCode).forEach(function (key) {
+                                        var keyDir = key.replace(/\./g, "").replace(/\//g, "_");
+                                        _this.emitFile({
+                                            type: "chunk",
+                                            id: path.join(RUNTIME_NAME, key),
+                                            fileName: buildName.replace("{template}", keyDir),
+                                        });
                                     });
-                                });
+                                }
                                 _i = 0, _a = Object.entries(options.exposes || {});
                                 _c.label = 1;
                             case 1:
@@ -1649,6 +1887,11 @@ var createExposesPlugin = function (options, currentManifestJson) {
                     });
                 });
             },
+            /**
+             * 产物阶段：收集 exposes 的打包路径与导出列表
+             * - 通过 chunk.modules[moduleId.id] 反查模块所属 chunk
+             * - 保存到当前 Manifest，以便下游消费
+             */
             generateBundle: function (_, bundles) {
                 return __awaiter(this, void 0, void 0, function () {
                     var chunks, resolveIdsMap, _loop_1, this_1, _a, _b, _c, _i, i;
@@ -1707,6 +1950,19 @@ var createExposesPlugin = function (options, currentManifestJson) {
     ];
 };
 
+/**
+ * mp-weixin 平台插件聚合器
+ * - 初始化并维护当前构建的 Manifest 管理器（state + IO）
+ * - 根据模式预清理发布目录并重置 outDir（避免脏数据影响产物）
+ * - 组合注册各业务插件：运行时暴露、资源搬运、Manifest 采集与主应用逻辑
+ * - 插件间通过 `currentManifestJson` 共享上下文（环境、文件列表、依赖、exposes 映射）
+ * - 插件注册顺序：
+ *   1) pre: @dd-code:genre-params（设置环境、重置 outDir）
+ *   2) post: exposes（生成 runtime 入口与 exposes 产物映射）
+ *   3) pre: apps-assets（下载/搬运其它应用资源到主输出目录）
+ *   4) default: manifest-plugin（采集 pages.json 与产物清单）
+ *   5) post: main-app（serve/watch/merge 核心逻辑）
+ */
 var createMpWeixinUniPlugin = function (options) {
     if (options === void 0) { options = {}; }
     var currentManifestJson = createManifestManager();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dd-code/uni-tools",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Universal tools for code utilities",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -14,6 +14,7 @@
   },
   "dependencies": {
     "inquirer": "^12.6.3",
+    "js-yaml": "^4.1.1",
     "@dd-code/shared": "1.0.9"
   },
   "peerDependencies": {