@feiyang666/dsh-mobile-remote 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,21 +1,22 @@
-# Changelog
+# 更新日志 / Changelog
 
-## [1.0.1] - 2026-08-19
+## v1.1.0 (2026-08-19)
 
-### 修复（Fixed）
+### 新增 / Added
+- **设置页「远程控制」面板**（client half：`lib/client.js` 注册 `settings.section`）：
+  - 连接二维码（host 端 `GET /__dsh_remote/qr` 生成 SVG）
+  - 开启 / 关闭开关（写入 / 移除 profile `cordis.patch.yml` 的 `webserver` 覆盖块，经 dsh HMR 热重载生效，无需重启）
+  - 当前连接的设备数量（移动端心跳上报，host 端活跃设备统计）
+- **host 侧远程控制 API**（`lib/index.js`）：`/__dsh_remote/status` / `toggle` / `heartbeat` / `qr`
+- **命令行远程控制支持**：无需桌面端，官方 `dsh --profile web` 即可通过设置页开关或 `--patch` overlay 开启
+- 内联 MIT QR 生成器（`lib/qrcode.js`），零运行时依赖
+- 双语 README（README.md / README.zh.md）、RELEASE_NOTES.md
 
-- **修复 client bundle 加载失败导致移动端适配不生效**：`package.json` 的 `dsh.client.inject` 中误声明了 `@deepseek-ai/dsh-client-ui-slots`（该包是纯类型契约包，无 `dsh.client` 声明与 `./client` 入口，不是合法的 client 加载条目）。这会导致 client loader 无法为该插件创建 fiber，整个浏览器端代码（移动端适配 CSS、浮动控制条、设置页）被丢弃。已移除该无效依赖，仅保留 `@deepseek-ai/dsh-client-ui-layout`。
-- Host 端 `/api/dsh-mobile-remote` 不受影响（已验证 HTTP 200、`0.0.0.0:3080` 监听、64 个会话可见）。
+### 变更 / Changed
+- `package.json`：新增 `dsh.client` 声明与 `./client` export；版本升至 1.1.0
 
-## [1.0.0] - 2026-08-19
+## v1.0.0 (2026-08-19)
 
-### 新增（Added）
-
-- 初始版本：手机端远程控制 DeepSeek Harness。
-- Host 半：`/api/dsh-mobile-remote` JSON API（status / ping）、局域网 IPv4 枚举、`mobile_remote_status` 模型工具。
-- Client 半：
-  - 设置页「远程控制」：开关状态、监听地址/端口、会话数、手机访问地址（一键复制）、二维码、连接测试、使用说明。
-  - 移动端界面适配（≤768px）：单列布局、侧栏抽屉化（滑入滑出 + 遮罩）、触控优化、iOS 安全区。
-  - 浮动控制条（shell.overlay）：会话列表抽屉开关 + 远程连接状态指示，每 15 秒轮询状态。
-
-[1.0.0]: https://github.com/feiyang-dev/dsh-mobile-remote/releases/tag/v1.0.0
+### 新增 / Added
+- 初始版本：移动端输入栏窄屏适配（选择器换行分排、限宽防粘连、按钮触控目标 ≥ 40px）+ iOS 触屏优化（输入框 16px 防聚焦缩放）
+- host 侧 `tapIndex` 注入移动端 CSS/JS，不破坏 DSH 原生 rail + 汉堡抽屉交互

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 feiyang-dev
+Copyright (c) 2026 dsh-mobile-remote contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,12 +1,16 @@
 <div align="center">
 
-# dsh-mobile-remote 📱
+# DeepSeek Harness Mobile Remote Control (dsh-mobile-remote) 📱
 
-[简体中文](./README.zh.md) | **English**
+**English** · [简体中文](./README.zh.md)
 
