dsh-code-server-app 0.1.30 → 0.1.32

package/README.en.md

@@ -12,6 +12,21 @@
 
 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);
 - Window is an **internal floating window** (modeled on dsh-univer-office's WorktreeWindow): fixed-position overlay + an inert root container, the window takes over pointer events,
@@ -47,7 +62,7 @@ pnpm pack
 
 ```powershell
 # 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.30.tgz
+dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-server-app-0.1.32.tgz
 ```
 
 > Installation only drops plugin files: **no package scripts run and code-server is not installed**
@@ -62,7 +77,7 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-
 - **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"),
+  - Triggers: host `POST /api/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);
@@ -163,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**,
@@ -193,20 +208,39 @@ User-level override example (write in `$DSH_HOME/profiles/web/cordis.patch.yml`,
     bin: C:\Users\User\AppData\Roaming\npm\code-server.cmd
 ```
 
-## JSON API (same-origin fetch; shared by the overlay and the web page)
+## JSON API (same-origin fetch; identical paths in web and desktop)
+
+**No `webServer` dependency**: the host half registers its routes on DSH Connection's shared `/api` channel through
+`ctx.connection.fetch.register`. In the web profile Connection mounts the `/api` prefix on webServer itself (with the
+Host/Origin fence and browser auth); in the desktop profile `apps/desktop-host` feeds `/api/*` into the same
+`createSharedFetchHandler('/api')` (IPC framed pipe, no HTTP server). The client only writes relative paths
+(`fetch('/api/code-server/<op>')`), so both carriers behave identically.
 
 | Method | Path | Description |
 |---|---|---|
-| GET | `/code-server/status` | `{ ok, running, status, host, port, pid, cwd, url, version, error, logTail, adopted }` (also `env` environment check and `setup` install-task progress) |
-| POST | `/code-server/start` | body `{ cwd? }` (omit cwd to keep the current workspace); idempotent |
-| POST | `/code-server/stop` | Stop and recycle the process tree |
-| POST | `/code-server/setup` | Run the environment install in the background (npm install code-server + native + VS Code internal deps); progress via `status.setup` polling |
-| POST | `/code-server/open-file` | body `{ file }` — writes the signal consumed by the built-in `dshcs-open-file` extension to open the file in code-server (also auto-expands the window from the client side) |
+| GET | `/api/code-server/status` | `{ ok, running, status, host, port, pid, cwd, url, version, error, logTail, adopted }` (also `env` environment check and `setup` install-task progress) |
+| POST | `/api/code-server/start` | body `{ cwd? }` (omit cwd to keep the current workspace); idempotent |
+| POST | `/api/code-server/stop` | Stop and recycle the process tree |
+| POST | `/api/code-server/setup` | Run the environment install in the background (npm install code-server + native + VS Code internal deps); progress via `status.setup` polling |
+| POST | `/api/code-server/open-file` | body `{ file }` — writes the signal consumed by the built-in `dshcs-open-file` extension to open the file in code-server |
+
+> The plugin no longer registers `/code-server/*` webServer-only routes, and the code-server icon is inlined as a data URI
+> in the client bundle — the client requests no plugin-owned HTTP resource at all.
+
+## DSH Desktop (no webServer)
+
+- The host half is `inject = ['connection', 'settings']` (**no `webServer`**) — the desktop profile disables webserver/web-runtime
+  and the plugin still works: `/api/*` requests travel Electron `dsh-app://` protocol handler → IPC framed pipe → `createSharedFetchHandler('/api')`.
+- The right-sidebar tab, guide entry box, artifact button, and settings card behave the same as in web (code-server remains an
+  iframe to the local `http://127.0.0.1:<port>`; the desktop renderer uses `webSecurity: true` with no CSP, so the cross-origin iframe loads).
+- Install into the desktop profile with `dsh plugin --profile desktop add dsh-code-server-app@<version>` (or the desktop plugin manager).
 
 ## 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.
 
@@ -214,6 +248,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

@@ -14,6 +14,24 @@
 **按需安装到 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 前端会记住“最近工作区”并自行恢复,
@@ -51,7 +69,7 @@ pnpm pack
 
 ```powershell
 # 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.30.tgz
+dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-server-app-0.1.32.tgz
 ```
 
 > 安装只落插件文件,**不执行任何包脚本、不安装 code-server**(pnpm 不会提示 build scripts 许可)。
@@ -65,7 +83,7 @@ dsh plugin --profile web add C:\Users\User\Desktop\dsh-code-server-app\dsh-code-
 - **code-server 不在 `dependencies`**(pnpm 不触碰它、无脚本许可问题),改由
   `scripts/setup-code-server.mjs` 在 **profile 专用目录**用 **npm** 按需安装
   **最新版** `code-server`(不锁版本,安装时取 npm latest):
-  - 触发方式:host `POST /code-server/setup`(启动安装指引弹窗「开始安装」/ 设置卡片「安装环境」)
+  - 触发方式:host `POST /api/code-server/setup`(启动安装指引弹窗「开始安装」/ 设置卡片「安装环境」)
     或手动 `npm run setup:code-server`;
   - 安装根:`<profile>\.code-server-app`(如 `C:\Users\User\.dsh\profiles\web\.code-server-app`),
     独立项目,与 profile 依赖树隔离(避开 ERESOLVE);
@@ -162,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**,
@@ -192,19 +210,38 @@ host 探测顺序:`<profile>\.code-server-app`(专用目录)> 插件包内 `node
     bin: C:\Users\User\AppData\Roaming\npm\code-server.cmd
 ```
 
-## JSON API(同源 fetch,浮层与网页共用)
+## JSON API(同源 fetch;web 与 desktop 同一套路径)
+
+**不依赖 `webServer`**:host 半部经 `ctx.connection.fetch.register` 把路由挂在 DSH Connection 的共享 `/api` 通道上——
+web profile 由 Connection 自己把 `/api` 前缀挂到 webServer(带 Host/Origin 校验 + 浏览器鉴权),
+desktop profile 由 `apps/desktop-host` 把 `/api/*` 交给同一个 `createSharedFetchHandler('/api')`(IPC 帧管道,无 HTTP 服务器)。
+客户端只写相对路径 `fetch('/api/code-server/<op>')`,两端行为一致。
 
 | 方法 | 路径 | 说明 |
 |---|---|---|
-| GET | `/code-server/status` | `{ ok, running, status, host, port, pid, cwd, url, version, error, logTail, adopted }`(另含 `env` 环境检测与 `setup` 安装任务进度) |
-| POST | `/code-server/start` | body `{ cwd? }`(省略 cwd 不切换工作目录);幂等 |
-| POST | `/code-server/stop` | 停止并回收进程树 |
-| POST | `/code-server/setup` | 后台执行环境安装(npm 自装 code-server + native + VS Code 内部依赖);进度经 `status.setup` 轮询 |
+| GET | `/api/code-server/status` | `{ ok, running, status, host, port, pid, cwd, url, version, error, logTail, adopted }`(另含 `env` 环境检测与 `setup` 安装任务进度) |
+| POST | `/api/code-server/start` | body `{ cwd? }`(省略 cwd 不切换工作目录);幂等 |
+| POST | `/api/code-server/stop` | 停止并回收进程树 |
+| POST | `/api/code-server/setup` | 后台执行环境安装(npm 自装 code-server + native + VS Code 内部依赖);进度经 `status.setup` 轮询 |
+| POST | `/api/code-server/open-file` | body `{ file }` — 写信号文件,由内置扩展 `dshcs-open-file` 在 code-server 中打开 |
+
+> 插件不再注册 `/code-server/*` 这类 webServer 专有路由;code-server 图标已内联为 data URI(client bundle 内),
+> 因此客户端不请求任何插件自有 HTTP 资源。
+
+## DSH Desktop(无 webServer)
+
+- host 半部 `inject = ['connection', 'settings']`(**不含 `webServer`**)——desktop profile 关掉了 webserver/web-runtime,
+  本插件照常工作;`/api/*` 请求由 Electron `dsh-app://` 协议处理器 → IPC 帧管道 → `createSharedFetchHandler('/api')`。
+- 右侧栏标签、guide 入口框、产物按钮、设置卡片在 desktop 下与 web 相同(code-server 仍是本机 `http://127.0.0.1:<port>` 的 iframe;
+  桌面端 `webSecurity: true` 且页面无 CSP 限制,跨源 iframe 正常加载)。
+- 安装到 desktop profile:`dsh plugin --profile desktop add dsh-code-server-app@<版本>`(或桌面端插件管理窗)。
 
 ## 已知限制
 
 - **子路径不支持**: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)。