# dsh-bridge

**Repository Path**: dtnsman/dsh-bridge

## Basic Information

- **Project Name**: dsh-bridge
- **Description**: DSH Bridge: lightweight HTTP/SSE bridge for DeepSeek Harness control plane, with DSH-Hosts Android multi-host client.
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-27
- **Last Updated**: 2026-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dsh-bridge

> 把本机 **DeepSeek Harness（DSH）** 的控制面，变成任何设备、任何脚本都能调用的 HTTP / SSE API。

[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)

- 纯 Node.js 实现，运行时依赖只有一个 `ws`
- 同时提供 HTTP REST 端点与 SSE 流式事件
- 内置隧道客户端，无需额外部署 frp / ngrok
- 附带单文件调试页 `dsh-proxy-hosts.html` 与 **Android 多主机管理应用 `DSH-Hosts`**

---

## 1. 它解决什么问题

DSH 桌面版是个很好用的本机 AI 工作台，但它的能力被锁在一台电脑的一块屏幕里。dsh-bridge 要解决的就是这件事：

| # | 真实痛点 | 没有 dsh-bridge 时 | dsh-bridge 的做法 |
|---|---|---|---|
| 1 | **只能坐在电脑前** | 桌面 GUI 绑定本机，离开电脑就没法看任务、发指令 | 把控制面完整暴露成 HTTP/SSE，手机、平板、脚本、其他 Agent 都能调用 |
| 2 | **想自动化但没有入口** | DSH 走 WebSocket RPC，还要先铸造带 HMAC 签名的 cookie，自己写客户端要处理鉴权、mux 多路复用、断线重连 | 这些全部封装好，一条 `curl` 就能发指令 |
| 3 | **出门在外想盯一眼** | 没有移动端，任务跑着也看不到 | 内置隧道 + Android 客户端，手机上直接连回家里的机器 |
| 4 | **多台机器各跑一个 DSH** | 地址、端口、clientId 逐个记，来回切换很烦 | 客户端集中保存多主机配置，一键切换 |
| 5 | **通用隧道“只搬字节”** | ngrok / frp 不理解 DSH 的流式事件与审批瀑布，SSE 常被缓冲打断 | 隧道内建 DSH 语义：自动应答审批、转发 SSE、维护任务索引 |
| 6 | **脚本状态容易丢** | 自己写的调用代码重启后不知道任务跑到哪一步 | `TaskRegistry` 持久化任务状态，重连后还能查询 |

一句话：**它不替代 DSH，而是把 DSH 从“桌面软件”变成“可被程序调用的服务”。**

---

## 2. 与市面同类方案的定位对比

> 下表的比较只在**能力维度**上说明定位差异。每个项目在自己的领域都更成熟，这里不评价优劣，只帮你判断该用哪个。

| 方案 | 它擅长什么 | 局限 | 与本项目的关系 |
|---|---|---|---|
| **dsh-bridge**（本项目） | 把 DSH 控制面语义化地暴露成 REST + SSE，并打通移动端 | 只服务于 DSH，不是通用网关 | — |
| **通用内网穿透**<br>ngrok / Cloudflare Tunnel / frp | 把任意本地端口映射到公网，生态成熟、有官方托管 | 只管传输，不理解上层协议；SSE、二进制帧、审批回调需要自己兜底 | 本项目**自带隧道**；也可以直接叠加在这些工具后面用 |
| **Open WebUI** 等自托管 LLM 前端 | 漂亮的对话界面，接 Ollama / OpenAI 兼容接口 | 面向“聊天”，不控制桌面 Agent 的终端、工作区、任务生命周期 | 定位互补：它是前端，本项目是**控制面桥接** |
| **MCP Server** | 用标准协议把工具/资源暴露给 LLM 客户端 | 需要支持 MCP 的客户端；粒度偏“工具调用”，不覆盖会话/终端/任务管理 | 本项目是完整控制面 API，不做 MCP 替代 |
| **scrcpy / Termux** 等安卓工具 | 镜像手机屏幕、在手机上开终端 | 是“远程操作手机”，不是“管理多台 AI 主机” | 定位不同，可共存 |
| **直接对接 DSH 原生 RPC** | 最灵活，零中间层 | 要自己实现 cookie 铸造、mux 流、重连、SSE 转发、任务状态维护 | 本项目的底层就是这套，已经帮你写完了 |

---

## 3. 差异化竞争点

**① DSH 语义感知，而不是“裸转发”**

普通反代 / 隧道只知道转发字节。dsh-bridge 认识 DSH 的协议：`session/follow` 的流式帧、`$events` 的 `waterfall` 审批、`workspaceFiles/changes` 的增量，都由 bridge 负责接线与保活。

**② 一个依赖，零框架**

运行时只依赖 `ws`。没有 Express、没有数据库、没有构建步骤，`npm install && npm start` 就能跑，方便审计和二次改造。

