dsh-zen-remote

一个 DeepSeek Harness 插件、两种角色。主服务端把 DSH 变成手机能安全访问的 PWA（手机界面、配对网关、锁屏推送），并把选定的会话共享给已配对的桌面端；子客户端跑在另一台 DSH 桌面端里，可同时连接最多 8 台主服务端，把服务端共享的会话直接摆进自己的侧边栏——完整历史、实时进度、发消息、审批、终端，全部在服务端执行。

English

会话列表主屏	会话页	会话信息卡

composer 权限 sheet	公网设备看到的配对页

截图为 390×844 手机视口、浅色主题；深浅主题均适配。配对页由网关绘制，按 DSH 官方风格、跟随系统浅色 / 深色。

目录

1. 安装
2. 快速上手（一体化配置与配对向导）
   • 场景 A：作为主服务端（开放手机与另一台电脑连入）
   • 场景 B：作为桌面客户端（连接最多 8 台远端服务端）
3. 日常使用：会话共享与跨端协作
4. 锁屏推送：通知什么时候会响
5. 功能一览
6. 进阶配置与字段参考
7. 架构、安全模型与已知说明

1. 安装

界面一键安装（推荐，桌面端 App 与 Web 端通用）

打开 DSH 左侧**「插件」页 → 点击「添加插件」→ 输入 dsh-zen-remote → 安装完成后点击「立即启用」**，然后重启 DSH 桌面端 App（或 dsh web）。

Web 服务命令行安装（无头服务器 dsh web）

dsh plugin --profile web add dsh-zen-remote
# 然后重启 dsh web（或直接运行 npx dsh-zen-remote setup 一键完成安装、拉起与向导配置）

dsh plugin 必须带 --profile 指定目标 profile。桌面端的 desktop profile 由 App 独占管理，命令行会拒绝 --profile desktop，桌面端请直接使用上面的界面安装。

无头服务器 CLI 一键向导（dsh-zen-remote）

插件自带同包分发的命令行工具，远程 VPS 与无头环境（dsh web）无需打开浏览器插件页，在终端即可完成全部接入配置、三灯连通验证与扫码 / 配对码配对：

npx dsh-zen-remote setup        # 三步交互向导：选角色 → 选接入方式 → 三灯验证 + 终端二维码 / 桌面配对码
dsh-zen-remote status           # 查看当前角色、网关与连接状态（--json 机器可读；--debug 导出脱敏诊断报告）

# 主服务端命令（role 为 host 时可用）
dsh-zen-remote host device pair --device-role web              # 生成手机/浏览器配对二维码与 8 位码（或 desktop-client）
dsh-zen-remote host device list                                # 列出全部已配对设备（支持 --json）
dsh-zen-remote host device revoke <id|--all> [--yes]           # 吊销单台或全部已配对设备
dsh-zen-remote host ingress start --mode lan                   # 配置并启动公网入口（caddy | cloudflared | external | lan）
dsh-zen-remote host ingress stop [--yes]                       # 停止托管的 Caddy / Cloudflare Tunnel 进程
dsh-zen-remote host ingress verify [--no-wait]                 # 三灯连通自检并同时打印手机二维码与桌面客户端配对码
dsh-zen-remote host ingress snippet [--proxy nginx|caddy|lucky] # 打印反向代理配置片段

# 子客户端命令（role 为 client 时可用，最多同时连接 8 台主服务端）
dsh-zen-remote client pair http://192.168.1.2:3088 --code 12345678 [--name My-Mac]
dsh-zen-remote client list                                     # 列出已配对的主服务端（最多 8 台）及在线状态
dsh-zen-remote client unpair <hostUrl|entryId|--all> [--yes]   # 移除单台或全部已配对的主服务端

// ~/.dsh/profiles/desktop/package.json
{
  "dependencies": {
    "dsh-zen-remote": "^2.4.4"        // 本地开发换成 "link:/path/to/dsh-zen-remote"
  }
}

cd ~/.dsh/profiles/desktop && pnpm install
# 若使用 link: 本地仓库，还需在仓库目录内执行一次 npm install --omit=dev 安装网关子进程的 web-push 依赖

2. 快速上手（一体化配置与配对向导）

同一个插件包含两种运行角色：

• 作为服务端（主机，role: host）：运行主力会话、启动本地安全网关与锁屏推送，允许手机浏览器/PWA 或另一台电脑连入。
• 作为桌面客户端（从机，role: client）：不启动网关也不抢端口，可同时连接最多 8 台远端主服务端，把它们共享的会话直接挂载到本机侧边栏。

打开 DSH 「插件」页 → 点击 dsh-zen-remote，页面顶部就是**「远程访问与设备配对」**向导卡片（无头服务器在终端运行 npx dsh-zen-remote setup 即可走完同一套三步流程）：

