@ttmg/cli 0.4.0-beta.1 → 0.4.1-beta.wasm1

package/CHANGELOG.md

@@ -0,0 +1,256 @@
+## 0.1.0
+
+发布正式版本，支持 H5 小游戏和原生小游戏的初始化、开发调试和打包构建。支持 Windows 系统
+
+## 0.1.0-beta.1
+
+移除 Client WS 端口和 Http 端口默认 -1 的配置，变成通过和 Node CLI 通信显示发端口
+
+## 0.1.0-beta.8
+
+支持自动打开浏览器，且聚焦在 devTools 窗口
+
+## 0.1.0-beta.9
+
+1. 支持文件上传进度显示
+2. 支持自动打开浏览器调试模式
+
+## 0.1.0-beta.10
+
+fix: 修复还未完成新编译就直接上传了的问题
+
+## 0.1.0-beta.11
+
+feat: 先关闭自动上传能力
+
+## 0.1.0-beta.12
+
+feat: 支持文件变更监听，告知浏览器文件变更，提醒开发者重新加载游戏
+
+## 0.1.0-beta.13
+
+1. 支持 sourcemap
+2. 优化上传环节产物，过滤 sourcemap 文件，提高上传效率
+
+## 0.1.0-beta.14
+
+1. 修复 client key 未成功写入 mock meta 的问题，导致不一致
+
+## 0.1.0-beta.15
+
+1. 还原 open url 历史方法
+
+## 0.1.1
+
+发布最新版本，提醒开发者升级最新版本
+
+## 0.1.2
+
+发布最新版本，支持 sourcemap
+
+## 0.1.3-beta.1
+
+优化显示二维码问题
+
+## 0.1.3-beta.2
+
+彻底修复二维码兼容问题
+
+## 0.1.3-beta.3
+
+修复 sourcemap 错乱问题
+
+## 0.1.3-beta.4
+
+修复循环依赖问题
+
+## 0.1.3-beta.5
+
+修复监听文件变化报错问题
+
+## 0.1.3
+
+发布优化版本 CLI
+
+## 0.1.4
+
+优化页面交互
+
+## 0.1.5
+
+1.fix: 控制台报错问题 2. feat: 优化
+
+## 0.1.6
+
+1. 优化控制台报错日志
+2. 优化调试启动环节耗时
+
+## 0.1.7
+
+- 修复 Windows 调试资源加载失败问题
+
+## 0.1.8
+
+优化 DevTool 网页端启动时间
+
+## 0.1.9-beta.1
+
+发布测试版本，供客户端调试使用
+
+## 0.1.9-beta.2
+
+发布测试版本，用于 Windows 测试
+
+## 0.1.9
+
+发布正式版本，支持
+
+- login
+- 支持上传游戏包
+- 支持启动模式
+- 支持 Debug Settings
+
+## 0.2.0-beta.1
+
+发布测试版本，用于 Windows 测试 login 登录异常逻辑
+
+## 0.2.0
+
+发布正式版本，支持 Windows 登录加载报错提示
+
+## 0.2.1
+
+1. 移除项目详情部分，比较冗余，不常用，融合到代码预检中
+2. 打开调试页面地址增加 version 参数，来规避新老版本缓存问题和不同网页之间的隔离（未来支持）
+3. 优化登录失败提示，增加网络检查提示，并给出如何修改网络设置的文档链接
+4. 补充发送 meta 至客户端链路，增加调试链路日志信息，便于排查问题
+
+## 0.2.2
+
+1. 修复访问无权限的小游戏，顶部报错问题
+
+## 0.2.3
+
+优化扫码连接不上问题，支持手动绑定电脑本地 IP 地址
+
+## 0.2.4
+
+支持新的 DevTool 平台
+
+## 0.2.5
+
+1. 增加不在游戏根目录启动调试校验
+2. 支持手动绑定客户端 IP 地址和端口
+3. 调整启动模式中的场景列表表达文案
+4. 修复文件上传问题，避免偶现上传失败
+5. 支持展示游戏详情模块，支持开发者查看当前小游戏基本信息
+6. 支持调试环节消费平台配置的域名
+7. 升级 ttmg-pack 0.1.7，修复构建环节对开发者 JS 代码降级的问题
+8. 文档新增常见问题部分，替换原有的开发文档
+
+## 0.2.6
+
+修复启动模式中场景列表展示问题，重复展示默认启动模式
+
+## 0.2.7
+1. 升级 ttmg-pack 0.2.3，调整 esbuild 配置，目标 es2020
+2. 支持校验子包配置文件名是否符合规范，对于非法文件名，提示开发者修改
+3. 调整域名校验默认逻辑，默认开启，校验失败时，提示开发者修改
+
+## 0.2.8
+1. 升级 ttmg-pack 0.2.4，修复 open data context 文件丢失问题
+
+## 0.2.9
+1. 升级 ttmg-pack 0.2.5，修复 open data context 打包问题
+## 0.3.0
+新增/优化功能适用 TikTok 版本 iOS >=43.1 | Android>=43.1
+支持了开发信息蒙层，打开后可以查看游戏 FPS、设备信息、调试开关等信息，便于查看游戏运行状态 了解如何使用
+支持删除历史启动模式，便于管理历史启动模式
+调整调试设置模块名称为开发选项，和客户端内调开发者选项保持一致 了解如何使用
+调试设置新增定义 vConsole 和 开发信息浮层设置
+支持了变更日志，用户可以在调试环境下查看游戏的变更记录，部分新功能可通过更多信息查看使用
+支持了调试设置开关本地缓存，避免每次都需要重新设置
+修复上传名称为中文的游戏时，平台展示乱码的问题
+修复启动模式模块，自定义query 参数无法持久化的问题
+修复扫描二维码模块，内容过多，纵向无法滚动问题
+
+## 0.3.1
+- 支持 unity 小游戏本地一些列调试功能，如 Wasm 分包、包大小校验、一键上传代码包至平台等 了解如何使用
+- 增加用户登录过期的异常提示，提醒开发者重新登录
+- 优化上传代码包至平台功能，开发者只用添加描述后点击上传便可自动压缩当前目录下的代码包上传至开发者平台
+- 优化 ttmg login 终端网络代理异常导致无法登录的报错引导，提示用户检查网络设置
+
+## 0.3.2-beta.1
+支持 cocos 2.0 openDataContext 相关适配
+
+## 0.3.2
+- 小游戏详情查询升级到 TikTok DevPortal v4 `devtool/info` 接口，字段映射更完整
+- 支持一键打包当前目录并上传代码包到开发者平台；上传失败提示更明确，文件名非法字符自动处理
+- Unity Wasm 分包：更新 `game.json` 子包配置写入逻辑（兼容 `subpackages`/`subPackages` 字段），Android/iOS main/sub 配置去重合并
+- 启动校验增强：检查是否在小游戏根目录执行，并提示 `subPackages` 拼写错误
+增加对 unity 是否需要分包的检查，对于需要分包的 unity 项目，给出明确提示
+支持通过 `ttmg setup` 配置 CLI 语言，调试环境会跟随语言设置展示文案，首次调试时会自动同步默认语言，后续 CLI 与 IDE 语言保持一致，减少反复切换
+调试与预检支持多语言展示，关键提示与校验信息更易理解
+支持 Cocos 2.0 openDataContext 配置
+变更记录新增提醒功能，当有新版本发布时，会通过弹窗提醒开发者更新
+ttmg login 支持 ttmg login --verbose 参数，打印更多登录信息
+API 预检建议文案统一收敛，避免重复提示，阅读更清晰
+顶部区域透出项目预检错误与警告信息，便于开发者及时发现问题并修复
+语言选择策略优化：优先使用 CLI 本地设置，未设置时自动回退浏览器语言
+启动校验增强：检查是否在小游戏根目录执行，对于分包配置 subPackages 给出明确报错，引导开发者修改为 subpackages
+修复项目详情中展示的主包大小限制和代码预检不一致的情况
+
+## 0.3.3
+升级 ttmg-pack 到 0.4.5，解决安卓无法调试 unity 项目问题
+
+## 0.3.4
+优化校验逻辑，给出提示
+
+## 0.3.5
+优化连接和代理，帮助开发者自助解决问题
+
+## 0.3.6
+修复分包过程超时问题
+
+## 0.3.7
+新增/优化功能适用 TikTok 版本 iOS >=43.1 | Android >=43.1
+
+1. 新增能力接入助手，帮助开发者基于小游戏变现类型获取关键能力的接入引导。
+2. 优化上传发布环节，将代码预检与代码上传整合为完整的上传发布流程。
+3. 扩充包体大小预检说明，补充整包、主包、独立分包限制规则与详细文档入口，便于开发者理解和处理包体超限问题。
+
+## 0.3.8
+修复 `ttmg login` 后接口鉴权异常的问题：
+
+1. 登录时把 `Set-Cookie` 响应头中的 `Path / Domain / Max-Age / Expires / Secure / HttpOnly / SameSite` 等属性被当成 cookie 拼接到 `Cookie` 字段，导致 CLI 发请求时把属性当成"假 cookie"一并带上。
+2. 同一域名下同名 cookie（例如服务端用 `Max-Age=0` 显式删除的占位 cookie）也会被一起发送，污染掉真正有效的同名 cookie，浏览器会自动过滤这种情况，CLI 不会，造成登录态接口异常。
+3. 修复后与浏览器行为保持一致：剥离 cookie 属性、过滤 `Max-Age<=0` 或 `Expires` 已过期的 cookie，仅保留 `name=value` 用于请求。
+4. 已登录用户无需重新登录，下次发起请求时会自动清洗 rc 中已存的脏数据。
+
+## 0.3.9
+本次主要优化调试 IDE 的视觉、交互与多语言一致性：
+
+1. 调试 IDE 默认使用浅色主题，暗色模式改为开发者手动开启并记忆选择，避免跟随系统强制进入暗色导致不适应。
+2. 优化暗色模式下二维码显示，调整背景避免过亮刺眼，同时保证扫码识别率。
+3. Wasm 分包页面及相关组件补齐多语言，修复此前页面文案中英文混排的问题。
+4. 能力接入助手页面视觉升级：变现模式卡片新增图标与强调色，关键能力标签按「必需 / 可选 / 实验」分级展示，信息层级更清晰。
+5. 完成扫码连接后，首页标题与说明文案会切换为「已连接」状态，状态反馈更明确。
+6. 新版本提示由红点改为「有更新」文字标签，含义更直观。
+7. 上传游戏包按钮配色与产品主题色统一。
+8. 修复多个页面中标题与正文内容未对齐的问题，整体排版更整齐。
+9. 文案细节调整：「身份与授权」更名为「登录与授权」；移除侧边栏冗余的「查看文档」入口。
+
+## 0.3.9-beta.1
+本次测试版本主要补充启动模式场景能力，并优化场景命名可理解性：
+
+1. 启动模式新增 `inbox` 场景，支持在调试链路中模拟消息入口启动小游戏。
+
+## 0.4.0-beta.1
+
+本次测试版本主要补充直玩卡调试与上线链路，并优化能力接入助手体验：
+
+1. 能力接入助手的直玩卡联调流程扩展为三个阶段：先调试游戏包本身，再生成预览二维码验证卡面和承接路径，最后管理已验证直玩卡的上线状态。
+2. 阶段三新增「上线 / 下线直玩卡」能力，复用阶段二选中的直玩卡内容，调用平台接口修改直玩卡线上状态。
+3. 阶段三保留卡片名称、Content ID、场景、启动包、Queries 等信息，并单独展示「上线状态」，避免与阶段二「审核状态」混淆。
+4. 已上线卡片会展示「下线直玩卡」操作，未上线卡片展示「上线直玩卡」操作，确认后刷新最新线上状态。
+5. 优化直玩卡调试页面的区块间距，修复操作按钮与信息面板贴得过近的问题。

