Cheng-xiu/dsh-mobile-link

dsh-mobile-link

一键让手机通过互联网连接本机 DeepSeek Harness（DSH），并把手机链接自动推送到你的微信（或你选择的其它渠道）。

一键让手机访问本机 DeepSeek Harness：一个 Cloudflare 快速隧道将 DSH Web GUI 暴露到互联网，手机链接通过你选择的推送渠道推送到你的微信。

功能特性

- 一键启动：双击 bin\start-mobile.cmd（Windows）或 bin/start-mobile.sh（macOS/Linux），或命令行运行 node bin/cli.js start。
- Cloudflare 隧道：自动检测/下载 cloudflared，启动 quick tunnel 转发 DSH Web 端口（默认 3080），复用已有隧道，绝不要求你注册 Cloudflare 账号。
- 自动放行 /api：命令行启动时以 dsh web --trusted-host  启动 DSH，树内自动模式则把隧道主机名动态加入信任栅栏，手机打开不会遇到 403。
- 多渠道推送：推送渠道可选，不强绑定任何服务：
- Server酱（默认，微信服务号「方糖」推送，免费额度每日有限）
- PushPlus（公众号推送）
- Bark（iOS App 推送，官方或自建服务器）
- ntfy（通用通知，任何端可订阅，官方或自建服务器）
- 自定义 webhook（POST JSON {title, content, url}，接入你自己的通道）
- 可选自动推送：配置 autoSend 后，每次 dsh web 启动约 8 秒后自动完成隧道 + 推送手机链接。
- 零键鼠接管、不依赖 PC 微信客户端：纯 HTTP 推送，微信没开机也能收到。
- 不依赖 Cloudflare 账号：quick tunnel 匿名可用。

一键安装（Windows，推荐）

1. 打开仓库右上角 Code → Download ZIP，解压到任意目录。
2. 双击根目录的 install.cmd。
3. 向导会检查 Node.js、DSH、pnpm，安装 GitHub 插件，然后显示 Server酱获取步骤并询问 SendKey。
4. 登录 （微信扫码），在 SendKey 页面复制形如 SCT... 的密钥，粘贴给向导。
5. 向导把密钥写入本机 ~/.dsh/mobile-link/config.json，询问是否立即启动并推送手机链接。

也可在 PowerShell 指定 profile、端口和自动推送：

.\\install.ps1 -Profile web -Port 3080 -AutoSend

SendKey 只保存在用户本机，安装脚本不会把它写入仓库或日志。Server酱免费额度有限，以其官网当前说明为准。安装后目标 DSH profile 必须重启一次，插件才会进入启动树。

commander 由插件作为运行时依赖自行安装，避免全新 profile 或独立 DSH_HOME 中出现 ERR_MODULE_NOT_FOUND；@deepseek-ai/schemastery 仍为可选 peer，仅供树内配置 schema 使用。

手动安装

前置要求：已安装 dsh CLI（DeepSeek Harness）、Node.js >= 18.17，且 pnpm 在 PATH 中（dsh plugin 依赖它完成安装，找不到会报 pnpm not found on PATH）。

本插件尚未发布到 npm，请从本地路径或 GitHub 安装：

从 GitHub 仓库安装
dsh plugin --profile web add github:Cheng-xiu/dsh-mobile-link

或从本地路径安装
dsh plugin --profile web add C:\path\to\dsh-mobile-link

插件会在下一次 dsh 启动时生效——安装完成后需要重启 dsh web（重启会短暂断开当前会话，属正常现象）。

若 pnpm 提示需要为构建脚本授权（pnpm 10+），按提示把该包加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重试。本插件是纯 JavaScript，无原生构建。

dsh plugin 是 pnpm 转发器：add 后面的参数会原样传给 pnpm，因此 dsh plugin --profile web --help 显示的是 pnpm 的帮助；spec 支持 npm 包名、github:owner/repo、git+https://...git、file:/path、link:/path 等形式。

快速开始

1. 安装并重启 dsh web

见上节。重启 dsh web 让插件注入前端运行时。

2. 配置推送渠道（一次性）

交互式向导（推荐）：

node bin/cli.js setup

或非交互配置（示例为 Server酱）：

node bin/cli.js setup --channel serverchan --key SCTxxxxxxxxxxxxxxxx --port 3080

凭证保存在本机 ~/.dsh/mobile-link/config.json（权限 0600），不会离开你的机器，也永远不会写进仓库或日志。

3. 一键启动 + 推送

双击 bin\start-mobile.cmd（Windows）或运行 bin/start-mobile.sh（macOS/Linux），等价于：

node bin/cli.js start

控制台会依次完成：确保隧道 → 启动 DSH Web（带 --trusted-host）→ 等待 Web 就绪 → 推送手机链接。你的微信（或所选渠道）会收到一条「[DSH 已启动] 手机链接」，点开即可在手机上使用 DSH。

4.（可选）每次启动自动推送

