@ttmg/cli 0.3.9-beta.wasm.1 → 0.4.0

package/dist/index.js

@@ -6588,9 +6588,30 @@ function buildCookieHeaderFromSetCookies(setCookies) {
     return sanitizeCookieHeader(setCookies.join('; '));
 }
 
+/**
+ * Verbose logging helpers.
+ *
+ * The CLI registers a global `--verbose` flag (see `src/index.ts`). Detailed
+ * diagnostic logs — HTTP request/response bodies, the local wasm split
+ * pipeline's `[wasmtool]` / `[wasm-split]` / `[download]` breadcrumbs — should
+ * only surface when the user explicitly opts in, so the default `ttmg dev`
+ * output stays readable.
+ *
+ * Genuine failures must keep using `console.error` directly so they are always
+ * visible regardless of `--verbose`.
+ */
 function isVerboseEnabled() {
     return process.argv.includes('--verbose');
 }
+function verboseLog(...args) {
+    if (isVerboseEnabled())
+        console.log(...args);
+}
+function verboseWarn(...args) {
+    if (isVerboseEnabled())
+        console.warn(...args);
+}
+
 /**
  * PPE / 测试环境开关。
  *
@@ -6749,7 +6770,7 @@ function printApiResponseLog(title, result) {
         ['Return Value', result.data],
     ]);
 }
-async function request({ url, method, data, headers, params, }) {
+async function request({ url, method, data, headers, params, logRequestBody = true, }) {
     const config = getTTMGRC();
     const cookie = sanitizeCookieHeader(config?.cookie);
     const proxyConfig = getAxiosProxyConfig();
@@ -6757,7 +6778,9 @@ async function request({ url, method, data, headers, params, }) {
         printApiRequestLog({
             url,
             method,
-            params: getRequestParams(params, data),
+            params: logRequestBody
+                ? getRequestParams(params, data)
+                : '[omitted: large request body]',
         });
     }
     try {
@@ -6821,7 +6844,7 @@ async function download(url, filePath) {
         catch { }
     }
     const proxyConfig = getAxiosProxyConfig();
-    console.log('[download] start', { url: url.slice(0, 120), filePath, hasProxy: !!proxyConfig.httpsAgent });
+    verboseLog('[download] start', { url: url.slice(0, 120), filePath, hasProxy: !!proxyConfig.httpsAgent });
     try {
         const res = await axios.get(url, {
             responseType: 'stream',
@@ -6857,7 +6880,7 @@ async function download(url, filePath) {
             };
             const onClose = () => {
                 cleanup();
-                console.log(`[download] done: ${received} bytes in ${Date.now() - startedAt}ms`);
+                verboseLog(`[download] done: ${received} bytes in ${Date.now() - startedAt}ms`);
                 resolve();
             };
             const cleanup = () => {
@@ -6875,7 +6898,7 @@ async function download(url, filePath) {
                     const pct = Math.floor((received / total) * 10) * 10;
                     if (pct !== lastLoggedPct) {
                         lastLoggedPct = pct;
-                        console.log(`[download] ${pct}% (${received}/${total})`);
+                        verboseLog(`[download] ${pct}% (${received}/${total})`);
                     }
                 }
             };
@@ -6889,7 +6912,7 @@ async function download(url, filePath) {
         return { ok: true };
     }
     catch (err) {
-        console.log('[download] failed:', err?.message);
+        verboseLog('[download] failed:', err?.message);
         if (isAxiosError(err) && err.response?.status === 403) {
             throw new Error('下载链接已过期，请重新进行分包后重试');
         }
@@ -8349,8 +8372,81 @@ async function compile(context) {
 }
 
 // import { uploadGame } from './uploadGame';
+/* ---------------------------------------------------------------------------
+ * Watch suspension control
+ *
+ * The wasm-split pipeline (prepare / split download / rollback) intentionally
+ * rewrites a burst of project files — the instrumented wasm, the `wasmcode*`
+ * subpackage dirs, `game.json`, `webgl-wasm-split.js`. Without gating, every
+ * one of those writes trips the watcher below, and each trip runs a full
+ * `compile` + device `resourceChange` reload *in the middle of the pipeline*.
+ * That both wastes cycles and can reload the device onto a half-written /
+ * transient build. We suspend the watcher around those operations and fire
+ * exactly one update after they complete ("完成之后再触发更新").
+ *
+ * `suspendDepth` is a refcount so overlapping / nested operations are safe.
+ * `muteUntil` keeps swallowing events for a short cooldown AFTER resume:
+ * chokidar's `awaitWriteFinish` delays events ~1s past the actual write, so
+ * those late events from our own writes would otherwise land after we've
+ * resumed and re-trigger the very reload we just suppressed.
+ * ------------------------------------------------------------------------- */
+let suspendDepth = 0;
+let muteUntil = 0;
+let pendingWhileSuspended = false;
+// chokidar awaitWriteFinish stabilityThreshold (1000ms) + headroom, so the
+// delayed FS events caused by the pipeline's own writes are swallowed.
+const RESUME_COOLDOWN_MS = 2500;
+// Wired up inside `watch()` so suspend/resume can reuse the exact same
+// (debounced) compile + resourceChange action the watcher fires normally.
+let triggerUpdate = null;
+function suspendWatch() {
+    suspendDepth += 1;
+}
+function resumeWatch(options = {}) {
+    if (suspendDepth > 0) {
+        suspendDepth -= 1;
+    }
+    if (suspendDepth > 0) {
+        return;
+    }
+    // Back to depth 0 — start the cooldown that swallows our own delayed FS
+    // events, then emit a single update if anything changed while suspended
+    // (or the caller forces it).
+    muteUntil = Date.now() + RESUME_COOLDOWN_MS;
+    const shouldEmit = options.emit ?? pendingWhileSuspended;
+    pendingWhileSuspended = false;
+    if (shouldEmit) {
+        triggerUpdate?.();
+    }
+}
+/**
+ * Run a project-file-mutating operation with the watcher muted, then fire a
+ * single update once it finishes. Use this around the wasm-split pipeline
+ * steps so their intermediate writes don't each reload the device.
+ */
+async function withWatchSuspended(fn, options = {}) {
+    suspendWatch();
+    try {
+        return await fn();
+    }
+    finally {
+        resumeWatch({ emit: options.emitOnFinish ?? true });
+    }
+}
 async function watch() {
     let debounceTimer = null;
+    const runUpdate = async () => {
+        await compile({ mode: 'watch' });
+        wsServer.sendResourceChange();
+    };
+    triggerUpdate = () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            runUpdate();
+            debounceTimer = null;
+        }, 2000);
+    };
     // 监听当前工作目录，排除 node_modules 和 .git
     const watcher = chokidar.watch(process.cwd(), {
         /**
@@ -8365,17 +8461,20 @@ async function watch() {
     });
     // 任意文件变化都触发
     watcher.on('all', (event, path) => {
-        // 清除之前的定时器
-        if (debounceTimer)
-            clearTimeout(debounceTimer);
-        // 重新设置定时器
-        debounceTimer = setTimeout(async () => {
-            (await compile({
-                mode: 'watch',
-            }),
-                wsServer.sendResourceChange());
-            debounceTimer = null;
-        }, 2000);
+        // Pipeline is actively rewriting project files. Remember that something
+        // changed so the resume flush can fire one update, and skip the per-write
+        // compile/reload.
+        if (suspendDepth > 0) {
+            pendingWhileSuspended = true;
+            return;
+        }
+        // Cooldown window right after a pipeline finished: these are the delayed
+        // `awaitWriteFinish` events from the pipeline's own writes. We already
+        // emitted one update on resume, so swallow them to avoid a double reload.
+        if (Date.now() < muteUntil) {
+            return;
+        }
+        triggerUpdate?.();
     });
     watcher.on('error', error => {
         // console.error(chalk.red('[watch] 监听发生错误:'), error);
@@ -9332,6 +9431,68 @@ const gameCheckRoute = {
 };
 
 const changelog = [
+    {
+        title: '0.3.9',
+        target: {
+            iOS: '>=43.1',
+            Android: '>=43.1',
+        },
+        changes: {
+            optimize: [
+                {
+                    desc: {
+                        'zh-CN': '调试 IDE 默认使用浅色主题，暗色模式改为手动开启并记忆选择，避免跟随系统强制进入暗色导致不适应',
+                        'en-US': 'The debugging IDE now defaults to the light theme. Dark mode is opt-in and your choice is remembered, so it no longer follows the system and forces an unexpected dark UI.',
+                    },
+                    module: 'new',
+                },
+                {
+                    desc: {
+                        'zh-CN': '优化暗色模式下二维码显示，调整背景避免过亮刺眼，同时保证扫码识别率',
+                        'en-US': 'Improve the QR code in dark mode by toning down the background so it is no longer glaring while staying easy to scan.',
+                    },
+                    module: 'scanQrcode',
+                },
+                {
+                    desc: {
+                        'zh-CN': 'Wasm 分包页面及相关组件补齐多语言，修复页面文案中英文混排的问题',
+                        'en-US': 'Complete localization for the Wasm Code Split page and its components, fixing the mixed Chinese/English text.',
+                    },
+                    module: 'check',
+                },
+                {
+                    desc: {
+                        'zh-CN': '能力接入助手页面视觉升级：变现模式卡片新增图标与强调色，关键能力标签按「必需 / 可选 / 实验」分级展示，信息层级更清晰',
+                        'en-US': 'Refresh the Capability Integration Assistant: monetization-mode cards get icons and accent colors, and capability tags are grouped as Required / Optional / Experimental for a clearer hierarchy.',
+                    },
+                    module: 'new',
+                },
+                {
+                    desc: {
+                        'zh-CN': '完成扫码连接后，首页标题与说明文案会切换为「已连接」状态，状态反馈更明确',
+                        'en-US': 'After scanning to connect, the home page title and subtitle switch to a "connected" state for clearer feedback.',
+                    },
+                    module: 'scanQrcode',
+                },
+                {
+                    desc: {
+                        'zh-CN': '新版本提示由红点改为「有更新」文字标签，含义更直观；上传游戏包按钮配色与产品主题色统一',
+                        'en-US': 'Replace the ambiguous red dot for new versions with an explicit "Update available" label, and align the upload button color with the product theme.',
+                    },
+                    module: 'new',
+                },
+            ],
+            bugfix: [
+                {
+                    desc: {
+                        'zh-CN': '修复多个页面中区块标题与正文内容未对齐的问题，整体排版更整齐',
+                        'en-US': 'Fix section titles that were misaligned with their body content across multiple pages for a tidier layout.',
+                    },
+                    module: 'new',
+                },
+            ],
+        },
+    },
     {
         title: '0.3.8',
         target: {
@@ -10405,42 +10566,83 @@ function restoreSplitConfigFromCache(entryDir = process.cwd()) {
  * to change.
  */
 function restoreFromCache(entryDir = process.cwd()) {
+    // Rollback rewrites a burst of project files (restored wasm, game.json,
+    // split config, removed split-output dirs). Mute the dev-server watcher for
+    // the duration so it doesn't fire a compile + device reload per file, then
+    // emit a single update once the project is back to its restored state.
+    suspendWatch();
+    try {
+        restoreFromCacheInner(entryDir);
+    }
+    finally {
+        resumeWatch({ emit: true });
+    }
+}
+function restoreFromCacheInner(entryDir) {
     const cacheDir = path.join(entryDir, WASM_SPLIT_CACHE_DIR);
-    // 1) Wipe stale split residue inside wasmcode/ first, THEN restore the
-    //    original. Order matters: if we restore first then wipe, we'd delete
-    //    the very file we just brought back.
     const originDir = path.join(entryDir, WASM_SPLIT_SUBPACKAGE_CONFIG.origin.root);
-    if (fs.existsSync(originDir)) {
-        for (const entry of fs.readdirSync(originDir)) {
-            // Only clean files split is known to write — `.br` (main wasm) and
-            // the empty `game.js` placeholder. Touching anything else risks
-            // nuking developer-authored content that happens to live in
-            // wasmcode/ for unrelated reasons.
-            if (entry.endsWith('.br') || entry === 'game.js') {
-                fs.rmSync(path.join(originDir, entry), { force: true });
+    // Resolve the cached original wasm BEFORE touching anything on disk. The
+    // previous order (wipe `wasmcode/*.br` first, then look for a cached
+    // original to restore) was destructive when the cache had no original to
+    // give back — e.g. the project was duplicated without `__TTMG_TEMP__`, the
+    // temp dir was cleared, or split completed in a session whose cache is gone.
+    // In that case it deleted the project's only wasm and restored nothing,
+    // leaving `wasmcode/` empty while `game.json` still pointed at the now-missing
+    // `<md5>.wasm.br`. The next prepare then crashed the dev server on an ENOENT
+    // decompress. We only clean + restore when we have a confirmed replacement.
+    const cachedWasmBr = fs.existsSync(cacheDir)
+        ? fs.readdirSync(cacheDir).find(item => item.endsWith('.br'))
+        : undefined;
+    if (cachedWasmBr) {
+        // Safe to wipe split residue first: we have a confirmed original to put
+        // back. Order matters — restoring first then wiping would delete the file
+        // we just brought back.
+        if (fs.existsSync(originDir)) {
+            for (const entry of fs.readdirSync(originDir)) {
+                // Only clean files split is known to write — `.br` (main wasm) and
+                // the empty `game.js` placeholder. Touching anything else risks
+                // nuking developer-authored content that happens to live in
+                // wasmcode/ for unrelated reasons.
+                if (entry.endsWith('.br') || entry === 'game.js') {
+                    fs.rmSync(path.join(originDir, entry), { force: true });
+                }
             }
         }
+        const destWasmBrPath = path.join(originDir, path.basename(cachedWasmBr));
+        ensureDirSync(path.dirname(destWasmBrPath));
+        fs.copyFileSync(path.join(cacheDir, cachedWasmBr), destWasmBrPath);
     }
-    if (fs.existsSync(cacheDir)) {
-        const targetWasmBrPath = fs
-            .readdirSync(cacheDir)
-            .find(item => item.endsWith('.br'));
-        if (targetWasmBrPath) {
-            const destWasmBrPath = path.join(entryDir, WASM_SPLIT_SUBPACKAGE_CONFIG.origin.root, path.basename(targetWasmBrPath));
-            ensureDirSync(path.dirname(destWasmBrPath));
-            fs.copyFileSync(path.join(cacheDir, targetWasmBrPath), destWasmBrPath);
-        }
-    }
-    const splitConfigCachePath = path.join(cacheDir, WASM_SPLIT_CONFIG_FILE_NAME);
-    if (fs.existsSync(splitConfigCachePath)) {
-        fs.copyFileSync(splitConfigCachePath, path.join(entryDir, WASM_SPLIT_CONFIG_FILE_NAME));
-    }
-    const gameJsonCachePath = path.join(cacheDir, 'game.json');
-    if (fs.existsSync(gameJsonCachePath)) {
-        fs.copyFileSync(gameJsonCachePath, path.join(entryDir, 'game.json'));
-    }
-    // Restore wasmcode/game.js. We just deleted whatever was there in step 1,
-    // so we always need to put something back when wasmcode is a subpackage.
+    else {
+        // No cached original. Do NOT delete whatever wasm is currently on disk —
+        // it is all the project has left. Preserve it so the project can still
+        // boot and a fresh prepare can re-seed the cache, rather than wiping it and
+        // crashing the next prepare. The split-output dirs below are still cleaned.
+        console.warn('[wasmtool] restoreFromCache: no cached original wasm found in ' +
+            `${WASM_SPLIT_CACHE_DIR}; skipping wasmcode/*.br cleanup to avoid ` +
+            'leaving the project without a wasm binary.');
+    }
+    // Only roll back the split config + game.json when we actually restored the
+    // original wasm above. Restoring game.json (which points at the original
+    // `<md5>.wasm.br`) while the matching wasm is NOT on disk recreates exactly
+    // the broken state this guard exists to prevent — a game.json referencing a
+    // file that isn't there. keepCacheSync writes the wasm, config and game.json
+    // together, so a cache that has game.json but no `.br` is partial/corrupt and
+    // must not be applied.
+    if (cachedWasmBr) {
+        const splitConfigCachePath = path.join(cacheDir, WASM_SPLIT_CONFIG_FILE_NAME);
+        if (fs.existsSync(splitConfigCachePath)) {
+            fs.copyFileSync(splitConfigCachePath, path.join(entryDir, WASM_SPLIT_CONFIG_FILE_NAME));
+        }
+        const gameJsonCachePath = path.join(cacheDir, 'game.json');
+        if (fs.existsSync(gameJsonCachePath)) {
+            fs.copyFileSync(gameJsonCachePath, path.join(entryDir, 'game.json'));
+        }
+    }
+    // Restore wasmcode/game.js. We just deleted whatever was there in the
+    // cleanup loop above, so we always need to put something back when wasmcode
+    // is a subpackage. Scoped to the same `cachedWasmBr` guard: in the degraded
+    // (lost-cache) path we left the existing wasmcode/ untouched, so we must not
+    // rewrite its game.js either.
     // Strategy:
     //   - Prefer the cache (keepCacheSync stashes pre-split contents to
     //     `__unity_cache__/wasmcode-game.js` when the original existed)
@@ -10451,14 +10653,16 @@ function restoreFromCache(entryDir = process.cwd()) {
     //     downloadSplited.ts also writes; it satisfies the platform requirement
     //     without changing semantics for projects that don't use wasmcode as
     //     a subpackage (the file is harmless empty).
-    const originGameJsCachePath = path.join(cacheDir, 'wasmcode-game.js');
-    const originGameJsDestPath = path.join(originDir, 'game.js');
-    if (fs.existsSync(originDir)) {
-        if (fs.existsSync(originGameJsCachePath)) {
-            fs.copyFileSync(originGameJsCachePath, originGameJsDestPath);
-        }
-        else {
-            fs.writeFileSync(originGameJsDestPath, '', 'utf-8');
+    if (cachedWasmBr) {
+        const originGameJsCachePath = path.join(cacheDir, 'wasmcode-game.js');
+        const originGameJsDestPath = path.join(originDir, 'game.js');
+        if (fs.existsSync(originDir)) {
+            if (fs.existsSync(originGameJsCachePath)) {
+                fs.copyFileSync(originGameJsCachePath, originGameJsDestPath);
+            }
+            else {
+                fs.writeFileSync(originGameJsDestPath, '', 'utf-8');
+            }
         }
     }
     for (const subDir of SPLIT_OUTPUT_DIRS) {
@@ -10576,21 +10780,53 @@ function setLocalState(partial) {
     Object.assign(state, partial);
 }
 
+/**
+ * Prepare overwrites the project wasm in place with the instrumented build.
+ * Mute the dev-server file watcher for the duration so the in-place rewrite
+ * doesn't fire a compile + device reload while the file is still being
+ * written, then emit a single update once the instrumented wasm is on disk.
+ */
 async function startPrepare$1(params) {
+    return withWatchSuspended(() => startPrepareImpl(params), {
+        emitOnFinish: true,
+    });
+}
+async function startPrepareImpl(params) {
     const tempDir = path$1.join(process.cwd(), TTMG_TEMP_DIR);
     ensureDirSync(tempDir);
     const inputPath = path$1.join(process.cwd(), params.wasm_file_path);
-    let rawWasmPath = path$1.join(tempDir, 'original.wasm');
-    if (inputPath.endsWith('.br')) {
-        await decompressWasmFile(inputPath, rawWasmPath);
-    }
-    else {
-        fs$1.copyFileSync(inputPath, rawWasmPath);
-    }
+    const rawWasmPath = path$1.join(tempDir, 'original.wasm');
     const preparedWasmPath = path$1.join(tempDir, 'prepared.wasm');
     try {
+        // The project wasm referenced by game.json can legitimately be missing on
+        // disk: a previous rollback may have wiped `wasmcode/*.br` without a cached
+        // original to restore, the project may have been duplicated without
+        // `__TTMG_TEMP__`, or Unity was re-exported. Detect it up front and return
+        // a structured error. Previously the `decompressWasmFile` / `copyFileSync`
+        // below sat OUTSIDE this try block, so a missing input threw ENOENT out of
+        // the route handler as an unhandled rejection and crashed the whole
+        // dev-server process instead of surfacing a recoverable error to the IDE.
+        if (!fs$1.existsSync(inputPath)) {
+            return {
+                data: null,
+                error: {
+                    code: 404,
+                    message: `WASM file not found: ${params.wasm_file_path}. ` +
+                        'The original wasm is missing — a previous "放弃分包" may have removed it ' +
+                        'without a cached original to restore. Re-export the Unity build (or restore ' +
+                        'the original wasm) and try preparing again.',
+                },
+                ctx: { logid: 'local', httpStatusCode: 404 },
+            };
+        }
+        if (inputPath.endsWith('.br')) {
+            await decompressWasmFile(inputPath, rawWasmPath);
+        }
+        else {
+            fs$1.copyFileSync(inputPath, rawWasmPath);
+        }
         const result = ttmgWasmtool.prepare(rawWasmPath, preparedWasmPath);
-        console.log(`[wasmtool] prepare done: ${result.outputSize} bytes, ${result.timeCost}s`);
+        verboseLog(`[wasmtool] prepare done: ${result.outputSize} bytes, ${result.timeCost}s`);
         const gameJson = getGameJson();
         const totalWasmFuncCount = gameJson.wasmFuncCount ?? 0;
         const wasmSize = fs$1.existsSync(inputPath)
@@ -10624,13 +10860,13 @@ async function startPrepare$1(params) {
         const preparedMd5 = fs$1.existsSync(preparedWasmPath)
             ? crypto$1.createHash('md5').update(fs$1.readFileSync(preparedWasmPath)).digest('hex')
             : '<missing>';
-        console.log(`[wasmtool] prepare sanity: raw(size=${rawSize} md5=${rawMd5}) -> prepared(size=${preparedSize} md5=${preparedMd5}) delta=${preparedSize - rawSize}`);
+        verboseLog(`[wasmtool] prepare sanity: raw(size=${rawSize} md5=${rawMd5}) -> prepared(size=${preparedSize} md5=${preparedMd5}) delta=${preparedSize - rawSize}`);
         if (preparedSize <= rawSize || preparedMd5 === rawMd5) {
-            console.warn('[wasmtool] WARNING: prepared wasm is not larger / md5 is unchanged vs raw wasm. Instrumentation likely did not happen.');
+            verboseWarn('[wasmtool] WARNING: prepared wasm is not larger / md5 is unchanged vs raw wasm. Instrumentation likely did not happen.');
         }
-        console.log('[wasmtool] compressing prepared wasm (quality=9)...');
+        verboseLog('[wasmtool] compressing prepared wasm (quality=9)...');
         await compressWasmFile(preparedWasmPath, willReplaceWasmPath);
-        console.log('[wasmtool] compressed and written to project');
+        verboseLog('[wasmtool] compressed and written to project');
         // Diagnostic: confirm the file the client actually fetches was overwritten,
         // and compare to the cached original brotli so we can prove on-disk replacement.
         const replacedSize = fs$1.existsSync(willReplaceWasmPath)
@@ -10649,12 +10885,12 @@ async function startPrepare$1(params) {
                 .update(fs$1.readFileSync(cachedOriginalBr))
                 .digest('hex')
             : '<missing>';
-        console.log(`[wasmtool] on-disk replace check: project=${params.wasm_file_path} size=${replacedSize} md5=${replacedMd5} | cached-original size=${cachedOriginalSize} md5=${cachedOriginalMd5}`);
+        verboseLog(`[wasmtool] on-disk replace check: project=${params.wasm_file_path} size=${replacedSize} md5=${replacedMd5} | cached-original size=${cachedOriginalSize} md5=${cachedOriginalMd5}`);
         if (replacedMd5 === cachedOriginalMd5) {
-            console.warn('[wasmtool] WARNING: project wasm md5 matches cached-original md5. The file was not actually replaced with the instrumented build.');
+            verboseWarn('[wasmtool] WARNING: project wasm md5 matches cached-original md5. The file was not actually replaced with the instrumented build.');
         }
         else {
-            console.log('[wasmtool] OK: project wasm differs from cached-original — instrumented wasm is on disk.');
+            verboseLog('[wasmtool] OK: project wasm differs from cached-original — instrumented wasm is on disk.');
         }
         // Local pipeline uses the new wasm-collect/v1/report API + archive sub-wasm.
         // ORIGINALWASMMD5 must be set now (not only at split time) so the plugin
@@ -10664,7 +10900,7 @@ async function startPrepare$1(params) {
             ENABLEARCHIVEMODE: true,
             ORIGINALWASMMD5: params.wasm_md5,
         });
-        console.log('[wasmtool] wasm split config updated (local pipeline: archive=true)');
+        verboseLog('[wasmtool] wasm split config updated (local pipeline: archive=true)');
         // Disk-persisted anchor for "wasm drift" detection in
         // `game-wasm-split-config` route. Stores the md5 that prepare just
         // wrote into the project alongside the project-relative path. The
@@ -10678,7 +10914,7 @@ async function startPrepare$1(params) {
             preparedWasmMd5: replacedMd5,
             codePath: params.wasm_file_path,
         });
-        console.log(`[wasmtool] prepared-meta written: md5=${replacedMd5} codePath=${params.wasm_file_path}`);
+        verboseLog(`[wasmtool] prepared-meta written: md5=${replacedMd5} codePath=${params.wasm_file_path}`);
         return {
             data: {
                 code: 0,
@@ -10787,42 +11023,30 @@ async function startWasmSession({ client_key, wasm_md5, reset, }) {
 }
 
 /**
- * "开始收集" 的本地 pipeline 实现。语义上等价于老远程流程的
- * `stark_wasm/v4/post/set_collecting`：**打开 server 端的 collect 窗口**，
- * 让 plugin 之后的 `/report` 请求能落库。
+ * 打开 server 端 collect session（本地 pipeline 的 `/start`）。
  *
- * 做三件事（顺序敏感）：
- *   1. `POST /start` 打开 session —— 失败必须立即返回给 IDE，
- *      否则 UI 会让用户进"正在收集"但实际 plugin 所有上报都会被 fail-close
- *      丢弃，场面非常悲伤。
- *   2. 成功后上传符号表（`/symbols`）。这一步故意不 await、错误仅 warn —
- *      符号表只是给 server 端后续调试用的 debug 信息，丢了也不影响分包主链路。
- *   3. 返回 `{code: 0}`。
+ * 这是**鉴权门**：`/start` 走 Portal 鉴权中间件，登录态失效会返回 `-401`
+ * （或带登录关键字的 `-1`）。鉴权失败必须立即把错误回给 IDE 并中止——
+ * 否则用户进了"正在收集"，但 plugin 之后所有 `/report` 都会被 fail-close
+ * 丢弃，函数数量永远 0，且很难归因。
  *
- * 两种调用语义（与 `wasm_api.md` §5.1 对齐）：
- *   - 默认（`resume` 缺省 / false）—— 用户点"开始收集 / 重新开始分包"，
- *     发 `reset: true`，服务端清空历史。这是历史行为，对应 IDE 上的
- *     "willCollect → startCollect" 主入口。
- *   - `resume: true` —— 页面刷新 / 恢复继续，发 `reset: false`，幂等
- *     打开 session、保留已有 func_ids。需要这条路径的 caller（如 IDE
- *     重新挂载组件检测到 server `collect_state: "open"` 想接续）必须
- *     显式传，避免误清。
+ * IDE 通过独立路由 `/game/wasm-collect-start` 调用本函数，所以它在浏览器
+ * Network 里是一条可见且**明确叫 start** 的请求——出鉴权问题时一眼能定位到
+ * 是开 session 这步失败，而不是被误认为 collect 轮询接口的问题。symbols
+ * 上传是另一步（`uploadCollectSymbols`），与开 session 解耦。
  *
- * Session 生命周期对前端透明——IDE 只知道"开始收集 / 完成收集"两个动作，
- * `/start` 和 `/finish` 都被封在本地 dispatcher 内。这样远程 pipeline（没有
- * session 概念）和本地 pipeline（有 session）在 IDE 层看起来是对称的。
+ * 两种语义（与 `wasm_api.md` §5.1 对齐）：
+ *   - 默认（`resume` 缺省 / false）→ `reset: true`，服务端清空历史。
+ *   - `resume: true` → `reset: false`，幂等打开、保留已有 func_ids。
  */
-async function setCollect$1({ client_key, wasm_md5, resume, }) {
+async function openCollectSession$1({ client_key, wasm_md5, resume, }) {
     const startRes = await startWasmSession({
         client_key,
         wasm_md5,
         reset: !resume,
     });
     if (startRes.error || !startRes.data || startRes.data.code !== 0) {
-        // /start is invoked internally by setCollect now; IDE only sees this
-        // bubbled up as a generic "开始收集失败" toast, so dump a structured
-        // one-liner here with logid — the single most useful field when
-        // asking backend to look up what happened on their side.
+        // 结构化日志带 logid——找后端排查鉴权/会话问题时最有用的字段。
         const code = startRes.error?.code ?? startRes.data?.code ?? -1;
         const message = startRes.error?.message ||
             startRes.data?.message ||
@@ -10835,6 +11059,20 @@ async function setCollect$1({ client_key, wasm_md5, resume, }) {
             ctx: startRes.ctx,
         };
     }
+    return {
+        data: { code: 0, message: 'success', result: startRes.data.result },
+        error: null,
+        ctx: startRes.ctx,
+    };
+}
+/**
+ * 上传符号表（`/symbols`）。只在 session 已打开后调用。
+ *
+ * 符号表只是给 server 端后续调试用的 debug 信息，丢了不影响分包主链路，
+ * 所以这里故意不 await、失败仅 warn，且总是返回 `{code: 0}`——它不应该
+ * 阻塞或失败掉"开始收集"流程。
+ */
+async function uploadCollectSymbols$1({ client_key, wasm_md5, }) {
     let symbolPath = path$1.join(process.cwd(), WASM_SYMBOL_FILE_NAME);
     if (!fs$1.existsSync(symbolPath)) {
         symbolPath = path$1.join(process.cwd(), TTMG_TEMP_DIR, WASM_SYMBOL_FILE_NAME);
@@ -10844,13 +11082,15 @@ async function setCollect$1({ client_key, wasm_md5, resume, }) {
         request({
             url: `${WASM_COLLECT_BASE_URL}/symbols`,
             method: 'POST',
+            // symbols 是整张符号表，verbose 下打出来会刷屏，关掉它的入参日志。
+            logRequestBody: false,
             data: {
                 app_id: client_key,
                 wasm_md5,
                 symbols,
             },
         }).catch(err => {
-            console.warn('[wasmtool] Failed to upload symbols:', err);
+            verboseWarn('[wasmtool] Failed to upload symbols:', err);
         });
     }
     return {
@@ -10963,7 +11203,7 @@ async function startSplit$1({ client_key, wasm_md5, }) {
             ctx: { logid: 'local', httpStatusCode: 400 },
         };
     }
-    console.log(`[wasmtool] splitting with ${funcIds.length} func IDs` +
+    verboseLog(`[wasmtool] splitting with ${funcIds.length} func IDs` +
         (bootFuncIds.length > 0
             ? `, ${bootFuncIds.length} boot-phase func IDs (→ alwaysInclude)`
             : ', no boot-phase info (legacy server, falling back to callClosure only)') +
@@ -11023,14 +11263,14 @@ async function startSplit$1({ client_key, wasm_md5, }) {
             const actualArchivePath = fs$1.existsSync(archiveBrPath)
                 ? archiveBrPath
                 : result.archivePath;
-            console.log(`[wasmtool] archivePath=${result.archivePath}, brExists=${fs$1.existsSync(archiveBrPath)}, actualExists=${fs$1.existsSync(actualArchivePath)}`);
+            verboseLog(`[wasmtool] archivePath=${result.archivePath}, brExists=${fs$1.existsSync(archiveBrPath)}, actualExists=${fs$1.existsSync(actualArchivePath)}`);
             if (fs$1.existsSync(actualArchivePath)) {
                 archiveMd5 = computeFileMd5Sync(actualArchivePath);
-                console.log(`[wasmtool] archive_md5=${archiveMd5}`);
+                verboseLog(`[wasmtool] archive_md5=${archiveMd5}`);
             }
         }
         else {
-            console.log(`[wasmtool] skip archive md5: archive=${archive}, archivePath=${result.archivePath}`);
+            verboseLog(`[wasmtool] skip archive md5: archive=${archive}, archivePath=${result.archivePath}`);
         }
         const globalVarList = result.globalVarList
             .split(';')
@@ -11072,7 +11312,7 @@ async function startSplit$1({ client_key, wasm_md5, }) {
             export_added: result.exportAdded,
         };
         setLocalState({ splitOutputDir, splitMeta });
-        console.log(`[wasmtool] split done: total=${result.totalWasmCount}, main=${result.mainWasmCount} ` +
+        verboseLog(`[wasmtool] split done: total=${result.totalWasmCount}, main=${result.mainWasmCount} ` +
             `(collect=${result.collectFuncCount}, +alwaysInclude=${result.alwaysIncludeAdded}, ` +
             `+closure=${result.closureAdded}, +indirectClosure=${result.indirectClosureAdded}` +
             `[types=${result.indirectClosureTypes}], +exports=${result.exportAdded}), ` +
@@ -11155,7 +11395,18 @@ function updateSubpackageConfigSync(archive = false) {
     fs__namespace.writeFileSync(gameJsonPath, JSON.stringify(gameJson, null, JSON_INDENT) + JSON_EOL);
 }
 
-async function downloadSplited$1(_context) {
+/**
+ * Lays down the split outputs (`wasmcode*` dirs, game.json, webgl-wasm-split.js)
+ * into the project root — a burst of file writes. Mute the watcher across the
+ * whole operation so it doesn't reload the device per file mid-write, then fire
+ * one update once the split layout is fully on disk.
+ */
+async function downloadSplited$1(context) {
+    return withWatchSuspended(() => downloadSplitedImpl(context), {
+        emitOnFinish: true,
+    });
+}
+async function downloadSplitedImpl(_context) {
     const cwd = process.cwd();
     const { splitMeta } = getLocalState();
     if (!splitMeta) {
@@ -11177,7 +11428,7 @@ async function downloadSplited$1(_context) {
     const dirs = [...new Set([mainAndroidDir, subAndroidDir, mainIosDir, subIosDir])];
     dirs.forEach(ensureDirSync);
     try {
-        console.log('[wasmtool] organizing split output...');
+        verboseLog('[wasmtool] organizing split output...');
         const mainWasmMd5 = splitMeta.main_wasm_md5;
         const subWasmMd5 = splitMeta.sub_wasm_md5;
         const mainWasmH5Md5 = splitMeta.main_wasm_h5_md5;
@@ -11220,20 +11471,20 @@ async function downloadSplited$1(_context) {
         if (isArchive && localArchivePath) {
             const archiveBrPath = localArchivePath + BR_SUFFIX;
             const actualArchivePath = fs.existsSync(archiveBrPath) ? archiveBrPath : localArchivePath;
-            console.log(`[wasmtool] archive copy: archive_md5=${splitMeta.archive_md5}, localPath=${localArchivePath}, brExists=${fs.existsSync(archiveBrPath)}, actual=${actualArchivePath}`);
+            verboseLog(`[wasmtool] archive copy: archive_md5=${splitMeta.archive_md5}, localPath=${localArchivePath}, brExists=${fs.existsSync(archiveBrPath)}, actual=${actualArchivePath}`);
             if (fs.existsSync(actualArchivePath)) {
                 const archiveMd5 = splitMeta.archive_md5 || '';
                 const archiveBaseName = path.basename(actualArchivePath);
                 const destName = archiveMd5 ? `${archiveMd5}.${archiveBaseName}` : archiveBaseName;
                 const archiveDest = path.join(subIosDir, destName);
-                console.log(`[wasmtool] archive dest: ${archiveDest}`);
+                verboseLog(`[wasmtool] archive dest: ${archiveDest}`);
                 fs.copyFileSync(actualArchivePath, archiveDest);
             }
         }
         dirs.forEach((dir) => {
             fs.writeFileSync(path.join(dir, 'game.js'), '', { encoding: 'utf-8' });
         });
-        console.log('[wasmtool] copy split output to root...');
+        verboseLog('[wasmtool] copy split output to root...');
         wsServer.sendUnitySplitStatus({ status: 'start_write_splited_wasm_br' });
         for (const file of fs.readdirSync(splitTempDir)) {
             const srcPath = path.join(splitTempDir, file);
@@ -11244,9 +11495,9 @@ async function downloadSplited$1(_context) {
             await promises.cp(srcPath, destPath, { recursive: true, force: true });
         }
         wsServer.sendUnitySplitStatus({ status: 'write_splited_wasm_done' });
-        console.log('[wasmtool] updating subpackage config...');
+        verboseLog('[wasmtool] updating subpackage config...');
         updateSubpackageConfigSync(isArchive);
-        console.log('[wasmtool] updating wasm split config...');
+        verboseLog('[wasmtool] updating wasm split config...');
         wsServer.sendUnitySplitStatus({ status: 'start_update_wasm_split_config' });
         updateWasmSplitConfig({
             ENABLEWASMCOLLECT: true,
@@ -11464,7 +11715,7 @@ async function downloadOne(opts) {
     const willDownloadedFileIsBr = url.includes(BR_SUFFIX);
     const finalOut = willDownloadedFileIsBr && !out.endsWith(BR_SUFFIX) ? out + BR_SUFFIX : out;
     wsServer.sendUnitySplitStatus({ status: startStatus });
-    console.log(`[remote-split-download] fetching -> ${finalOut}`);
+    verboseLog(`[remote-split-download] fetching -> ${finalOut}`);
     const t0 = Date.now();
     await withRetry(() => download(url, finalOut), DOWNLOAD_RETRY);
     const st = await promises.stat(finalOut);
@@ -11472,13 +11723,23 @@ async function downloadOne(opts) {
         await promises.rm(finalOut, { force: true });
         throw new Error(`Empty download: ${finalOut}`);
     }
-    console.log(`[remote-split-download] done: ${path.basename(finalOut)} size=${st.size}B time=${Date.now() - t0}ms`);
+    verboseLog(`[remote-split-download] done: ${path.basename(finalOut)} size=${st.size}B time=${Date.now() - t0}ms`);
     wsServer.sendUnitySplitStatus({ status: doneStatus, url });
     // Legacy behaviour: write an empty game.js next to each downloaded artifact
     // so the subpackage loader doesn't complain about missing js entries.
     fs.writeFileSync(path.join(path.dirname(out), 'game.js'), '', 'utf-8');
 }
+/**
+ * Remote-mode counterpart of `downloadSplited`: downloads the server-built
+ * split artifacts and copies them into the project root. Same watcher gating
+ * rationale — mute across the burst of writes, emit one update at the end.
+ */
 async function downloadSplitedRemote(context) {
+    return withWatchSuspended(() => downloadSplitedRemoteImpl(context), {
+        emitOnFinish: true,
+    });
+}
+async function downloadSplitedRemoteImpl(context) {
     const cwd = process.cwd();
     const splitTempDir = path.join(cwd, WASM_SPLIT_CACHE_DIR, DIR_SPLIT);
     ensureDirSync(splitTempDir);
@@ -11492,7 +11753,7 @@ async function downloadSplitedRemote(context) {
     const mainIosOut = path.join(mainIosDir, `${context.main_wasm_h5_md5}${WASM_FILENAME_SUFFIX}`);
     const limit = pLimit(CONCURRENCY_LIMIT);
     try {
-        console.log('[remote-split-download] start', {
+        verboseLog('[remote-split-download] start', {
             original_wasm_md5: context.original_wasm_md5,
             main_wasm_md5: context.main_wasm_md5,
             sub_wasm_md5: context.sub_wasm_md5,
@@ -11530,7 +11791,7 @@ async function downloadSplitedRemote(context) {
                 out: path.join(subIosDir, 'subjs.data'),
             })),
         ]);
-        console.log('[remote-split-download] copying split output to project root...');
+        verboseLog('[remote-split-download] copying split output to project root...');
         wsServer.sendUnitySplitStatus({ status: 'start_write_splited_wasm_br' });
         for (const file of fs.readdirSync(splitTempDir)) {
             const srcPath = path.join(splitTempDir, file);
@@ -11541,9 +11802,9 @@ async function downloadSplitedRemote(context) {
             await promises.cp(srcPath, destPath, { recursive: true, force: true });
         }
         wsServer.sendUnitySplitStatus({ status: 'write_splited_wasm_done' });
-        console.log('[remote-split-download] updating subpackage config...');
+        verboseLog('[remote-split-download] updating subpackage config...');
         updateSubpackageConfigSync(false);
-        console.log('[remote-split-download] updating webgl-wasm-split.js...');
+        verboseLog('[remote-split-download] updating webgl-wasm-split.js...');
         wsServer.sendUnitySplitStatus({ status: 'start_update_wasm_split_config' });
         updateWasmSplitConfig({
             ENABLEWASMCOLLECT: true,
@@ -11560,12 +11821,12 @@ async function downloadSplitedRemote(context) {
             USINGWASMH5: Boolean(context.main_wasm_h5_md5),
         });
         wsServer.sendUnitySplitStatus({ status: 'update_wasm_split_config_done' });
-        console.log('[remote-split-download] all done');
+        verboseLog('[remote-split-download] all done');
         return { data: { isSuccess: true }, ctx: context };
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        console.log('[remote-split-download] failed:', message);
+        verboseLog('[remote-split-download] failed:', message);
         wsServer.sendUnitySplitStatus({ status: 'wasm_split_failed', errorMsg: message });
         return {
             data: { isSuccess: false },
@@ -11890,7 +12151,7 @@ async function downloadPreparedRemote(data) {
     try {
         const downloadUrl = res?.data?.result?.download_url;
         if (!downloadUrl) {
-            console.log('[remote-download-prepared] no download_url in response');
+            verboseLog('[remote-download-prepared] no download_url in response');
             return {
                 isSuccess: false,
                 error: { code: res.data?.code, message: res.data?.message || 'No download_url returned' },
@@ -11903,28 +12164,28 @@ async function downloadPreparedRemote(data) {
             originalWasmPath: data.wasm_path,
             originalSplitConfigPath: WASM_SPLIT_CONFIG_FILE_NAME,
         });
-        console.log(`[remote-download-prepared] target=${willReplaceWasmPath}`);
+        verboseLog(`[remote-download-prepared] target=${willReplaceWasmPath}`);
         if (downloadUrl.includes('.br')) {
             const tempWasmPath = path$1.join(cacheDir, '__temp__.wasm.br');
-            console.log('[remote-download-prepared] downloading (br) ->', tempWasmPath);
+            verboseLog('[remote-download-prepared] downloading (br) ->', tempWasmPath);
             wsServer.sendUnitySplitStatus({ status: 'start_download_prepared_wasm', url: downloadUrl });
             const startedAt = Date.now();
             await download(downloadUrl, tempWasmPath);
-            console.log(`[remote-download-prepared] download done in ${Date.now() - startedAt}ms, size=${fs$1.statSync(tempWasmPath).size}`);
+            verboseLog(`[remote-download-prepared] download done in ${Date.now() - startedAt}ms, size=${fs$1.statSync(tempWasmPath).size}`);
             fs$1.copyFileSync(tempWasmPath, willReplaceWasmPath);
             wsServer.sendUnitySplitStatus({ status: 'download_prepared_wasm_done', url: downloadUrl });
         }
         else {
             const tempWasmPath = path$1.join(cacheDir, '__temp__.wasm');
-            console.log('[remote-download-prepared] downloading (raw) ->', tempWasmPath);
+            verboseLog('[remote-download-prepared] downloading (raw) ->', tempWasmPath);
             wsServer.sendUnitySplitStatus({ status: 'start_download_prepared_wasm', url: downloadUrl });
             const startedAt = Date.now();
             await download(downloadUrl, tempWasmPath);
-            console.log(`[remote-download-prepared] download done in ${Date.now() - startedAt}ms, size=${fs$1.statSync(tempWasmPath).size}`);
+            verboseLog(`[remote-download-prepared] download done in ${Date.now() - startedAt}ms, size=${fs$1.statSync(tempWasmPath).size}`);
             wsServer.sendUnitySplitStatus({ status: 'download_prepared_wasm_done', url: downloadUrl });
             wsServer.sendUnitySplitStatus({ status: 'start_compress_prepared_wasm' });
             await compressWasmFile(tempWasmPath, willReplaceWasmPath);
-            console.log('[remote-download-prepared] compressed and written to project');
+            verboseLog('[remote-download-prepared] compressed and written to project');
             wsServer.sendUnitySplitStatus({ status: 'compress_prepared_wasm_done', url: downloadUrl });
             wsServer.sendUnitySplitStatus({ status: 'write_compress_prepared_wasm_done' });
         }
@@ -11942,11 +12203,11 @@ async function downloadPreparedRemote(data) {
                 data.wasm_md5,
         });
         wsServer.sendUnitySplitStatus({ status: 'update_wasm_split_config_done' });
-        console.log('[remote-download-prepared] split config updated, returning success');
+        verboseLog('[remote-download-prepared] split config updated, returning success');
         return { isSuccess: true, ctx: res?.ctx };
     }
     catch (error) {
-        console.log('[remote-download-prepared] error:', error);
+        verboseLog('[remote-download-prepared] error:', error);
         return {
             isSuccess: false,
             error: { code: res.data?.code, message: error instanceof Error ? error.message : String(error) },
@@ -11960,7 +12221,21 @@ function isLocal() {
 }
 const startPrepare = (params) => isLocal() ? startPrepare$1(params) : startPrepareRemote(params);
 const downloadPrepared = (params) => isLocal() ? downloadPrepared$1() : downloadPreparedRemote(params);
-const setCollect = (params) => isLocal() ? setCollect$1(params) : setCollectRemote(params);
+// 开 collect session（鉴权门）。IDE 经 `/game/wasm-collect-start` 调用，
+// 所以它在浏览器 Network 里是一条独立可见、明确叫 start 的请求。
+//   - 本地 → `/start`
+//   - 远程 → 老的 `set_collecting`（远程没有独立 /start，set_collecting 即开窗）
+const openCollectSession = (params) => isLocal() ? openCollectSession$1(params) : setCollectRemote(params);
+// 上传符号表。本地走 `/symbols`（非阻塞、失败不致命）；远程在 prepare 阶段
+// 已随表单上传过 symbol 文件，这里是 no-op，直接返回成功保持两条 pipeline
+// 在 IDE 层对称。
+const uploadCollectSymbols = (params) => isLocal()
+    ? uploadCollectSymbols$1(params)
+    : Promise.resolve({
+        data: { code: 0, message: 'success', result: {} },
+        error: null,
+        ctx: { logid: 'remote-noop', httpStatusCode: 200 },
+    });
 const getCollectedFuncIds = (params) => isLocal() ? getCollectedFuncIds$1(params) : getCollectedFuncIdsRemote(params);
 const getCollecttingInfo = (params) => isLocal() ? getCollecttingInfo$1(params) : getCollecttingInfoRemote(params);
 const startSplit = (params) => isLocal() ? startSplit$1(params) : startSplitRemote(params);
@@ -12148,20 +12423,58 @@ const gameWasmPrepareRoute = {
     },
 };
 
+/**
+ * 上传符号表（`/symbols`）。只在 session 已通过 `/game/wasm-collect-start`
+ * 打开后调用，与"开 session"解耦：
+ *   - 鉴权门是 `/game/wasm-collect-start`（→ `/start`），不在这条。
+ *   - 这步是非关键的 debug 信息上传，本地非阻塞/失败不致命，远程为 no-op。
+ * 因此即便失败也只回 errorCode 让调用方静默处理，不应阻断"开始收集"。
+ */
 const gameWasmSetCollectRoute = {
     method: 'post',
     path: '/game/wasm-set-collect',
     handler: async (req, res) => {
-        // `resume` is optional and only meaningful for the local pipeline:
-        // when the IDE detects an existing open session (e.g. user refreshed
-        // the page mid-collect) and wants to "继续收集" without nuking the
-        // already-uploaded func_ids, it POSTs `{ resume: true }`. Default
-        // (omitted / false) keeps the historical "fresh run" behaviour on
-        // /start (server gets `reset: true`). See `setCollect` jsdoc for the
-        // two-path contract; remote pipeline ignores the field outright.
+        const { clientKey, codeMd5 } = req.body;
+        console.log('wasm-set-collect (upload symbols)', req.body);
+        const response = await uploadCollectSymbols({
+            client_key: clientKey,
+            wasm_md5: codeMd5,
+        });
+        if (response.error) {
+            res.send({
+                code: errorCode,
+                error: response.error,
+                ctx: response.ctx,
+            });
+        }
+        else {
+            res.send({
+                code: successCode,
+                data: response.data || {},
+                ctx: response.ctx,
+            });
+        }
+    },
+};
+
+/**
+ * 打开 collect session —— 对应后端 `/start`（本地）/ `set_collecting`（远程）。
+ *
+ * 单独成一条 IDE 可见路由（而不是埋在 set-collect 里），是为了让浏览器
+ * Network 里有一条**明确叫 start** 的请求：`/start` 走 Portal 鉴权中间件，
+ * 鉴权失败（`-401`）时这条请求会带着透传上来的 `error.code:-401` 返回，
+ * IDE 全局拦截器据此弹"登录态失效"toast，且排查时能一眼定位到是开 session
+ * 这步报的鉴权，而非 collect 轮询接口。
+ *
+ * `resume` 可选：仅本地 pipeline 有意义，缺省 → `reset:true`（重新开始）。
+ */
+const gameWasmCollectStartRoute = {
+    method: 'post',
+    path: '/game/wasm-collect-start',
+    handler: async (req, res) => {
         const { clientKey, codeMd5, resume } = req.body;
-        console.log('wasm-set-collect', req.body);
-        const response = await setCollect({
+        console.log('wasm-collect-start', req.body);
+        const response = await openCollectSession({
             client_key: clientKey,
             wasm_md5: codeMd5,
             resume,
@@ -12533,6 +12846,7 @@ const routes = [
     gameWasmPrepareDownloadRoute,
     gameWasmSplitRoute,
     gameWasmTaskinfoRoute,
+    gameWasmCollectStartRoute,
     gameWasmSetCollectRoute,
     gameWasmCollectFuncidsRoute,
     gameWasmCollectInfoRoute,
@@ -12545,14 +12859,61 @@ const routes = [
     gamePipelineModeGetRoute,
     gameLanguageRoute,
 ];
+/**
+ * Express 4 does not catch rejections from async route handlers — an
+ * unhandled rejection in any handler propagates to the process and, under
+ * Node's default `unhandledRejection` behavior, kills the whole dev server.
+ * That's how a single missing-file ENOENT in `wasm-prepare` could take the
+ * CLI down. Wrap every handler so a failing request returns a 500 instead of
+ * crashing the process. Individual routes can still return structured errors;
+ * this is only the last-resort net for unexpected throws.
+ */
+function withErrorBoundary(handler) {
+    return (req, res, next) => {
+        try {
+            const result = handler(req, res, next);
+            if (result && typeof result.then === 'function') {
+                result.catch((err) => {
+                    console.error(`[dev-server] unhandled error in ${req.method} ${req.path}:`, err);
+                    if (!res.headersSent) {
+                        res
+                            .status(500)
+                            .send({
+                            code: -1,
+                            error: {
+                                code: 500,
+                                message: err instanceof Error ? err.message : String(err),
+                            },
+                        });
+                    }
+                });
+            }
+        }
+        catch (err) {
+            console.error(`[dev-server] unhandled error in ${req.method} ${req.path}:`, err);
+            if (!res.headersSent) {
+                res
+                    .status(500)
+                    .send({
+                    code: -1,
+                    error: {
+                        code: 500,
+                        message: err instanceof Error ? err.message : String(err),
+                    },
+                });
+            }
+        }
+    };
+}
 function registerRoutes(app, options) {
     const allRoutes = [...routes, getGameFallbackRoute(options.publicPath)];
     for (const route of allRoutes) {
+        const handler = withErrorBoundary(route.handler);
         if (route.method === 'get') {
-            app.get(route.path, route.handler);
+            app.get(route.path, handler);
         }
         else if (route.method === 'post') {
-            app.post(route.path, route.handler);
+            app.post(route.path, handler);
         }
     }
 }
@@ -12997,7 +13358,7 @@ async function upload({ clientKey, note = '--', dir, }) {
     }
 }
 
-var version = "0.3.9-beta.wasm.1";
+var version = "0.4.0";
 var pkg = {
 	version: version};