njjpro/dsh-remote-workspace

DSH 远程工作区（Remote Workspace）

一个窗口管两台机器：把另一台 DSH 实例的工作区接进本机侧栏，点开远端会话时，对端的真实 GUI 直接渲染在本地中列——不另开浏览器窗口，不换壳，不对端模拟。

本包为 dsh web GUI 提供设备工作区联邦。配对一台远端 DSH 实例后：

1. 远端工作区当本机工作区用。 对端的项目与会话出现在本机侧栏，就在本机工作区列表下方，浏览方式完全一致（运行状态圆点、相对时间、可折叠分组）。
2. 远端会话在本地中列就地打开。 点击侧栏里的远端会话，本地中列切换到该会话，本机侧栏常驻。渲染的是对端真实 GUI：聊天、流式输出、会话切换全部由对端后端执行，不是模拟界面，也不是把对端界面搬过来重建。
3. 仍然只占一个窗口。 不需要第二个浏览器窗口、第二套凭据、第二个书签——这正是它与「用隧道地址另开一个标签页」的本质区别。
4. 能在远端新建对话。 每个远端工作区行都提供新建入口，对端创建会话、本地打开它返回的结果，因此远端工作区不局限于已存在的会话。

远端会话在本地中列打开，侧栏「远程工作区」下列出已配对实例的工作区与会话

截图为本地界面：侧栏先列出本机工作区，其下是已配对实例的远程工作区；中列正在显示运行在另一台机器上的会话。截图中的项目名已打码。

工作原理

本包是单一双面包：

- host 半区（跑在 DSH 宿主进程）：提供对端清单路由（供已配对的远端实例读取本机工作区）、把对端 GUI 重新发布到回环端口的嵌入式代理，以及本地浏览器半区调用的控制路由。
- browser 半区（跑在 Web GUI 内）：渲染侧栏中可折叠的远程工作区分组，并把每个远端会话承载在 iframe 中。

远端会话面板经回环嵌入式代理加载：代理以设备凭据访问对端，把对端 GUI 发布到 127.0.0.1 的本地端口，因此浏览器无需持有对端 cookie，面板与本地界面同源可分。

本包在构建期独立于 @linxin666/dsh-remote-web-ui（不 import、不声明包依赖），只在运行期通过 cordis 服务 remoteWebUiPairing 读取该插件的配对身份——配对本身（签发令牌、撤销、设备 cookie）归该插件，本包只兑换一次令牌。两包的路由表不相交，可并存安装。

功能

上面四条是核心，以下是配套细节。

- 侧栏集成：分组位于官方工作区列表之下，折叠状态跨刷新保留，因此界面维持用户上次留下的样子。
- 有界挂载：同时最多挂载三个远端面板，避免常驻流耗尽同源连接预算。
- 切换不丢状态：打开本机会话只是折叠远端视图、不销毁其框架，因此下次点击时远端会话仍是已加载状态。
- 皮肤可锚定：每个远端界面输出 data-dsh-plugin="remote-workspace" 与裸值 data-dsh-part。
- 排除归档会话：对端把归档会话同时排除在会话列表与工作区成员之外，因此该分组只提供真正能打开的会话。

安装

两台机器都需要官方 @linxin666/dsh-remote-web-ui 插件：配对由它负责，本包只兑换它签发的令牌。

从 npm 安装

dsh plugin --profile web add @njjpro/dsh-remote-workspace

从本仓库安装（开发回路）

git clone
cd dsh-remote-workspace
pnpm install
pnpm build
dsh plugin --profile web add file:$(pwd)

开发

pnpm install
pnpm typecheck   # tsc -b --pretty false
pnpm test        # vitest run
pnpm build       # tsc -b && tsdown

build/tsdown.client.ts 是本仓库自带的客户端打包预设，连同它读取的平台种子表一起从 dsh-web 单仓的 shared/tsdown.client.ts 摘出，因此本包在没有那个仓库时也能构建。这里不使用 pnpm-workspace.yaml 与根级 packages/ 布局：本仓库本身就是那个包。

配置

| 键 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| enabled | boolean | true | 总开关；关闭后两个界面都不挂载。 |
| peerBaseUrl | string | '' | 已配对对端实例的基址；为空表示未配置对端。 |
| peerPairToken | secret string | '' | 在对端面板生成的一次性配对令牌；兑换一次并持久化。 |
| peerEmbedPort | number | 43121 | 嵌入式代理绑定的回环端口，仅 127.0.0.1。 |

安全模型

- 对端清单路由（/pair-remote/）要求有效的已配对设备凭据，且不把回环当作绕过通道。判定用的是宿主自身的配对检查，因此无法与本实例配对的请求读不到清单。
- 控制路由（/api/pair/peer/）仅限回环：套接字地址与 Host 头都必须是回环，因此局域网来源即便伪造 Host 也无法触达票据铸造与会话创建端点。
- 配对本身不在这里进行。令牌签发、撤销与设备 cookie 都归 @linxin666/dsh-remote-web-ui；本包只是兑换 POST /api/pair/accept，并按对端基址分别存储凭据。
- 嵌入式代理绑定 127.0.0.1，附带该凭据重新发布对端 GUI。嵌入票据一次性且有 TTL 上限，且只为清单实际列出的会话铸造。
- 未安装官方插件时配对服务缺失，所有对端路由以 401 失败关闭。

已知限制

- 远端会话的文档由对端提供，因此它的外壳、service worker 与注入脚本都是对端的那一份。这些部分的修复属于对端的安装，不在本包。
- 侧栏挂载点与嵌入布局覆盖以官方 CSS Modules 类名后缀为锚，官方界面重构后需要先做一轮真实 GUI 视觉 QA 再发版。
- 回环嵌入式代理仅支持 HTTP；经隧道访问的对端仍在它自己的源上终结。
- 运行期依赖官方插件意味着本包无法单独使用：必须安装官方插件，围栏才会放行任何请求。

许可

Apache-2.0。