[Fix] dsh web fails to launch on Node 24.0–24.11.1: loader resolveSync shape probe (with patch + verification)

[Shizuku-keop]

中文摘要

0.1.2-alpha.1 在 Node 24.0–24.11.1 下启动失败（浏览器报 HTML did not preload @deepseek-ai/dsh-client-modules/client.js，讨论 #4885 / #4959 / #4955）。根因已源码级定位并完成修复验证：

• vendor/loader/src/internal.ts 的 ModuleLoader.fromInternal() 对所有 major >= 24 无条件标记 version: 'v2'，但 v2 接口（resolveSync(parentURL, request) + getOrCreateModuleJob）直到 Node 24.12.0 才引入；24.0–24.11.1 仍是 v1 形状（resolveSync(specifier, parentURL, attributes)）。
• packages/client/modules/src/index.ts 的 locatePkgJson() 已有 v1/v2 双分支，但判断依据是 internal.version（被误标）→ v2 形状调用抛 TypeError → catch 静默吞掉 → resolveMeta 缓存 null → client 表空 → __DSH_BOOT__.entries = [] → preload 0 → 浏览器报错，且服务端零日志。
• arity 不可靠（24.11.1 的 resolveSync arity 也是 2）；可靠判据 = getOrCreateModuleJob / getModuleJobForImport 存在性，两 API 皆无时用实际调用试探。

修复（单包两处改动，不动 vendor/）：

1. 新增 resolveLoaderShape()：按 API 存在性判定 v1/v2，兜底调用试探，进程内缓存；
2. locatePkgJson() 改用探测结果调用；catch 失败时 logger.warn（一次/名+树），不再静默。

补丁：https://gist.github.com/Shizuku-keop/a471fe04621f416cb34138a0d1eb44b0

验证（真机，本机 Node 24.19.0 + portable Node 24.11.1）：

环境	修复前	修复后
Node 24.11.1（v1 形状）	HTML 2520B，entries=[]，preload 0，script 缺失	HTML 25396B，preload 46 bundles，script 存在 ✅
Node 24.19.0（v2 形状）	正常（基线）	25396B，与基线逐字节一致，不回归 ✅

单测：packages/client/modules 83/83 全绿（新增两条回归：误标 v2 的 v1 loader 走 v1 调用；resolve 抛错 warn 一次+缓存静默）。

感谢 #4885 中 programmingWTF 的形状探测建议与 good770326 的 minor 版本判断、以及 #4955/#4957 报告者。

English

Problem: dsh web 0.1.2-alpha.1 fails to launch on Node 24.0–24.11.1 with HTML did not preload @deepseek-ai/dsh-client-modules/client.js (#4885, #4959, #4955). Root cause, fix, and real-machine verification below.

Root cause: vendor/loader/src/internal.ts ModuleLoader.fromInternal() tags every major >= 24 loader as version: 'v2', but the v2 internal API (resolveSync(parentURL, request) + getOrCreateModuleJob) only lands in Node 24.12.0. On 24.0–24.11.1 the loader is still v1-shaped. packages/client/modules/src/index.ts locatePkgJson() already has a v1/v2 branch but keys off the mislabeled internal.version; the v2-shaped call throws TypeError, the catch swallows it, resolveMeta caches null, the client table comes out empty, __DSH_BOOT__.entries = [], zero preloads, and the browser reports the error with no server-side log.

Note: arity is not a reliable discriminator (v1 resolveSync reports arity 2 on 24.11.1). Reliable signals: presence of getOrCreateModuleJob (v2) / getModuleJobForImport (v1); a real call probe when neither API exists.

Fix (one package, two hunks, vendor/ untouched):

1. New resolveLoaderShape(): decide by API presence, fall back to a call probe, cache per process.
2. locatePkgJson() calls with the probed shape; on failure logger.warn once per name+tree instead of silently emptying the graph.

Patch (gist, also on branch fix/node24-loader-shape-probe of my fork): https://gist.github.com/Shizuku-keop/a471fe04621f416cb34138a0d1eb44b0

Verification (real machines: system Node 24.19.0 + portable Node 24.11.1):

Env	Before	After
Node 24.11.1 (v1)	HTML 2520B, entries=[], 0 preloads, no script	HTML 25396B, 46 preloads, script present ✅
Node 24.19.0 (v2)	OK (baseline)	25396B, byte-identical to baseline, no regression ✅

Tests: packages/client/modules 83/83 green (new regressions: mislabeled-v2 v1 loader resolves via v1 call; resolve throw warns once + cached negative stays silent).

Credits: programmingWTF's shape-probe suggestion and good770326's minor-version analysis in #4885.

Changelog

• 2026-08-29: initial posting with patch, verification matrix, and tests.