dsh-remote-control：通过 HTTPS 远程控制正在运行的 DeepSeek Harness

前言¶

DeepSeek Harness（DSH）运行在本地，项目文件、服务商配置与 Core 进程都留在电脑上。如果你需要在手机上继续同一批会话、发送消息或审批操作，通常需要把配置或 DSH 服务搬到公网，或者使用第三方远程桌面工具。这会带来权限扩大和配置迁移的负担。

dsh-remote-control 是一个社区插件，允许手机浏览器通过 HTTPS 入口访问本机已有的 DSH Web Host。它通过 Cloudflare Quick Tunnel 或 SSH 反向隧道建立桥接，所有敏感数据与 Core 进程仍然留在运行 DSH 的电脑上，无需在手机上安装客户端或迁移配置。

连接方式¶

插件支持两种 HTTPS 入口模式：

quick（默认）：使用本机的 cloudflared 建立临时隧道，获得 *.trycloudflare.com 域名。无需 Cloudflare 账号或自备域名，适合快速测试与临时访问。
ssh（可选）：使用本机 OpenSSH、自有域名、有效 TLS 证书及受限 SSH 中继账户，建立固定 HTTPS 入口。服务器只承担 HTTPS 终止与到本机的转发，不触碰 DSH 或项目配置。

两种模式都保留本机回环桥接，不改变 DSH 的监听地址或信任列表。如果 DSH 的监听地址需要显式指定为 127.0.0.1 或 [::1]，请使用 dsh web --host 127.0.0.1（或 --host ::1）启动。

核心功能¶

显式开关远程入口：在电脑的“设置 → 远程控制”中开启或关闭。默认关闭，需要手动启用。
短时配对二维码：生成一次性配对码，手机扫码后填写或确认设备名称，再提交配对。无效名称不会消耗配对码。
多设备管理：默认支持 4 台配对设备，可配置到 16 台；可在电脑设置中逐台重命名或撤销。
自动续期凭证：通过 HTTP / WebSocket 访问现有 DSH Host，并自动续期访问凭证。
持久配对与 SSH 自动重连：可选持久保存设备刷新授权与开关意图；SSH 进程在短暂公网健康失败时不会立即终止，支持自动重连。
健康状态区分：入口“已启用”、SSH 进程存活和 Core WebSocket 已连接是不同状态，可通过管理页查看 connection.status、lastHealthyAt 和 checkedAt。

安装与启用¶

通过 GitHub tag 安装到 Web profile：

dsh plugin --profile web add github:slicenferqin/dsh-remote-control#v0.3.1

默认 Quick 模式需要在本机安装 cloudflared：

# macOS
brew install cloudflared

# Windows
winget install Cloudflare.cloudflared

其他平台使用 cloudflared 官方发行版，将可执行文件加入 PATH 或通过 cloudflaredPath 指定。SSH 模式改用本机 OpenSSH，不依赖 cloudflared；可参考文档固定 HTTPS 入口指南准备网关与配置。

如需更完整的手机工作台体验，可在同一 profile 加装手机工作台插件：

dsh plugin --profile web add github:slicenferqin/dsh-mobile#v0.1.0

使用 dsh web（或 dsh --profile web）启动。若 DSH 已在运行，安装后请重启该 profile 并刷新本机页面，再打开 DSH 输出的已认证本机浏览器入口。

配对与使用¶

在电脑打开 设置 → 远程控制，开启远程入口。
等待公网健康确认与二维码。Quick Tunnel 首次启动可能接近一分钟；SSH 模式需先配置固定入口。
手机相机扫码，在浏览器打开配对页。
填写或确认设备名称，再点击「配对并进入」。 页面不会自动提交；无效名称不会消耗配对码。
手机进入现有 DSH 会话。不同浏览器共享同一 Host 及记录，但可以各自选择不同会话。
在电脑的远程控制设置中重命名或撤销设备。安装 dsh-mobile 后，已配对手机也可在“设备”中修改自己的名称。

电脑需要保持唤醒、联网并持续运行 DSH。每增加一台设备请生成新二维码。配对链接默认两分钟有效，只能领取一次；生成新码会使未领取的旧码失效。

