DSH Remote

把电脑上的 DSH，带到你的掌心。

DSH Remote 是一套面向 DSH 的远程控制台：在手机或另一台电脑上查看会话、处理审批与提问、传输文件，并掌握主机运行状态。

中文 · English

DSH Remote 由 DSH 插件、独立网关和多端客户端组成。插件负责在 DSH 侧提供入口并管理网关；网关负责鉴权、实时连接和文件传输；客户端包括 Android、HarmonyOS 应用以及手机和桌面浏览器中的 WebUI。

3 分钟开始连接

dsh plugin --profile web add dsh-remote-plugin

完整重启 DSH Web 后，从侧栏打开 DSH Remote。管理控制台会按顺序检查 DSH、网关、局域网地址、主机防火墙、终端配对与实时通道；跟随提示启动网关并扫码，即可在手机继续会话。详细步骤和故障排查见快速开始。

手机和电脑应位于同一可信局域网，或通过 Tailscale 互通。不要把网关端口直接暴露到公网，也不要公开配对令牌。

✨ 为什么是 DSH Remote

🧩 三个部分，各司其职

🔐 令牌就是远程控制凭证。默认不额外引入账号系统，部署简单，但请像保护 SSH 密钥一样保护它。

🖼️ 应用内截图

真实界面示例，截图中的会话标题、地址和令牌已做模糊处理。

🎯 适合什么场景

• DSH 在电脑上运行，但你想用手机查看会话、回复提问或处理工具审批。
• 你需要在手机与 DSH 工作目录之间传输文件，或把图片作为当前会话的附件发送。
• 你需要从另一台电脑查看会话、文件、Token 统计和设备连接状态。
• 你希望通过局域网或 Tailscale 访问，而不为 DSH 额外搭建账号系统。

🧭 当前界面

📱 手机端 / Android 应用

手机端进入后默认显示主页，底部导航为：

底部导航中的插件页提供独立管理入口；主页保留简要用量，会话顶部的统计按钮可查看 Token、费用和趋势。

会话详情页支持实时消息、历史加载、目标控制、子代理中断、斜杠命令、模型切换、模型级思考档位和全屏输入。繁忙时可排队发送；设置中还可启用长按插队发送（默认关闭），插队请求被 DSH 接受不代表当前工具已经中断。设置 → 模型中可为自定义提供方的每个模型配置档位名称、档位值、说明和默认档位；选择结果通过 DSH 适配器转换为第三方接口参数。全屏输入会保留会话标题栏，发送动作上移到标题栏；退出全屏可以点击收起按钮、下滑顶部手柄或使用系统返回键。

图片附件入口支持拍照和相册选择。图片会作为 session.prompt 的图片内容发送到当前 DSH 会话；图片能力仍取决于当前 DSH 组合和模型路由是否支持图像输入。

🌿 HarmonyOS 应用

仓库包含使用 ArkTS / ArkUI 编写的鸿蒙客户端源码，支持手机布局和平板分栏，并连接同一网关。本次 0.7.3 不包含鸿蒙 HAP 安装包。构建与签名说明见 HarmonyOS 工程说明及客户端模块文档；未签名 HAP 需使用自己的 DevEco 签名配置后才能安装。当前关于页致谢改动尚未构建或真机验证。

🖥️ 桌面端 WebUI

电脑浏览器打开网关地址时会自动进入桌面布局：

• 左侧会话列表与工作台项目；
• 文件传输；
• 主页总览；
• 统计抽屉；
• 设置、服务器分组和主题切换；
• 审批 / 提问通知卡片栈。

🛠️ 插件面板与管理控制台

DSH 插件入口提供快速状态面板，可查看网关运行情况、设备数、Token 用量和快捷操作。进入管理控制台后可以查看：

• 网关版本、运行时长、端口和 DSH 上游状态；
• 主机 IP、已连接设备、请求数、通道和最后活跃时间；
• Token 统计与近 7 日峰谷用量；
• 令牌复制、二维码配对和令牌轮换；
• 首次连接向导与 Doctor 自检，逐项显示 DSH、网关、网络、终端和实时链路状态；
• 网关启动 / 停止、自愈设置和更新检查。

🧩 插件管理与会话洞察

手机端和桌面端的“插件”页面提供已安装列表、插件发现、安装、更新、卸载、配置启停与操作记录。可用操作取决于主机端管理能力；无法确认管理入口时显示只读状态。DSH Desktop 使用桌面版自带的插件管理入口。详见插件中心说明。

