virlen-remote 0.4.0 → 0.6.1

package/src/transport/transfer-tier.ts

@@ -1,64 +1,64 @@
-/**
- * 传输档位 —— 「这条链路上，详细内容发不发」。
- *
- * ## 为什么要有这一层
- *
- * 「直连 / 中继」此前只影响**界面上一枚胶囊**（`link-kind.ts`）：用户看到「TURN 中继」，知道慢，
- * 但慢的代价其实落在手机上 —— 中继意味着**每一个字节都要经 TURN 服务器绕一圈**，而手机那头
- * 常常是蜂窝流量。手机上真正的大头也不是聊天正文，而是**工具输出**（`git diff` / 命令回显 /
- * 文件片段，单条动辄数 KB，一屏历史里几十条）。
- *
- * 于是把链路类型**再映射一层**成可执行的档位：
- *  - `full`（完整）：该发什么发什么；
- *  - `lean`（精简）：只发「主要内容」；详细内容（当前 = `role:'tool'` 的输出正文）由电脑端
- *    在**投影时**省略（`toMessageDTO`），并带上 `MessageDTO.detail = 'omitted'`，
- *    让手机端如实显示「输出已省略」，而不是骗人的「这次调用没有输出」。
- *
- * ## 口径为什么也必须只有一份
- *
- * 档位是**两端都会读**的：电脑端据此裁剪（发送侧 —— 唯一能真正省下流量的地方），
- * 手机端据此解释「工具输出为什么是空的」并在通讯面板上显示当前档位。两端口径一旦漂移，
- * 用户看到的就是自相矛盾（电脑按精简发、手机写着「完整传输」）—— 与 `link-kind.ts`
- * 当初收敛到本包是同一条理由：**这里即那份唯一实现。**
- *
- * ## 判定口径（用户 2026-10-02 拍板）
- *
- * - `direct`（P2P 直连）→ `full`：字节不经服务器，省它没有意义，信息完整优先；
- * - `relay`（TURN 中继）→ `lean`：字节要过服务器（手机流量 + 服务器带宽），砍详细内容；
- * - `unknown`（还没结论 / 非 WebRTC 链路）→ **也是 `lean`**：宁可把「其实一直是直连」的链路
- *   先按精简发，也不要在开局那一屏白白走完整档 —— 而开局那一屏恰好是全量最大的一笔
- *   （手机连上就拉最近一窗消息，里面全是历史工具输出）。
- *
- *   ⚠️ **代价如实记在这里**：`unknown` 是常态之一 —— 非 WebRTC 链路（同源 Broadcast 联调 /
- *   测试注入的链路）永远读不到候选对，于是永远按精简发；真机上也存在「其实是直连、但首个
- *   候选对还没定形」的几秒。这些情形下用户看到的是「工具输出已省略」而不是崩溃或空屏，
- *   重开会话（重拉窗口）或链路判定为直连之后新产生的数据都会是完整的。
- *   **不要**把「联调时工具输出是空的」当成 bug 去修。
- */
-import type { LinkKind } from './link-kind'
-
-/** 传输档位：`full` = 完整（含详细内容）；`lean` = 精简（只发主要内容）。 */
-export type TransferTier = 'full' | 'lean'
-
-/**
- * 两端都要声明/列出的**能力名**（手机端写进 `hello.capabilities`；电脑端写进 ACL 能力集）。
- *
- * 两端各表一半（能力协商本来就是「我会什么」的交集）：
- *  - 手机端声明它 = 「我能渲染 `MessageDTO.detail` 的省略标记」；
- *  - 电脑端列出它 = 「我会按档位裁剪正文，并在裁掉时打标记」。
- *
- * **为什么裁剪必须被它挡住，而不能无条件裁**：已部署的旧手机端不认 `detail` 字段 ——
- * 它的工具卡片会把「正文为空」显示成「这次调用没有输出」，而那是**假话**（工具有输出，
- * 只是被省略了）。宁可对旧手机端继续全量发送，也不要在它的界面上写一句不成立的结论；
- * 反过来，旧电脑端不认识这个能力名，新手机端也只是继续收完整正文，同样不会出问题。
- */
-export const MESSAGE_DETAIL_CAPABILITY = 'message.detail'
-
-/**
- * 链路类型 → 传输档位（**两端唯一口径**）。
- *
- * 纯函数：喂一个 `LinkKind` 即可，不碰 DOM、不碰 store，故可完整单测。
- */
-export function transferTierOf(kind: LinkKind): TransferTier {
-  return kind === 'direct' ? 'full' : 'lean'
-}
+/**
+ * 传输档位 —— 「这条链路上，详细内容发不发」。
+ *
+ * ## 为什么要有这一层
+ *
+ * 「直连 / 中继」此前只影响**界面上一枚胶囊**（`link-kind.ts`）：用户看到「TURN 中继」，知道慢，
+ * 但慢的代价其实落在手机上 —— 中继意味着**每一个字节都要经 TURN 服务器绕一圈**，而手机那头
+ * 常常是蜂窝流量。手机上真正的大头也不是聊天正文，而是**工具输出**（`git diff` / 命令回显 /
+ * 文件片段，单条动辄数 KB，一屏历史里几十条）。
+ *
+ * 于是把链路类型**再映射一层**成可执行的档位：
+ *  - `full`（完整）：该发什么发什么；
+ *  - `lean`（精简）：只发「主要内容」；详细内容（当前 = `role:'tool'` 的输出正文）由电脑端
+ *    在**投影时**省略（`toMessageDTO`），并带上 `MessageDTO.detail = 'omitted'`，
+ *    让手机端如实显示「输出已省略」，而不是骗人的「这次调用没有输出」。
+ *
+ * ## 口径为什么也必须只有一份
+ *
+ * 档位是**两端都会读**的：电脑端据此裁剪（发送侧 —— 唯一能真正省下流量的地方），
+ * 手机端据此解释「工具输出为什么是空的」并在通讯面板上显示当前档位。两端口径一旦漂移，
+ * 用户看到的就是自相矛盾（电脑按精简发、手机写着「完整传输」）—— 与 `link-kind.ts`
+ * 当初收敛到本包是同一条理由：**这里即那份唯一实现。**
+ *
+ * ## 判定口径（用户 2026-10-02 拍板）
+ *
+ * - `direct`（P2P 直连）→ `full`：字节不经服务器，省它没有意义，信息完整优先；
+ * - `relay`（TURN 中继）→ `lean`：字节要过服务器（手机流量 + 服务器带宽），砍详细内容；
+ * - `unknown`（还没结论 / 非 WebRTC 链路）→ **也是 `lean`**：宁可把「其实一直是直连」的链路
+ *   先按精简发，也不要在开局那一屏白白走完整档 —— 而开局那一屏恰好是全量最大的一笔
+ *   （手机连上就拉最近一窗消息，里面全是历史工具输出）。
+ *
+ *   ⚠️ **代价如实记在这里**：`unknown` 是常态之一 —— 非 WebRTC 链路（同源 Broadcast 联调 /
+ *   测试注入的链路）永远读不到候选对，于是永远按精简发；真机上也存在「其实是直连、但首个
+ *   候选对还没定形」的几秒。这些情形下用户看到的是「工具输出已省略」而不是崩溃或空屏，
+ *   重开会话（重拉窗口）或链路判定为直连之后新产生的数据都会是完整的。
+ *   **不要**把「联调时工具输出是空的」当成 bug 去修。
+ */
+import type { LinkKind } from './link-kind'
+
+/** 传输档位：`full` = 完整（含详细内容）；`lean` = 精简（只发主要内容）。 */
+export type TransferTier = 'full' | 'lean'
+
+/**
+ * 两端都要声明/列出的**能力名**（手机端写进 `hello.capabilities`；电脑端写进 ACL 能力集）。
+ *
+ * 两端各表一半（能力协商本来就是「我会什么」的交集）：
+ *  - 手机端声明它 = 「我能渲染 `MessageDTO.detail` 的省略标记」；
+ *  - 电脑端列出它 = 「我会按档位裁剪正文，并在裁掉时打标记」。
+ *
+ * **为什么裁剪必须被它挡住，而不能无条件裁**：已部署的旧手机端不认 `detail` 字段 ——
+ * 它的工具卡片会把「正文为空」显示成「这次调用没有输出」，而那是**假话**（工具有输出，
+ * 只是被省略了）。宁可对旧手机端继续全量发送，也不要在它的界面上写一句不成立的结论；
+ * 反过来，旧电脑端不认识这个能力名，新手机端也只是继续收完整正文，同样不会出问题。
+ */
+export const MESSAGE_DETAIL_CAPABILITY = 'message.detail'
+
+/**
+ * 链路类型 → 传输档位（**两端唯一口径**）。
+ *
+ * 纯函数：喂一个 `LinkKind` 即可，不碰 DOM、不碰 store，故可完整单测。
+ */
+export function transferTierOf(kind: LinkKind): TransferTier {
+  return kind === 'direct' ? 'full' : 'lean'
+}