DeepSeekHarnessRemoteGatewayDeepSeek Harness plugin

一个轻量级 DeepSeek Harness 远程网关，让你通过 Web 或移动设备远程访问和控制本地 AI Agent

GitHub
Stars
22
Forks
1
License
MIT
Last commit
Aug 14, 2026
Latest release
v0.1.0

Overview

一个轻量级 DeepSeek Harness 远程网关，让你通过 Web 或移动设备远程访问和控制本地 AI Agent

Original README

Cached from the project repository on Sep 3, 2026. This is source content, separate from the Agents.md review above.

View source
DSH Remote Gateway banner

DSH Remote Gateway

让 DeepSeek Harness Web 获得可被手机远程访问的能力

不修改 DeepSeek Harness 本体代码，默认生成随机公网 URL、随机 6 位密码和扫码二维码，手机端仅需浏览器即可访问。

安装说明 · 常见问题 · 发布检查清单 · Release 附件策略 · Release 文案模板 · 许可证

License: MIT Node.js 22+ DeepSeek Harness Platform Cloudflare Tunnel Release Stars

项目简介

让DeepSeek Harness 可以手机远程访问、操作的轻量 sidecar 网关。

在保留 DeepSeek Harness 现有 Web UI 的前提下，为本地运行中的 DSH 增加一层远程访问能力：

  • 启动后自动生成随机公网 URL
  • 默认自动生成随机 6 位密码
  • 自动输出二维码，手机扫码即可访问
  • 支持 Windows、macOS、Linux
  • 适合临时远程访问、移动端查看和继续对话

为什么做这个

  • DeepSeek Harness 本身已经有完整的 Web UI
  • 真正缺的是“远程接入能力”，不是第二套前端
  • 对移动端场景来说，更重要的是“继续任务”，而不是“重新设计界面”
  • sidecar 形态更轻、更适合插件化复用，也更容易发布到 topics/dsh-plugin

核心特点

  • 不修改 DeepSeek Harness 源码
  • 默认随机公网 URL
  • 默认随机 6 位密码
  • 默认输出二维码
  • 手机只需浏览器
  • 支持 Cloudflare Quick Tunnel
  • 支持按平台生成发布包
  • 支持把 macOS / Linux 版本作为 GitHub Release 附件分发

截图预览

分享页手机登录页手机对话页
分享页手机登录页手机对话页

30 秒上手

  1. 先在本地启动 dsh web，并确认它可通过 http://127.0.0.1:3080 访问。
  2. 准备 cloudflared，放到 remote-gateway/bin/，或者确保系统 PATH 中可直接调用。
  3. 运行 npm run doctor 做一次环境检查。
  4. 根据当前平台启动 start_Windows.bat、start.ps1、start_Mac_or_Linux.sh、start.sh 或 start.command。
  5. 用手机扫描启动后生成的二维码，输入 6 位密码即可访问。

更完整的安装和排障说明见 INSTALL.md。

默认行为

正常启动后，网关会自动完成以下动作：

  • 在 127.0.0.1:8787 启动本地 HTTP 网关
  • 当未配置密码时，自动生成随机 6 位密码
  • 当 cloudflared 可用时，自动启动 Cloudflare Quick Tunnel
  • 在终端打印临时公网 URL、密码和二维码
  • 在 runtime/share.html 生成本地分享页
  • 默认自动在桌面打开这个分享页

这个默认流程非常适合插件分发场景：不需要固定域名、不需要公网 IP、也不需要改动 DSH 核心代码。

当前限制

工作区切换

当前远程状态下，无法直接从手机端主动打开本地尚未打开的工作区。
如果需要切换工作区，仍然需要先在电脑端打开目标工作区，再从远程端继续访问和切换。

平台支持

  • Windows
  • macOS
  • Linux

项目主体是纯 Node.js。平台差异主要集中在：

  • cloudflared 二进制
  • 各平台启动脚本
  • 发布包分发方式