已配对设备再次进入¶

请保存远程首页，例如固定入口的 https://dsh.example.com/，或本轮 Quick Tunnel 的首页，不要把一次性扫码地址当作日常入口。重新打开已清除一次性码的配对页时，会尝试使用该浏览器已有的刷新凭证，确认新 Cookie 已生效后进入首页。真正的顶层首页 HTML 导航遇到配对 401 时，也可显示同一恢复页面。它最多自动恢复一次并返回固定首页；API、POST、WebSocket 和其他业务路径不会自动跳转。恢复失败时可显式重试或重新配对。

浏览器凭证只保存在完成配对的浏览器 Cookie 中；换浏览器、使用另一个隐私会话或清除站点数据后，需要新的二维码。更换域名后，每个设备都要在新域名首次配对一次，旧域凭证不会迁移。

持久配对与有效期¶

访问凭证默认有效 8 小时。刷新凭证采用滚动 10 天有效期，每次成功刷新重新计时。浏览器通常在访问凭证到期前 5 分钟续期；只要刷新凭证有效，后台恢复、重新打开页面或浏览器冷启动时也可透明续期。

persistDevices 默认 false。启用后必须指定绝对的 deviceStorePath。本机存储仅记录当前刷新凭证的 SHA-256 hash、到期时间、设备 ID/名称/时间等元数据及入口开关意图，不保存原始刷新或访问凭证、Core Cookie、DSH 启动 token 或配对码。文件以原子方式、0600 权限写入；坏文件和权限错误会拒绝恢复。

启用持久化后，受控插件重载、卸载或 DSH 重启会保留设备刷新授权和已记录的开关意图，恢复仍要求同一域名。旧 access 不恢复，下次凭有效 refresh 重新兑换当前 Host 的 Core Cookie，设备 ID 保持。若用户在本机主动关闭，或通过 remote_control agent 调用 disable，会撤销全部设备、关闭隧道与连接，并在持久存储中记为 Off；重启不会自动复活入口。撤销单台设备会使该设备授权失效并关闭连接，再次连接需要新二维码。更换域名或刷新授权到期后，旧授权不能恢复，需要重新配对。

autoStart 默认 false，即使已保存配对，重启后也需用户在本机重新开启入口。显式配置 autoStart: true 才会尝试自动开启，包括尚无开关记录的首次启动。若同时启用持久化，已记录的 Off 优先；要恢复自动启动，需要用户再次在本机开启。未启用持久化时，Off 不会写入跨进程状态。

健康状态与连接恢复¶

入口“已启用”、SSH 进程存活和 Core WebSocket 已连接是不同状态。connection.status 可为 checking、online、degraded、reconnecting 或 offline。lastHealthyAt 记录最近一次确认当前桥接成功的时间，首次确认前为 null；它与最新探测时间 checkedAt 不同。

0.3.1 中，已验证的 SSH 进程不会因为短暂公网健康失败被主动终止：普通失败连续三次后标记为 degraded，并保留上次成功时间和现有传输；非法响应或不匹配的 entryId 会立即降级。再次收到匹配的健康响应后恢复 online。SSH 真正退出或反向转发失败时仍会自动重连。短失败期间保留 online 与历史成功记录，不代表最新请求一定成功；首次启动仍须通过当前桥接的公网确认。

Core 进入持续重连时，客户端在短暂宽限后为每次故障合并一次凭证恢复，复用续期器已有的网络重试；只有凭证已就绪且 Core 仍在重连，才最多提示一次 Core 立即重试。若 Core 已自行恢复、凭证已失效或插件已卸载，不会用这次恢复去打断当前流。它不放宽 WebSocket、Host / Origin 或 Cookie 校验。

Core 默认 WS 心跳间隔为 2 秒，代际就绪超时为 15 秒，相关设置属于 Core，本插件不修改这些默认值。电脑休眠、断网或服务故障仍会中断访问。

配置字段¶

在 DSH 插件设置中编辑配置，常用字段如下：

