dsh-plugin-mobile-gateway

dsh plugin --profile web add dsh-plugin-mobile-gateway

[English](README.md) · 简体中文 · [日本語](docs/readme/README.ja.md) · [한국어](docs/readme/README.ko.md) · [Español](docs/readme/README.es.md) · [Français](docs/readme/README.fr.md) · [Deutsch](docs/readme/README.de.md) · [Português (Brasil)](docs/readme/README.pt-BR.md)

部分深入协议与接入文档目前仅提供中文。

<p align="center">

<img src="docs/assets/whale-girl-ios-app-promo-16x9.png" alt="DeepSeek Harness Mobile 与移动网关" width="100%">

</p>

dsh-plugin-mobile-gateway

当前源码增加实验性 P2P 优先 传输：开启 webrtc.enabled 后，支持该能力的新客户端通过现有鉴权 WebSocket 协商双 WebRTC DataChannel，准备失败整组回退 WebSocket。首次使用默认“局域网直连”，通过同一 Wi-Fi 下的主机地址使用 WebSocket；可在“连接与配对 → 连接方案”主动选择“公网入口 + 优先 P2P（实验）”或其他方案，已保存的选择会保留；旧客户端保持原行为。网关可联调，Android/iOS App 待接入，尚未发布。详见 [App 接入契约](docs/webrtc-app-integration.md)、[运行库决策](docs/webrtc-runtime-decision.md) 和 [验收记录](docs/webrtc-acceptance.md)。

DeepSeek Harness 的第三方设备鉴权移动网关，支持会话与实时事件、排队消息同步及编辑/删除/Steer、Session 归档和重命名的双向同步、停止当前生成并稍后继续、任务列表和当前 Goal 同步及管理、服务端驱动的命令和技能菜单、Human-in-the-loop、图片及文件传输。安装后，Harness WebUI 左侧边栏会出现“移动设备”入口，可直接开启网关、生成配对二维码和管理可信设备。

当前源码以 DSH 0.2.1-rc.2 为适配基线，需要 Connection Peer 接口，使用 Session format 4；旧版历史游标需重新取得基线。

实时流已改为独立 assistant-stream 帧，移动端需要按 [rc.2 接入说明](docs/dsh-rc2-mobile-integration.md) 更新订阅、缓存与分页处理。当前修改尚未发布。

v0.11.1（当前源码，尚未发布）：新增普通文件分块上传，支持 SHA-256 校验、进度确认、取消与断线清理，复用 DSH 官方附件存储和会话专属凭证，支持文件随消息发送及实时和历史文件引用。App 需按 file-upload-v1 能力接入，详见 [移动端普通文件上传对接指南](docs/file-upload-app-integration.md)。

v0.11.0：新增智能体团队与子会话协议，支持团队成员、共享任务看板、多层子智能体目录和运行状态实时同步，以及子智能体独立历史、视图切换、继续对话、图片输入与停止执行。APP 需按能力发现接入，详见 [智能体团队 APP 详细接入指南](docs/agent-team-app-integration.md)。

v0.10.4：精简会话列表投影，仅保留标题与投影切点，修复大量会话通过公网隧道传输时超时的问题；保留会话元信息和历史完整投影，现有移动客户端无需配套修改。

v0.10.3：适配 DSH 0.2.1-rc.2，为 Remote 请求及实时订阅补齐 Connection Peer，修复 Cannot read properties of undefined (reading 'signal') 报错，并在网关停止时释放 Peer。移动端协议保持不变。

v0.10.2：新增文件卡片事件透传与安全文件引用解析，复用现有分块下载，为移动端文件卡片和正文文件链接预览提供协议支持。App 接入方式见 [文件卡片与预览接入说明](docs/file-cards-mobile-integration.md)。

v0.10.1：新增官方语音输入接入，支持语音模型准备与状态同步、移动端音频转文字、取消转写及连接关闭后的任务清理。通过官方 speech Remote 处理识别，移动网关无需打包 ASR 模型。

