远程访问助手 godchen520/dsh-web-remote

dsh-web-remote

手机 / 外网远程访问 DeepSeek Harness（DSH）的插件。随时随地通过浏览器，或微信 / 飞书 / Telegram / QQ官方 机器人控制你的 DSH。

✨ 功能亮点

| 功能 | 说明 |
| 🌐 公网访问 | Cloudflare Quick Tunnel，无需公网 IP、无需注册，cloudflared 缺失时自动下载 |
| 🖥️ 官方桌面版 | 支持 DSH 官方桌面版（dsh-app://）：按钮注入走官方结构化通道，目标端口自动探测 |
| 📡 局域网直连 | HTTP + HTTPS 并列两条链接：HTTP 免证书直接可开，HTTPS 自签名（点「继续前往」即可） |
| 🔒 安全认证 | 每次启动生成随机令牌；HttpOnly Cookie；局域网可免 token |
| ⚡ 性能加速 | 反向代理自动 gzip 压缩，大历史会话加载更快 |
| 📱 侧边栏图标 | 手机快捷按钮常驻左下角，刷新不消失 |
| 🛰️ P2P（Tailscale） | 装了 Tailscale 时自动把 100.x 地址列到「公网」页，免 token 直连（在外面访问家里）；/链接 命令同时发公网与 P2P 两条链接，P2P 没打通时写明 p2p未打通 |
| 📶 Tailscale 状态 | 面板直接显示「已连接 / 未登录 / 未运行」+ 手机在不在线 + 路径是直连还是中继（哪个节点） |
| 🔌 自定义端口 | HTTP / HTTPS 端口可分别自定义，带同端口冲突拦截与占用检测 |
| 🤖 微信机器人 | iLink 协议直连微信，支持 AI 对话、会话控制、模型切换 |
| 💬 飞书机器人 | WebSocket 长连接，支持命令控制、会话监听通知 |
| ✈️ Telegram 机器人 | 长轮询收发消息，支持 HTTP 代理、命令控制、监听推送 |
| 🐧 QQ 官方机器人 | QQ 开放平台官方接入，WebSocket 长连接，无需额外 QQ 号 / 公网入口 |
| 🔔 钉钉机器人 | 企业内部应用 + Stream 模式长连接，不需要公网地址，被动回复 + OpenAPI 主动推送 |
| 👁️ 会话监听 | /监听 命令，Agent 思考完毕自动推送到已绑定通道 |
| 🩺 通道健康监测 | 微信/飞书/Telegram/QQ官方/钉钉 独立监测，连续 3 次失败自动告警并停止，红点直达 + 一键重连 |

⚡ 一句话安装

复制下面这句话给你的 DSH，它自己会装好一切：

请帮我安装 dsh-web-remote 远程访问插件（https://github.com/godchen520/dsh-web-remote），装完告诉我如何重启 DSH Web。

不想麻烦 Agent？命令行一条：

dsh plugin --profile web add github:godchen520/dsh-web-remote && dsh web

📸 截图

快捷按钮（页面左下角）：

快捷按钮

远程面板（公网 / 局域网切换、一键复制链接、二维码、启动 / 停止）：

远程面板

📋 安装方式

方式一：GitHub 直接安装（推荐）

cd $DSH_HOME/profiles/web
pnpm add github:godchen520/dsh-web-remote

在 package.json 的 dsh.profile.bundles 数组中添加 "dsh-web-remote"，重启 DSH。

--config.minimumReleaseAge=0 可绕过 pnpm 11 新包发布年龄校验（如需要）。

方式二：手动 patch

把本包放入 profile 的 node_modules，然后在 cordis.patch.yml 追加：

- insert:
- id: web-remote
name: 'dsh-web-remote'

bundle 方式需重启；cordis.patch.yml 方式会被 HMR 热加载。

⚙️ 配置

全部可选，不配置即开箱即用。在 cordis.patch.yml 里覆盖：

| 参数 | 默认值 | 说明 |
| targetPort | 自动探测 | DSH 自身端口。显式配置最优先；否则依次读 DSH_WEB_URL → DSH_PORT → 兜底 3080 |
| httpPortStart | 3081 | 局域网 HTTP 起始端口（自动跳过占用） |
| httpsPortStart | 3082 | 局域网 HTTPS 起始端口 |
| cloudflaredPath | '' | 指定 cloudflared 路径；留空自动探测 / 自动下载 |
| pfxPath | '' | 指定 PFX 证书；留空自动生成自签名 |
| pfxPass | '' | PFX 密码 |
| toolsDir | '' | 工具与证书缓存目录；留空使用 $DSH_HOME/tools |
| autoStart | true | 插件加载即自动启动 |
| lanOpen | true | 局域网免 token（私网来源放行） |

📱 使用方法

1. 启动后页面左下角出现 📱 图标
2. 点击图标 → 面板显示运行状态和链接
3. 手机浏览器打开链接即可访问 DSH

公网：https://xxx.trycloudflare.com/?token=...

局域网（同 Wi-Fi；默认免 token，并列给两条）：

