Mobile remote control for DSH with a Flutter app

# DSH Remote（dsh-mobile-remote）

> 把 DeepSeek Harness 变成随身控制台：**手机远程操作电脑上的 agent** —— 发消息派活、看进度、收通知、审批决策、管理会话。电脑端跑着，人不在电脑前也能全程操作。（App 目前为 **Android 端**；**iOS 端未开发**——开发者无苹果设备，欢迎社区贡献，见 docs/09 §4）

## 截图

| 首页 | 对话 | 通知 |
|---|---|---|
| ![首页](docs/screenshots/01-home.png) | ![对话](docs/screenshots/04-chat.png) | ![通知](docs/screenshots/02-notifications.png) |

| 会话列表 | 设置 | 新建会话 |
|---|---|---|
| ![会话](docs/screenshots/03-sessions.png) | ![设置](docs/screenshots/05-settings.png) | ![新建会话](docs/screenshots/06-new-session.png) |

| 外出访问：蒲公英 App（移动端） | 蒲公英 PC 客户端 | 应用商店搜索 |
|---|---|---|
| ![蒲公英移动端](docs/screenshots/pgy-mobile-app.jpg) | ![蒲公英PC客户端](docs/screenshots/pgy-pc-client.jpg) | ![应用商店搜索](docs/screenshots/pgy-appstore.jpg) |

## 功能

> **推送与公网访问配置说明（重要）**：本项目的推送消息通道（Server酱 / ntfy / Bark / 自建等）与**非局域网使用方式**（蒲公英 / Tailscale / FRP 内网穿透等）**均为按需自配置，没有统一标准**——`cordis.patch.yml` 里的 `pushUrls`（推送通道）、`trustedHosts`（公网中继域名）、`lanBridge`（桌面版 LAN 桥）、`approvalMode`（审批位置：`both` 双端 / `mobile` 手机独占 / `desktop` 仅桌面，默认 `both`）等字段请**按自己的需求修改**，文档（docs/06、docs/04-security）只给示例与安全边界，不强制任何固定方案。

- 📱 **手机远程操作**：发消息/派任务、流式回复、Markdown 渲染、token 用量、**微信式无限上翻**（滑到顶部自动加载更早 + 回到底部浮钮）
- ❓ **问询/审批弹窗**：agent 思考中途要你拍板（选选项/输入自定义答案）或工具要权限（允许一次/拒绝）时，手机弹卡片——**与 PC 端同一待办，任一端回答两端同步消失**（v3.1.3 起默认双端呈现，`approvalMode` 可切手机独占/仅桌面）
- 🔔 **系统通知**：agent 完成 / 需要你回答 / 失败 → 手机弹窗（Server酱 / ntfy / Bark 任选；同会话同类型自动聚合）；通知页支持**单删/批量/清空**
- 💬 **会话管理**：查看/切换/续接全部会话，标题与 PC 端实时同步，按工作区分组（子目录自动归属最近工作区），归档与 PC 端同源
- ➕ **新建会话**：选 Agent 模式（标准/PTC/极简/创造）+ 选工作目录（跨盘浏览、可新建文件夹）
- ⚙️ **配置对齐 PC 端**：模型、推理强度、权限预设（危险权限需风险确认）、**默认 Agent 预设 / 默认权限预设可直接修改**（作用于之后新建的会话）
- 🏢 **模型提供商互通**：PC 端「设置 → 模型」与手机同一配置通道——37 个内置提供商（anthropic / openai / google / groq 等）手机可见可配（baseURL + API Key 即激活），模型选择器按提供商分组，设置页「模型提供商」可搜索/编辑/探测模型
- 👀 **过程可见性**：活动条（思考中 / 正在调用工具实时状态行）+ 可折叠思考面板（默认只显示状态）
- 🛠️ **会话工具**：运行中的后台任务实时卡片（可取消）+ 三页签弹层——任务 / 子代理（查看+中断）/ 目标（查看、创建、暂停、继续、标记完成，与 PC 端 goal 服务同源）
- 🫧 **悬浮球**：透明鲸鱼常驻桌面——空闲灰 / 有任务·通知·余额低亮蓝+红点；单击迷你面板（运行中会话 / 通知 / 打开 App / 去充值），拖动贴边 5 秒自动缩进，双击开 App，长按退出；错过的通知也会补提示（气泡/横幅）
- 💾 **体验打磨**：Agent 状态 bootstrap 同步（按钮/活动条即时反映 PC 状态）、下拉刷新收集地址（蒲公英/Tailscale 自动进候选）、聊天草稿保留（退出重进自动恢复）、首页改版（官方 logo / 新欢迎语 / 最近会话卡片滑动）、语言切换（中/英）
- 📶 **扫码连接**：桌面 dsh 设置页出现「连接移动端设备」二维码 → 手机 App 扫码即连（免输 IP/口令）
- 🩺 **环境诊断**：一键查看当前环境各项能力（含问询/审批桥状态），升级/排障一目了然
- 🧩 **插件动作区**：第三方插件注册的动作自动出现在移动端（可选）
- 🖼️ **原生 App**：`dsh-mobile-app/` 子目录，Flutter 原生实现，与网页端共享同一 API 与设计

