前言¶

DSH 的「一切皆插件」思路下，远程入口、状态面板和网关可以按 web 客户端插件接入 DSH。如果目标是给 DSH 增加侧边栏入口、在手机或桌面查看会话与状态、上传下载文件，并带一个随 DSH 启停的远程网关，dsh-remote-plugin 是一个已经把这些能力打包起来的 bundle 插件。

这是什么¶

dsh-remote-plugin 是 DSH Remote 的官方 bundle 插件：在 DSH 侧边栏提供入口，打开快速状态面板和完整管理控制台，并内置随 DSH 自动启停的远程网关。仓库由 Blank-not-black 维护，许可证为 MIT。

它的 package.json 声明 dsh.client 注入：

@deepseek-ai/dsh-client-runtime
@deepseek-ai/dsh-client-ui-slots

同时声明：

platform: web
Node engine: >=18

核心功能¶

• 在 DSH 侧边栏提供入口。
• 打开快速状态面板和完整管理控制台。
• 快速面板展示网关状态、在线设备、Token 用量和快捷操作。
• 管理控制台支持端口、上游、设备、请求、Token 统计、二维码和令牌轮换。
• 内置 gateway.cjs，默认监听 0.0.0.0:8787，并带 Bearer token 鉴权。
• 网关自愈：DSH 重启或网关意外退出后自动拉起，可在面板中停止或启动。
• 提供 /fs/* 文件端点：列表、下载、分块上传、断点续传、暂停/继续/取消和 SHA-256 校验。
• 提供手机端、桌面端和管理页 WebUI，以及随插件分发的 Android APK。
• Android 应用 / 手机 WebUI 提供会话、文件、主页、统计、设置五个主要页面。
• 会话详情支持目标控制、子代理中断、模型切换、全屏输入、斜杠命令和图片附件。
• 图片附件可从相机或相册选择，并以 session.prompt 图片内容发送到当前会话。
• 通知设置支持审批 / 提问通知、后台轮询、峰谷提醒、任务完成提醒和历史公告。
• 公告通过中央 HTTPS 源更新，App 前台每 30 秒检查，中央源不可达时回退网关缓存或安装包内公告。
• 当前保留四套主题：默认深空、落日、易北爱乐厅、草原孤塔。

安装与启用¶

先安装到 DSH 的 web profile，再确认插件列表：

dsh plugin --profile web add dsh-remote-plugin
dsh plugin --profile web list --depth 0

第二条命令用于确认插件安装在正确的 web profile。

如需按 README 示例安装指定版本，可以使用：

dsh plugin --profile web add dsh-remote-plugin@0.6.8

安装后完整重启 DSH Web 进程，并 Ctrl+F5 强刷浏览器。左侧边栏会出现 DSH Remote 入口。

如果 DSH Web 由 systemd 用户服务管理，可执行：

systemctl --user restart dsh-web

手动运行时，需要先停止旧的 dsh web 进程，再重新启动。

安装后先在 DSH 主机访问：

curl -i http://127.0.0.1:8787/health

看到 JSON 后，再用手机连接 DSH 主机的局域网地址：

http://<电脑局域网IP>:8787

注意：手机上的 127.0.0.1 和 localhost 指向手机自己，不是 DSH 主机。

典型用法与排障¶

在 DSH 主机先检查网关健康、端口监听和 DSH Web 上游：

curl -i http://127.0.0.1:8787/health
ss -ltnp | grep ':8787'
curl -i http://127.0.0.1:3080/

如果 8787 本机也拒绝连接，检查插件是否装在 web profile、插件面板的网关开关、DSH Web 是否真正重启，以及 8787 是否被占用。

如果 /health 能打开但 upstreamOk: false，说明网关已运行，应检查 DSH Web 的 3080 端口。

如果本机能打开但手机不能，使用电脑局域网或 Tailscale IP，并允许防火墙 TCP 8787 入站；不需要对公网放行 3080。

如果访问出现 401，重新扫码，或复制：

~/.dsh-remote/token

如果页面黑屏或功能未更新，先在浏览器 Ctrl+F5 强刷，手机端完全退出后重开。

插件网关可能以 transient 进程运行，不要依赖：

systemctl --user restart dsh-remote-gateway.service

优先在插件面板启动网关，或重启 DSH Web 触发自愈。

常用入口：

管理页：http://<网关IP>:8787/admin
桌面 WebUI：http://<网关IP>:8787

网关配置¶

网关默认监听 0.0.0.0:8787，并带 Bearer token 鉴权。DSH 上游默认是：

http://127.0.0.1:3080

相关配置项：

• 网关端口优先级：DSH_REMOTE_GATEWAY_PORT 环境变量 → ~/.dsh-remote/gateway-port → 8787
• 令牌：~/.dsh-remote/token，首次运行自动生成
• 自愈开关：~/.dsh-remote/gateway.enabled，或使用 DSH_REMOTE_AUTOSTART=0 禁用自动管理
• 文件根目录：DSH 已登记工作区会自动放行；其他目录用 DSH_REMOTE_FS_ROOT 配置，Linux/macOS 使用 :，Windows 使用 ;
• 文件上限：DSH_REMOTE_FS_MAX_UPLOAD，默认 2GB
• 中央公告：DSH_REMOTE_ANNOUNCEMENTS_URL 可覆盖默认 HTTPS 地址，设为空字符串可禁用中央源

适用场景与注意¶

适合需要在 DSH Web 侧边栏内查看远程状态、管理会话和文件，或希望把手机/桌面入口和网关一起接入 DSH 的用户。

安装前建议检查源码和许可证。插件以当前 DSH 进程权限运行，网关令牌和远程入口都应视为敏感能力。令牌等同于 DSH 远程操作凭证，请不要公开或提交到仓库。

局域网访问建议配合防火墙；跨网络访问建议使用 Tailscale 或其他带认证的安全隧道。

链接¶

GitHub：https://github.com/Blank-not-black/dsh-remote-plugin

目录页地址未在本次核实资料中给出。