Initialize cross-platform workspace host scaffold

2026-09-29 11:30:51 +08:00
commit 4bc3552167
56 changed files with 2627 additions and 0 deletions
@@ -0,0 +1,39 @@
+# 连接与会话协议
+
+本文定义传输集成时应遵守的行为契约。当前共享核心实现控制权仲裁，消息编码和端点处于集成阶段。
+
+## 连接状态
+
+```text
+Authenticated → Authorized → Acquired → Attached
+                                ↑          ↓
+                             Reconnect ← Detached
+```
+
+host 工作区归属随创建建立，随显式结束释放。连接断开只改变附着状态。
+
+## 控制权
+
+- 首次授权连接取得控制权。
+- 同身份第二连接提交显式 takeover 请求后，原连接失效。
+- 其他身份得到 host 已被占用的响应。
+- 每次控制权获取生成新的连接 ID 和递增 generation。
+- 每个 broker 实例另有独立 epoch；IPC 集成使用 `(epoch, generation, connectionId)` 标识控制权。
+- WebSocket 关闭、心跳超时或授权失效时，按连接标识撤销控制权。
+
+`HostConnectionGate` 使用进程内不可伪造的 lease 对象。`TryDispatch` 在同一临界区中完成校验与同步入队，接管与输入接受存在确定顺序。接管完成后旧 lease 的输入、关闭与释放均被拒绝；接管前已接受的输入按队列顺序执行。真正传输集成应把控制消息与输入交由同一有序派发路径处理。
+
+## 消息职责
+
+| 消息 | 内容与行为 |
+| --- | --- |
+| Attach | 目标工作区、协议版本、显式接管意图 |
+| Input | 二进制终端输入，绑定已验证连接与控制权 |
+| Resize | 有界列数与行数，绑定当前控制权 |
+| Output | 二进制终端输出与递增序列号 |
+| Snapshot | 屏幕、光标、终端模式、历史边界和输出序列号 |
+| Heartbeat | 检测失效连接并触发释放 |
+| Detach | 结束传输，保留工作区 |
+| Terminate | 授权后结束工作区进程并释放归属 |
+
+终端数据按字节传输，控制消息使用独立类型。输入限制、输出缓冲上限、快照一致性和客户端尺寸变化由协议实现和测试固定。传输入口先完成认证授权，再允许升级及访问工作区。