-[MIT License](./LICENSE)
+[GitHub](https://github.com/feiyang-dev/dsh-mobile-remote) · [npm](https://www.npmjs.com/package/@feiyang666/dsh-mobile-remote) · MIT License
 
-**A plugin for DeepSeek Harness that lets your phone sync with and remotely control your desktop**, with full two-way synchronization of conversations, session lists and settings, plus mobile-optimized UI.
+**A community plugin for DeepSeek Harness** — adds a built-in "Remote Control" page to the Web settings: connection QR code, one-click toggle, and live connected-device count. Access and control your desktop DeepSeek Harness from your phone over LAN, with mobile-first UI polish.
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Node](https://img.shields.io/badge/node-%3E%3D18-339933)
+![Platform](https://img.shields.io/badge/platform-web%20%26%20desktop-4d9fff)
 
 </div>
 
@@ -14,102 +18,187 @@
 
 ## Overview
 
-`dsh-mobile-remote` builds on the built-in **「移动端远程控制」 (mobile remote control)** switch of the DeepSeek Harness desktop app (`dsh-desktop`). When enabled, the dsh web service listens on all interfaces (`0.0.0.0`), so any phone on the same Wi-Fi can open the desktop's LAN address in a browser and use **the very same Web UI**.
+`dsh-mobile-remote` is a DeepSeek Harness ecosystem **mobile remote-control plugin** (DSH plugin, Host + Client in one package). After installation, a management panel appears under **Settings → Remote Control** in the Web UI:
+
+- **Connection QR code**: auto-generates a QR for `http://<lan-ip>:<port>` — scan it with your phone's camera / browser to connect.
+- **On / Off toggle**: switches the webserver listen address (`0.0.0.0` ↔ `127.0.0.1`) with one click. Applied via dsh's official HMR hot-reload — **no service restart needed**.
+- **Connected device count**: mobile heartbeats report online devices in real time.
+- LAN address list, phone access URLs, and config location at a glance.
+
+**Key selling point: pure CLI users don't need the desktop app.** The official CLI deliberately rejects `--host 0.0.0.0` for safety, but this plugin writes `webserver.host: 0.0.0.0` through the profile's `cordis.patch.yml` (or a `--patch <overlay>`) — exactly how the desktop app's "Mobile Remote Control" switch works. The phone and the computer share the same dsh backend process and the same `~/.dsh` data, so **sessions, history, workspace and settings are naturally two-way synced — no data copying involved**.
+
+---
+
+## Screenshots
+
+### Settings → Remote Control
+![Remote Control](./docs/assets/remote-control.png)
+
+## Recommended Installation
+
+> Either method works and is equivalent. **We recommend the desktop app** — fully graphical, no command line needed.
+
+### Option 1 (recommended): One-click via the desktop app
+
+Install [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop), open it, then go to **"Install Plugins" → Recommended → Mobile Remote Control → Install** and click **"Restart Service Now"** to activate.
+
+### Option 2: Command line
+
+```bash
+# Prerequisite: install dsh (npm install -g @deepseek-ai/dsh)
+dsh plugin --profile web add @feiyang666/dsh-mobile-remote
+```
 
-Because the phone and the desktop access the same session data:
+Restart the dsh web service to activate.
 
-- **Real-time two-way sync**: conversations, session list, settings — everything stays consistent. An action on either side shows up on the other instantly;
-- **Full control from your phone**: send messages, switch sessions, inspect details, manage settings — everything the desktop can do, the phone can do;
-- **Mobile UI adaptation**: this plugin optimizes touch targets and layout for phone screens.
+---
 
-npm package: `@feiyang666/dsh-mobile-remote` (same series as `@feiyang666/dsh-usage-plugin` and `@feiyang666/dsh-vault`).
+## Usage
 
-## Features
+1. Start dsh (any way: desktop app / `npx @deepseek-ai/dsh web` / from source).
+2. Open `http://127.0.0.1:3080` in a desktop browser → **Settings → Remote Control**.
+3. Toggle the switch **ON** (hot-reloaded, no restart).
+4. Put your phone and computer on the **same Wi-Fi**, **scan the QR** or open the LAN URL.
+5. The phone now shows all desktop data — sessions, history, workspace, settings — and can send messages to control the desktop.
 
-| Capability | Description |
-|---|---|
-| **Remote-control settings page** | A new「远程控制」page in the Web settings: live switch state, bind host/port, session count, LAN IPv4 addresses, one-tap copy of the phone URL, QR code, connection test and usage guide |
-| **Mobile UI adaptation** | On screens ≤768px: three-column layout collapses to a single column, the sidebar becomes a slide-in drawer with backdrop, touch targets are enlarged, double-tap zoom is disabled, iOS safe-area is respected |
-| **Floating control dock** | Top-right floating buttons on phones: `☰` opens the session-list drawer anytime; the status dot shows connection state (green = connected over LAN, yellow = enabled but accessing locally, gray = off). Tap it to view and copy the phone address |
-| **Status polling** | The dock queries the host every 15 seconds to keep sessions, addresses and connection state fresh |
-| **Model tool** | Registers `mobile_remote_status` so the model can query remote-control status and phone URLs directly |
-| **Host JSON API** | `POST /api/dsh-mobile-remote`: `status` (full snapshot) / `ping` (heartbeat) |
+### Pure CLI startup (no desktop app)
 
-## How it works
+```bash
+# Way 1: use the settings-page toggle (recommended)
+dsh --profile web
+# then open http://127.0.0.1:3080 → Settings → Remote Control → ON
 
+# Way 2: manual overlay
+dsh --profile web --patch remote-control.patch.yml
 ```
-┌─────────────┐   same Wi-Fi   ┌──────────────────────────┐
-│  Phone browser │ ──────────▶ │  dsh web (desktop, :3080) │
-│  (mobile UI)   │  http://LAN  │  - the same Web UI        │
-│  ☰ drawer/FAB  │ ◀──────────  │  - the same session data  │
-└─────────────┘   two-way sync └──────────────────────────┘
+
+`remote-control.patch.yml`:
+
+```yaml
+- id: webserver
+  config:
+    host: '0.0.0.0'
+    port: !!js ctx.webStartup.port ?? 3080
 ```
 
-- The phone and the desktop access the **same web app and the same `~/.dsh` session data**, so synchronization is inherent and real-time (no intermediate layer, no copying);
-- The dsh-desktop switch makes the service listen on `0.0.0.0` via an overlay config (only the listen address changes; the desktop itself still uses `127.0.0.1`);
-- This plugin adds what is missing: mobile UI adaptation, a setup/guide settings page, and connection-status indicators.
+> **Security note**: enabling remote control exposes the service to your LAN. Use it only on trusted home / office networks — **do not expose it to the public internet**.
+
+---
+
+## What This Package Is
+
+One npm package = **host half** (Node-side Cordis plugin: `/__dsh_remote/*` API, patch-file management, heartbeat device counting, index.html injection — see `lib/index.js`) + **client half** (browser settings panel — see `lib/client.js`, talking to the host via `/__dsh_remote/status` etc.).
 
-## Install
+It plugs into DSH through two declarations:
 
-### Option 1: dsh-desktop (recommended)
+| Declaration | Purpose |
+| --- | --- |
+| `dsh.bundle.patch` (`cordis.patch.yml`) | Lets DSH treat it as a **standard bundle plugin package**: `dsh plugin --profile <name> add <pkg>` installs and wires it in one command |
+| `dsh.client` + `exports["./client"]` | Lets the web client auto-load the settings panel at `/plugins/<pkg>/client.js` |
 
-Install [DeepSeek Harness 桌面版](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop), open **「安装插件」→ recommended plugins → 手机端远程控制 → 一键安装**, then click **「立即重启服务」**.
+So for users, **installing is one command** — no YAML editing, no manual file copying.
 
-### Option 2: command line
+---
+
+## How It Works
+
+| Layer | File | Responsibility |
+| --- | --- | --- |
+| host | `lib/index.js` | `/__dsh_remote/status` / `toggle` / `heartbeat` / `qr` API; patch-file read/write; heartbeat device counting; index.html injection |
+| client | `lib/client.js` | Registers the `settings.section` "Remote Control" panel (toggle / QR / device count) |
+| qrcode | `lib/qrcode.js` | Inlined MIT QR generator (`qrcode-generator`), zero runtime deps |
+
+- **Toggle**: `POST /__dsh_remote/toggle` → writes/removes a `webserver` override block in the profile's `cordis.patch.yml` → dsh's `watchUserPatches` (Cordis HMR) hot-reloads the webserver entry to re-listen.
+- **Device count**: mobile-injected JS heartbeats every 30s; the host keeps an active-device map (90s TTL).
+- **QR code**: `GET /__dsh_remote/qr?url=...` returns SVG.
+- **Mobile polish**: `tapIndex` injects mobile CSS/JS — composer toolbar wraps on narrow screens, selects get width-capped, iOS inputs get 16px to prevent focus zoom; **DSH's native rail + hamburger drawer interactions are untouched**.
+
+---
+
+## Installation (for users)
+
+### 0. Prerequisites
+
+- DeepSeek Harness installed (`npm install -g @deepseek-ai/dsh` globally, or via the desktop app / `npx @deepseek-ai/dsh web`).
+- `dsh` on your PATH (use the desktop app's own terminal if it manages its environment).
+
+### 1. One-command install
 
 ```bash
-# Requires dsh (npm install -g @deepseek-ai/dsh)
 dsh plugin --profile web add @feiyang666/dsh-mobile-remote
 ```
 
-## Usage
+This command does three things automatically:
 
-1. **Enable remote control**: open dsh-desktop settings, turn on **「移动端远程控制」**, restart the service;
-2. **Get the phone URL**: open the Web UI → Settings → **「远程控制」**, copy any「手机访问地址」or scan the QR code;
-3. **Open on your phone**: make sure the phone and desktop are on the **same Wi-Fi**, then open the address in the phone browser;
-4. **Start controlling**: the phone shows the exact same interface as the desktop. Use `☰` anytime to open the session drawer; tap the status dot to check the connection.
+1. Installs the package into `~/.dsh/profiles/web` via pnpm (initializes the profile on first use);
+2. Detects the `dsh.bundle` declaration and registers the package in the profile's `dsh.profile.bundles`;
+3. After restart, DSH reads the package's `cordis.patch.yml` and mounts the plugin entry into the app tree — **no manual config editing**.
 
-> Phone URLs look like `http://192.168.x.x:3080`. If the page says「not enabled」, make sure the dsh-desktop switch is on and the service has been restarted.
+The same works for other profiles — replace `web` with your profile name.
 
-## API reference
+> Local tarball testing: `dsh plugin --profile web add C:\path\to\feiyang666-dsh-mobile-remote-1.1.0.tgz`
 
-`POST /api/dsh-mobile-remote` with body `{ "action": "status" | "ping" }`.
+### 2. Restart and verify
 
-### status
+Restart the dsh web app (CLI: stop the old process and run `dsh web` again; desktop: fully quit and reopen). Then:
 
-| Field | Type | Description |
-|---|---|---|
-| `enabled` | boolean | Whether remote control is active (listening on a non-loopback address) |
-| `host` | string | Actual bind host (e.g. `0.0.0.0`) |
-| `port` | number | Actual listen port (e.g. `3080`) |
-| `lanAddresses` | string[] | LAN IPv4 addresses of the desktop |
-| `urls` | string[] | Phone-accessible URLs (`http://<ip>:<port>`) |
-| `sessionCount` | number | Current session count |
-| `serverTime` / `serverTimeIso` | number / string | Server time (clock sync / heartbeat) |
-| `pid` / `workspace` | number / string | Process PID and working directory |
+- Refresh http://127.0.0.1:3080 → Settings → the **"Remote Control"** panel should appear.
 
-### ping
+---
 
-Returns `{ ok: true, serverTime, serverTimeIso }` for link probing.
+## Uninstall
+
+```bash
+dsh plugin --profile web remove @feiyang666/dsh-mobile-remote
+```
+
+Then restart the app.
+
+---
 
 ## FAQ
 
-**Q: The phone cannot open the desktop address?**
+| Symptom | Cause / Fix |
+| --- | --- |
+| No "Remote Control" panel in Settings | Plugin not activated. Check the `cordis.patch.yml` row exists with the right `name`; restart and hard-refresh |
+| Phone still can't connect after toggling ON | Same Wi-Fi? Firewall allowing port 3080? Accessing the LAN IP (not `127.0.0.1`)? |
+| Phone connects but shows 403 | dsh's trust fence: make sure the plugin is installed and dsh is started the supported way (`--patch` / profile patch overriding `webserver.host`) |
+| Device count stays 0 | The phone page must be opened once to start heartbeat; wait a few seconds and refresh |
+| QR won't scan | Confirm Remote Control is ON; use a camera app that supports QR |
+
+---
+
+## Related Projects
+
+| Project | Description | Installation |
+| --- | --- | --- |
+| [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop) | Windows desktop console: install/start/stop/restart the dsh web service with one click, built-in plugin management — **install this plugin from its Recommended section** | Download the desktop app and click a few buttons |
+| [Usage & Cost Tracker (dsh-usage-plugin)](https://github.com/feiyang-dev/dsh-usage-plugin) | Per-call token/cache-hit stats, peak/off-peak billing, balance query, CSV/JSON/PNG export | One-click from the desktop app, or `dsh plugin add @feiyang666/dsh-usage-plugin` |
+| [Data Vault (dsh-vault)](https://github.com/feiyang-dev/dsh-vault) | Auto-backup, wipe detection, one-click restore for chat history and workspace data | One-click from the desktop app, or `dsh plugin add @feiyang666/dsh-vault` |
+| [DeepSeek-Harness](https://github.com/deepseek-ai/DeepSeek-Harness) | Official CLI / Web service | Quick start below |
 
-A: Make sure ① the phone and desktop are on the same Wi-Fi/LAN segment; ② the dsh-desktop「移动端远程控制」switch is on and the service has **been restarted**; ③ the firewall allows the dsh port.
+### Running DeepSeek Harness
 
-**Q: Does the phone need a dedicated app?**
+**Quick start (via npm)**
 
-A: No. Any mobile browser works, nothing to install.
+Install Node.js, then run:
 
-**Q: Does enabling remote control affect desktop usage?**
+```bash
+npx @deepseek-ai/dsh web
+```
 
-A: No. dsh-desktop's health checks, main window and logs still use `127.0.0.1`; only the LAN listening is added.
+This starts the Web UI at http://127.0.0.1:3080 by default. See the [Web UI Guide](https://github.com/deepseek-ai/DeepSeek-Harness).
 
-**Q: Is the phone data the same as the desktop?**
+**Run from source**
 
-A: Yes, and it stays in sync in real time. The phone and desktop share one service and one set of session data, with no intermediate sync layer.
+```bash
+git clone https://github.com/deepseek-ai/deepseek-harness.git
+cd deepseek-harness
+pnpm install
+pnpm run build
+pnpm dsh web
+```
 
 ## License
 
-[MIT](./LICENSE)
+MIT © dsh-mobile-remote

package/README.zh.md

@@ -1,12 +1,16 @@
 <div align="center">
 
-# 手机端远程控制（dsh-mobile-remote）📱
+# DeepSeek Harness 移动端远程控制插件（dsh-mobile-remote）📱
 
 [English](./README.md) | **简体中文**
 
-[MIT License](./LICENSE)
+[GitHub](https://github.com/feiyang-dev/dsh-mobile-remote) · [npm](https://www.npmjs.com/package/@feiyang666/dsh-mobile-remote) · MIT License
 
-**让手机实时同步并远程操控电脑端 DeepSeek Harness 的官方扩展插件** —— 对话记录、会话列表、设置全部双向同步，手机上直接发消息，并对手机屏幕做移动端界面适配。
+**由开发者制作的 DeepSeek Harness 插件** —— 在 Web UI 设置页内置「远程控制」：连接二维码、一键开关、在线设备数，让手机通过局域网访问并操控电脑上的 DeepSeek Harness，同时提供移动端界面优化。
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Node](https://img.shields.io/badge/node-%3E%3D18-339933)
+![Platform](https://img.shields.io/badge/platform-web%20%26%20desktop-4d9fff)
 
 </div>
 
@@ -14,104 +18,189 @@
 
 ## 简介
 
-`dsh-mobile-remote` 利用 DeepSeek Harness 桌面端（dsh-desktop）内置的「移动端远程控制」能力：开启该开关后，dsh web 服务会监听局域网（`0.0.0.0`），手机与电脑处于同一 Wi-Fi 时，用手机浏览器打开电脑的局域网地址即可访问 **同一个 Web UI**。
+`dsh-mobile-remote` 是 DeepSeek Harness 生态的**移动端远程控制插件**（DSH plugin，Host + Client 双面一体包）。装好后在 WebUI **设置 → 远程控制** 出现一个管理面板：
 
-因为手机和电脑访问的是同一份会话数据，所以：
+- **连接二维码**：自动生成 `http://<局域网IP>:<端口>` 的二维码，手机相机 / 浏览器扫码即连；
+- **开启 / 关闭开关**：一键切换 webserver 监听地址（`0.0.0.0` ↔ `127.0.0.1`），经 dsh 官方 HMR 热重载**无需重启服务**；
+- **当前连接的设备数量**：移动端心跳上报，实时统计在线设备数；
+- 局域网地址列表、手机访问地址、配置位置一目了然。
 
-- **实时双向同步**：对话记录、会话列表、设置项等所有信息天然一致，任何一端的操作都会即时反映到另一端；
-- **手机端完整操控**：手机上直接发送消息、切换会话、查看详情、管理设置……电脑端能做的一切都能做；
-- **移动端界面适配**：本插件针对手机屏幕优化触控与布局，让 Web UI 在手机上流畅可用。
+**核心卖点：纯命令行用户无需安装桌面端。** 官方 CLI 出于安全拒绝 `--host 0.0.0.0`，但本插件通过 profile 的 `cordis.patch.yml`（或 `--patch <overlay>`）写入 `webserver.host: 0.0.0.0`——这正是桌面端「移动端远程控制」开关的实现方式。手机与电脑共享同一个 dsh 后端进程与同一份 `~/.dsh` 数据，**会话列表、历史记录、工作区、设置全部天然双向同步，无需任何数据复制**。
 
-npm 包名：`@feiyang666/dsh-mobile-remote`（同项目系列：`@feiyang666/dsh-usage-plugin` 用量插件、`@feiyang666/dsh-vault` 数据保险箱）。
+---
 
-## 功能
+## 界面预览
 
-| 能力 | 说明 |
-|---|---|
-| **远程控制设置页** | Web 端设置页新增「远程控制」页面：实时显示开关状态、监听地址/端口、会话数、本机局域网 IPv4 地址、手机访问 URL（一键复制）、扫码二维码、连接测试、使用说明 |
-| **移动端界面适配** | 手机屏幕（≤768px）自动生效：三列布局收敛为单列、侧栏变成滑出抽屉（带遮罩）、触控目标放大、禁止双击缩放、iOS 安全区适配 |
-| **浮动控制条** | 手机端右上角悬浮按钮：`☰` 随时打开会话列表抽屉；状态圆点指示远程连接状态（绿=已通过局域网连接、黄=已开启但本机访问、灰=未开启），点击可查看手机访问地址并复制 |
-| **实时状态轮询** | 浮动控制条每 15 秒向 Host 查询一次状态，会话数、监听地址、连接状态保持最新 |
-| **模型工具** | 注册 `mobile_remote_status` 工具，模型可直接查询远程控制状态与手机访问链接 |
-| **Host JSON API** | `POST /api/dsh-mobile-remote`：`status`（完整状态快照）/ `ping`（心跳），供 UI 与扩展调用 |
+### 设置 → 远程控制
+![远程控制](./docs/assets/remote-control.png)
 
-## 工作原理
+## 推荐安装方式
+
+> 两个方法任选其一，效果等价。**推荐使用桌面端**，全程图形化、无需命令行。
+
+### 方式一（推荐）：桌面端一键安装
+
+安装 [DeepSeek Harness 桌面版](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop)，打开后点击 **「安装插件」→ 推荐插件 → 移动端远程控制 → 一键安装**，完成后点 **「立即重启服务」** 即可生效。
+
+### 方式二：命令行安装
+
+```bash
+# 前提：已安装 dsh（npm install -g @deepseek-ai/dsh）
+dsh plugin --profile web add @feiyang666/dsh-mobile-remote
+```
 
+装完重启 dsh web 服务即可。
+
+---
+
+## 使用步骤
+
+1. 启动 dsh（任意方式：桌面端 / `npx @deepseek-ai/dsh web` / 源码模式）。
+2. 电脑浏览器打开 `http://127.0.0.1:3080` → **设置 → 远程控制**。
+3. 点击开关**开启**（无需重启，HMR 热重载生效）。
+4. 手机与电脑连**同一 Wi-Fi**，用相机 / 浏览器**扫码**或访问局域网地址。
+5. 手机端即显示电脑端的会话列表、历史记录、工作区、设置等全部数据，可直接发消息操控电脑端执行。
+
+### 纯命令行启动（无需桌面端）
+
+```bash
+# 方式一：直接使用设置页开关（推荐）
+dsh --profile web
+# 然后打开 http://127.0.0.1:3080 → 设置 → 远程控制 → 开启
+
+# 方式二：手动 overlay（启动时传参）
+dsh --profile web --patch remote-control.patch.yml
 ```
-┌─────────────┐  同 Wi-Fi    ┌──────────────────────────┐
-│   手机浏览器  │ ──────────▶ │  dsh web (电脑, :3080)    │
-│  (移动端适配) │  http://LAN  │  - 同一个 Web UI           │
-│  ☰ 抽屉/FAB  │ ◀──────────  │  - 同一份会话数据(实时同步) │
-└─────────────┘   双向同步    └──────────────────────────┘
+
+`remote-control.patch.yml`：
+
+```yaml
+- id: webserver
+  config:
+    host: '0.0.0.0'
+    port: !!js ctx.webStartup.port ?? 3080
 ```
 
-- 手机与电脑访问的是**同一个 Web 应用、同一份 `~/.dsh` 会话数据**，因此「同步」是天然且实时的（无中间层、无二次复制）；
-- dsh-desktop 的「移动端远程控制」开关通过 overlay 配置让服务监听 `0.0.0.0`（仅影响监听地址，不影响桌面端自身）；
-- 本插件在此基础上补齐：移动端 UI 适配、远程控制引导设置页、连接状态指示与巡检。
+> **安全提示**：开启后服务暴露到局域网，请仅在可信的家庭 / 办公网络使用，**不要暴露到公网**。
 
-## 推荐安装方式
+---
 
-> 两个方法任选其一，效果等价。**推荐使用桌面端**，全程图形化、无需命令行。
+## 这个包是什么
 
-### 方式一：桌面端一键安装
+一个 npm 包 = **host 半**（Node 侧 Cordis 插件，提供 `/__dsh_remote/*` API、patch 文件管理、心跳设备计数、index.html 注入，见 `lib/index.js`）+ **client 半**（浏览器侧设置面板，见 `lib/client.js`，通过 `/__dsh_remote/status` 等与 host 通信）。
 
-安装 [DeepSeek Harness 桌面版](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop)，打开后点击 **「安装插件」→ 推荐插件 → 手机端远程控制 → 一键安装**，完成后点 **「立即重启服务」** 即可生效。
+包通过两处声明接入 DSH：
 
-### 方式二：命令行安装
+| 声明 | 作用 |
+| --- | --- |
+| `dsh.bundle.patch`（`cordis.patch.yml`） | 让 DSH 把它识别为**标准 bundle 插件包**：`dsh plugin --profile <名> add <包名>` 一条命令即可安装并自动接线，无需手改任何配置文件 |
+| `dsh.client` + `exports["./client"]` | 让 web 客户端在 `/plugins/<包名>/client.js` 自动加载设置页面板 |
+
+所以对使用者来说，**安装就是一条命令**，不用碰 YAML、不用手动复制文件。
+
+---
+
+## 工作原理
+
+| 层 | 文件 | 职责 |
+| --- | --- | --- |
+| host | `lib/index.js` | `/__dsh_remote/status` / `toggle` / `heartbeat` / `qr` API；patch 文件读写；心跳设备计数；index.html 注入 |
+| client | `lib/client.js` | 注册 `settings.section`「远程控制」面板（开关 / 二维码 / 设备数） |
+| qrcode | `lib/qrcode.js` | 内联 MIT QR 生成器（`qrcode-generator`），零运行时依赖 |
+
+- **开关**：`POST /__dsh_remote/toggle` → 写入 / 移除 profile `cordis.patch.yml` 的 `webserver` 覆盖块 → dsh `watchUserPatches`（Cordis HMR）热重载 webserver 行重新监听。
+- **设备数**：移动端注入 JS 每 30s 心跳上报，host 维护活跃设备表（90s 过期）。
+- **二维码**：`GET /__dsh_remote/qr?url=...` 返回 SVG。
+- **移动端适配**：`tapIndex` 注入移动端 CSS/JS，composer 输入栏窄屏换行、选择器限宽、iOS 输入框 16px 防缩放；**不破坏 DSH 原生 rail + 汉堡抽屉交互**。
+
+---
+
+## 安装（给使用者）
+
+### 0. 前提条件
+
+- 已安装 DeepSeek Harness（`npm install -g @deepseek-ai/dsh` 全局安装，或使用基于它的桌面应用 / `npx @deepseek-ai/dsh web`）。
+- 确保 `dsh` 命令在 PATH 里（桌面应用自带环境则在其终端中执行）。
+
+### 1. 一条命令安装
 
 ```bash
-# 前提：已安装 dsh（npm install -g @deepseek-ai/dsh）
 dsh plugin --profile web add @feiyang666/dsh-mobile-remote
 ```
 
-## 使用方法
+这条命令会做三件事（全部自动）：
 
-1. **开启远程控制**：打开 dsh-desktop 设置页，开启 **「移动端远程控制」** 开关，重启服务；
-2. **获取手机访问地址**：打开 Web UI → 设置 → **「远程控制」** 页面，复制任一「手机访问地址」（或扫二维码）；
-3. **手机访问**：确保手机与电脑连接**同一个 Wi-Fi**，用手机浏览器打开该地址；
-4. **开始远程操控**：手机上即可看到与电脑端完全一致的界面并直接操控。右上角 `☰` 可随时打开会话列表抽屉，状态圆点可查看连接状态。
+1. 在 `~/.dsh/profiles/web` 里通过 pnpm 安装本包（首次使用会自动初始化该 profile）；
+2. 检测到包的 `dsh.bundle` 声明，自动把包名写进 profile 的 `dsh.profile.bundles` 层列表；
+3. 重启后，DSH 启动时会自动读取包内的 `cordis.patch.yml`，把插件行挂进应用树——**不需要**手动编辑任何配置文件。
 
-> 提示：手机访问地址形如 `http://192.168.x.x:3080`。若页面提示「未开启」，请确认 dsh-desktop 的「移动端远程控制」开关已打开并重启了服务。
+其它 profile 同理，把 `web` 换成你的 profile 名即可（如 `dsh plugin --profile headless add ...`）。
 
-## API 参考
+> 想用本地 tarball 测试：`dsh plugin --profile web add C:\path\to\feiyang666-dsh-mobile-remote-1.1.0.tgz`
 
-`POST /api/dsh-mobile-remote`，请求体为 JSON：`{ "action": "status" | "ping" }`。
+### 2. 重启并验证
 
-### status
+重启 DeepSeek Harness 的 web 应用（命令行：结束旧进程后重新运行 `dsh web`；桌面应用：完全退出后重新打开）。然后：
 
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `enabled` | boolean | 远程控制是否生效（服务监听非回环地址） |
-| `host` | string | 实际监听地址（如 `0.0.0.0`） |
-| `port` | number | 实际监听端口（如 `3080`） |
-| `lanAddresses` | string[] | 本机局域网 IPv4 地址列表 |
-| `urls` | string[] | 手机可访问 URL 列表（`http://<ip>:<port>`） |
-| `sessionCount` | number | 当前会话数 |
-| `serverTime` / `serverTimeIso` | number / string | 服务器时间（心跳/对时用） |
-| `pid` / `workspace` | number / string | 进程 PID 与工作目录 |
+- 刷新 http://127.0.0.1:3080 → 设置 → 应出现 **「远程控制」** 面板。
 
-### ping
+---
 
-返回 `{ ok: true, serverTime, serverTimeIso }`，用于连接链路探测。
+## 卸载
+
+```bash
+dsh plugin --profile web remove @feiyang666/dsh-mobile-remote
+```
+
+然后重启应用即可。
+
+---
 
 ## 常见问题
 
-**Q：手机打不开电脑地址？**
+| 现象 | 原因 / 处理 |
+| --- | --- |
+| 设置里没有「远程控制」面板 | 插件未激活。确认 `cordis.patch.yml` 里的行存在且 `name` 正确；重启后刷新（清缓存） |
+| 开启开关后手机还是连不上 | 确认手机与电脑同一 Wi-Fi；确认防火墙放行 3080 端口；确认访问的是局域网 IP 而非 `127.0.0.1` |
+| 手机能访问但显示 403 | dsh 的信任围栏：请确认本插件已安装、且以官方支持的方式启动（`--patch` / profile patch 覆盖 `webserver.host`） |
+| 设备数为 0 | 手机端页面需打开过才会心跳上报；等待几秒刷新 |
+| 二维码扫不出来 | 确认「远程控制」已开启；相机应用需支持扫码 |
+
+---
+
+## 相关项目
+
+| 项目 | 说明 | 安装方式 |
+| --- | --- | --- |
+| [DeepSeek Harness 桌面版](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop) | Windows 桌面控制台：一键安装/启动/停止/重启 dsh web 服务，内置插件管理，**推荐插件区一键安装本插件** | 下载桌面版，点几下即可 |
+| [用量与消耗插件（dsh-usage-plugin）](https://github.com/feiyang-dev/dsh-usage-plugin) | 记录每次模型调用的 token 用量与消耗，支持峰谷计费、余额查询、日历热力图与 CSV / JSON / PNG 导出 | 桌面端一键安装，或 `dsh plugin add @feiyang666/dsh-usage-plugin` |
+| [数据保险箱（dsh-vault）](https://github.com/feiyang-dev/dsh-vault) | 自动备份 / 清空检测 / 一键恢复，保护聊天记录与工作区数据 | 桌面端一键安装，或 `dsh plugin add @feiyang666/dsh-vault` |
+| [DeepSeek-Harness](https://github.com/deepseek-ai/DeepSeek-Harness) | 官方 CLI / Web 服务 | 见下方「运行 DeepSeek Harness」 |
 
-A：确认 ① 手机与电脑在同一个 Wi-Fi/网段；② dsh-desktop「移动端远程控制」已开启并**重启过服务**；③ 电脑防火墙放行了 dsh 监听端口。
+### 运行 DeepSeek Harness
 
-**Q：本插件是否需要手机端单独安装 App？**
+**快速安装（通过 npm）**
 
-A：不需要。手机浏览器即可，无需任何安装。
+安装 Node.js，然后运行：
 
-**Q：在电脑上开启远程控制是否影响桌面端使用？**
+```bash
+npx @deepseek-ai/dsh web
+```
 
-A：不影响。dsh-desktop 自身的健康检查、主窗口、日志仍走 `127.0.0.1`，仅新增局域网监听能力。
+该命令会启动 Web UI，默认地址为 http://127.0.0.1:3080。详见 [Web UI 指南](https://github.com/deepseek-ai/DeepSeek-Harness)。
 
-**Q：手机上的数据与电脑端一致吗？**
+**从源码运行**
 
-A：完全一致且实时。手机与电脑访问同一个服务、同一份会话数据，不经过任何中间同步层。
+如需从仓库源码运行：
+
+```bash
+git clone https://github.com/deepseek-ai/deepseek-harness.git
+cd deepseek-harness
+pnpm install
+pnpm run build
+pnpm dsh web
+```
 
-## 许可证
+## 许可
 
-[MIT](./LICENSE)
+MIT © dsh-mobile-remote