场景 A：作为主服务端（开放手机与另一台电脑连入）

点击卡片上的**「开始配置向导」（已配置过则点「修改接入配置」**），三步完成：

第 1 步：选择「作为服务端（主机）」与接入方式

第 2 步：填写连接参数

• 内置 Caddy / Cloudflare Tunnel：填写公开域名（如 dsh.example.com）并粘贴 Cloudflare API 令牌。
• 使用已有反向代理：填写外部 https:// 地址，复制生成的 Nginx / Caddy / Lucky 配置片段。
• 局域网 / Tailscale 直连：直接确认向导自动检测并预填的 http://<本机局域网或Tailscale IP>:3088。

第 3 步：连通验证与扫码 / 配对码配对

1. 启动入口服务 & 自动连通自检：点击顶部状态栏**「启动 Caddy」或「创建并启动隧道」**（如适用），向导自动探测「本地网关就绪」与「访问地址连通」。
2. 配对手机 / 浏览器（Web 应用端）：在「配对手机 / 浏览器（扫码）」标签页点**「生成配对二维码」，手机扫码并输入 8 位配对码进入 DSH，随后点浏览器菜单「添加到主屏幕」**安装为独立 PWA。
3. 配对另一台电脑（桌面客户端）：切到**「配对另一台电脑（桌面客户端）」标签页，点「生成桌面配对码」并「复制地址与配对码」**。

日常快捷操作：配置完成后无需再进向导——直接在总览卡片底部点**「配对手机 / 扫码」、「配对另一台电脑」或「管理设备」**。

场景 B：作为桌面客户端（连接最多 8 台远端服务端）

在另一台装了 DSH 桌面端的电脑上（或通过命令行 dsh-zen-remote client pair <hostUrl> --code <8位码>）：

1. 打开「插件」页 → dsh-zen-remote → 点击**「开始配置向导」（若已是客户端角色，可直接点「+ 添加服务端」**）。
2. 第 1 步：选择**「作为桌面客户端（从机）」**，点击「下一步」。
3. 第 2 步：填写本机显示名称（如 MacBook-Pro）、主服务端的访问地址（公网必须为 https://，局域网 / Tailscale 可为 http://192.168.x.x:3088 或 http://100.x.x.x:3088）以及从主服务端复制来的 8 位桌面配对码，点击**「配对并连接」**。
4. 第 3 步：三盏状态灯（「本地配对凭证」「服务端连接」「会话与插件同步」）全绿即表示连接成功，左侧边栏会立即出现主服务端共享的工作区与会话分组。
5. 多服务端管理（最多同时连接 8 台主服务端）：
   • 在向导第 3 步点**「+ 继续添加另一台」、顶栏总览卡点「+ 添加服务端」，或打开「管理服务端」弹窗（及底层设置卡片）即可逐台查看在线状态、立即重连、重新配对、移除或全部移除**（配满 8 / 8 台时会有显眼红字提醒上限，已有地址仍可覆盖重配）。
   • 各台主服务端的远程分组严格按配对添加顺序合并在本地工作区之后；多台同名主服务端自动编号「名称-1」「名称-2」；模型选单、标题栏连接图标、只读横幅、插件桥与附件上传均按各会话所属 serverId 独立隔离。

3. 日常使用：会话共享与跨端协作

如何开启或关闭单个会话的远程共享

服务端默认只将你选定的会话暴露给桌面客户端（也可在向导第 2 步勾选「新建会话自动开启远程共享」）。有四个开关入口：

1. 主服务端侧边栏：在会话行的「…」菜单里点**「开启远程 / 关闭远程」**；

   

2. 主服务端会话页标题栏：点击标题右侧的地球图标（悬停可查看剩余闲置休眠时间；图标带绿点代表此刻有桌面客户端正在查看）；

3. 手机端（Web 应用端）会话页：打开右上角 ⓘ 会话信息卡片，切换**「远程访问」**开关；

   

4. 主服务端设置页：「已开启远程的会话」列表支持逐个关闭或一键全部关闭。

在子客户端上使用远程会话

• 侧边栏分组：服务端至少有一个会话开启远程后，子客户端侧边栏底部会出现**「服务端名 · 工作区名」**分组（最多同时接入 8 台主服务端，按配对顺序排列）。点开即可像本地会话一样查看历史、流式对话、审批工具、使用服务端终端、查看文件树与 Git diff、加载正文图片、下载交付物或拖拽/粘贴/选择文件上传。

  

