dsh-lan-guard 0.3.5 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +137 -0
- package/README.md +58 -2
- package/README.zh.md +57 -2
- package/lib/client.js +1038 -13
- package/lib/client.js.map +1 -1
- package/lib/index.d.ts +81 -0
- package/lib/index.js +992 -52
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,142 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.4.1] — 2026-09-28(修掉手机端「聊天区滑不动」)
|
|
4
|
+
|
|
5
|
+
### 修复 — 手机上会话内容可见但无法上下滑动
|
|
6
|
+
|
|
7
|
+
**症状**(2026-09-28 用户报告):手机上打开会话,最新内容能看到一部分,但**无法上下滑动**;底部固定的「目标条 / 快捷回复 / 输入框」压住内容,右侧滚动条停在中途。
|
|
8
|
+
|
|
9
|
+
**定位(诊断数据来自真实 iPhone 视口)**:DSH 官方外壳在**窄屏 + 移动端**下的根层 `pI_x6G_frame` 是 `overflow:hidden` 且内容溢出——实测 `clientHeight=844 / scrollHeight=1688`,同时**整页也不可滚**(`pageScrolls=false`)。内容被裁在容器里,手指自然滑不动。同一视口在桌面 Chrome 上滚动正常,因此这是 iOS/窄屏的布局差异,**与反向代理无关**(页面 DOM/CSS 全部来自官方 UI)。
|
|
10
|
+
|
|
11
|
+
**改动**:新增默认开启的 `mobileScrollFix`。注入的脚本**只在四个条件同时成立时**才动手:窄屏(≤1023px)、移动端 UA、**整页不可滚**、且**确实找到被裁剪且内容溢出的层**;然后只把那几层改为可触摸滚动(`overflow-y:auto`、`-webkit-overflow-scrolling:touch`、`touch-action:pan-y`)。能正常滚动的页面一律不碰(实测:桌面视口与健康页面下 no-op)。诊断:页面 URL 加 `?lgdiag=1` 会显示一屏布局数据(`narrow/mobile/innerH/pageScrolls/clippingLayers/是否已修`)。
|
|
12
|
+
|
|
13
|
+
### 真机验收(2026-09-28 用户实测通过)
|
|
14
|
+
|
|
15
|
+
同一台 iPhone(16 Pro Max)上验证:
|
|
16
|
+
|
|
17
|
+
| 场景 | 结果 |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| 打开长会话 | 能看到最新内容、可上下滑动(修复前内容被裁、滑不动) |
|
|
20
|
+
| **锁屏 60 秒后回来** | 会话仍在、**无需重连**,回来后直接发消息成功 |
|
|
21
|
+
| 代理侧记录(同轮) | 最长一条连接存活 **86.4 秒**且**正常 Close**;整轮**无 `1006` 异常断开**;代答心跳累计 **274 次**。对照 0.3.6 基线:静默客户端 ~6 秒即被 `1006` 切断 |
|
|
22
|
+
|
|
23
|
+
### 同时
|
|
24
|
+
|
|
25
|
+
- `mobileCompat`(垫片)与 `socketWatchdog`(看门狗)**保持关闭**:`0.4.0` 曾让手机整页空白,在确认到具体成因前不默认开启。代理代答心跳 `answerHeartbeat` 保持开启(本次问题的另一处真修复,不碰页面)。
|
|
26
|
+
|
|
27
|
+
### 升级
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
dsh plugin --profile web add dsh-lan-guard@latest
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
重启一次 dsh 生效。
|
|
34
|
+
|
|
35
|
+
## [0.4.0] — 2026-09-28(手机长连接自愈:代理代答心跳 + 页面看门狗 + 兼容垫片)
|
|
36
|
+
|
|
37
|
+
### 修复 — 手机端「会话载入不全,甚至断开」
|
|
38
|
+
|
|
39
|
+
**症状**(2026-09-28 用户报告,附手机截图):手机上打开会话,界面、目标条、统计数字都在,唯独对话区永久停在「载入历史…」,并反复断开;同一网络下别的局域网入口却看不出来。
|
|
40
|
+
|
|
41
|
+
**定位(实测,不是推测)**:会话记录**只走 WebSocket**(`/api/remote.mux` 上的 `session/follow`),会话列表/goal/统计则来自 HTTP——所以症状的形状是「界面在、对话空」。
|
|
42
|
+
|
|
43
|
+
1. 宿主每 2 秒 Ping 一次,连续两次没被回应就 `terminate`(`websocketHeartbeatIntervalMs: 2000`、`MAX_MISSED_HEARTBEATS: 2`)。
|
|
44
|
+
2. 用真实 DSH 实测:客户端停止回 Pong 后 **6.0 秒**被切断,`close 1006`(连 Close 帧都没有),三处独立复现(直连 3081、经转发、浏览器冻结主线程各一次)。
|
|
45
|
+
3. 手机锁屏/切走时页面被系统挂起,回不了心跳;WebKit 另有一类已知问题:后台恢复后 `new WebSocket()` 永久停在 CONNECTING,而 HTTP 一切正常。
|
|
46
|
+
4. 缺现代 API 的引擎(`AbortSignal.any` 等)会在 DSH 的会话流里抛错,而 `Session.doOpen` 会把非传输类异常原样抛出——界面上就只剩「载入历史…」,**连报错都没有**。
|
|
47
|
+
|
|
48
|
+
**改动**(三层,默认全开、可逐项关闭):
|
|
49
|
+
|
|
50
|
+
- **`answerHeartbeat`(代理代答心跳)**:新增 `src/ws-heartbeat.ts`,在中转时只读地解析上游→浏览器方向的 WS 控制帧,遇到 Ping 立刻以客户端身份回一个掩码 Pong。RFC 6455 允许未经请求的 Pong,宿主只按「收到过 Pong」重置计数,手机自己回的重复包无害。**实测:停回心跳 6 秒被切断 → 代答后 20 秒以上存活。** 转发仍是纯字节管道,观察器最多只累积 14 字节头(Ping 再多 125 字节),异常即永久退出(fail-open)。
|
|
51
|
+
- **`socketWatchdog`(断线看门狗)**:服务端注入的页面补丁。卡在 CONNECTING 超过 8 秒的 socket 会被关掉;从后台回来 10 秒后仍一条都没连上时重载一次(每标签连续最多 3 次,冷却 20 秒起、成功连上即清零)。从未建过 socket 的页面永远不会被重载。
|
|
52
|
+
- **`mobileCompat`(移动端兼容垫片)**:补 `AbortSignal.any`/`AbortSignal.timeout`/`Promise.withResolvers`/`Iterator`,并把 viewport 换成带 `viewport-fit=cover` 的那一条、补 `apple-mobile-web-app-*` 与 `theme-color`。每个垫片都只在缺失时安装;**不禁用缩放**(本插件的移动端契约不是拿走用户的捏合手势)。
|
|
53
|
+
|
|
54
|
+
### 新增 — 「连接与证书 → 手机连接与自愈」+ 连接体检
|
|
55
|
+
|
|
56
|
+
- 三个开关的控件都在这里,每个都写明「为什么需要它」。
|
|
57
|
+
- **连接体检**在这个浏览器里跑:缺哪些 API、页面拿到了哪些补丁、对当前地址做一次真实 WebSocket 握手(12 秒超时会把「卡在 CONNECTING」单独报出来)。
|
|
58
|
+
- 代理侧计数:在活连接、累计升级、被拒次数、**代答心跳次数**,以及最近 12 条连接的时长、上下行字节、是否异常断开(无 Close 帧)。计数器是有界环形缓冲,不写日志文件。
|
|
59
|
+
|
|
60
|
+
### 验证
|
|
61
|
+
|
|
62
|
+
- 新增/更新用例,测试套件 **349 项**全绿(0.3.6 为 330)。
|
|
63
|
+
- 心跳代答有端到端用例:上游按 40ms 心跳、漏 2 次即 destroy —— **关掉代答必被回收、打开代答连接存活**。
|
|
64
|
+
- 注入的页面脚本在测试里被执行(假环境 + 假时钟):超时关 socket、有 OPEN 不重载、无 socket 不重载、后台恢复才重载一次并按冷却与上限退避、隐藏时不重载。
|
|
65
|
+
- 浏览器实测(Chrome 154,经临时回环转发走完整插件链路):WS 握手 3ms、首帧 2.1MB 单帧 43–110ms、12 秒 310 帧无中断;无代答的连接在页面冻结 12 秒后收到 `close 1006`。
|
|
66
|
+
- 真实 DSH 上的装机验证在发布后进行(本机运行的是已安装的 0.3.6,需重装 + 重启 dsh 才生效)。
|
|
67
|
+
|
|
68
|
+
### 升级
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
dsh plugin --profile web add dsh-lan-guard@latest
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## [0.3.6] — 2026-09-26(远程也能添加工作区:修掉让远程管理台永远锁定的代理缺陷)
|
|
75
|
+
|
|
76
|
+
### 新增 — 远程设备可以添加工作区(智能分流 + 页面内目录浏览器)
|
|
77
|
+
|
|
78
|
+
**症状**(2026-09-26 用户报告):在局域网另一台电脑(或手机)上点「添加工作区」,远程那侧没有任何反应,**对话框却开在运行 DSH 的电脑屏幕上**。
|
|
79
|
+
|
|
80
|
+
**根因**:DSH 的目录选择器在**进程启动时判定一次**(`dsh-host-directory-picker-auto`)。判定要求「仅回环绑定 + 非 SSH + 有显示器」,而 DSH 自身正是只绑回环,所以 macOS/Windows 上恒判为 `native`——对话框属于**宿主屏幕**,远程设备永远够不到。这个判定是进程级的,无法按客户端重算。
|
|
81
|
+
|
|
82
|
+
**改动**:不碰 DSH 的组合(钉死 `-browse` 会把本机操作者的系统对话框也一起拿走),而是在浏览器侧**遮蔽**官方目录流程占用者——`single` 槽位渲染最低优先级,且每个优先级只允许一个占用者,因此 `priority: -20` 能接管而不触发重复注册:
|
|
83
|
+
|
|
84
|
+
- **本机浏览器**(回环 hostname / Electron / 桌面 preload)仍走系统原生对话框;
|
|
85
|
+
- **远程设备**改用页面内目录浏览器:面包屑、快捷入口、目录列表、「使用此目录」,并可在弹层内**直接解锁管理台**,不必再去找设置页的锁定卡片。
|
|
86
|
+
|
|
87
|
+
选中的路径仍交回 DSH 官方工作区流程登记(`onPicked` → `workspaces.create`),插件**只读目录、不创建不修改任何文件**。
|
|
88
|
+
|
|
89
|
+
### 修复 — 代理双向丢弃插件自己的管理 cookie,`password_unlock` 对远程形同虚设
|
|
90
|
+
|
|
91
|
+
**症状**:在远程设备上把管理策略设为「密码解锁」并提示已保存,但远程设置页始终锁定、远程目录浏览恒返回 `403 admin_required`(用户描述为「添加工作区里仍然是空的」)。
|
|
92
|
+
|
|
93
|
+
**根因**:代理**双向**丢弃了本插件自己的管理会话 cookie —— 请求方向用注入的上游 cookie 整体替换 `Cookie` 头,响应方向丢弃全部 `set-cookie`。而校验 `isAdminUnlocked()` 的代码跑在 DSH 的 web server 上、只能经代理到达,于是解锁 POST 返回 200、下一个请求仍被判为锁定。
|
|
94
|
+
|
|
95
|
+
**改动**(`src/headers.ts`、`src/proxy.ts`):只放行本插件自己的 cookie 名(`dsh_lan_guard_admin`)。**DSH 自身的会话 cookie 依旧绝不外泄**,访客的门禁会话与设备身份 cookie 也依旧不到上游。这一处修复同时修好了整个远程管理面(设置写入、设备管理、解锁),不只是目录浏览。
|
|
96
|
+
|
|
97
|
+
### 修复 — 设置页一直没有「远程设备管理权限」控件
|
|
98
|
+
|
|
99
|
+
**根因**:`POLICY_CHOICES`(密码解锁 / 仅本机 / 不锁定)从写下那天起就是**死代码**,从未被渲染;`adminPolicy` 只能手改 profile patch,而它正是远程目录浏览能否工作的开关。
|
|
100
|
+
|
|
101
|
+
**改动**:安全认证 tab 补上「远程设备管理权限」与「管理操作需要先解锁」两个控件。另外,目录浏览路由的鉴权改为与其它管理写入完全一致(`adminProtection=false` 同样放行),避免「设置能改、目录却被拒」的矛盾。
|
|
102
|
+
|
|
103
|
+
### 修复 — 「已保存」横幅会把整页推下去
|
|
104
|
+
|
|
105
|
+
**症状**:任何一次保存都在页面顶部弹出一栏,长 tab 底部保存时页面像跳了一下,且看不出是否真的保存了。
|
|
106
|
+
|
|
107
|
+
**改动**:改为**右上角固定 toast** —— 不占布局、不引起位移;带图标、关闭按钮与倒计时条(条与定时器共用同一个 `TOAST_MS`,不会漂移)。同时修掉「2.6 秒内连续保存时,旧定时器把新提示提前掐掉」的问题。
|
|
108
|
+
|
|
109
|
+
### 修复 — 状态表面配色在深色与浅色下都不达标
|
|
110
|
+
|
|
111
|
+
**根因**(按 DSH 0.1.7 真实调色板实测):
|
|
112
|
+
|
|
113
|
+
- `--dsw-alias-state-business-primary` 当**正文颜色**时对比度只有浅色 **3.60:1** / 深色 **4.39:1**,低于 AA 正文的 4.5:1;
|
|
114
|
+
- `--dsw-alias-interactive-bg-hover-danger` 解析成 8 位 hex、alpha 仅 **0x0d(5%)**——它是 hover 染色,**不能当背景**,拿它当表面等于背景近乎透明。
|
|
115
|
+
|
|
116
|
+
**改动**:语义色只用于**图标与边框**(门槛 3:1),文字一律 `label-primary`(浅 16.04:1 / 深 9.79:1);danger 表面改为 `color-mix(error-primary 12%, bg-layer-1)`(浅 `#fde3e3` / 深 `#3c2a2a`),按仓库既有约定先写实心 token 兜底。**原有的 `.lg-bar.*` 与 `.lg-chip.wait` 有同样问题,一并修正。**
|
|
117
|
+
|
|
118
|
+
### 修复 — 目录弹层的面包屑与快捷入口两行被压扁重叠
|
|
119
|
+
|
|
120
|
+
**根因**:flex item 的**自动最小尺寸**在其 `overflow` 不是 `visible` 时解析为 **0**,而这两行都要横向滚动;列表又写了 `min-height`,于是内容超高时被压缩的只有这两行(实测被压到 9px / 11px,内容需要 24px / 27px,必然溢出重叠)。
|
|
121
|
+
|
|
122
|
+
**改动**:固定行显式 `flex:0 0 auto`,列表成为唯一可伸缩行(底部按钮永远不会被挤出),sheet 加 `overflow:hidden`,面包屑与快捷入口 chip 加 `white-space:nowrap`。
|
|
123
|
+
|
|
124
|
+
### 验证
|
|
125
|
+
|
|
126
|
+
- `pnpm run typecheck` ✓;`pnpm test` — **330 项全绿**(0.3.5 为 273 项,+57);
|
|
127
|
+
- **逐提交隔离验证**(在独立 worktree 里检出每个提交单独跑):`fix(proxy)` 278 项、`feat(picker)` 宿主半边 304 项、`feat(picker)` 浏览器半边 330 项,三个提交各自 typecheck 干净、测试全绿;
|
|
128
|
+
- 新增用例覆盖:代理 cookie 双向中转(含 gate cookie 不外泄的反证)、目录栅栏(敏感段 / 符号链接逃逸 / 截断 / 限流)、路由鉴权矩阵(本机 / 远程只读 / 需解锁 / 已解锁 / 栅栏拒绝)、slot 注册契约、错误码→可执行提示、CSS 布局不变量、设置页控件覆盖、toast 单一常量与定时器清理;
|
|
129
|
+
- **反证**(隔离回退后重跑):回退 cookie 中转 → round-trip 用例失败;回退 `flex:0 0 auto` → 布局不变量用例失败;把 hover 染色当背景 → 配色用例失败;
|
|
130
|
+
- 配色对比度用 DSH 真实 token 取值逐项计算,**浅色/深色 10/10 通过**;弹层布局在真实 Chrome 里量过尺寸(修复前 9px/11px → 修复后 30px/36px)。
|
|
131
|
+
|
|
132
|
+
### 升级
|
|
133
|
+
|
|
134
|
+
```sh
|
|
135
|
+
dsh plugin --profile web add dsh-lan-guard@latest
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
然后重启一次 DSH(宿主与客户端 bundle 都变了,刷新页面不够)。
|
|
139
|
+
|
|
3
140
|
## [0.3.5] — 2026-09-26(连接层可见性:明文请求 301 + 旧设备 cookie 不再锁死)
|
|
4
141
|
|
|
5
142
|
### 修复 — 用 `http://` 打开 TLS 端口时只看到「无法访问」,日志里也什么都没有
|
package/README.md
CHANGED
|
@@ -38,6 +38,7 @@ DSH serves its Web UI on `127.0.0.1` only, and it deliberately refuses to bind `
|
|
|
38
38
|
- **Your own machine is never locked** — direct `127.0.0.1` access is physically unlocked (whoever can use this computer could change these settings anyway). Remote access follows `adminPolicy`: read-only (default), password-unlocked, or open.
|
|
39
39
|
- **Device pairing and permanent blocking** — a phone names itself once when it first passes the gate, receives an HttpOnly device-identity cookie, and appears under **已授权设备** (name / created / last used / source IP) where you can **revoke and block** it. Blocking does not rely on device fingerprinting: re-pairing with the access password from another browser is refused too, and unblocking is the only way back.
|
|
40
40
|
- **Settings inside the official page** — the "局域网访问" section has four tabs: QR access, authentication, authorised devices, and connection & certificates. All typography and colours use the official design tokens; **no official layout is replaced**.
|
|
41
|
+
- **Adding a workspace from a phone (smart routing)** — DSH resolves its directory picker once at boot, and a loopback bind with a display resolves to `native`: tapping "添加工作区" on a phone actually opens the folder dialog **on the host's screen**. This plugin shadows the official pick flow from the browser half at a lower slot priority, so **the local browser keeps the OS dialog while a remote device gets an in-page directory browser** (breadcrumbs, shortcuts, directory list). The chosen path still goes through DSH's own workspace flow — this plugin only reads directories, never writes anything.
|
|
41
42
|
- **Configurable port and listen scope** — defaults to `3081` (DSH's port + 1) and walks up to ten ports when that one is taken, with an availability check in the settings page. The listen scope toggles between "LAN (default)" and "this machine only"; both need a DSH restart.
|
|
42
43
|
- **Optional mDNS** — off by default; advertises `_dsh-lan-guard._tcp` when enabled.
|
|
43
44
|
- **Update check** — the settings page shows "current version → latest on npm" with a copyable upgrade command. The plugin **never installs or restarts anything itself**.
|
|
@@ -81,7 +82,7 @@ Then **restart DSH once** and open **Settings → 局域网访问**. After that
|
|
|
81
82
|
|
|
82
83
|
## Settings
|
|
83
84
|
|
|
84
|
-
Everything lives under **Settings → 局域网访问**, in four tabs. The non-sensitive switches (`enabled`, `listenPort`, `listenHost`, `networkInterface`, `settingsUnlock`, `auth.mode`, `auth.adminPolicy`, `auth.adminProtection`, `auth.allowLoopback`, `auth.requirePairing`, `auth.requireApproval`) are editable directly; `listenPort` and `listenHost` take effect on the next DSH restart; `settingsUnlock`
|
|
85
|
+
Everything lives under **Settings → 局域网访问**, in four tabs. The non-sensitive switches (`enabled`, `listenPort`, `listenHost`, `networkInterface`, `settingsUnlock`, `answerHeartbeat`, `socketWatchdog`, `mobileCompat`, `auth.mode`, `auth.adminPolicy`, `auth.adminProtection`, `auth.allowLoopback`, `auth.requirePairing`, `auth.requireApproval`) are editable directly; `listenPort` and `listenHost` take effect on the next DSH restart; `settingsUnlock`, `socketWatchdog` and `mobileCompat` take effect on the next page load while `answerHeartbeat` also applies to connections that are already open; `dataDir` and `tls.*` are startup fields that need a profile-patch edit.
|
|
85
86
|
|
|
86
87
|
| Setting | Default | Effect |
|
|
87
88
|
| --- | --- | --- |
|
|
@@ -92,7 +93,13 @@ Everything lives under **Settings → 局域网访问**, in four tabs. The non-s
|
|
|
92
93
|
| Access password | unset | The login password for visitor devices. **While unset, the gate refuses every device.** |
|
|
93
94
|
| Admin password | unset | Unlocks this settings page's management console; falls back to the access password. |
|
|
94
95
|
| Loopback exempt | **on** | Direct `127.0.0.1` access skips the gate (physically unlocked). |
|
|
96
|
+
| Remote management rights | **this machine only** | Whether LAN devices may manage: "this machine only" is read-only; "password unlock" needs an unlock first; "not locked" adds no requirement. **Browsing directories and adding a workspace remotely needs one of the latter two.** |
|
|
97
|
+
| Management needs an unlock | **on** | Turned off, a remote session that satisfies the policy may change settings directly — except under "this machine only", which never allows remote management. |
|
|
95
98
|
| Official settings page on the LAN | **on** | DSH opens its official settings surface only to loopback pages, so a LAN device opening **Settings → Models** reports `settings are unavailable in this browser`. With this on, any device that passes the gate (phones included) can use those pages after a page refresh. It is a UI unlock, not a new privilege: the settings RPC is gated by the visitor gate either way, and DSH still redacts secret reads. Refresh the page to apply; no restart needed. |
|
|
99
|
+
| Answer the host heartbeat | **on** | DSH pings every WebSocket every 2 s and drops it after two unanswered pings (measured: 6 s). A suspended phone cannot answer, and the **session transcript** — the only part of the UI that rides that socket — then loads incompletely or disconnects. With this on the proxy answers instead; the phone's own Pong, when it arrives, is a harmless duplicate. Applies immediately, including to open connections. |
|
|
100
|
+
| Socket watchdog | **on** | Page patch: a WebSocket still in CONNECTING after 8 s is closed, and a page resumed with nothing open reloads itself once (at most three in a row per tab, backing off from 20 s). Only a page that genuinely cannot connect is affected. Applies on page refresh. |
|
|
101
|
+
| Mobile compatibility shims | **on** | Page patch: fills in `AbortSignal.any`/`AbortSignal.timeout`/`Promise.withResolvers`/`Iterator` and the mobile metas. Without those APIs DSH's client throws inside its session-stream path and the UI just sits on 「载入历史…」 with no error at all. On a modern engine every branch is a no-op. Applies on page refresh. |
|
|
102
|
+
| Narrow-screen scroll fix | **on** | DSH's own shell clips the conversation column on a phone (`pI_x6G_frame`, measured 844/1688) and the page cannot scroll, so content is visible but cannot be dragged. The patch only acts when narrow screen + mobile UA + page cannot scroll + a clipping overflowing layer exists; healthy pages are untouched. `?lgdiag=1` prints a layout report. Applies on page refresh. |
|
|
96
103
|
| Require naming | **on** | A new device must name itself once before it appears in the device list. |
|
|
97
104
|
| Require approval | off | When on, a named device still needs your **批准** before it is let in. |
|
|
98
105
|
| TLS | **self-signed HTTPS** | Turning it off sends the gate password in clear; a non-loopback bind with TLS off is **refused at startup** unless you set `tls.allowInsecureLan: true`. |
|
|
@@ -111,6 +118,9 @@ The plugin reads its config from its Cordis entry. **Every key has a usable defa
|
|
|
111
118
|
listenPort: 3081 # DSH port + 1; auto-walks up to 10 ports when taken
|
|
112
119
|
networkInterface: en0 # optional: publish on one NIC (empty = automatic)
|
|
113
120
|
settingsUnlock: true # LAN devices may use the official settings page (default on)
|
|
121
|
+
answerHeartbeat: true # proxy answers the WebSocket heartbeat (default on)
|
|
122
|
+
socketWatchdog: true # page-side socket watchdog (default on)
|
|
123
|
+
mobileCompat: true # mobile compatibility shims (default on)
|
|
114
124
|
dataDir: ~/.dsh/profiles/web/data/dsh-lan-guard # optional; this is the derived default
|
|
115
125
|
tls:
|
|
116
126
|
mode: self-signed # 'self-signed' (default) | 'provided' | 'off'
|
|
@@ -137,10 +147,12 @@ The plugin reads its config from its Cordis entry. **Every key has a usable defa
|
|
|
137
147
|
|
|
138
148
|
## Compatibility
|
|
139
149
|
|
|
140
|
-
Current version: plugin **`0.
|
|
150
|
+
Current version: plugin **`0.4.0`**; mobile long-connection self-healing — the proxy answers DSH's WebSocket heartbeat, and the served page carries a socket watchdog plus mobile compatibility shims (verified on DeepSeek Harness **`0.1.7-rc.2`**).
|
|
141
151
|
|
|
142
152
|
| Plugin | Verified DeepSeek Harness | What this version is |
|
|
143
153
|
| --- | --- | --- |
|
|
154
|
+
| **`0.4.0`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Mobile long-connection self-healing: the proxy answers DSH's WebSocket heartbeat (measured: 6 s reap without it, 20 s+ survival with it); page patches adding a socket watchdog and mobile compatibility shims; a connection health check and relay counters on the "connection" tab |
|
|
155
|
+
| **`0.3.6`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Adding a workspace from a remote device: the browser half shadows the official directory flow (the local browser keeps the OS dialog, a remote device gets an in-page browser and can unlock inside it); fixes the proxy dropping the plugin's admin cookie in both directions, which made `password_unlock` meaningless remotely; adds the missing "remote management rights" control; moves the "saved" confirmation to a top-right notification; reworks status-surface colours against measured contrast; fixes the picker's crushed breadcrumb/shortcut rows |
|
|
144
156
|
| **`0.3.5`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Connection-level visibility: an `http://` request to the TLS port goes from "blank page + no log" to a 301 onto `https` with a log line; a deleted device record no longer locks that browser out (revoked/blocked still refuse); the removal-page copy follows |
|
|
145
157
|
| **`0.3.4`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Official settings page on the LAN: a new `settingsUnlock` switch (on by default) that injects the host-surface marker into the index; applies on page refresh; a UI unlock, not a new privilege |
|
|
146
158
|
| **`0.3.3`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Gate UX fixes: the two first-visit steps are announced up front; an inert-link page can be logged into again; the blocking note now matches real behaviour (no host-facing change) |
|
|
@@ -154,6 +166,31 @@ Current version: plugin **`0.3.5`**; connection-level visibility and gate-recove
|
|
|
154
166
|
- Declared range `>=0.1.7-rc.1 <0.2.0` (`dsh.engines.dsh`); DSH versions not listed are **unverified** — verify them yourself before use.
|
|
155
167
|
- Host/client interfaces this plugin uses: `webServer.register` / `webServer.tapIndex` (indexTaps), `connection.requestRejection`, `connection.authenticatedUrl`, the additive `settings.section` seat, `@deepseek-ai/schemastery`, and `profileContext` (for deriving the default data directory).
|
|
156
168
|
- **Breaking default change (from `0.3.2`)**: `listenHost` now defaults to `0.0.0.0` instead of `127.0.0.1`, so one restart after install is enough; `0.3.1` and earlier default to loopback only. The gate and self-signed TLS defaults are unchanged (with no password the gate still refuses every device). See the [CHANGELOG](CHANGELOG.md).
|
|
169
|
+
- **`0.4.0` verification status**: all three changes carry measurements, not just specs.
|
|
170
|
+
1. **Proxy answers the heartbeat**: a Node client against the **real DSH** measured a **6.0 s** reap after it stopped sending Pongs (`close 1006`, no Close frame); with the answerer on the same link **survived 20 s** (10 pings answered). An end-to-end spec reproduces the pair against a DSH-shaped upstream (40 ms pings, destroy after two misses): **reaps without the answerer, survives with it**.
|
|
171
|
+
2. **Page patches**: the injected scripts are **executed** in the suite against a fake environment and clock — "a socket stuck in CONNECTING is closed after 8 s", "never reloads while one socket is OPEN", "never reloads a page that created no socket", "reloads once after a resume with nothing open, then backs off within the cooldown and cap", "never reloads while hidden".
|
|
172
|
+
3. **Browser verification** (BrowserSkill, Chrome 154, through a temporary loopback forward that still traverses the whole plugin path): `/api/remote.mux` handshake 3 ms; the `session/follow` snapshot arrives in 43–110 ms as a single 2.1 MB frame; 310 frames over 12 s with no interruption; and with the page's main thread frozen for 12 s a connection without the answerer received `close 1006`.
|
|
173
|
+
The suite is green at **349** specs (330 in 0.3.6). The real-DSH install verification follows the release (this machine runs the installed 0.3.6, so the code takes effect after a reinstall plus a DSH restart).
|
|
174
|
+
|
|
175
|
+
### Why a phone's session socket dies (measured 2026-09-28)
|
|
176
|
+
|
|
177
|
+
The session transcript — the 「载入历史…」 part of the UI — **rides the WebSocket only**; the session list, the goal chip and the statistics arrive over HTTP, which is why the failure looks like "everything is there except the conversation". Three facts define it:
|
|
178
|
+
|
|
179
|
+
| Fact | Source |
|
|
180
|
+
| --- | --- |
|
|
181
|
+
| The host pings every 2 s and drops a socket after two unanswered pings | `websocketHeartbeatIntervalMs: 2000`, `MAX_MISSED_HEARTBEATS: 2` |
|
|
182
|
+
| A client that stops sending Pongs is dropped after **6.0 s** (`close 1006`, no Close frame) | measured three ways: direct on 3081, through a forward, and with a frozen browser main thread |
|
|
183
|
+
| A phone that switches away or locks its screen cannot answer | iOS suspends the page; WebKit additionally has a case where `new WebSocket()` stays in CONNECTING forever after a resume while HTTP keeps working |
|
|
184
|
+
|
|
185
|
+
Three layers ship in this release, all on by default and each individually switchable:
|
|
186
|
+
|
|
187
|
+
1. **`answerHeartbeat`** — while relaying, the proxy reads the upstream→browser control frames and answers a Ping with a masked Pong on the client's behalf. RFC 6455 allows an unsolicited Pong and the host only resets its counter on "a Pong arrived", so the phone's own duplicate is harmless. This is the only layer that stops the host from reaping a suspended phone.
|
|
188
|
+
2. **`socketWatchdog`** — the page-side half: close a socket that is stuck in CONNECTING, and reload once when a resume leaves nothing open.
|
|
189
|
+
3. **`mobileCompat`** — `AbortSignal.any`/`timeout`, `Promise.withResolvers`, `Iterator` and the mobile metas. DSH's client calls `AbortSignal.any` on its session-stream path, and `Session.doOpen` re-throws non-transport errors, so a missing API shows up as a permanent 「载入历史…」 with no error text.
|
|
190
|
+
|
|
191
|
+
**Settings → 局域网访问 → 连接与证书 → 手机连接与自愈** carries a connection health check: it inspects which APIs this browser lacks, which patches the page received, runs a real WebSocket handshake against the current origin, and shows the proxy-side counters (open connections, upgrades, refusals, answered heartbeats) plus the last connection's duration, bytes and whether it died abnormally.
|
|
192
|
+
|
|
193
|
+
- **`0.3.6` verification status**: the change spans the host side (a new directory-listing route and cookie relaying) and the client side (the directory browser, the settings controls, the notification and the colour rework). The suite is green at **330** specs (+57); all three commits were verified in isolation in their own worktrees (278 / 304 / 330 each passing); it was falsified (reverting the cookie relay, the no-shrink rule, or the hover-tint surface each fails its specs); and contrast was computed from DSH's real token values, 10/10 passing in light and dark. The real-DSH install verification follows the release.
|
|
157
194
|
- **`0.3.5` verification status**: the changes touch only the proxy's connection-level handling and the gate's verdict; no host/client interface changed; the suite is green at **273** specs (+10) and was falsified (reverting a fix fails its specs); the real-DSH install verification follows the release.
|
|
158
195
|
- **`0.3.4` verification status**: the change adds one host-side switch, one index injection and a switch on the plugin's own settings page (`webServer.tapIndex` is a declared host interface); the suite is green at **263** specs; the injected script was exercised in a real Chrome over a non-loopback address in three states; the real-DSH install verification follows the release.
|
|
159
196
|
- **`0.3.3` verification status**: the changes touch only the plugin's own pages, copy and gate-form availability; no host/client interface changed; the suite is green at **247** specs; the real-DSH install verification follows the release.
|
|
@@ -164,6 +201,17 @@ The official UI is reused with zero modifications and adapts on a phone viewport
|
|
|
164
201
|
<img src="./assets/mobile.png" width="30%" alt="The official DSH UI at a 390px phone viewport: the plugin only proxies, the interface is the official one">
|
|
165
202
|
</p>
|
|
166
203
|
|
|
204
|
+
### Why a phone "cannot see all messages" / cannot scroll (measured 2026-09-28)
|
|
205
|
+
|
|
206
|
+
**Symptom**: on a phone the newest content is partly visible but the column cannot be dragged, while the fixed goal / quick-reply / composer floats cover the text.
|
|
207
|
+
|
|
208
|
+
**Root cause (measured on the device viewport)**: on narrow screens DSH's own shell keeps the conversation in `pI_x6G_frame` with `overflow:hidden` while the content is taller — measured `clientHeight=844 / scrollHeight=1688` — and the page as a whole cannot scroll either (`pageScrolls=false`). The content is clipped, so it is visible but not draggable. The same viewport scrolls fine in desktop Chrome, so this is an iOS/narrow-screen layout difference, **not the reverse proxy** (all DOM/CSS comes from the official shell and the installed plugins).
|
|
209
|
+
|
|
210
|
+
**Fix (`mobileScrollFix`, on by default)**: the injected script only acts when narrow screen AND mobile UA AND the page cannot scroll AND it actually finds a layer clipping overflowing content; it then makes exactly those layers touch-scrollable (`overflow-y:auto`, `-webkit-overflow-scrolling:touch`, `touch-action:pan-y`). Healthy pages are never touched.
|
|
211
|
+
|
|
212
|
+
**Self-check**: append `?lgdiag=1` to the page URL for an on-screen report (`narrow / mobile / innerHeight / visualViewport / pageScrolls / clippingLayers / patched`). That report is exactly the data that located this bug.
|
|
213
|
+
|
|
214
|
+
|
|
167
215
|
## Security boundary
|
|
168
216
|
|
|
169
217
|
- DSH's own listen address is never changed; the plugin modifies no DSH configuration, session data, or official UI.
|
|
@@ -173,6 +221,8 @@ The official UI is reused with zero modifications and adapts on a phone viewport
|
|
|
173
221
|
- Loopback access is **physically unlocked by design** — whoever can use this computer could change these settings anyway.
|
|
174
222
|
- **The official-settings-page unlock (`settingsUnlock`) is a UI compatibility patch, not a new transport privilege.** A proxied request is already rewritten to a loopback `host`, and DSH's settings RPC is gated only by the visitor gate (reads are redacted by DSH); the switch merely stops the official page from reporting "settings are unavailable in this browser". Turn it off to restore DSH's stock behaviour.
|
|
175
223
|
- The access password is **shared**: revoking a device invalidates that device's identity cookie immediately, but the same browser can re-pair with the password. Permanently blocking one machine would need device fingerprinting or per-device tokens, which this project deliberately avoids.
|
|
224
|
+
- **Exactly one cookie is relayed.** The proxy injects DSH's loopback session cookie and never passes an upstream `set-cookie` through — with one exception: this plugin's OWN admin session cookie (`dsh_lan_guard_admin`, HttpOnly, SameSite=Strict, 30 minutes by default). The plugin mints it and the plugin's route validates it, but that route runs on DSH's web server, so without the relay no remote device could ever unlock the console and `password_unlock` would be meaningless. The visitor's gate session and device identity still never reach DSH.
|
|
225
|
+
- **The remote directory browser is read-only and carries the management console's authority.** It lists directory names only (credential stores such as `.ssh`/`.aws`/`.env` and system directories are refused, symlinks are re-checked against their real target, one level is capped at 1,000 rows and rate-limited), and it **creates or modifies nothing** — DSH's own workspace flow performs the registration. The route reuses the management authentication: the machine's operator or an unlocked remote session, so under the default `local_only` a remote device gets `read_only_remote`.
|
|
176
226
|
- LAN only: no public tunnels, no IM bots, no port forwarding.
|
|
177
227
|
- The plugin **installs, restarts and pushes nothing**: you copy and run the upgrade command yourself.
|
|
178
228
|
|
|
@@ -190,6 +240,12 @@ The official UI is reused with zero modifications and adapts on a phone viewport
|
|
|
190
240
|
|
|
191
241
|
**"This device's access was removed" (403).** The device was revoked or blocked under **已授权设备**. Delete the record to let it pair again (a blocked device needs **解除拉黑** first).
|
|
192
242
|
|
|
243
|
+
**Tapping "添加工作区" remotely does nothing (or the dialog opens on the computer).** That is DSH's directory picker: it resolves once at boot, and a loopback bind with a display resolves to `native`, so the dialog opens **on the host's screen** where a remote device cannot see or reach it. This plugin takes it over with two interactions — the OS dialog locally, an in-page directory browser remotely.
|
|
244
|
+
|
|
245
|
+
If the sheet reports "**远程设备当前只读**", the policy is still "this machine only": open **设置 → 局域网访问 → 安全认证 → 远程设备管理权限** on the computer and pick "密码解锁" (or "不锁定"), then refresh the page on that device.
|
|
246
|
+
|
|
247
|
+
If it reports "**需要先解锁管理控制台**", just type the admin password into the sheet and press 解锁 — the list appears immediately, with no trip to the settings page.
|
|
248
|
+
|
|
193
249
|
**I forgot the access password.** On the machine that runs DSH, open `http://127.0.0.1:3080` (direct loopback access is physically unlocked) and set a new one. On a headless server, delete `secrets.json` in `dataDir` and set a new password — until then the gate refuses every device.
|
|
194
250
|
|
|
195
251
|
**Every device needs the password again after I changed it.** That is intentional: changing the access password or switching the auth mode **revokes every existing visitor session**.
|
package/README.zh.md
CHANGED
|
@@ -38,6 +38,7 @@ DSH 的 Web 界面只监听 `127.0.0.1`,而官方明确拒绝绑定 `0.0.0.0`
|
|
|
38
38
|
- **本机永不锁定**:直连 `127.0.0.1` 享有物理免锁特权(能用这台电脑的人本就能改这些设置);远程访问按 `adminPolicy` 处理——只读(默认)、需密码解锁、或不锁。
|
|
39
39
|
- **设备配对与永久拉黑**:手机首次通过门禁时自己命名一次,获得 HttpOnly 设备身份 cookie,出现在 **已授权设备** 里(名称 / 创建时间 / 最近使用 / 来源 IP),可逐个「吊销并拉黑」。拉黑不依赖设备指纹——换浏览器用密码重新配对也会被拒,「解除拉黑」是唯一的恢复方式。
|
|
40
40
|
- **设置挂在官方设置页内**:「局域网访问」分区含四个 tab——扫码访问、安全认证、已授权设备、连接与证书。排版与配色全部使用官方设计 token,**不替换任何官方布局**。
|
|
41
|
+
- **远程也能添加工作区(智能分流)**:DSH 的目录选择器在启动时判定一次,本机回环绑定 + 有显示器会判成「原生」——手机点「添加工作区」实际是在**电脑屏幕上**弹文件夹对话框。本插件在浏览器侧以更低优先级遮蔽官方选择流程:**本机浏览器照旧走系统原生对话框,远程设备改用页面内目录浏览器**(面包屑、快捷入口、目录列表)。选中后仍由 DSH 官方工作区流程登记,插件只读目录、不写任何东西。
|
|
41
42
|
- **端口与监听范围可配**:默认 `3081`(DSH 端口 + 1),被占用时自动往后顺延(最多试 10 个);设置页可改端口并带可用性检查,也可在「局域网(默认)/ 仅本机」之间切换(两者都需重启 dsh 生效)。
|
|
42
43
|
- **可选 mDNS**:默认关闭;开启后广播 `_dsh-lan-guard._tcp`。
|
|
43
44
|
- **升级检测**:设置页显示「当前版本 → npm 上最新版本」并给出可复制的升级命令;插件**不会自己安装或重启任何东西**。
|
|
@@ -81,7 +82,7 @@ dsh plugin --profile web add "link:$(pwd)"
|
|
|
81
82
|
|
|
82
83
|
## 设置
|
|
83
84
|
|
|
84
|
-
设置项集中在 **设置 → 局域网访问** 的四个 tab 里。非敏感开关(`enabled`、`listenPort`、`listenHost`、`networkInterface`、`settingsUnlock`、`auth.mode`、`auth.adminPolicy`、`auth.adminProtection`、`auth.allowLoopback`、`auth.requirePairing`、`auth.requireApproval`)可直接改;`listenPort` 与 `listenHost` 需重启 dsh 生效;`settingsUnlock`
|
|
85
|
+
设置项集中在 **设置 → 局域网访问** 的四个 tab 里。非敏感开关(`enabled`、`listenPort`、`listenHost`、`networkInterface`、`settingsUnlock`、`answerHeartbeat`、`socketWatchdog`、`mobileCompat`、`auth.mode`、`auth.adminPolicy`、`auth.adminProtection`、`auth.allowLoopback`、`auth.requirePairing`、`auth.requireApproval`)可直接改;`listenPort` 与 `listenHost` 需重启 dsh 生效;`settingsUnlock` / `socketWatchdog` / `mobileCompat` / `mobileScrollFix` 刷新页面即可生效,`answerHeartbeat` 立即对**已打开**的连接生效;`dataDir` 与 `tls.*` 属启动期字段,需在 profile patch 里改。
|
|
85
86
|
|
|
86
87
|
| 设置项 | 默认 | 作用 |
|
|
87
88
|
| --- | --- | --- |
|
|
@@ -92,7 +93,13 @@ dsh plugin --profile web add "link:$(pwd)"
|
|
|
92
93
|
| 访问密码 | 未设置 | 手机等访客设备的登录密码。**未设置时门禁拒绝所有设备**。 |
|
|
93
94
|
| 管理密码 | 未设置 | 解锁本设置页的管理台;未设置时退回访问密码。 |
|
|
94
95
|
| 本机回环访问免密 | **开** | `127.0.0.1` 直连跳过门禁(物理免锁)。 |
|
|
96
|
+
| 远程设备管理权限 | **仅本机** | 决定局域网设备能否管理:「仅本机」只读;「密码解锁」需先解锁;「不锁定」不额外要求。**远程浏览目录并添加工作区需要后两者之一**。 |
|
|
97
|
+
| 管理操作需要先解锁 | **开** | 关闭后,符合策略的远程会话可直接修改设置(`local_only` 除外,它永远只允许本机)。 |
|
|
95
98
|
| 局域网设备可用官方设置页 | **开** | DSH 官方设置面默认只对回环页面开放,局域网设备打开「设置 → 模型」会提示 `settings are unavailable in this browser`。开启后,通过门禁的设备(含手机)刷新页面即可使用官方设置页;这是界面解锁,不是新增权限——设置接口本来就只由门禁把关,读取密钥仍由 DSH 脱敏。刷新页面生效,无需重启。 |
|
|
99
|
+
| 代理代答心跳 | **开** | DSH 每 2 秒给每条 WebSocket 发心跳,连续两次没被回应就断开(实测 6 秒)。手机锁屏/切走时页面被系统挂起、回不了心跳,于是只走 WebSocket 的**会话记录**就会「载入不全、甚至断开」。开启后由代理替手机回心跳,手机自己回的那次是重复包,无副作用。立即生效(含已打开的连接)。 |
|
|
100
|
+
| 断线看门狗 | **开** | 页面补丁:卡在「连接中」超过 8 秒的 WebSocket 会被关掉;从后台回来 10 秒后仍一条都没连上时自动重载一次(每标签最多连续 3 次,冷却 20 秒起)。只对真的连不上的页面生效。刷新页面生效。 |
|
|
101
|
+
| 移动端兼容垫片 | **开** | 页面补丁:补 `AbortSignal.any`/`AbortSignal.timeout`/`Promise.withResolvers`/`Iterator` 与移动端 meta。缺这些 API 时 DSH 客户端在会话流里抛错,界面只会一直显示「载入历史…」且没有报错。现代浏览器上这些分支不生效。刷新页面生效。 |
|
|
102
|
+
| 手机滚动矫正(窄屏) | **开** | 手机端 DSH 外壳在窄屏下把对话列裁在 `overflow:hidden` 的层里(实测 844/1688),整页也不可滚 → 内容可见但**滑不动**。开启后只在「窄屏 + 移动端 + 整页不可滚 + 找到被裁剪溢出的层」四条同时成立时,把那几层改成可触摸滚动;正常页面不碰。页面加 `?lgdiag=1` 可看布局诊断。刷新页面生效。 |
|
|
96
103
|
| 新设备需要命名确认 | **开** | 新设备首次通过门禁时要自己命名一次,之后才出现在设备列表里。 |
|
|
97
104
|
| 新设备需要管理员批准 | 关 | 开启后,命名完还要你在设备列表点「批准」才能进入。 |
|
|
98
105
|
| TLS | **自签 HTTPS** | 关闭会明文传输门禁密码;非回环 + 关闭 TLS 必须显式设置 `tls.allowInsecureLan: true`,否则**拒绝启动**。 |
|
|
@@ -111,6 +118,9 @@ dsh plugin --profile web add "link:$(pwd)"
|
|
|
111
118
|
listenPort: 3081 # DSH 端口 + 1;被占用时自动顺延
|
|
112
119
|
networkInterface: en0 # 可选:只在一个网卡上公布(留空 = 自动)
|
|
113
120
|
settingsUnlock: true # 局域网设备可用官方设置页(默认开;关闭恢复 DSH 默认)
|
|
121
|
+
answerHeartbeat: true # 代理代答 WebSocket 心跳(默认开;手机挂起时不被宿主回收)
|
|
122
|
+
socketWatchdog: true # 页面断线看门狗(默认开)
|
|
123
|
+
mobileCompat: true # 移动端兼容垫片(默认开)
|
|
114
124
|
dataDir: ~/.dsh/profiles/web/data/dsh-lan-guard # 可选;缺省即用这个推导路径
|
|
115
125
|
tls:
|
|
116
126
|
mode: self-signed # 'self-signed'(默认)| 'provided' | 'off'
|
|
@@ -137,10 +147,12 @@ dsh plugin --profile web add "link:$(pwd)"
|
|
|
137
147
|
|
|
138
148
|
## 兼容性
|
|
139
149
|
|
|
140
|
-
当前版本:插件 **`0.3.
|
|
150
|
+
当前版本:插件 **`0.3.6`**;远程设备也能添加工作区 + 修掉让远程管理台永远锁定的代理缺陷(已在 DeepSeek Harness **`0.1.7-rc.2`** 上验证)。
|
|
141
151
|
|
|
142
152
|
| 插件 | 已验证的 DeepSeek Harness | 这个版本是什么 |
|
|
143
153
|
| --- | --- | --- |
|
|
154
|
+
| **`0.4.0`** | **`0.1.7-rc.2`**、`0.1.7-rc.1` | 手机长连接自愈:代理代答 DSH 的 WebSocket 心跳(实测把「停回心跳 6 秒被切断」变成「20 秒以上存活」);页面补丁加入断线看门狗与移动端兼容垫片;「连接与证书」新增连接体检与代理侧计数 |
|
|
155
|
+
| **`0.3.6`** | **`0.1.7-rc.2`**、`0.1.7-rc.1` | 远程也能添加工作区:浏览器侧遮蔽官方目录流程(本机仍走系统对话框,远程改用页面内目录浏览器,可在弹层内解锁);修掉代理双向丢弃插件管理 cookie 导致 `password_unlock` 对远程形同虚设;补上一直缺失的「远程设备管理权限」控件;「已保存」改为右上角提示;状态表面配色按实测重做;弹层两行被压扁重叠 |
|
|
144
156
|
| **`0.3.5`** | **`0.1.7-rc.2`**、`0.1.7-rc.1` | 连接层可见性:`http://` 访问 TLS 端口由「空白页 + 无日志」改为 301 跳 `https` 并记日志;删除设备记录后旧 cookie 不再把浏览器锁死(吊销/拉黑仍拒绝);移除页文案同步修正 |
|
|
145
157
|
| **`0.3.4`** | **`0.1.7-rc.2`**、`0.1.7-rc.1` | 局域网设备可用官方设置页:新增默认开启的 `settingsUnlock` 开关(index 注入宿主界面标记,刷新页面生效;界面解锁而非新增权限) |
|
|
146
158
|
| **`0.3.3`** | **`0.1.7-rc.2`**、`0.1.7-rc.1` | 门禁体验修复:首次访问的两道关提前说明;失效链接页恢复可登录;拉黑说明改为与实现一致(未触碰宿主接口) |
|
|
@@ -154,6 +166,31 @@ dsh plugin --profile web add "link:$(pwd)"
|
|
|
154
166
|
- 声明范围 `>=0.1.7-rc.1 <0.2.0`(`dsh.engines.dsh`);未列入的 DSH 版本属**未验证**,请自行验证后再使用。
|
|
155
167
|
- 本插件用到的宿主/客户端接口:`webServer.register` / `webServer.tapIndex`(indexTaps)、`connection.requestRejection`、`connection.authenticatedUrl`、追加型 `settings.section` seat、`@deepseek-ai/schemastery`,以及 `profileContext`(用于推导默认数据目录)。
|
|
156
168
|
- **破坏性默认值变更(`0.3.2` 起)**:`listenHost` 默认由 `127.0.0.1` 改为 `0.0.0.0`,装完重启一次即可用;`0.3.1` 及更早默认仅回环。门禁与自签 TLS 的默认值未变(未设密码仍拒绝所有设备)。详见 [CHANGELOG](CHANGELOG.md)。
|
|
169
|
+
- **`0.4.0` 的验证状态**:三处改动都做了实测,不只跑用例。
|
|
170
|
+
1. **代理代答心跳**:先用 Node 客户端对**真实 DSH** 测得「停止回 Pong 后 **6.0 秒**被切断,`close 1006`(无 Close 帧)」;再加上代答后同一条链路 **20 秒仍存活**(收到 10 次 Ping)。仓库里有一条端到端用例复现同一对行为(上游按 40ms 心跳、漏 2 次即 destroy):**关掉代答必被回收、打开代答连接存活**。
|
|
171
|
+
2. **页面补丁**:注入的脚本在测试里**被执行**(假环境 + 假时钟),断言「卡在 CONNECTING 8 秒被关掉」「有一条 OPEN 就不重载」「从未建过 socket 不重载」「后台回来无 OPEN 才重载一次、并按冷却与上限退避」「隐藏状态不重载」。
|
|
172
|
+
3. **浏览器实测**(BrowserSkill,Chrome 154,经临时回环转发走完整插件链路):`/api/remote.mux` 握手 3ms、`session/follow` 首帧 2.1MB 单帧 43–110ms、12 秒 310 帧无中断;同一页面把主线程冻结 12 秒时,无代答的连接收到 `close 1006`。
|
|
173
|
+
测试套件 **349 项**全绿(0.3.6 为 330)。真实 DSH 上的装机验证在发布后进行(本机运行的是已安装的 0.3.6,需重装 + 重启 dsh 才生效)。
|
|
174
|
+
|
|
175
|
+
### 手机长连接为什么会断(实测,2026-09-28)
|
|
176
|
+
|
|
177
|
+
会话记录(就是界面上的「载入历史…」那一段)**只走 WebSocket**:会话列表、目标条、统计数字都来自 HTTP,所以 WS 一断就会呈现「界面都在、对话区空白」的形状。三个事实决定了这个失效模式:
|
|
178
|
+
|
|
179
|
+
| 事实 | 实测/来源 |
|
|
180
|
+
| --- | --- |
|
|
181
|
+
| 宿主每 2 秒 Ping 一次,连续两次没被回应才回收 | `websocketHeartbeatIntervalMs: 2000`、`MAX_MISSED_HEARTBEATS: 2` |
|
|
182
|
+
| 停止回 Pong 后 **6.0 秒**被切断(`close 1006`,无 Close 帧),三处独立复现 | 直连 3081、经转发、浏览器冻结主线程 |
|
|
183
|
+
| 手机切走/锁屏时页面被系统挂起,回不了心跳 | iOS 行为;WebKit 另有「后台恢复后 `new WebSocket()` 永久卡 CONNECTING 而 HTTP 正常」的已知问题 |
|
|
184
|
+
|
|
185
|
+
因此本版本提供三层兜底,默认全开、可逐项关闭:
|
|
186
|
+
|
|
187
|
+
1. **代理代答心跳(`answerHeartbeat`)**:代理在中转时读取上游→浏览器方向的 WS 控制帧,遇到 Ping 立刻以客户端身份回一个掩码 Pong。RFC 6455 允许未经请求的 Pong,宿主只按「收到过 Pong」重置计数,所以手机自己回的重复包无害。这是唯一能阻止宿主回收挂起手机连接的一层。
|
|
188
|
+
2. **断线看门狗(`socketWatchdog`)**:页面侧兜住 WebKit 的「卡 CONNECTING」——超时关掉卡住的 socket,从后台回来仍连不上时限流重载一次。
|
|
189
|
+
3. **移动端兼容垫片(`mobileCompat`)**:补 `AbortSignal.any`/`timeout`、`Promise.withResolvers`、`Iterator` 与移动端 meta。DSH 客户端在会话流里直接调用 `AbortSignal.any`,而 `Session.doOpen` 会把**非传输类异常原样抛出**——缺 API 时的表现就是「永久载入历史…、连报错都没有」。
|
|
190
|
+
|
|
191
|
+
「连接与证书 → 手机连接与自愈」里有一个**连接体检**:它在这个浏览器里检查缺哪些 API、页面拿到了哪些补丁,并对当前地址做一次真实 WebSocket 握手,同时显示代理侧的计数(在活连接 / 累计升级 / 被拒 / 代答心跳次数)与最近一条连接的时长、上下行字节、是否异常断开。
|
|
192
|
+
|
|
193
|
+
- **`0.3.6` 的验证状态**:改动包含宿主侧(新增目录列举路由与 cookie 中转)与客户端(目录浏览器、设置页控件、提示层与配色)。测试套件 **330 项**全绿(+57);三个提交在独立 worktree 里逐提交验证(278 / 304 / 330 各自通过);并做过反证(回退 cookie 中转、固定行不收缩、hover 染当背景,各自让对应用例失败);配色对比度按 DSH 真实 token 逐项计算,浅色/深色 10/10 通过。真实 DSH 上的装机验证在发布后进行。
|
|
157
194
|
- **`0.3.5` 的验证状态**:改动只在代理的连接层处理与门禁判定,未改动任何宿主/客户端接口;测试套件 **273 项**全绿(+10),并做过反证(回退修复后对应用例失败);真实 DSH 上的装机验证在发布后进行。
|
|
158
195
|
- **`0.3.4` 的验证状态**:改动只新增一个宿主侧开关、一行 index 注入与插件自己的设置页开关(`webServer.tapIndex` 是已声明的宿主接口);测试套件 **263 项**全绿;注入脚本已在真实 Chrome + 非回环地址实测三种状态;真实 DSH 上的装机验证在发布后进行。
|
|
159
196
|
- **`0.3.3` 的验证状态**:改动只在插件自己的页面、文案与门禁表单可用性,未改动任何宿主/客户端接口;测试套件 **247 项**全绿;真实 DSH 上的装机验证在发布后进行。
|
|
@@ -164,6 +201,16 @@ dsh plugin --profile web add "link:$(pwd)"
|
|
|
164
201
|
<img src="./assets/mobile.png" width="30%" alt="390px 手机视口下的官方 DSH 界面:插件只做代理,界面由官方原样提供">
|
|
165
202
|
</p>
|
|
166
203
|
|
|
204
|
+
### 手机上为什么「看不到全部消息」/ 滑不动(实测,2026-09-28)
|
|
205
|
+
|
|
206
|
+
**症状**:手机上打开会话,最新内容能看到一部分,但**手指滑不动**;底部固定的「目标条 / 快捷回复 / 输入框」压住正文,右侧滚动条停在中途。
|
|
207
|
+
|
|
208
|
+
**根因(真机视口实测)**:DSH 官方外壳在**窄屏**下的根层 `pI_x6G_frame` 是 `overflow:hidden`,而内容高于它——实测 `clientHeight=844 / scrollHeight=1688`,同时**整页也不可滚**(`pageScrolls=false`)。内容被裁在容器里,所以"看得见、滑不动"。同一视口在桌面 Chrome 上正常,因此这是 iOS/窄屏的布局差异,**与反向代理无关**(DOM/CSS 全部来自官方 UI 与已装插件)。
|
|
209
|
+
|
|
210
|
+
**修复(`mobileScrollFix`,默认开)**:注入脚本**只在四条同时成立时**才动手——窄屏(≤1023px)、移动端 UA、**整页不可滚**、且**确实找到被裁剪且内容溢出的层**;然后只把那几层改成可触摸滚动(`overflow-y:auto`、`-webkit-overflow-scrolling:touch`、`touch-action:pan-y`)。能正常滚动的页面一律不碰。
|
|
211
|
+
|
|
212
|
+
**自检**:在页面地址后加 `?lgdiag=1`,顶部会出现一屏诊断(`narrow / mobile / innerHeight / visualViewport / pageScrolls / clippingLayers / 是否已修`)。这一屏就是本次定位所用的数据,以后复现同类问题不必连 Mac 调试。
|
|
213
|
+
|
|
167
214
|
## 安全边界
|
|
168
215
|
|
|
169
216
|
- DSH 自身的监听地址不被改动;本插件从不修改 DSH 配置、会话数据或官方 UI。
|
|
@@ -173,6 +220,8 @@ dsh plugin --profile web add "link:$(pwd)"
|
|
|
173
220
|
- 回环直连**按设计物理免锁**——能使用这台电脑的人本就能改这些设置。
|
|
174
221
|
- **官方设置页解锁(`settingsUnlock`)是界面层的兼容补丁,不是新的传输权限**:经代理的请求本就会被改写成回环 `host`,DSH 的设置接口只由门禁把关(读取被 DSH 脱敏),该开关只是让官方页面不再显示「settings are unavailable in this browser」。想恢复 DSH 原生行为,把开关关掉即可。
|
|
175
222
|
- 访问密码是**共享**的:吊销设备会立即让该设备的身份 cookie 失效,但换个浏览器用密码仍可重新配对。要「同一台机器永久拉黑」需要设备指纹或每设备独立令牌,本项目刻意不用指纹。
|
|
223
|
+
- **Cookie 中转只有一个例外**:代理注入 DSH 的回环会话 cookie,且**绝不**把上游的 `set-cookie` 透传给访客;唯一被中转的是**本插件自己的**管理会话 cookie(`dsh_lan_guard_admin`,HttpOnly、SameSite=Strict、默认 30 分钟)。它由本插件签发、也只由本插件的路由校验,但校验代码跑在 DSH 的 web server 上——不中转它,远程设备就永远无法解锁管理台(`password_unlock` 形同虚设)。访客的门禁会话与设备身份 cookie 依旧不会到达 DSH。
|
|
224
|
+
- **远程目录浏览器只读,且要管理台同等的权限**:它只列举目录名(凭据目录 `.ssh`/`.aws`/`.env` 等与系统目录一律拒绝,符号链接解析到真实路径后二次校验,单层上限 1000 行、带限流),**不创建、不修改任何文件**;登记工作区仍由 DSH 官方流程完成。该接口复用管理台鉴权——本机操作者或已解锁的远程会话可用,默认 `local_only` 下远程设备得到 `read_only_remote`。
|
|
176
225
|
- 只面向局域网:不做公网隧道、不做 IM Bot、不做端口转发。
|
|
177
226
|
- 插件自己**不安装、不重启、不推送**任何东西:升级命令由你复制执行。
|
|
178
227
|
|
|
@@ -190,6 +239,12 @@ dsh plugin --profile web add "link:$(pwd)"
|
|
|
190
239
|
|
|
191
240
|
**「此设备已被移除访问权限」(403)。** 该设备已在 **已授权设备** 中被吊销或拉黑。删除那条记录即可让它重新配对(被拉黑的需先「解除拉黑」)。
|
|
192
241
|
|
|
242
|
+
**远程点「添加工作区」没反应(或对话框开在电脑上)。** 这是 DSH 目录选择器的机制:它在启动时判定一次,本机回环绑定 + 有显示器 ⇒ 判成「原生」,对话框开在**电脑屏幕上**,远程设备看不到也点不到。本插件已把它接管为「本机走系统原生对话框 / 远程走页面内目录浏览器」两套交互。
|
|
243
|
+
|
|
244
|
+
若远程弹出「**远程设备当前只读**」,说明策略还是「仅本机」:去电脑的 **设置 → 局域网访问 → 安全认证 → 远程设备管理权限** 选「密码解锁」(或「不锁定」),然后在远程设备上刷新页面。
|
|
245
|
+
|
|
246
|
+
若弹出「**需要先解锁管理控制台**」,直接在弹层里输入管理密码(未设管理密码时用访问密码)点「解锁」,列表会立刻出现——不必再去找设置页的锁定卡片。
|
|
247
|
+
|
|
193
248
|
**我忘了访问密码。** 在运行 DSH 的电脑上直连 `http://127.0.0.1:3080`(本机直连物理免锁)重设。无头服务器则删除 `dataDir` 下的 `secrets.json` 后重设——在此之前门禁会拒绝所有设备。
|
|
194
249
|
|
|
195
250
|
**改过密码后所有设备都要重新输密码。** 这是有意的:更换访问密码或切换验证模式会**吊销所有已有访客会话**。
|