@marktrue/dsh-mobile-remote 3.2.1-rc.1-app → 3.2.1-rc.1

package/docs/06-install-run.md

@@ -0,0 +1,308 @@
+# 06 部署与启用文档 — dsh-mobile-remote
+
+> 版本：v3.0.0 · 状态：已在本机安装与验证 · 配套：03-api.md、04-security.md、07-user-manual.md、09-compatibility.md
+> 适用环境：**DSH 0.1.1-rc.2（DSH Desktop v2.0.2）**。桌面版 webserver 强制只听 `127.0.0.1`，移动端经插件 **LAN 桥**（默认 `0.0.0.0:3080`）接入；web 版 DSH 无回环限制，可直接让 webserver 绑 0.0.0.0。
+
+## 1. 部署拓扑
+
+```mermaid
+graph LR
+    PH[手机（DSH Remote App）] -->|同一 WiFi：桥 3080| BR[插件 LAN 桥 0.0.0.0:3080]
+    PH -.外出（蒲公英虚拟组网）.-> PG[蒲公英虚拟网卡] -.-> BR
+    BR --> WS[DSH 回环 webserver /m/api]
+    WS --> DSH[dsh services: agents / sessions]
+```
+
+- 手机端：安装 DSH Remote App（构建方法见 §8），连接电脑地址（如 `http://192.168.1.100:3080/m` 或 `https://<蒲公英虚拟IP>:3080/m`——**端口 3080 是插件桥端口**，见 §4b）。
+- 桌面端入口：DSH Desktop 设置页「连接移动端设备」（插件客户端模块）显示二维码与连接信息（二维码在桥监听成功时自动使用桥地址）。
+- 外出访问：**蒲公英组网**（推荐，见 §5.1）；其他虚拟组网/隧道类见 §5.2。
+
+### 1.1 两种运行形态速查（先看你是哪种）
+
+| 形态 | webserver host | 手机连接方式 | 插件额外配置 |
+|---|---|---|---|
+| **web 版**（`dsh --profile web`）| 默认 `0.0.0.0:3080` | **开箱直连** `http://<IP>:3080/m`（老姿势）| 无需 lanBridge、无需覆盖 webserver 行；放行防火墙即可 |
+| **桌面版**（DSH Desktop）| 强制 `127.0.0.1`（不可覆盖）| 启用 **LAN 桥** `0.0.0.0:3080` 后连 `http://<IP>:3080/m` | 见 §4b（桥 + 强口令门禁）|
+
+> web 版说明：0.1.1-rc.2 的 dsh-web-app 默认 webserver `host: 0.0.0.0, port: 3080`（实测 `--dump-config`）；**不需要**写 `- id: webserver` 覆盖行；更老版本（默认 127.0.0.1 时代）才需覆盖且**必须写全 `host`+`port`**（§4 警示）。
+> **实测记录（2026-08-23）**：在隔离 DSH_HOME 以 web profile 启动（`host: 0.0.0.0, port: 3081`）→ 局域网 IP `http://192.168.10.8:3081/m/api/bootstrap` 直连 **HTTP 200**（plugin v3.0.0，`server.urls[0]` 即局域网地址，auth 生效）——web 形态局域网直连实锤；与桌面版（LAN 桥）并存两条路径，均为真机验证。
+
+## 2. 安装位置说明（以桌面版为主）
+
+| 项目 | 位置 |
+|---|---|
+| 插件源码 | `<本仓库>/`（package.json / lib / docs / tools） |
+| 已安装副本 | `~/.dsh/profiles/desktop/node_modules/dsh-mobile-remote/`（web 版为 `profiles/web/...`） |
+| profile 依赖声明 | `~/.dsh/profiles/<profile>/package.json` → `"dsh-mobile-remote": "file:<本仓库路径>"` |
+| 启用配置 | `~/.dsh/profiles/<profile>/cordis.patch.yml`（insert mobile-remote 行；**无需覆盖 webserver 行**，见 §4 警示） |
+| 访问口令 | 部署时生成（`crypto.randomBytes(24).toString('base64url')`），写入 `authToken` |
+
+### 2.1 依赖声明的两种方式
+
+**方式 A（推荐，已实测）—— 本地 clone + `file:` 依赖**：
+
+```powershell
+git clone https://github.com/201222-L/dsh-mobile-remote.git
+# 锁版本（推荐）：tag 与版本号一致；不 checkout 则跟随最新 main
+git -C dsh-mobile-remote checkout v3.0.0
+# profile package.json:
+#   "dsh-mobile-remote": "file:<clone 出来的路径>"
+corepack pnpm install
+```
+
+**方式 B（快捷，免手动 clone）—— 直接写 GitHub 地址，`pnpm install` 自动下载**：
+
+```json
+{ "dependencies": { "dsh-mobile-remote": "github:201222-L/dsh-mobile-remote" } }
+```
+
+**锁定指定版本**（推荐：App 与插件版本保持一致）—— 用 git tag 固定：
+
+```json
+{ "dependencies": { "dsh-mobile-remote": "github:201222-L/dsh-mobile-remote#v3.0.0" } }
+```
+
+**方式 C —— 下载 Release 里的插件包离线安装**：GitHub Releases 的 `dsh-mobile-remote-vX.Y.Z.tgz` 下载后：
+
+```powershell
+# profile package.json:
+#   "dsh-mobile-remote": "file:<下载解压后的包路径>"
+corepack pnpm install
+```
+
+> 版本匹配规则：**App 与插件同版本 = 完美配对**；不同版本也能用（谁旧谁吃亏，但都不崩），详见 README「版本与兼容」。实际配对在 App 设置 → 关于 → 版本查看。
+> 方式 B 依赖网络能访问 GitHub 与 npm（含插件依赖 `qrcode`、`@deepseek-ai/*` 的公开解析；后者桌面端为内置打包、公开 npm 可解析性未逐一验证，遇解析失败请改用方式 A/C）。
+> 更新插件时：方式 A 重新 `git pull` 后 `pnpm install`；方式 B 改 tag 后 `pnpm install`；方式 C 换新 tgz 重装。
+
+## 3. 启用 / 重启步骤
+
+**桌面版（DSH Desktop）**：
+1. 修改插件源码后，同步已安装副本（`file:` 依赖不会自动重装）：`cd ~/.dsh/profiles/desktop && corepack pnpm install`（或直接 `git pull` 后在 profile 目录 `pnpm install`）。
+2. （可选）校验组合配置（不启动）：`npx @deepseek-ai/dsh --profile desktop --dump-config`，确认输出包含 `mobile-remote` 行。
+3. **重启 DSH Desktop**（插件随进程加载）。日志出现 `mobile-remote: lanBridge 已监听 0.0.0.0:3080 → 127.0.0.1:<port>/m/api` 即桥已工作。
+
+**web 版（`dsh --profile web`）**：步骤 1 同上（profile 换 `web`），步骤 3 为重启 `dsh web` 进程；**web 版 webserver 默认即 `0.0.0.0:3080`**（局域网直连开箱即用；无需覆盖 webserver 行，见 §4 警示）。注：web 版直连 webserver 时插件路由在同一个 webserver 上；桌面版见 §4b LAN 桥。
+
+## 4. 变更配置（口令/路径/充值地址）
+
+编辑 `cordis.patch.yml` 改 `mobile-remote` 行的 `config`，然后重启：
+
+```yaml
+- insert:
+    - id: mobile-remote
+      name: dsh-mobile-remote
+      config:
+        path: /m
+        authToken: <新口令，留空=关闭认证>
+        rechargeUrl: https://platform.deepseek.com/top_up
+```
+
+口令生成建议：`node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"`
+
+> ⚠️ **webserver 行覆盖的坑（重要，来自实测 issue）**：cordis patch 对**已有行**是**整体替换 config 对象（非合并）**——若你写 `- id: webserver` + `config: {host: 0.0.0.0}`，DSH 自带行的其余字段（如 `port: !!js ctx.webStartup.port ?? 3080`）会被**顶掉**，而 `port` 是必填 → 启动校验即报 `$port missing required value`（`--dump-config` 与 smoke 测试都不会暴露，只有真启动才报）。
+> **因此**：① **web 版完全不需要覆盖 webserver 行**（默认已是 `host: 0.0.0.0, port: 3080`）；② 若出于自定义（如改端口）确要覆盖，**必须写全全部必填字段**（`host` + `port`）；③ **桌面版（0.1.1-rc.2）webserver 的 `host` 不可改为 0.0.0.0**（DesktopWebServer 构造器对非回环 host 直接 throw，用户 patch 无法覆盖）——移动端访问请用 **§4b 的 lanBridge**，不要覆盖 webserver 行。
+
+## 4b. 局域网直连（同一 WiFi，v3.0.0 新增：桌面版终于可以连了）
+
+> **背景**：DSH Desktop（0.1.1-rc.2 起）强制 web 服务只听 `127.0.0.1`（内核硬限制，改不了），手机无法直连；**web 版默认即监听 `0.0.0.0:3080`**（局域网直连开箱即用，无需覆盖任何行）。v3.0.0 起插件内置 **LAN 桥**：桌面版在 DSH 进程内自建监听，把 `/m` 请求转发给回环服务——手机走局域网 IP 即可连，**无需穿透、无需额外工具、不改 DSH**。
+
+1. **开桥**：`cordis.patch.yml` 的 `mobile-remote` 行 `config` 加：
+```yaml
+        lanBridge:
+          enabled: true
+          port: 3080        # 与其它服务冲突可改；改后手机地址的端口同步改
+          host: 0.0.0.0     # 默认全接口；单机调试可用 127.0.0.1
+```
+2. **重启** DSH，首次监听 `0.0.0.0` 时 Windows 防火墙弹窗点「允许」；或手动放行：
+   `netsh advfirewall firewall add rule name="DSH Mobile LAN" dir=in action=allow protocol=TCP localport=3080`
+3. **手机连**：设置 → 重新配置连接 → 扫码（桌面设置页二维码已自动变为桥地址）或手动填 `http://<电脑局域网IP>:3080/m` + 口令。
+4. **安全**：`authToken` **必须** 配置强口令（桥拒绝无口令启动）；桥只转发 `/m/*`，桌面 `/api` 网关与 `qr-config`/`qr.png` 不转发，不扩大攻击面。
+5. **排查**：`GET /m/api/diagnostics` → `runtime.lanBridge.listening` 应为 `true`；插件日志会打印监听地址；连不上先查防火墙与 IP（`ipconfig`，VMware 虚拟网卡地址手机不可达）。
+6. **升级自检**：App 断线会自动轮换地址（局域网 IP 优先），出门场景仍走第 5 节组网方案，两者不冲突。
+
+## 5. 外出访问（人不在家）
+
+> 共同前提：家里电脑保持开机、dsh 运行。**推荐方案：蒲公英组网**（已真机实测通过，国内可用、免费版够用）。原理是"虚拟局域网"——电脑和手机加入同一个虚拟网，手机无论在家 WiFi 还是户外流量都能直达电脑。**禁止把 3080 端口直接映射/穿透到公网裸奔**。
+
+### 5.1 推荐方案：蒲公英组网（已实测 ✅）
+
+1. **电脑**：从[蒲公英官网下载 PC 客户端](https://pgy.oray.com/download/)安装，登录账号，创建/加入一个**智能组网**（免费版支持 3 个成员）。加入后电脑会获得一个虚拟 IP（客户端界面可见，形如 `172.16.x.x`）。
+2. **手机**：在手机**应用商店搜索「蒲公英」**安装 App，登录**同一账号**，加入**同一组网**，确认手机与电脑都显示「在线」。
+3. **DSH Remote App 首连（关键一步）**：设置 → 重新配置连接 → 手动输入 `http://<电脑虚拟IP>:3080` + 口令。连接成功后，App 会自动把电脑的**局域网 IP 和蒲公英虚拟 IP 都记住**（设置 → 电脑地址显示「共 N 个地址自动切换」）。
+4. **验证**：手机关 WiFi 开流量 → 状态点变绿 → 发一条消息收到回复即成功。
+5. 之后完全自动：出门自动走蒲公英、回家自动走局域网，无需再手动改任何配置。
+6. **账号提示**：以上流程对蒲公英账号可用者完全适用；若账号不可用（登录受限/过期等），属账号个体情况，可改用 §5.2 的其他组网方案，插件侧无需改动。
+
+| 蒲公英 App（移动端） | 蒲公英 PC 客户端 | 应用商店搜索 |
+|---|---|---|
+| ![蒲公英移动端](screenshots/pgy-mobile-app.jpg) | ![蒲公英PC客户端](screenshots/pgy-pc-client.jpg) | ![应用商店搜索](screenshots/pgy-appstore.jpg) |
+
+> ⚠ **手机必须给蒲公英「免死金牌」**（国产 ROM 杀后台是外出断连的头号原因）：设置 → 应用管理 → 蒲公英 → **省电策略「无限制」+ 自启动「允许」**；并在最近任务卡片上**锁定**蒲公英（出现锁图标）。否则手机一省电就把 VPN 杀掉，隧道断了 App 再自动切换也没路可走（表现就是"出门连不上、等一会又好了"）。
+
+### 5.2 其他方案（思路参考，按自己环境自行适配）
+
+任何"虚拟组网/内网穿透"方案都能接，原理完全一致——电脑上会多出一个虚拟网卡（或中继通道），插件会自动把它收进地址列表（`/api/bootstrap` 的 `server.urls`，按「局域网私有地址优先」排序）；App 断线时自动轮换候选地址。已适配的要点：
+
+- **虚拟组网类**（Tailscale / ZeroTier / EasyTier / 路由器 WireGuard / 蒲公英）：电脑加入组网后其虚拟 IP 自动进入地址列表，无需改插件配置；手机首连手动填一次虚拟 IP 即可（**Tailscale 国内控制面不可达，不推荐**；ZeroTier/EasyTier 亦为备选，注意其公共节点是否在服务期——云侧可用性以官方为准）。
+- **隧道/中继类**（frp 自建 / SakuraFrp 托管等）：手机经公网中继访问时，请求的 Host 头是中继地址，需在插件配置显式放行 + 强口令：
+
+```yaml
+- insert:
+    - id: mobile-remote
+      name: dsh-mobile-remote
+      config:
+        path: /m
+        authToken: <16位以上随机口令>       # 公网段的唯一防线，必须强随机
+        trustedHosts: ["<中继域名或IP>"]    # 如 frp-boy.com / xxx.natfrp.com
+```
+
+> 隧道类注意：域名接入国内托管/反代通常要求 **ICP 备案**（自有域名绑定公网服务必然遇到）；未备案时请选择**免备案节点地址/自带域名**，并务必保证 **TLS**（公网明文 HTTP = 口令暴露，违反 04-security 禁止项）；若隧道方案拿不到 TLS/免备案入口，请转向 §5.1 的虚拟组网。
+- 全部方案通用：`authToken` 保持开启、别把 3080 裸奔暴露公网；换隧道/换节点后更新手机地址与 `trustedHosts` 即可。
+
+## 6. 推送桥配置（可选，部署者 3 分钟）
+> agent 完成 / 需要你回答 / 失败 → 手机系统通知。**不配置则无推送**，其他功能不受影响。
+> 电脑只需能正常上网（HTTPS 出站），无需公网端口。
+在 `cordis.patch.yml` 的 `mobile-remote` 行 `config` 下加 `pushUrls`（可配多个通道，事件同时推送到全部）：
+
+### 企业微信群机器人（微信推送，推荐：国内稳定、免登录态、几乎无配额限制）
+> 建一个企业微信群（同事/家人/自己一人群均可）→ 群设置 → 添加群机器人 → 复制 **Webhook URL**（形如 `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=…`）。约 20 条/分钟限额，足够日常提醒。
+```yaml
+        pushUrls:
+          - name: 企业微信
+            url: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=<你的key>
+            format: wecom
+```
+
+### Server酱（微信服务号推送，安卓/全平台通用）
+```yaml
+- insert:
+    - id: mobile-remote
+      name: dsh-mobile-remote
+      config:
+        path: /m
+        authToken: <口令>
+        pushUrls:
+          - name: 微信
+            # Server酱³（推荐）：SendKey 页面可复制 API URL，形如
+            # https://<uid>.push.ft07.com/send/<sendkey>.send （key 以 sctp…t 开头）
+            url: https://<uid>.push.ft07.com/send/<sendkey>.send
+            format: serverchan
+```
+
+Server酱³ SendKey 获取：手机微信扫码打开 `https://sc3.ft07.com/sendkey` → 复制 **API URL**（推荐，`push.ft07.com` 官方入口）。老 Turbo 接口 `sctapi.ftqq.com` 域名偶发不可用（实测 400/连接失败，2026-08），建议用 ³ 官方 URL；`format: serverchan` 两者通用（form: title/desp）。**免费版每天 5 条上限**（AUTH 40001），需更多条数请升级。
+### ntfy（安卓系统通知栏，开源自托管友好）
+```yaml
+        pushUrls:
+          - name: ntfy
+            url: https://ntfy.sh/<你的随机topic>
+            format: ntfy
+```
+
+手机装 ntfy App 订阅同一 topic。注意公共服务器 topic 可被猜测，建议用长随机串。⚠️ **`ntfy.sh` 公共服务器在境内通常无法直连**（实测连接超时）——局域网自托管 ntfy 才推荐用这条，否则建议用上面的企业微信机器人或 Server酱。
+### Bark（iPhone）
+```yaml
+        pushUrls:
+          - name: Bark
+            url: https://api.day.app/<你的key>
+            format: bark
+```
+
+### 通用 webhook
+
+```yaml
+        pushUrls:
+          - name: 自建
+            url: https://your-server.example.com/hook
+            format: generic
+```
+
+**验证两种方式**：
+1. **推荐：App 设置 → 通知 → 「发送测试通知」**— 配置后重启桌面端，手机点一下即可逐通道验证（绕过节流，结果数即"几个通道成功"）；
+2. 或让 agent 跑一个任务（完成/失败/提问任一发）看是否收到。
+同会话同类型 60 秒内合并（`pushCooldownMs` 可调）。
+> **隐私**：推送默认只含「事件类型 + 会话短码」（`pushContent: minimal`），会话标题/错误详情等核心内容不经过第三方通道；确需完整内容（信任通道时）在 config 加 `pushContent: standard`。
+
+## 6b. HTTPS 反代（可选）
+
+> 适用：不信任的 WiFi（酒店/咖啡馆）、或经公网反代访问。原理：用反向代理（Caddy/nginx）在 3080 前加 TLS。
+> **证书**：App 按标准 TLS 校验，**不支持放行自签证书**。请使用受信任 CA（需公网域名，Let's Encrypt），或自建内网 CA 并把**根证书安装进手机**（设置 → 安全 → 安装证书）。
+> **提示**：如需公网域名，国内域名接入须 **ICP 备案**（见 §5.2 提示）；内网自用可直接用内网 CA（mkcert）。
+
+**Caddy 示例（mkcert 内网 CA）**：
+
+```powershell
+# ① 生成内网 CA 并签发证书（安装 mkcert 后）
+mkcert -install                 # 把 CA 根证书装进系统
+mkcert 192.168.1.100 172.16.x.x # 给电脑的局域网/组网 IP 签证书
+# ② Caddyfile：
+#   :3443 {
+#     tls <生成的 cert.pem> <生成的 key.pem>
+#     reverse_proxy 127.0.0.1:3080
+#   }
+# ③ 把 mkcert 的 CA 根证书传到手机安装（Android：设置 → 安全 → 加密与凭据 → 安装证书）
+# ④ 启动 caddy，App 手动连接 https://<电脑IP>:3443 + 口令
+```
+
+**注意**：
+- 反代只负责传输加密；`authToken` 仍必须启用（v2.6 起未启用会在启动日志与设置页显式警示）。
+- 地址自动收集/二维码按 http 生成；HTTPS 场景请手动填地址。
+- 纯局域网 + 蒲公英（WireGuard 加密）场景无需 TLS。
+
+## 7. 回滚方案
+
+1. 从 `cordis.patch.yml` 删除 `mobile-remote` 行（如有 `webserver` 覆盖行一并删除——若确需写该覆盖，务必按 §4 警示补全必填字段）。
+2. 从 `package.json` 删除 `dsh-mobile-remote` 依赖并 `corepack pnpm install`。
+3. 重启 DSH（Desktop 或 web）。插件路由、SSE 连接随 fiber dispose 全部释放，桌面 GUI 不受影响。
+
+## 8. Flutter App（dsh-mobile-app，安卓）
+
+> 源码：`dsh-mobile-app/` 子目录（独立 Flutter 工程，与插件同仓库发布）。
+### 8.0 安装 App（推荐：直接下载 APK）
+
+**无需编译环境**：从 [GitHub Releases](https://github.com/201222-L/dsh-mobile-remote/releases/latest) 下载 `DSH-Remote-*.apk`（正式签名）传到手机安装即可。愿意自己改代码/构建的开发者见 §8.2。
+### 8.1 架构
+
+App = **原生 Flutter 应用**（非 WebView）：全部界面用 Flutter 原生组件绘制，与插件 `/m/api` 共享同一套 API 与设计令牌（DeepSeek 配色）。
+- 连接：扫码连接（扫桌面 DSH 设置页「连接移动端设备」二维码）或手动输地址+口令。
+- 页面：首页（欢迎 + 最近会话）、对话（流式回复、Markdown、token 用量、工具活动条、图片渲染与全屏）、会话列表、通知中心、设置（余额/默认预设/深色模式/环境诊断）、新建会话（模式 + 工作目录跨盘浏览）。
+- 数据：全部实时读写 PC 端 DSH，无本地状态。
+### 8.2 构建 APK
+
+前置：Flutter SDK（本项目用 3.47.0） + Android SDK。
+
+**构建、Release 签名、代理、Gradle/缓存排障与产物校验的完整步骤，统一见发布操作手册 [`docs/10-release.md`](10-release.md) §4（构建）与[附录 A（Android 构建与排障）](10-release.md#附录-aandroid-apk-构建与排障)。** 日常开发的最短路径：
+
+```powershell
+cd dsh-mobile-app
+flutter analyze        # 应为 No issues found
+flutter build apk --release
+# 产物：build\app\outputs\flutter-apk\app-release.apk
+```
+
+> 正式发布必须走 `docs/10-release.md`（含版本 bump、载体打包、预检、演练与发布顺序）；本文件不再重复签名/排障细节，避免两处维护。
+> 更换图标：把 1024×1024 PNG 覆盖到 `assets/icon-1024.png`，运行 `python tools/make_icon.py` 后重新构建。
+> 多品牌/兼容性注意事项见 docs/09-compatibility.md。
+### 8.3 安装与使用
+1. 把 APK 传到手机（微信文件传输/网盘/USB），点击安装（需允许"安装未知来源应用"）。
+2. 打开 App →「扫码连接」对准电脑屏幕上的二维码（桌面 DSH 设置 →「连接移动端设备」页）；或手动输入电脑地址 + 访问口令。
+3. 连接成功进入首页，直接发消息派活。
+> 说明：Android 9+ 默认禁止明文 HTTP，App 已配置 `usesCleartextTraffic`，仅限局域网/内网使用，勿暴露公网。
+> 换签名安装会报「签名不一致」：先卸载旧版再装新版（连接信息需重新扫码）。
+### 8.4 重建与更新
+- 插件/网页端改动 → 按 §3 同步并重启 DSH。
+- App 改动 → 重新 `flutter build apk --release` 并重装（同签名覆盖安装，保留连接信息）。
+
+## 9. 验收清单（已执行 ✅）
+
+- [x] `--dump-config` 含 mobile-remote 行；启动日志含 lanBridge 监听行（桌面版）
+- [x] **web 版局域网直连实测**（2026-08-23，隔离 DSH_HOME）：`0.0.0.0:3081` + 局域网 IP bootstrap 200
+- [x] 未认证 401 / 错误口令 401 / 正确口令通行
+- [x] `POST /m/api/send` 注入成功（200 + messageId；图片路径 200 + accepted:true）
+- [x] SSE 连接 + hello + 事件转发（重连退避、断线补拉、pendingFrames 回放、心跳 25s）
+- [x] `/m/qr.png` 返回 PNG
+- [x] 桌面设置页「连接移动端设备」二维码 + App 扫码自动连接
+- [x] Flutter App：analyze 零问题 + 正式签名 release 构建 + 真机全流程测试
+- [x] 问询弹窗端到端（手机选选项→agent 收到答案 / ✕→取消 / PC 端先答两端同步）
+- [x] 权限审批弹窗端到端（允许一次→操作继续 / 拒绝→操作被拒）
+- [x] 通知删除（单删/批量/清空）+ 诊断页服务探针（respondBridge/frameBridge ✅）
+- [x] 图像链路实机：发送/渲染/全屏/限额/类型纠正（v3.0.0 全套，见 CHANGELOG）

package/docs/07-user-manual.md

@@ -0,0 +1,65 @@
+# 07 用户操作手册 — DSH Remote
+
+> 版本：v2.7.0 · 配套：06-install-run.md · 面向使用手机 App 的最终用户
+## 1. 快速开始
+1. 确认电脑端 dsh（DeepSeek Harness）正在运行。
+2. 手机与电脑连接**同一 WiFi**；**人不在家**时用蒲公英组网（电脑+手机装蒲公英客户端、同一组网，见 06-install-run.md §5）。
+3. 打开 DSH Remote App：
+   - **扫码连接**：对准电脑屏幕上 dsh 设置页「连接移动端设备」的二维码，自动填入地址+口令。
+   - **手动输入**：地址 `http://<电脑局域网IP>:3080`（外出首次手动填电脑的蒲公英虚拟 IP） 访问口令（部署者配置的 `authToken`）。
+4. 连接成功进入首页，直接发消息派活。
+## 2. 界面说明
+
+| 区域 | 功能 |
+|---|---|
+| 首页 | 欢迎语 + 最近会话 + 底部输入框（模型/权限胶囊）；右上角铃铛进通知 |
+| 对话页 | 消息流：你的消息（右）、Harness 回复（左，Markdown 渲染）、token 用量、轮次分隔线；底部输入框发送，状态点显示执行中/等待回答 |
+| 会话列表 | 全部会话（标题/时间/工作目录），点按进入；下拉刷新 |
+| 通知中心 | 完成✅ 失败❌ 需回答⚠ 三色通知，未读角标，点击跳转会话，全部已读 |
+| 设置 | 连接信息（电脑地址可点按切换）、默认 Agent/权限预设、余额、深色模式、环境诊断、重新配置连接 |
+
+## 3. 常用操作
+
+**发消息/派任务**：首页或对话页底部输入 → 发送。消息注入电脑端正在运行的 agent，立即开始执行；手机实时看到流式回复。
+**切换会话**：抽屉 → 会话 → 点按进入。标题与 PC 端实时同步。
+**切换工作区**：抽屉 → 工作区（或会话页顶部筛选条）→ 选择目标工作区。会话列表与首页"最近会话"只显示该工作区下的会话；新建会话默认在该工作区目录下创建。
+**看更早的消息**：对话页向上滑动——滑到顶部会自动加载更早一页，继续上滑继续加载（微信式，无断页）；已到会话开头会有提示。往上翻后右下角（输入框正上方）会出现灰白色「回到底部」圆钮，点按直接回到最新消息。
+**收通知**：agent 完成任务/需要你回答/失败时，App 通知页出现通知；配合推送桥（企业微信机器人 / Server酱 / ntfy / Bark，配置见 docs/06 §6）可收**手机系统弹窗**——不依赖 App 常驻后台。推送默认只含事件类型与会话短码，会话内容不经过第三方通道。
+**删除通知**：通知页**长按**某条可单独删除；右上角垃圾桶 → 批量多选删除或清空全部。仅删除手机 App 里的记录，不影响电脑端。
+**审批/回答**：agent 思考途中需要你拍板时，对话页弹出卡片——按选项选择（可多选），或输入你自己的答案后「提交」；工具需要更高权限时弹出「权限请求」，选「允许一次 / 拒绝」。与电脑端同一个待办，任一端回答后两端同时消失；也可点卡片右上角 ✕ 取消（agent 按取消继续）。agent 只是等待你普通回复时（状态点橙色），直接输入消息即可。
+**新建会话**：首页「＋ 新建会话」→ 选模式（标准/PTC/极简/创造）→ 可选工作目录（跨盘浏览、可新建文件夹）→ 创建。
+**修改默认配置**：设置 → 默认 Agent 预设 / 默认权限预设 → 选择（作用于之后新建的会话，与 PC 端同一写入通道）。
+**深色模式**：设置 → 深色模式：跟随系统 / 深色 / 浅色。
+**外出使用**：电脑和手机都装蒲公英客户端登录同一账号、加入同一组网（电脑保持开机）。首次在 App 里手动填一次电脑的蒲公英虚拟 IP（`http://172.16.x.x:3080`），之后 App 自动切换：出门走蒲公英、回家走局域网（设置 → 电脑地址显示「共 N 个地址自动切换」）。详见 06-install-run.md §5。
+**切换电脑地址**：设置 → 电脑地址 → 点按弹出候选地址列表（当前地址打勾），选择后自动探测可达并切换重连——回家切局域网、出门切蒲公英（v2.5.0 起）。
+**重新配置连接**：设置 → 重新配置连接 → 回到连接页（可重新扫码/输入）。
+## 4. 安全须知
+
+- 访问口令是唯一凭据：二维码含口令，请勿截屏转发；怀疑泄露立即在 `cordis.patch.yml` 更换并重启。
+- App 仅与电脑直连（局域网/蒲公英虚拟网），无 TLS —— 只在**自家可信 WiFi** 或**虚拟组网**下使用；不要把 3080 端口暴露公网。
+- 连接信息仅存手机本地，不上传任何第三方。
+## 5. 常见问题（FAQ）
+**Q1 连接失败/超时**
+- 电脑端 DSH 是否运行？**桌面版请确认插件 LAN 桥已启用**（`lanBridge.enabled: true`，默认 `0.0.0.0:3080`，见 docs/06 §4b）；web 版默认即 `0.0.0.0:3080` 无需配置（改端口时覆盖 webserver 行须写全 `host`+`port`）？
+- 手机与电脑是否同一网络？口令是否正确（改过需重启桌面端）？
+- Windows 防火墙若拦截 3080，放行 `node`/`DeepSeek Harness`。
+**Q2 扫码没反应**
+- App 用自带「扫码连接」按钮（系统相机会跳浏览器打开网页）；二维码随口令变更而更新（改口令需重启桌面端）。
+**Q3 发消息没反应**
+- agent 正在处理上一轮时新消息会**排队**（App 有提示）；等上一轮完成。
+- 状态点：绿色=执行中，橙色=等待你回答（直接回复）。
+**Q4 收不到系统通知**
+- 需部署者配置 `pushUrls`（企业微信机器人 / Server酱 / ntfy / Bark，见 docs/06 §6）；检查手机通知权限。
+- **先验证通道**：设置 → 通知 → **「发送测试通知」**——逐个通道发测试消息，返回"成功几个"；失败的通道对照 docs/06 检查 URL/格式/配额（Server酱每日 5 条、ntfy.sh 境内不通等）。
+**Q5 看不到实时回复**
+- SSE 断线自动重连（指数退避），恢复后自动补拉历史；检查网络。
+**Q6 新建会话在 PC 端显示"未分组"**
+- 所选目录不在任何已注册工作区（或其子目录）；在工作区子目录下会自动归属。
+**Q7 agent 问问题/要权限时，手机不弹卡片**
+- 确认你在**该会话的对话页**（弹窗是会话内的，别处只有通知中心「需要你回答」条目，点进去即见弹窗）。
+- 电脑端 dsh 是否为最新版并已**重启**（弹窗桥随插件加载）？App 设置 → 环境诊断：`respondBridge`/`frameBridge` 应为 ✅（否则见 docs/09-compatibility.md）。
+- 若电脑上也没有弹窗：可能是该会话审批策略为「从不询问」，或你的 Harness 已配置自动答题/自动审批（此时不弹窗是正常行为）。
+**Q8 其他品牌手机能用吗 / 有苹果版吗**
+- Android 7.0+ 均可（渲染自动回退，详见 docs/09-compatibility.md §3）；苹果端尚未开发（§4）。
+**Q9 换手机/重装后要重新连接吗**
+- 要：连接信息只存手机本地，换机后用二维码重新扫一次即可（口令未变则无需改电脑端）。

package/docs/08-/346/211/251/345/261/225/345/274/200/345/217/221/346/214/207/345/215/227.md

@@ -0,0 +1,86 @@
+# 08 扩展与二次开发指南
+> 本项目的设计目标之一就是**容易扩展**：从改一行文案到加一个完整功能，都有清晰的切入点。
+> 欢迎你在此基础上创建自己的版本，也欢迎把好的改动 PR 回上游。
+> 注：v2.1 起已移除网页版（`page.html`），移动端仅原生 App；扩展主要落在服务端端点、插件契约与 App 界面。
+## 1. 扩展点总览（由浅入深）
+
+| 层级 | 能改什么 | 难度 | 入口 |
+|---|---|---|---|
+| 文案/样式 | 首页文案、配色、圆角、间距 | ★ | App `lib/theme.dart`、各 screen |
+| 插件动作区 | 第三方插件往移动端加"快捷动作" | ★★ | 插件契约 `mobileActions`（见 §2） |
+| 推送通道 | 自定义通知渠道 | ★★ | `pushUrls` + `pushToChannel`（见 §3） |
+| 服务端端点 | 新 API（自定义数据/操作） | ★★★ | `lib/index.js` `handleApi` |
+| App 原生界面 | 主题、图标、页面、深色模式 | ★★★ | `dsh-mobile-app/`（Flutter） |
+| 桌面设置页 | 扫码页样式/信息 | ★★ | `lib/client.js`（dsh 客户端模块） |
+
+## 2. 插件动作区（最推荐的扩展方式）
+
+任何 dsh 插件都可以向移动端注册"快捷动作"——对话页底部自动出现动作按钮，点击后带参数执行。`mobileActions` 服务由本插件提供（`ctx.provide`），**其他插件消费**：
+
+```js
+// 你的插件里：取服务并注册
+const mobileActions = ctx.get("mobileActions");
+mobileActions?.register({
+  id: "translate-clipboard",
+  title: "翻译剪贴板",
+  icon: "globe", // 移动端 App 内置图标 id（见 dsh-mobile-app 图标映射）
+  fields: [{ key: "target", label: "目标语言", placeholder: "en" }],
+  handler(args) {
+    const text = clipboard.read();
+    return translator.translate(text, args.target);
+  },
+});
+```
+
+注册后：移动端对话页自动出现「翻译剪贴板」按钮 → 点击弹参数表单 → 执行（跑在电脑端）→ 结果经会话消息回流。
+**约定**：`handler` 在电脑端执行；长任务不要同步等待，通过发消息/工具调用呈现进展（`POST /m/api/actions/:id/invoke` 立即返回 `accepted`）。
+## 3. 自定义推送通道
+
+`pushUrls` 支持 `generic` 格式 —— 任何 HTTP webhook 都能接：
+
+```yaml
+pushUrls:
+  - name: 我的机器人
+    url: https://my-bot.example.com/hook
+    format: generic   # POST JSON: { kind, title, detail, sessionId, time }
+```
+
+想加一个**正式通道**（像 serverchan/ntfy 那样有专属格式）：
+1. 在 `lib/index.js` 的 `pushToChannel` 加一个 `else if (target.format === "xxx")`
+2. `docs/03-api.md` 与 README 推送节补说明
+## 4. App 定制（dsh-mobile-app）
+- **主题**：`lib/theme.dart` —— DeepSeek 设计令牌集中在这一个文件（浅色/深色两套），换色只改这里
+- **图标**：覆盖 `assets/icon-1024.png` → `python tools/make_icon.py` → 重新构建
+- **页面**：`lib/screens/` 每页一个文件，结构清晰
+- **状态/事件**：`lib/store.dart` 全局状态 + SSE 事件桥；`lib/api.dart` 全部 API 调用
+- **构建**：见 App README（`flutter analyze` + `flutter build apk --release`）
+## 5. 桌面设置页定制（lib/client.js）
+- dsh 设置页「连接移动端设备」由 `client.js` 客户端模块提供（React 手写，无构建链）
+- 数据来自 `/m/api/qr-config`（仅 loopback）；二维码经 `/m/qr.png?text=...` 生成
+- 改文案/布局直接编辑该文件，重启桌面端生效
+## 6. 保持兼容的约定
+改代码时请守住这些边界（否则可能破坏既有部署）：
+
+- **路由**：`/m` 前缀与 `handleApi` 结构不要动；新端点加在 `handleApi` 内并补文档
+- **认证**：新端点默认走统一鉴权；含敏感数据的端点只允许 loopback（参考 `/api/qr-config`）
+- **API 兼容**：已发布端点（docs/03-api.md 总表）的响应结构不要破坏性变更；要改就加字段
+- **SSE 事件格式**：`summarizeEvent` 输出结构是 App 依赖的契约
+- **App 多端并存**：App 与脚本测试共享同一 API，改服务端时都要验证
+
+## 7. 分享你的版本
+
+- **小改动**：直接提 PR 回上游（见 CONTRIBUTING.md）
+- **个性化定制**：Fork 后改自己的分支，README 注明基于哪个版本
+- **独立插件**：动作区/新端点做成独立 dsh 插件（依赖 `ctx.provide("mobileActions")`），互不冲突
+- **展示**：欢迎在 README「衍生项目」区挂你的链接
+## 8. 常见扩展需求速查
+
+| 想要 | 改哪里 |
+|---|---|
+| 换首页欢迎语 | `home_screen.dart`（App） |
+| 换主题色 | App `lib/theme.dart` |
+| 加一个快捷操作按钮 | 动作区注册（§2） |
+| 推送发到我的机器人 | generic webhook（§3） |
+| 对话页加特殊消息类型 | `summarizeEvent` + App `chat_screen.dart` 渲染 |
+| 新建会话加字段 | `handleApi` `/sessions` + 弹层 |
+