手机局域网网关agent-mobile/dsh-mobile-gateway

dsh-mobile-gateway

DeepSeek Harness（DSH）官方版的局域网访问插件：装一个插件，手机 App 直接连。
不改 dsh 源码、不需要重新下载编译——dsh plugin 一条命令安装，dsh web 裸启动即可。

完整使用说明（配手机 App）见 USAGE.md。语音模式 / 实时转写 / 远程组网（蒲公英 · WireGuard）见 VOICE-AND-NETWORK.md。

它解决什么问题

官方 dsh web 出于安全默认只监听 127.0.0.1，且官方 CLI 显式拒绝 --host 0.0.0.0。
手机（或局域网内任何设备）因此连不上主机。本插件以官方扩展点实现远程访问：

| 动作 | 机制 |
| --- | --- |
| 服务器监听所有网卡 | 插件的 cordis.patch.yml 覆盖 webserver 行配置为 host: 0.0.0.0（--port 仍可用；卸载插件即恢复仅本机） |
| 官方 /api 收窄为仅本机 | 绑 0.0.0.0 时 SDK 会自动信任局域网 IP（相当于无认证暴露）——插件把 trustedHosts 置空关闭该行为；本机浏览器不受影响，--trusted-host 在本插件下失效 |
| 手机调用全部 RPC | 在官方 /api 旁挂一条 token 门控的 /m/api 前缀路由，验票后进程内转发给官方 apiProxy（toFetchHandler），不碰官方围栏 |
| 实时消息推送 | /m/api/events.mux、/m/api/events.host 两条 WebSocket 下行流，帧格式与官方完全一致，只改路径前缀 |
| 审批 / 提问应答 | /m/api/respond 直通官方 respond 通道 |
| 大图发送 | 顺带放宽 attachment 图片限额与请求体上限（500 MB 消息图片可用） |
| 管理页 /m/ | 仅限本机：一键生成/轮换 token（settings 热生效、持久化）、按网卡生成配对二维码、设备列表与单台屏蔽 |
| 侧边栏入口 | 官方 Web GUI 侧边栏底部（设置旁）的 手机 图标，当前页弹窗打开管理页（可一键转新标签页；v0.3.3+，uiEntry 可关） |
| 扫码配对 | 二维码编码 服务器\|令牌，配套 App（v1.0.36+）扫码自动填入 |

快速开始

1. 安装官方 dsh（已装可跳过）
npm install -g @deepseek-ai/dsh

2. 安装本插件（从 GitHub，一条命令）
dsh plugin --profile web add github:agent-mobile/dsh-mobile-gateway
首次安装 pnpm 会询问是否允许构建本包（allowBuilds），按 dsh 的提示放行即可；
开发调试:  dsh plugin --profile web add link:

3. 配置 token（见下），然后启动——不用任何 flag
dsh web
启动行会打印 LAN 地址，例如:
dsh web: http://127.0.0.1:3080 (LAN: http://192.168.1.5:3080)

4. 手机 App（同一 Wi-Fi）连接 http://:3080 + token

首次启动防火墙：Windows 会弹"允许 Node.js 入站连接"，勾选专用网络即可；
Linux 需要 sudo ufw allow  之类放行。

配置

token 必填，其余有默认值。两种配置途径：

途径一：profile patch（~/.dsh/profiles/web/cordis.patch.yml）：

- id: mobile-gateway
config:
token: 换成一个长随机串
allowSettings: true        # 设置面（settings.），默认 true
allowCredentials: true     # 凭据面（credentials.），默认 true
extraMethods: []           # 追加放行的方法名，如 ['subagent.history']
maxRequestBodyBytes: 750000000

途径二：Web GUI 设置卡（设置 → 插件配置 → mobile-gateway），改完热生效。

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| token | （必填） | App 侧以 Authorization: Bearer  呈现；留空插件拒绝启动 |
| allowSettings | true | 放行 settings.describe/update/replace/mutate |
| allowCredentials | true | 放行 credentials.describe/set/unset |
| extraMethods | [] | 白名单之外追加放行的方法 |
| maxRequestBodyBytes | 750000000 | /m/api 单请求体上限（须与 connection 行同步调大） |

