dsh-code-server-app 0.1.27 → 0.1.31

package/README.en.md

@@ -10,7 +10,22 @@
 > - 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 latest [code-server](https://github.com/coder/code-server) **as a plugin dependency** (installed by the plugin's postinstall), auto-discovered and used on startup — no global npm install, no `bin` configuration.
+A static profile plugin (npm package with host + client bundle) that installs the latest [code-server](https://github.com/coder/code-server) **on demand into a dedicated profile directory** (installing the plugin itself is script-free and does not install code-server), auto-discovered and used on startup — no global npm install, no `bin` configuration.
+
+## UI carrier (chosen by the DSH version, feature-detected at runtime)
+
+| DSH version | Carrier | Entry points |
+|---|---|---|
+| **>= 0.1.5-alpha.1** (has `sidebarRight` / `sidebarRightTabs`) | **Right-sidebar tab** (kind `code-server`, chip `Code Server`); the floating window is **no longer used** | ① the **Code Server box** on the sidebar's guide ("开始") page; ② the icon button beside each turn's artifacts; ③ Settings → Plugins → Code Server → **"Open in right sidebar"** |
+| older (no sidebar service) | floating ball + internal floating window (unchanged) | the bottom-right floating ball |
+
+- Detection: `ctx.inject(['sidebarRightTabs','sidebarRight'], …)` registers the tab type only when the services are ready; if they never appear (or registration fails) nothing is registered and the floating ball fallback stays in place. No version comparison, and the plugin's own activation is never blocked.
+- The sidebar tab hosts the code-server page (iframe) and follows the current session workspace; the panel can be collapsed/split/floated/fullscreened by DSH's right sidebar.
+- **Known trade-off**: DSH renders only the active tab's body, so switching away and back remounts the iframe (a full code-server reload; unsaved editor buffers are lost). Float the tab into its own panel or keep it active for long-running sessions.
+- In sidebar mode the settings card hides "Reserve space above the composer" (floating-window geometry only). "Open in a window (new tab)" still applies to every entry point.
+- `windowedOpen` has the highest priority: when on, entry buttons always open a browser tab.
+
+## Floating ball / window (legacy-DSH fallback path only)
 
 - **Floating ball** (bottom-right, official code-server icon, above the composer): click to **expand the floating window and light it up** (blue glow), click again to **collapse**; **drag to any position** (remembered across refreshes; no accidental click after drag);
   no sidebar button, no window control button group (the ball is the only entry/toggle); the ball carries a status dot (green = running / amber = starting / red = error);
@@ -29,12 +44,12 @@ A static profile plugin (npm package with host + client bundle) that ships the l
   while `file:///C:/...` reports "Workspace does not exist".
 - Process lifecycle is managed by the host plugin: startup writes `$DSH_HOME/code-server/pid.json`, stop kills the tree (`taskkill /T` or process-group SIGKILL),
   crash/exit updates status live; after a DSH host restart the plugin **adopts** a still-running instance (verifies pid + `/healthz`), without duplicate start or killing unrelated processes;
-- `node_modules` (dependencies, including code-server) is git-ignored; after cloning, follow "Install plugin (code-server self-installed in profile)" below — `pnpm pack` + `dsh plugin --profile web add`.
+- `node_modules` (dependencies, including code-server) is git-ignored; after cloning, follow "Install the plugin (script-free install; code-server installed on demand)" below — `pnpm pack` + `dsh plugin --profile web add`.
 
 > Verified locally (BM: Windows 11 ARM64): `code-server@4.134.0` (with Code 1.135.0)
 > shipped with the plugin, auto-discovered → started → healthz 200 → cwd switch restart while running → stopped → fully recycled.
 
-## Install the plugin (code-server self-installed in profile; zero flags, zero errors)
+## Install the plugin (script-free install; code-server installed on demand)
 
 ```powershell
 # 1) Pack (in the plugin workspace)
@@ -43,34 +58,47 @@ cd C:\Users\User\Desktop\dsh-code-server-app
 pnpm install            # esbuild + motion (pack only)
 pnpm run build:client   # src/factory.js → lib/client.js
 pnpm pack
-
-# 2) One-time: approve the plugin postinstall (pnpm only honors the host root config)
-cd C:\Users\User\.dsh\profiles\web
-pnpm approve-builds dsh-code-server-app   # interactive 'yes'; if it fails, edit pnpm-workspace.yaml manually
 ```
 
-> If `approve-builds` rejects the `file:` spec (unknown), set the `dsh-code-server-app@file:...tgz` entry
-> in `pnpm-workspace.yaml`'s `allowBuilds` to `true` (equivalent to interactive approval, once only).
-
 ```powershell
-# 3) Install (published tarball; no --ignore-scripts / --allow-build needed)
-dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-server-app-0.1.20.tgz
+# 2) Install (published tarball; the plugin has no postinstall → no pnpm approve-builds / allowBuilds needed)
+dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-server-app-0.1.31.tgz
 ```
 
+> Installation only drops plugin files: **no package scripts run and code-server is not installed**
+> (pnpm prints no build-scripts approval prompt). code-server is installed **on first use**: the startup
+> install-guide modal's "Install" button, Settings → Plugins → Code Server → "Install environment",
+> or manually `node <plugin-dir>\scripts\setup-code-server.mjs` (`npm run setup:code-server`).
+
 ### Install mechanism
 
-- **code-server is not in `dependencies`** (pnpm never touches it; no script-approval issues);
-- The plugin's `postinstall` (`scripts/setup-code-server.mjs`) installs **the latest** `code-server` **with npm into a dedicated profile directory**
-  (version not pinned; npm `latest` is used at install time):
+- **Script-free install**: `package.json` has no `postinstall`, so pnpm runs no package script while
+  installing the plugin (no `pnpm approve-builds` / `allowBuilds` approval needed) and does not install code-server;
+- **code-server is not in `dependencies`** (pnpm never touches it; no script-approval issues); instead
+  `scripts/setup-code-server.mjs` installs **the latest** `code-server` **with npm into a dedicated profile
+  directory** on demand (version not pinned; npm `latest` is used at install time):
+  - Triggers: host `POST /code-server/setup` (startup guide modal "Install" / settings card "Install environment"),
+    or manually `npm run setup:code-server`;
   - Install root: `<profile>\.code-server-app` (e.g. `C:\Users\User\.dsh\profiles\web\.code-server-app`),
     a standalone project isolated from the profile dependency tree (avoids ERESOLVE);
   - The install root carries its own `package.json` with `allowScripts`: `code-server: false` (skips the official `sh ./postinstall.sh`
     — Windows has no `sh`, it would fail; `argon2/unrs-resolver: true` builds native modules; both without version pins);
   - Afterwards it installs VS Code internal dependencies (144 packages) + `bin\code-server.cmd`;
 - **code-server lands at** `<profile>\.code-server-app\node_modules\code-server\`;
-  idempotent and self-healing (reinstalling the plugin → postinstall reruns → skips if already instantiated;
-  **if the installed version differs from the latest, it auto-upgrades**).
-- **Pin a version**: set the env var `DSHCS_CODE_SERVER_VERSION` (e.g. `4.134.0`) to freeze a specific release; unset it to follow latest.
+  idempotent and self-healing (every on-demand run checks first: skips when instantiated and equal to npm latest;
+  **auto-upgrades when the installed version differs**).
+- **Pin a version**: set the env var `DSHCS_CODE_SERVER_VERSION` (it must be visible to the **process that runs setup** — the `dsh web` process for UI-triggered installs; e.g. `4.134.0`); unset it to follow latest.
+- **Why no install-time setup**: installation stays fast and succeeds even without a C++ toolchain (a missing
+  toolchain surfaces later in the "Install" flow, with logs in the top banner and the settings card); code-server
+  upgrades now happen only during on-demand installs and **no longer on every plugin reinstall**.
+
+> **Migration note when upgrading from ≤ 0.1.28**: the old plugin shipped a `postinstall`, so the profile's
+> `pnpm-workspace.yaml` may still carry `allowBuilds: dsh-code-server-app@file:...<old version>.tgz: true`
+> entries and pnpm 11 may have recorded an `ignoredBuilds` entry in `node_modules/.modules.yaml` — after which
+> every install reports `[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: dsh-code-server-app@file:...`
+> even though the new version has no install scripts at all. Fix: collapse those entries in the profile's
+> `pnpm-workspace.yaml` into a single `dsh-code-server-app: false` ("never build") and re-run the install;
+> this machine's 0.1.29 upgrade already performed that migration.
 
 > **Uninstall**: the code-server directory is independent of the plugin package — first
 > `Remove-Item -Recurse -Force <profile>\.code-server-app`, then `dsh plugin --profile web remove dsh-code-server-app`.
@@ -84,8 +112,10 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-
 dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app
 ```
 
-> A source path installs via `link:`; pnpm installs code-server into the **plugin workspace node_modules**;
-> the layout differs from the profile-dir approach (the host supports both). First time also needs step 2 above.
+> A source path installs via `link:`; when the profile layout is unavailable, the host's
+> `scripts/setup-code-server.mjs` falls back to installing code-server into the **plugin workspace node_modules**
+> (the host supports both layouts). The install itself runs no scripts; on first use click "Install" or run
+> `npm run setup:code-server` manually.
 >
 > **Changing the client bundle**: edit `src/factory.js` then run `pnpm run build:client`
 > to regenerate `lib/client.js` (that artifact is not tracked; a browser refresh picks it up — no host restart needed).
@@ -93,7 +123,7 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app
 
 ### Environment requirements (packages that need building + toolchain)
 
-During installation (`postinstall` → `scripts/setup-code-server.mjs` → npm self-installs code-server + VS Code internal deps), **only one package really needs local compilation**:
+During the on-demand install (`scripts/setup-code-server.mjs` → npm self-installs code-server + VS Code internal deps), **only one package really needs local compilation** (installing the plugin itself needs no toolchain):
 
 | Package | Build method | ARM64 local compile | x64 local compile |
 |---|---|---|---|
@@ -123,15 +153,17 @@ During installation (`postinstall` → `scripts/setup-code-server.mjs` → npm s
 - **VS needs the Spectre-mitigated libraries** (MSB8040): Visual Studio Installer → Individual components →
   "MSVC v18x Spectre-mitigated libraries for ARM64" (same for x86/x64).
 - **node-gyp 13.x** (9.x does not recognize VS 2026): `npm install -g node-gyp@latest`.
-- Latest code-server requires **Node v24** (checked by postinstall; v24.13.1 verified here).
+- Latest code-server requires **Node v24** (v24.13.1 verified here; a lower version fails at startup).
 - If you don't need the self-contained install (e.g. a global code-server already exists), skip it:
   the plugin falls back to a configured/PATH `bin` (see the "Config" table).
 
 ### Upgrading the code-server version
 
-- **Automatic by default**: postinstall does not pin the version — if the installed version differs from npm latest it reinstalls to latest (no manual edits).
-- **To pin**: set the env var `DSHCS_CODE_SERVER_VERSION` (e.g. `4.134.0`); unset it to follow latest again.
-- Re-run `pnpm pack` + `dsh plugin --profile web add <tgz>` to trigger the postinstall check (or delete `.code-server-app` and reinstall).
+- **Automatic by default**: the script does not pin the version — during an on-demand install, if the installed version differs from npm latest it reinstalls to latest (no manual edits).
+- **How to trigger**: Settings → Plugins → Code Server → "Install environment", or `npm run setup:code-server`;
+  **it no longer upgrades on plugin reinstall** (reinstalling the plugin neither installs nor upgrades code-server).
+- **To pin**: set the env var `DSHCS_CODE_SERVER_VERSION` (e.g. `4.134.0`; must be in the `dsh web` process environment); unset it to follow latest again.
+- Measured locally: installed `4.135.0`, npm latest `4.136.2` — the next on-demand install will upgrade to `4.136.2`.
 
 ### Compatibility with the old runtime-directory install
 
@@ -146,8 +178,8 @@ persisted via the official settings domain (`settingsScope`, namespace `code-ser
 
 | Key | Default | Description |
 |---|---|---|
-| `reserveComposer` | `true` | Whether the window **reserves space above the composer**: on, the window's initial/drag/resize/maximize stop above the composer (never covers it); off, it may cover the composer (maximize to viewport bottom) |
-| `windowedOpen` | `false` | **Open in a window**: on, clicking the floating ball opens code-server in a browser **new tab** (auto-starts and follows the active workspace); off (default) uses the internal floating window |
+| `reserveComposer` | `true` | Whether the window **reserves space above the composer**: on, the window's initial/drag/resize/maximize stop above the composer (never covers it); off, it may cover the composer (maximize to viewport bottom). **Applies to the legacy floating window only** — hidden in sidebar mode |
+| `windowedOpen` | `false` | **Open in a window**: on, every entry point (artifact button / settings card / floating ball) opens code-server in a browser **new tab** (auto-starts and follows the active workspace); off (default) uses the right-sidebar tab (or the internal floating window on older DSH) |
 
 > Card changes take effect immediately via `scope.watch` (the host status API returns `reserveComposer` and
 > `windowedOpen`; the client applies them at once); no dsh restart needed. **After adding new setting keys, restart dsh web before first use**,
@@ -189,7 +221,9 @@ User-level override example (write in `$DSH_HOME/profiles/web/cordis.patch.yml`,
 ## Artifact open buttons
 
 Each produced file (written/edited) in a turn is shown as a chip with a **code-server icon button** next to it
-in the conversation's turn tail; clicking either opens the file in code-server (and expands the floating window if collapsed).
+in the conversation's turn tail; clicking either opens the file in code-server — in the right-sidebar tab on
+DSH >= 0.1.5-alpha.1 (opening/expanding the column and focusing the tab), or in the floating window on older hosts
+(when `windowedOpen` is on, both open a browser tab instead).
 The `dshcs-open-file` extension is installed as a **built-in** extension of code-server (in `lib/vscode/extensions`),
 so users cannot remove it from the extensions panel.
 
@@ -197,6 +231,7 @@ so users cannot remove it from the extensions panel.
 
 - **No sub-path**: the code-server front-end uses root paths/WebSocket/Service Worker, so it must be a direct iframe on its own port;
   no DSH webServer reverse proxy; `--base-path` is not officially supported.
-- **Single instance across sessions**: one shared code-server per host; switching cwd requires a restart (the overlay handles it and hints).
+- **Single instance across sessions**: one shared code-server per host; switching cwd requires a restart (the sidebar tab / floating window handles it and hints).
+- **Sidebar tab switching reloads**: DSH's right sidebar renders only the active tab's body, so switching away and back remounts the iframe (a full code-server reload); keep the tab active or float it for long-running sessions.
 - **Remote access**: default is loopback + no auth. Cross-machine access requires `host` + `auth: password` + `passwordToken`,
   and the browser must be able to reach that host directly (the plugin's "open in new tab" builds the URL from `host:port`).

package/README.md

@@ -11,9 +11,27 @@
 > - **需要微软专有扩展时**:从 Marketplace 网页下载 `.vsix`,用 `code-server --install-extension <文件>`(或放入 `--extensions-dir`)手动安装,即可在插件列表使用。
 
 静态 profile 插件(npm 包形态,host + client bundle),把最新版 [code-server](https://github.com/coder/code-server)
-**作为插件依赖随装**(package.json dependencies),插件启动时自动发现并使用它,
+**按需安装到 profile 专用目录**(安装插件本身零脚本、不装 code-server),插件启动时自动发现并使用它,
 无需全局 npm 安装、无需配置 `bin`。
 
+## UI 载体(DSH 版本决定,运行时特性检测)
+
+| DSH 版本 | 载体 | 入口 |
+|---|---|---|
+| **≥ 0.1.5-alpha.1**(有 `sidebarRight` / `sidebarRightTabs` 服务) | **右侧栏标签**(kind=`code-server`,标签名 `Code Server`),**不再使用悬浮窗** | ① 右侧栏「开始」页的 **Code Server 入口框**;② 每轮产物旁的图标按钮;③ 设置 → 插件 → Code Server → **「在右侧栏打开」** |
+| 更早(无右侧栏服务) | 悬浮球 + 内部浮动窗口(与旧版一致) | 右下角悬浮球 |
+
+- 检测方式:`ctx.inject(['sidebarRightTabs','sidebarRight'], …)`——服务就绪才注册标签类型;
+  服务缺失/注册失败则整段不生效,自动回退悬浮球(不按版本号硬判,也不影响插件激活)。
+- 侧栏标签内即 code-server 页面(iframe),跟随当前会话工作区;面板可折叠/分屏/浮动/全屏(由 DSH 右侧栏提供)。
+- **已知取舍**:DSH 只渲染「当前激活标签」的 body,切到别的标签再切回会重挂 iframe
+  (code-server 整页重载,未保存的编辑缓冲区会丢);需要长驻会话时请把该标签**浮动**出来或保持激活。
+- 设置卡片在侧栏模式下隐藏「保留输入框上方空间」(只对浮窗有意义);
+  「窗口化打开(新标签页)」仍然生效(开启后各入口改为浏览器新标签页打开)。
+- `windowedOpen` 优先级最高:开启时入口按钮一律新开浏览器标签页。
+
+## 悬浮球 / 浮窗(仅旧版 DSH 回退路径)
+
 - **右下角悬浮球**(code-server 官方图标,输入框上方):点击**展开浮窗并亮起**(蓝色光环),再点击**收起并复原**;
   **可按住拖动到任意位置**(松手后记忆,刷新不丢;拖完不会误触发点击);
   无侧栏按钮、无窗口控制按钮组(球是唯一入口/开关);球上带运行状态点(绿=运行 / 黄=启动中 / 红=错误);
@@ -22,7 +40,7 @@
   **最大化后按住顶部细条向下拖 = 恢复**并继续跟手拖动)、双击最大化、8 向缩放、Esc 关闭(与球收起等效),
   初始位置在输入框上方靠右,最大化与缩放都止于输入栏上方,不遮挡 composer;
 - 窗口内直接是 code-server 页面(iframe);未运行/启动失败时显示状态说明与错误信息;
-- code-server 服务目录**跟随活动工作区/会话**:浮层打开期间切换 DSH 会话/工作区,code-server 自动重启到新目录
+- code-server 服务目录**跟随活动工作区/会话**:打开期间切换 DSH 会话/工作区,code-server 自动重启到新目录
   (解析优先级:当前会话 cwd → 会话所属 workspace.path → recentWorkspace.path → 首个 workspace.path);
   打开目录显示在 code-server 页面内(`?folder=<cwd>`,跟随切换时页面自动重新加载);
   实现要点:iframe src 必须带 `?folder=<cwd>`——code-server 前端会记住“最近工作区”并自行恢复,
@@ -33,12 +51,12 @@
 - process 生命周期由 host 插件管理:启动写 `$DSH_HOME/code-server/pid.json`,停止树级终止(taskkill /T 或进程组 SIGKILL),
   崩溃/退出实时更新状态;DSH host 重启后自动 adopt 仍在运行的实例(校验 pid + /healthz),不重复启动、不误杀别的进程;
 - `node_modules`(依赖,含 code-server)已被 `.gitignore` 排除,推送/克隆仓库后按下方
-  "安装插件(code-server 包内自装)"执行 `pnpm pack` + `dsh plugin --profile web add` 即可。
+  "安装插件(安装期零脚本,code-server 按需安装)"执行 `pnpm pack` + `dsh plugin --profile web add` 即可。
 
 > 本机(BM: Windows 11 ARM64)实测:`code-server@4.134.0`(with Code 1.135.0)
 > 随插件依赖安装并完成自动发现 → 启动 → healthz 200 → 运行中切换 cwd 重启 → 停止 → 回收全链路验证。
 
-## 安装插件(code-server 包内自装,零 flag 零报错)
+## 安装插件(安装期零脚本,code-server 按需安装)
 
 ```powershell
 # 1) 打包(在插件工作区)
@@ -47,34 +65,43 @@ cd C:\Users\User\Desktop\dsh-code-server-app
 pnpm install            # esbuild + motion(仅打包用)
 pnpm run build:client   # src/factory.js → lib/client.js
 pnpm pack
-
-# 2) 一次性前置:批准插件 postinstall 许可(pnpm 只认宿主根配置,无包内声明路径)
-cd C:\Users\User\.dsh\profiles\web
-pnpm approve-builds dsh-code-server-app   # 交互选 yes;失败时手动编辑 pnpm-workspace.yaml
 ```
 
-> 若 `approve-builds` 不接受 file: spec(提示 unknown),把 `pnpm-workspace.yaml` 的
-> `allowBuilds` 中 `dsh-code-server-app@file:...tgz`改为 `true`
-> (等价于交互批准,仅此一次;之后安装无需再次处理)。
-
 ```powershell
-# 3) 安装(发布形态 tarball;无需 --ignore-scripts / --allow-build)
-dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-server-app-0.1.15.tgz
+# 2) 安装(发布形态 tarball;插件无 postinstall → 无需 pnpm approve-builds / allowBuilds)
+dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-server-app-0.1.31.tgz
 ```
 
+> 安装只落插件文件,**不执行任何包脚本、不安装 code-server**(pnpm 不会提示 build scripts 许可)。
+> code-server 在**首次使用时按需安装**:启动安装指引弹窗「开始安装」→ 设置 → 插件 → Code Server
+> → 「安装环境」,或手动 `node <插件目录>\scripts\setup-code-server.mjs`(`npm run setup:code-server`)。
+
 ### 安装机制
 
-- **code-server 不在 `dependencies`**(pnpm 不触碰它、无脚本许可问题);
-- 插件的 `postinstall`(`scripts/setup-code-server.mjs`)在 **profile 专用目录**用 **npm** 自装
+- **安装期零脚本**:`package.json` 无 `postinstall`,pnpm 安装插件时不执行任何包脚本
+  (无需 `pnpm approve-builds` / `allowBuilds` 批准),也不安装 code-server;
+- **code-server 不在 `dependencies`**(pnpm 不触碰它、无脚本许可问题),改由
+  `scripts/setup-code-server.mjs` 在 **profile 专用目录**用 **npm** 按需安装
   **最新版** `code-server`(不锁版本,安装时取 npm latest):
+  - 触发方式:host `POST /code-server/setup`(启动安装指引弹窗「开始安装」/ 设置卡片「安装环境」)
+    或手动 `npm run setup:code-server`;
   - 安装根:`<profile>\.code-server-app`(如 `C:\Users\User\.dsh\profiles\web\.code-server-app`),
     独立项目,与 profile 依赖树隔离(避开 ERESOLVE);
   - 安装根自带 `package.json`(allowScripts:`code-server: false` 跳过官方 `sh ./postinstall.sh`
     ——Windows 无 sh 会失败、`argon2/unrs-resolver: true` native 构建,均不带版本号);
   - 装完补装 VS Code 内部依赖(144 包)+ `bin\code-server.cmd`;
 - **code-server 落在** `<profile>\.code-server-app\node_modules\code-server\`;
-  幂等自愈(pnpm 重装插件 → postinstall 重跑 → 检测已实例化则跳过;**若已装版本与最新不一致则自动升级到最新**)。
-- **锁版本**:设置环境变量 `DSHCS_CODE_SERVER_VERSION`(如在 dsh web 环境)可钉住某个版本(如 `4.134.0`);缺省跟随 npm latest。
+  幂等自愈(每次按需调用先检测:已实例化且版本与 npm latest 一致则跳过;**不一致则自动升级到最新**)。
+- **锁版本**:设置环境变量 `DSHCS_CODE_SERVER_VERSION`(需出现在**执行 setup 的进程**环境中,UI 触发即 dsh web 进程)可钉住某个版本(如 `4.134.0`);缺省跟随 npm latest。
+- **为什么安装期不装**:安装快、没有 C++ 工具链也能装成功(缺工具链的失败延后到「开始安装」,错误显示在
+  顶部横幅与设置卡片日志);code-server 升级只发生在按需安装时,**不再随每次重装插件自动升级**。
+
+> **从旧版本升级的迁移提示(≤ 0.1.28)**:旧版插件带 `postinstall`,profile 的 `pnpm-workspace.yaml`
+> 里曾有 `allowBuilds: dsh-code-server-app@file:...<旧版本>.tgz: true` 条目,pnpm 11 还可能在
+> `node_modules/.modules.yaml` 留下 `ignoredBuilds` 记录——于是每次安装后都会报
+> `[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: dsh-code-server-app@file:...`(即使新版本已无任何
+> 安装脚本)。处理:把 profile 的 `pnpm-workspace.yaml` 中该包相关条目合并为一条
+> `dsh-code-server-app: false`(显式声明"永不构建"),重跑安装即可;本机 0.1.29 升级已完成该迁移。
 
 > **卸载**:code-server 目录独立于插件包——先手动删除
 > `Remove-Item -Recurse -Force <profile>\.code-server-app`,再 `dsh plugin --profile web remove dsh-code-server-app`。
@@ -88,8 +115,9 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-
 dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app
 ```
 
-> 源码路径以 `link:` 安装,pnpm 会把 code-server 装到**插件工作区 node_modules**;
-> 与方案 D 的布局不同(host 已支持两种)。首次也需按上面的步骤 2 批准 postinstall 许可。
+> 源码路径以 `link:` 安装;host 的 `scripts/setup-code-server.mjs` 在 profile 布局不可用时回退把
+> code-server 装到**插件工作区 node_modules**(两种布局 host 都支持)。
+> 安装本身不跑脚本,首次使用需点「开始安装」或手动 `npm run setup:code-server`。
 >
 > **改动 client bundle**:编辑 `src/factory.js` 后执行 `pnpm run build:client`
 > 重新生成 `lib/client.js`(仓库不跟踪该产物;浏览器刷新即生效,host 无需重启)。
@@ -97,7 +125,7 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app
 
 ### 安装环境要求(需要编译的包与工具链)
 
-安装过程(`postinstall` → `scripts/setup-code-server.mjs` → npm 自装 code-server + VS Code 内部依赖)中,**真正需要本地编译的只有一个包**:
+按需安装过程(`scripts/setup-code-server.mjs` → npm 自装 code-server + VS Code 内部依赖)中,**真正需要本地编译的只有一个包**(安装插件本身不需要任何工具链):
 
 | 包 | 构建方式 | ARM64 本地编译 | x64 本地编译 |
 |---|---|---|---|
@@ -127,15 +155,17 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app
 - **VS 需 Spectre 缓解库组件**(MSB8040):Visual Studio Installer → 单个组件 →
   "适用于 ARM64 的 MSVC v18x Spectre-mitigated 库"(x86/x64 同理)。
 - **node-gyp 13.x**(旧版 9.x 不识别 VS 2026):`npm install -g node-gyp@latest`。
-- code-server 最新版要求 **Node v24**(postinstall 校验;本机 v24.13.1 通过)。
+- code-server 最新版要求 **Node v24**(本机 v24.13.1 通过;版本不足时启动会报错)。
 - 若不需要插件自足(例如已有全局 code-server),可跳过安装:
   插件会回退到 PATH/配置的 `bin`(见"配置"表)。
 
 ### 升级 code-server 版本
 
-- **默认自动**:postinstall 不锁版本——已装版本与 npm latest 不一致时自动重装到最新(无需手动改)。
-- **想钉住版本**:设环境变量 `DSHCS_CODE_SERVER_VERSION`(如 `4.134.0`);去掉它回到跟随 latest。
-- 重新 `pnpm pack` + `dsh plugin --profile web add <tgz>` 即触发 postinstall 检查(或直接删 `.code-server-app` 重装)。
+- **默认自动**:脚本不锁版本——按需安装时若已装版本与 npm latest 不一致则自动重装到最新(无需手动改)。
+- **触发检查**:设置 → 插件 → Code Server → 「安装环境」,或手动 `npm run setup:code-server`;
+  **不再随插件重装自动升级**(重装插件本身不安装/升级 code-server)。
+- **想钉住版本**:设环境变量 `DSHCS_CODE_SERVER_VERSION`(如 `4.134.0`;需在 dsh web 进程环境中);去掉它回到跟随 latest。
+- 本机当前实测:已装 `4.135.0`,npm latest `4.136.2`——下次按需安装会升级到 `4.136.2`。
 
 ### 兼容旧的 runtime 目录安装
 
@@ -150,8 +180,8 @@ host 探测顺序:`<profile>\.code-server-app`(专用目录)> 插件包内 `node
 
 | 键 | 默认 | 说明 |
 |---|---|---|
-| `reserveComposer` | `true` | 窗口是否**保留输入框上方空间**:开启时窗口初始/拖动/缩放/最大化都止于输入栏上方(不遮挡 composer);关闭后允许盖住输入框(最大化到视口底) |
-| `windowedOpen` | `false` | **窗口化打开**:开启后点击悬浮球在浏览器**新标签页**打开 code-server(自动启动并跟随当前工作区目录);关闭(默认)使用内部浮动窗口 |
+| `reserveComposer` | `true` | 窗口是否**保留输入框上方空间**:开启时窗口初始/拖动/缩放/最大化都止于输入栏上方(不遮挡 composer);关闭后允许盖住输入框(最大化到视口底)。**仅对旧版 DSH 的浮窗生效**——右侧栏模式下该行隐藏 |
+| `windowedOpen` | `false` | **窗口化打开**:开启后各入口(产物按钮 / 设置卡 / 悬浮球)在浏览器**新标签页**打开 code-server(自动启动并跟随当前工作区目录);关闭(默认)使用右侧栏标签(旧版 DSH 为内部浮动窗口) |
 
 > 卡片改动经 `scope.watch` 实时生效(host 端 status API 同步返回 `reserveComposer` 与
 > `windowedOpen`,客户端立即生效);无需重启 dsh。**新增设置键后首次使用前需重启 dsh web**,
@@ -193,6 +223,8 @@ host 探测顺序:`<profile>\.code-server-app`(专用目录)> 插件包内 `node
 
 - **子路径不支持**:code-server 前端使用根路径/WebSocket/Service Worker,因此必须独立端口
   iframe 直连,不做 DSH webServer 反向代理;`--base-path` 官方不支持。
-- **跨会话单实例**:host 级共享一份 code-server;切换 cwd 需重启实例(浮层自动处理并提示)。
+- **跨会话单实例**:host 级共享一份 code-server;切换 cwd 需重启实例(右侧栏标签/浮窗自动处理并提示)。
+- **侧栏标签切换重载**:DSH 右侧栏只渲染当前激活标签的 body,切走再切回会重挂 iframe(code-server 整页重载);
+  长驻会话请保持该标签激活或将其浮动为独立面板。
 - **远程访问**:默认仅回环 + 无认证。跨机访问需改 `host` + `auth: password` + `passwordToken`,
   且浏览器必须能直接到达该主机(本插件的“在新标签打开”按 `host:port` 拼 URL)。