## 两种使用形态

| 形态 | 说明 |
|---|---|
| **原生 App（安卓，推荐）** | `dsh-mobile-app/` 构建 APK 安装；扫码连接、原生体验、系统通知 |

## 微信入口（可选）：dsh-im

想「在微信里直接给 agent 说话派活」？**本插件不内置 IM 机器人**（那是另一层协议），官方推荐安装 **[@xmanrui/dsh-im](https://github.com/xmanrui/dsh-im)**——一个独立的 DeepSeek Harness 插件，支持微信（个人号扫码）/ 飞书 / 钉钉 / 企业微信 / QQ / Slack / Telegram / Discord / WhatsApp 等 9 种 IM 通道。与本插件互补：

- **dsh-im**：微信/IM 对话入口（在微信里直接聊天派活、收到回复）
- **本插件**：手机控制台（进度 / 审批 / 会话管理）+ **干活完成提醒**（推送桥，不依赖 App 常驻后台）

装法（电脑端）：`dsh plugin add @xmanrui/dsh-im` → 微信扫码登录 → 完成。干活完成提醒走本插件推送桥（docs/06 §6：企业微信机器人 / Server酱 / Bark 任选）。

## 架构

```
手机（原生 App） ──HTTP/SSE──► 电脑上的 dsh 进程（本插件）
                                  │ ctx 服务（agents/sessions/llm/…）
                                  │ /api 桥（与 PC 端 GUI 同一协议）
                                  ▼
                             dsh 内核（会话唯一真源）
```

- **会话唯一真源在 PC 端**：移动端不存状态，实时读写——天然一致，不存在"同步"
- **移动端零插件感知**：核心功能只依赖 dsh 内核语义；个性化（模型/权限/预设）全部动态读取
- **桌面端/命令行双形态兼容**：同一 profile，插件自动加载

## 安装（部署者 3 步）

> 🤖 **让 DSH 的 agent 自动安装**：直接告诉 agent「按本仓库 docs/06 安装 dsh-mobile-remote 插件」即可。agent 默认会采用下面的「方式一」，拉取的就是**当前正式版**（main 分支永远保持完整可发布状态，版本号与最新 Release 一致）。需要与手机 App 精确配对时，把依赖写成 `"dsh-mobile-remote": "github:201222-L/dsh-mobile-remote#v3.0.0"`。

### 方式一：命令行 dsh web（web 版流程）

```powershell
# 1. 在 profile 声明插件
# 编辑 C:\Users\\.dsh\profiles\web\package.json，dependencies 加：
#   "dsh-mobile-remote": "file:"

# 2. 安装依赖
cd C:\Users\\.dsh\profiles\web
corepack pnpm install

# 3. 启用插件（cordis.patch.yml，见下方配置节）后启动
npx @deepseek-ai/dsh web
```

### 方式二：DeepSeek Harness 桌面端（当前主线）

安装插件后**重启 DSH Desktop** 即可（desktop profile 自动加载；移动端经插件 **LAN 桥**，默认 `0.0.0.0:3080`，见 「LAN 桥」节与 docs/06 §4b）。

### LAN 桥（桌面版必开，手机局域网直连）

```yaml
# cordis.patch.yml（mobile-remote 行 config 内）
        lanBridge:
          enabled: true
          port: 3080
          host: 0.0.0.0
```

> ⚠️ **不要覆盖 webserver 行**：桌面版（0.1.1-rc.2）webserver 强制回环（覆盖 host 直接报错），移动端用上方 LAN 桥；**web 版默认已是 `0.0.0.0:3080`，无需覆盖**——仅当你想改端口时才写覆盖行，且**必须写全必填字段**（`host` + `port`），否则启动报 `$port missing required value`（`--dump-config`/smoke 测不出来，只有真启动才暴露）。

```yaml
# 仅 web 版需要改端口时适用：覆盖 webserver 行必须写全字段！
- id: webserver
  config:
    host: 0.0.0.0
    port: 3080
```

## 配置（cordis.patch.yml）

```yaml
- insert:
    - id: mobile-remote
      name: dsh-mobile-remote
      config:
        path: /m
        authToken: 
        pushUrls: []   # 见下方推送配置
        # pushContent: standard  # 默认 minimal：推送只含事件类型+会话短码（核心内容不外出）；standard 才含标题/详情
        # rateLimit: { maxFailures: 10, windowMs: 60000, blockMs: 60000 }  # 登录失败限流
        # trustedHosts: [""]  # 仅 frp 等中继方案需要，见 docs/06 §5B
```

## 桌面设置页入口（客户端模块）

插件启用后，dsh 设置页会出现**「连接移动端设备」**一页：显示连接二维码（含地址+口令）、电脑地址列表与口令（可复制）。手机 App 扫此二维码自动连接。该页数据仅电脑本机可读取（`/m/api/qr-config` 仅允许 loopback 访问）。

## 推送配置（可选，3 分钟）

> 不配置则无系统推送，其余功能不受影响。三种任选，也可同时配置多个（事件会推送到全部通道）。同会话同类型 60 秒内合并（`pushCooldownMs` 可调），通知中心按会话聚合。
> **隐私（v2.6 起）**：推送默认只含「事件类型 + 会话短码」，会话标题/错误详情等核心内容不经过第三方通道；确需完整内容（信任通道时）设 `pushContent: standard`。

### Server酱（微信推送，最省事）

1. 手机微信扫码打开 https://sc3.ft07.com/sendkey → 复制 **API URL**（形如 `https://.push.ft07.com/send/.send`，免备案；老 Turbo 接口 sctapi.ftqq.com 已不可用，2026-08 实测）
2. 配置：

```yaml
pushUrls:
  - name: 微信
    url: https://.push.ft07.com/send/.send
    format: serverchan
```

> ⚠️ Server酱³ 免费版**每天限 5 条**（AUTH 40001），需更多条数请升级。

### ntfy（安卓系统通知栏，原生弹窗）

1. 手机安装 ntfy App（Google Play / F-Droid / 酷安）
2. 生成随机主题并订阅：`dsh-`（例如 `dsh-a1b2c3d4e5f6`）
3. 配置：

```yaml
pushUrls:
  - name: 系统通知
    url: https://ntfy.sh/
    format: ntfy
```

### Bark（iPhone）

1. iPhone 安装 Bark App → 复制推送 key
2. 配置：

```yaml
pushUrls:
  - name: Bark
    url: https://api.day.app/
    format: bark
```

### 验证

配置后重启，让 agent 跑一个任务——手机收到"✅ 任务完成"通知即成功。

## 手机使用

0. **下载 App**：[GitHub Releases](https://github.com/201222-L/dsh-mobile-remote/releases/latest) 下载 `DSH-Remote-vX.Y.Z.apk` 安装（或按 dsh-mobile-app/README 自行构建）
1. 与电脑同一 WiFi；**人不在家**用蒲公英组网等虚拟组网方案（已实测，见 docs/06 §5，App 自动切换地址）
2. 打开 App →「扫码连接」对准桌面 dsh 设置页二维码（或手动输地址+口令）
3. 首页直接发消息派活；对话页实时流式回复；通知页看完成/提问/失败

## ⚠️ 注意事项

**安全**
- 访问口令（`authToken`）是唯一凭据：**每台电脑用不同口令**，扫码二维码含口令，请勿截屏转发；怀疑泄露立即更换（改配置重启后二维码自动更新，旧码作废）。
- 仅限局域网/可信内网使用；**禁止将 3080 端口映射/穿透到公网**（详见 docs/04-security.md）。
- `/m/api/qr-config`（桌面二维码数据）仅允许电脑本机读取。

**使用**
- 会话数据实时存于 PC 端；删除插件/断网不影响已存会话，重装后自动恢复。
- agent 处理上一轮时继续发消息会**排队**（dsh 机制），移动端会提示"正在处理上一轮"。
- 新建会话选的工作目录不在任何已注册工作区时，PC 端按"未分组"显示；在工作区子目录下会自动归属。

**已知限制**
- 移动端默认以普通模式展示对话时间线与工具活动摘要；可切换调试模式查看原始参数/结果、事件元数据与未知可见事件。图片/Markdown 结果支持预览，文件结果可下载到应用私有目录（保存后提示完整路径，系统相册/下载列表不收录）；旧服务端未保存的详情会明确显示不可用。协议/运行时元数据（会话标题、模型选择等）只出现在调试模式；系统提示词、请求快照与压缩摘要不呈现。
- 长任务期间建议等待上一轮完成再发新消息，避免排队混乱。
- 归档（archive）会话与 PC 端同源显示，行为一致。
- 问询/审批弹窗链路随内核版本走对应机制：0.1.2-rc.1+ 为 Agent 作用域瀑布 + 插件 answerer（`both` 双端呈现走内核 `$events` 远程事件通道，与 PC 端 GUI 同通道）；更早内核走 `apiProxy` 帧桥（私有协议，未来大版本可能断桥，插件干净降级、随版本更新恢复）。手机不弹时先跑环境诊断看 `approvalMode`/`remoteEvents`（见 FAQ「问询/审批弹窗类」）。
- 通知删除只清记录不"静音"：同会话同类新事件仍会产生新通知。
- App 构建签名：正式分发须自建 keystore（换签名 = 换应用，用户需重装重扫）；详见 docs/06 §8.2 与 docs/09 §6。
- **与 dsh-web 的移动端远程（`@linxin666/dsh-remote-web-ui`）同装会冲突**：对方把手机页面/API 整体写死在 `/m` 前缀（不可配置），本插件默认也挂在 `/m`——两者抢同一路由前缀可能导致异常/崩溃。共存方法：给本插件配 `path: /mr`（任意非 `/m` 单段）并重启 DSH，手机 App 自动适配无需重装（详见 FAQ「设备/兼容类」）。

## 环境诊断

设置页 → 环境诊断：检测服务（agents/sessions/llm/权限/预设/工作区）与端点实测，`✅/❌` 一目了然，含检测时间。**升级 dsh 后先跑一次诊断**，红了就是需要适配的地方。

## 兼容性

- **dsh 版本**：v3.1.2/v3.1.3 基线为 **`0.1.2-rc.1` 服务包 = DSH Desktop v2.0.5**（approval/request 瀑布 answerer、`$events` 远程事件双端审批、RPC 网关直通、桌面浏览器门禁适配）；v3.0.0–v3.1.1 基线 **`0.1.1-rc.2` = DSH Desktop v2.0.2**（`commands.execute` 四参、桌面版强制回环 → LAN 桥）。更低版本按功能降级，服务依赖与降级行为详见 **[docs/09-compatibility.md](docs/09-compatibility.md)**
- **平台（App）**：Android 7.0+ 全品牌（渲染 Impeller 自动回退；实测小米 17 Pro Max）；**iOS 未开发**（开发者无苹果设备，Dart 代码已平台无关，欢迎社区贡献，见 docs/09 §4）
- **平台（桌面）**：Windows/macOS；命令行 dsh web 与桌面端均支持（纯 headless 形态插件静默无操作）
- **个性化**：模型/权限/Agent 预设动态读取 PC 端真实目录，用户自定义自动出现；自定义动作经 `mobileActions` 注册自动上架
- **深度魔改 web profile**（禁用标准服务）：对应功能自动降级，不崩溃——诊断页可查每个服务状态

## 版本与兼容

- **版本号统一**：App 版本 = 插件版本 = git tag（如 `v3.0.0` = App 3.0.0+5 + 插件 3.0.0）。GitHub Releases 每个版本同时提供两个附件：`DSH-Remote-vX.Y.Z.apk`（手机装）与 `dsh-mobile-remote-vX.Y.Z.tgz`（电脑插件包，`pnpm add ` 或 `npm install -g` 安装）。
- **版本差矩阵**（一句话：谁旧谁吃亏，但都不崩）：

| 组合 | 结果 |
|---|---|
| 同版本 | ✅ 完美 |
| 插件新 + App 旧 | ✅ 老功能正常，新功能不可见（协议只加不删，未知帧一律忽略） |
| App 新 + 插件旧 | ✅ 老功能正常，新功能提示升级 |
| 破坏性变更 | ❌ 禁止——已发布接口只加字段（docs/08 约定） |

- 插件源码按 git tag 锁定版本：`"dsh-mobile-remote": "github:201222-L/dsh-mobile-remote#v3.0.0"`（不带 `#` 取最新）。
- 实际配对可在 App **设置 → 关于 → 版本**（`App vX · 插件 vY`）或环境诊断页对照。

## 文档

- `README.md` — 项目总览：功能、安装、配置、注意事项
- `FAQ.md` — 常见问题速查（连接/使用/安全/弹窗/设备）
- `CHANGELOG.md` — 版本历史
- `CONTRIBUTING.md` — 贡献指南
- `docs/00-开发总纲.md` — 产品规划、阶段划分、决策记录
- `docs/01-PRD.md` ~ `docs/07-user-manual.md` — 需求/架构/API/安全/测试/部署/手册
- `docs/08-扩展开发指南.md` — **二次开发：动作区、自定义推送、页面/App 定制、分享你的版本**
- `docs/09-compatibility.md` — **兼容性：内核耦合点、降级行为、多品牌/苹果端、已知问题、签名**

## 开发

```
lib/index.js    服务端：路由、认证、事件桥、catalog、会话、通知、动作、推送、默认配置
lib/client.js   桌面 GUI 客户端模块（设置页「连接移动端设备」）
dsh-mobile-app/ Flutter 原生 App（扫码连接 + 全部移动界面）
tools/          验证脚本（e2e-check / phase1-check / push-test）
prototype/      界面原型（v7 定稿，设计参考）
```

## 许可

[MIT](LICENSE)