[0.1.6-alpha.2] 含 jsdom 的插件树无法启动：CJS 解析路由在 require("punycode/") 处崩溃（同 profile 在 alpha.1 正常）

[Cozieur]

TL;DR (EN) — On 0.1.6-alpha.2 a profile whose plugin tree pulls in jsdom (→ whatwg-url → tr46 → require("punycode/")) cannot boot: the plugin tree aborts inside ResolutionRouter.routeScoped, the host exits, and launchd restarts it forever. The identical profile boots and runs for days on 0.1.6-alpha.1 / 0.1.5-rc.1. Locally adding the ?? [] guard that the same file already uses elsewhere moves the failure one step further, to Cannot find module 'punycode/' inside resolveRoutedCjs.

环境

DSH	0.1.6-alpha.2（npm alpha tag 直装，失败）／对照 0.1.6-alpha.1（同机同 profile，正常）
OS / Node	macOS 27.0 (arm64) / Node v22.22.3
profile	web，18 个第三方 bundle

其中 4 个插件都依赖 jsdom（所以这不是很偏门的组合）：

插件	版本	jsdom
dsh-web-search-pro	0.1.12-alpha.5	^29.0.0 ← 第一个炸的 entry
dshmarket	1.46.1	^29.1.1
dsh-univer-office	0.2.14	^26.1.0
@a9i5k4/dsh-literature	0.3.6	^24.1.3

依赖链版本：jsdom 29.1.1 → whatwg-url 16.0.1 → tr46 6.0.0 → require("punycode/")。
punycode@2.3.1 已装在 profile 自己的 node_modules 里（这一步很关键，见第二层）。

复现

1. 任一 profile 装上会拉 jsdom 的插件（例如 dsh plugin --profile web add dsh-web-search-pro）；
2. 用 0.1.6-alpha.2 启动该 profile；
3. 现象：插件树加载失败 → 宿主退出 → KeepAlive 拉起 → 无限循环。

一个容易误判的点：循环期间服务偶尔能回 401/200（webserver 早于插件树绑定），所以「HTTP 通」不能当健康证据；真正的判据是 launchctl print 的 runs 计数在持续增长（本次从 1 涨到 24+）。

第一层错误

dsh: plugin tree failed to load: failed to apply loader entry include (cordis:include):
failed to import loader entry web-search-pro (dsh-web-search-pro):
createRequire.resolve.paths is not a function or its return value is not iterable
TypeError: createRequire.resolve.paths is not a function or its return value is not iterable
    at ResolutionRouter.routeScoped (…/@deepseek-ai/dsh-app-boot/lib/index.js:1327:58)
    at ResolutionRouter.routePath (…:1447:15)
    at Function.wrappedFilename [as _resolveFilename] (…:1747:24)
    at Module.require (node:internal/modules/helpers:147:16)
    at Object.<anonymous> (…/profiles/web/node_modules/tr46/index.js:3:18)

tr46/index.js 第 3 行是 require("punycode/")。Node 的 require.resolve.paths("punycode") 对核心模块名返回 null，而 routeScoped 直接

