dsh-code-server-app 0.3.44 → 0.3.46

package/README.en.md

@@ -10,7 +10,7 @@
 > - Microsoft **open-source** extensions (Python, TypeScript debugger, ESLint, …) are mirrored on Open VSX and install normally by search;
 > - **If you need a proprietary Microsoft extension**: download the `.vsix` from the Marketplace page and install it manually with `code-server --install-extension <file>` (or drop it into `--extensions-dir`).
 
-A static profile plugin (npm package with host + client bundle) that ships the **VS Code server tree** from a [code-server](https://github.com/coder/code-server) release as a **platform-independent dependency package** (pack-time artifact `vendor/vscode` → `@jinsiyu/dshcs-vscode-server`, no install scripts, no postinstall). The code-server **Node service layer is replaced by the plugin's own `lib/launcher.mjs`**: it drives `<tree>/lib/vscode/out/server-main.js` (`loadCodeWithNls()` / `createServer()` / `handleRequest()` / `handleUpgrade()`) directly and re-adds the few HTTP endpoints code-server used to provide (`/healthz`, `/manifest.json`, `/_static/*`, `/proxy/:port`). The 16 native modules (node-pty / @vscode/sqlite3 / spdlog / …) come from `@jinsiyu/dshcs-*-win32-<arch>` platform packages selected automatically per architecture by the platform aggregator. VS Code's inner dependencies and the prebuilt native modules are **all installed by the package manager together with the plugin** — no global npm install, no `bin` configuration, no profile config changes, no second install command, **no argon2/C++ toolchain**.
+A static profile plugin (npm package with host + client bundle) that ships the **VS Code server tree** from a [code-server](https://github.com/coder/code-server) release as a **platform-independent dependency package** (pack-time artifact `vendor/vscode` → `@jinsiyu/dshcs-vscode-server`, no install scripts, no postinstall). The code-server **Node service layer is replaced by the plugin's own `lib/launcher.mjs`**: it drives `<tree>/lib/vscode/out/server-main.js` (`loadCodeWithNls()` / `createServer()` / `handleRequest()` / `handleUpgrade()`) directly and re-adds the few HTTP endpoints code-server used to provide (`/healthz`, `/manifest.json`, `/_static/*`, `/proxy/:port`). The 16 native modules (node-pty / @vscode/sqlite3 / spdlog / …) come from `@jinsiyu/dshcs-*` sub-packages declared **directly on the plugin's dependency table** under their real names (os/cpu-gated per target), with the original import names restored by runtime junctions. VS Code's inner dependencies and the prebuilt native modules are **all installed by the package manager together with the plugin** — no global npm install, no `bin` configuration, no profile config changes, no second install command, **no argon2/C++ toolchain**.
 
 > Since 0.3.22 the ask panel renders the session's new content with **DSH's own Markdown renderer** (the same
 > renderer and design tokens as the DSH UI; new content only) and can **answer approval requests in place**
@@ -390,11 +390,12 @@ Diagnostics: `GET /api/code-server/status` exposes
   "Install the plugin (script-free install; code-server bundled)" below — `pnpm install` → `pnpm run build:client` →
   `pnpm run vendor:vscode` → `pnpm pack` + `dsh plugin --profile web add`.
 
-> Verified locally (BM: Windows 11 ARM64): the whole tree/dependency chain is supplied by per-platform
-> sub-packages — the tree package `@jinsiyu/dshcs-vscode-server` (currently 4.137.0, a 50.8 MB tarball),
-> the pure-JS inner dependencies directly in the plugin's `dependencies`, and 16 prebuilt native modules
-> re-exported under their original names by the aggregator `@jinsiyu/dsh-code-server-runtime-win32-<arch>`
-> (picked by os/cpu) → healthz 200 → stopped → fully recycled.
+> Verified locally (BM: Windows 11 ARM64): the whole tree/dependency chain hangs directly off the plugin's
+> dependency table — the tree package `@jinsiyu/dshcs-vscode-server` (currently 4.137.0, a 50.8 MB tarball),
+> the pure-JS inner dependencies plus the 8 platform-independent repacks in `dependencies`, and the 8
+> platform-specific repacks (win32-arm64 / win32-x64) in `optionalDependencies` with their own os/cpu gates;
+> the original names are restored by junctions created at runtime (`lib/native.js`)
+> → healthz 200 → stopped → fully recycled.
 > (The 0.1.37-era "one big platform package" layout is gone — see "Upgrading the VS Code tree" below.)
 
 ## Packaging (how to build the tarball)
@@ -419,7 +420,7 @@ pnpm run promote -- <version>
 > `pnpm run promote -- <version>` (= `npm dist-tag add dsh-code-server-app@<version> latest`)
 > **after the user restarts `dsh web` and confirms it works**. That way
 > `dsh plugin add dsh-code-server-app` (no version) — and anything else resolving `latest` — never picks up an
-> unverified build. Sub-packages (`@jinsiyu/dshcs-*`, the aggregators) are referenced by exact/caret versions,
+> unverified build. Sub-packages (`@jinsiyu/dshcs-*`) are referenced by exact versions,
 > so their dist-tags do not affect resolution, but they default to `next` as well.
 > Inspect the current tags with `npm dist-tag ls dsh-code-server-app`.
 
@@ -436,8 +437,8 @@ pnpm run promote -- <version>
 | Sub-package | Content | os/cpu |
 |---|---|---|
 | `@jinsiyu/dshcs-vscode-server@<code-server version>` | the trimmed VS Code tree (`lib/vscode` + `out/browser` + `src/browser`; **without** code-server's `out/node` and its 136 runtime deps) | platform-independent |
-| `@jinsiyu/dshcs-<name>[-win32-<arch>]` ×24 | the VS Code inner packages that need building (node-pty / @vscode/sqlite3 / kerberos / koffi / ssh2 / …) | gated when platform-specific |
-| `@jinsiyu/dsh-code-server-runtime-win32-<arch>` | platform aggregator: its `dependencies` map those 16 natives back to their original names via `npm:` aliases | win32-<arch> |
+| `@jinsiyu/dshcs-<name>[-win32-<arch>]` ×16 | the VS Code inner packages that need building (node-pty / @vscode/sqlite3 / kerberos / koffi / ssh2 / …) | gated when platform-specific |
+| `lib/vendored.json` (**not** a package) | the "original name → repack sub-package" table shipped inside the plugin; `lib/native.js` uses it to create the junctions. Since 0.3.45 there is **no platform aggregator** | — |
 
 | Goal | Command |
 |---|---|
@@ -445,7 +446,7 @@ pnpm run promote -- <version>
 | **Pin a version** | `pnpm run vendor:vscode -- --version 4.137.0` |
 | **Snapshot from an existing tree** | `pnpm run vendor:vscode -- --from <code-server dir>` (seconds) |
 | **Rebuild every sub-package** | `pnpm run repack:build -- --target win32-arm64,win32-x64 --pack` (without `--from` it npm-installs and compiles the source tree itself — slow) |
-| **Rebuild only the tree/aggregator packages** | `node scripts/vendor-repacks.mjs --reuse --target win32-arm64,win32-x64 --pack` (reuses the natives already in `repack/build`) |
+| **Rebuild only the tree + dependency table** | `node scripts/vendor-repacks.mjs --reuse --target win32-arm64,win32-x64 --pack` (reuses the natives already in `repack/build`; also rewrites `lib/vendored.json` and the plugin dependency table) |
 | **Publish sub-packages** | `pnpm run publish:repacks` (`--dry-run` to preview; `--only <substr>` to filter; `--otp <code>` / `--limit N` for 2FA) |
 | **Publish the plugin itself** | `pnpm run publish:plugin` (publishes the exact tarball that was verified; no re-packing; default dist-tag `next`) |
 | **Promote `latest`** | `pnpm run promote -- <version>` (only after the user restarted and confirmed; `--dry-run` shows the current tags first) |
@@ -474,10 +475,13 @@ The main package is only **~110KB** (the plugin's own code plus the launcher); e
   `@jinsiyu/dshcs-code-server/code-server` is still recognised as a fallback);
 - the **pure-JS part** of VS Code's inner dependencies (35 packages: xterm / katex / typescript / ws / tar …) is
   declared in the plugin's `dependencies` and installed by pnpm into the profile's `node_modules` (hoisted);
-- the **binary part** comes entirely from `@jinsiyu/dshcs-*` platform packages: 16 native packages mapped back to their
-  **original names** (`node-pty` / `@vscode/sqlite3` / `@vscode/spdlog` / …) by the **platform aggregator**
-  `@jinsiyu/dsh-code-server-runtime-win32-<arch>` using `npm:` aliases; the aggregators sit in the plugin's
-  `optionalDependencies`, so pnpm auto-selects the right platform;
+- the **binary part** comes entirely from `@jinsiyu/dshcs-*` sub-packages, declared **directly on the plugin's own
+  dependency table** (since 0.3.45): the 8 platform-independent repacks (`node-pty` / `koffi` / `ssh2` /
+  `cpu-features` / `@parcel/watcher` / `@vscode/fs-copyfile` / `@vscode/proxy-agent` / `@microsoft/mxc-sdk`) go into
+  `dependencies` under their real names; the 8 platform-specific ones (`@vscode/sqlite3` / `spdlog` / `kerberos` /
+  `deviceid` / `native-watchdog` / `windows-registry` / `windows-process-tree` / `windows-ca-certs`) go into
+  `optionalDependencies` once per target (real names + their own os/cpu gates), so one command picks the right arch;
+  the **original names** are restored at runtime by junctions created from `lib/vendored.json`;
 - consequently the dependency graph contains **no package with pre/install/postinstall or a `binding.gyp`** →
   no profile `allowBuilds`, no build script ever runs, and **the user machine needs no C++ toolchain**;
 - **upgrading the plugin no longer re-downloads the tree**: the tree package is cached by version
@@ -500,10 +504,15 @@ The main package is only **~110KB** (the plugin's own code plus the launcher); e
   **removed** (the built `.node` and every runtime file stay) → sibling packages in its dependency list become `npm:`
   aliases → platform-specific ones get `os`/`cpu` plus a `-<platform>-<arch>` suffix. For win32 targets the script also
   verifies each `.node` PE machine (0x8664=x64 / 0xaa64=arm64) so a cross-compiled artifact cannot ship the wrong arch;
-- **the platform aggregator** maps those repacks back to their original names (e.g.
-  `"node-pty": "npm:@jinsiyu/dshcs-node-pty@1.2.0-beta.15"`), so VS Code's `import('node-pty')` needs no change; the
-  aggregator is itself `os`/`cpu` gated, and the plugin declares both win32-arm64 and win32-x64 in
-  `optionalDependencies`, so one command picks the right one;
+- **how the original names come back** (since 0.3.45): a repack's real name is `@<scope>/dshcs-<name>` while VS Code
+  imports `node-pty` / `@vscode/sqlite3`; pack time writes the "original name → real name" table into
+  `lib/vendored.json` (shipped with the plugin) and `lib/native.js` creates `<tree>/node_modules/<original name>`
+  junctions to the real directories (idempotent, self-healing).
+  **Why the old "platform aggregator + `npm:` aliases" is gone**: pnpm's incremental hoisted install drops those
+  aliased packages when they sit inside an **optional subtree** (measured: 9 of 16 missing) while dsh-desktop
+  validates the dependency graph right after the install ⇒ the first install always failed with `requires missing`;
+  with real-name direct dependencies the same install command plus the validator's own predicate passes end to end
+  (reproduction in `docs/desktop-first-install-root-cause.md`);
 - **resolution path**: the host finds the tree with `require.resolve('@jinsiyu/dshcs-vscode-server/package.json')`
   (then the inner `vscode/` directory) and the entry is `vscode/lib/vscode/out/server-main.js`; VS Code's inner deps are
   resolved upwards from that root (`vscode/lib/vscode/node_modules` → package `node_modules` → `<profile>/node_modules`).
@@ -511,8 +520,8 @@ The main package is only **~110KB** (the plugin's own code plus the launcher); e
 - **runtime layout self-healing** (`ensureRuntimeLayout()` in `lib/native.js`, idempotent, run **at activation before
   `envCheck` and again before every start**): the host adds two kinds of **junctions** (Windows junctions / POSIX dir
   symlinks) into the tree:
-  1. `ensureAliasLinks()`: re-links the native aliases the aggregator carries into `<tree>/node_modules` — pnpm nests
-     `os`/`cpu`-gated packages under the aggregator's own `node_modules`, and `lib/vscode/out/server-main.js` uses
+  1. `ensureAliasLinks()`: links the 16 **original names** listed in `lib/vendored.json` into `<tree>/node_modules`
+     — the real-name packages live in the plugin's dependency graph, and `lib/vscode/out/server-main.js` uses
      **ESM imports** (ESM ignores `NODE_PATH`), so a missing link means an immediate 500;
   2. `ensureInnerModuleLinks()`: restores VS Code's **inner dependency directories**
      `lib/vscode/node_modules` and `lib/vscode/extensions/node_modules` from the two `package.json` files — the trimmed

package/README.md

@@ -15,7 +15,7 @@
 无安装脚本、无 postinstall);**code-server 的 Node 服务层已由插件自带的 `lib/launcher.mjs` 取代**
 (它直接驱动 `<树>/lib/vscode/out/server-main.js` 的 `loadCodeWithNls()` / `createServer()` / `handleRequest()` /
 `handleUpgrade()`,并补上 `/healthz`、`/manifest.json`、`/_static/*`、`/proxy/:port` 这几条 code-server 原本提供的 HTTP 面);
-原生模块(node-pty / @vscode/sqlite3 / spdlog …)由 `@jinsiyu/dshcs-*-win32-<架构>` 平台包经聚合包按架构自动选中 ——
+原生模块(node-pty / @vscode/sqlite3 / spdlog …)由 `@jinsiyu/dshcs-*` 子包按**真名直接挂在插件依赖上**、按 os/cpu 自动选中 ——
 **无需全局 npm 安装、无需配置 `bin`、无需改 profile 配置、无需第二条安装命令、无需 argon2/C++ 工具链**。
 
 > 0.2.0 起:**argon2 与 code-server 的 136 个运行时依赖(express / proxy-agent / js-yaml / pem / limiter …)
@@ -365,10 +365,11 @@ host 反向请求不到它。所以编辑器状态只能在扩展主动发起的
   "打包(如何出包)"执行 `pnpm install` → `pnpm run build:client` → `pnpm run vendor:vscode` →
   (发布预编译原生包)→ `pnpm pack` + `dsh plugin --profile web add` 即可。
 
-> 本机(BM: Windows 11 ARM64)实测:树/依赖全链路是"平台子包 + 聚合包"供给 ——
-> 树包 `@jinsiyu/dshcs-vscode-server`(当前 4.137.0,50.8 MB tgz)、纯 JS 内部依赖直接进插件
-> `dependencies`、16 个预编译原生包经平台聚合包 `@jinsiyu/dsh-code-server-runtime-win32-<arch>`
-> (按 os/cpu 自动选)装回原名 → healthz 200 → 停止 → 回收全链路验证。
+> 本机(BM: Windows 11 ARM64)实测:树/依赖全链路是"平台子包直挂插件依赖"供给 ——
+> 树包 `@jinsiyu/dshcs-vscode-server`(当前 4.137.0,50.8 MB tgz)、纯 JS 内部依赖与 8 个平台无关
+> 重打包包直接进插件 `dependencies`、8 个平台专属重打包包按 win32-arm64/x64 进
+> `optionalDependencies`(包自带 os/cpu 自动选),原始名字由 `lib/native.js` 补 junction 还原
+> → healthz 200 → 停止 → 回收全链路验证。
 > (0.1.37 时代的主包形态已废弃,见下方"升级 VS Code 树"。)
 
 ## 打包(如何出包)
@@ -398,8 +399,18 @@ pnpm run promote -- <version>
 > `latest` 只保留「最近一个确认无 bug 的版本」,由 `pnpm run promote -- <version>`
 > (= `npm dist-tag add dsh-code-server-app@<version> latest`)在**用户重启 dsh web 确认无误后**才推进。
 > 这样 `dsh plugin add dsh-code-server-app`(不带版本)和任何按 latest 安装的流程都不会拿到未验证的版本。
-> 子包(`@jinsiyu/dshcs-*`、聚合包)被依赖以精确/插入符版本引用,dist-tag 不影响解析,但同样默认发 `next`。
+> 子包(`@jinsiyu/dshcs-*`)被依赖以**精确版本**引用(平台专属的按目标各钉一份),dist-tag 不影响解析,但同样默认发 `next`。
 > 查看当前标签:`npm dist-tag ls dsh-code-server-app`。
+>
+> **desktop profile 不走命令行安装**(2026-09-13 起的约定):对 desktop 只做 `pnpm pack` + `publish:plugin`(发 `next`),
+> 由用户在 DSH Desktop 里用**官方安装方式**自行安装;不要再把 tarball 文件级覆盖进 `~/.dsh/profiles/desktop` ——
+> 那条路会绕过 desktop 应用自己的依赖闭包检查,把真实的解析问题掩盖成"装上了但行为怪"。
+> web profile 仍可照旧安装验证。
+>
+> **0.3.45 起没有平台聚合包**,`requires missing @microsoft/mxc-sdk@npm:…` 那类报错不会再出现。根因(实测):
+> pnpm 的**增量 hoisted 安装**会漏链「可选子树里的 `npm:` 别名包」,16 个里漏 9 个(第一个就是 mxc-sdk),而
+> dsh-desktop 在 `pnpm add` 之后**立刻**校验依赖图 ⇒ 首次安装必失败;重启后应用走「删 node_modules + 完整安装」
+> 才补齐 ⇒ 就是你看到的"重启自己装好了"。复现命令与两条修法见 `docs/desktop-first-install-root-cause.md`。
 
 `repack:build`(`scripts/vendor-repacks.mjs`)是**唯一的子包产出脚本**,一次生成:
 
@@ -407,7 +418,7 @@ pnpm run promote -- <version>
 |---|---|---|
 | `@jinsiyu/dshcs-vscode-server@<code-server 版本>` | 精简 VS Code 树(`lib/vscode` + `out/browser` + `src/browser`,**不含** code-server 的 `out/node` 与 136 个运行时依赖) | 平台无关 |
 | `@jinsiyu/dshcs-<名字>[-win32-<arch>]` ×16 | VS Code 内部依赖里需要构建的原生包(node-pty / @vscode/sqlite3 / kerberos / koffi / ssh2 / spdlog / …) | 平台专属带 os/cpu |
-| `@jinsiyu/dsh-code-server-runtime-win32-<arch>` | 平台聚合包:`dependencies` 用 `npm:` 别名把上面 16 个原生包装回原始名字 | win32-<arch> |
+| `lib/vendored.json`(**不是包**) | 「原名 → 重打包子包」表,随插件发布;运行时由 `lib/native.js` 据此补 junction。0.3.45 起**不再产出平台聚合包** | — |
 
 > argon2 已随 code-server 服务层一起移除(0.2.0):`auth` 固定 `none`,需要对外访问请用 `serve: dsh`。
 
@@ -418,7 +429,7 @@ pnpm run promote -- <version>
 | **从已装好的树快照** | `pnpm run vendor:vscode -- --from <code-server 目录>`(秒级) |
 | **开发期让树可直接跑** | `pnpm run vendor:vscode -- --dev-links`(额外把 `lib/vscode/node_modules` 用 junction 补上) |
 | **完整重打子包** | `pnpm run repack:build -- --target win32-arm64,win32-x64 --pack`(不给 `--from` 会自动 npm install 解包 + 编译,耗时) |
-| **只重打树包/聚合包** | `node scripts/vendor-repacks.mjs --reuse --target win32-arm64,win32-x64 --pack`(复用 `repack/build` 里已有的原生包,不重新分析源树) |
+| **只重打树包 + 依赖表** | `node scripts/vendor-repacks.mjs --reuse --target win32-arm64,win32-x64 --pack`(复用 `repack/build` 里已有的原生包,不重新分析源树;顺带重写 `lib/vendored.json` 与插件依赖表) |
 | **发布子包** | `pnpm run publish:repacks`(`--dry-run` 预览;`--only <子串>` 过滤;`--otp <code>` / `--limit N` 应对 2FA) |
 | **发布插件本体** | `pnpm run publish:plugin`(发布**已验证过的那份 tarball**,不会重新打包;默认 dist-tag = `next`) |
 | **推进 latest** | `pnpm run promote -- <version>`(用户重启确认无误后;`--dry-run` 先看当前标签) |
@@ -439,6 +450,7 @@ pnpm test:webview            # 面板 webview 产物:官方渲染器与令牌打
 pnpm test:launcher-routes    # launcher 的 HTTP 面(起真进程,较慢)
 pnpm test:workspace-switch   # 切工作区不重启进程
 pnpm test:fullscreen         # 打开标签即全屏
+pnpm test:vendored           # 重打包表 ↔ 插件依赖表一致(无 npm: 别名 / 无聚合包 / vendored.json 进了 files)
 ```
 
 > `test:bridge-routes` 会把 `DSH_HOME` 指向临时目录(否则它会 adopt 开发机上正在跑的那个实例,
@@ -461,9 +473,13 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-
   `<profile>\node_modules\@jinsiyu\dshcs-vscode-server\vscode`;
 - VS Code 内部依赖里**纯 JS 的部分**(35 个:xterm / katex / typescript / ws / tar …)也写在插件
   `dependencies`,由 pnpm 装到 profile 的 `node_modules`(hoisted);
-- **二进制部分**全部由 `@jinsiyu/dshcs-*` 平台包提供(每个平台各一份,os/cpu 限定):
-  16 个原生包经**平台聚合包** `@jinsiyu/dsh-code-server-runtime-win32-<arch>` 用 `npm:` 别名装回**原始名字**
-  (`node-pty` / `@vscode/sqlite3` / `@vscode/spdlog` / …),聚合包挂在插件 `optionalDependencies` → pnpm 按架构自动选;
+- **二进制部分**全部由 `@jinsiyu/dshcs-*` 子包提供,且**直接挂在插件依赖上**(0.3.45 起):
+  平台无关的 8 个(`node-pty` / `koffi` / `ssh2` / `cpu-features` / `@parcel/watcher` /
+  `@vscode/fs-copyfile` / `@vscode/proxy-agent` / `@microsoft/mxc-sdk`)写进插件 `dependencies`(真名);
+  平台专属的 8 个(`@vscode/sqlite3` / `spdlog` / `kerberos` / `deviceid` / `native-watchdog` /
+  `windows-registry` / `windows-process-tree` / `windows-ca-certs`)按 win32-arm64 与 win32-x64
+  各一份写进 `optionalDependencies`(真名 + 包自带 os/cpu)→ 一条命令自动选对架构;
+  **原始名字**由 `lib/native.js` 运行时补 junction 还原(见下「运行时布局自愈」);
 - 因此依赖图里**没有任何带 pre/install/postinstall 或 binding.gyp 的包** →
   不需要 profile 的 `allowBuilds`、不执行任何构建、**使用者机器不需要 C++ 工具链**;
 - **升级插件不再重下树**:树包版本按上游 code-server 版本缓存,pnpm 直接复用(约 60MB,解包 ≈197MB)。
@@ -484,18 +500,21 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-
   (保留编译好的 `.node` 与全部运行时文件)→ 依赖里的同集包改成 `npm:` 别名 → 平台专属的加
   `os`/`cpu` 与 `-<platform>-<arch>` 后缀;win32 目标还会校验 `.node` 的 PE machine
   (0x8664=x64 / 0xaa64=arm64),防交叉编译产物装错架构;
-- **平台聚合包**把重打包包按原始名字装回去(如 `"node-pty": "npm:@jinsiyu/dshcs-node-pty@1.2.0-beta.15"`),
-  于是 VS Code 的 `import('node-pty')` 不用改;聚合包本身 `os`/`cpu` 限定,
-  插件 `optionalDependencies` 同时声明 win32-arm64 与 win32-x64 两份 → 一条命令自动选对;
+- **原始名字怎么还原**(0.3.45 起):重打包包的真名是 `@<scope>/dshcs-<名字>`,而 VS Code `import` 的是
+  `node-pty` / `@vscode/sqlite3` 这类**原名**;打包期把「原名 → 真名」写进 `lib/vendored.json`(随插件发布),
+  运行时由 `lib/native.js` 在 `<树>/node_modules/<原名>` 补 junction 指向真名包(幂等、可自愈)。
+  **为什么不再用「平台聚合包 + `npm:` 别名」**:pnpm 的增量 hoisted 安装会漏链**可选子树**里的别名包
+  (实测 16 个漏 9 个),而 dsh-desktop 安装后立刻校验依赖图 ⇒ 首次安装必报 requires missing;
+  改成真名直接依赖后,同一条安装命令 + 校验器判据实测全部通过(复现见 `docs/desktop-first-install-root-cause.md`);
 - **解析路径**:host 用 `require.resolve('@jinsiyu/dshcs-vscode-server/package.json')` 找到运行根
   (包内子目录 `vscode/`),入口 `vscode/lib/vscode/out/server-main.js`;VS Code 内部依赖从该运行根向上查找
   (`vscode/lib/vscode/node_modules` → 包 `node_modules` → `<profile>/node_modules`)。
   (旧全量树 `@jinsiyu/dshcs-code-server/code-server` 仍作为回退被识别。)
 - **运行时布局自愈**(`lib/native.js` 的 `ensureRuntimeLayout()`,**激活时(先于 envCheck)与每次启动前**幂等执行):
   host 会在 VS Code 树里补两类 **junction**(Windows junction / POSIX 目录软链):
-  1. `ensureAliasLinks()`:把聚合包带回的原生别名补到 `<树>/node_modules`
-     —— pnpm 会把 `os`/`cpu` 限定的包**嵌套装在聚合包自己的 node_modules 下**,而 VS Code 的
-     `lib/vscode/out/server-main.js` 用 **ESM import**(ESM 不认 `NODE_PATH`),缺了就直接 500;
+  1. `ensureAliasLinks()`:按 `lib/vendored.json` 把 16 个**原始名字**补到 `<树>/node_modules`
+     —— 真名子包装在插件依赖图里,而 VS Code 的 `lib/vscode/out/server-main.js` 用 **ESM import**
+     (ESM 不认 `NODE_PATH`),缺了就直接 500;
   2. `ensureInnerModuleLinks()`:把 VS Code 的**内部依赖目录** `lib/vscode/node_modules` 与
      `lib/vscode/extensions/node_modules` 按两个 `package.json` 的 `dependencies` 补回老布局
      —— 精简树里没有这两个目录,**用显式路径拼依赖的代码**
@@ -531,7 +550,7 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app
 
 > 源码路径以 `link:` 安装。开发机上没有 `vendor/vscode` 时先 `pnpm run vendor:vscode -- --dev-links`;
 > 没有平台子包时 host 会回退到包内 `vendor/code-server`(两种布局都支持)。
-> 依赖(内部 JS 依赖 + 平台子包 + 聚合包)同样由 pnpm 安装 —— 本地未发布的 `@jinsiyu/*` 需先发布,
+> 依赖(内部 JS 依赖 + 重打包子包)同样由 pnpm 安装 —— 本地未发布的 `@jinsiyu/*` 需先发布,
 > 或把 `repack/tgz/*.tgz` 以 `file:` 依赖临时装进 profile(见 `.tmp-verify.mjs`)。
 >
 > **改动 client bundle**:编辑 `src/factory.js` 后执行 `pnpm run build:client`
@@ -582,7 +601,8 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app
 - **换版本后重新出子包并发布**(全部由同一个脚本):
   1. `pnpm run repack:build -- --target win32-arm64,win32-x64 --pack` → 新的树包
      (`@jinsiyu/dshcs-vscode-server@<新版本>`)以及按新内部依赖重建的原生包
-     (脚本会把新的「纯 JS 直装集」写进插件 `dependencies`、更新两个聚合包版本);
+     (脚本会把新的「纯 JS 直装集」写进插件 `dependencies`,并把 16 个重打包包按真名写进
+     `dependencies` / `optionalDependencies`、重写 `lib/vendored.json`);
   2. `pnpm run publish:repacks` → 发布;然后 bump 插件版本 → `pnpm pack` → 发布插件。
 - `productPath`(`<quality>-<commit>`,客户端 WS 路径的组成)**从 `lib/vscode/product.json` 现算**,
   升级树后无需改代码 —— 但也意味着切版本后必须重启 dsh web(路由在激活期注册)。
@@ -612,7 +632,7 @@ host 探测顺序:`@jinsiyu/dshcs-vscode-server/vscode`(**0.2.0+ 正式布局**)
 
 0.2.7 起卡片**没有**「入口」「依赖安装」「环境检测」三行:入口在右侧栏「开始」页的 Code Server 入口框(或官方的文件点击),
 诊断信息不再进 UI —— `/api/code-server/status` 的 `env` 字段仍返回
-树版本 / `productPath` / server 入口、VS Code 内部依赖、**预编译原生包**(平台聚合包名 + 已解析模块数),需要时用脚本查或看 host 日志。
+树版本 / `productPath` / server 入口、VS Code 内部依赖、**预编译原生包**(重打包子包名 + 已解析模块数),需要时用脚本查或看 host 日志。
 
 > 卡片改动经 `scope.watch` 实时生效(host 端 status API 同步返回 `keepResident`、`claimExtensions` 与
 > `fullscreenOnOpen`,客户端立即生效);无需重启 dsh。**新增设置键后首次使用前需重启 dsh web**,

package/lib/index.js

@@ -35,7 +35,7 @@ import {
   vsRoot,
   vsServerEntry,
 } from './vendor.js';
-import { aliasNodePathDirs, ensureRuntimeLayout, resolveRuntime, runtimePackageName, verifyNatives } from './native.js';
+import { ensureRuntimeLayout, nativeRuntimeStatus } from './native.js';
 import { MOUNT_PATH, mountOnWebServer } from './serve-dsh.mjs';
 import { DEFAULT_CLAIM_EXTENSIONS, describeClaimPolicy, normalizeClaimExtensions } from './claim-types.js';
 import {
@@ -427,13 +427,12 @@ function envCheck() {
   const root = vsRoot();
   const entry = vsServerEntry();
   const inner = checkInnerDeps();
-  const runtime = resolveRuntime();
-  const natives = verifyNatives(runtime !== null ? runtime.modules : []);
+  const natives = nativeRuntimeStatus();
   const installed = root !== null ? readTreeVersion(root) : null;
   const vendored = vendoredVersion();
   return {
     ok: entry !== null && inner.missing.length === 0
-      && runtime !== null && natives.missing.length === 0,
+      && natives.resolved > 0 && natives.missing.length === 0,
     tree: root !== null ? root.replace(/\\/g, '/') : null,
     entry: entry !== null ? entry.replace(/\\/g, '/') : null,
     productPath: productPath(root),
@@ -442,16 +441,14 @@ function envCheck() {
     treeVersion: installed,
     vendored,
     upToDate: installed !== null && vendored !== null && installed === vendored,
-    // 本平台预编译原生产物(平台聚合包 + 它带回原始名字的原生模块)
-    nativeRuntime: runtime !== null
-      ? {
-        name: runtime.name,
-        source: 'package',
-        version: runtime.version,
-        packages: natives.resolved.length,
-        missing: natives.missing,
-      }
-      : { name: runtimePackageName(), source: null, version: null, packages: 0, missing: [] },
+    // 本平台预编译原生产物(重打包子包按真名装进依赖图,运行时按原名补 junction)
+    nativeRuntime: {
+      name: natives.name,
+      source: natives.source,
+      version: natives.version,
+      packages: natives.resolved,
+      missing: natives.missing,
+    },
     node: process.version,
     platform: process.platform,
     arch: process.arch,
@@ -1650,14 +1647,9 @@ export async function apply(ctx, config) {
     // ?v= 缓存击穿标记:按"插件版本 + VS Code 树"生成 —— 只在真升级时让渲染器丢掉旧 bundle,
     // 平时正常命中缓存(workbench.js 有 18MB,每次启动都重拉不划算)。
     env.DSHCS_HTML_TAG = `${pluginVersion()}-${productPath() ?? 'dev'}`.replace(/[^A-Za-z0-9._-]/g, '');
-    // pnpm 会把带 os/cpu 限定的原生包嵌套装在平台聚合包下(如 <profile>/node_modules/@<scope>/
-    // dsh-code-server-runtime-<平台>-<架构>/node_modules/@vscode/spdlog),那些目录不在 VS Code
-    // 树的向上查找链里 → 用 NODE_PATH 让子进程的 require 找得到(CJS;ESM 由 ensureAliasLinks 的 junction 负责)。
-    const nodePathDirs = aliasNodePathDirs();
-    if (nodePathDirs.length > 0) {
-      const existing = typeof env.NODE_PATH === 'string' && env.NODE_PATH !== '' ? env.NODE_PATH.split(path.delimiter) : [];
-      env.NODE_PATH = [...new Set([...nodePathDirs, ...existing])].join(path.delimiter);
-    }
+    // 0.3.45 起不再需要给子进程加 NODE_PATH:重打包原生包按**真名**挂在插件依赖上,而它们要的
+    // **原始名字**(node-pty / @vscode/sqlite3 …)由 ensureRuntimeLayout() 在树里补 junction ——
+    // 目录链同时满足 ESM import 与 CJS require,NODE_PATH 只对 CJS 生效且属兜底。
 
     let proc;
     try {
@@ -1781,7 +1773,7 @@ export async function apply(ctx, config) {
       parts.push(`内部依赖未装全(缺 ${missing.length} 个:${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ' …' : ''})`);
     }
     if (env.nativeRuntime !== null && env.nativeRuntime.source === null) {
-      parts.push(`平台预编译包未安装(${env.nativeRuntime.name})`);
+      parts.push(`预编译原生模块未安装(${env.nativeRuntime.name})`);
     } else if (Array.isArray(env.nativeRuntime?.missing) && env.nativeRuntime.missing.length > 0) {
       parts.push(`原生模块解析失败:${env.nativeRuntime.missing.slice(0, 5).join(', ')}`);
     }

package/lib/native.js

@@ -1,90 +1,93 @@
-// lib/native.js — 平台聚合包(预编译原生模块)的定位与校验。
+// lib/native.js — 预编译原生模块(重打包子包)的定位、校验与目录链还原。
 //
-// 模型(0.1.36 起):VS Code 内部依赖里那批「pnpm 拒绝安装」的原生包(node-pty /
-// @vscode/sqlite3 / kerberos / koffi / ssh2 / cpu-features / @parcel/watcher /
-// @vscode/windows-* …)在打包期由 scripts/vendor-repacks.mjs 重打包成
-// @<scope>/dshcs-<名字>[-<平台>-<架构>],再由平台聚合包
-//   @<scope>/dsh-code-server-runtime-<平台>-<架构>
-// 用 npm: 别名把它们装回**原始名字**。聚合包挂在插件 package.json 的
-// optionalDependencies 上(os/cpu 限定)→ pnpm 一条命令按架构自动选中。
+// 模型(0.3.45 起,取代 0.1.36 的「平台聚合包 + npm: 别名」):
+//   VS Code 内部依赖里那批「pnpm 拒绝安装」的原生包(node-pty / @vscode/sqlite3 / kerberos /
+//   koffi / ssh2 / cpu-features / @parcel/watcher / @vscode/windows-* …)在打包期由
+//   scripts/vendor-repacks.mjs 重打包成 @<scope>/dshcs-<名字>[-<平台>-<架构>],并**直接挂在插件
+//   依赖上**:
+//     · 平台无关的重打包包 → 插件 `dependencies`(真名,如 @<scope>/dshcs-node-pty);
+//     · 平台专属的重打包包 → 插件 `optionalDependencies`(真名 + 包自带 os/cpu,每平台一份,
+//       包管理器按架构自动选中,不匹配的在 lockfile 里是 optional ⇒ 缺失是允许的)。
 //
-// 本模块只做三件事:
-//   1. 找到本平台聚合包(以及它的依赖清单 = 期望可解析的原生模块名);
-//   2. 从 code-server 运行位置出发校验这些模块是否真的能 require 到;
-//   3. 必要时在 code-server 树里补齐别名 junction(ESM import 不认 NODE_PATH,只能靠目录链)。
+//   为什么不沿用聚合包:聚合包把 16 个包挂在**可选子树**里,靠 `npm:` 别名还原原始名字;
+//   而 dsh-desktop 的依赖图校验器在 `pnpm add` 之后立刻校验,偏偏 pnpm 的增量 hoisted 安装会
+//   漏链这类「可选子树里的别名包」(实测 16 个漏 9 个,报 requires missing @microsoft/mxc-sdk)。
+//   直接依赖(真名)在同一套设置下 100% 装上 ⇒ 改用直接依赖 + 运行时补 junction。
+//   实测证据与复现命令见 docs/desktop-first-install-root-cause.md。
+//
+//   「原名 → 真包」的表由打包期写进 lib/vendored.json(随包发布),本模块运行时只读它。
+//
+// 本模块只做四件事:
+//   1. 读 lib/vendored.json → 本平台期望可解析的「原名 → 真包」表;
+//   2. 从 code-server 运行位置出发校验这些原名是否真的能 require/import 到;
+//   3. 解析不到的在树里补 junction(ESM 不认 NODE_PATH,只认目录链);
+//   4. 给环境检测卡片一份状态汇总。
 import { createRequire } from 'node:module';
 import { existsSync, readFileSync, mkdirSync, symlinkSync, lstatSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { PACKAGE_ROOT, codeServerRoot, profileRootOf } from './vendor.js';
+import { PACKAGE_ROOT, codeServerRoot } from './vendor.js';
 
 const require_ = createRequire(import.meta.url);
+/** 打包期由 scripts/vendor-repacks.mjs 写出的重打包表。 */
+const VENDORED_FILE = join(PACKAGE_ROOT, 'lib', 'vendored.json');
 
 /** 平台目录名,如 win32-arm64。 */
 export function platformKey(platform = process.platform, arch = process.arch) {
   return `${platform}-${arch}`;
 }
 
-/** 本平台聚合包名(取插件 optionalDependencies 中匹配 <平台>-<架构> 的那个)。 */
-export function runtimePackageName(platform = process.platform, arch = process.arch) {
-  const key = platformKey(platform, arch);
+/** 读重打包表。
+ *  @returns {{scope:string, targets:string[], modules:{alias:string,package:string,version?:string,platform?:boolean}[]}} */
+export function readVendoredTable() {
   try {
-    const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
-    const declared = { ...(pkg.optionalDependencies ?? {}), ...(pkg.dependencies ?? {}) };
-    const hit = Object.keys(declared).find((name) => /^@[^/]+\/dsh-code-server-runtime-/.test(name) && name.endsWith(`-${key}`));
-    if (hit !== undefined) return hit;
-  } catch { /* 回退默认 scope */ }
-  return `@jinsiyu/dsh-code-server-runtime-${key}`;
+    const doc = JSON.parse(readFileSync(VENDORED_FILE, 'utf8'));
+    const modules = Array.isArray(doc?.modules)
+      ? doc.modules.filter((m) => m !== null && typeof m === 'object'
+        && typeof m.alias === 'string' && m.alias !== ''
+        && typeof m.package === 'string' && m.package !== '')
+      : [];
+    return {
+      scope: typeof doc?.scope === 'string' && doc.scope !== '' ? doc.scope : '@jinsiyu',
+      targets: Array.isArray(doc?.targets) ? doc.targets.filter((t) => typeof t === 'string') : [],
+      modules,
+    };
+  } catch {
+    return { scope: '@jinsiyu', targets: [], modules: [] };
+  }
 }
 
-/** 定位已安装的平台聚合包。
- *  @returns {{name:string, version:string|null, root:string, modules:string[]}|null} */
-export function resolveRuntime() {
-  const name = runtimePackageName();
-  const candidates = [];
-  try {
-    candidates.push(dirname(require_.resolve(`${name}/package.json`)));
-  } catch { /* 未安装 */ }
-  const profileRoot = profileRootOf();
-  for (const root of [join(PACKAGE_ROOT, 'node_modules'), profileRoot !== null ? join(profileRoot, 'node_modules') : null, PACKAGE_ROOT]) {
-    if (root !== null) candidates.push(join(root, name));
-  }
-  for (const root of candidates) {
-    const manifestPath = join(root, 'package.json');
-    if (!existsSync(manifestPath)) continue;
-    try {
-      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-      const modules = Object.keys({ ...(manifest.dependencies ?? {}), ...(manifest.optionalDependencies ?? {}) });
-      return { name, version: typeof manifest.version === 'string' ? manifest.version : null, root, modules };
-    } catch { /* 尝试下一个 */ }
-  }
-  return null;
+/** 某个条目在指定平台的**真包名**(平台专属的按 `-<平台>-<架构>` 拼后缀)。 */
+export function vendoredPackageName(entry, platform = process.platform, arch = process.arch) {
+  return entry.platform === true ? `${entry.package}-${platformKey(platform, arch)}` : entry.package;
+}
+
+/** 本平台期望装在依赖图里的重打包子包(原名 + 真名),按原名排序。
+ *  @returns {{alias:string, packageName:string, version:string|null, platform:boolean}[]} */
+export function vendoredEntries(platform = process.platform, arch = process.arch) {
+  return readVendoredTable().modules
+    .map((m) => ({
+      alias: m.alias,
+      packageName: vendoredPackageName(m, platform, arch),
+      version: typeof m.version === 'string' ? m.version : null,
+      platform: m.platform === true,
+    }))
+    .sort((a, b) => a.alias.localeCompare(b.alias));
 }
 
-/** 解析原生/别名模块时的锚点目录:
+/** 解析原生模块时的锚点目录:
  *   ① code-server 运行根(树自带 node_modules);
- *   ② 平台聚合包目录 —— pnpm 会把带 os/cpu 限定的包**嵌套装在聚合包下**
- *      (`<profile>/node_modules/@<scope>/dsh-code-server-runtime-<平台>-<架构>/node_modules/<别名>`),
- *      既不在 profile 根也不在 code-server 树里,所以要单独作为锚点(运行时用 NODE_PATH 覆盖同一批目录)。
- *  @returns {string[]} */
+ *   ② 插件包根 —— 重打包子包挂在插件依赖上(profile 根或插件自己的 node_modules),
+ *      从插件清单出发的解析链才看得到它们。 */
 export function nativeSearchRoots() {
   const roots = [];
   const cs = codeServerRoot();
   if (cs !== null) roots.push(cs);
-  const runtime = resolveRuntime();
-  if (runtime !== null) roots.push(runtime.root);
+  roots.push(PACKAGE_ROOT);
   return roots;
 }
 
-/** 运行时需要加进 NODE_PATH 的目录(平台聚合包下嵌套的别名包)。
- *  @returns {string[]} */
-export function aliasNodePathDirs() {
-  const runtime = resolveRuntime();
-  if (runtime === null) return [];
-  const dir = join(runtime.root, 'node_modules');
-  return existsSync(dir) ? [dir] : [];
-}
-
 /** 解析某个模块的包目录(依次尝试各锚点;先 `<name>/package.json`,再模块入口)。
+ *  @param {string} name 真包名(重打包子包名),如 `@jinsiyu/dshcs-node-pty`
  *  @returns {string|null} */
 export function resolveNativeDir(name) {
   for (const root of nativeSearchRoots()) {
@@ -101,22 +104,23 @@ export function resolveNativeDir(name) {
   return null;
 }
 
-/** 从 code-server 运行位置(与聚合包目录)校验原生模块能否解析。
- *  先试 `<name>/package.json`(ESM-only 包没有 require 入口,如 @microsoft/mxc-sdk),
- *  再退回 `<name>` 本身。
- *  @param {string[]} modules 期望的原生模块名(通常来自聚合包依赖清单)
+/** 从 code-server 运行位置校验原生模块能否解析(名字用「原名」,即 VS Code 实际 import 的名字)。
+ *  先试 `<name>/package.json`(ESM-only 包没有 require 入口,如 @microsoft/mxc-sdk),再退回 `<name>` 本身。
+ *  @param {string[]} modules 期望的原生模块名(别名)
  *  @returns {{resolved:string[], missing:string[]}} */
 export function verifyNatives(modules) {
+  const csRoot = codeServerRoot();
   const resolved = [];
   const missing = [];
   for (const name of modules) {
-    if (resolveNativeDir(name) !== null) resolved.push(name);
+    const ok = csRoot !== null && resolvesFromRoot(csRoot, name);
+    if (ok) resolved.push(name);
     else missing.push(name);
   }
   return { resolved, missing };
 }
 
-/** 某个模块能否**只靠 code-server 运行根**(含其祖先 node_modules)解析。 */
+/** 某个名字能否**只靠 code-server 运行根**(含其祖先 node_modules)解析。 */
 function resolvesFromRoot(root, name) {
   try {
     const from = createRequire(join(root, 'package.json'));
@@ -130,34 +134,33 @@ function resolvesFromRoot(root, name) {
   return false;
 }
 
-/** 确保聚合包带回的别名模块能被 **code-server 树**解析。
+/** 确保重打包子包能被 **code-server 树**按**原始名字**解析。
  *
- *  为什么必须做:pnpm 会把带 `os`/`cpu` 限定的包**嵌套装在聚合包自己的 node_modules 下**
- *  (如 `<profile>/node_modules/@<scope>/dsh-code-server-runtime-win32-arm64/node_modules/@vscode/windows-registry`),
- *  而 VS Code 的 `lib/vscode/out/server-main.js` 用 **ESM `import`** 加载这些包 —— ESM 不认
- *  `NODE_PATH`(那是 CJS 的兜底),只认目录链。所以这里在 `<codeServerRoot>/node_modules` 下
- *  为每个「从树里解析不到」的别名补一个 junction,指向聚合包内的真实目录。
+ *  为什么必须做:重打包子包的真名是 `@<scope>/dshcs-<名字>`,而 VS Code 的
+ *  `lib/vscode/out/server-main.js` 用 **ESM `import`** 加载 `node-pty` / `@vscode/sqlite3` 这类原名 ——
+ *  ESM 不认 `NODE_PATH`(那是 CJS 的兜底),只认目录链。所以这里在 `<树根>/node_modules` 下为每个
+ *  「从树里解析不到」的原名补一个 junction,指向插件依赖图里的真实目录。
  *  幂等、可重复调用;插件重装后由下次激活/启动自愈。
  *  @returns {{created:string[], failed:string[]}} */
 export function ensureAliasLinks() {
-  const runtime = resolveRuntime();
   const csRoot = codeServerRoot();
-  if (runtime === null || csRoot === null) return { created: [], failed: [] };
+  if (csRoot === null) return { created: [], failed: [] };
   const linkRoot = join(csRoot, 'node_modules');
   const created = [];
   const failed = [];
-  for (const alias of runtime.modules) {
-    if (resolvesFromRoot(csRoot, alias)) continue; // 目录链已能看到(profile 根或树内),无需补
-    const target = resolveNativeDir(alias);
-    if (target === null) continue; // 该平台包没装上 → 交给 envCheck 报缺
-    const link = join(linkRoot, alias);
+  for (const entry of vendoredEntries()) {
+    if (resolvesFromRoot(csRoot, entry.alias)) continue; // 目录链已能看到(profile 根或树内),无需补
+    const target = resolveNativeDir(entry.packageName);
+    if (target === null) continue; // 该平台子包没装上 → 交给 envCheck 报缺
+    const link = join(linkRoot, entry.alias);
     try {
-      if (existsSync(link)) continue;
+      if (existsSync(join(link, 'package.json'))) continue; // 链接有效(真实目录或有效 junction)
+      if (pathEntryExists(link)) rmSync(link, { recursive: true, force: true }); // 断链(树被重装过)→ 清掉重建
       mkdirSync(dirname(link), { recursive: true });
       symlinkSync(target, link, process.platform === 'win32' ? 'junction' : 'dir');
-      created.push(alias);
+      created.push(entry.alias);
     } catch (error) {
-      failed.push(`${alias}: ${error && error.message ? error.message : String(error)}`);
+      failed.push(`${entry.alias}: ${error && error.message ? error.message : String(error)}`);
     }
   }
   return { created, failed };
@@ -251,7 +254,7 @@ export function ensureInnerModuleLinks() {
   return { created, failed };
 }
 
-/** 一次性补齐两类链接:VS Code 内部依赖目录 + 聚合包别名。 */
+/** 一次性补齐两类链接:VS Code 内部依赖目录 + 重打包子包的原始名字。 */
 export function ensureRuntimeLayout() {
   const inner = ensureInnerModuleLinks();
   const aliases = ensureAliasLinks();
@@ -260,3 +263,28 @@ export function ensureRuntimeLayout() {
     failed: [...inner.failed, ...aliases.failed],
   };
 }
+
+/** 本平台预编译原生包的状态汇总(环境检测卡片用)。
+ *  @returns {{name:string, source:'package'|null, version:string|null, modules:number, packages:number,
+ *             resolved:number, missing:string[], missingPackages:string[]}} */
+export function nativeRuntimeStatus(platform = process.platform, arch = process.arch) {
+  const table = readVendoredTable();
+  const entries = vendoredEntries(platform, arch);
+  const installed = [];
+  const missingPackages = [];
+  for (const entry of entries) {
+    if (resolveNativeDir(entry.packageName) !== null) installed.push(entry);
+    else missingPackages.push(entry);
+  }
+  const { resolved, missing } = verifyNatives(entries.map((entry) => entry.alias));
+  return {
+    name: `${table.scope}/dshcs-*-${platformKey(platform, arch)}`,
+    source: installed.length > 0 ? 'package' : null,
+    version: null,
+    modules: entries.length,
+    packages: installed.length,
+    resolved: resolved.length,
+    missing,
+    missingPackages: missingPackages.map((entry) => entry.packageName),
+  };
+}

package/lib/vendor.js

@@ -10,7 +10,9 @@
 //   - VS Code 内部依赖(约 1GB)与需编译的原生模块仍由包管理器安装:
 //     纯 JS 部分写在插件 package.json 的 dependencies;
 //     pnpm 拒绝安装的原生包由 scripts/vendor-repacks.mjs 重打包成 @<scope>/dshcs-*,
-//     再由平台聚合包 @<scope>/dsh-code-server-runtime-<platform>-<arch> 用 npm: 别名装回原名字;
+//     并**直接挂在插件依赖上**(平台无关的 → dependencies;平台专属的 → optionalDependencies,
+//     包自带 os/cpu 按架构自动选)。原始名字由 lib/native.js 按 lib/vendored.json 补 junction ——
+//     0.3.45 起不再有平台聚合包,原因见 docs/desktop-first-install-root-cause.md;
 //   - 插件包内 `vendor/vscode/` 只作为**开发期/兼容**回退(发布包不含 vendor)。
 import { createRequire } from 'node:module';
 import { existsSync, readFileSync } from 'node:fs';

package/lib/vendored.json

@@ -0,0 +1,99 @@
+{
+  "schemaVersion": 1,
+  "generatedBy": "scripts/vendor-repacks.mjs",
+  "scope": "@jinsiyu",
+  "targets": [
+    "win32-arm64",
+    "win32-x64"
+  ],
+  "modules": [
+    {
+      "alias": "@microsoft/mxc-sdk",
+      "package": "@jinsiyu/dshcs-microsoft-mxc-sdk",
+      "version": "0.8.0"
+    },
+    {
+      "alias": "@parcel/watcher",
+      "package": "@jinsiyu/dshcs-parcel-watcher",
+      "version": "2.5.6"
+    },
+    {
+      "alias": "@vscode/deviceid",
+      "package": "@jinsiyu/dshcs-vscode-deviceid",
+      "version": "0.1.5",
+      "platform": true
+    },
+    {
+      "alias": "@vscode/fs-copyfile",
+      "package": "@jinsiyu/dshcs-vscode-fs-copyfile",
+      "version": "2.0.0"
+    },
+    {
+      "alias": "@vscode/native-watchdog",
+      "package": "@jinsiyu/dshcs-vscode-native-watchdog",
+      "version": "1.4.6",
+      "platform": true
+    },
+    {
+      "alias": "@vscode/proxy-agent",
+      "package": "@jinsiyu/dshcs-vscode-proxy-agent",
+      "version": "0.44.0"
+    },
+    {
+      "alias": "@vscode/spdlog",
+      "package": "@jinsiyu/dshcs-vscode-spdlog",
+      "version": "0.15.8",
+      "platform": true
+    },
+    {
+      "alias": "@vscode/sqlite3",
+      "package": "@jinsiyu/dshcs-vscode-sqlite3",
+      "version": "5.1.12-vscode",
+      "platform": true
+    },
+    {
+      "alias": "@vscode/windows-ca-certs",
+      "package": "@jinsiyu/dshcs-vscode-windows-ca-certs",
+      "version": "0.3.4",
+      "platform": true
+    },
+    {
+      "alias": "@vscode/windows-process-tree",
+      "package": "@jinsiyu/dshcs-vscode-windows-process-tree",
+      "version": "0.8.0",
+      "platform": true
+    },
+    {
+      "alias": "@vscode/windows-registry",
+      "package": "@jinsiyu/dshcs-vscode-windows-registry",
+      "version": "1.2.0",
+      "platform": true
+    },
+    {
+      "alias": "cpu-features",
+      "package": "@jinsiyu/dshcs-cpu-features",
+      "version": "0.0.10"
+    },
+    {
+      "alias": "kerberos",
+      "package": "@jinsiyu/dshcs-kerberos",
+      "version": "2.1.1-dshcs.1",
+      "platform": true
+    },
+    {
+      "alias": "koffi",
+      "package": "@jinsiyu/dshcs-koffi",
+      "version": "3.1.2"
+    },
+    {
+      "alias": "node-pty",
+      "package": "@jinsiyu/dshcs-node-pty",
+      "version": "1.2.0-beta.15"
+    },
+    {
+      "alias": "ssh2",
+      "package": "@jinsiyu/dshcs-ssh2",
+      "version": "1.17.0"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-code-server-app",
-  "version": "0.3.44",
+  "version": "0.3.46",
   "description": "VS Code (from a code-server release) inside DSH: a right-sidebar tab driven by the plugin's own launcher over the in-process VS Code server (lib/launcher.mjs). Since 0.3.0 the bundle also ships an editor bridge (assets/extensions/dshcs-editor-bridge): a read-only channel between the in-tree VS Code extension host and DSH, giving the agent what only the editor knows (unsaved buffers, language-server diagnostics, the active selection) and letting editor gestures drive the session. Since 0.3.22 the ask panel renders that session's new content with DSH's own Markdown renderer (pinned to the deployed DSH UI version); since 0.3.23 it is a full-width dialog with collapsible thinking rows and can answer approval requests in place — the bridge's only non-read-only route (POST /approve, constrained to pending in-process requests and the outcomes allowed-once/rejected; panel-first for 5 minutes, handed back to the official card the moment the panel closes). The tab claims DSH file addresses (dsh-resource://file/**) by file type (setting claimExtensions), so the product's own produced-file chips, delivered-file previews and inline prose mentions open in the workbench. The IDE is a resident surface moved with Element.moveBefore instead of being remounted, so switching sidebar tabs no longer reloads it. Opening the tab switches the right sidebar to fullscreen by default (setting fullscreenOnOpen). Following a workspace switch is lightweight: the workbench re-navigates with the new ?folder= and the IDE process is not restarted (since 0.2.12). Requires a DSH with the right-sidebar services (sidebarRightTabs/sidebarRight, >= 0.1.5-alpha.1); older DSH versions get a single upgrade notice on the settings page and no other UI. Two serving modes: loopback port (default) or same-origin mount on DSH's own webServer (/code-server, protected by ctx.connection.requestRejection). No code-server Node layer, no argon2, no C++ toolchain.",
   "homepage": "https://github.com/jinsiyu/dsh-code-server-app",
   "repository": {
@@ -50,6 +50,7 @@
     "lib/serve-dsh.mjs",
     "lib/vendor.js",
     "lib/native.js",
+    "lib/vendored.json",
     "assets/favicon.ico",
     "assets/favicon.svg",
     "assets/extensions/dshcs-open-file",
@@ -63,6 +64,28 @@
     "README.md",
     "README.en.md"
   ],
+  "scripts": {
+    "vendor:vscode": "node scripts/vendor-vscode-server.mjs",
+    "vendor:latest": "node scripts/vendor-vscode-server.mjs --force",
+    "vendor:check": "node scripts/vendor-vscode-server.mjs --check",
+    "vendor:code-server": "node scripts/vendor-code-server.mjs",
+    "repack:build": "node scripts/vendor-repacks.mjs",
+    "publish:repacks": "node scripts/publish-repacks.mjs",
+    "publish:plugin": "node scripts/publish-plugin.mjs",
+    "promote": "node scripts/promote.mjs",
+    "prepack": "node scripts/vendor-vscode-server.mjs && node scripts/build-webview.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "build:webview": "node scripts/build-webview.mjs",
+    "test:apply": "node scripts/test-plugin-apply.mjs",
+    "test:launcher-routes": "node scripts/test-launcher-routes.mjs",
+    "test:fullscreen": "node scripts/test-sidebar-fullscreen.mjs",
+    "test:claim-types": "node scripts/test-claim-types.mjs",
+    "test:workspace-switch": "node scripts/test-workspace-switch.mjs",
+    "test:bridge-routes": "node scripts/test-bridge-routes.mjs",
+    "test:bridge-extension": "node scripts/test-bridge-extension.mjs",
+    "test:webview": "node scripts/test-webview-bundle.mjs",
+    "test:vendored": "node scripts/test-vendored-table.mjs"
+  },
   "devDependencies": {
     "@deepseek-ai/dsh-client-ui-primitives": "0.1.5-rc.2",
     "@deepseek-ai/dsh-client-ui-theme": "0.1.5-rc.2",
@@ -89,6 +112,14 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@jinsiyu/dshcs-cpu-features": "0.0.10",
+    "@jinsiyu/dshcs-koffi": "3.1.2",
+    "@jinsiyu/dshcs-microsoft-mxc-sdk": "0.8.0",
+    "@jinsiyu/dshcs-node-pty": "1.2.0-beta.15",
+    "@jinsiyu/dshcs-parcel-watcher": "2.5.6",
+    "@jinsiyu/dshcs-ssh2": "1.17.0",
+    "@jinsiyu/dshcs-vscode-fs-copyfile": "2.0.0",
+    "@jinsiyu/dshcs-vscode-proxy-agent": "0.44.0",
     "@jinsiyu/dshcs-vscode-server": "4.137.0",
     "@microsoft/1ds-core-js": "3.2.13",
     "@microsoft/1ds-post-js": "3.2.13",
@@ -107,17 +138,21 @@
     "@xterm/addon-webgl": "0.20.0-beta.299",
     "@xterm/headless": "6.1.0-beta.302",
     "@xterm/xterm": "6.1.0-beta.303",
+    "bindings": "1.5.0",
     "cookie": "0.7.2",
     "detect-libc": "2.1.2",
+    "fs-extra": "11.4.0",
     "http-proxy-agent": "7.0.0",
     "https-proxy-agent": "7.0.2",
     "jschardet": "3.1.4",
     "minimist": "1.2.8",
+    "mkdirp": "1.0.4",
     "node-addon-api": "6.1.0",
     "tar": "7.5.22",
     "tas-client": "0.4.3",
     "tslib": "2.8.1",
     "typescript": "6.0.3",
+    "uuid": "14.0.2",
     "vscode-oniguruma": "1.7.0",
     "vscode-regexpp": "3.1.0",
     "vscode-textmate": "9.3.2",
@@ -127,27 +162,21 @@
     "zod": "4.4.3"
   },
   "optionalDependencies": {
-    "@jinsiyu/dsh-code-server-runtime-win32-arm64": "^0.3.10",
-    "@jinsiyu/dsh-code-server-runtime-win32-x64": "^0.3.10"
-  },
-  "scripts": {
-    "vendor:vscode": "node scripts/vendor-vscode-server.mjs",
-    "vendor:latest": "node scripts/vendor-vscode-server.mjs --force",
-    "vendor:check": "node scripts/vendor-vscode-server.mjs --check",
-    "vendor:code-server": "node scripts/vendor-code-server.mjs",
-    "repack:build": "node scripts/vendor-repacks.mjs",
-    "publish:repacks": "node scripts/publish-repacks.mjs",
-    "publish:plugin": "node scripts/publish-plugin.mjs",
-    "promote": "node scripts/promote.mjs",
-    "build:client": "node scripts/build-client.mjs",
-    "build:webview": "node scripts/build-webview.mjs",
-    "test:apply": "node scripts/test-plugin-apply.mjs",
-    "test:launcher-routes": "node scripts/test-launcher-routes.mjs",
-    "test:fullscreen": "node scripts/test-sidebar-fullscreen.mjs",
-    "test:claim-types": "node scripts/test-claim-types.mjs",
-    "test:workspace-switch": "node scripts/test-workspace-switch.mjs",
-    "test:bridge-routes": "node scripts/test-bridge-routes.mjs",
-    "test:bridge-extension": "node scripts/test-bridge-extension.mjs",
-    "test:webview": "node scripts/test-webview-bundle.mjs"
+    "@jinsiyu/dshcs-kerberos-win32-arm64": "2.1.1-dshcs.1",
+    "@jinsiyu/dshcs-kerberos-win32-x64": "2.1.1-dshcs.1",
+    "@jinsiyu/dshcs-vscode-deviceid-win32-arm64": "0.1.5",
+    "@jinsiyu/dshcs-vscode-deviceid-win32-x64": "0.1.5",
+    "@jinsiyu/dshcs-vscode-native-watchdog-win32-arm64": "1.4.6",
+    "@jinsiyu/dshcs-vscode-native-watchdog-win32-x64": "1.4.6",
+    "@jinsiyu/dshcs-vscode-spdlog-win32-arm64": "0.15.8",
+    "@jinsiyu/dshcs-vscode-spdlog-win32-x64": "0.15.8",
+    "@jinsiyu/dshcs-vscode-sqlite3-win32-arm64": "5.1.12-vscode",
+    "@jinsiyu/dshcs-vscode-sqlite3-win32-x64": "5.1.12-vscode",
+    "@jinsiyu/dshcs-vscode-windows-ca-certs-win32-arm64": "0.3.4",
+    "@jinsiyu/dshcs-vscode-windows-ca-certs-win32-x64": "0.3.4",
+    "@jinsiyu/dshcs-vscode-windows-process-tree-win32-arm64": "0.8.0",
+    "@jinsiyu/dshcs-vscode-windows-process-tree-win32-x64": "0.8.0",
+    "@jinsiyu/dshcs-vscode-windows-registry-win32-arm64": "1.2.0",
+    "@jinsiyu/dshcs-vscode-windows-registry-win32-x64": "1.2.0"
   }
-}
+}

package/scripts/vendor-repacks.mjs

@@ -9,8 +9,10 @@
 //      + src/browser),不含 code-server 的 out/node 与它的 136 个依赖(那层由 lib/launcher.mjs 取代);
 //   ② @<scope>/dshcs-<名字>[-<platform>-<arch>]@<版本>  需要构建的原生包(node-pty / @vscode/sqlite3 /
 //      kerberos / koffi / ssh2 / …),依赖链上命中它们的包也一并重打包(含 optionalDependencies);
-//   ③ @<scope>/dsh-code-server-runtime-<platform>-<arch>@<插件版本>  平台聚合包:用 npm: 别名把 ② 装回
-//      原始名字,VS Code 的 require/import 无需改动;插件按 os/cpu 声明 ①(常规)+ ③(可选)依赖。
+//   ③ 插件依赖表 + lib/vendored.json —— **0.3.45 起不再有平台聚合包**:平台无关的重打包包写进插件
+//      `dependencies`(真名),平台专属的写进 `optionalDependencies`(真名 + 包自带 os/cpu,每目标一份);
+//      原始名字(node-pty / @vscode/sqlite3 …)由 lib/native.js 在运行时按 lib/vendored.json 补 junction。
+//      为什么弃用「平台聚合包 + npm: 别名」:见 docs/desktop-first-install-root-cause.md。
 //
 // 用法:node scripts/vendor-repacks.mjs [--from <已完整安装的 code-server 树>]
 //        [--target win32-arm64,win32-x64] [--scope @jinsiyu] [--pack]
@@ -395,63 +397,15 @@ function hostMapFromProfile() {
   return best;
 }
 
-/** --reuse:从现有 repack/build + 聚合包清单还原「重打包集」,不重新分析源树。
- *  @returns {{repack: Map<string,{pkg:{version:string},platformSpecific:boolean}>, declare:{name:string,version:string}[], reusedItems:{dir:string,file:string}[]}} */
-function reuseExisting(targets, hostKey) {
+/** --reuse:从现有 repack/build + 重打包表还原「重打包集」,不重新分析源树。
+ *  @returns {{modules:{alias:string,package:string,version:string,platform:boolean}[],
+ *             declare:{name:string,version:string}[], reusedItems:{dir:string,file:string}[]}} */
+function reuseExisting(targets) {
   const buildRoot = join(OUT, 'build');
   if (!existsSync(buildRoot)) throw new Error('--reuse 需要 repack/build 已存在(先跑一次完整流程)');
-  const byTarget = new Map();
-  for (const target of targets) {
-    const agg = readJson(join(OUT, 'aggregator', target, 'package.json'));
-    if (agg === null) continue;
-    const map = new Map();
-    for (const [orig, spec] of Object.entries(agg.dependencies ?? {})) {
-      // 旧的聚合包清单里可能仍带 argon2(已随 code-server 服务层移除)
-      if (orig === 'argon2') continue;
-      const hit = /^npm:(.+)@([^@]+)$/.exec(spec);
-      if (hit === null) throw new Error(`无法解析聚合包依赖 ${orig}: ${spec}`);
-      map.set(orig, { pkgName: hit[1], version: hit[2] });
-    }
-    byTarget.set(target, map);
-  }
-  if (byTarget.size === 0) {
-    const base = hostMapFromProfile();
-    if (base === null) {
-      throw new Error('--reuse 需要 repack/aggregator/*/package.json 或一个已安装的 profile 用于还原映射');
-    }
-    byTarget.set(hostKey, base);
-  } else {
-    // 与已安装 profile 的别名取并集:聚合包清单可能在上一次失败的重建里丢过条目
-    const hostTarget = byTarget.has(hostKey) ? hostKey : targets[0];
-    const base = hostMapFromProfile();
-    if (base !== null) {
-      const merged = new Map(byTarget.get(hostTarget));
-      let added = 0;
-      for (const [orig, info] of base) {
-        if (!merged.has(orig)) { merged.set(orig, info); added += 1; }
-      }
-      if (added > 0) console.log(`[repack] --reuse:聚合包清单缺 ${added} 个条目 → 已用 profile 别名补齐`);
-      byTarget.set(hostTarget, merged);
-    }
-  }
-  const known = byTarget.get(hostKey) ?? byTarget.get(targets[0]);
-  // 其余目标:按后缀替换推导(平台专属包名只在结尾的 -<platform>-<arch> 上不同)
-  const knownTarget = byTarget.has(hostKey) ? hostKey : targets[0];
-  for (const target of targets) {
-    if (byTarget.has(target)) continue;
-    const map = new Map();
-    for (const [orig, info] of known) {
-      const pkgName = info.pkgName.endsWith(`-${knownTarget}`)
-        ? `${info.pkgName.slice(0, -knownTarget.length)}${target}`
-        : info.pkgName;
-      map.set(orig, { pkgName, version: info.version });
-    }
-    byTarget.set(target, map);
-  }
-  const hostSet = byTarget.get(knownTarget);
-  const repack = new Map();
-  for (const [orig, info] of hostSet) {
-    repack.set(orig, { pkg: { version: info.version }, platformSpecific: info.pkgName.endsWith(`-${knownTarget}`) });
+  const modules = readModules(targets);
+  if (modules.length === 0) {
+    throw new Error('--reuse 需要 lib/vendored.json、repack/aggregator/*/package.json 或一个已安装的 profile 用于还原重打包表');
   }
   // 已有原生包目录 → plan 项;顺带清掉将被重建的树目录(旧 code-server / argon2 目录一并清理)
   const reusedItems = [];
@@ -464,50 +418,168 @@ function reuseExisting(targets, hostKey) {
     if (m === null) continue;
     reusedItems.push({ dir: join(buildRoot, ent), file: tgzName(m.name, m.version) });
   }
-  // 纯 JS 直装集:插件现有 dependencies 里非 @jinsiyu 的项
+  // 纯 JS 直装集:插件现有 dependencies 里既不是树包、也不是重打包子包的项
+  const vendoredNames = new Set(modules.map((m) => m.package));
   const pluginPkg = readJson(join(pkgRoot, 'package.json'));
   const declare = Object.entries(pluginPkg.dependencies ?? {})
-    .filter(([name]) => !/^@jinsiyu\//.test(name))
+    .filter(([name]) => !vendoredNames.has(name) && !/\/(?:dshcs-vscode-server|dshcs-code-server)$/.test(name))
     .map(([name, version]) => ({ name, version }));
   rmSync(join(OUT, 'aggregator'), { recursive: true, force: true });
-  console.log(`[repack] --reuse:复用 ${reusedItems.length} 个已打包目录、${repack.size} 个重打包条目、${declare.length} 个纯 JS 直装依赖`);
-  return { repack, declare, reusedItems };
+  console.log(`[repack] --reuse:复用 ${reusedItems.length} 个已打包目录、${modules.length} 个重打包条目、${declare.length} 个纯 JS 直装依赖`);
+  return { modules, declare, reusedItems };
+}
+
+/** 重打包子包的平台后缀(平台专属包才有),如 `@<scope>/dshcs-kerberos-win32-arm64`。 */
+const PLATFORM_SUFFIX = /-(win32|darwin|linux)-(arm64|x64)$/;
+
+/** 由「原名 + 真包名 + 版本」得到重打包条目(平台专属的存**基名**,运行时按目标拼后缀)。 */
+function moduleEntry(alias, pkgName, version) {
+  const hit = PLATFORM_SUFFIX.exec(pkgName);
+  return hit === null
+    ? { alias, package: pkgName, version, platform: false }
+    : { alias, package: pkgName.slice(0, -hit[0].length), version, platform: true };
+}
+
+/** 读「原名 → 重打包子包」表:优先 lib/vendored.json(0.3.45 起),
+ *  否则从平台聚合包清单(0.3.44 及更早)或已安装 profile 迁移,再否则返回空表。 */
+function readModules(targets) {
+  const vendoredFile = join(pkgRoot, 'lib', 'vendored.json');
+  const doc = readJson(vendoredFile);
+  if (doc !== null && Array.isArray(doc.modules) && doc.modules.length > 0) {
+    const modules = doc.modules
+      .filter((m) => m !== null && typeof m === 'object' && typeof m.alias === 'string' && typeof m.package === 'string')
+      .map((m) => ({
+        alias: m.alias,
+        package: m.package,
+        version: typeof m.version === 'string' ? m.version : null,
+        platform: m.platform === true,
+      }))
+      .sort((a, b) => a.alias.localeCompare(b.alias));
+    if (modules.length > 0) {
+      console.log(`[repack] 读 lib/vendored.json:${modules.length} 个重打包条目`);
+      return modules;
+    }
+  }
+  // 迁移:旧的聚合包清单(每个目标一份,dependencies 里是 npm: 别名)
+  let source = null;
+  for (const target of targets) {
+    const agg = readJson(join(OUT, 'aggregator', target, 'package.json'));
+    if (agg === null) continue;
+    const map = new Map();
+    for (const [orig, spec] of Object.entries(agg.dependencies ?? {})) {
+      // 旧的聚合包清单里可能仍带 argon2(已随 code-server 服务层移除)
+      if (orig === 'argon2') continue;
+      const hit = /^npm:(.+)@([^@]+)$/.exec(spec);
+      if (hit === null) throw new Error(`无法解析聚合包依赖 ${orig}: ${spec}`);
+      map.set(orig, { pkgName: hit[1], version: hit[2] });
+    }
+    if (map.size > 0) { source = { label: `repack/aggregator/${target}`, map }; break; }
+  }
+  // 与已安装 profile 的别名取并集:聚合包清单可能在上一次失败的重建里丢过条目
+  const base = hostMapFromProfile();
+  if (source === null && base === null) return [];
+  const merged = new Map(source !== null ? source.map : []);
+  if (base !== null) {
+    let added = 0;
+    for (const [orig, info] of base) {
+      if (!merged.has(orig)) { merged.set(orig, info); added += 1; }
+    }
+    if (added > 0) console.log(`[repack] 重打包表缺 ${added} 个条目 → 已用 profile 别名补齐`);
+  }
+  const modules = [...merged]
+    .map(([alias, info]) => moduleEntry(alias, info.pkgName, info.version))
+    .sort((a, b) => a.alias.localeCompare(b.alias));
+  console.log(`[repack] 迁移 ${modules.length} 个重打包条目(${source !== null ? source.label : 'profile 别名'})→ 将写入 lib/vendored.json`);
+  return modules;
+}
+
+/** 平台专属重打包包(写在插件 `optionalDependencies`)自带的**注册表依赖** —— 必须同时提成插件
+ *  自己的直接依赖。原因(0.3.46 实测,复现与证据见 docs/desktop-first-install-root-cause.md 第 5 节):
+ *  pnpm 的增量 hoisted 安装会把「optional 子树里 depth≥2」的依赖整支丢进 `node_modules/.modules.yaml`
+ *  的 `skipped`(`bindings` / `fs-extra` / `uuid` / `mkdirp` 全在内),而 dsh-desktop 在 `pnpm add`
+ *  之后**立刻**用 `require.resolve.paths()` 校验依赖图 ⇒ 首次安装报
+ *  `@jinsiyu/dshcs-kerberos-win32-arm64 requires missing bindings@^1.5.0`;
+ *  更糟的是 `pnpm install --frozen-lockfile` 会认为 «Already up to date»(锁文件本身也缺这些条目),
+ *  于是 profile 永远修不好,只能靠删 node_modules 重装。提到插件根依赖后它们落在 profile 根
+ *  `node_modules`,校验器与运行时都能解析到。这些都是纯 JS、无 ABI 约束,版本在此钉死;
+ *  将来平台专属包新增注册表依赖时 verifyOptionalSubtreeDeps() 会在构建期直接报错。 */
+const OPTIONAL_SUBTREE_DEPS = {
+  bindings: '1.5.0',
+  mkdirp: '1.0.4',
+  'fs-extra': '11.4.0',
+  uuid: '14.0.2',
+};
+
+/** 构建期闸门:平台专属重打包清单里的每个非别名依赖都必须在 OPTIONAL_SUBTREE_DEPS 里。
+ *  @param dirs - 已生成的平台专属重打包目录。 */
+function verifyOptionalSubtreeDeps(dirs) {
+  const seen = new Set();
+  for (const dir of dirs) {
+    const m = readJson(join(dir, 'package.json'));
+    if (m === null) continue;
+    for (const fld of ['dependencies', 'optionalDependencies']) {
+      for (const [name, spec] of Object.entries(m[fld] ?? {})) {
+        if (String(spec).startsWith('npm:')) continue; // 已重打包(真名子包),不走注册表
+        seen.add(name);
+        if (!Object.hasOwn(OPTIONAL_SUBTREE_DEPS, name)) {
+          throw new Error(`${m.name}: 注册表依赖 ${name}@${spec} 不在 OPTIONAL_SUBTREE_DEPS 里 ——`
+            + ' 它位于 optional 子树(depth≥2),pnpm 的增量 hoisted 安装会丢包,'
+            + ' dsh-desktop 安装后立刻校验必报 requires missing;请把它提为插件直接依赖'
+            + '(见 docs/desktop-first-install-root-cause.md 第 5 节)');
+        }
+      }
+    }
+  }
+  const unused = Object.keys(OPTIONAL_SUBTREE_DEPS).filter((name) => !seen.has(name));
+  if (unused.length > 0) {
+    console.warn(`  ⚠ OPTIONAL_SUBTREE_DEPS 里的 ${unused.join(', ')} 已不再被任何平台专属包需要,可以删掉`);
+  }
 }
 
 function main() {
   const hostKey = `${process.platform}-${process.arch}`;
   const targets = TARGETS.length > 0 ? TARGETS : [hostKey];
-  const pluginVersion = readJson(join(pkgRoot, 'package.json'))?.version ?? '0.0.0';
 
-  let repack;
+  let repack = null;
+  let modules;
   let declare;
   let reusedItems = [];
   let autoSourceTree = null;
   if (REUSE) {
-    ({ repack, declare, reusedItems } = reuseExisting(targets, hostKey));
+    ({ modules, declare, reusedItems } = reuseExisting(targets));
   } else {
     const autoSource = FROM === null;
     const sourceTree = autoSource ? prepareSourceTree() : FROM;
     if (autoSource) autoSourceTree = sourceTree;
     ({ repack, declare } = analyze(sourceTree));
+    modules = [...repack]
+      .map(([name, r]) => ({
+        alias: name,
+        package: `${SCOPE}/dshcs-${flat(name)}`,
+        version: r.pkg.version,
+        platform: r.platformSpecific,
+      }))
+      .sort((a, b) => a.alias.localeCompare(b.alias));
     rmSync(OUT, { recursive: true, force: true });
   }
-  console.log(`\n重打包集(${repack.size}):`);
-  for (const [name, r] of [...repack].sort()) {
-    console.log(`  ${name}@${r.pkg.version} ${r.platformSpecific ? '[平台专属]' : '[全平台]'}`);
+  console.log(`\n重打包集(${modules.length}):`);
+  for (const m of modules) {
+    console.log(`  ${m.alias}@${m.version} → ${m.package}${m.platform ? `-<平台>` : ''} ${m.platform ? '[平台专属]' : '[全平台]'}`);
   }
   console.log(`\n直装集(${declare.length}): ${declare.map((d) => d.name).join(', ')}\n`);
 
   mkdirSync(join(OUT, 'build'), { recursive: true });
 
-  // 每个目标的包名映射
+  // 每个目标的包名映射:平台专属的按目标拼后缀,平台无关的到处同名
   const byTarget = new Map();
   for (const target of targets) {
-    const suffix = `-${target}`;
-    const map = new Map(); // 原包名 -> { pkgName, version }
-    for (const [name, r] of repack) {
-      const pkgName = `${SCOPE}/dshcs-${flat(name)}${r.platformSpecific ? suffix : ''}`;
-      map.set(name, { pkgName, version: r.pkg.version, platformSpecific: r.platformSpecific });
+    const map = new Map(); // 原包名 -> { pkgName, version, platformSpecific }
+    for (const m of modules) {
+      map.set(m.alias, {
+        pkgName: `${m.package}${m.platform ? `-${target}` : ''}`,
+        version: m.version,
+        platformSpecific: m.platform,
+      });
     }
     byTarget.set(target, map);
   }
@@ -581,6 +653,7 @@ function main() {
     }
   }
   // 3) 平台专属包:host 用现成树,其它目标用交叉安装树(--reuse 时用已打包目录)
+  const platformDirs = [];
   if (!REUSE) for (const target of targets) {
     const map = byTarget.get(target);
     const specs = [...repack].filter(([, r]) => r.platformSpecific).map(([name, r]) => ({ name, version: r.pkg.version }));
@@ -595,49 +668,58 @@ function main() {
         continue;
       }
       const dir = writeRepack(srcDir, info, `${flat(name)}-${target}`);
+      platformDirs.push(dir);
       plan.push({ dir, file: tgzName(info.pkgName, r.pkg.version) });
     }
     if (crossTree !== null) rmSync(crossTree, { recursive: true, force: true });
   }
-  // 3) 聚合包(每平台一个):dependencies 用 npm: 别名把重打包包装回原名
-  for (const target of targets) {
-    const map = byTarget.get(target);
-    const aggName = `${SCOPE}/dsh-code-server-runtime-${target}`;
-    const aggDir = join(OUT, 'aggregator', target);
-    mkdirSync(aggDir, { recursive: true });
-    const deps = {};
-    for (const [name] of repack) deps[name] = `npm:${map.get(name).pkgName}@${map.get(name).version}`;
-    writeFileSync(join(aggDir, 'package.json'), JSON.stringify({
-      name: aggName,
-      version: pluginVersion,
-      description: `Prebuilt native modules for the VS Code server tree on ${target} `
-        + '(node-pty, @vscode/sqlite3, kerberos, @vscode/spdlog, …), '
-        + 'so that installing the VS Code inner dependencies needs no build approval or C++ toolchain.',
-      os: [target.split('-')[0]],
-      cpu: [target.split('-')[1]],
-      dependencies: deps,
-      license: 'MIT',
-      repository: readJson(join(pkgRoot, 'package.json'))?.repository ?? undefined,
-    }, null, 2) + '\n', 'utf8');
-    plan.push({ dir: aggDir, file: tgzName(aggName, pluginVersion), aggregator: true, target });
-  }
+  // 3b) --reuse 时平台专属目录已存在,就地复查闸门
+  if (REUSE) for (const item of reusedItems) {
+    if (PLATFORM_SUFFIX.test(String(readJson(join(item.dir, 'package.json'))?.name ?? ''))) platformDirs.push(item.dir);
+  }
+  verifyOptionalSubtreeDeps(platformDirs);
+  // 3) 重打包表(lib/vendored.json,随插件发布):运行时用它把真名子包补成原始名字
+  const vendoredDoc = {
+    schemaVersion: 1,
+    generatedBy: 'scripts/vendor-repacks.mjs',
+    scope: SCOPE,
+    targets,
+    modules: modules.map((m) => {
+      const entry = { alias: m.alias, package: m.package, version: m.version };
+      if (m.platform) entry.platform = true;
+      return entry;
+    }),
+  };
+  writeFileSync(join(pkgRoot, 'lib', 'vendored.json'), `${JSON.stringify(vendoredDoc, null, 2)}\n`, 'utf8');
+  const independent = modules.filter((m) => !m.platform);
+  const specific = modules.filter((m) => m.platform);
+  console.log(`[repack] 重打包表 → lib/vendored.json(${modules.length} 个:全平台 ${independent.length} / 平台专属 ${specific.length})`);
 
   writeFileSync(join(OUT, 'pack-plan.json'), JSON.stringify(plan, null, 2) + '\n', 'utf8');
   console.log(`[repack] 生成 ${plan.length} 个待打包目录 → repack/ (计划:repack/pack-plan.json)`);
 
-  // 4) 改写插件 package.json 的依赖:纯 JS 直装集 + VS Code 树包(平台无关);
-  //    平台专属的(原生包)通过聚合包按 os/cpu 自动选。
+  // 4) 改写插件 package.json 的依赖:树 + 纯 JS 直装集 + **全平台**重打包包写 dependencies(真名);
+  //    平台专属的重打包包按目标写 optionalDependencies(真名 + 包自带 os/cpu,包管理器按架构自动选),
+  //    它们自己的注册表依赖再由 OPTIONAL_SUBTREE_DEPS 提到 dependencies(否则 pnpm 丢包,见该表注释)。
+  //    这样每个包在依赖图里都是「根项目的直接依赖」,不依赖 pnpm 对可选子树别名的处理
+  //    (见 docs/desktop-first-install-root-cause.md)。
   const pkgFile = join(pkgRoot, 'package.json');
   const pluginPkg = readJson(pkgFile);
   pluginPkg.dependencies = Object.fromEntries([
     [vscodePkg.name, vscodePkg.version],
     ...declare.map((d) => [d.name, d.version]),
+    ...independent.map((m) => [m.package, m.version]),
+    ...Object.entries(OPTIONAL_SUBTREE_DEPS),
   ].sort(([a], [b]) => a.localeCompare(b)));
   pluginPkg.optionalDependencies = Object.fromEntries(targets
-    .map((t) => [`${SCOPE}/dsh-code-server-runtime-${t}`, `^${pluginVersion}`]));
+    .flatMap((t) => specific.map((m) => [`${m.package}-${t}`, m.version]))
+    .sort(([a], [b]) => a.localeCompare(b)));
   writeFileSync(pkgFile, JSON.stringify(pluginPkg, null, 2) + '\n', 'utf8');
-  console.log(`[repack] 已写入 package.json:dependencies ${pluginPkg.dependencies ? Object.keys(pluginPkg.dependencies).length : 0} 个`
-    + `(VS Code 树 + 纯 JS),optionalDependencies ${targets.length} 个平台聚合包`);
+  console.log(`[repack] 已写入 package.json:dependencies ${Object.keys(pluginPkg.dependencies).length} 个`
+    + `(VS Code 树 + 纯 JS + ${independent.length} 个全平台重打包包`
+    + ` + ${Object.keys(OPTIONAL_SUBTREE_DEPS).length} 个 optional 子树兜底依赖),`
+    + `optionalDependencies ${Object.keys(pluginPkg.optionalDependencies).length} 个`
+    + `(${specific.length} 个平台专属重打包包 × ${targets.length} 个目标)`);
 
   // 5) 可选:直接打包
   if (DO_PACK) {