sh
node bin/cli.js setup --auto

之后每次 dsh web 启动约 8 秒后会自动完成隧道与推送，无需任何操作。

命令参考

独立 CLI（node bin/cli.js ）：

| 命令 | 说明 | 参数 |
| --- | --- | --- |
| start | 一键：唯一隧道 → 修复/重启 DSH Web（--trusted-host 与隧道一致）→ 公网首页 + /api 双探针验证 → 推送链接 | --port  --profile  --test --dry-run --no-push |
| send | 只推送（复用已有隧道，无则新建） | --test --dry-run --port  |
| setup | 配置渠道与凭证（交互式，也可纯参数） | --channel --key --token --device-key --topic --url --ntfy-server --ntfy-token --port --auto --no-auto |
| tunnel | 只管理隧道，打印手机 URL | --port  --stop |
| doctor | 环境诊断（cloudflared、端口、渠道连通性） | — |
| status | 隧道与配置状态 | — |

常用示例：
sh
node bin/cli.js start                # 一键启动 + 推送
node bin/cli.js start --dry-run      # 只打印将发送的内容，不真正推送
node bin/cli.js start --test         # 发送测试消息而非真实链接
node bin/cli.js send --port 3099     # 只推送，指定端口
node bin/cli.js tunnel --stop        # 停止本插件管理的隧道
node bin/cli.js status               # 查看隧道与配置状态
node bin/cli.js doctor               # 环境诊断

start / send / tunnel / setup 默认端口取配置 config.json 的 webPort（缺省 3080），都可用 --port  覆盖。

配置字段

~/.dsh/mobile-link/config.json：
json
{
"channel": "serverchan",
"serverchan": { "sendKey": "SCT..." },
"pushplus": { "token": "" },
"bark": { "deviceKey": "", "server": "" },
"ntfy": { "topic": "", "server": "", "token": "" },
"custom": { "url": "", "headers": {} },
"autoSend": false,
"webPort": 3080
}

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| channel | string | serverchan | 当前渠道：serverchan|pushplus|bark|ntfy|custom |
| serverchan.sendKey | string | "" | Server酱 SendKey（形如 SCT...） |
| pushplus.token | string | "" | PushPlus token |
| bark.deviceKey | string | "" | Bark device key |
| bark.server | string | "" | Bark 自建服务器地址（空则用官方） |
| ntfy.topic | string | "" | ntfy topic |
| ntfy.server | string | "" | ntfy 服务器（空则用 https://ntfy.sh） |
| ntfy.token | string | "" | ntfy access token（可选） |
| custom.url | string | "" | 自定义 webhook URL |
| custom.headers | object | {} | 自定义 webhook 额外请求头 |
| autoSend | boolean | false | dsh web 启动后自动隧道 + 推送 |
| webPort | number | 3080 | 隧道转发的 DSH Web 端口 |

渠道凭证获取方式（一句话）

- Server酱：登录  获取 SendKey（形如 SCT...），--channel serverchan --key 。
- PushPlus： 扫码后获取 token，--channel pushplus --token 。
- Bark：在 Bark App 内查看 device key，--channel bark --device-key 。
- ntfy：自选 topic（可加自建服务器与 access token），--channel ntfy --topic 。
- 自定义 webhook：--channel custom --url ，会收到 POST JSON {title, content, url}。

树内自动模式

插件在 dsh web 进程内注册了一个自动模式（cordis 插件行 mobile-link，无命令行界面）。当 config.json 的 autoSend 为 true（或在 dsh 配置里开启 autoSend）时，dsh web 启动约 8 秒后自动执行与 start 相同的流程：确保隧道 → 把隧道主机名动态加入 /api 信任栅栏 → 等待 Web 就绪 → 推送手机链接。
- 开启：node bin/cli.js setup --auto，或把 config.json 的 autoSend 改为 true。
- 延迟可在 dsh 配置的 autoSendDelayMs 调整（默认 8000 毫秒）。
- 干跑调试（无需真发，方便验证流程）：
- DSH_MOBILE_LINK_DRY_RUN=1：只打印将发送的内容，不真正推送。
- DSH_MOBILE_LINK_TEST=1：发送测试消息而非真实链接。
- CLI 的 --dry-run / --test 标志优先于这两个环境变量。

cloudflared 说明