- http://192.168.x.x:3081 —— 推荐，免证书，浏览器直接打开（非安全上下文，剪贴板 API 等受限）
- https://192.168.x.x:3082 —— 自签名证书，浏览器提示不安全，需手动「高级 → 继续前往」（安全上下文）

面板功能：
- 公网标签页：可填写自定义公网 URL（如自己的 ngrok 地址）
- 局域网标签页：两条链接各自的端口号可点击直接修改（HTTP / HTTPS 分别设置），二维码指向 HTTP 地址（手机扫码直接能开）

🖥️ 官方桌面版

插件支持 DSH 官方桌面版（窗口地址 dsh-app://app/）。与浏览器版有两点差异：

| 项 | 说明 |
| 按钮注入 | 桌面版走静态部署渲染路径，只消费官方结构化注入行（webserver/index-inject），不跑 tapIndex。插件已同时使用两条通道，两端都覆盖 |
| 目标端口 | 桌面版由宿主动态分配端口（实测 19387），且插件进程里看不到 DSH_WEB_URL（那是注入给 agent shell 的）。需要显式指定 |

在 profile 的 cordis.patch.yml 里补上端口：

- id: web-remote
name: dsh-web-remote
config:
targetPort: 19387 # 换成你桌面版的实际端口

不配置会兜底 3080，桌面版下的表现是隧道 502 Bad Gateway / Host Error。
面板 /remote/info 会返回 targetPort 与 portSource（config / env / default），可用来确认实际取到了哪个端口。

🤖 微信机器人

通过微信直接控制 DSH，支持：

远程控制命令：
- /链接 — 获取公网链接（未启动自动开启）
- /停止远程 — 关闭远程服务
- /监听 — 开启/关闭会话监听模式（思考完毕自动通知）

会话管理：
- /会话列表 — 列出所有会话
- /选择 N — 选中第 N 个会话
- /当前会话 — 查看选中会话名称
- /历史内容 — 查看会话最近输出

模型切换：
- /当前模型 — 查看当前使用的模型
- /切换模型 — 列出所有模型并切换
- /选强度 N — 设置思考强度

对话：
- 直接发送内容 → 自动发到选中的会话并回传结果
- 未选择会话时提示先选择

💬 飞书机器人

通过飞书直接控制 DSH，支持：

远程控制命令：
- /链接 — 获取公网链接
- /停止远程 — 关闭远程服务
- /监听 — 开启/关闭会话监听模式
- /帮助 — 显示命令列表

绑定方式： 在 DSH Web 面板 → 机器人标签页 → 飞书，填写 App ID 和 App Secret，点击绑定。

✈️ Telegram 机器人

通过 Telegram 直接控制 DSH，支持：

远程控制命令：
- /链接 — 获取公网链接
- /停止远程 — 关闭远程服务
- /监听 — 开启/关闭会话监听模式
- /帮助 — 显示命令列表

绑定方式： 在 DSH Web 面板 → 机器人标签页 → Telegram，填写 Bot Token，点击绑定。

代理支持： 国内网络无法直连 Telegram API 时，可在面板中配置 HTTP 代理地址。

🐧 QQ 官方机器人

通过 QQ 开放平台接入的官方机器人，支持：

远程控制命令：
- /链接 — 获取公网链接
- /停止 — 关闭远程服务
- /监听 — 开启/关闭会话监听模式
- /模型 — 查看当前模型
- /状态 — 查看通道状态
- /帮助 — 显示命令列表

场景支持： QQ 群聊 + 消息列表单聊。

接入方式（两种，任选）：

方式一：扫码绑定（推荐，全程不用复制密钥）

1. DSH Web 面板 → 机器人标签页 → QQ官方 → 点「📱 扫码绑定」
2. 用手机 QQ 扫描面板上出现的二维码
3. 在弹出的页面里选择你要绑定的机器人（已创建好的）→ 确认授权
4. 凭据自动填入并连接

注意：扫码是绑定已有机器人，不会新建机器人。若还没有，先用方式二创建。

方式二：手动填写

1. 打开 QQ 开放平台快捷创建，用 QQ 登录后点「创建机器人」（个人主体可创建 5 个）
2. 在开放平台「开发设置」里复制 AppID 与 AppSecret
3. 面板里填入后点「确认并连接」

特点：

| 项 | 说明 |
| 额外 QQ 号 | 不需要 —— 平台分配独立机器人身份，你的 QQ 只作为管理员 |
| 公网入口 | 不需要 —— 走 WebSocket 长连接，SDK 自带心跳与 RESUME 补发 |
| 备案 | 不需要 |
| 会话持久化 | 支持，进程重启后可 RESUME 补上断连期间的消息 |
| 主动推送 | 支持（需你曾给机器人发过消息；群聊需群主允许） |

群聊启用： 群主把机器人拉进群即可；若允许接收全量消息，需群主在机器人设置里开启。

说明： 这是本插件唯一的 QQ 接入方式。早期版本曾提供基于 OneBot 11（NapCat）的通道，已于 5.0.0 移除 —— 官方机器人合规稳定、无需额外 QQ 号，也不需要跑 NapCat 中间层。

🔔 钉钉机器人

