dsh-plugin-mobile-gateway

dsh-plugin-mobile-gateway

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 接入说明 更新订阅、缓存与分页处理。当前修改尚未发布。

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

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

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 接入方式见 文件卡片与预览接入说明。

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 插件管理对接方案。

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 移动端接入说明；早期迁移记录见 Remote Gateway 重构实施计划。

• WebSocket：/ws/mobile
• 局域网：ws://:3081/ws/mobile
• Linux 服务器公网：wss:///ws/mobile
• 协议文档：PROTOCOL.md

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

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

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

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

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

插件提供稳定 gatewayId、可配置 gatewayName、配对候选地址列表，以及可持久化的“关闭 / 临时开启 / 常驻开启”运行模式。一个 App 可以分别配对不同机器上的网关；客户端多网关管理仍需按 App 对接说明 实现。本次源码尚未发布新的 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 分钟过期，文件传输超时等独立规则不变。

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

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

gatewayName 最多 80 字符，未设置时使用主机名。endpoints 是额外候选地址，最多 16 项，每项最多 2048 字符；配对时还会合并首选地址、公网配置与已监听的 LAN 地址，合并超过 16 项会报错。所有地址必须指向同一网关；不得填写 0.0.0.0 / ::。地址需要手机实际可达，公网使用 WSS。

测试结果与人工步骤见 验收报告，完成范围见 多网关待办。

配套 iOS 客户端

DeepSeek Harness Mobile 是本仓库的兄弟项目。它是面向 iOS 17+ 的 SwiftUI 原生客户端，支持工作区与会话、工作区内创建文件夹、历史和实时对话、图片、Agent 执行轨迹、Human-in-the-loop，以及由网关配置驱动的命令、技能、模型与权限菜单。

工作区首页 实时对话 设备配对

安装插件

前提：已经安装 dsh CLI 和 pnpm，并能正常启动 dsh web。可先执行 pnpm --version 确认当前用户的环境能够找到 pnpm。

局域网使用只需安装插件：

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

需要在 Linux 服务器通过公网 IP 接入时，推荐执行统一初始化命令。它会安装/更新插件，并请求一次 sudo 权限安装系统 Helper：

npx --yes dsh-plugin-mobile-gateway@latest init

init 会把当前正在执行的 npm 包精确版本安装到 DSH profile，并仅对该版本跳过 pnpm 的新版本等待期，确保插件与 Helper 版本一致。

安装后停止并重新启动 WebUI：

dsh web

打开 WebUI，确认左侧边栏底部出现“移动设备”。

局域网配对

适用于 DSH 电脑和 iPhone 位于同一个可互访的局域网。

1. 打开 WebUI 的“移动设备”。
2. 将“网关运行模式”设为“常驻开启”（短期配对也可选“临时开启”）。
3. 保持“设备鉴权”开启。
4. 在“配对连接方式”选择“局域网直连”，确认 WebSocket 地址为 ws://:3081/ws/mobile。即使 Cloudflare Tunnel 已开启，也无需关闭它。选择框旁的问号会按当前网关环境解释各入口并给出场景建议，不会自动更改选择。
5. 填写设备名称并点击“生成配对二维码”。
6. 在 iOS 客户端打开“设备认证”，扫描二维码。
7. WebUI 的可信设备显示“在线”后即完成。

如果系统防火墙拦截连接，只允许私有网络访问 TCP 3081。不要把 3081 开放到公网。

Linux 服务器公网 IP 配对

[!NOTE]

本文所说的“公网 IP 配对”特指 Linux 服务器。一键公网安装从 v0.6.4 开始提供，适用于带固定公网 IPv4 的 Ubuntu/Debian 服务器。服务器需要已经安装 Node.js、pnpm 和 dsh CLI；当前尚不支持 CentOS。

1. 准备公网端口

在云厂商控制台复制服务器的公网 IPv4，并在安全组中放行入站 TCP 80 和 443。不要将 DSH WebUI 端口或 TCP 3081 开放到公网。

2. 一键初始化

先确认普通 DSH 用户可以直接调用 pnpm：

pnpm --version

然后使用同一个普通用户执行（不要使用 root 或 sudo npx）：

npm_config_registry=https://registry.npmjs.org \
npx --yes dsh-plugin-mobile-gateway@latest init

该命令会安装或更新插件，并请求一次 sudo 权限安装 Nginx、Certbot、系统 Helper 和证书续期定时器。init 会确保 DSH profile 与 Helper 使用同一个精确版本。

完成后启动或重新启动 WebUI：

dsh web

3. 打开远程 WebUI

优先使用 VS Code、Cursor 等 IDE 自带的端口转发。也可以在自己的电脑执行：

ssh -N -L <本地端口>:127.0.0.1:<DSH 实际端口> <服务器用户名>@<服务器公网 IP>

然后在本地浏览器打开：

http://127.0.0.1:<本地端口>

4. 在 UI 配置公网入口

打开左侧的“移动设备”，在“公网接入”填写云厂商控制台提供的公网 IPv4，然后点击“配置公网接入”或“更新公网配置”。Helper 会自动读取当前 dsh web 端口并配置 Nginx、TLS 证书和 wss:///ws/mobile。

5. 配对移动设备

1. 开启“允许移动设备连接”，保持“设备鉴权”开启。
2. 填写设备名称并点击“生成配对二维码”。
3. iPhone 打开“设备认证”并扫描二维码。
4. WebUI 的可信设备显示“在线”后即完成。

二维码只能使用一次，并会在 5 分钟后过期；超时后在 WebUI 重新生成即可。

Windows / macOS 家用电脑远程连接

家用电脑通常没有固定公网 IP，不建议配置路由器端口转发。Windows / macOS 面板提供两种可选入口：无需账户或域名的 Quick Tunnel，以及使用固定域名的命名 Tunnel。插件会在首次开启时自动下载并校验 Cloudflare 官方 cloudflared，保存在当前用户的缓存目录；无需手动安装系统服务。

使用前先启动 dsh web。电脑必须保持开机、联网且 DSH 进程运行；休眠或进程退出后外网连接会中断。