@marktrue/dsh-mobile-remote 3.2.4-alpha.3-app → 3.2.4-alpha.3

package/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# 贡献指南
+
+欢迎任何形式的贡献：提 issue、修 bug、加功能、补文档、二次开发。
+
+## 参与方式
+
+- **报告问题**：GitHub Issues —— 说明环境（dsh 版本 / 平台）、操作步骤、现象；移动端问题附截图更佳
+- **提交代码**：Fork → 分支 → PR；小改动直接 PR，大功能先开 issue 讨论
+- **文档**：README / docs/ 的任何改进都欢迎
+- **二次开发**：见 `docs/08-扩展开发指南.md` —— 欢迎基于本项目做自己的定制并回馈上游
+
+## 开发环境
+
+- **插件**：Node.js 18+；在 `~/.dsh/profiles/<desktop|web>` 以 `file:` 依赖引入（见 docs/06-install-run.md；桌面版移动端用 LAN 桥）
+- **App**：Flutter 3.47+ + Android SDK；`flutter analyze` 必须零问题
+
+## 代码约定
+
+- 插件：ESM，遵循现有 `lib/index.js` 的风格；新端点必须在 `docs/03-api.md` 补文档
+- 原型：`prototype/app-prototype.html`（设计参考，零构建，改完直接刷新浏览器看效果）
+- App：`flutter analyze` 零 warning；UI 使用 `theme.dart` 设计令牌，不硬编码颜色
+- 提交信息：中文或英文均可，一句话说明改动（如 `fix: SSE 解析死循环`）
+- 兼容边界：改动涉及内核服务依赖时，对照 `docs/09-compatibility.md` 的降级约定
+
+## 测试要求
+
+- 插件改动：跑 `tools/e2e-check.mjs`（需 `DSH_MOBILE_TOKEN` 环境变量）
+- App 改动：`flutter analyze` + 真机冒烟（发消息/收通知/新建会话）
+- 新端点：在 `docs/05-test-cases.md` 补用例
+
+## 安全底线
+
+- 任何新端点默认走统一鉴权；敏感数据（口令/二维码）只允许 loopback 读取
+- 不引入公网暴露；见 `docs/04-security.md`
+
+## 发布新版本（维护者清单）
+
+**版本号统一原则**：App 版本（pubspec）= 插件版本（package.json）= git tag（如 `v3.0.0` = App 3.0.0+6 + 插件 3.0.0）。**任何一端改动都要三处一起 bump 到同一个新版本号。**
+
+**main 分支完整性约定**：main **永远保持完整可发布状态**——每次合并前必须完成：版本号已 bump、CHANGELOG 已更新、`flutter analyze`/`node --check` 通过；不推半成品。这样"拉最新 main"（普通用户让 agent 自动安装的默认路径）拿到的永远是当前正式版，与最新 Release 一致。破坏性/实验性改动走分支或 PR，不进 main。
+
+**插件改动（电脑端）**：改 `lib/index.js` → `node --check` → 同步安装目录并重启实测 → `package.json` 版本号（与 App 同步）→ CHANGELOG 条目。
+
+**App 改动（手机端）**：改代码 → `flutter analyze` + `flutter test` → `flutter build apk --release` + 真机实测 → `pubspec.yaml` 版本号（形如 `2.5.2+1`）。
+
+**共同步骤**：
+1. 文档同步（API/行为变化时更新 docs/03 等）
+2. `git commit`（一句话说明改动）+ `git push origin main`
+3. `git tag -a vX.Y.Z -m "..."` + `git push origin main --tags`
+4. **本地归档**：运行 `dsh-mobile-app\tools\package-release.ps1` → 生成两个带版本号的文件：`dist\DSH-Remote-vX.Y.Z.apk`（App）与 `dist\dsh-mobile-remote-vX.Y.Z.tgz`（插件包）
+5. GitHub 网页创建 **Release**：选新 tag → 标题 `DSH Remote vX.Y.Z` → 说明写清本次改动 → **同时上传上面两个附件**
+6. 大更新在 DSH 社区发帖；CHANGELOG 保持完整历史
+
+**版本保留原则**：
+- **旧版 Release 永远保留不删**——它们是版本历史，用户可自行选择下载任一版本回退；每次只**新增**一条 Release（选新 tag），新版本自动成为 Latest
+- 每次改动**必须三处同步 bump 版本号**（pubspec / package.json / CHANGELOG），否则新旧包无法区分
+- 同一签名覆盖安装，用户升级无痛；换 keystore 除外（= 换应用）
+
+> 提醒：手机侧载安装无自动更新，重要修复在 Release 说明里写醒目；**不要更换签名 keystore**（同签名覆盖安装保留连接信息）。