通过 钉钉开放平台「企业内部应用 + 机器人」 接入，消息接收模式用 Stream 模式（长连接），因此和飞书/QQ官方一样：不需要公网 IP、域名、证书或内网穿透。

远程控制命令： 与其它通道完全一致 —— /帮助 /链接 /启动 /停止 /监听 /状态 /会话列表 /选择 N /当前会话 /历史内容 /当前模型 /切换模型 /选强度，以及直接发一句话（不带 /）转发进选中的会话。

特点：

| 项 | 说明 |
| 账号要求 | 需要企业/组织（个人版钉钉不支持应用机器人）；自测可免费新建一个团队，自己当管理员 |
| 公网入口 | 不需要 —— Stream 模式长连接（wss-open-connection.dingtalk.com） |
| 被动回复 | 用消息自带的 sessionWebhook，无需额外权限；有效期 1.5 小时，过期自动回落 OpenAPI |
| 主动推送 | 用 OpenAPI（单聊 oToMessages/batchSend / 群聊 groupMessages/send），需要「企业内机器人发送消息权限」 |
| 监听通知 | 走 OpenAPI 主动推送，不受 1.5 小时限制；重启 DSH 后会自动恢复上次的会话目标 |
| 群聊 | 需要 @机器人 才会收到消息；主动推送不支持 @ |
| 单条长度 | 自动按 4000 字分片（群聊接口 msgParam 上限 15000 字节） |

接入步骤：

1. 用企业管理员（或让管理员给你开发者权限）登录 钉钉开发者后台
2. 应用开发 → 创建企业内部应用 → 记下 Client ID / Client Secret（即 AppKey / AppSecret）
3. 应用能力 → 添加 机器人 → 填写名称等信息 → 消息接收模式选「Stream 模式」 → 保存
4. 发布应用：版本管理与发布 → 创建新版本（勾选「机器人」）→ 发布没发布时，机器人不会出现在会话里，senderStaffId 也不会返回 —— 主动推送会拿不到 userId
5. 申请权限：开发配置 → 权限管理 → 搜索「企业内机器人发送消息权限」→ 申请只用被动回复（收到消息才回）可以不申请；/监听 通知必须申请
6. 群聊场景：群设置 → 群管理 → 机器人 → 添加机器人（群需属于该应用所在企业）
7. DSH 面板 → 机器人标签页 → 钉钉 → 填 Client ID / Client Secret → 「验证并连接」

排错：

- 面板提示「AppKey 或 AppSecret 不正确」→ 凭证预检就失败了，核对后台的 Client ID / Client Secret
- 面板提示「连接超时」→ 凭证有效但没连上：确认应用已发布、机器人消息接收模式是 Stream
- 收到消息不回 → 看日志里是否有 [dingtalk] 收到消息；群聊必须先 @机器人
- 通知推不出去 → 检查是否申请了「企业内机器人发送消息权限」，以及是否给机器人发过至少一条消息（用来记录推送目标）

🩺 通道健康监测

微信 / 飞书 / Telegram / QQ官方 / 钉钉 各通道独立监测：

- 连续 3 次失败 → 自动停止该通道并告警
- 远程图标显示红点提示（任一通道断开即亮）
- 点击红点直达出问题的通道页，提供一键重连按钮

🔧 兼容性

| DSH 版本 | 状态 |
| 0.2.x（0.2.0-rc.2 实测） | ✅ 支持 |
| 0.1.2-rc.1 ~ 0.1.x | ✅ 支持 |
| < 0.1.2-rc.1 | ❌ 不支持（那之前 session.events 还是属性，没有 snapshotEvents()） |

本插件不 import 任何 @deepseek-ai/* 官方包 —— 宿主能力（webServer、subprocess、agents、sessions、sessionQuery 等）全部通过 cordis 服务注入获取。因此 DSH 改动包级导出（例如 0.2.x 移除 dsh-settings 的 settingsNamespace / installSettingsSection）不会影响它。

需要跟着 DSH 适配的只有服务接口本身：目前用到 session.snapshotEvents()（0.1.2+ 的新形式）。

❓ 常见问题

Q: 局域网链接打开提示"不安全"？ A: 那是 HTTPS 自签名证书的预期行为（公网隧道用的是真证书，不会提示）。
最简单的办法是用面板里并列给出的 HTTP 那条链接 —— 免证书，直接打开。
若确实需要安全上下文（剪贴板 API 等），才用 HTTPS 那条：手机浏览器选「继续访问」，Edge 需关闭"增强安全性"。

Q: 重启 DSH 后链接变了？ A: 公网隧道每次重启会生成新地址，这是正常行为。微信绑定的 token 会自动持久化恢复。

Q: cloudflared 下载失败？ A: 首次启动需要联网下载 cloudflared（约 10MB），之后复用缓存。可手动下载放到 toolsDir 目录。

Q: 微信扫码后断开？ A: 重启 DSH 后微信会自动重连（token 已持久化）。如仍断开，重新发送 /链接 扫码绑定。

📝 更新日志

查看 CHANGELOG.md 了解版本更新历史。

🤝 贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解开发和提交流程。

📄 License

MIT