deepseek-harness-desktop/packages/dsh-remote-web-ui

156Star5Fork6Issue0Watching

为 dsh web 增加扫码配对式手机远程控制与自更新能力,扫码即在手机小屏独立界面操作工作区。

机审证据安装命令仓库已核验dsh-plugin Topic许可证READMEAI 百科

此插件是大仓库 ningbainb/deepseek-harness-desktop 的子包,星数与活跃度统计的是整个仓库。

语言
TypeScript
License
BSD-3-Clause
分支
main
ai-agentai-coding-assistantcodexdeepseekdeepseek-harnessdesktop-appdshdsh-plugin

安装

$ dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-remote-web-ui

在终端中运行以上命令,通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh?看这篇新手教程

对话式安装

帮我安装 DeepSeek Harness 插件 ningbainb/deepseek-harness-desktop/packages/dsh-remote-web-ui:先查看仓库 https://github.com/ningbainb/deepseek-harness-desktop.git 确认安全性,然后执行安装命令并验证插件加载成功。

把这段指令粘贴给 DSH Web GUI 里的助手,由它代你完成安装与验证。

一句话定位

为 DeepSeek Harness (DSH) 的 Web GUI 增加扫码配对式手机远程控制 ——扫描桌面侧边栏手机图标生成的二维码,手机会进入一个独立、专为小屏设计的轻客户端界面,远程使用当前工作区;侧边栏的下载按钮可一键自更新 dsh-web-ui 全家桶。

核心能力

  • 扫码配对:侧边栏底部手机图标打开面板,生成一次性、限时的二维码链接,手机扫码即绑定并落到 /m 独立移动端界面。
  • 移动端独立界面:手机加载的是专为小屏设计的精简界面(工作区、会话、聊天、模型选择),不是把桌面 UI 塞进手机。
  • 实时同步:桌面面板和手机之间通过 SSE 实时同步配对状态(等待/已连接/已断开),消息可达时手机端实时推送新消息。
  • 局域网栅栏:默认开启后,所有非本机 /api 请求必须携带配对 Cookie;点「刷新二维码」旧链接立刻失效,点「停止」全设备所有令牌与会话被清空。
  • 一键公网隧道:开启后插件自动拉起 Cloudflare quick tunnel(无需账号/域名),二维码自动变为公网链接;也可手动指定已搭好的 publicBaseUrl
  • 一键自更新:侧边栏下载按钮异步检查 npm 上 @linxin666/dsh-* 全家桶最新版本,发现新版本自动跑 pnpm update,并提示重启 dsh web 生效。

技术实现

  • 语言: TypeScript
  • 关键依赖: @deepseek-ai/cordis@deepseek-ai/dsh-host-webserverqrcode.react(无 canvas 的纯 SVG 二维码渲染)、cloudflared(随包分发的 Cloudflare 隧道二进制)、schemastery(DSH 标准配置 schema 校验)
  • 架构模式: 双半区 cordis 插件 —— host 半区(src/index.ts)持有配对令牌、设备会话、/api/pair 路由族、/api/update 端点和 api/gate 监听器;browser 半区(src/client/)渲染侧边栏入口、配对面板、设置卡片、自更新面板。每个半区都通过 cordis apply() 单独挂载,gate 监听器在 /api 进入 ApiProxy 之前拦截未配对请求。
  • 入口文件: src/index.ts(host 半区) + src/client/index.ts(browser 半区)

适用场景

经常离开工位但想随时用手机继续某个 DSH 工作区的人 ——比如在沙发上、床上、外出路上想接着写提示词、看日志、追流式输出,又不想在手机浏览器里塞桌面版 UI。安装后扫码即用,手机走的是精简小屏界面,过期可一键刷新、被入侵可一键撤销;附带的一键自更新让多插件用户免去手动 pnpm update 的麻烦。

前置依赖与兼容性

依赖最低版本说明
DSH>= 0.1.0-rc.7依赖 api/gate 水位、sidebar.remote 座位、host-apiproxy 的 LAN 修复;旧版本缺失这些 seam 会失去部分功能
Node>= 22.19.0 或 >= 24.0.0package.json#engines 声明
平台macOS / Windows / Linux跨平台;Windows 下更新走 cmd.exe 解析 npm 的 .cmd shim
原生模块cloudflared一键公网隧道随包自动下载平台二进制,无需用户安装;未启用 autoTunnel 则不依赖

安装方式

dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-remote-web-ui

配置项

配置类型说明默认值
启用移动端远程控制开关关闭后移除侧边栏入口并停用配对路由与局域网栅栏
配对令牌有效期(毫秒)数字新生成的二维码链接在此时间后失效,最低 60000600000(10 分钟)
设备离线判定(毫秒)数字配对设备超过该时长未上报心跳即视为离线25000
已配对设备上限数字超过时淘汰最旧的设备会话,范围 1-644
设备 Cookie 名文本携带已配对设备标识的 Cookie 名称dsh_pair
局域网访问要求配对开关开启:所有非本机的 /api 请求必须带有效配对 Cookie;关闭:LAN 栅栏放开,只保留令牌、状态、撤销
公网地址(可选)文本内网穿透的公网地址,如 https://xxx.trycloudflare.com;填后二维码即变为公网链接留空
自动公网隧道开关开启后插件自动启动 Cloudflare quick tunnel(无需安装任何工具),并自动更新公网地址与信任配置
移动端回车发送开关开启:手机输入框按 Enter 直接发送,Shift+Enter 换行;关闭:Enter 换行,仅点发送按钮发送

