dsh-plugin-mobile-gateway 0.7.1 → 0.7.3

package/docs/multi-gateway-todo.md

@@ -0,0 +1,137 @@
+# dsh-mobile 多网关支持待办
+
+## 目标与范围
+
+一个 dsh-mobile 客户端可以添加、保存并连接部署在云服务器或不同 PC 上的多个独立 Gateway。各网关拥有独立的凭证、连接状态和业务数据。
+
+第一阶段支持多网关管理与切换连接；第二阶段支持前台同时连接多个网关；第三阶段按需增加局域网自动发现。第一阶段无需中心服务器。
+
+2026-09-09：第一阶段 Gateway 插件 G1–G4 已实现并通过自动化回归，以下已完成项打勾。App 未修改，后续阶段及人工多机验收尚未完成。详见 [App 对接说明](multi-gateway-app-integration.md) 与 [验收报告及人工步骤](multi-gateway-phase1-acceptance.md)。
+
+## 实施前基础
+
+- 启动配置 `gatewayEnabled: true` 已支持常驻，不会启动无人连接自动关闭计时器。
+- 管理界面手动开启后，默认 5 分钟无人连接才自动关闭；成功连接后会清除计时器，后续断线不会重新计时。
+- 已有一次性配对码、长期设备 token、设备撤销和独立局域网 WebSocket 监听。
+- 已有 `control` / `conversation` 通道拆分，适合后续多网关并行连接。
+- 当前 `hello` 和配对载荷没有稳定的网关身份字段，局域网监听也不等于自动发现。
+
+## 第一阶段：网关插件待办
+
+### G1. 明确并持久化常驻模式
+
+- [x] 将运行模式明确为关闭、临时开启、常驻开启；管理界面显示当前模式。
+- [x] 常驻开启不启动无人连接关闭计时器；临时开启保留当前等待首次连接的超时行为。
+- [x] 持久化用户选择；优先级为已保存模式 > `gatewayMode` > 旧 `gatewayEnabled`。临时模式重启重新计时，自动关闭后保存关闭状态。
+- [x] 管理界面切换到常驻后，重启仍保持常驻；主动关闭后按约定保持关闭。
+- [x] 保留配对码有效期、请求超时和文件传输空闲超时，避免与网关运行模式混淆。
+- [x] 更新管理接口、界面文案、配置说明与部署说明，注明常驻依赖 DSH 进程运行及机器网络可达。
+
+### G2. 增加稳定网关身份
+
+- [x] 首次启动生成随机 `gatewayId` 并持久化，重启、升级、地址变化时保持不变。
+- [x] 支持可配置的 `gatewayName`，用于展示机器名称；App 可单独保存本地别名。
+- [x] 明确身份文件的保存位置（默认 `<deviceFile>.gateway.json`）、原子写入与损坏处理，避免损坏后静默生成新身份。
+- [x] 说明克隆部署时必须生成新的网关身份，避免多台机器复用同一 `gatewayId`。
+- [x] 在 `hello`、首次配对成功帧和本机管理状态中增加网关身份信息。
+- [x] 配对载荷携带 `gatewayId`、`gatewayName`，协议字段命名在实现前与 App 对齐。
+
+### G3. 支持同一网关的多个访问地址
+
+- [x] 定义可选的 `endpoints: string[]` 字段，在配对载荷及本机管理状态返回候选地址，并保留现有 `publicUrl` 兼容字段。
+- [x] 允许管理员配置并在配对时提供多个候选地址，不把监听地址 `0.0.0.0` 当作可连接地址。
+- [x] 多个地址指向同一网关时返回相同身份，控制和会话通道返回相同身份。
+- [x] 候选地址仅作为连接提示，不作为身份认证依据；地址变化不自动建立信任。
+
+### G4. 协议与兼容性
+
+- [x] 更新 `PROTOCOL.md`，给出网关身份、地址列表、常驻模式和配对示例。
+- [x] 优先采用可选字段扩展，保持已有请求与响应含义不变；验证旧 App 的解码行为后再决定是否升级配对载荷版本。
+- [x] 保持每个网关独立签发和撤销设备 token，禁止引入跨网关通用 token。
+- [x] 增加验证：身份持久化、常驻无客户端、临时模式超时、模式切换与重启、旧客户端兼容、双通道身份一致。
+
+## 第一阶段：App 待办
+
+### A1. 多网关资料与迁移
+
+- [ ] 建立 `GatewayProfile`：本地记录 ID、远端 `gatewayId`（旧网关允许缺失）、名称、本地别名、候选地址、凭证引用、最近连接时间。
+- [ ] 将现有单网关配置迁移为默认网关，保留原凭证与用户数据；迁移可重复执行且不产生重复记录。
+- [ ] 按网关隔离安全存储中的 token 和服务端返回的 device ID；客户端安装级设备 ID 可继续复用，不能代替鉴权凭证。
+- [ ] 支持添加、重命名、排序、删除网关和选择默认网关。
+- [ ] 再次扫描同一网关时更新已有记录；若重新配对导致 token 轮换，替换凭证并重建该网关连接。
+- [ ] 区分本地删除与服务端撤销授权；本地删除不宣称已撤销服务端设备权限。
+
+### A2. 连接管理与恢复
+
+- [ ] 将单一连接管理改为按网关创建连接上下文，包含控制通道、会话通道、请求等待队列和重连任务。
+- [ ] 第一阶段只保持当前网关的业务连接；切换时取消旧订阅与等待请求，并阻止旧回调污染新页面。
+- [ ] 每个网关独立维护未连接、连接中、在线、离线、需要重新配对等状态。
+- [ ] 连接后核对已保存的网关身份；身份不匹配时停止业务操作并提示重新确认，不能自动覆盖原记录。
+- [ ] 新发现或未经确认的地址不直接携带已有 token 探测；制定候选地址信任规则，保留 TLS 校验。
+- [ ] 支持网络恢复后的退避重连与候选地址切换；鉴权失败进入重新配对流程，避免无限重试。
+- [ ] 定义旧网关兼容行为：缺少 `gatewayId` 时使用本地记录 ID 隔离，升级后经可信连接绑定远端身份，不能仅凭名称合并。
+
+### A3. 业务数据隔离
+
+- [ ] 会话、工作区、任务、Goal、文件缓存等使用 `(本地网关记录 ID, resourceId)` 作为客户端存储与索引范围。
+- [ ] 所有发送、审批、停止、重命名、归档和文件操作显式携带所属网关上下文。
+- [ ] 页面、订阅、异步回调和待处理请求绑定网关及连接代次，丢弃过期连接的响应。
+- [ ] 切换网关后加载对应配置、模型与能力列表，不复用其他网关的能力判断。
+- [ ] 连接中断后不自动重发发送消息、审批等写操作；结果不确定时先查询状态，避免重复执行。
+- [ ] 明确删除网关时本地缓存、下载文件与会话草稿的处理规则，并在界面说明。
+
+### A4. 界面与验证
+
+- [ ] 增加网关列表或切换入口，展示名称、连接状态、当前网关及重新配对入口。
+- [ ] 扫码添加新网关不覆盖已有网关；已存在时明确提示更新。
+- [ ] 会话和审批页面显示所属网关，避免用户向错误机器发送操作。
+- [ ] 增加验证：旧配置迁移、重复配对、切换期间事件到达、跨网关同名同 ID 资源、凭证隔离、撤销后重连、地址与身份不匹配。
+
+## 第二阶段：前台同时连接多个网关
+
+### 网关插件
+
+- [ ] 验证仅连接控制通道时的状态同步，以及对审批/提问认领和释放行为的影响。
+- [ ] 验证会话通道按需建立、断开及重建不会影响其他设备或控制通道。
+- [ ] 明确重连后的状态快照与待处理交互恢复约定，有缺口时补充协议或实现。
+
+### App
+
+- [ ] 前台为用户启用的多个网关维护控制通道，进入会话时按需连接对应会话通道。
+- [ ] 单个网关连接失败不阻塞其他网关初始化、列表加载或操作。
+- [ ] 如增加聚合任务/会话页面，每项保留来源标识，点击后路由至所属网关。
+- [ ] 限制并发连接与重连频率，处理进入后台、返回前台和网络切换后的状态恢复。
+- [ ] 不将后台常驻 WebSocket 作为可靠通知方案；若需要后台审批通知，另立推送方案待办。
+
+## 第三阶段：局域网自动发现（可选）
+
+### 网关插件
+
+- [ ] 增加可选的 mDNS / DNS-SD 广播，约定服务类型、网关 ID、名称、端口、路径与协议版本。
+- [ ] 广播中不包含 token 或配对码；服务关闭时停止广播。
+- [ ] 处理多网卡、地址变化与广播生命周期。
+
+### App
+
+- [ ] 实现局域网服务浏览及相应平台权限流程，提供拒绝权限后的扫码/手动添加入口。
+- [ ] 展示“发现但未配对”的网关，发现结果仍需完成配对才能访问业务数据。
+- [ ] 对发现结果去重；广播身份仅用于提示，不据此自动更新可信地址或发送凭证。
+
+跨互联网自动发现不属于本阶段。如果后续需要登录账号后自动列出所有机器，再设计设备目录、登记鉴权、心跳和访问网络方案；目录服务本身不能解决网络不可达问题。
+
+## 实施顺序与验收
+
+1. 先对齐身份字段、地址信任规则与兼容策略，再并行开展网关和 App 实现。
+2. 完成 G1–G4 与 A1–A4，交付可保存多个网关并可靠切换的版本。
+3. 再实施前台并行连接，最后按需求增加自动发现。
+
+第一阶段验收清单：
+
+- [ ] 同一 App 添加一台服务器和两台 PC，资料及凭证在重启后保留。
+- [ ] 三个网关均可常驻，长时间无客户端后仍能连接；网关重启后身份不变。
+- [ ] 任意切换网关，会话、工作区、模型配置、审批及文件不会串用。
+- [ ] 两个网关返回相同资源 ID 时，缓存和操作仍正确隔离。
+- [ ] 一台机器离线或凭证被撤销，不影响其他网关。
+- [ ] 同一网关更换已确认的访问地址后可恢复连接；不同身份的端点不会被误绑定。
+- [ ] 旧 App 连接新插件、旧单网关配置迁移到新 App 均通过兼容性验证。
+- [ ] 网关插件现有测试与新增行为测试通过，App 完成对应自动化验证及多机联调。