- 自动下载：未在 PATH 或常见位置找到 cloudflared 时，按平台从 GitHub 官方 release 自动下载到缓存 ~/.dsh/mobile-link/bin/（Windows 为 cloudflared.exe）。
- 镜像前缀：CLOUDFLARED_BASE 环境变量可覆盖下载源前缀（如内网镜像 CLOUDFLARED_BASE=https://mirror.example.com/cloudflared），缺省用官方 releases/latest/download。
- 已装复用：PATH 或常见安装位置（npm 全局、WinGet、scoop、~/.cloudflared 等）已有 cloudflared 时优先复用，不重复下载。
- 唯一隧道所有权：同一 Web 端口只保留一条受管 quick tunnel。检测到旧版状态、外部/重复 cloudflared 或不健康 metrics 时会停止并替换，避免 DSH 信任主机与屏幕/微信中的 URL 分属两条隧道。
- 严格状态绑定：复用必须同时匹配 cloudflared PID、目标端口、状态版本、metrics 地址、活动 HA 连接和 metrics 中报告的 userHostname；创建过程还需看到本进程的 URL、metrics 与 Registered tunnel connection。
- 并发锁：CLI、安装器和树内自动模式同时触发时会串行管理隧道，不会各自创建不同 URL。日志按端口分文件（cloudflared-.log）。

与已运行实例的行为

- start 先建立唯一受管隧道（同端口已有的外部/重复 cloudflared 会被替换），然后检查端口上的监听者：
- 没有监听者 → 自动启动 dsh web --trusted-host ；
- 是 DSH 且 --trusted-host 与隧道一致 → 直接复用，不重启；
- 是 DSH 但 --trusted-host 不匹配（手机 /api 403 的根源）→ 自动重启该 DSH 并带上正确的隧道主机名；
- 不是 DSH 的进程占用端口 → 不误杀，直接失败并提示。
- start 只有在公网首页 HTTP 200 且 /api 不被 403 拦截后才显示/推送链接；send、tunnel、status、doctor 同样会对 URL 做公网验证，未验证的 URL 不会显示为可分享链接。
- send 检测到 trusted-host 不匹配时拒绝推送并提示运行 start 修复，避免再次把打不开的链接发到手机/微信。
- 桌面启动器（DeepSeek Harness 一键启动.cmd）已改为委托已安装插件 CLI 的 start --no-push 管理 3080 隧道与 DSH 信任主机；只有在插件未安装时才回退到计划任务 legacy 隧道模式。OpenBiliClaw（8420）隧道始终由其自身的计划任务管理，不受主隧道清理逻辑影响。

安全与隐私说明

- quick tunnel URL 是公开的：任何知道该 URL 的人都能访问你暴露的 DSH Web。请勿把推送消息中的链接公开分享；关闭 DSH 或隧道后链接立即失效。
- 不要外传凭证：Server酱 SendKey、PushPlus token 等凭证仅存本机 ~/.dsh/mobile-link/config.json（0600）。
- 插件不收集数据：不向任何第三方上报日志、配置或使用情况；推送只发生在你主动选择的、路由到所选渠道的 HTTP 请求中。
- /api 信任栅栏仍会拦截其它来源的请求，插件只为当前隧道主机名（裸主机名或主机:端口）放行。

常见问题

Q: cloudflared 下载失败 / 网络受限？
先确认能访问 GitHub。需要走代理或内网镜像时，设置 CLOUDFLARED_BASE 指向可用的下载前缀，或手动安装 cloudflared 并加入 PATH（本插件会优先复用）。

Q: 双击脚本后端口提示被占用 / 已有 DSH 实例？
如果已有旧 DSH 实例在运行，它会缺少本插件动态放行的隧道主机名。关闭旧实例后重新双击即可。

Q: 手机打开后界面异常 / 接口 403？
先确认用的是本插件推送的最新链接（隧道 URL 每次重启都变）；然后运行 node bin/cli.js start——它会自动把 DSH 的 --trusted-host 重启成与当前隧道一致，并做公网首页 + /api 双探针验证，验证通过后才推送链接。403（trusted-host 不匹配）是 v0.1.4 之后可以自愈的问题。

Q: 微信收不到推送？
运行 node bin/cli.js doctor 检查渠道凭证与网络；注意 Server酱等渠道有每日免费额度上限。

Q: 想换渠道？
重新运行 node bin/cli.js setup 即可，凭证覆盖保存。

Q: 我有多个 DSH 实例 / 想用别的端口？
一份 ~/.dsh/mobile-link/config.json 同时只支持一个 webPort。多个实例请分别为各 profile 安装插件，并用 node bin/cli.js setup --port  修改 webPort 后重启对应实例。

开发说明

- 双轨架构：独立 CLI（bin/cli.js，自己 spawn dsh web --trusted-host ）+ 树内自动模式（index.js cordis 插件行，仅自动推送）。树内不注册任何 dsh web  命令行——这是为避免与 dsh web-startup 的参数快照解析冲突而作出的取舍，所以所有交互命令都走独立 CLI。
- 入口：bin/cli.js（CLI）、index.js（cordis 插件）、cordis.patch.yml（bundle patch，只插入 mobile-link 插件行）。
- 依赖：纯 JavaScript，无原生构建；peer 依赖 @deepseek-ai/schemastery ^3.18.0 与 commander ^12 || ^13 || ^14 || ^15。
- 配置 schema：见 index.js 的 Config（webPort / autoSend / autoSendDelayMs）；渠道凭证存 ~/.dsh/mobile-link/config.json。

许可证

MIT