for (const searchPath of createRequire(parent).resolve.paths(name)) {

→ TypeError: … is not iterable。

值得注意的是：同一个文件里官方自己在另一处已经写了这个守卫（alpha.2 第 882 行：createRequire(anchor).resolve.paths(packageName) ?? []），但另外三处漏了——alpha.2 的第 1189 / 1327 / 1927 行（alpha.1 对应 1129 / 1267 / 1867）。

第二层错误（补上守卫之后暴露出来的）

本地把那三处补成 ?? [] 之后，崩溃点前移到路由本身：

failed to import loader entry web-search-pro (dsh-web-search-pro):
Cannot find module 'punycode/'
Require stack:
- …/profiles/web/node_modules/tr46/index.js
- …/profiles/web/node_modules/whatwg-url/lib/url-state-machine.js
- …/profiles/web/node_modules/whatwg-url/index.js
- …/profiles/web/node_modules/jsdom/lib/api.js
    at resolveRoutedCjs (…/@deepseek-ai/dsh-app-boot/lib/index.js:1705:28)
    at Function.wrappedFilename [as _resolveFilename] (…:1785:16)

也就是说：这个 punycode/（带尾斜杠的裸标识符）被路由接管后没能解析成功，而原生解析本应成功——…/profiles/web/node_modules/punycode/ 确实存在（2.3.1）。

为什么判断这是 alpha.2 的回归

• 同一 profile、同一批插件、同一 Node 版本：alpha.1 连续跑了 3 天无异常，换 alpha.2 后 60 秒内进入崩溃循环（首次拉起时还能 serve，随后即死）。
• 那三处未守卫的 resolve.paths 调用在 alpha.1 里也存在，说明变化点不是这行代码本身，而是这条 require 在 alpha.2 走到了这段路由。两版 dsh-app-boot/lib/index.js 有 563 行差异（alpha.2 新增了 dsh-lazy-require、dsh-atomic-write、dsh-plugin-manager、dsh-hmr 等包，并移除了 cordis-plugin-hmr）。

建议

1. 补守卫：createRequire(parent).resolve.paths(name) → … ?? []（1189 / 1327 / 1927 三处，与 882 行保持一致）。核心模块没有搜索路径，空迭代即回落到原生解析，语义正确。
2. 路由回退：resolveRoutedCjs 对「核心模块名」或「带尾斜杠的裸标识符」应直接交回原生解析；或在路由目标不存在时回退到原生解析，而不是抛 Cannot find module。
3. 可选：插件树加载失败时给出可判定的错误信号（错误码或 --json 字段），便于自动回滚——本次是靠 runs 计数才及时发现的。

附：如何确认是不是同一个问题

# 崩溃循环的判据（HTTP 不可信）
launchctl print gui/$UID/com.dongyue.dsh-web | grep -E "runs|last exit code"

# 判定性错误串
grep -m1 "createRequire.resolve.paths is not a function" ~/.dsh/web.err.log
grep -m1 "failed to import loader entry" ~/.dsh/web.err.log

当前已回滚到 0.1.6-alpha.1（vendor 整树回滚 + 服务恢复，三个 profile 均正常）。alpha.2 里那些新特性（插件管理页、HMR、文件改动卡片）很想用，等这条修好再上。

[PerryLink]

先给结论：确认是 alpha.2 的真实回归，你的定位基本全对，而且我找到了具体触发器——alpha.2 把普通启动的解析模式默认值从 link 改成了 runtime（commit 9ddef32），让 require("punycode/") 这条路径第一次走进了 CJS 解析路由；alpha.1 同文件同样没有守卫，只是这段代码根本没被执行到。

证据（均对照 HEAD = ddefc45，v0.1.6-alpha.2）：

• apps/cli/src/profile-boot.ts:263（HEAD）：const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'runtime'；alpha.1 同处是 ?? 'link'（git show dsh-v0.1.6-alpha.1:apps/cli/src/profile-boot.ts 可证）。同一文件 :312-315：hostCtx.plugin(PluginPackages, resolutionMode === 'link' ? {} : { generation: ..., behavior: ... })。
• packages/boot/app-boot/src/profile-resolution/service.ts:70：if (config.generation === undefined) return——link 模式根本不安装 _resolveFilename 包装器，所以 alpha.1 里那三处未守卫的 resolve.paths 永远跑不到。你的判断“变化点不是这行代码本身，而是这条 require 在 alpha.2 走到了这段路由”与源码完全一致；git diff dsh-v0.1.6-alpha.1..HEAD -- .../resolver.ts 为空（文件逐字节相同）。
• 崩溃点：resolver.ts:350 for (const searchPath of createRequire(parent).resolve.paths(name) as string[])（:165 同型；service.ts:112 是第三处）。我本机用 Node 22 验证：require.resolve.paths('punycode') === null、isBuiltin('punycode/') === false、isBuiltin('punycode') === true——barePackageName（resolver.ts:114-122）把带斜杠的 punycode/ 切成裸名 punycode，绕过了 isBuiltin 检查，随后对核心模块名取 paths 得到 null，for...of null 抛 TypeError。仓库里现成的守卫在 packages/boot/app-boot/src/profile.ts:835-837（... ?? []，注释写明 "resolve.paths returns null only for builtins"），对应你看到的编译产物 882 行；源码行号与 lib 行号不同，补丁应落在 resolver.ts:165、resolver.ts:350、service.ts:112 三处。

第二层失败（补守卫后的 Cannot find module 'punycode/'）含义：守卫让候选集为空（核心模块名没有搜索路径），routeScoped 落到 after-fallback，锚点取 join(dirname(profilesDir), 'package.json')（resolver.ts:392-397）；resolveRoutedCjs（resolver.ts:788-805）从这个锚点重建 synthetic.paths = cjs._nodeModulePaths(dirname(anchor))（:797-799）——这条链不含 profile 自己的 node_modules（punycode@2.3.1 所在地），而原生解析从 tr46 的父路径出发本可以命中。所以“补 ?? [] + 非受管裸名（含带尾斜杠者）直接交回原始 parent 的原生解析”正是完整修复的形状，与你的建议 1+2 一致。

临时规避：没有 profile 级开关（apps/cli/src/args.ts 无任何 resolution-mode flag，runCli 不传该选项）。稳妥做法就是你已经做的回滚 alpha.1；若必须跑 alpha.2 源码，可把 profile-boot.ts:263 改回 ?? 'link'（恢复 alpha.1 行为，link 模式不装路由），但这是改启动器源码、升级即被覆盖，风险自担。未验证：我无法在 macOS/launchd 环境重跑崩溃循环，第二层机制是按你的栈与上述代码路径推演。

如果你手上有 alpha.2 启动失败那几行的完整 stderr（~/.dsh/web.err.log），贴出来可以进一步确认是否还有别的 builtin 裸名走了同一路径。

[Cozieur]

感谢定位——「触发器是 resolutionMode 默认值从 link 改成 runtime」这条和我们的观察完全对得上，resolver.ts 两版逐字节相同也正是我们卡住的地方（我们最初按代码 diff 找变化点，找不到）。

补两样你问的东西。

1. 完整 stderr

环境：macOS 27.0 arm64 / Node v22.22.3 / 真实 web profile（非空 home），dsh 0.1.6-alpha.2。

第一层（~/.dsh/web.err.log，外层是插件树失败）：

[dsh-literature] uncaught exception: Error: dsh: plugin tree failed to load: failed to apply loader entry include (cordis:include): failed to import loader entry web-search-pro (dsh-web-search-pro): createRequire.resolve.paths is not a function or its return value is not iterable
TypeError: createRequire.resolve.paths is not a function or its return value is not iterable
    at ResolutionRouter.routeScoped (file:///Users/dongyue/.dsh/vendor/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js:1327:58)
    at ResolutionRouter.routePath (file:///Users/dongyue/.dsh/vendor/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js:1447:15)
    at Function.wrappedFilename [as _resolveFilename] (file:///Users/dongyue/.dsh/vendor/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js:1747:24)
    at defaultResolveImpl (node:internal/modules/cjs/loader:1040:19)
    at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1045:22)
    at Function._load (node:internal/modules/cjs/loader:1216:25)
    at wrapModuleLoad (node:internal/modules/cjs/loader:254:19)
    at Module.require (node:internal/modules/cjs/loader:1527:12)
    at require (node:internal/modules/helpers:147:16)
    at Object.<anonymous> (/Users/dongyue/.dsh/profiles/web/node_modules/tr46/index.js:3:18)
    at boot (file:///Users/dongyue/.dsh/vendor/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js:2738:9)

宿主随后退出，三个 profile 服务全部进入 KeepAlive 循环（runs 10 秒内从 11 涨到 17，PID 撑不过 40s）。

第二层（本地把 lib 里那三处补上 ?? [] 之后，崩点前移）：

Cannot find module 'punycode/'
Require stack:
- /Users/dongyue/.dsh/profiles/web/node_modules/tr46/index.js
- /Users/dongyue/.dsh/profiles/web/node_modules/whatwg-url/lib/url-state-machine.js
- /Users/dongyue/.dsh/profiles/web/node_modules/whatwg-url/lib/URL-impl.js
- /Users/dongyue/.dsh/profiles/web/node_modules/whatwg-url/lib/URL.js
- /Users/dongyue/.dsh/profiles/web/node_modules/whatwg-url/webidl2js-wrapper.js
- /Users/dongyue/.dsh/profiles/web/node_modules/whatwg-url/index.js
- /Users/dongyue/.dsh/profiles/web/node_modules/jsdom/lib/api.js
    at Function.<anonymous> (node:internal/modules/cjs/loader:1430:15)
    at resolveRoutedCjs (file:///Users/dongyue/.dsh/vendor/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js)

（punycode@2.3.1 就在 profiles/web/node_modules/punycode，原生解析从 tr46 的父路径出发本可命中。）

2. 还有没有别的 builtin 裸名走同一路径：扫下来只有这一个

范围 = 本机真实依赖面三个根（vendor/node_modules、profiles/web/node_modules、~/dsh-plugins），共 13590 个 .js/.cjs/.mjs。匹配 require("X/…") / import … from "X/…"（X 为 Node builtin 名），再对完整 specifier 逐条跑 isBuiltin() 判可达性：

specifier	isBuiltin(spec)	命中	后果
punycode/	false	1 处：profiles/web/node_modules/tr46/index.js:3	唯一会进 CJS 路由的
fs/promises	true	20 处	不进路由
stream/web	true	1 处	不进路由

所以至少在 macOS + 这套插件面上是单点触发：把 isBuiltin() 返回 false 而裸名又是 builtin 的候选集筛出来，只剩 punycode/ 一行。（fs/promises 这类带斜杠但被 Node 认作 builtin 的会正常返回 true，可以直接排除。）

补充一条对照：崩溃后整树回滚 alpha.1，同一份 profile 立刻正常（三个服务 runs=1、连续运行 >1 天、3080 回 401）。

---