dsh-mini-remote 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 本文件记录每个版本改了什么。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.2.2] - 2026-10-18
+
+发布后一天的收尾，只有一件事：**把「跨机窗口白屏」这个问题在源头拦住，并防它将来以别的方式再出现**。判断来自把它查到底的一次调研——那枚窗口会话 cookie 属于"第三方 cookie"，而浏览器正在收紧这一类。
+
+### 改了的
+
+- **配对时填 `http://` 会被当场拒绝**（本机回环地址除外）。原来它能配对、也能取票，用户一路顺利，直到点开那一行才看见白屏——因为进门要种的那枚 cookie 是 `SameSite=None; Secure`，浏览器在非 https 的地址上直接把它丢掉。现在在"填地址"这一步就说清，并说明原因。本机 `127.0.0.1` / `localhost` 仍可用 `http://`（浏览器把回环当可信来源），本机自测那条路不受影响。
+
+### 修了的
+
+- **手机端导航适配"整份失效"的真根因找到了：我们注入的样式被 HMR 清掉了。** 上一版把选择器改成 `[class*="_sidebarCol"]` 之后仍然不生效，于是换成**去浏览器里查**（无头 Edge + 390×844，加载前先挂 `MutationObserver`）：页面加载后约 **270 毫秒**，`@deepseek-ai/dsh-client-hmr` 会重建 `<head>`，把**不认识的 `<style>` 一律当旧的移除**——官方那几份随后会被它重新插回来，**我们这份不会**。所以服务端返回的 HTML 里明明有 `#mini-mirror-adapt`（位置、长度都对），浏览器里 `getElementById` 却是 null，整份适配一条规则都不生效。现在**别往 DOM 里放**了——用 `adoptedStyleSheets`：样式以 `CSSStyleSheet` 对象挂在 `document` 上，**根本不在 DOM 里**，HMR 重建 `<head>` 时删不到它。实测插入后侧栏 `overflow-y` 立刻变 `auto`，6 秒后再看（HMR 又重建过一轮、`<style>` 标签确实已被删）依然是 `auto`。老浏览器没有这个 API 时，退回"插 `<style>` + 有上限的轮询"。
+
+**这一天在这条路上踩了三次**，前后记下来：① `MutationObserver` 盯 `<head>`、回调里又插节点 → 和 HMR 互相触发**死循环、页面卡死**（用户报「进不去」）；② 改成节流轮询 → 手机布局下 HMR 比桌面活跃，补一次删一次，25 次耗尽后照样失效；③ `adoptedStyleSheets` → 绕开 DOM，一次成功。**教训：跟一个会重建 DOM 的东西抢 DOM，怎么抢都是输；换个不参与竞争的位置才对。**
+
+- **手机端侧栏滚不动、够不着「设置」、会话列表被挤没——修回来了。** 官方把侧栏那一列的标记 `data-pane="sidebar"` **整套去掉**了（8.9MB 的客户端包里已经一次都不出现），而"放开侧栏纵向滚动"那条规则还在、**但匹配不到任何元素**：规则没删、也不报错，静默失效。现在改按类名匹配 `[class*="_sidebarCol"]`（前缀是每次构建的随机哈希，只匹配稳定那半截）。症状和当初修它之前一模一样，原因却完全不同。
+
+- **窗口会话 cookie 加 `Partitioned` 的事：试过，撤回了。** 本来是想防"浏览器收紧第三方 cookie"（CHIPS）。但 DSH 桌面端那一层的顶层页面跑在自定义协议 `dsh-app://app/` 上——那**不是有效的分区上下文**，浏览器会把整枚 cookie 拒掉。真机症状：框里停在「Loading plugins…」（说明带票那次请求成功了、HTML 到了），之后子资源全过不去，20 秒后报「那台电脑的界面一直没打开」。撤掉后恢复正常。将来要再碰这一块，得先解决"分区键从哪来"。
+
+- **窗口凭据被浏览器拒收时，不再静默白屏。** 撤掉 `Partitioned` 之后，"阻止第三方 cookie"这个风险还在：那枚窗口会话 cookie 属于"第三方 cookie"，被拦掉时的表现是框里停在「Loading plugins…」——用户只会去怀疑网络或对面没开，而修法完全不同。现在两头都加了说明：服务端能认出"刚种下却没被带回来"（连两次才算数，排除竞态），在自检的「最近出错」里报一条并说清原因与修法；那一屏的兜底提示也把"浏览器拦了跨站凭据"列进可能原因，并提示去顶部横条点「再试一次」。
+
+### 文档
+
+- **开篇那段重写了。** 原来只讲移动端（"只保留你的输入和结论"），现在把 PC 端一起说清：移动端三种模式（单帧 / 聊天 / 完整）自己选屏蔽还是展开，PC 端则在多台设备上、用桌面端原生的界面操作核心设备上的 DSH。
+- **导航里加了「移动端使用」**，位置在「效果预览」和「远程窗口」之间——三个"看和用"的入口连在一起：先看效果、再看手机怎么用、然后是桌面端远程窗口，之后才是"装"。
+- 「移动端页面操作指引」补上**怎么拿到这个页面的地址**：那一页会列出这台电脑能用的每一条地址（本机 / 内网 / Tailscale / Tailscale（加密）/ 公网访问），每条左边是二维码、右边是完整网址，点一下网址框会自动全选。同时提醒：**这条网址里带着访问口令**，别外发。
+- 「必须 https」那句改准了：被浏览器丢掉的是**票换来的那枚 cookie**，不是票本身——票在 http 下照常能用，所以配对和取票都成。
+- 「远程窗口」与「移动端会话治理」两条特性描述改得更凝练；中英两版逐节拉平（28 对 28 节、每节行数比 1.00），顺手统一了几处中英混排的空格和 `DeepSeek Harness` 的写法。
+
+## [0.2.1] - 2026-10-17
+
+这一版跨了十天、46 笔改动，主体是**「远程窗口」真的能跨电脑了** —— 在另一台电脑的 DSH 桌面端里，打开这台电脑的界面。它前面压着一件必须先做的事：**多设备身份**（原来一个口令管所有设备，撤销一台等于全撤）。后面跟着一串"让它用起来不别扭"的修补，以及一件拖了很久的工程账：**这个仓库终于有 CI 了**。
+
+### 新加的
+
+- **跨电脑「远程窗口」。** 在 B 电脑的 DSH 桌面端里，打开 A 电脑的界面——不用切窗口、不用远程桌面。做法是"一次性票据过门"：A 发一张 30 秒、只能兑一次的票，B 的浏览器拿着它进门，进门那一刻换成窗口会话；**访问口令和长期凭据一个字节都不进浏览器**。跨站嵌入默认只许同源，带票那一次才放开。
+  - **地址怎么填**：填那台电脑「手机遥控」页里那条，**必须 https**（明文能配对、能取票，但框里是白的——通行凭据在非 https 的地址上会被浏览器丢掉，这是实测出来的）。推荐 Tailscale：地址固定，设一次就好。
+  - **A 侧有一个默认关的总开关「允许别的电脑连接」**。关着的时候，配对和取票两条路一条都不接——"关"是一个用户能读懂的整体状态。
+
+- **多设备身份。** 每台设备一枚自己的凭据，可以单独撤销（撤销是即时的，连已经开着的窗口下次请求也会 401）。**手机页的地址栏不再带着访问口令**——口令退回它本来的角色：入场邀请函，扫一次码就发一张凭据。
+  - 电脑端设置页多了设备列表：看得到谁连过、能改名、能撤销。
+
+- **自检。** 设置页最末多了一块，回答三个问题：**这台跑的是哪一版**、**哪些接口现在真的在**、**开关什么状态**。它还会说一句"进程比代码旧"——那是真机上真出过的事：桌面端连开一天，装是新版，跑的却是旧的。
+
+- **出错的时候，看得见了。** 原来错误只打在终端里，用户看着图形界面一个字也看不到；跨机那条路连状态都不留，退出面板就再也查不到。现在有一圈"最近 20 条错误"进自检，**进去之前先脱敏**（口令、飞书密钥、地址里的凭据参数、设备凭据形状，四类都换成 `***`）。
+
+- **电脑端界面的顶栏改成鼠标碰顶才滑出**，感应带从 6 像素加高到 16（原来几乎要精确放到那条线上）。
+
+### 改了的
+
+- **侧栏那枚「远程窗口」点开是「其他电脑」名单，不再显示本机界面。** 人坐在电脑前，为什么还要在面板里再看一遍自己的界面——"看本机"是跨机做不出来时的中间验证，跨机做完了它就退休了。底层那套取票、嵌框、过门的零件保留（跨机在复用）。
+- 手机侧栏的会话条目补齐了执行功能：重命名、置顶、归档、分叉。归档相关的两个按钮先藏起来（代码不删）。
+- 「完整」模式回答落定后，停在这一轮内容的开头，不再停在总结正文的开头。
+
+### 修了的
+
+- **远程窗口每约 25 秒整屏重载一次。** 根因是面板自己在定时换票（票一变，框的地址就变）。那个凭据本来就不会按时间过期——它只在 DSH 重启或对面撤销时失效——所以定时换票纯属多余，拆掉。
+- **取票请求没有超时。** 对面不回话时，那一屏会永远停在"正在向那台电脑换一张通行证…"。现在 15 秒上限（比宿主自己那条 8 秒长，不会把"慢但会成"的请求掐掉），超时给一句人话 + 「再试一次」。
+- **那个 20 秒兜底在框加载成功之后不取消**，会在加载好 19 秒后把正常界面换成"一直没打开"。现在框一加载好就掐钟。
+- **框没打开时自动重取一次票。** 上一版拆掉定时换票之后只剩人手动重试，而"第一次加载被拖过 30 秒"本来能救回来——补上这条约束：自动重取永远跟着一次人的动作，最多一次，不会变成每 20 秒自己转。
+- **「再点一下退出远程窗口」失效**：退出入口只挂在 16×16 的图标上，人点的是 252×36 那一行。改成整行都认。
+
+### 工程
+
+- **加了 CI（GitHub Actions）。** 两个 job：`gate` 在 Windows 上跑 Node 22 与 24（红了就是真红），`probe` 在 Linux 上跑一遍（允许红，但要看得见——它红一般是"某条测试只在 Windows 上成立"）。加载探针、活体检查、真机这三层仍然手跑：它们要活的 DSH，塞进 CI 只会长期红着然后没人看。
+- **版本号与 CHANGELOG 改成互证。** 原来测试里钉着一个字面量版本，发一次版要改三个地方，其中一个纯粹是为了让测试继续绿。现在断言"`package.json` 的 version 必须等于 CHANGELOG 最顶上那条"，忘一处必红。
+- **体量守门**：手机页不超过 8,700 行 / 480 KB，发布包不超过 3 MB（问 `npm pack` 要真实数字，不自己遍历目录）。
+- **发版清单入仓**（`docs/发版清单.md`）：七步，从改版本到 publish 之后的核对。
+- CI 首跑红了两次，抓到的都是**本机永远发现不了**的问题：一条测试要 `numpy` 而 skip 条件只探了 python；三条测试把时间钉死在 `+08:00`，而界面按本地时区显示（本机是 UTC+8 所以一直绿）。顺带记下一个能在本地预演 CI 的办法：`$env:TZ="UTC"` 之后再跑。
+
 ## [0.2.0] - 2026-10-08
 
 这一版跨了三天、50 笔改动，主体是**「进阶设置」——把电脑端那整套界面搬到手机上**，加上一颗「回到底部」的浮标，以及它俩连着带出来的一批手机端修补。