package/FAQ.md

@@ -0,0 +1,111 @@
+# FAQ（常见问题）
+
+## 连接类
+
+**Q：手机连不上（连接失败 / 超时）？**
+1. 确认电脑端 DSH 已启动；**桌面版（0.1.1-rc.2）webserver 强制只听 127.0.0.1，手机必须走插件 LAN 桥**（`lanBridge.enabled: true`，默认 `0.0.0.0:3080`，见 docs/06 §4b）；**web 版默认即 `0.0.0.0:3080`，开箱即用无需覆盖**（自定义改端口时覆盖 webserver 行必须写全 `host`+`port`，见 docs/06 §4 警示）
+2. 手机和电脑必须在同一网络（同一 WiFi / 虚拟组网）
+3. 口令是否正确（`cordis.patch.yml` 的 `authToken`）；改了口令要重启桌面端
+4. **Windows 防火墙（最常见）**：路由器重启/换网后 Windows 会把网络重新识别为「公用」，默认拦截入站 3080。修复：
+   - 设置 → 网络和 Internet → 当前网络 → 网络配置文件类型改为「**专用网络**」；
+   - 或以管理员身份运行 PowerShell：
+     ```powershell
+     netsh advfirewall firewall add rule name="DSH Mobile 3080" dir=in action=allow protocol=TCP localport=3080 profile=private
+     ```
+   - 判断方法：电脑上 `http://127.0.0.1:3080/m/api/bootstrap` 能通、手机却连不上，基本就是防火墙/网络类别问题
+
+**Q：扫码连不上 / 二维码扫了没反应？**
+- App 请用自带的「扫码连接」按钮，不要用系统相机（系统相机会跳浏览器打开网页）
+- 二维码含口令，改了 `authToken` 后需重启桌面端，二维码自动更新
+- 手机与电脑需同一网络
+
+**Q：外出（不在家）怎么连？**
+**推荐：蒲公英组网**（已实测 ✅）——电脑和手机装蒲公英客户端，登录同一账号加入同一组网（免费版 3 个成员）。手机 DSH App 首次手动填一次电脑的蒲公英虚拟 IP（`http://172.16.x.x:3080`），之后 App 自动切换：出门走蒲公英、回家走局域网（设置 → 电脑地址显示「共 N 个地址自动切换」）。步骤详见 docs/06 §5.1。
+其他虚拟组网（ZeroTier/路由器 WireGuard）与内网穿透（frp/樱花映射）同理可接，配置要点见 docs/06 §5.2（隧道类需插件 `trustedHosts` 放行 + 强口令）。**禁止公网端口裸奔映射**；Tailscale 因国内控制面不可达不推荐。
+
+## 使用类
+
+**Q：发消息没反应？**
+- agent 正在处理上一轮时新消息会**排队**（dsh 机制），移动端会提示；等上一轮完成即可
+- 检查状态点：绿色=运行中，橙色=等待你回答（直接回复即可）
+
+**Q：通知不推送？**
+- 检查 `pushUrls` 配置是否正确 + 重启桌面端
+- Server酱：SendKey 是否有效；ntfy：手机 App 是否订阅了同一 topic
+- 同会话同类型通知 60 秒内合并（`pushCooldownMs`）
+
+**Q：通知列表里看不到任务完成？**
+通知中心按会话聚合（同会话同类型只保留一条）；PC 端任务完成/失败/需回答才会产生通知。
+
+**Q：新建会话选的工作目录在 PC 端显示"未分组"？**
+该目录不在任何已注册工作区（或不在其子目录下）。在工作区子目录下会自动归属；也可在 PC 端把该目录注册为工作区。
+
+**Q：会话列表和 PC 端不一致？**
+不会 —— App/网页端与 PC 端共用同一会话数据源（实时读写），标题/分组/归档全部同源。
+
+## 问询/审批弹窗类
+
+**Q：agent 问我问题/要权限时，手机为什么不弹卡片？**
+1. 弹窗在**该会话的对话页**里；人在别的页面时只有通知中心的「需要你回答」条目，点进去即见弹窗
+2. 电脑端 dsh 需重启过（answerer 随插件加载）；App 设置 → 环境诊断：v3.1.3+ 看 `checks.approvalMode` / `checks.remoteEvents`（0.1.2-rc.1+ 宿主不再输出旧版 `respondBridge`/`frameBridge`/`apiProxy` 键——那是 0.1.1 及更早内核的帧桥探测项，**缺失即正常**；旧版 App + 新插件时字符串行按布尔渲染显示 ❌ 属显示限制，以插件日志/诊断 JSON 为准）
+3. 若 PC 端也没弹：会话审批策略为「从不询问」，或 Harness 配了自动答题/自动审批（不弹是正常行为）
+4. 配置了 `approvalMode: desktop`（审批/问询只走桌面 GUI）时手机不弹卡——符合配置语义，不是故障
+详见 docs/09-compatibility.md。
+
+**Q：手机在线时，桌面端不弹审批/问询框？（issue #9）**
+v3.1.2 起审批/问询改走内核 0.1.2 的单条 Cordis 瀑布 + 手机接管机制：手机在线即由手机独占应答，桌面 GUI 不再弹卡。**v3.1.3 起默认 `approvalMode: both`**——桌面 GUI 与手机同时收到待办，任一端先答即生效、另一端自动收卡（恢复 v3.1.1 帧桥体验）。仍可切换其它策略（`cordis.patch.yml` → mobile-remote 行 `config`，重启生效）：
+
+```yaml
+approvalMode: both      # 默认。两端同卡、先答生效（需 DSH 0.1.2-rc.1+ / 桌面 v2.0.5+）
+# approvalMode: mobile  # 手机在线独占（v3.1.2 行为），外出远程用
+# approvalMode: desktop # 审批/问询只走桌面 GUI，常驻电脑前用
+```
+
+旧宿主（0.1.1-rc.2 及更早，无 $events 通道）`both` 自动按 `mobile` 处理；诊断页 notes 会说明实际生效语义。
+
+**Q：手机点了 ✕ / 回答了，电脑端会怎样？**
+两端同一待办：手机 ✕ = 取消（审批 → cancelled、问询 → 跳过），手机回答 = 答案直接传给 agent；任何一端处理后另一端弹窗同步消失。先到先得，后答的一方提示"可能电脑端已先处理"。
+
+## 设备/兼容类
+
+**Q：哪些手机能用？有苹果版吗？**
+Android 7.0+ 各品牌均可（Flutter 原生，渲染自动回退）；实测机型：小米 17 Pro Max。**苹果端尚未开发**——开发者没有苹果设备（Mac/iPhone），无法构建与真机调试；代码本身已平台无关，欢迎有 Mac 的开发者贡献 iOS 版本（见 docs/09-compatibility.md §4）。
+
+**Q：换手机 / 重装 App 后要重新连接吗？**
+要：连接信息只存手机本地。重新扫一次电脑端二维码即可（口令未变则电脑端不用动）。
+
+**Q：装了 dsh-web 的「移动端远程」后插件冲突 / 网页崩溃？怎么共存？**
+- **原因**：dsh-web 生态的 `@linxin666/dsh-remote-web-ui` 把手机页面与接口整体写死在 `/m` 前缀（不可配置），本插件默认也挂在 `/m`——两者抢同一路由前缀，请求互相覆盖导致异常/崩溃；
+- **解法**：给本插件换一个非 `/m` 的单段前缀即可共存（对方写死，只能我们让路）——在 `cordis.patch.yml` 的 mobile-remote 行 `config` 里加 `path: /mr`（或任意单段，如 `/mobile`），重启 DSH：
+  ```yaml
+  - insert:
+      - id: mobile-remote
+        name: dsh-mobile-remote
+        config:
+          path: /mr          # 避让 dsh-web 占用的 /m 前缀
+          authToken: <口令>
+          # lanBridge: { enabled: true, port: 3080, host: 0.0.0.0 }  # 桌面版需要
+  ```
+- **手机 App 无需改动**：路径经二维码 / `bootstrap` 动态获取，自动适配新前缀。
+
+**Q：为什么我装的 App 升级时提示签名不一致？**
+构建者更换了签名 keystore（签名变更 = 新应用）。卸载旧版重装，然后重新扫码。开发/自用构建回退 debug 签名，公开分发必须用同一正式 keystore（见 dsh-mobile-app/README.md）。
+
+## 深色/显示类
+
+**Q：界面是黑的 / 想换浅色？**
+设置 → 深色模式：跟随系统 / 深色 / 浅色 三态切换（App）；网页端跟随浏览器系统主题。
+
+**Q：看不到工具调用过程？**
+对话页输入框上方有**活动条**：思考中 / 正在调用工具（如 read）实时显示，结束后消失；思考内容可点开查看（v2.6 起）。工具结果细节以 PC 端为准。
+
+## 安全类
+
+**Q：二维码/口令泄露了怎么办？**
+修改 `cordis.patch.yml` 的 `authToken` → 重启桌面端 → 二维码自动更新，旧码作废。
+
+**Q：可以把 3080 映射到公网吗？**
+**禁止**。插件面向可信内网设计（详见 docs/04-security.md）；外出请用**蒲公英组网**（推荐，docs/06 §5.1；Tailscale 国内控制面不可达不推荐，其他组网/隧道思路见 §5.2，公网隧道必须配 TLS）。
+
+**Q：App 会联网上传我的数据吗？**
+不会。App 只与本机配置的电脑地址通信（HTTP 直连），连接信息仅存手机本地。

