wenbin-wb/dsh-bridge

dsh-bridge · DSH 远程连接 / 远程控制插件

简体中文 | English

DeepSeek Harness 多通道远程访问与全域安全门禁插件（DSH 远程连接 / 远程控制 / 远程链接插件，remote control）

手机扫个码，人不在电脑前也能继续用 DeepSeek Harness。无论躺在沙发上、出差通勤、还是跨网协作——都不用守着电脑，也不用自己搭公网服务器，扫码即可在手机、平板或任意设备上接着干。

将您本地运行的 DeepSeek Harness 无缝延伸至手机网页、PWA 原生全屏应用、公网安全隧道、以及 微信 / QQ / 飞书 / Telegram 机器人矩阵。随时随地调度 AI 编写代码、执行任务、审批操作与管理工作区。

📖 远程连接着陆页：docs/remote-connection.md ｜ 🤖 给 AI 看的摘要：llms.txt

目录

• ✨ 功能特性
• 📦 环境要求与安装
• 🚀 核心功能与使用指南
• 1. 🛜 局域网访问与多网卡智能切换
• 2. 🌐 公网隧道（Cloudflare 临时/固定域名 & 自建隧道）
• 3. 📱 移动端交互与 PWA 独立全屏 App
• 4. 🗂️ 远程工作区网页选择器
• 5. 🔐 全域安全认证与防篡改门禁
• 6. 🤖 全能 IM 机器人矩阵（微信 / QQ / 飞书 / Telegram）
• 7. 📊 运维监控看板与一键平滑重启
• 💬 常见问题 (FAQ)
• 🛠️ 开发与贡献
• ⭐ Star History
• 📄 开源协议

✨ 功能特性

