westanke/dsh-remote-bridge

dsh-remote-bridge

把 DSH 内核的私有 remote 协议翻译成版本化 REST，供手机与第三方客户端远程访问这台机器；桌面端则提供一个集中设置中心。

中文 · English

dsh-remote-bridge 是 DeepSeek Harness（DSH）的远程访问桥接插件：它把 DSH 内核的私有 remote 协议翻译成版本化的 REST 接口，让 dsh-companion（GitHub · Gitee）等受信任客户端在离开电脑后仍能使用同一套聊天、工作区与文件能力；桌面端在你的 DSH 设置里提供一个「手机设置」，内联七张设置卡片（根目录 / 远程访问 / 设备 / 识图 / 回收站 / 审计 / App 下载），每张卡片各自折叠、可多张同时展开。）。

界面默认中文，可随时切换 English。插件支持 Windows、macOS 和 Linux，安装包已经包含编译产物，不要求用户在服务器上重新构建。

版本警告：请务必使用 ≥ v2.0.4版本。

DSH 0.2.x 兼容性：本分支在上游 v1.0.0 的基础上增加了对 DSH 0.2.0-rc.2 的兼容层。

0.2.x 用 dsh-api-gateway 替换了提供 apiProxy 服务的 dsh-host-apiproxy，导致上游版本在

0.2.x 上无法启动（表现为「添加根目录返回 405」）。兼容层的完整说明——基于什么、为什么、改了什么、

测了什么——见 DSH 0.2.x 兼容性适配说明。

对 DSH 0.2.1-rc.2 的适配结论（2026-10-20 复核，依据 docs/project/DSH-0.2.1-ADAPTATION.md）：

