@ttmg/cli 0.4.0 → 0.4.1

package/dist/index.js

@@ -6924,10 +6924,8 @@ function isAxiosError(e) {
 }
 
 const CREATE_DIRECT_FEED_CARD_URL = 'https://developers.tiktok.com/tiktok/v4/devportal/mini_game/fyf_card/create_direct_feed_card';
-const DIRECT_FEED_CARD_HEADERS$2 = {
+const DIRECT_FEED_CARD_HEADERS$3 = {
     'Content-Type': 'application/json',
-    'x-use-ppe': '1',
-    'x-tt-env': 'ppe_feed_play',
 };
 async function createDirectFeedCard({ appId, clientKey, directFeedCard, }) {
     const payload = {
@@ -6938,22 +6936,20 @@ async function createDirectFeedCard({ appId, clientKey, directFeedCard, }) {
     return request({
         url: CREATE_DIRECT_FEED_CARD_URL,
         method: 'POST',
-        headers: DIRECT_FEED_CARD_HEADERS$2,
+        headers: DIRECT_FEED_CARD_HEADERS$3,
         data: payload,
     });
 }
 
 const GET_DIRECT_FEED_SCENARIOS_URL = 'https://developers.tiktok.com/tiktok/v4/devportal/mini_game/fyf_card/get_direct_feed_scenario';
-const DIRECT_FEED_CARD_HEADERS$1 = {
+const DIRECT_FEED_CARD_HEADERS$2 = {
     'Content-Type': 'application/json',
-    'x-use-ppe': '1',
-    'x-tt-env': 'ppe_feed_play',
 };
 async function fetchDirectFeedScenarios({ appId, clientKey, }) {
     return request({
         url: GET_DIRECT_FEED_SCENARIOS_URL,
         method: 'POST',
-        headers: DIRECT_FEED_CARD_HEADERS$1,
+        headers: DIRECT_FEED_CARD_HEADERS$2,
         data: {
             app_id: appId,
             client_key: clientKey,
@@ -6973,16 +6969,14 @@ async function fetchGameAssetPreviewUrl({ assetId, }) {
 }
 
 const GET_DIRECT_FEED_CARD_ASSET_PREVIEW_URL = 'https://developers.tiktok.com/tiktok/v4/devportal/mini_game/fyf_card/get_direct_feed_card_asset_preview_url';
-const DIRECT_FEED_CARD_HEADERS = {
+const DIRECT_FEED_CARD_HEADERS$1 = {
     'Content-Type': 'application/json',
-    'x-use-ppe': '1',
-    'x-tt-env': 'ppe_feed_play',
 };
 async function fetchDirectFeedCardAssetPreviewUrl({ assetId, contentId, }) {
     return request({
         url: GET_DIRECT_FEED_CARD_ASSET_PREVIEW_URL,
         method: 'POST',
-        headers: DIRECT_FEED_CARD_HEADERS,
+        headers: DIRECT_FEED_CARD_HEADERS$1,
         data: {
             asset_id: assetId,
             content_id: contentId,
@@ -7040,8 +7034,6 @@ async function fetchGameInfo(clientKey) {
 const LIST_DIRECT_FEED_CARD_URL = 'https://developers.tiktok.com/tiktok/v4/devportal/mini_game/fyf_card/list_direct_feed_card';
 const LIST_DIRECT_FEED_CARD_HEADERS = {
     'Content-Type': 'application/json',
-    'x-use-ppe': '1',
-    'x-tt-env': 'ppe_feed_play',
 };
 async function listDirectFeedCards({ appId, clientKey, }) {
     return request({
@@ -7055,6 +7047,23 @@ async function listDirectFeedCards({ appId, clientKey, }) {
     });
 }
 
+const CHANGE_DIRECT_FEED_CARD_STATUS_URL = 'https://developers.tiktok.com/tiktok/v4/devportal/mini_game/fyf_card/change_direct_feed_card_status';
+const DIRECT_FEED_CARD_HEADERS = {
+    'Content-Type': 'application/json',
+};
+async function changeDirectFeedCardStatus({ appId, clientKey, contentStatus, }) {
+    return request({
+        url: CHANGE_DIRECT_FEED_CARD_STATUS_URL,
+        method: 'POST',
+        headers: DIRECT_FEED_CARD_HEADERS,
+        data: {
+            app_id: appId,
+            client_key: clientKey,
+            content_status: contentStatus,
+        },
+    });
+}
+
 async function uploadGameToPlatform({ data, name, clientKey, note = '--', appId, }) {
     if (!appId) {
         return {
@@ -9431,6 +9440,49 @@ const gameCheckRoute = {
 };
 
 const changelog = [
+    {
+        title: '0.4.1',
+        target: {
+            iOS: '>=43.1',
+            Android: '>=43.1',
+        },
+        changes: {
+            optimize: [
+                {
+                    desc: {
+                        'zh-CN': '优化上传代码包流程：上传后的平台处理提示改为更易理解的文案，不再向开发者暴露平台内部状态码及 asset / ready 等技术字段，进度与失败原因表达更清晰',
+                        'en-US': 'Improve the code package upload flow: post-upload platform status messages are now easier to understand and no longer expose internal status codes or technical fields like asset / ready, making progress and failure reasons clearer.',
+                    },
+                    module: 'upload',
+                },
+                {
+                    desc: {
+                        'zh-CN': '重构上传成功卡片布局：二维码与版本信息分区展示并以分隔线区隔，新增成功状态标识，排版更紧凑协调',
+                        'en-US': 'Rework the upload success card layout: the QR code and version info are separated into clear sections with a divider, a success indicator is added, and the layout is more compact and balanced.',
+                    },
+                    module: 'upload',
+                },
+            ],
+        },
+    },
+    {
+        title: '0.4.0',
+        target: {
+            iOS: '>=43.1',
+            Android: '>=43.1',
+        },
+        changes: {
+            bugfix: [
+                {
+                    desc: {
+                        'zh-CN': '修复游戏无开发权限时提示信息展示异常的问题，引导更准确',
+                        'en-US': 'Fix incorrect prompt messaging when the developer has no permission to develop the game, providing more accurate guidance.',
+                    },
+                    module: 'detail',
+                },
+            ],
+        },
+    },
     {
         title: '0.3.9',
         target: {
@@ -9912,7 +9964,7 @@ const gameDirectFeedCardAssetPreviewRoute = {
     },
 };
 
-async function resolveAppIdentity$2(body) {
+async function resolveAppIdentity$3(body) {
     const clientKey = body?.clientKey?.trim() ||
         body?.client_key?.trim() ||
         getClientKey().clientKey?.trim();
@@ -9979,7 +10031,7 @@ const gameDirectFeedCardCreateRoute = {
     method: 'post',
     path: '/game/direct-feed-card/create',
     handler: async (req, res) => {
-        const identity = await resolveAppIdentity$2(req.body);
+        const identity = await resolveAppIdentity$3(req.body);
         if (identity.error) {
             res.send({
                 code: errorCode,
@@ -10035,7 +10087,7 @@ function isUsableDirectFeedCard(card) {
     }
     return true;
 }
-async function resolveAppIdentity$1(body) {
+async function resolveAppIdentity$2(body) {
     const clientKey = body?.clientKey?.trim() ||
         body?.client_key?.trim() ||
         getClientKey().clientKey?.trim();
@@ -10080,7 +10132,7 @@ const gameDirectFeedCardListRoute = {
     method: 'post',
     path: '/game/direct-feed-card/list',
     handler: async (req, res) => {
-        const identity = await resolveAppIdentity$1(req.body);
+        const identity = await resolveAppIdentity$2(req.body);
         if (identity.error) {
             res.send({
                 code: errorCode,
@@ -10185,7 +10237,7 @@ function extractScenarioOptions(data) {
     }
     return [];
 }
-async function resolveAppIdentity(body) {
+async function resolveAppIdentity$1(body) {
     const clientKey = body?.clientKey?.trim() ||
         body?.client_key?.trim() ||
         getClientKey().clientKey?.trim();
@@ -10230,7 +10282,7 @@ const gameDirectFeedCardScenariosRoute = {
     method: 'post',
     path: '/game/direct-feed-card/scenarios',
     handler: async (req, res) => {
-        const identity = await resolveAppIdentity(req.body);
+        const identity = await resolveAppIdentity$1(req.body);
         if (identity.error) {
             res.send({
                 code: errorCode,
@@ -10270,6 +10322,112 @@ const gameDirectFeedCardScenariosRoute = {
     },
 };
 
+async function resolveAppIdentity(body) {
+    const clientKey = body?.clientKey?.trim() ||
+        body?.client_key?.trim() ||
+        getClientKey().clientKey?.trim();
+    let appId = body?.appId?.trim() ||
+        body?.app_id?.trim() ||
+        store.getState().appId?.trim();
+    if (!clientKey) {
+        return {
+            clientKey: '',
+            appId,
+            error: 'Missing client key. Please run `ttmg init` or pass `clientKey` from IDE.',
+        };
+    }
+    if (!appId) {
+        const gameInfoResponse = await fetchGameInfo(clientKey);
+        if (gameInfoResponse.error) {
+            return {
+                clientKey,
+                appId: '',
+                error: gameInfoResponse.error,
+            };
+        }
+        appId = gameInfoResponse.data?.app_id?.trim() || '';
+        if (appId) {
+            store.setState({ appId });
+        }
+    }
+    if (!appId) {
+        return {
+            clientKey,
+            appId: '',
+            error: 'Missing app id. Please open project detail first or pass `appId` from IDE.',
+        };
+    }
+    return {
+        clientKey,
+        appId,
+        error: null,
+    };
+}
+function normalizeContentStatus(body) {
+    const source = body?.contentStatus || body?.content_status || {};
+    const contentStatus = Object.entries(source).reduce((result, [contentId, status]) => {
+        const normalizedContentId = String(contentId || '').trim();
+        const normalizedStatus = Number(status);
+        if (normalizedContentId && Number.isFinite(normalizedStatus)) {
+            result[normalizedContentId] = normalizedStatus;
+        }
+        return result;
+    }, {});
+    if (Object.keys(contentStatus).length === 0) {
+        return {
+            contentStatus,
+            error: 'Missing direct-play card status. Please pass a non-empty `contentStatus` from IDE.',
+        };
+    }
+    return {
+        contentStatus,
+        error: null,
+    };
+}
+const gameDirectFeedCardStatusRoute = {
+    method: 'post',
+    path: '/game/direct-feed-card/status',
+    handler: async (req, res) => {
+        const body = req.body;
+        const identity = await resolveAppIdentity(body);
+        if (identity.error) {
+            res.send({
+                code: errorCode,
+                error: identity.error,
+                data: null,
+            });
+            return;
+        }
+        const normalized = normalizeContentStatus(body);
+        if (normalized.error) {
+            res.send({
+                code: errorCode,
+                error: normalized.error,
+                data: null,
+            });
+            return;
+        }
+        const response = await changeDirectFeedCardStatus({
+            appId: identity.appId,
+            clientKey: identity.clientKey,
+            contentStatus: normalized.contentStatus,
+        });
+        if (response.error) {
+            res.send({
+                code: errorCode,
+                error: response.error,
+                ctx: response.ctx,
+            });
+            return;
+        }
+        res.send({
+            code: successCode,
+            data: response.data,
+            ctx: response.ctx,
+        });
+    },
+};
+
 const gameDetailRoute = {
     method: 'get',
     path: '/game/detail',
@@ -11203,36 +11361,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,
@@ -12826,6 +13027,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,
@@ -12838,6 +13339,7 @@ const routes = [
     gameDirectFeedCardCreateRoute,
     gameDirectFeedCardListRoute,
     gameDirectFeedCardScenariosRoute,
+    gameDirectFeedCardStatusRoute,
     gameUploadRoute,
     gameWasmSplitConfigRoute,
     gameWasmSplitOptionsRoute,
@@ -12858,6 +13360,9 @@ const routes = [
     gamePipelineModeRoute,
     gamePipelineModeGetRoute,
     gameLanguageRoute,
+    gamePreloadSubpackagesConfigRoute,
+    gamePreloadSubpackageCandidatesRoute,
+    gameCollectPreloadSubpackagesRoute,
 ];
 /**
  * Express 4 does not catch rejections from async route handlers — an
@@ -13358,7 +13863,7 @@ async function upload({ clientKey, note = '--', dir, }) {
     }
 }
 
-var version = "0.4.0";
+var version = "0.4.1";
 var pkg = {
 	version: version};