# dsh-mobile-connector 中文文档

规范地址：https://npmcn.com/package/dsh-mobile-connector/

版本：0\.1\.18
npm 元数据更新时间：2026-11-03T12:46:13.230Z
中文译文更新时间：2026-11-03T12:58:53.799Z
软件包许可：PolyForm-Noncommercial-1\.0\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/dsh-mobile-connector
原文对照：https://npmcn.com/package/dsh-mobile-connector/?lang=original
项目主页：https://github.com/Imzl-zl/deepseek-harness-mobile/tree/main/connector
源码仓库：https://github.com/Imzl-zl/deepseek-harness-mobile

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：575 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.19\.0 \|\| \>=24\.0\.0
- 运行依赖：3 个
- peer 依赖：@deepseek-ai/cordis 4\.0\.5，@deepseek-ai/schemastery 3\.18\.5，@deepseek-ai/dsh-typert-protocol 0\.2\.1-rc\.5
- 首次发布：2026-10-30T15:45:23.602Z
- 最新版本发布：2026-11-03T12:46:12.527Z
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

DSH 插件:手机端远程通道的电脑侧桥接

## 安装

```sh
npm install dsh-mobile-connector
```

也可以使用：`pnpm add dsh-mobile-connector`、`yarn add dsh-mobile-connector`、`bun add dsh-mobile-connector`

## README

# dsh-mobile-connector