字段	默认值	含义及范围
`tunnelMode`	`quick`	`quick` 临时隧道或 `ssh` 固定 HTTPS 入口。
`publicOrigin`	空字符串	SSH 模式必填，如 `https://dsh.example.com`；仅 HTTPS、443，不能含 userinfo、业务路径、query 或 fragment。
`sshPath`	`ssh`	本机 OpenSSH 可执行文件名或路径。
`sshTarget`	空字符串	SSH 模式必填；推荐专用 OpenSSH Host 别名。
`sshConfigPath`	空字符串	可选的本机 OpenSSH 配置文件绝对路径；私钥通过 SSH 配置引用。
`sshRemotePort`	`18380`	服务器上的回环监听端口，整数 1024–65535，须与 HTTPS 网关及 SSH 账户限制一致。
`persistDevices`	`false`	是否持久保存设备刷新授权和开关意图。
`deviceStorePath`	空字符串	持久化启用时必填；本机私有状态文件的绝对路径，不自动猜测 HOME 或 profile。
`autoStart`	`false`	显式允许启动时自动开启；持久记录的 Off 优先。
`cloudflaredPath`	`cloudflared`	Quick 模式使用的本机可执行文件名或绝对路径。
`tunnelProtocol`	`http2`	Quick 模式的 `http2` / `quic` / `auto`；HTTP/2 不依赖出站 UDP。
`startupTimeoutSeconds`	`60`	隧道启动超时，整数 10–180 秒。
`pairingTtlSeconds`	`120`	一次性配对码有效期，整数 30–600 秒。
`deviceTtlHours`	`8`	访问凭证有效期，1–168 小时。
`refreshTtlDays`	`10`	滚动刷新有效期，1–90 天；必须长于访问凭证寿命。
`refreshAheadSeconds`	`300`	提前续期时间，整数 30–3600 秒；必须短于访问凭证寿命。
`refreshRetrySeconds`	`30`	临时续期失败后的重试间隔，整数 5–60 秒。
`maxDevices`	`4`	配对设备上限，整数 1–16。
`heartbeatSeconds`	`15`	本机管理页状态流的保活间隔，整数 5–60 秒。

安全范围与限制¶

已配对设备可以通过 HTTPS 访问本机 DSH Host 的公开接口与业务 API，具体权限取决于 DSH 本身的配置。插件本身不持有或转发 Core Cookie、DSH 启动 token 或配对码。刷新凭证只保存在本机持久存储的元数据中（SHA-256 hash、到期时间等），文件权限为 0600。

插件要求本机 DSH Web origin 的主机名必须是 localhost、127.0.0.1 或 [::1]，不支持 0.0.0.0、[::] 等通配绑定。如果自定义监听地址触发 LOOPBACK_REQUIRED，请使用 dsh web --host 127.0.0.1（或 --host ::1）重启 DSH。

兼容性要求 Node.js 22.19 或更新版本，已安装 DSH，profile 包管理需要 PATH 中有 pnpm。插件声明的 DSH 版本范围为 >=0.2.1-rc.2 <0.3.0。插件版本 0.3.1 不代表它要求 DSH 0.3.0。DSH 插件 API 尚未稳定，升级前请核对兼容性。

适用场景与注意¶

需要在手机或平板浏览器中继续同一批 DSH 会话、发送消息或审批操作，且不想将 DSH 服务搬到公网。
需要临时访问本地 DSH，且希望保持所有配置与进程在本地，只通过 HTTPS 桥接暴露控制能力。
需要多设备远程控制，且希望使用一次性配对码与滚动刷新凭证来管理访问。

插件以当前 DSH 进程的权限运行，安装前建议检查源码与许可证。若需要固定域名入口与更高稳定性，推荐使用 ssh 模式并启用持久配对与 autoStart。

价值与链接¶

dsh-remote-control 通过 HTTPS 桥接将手机浏览器接入本地 DSH Host，支持临时与固定入口、多设备配对与滚动刷新凭证，让远程控制更可控、更安全。DSH 的所有敏感配置与 Core 进程始终留在电脑上，插件本身只承担隧道与桥接职责。

插件目录：https://www.skillhub.cn/plugins/slicenferqin/dsh-remote-control
GitHub：https://github.com/slicenferqin/dsh-remote-control