dsh-remote 🐋
> DeepSeek Harness 手机远程控制插件：扫一下二维码，用手机指挥你的 Agent。
> 局域网 / IPv6 / Cloudflare 隧道三通道，令牌鉴权，Windows 开箱即用。
>
> A remote-control plugin for DeepSeek Harness — scan a QR code and drive your agent from your phone.
English · 使用文档 · 注意事项 · 更新日志
✨ 功能
- 📋 会话总览：手机查看全部会话与实时运行状态（含子 Agent 标记）
- 💬 对话阅读：Markdown / 表格 / 代码块渲染，色彩突出重点；历史消息分页加载
- ✉️ 远程指挥：给任意会话发消息（忙时自动排队）、停止任务、新建会话
- 📎 图片与文件：手机上传，图片自动转 JPEG 压缩；Agent 经视觉工具（modlens）读图
- 🌐 三通道连接：局域网直连（首选）· Cloudflare 外网隧道（HTTPS，任何网络可用）· IPv6 直连（备用）
- 🔐 安全内置：令牌鉴权、配对页仅限本机、隧道来源隔离
🌟 特色
| 特色 | 说明 |
|---|---|
| 📱 手机零安装 | 只需浏览器（iOS Safari 即可），无需 App、无需公网 IP、无需升级系统 |
| 🧰 一体化配对页 | 二维码、隧道一键开关（实时日志 + 超时诊断）、视觉 Key 填写、令牌旋转——全在一个页面，不依赖插件设置页 |
| 🚀 Windows 开箱即用 | 安装包内置 cloudflared（52MB → 压缩后 18MB），打开隧道开关即可用，无需下载任何东西 |
| 🖼 纯文本模型也能看图 | 图片由 Agent 调用视觉工具读成文字证据；视觉 Key 在配对页粘贴即自动配置 |
| 🛡 防御式设计 | 服务惰性获取（开机时序安全）、错误落盘、老浏览器兼容、虚拟网卡过滤 |
📦 安装
tgz 安装（推荐）
# 从 Releases 下载 dsh-remote-1.2.0.tgz，或自行打包：
pnpm pack
# 桌面端 profile
dsh plugin --profile desktop add "D:\path\to\dsh-remote-1.2.0.tgz"
# WebUI profile
npx -y @deepseek-ai/dsh plugin --profile web add "D:\path\to\dsh-remote-1.2.0.tgz"
重启 DeepSeek Harness 后，电脑打开 http://127.0.0.1:4666/，手机扫码即可。
源码安装
git clone <仓库地址> && cd dsh-remote
pnpm install && pnpm pack # 注意：仓库不含 cloudflared 二进制，见下方说明
⚙️ 配置后即可使用
| 配置项 | 默认值 | 说明 |
|---|---|---|
| enabled | true | 总开关 |
| port | 4666 | HTTP 服务端口 |
| bind | lan | lan = 0.0.0.0（手机可访问）；loopback = 仅本机 |
| token | 留空自动生成 | 访问令牌，内嵌在二维码链接中 |
| tunnel | false | Cloudflare 快速隧道（也可在配对页一键开启） |
| cloudflaredPath | 空 | 自定义 cloudflared 路径 |
| visionKey | 空 | 图片识别 Gemini Key（配对页填写，自动写入 modlens 配置） |
> 隧道程序：tgz / Release 已内置 Windows 版 cloudflared；源码仓库不含二进制（体积大），
> 源码安装用户请从 Cloudflare 官方 下载放到 ~/.dsh/bin/。
> 图片识别：需安装 modlens 视觉插件。
🧭 工作原理
┌──────────┐ QR（含令牌） ┌────────────────────────────┐
│ 手机浏览器 │ ────────────────► │ dsh-remote 插件（DSH Host 内）│
└──────────┘ http/https │ · 自带 HTTP 服务（默认 4666） │
▲ │ · 令牌鉴权 / 配对页本机隔离 │
│ │ · 惰性调用 DSH sessionController│
└── 三通道 ◄────────────────┴────────────────────────────┘
局域网 IP / IPv6 直连 / Cloudflare 隧道（HTTPS，任何网络）
⚠️ 已知问题（尚待修复）
| # | 问题 | 影响与规避 |
|---|---|---|
| 1 | 部分网络无法建立 Cloudflare 快速隧道（运营商拦截 UDP 7844 等） | 隧道卡住时配对页有日志与超时诊断；可改用局域网 / 自行搭建固定隧道 |
| 2 | 快速隧道域名随机，重连后变化 | 出门前刷新一次二维码；永久固定需自建命名隧道 + 域名 |
| 3 | 手机端不支持应答「审批 / 提问确认」 | Agent 等待确认时需回电脑操作（下版本规划） |
| 4 | 无推送通知 | iPhone 锁屏后轮询暂停，解锁即恢复（下版本规划） |
| 5 | 局域网通道为明文 HTTP | 同一 Wi-Fi 内理论上可被嗅探；敏感场景请用隧道或 loopback + 隧道 组合 |
| 6 | 上传目录不自动清理 | 手动清理 ~/.dsh/dsh-remote-uploads/ |
| 7 | DSH 插件设置页的配置卡片在部分环境不渲染 | 已把关键配置全部搬到配对页；设置页渲染为后续优化 |
| 8 | macOS / Linux 未实测 | 移动页与核心逻辑跨平台；cloudflared 需自行下载对应版本 |
📌 注意事项
- 令牌 = 遥控钥匙：拿到令牌即可控制 DSH，请勿外传；配对页与令牌旋转仅限本机访问，隧道来源被强制隔离
- 防火墙：首次使用放行 node 入站（专用 + 公用都勾；手机热点通常算公用网络）
- 代理共存：系统代理模式无影响；TUN 模式请将
*.trycloudflare.com等设为 DIRECT - iPhone：同一时间只能运行一个 VPN；iOS 18 的 Safari「不安全连接警告」会拦 http 链接（设置 → App → Safari 关闭，或直接用隧道码）；微信扫码限制 http 外链，用系统相机扫
- 隐私：图片会发送给你配置的视觉引擎服务商；Key 只存本机（
~/.modlens/config.json，0600） - 完整说明见 docs/NOTES.zh-CN.md
🗂 目录结构
├── src/ # 插件源码（index/plugin/server/api/settings-scope + 静态页面）
├── tools/gen-qr.mjs # 离线二维码生成器（可选工具）
├── docs/ # 使用文档与注意事项
├── cordis.patch.yml # 插件行插入补丁
└── CHANGELOG.md # 更新日志
常见问题速查
| 现象 | 处理 |
|---|---|
| 手机提示「仅 HTTPS」 | 关闭 Safari「不安全连接警告」，或扫隧道码 |
| 页面空白 | 检查地址栏是否被改成 https://（删 s 重试 / 换 Chrome） |
| 只有局域网和 IPv6 码 | 点配对页「开启外网隧道」；看状态与日志 |
| 发图 Agent 读不懂 | 安装 modlens 并在配对页填视觉 Key |
| 只能看到部分消息 | 会话顶部点「↑ 加载更早的消息」 |
许可
MIT。内置组件：qrcode-generator（MIT）· cloudflared（Apache-2.0，仅随 tgz/Release 分发）。