v0.10.0：移动设备面板改为响应式居中设置窗口，跟随主应用深浅色主题；统一自定义下拉菜单与连接状态高亮；配对二维码使用独立模态窗口并支持缩放进出动画；安装重启提醒可按网关运行实例关闭；可信设备默认仅显示在线设备，支持展开离线设备、移动端名称上报与同名编号；Tunnel 切换自动应用，命名配置编辑后保存。

v0.9.0：新增 DSH 0.2.0-rc.2 插件管理能力；PC 端可在面板开启、重启 Cloudflare Quick / 命名 Tunnel，使用插件私有缓存中的 cloudflared 并校验文件；配对面板增加局域网与外网入口选择指引；工具菜单可重启网关或停止 DSH Web，重启时不再打开新标签页。

v0.7.3：优化移动网关运行模式下拉框的箭头间距。

v0.7.2：新增独立对话/控制连接、空 Session 创建、停止生成与稍后继续、排队消息同步及编辑/删除/Steer，以及 Session 归档和重命名的双向同步。

协议与 DSH 兼容层

移动端连接的是本项目维护的 dsh-mobile-v1，不是 DSH 的内部 Remote 协议。插件内部通过独立 Host Adapter 对接 DSH 0.2.1-rc.2 的 Remote Gateway；Session、Workspace、Settings、Commands、Goals、Schedule、Permission Presets、Plugin Manager 等 namespace 和严格参数只存在于该适配层。插件管理的请求帧及 DSH Mobile 页面方案见 [RC2 插件管理对接方案](docs/dsh-0.2.0-rc.2-plugin-management-mobile-integration.md)。

DSH 0.2.1-rc.2 要求每次 Remote 调用携带 peer。网关通过 ctx.connection.createPeer() 创建一个随插件释放的本机用户 Peer，普通请求、首帧读取和实时订阅都由 Host Adapter 注入它；移动端不能设置调用方身份。问答与审批继续由网关的 Host 监听器处理。旧网关漏传此字段时会出现 Cannot read properties of undefined (reading 'signal')，升级 DSH 后需重新安装本源码版本并重启 dsh web，手机无需更改协议。

可用本机已安装的官方 DSH 验证此契约（真实 Gateway / Connection，业务服务使用测试数据，不读写用户会话）：

DSH_INSTALL_ROOT=/absolute/path/to/@deepseek-ai/dsh node test/host-official.test.mjs

配对鉴权和 dsh-mobile-v1 / hello.protocol = 3 保持不变。新版实时 token 不占用持久事件的 seq：客户端显式订阅 assistantStream: true，接收原子的 session-snapshot 和独立增量；普通 event 只携带持久事件。未接入新订阅的客户端只能收到持久消息。

历史响应包含 historyFormatVersion 和 cursor。客户端格式变化时应清理历史缓存、重新安装基线；携带 beforeSeq 的分页或携带 atSeq 的 fork 必须同时发送 historyFormatVersion: 4。

当前协议接入与验收见 [rc.2 移动端接入说明](docs/dsh-rc2-mobile-integration.md)；早期迁移记录见 [Remote Gateway 重构实施计划](docs/remote-gateway-refactor-plan.md)。

• WebSocket：/ws/mobile
• 局域网：ws://<局域网 IP>:3081/ws/mobile
• Linux 服务器公网：wss://<公网 IP>/ws/mobile
• 协议文档：[PROTOCOL.md](PROTOCOL.md)

当前源码新增会话模式选择：App 创建空白 Session 后，可查询并修改该 Session 的 Agent preset；首次对话后锁定。通过 session-agent-preset 能力发现接入，详见 [App 接入说明](docs/session-agent-preset-app-integration.md)。App 界面需按此说明接入，本次源码尚未发布。

