[Bug][Fix available] pnpm add -g 后 native binding 解析失败，dsh web 找不到已安装插件

[Scrates1]

Affected scenario

这个问题发生在发布版 DSH CLI 通过 pnpm 安装到用户级全局目录时，而不是在源码仓库中运行 pnpm dsh web：

pnpm add -g @deepseek-ai/dsh
dsh web

触发条件是全局安装采用隔离的 content-addressed / global virtual-store 布局：node-addon-require-builtin、共享的 node-addon-native-custom-loader 和当前平台包位于不同的物理包根目录，没有依赖 pnpm hoist。Node 22+ 正常启动，不额外传入 --expose-internals。

What the user sees

dsh web 在挂载 profile 中的 bare plugin specifier 时失败，错误形态是：

failed to import loader entry ...:
Cannot find module '@deepseek-ai/...' imported from ...

报错中的插件包实际上已经安装。用户通常看不到真正更早的错误，因为 Loader 会把 native bridge 当作可选能力并吞掉它：

No usable native binding found

随后 ModuleLoader.fromInternal() 返回 undefined，bare plugin import 改走普通动态导入，并从 vendored Loader 包而不是 profile / 已安装应用解析，于是产生误导性的二次 Cannot find module。

Root cause

node-addon-require-builtin 持有当前平台包作为自己的 optional dependency，并委托 node-addon-native-custom-loader 选择和加载平台包。共享 custom loader 却从自己的物理模块位置执行平台包 require()。

在 pnpm global virtual-store 中，平台包仍然存在并且能从 entry package 的依赖目录解析，但不在共享 custom loader 的祖先搜索路径中，因此 native entry 加载失败。

最小回归测试使用 rc.7 锁文件中的三个真实 0.1.4 包构造该布局，并证明：

• entry package 持有 custom loader 与当前平台包的依赖链接；
• 平台包已安装且能从 entry package 的依赖目录解析；
• 未修改的 native entry 仍稳定抛出 No usable native binding；
• 修复后的 ModuleLoader.fromInternal() 能得到 Node internal loader。

Fix

正常 native entry 加载失败后，Loader 按依赖所有权从 entry package 自己的依赖目录解析 custom loader 与平台包，再调用 platform bridge。NARB_DISABLE_OPTIONAL_PACKAGE=1 仍会明确禁用该路径，普通动态导入行为保持不变。

完整修复（基于 rc.7 的 99f6f02，共 2 commits）：

• 完整差异
• 主修复 ee3c84c
• 保留显式 opt-out 语义 6c54acf

Validation

• 隔离布局回归测试：2/2（正常加载 + 显式 opt-out）；
• Loader typecheck；
• 完整 lint/build；
• doc-sync：28/28；
• pre-push typecheck。

Scope

这项改动只修复 pnpm 用户级全局安装中的 native platform-package 解析路径。它不是 #2699 中“源码启动 + watch-only HMR 依赖契约”问题的修复，也不表示所有 dsh web 启动错误都有相同根因。

请维护者 review 这项依赖所有权解析修复是否符合 Loader 的预期语义；完整两提交已经可以供内部移植或 squash。

[denial123789]

I converted this failure mode into an operator-focused, source-pinned guide: Fix pnpm global native-binding plugin resolution.

The guide keeps three boundaries separate:

• global pnpm virtual-store layout versus a source checkout;
• a platform package being present on disk versus being resolvable from the shared loader's physical root;
• the swallowed native-helper failure versus the later, misleading bare-plugin import error.

For users on an affected release, the least invasive A/B is to preserve the failing global tree and run the same exact published version from a disposable project-local install. A release acceptance test should use a fresh isolated global prefix, mount a real bare plugin, cold-restart, and verify that the documented optional-package opt-out remains explicit. Broad hoisting, copied native binaries, and permanent --expose-internals flags can hide the boundary without repairing it.

The source references are pinned to 99f6f02; the page can be revised once an official release contains the reviewed fix.

[bharatagarwal]

确认一个 macOS arm64 的复现，补充两点细节：