package/dist/index.js

@@ -11318,36 +11318,79 @@ async function startSplit$1({ client_key, wasm_md5, }) {
             ctx: { logid: 'local', httpStatusCode: 400 },
         };
     }
+    // ── Local boot-miss feedback (no server change) ──────────────────────
+    // The runtime logs every sub-package function it had to pull in BEFORE the
+    // first frame as `[wasmcode2] ... firstFrame=BEFORE` — each one is a
+    // first-screen hitch. Drop those func ids into
+    // `__TTMG_TEMP__/boot_extra_func_ids.txt` (one per line) and they get
+    // merged into `alwaysInclude` so the next split pins them into the main
+    // package, closing the gap WITHOUT re-enabling the indirect-closure flood.
+    // No-op when the file is absent.
+    const bootExtraPath = path$1.join(tempDir, 'boot_extra_func_ids.txt');
+    let bootExtra = [];
+    if (fs$1.existsSync(bootExtraPath)) {
+        bootExtra = fs$1
+            .readFileSync(bootExtraPath, 'utf-8')
+            .split('\n')
+            .map(l => parseInt(l.trim(), 10))
+            .filter(n => Number.isInteger(n) && n > 0);
+    }
+    const alwaysIncludeIds = Array.from(new Set([...bootFuncIds, ...bootExtra]));
+    // ── Collect coverage signal ──────────────────────────────────────────
+    // With the indirect-call closure off, the main package ≈ the collected
+    // set, so collect coverage now directly determines first-screen safety.
+    // Surface it, and warn (never block) when it looks too thin to cover boot.
+    const totalFuncs = Number(getGameJson()?.wasmFuncCount) || getLocalState().totalWasmFuncCount || 0;
+    const coveragePct = totalFuncs ? (funcIds.length / totalFuncs) * 100 : 0;
     verboseLog(`[wasmtool] splitting with ${funcIds.length} func IDs` +
+        ` (coverage ${coveragePct.toFixed(1)}% of ${totalFuncs})` +
         (bootFuncIds.length > 0
-            ? `, ${bootFuncIds.length} boot-phase func IDs (→ alwaysInclude)`
-            : ', no boot-phase info (legacy server, falling back to callClosure only)') +
-        `, archive=${archive}`);
+            ? `, ${bootFuncIds.length} boot-phase func IDs`
+            : ', no boot-phase info (legacy server, relying on collect + callClosure)') +
+        (bootExtra.length > 0 ? `, +${bootExtra.length} boot-extra(local)` : '') +
+        `, ${alwaysIncludeIds.length} → alwaysInclude, archive=${archive}`);
+    // THIN_COLLECT_FLOOR is a heuristic, not a hard rule — tune from real
+    // first-screen sizes. Warn-only: a thin collect with no boot hints means
+    // first-screen functions may be served from the sub package before the
+    // first frame (a visible hitch).
+    const THIN_COLLECT_FLOOR = 8000;
+    if (alwaysIncludeIds.length === 0 && funcIds.length < THIN_COLLECT_FLOOR) {
+        verboseWarn(`[wasmtool] collect looks thin (${funcIds.length} funcs, no boot hints). ` +
+            `First package may miss first-screen functions → pre-first-frame sub-package loads. ` +
+            `Collect more scenarios (resume) before splitting, or add ids to ${bootExtraPath}.`);
+    }
     try {
         const result = ttmgWasmtool.split({
             input: rawWasmPath,
             funcIds,
-            // Boot-phase func ids → `alwaysInclude`. They are a subset of
-            // `funcIds` so this doesn't grow `collect_count`, but it DOES seed
-            // the direct-call closure BFS with the exact set needed for first
-            // frame, and the split tool's `alwaysIncludeAdded` counter is the
-            // observability signal when zero (= server didn't return boot info).
-            alwaysInclude: bootFuncIds.length > 0 ? bootFuncIds : undefined,
+            // Boot-phase func ids (server) ∪ local boot-extra feedback →
+            // `alwaysInclude`. These seed the direct-call closure BFS with the
+            // exact set needed for the first frame and force first-screen
+            // functions into main; the split tool's `alwaysIncludeAdded` counter
+            // is the observability signal (0 = no boot hints from any source).
+            alwaysInclude: alwaysIncludeIds.length > 0 ? alwaysIncludeIds : undefined,
             // Always-on direct-call closure over (collect ∪ alwaysInclude ∪
             // start_func). Folds in func ids that collect missed (untaken
             // branches, race conditions during collect) so first-screen code
             // paths don't trap on archive trampolines. See the split tool's
             // `closure_added` counter for the per-build size impact.
             callClosure: true,
-            // Always-on indirect-call type-closure scoped to the boot subset.
-            // Catches IL2CPP virtual / interface / delegate dispatch which is
-            // the dominant source of remaining `firstFrame=BEFORE` archive
-            // trampoline hits after the runtime collect + direct closure
-            // passes (see `indirectClosureAdded` for the per-build size
-            // impact). Defaults to `true` in the wasmtool but we set it
-            // explicitly so a future tool default change can't silently turn
-            // it off in our pipeline.
-            callIndirectClosure: true,
+            // OFF: the indirect-call type-closure is a static over-approximation
+            // that pulls EVERY table function whose signature matches one used by
+            // a boot root. In IL2CPP builds ~90% of functions live in the indirect
+            // table and share only a few hundred signatures, so any non-trivial
+            // boot set touches them all and this broadcasts almost the entire
+            // module into main — measured ~135k/136k funcs (~50MB) main, defeating
+            // the split. First-screen indirect-call targets are instead covered
+            // precisely by the runtime collect (logCall is injected into every
+            // function body, so any function that actually runs before first frame
+            // — including call_indirect targets — is already in `funcIds`) plus the
+            // direct-call closure and `alwaysInclude`. Any residual first-frame
+            // indirect hit is served on-demand by the archive loader at runtime;
+            // keep those rare by improving collect-session coverage, not by
+            // re-enabling this flood. Set explicitly so the wasmtool default
+            // (currently `true`) can't silently turn it back on.
+            callIndirectClosure: false,
             outputDir: splitOutputDir,
             archive,
             compress: true,
@@ -12941,6 +12984,306 @@ const gamePipelineModeGetRoute = {
     },
 };
 
+/**
+ * 启动链路子包收集 —— DevTool CLI 侧契约类型。
+ *
+ * 协议字段与设计方案保持一致（见
+ * topics/performance/startup-subpackage-collection-technical-design.md）。
+ * `entry` 在协议层用单字段 name 表示：主包入口为内部约定 `__GAME__`，
+ * 独立分包入口为该独立分包在源码 `subpackages[]` 中的 name。
+ */
+/** 平台内部主包标识，只活在 DevTool / 客户端 / 编译服务等平台组件之间。 */
+const GAME_ENTRY = '__GAME__';
+/** 启动子包预下载配置字段名（源码侧 + 编译产物侧同名）。 */
+const PRELOAD_FIELD_NAME = 'parallelPreloadSubpackages';
+
+/**
+ * 从磁盘**新鲜读取**源码 game.json（不走 getGameJson 缓存，因为本流程要写）。
+ * game.json 不存在或解析失败时抛错，由上层转成 failed 状态。
+ */
+function readRawGameJson() {
+    const filePath = path__namespace.join(process.cwd(), SUBPACKAGE_CONFIG_FILE_NAME);
+    if (!fs__namespace.existsSync(filePath)) {
+        throw new Error('game.json 不存在');
+    }
+    const raw = fs__namespace.readFileSync(filePath, 'utf-8');
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('game.json 解析失败');
+    }
+    const subpackagesField = SUBPACKAGE_FIELD_NAMES.find(k => Array.isArray(json[k])) ??
+        SUBPACKAGE_FIELD_NAMES[0];
+    return { filePath, raw, json, subpackagesField };
+}
+/** 只读读取一份 game.json；不存在 / 解析失败时返回 null，不抛错。 */
+function tryReadGameJson() {
+    try {
+        return readRawGameJson();
+    }
+    catch {
+        return null;
+    }
+}
+/** 取 subpackages 数组（保证返回数组）。 */
+function getSubpackages(game) {
+    const list = game.json[game.subpackagesField];
+    return Array.isArray(list) ? list : [];
+}
+/** 按 name 在 subpackages[] 中定位 entry。 */
+function findSubpackage(game, name) {
+    return getSubpackages(game).find(s => s?.name === name);
+}
+/**
+ * 把对象就地写回磁盘，沿用仓库 JSON 缩进 / 换行约定。
+ */
+function writeGameJson(game) {
+    fs__namespace.writeFileSync(game.filePath, JSON.stringify(game.json, null, JSON_INDENT) + JSON_EOL);
+}
+/** 失败回滚：把原始文本原样写回。 */
+function restoreGameJson(game) {
+    fs__namespace.writeFileSync(game.filePath, game.raw);
+}
+/** entry 是否为主包入口。 */
+function isGameEntry(entry) {
+    return entry === GAME_ENTRY;
+}
+
+/**
+ * 写入前校验：通用规则 + 独立分包入口增量规则。
+ * 任意一条不满足直接抛 Error（上层转 failed，不写 game.json）。
+ * 返回过滤掉防御性条目后的待写入列表（含 root）。
+ */
+function validateCollect(game, entry, reported) {
+    const subpackages = getSubpackages(game);
+    if (!Array.isArray(game.json[game.subpackagesField])) {
+        throw new Error('game.json.subpackages 缺失或不是数组');
+    }
+    // 独立分包入口增量校验
+    if (!isGameEntry(entry)) {
+        const entryPkg = findSubpackage(game, entry);
+        if (!entryPkg) {
+            throw new Error(`独立分包入口 ${entry} 不存在于 game.json.subpackages`);
+        }
+        if (entryPkg.independent !== true) {
+            throw new Error(`入口 ${entry} 不是独立分包（independent !== true），不可作为启动入口采集`);
+        }
+    }
+    const nameToPkg = new Map(subpackages.map(s => [s?.name, s]));
+    const result = [];
+    const seen = new Set();
+    for (const item of reported) {
+        const subPkgName = item?.subPkgName;
+        // 客户端不应上报 __GAME__ 作为子包名：防御性忽略，不入库、不阻塞
+        if (!subPkgName || subPkgName === GAME_ENTRY) {
+            continue;
+        }
+        // 独立分包不预下载自己
+        if (!isGameEntry(entry) && subPkgName === entry) {
+            throw new Error(`独立分包入口 ${entry} 不能预下载自身`);
+        }
+        if (seen.has(subPkgName)) {
+            continue;
+        }
+        seen.add(subPkgName);
+        const pkg = nameToPkg.get(subPkgName);
+        if (!pkg) {
+            throw new Error(`子包 ${subPkgName} 未定义在 game.json.subpackages`);
+        }
+        if (!pkg.root || typeof pkg.root !== 'string') {
+            throw new Error(`子包 ${subPkgName} 缺少 root 字段`);
+        }
+        const absDir = path__namespace.isAbsolute(pkg.root)
+            ? pkg.root
+            : path__namespace.join(process.cwd(), pkg.root);
+        if (!fs__namespace.existsSync(absDir) || !fs__namespace.statSync(absDir).isDirectory()) {
+            throw new Error(`子包 ${subPkgName} 的目录不存在：${pkg.root}`);
+        }
+        result.push({
+            subPkgName,
+            isStartup: !!item.isStartup,
+            root: pkg.root,
+        });
+    }
+    return result;
+}
+
+/** 读出某个 entry 当前的 parallelPreloadSubpackages（保证返回数组）。 */
+function readEntryConfig(game, entry) {
+    const container = isGameEntry(entry)
+        ? game.json
+        : findSubpackage(game, entry);
+    const list = container?.[PRELOAD_FIELD_NAME];
+    return Array.isArray(list) ? list : [];
+}
+/**
+ * 按 entry 只读读取源码 game.json 中已有的 parallelPreloadSubpackages，
+ * 用于 UI 初始化配置预览。game.json 不存在 / 字段缺失时返回空数组，不阻塞。
+ */
+function readPreloadSubpackagesConfig(entry) {
+    const game = tryReadGameJson();
+    if (!game) {
+        return { entry, parallelPreloadSubpackages: [] };
+    }
+    return { entry, parallelPreloadSubpackages: readEntryConfig(game, entry) };
+}
+/**
+ * 列出某个 entry 下可被采集（可预下载）的候选子包，供 UI 基于真实可用包选择。
+ *
+ * 候选 = game.json.subpackages 中 root 目录真实存在、且 name 不等于当前 entry
+ * 的子包（独立分包入口不可预下载自身）。仅供 mock 上报基于真实可用包选择，
+ * 不含 size —— size 在编译期由 ttmg-compile 按压缩加密后体积回填。
+ * game.json 不存在 / 字段缺失时返回空数组，不阻塞。
+ */
+function listPreloadSubpackageCandidates(entry) {
+    const game = tryReadGameJson();
+    if (!game) {
+        return { entry, candidates: [], totalSubpackages: 0 };
+    }
+    const subpackages = getSubpackages(game);
+    const candidates = [];
+    for (const sub of subpackages) {
+        const subPkgName = sub?.name;
+        const root = sub?.root;
+        if (typeof subPkgName !== 'string' || !subPkgName)
+            continue;
+        if (subPkgName === entry)
+            continue;
+        if (typeof root !== 'string' || !root)
+            continue;
+        const absDir = path__namespace.isAbsolute(root)
+            ? root
+            : path__namespace.join(process.cwd(), root);
+        if (!fs__namespace.existsSync(absDir) || !fs__namespace.statSync(absDir).isDirectory())
+            continue;
+        candidates.push({
+            subPkgName,
+            root,
+            independent: sub.independent === true,
+        });
+    }
+    return { entry, candidates, totalSubpackages: subpackages.length };
+}
+/**
+ * 收集快照写入：校验 → 按 entry 覆盖写入对应位置 → 失败回滚。
+ *
+ * 只写入 `subPkgName` + `isStartup`，**不写 size**：size 是压缩+加密后的真实
+ * 下发体积，由编译服务（ttmg-compile）在产出 STTPKG 时回填到编译产物，收集期
+ * 拿不到也不写（见技术方案 3.4 / 3.5）。
+ *
+ * - 写入前校验失败：抛错，不修改 game.json。
+ * - 进入写入阶段后异常：回滚原始 game.json 再抛错。
+ * 返回本次 entry 下最终写入的 parallelPreloadSubpackages。
+ */
+function collectPreloadSubpackages(entry, reported) {
+    // readRawGameJson 抛错即「game.json 不存在 / 解析失败」，写入前阶段，不动文件
+    const game = readRawGameJson();
+    const validated = validateCollect(game, entry, reported);
+    const parallelPreloadSubpackages = validated.map(item => ({
+        subPkgName: item.subPkgName,
+        isStartup: item.isStartup,
+    }));
+    let started = false;
+    try {
+        const container = isGameEntry(entry)
+            ? game.json
+            : findSubpackage(game, entry);
+        if (!container) {
+            // 独立分包入口已在 validate 阶段确认存在，这里是防御
+            throw new Error(`入口 ${entry} 不存在`);
+        }
+        started = true;
+        container[PRELOAD_FIELD_NAME] = parallelPreloadSubpackages;
+        writeGameJson(game);
+    }
+    catch (err) {
+        if (started) {
+            restoreGameJson(game);
+        }
+        throw err;
+    }
+    return { entry, parallelPreloadSubpackages };
+}
+
+/**
+ * 读取某个启动入口已有的 parallelPreloadSubpackages（只读），用于 UI 初始化
+ * 配置预览。对应设计方案的 `getPreloadSubpackagesConfig`。
+ *
+ * query: `entry`（缺省按主包 `__GAME__` 处理）。
+ */
+const gamePreloadSubpackagesConfigRoute = {
+    method: 'get',
+    path: '/game/preload-subpackages-config',
+    handler: async (req, res) => {
+        const entry = req.query.entry || GAME_ENTRY;
+        try {
+            const data = readPreloadSubpackagesConfig(entry);
+            res.send({ code: successCode, data });
+        }
+        catch (err) {
+            res.send({
+                code: errorCode,
+                error: { message: err.message },
+            });
+        }
+    },
+};
+
+/**
+ * 列出某个启动入口下可被采集（可预下载）的候选子包，供 UI mock 上报时
+ * 基于真实可用包选择，而不是手填名字。候选直接来自 game.json.subpackages
+ * 中 root 真实存在、name 不等于当前 entry 的子包，并附带压缩前体积。
+ *
+ * query: `entry`（缺省按主包 `__GAME__` 处理）。
+ */
+const gamePreloadSubpackageCandidatesRoute = {
+    method: 'get',
+    path: '/game/preload-subpackage-candidates',
+    handler: async (req, res) => {
+        const entry = req.query.entry || GAME_ENTRY;
+        try {
+            const data = listPreloadSubpackageCandidates(entry);
+            res.send({ code: successCode, data });
+        }
+        catch (err) {
+            res.send({
+                code: errorCode,
+                error: { message: err.message },
+            });
+        }
+    },
+};
+
+/**
+ * 收集快照写入：按 entry 校验 + 补体积 + 覆盖写入源码 game.json 对应位置，
+ * 失败回滚。对应设计方案的 `collectPreloadSubpackages` /
+ * `updatePreloadSubpackagesConfig`（HTTP 请求-响应实现，start 态由 UI 自身的
+ * 处理中状态承载，CLI 只回 success / failed）。
+ *
+ * body: `{ entry, subpackages: [{ subPkgName, isStartup }] }`。
+ */
+const gameCollectPreloadSubpackagesRoute = {
+    method: 'post',
+    path: '/game/collect-preload-subpackages',
+    handler: async (req, res) => {
+        const entry = req.body?.entry || GAME_ENTRY;
+        const subpackages = req.body?.subpackages || [];
+        console.log('collect-preload-subpackages', { entry, count: subpackages.length });
+        try {
+            const data = collectPreloadSubpackages(entry, subpackages);
+            res.send({ code: successCode, data });
+        }
+        catch (err) {
+            res.send({
+                code: errorCode,
+                error: { message: err.message },
+            });
+        }
+    },
+};
+
 const routes = [
     gameAssetPreviewUrlRoute,
     gameAssetsRoute,
@@ -12974,6 +13317,9 @@ const routes = [
     gamePipelineModeRoute,
     gamePipelineModeGetRoute,
     gameLanguageRoute,
+    gamePreloadSubpackagesConfigRoute,
+    gamePreloadSubpackageCandidatesRoute,
+    gameCollectPreloadSubpackagesRoute,
 ];
 /**
  * Express 4 does not catch rejections from async route handlers — an
@@ -13474,7 +13820,7 @@ async function upload({ clientKey, note = '--', dir, }) {
     }
 }
 
-var version = "0.4.0-beta.1";
+var version = "0.4.1-beta.wasm1";
 var pkg = {
 	version: version};