常见问题

Q: 安装后启动看不到手机图标?

A: 三种常见原因:① 启动时绑定 127.0.0.1 而没有配置 publicBaseUrl / 开启 autoTunnel,面板会显示「此功能需要…」。请用 dsh web --host 0.0.0.0 启动,或在设置里配置公网地址/打开自动隧道;② DSH 版本过旧(< 0.1.0-rc.7)缺少 sidebar.remote 座位 —— 升级宿主;③ DSH 设置 allowlist 没把本插件命名空间开放给配置页 —— 走到 ~/.dsh/settings.yaml 直接配置 remote-web-ui 命名空间。

Q: 关闭「局域网访问要求配对」后还会被断线吗?

A: 不会。该开关只决定非本机的 /api 请求是否必须带配对 Cookie。关闭后令牌、状态、撤销、心跳这些行为都还在;只是 LAN 栅栏被绕过,任何人在局域网内都能直接访问 /api,手机配对像是多了一道双保险。

Q: Quick Tunnel 启动后手机端新消息为何延迟几秒才到?

A: 这是预期行为。cloudflared 的 quick tunnel 与 Tailscale Serve 默认不转发 Server-Sent Events(SSE),而 SSE 是手机端实时收消息的通道。本插件会自动回退到按短间隔轮询 session.history,消息仍能到达,只是不够即时;SSE 通道恢复后立刻恢复流式。要真正实时推送,请用 Cloudflare Named Tunnel(域名托管在 Cloudflare)或 TCP 端口转发(LAN 地址、Tailscale 虚拟接口地址、ssh -L、cloudflared TCP 隧道都可)。

Q: 一键自更新能更新什么,不能更新什么?

A: 面板只更新通过 npm 正常安装的 @linxin666/dsh-web-ui 全家桶(执行 pnpm update,失败时回退 corepack pnpm / npx --yes pnpm,Windows 上经 cmd.exe 解析 .cmd shim)。若插件是 link: 安装(开发模式),面板会检测到并只报告显示版本号,提示你在仓库里 git pull,不会执行更新(因为 link 模式没有 npm 上对应的版本)。

Q: 如何撤销已配对的手机?

A: 在桌面面板点「停止」即可。当前活动的配对令牌与所有绑定设备会话会被立即清空,下一次点「刷新二维码」可重新开始扫码。已连接的手机在下一次请求时会被 LAN 栅栏挡掉(403),实时流也会被切断。

Q: 移动端聊天能否发图片或附件?

A: 本插件描述范围内未涉及图片/附件/工具调用确认等富交互,移动端提供文本输入、模型选择、权限切换;mobile 端代码仅做 chat 历史/流式收发、模型/权限切换等 RPC 富能力,附件/工具调用确认走宿主原生会话,手机端只负责文本对话与切换设置。

Q: 电脑多网卡 / Tailscale 虚拟接口时二维码指向哪个网段?

A: 面板会列出机器所有非内部 IPv4 字面量供选择(含虚拟适配器),Tailscale 的 100.x 虚拟接口也会自动出现。手机与电脑在同一网络时选 LAN 段最稳,不在时选公网地址即可。

Q: 必须用 Cloudflare 隧道才能从外网访问吗?

A: 不是。任何把公网地址转回本机 127.0.0.1:端口 的隧道都行 —— 只需在插件设置填写 publicBaseUrl(如 https://xxx.trycloudflare.com),并在 dsh web 启动时加 --trusted-host <对应公网主机> 让宿主 ApiProxy 信任该主机;云网络未自动把该主机信任,公网 /api 请求会在到达配对层之前就被 403 拒绝。

上手难度

入门 — 装好插件、扫码、立即可用;要调整安全策略或走公网的话只需在设置卡片里开/关对应开关,不需要写代码。

已知问题与限制

  • 撤销是逐请求生效的:点「停止」时还在途中的请求会跑完,下一次请求才会被 403;这是设计上的并发副作用,不是 bug。
  • 设备会话在内存中:配对状态(token + devices)随 dsh web 进程重置,重启后所有手机需重新扫码。
  • 没有逐设备管理 UI:面板只显示聚合状态(等待/已连接 N 台/离线),单一设备的撤销被推迟,需「停止」全部后由下次自动刷新。
  • Quick-tunnel 主机名每次都变:trycloudflare.com URL 每次 cloudflared 启动都是随机新主机名,宿主 --trusted-host 与插件 publicBaseUrl 需一起更新;用 Named Tunnel(固定主机名)可避免这种抖动。
  • 安装了此插件后默认开启 LAN 栅栏:经局域网 URL 打开的桌面浏览器必须像手机一样扫码配对,否则 /api 全部 403;想保留原有开放 LAN 行为,把「局域网访问要求配对」关掉即可。
  • 自动公网隧道在中国大陆的可达性不保证:Cloudflare 自行判定,本地需自测。
  • 当插件以 link: 形式(开发模式)安装时,一键自更新按钮只显示当前版本号与「请在仓库里 git pull」提示,不会真正发起更新。
  • Dev HMR:dsh web --dev 按路径轮询每个 roster bundle,因此重建本包(其自己的 tsdown --watch)会热重载 client bundle;这与日常使用无关,仅开发期需要知道。

收录徽章

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/ningbainb/deepseek-harness-desktop/packages/dsh-remote-web-ui)

把这段 markdown 粘贴到你的 GitHub README,链接回本插件详情页。徽章只声明已被本站收录,不代表安全认证。

返回插件目录