打开会话后，点击标题栏“更多操作”中的“上下文与费用”可查看两个只读面板：上下文组成与占用依赖主机安装并启用 dsh-context；会话费用、余额和套餐用量依赖 dsh-cost-meter 及主机端 Remote 插件支持。没有数据时显示缺失或不可用状态，费用估算以供应商账单为准，且不与 Remote 自身的统计金额合并。鸿蒙尚未同步这两个面板，详见会话洞察说明。

📝 0.7.3 界面更新

0.7.3 包含以下界面更新，鸿蒙相关内容仅为源码改动：

• 手机和桌面端隐藏 DSH 标记为 blank 的空会话，主列表、工作区树与主页统计保持一致；会话开始首轮对话后恢复显示，原始会话与子代理数据仍保留。
• “设置 → 关于”新增离线贡献者致谢与完整贡献记录入口，按 GitHub 贡献提交数降序排列；鸿蒙在“关于 DSH Remote”弹窗中提供名单。鸿蒙构建与真机验收仍待完成。

📦 下载

所有正式版资产位于 GitHub Releases。RC 版本只用于真机验收，不会替代 Latest 正式版。

🚀 快速开始：插件模式（推荐）

先确认 DSH Web 本身可以在这台电脑上正常打开，然后在安装 DSH 的同一用户下执行：

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

第二条命令用于确认插件确实装进了 web profile。接着：

1. 完整重启 DSH Web 进程。如果你是手动运行 dsh web，先停止旧进程再重新运行；如果你配置了 systemd 用户服务，可执行 systemctl --user restart dsh-web。
2. 在 DSH Web 中执行一次 Ctrl+F5，从左侧入口打开 DSH Remote 面板。
3. 在插件面板确认“网关已运行”，然后先在 DSH 主机上打开 http://127.0.0.1:8787/health。看到 JSON 即表示网关端口已可用。
4. 从插件面板复制令牌或打开配对二维码。令牌也保存在 ~/.dsh-remote/token，请勿公开。
5. 在 Android 应用或已安装的 HarmonyOS 客户端的「设置 → 服务器」中扫码，或手动填写 http://电脑局域网IP:8787 和令牌。手机中不能填 127.0.0.1 或 localhost，它们指向手机自己。
6. 另一台电脑可直接打开 http://DSH主机IP:8787，桌面浏览器会进入桌面 WebUI。

稳定版使用 npm 的 latest 标签，RC 使用 next 标签；需要固定版本时可将标签换成明确版本号。也可以从 Git 源安装：

# 安装 npm 稳定版
dsh plugin --profile web add dsh-remote-plugin@latest

# 安装 RC 版
dsh plugin --profile web add dsh-remote-plugin@next

# monorepo 插件目录
dsh plugin --profile web add "github:Blank-not-black/dsh-Remote#main&path:/packages/plugin"

插件内置网关，默认监听 0.0.0.0:8787，并随 DSH 自动启动和自愈。网关意图保存在 ~/.dsh-remote/gateway.enabled，令牌保存在 ~/.dsh-remote/token。

🩺 网关打不开：按顺序排查

先在 DSH 所在电脑 上测试，再测手机。这样可以快速区分“网关没启动”和“网络无法到达”。

# 1. 网关是否在监听
curl -i http://127.0.0.1:8787/health

# 2. Linux 查看 8787 端口的真实占用者
ss -ltnp | grep ':8787'

# 3. DSH Web 上游是否可访问（默认 3080）
curl -i http://127.0.0.1:3080/

Windows 可用 netstat -ano | findstr :8787，或在 PowerShell 执行 Invoke-RestMethod http://127.0.0.1:8787/health。

如果使用 systemd 运行 DSH，还可查看：

systemctl --user status dsh-web --no-pager
journalctl --user -u dsh-web -n 100 --no-pager

插件拉起的网关可能是 transient 进程，不要把 systemctl --user restart dsh-remote-gateway.service 作为通用重启方式。优先使用插件面板的“启动网关”，或重启 DSH Web 让插件自愈拉起。发布日志或截图前，请隐藏令牌。

🧰 独立网关模式

不使用 DSH 插件时，可以直接下载对应平台的单文件网关：

./dsh-remote-linux-x64

# 自定义端口或固定令牌
PORT=9000 TOKEN=your-token ./dsh-remote-linux-x64

默认上游为本机 DSH Web http://127.0.0.1:3080，默认监听 0.0.0.0:8787。管理页地址为 http://127.0.0.1:8787/admin。