当前源码新增 turn-outline-v1：透传 WebUI 使用的完整轮次大纲及实时更新，支持 App 在未加载全部正文时展示会话刻度、问答预览并按需分页跳转。控制连接重建和新设备连接会恢复大纲基线；Host 未提供大纲时可降级为已加载轮次导航。详见 [App 会话轮次导航接入指南](docs/turn-outline-app-integration.md)。App 界面需单独接入，本次源码尚未发布。

当前源码新增 file-upload-v1：已配对移动端可通过控制连接分块上传 PDF、Office、压缩包、音频等普通文件，校验 SHA-256 后存入 DSH 官方附件存储，再以会话专属凭证随消息发送。支持进度确认、取消、断线清理及实时/历史文件引用；复用官方 WebUI 的附件准入，不写入客户端指定的主机路径。帧示例、App 状态机、限制及验收见 [移动端普通文件上传对接指南](docs/file-upload-app-integration.md)。App 页面需单独接入，本次源码尚未发布。

当前源码新增 agent-team-v1、subagent-conversations-v1：支持团队成员与共享任务板查询、各层子智能体目录、团队投影和成员运行状态实时同步，以及子会话独立历史、订阅、继续对话与停止执行。APP 的目标地址、完整 JSON 示例、看板规则、切换与重连状态机、错误处理和验收清单见 [智能体团队 APP 详细接入指南](docs/agent-team-app-integration.md)。本次只提供网关能力，APP 页面需单独接入，源码尚未发布。

多网关第一阶段（当前源码）

插件提供稳定 gatewayId、可配置 gatewayName、配对候选地址列表，以及可持久化的“关闭 / 临时开启 / 常驻开启”运行模式。一个 App 可以分别配对不同机器上的网关；客户端多网关管理仍需按 [App 对接说明](docs/multi-gateway-app-integration.md) 实现。本次源码尚未发布新的 npm 版本。

在“移动设备”面板选择“常驻开启”，网关会持续接受已授权设备连接，重启后保持。常驻需要 DSH 进程运行、机器未休眠且网络可达，不提供自动发现或网络中转。

部署配置示例（对应 mobile-gateway 插件的 config）：

gatewayMode: persistent
gatewayName: 家里电脑
requireAuth: true
endpoints:
  - wss://gateway.example.com/ws/mobile
  - ws://192.168.1.10:3081/ws/mobile

运行模式的优先级：已保存的界面选择 > gatewayMode > 旧 gatewayEnabled。没有保存选择时，旧配置 gatewayEnabled: true 对应常驻，false 对应关闭。

• 关闭：立即断开移动连接，重启后仍关闭。
• 临时开启：默认 5 分钟没有设备成功连接则关闭并保存关闭状态；成功连接后本次运行保持开启。若以临时模式重启，则重新开始等待首次连接。gatewayWaitTimeoutMs 可配置 30 秒至 30 分钟。
• 常驻开启：没有无人连接关闭计时器。配对码仍默认 5 分钟过期，文件传输超时等独立规则不变。

状态默认保存到 <deviceFile>.gateway.json，通常为 ~/.dsh/mobile-gateway-devices.json.gateway.json；可通过 gatewayStateFile 单独配置。文件包含随机 UUID v4 身份及用户选择，权限为 0600，使用同目录临时文件原子替换；损坏时启动报错，不能静默生成新身份。每个运行实例必须使用独立的设备注册文件和状态文件。

升级和迁移机器时应一并保留这两个文件。克隆为新的独立网关时，不复制原实例的状态文件和设备注册文件，让新实例生成新身份并重新配对。不要在运行中删除身份文件来恢复默认模式；如需重新使用启动配置，应停止该实例、备份状态文件、仅将其 mode 改为 null，保留 version 和 gatewayId 后重启。

gatewayName 最多 80 字符，未设置时使用主机名。endpoints 是额外候选地址，最多 16 项，每项最多 2048 字符；

…(truncated)