• 关闭与自动休眠：开启远程的会话若连续 48 小时（idleHours 可调）无任何回合活动，会自动休眠关闭远程（正在运行或等待审批/回答的会话绝不休眠）。当会话关闭远程、或客户端移除配对/被服务端吊销时，侧边栏会自动将其归档隐藏；正在查看的会话页会展示「远程已关闭」横幅并禁用输入，重新开启后自动恢复。

  

4. 锁屏推送：通知什么时候会响

默认只在真正需要你介入的时候响，分为两条独立通道（推送载荷全程 aes128gcm 端到端加密；可通过总开关 pushEnabled 一键停用全部通知与 push_notify 工具，或开启 pushSessionName 在通知正文首行显示 来源会话：<会话名>）：

1. 系统自动触发（pushEnabled 开启时恒开，不受最小间隔压制）：
   • 工具等待授权：等待 DSH_PUSH_APPROVAL_GRACE_MS（默认 5 秒，让自动审批插件先行处理）后仍未决时，推送「DSH 等你授权」（附带工具名）。
   • 模型调用 ask_user_question 等待回答：推送「DSH 等你回答」。
2. 模型主动调用（push_notify 工具）：
   • 当你交代「做完告诉我」、或模型遇到阻塞必须你拍板时，模型会主动调用 push_notify 推送到手机锁屏。普通回合结束默认不推送（如需每轮结束都推，可打开 pushTurnEnd；开启 pushSummary 可附带 120 字以内的最终回复摘要）。

5. 功能一览

• 移动端 PWA 界面（主服务端）：会话列表主屏 + 独立会话页两级页面栈（左缘右滑返回、安卓返回手势接管、冷启动首帧骨架屏与内容哈希长缓存）、主屏插件入口 chips 自动发现、底部重排 composer（图标化按钮、底部权限/模型 Sheet、手机拍照/文件上传）、会话信息卡（六格统计含 tok/s 输出速度、导出日志、重命名、Fork、归档、一键导出 PNG 分享长图、远程访问开关）。
• 一体化配置向导与无头 CLI（dsh-zen-remote）：插件详情页顶部 2×2 实时状态总览、三步向导弹窗，以及同包命令行工具（setup / status / host / client），统一覆盖服务端四路接入（内置 Caddy 自动证书、已有反代、Cloudflare Tunnel、局域网/Tailscale 直连 + 私网源 IP 铁闸）与客户端配对。
• 跨桌面端远程会话与多服务端连接池（桌面客户端）：支持同时连接最多 8 台主服务端（按配对顺序合并分组、同名自动编号），提供完整历史与流式对话、审批/提问同步、按 serverId 隔离的服务端模型选单、文件树与改动 diff、双工服务端远程终端（terminal/attach）、正文内联图片转发、交付物分段下载、服务端 LibreOffice PDF 预览、最大 500 MiB 非图片大文件流式上传（拖拽、回形针选择、粘贴全覆盖）及一键导出脱敏诊断报告。
• 第三方插件桥（Plugin Bridge）：协作插件登记桥接声明或通过内置适配器（如 dsh-better-sidebar 0.25.0–0.30.1），即可在远程会话中直接读写主服务端的数据面板（整机数据需服务端主人逐插件授权）。详见 插件桥文档。

深度说明：界面设计文档 · 公网接入与中继协议

6. 进阶配置与字段参考

日常使用只需通过插件详情页顶部的**「远程访问与设备配对」向导**（或终端 npx dsh-zen-remote setup）即可完成全部配置。若需微调底层参数，可在 dsh-zen-remote 插件详情页的**「包含的组件」**下再次点击 dsh-zen-remote 展开底层配置卡片。

主服务端角色与配对卡片	已开启远程的会话列表	子客户端配置与诊断卡片

7. 架构、安全模型与已知说明

• 受信任客户端与严格会话隔离：已配对的桌面客户端在远程会话中以服务端系统用户权限运行终端与文件预览，而未开启远程的会话在服务端中继层被严格过滤或拒绝；即便在局域网模式下监听 0.0.0.0，网关内置私网源 IP 铁闸也会直接拒绝公网 IP 的未代理直连（403 public-direct-forbidden），且配对、向导与设备管理操作仅限在服务端本机执行。
• 版本容错：主服务端与子客户端需保持 dsh-zen-remote 版本一致；两端 DSH 宿主版本可以不同（握手时自动比对接口规范化指纹，存在差异时仅受影响的单面板降级，其余功能照常工作）。

上游致谢

本插件的界面层衍生自 mexiaosqwq/dsh-web-mobile，通道层衍生自 zylzyqzz/dsh-mobile-pwa（其自身衍生自 Bernardxu123/dsh-mobile-gate），均为 MIT，原始版权行保留在 LICENSE。

License

MIT