dsh-mobile — Phone Connect for DeepSeek Harness

dsh-mobile is a DeepSeek Harness (DSH) plugin that brings the official phone-connect experience to any DSH web profile: a LAN pairing bridge, a mobile-optimized DSH client for your phone, and a phone entry in the settings row of the web GUI. It is a faithful port of the dsh-desktop phone-connect feature.

This plugin is built for DeepSeek Harness, not for any specific shell app. It works in every deployment that runs a DSH web profile — plain dsh web from the CLI, Bigfish, DSH Desktop-style desktop shells, or any other wrapper. It contains no Bigfish- or DSH Desktop-specific code.

dsh-mobile 是面向 DeepSeek Harness 本体 的插件：任何运行 DSH web profile 的部署（命令行 dsh web、Bigfish、类 DSH Desktop 的桌面壳、或任何封装）都可以 安装使用，不绑定任何特定应用。

Features

• QR pairing with desktop approval — your phone scans a QR code (30-minute rotating token, timing-safe), the desktop confirms, and the phone gets an HttpOnly session cookie.
• Mobile DSH client — workspaces, session list, chat history, send prompts, stop generation; served by the bridge and fully usable over the LAN.
• Settings-row phone entry — a phone icon sits at the right end of the settings row; it shows a green connection dot while a phone is paired, and opens the pairing/manage dialog (QR + copy + countdown + approve/deny + disconnect).
• Safe by default — private-network-only listener on a random port, loopback-only desktop endpoints, RPC allowlist (workspace.list, session.list, session.history, session.create, session.prompt, session.cancel), strict CSP headers.

Architecture

Phone ──HTTP──▶ lan-bridge.mjs (LAN, random port)
                    │  QR pairing / mobile client / allowlisted RPC
                    │  (RPC forwarded to the harness /api with the
                    │   client-request envelope)
                    ▼
Harness web UI ──▶ /phone-connect/bridge  (host plugin, same-origin)
                    │  bridge snapshot: port/status/connected/desktopUrl
                    ▼
                /desktop* loopback endpoints (CORS for the GUI origin)

Install (安装)

Requires a DeepSeek Harness web profile (any deployment — the profile mechanism is core DSH, so this works on plain dsh web, Bigfish, desktop shells that mount a web profile, etc.).

dsh plugin --profile web add https://github.com/s17179XTY/dsh-mobile
# or via the DSH plugin market / dshmarket UI

Then restart the harness (or re-boot the profile) so the cordis.patch.yml row mounts. The package depends on qrcode, installed automatically by the profile's package manager.

Shell integration (壳侧整合)

"Shell" here means the app that hosts the harness around the web profile. The plugin integrates with the shell at two levels:

1. Web GUI shell — built in (无需额外工作)

The plugin's browser half registers into the web profile's own slot system: the settings-row phone entry (with the connected-status dot) and the pairing dialog appear in any DSH web GUI automatically. A browser-only deployment needs nothing else.

2. Native desktop shells — integration hook provided by the plugin

For a desktop shell with its own chrome (e.g., a DSH Desktop-style Electron app), the shell can add a native entry — a "Connect Phone…" menu item or tray action — that opens the bridge's desktop pairing page:

• The host plugin publishes the bridge snapshot at GET /phone-connect/bridge, including desktopUrl (http://127.0.0.1:<port>/desktop, loopback-only).
• That page is the full pairing/manage UI (QR, auto-refresh, approve/deny, disconnect) — exactly what dsh-desktop shows in its own Electron window.
• A shell can therefore discover the URL with one same-origin HTTP call and open it in a small window — no configuration, no credentials.

Shell (native chrome) ──GET /phone-connect/bridge──▶ desktopUrl
        │                                              │
        └──── open http://127.0.0.1:<port>/desktop ◀───┘   (loopback-only page)

Can DeepSeek Harness do this? / DeepSeek Harness 能做到吗？

Yes. Every runtime piece the plugin needs is core DeepSeek Harness capability available to any profile: the profile-plugin mechanism (cordis.patch.yml + dsh plugin add), webServer route registration, the subprocess service, the standalone LAN bridge, and the browser-side slot system. Nothing in this plugin depends on a particular shell app.

The one thing a plugin cannot do from inside the harness is inject native menu items into a desktop shell's own menu bar — that chrome belongs to the shell's code (it is exactly how dsh-desktop ships its "Harness → Connect Phone…" item natively). For that case the plugin provides the desktopUrl hook above, and the shell wires a menu/tray item to it.

Usage

1. Open the web GUI and find the phone icon at the right end of the settings row (bottom-left sidebar).
2. Click it → the pairing dialog opens with a QR code (valid 30 minutes; auto-refreshes on expiry; Copy button next to the URL).
3. On your phone, keep it on the same trusted Wi-Fi, scan the QR with the camera (or open the copied URL).
4. The dialog shows the pending phone — click 允许 / Allow.
5. The phone opens the mobile DSH client. The connection stays active in the background; the icon shows a green dot while connected. Reopen the dialog to disconnect or refresh the QR.

The pairing URL stays valid across dialog sessions for its full lifetime — only an expired token is rotated.

Security

• The bridge binds 0.0.0.0 on a random port and rejects non-private clients (10/8, 172.16/12, 192.168/16, ULA/link-local IPv6).
• /desktop* endpoints are loopback-only; CORS is granted only to the harness GUI origin.
• Pairing token: 32 random bytes, timing-safe comparison, 30-minute TTL.
• Phone sessions: HttpOnly, SameSite=Strict cookie.
• The mobile client can only call the allowlisted RPC methods.
• Keep it on a network you trust. Remove the dsh-mobile row from cordis.patch.yml (or uninstall) when you do not need phone access.

Troubleshooting

• Dialog stuck on "桥已停止，正在自动重试…" (bridge stopped, retrying). Refresh the page first. If it persists, verify the bridge is actually up: GET /phone-connect/bridge on the harness origin should return {"status":"running", ..., "port": <n>}; the bridge's own http://127.0.0.1:<port>/desktop/snapshot should return {"running": true, ...}. The dialog accepts both liveness fields.
• The browser tab no longer shows the plugin. The web shell picks a random port on each start, so a hand-opened tab keeps pointing at a dead port. Reopen the current harness URL (desktop shells reopen their own window automatically).
• Pairing URL says "invalid or expired". The token lives 30 minutes and is only rotated when actually expired — a copied URL stays usable for its full lifetime. A URL from an older rotation (or before a plugin update restarted the bridge) is intentionally dead; open the dialog to get a fresh one.
• Bridge keeps restarting. The host auto-restarts a crashed bridge up to 5 times (3 s apart); the error field of /phone-connect/bridge carries the last exit reason and stderr tail.

Configuration

• --locale zh|en and --app-name are passed to the bridge by the host; the web UI posts its locale automatically to /phone-connect/config.
• The harness URL is derived from webServer.port, so a changed GUI port needs no configuration.

Development

npm install        # dev deps (qrcode etc.)
npm run check      # node --check on all sources
npm test           # end-to-end bridge test (HARNESS_URL overrides the target)

The bridge can also be run standalone:

node lan-bridge.mjs --harness-url http://127.0.0.1:6730 \
                    --gui-origin http://127.0.0.1:6730 \
                    --locale zh --port 0

License

MIT — see LICENSE. The phone/mobile pages are ports of code from dataelement/dsh-desktop (MIT).