它能做什么

  • 提供一个简单的登录页
  • 通过 HttpOnly Cookie 维护会话
  • 反向代理 DeepSeek Harness Web UI
  • 转发 /api/*
  • 转发 Harness 使用的两个 WebSocket 下行通道：
    • /api/events.mux
    • /api/events.host
  • 通过临时公网地址把本地网关暴露给手机端

它不做什么

  • 不修改 DeepSeek Harness 代码
  • 不自己提供 TLS 证书能力
  • 不要求固定公网域名

配置文件

可编辑配置文件：

remote-gateway/config.json

如果 auth.password 为 null，则每次启动都会生成一个新的随机 6 位密码。

如需使用固定密码，直接在 config.json 中手动填写即可。

配置示例

json
1{
2  "server": {
3    "bindAddress": "127.0.0.1",
4    "bindPort": 8787
5  },
6  "upstream": {
7    "origin": "http://127.0.0.1:3080",
8    "loopbackMode": null
9  },
10  "auth": {
11    "password": null,
12    "sessionSecret": null,
13    "cookieName": "dsh_remote_session",
14    "sessionTtlHours": 168,
15    "secureCookies": false
16  },
17  "dsh": {
18    "command": null
19  },
20  "tunnel": {
21    "enabled": true,
22    "mode": "quick",
23    "cloudflaredPath": null
24  },
25  "share": {
26    "openOnStart": true
27  }
28}

重要说明

Quick Tunnel 模式

默认隧道模式是 quick，会生成一个随机的 *.trycloudflare.com 地址。

当 upstream.loopbackMode 保持为 null 时，网关会在 Quick Tunnel 模式下自动启用 loopback 风格的上游请求头。这样每次随机域名变化时，不需要反复重启 dsh web。

这非常适合临时分享和插件分发，但它不是固定域名部署的最终形态。

cloudflared 二进制

默认查找顺序如下：

  • Windows：remote-gateway/bin/cloudflared.exe
  • macOS/Linux：remote-gateway/bin/cloudflared

如果本地 bin/ 目录中没有对应文件，网关会回退到系统 PATH 中的 cloudflared。

你也可以在 config.json 或环境变量中显式指定 cloudflaredPath。

macOS/Linux 说明

如果将二进制放到 remote-gateway/bin/ 中，记得先赋予可执行权限：

bash
chmod +x remote-gateway/bin/cloudflared

如果桌面环境没有 xdg-open，网关仍然可以正常启动，只是不会自动打开分享页，此时可手动打开输出的分享页路径。

环境变量覆盖

以下主要配置项都可以通过环境变量覆盖：

  • REMOTE_GATEWAY_BIND_ADDRESS
  • REMOTE_GATEWAY_BIND_PORT
  • REMOTE_GATEWAY_UPSTREAM_ORIGIN
  • REMOTE_GATEWAY_UPSTREAM_LOOPBACK_MODE
  • REMOTE_GATEWAY_PASSWORD
  • REMOTE_GATEWAY_SESSION_SECRET
  • REMOTE_GATEWAY_COOKIE_NAME
  • REMOTE_GATEWAY_SESSION_TTL_HOURS
  • REMOTE_GATEWAY_SECURE_COOKIES
  • REMOTE_GATEWAY_DSH_COMMAND
  • REMOTE_GATEWAY_TUNNEL_ENABLED
  • REMOTE_GATEWAY_TUNNEL_MODE
  • REMOTE_GATEWAY_CLOUDFLARED_PATH
  • REMOTE_GATEWAY_SHARE_OPEN_ON_START

直接运行

bash
node src/index.js

如果 share.openOnStart 为 true，会自动打开本地分享页。否则可以手动打开：

remote-gateway/runtime/share.html

一键启动

按平台选择合适的启动入口：

  • Windows 资源管理器 / CMD：remote-gateway/start_Windows.bat
  • Windows 兼容别名：remote-gateway/start.bat
  • Windows PowerShell：remote-gateway/start.ps1
  • macOS/Linux 终端：remote-gateway/start_Mac_or_Linux.sh
  • macOS/Linux 兼容别名：remote-gateway/start.sh
  • macOS Finder 双击：remote-gateway/start.command

这些启动器会自动完成三件事：

  • 检查本机是否有 Node.js 22+
  • 如果缺依赖，首次启动时自动执行 npm install
  • 按当前 config.json 启动网关

macOS/Linux 首次使用前，建议先执行：

bash
chmod +x remote-gateway/start.sh remote-gateway/start.command

Doctor 自检

首次启动前，建议先运行一次环境检查：

bash
npm run doctor

它会检查：

  • Node.js 版本
  • config.json 是否可解析
  • 上游 DSH 是否可达
  • cloudflared 是否能被发现
  • 依赖是否已安装
  • 当前密码模式是固定还是随机

适合发布的目录结构

  • 运行时文件已通过 remote-gateway/.gitignore 忽略
  • 日志文件已通过 remote-gateway/.gitignore 忽略
  • remote-gateway/bin/README.md 说明了如何替换或内置 cloudflared
  • remote-gateway/INSTALL.md 提供首次安装步骤
  • remote-gateway/FAQ.md 提供常见问题答案
  • remote-gateway/RELEASE_CHECKLIST.md 提供发布前检查项
  • remote-gateway/RELEASE_ASSETS.md 说明 GitHub Release 附件策略
  • remote-gateway/RELEASE_TEMPLATE.md 提供 GitHub Release 文案模板

仓库结构

  • src/ 网关核心运行代码
  • scripts/ 启动、自检、打包脚本
  • bin/ 本地开发或直接运行时使用的 cloudflared
  • vendor/cloudflared/ 按平台打包发布时使用的源二进制目录
  • runtime/ 运行时生成的分享页和临时产物
  • docs/screenshots/ 仓库首页和 Release 使用的截图目录
  • INSTALL.md 安装说明
  • FAQ.md 常见问题
  • RELEASE_CHECKLIST.md 发布检查清单
  • RELEASE_ASSETS.md GitHub Release 附件说明
  • RELEASE_TEMPLATE.md GitHub Release 文案模板

健康检查接口

GET /_gateway/health

该接口会返回网关状态、上游探测结果、当前公网 URL 和当前生效密码。