**③ REST + SSE 双通道**

同步操作走普通 HTTP，实时输出走 SSE。标准 `EventSource` 直接可用，不需要额外 SDK，也不强制 WebSocket 客户端。

**④ 内置隧道，开箱即用**

不用先去注册 ngrok、部署 frp。`clientId` 稳定持久化在本地，重启后域名不变，手机上的旧链接不会失效。

**⑤ 端侧配套齐全**

仓库里同时有 Android 客户端（多主机管理）和单文件网页调试页。不用为了“看一眼状态”专门写个前端。

**⑥ 可完全自托管，数据不出本机**

整条链路可以只跑在自己的机器和自己的隧道上，任务内容、工作区文件、模型调用都不经过第三方 SaaS。

---

## 4. 适用与不适用

**适合你，如果：**

- 你在用 DSH，希望手机 / 平板 / 脚本 / 其他 Agent 也能操作它
- 你想把本机 AI 任务接进自己的自动化流程
- 你有多台机器跑 DSH，需要一个统一的入口
- 你更愿意自托管，而不是把工作内容交给云端服务

**可能不适合你，如果：**

- 你只是想找个聊天网页 —— 用 Open WebUI 这类前端更合适
- 你需要的是通用内网穿透 —— 直接用 frp / Cloudflare Tunnel
- 你希望零配置暴露到公网 —— 本项目默认只监听回环地址，公网访问需要你自己加鉴权和隔离

---

## 5. 特性

| 能力 | 说明 |
|---|---|
| 任务 Task | 创建、查询、取消任务 |
| 会话 Session | 会话列表、历史消息、发送消息 |
| 工作区 Workspace | 列出工作区、工作区文件读写 |
| 终端 Terminal | 执行命令、读取输出 |
| Job | 后台任务轮询与结果获取 |
| Skills / Commands / AgentPresets | 元数据枚举 |
| 通用 RPC 透传 | 任意 DSH RPC 方法直接转发 |
| SSE | 实时订阅事件流 |
| 多主机管理 | Android 应用集中管理多个 dsh-bridge 主机 |

---

## 6. 环境要求

- Node.js >= 18
- 本机已安装并可运行 DeepSeek Harness

## 7. 快速开始

```bash
npm install
npm start
```

默认监听 `http://127.0.0.1:10998`。

其他脚本：

```bash
npm run check   # 配置自检
npm run dev     # 开发模式（无隧道 + 详细日志）
```

## 8. 配置

配置通过环境变量覆盖，主要项：

| 变量 | 说明 |
|---|---|
| `DSH_BRIDGE_PORT` | 监听端口，默认 `10998` |
| `DSH_BRIDGE_HOST` | 监听地址，默认 `127.0.0.1` |
| `DSH_BRIDGE_VERBOSE` | 设为 `1` 输出详细日志 |

## 9. 目录结构

```text
bin/      命令行入口
src/      核心实现（路由、RPC、隧道、任务、事件等）
docs/     HTTP API 文档
release/  Android 应用安装包（DSH-Hosts.apk）
```

## 10. Android 应用：DSH-Hosts（多主机管理）

`release/DSH-Hosts.apk` 是给 DSH 配套的 **Android 客户端**，用于在一台手机上集中管理多台运行 `dsh-bridge` 的主机。

安装方式：把 APK 传到 Android 设备后点击安装（需允许「安装未知来源应用」）。

主要用途：

- 保存并切换多个 dsh-bridge 主机（不同机器 / 不同端口）
- 通过 HTTP API 连接各主机，查看任务、会话与事件流
- 配合 `dsh-proxy-hosts.html` 一起使用，移动端与桌面端共享同一套主机配置思路

> 注意：APK 为配套客户端，使用前请先在本机启动 `dsh-bridge` 服务。若需从手机访问，需让服务监听非回环地址（`DSH_BRIDGE_HOST=0.0.0.0`）并做好鉴权与网络隔离。

## 11. 文档

完整的端点说明、参数与典型流程见 [docs/HTTP-API.md](docs/HTTP-API.md)。

## 12. 调试页面

`dsh-proxy-hosts.html` 是随项目分发的单文件调试页，直接用浏览器打开即可（静态文件仅此一个随仓库发布）。

## 13. 安全说明

- 服务默认只绑定本机回环地址，请勿在无鉴权的情况下直接暴露到公网。
- **Bridge 的 HTTP 层本身没有入站鉴权**，任何能访问该端口的人都能控制 DSH；公网部署必须自行加防火墙、反向代理认证或仅允许隧道内访问。
- `EventBridge` 会自动应答 DSH 的审批瀑布（`allowed-once`），远程调用者可能绕过人工审批，生产环境请评估。
- 若需要对外访问，请自行置于反向代理与访问控制之后。

## 14. 许可证

[GPL-3.0](LICENSE)