方法白名单

默认放行（token 验证后）：会话（session. 含 export 下载）、工作区、host.listDirectory/createDirectory、subagent、goal、skill.list、commands/list/execute（会话级斜杠命令，范围不超 session.prompt）、llm.models/providers，加上可选的 settings / credentials 面。

始终拒绝：驱动宿主机原生对话框的 host.pickDirectory/openPath、探针型 llm.discoverModels、agent 预设管理（agentPreset.read/copy/...）——手机端无意义或有侦察价值，不给就不给。

App 侧需要什么

配套 App（dsh_mobile_app / dsh_dart_sdk）v1.0.35+ 已默认走 /m/api，直接可用：
| 官方 fork 直连（apiPrefix: '/api'） | 本插件（默认） |
| --- | --- |
| POST /api/ | POST /m/api/ |
| POST /api/respond | POST /m/api/respond |
| ws://…/api/events.mux | ws://…/m/api/events.mux |
| ws://…/api/events.host | ws://…/m/api/events.host |

token、信封格式、帧格式、rpcId 关联全部不变。DshApiClient 保留 apiPrefix
参数（默认 /m/api），传 /api 可连回自编译 fork 的后端。

安全须知

- token 就是钥匙：生成足够长的随机串（如 openssl rand -hex 32）。持有 token 的设备拥有白名单内的完整 agent 能力（含在你电脑上执行命令的会话）。
- 边界是局域网：本插件不提供公网隧道。需要外网访问请自行加 Cloudflare named tunnel / Tailscale 等带认证的通道，且确保该通道透传 WebSocket。
- 不要用 --trusted-host：那会把官方 /api 直接暴露给局域网并绕过本插件的白名单；本插件的路线完全不依赖它。
- 停用：dsh plugin --profile web remove dsh-mobile-gateway 并重启，服务器恢复仅本机监听。

兼容性

- 已验证：@deepseek-ai/dsh 0.1.2-rc.1（dsh.engines 要求 >=0.1.2-rc.1），Node ^22.19 || >=24。
- 插件启动时自检官方接缝（apiProxy.respond/events.、toFetchHandler）；dsh 升级后接缝变动会启动即报错，不会静默半瘫。
- 依赖的接缝都是官方 npm 包的公开导出（dsh-host-webserver 路由注册、dsh-host-apiproxy 服务与 fetch carrier）。

开发

pnpm install
pnpm test          # 单测 + 真实 WebServer/toFetchHandler 集成测试
pnpm run typecheck
pnpm run build     # 产物 lib/index.js（官方包全部外部化）
node scripts/e2e-ws-probe.cjs     # 对运行中的 dsh web 探测 WS 通道

已验证行为（真实官方 dsh + 本插件）

- 裸 dsh web 绑定 0.0.0.0，URL 行自动打印 LAN 地址
- 官方 /api 从局域网直连一律 403（fence 已收窄）；本机 127.0.0.1 浏览器照常 200
- /m/api：无 token / 错 token → 401；白名单外方法（如 host.openPath）→ 403；被屏蔽设备 → 403
- host.describe（App 连接探测）、llm.providers、settings.describe → 200 + 真实数据
- /m/api/respond 直通官方通道（未知 rpcId 正确返回 {"accepted":false,"reason":"not-pending"}）
- WS：无 token 握手被 403 拒绝；带 token 握手成功，帧格式与官方下行一致
- 管理页 /m/：本机 200 / 局域网 Host 403；轮换 token 后旧 token 立即 401、新 token 立即 200（热生效），重启后依然有效；设备按 x-dsh-device 头（缺省按 IP）追踪，屏蔽/解除即时生效
- Dart SDK 真机链路（dart run tool/smoke.dart http://127.0.0.1:3080 ）：
认证、session.list/create/prompt/history、mux 事件流全部通过

许可证

MIT