环境：Node v24.11.0，dsh 0.1.0-rc.7（pnpm add -g），addon 解析到 node-addon-require-builtin@0.1.5。

根因链路（与主楼一致，附新证据）：

1. node-addon-native-custom-loader@0.1.5 的 loadEntry 以裸说明符 require('node-addon-require-builtin-darwin-arm64') 解析平台包，锚点在其自身模块位置。pnpm 全局 store-links 布局下，该模块向上回溯的路径上没有共享 node_modules 层（平台包只存在于 family 包自己的 virtual store 目录），因此 MODULE_NOT_FOUND → 整体报 No usable native binding found。
2. 平台 prebuilt 本身是好的：prebuilt/darwin-arm64-napi-v9.node 用绝对路径 require 可正常加载（Mach-O arm64，napi-v9）。
3. ModuleLoader.fromInternal() 静默返回 undefined 后，Loader 的 import(name) 退化为普通动态导入，锚定在 store 里的 cordis-plugin-loader 包，于是每个 bare plugin 名都报 ERR_MODULE_NOT_FOUND: Cannot find package ... imported from cordis-plugin-loader/lib/index.js。

对照：仓库内 pnpm dsh 之所以正常，是因为 workspace 安装存在 node_modules/.pnpm/node_modules 的 hoist 层，平台包恰好在回溯路径上；npm i -g（扁平布局）同理可用。这解释了为什么只有 pnpm 的隔离布局触发。

---

Confirming a macOS arm64 reproduction, with two additional details:

Environment: Node v24.11.0, dsh 0.1.0-rc.7 (pnpm add -g), addon resolved to node-addon-require-builtin@0.1.5.

Root-cause chain (matches the original report, new evidence attached):

1. node-addon-native-custom-loader@0.1.5 resolves the platform package with the bare specifier require('node-addon-require-builtin-darwin-arm64'), anchored at its own module location. Under pnpm's global store-links layout, that module's upward walk has no shared node_modules layer (the platform package exists only in the family package's own virtual store directory), so MODULE_NOT_FOUND → the overall No usable native binding found.
2. The platform prebuilt itself is fine: prebuilt/darwin-arm64-napi-v9.node loads normally when required by absolute path (Mach-O arm64, napi-v9).
3. After ModuleLoader.fromInternal() silently returns undefined, the Loader's import(name) degrades to a plain dynamic import anchored at the cordis-plugin-loader package in the store, so every bare plugin name reports ERR_MODULE_NOT_FOUND: Cannot find package ... imported from cordis-plugin-loader/lib/index.js.

Contrast: pnpm dsh inside the repo works because workspace installs have the node_modules/.pnpm/node_modules hoist layer, putting the platform package on the walk path; npm i -g (flat layout) works the same way. This is why only pnpm's isolated layout triggers it.

[sjh9714]

Confirmed this is still reproducible with published DSH 0.1.1-rc.2, Node 22.23.2, pnpm 11.24.0, macOS arm64, and both native-addon packages at 0.1.5.

The pnpm dlx @deepseek-ai/dsh@0.1.1-rc.2 runtime uses the global virtual-store layout and hits the same chain described here. I also reproduced the dependency-ownership failure without DSH in two fresh private projects, each depending only on node-addon-require-builtin@0.1.5:

• nodeLinker: isolated, hoist: false, enableGlobalVirtualStore: false: the platform package resolves from the family entry, its native binary loads directly (napi-v9), but it does not resolve from the shared loader. Loading the public family entry fails, with the optional-package attempt carrying MODULE_NOT_FOUND.
• nodeLinker: hoisted: the same platform package resolves from both locations and the public entry loads successfully.

With the published DSH runtime, the isolated path then reports ERR_MODULE_NOT_FOUND for official packages such as @deepseek-ai/dsh-settings-file. A separate local hoisted installation of the same DSH version passes the official web baseline's HTML/JavaScript readiness and process/port cleanup checks.

These tests kept the original profile intact and did not patch the pnpm store, copy native binaries into dependencies, add internal Node flags, or disable release-age/script-approval checks. Adding current-release evidence to this existing report; the dependency-ownership fix is still needed in an official release.