Docker/面板部署时，容器通常只能枚举容器网卡。可用 DSH_REMOTE_ADVERTISE_HOSTS=192.168.1.20,100.64.0.2 显式加入手机可访问的宿主 IP/主机名，或在管理页“主机 IP 地址”中手动添加；这些地址会进入配对二维码。若 DSH 生命周期由 Docker Compose、面板或其他外部平台负责，设置 DSH_REMOTE_DSH_CONTROL_MODE=disabled，前端会隐藏无效的启动/重启操作并显示外部管理提示。

📁 文件传输

手机端和桌面端都可以使用文件页。网关文件端点受到 Bearer token 保护：Windows 默认允许当前用户目录及 C 盘以外的可用盘符；Linux/macOS 默认允许当前用户目录，并会向本机 DSH 校验后自动允许 workspace.list 中已登记的工作区目录。

• 默认单文件上限为 2GB，可通过 DSH_REMOTE_FS_MAX_UPLOAD 调整；
• 上传支持分块、断点续传、暂停、继续和取消；
• 完成上传前进行 SHA-256 校验，校验通过后再原子落位；
• 拒绝 ../ 路径穿越、绝对路径逃逸和指向允许根目录之外的符号链接；
• 可用 DSH_REMOTE_FS_ROOT 显式覆盖默认文件根，Linux/macOS 使用 : 分隔，Windows 使用 ; 分隔；显式配置模式仍兼容 DSH 已登记工作区。

Windows 文件树支持 C:\Users\... 盘符路径、正反斜杠输入和 UNC 共享路径。文件页的目录选择器默认列出当前用户目录和启动时可用的其他盘符（如 D:\、E:\），可跨盘浏览并创建工作区。默认模式下，C 盘其他用户和系统目录即使登记为 DSH 工作区也不会开放，其他盘符上的 junction 指向这些目录同样会被拒绝。新挂载磁盘后重启网关即可发现；UNC 共享需要显式授权。访问仍受运行网关的 Windows 账户权限限制。

示例：

TOKEN=$(cat ~/.dsh-remote/token)
HOST=http://127.0.0.1:8787

curl -H "Authorization: Bearer $TOKEN" "$HOST/fs/list"
curl -OJ -H "Authorization: Bearer $TOKEN" "$HOST/fs/file?path=~/Downloads/example.zip"
curl -H "Authorization: Bearer $TOKEN" --data-binary @./photo.jpg \
  "$HOST/fs/upload?path=~/Downloads&name=photo.jpg"

🌐 远程访问与安全

• 局域网访问：手机和电脑在同一网络，访问电脑的局域网 IP；
• Tailscale：两端加入同一网络后，使用电脑的 100.x.x.x 地址；
• 公网隧道：只使用带认证、可靠支持 WebSocket 的方案，并限制暴露范围。

网关默认监听所有网卡，令牌等同于 DSH 的远程操作凭证。请不要把令牌提交到仓库、截图公开或写入 URL 后转发给他人。实时连接使用 WebSocket；连续失败后会自动降级为轮询，恢复后再切回实时通道。

网关控制台可以选择开启「独立设备密钥」。开启后，共享令牌只用于进入管理控制台，每台手机或浏览器使用各自的设备令牌；控制台按“备注、最近 IP、Token”列出设备密钥，并支持分别生成二维码、轮换、复制和退出。开启或关闭模式、轮换令牌、退出设备时，受影响的现有实时连接会立即断开，避免旧凭证继续使用。独立设备密钥保存在 ~/.dsh-remote/device-keys.json，文件权限会收紧为仅当前用户可读写；可用 DSH_REMOTE_DEVICE_KEYS 覆盖保存位置。

/health 同时返回 protocol.version 和 capabilities。新版 App 会根据明确声明的能力选择短时 WebSocket ticket、DSH 生命周期控制等路径；旧网关没有能力声明时仍按兼容路径尝试，不会仅因缺少该字段拒绝连接。