本插件**刻意不 import 任何 @deepseek-ai/* 包**，全部宿主服务经结构类型 + Host 注入消费

（见 src/host/dsh-0.2-bridge.ts 头注释）。逐一到 0.2.1-rc.2 实装包核对：cordis.patch.yml

的 10 项 inject 服务名全部仍存在且签名未变，engines.dsh 在 0.2.1 被内核识别

（dsh-app-boot/lib/index.js 的 prepareProfileEntries），不满足时只把该 entry 置

disabled 并打 stderr，宿主进程不退出。故本插件无需改码即可运行于 0.2.1-rc.2。

两版的功能差异（重要）：inject 里只放两个版本都存在的服务 —— cordis 的 inject 是

硬依赖，任何一个服务缺失就整个插件不激活（CI 在 0.2.0-rc.2 基线上实锤过：

一度因为把 0.2.1 才有的服务写进 inject 而让插件在 0.2.0 上整体不激活）。

因此 0.2.1 才提供的服务（后台任务 jobController、权限档位目录

permissionPresets、文件上传 fileUploads、附件存储 attachments）改为运行时经

ctx.reflect.get(name, false) 读取：**0.2.1-rc.2 上这些功能全部可用，0.2.0-rc.2 上

自动降级**（如后台任务端点返回 404、权限档位走内置目录），插件本体两种内核都能跑。

用 GET /api/v1/debug/host-services 可以查这台机器上哪些可选能力可用。

实际效果

桌面端的入口就在你的 DSH 设置里：打开设置，找到标题为「📱 手机设置」的一节，点进去直接内联渲染七张折叠卡片，不再另开弹窗。它只做设置。

远程访问默认关闭。管理员可在本机 WebUI 中设置绑定 IP、端口和新设备的初始权限。

关于这几张截图。 assets/screenshots/ 下的四张图由 scripts/generate-screenshots.ts 生成，它用与测试同一份产出来源渲染面板 —— ADMIN_TABS、WORKSPACE_CSS、APP_QR_CODES 全部取自 src/client/，所以你看到的是发布包里的标记与样式表，不是另画的示意图。图中呈现的是一台刚装好插件、尚未启用远程访问的机器，这是最诚实的默认状态。本 README 早前曾放过两张界面截图，但都摄于改名之前（标题还是「DSH 文件工作区」，远程访问那张还标着 v1.0.0，且把文件树与设置显示成上下两个弹窗），与上文描述的形态已不符，于是撤掉而不是留着误导。

市场会从 screenshots.json 自动取用这些图 —— 不必再来提 PR、不必等维护者。换了图直接推自己的仓库即可，下一次构建自动生效。

关于改名（2.0.4）

插件由 dsh-workspace 改名为 dsh-remote-bridge。改名理由是：旧名字比内容窄——插件实际承担的是「把 DSH 内核的私有 remote 协议翻译成版本化 REST，供手机端远程访问这台机器」再加一个设置中心，而「workspace」只是其中一页。

改名只动「安装时叫什么、bundle 叫什么」，以下几处对外契约刻意保持不变：

保持不变 · 位置 · 为什么不能改 REST 前缀 /dsh-workspace-api · src/host/server.ts · 已发布的 App 把它写死了 状态目录（dataDir，默认 dsh-workspace） · DSH profile 配置 · 换目录等于让用户的授权根配置与回收站全部消失

已不再列入契约的两项（2.2.0 随独立页一并退役）：

• 独立页路径 `/dsh-workspace`：该页面（文件树 + CodeMirror 编辑器）已删除，路径随之下线。注意它与 REST 前缀 /dsh-workspace-api 是两回事 —— 前缀还在，是 App 的对外契约；页面没了，不再承诺任何东西。
• 浏览器存储键 `dsh-workspace-device-token`：它只被那个已删的页面读写过，现在全仓库（含 App）已无任何读写方。一个没人读的键不构成契约，所以不列入上表；键名本身也不回收，以免日后排查时多一个迷惑项。

所以安装后看到 REST 地址或状态目录里仍然是 dsh-workspace，是预期行为，不是改名没改干净。

快速安装

环境要求

• 已安装并能正常启动的 DeepSeek Harness WebUI
• DSH 内核 `>=0.2.0-rc.2 <0.3.0`（兼容 0.2.0-rc.2 及其后全部 0.2.x，含 0.2.1-rc.2；由本分支的兼容层支持，见 DSH 0.2.x 兼容性适配说明）。

package.json 的 engines.dsh 已声明同一范围 —— 内核按 semver 裁决，不满足时该插件被禁用（宿主进程不退出），用户可按内核提示授予精确版本豁免。

• Node.js ^22.19.0 或 >=24.0.0
• 默认端口 3090 可用，或准备一个其他端口

使用运行 DSH WebUI 的同一系统用户执行。推荐用 npm 包名（三种方式装的是同一份产物）：

# ① npm 包名（推荐：装的是预构建产物，不需要 pnpm 的构建授权）
dsh plugin --profile web add dsh-remote-bridge

# 国内镜像更快时，指定 registry
dsh plugin --profile web add dsh-remote-bridge --registry https://registry.npmmirror.com

# ② GitHub Release 的 tarball
dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.5.0/dsh-remote-bridge-v2.5.0.tgz

# ③ Gitee Release 的 tarball（国内访问更快）
dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.0/dsh-remote-bridge-v2.5.0.tgz

npx @deepseek-ai/dsh web

dsh plugin add 底层就是 pnpm add，因此 --registry 等 pnpm 选项可直接使用。

本 README 由 GitHub 与 Gitee 共用同一份文件，因此凡是必须带主机名的地址（安装命令、Release 下载）

都会把两站都列出来 —— 相对链接可以跟着站点走，但 /releases/download/... 没有相对形式。

npm 包名与 GitHub 上的仓库同名，两站看到的都一样。

重启 DSH 后，打开设置就能看到「手机设置」。它是纯设置，不含文件树；会话视图中工具轨迹旁的「文件」标签页已在 2.0.4 移除。桌面端不再有浏览或编辑文件的界面：独立页 /dsh-workspace 已在 2.2.0 删除，文件操作请走手机 App，或在会话里让 agent 用工具完成。

从 GitHub Release 下载离线安装包时，可直接安装 tarball：

dsh plugin --profile web add ./dsh-remote-bridge-v2.5.0.tgz

第一次使用

1. 打开 DSH 设置，进入「手机设置」；默认落在「根目录」页）。
2. 在「根目录」页默认添加允许管理的DSH当前目录。
3. 需要连接手机时，进入「远程访问」，填写绑定 IP 和端口并保存。
4. 点击“启用并创建配对”，再将十分钟内有效的一次性配对码填入 App。
5. 在手机 App 的文件页里选择授权根，即可浏览和编辑文件。

远程访问只有在至少存在一个授权根时才能开启。安装插件本身不会把服务暴露到局域网，未启用时只监听回环地址。

你可以做什么

桌面端不再有文件管理界面

2.2.0 删除了独立页 /dsh-workspace，包括整个文件树、上传下载入口和 CodeMirror 6 编辑器。原因是手机 App 的文件页已经原生覆盖同一套能力，桌面端这个页面没人用，却让发布包从 0.25 MB 撑到 1.72 MB。

代价要说清楚：现在在电脑上动文件只剩两条路 ——

1. 在会话里对 agent 说话，让它用工具读写文件；
2. 打开终端自己操作。

手机端不受影响：App 的文件页照旧可用，走的是插件保留的同一套 REST 文件接口（/dsh-workspace-api 前缀与 /roots、/roots/{rootId}/content 等端点一个都没删）。回收站里的删除记录现在只来自手机 App。

桌面端设置面板

入口在 DSH 设置里，标题为「手机设置」。设置区内联渲染，不另开弹窗；七张折叠卡片平铺，可多张同时展开，默认展开「根目录」：

分区 · 用途 根目录 · 添加、移除授权目录并设置显示名称；DSH 当前的工作区会作为默认根自动登记（不可删除，但可正常访问） 远程访问 · 设置绑定 IP / 端口，启用远程访问并创建配对码 设备 · 查看设备权限与根目录授权，随时撤销 识图 · 设置图片交接目录（识图路径），并只读展示出厂默认 .dsh-images 与兜底目录 回收站 · 查看与恢复被删除的条目（只列出来自手机 App 的删除记录） 审计 · 查看操作类型与对象的审计记录 App 下载 · 扫码下载 Android 客户端，二维码指向两个站点的 Releases 列表页

图片交接：手机发的图，桌面也看得见

模型看不到图时（纯文本模型），本插件会在发消息之前把图存成工作区文件，消息里只留两样东西：一句人话（图存在哪、要看图怎么办）+ 一行给识图工具读的绝对路径。

现在 DSH WebUI 也会在该轮末尾把这张图画出来 —— 点击看原图、Escape 或点任意处关闭，图下面仍然保留那条路径。手机 App 那边一直可以显示，桌面这边此前只有一段文字；两边现在一致了。

• 落点：//.，文件名是内容哈希，所以同一张图反复发不会堆副本（目录 0700、文件 0600）。
• 识图路径默认 .dsh-images，在设置页「识图」里可以改，改完立即生效、不需要重启；「当前默认」那一栏是只读的 —— 历史交接消息和识图工具都按它写过路径，它不跟着你的修改走。旁边还列出解析不出会话工作目录时用的兜底目录。
• 只认交接句式，而且只认你自己发的那条消息：助手正文、上下文注入、工具输出里出现的 .dsh-images/… 不会被渲染成图（对话里到处都是这种引用，读它们只会把别人的话切成碎图）。

如果你此前装过 dsh-image-paths，请把它那一行停用：两个插件的图集会挂在同一个位置，同一张图会被画两遍。本插件已自带这套能力。

连接 Android App 或其他客户端

配套的 Android 客户端是 dsh-companion（Gitee）。 用手机扫描下面任意一个码即可下载 —— 两个码都指向对应站点的 Releases 列表页， 所以发新版不需要更换二维码：

GitHub · Gitee（国内访问更快） · ·

二维码里写的是 Releases 列表页，不是某个具体的 APK 文件名 ——

装好 App 后，在「手机设置 → 远程访问」里生成配置文本或配对码即可连上本机。 公开 API 不依赖 DSH 私有协议，也可用于其他客户端：

• 查看、新建、重命名和移除 DSH 工作区登记。
• 创建、重命名、分叉和归档会话。
• 读取消息、流式接收正文和思考、追加引导或取消运行。
• 查看 TODO、斜杠命令、权限模式和待审批操作。
• 选择 Agent、模型和思考强度。
• 查看或修改模型供应商，支持完全自定义供应商。
• 管理设备获准访问的文件和回收站项目。

远程访问与安全

默认远程地址为 0.0.0.0:3090，IP 和端口都可修改。客户端可以使用能到达服务器的 IP 或域名连接。

插件允许直接使用 HTTP，不强制配置证书。这对可信局域网和临时部署比较方便，但要清楚它的代价：

HTTP 会明文传输设备令牌、聊天内容和文件内容。在公网或不可信网络中，请使用 Caddy/Nginx 配置 HTTPS，或通过 VPN、Tailscale/WireGuard、SSH 隧道等可信通道连接。

无论是否使用 HTTPS，以下保护都会生效：

• 十分钟有效且只能使用一次的配对码。
• 256 位设备令牌，服务器只保存摘要。
• 可撤销的设备权限与独立根目录授权。
• 配对、认证和普通请求分别限流。
• 审计记录操作类型和对象，但不记录令牌、文件正文或聊天正文。
• 新增根目录不会自动授权给已经配对的设备。

只有来自回环地址的管理界面可以添加根目录、调整设备权限、生成配对码、修改监听设置和永久清理回收站。