• 🛜 局域网多网卡智能识别与切换：自动探测物理 Wi-Fi、以太网与虚拟网卡（WSL/VMware/Docker），支持在控制台可视化一键切换并记忆持久化，彻底解决多网卡 IP 不互通问题；
• 🌐 双模 Cloudflare 公网隧道：免登录一键获取随机临时域名，或填入 Cloudflare Token 绑定固定域名并随 DSH 开机自启；支持 macOS 下 Gatekeeper 隔离自愈与全局探测；代理层为事件流（SSE）内置空闲保活，远端实时通道不再被链路掐断；
• 📡 隧道可观测性：每 60s 实测公网入口端到端可达性（DNS / TLS / 边缘 / 回源，/ready 假绿一眼识别，疑似 DNS 污染自动标注解析 IP）；面板展示实际 cloudflared 路径 · 版本 · 来源；检测到与你使用同一 Tunnel Token 的其他 cloudflared 时黄条告警；
• 📱 原生级移动端交互与 PWA 全屏应用：动态居中会话标题、复用 DSH 原生侧边栏抽屉与 [| 收起图标、防重叠自适应工具栏，支持手机浏览器「添加到主屏幕」作为独立原生 App 运行；
• 🌏 界面跟随 DSH 主体语言（中文 / English）：设置面板五大分类、全部卡片、锁屏与解锁、远程目录选择弹窗、命令与升级提示等文案均随 ` 自动切换中英；访客登录页（认证发生在 DSH 语言之前）按浏览器 Accept-Language` 选择中英；无需单独的语言开关；
• 🗂️ 远程工作区网页选择器：手机端点击添加工作区唤出树形目录抽屉浏览器，电脑本机点击自动分流调用系统原生选择窗口；支持 IM 指令 /addworkspace 远程注册；
• 🔐 全域安全认证与双防线门禁：专属二维码 256-bit Token 免密直通、外部访问密码门禁、独立后台管理员防篡改锁；内置物理机（127.0.0.1）最高特权与终端一秒救急重置（reset-auth）；
• 🤖 全能 IM 机器人矩阵（微信 / QQ / 飞书 / Telegram）：支持多工作区会话调度、跨重启会话持久化、Markdown 打字机流式输出、Card 2.0 原生一键点击审批与文件双向直传；飞书底层为官方 Channel SDK，接入只需手机扫码一键创建应用；各平台均支持本轮改动摘要（每轮播报改了哪些文件，/diff 可导出 .patch 补丁）与实时插话模式（Agent 忙碌时新消息注入到当前轮次的下一步，默认关闭，设置页可开）；
• 📊 运维看板与平滑升级：系统 CPU / 内存 / Uptime 实时看板、网络连通性一键诊断、全局配置 JSON 导出恢复、npmmirror 极速版本检查与平滑重启。

📦 环境要求与安装

环境要求

1. Node.js ≥ 22（DSH 要求 ^22.19.0 或 ≥ 24.0.0）
2. dsh CLI 可用（能在终端直接运行 dsh 命令）

# 检查 Node 版本
node -v   # 应显示 v22.19+ 或 v24+

# 检查 dsh 是否可用
dsh --version

DSH 版本兼容性

本插件同时兼容新旧 DSH，无需按 DSH 版本挑选插件版本：

DSH 版本 · 状态 0.1.0 ~ 0.1.1 · ✅ 支持（回环专用 RPC 通道加固） 0.1.2 ~ 0.1.4 · ✅ 支持 0.1.5-alpha.1 ~ 0.1.5-rc.2 · ✅ 支持（v2.10.9 起） 0.1.6 ~ 0.1.7 · ✅ 支持（v2.12.x 适配 0.1.7 存储格式与 grid 布局变更；0.1.6 旧存储布局有向后兼容回归用例） 0.2.0-rc.2（Web，profile web） · ✅ 支持（v2.12.4 起宿主 CSS-module 类名改为运行时解析，全部移动端 UI 验收在该版本通过） 桌面版内置宿主 0.2.0-rc.2（profile desktop） · ✅ 支持（v2.12.4 修复桌面宿主上移动端设置页样式整片失效；已实机验证）

关于 DSH 原生鉴权：DSH 从 0.1.2 起为 dsh web 内置了浏览器鉴权——启动时会打印带一次性 token 的地址（http://127.0.0.1:3080/?token=…），换取一枚绑定回环地址的会话 cookie，此后 /、/api 及各插件 RPC 通道都要求该 cookie。

这与本插件的访问密码门禁是两层互补的防护，不冲突也不重复：原生鉴权保护的是"本机回环上的 DSH 进程"，本插件的门禁保护的是"经局域网 / 公网隧道进入的远程访问"。本插件的反向代理会在转发时自动注入合法的回环会话 cookie，因此手机 / 隧道访问无需手动处理 DSH 的 ?token=，按本页说明正常使用即可。

安装插件

# 方式一：从 npm 安装最新版（推荐）
dsh plugin --profile web add @wenbin_wb/dsh-bridge

# 方式二：免全局权限的 npx 方式
npx --yes @deepseek-ai/dsh plugin --profile web add @wenbin_wb/dsh-bridge

# 方式三：从源码安装
git clone https://github.com/wenbin-wb/dsh-bridge.git
dsh plugin --profile web add ./dsh-bridge

升级至最新版

# 方式一：在设置页「远程访问」底部点击「🚀 一键升级到最新版并重启」（推荐，全自动）

# 方式二：终端强制覆盖安装最新版
dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest

💡 提示（pnpm 11 用户）：如果升级后仍显示旧版，是由于 pnpm 11 的 minimumReleaseAge 机制限制。在 Web 控制台点击「一键升级」即可自动跳过限制安装最新版。

DSH Desktop 桌面版安装

桌面版（Electron 应用）运行在独立的 desktop profile 上，与 Web 端是两套插件安装，需单独安装：

• 方式一 · 图形界面（推荐）：打开 设置 → 插件 → 「+ 添加插件」 → 输入包名 @wenbin_wb/dsh-bridge → 国内网络可在「安装源」切换 中国大陆镜像源 → 点击 「安装」 → 完成后在左侧「已安装」列表确认插件已启用 → 通过应用菜单重启 DeepSeek Harness 后生效。
• 方式二 · 命令行：

dsh plugin --profile desktop add @wenbin_wb/dsh-bridge

🚀 核心功能与使用指南

启动 DeepSeek Harness 后，在设置面板找到 「远程访问」 即可开启全部功能：

1. 🛜 局域网访问与多网卡智能切换

插件启动后自动随服务开启局域网代理，无需手动配置。

• 零配置极速扫码：同一 Wi-Fi 下打开手机相机扫码即可直达移动端 Web 界面；
• 多网卡智能切换：当主机存在多张网卡（如物理 Wi-Fi、以太网、WSL 虚拟网卡、VMware、Docker 等）时，控制台自动展示 「🛜 局域网网卡 / IP 选择」 下拉框；智能评分高亮推荐物理网卡，点选后二维码与访问 URL 秒级重新生成并自动持久化保存。

2. 🌐 公网隧道（Cloudflare 临时/固定域名 & 自建隧道）

无需公网 IP 与路由器端口映射，随时随地从外网访问电脑上的 DeepSeek Harness：

• 模式 1：极速免登录临时隧道（默认）

1. 直接点击「Cloudflare 隧道」卡片中的「开启」按钮；
2. 系统全自动准备 cloudflared 二进制（macOS 自动剥离 Gatekeeper 隔离属性与自愈校验）；
3. 几秒内自动生成公网 URL 和二维码，点「重置链接」可随时换新。

• 模式 2：Cloudflare Token 固定域名（永久不变 · 免费）

1. 在 Cloudflare Zero Trust 控制台 免费创建 Tunnel 并绑定域名（如 dsh.yourdomain.com）——📖 从零申请/配置完整教程（注册账号 → 接入域名 → 建隧道 → 取 Token → 绑定子域名 → 填回面板）；
2. 展开卡片底部的 「⚙️ 高级配置：固定域名 (Cloudflare Token)」，填入自定义域名与 Tunnel Token 并保存；
3. 勾选 「随 DSH 启动自动开启」，每次 DSH 重启即可自动恢复隧道，URL 永久固定不变！
4. （可选）同一表单内可调整网络参数：协议（QUIC / HTTP/2）、边缘 IP（4 / 6 / 自动）、区域（美国 / 全球）——取值来自 Cloudflare 官方白名单，默认保持 cloudflared 默认行为；改动需重新开启隧道生效，当前二进制不支持的参数会自动跳过并告警；

• 模式 3：自建 WebSocket 隧道
• 支持连接个人 VPS 隧道中转服务器（查看自建隧道部署教程），具备数据端到端 gzip 压缩与 SSE 响应优化。
• 📡 运行状态一眼看全：卡片内 数据面 行 = 最近一次公网端到端探测（每 60s，含实际解析 IP，失败自动区分"回源失败"与"疑似 DNS 污染/伪造证书"）；cloudflared 行 = 实际使用的二进制路径 · 版本 · 来源（系统安装不参与版本钉死）；若检测到另一个使用相同 Tunnel Token 的 cloudflared，会黄条提示"隧道状态可能只反映一半"。

自建隧道安全须知：隧道服务端（scripts/install-tunnel-server.sh）只对「隧道客户端控制通道」校验 TOKEN；公网访客对隧道域名的 HTTP/WebSocket 转发不再做独立认证，安全完全依赖插件本地的「访问认证」（x-dsh-internal-tunnel 标识使隧道流量无法享受本机回环保留）。请务必在插件设置中开启「安全认证」并设置访问密码/二维码 Token（尤其 scope=all 或公网使用时）；未设置任何密码时，任何知道隧道地址的访客都能直接访问您的 DSH。

3. 📱 移动端交互与 PWA 独立全屏 App

针对手机屏幕与触控操作进行深度优化，无需额外配置即可获得原生 App 级流畅体验：

• 极简顶栏布局：保留左侧菜单抽屉与右侧快速新建会话，顶部动态居中显示当前会话标题；
• 原生侧边栏抽屉：完整复用 DSH 原生历史记录与工作区分类，顶部集成原生 [| 收起图标，支持边缘滑动与手势开合；
• PWA 原生全屏支持：在手机浏览器菜单点击「添加到主屏幕」即可作为 100% 独立原生全屏 App 运行（无浏览器地址栏与底栏）；
• 自适应防重叠排版：底部工具栏根据屏幕宽度弹性自适应，彻底消除权限预设与模型选择器重叠碰撞。

移动端对话与工作区管理体验

     

远程访问与移动端设置中心

     

4. 🗂️ 远程工作区网页选择器

针对手机端或远程浏览器无法唤起本地电脑文件弹窗的痛点，内置响应式网页树形目录浏览器：

• 智能分流：电脑本机访问（127.0.0.1）点击添加工作区直接呼出系统原生文件弹窗；手机或远程访问时自动弹出响应式底部目录抽屉；
• 极速直达：支持 Windows 驱动器盘符（C盘、D盘）以及系统常用目录（桌面、文稿、下载、Projects）一键直达，支持层级深入浏览与手动输入校验。

5. 🔐 全域安全认证与防篡改门禁

打开设置页「远程访问」→「安全认证」Tab 即可一键启用全方位安全守护：

1. 🛡️ 第一道防线：外部访问门禁（保护谁能进 Web 界面）

• 多通道分流生效：
• 全部通道开启防护：局域网与所有公网隧道均需认证；
• 仅公网隧道开启防护 (推荐)：局域网同一 Wi-Fi 内保持免密，暴露至公网的隧道强制开启认证门禁；
• 仅局域网开启防护：仅对局域网进行门禁拦截。
• 三种灵活验证模式：
• 🟢 扫码免密 + 密码认证 (默认推荐)：控制台生成的二维码已自动注入 256-bit 专属安全 Token，手机扫码即可免密秒进；直接在浏览器手动输入 IP 或公网域名的访客，需输入您设置的访客访问密码；
• 🔑 仅密码 / PIN 码：所有外部设备一律要求输入访问密码；
• 🎫 仅专属 Token 免密：仅允许通过控制台生成的二维码或带 Token 的专属链接进入。
• 一键轮换凭据：点击「🔄 重置安全 Token」即可使之前分享的旧二维码和链接立即全部失效。

📱 点击展开外部访问安全认证登录页截图

2. 🔒 第二道防线：管理后台防篡改（保护谁能改插件设置）

• 独立管理员密码：访客访问密码与管理控制密码彻底分离，即使将访问密码告诉外部朋友，对方也无法查看或篡改您的插件设置；
• 三种后台权限策略：
• 🔑 需密码解锁 (默认推荐)：远程设备进入控制台时全屏锁定，输入管理密码后解锁临时会话；
• 🛡️ 仅限电脑本机管理 (最高安全)：远程设备一律禁止查看与修改任何网络、机器人配置与 Token，仅允许在电脑本机（127.0.0.1）操作；
• 🌐 宽松模式：允许通过访客认证的远程设备直接管理。

🖥️ 点击展开远程设备管理控制台防篡改锁定截图

3. 🛟 三重容灾保命体系（永不自锁）

• 物理机免密直通：运行 DSH 的宿主电脑（127.0.0.1 / localhost）享有全局最高物理特权，永不要求输入访问密码，设置面板永不会被锁定；
• 服务器一键救急指令：无头 Linux 服务器或极端忘记密码时，在宿主电脑终端执行单行命令：

touch ~/.dsh/dsh-bridge/reset-auth

插件将在下次插件启动时检测到该标记，自动清空密码与安全策略并删除标记，恢复初始免密状态（重启 DSH 或重载插件后生效）；

• 全界面忘记密码指引：访客登录页与锁屏页均提供 ❓ 忘记密码？ 救助展开卡片。

6. 🤖 全能 IM 机器人矩阵（微信 / QQ / 飞书 / Telegram）

无需打开浏览器，直接在常用聊天软件中与本地 Agent 对话、下达任务、接收进度与审批操作：

• 🔀 同平台多账号：微信 / QQ / 飞书 / Telegram 均可在一台机器上并行挂多个同平台机器人（例如两个飞书自建应用「小鲸」「小秤」），凭证、人设、工作区、白名单与会话归属各自隔离；设置页「＋ 添加账号」即可新增，单平台最多 10 个。详见 同平台多账号指南。

🟢 微信 Bot（ClawBot / iLink）

基于腾讯官方开放的微信 ClawBot 插件功能（底层 iLink Bot API），扫码登录微信个人号后即可对话与审批，全程走腾讯官方服务器，无需公网与隧道。

📱 点击展开手机微信对话与审批截图

• 使用步骤：设置页「远程访问」→「IM 机器人」→ 选中「微信」→ 点「扫码登录」并扫码确认 → 向该微信 Bot 发送第一条消息即自动完成白名单授权。完整文档见 微信使用说明。

🐧 QQ Bot（OpenAPI v2）

接入 QQ 官方机器人，支持单聊与群聊（群聊需 @机器人），支持 Markdown 渲染、快捷按钮键盘与富媒体文件直传。

📱 点击展开手机 QQ 单聊与群聊对话截图

• 使用步骤：在 QQ 开放平台 创建机器人获取 AppID 和 ClientSecret → 填入并保存连接 → 添加机器人好友发送首条消息（或群聊首次 @机器人）自动加白名单。完整文档见 QQ Bot 使用说明。

🐦 飞书 Bot（推荐 · 官方 Channel SDK）

底层已全面接入飞书官方 Channel SDK：长连接与自动重连、事件验签解密与归一化、消息渲染与分片、流式打字机卡片、媒体上传下载全部由官方实现（本插件不再自维护协议栈）。 接入门槛也降下来了——不用进开发者后台逐项配置：设置面板里手机扫码即可一键创建应用，权限、事件订阅与卡片回调自动预置；仍保留手动填写已有应用凭证的方式。长连接模式 100% 免公网 IP / 免域名 / 免配置 Webhook。

📱 点击展开手机飞书对话与卡片审批截图

• 🚀 扫码一键创建应用（推荐）：设置面板点 「📱 扫码一键创建应用」 → 手机飞书扫码确认，权限 / 事件订阅 / 卡片回调自动预置并连接，全程无需进开发者后台；扫码创建的应用按租户自动识别飞书 / Lark 域名。
• ⌨️ 原生斜杠指令面板：连接后自动向飞书注册 /help /new /sessions /use /status /diff /ask 等 12 条指令，输入 / 即可从面板一键调用（需 PC 飞书 ≥ 7.70 / 移动端 ≥ 7.71；低版本直接手打指令同样可用）。
• 📄 云文档评论 @机器人：在飞书文档/表格的评论里 @机器人 提问，回答直接回到该评论线程（同一线程追问免 @；评论为纯文本交互，无流式/卡片）。
• 🙋 回答 Agent 的提问：Agent 需要你做个决定时（ask_user_question / 计划审批）会主动发到会话——选项卡片可直接点选（推荐项带 ⭐），也可文字回复（/ask 1、/ask 1,3 多选、/ask =自由输入、/ask 1; 2=1 多问分别作答）；只在本轮由该 IM 发起时接管，绝不抢走 Web 端的提问。
• 👀 实时活动状态：Agent 干活时卡片顶部显示它当前在做什么（⌨️ 正在运行命令（npm test）、📝 正在编辑文件（…）、🤖 正在协调子智能体 等，与 Web 端「思考 / 运行命令」同一套口径），用引用块+斜体与正文区分；卡片原地更新不刷屏，轮次结束自动消失（飞书 / Telegram）；默认关闭，可在设置页勾选开启。
• 🛡 审批卡片原地更新：点击批准/拒绝后卡片当场变结果态（显示决议者与发起人、超时/取消同样标出），不再补发重复文字。
• 使用步骤（已有应用）：在 飞书开放平台 创建企业自建应用并开启长连接接收事件 → 填入 App ID 与 App Secret 并连接。完整文档见 飞书接入指南。

✈️ Telegram Bot（官方 Bot API + 代理支持）