若用 Caddy Basic Auth 保护插件页面，请让 /remote/ 页面及 /remote/admin/api/* 使用同一登录规则。插件内嵌管理页不会再发送 Bearer Authorization 覆盖浏览器的 Basic 凭据；若代理把 API 重写到登录页，页面会显示“登录代理拦截了管理 API”，而不是清除 Remote token 并反复登录。

🔔 通知、公告与后台轮询

• 通知设置支持审批 / 提问通知、峰谷提醒、后台轮询和任务结束通知；
• 「设置 → 通知 → 历史公告」会保存已获取的公告，方便再次查看；
• 公告默认从项目的中央 HTTPS 公告源读取，网关会短时缓存并在中央源不可达时回退安装包内的 announcements.json，格式如下：

{
  "items": [
    {
      "id": "example-announcement",
      "title": "公告示例",
      "content": "这是一条公告示例。",
      "minVersion": "0.1.0",
      "publishedAt": "2026-09-24T10:00:00+08:00",
      "expiresAt": "2026-12-31T23:59:59+08:00",
      "actionUrl": "https://github.com/Blank-not-black/dsh-Remote/releases",
      "actionText": "查看版本详情",
      "poll": {
        "id": "example-poll",
        "question": "下一步你更希望优先改进什么？",
        "options": [
          { "id": "stability", "label": "连接稳定性", "description": "继续优化弱网和重连" },
          { "id": "files", "label": "文件能力", "description": "增加更多预览与管理功能" }
        ]
      }
    }
  ]
}

公告按版本、发布时间和有效期筛选，内容按纯文本展示，不执行远端 HTML 或脚本；需要用户确认后才能关闭时可设置 "force": true。

投票为单选，每个公告支持 2–8 个选项。网关会根据中央公告缓存（中央源不可达时回退内置文件）校验 announcementId、pollId 和 optionId，不接受客户端伪造的选项名；合法投票会通过现有反馈收集器提交结构化字段，同时用稳定的 POLL {...} 文本兼容只保留通用字段的旧收集器。App 在网关无地址、网络失败或令牌失效时可直连同一公网收集器托底，普通反馈仍只走网关；直连端点需允许 App/Web 的 CORS。客户端只在服务端确认成功后记录“已投票”；未投票的公告可从历史公告再次打开。系统不收集账号，网关路径仍使用原有的频率限制和脱敏 IP。

可以直接对收集器的 JSONL 文件生成去标识化计数和百分比，脚本不输出联系方式或 IP：

node scripts/summarize-polls.mjs /path/to/feedback.jsonl
node scripts/summarize-polls.mjs /path/to/feedback.jsonl --json

App/页面启动后约 4 秒检查公告，前台运行时每 30 秒检查一次；重新回到前台或网络恢复时也会立即补查。网关默认从 https://vm-0-2-ubuntu.tail1f6fc4.ts.net/announcements.json 读取中央公告，15 秒内复用缓存，中央源失败时优先保留上次成功内容，冷启动失败才回退内置文件。可用 DSH_REMOTE_ANNOUNCEMENTS_URL 覆盖中央源，设为空字符串则完全禁用中央源；自定义公网地址必须使用 HTTPS（仅测试时允许 localhost HTTP）。

维护者更新 public/announcements.json 后运行 bash scripts/sync-central-announcements.sh，即可原子上传并回读验证中央公告。中央源只提供经过大小和 JSON 结构校验的公开数据，公告正文仍按纯文本展示，不执行远端 HTML 或脚本。

Android 后台轮询由前台服务执行，间隔为 30 秒、1 分钟、5 分钟或 15 分钟。灭屏后的 Doze 策略可能拉长实际间隔；部分系统还需要允许应用自启动、后台运行和不受限电量使用。

🎨 主题与反馈

当前提供五套配色：默认深空、落日、易北爱乐厅、草原孤塔、黑曜白。主题变量同时作用于页面、图标和状态色，避免切换皮肤后图标融入背景。

App、桌面端和管理页都提供反馈入口。App / 桌面端的「写反馈」会通过网关转发到反馈收集器，也可以直接提交 GitHub Issues。

🧪 开发与发布

项目约束：零新增运行时依赖（Node、WebUI、Android 和鸿蒙端使用系统与内置能力，不引入第三方运行时库）、单文件网关、零构建纯 JavaScript WebUI。修改 WebUI 时只编辑根目录 public/，然后同步插件副本。

npm install
npm run check          # 语法检查 + Node 测试
npm run sync-plugin    # 同步 public/、gateway.cjs 与插件资源
npm run build-app      # 构建 Android APK
npm run publish        # 复制 APK、生成 update.json 并同步插件
npm run build-bin      # 构建 Windows/Linux 单文件网关

模块结构、功能边界、实现方式、数据契约和 Vibe Coding 变更规则见模块文档与开发规范。

RC 和稳定版均使用以下命令发布；版本号格式为 x.y.z 或 x.y.z-rc.N。执行前将占位符替换为目标版本：

npm run release <版本号>

发布脚本会更新版本元数据、本地构建 Android APK、同步插件，并提交推送 main 和版本 tag。GitHub Actions 构建 Android APK 与 Windows/Linux 单文件网关，生成 SHA256SUMS.txt，上传 GitHub Release、发布 npm 包并同步独立插件仓库。RC 发布使用 npm next 标签，稳定版使用 latest。--no-build 可跳过本地 APK 构建，交由 CI 构建发布资产。

🗂️ 项目结构

gateway.js                 # 单文件网关
public/                    # 手机端、桌面端、管理页与公共资源
packages/plugin/           # DSH 插件及同步后的插件资源
android/                   # Capacitor Android 工程
harmonyos/                 # HarmonyOS 客户端（ArkTS/ArkUI，侧载分发）
docs/modules/              # 模块说明、跨端契约与 Vibe Coding 规范
tests/                     # 网关、Markdown、统计测试
scripts/                   # 同步、构建、发布脚本

🤝 贡献者与致谢

感谢每一位为 DSH Remote 提交代码、修复问题、完善文档和提供反馈的贡献者。

以下按 GitHub 统计的贡献提交数降序排列，同数量时按用户名排序，与客户端的致谢名单一致：

1. Blank-not-black
2. wikkd
3. anupamme
4. liuchang-t

更多贡献记录见 GitHub Contributors。当前开发版本也可在手机和桌面的 设置 → 关于 查看离线致谢名单与个人主页链接；鸿蒙入口为 设置 → 关于 DSH Remote。

☕ 支持项目

如果 DSH Remote 对你的工作流有帮助，欢迎给项目点一个 Star，或请作者喝杯咖啡。每一份反馈、Issue、PR 和赞赏，都会帮助这个小工具继续变得更可靠。

License

MIT

Windows Desktop 远程控制（实验性）

Desktop 加载 Remote 插件后自动记录经过核验的桌面程序路径、主进程与 Host 身份、配置目录和上游地址。网关在线时，手机设置中的 DSH 控制可以启动或重启 Desktop。重启会关闭并重新打开桌面程序，正在执行的任务会中断。网关只控制身份和端口归属均匹配的实例；身份变化、端口被其他进程占用或 Host 未退出时拒绝操作，不按进程名称批量结束进程。电脑关机或网关未运行时不能远程启动；此功能不会自动注册 Windows 登录自启。

对话缓存与崩溃恢复（0.7.3）

手机和桌面 WebUI 会先读取当前连接身份对应的本地历史，再后台拉取并比对 DSH 历史；内容一致时复用消息节点，保留滚动位置。界面明确显示缓存、同步或离线状态。单次布局最多包含 180 条记录，旧记录分批载入，内存最多保留 5,000 条；回到最新可重新拉取尾部。IndexedDB 按连接身份保存最近 10 个会话、每会话最多 250 条及约 750,000 字符的事件数据，失败时使用有界本地存储。缓存仅在当前设备保存；移动端“重置本地设置”也会清除缓存。

插件自动启动的网关及 npm start 使用同一单文件网关的监督模式；直接运行时可用 node gateway.js --supervise（独立二进制可加 --supervise）。异常退出按 1、2、4、8、16 秒退避恢复，5 分钟内最多尝试 5 次。主动停止和端口冲突不会重启。本网关启动并持有句柄的 DSH 进程可按异常退出恢复；已运行的 Windows Desktop 则必须核对应用错误事件 1000、启动时间、可执行文件及 PID，普通关闭和上游网络不可达不会触发重启。外部 Docker、系统服务及启动器继续负责各自的恢复。

设置 DSH_REMOTE_AUTO_RESTART=0 可关闭自动恢复。结构化诊断默认写入 ~/.dsh-remote/crashes.jsonl，约 128 KiB 轮转并保留一个备份；可用 DSH_REMOTE_CRASH_LOG_FILE 指定路径。记录时间、组件、退出码、重试次数和源码位置，不记录任意错误正文、对话或密钥。反馈页的“附带崩溃日志摘要”默认不勾选，可预览最近最多 3 条摘要；主动提交时经原有 /feedback → 云端 /submit 通道上传，兼容现有收集器的 serverInfo 字段（最多 500 字符），不会自动上传完整本机日志。电脑或监督进程本身被结束后不能保证恢复，Desktop 自动恢复也依赖 Windows 能提供匹配的崩溃事件。