package/docs/runtime-architecture.architecture.json

@@ -0,0 +1,264 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "DSH Mobile Gateway 运行时架构",
+    "subtitle": "移动 App 经网关访问 DSH Host，并接收会话、控制与工作区的实时状态",
+    "locale": "zh-CN",
+    "output": "runtime-architecture.html",
+    "quality_profile": "showcase",
+    "visual_preset": "signal-flow",
+    "viewBox": [1300, 700],
+    "views": [
+      {
+        "id": "request-path",
+        "label": "请求主链路",
+        "focus": ["mobileApp", "gatewayIngress", "protocolAdapter", "typertGateway", "dshRuntime"],
+        "note": "查看移动请求从 WebSocket 接入到 DSH Runtime 的完整调用链。"
+      },
+      {
+        "id": "realtime-path",
+        "label": "实时状态链路",
+        "focus": ["dshRuntime", "streamBridge", "gatewayIngress", "mobileApp"],
+        "note": "查看会话事件、运行状态与工作区变化如何增量推送回 App。"
+      },
+      {
+        "id": "security-data",
+        "label": "安全与数据",
+        "focus": ["deviceRegistry", "gatewayIngress", "fileTransfer", "durableState"],
+        "note": "查看设备鉴权、Token 摘要、附件和 Host 持久化边界。"
+      }
+    ]
+  },
+  "layout": {
+    "mode": "grid",
+    "origin": [40, 80],
+    "cols": 5,
+    "gapX": 70,
+    "gapY": 120,
+    "cellW": 180,
+    "cellH": 76
+  },
+  "components": [
+    {
+      "id": "mobileApp",
+      "type": "frontend",
+      "label": "移动端 App",
+      "sublabel": "控制通道 + 会话通道",
+      "pos": [40, 330],
+      "size": [150, 76]
+    },
+    {
+      "id": "dshWebUi",
+      "type": "frontend",
+      "label": "DSH WebUI",
+      "sublabel": "同进程管理界面",
+      "pos": [40, 80],
+      "size": [150, 76]
+    },
+    {
+      "id": "gatewayIngress",
+      "type": "cloud",
+      "label": "网关接入",
+      "sublabel": "WSS / LAN · /ws/mobile",
+      "tag": "Nginx 可选",
+      "pos": [250, 330],
+      "size": [180, 76]
+    },
+    {
+      "id": "deviceRegistry",
+      "type": "security",
+      "label": "设备认证",
+      "sublabel": "配对码 · Token 摘要",
+      "pos": [250, 80],
+      "size": [180, 76]
+    },
+    {
+      "id": "protocolAdapter",
+      "type": "backend",
+      "label": "协议路由与适配",
+      "sublabel": "控制 / 会话 → Host 调用",
+      "pos": [500, 330],
+      "size": [180, 76]
+    },
+    {
+      "id": "fileTransfer",
+      "type": "backend",
+      "label": "附件传输",
+      "sublabel": "上传 · 下载 · 工作区文件",
+      "pos": [250, 500],
+      "size": [180, 76]
+    },
+    {
+      "id": "streamBridge",
+      "type": "messagebus",
+      "label": "实时状态桥",
+      "sublabel": "SessionEvent · control · workspace",
+      "pos": [500, 500],
+      "size": [180, 76]
+    },
+    {
+      "id": "typertGateway",
+      "type": "backend",
+      "label": "Remote Gateway",
+      "sublabel": "invoke / stream",
+      "pos": [750, 330],
+      "size": [180, 76]
+    },
+    {
+      "id": "dshRuntime",
+      "type": "backend",
+      "label": "DSH Runtime",
+      "sublabel": "Session · Workspace · HITL",
+      "pos": [1000, 330],
+      "size": [180, 76]
+    },
+    {
+      "id": "durableState",
+      "type": "database",
+      "label": "本地持久化",
+      "sublabel": "设备 · 附件 · Session 历史",
+      "pos": [1000, 500],
+      "size": [180, 76]
+    }
+  ],
+  "boundaries": [
+    {
+      "kind": "region",
+      "label": "客户端",
+      "wraps": ["mobileApp", "dshWebUi"],
+      "pad": 24
+    },
+    {
+      "kind": "region",
+      "label": "Mobile Gateway 插件进程",
+      "wraps": ["gatewayIngress", "deviceRegistry", "protocolAdapter", "fileTransfer", "streamBridge"],
+      "pad": 28
+    },
+    {
+      "kind": "region",
+      "label": "DSH Host",
+      "wraps": ["typertGateway", "dshRuntime", "durableState"],
+      "pad": 28
+    }
+  ],
+  "connections": [
+    {
+      "id": "mobileTransport",
+      "from": "mobileApp",
+      "to": "gatewayIngress",
+      "label": "WS / WSS",
+      "variant": "emphasis",
+      "fromSide": "right",
+      "toSide": "left",
+      "labelAt": [220, 352]
+    },
+    {
+      "id": "webUiManagement",
+      "from": "dshWebUi",
+      "to": "gatewayIngress",
+      "label": "管理 API",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "via": [[115, 230], [340, 230]]
+    },
+    {
+      "id": "deviceAuth",
+      "from": "deviceRegistry",
+      "to": "gatewayIngress",
+      "label": "鉴权",
+      "variant": "security",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelAt": [340, 170]
+    },
+    {
+      "id": "protocolFrames",
+      "from": "gatewayIngress",
+      "to": "protocolAdapter",
+      "variant": "emphasis",
+      "fromSide": "right",
+      "toSide": "left"
+    },
+    {
+      "id": "hostCalls",
+      "from": "protocolAdapter",
+      "to": "typertGateway",
+      "variant": "emphasis",
+      "fromSide": "right",
+      "toSide": "left"
+    },
+    {
+      "id": "remoteContract",
+      "from": "typertGateway",
+      "to": "dshRuntime",
+      "variant": "emphasis",
+      "fromSide": "right",
+      "toSide": "left"
+    },
+    {
+      "id": "persistHostState",
+      "from": "dshRuntime",
+      "to": "durableState",
+      "label": "历史 / 工作区",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelAt": [1090, 430]
+    },
+    {
+      "id": "emitRuntimeState",
+      "from": "dshRuntime",
+      "to": "streamBridge",
+      "label": "事件 / 状态",
+      "variant": "dashed",
+      "fromSide": "left",
+      "toSide": "right",
+      "via": [[950, 368], [950, 538]]
+    },
+    {
+      "id": "pushMobileState",
+      "from": "streamBridge",
+      "to": "gatewayIngress",
+      "label": "增量推送",
+      "variant": "dashed",
+      "fromSide": "top",
+      "toSide": "bottom",
+      "via": [[590, 455], [340, 455]]
+    },
+    {
+      "id": "readWorkspace",
+      "from": "fileTransfer",
+      "to": "durableState",
+      "label": "文件 I/O",
+      "fromSide": "bottom",
+      "toSide": "bottom",
+      "via": [[340, 650], [1090, 650]]
+    }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "请求路径",
+      "items": [
+        "App 经 WSS 或局域网接入",
+        "网关鉴权、分流并调用 Host"
+      ]
+    },
+    {
+      "dot": "emerald",
+      "title": "实时路径",
+      "items": [
+        "订阅 SessionEvent 与控制状态",
+        "按连接向 App 增量推送"
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "安全与数据",
+      "items": [
+        "设备 Token 仅持久化摘要",
+        "附件与 Session 历史分层管理"
+      ]
+    }
+  ]
+}