@jaxzhou/dsh-proxy-client
dsh-proxy 的 DSH 客户端插件包（npm 包名 @jaxzhou/dsh-proxy-client，本地目录 packages/dsh-proxy-client）：把本机终端里的 dsh web 通过 dsh-proxy-server 反向暴露给同账号的其它端，并提供 GUI 配置页面。
- 宿主半（
lib/index.js，cordis 插件）：本地配置/令牌存储、出站 WebSocket 持久连接与自动重连、把服务器开出的虚拟流桥接到 ctx.webServer.port 上的本机 dsh web、注册面板 API。零运行时依赖（用 Node 内置 WebSocket）。
- 浏览器半（
lib/client.js，window.__ModuleLoader__ bundle）：侧边栏底部入口 + 键控 main 面板，提供服务器地址、与 textwork.cn 相同的账号登录（手机号+短信验证码 / 账号密码）、连接开关、设备列表与「切换到此端」。
账号与 textwork.cn 一致：手机号 + 短信验证码（含京东云人机验证），或账号密码。登录由代理服务器
内部转调 textwork.cn 后端完成；本机只保存服务器签发的长效 token（默认 30 天），密码不落盘。
安装
# 在跑 dsh web 的机器上（包内声明了 dsh.bundle，安装后自动加入 profile bundles 并激活）
dsh plugin --profile web add @jaxzhou/dsh-proxy-client # 从 npm
dsh plugin --profile web add <仓库路径>/packages/dsh-proxy-client # 或从本地目录（开发时）
dsh --profile web # 重启后生效
启动日志出现下面两行即装载成功：
[dsh-proxy-client] panel API ready; local dsh web on 127.0.0.1:3080
[dsh-proxy-client] not connected yet - configure the server address and log in from the DSH sidebar panel
若把包作为普通依赖安装（不带 bundle 声明），需在 profile 的 cordis.patch.yml 手工加入：
- insert:
- id: jaxzhou-proxy-client
name: '@jaxzhou/dsh-proxy-client'
⚠️ 不要同时使用两种方式：本包自带的 bundle 层会插入同一行；重复的 loader entry id 会让 dsh web
启动失败（duplicate loader entry id: jaxzhou-proxy-client）。如果你以前手工加过这一行，升级/安装本包后
请把手工行删掉（profile 的 cordis.patch.yml 恢复为 []）再重启。
故障隔离（远端不可用时不影响 DSH）
本插件是可选增强：代理服务器宕机、网络不可达、服务器地址写错、甚至本地配置文件不可写，
都不应影响 DSH 本体和其它插件。为此：
| 风险 | 处理 |
|---|
| 启动时阻塞 | apply() 不做任何网络 I/O；首次连接用 setTimeout(0) 推迟到启动路径之外，DSH 启动不等待本插件 |
| 连接挂死 | 连接阶段有 20s 上限（connectTimeoutMs，含 TCP/TLS/WS 升级）；握手另有 10s 上限；超时即放弃并按指数退避重试（1s → 30s） |
| 关闭卡住 | stop() 最多等 3s（stopTimeoutMs），并用 generation 计数让被放弃的旧循环彻底失效，不会出现双循环 |
| 未处理 rejection 杀掉进程 | 连接循环、重连、事件回调、节流定时器全部自带捕获；后台任务绝不以 rejection 收尾（unhandled rejection 在现代 Node 上是致命错误，会连带杀掉 DSH） |
| 同步抛错破坏插件树 | apply() 整体不抛：面板路由注册失败只损失面板、隧道照常；配置存储不可用则整个插件安静退出 |
| 配置文件不可写 | 读/写/解析失败一律降级为内存配置（store.lastError 记录原因，日志提示一次），插件继续可用 |
| GUI 渲染异常 | 插件注入的两个 slot 都包在错误边界里：本插件面板崩溃只会显示一块「已隔离」小卡片，不会白屏 DSH 或影响其它插件 slot |
| 面板请求挂住 | 浏览器半的每次调用有 30s 上限；宿主半的面板 API 对上游请求有 20s 上限，服务器不可达时快速返回类型化错误（含上游状态码） |
| 日志刷屏 | 连接失败只在状态变化时记录，退避到 30s 后每分钟最多两条 |
| 进程无法退出 | 插件创建的所有定时器都 unref()，不会阻止 DSH 正常关闭 |
对应的自动化断言见 npm run e2e 的「resilience: remote server unavailable」一节（93 项断言内）。
配置页面
入口在 侧边栏底部、设置（Settings）行正上方：一个「远程访问」行（折叠成窄栏时是圆形图标），
行尾带一个连接状态小圆点（绿=已连接 / 黄=连接中 / 红=认证失败 / 灰=未连接）。点击即可打开配置面板：
| 区块 | 内容 |
|---|
| 状态 | 已连接 / 连接中 / 认证失败 / 未配置，以及当前连接的细节 |
| 本机 DSH Web | 代理将要暴露的本机地址（自动取自 DSH 实际监听端口）与设备名/ID |
| 服务器 | 服务器地址、设备名、自动连接、反向访问（是否共享本机 DSH 启动令牌）、连接 / 断开、保存并应用；外加一行只读的「登录账号」状态（已登录显示显示名 + 切换账号 / 退出登录） |
| 同账号在线端 | 设备名、ID、连接时间、「本机」标记与「在服务器中打开 →」（新标签页打开服务器同源的设备视图 https://<server>/d/<设备ID>/，由服务器经本插件的隧道代理到对方本机的 dsh web） |
生产服务器地址：https://dsh.textwork.cn。
连接与登录流程
面板本身只有「地址 + 连接」，凭据只在弹窗里输入：
填服务器地址 ──► 点「连接」
│
├─ 本机已有可用 token ──► 直接连接（不打扰）
│
└─ 没有 token / token 已失效 ──► 弹出账号输入框
├─ 手机号验证码登录（可注册）
└─ 账号密码登录
↓
提交给代理服务器换取登录令牌（密码不落盘）
↓
自动连接并上线
要点：
- 客户端不保存密码：弹窗里的凭据只提交给代理服务器，服务器校验后返回一个长效 token，
本机只保存这个 token（
$DSH_HOME/dsh-proxy-client.json，0600）。
- 弹窗内容随服务器能力变化：
/api/auth/config 报告该服务器是否支持短信登录 / 账号密码 / 注册
（textwork.cn 三种都支持；--auth local 的独立部署只显示账号密码）。
- 切换服务器会失效旧 token：
/config 发现地址变化时会清掉上一个服务器签发的 token，
下次「连接」重新弹窗——避免拿 A 服务器的 token 去连 B 服务器。
- 登录态失效（服务器重启、token 过期、被吊销）时面板显示「认证失败」，点「连接」会重新弹窗。
- 已登录时也可以点「切换账号」主动换一个账号，或点「退出登录」清除本机 token。
本地配置
$DSH_HOME/dsh-proxy-client.json（默认 ~/.dsh/dsh-proxy-client.json，权限 0600）：
{
"serverUrl": "https://dsh.textwork.cn",
"account": "13810385787",
"displayName": "138****5787",
"token": "<代理服务器下发的 bearer token>",
"deviceId": "<本机稳定设备 ID，首次自动生成>",
"deviceName": "desk-pc",
"autoConnect": true,
"shareLoginToken": true
}
密码与短信验证码从不写入该文件。
面板 API（DSH 同源，供面板使用）
| 方法与路径 | 说明 |
|---|
GET /dsh-proxy-client/api/status | 连接状态、脱敏配置、本机 dsh web 地址、同账号设备（带 self 标记） |
GET /dsh-proxy-client/api/auth-config?serverUrl= | 目标服务器支持的登录方式（authMode/phoneLogin/passwordLogin/register） |
GET /dsh-proxy-client/api/captcha-session?serverUrl= | 人机验证风险预判（转发给代理服务器 → textwork 上游） |
POST /dsh-proxy-client/api/send-code | {serverUrl?, phone, captchaSid, captchaToken} → 发送短信验证码 |
POST /dsh-proxy-client/api/login | /register | {serverUrl?, phone, smsCode, displayName?} 或 {serverUrl?, username, password} → 登录并保存 token、连接 |
POST /dsh-proxy-client/api/config | {serverUrl?, deviceName?, autoConnect?, shareLoginToken?} → 保存并重连；地址变化时清除上一个服务器签发的 token，返回体里的 config.hasToken 决定面板是直接连接还是弹窗 |
POST /dsh-proxy-client/api/logout | 注销并断开 |
POST /dsh-proxy-client/api/connect | /disconnect | 手动连接控制 |
POST /dsh-proxy-client/api/attach | {deviceId} → 服务器返回同源代理地址（/d/<设备ID>/?ticket&token），浏览器无需能访问目标机器 |
该路由与 DSH GUI 同源、默认只在回环可达；令牌始终留在宿主半，浏览器半拿不到。
上游状态码会一并回传（{ok:false,error,status}），因此验证码服务不可用时前端能与服务器一样「放行」。
反向访问的登录链路
目标端 DSH 的首页需要它自己的进程启动令牌。宿主半通过 DSH Connection 服务的 ctx.connection.authenticatedUrl() 读到该令牌（受「反向访问」开关控制），随 hello 上报给服务器；服务器在 attach URL 上拼接：
https://dsh.textwork.cn/d/<deviceId>/?__dshproxy_ticket=<ticket>&token=<目标端启动令牌>
浏览器停在代理服务器的源上，服务器经隧道转发；目标 DSH 完成 token→cookie 交换，标签页里获得完整可用的 GUI。
开发与测试
# 无需 DSH 的宿主模拟器（跑本包真实的连接管理器）
node scripts/fake-client.ts --server http://127.0.0.1:4000 --username demo --password demo1234 \
--name desk-pc --target 127.0.0.1:3080 --state .tmp/client-desk.json
npm run smoke:client # 用 react-dom/server 真渲染浏览器半（28 项：面板无内联凭据表单、弹窗两种登录方式、错误边界）
npm run e2e # 进程内 97 项断言（含 textwork 认证中转、面板 API 契约与故障隔离）
npm run probe:deployed # 对已部署服务器做真实 TLS 端到端探测（两阶段：服务端隧道 + 面板 API 登录流程）
npm run check # typecheck + smoke:client + e2e
npm run demo # 五进程本地演示
代码地图
| 文件 | 作用 |
|---|
lib/index.js | cordis 插件：注册面板路由、读取 DSH 启动令牌、启动/停止连接；apply() 不抛错、不做内联网络 I/O |
lib/connection.js | WebSocket 会话循环、重连退避、流桥接、背压；连接/握手/停止均有超时上界，回调全部隔离 |
lib/settings.js | 配置存储（原子写、0600、deviceId 生成）；I/O 失败降级为内存配置并记录 lastError |
lib/api.js | 面板 API、textwork 登录链路中转、服务器 REST 调用（20s 上游超时，响应写入自带保护；切换服务器时清 token） |
lib/protocol.js | 线协议帧（与 proxy-server 的 protocol.ts 逐字节一致，e2e 校验） |
lib/client.js | 浏览器半 bundle：侧边栏图标 + 「地址 + 连接」主面板 + 账号弹窗（两种登录方式）+ 人机验证浮层；两个 slot 均包错误边界，调用有 30s 上限 |
cordis.patch.yml | bundle 层：插入插件行（id: jaxzhou-proxy-client） |