[![npm](https://img.shields.io/npm/v/dsh-mobile-connector)](https://www.npmjs.com/package/dsh-mobile-connector) [![npm downloads](https://img.shields.io/npm/dm/dsh-mobile-connector)](https://www.npmjs.com/package/dsh-mobile-connector) [![ci](https://github.com/Imzl-zl/deepseek-harness-mobile/actions/workflows/ci.yml/badge.svg)](https://github.com/Imzl-zl/deepseek-harness-mobile/actions/workflows/ci.yml) [![license](https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-blue)](https://github.com/Imzl-zl/deepseek-harness-mobile/blob/main/LICENSE)

**DSH 插件：手机端远程通道的电脑侧网关。** 装进 [DeepSeek Harness](https://github.com/Imzl-zl/deepseek-harness-mobile) 之后， 手机扫码就能连到这台电脑 —— 对话、轨迹、改动卡、审批与提问、子智能体与后台任务，都在手机上。

![DSH 侧边栏「手机」面板](https://raw.githubusercontent.com/Imzl-zl/deepseek-harness-mobile/main/docs/assets/plugin-panel.png)

装好之后，DSH 侧边栏多一个「手机」入口：总览 · 连接 · 通道与地址 · 已配对设备 · 配对码 · 版本

* * *

## 要求

| 项 | 版本 |
| --- | --- |
| DSH | `>=0.2.1-rc.5 <0.2.2` |
| Node | `^22.19.0 || >=24.0.0` |
| 对端 | 手机 App（[Release](https://github.com/Imzl-zl/deepseek-harness-mobile/releases) 里的 APK） |

## 安装

**两条通道，装哪个都行**（版本号可能不一致，见下）：

```bash
# ① npm（DSH 插件面板里按包名装 = 走这条）
dsh plugin --profile <profile> add dsh-mobile-connector

# ② GitHub Release 的 tgz（面板「安装」里也能直接粘这个 URL）
dsh plugin --profile <profile> add \
  https://github.com/Imzl-zl/deepseek-harness-mobile/releases/download/v0.2.3/dsh-mobile-connector-0.1.9.tgz
```

> **装完要重启一次 DSH**：插件热重载会让旧 fiber 先拆、新 fiber 再挂， 那一拍存储后端正在关，管理面可能挂不上（症状：面板 404、手机离线）。 新版已经对这一拍做了退避重试，但**当次**已经失败的那次挂载不会自己回来。

## 配置

三种写法等价，改哪个都生效（面板改的是 profile 的设置，不用重启）：

**A. 面板（推荐）** —— DSH 侧边栏「手机」→「连接」卡：

-   **中转**：`内置中转`（开箱即用）/ `自定义`（填自己的中转根地址）
-   **令牌**：粘贴中转的连接器令牌（只写不读，界面上不显示值）；令牌行可点「去注册 / 登录」打开中转。
-   **直连**：`8790`（局域网点对点用；`0` = 不开）

**B. profile 的 `cordis.patch.yml`：**

```yaml
- id: dsh-mobile-connector
  config:
    relayUrl: wss://relay.example.com/ws/connector   # 连接器拨的地址，带 /ws/connector
    relayTokenRef: relay-connector                   # 可选；不写就用默认格 relay-connector
    listenPort: 8790                                 # 局域直连端口，0 = 不开
    listenHost: 0.0.0.0
```

**C. 环境 / 凭据面**：令牌本体走 DSH 的 `ctx.credentials`，配置里只放**引用名**（`relayTokenRef`）。

> **地址形状容易搞错**：电脑侧这条是**连接器拨的**，带 `/ws/connector`； 手机侧拿到的是**根地址**，它自己拼 `/ws-ticket` 与 `/ws/device?ticket=`。

## 面板能做什么

| 区块 | 能做的事 |
| --- | --- |
| 总览 | 中转状态 · 在线台数 · 直连端口，一眼判断"这台电脑现在通不通" |
| 连接 | 选中转（内置 / 自定义）、写令牌、开/关直连端口，卡头直接保存 |
| 通道与地址 | 逐条启停（中转拨号 / 直连监听）· 删除不再上报的网卡地址（可恢复）· 追加一条不在枚举里的地址（Tailscale 这类） |
| 已配对设备 | 停用 / 启用 · 接管（换掉正在服务的那台）· **删除**（在用的也行：先停用拿终态，再抹记录） |
| 配对新手机 | 出二维码（5 分钟有效，同一台手机重扫替换旧记录） |
| 版本 | 当前插件版本 ·「检查更新」（电脑代查 npm 的 `latest`；查不到会说原因，不冒充"已是最新"） |

**停 ≠ 卸载**：停传输不清凭据、不动身份，再启动不用重扫。**断开 ≠ 解绑**：删设备才需要重新配对。

## 它怎么工作

-   **两条链路**：一条控制连接接收路由与名册通知；每台设备再拨一条独立数据连接。
-   **端到端加密**：每条连接现场协商密钥（X25519 + AEAD），手机只信任二维码里带出的电脑公钥；中转只转发密文与路由元数据。
-   **方法白名单**：只暴露列出的方法；审批 / 提问 / 任务走同一条通道，不另开端口。
-   **独占 1:1**：同一时刻只服务一台设备，被拒的那台会收到占用者的名字（面板里可以「接管」）。

## 排错

| 症状 | 多半是 |
| --- | --- |
| 面板整块红、出码报 `HTTP 404: not found` | 管理面没挂上（装插件后的热重载那一拍）。**重启一次 DSH** |
| 手机显示"端点点拨不通" | 电脑不在线 / 换了网络。局域网直连要 `listenPort` 开着且同网段 |
| 中转一直是"连接中" | `relayUrl` 少了 `/ws/connector`、或令牌不对（中转会 401） |
| 手机上「检查更新」有新版但装不上 | 手机装的是 debug 签名包，与 Release 的正式签名不同 —— 只能卸载重装 |

## 开发与门禁

```bash
cd connector
pnpm exec tsc --noEmit     # 类型
pnpm build                 # 产出 lib/（插件入口）
pnpm test                  # 825 项
node --check client.js     # 浏览器半侧是手写 JS，没有类型检查
```

协议与设计文档：`docs/subsystems/connector-and-relay.md`、`docs/subsystems/remote-channel.md`（在仓库里）。

## 链接

[仓库](https://github.com/Imzl-zl/deepseek-harness-mobile) · [连接器与中转](https://github.com/Imzl-zl/deepseek-harness-mobile/blob/main/docs/subsystems/connector-and-relay.md) · [通道协议](https://github.com/Imzl-zl/deepseek-harness-mobile/blob/main/docs/subsystems/remote-channel.md) · [自建中转](https://github.com/Imzl-zl/deepseek-harness-mobile/blob/main/docs/cookbook/relay-on-a-server.md)

## License

[PolyForm Noncommercial 1.0.0](https://github.com/Imzl-zl/deepseek-harness-mobile/blob/main/LICENSE) —— 可自由使用、修改、分发，**不可商用**。

## 常见问题

### dsh-mobile-connector 是什么？

DSH 插件:手机端远程通道的电脑侧桥接

### 如何安装 dsh-mobile-connector？

在项目目录运行 npm install dsh-mobile-connector，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（4\.0\.5）、@deepseek-ai/schemastery（3\.18\.5）、@deepseek-ai/dsh-typert-protocol（0\.2\.1-rc\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### dsh-mobile-connector 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### dsh-mobile-connector 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### dsh-mobile-connector 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.19\.0 \|\| \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### dsh-mobile-connector 可以商用吗？

dsh-mobile-connector 使用 PolyForm-Noncommercial-1\.0\.0 许可。声明的许可为 PolyForm-Noncommercial-1\.0\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### dsh-mobile-connector 还在维护吗？

最新版本 0\.1\.18 发布于 2026/11/03（今天）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/10/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。