package/README.md

@@ -1,9 +1,257 @@
-# DSH Mobile Remote App 载体（@marktrue/dsh-mobile-remote@3.2.4-alpha.3-app）
+# DSH Remote（dsh-mobile-remote）
 
-本包是 DSH Mobile Remote 的 **App 载体**，只承担数据分发角色：
+> 把 DeepSeek Harness 变成随身控制台：**手机远程操作电脑上的 agent** —— 发消息派活、看进度、收通知、审批决策、管理会话。电脑端跑着，人不在电脑前也能全程操作。（App 目前为 **Android 端**；**iOS 端未开发**——开发者无苹果设备，欢迎社区贡献，见 docs/09 §4）
 
-- `DSH-Remote-v3.2.4.apk`：与插件 3.2.4-alpha.3 配对的 Android 安装包；
-- `manifest.json`：schema 1 发布清单，描述同一次发布的两端产物身份与哈希。
+## 截图
 
-本包**没有**可执行入口（无 main/exports/bin），不包含插件代码或安装脚本，
-也不是 DSH 插件/bundle。它由 `@marktrue/dsh-mobile-remote@3.2.4-alpha.3` 的精确别名依赖随插件一起安装。
+| 首页 | 对话 | 通知 |
+|---|---|---|
+| ![首页](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 服务同源）
+- 🐋 **桌面宠物（大肥鱼）**：MIT 鲸尾女仆常驻桌面——任务/通知/余额驱动 16 组动作（思考、处理、等待、完成、出错、待机微动作）；点头部/身体/尾巴互动，双击摸头，拖动悬空+落地，长按打开旧迷你面板（运行中会话 / 通知 / 用量与额度 / 余额 / 打开 App / 去充值）；贴边 5 秒缩进 45% 并虚化，完成/等待/出错自动探头；支持三档大小与减少动效；**App 在前台时自动收起**（不与首页角色同屏、不挡按钮）；错过的通知也会补提示（气泡/角标/横幅）
+- 🎨 **外观：皮肤与图标**：四套皮肤（默认 / 深潜夜航 / 海盐汽水 / 鲸落星海，各含明暗两套）——三套大肥鱼皮肤下首页换成角色 Hero + 动态背景（气泡/声呐环/星尘月盘的 30fps 上限动画），角色可点头部/身体/尾巴互动、长按开面板；App 图标 8 款（原图标 / 深海头像 / 贝壳徽章 / 月夜潮线 / 奶油贴纸 / 鲸邮票 / 霓虹灯牌 / 鲸尾剪影），用 `activity-alias` 切换，默认与原图标逐像素一致
+- 💾 **体验打磨**：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://<uid>.push.ft07.com/send/<key>.send`，免备案；老 Turbo 接口 sctapi.ftqq.com 已不可用，2026-08 实测）
+2. 配置：
+
+```yaml
+pushUrls:
+  - name: 微信
+    url: https://<uid>.push.ft07.com/send/<sendkey>.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/<你的key>
+    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)

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# dsh.bundle 激活补丁（DSH 桌面/CLI 安装本包时作为 profile 层应用）。
+#
+# 有了它，用户 `dsh plugin add @marktrue/dsh-mobile-remote` 之后无需手工编辑
+# profile 的 cordis.patch.yml——本文件就是那一段 insert。
+#
+# 口令：**不需要在这里写死**。未配置时插件会自动生成 43 字符强随机口令并存到
+#    <DSH_HOME>/mobile-remote/auth-token，连接二维码会携带它；移动接口一律 fail-closed。
+#    桌面版（webserver 只听回环）还需开启 lanBridge 才能让手机连上：
+#      config.lanBridge: { enabled: true, port: 3081 }
+- insert:
+    - id: mobile-remote
+      name: "@marktrue/dsh-mobile-remote"
+      config:
+        path: /m

package/docs/00-/345/274/200/345/217/221/346/200/273/347/272/262.md

@@ -0,0 +1,125 @@
+# 00 开发总纲 — DSH Mobile（手机远程操作端）
+> 版本：v2.7.0 · 状态：已开源发布，持续维护 · 本文件是后续全部工作的最高依据
+## 1. 项目一句话
+
+**把 dsh（DeepSeek Harness）变成随身控制台**：手机随时查看 agent 状态、发消息派活、审批决策、接收完成/待回答/失败通知、管理会话——电脑端跑着，人不在电脑前也能全程操作。
+## 2. 资产现状（开发起点）
+
+| 资产 | 状态 | 位置 |
+|---|---|---|
+| `dsh-mobile-remote` host 插件（/m/api + 桌面客户端模块） | ✅ 已安装启用（desktop profile；web profile 亦可） | `<插件安装目录>` |
+| 桌面端兼容 | ✅ 已验证（DSH Desktop v2.0.2 / 内核 0.1.1-rc.2，LAN 桥接入） | deepseek-harness-desktop（本机验证） |
+| 移动端界面原型 v7（DeepSeek 配色） | ✅ **已定稿** | `prototype\app-prototype.html` |
+| 既有文档 01~09 | ✅ 已更新到 v3.0.0 产品版 | `docs\` |
+| 发布产物 | ✅ 版本线统一：App 版本 = 插件版本 = git tag；Release 每版双附件（APK + 插件 tgz） | GitHub Releases |
+
+## 3. 设计定稿（界面冻结，开发必须遵守）
+
+- **视觉**：DeepSeek 品牌配色（主色 `#426EFE`，深色 `#0E1116`）、衬线大标题、1.5 线宽线性图标、大圆角、默认跟随系统深浅色
+- **信息架构**：侧边栏三项（首页 / 会话 / 设置）；对话、通知为详情页；无底部 tab
+- **首页固定欢迎界面**（不做状态切换）：欢迎语 + 最近会话 + 新建会话 + 输入权限
+- **新建会话当场选模式**（标准 PTC/极简/创造，预设 · 设置默认值）
+- **所有展示数据真实对齐 PC 端**：模型（deepseek-v4-flash / deepseek-v4-pro）、推理强度（off/high/max）、权限（read-only / workspace-write / danger-full-access，Full Access 需风险确认）、模式显示名（标准 PTC/极简/创造）
+- **诚实原则**：未实现的功能明确标注「开发中」，不出现无声摆设；深色模式默认跟随系统
+- **移动端不感知插件**：核心层只依赖 dsh 内核语义；动作区（可选）打开时实时拉取清单；插件管理永远在 PC 端
+## 4. 开发阶段（依赖顺序）
+> 现状（v2.7.0）：Phase 1-4 全部完成；网页版已移除（见 Phase 3 注）；v2.2~v2.5 补充：消息操作/通知删除/问询审批弹窗/无限上翻/多地址切换/连接自愈/版本线统一等（详见 Phase 4 与 CHANGELOG）；**v2.6.0 安全加固 + 过程可见性 + 模型提供商互通**：登录限流、推送脱敏、链接白名单、qr.png 收口、口令加固、认证警示、备份隔离、活动条/思考面板、37 个 dormant 提供商手机可见可配、llm-providers 端点；**v2.7.0 会话工具 + 体验打磨**：任务进度实时推送、子代理/目标手机端可见可操作（jobs/subagents/goal 端点）、agent 状态 bootstrap 同步、下拉刷新收集地址、聊天草稿保留、首页改版（官方 logo / 新欢迎语 / 最近会话卡片滚动）。
+### Phase 1：后端 API 补全（完成 ✅）
+
+**范围**：插件新增移动端所需的全部 API。
+| 交付版 | 验收标准 |
+|---|---|
+| 模型目录 API（读取） | 返回 PC 端真实模型 + 推理强度选项与当前值 |
+| 会话配置 API（读写） | 切换当前会话模型/推理强度/权限预设；风险确认后允许 danger-full-access |
+| Agent 预设 API（读写） | 读默认预设；新建会话带预设参数 |
+| 新建会话 API | 按 preset 创建会话，返回 id 可续接 |
+| 通知中心 API | 聚合完成/待回答/失败事件；未读 已读状态 |
+| 动作区契约 v0.1 | GET 动作清单 + POST 执行（注册服务 `ctx.mobileActions`） |
+
+**Phase 1 完成标志**：API 全链路可用（e2e-check 通过）。
+### Phase 2：推送桥（完成 ✅）
+
+**范围**：agent 完成 / 需要回答 / 失败三类事件 → 推送服务（Bark / Serverchan / ntfy，可配置）→ 手机系统通知；App 在后台也能收到。
+| 交付版 | 验收标准 |
+|---|---|
+| 推送桥配置（profile settings） | 配置推送服务 URL + 开关 + 事件类型选择 |
+| 事件 → 推送转发 | 三类事件触发推送，内容含会话摘要；同会话同类型聚合 |
+
+**Phase 2 完成标志**：手机锁屏收到任务完成/需要回答通知。
+### Phase 3：Flutter App（完成 ✅）
+
+**范围**：按定稿原型实现原生 App，对接 Phase 1 API。
+| 交付版 | 验收标准 |
+|---|---|
+| Flutter 工程（Android 优先） | 全部界面与弹窗按原型实现 |
+| 连接管理 | 扫码/手动连接、重连、断线提示 |
+| 通知接入 | 前台 SSE + 后台依赖 Phase 2 推送桥 |
+| 打包 | Android APK 可安装 |
+
+**Phase 3 完成标志**：APK 安装后全功能可用，体验等于原型。
+> **v2.1 决策**：网页版（`/m` 页面）在 App 完成后移除（不再提供浏览器形态），减少运行资源；桌面设置页由客户端模块（`client.js`）提供扫码入口。
+### Phase 4：移动端补齐与可靠性加固（完成 ✅）
+
+**范围**：把「人不在电脑前」做实——人类交互补全（问询/审批）、连接不丢、断了快恢复、版本不混乱。
+| 交付版 | 验收标准 |
+|---|---|
+| 问询/审批弹窗（v2.4.0） | agent 提问/工具越权时手机弹卡片，与 PC 同一 pending 通道，任一端回答两端同步消失 |
+| 多地址自动切换（v2.4.1） | 连接成功后自动收集全部地址（局域网 IP + 虚拟组网 IP），断线重试失败自动轮换——出门切虚拟组网、回家切局域网，全程免手动 |
+| 连接自愈（v2.4.2/v2.5.1） | SSE 心跳看门狗（75s 无心跳强制重建）；黑洞地址故障切换 72s→约 10s；下拉刷新「探测→自愈→拉数据」 |
+| 手动切换连接地址（v2.5.0） | 设置 → 电脑地址点按弹出候选列表，探测可达后切换并重连 |
+| 版本线统一（v2.5.1） | App 版本 = 插件版本 = git tag；Release 每版双附件（APK + 插件 tgz） |
+| 布局溢出硬化（v2.5.2） | 工作区抽屉/底部弹层/问询卡片/连接配置页在内容多、小屏 + 键盘场景不溢出 |
+
+**Phase 4 完成标志**：手机断网/组网失效后约 10 秒自动切到可用地址；抽屉与弹层在极端内容量下不破版。
+
+## 5. 阶段依赖与顺序理顺
+1. **API 先行**：App 与脚本测试共用同一套 API，先写 API 再写客户端
+2. **推送桥在 App 前**：App 的后台通知直接复用推送桥，不必在 Flutter 里重做
+3. **App 最后**：纯锦上添花，风险最低的部分最后做
+
+## 6. 关键决策记录（ADR 摘要）
+| # | 决策 | 理由 |
+|---|---|---|
+| D1 | 视觉 = DeepSeek 品牌色 + Claude/Notion 排版 | 用户定稿；暖色、蓝色都试过，DeepSeek 蓝最对味 |
+| D2 | 首页固定欢迎界面，无状态切换 | 任务断断续续时切换体验差（用户明确要求） |
+| D3 | 新建会话当场选模式 | 避免每次去设置改默认（用户明确要求） |
+| D4 | 权限三档 + Full Access 风险确认 | 与 PC 端沙箱模式一致 |
+| D5 | 移动端零插件感知 + 可选动作区 | 插件生态差异不进入移动端核心层 |
+| D6 | 诚实原则（开发中标注） | 避免虚假功能误导 |
+| D7 | 桌面端 命令行双形态兼容 | 同 profile 同 CLI，插件天然兼容 |
+| D8 | 版本线统一：App 版本 = 插件版本 = git tag，Release 双附件 | v2.5.1；避免版本错配困惑；已发布接口只加不删（破坏性变更禁止） |
+| D9 | 连接自愈多级兜底：SSE 超时 + 心跳看门狗 + 地址轮换 | 断连形态多样（静默死亡/黑洞/半开），单一机制覆盖不全 |
+| D10 | 地址策略：自动切换为主、手动切换兜底 | 自动覆盖日常（出门/回家）；特殊组网场景留给用户手动选 |
+| D11 | 登录失败限流（10 次/60s/来源 IP，成功重置） | 防弱口令爆破；正常用户零感知（v2.6.0） |
+| D12 | 推送内容默认脱敏（minimal：仅事件类型+会话短码） | 第三方推送通道（Server酱/ntfy/Bark）不可信；核心内容默认不出本机（v2.6.0） |
+| D13 | 消息链接 scheme 白名单（仅 http/https 可点击） | 防 file:/intent:/tel: 拉起任意应用（v2.6.0，App） |
+| D14 | qr.png 与 qr-config 同策略（Host 校验 + loopback only） | 消除唯一无认证路由；桌面设置页本就要求 loopback 拉数据（v2.6.0） |
+| D15 | 移动 Git 聚焦日常闭环，复杂历史操作后置 | 手机优先短时高频操作；按基础只读、日常写闭环、扩展管理分阶段交付 |
+| D16 | Git 采用 Service Definition / Provider / Consumer 接缝 | App 零插件感知；mobile-remote 不依赖社区插件私有协议，也不重复实现 Git |
+| D17 | Git 写操作采用仓库串行的可恢复任务 | 支持断线恢复和幂等；取消不冒充回滚；破坏性操作由服务端确认 |
+
+## 7. 风险与应对
+| 风险 | 应对 |
+|---|---|
+| 会话配置 API 需要权限边界（改模型 权限影响会话行为） | 写操作要求认证 + 与 PC 端相同的风险确认流程 |
+| 通知聚合的事件语义（待回答如何判定） | 已实现：`turn/end` reason.kind=blocked → needs-answer（v2.4 与问询/审批弹窗联动） |
+| 动作区契约被第三方插件滥用 | 注册表冲突抛错（Cordis 语义） 文档约定命名空间 |
+| 问询/审批桥依赖 apiProxy 私有协议 | 干净降级（不崩、不弹窗），诊断可查，随插件版本跟进——见 09-compatibility |
+| 组网/隧道断连产生黑洞地址（连接不拒绝但无响应） | SSE 超时 + 心跳看门狗 + 地址轮换多级自愈（v2.5.1 实测 72s→约 10s 恢复） |
+| 国产 ROM 杀后台导致外出断连/漏通知 | 文档引导保活设置（docs/06 蒲公英手机端），App 侧地址自愈兜底 |
+| 弱口令被爆破（早期无速率限制） | v2.6 登录限流：10 次/60s → 429 + Retry-After；认证成功重置计数 |
+| 推送内容经第三方通道泄露（会话标题/错误详情） | v2.6 推送默认脱敏：只推事件类型 + 会话短码（pushContent: minimal） |
+
+## 8. 文档索引
+
+- 本文件：总纲（最高依据）
+- `01-PRD.md`：产品需求（v0.1/v1 历史 + v2.0 移动端产品版）
+- `02-architecture.md`：架构（插件 + App）
+- `03-api.md`：API 设计（全部端点 + SSE 帧）
+- `04-security.md`：安全设计
+- `05-test-cases.md`：测试用例（含 v2.3 问询/审批、通知删除端到端用例；连接逻辑另有单元测试，见 §4 回归建议）
+- `06-install-run.md`：部署与启用（安装/配置；构建/签名与排障见 `10-release.md`）
+- `07-user-manual.md`：用户手册（含 FAQ）
+- `08-扩展开发指南.md`：二次开发（动作区/推送/App 定制/分享你的版本）
+- `09-compatibility.md`：兼容性（内核耦合点/多品牌/已知问题）
+- `10-release.md`：发布操作手册（构建 → 预检 → 演练 → 试发布 → 正式发布 → 验证/回滚；含 Android 构建与排障附录 A）