dsh-zen-remote 1.0.0

package/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md — dsh-zen-remote
+
+单一 npm 包 `dsh-zen-remote`，DSH（DeepSeek Harness）的 bundle 插件。
+一个包里有两半代码，但**对用户是一个插件**：文档、安装说明、README 都不要
+再按「两个包」叙述（2026-08-17 由 monorepo 的 `packages/gateway` +
+`packages/mobile-ui` 合并而来，包名 `dsh-mobile-pwa` 与
+`@dsh-external/dsh-mobile-nav` 已作废）。
+
+## 目录
+
+| 路径 | 作用 |
+| --- | --- |
+| `package.json` | 单包声明：`dsh.bundle.patch` → `cordis.patch.yml`，`dsh.client` → `exports["./client"]` |
+| `cordis.patch.yml` | 组合层，三行 insert（界面 / 网关 / 推送），随包自带 |
+| `src/index.ts` → `lib/index.js` | host 半边入口（插件行 `dsh-zen-remote`）：唯一一条路由 `POST /_dsh/mobile-nav/upload` |
+| `src/client/**` → `lib/client.js` | 浏览器半边（同一插件行，经 `dsh.client` 发现）：app 外壳、slot、样式 |
+| `lan-gate.mjs` | 网关 Cordis entry（插件行 `dsh-zen-remote-gateway`）：spawn 子进程 |
+| `lib/lan-gate-server.cjs` | 网关本体（独立 Node 子进程，Node stdlib + `web-push`） |
+| `dsh-push.mjs` | 推送 entry（插件行 `dsh-zen-remote-push`）：回合结束推送 + `push_notify` 工具 |
+| `pwa/**` | manifest / service worker / 注入脚本 / 手势 / 壳级 CSS / 图标 |
+| `test/*.test.cjs` | 网关侧测试（真子进程 + mock 上游） |
+| `scripts/check-*.mjs` | 界面侧自检（纯 `node:assert`，靠 Node ≥23.6 类型剥离直接 import `.ts`） |
+| `scripts/build-client.mjs` | client 打包器（内联相对模块 → `__ModuleLoader__.load({id:"dsh-zen-remote"})`） |
+| `docs/**` | 深度文档，见下 |
+
+## 命令
+
+```sh
+pnpm install
+pnpm build     # tsc host + tsc client + build-client.mjs → lib/（产物入库，改 src/ 必须重跑并提交 lib/）
+pnpm verify    # 两个 tsconfig 的 --noEmit 类型检查
+pnpm test      # 网关 43 个 node:test 用例 + 三个界面自检脚本，一条命令全跑
+```
+
+## 深度文档
+
+| 文件 | 内容 |
+| --- | --- |
+| [`docs/remote-access.md`](docs/remote-access.md) | 通道半边：反代配置（nginx/Caddy/Lucky）、配对流程、环境变量表、管理 API、推送、安全边界 |
+| [`docs/interface.md`](docs/interface.md) | 界面半边：断点策略、调试徽章、安全区体系、兼容插件清单 |
+
+## 合仓后仍然成立的硬约束
+
+- **网关是子进程**：`lan-gate.mjs` 只负责 spawn + 生命周期，永远不要把
+  `lib/lan-gate-server.cjs` import 进 DSH 进程。
+- **CSS 分工没变**：排版类规则在 `src/client/styles/`；`pwa/app.css` 只留壳级
+  规则（iOS 输入框防缩放、安全区滚动补偿、代码块横向滚动）。两边抢同一个元素
+  是历史事故的根源，加规则前先确认归属。
+- **`lib/` 是产物，不手改**：改 `src/` → `pnpm build` → 提交 `lib/`。
+- **桌面必须 no-op**：≥1024px 逐像素与未安装时一致。
+  是从真机事故里攒出来的，改相关代码前先读。

package/LICENSE

@@ -0,0 +1,38 @@
+MIT License
+
+Copyright (c) 2026 dsh-zen-remote contributors
+Copyright (c) 2026 mexiaosqwq — original dsh-web-mobile — 界面层上游 / upstream of the interface half
+Copyright (c) 2026 dsh-mobile-pwa contributors — 通道层上游 / upstream of the gateway half
+Copyright (c) 2026 Bernardxu123 — original dsh-mobile-gate (base for lib/lan-gate-server.cjs)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTICE — provenance of the two packages merged into this repository:
+
+* `packages/mobile-ui` derives from `dsh-web-mobile` (MIT, mexiaosqwq), rewritten
+  into an app-shell information architecture for phone widths (v2.0).
+* `packages/gateway` derives from `dsh-mobile-pwa` (MIT), which itself derives
+  from `dsh-mobile-gate` (MIT, Bernardxu123). The gateway
+  `packages/gateway/lib/lan-gate-server.cjs` is based on that original, extended
+  with pairing-code authentication, per-device tokens, PWA manifest/service-worker
+  injection and VAPID Web Push.
+
+Each package keeps its own LICENSE file with the upstream copyright lines intact.

package/README.md

@@ -0,0 +1,237 @@
+<h1 align="center">dsh-zen-remote</h1>
+<p align="center">把 DeepSeek Harness 变成一个能从公网安全访问的手机 App：移动端界面重排 + 配对认证网关 + 装到主屏 + 锁屏推送。</p>
+
+<p align="center">
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0B7285?style=flat-square" alt="MIT"></a>
+<img src="https://img.shields.io/badge/release-v1.0.0-5B4CF0?style=flat-square" alt="v1.0.0">
+<img src="https://img.shields.io/badge/DSH-Web%20Profile-5B4CF0?style=flat-square" alt="DSH Web Profile">
+</p>
+
+| 会话列表主屏 | 会话页 | 会话信息卡 |
+| --- | --- | --- |
+| ![会话列表主屏](assets/home.png) | ![会话页](assets/session.png) | ![会话信息卡](assets/info.png) |
+
+| composer 权限 sheet | 公网设备看到的配对页 |
+| --- | --- |
+| ![composer 权限 sheet](assets/sheet.png) | ![配对页](assets/pairing.png) |
+
+> 截图为 390×844 手机视口、浅色主题；深浅主题均适配。配对页是网关自绘页面，固定深色设计。
+
+---
+
+## 安装
+
+```sh
+dsh plugin add dsh-zen-remote
+```
+
+装完重启 `dsh web`，手机界面与网关一起生效，不需要再手写任何配置行。
+
+> 兼容性：在 DSH `0.1.0-rc.6`（web profile）上开发并实测，最后验证 2026-08-18。
+
+卸载：`dsh plugin remove dsh-zen-remote`（或从 profile 的 `dependencies` 与 `bundles` 里删掉那两行），重启 `dsh web` 即恢复原状；要清掉配对数据再删 `~/.dsh/lan-gate-state.json` 与 `~/.dsh/lan-gate.config.json`。
+
+<details>
+<summary>手动写法 / 本地开发</summary>
+
+手动改 `~/.dsh/profiles/web/package.json`——`dependencies` 一行、`bundles` 一行：
+
+```jsonc
+{
+  "dependencies": {
+    "dsh-zen-remote": "^1.0.0"        // 本地开发换成 "link:/path/to/dsh-zen-remote"
+  },
+  "dsh": { "profile": { "bundles": [
+    "@deepseek-ai/dsh-base",
+    "@deepseek-ai/dsh-web-app",
+    "dsh-zen-remote"
+  ] } }
+}
+```
+
+```sh
+cd ~/.dsh/profiles/web && pnpm install
+# 重启 dsh web
+```
+
+不想走 profile 安装流程的静态挂载写法见 [`cordis.patch.yml.example`](cordis.patch.yml.example)。
+
+从旧的两包结构（`dsh-mobile-pwa` + `@dsh-external/dsh-mobile-nav`）升级：两行依赖、两条 bundle 换成上面的一行一条，并把 profile 的 `cordis.patch.yml` 里手挂 `dsh-mobile-pwa/dsh-push.mjs` 的那行删掉——推送现在随包自带。
+</details>
+
+---
+
+## 配置公网访问
+
+装完在本机 `127.0.0.1:3080` 就能用手机界面。要从外面访问，按下面三步走。
+
+### 1. 配一个反代终结 HTTPS
+
+网关默认只监听 `127.0.0.1:3088`，必须由你自己的反代对外。**家宽没有公网 IP、或者不想开路由器端口**，就跳过 nginx/Caddy 直接看第三个块（Cloudflare Tunnel）。
+
+<details open>
+<summary><b>nginx</b></summary>
+
+```nginx
+# http {} 块里加一次
+map $http_upgrade $connection_upgrade { default upgrade; '' close; }
+
+server {
+    listen 443 ssl http2;
+    server_name dsh.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/dsh.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/dsh.example.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:3088;
+        proxy_http_version 1.1;
+
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        proxy_buffering off;
+        proxy_read_timeout 3600s;
+    }
+}
+```
+
+</details>
+
+<details open>
+<summary><b>Caddy</b></summary>
+
+```
+dsh.example.com {
+    reverse_proxy 127.0.0.1:3088
+}
+```
+
+</details>
+
+<details open>
+<summary><b>没有公网 IP？用 Cloudflare Tunnel</b></summary>
+
+家宽拿不到公网 IP、或者不想在路由器上开端口时用这个：`cloudflared` 从你这台机器主动连出去，Cloudflare 那边负责域名、证书和入口，路由器一个端口都不用开。免费版够用。
+
+前置：域名托管在 Cloudflare（NS 指过去）。
+
+1. 打开 [Zero Trust 控制台](https://one.dash.cloudflare.com/) → **Networks → Tunnels → Create a tunnel** → 选 **Cloudflared**，起个名字，创建后页面会给你一条带 token 的安装命令；
+2. 在跑 DSH 的这台机器上执行那条命令（就是下面这个形状，token 用页面给的）：
+
+   ```sh
+   # macOS / Linux：装成常驻服务，开机自启
+   cloudflared service install eyJhIjoi...你的token
+   ```
+
+3. 回到隧道详情页 → **Public Hostname** → **Add a public hostname**：
+
+   | 字段 | 填什么 |
+   | --- | --- |
+   | Subdomain / Domain | `dsh` / `example.com`（即 `dsh.example.com`） |
+   | Service Type | `HTTP` |
+   | URL | `127.0.0.1:3088` |
+
+   保存后 `https://dsh.example.com` 就通了，证书 Cloudflare 自动签。网关的 `LAN_GATE_HOST` 保持默认 `127.0.0.1` 即可——`cloudflared` 就在本机。
+
+**装完必须做第 2 步的 403 自检**，这一步对隧道尤其要紧：`cloudflared` 和网关走的是本机回环连接，网关区分「公网访客」和「坐在这台电脑前的你」，全靠隧道有没有带上 `X-Forwarded-For`。`cloudflared` 默认是带的，所以配对墙正常生效；但万一你的版本或配置把它去掉了，公网请求就会被当成本机管理员，配对墙形同虚设——**用手机流量访问 `/lan-gate/admin`，看到 403 才算安全**。
+
+> 提示：不用设 `LAN_GATE_TRUSTED_PROXIES`——网关本来就把回环来的连接当作可信反代，填 `127.0.0.1` 是空操作，也**不能**替代上面那个自检。
+>
+> Cloudflare 免费版支持 WebSocket（DSH 对话流需要），单个请求体上限 100MB，高于本插件默认的 20MB 上传上限，不影响使用。
+
+命令行流程（`cloudflared tunnel login` / `create` / `route dns` + `config.yml` 里写 ingress）见 [docs/remote-access.md](docs/remote-access.md#cloudflare-tunnel没有公网-ip-时的接入方式)。
+</details>
+
+Lucky（路由器/NAS）的配法见 [docs/remote-access.md](docs/remote-access.md#lucky)。反代与网关不在同一台机器时，要把反代出口 IP 填进 `LAN_GATE_TRUSTED_PROXIES`。
+
+### 2. 自检
+
+用**手机流量**（别连家里 Wi-Fi）访问 `https://你的域名/lan-gate/admin`，正确结果是 **403**。
+
+能看到管理页说明反代没带 `X-Forwarded-*` 头，公网请求被当成了本机用户——回去检查转发头再往下走。
+
+### 3. 配对设备
+
+```sh
+# 在跑 DSH 的这台机器上，用本机浏览器打开
+open http://127.0.0.1:3088/lan-gate/admin
+```
+
+1. 点「生成配对码」，得到 8 位码（10 分钟有效、只能用一次）；
+2. 手机打开你的 HTTPS 域名，在配对页输入这个码；
+3. 配对成功即进入 DSH，身份存在长期 Cookie 里，换网络不掉线；
+4. 浏览器菜单「添加到主屏幕」装成 App；
+5. 同意通知权限，agent 干完活推到锁屏。
+
+管理页还能改设备名、设备类型，或单独/全部吊销设备。
+
+---
+
+## 可选配置
+
+环境变量，或 `~/.dsh/lan-gate.config.json`（键名是变量去前缀转小驼峰，如 `port` / `trustedProxies`；显式环境变量优先）。改完重启 `dsh web`。
+
+| 变量 | 默认 | 说明 |
+| --- | --- | --- |
+| `LAN_GATE_PORT` | `3088` | 网关端口；被占用自动往上试（最多 +20） |
+| `LAN_GATE_HOST` | `127.0.0.1` | 监听地址；反代不在本机时才需要放开 |
+| `LAN_GATE_TARGET_PORT` | `3080` | 本机 DSH Web UI 端口 |
+| `LAN_GATE_RATE_LIMIT` | `120` | 未配对请求的每分钟上限（按真实客户端 IP） |
+| `LAN_GATE_TRUSTED_PROXIES` | 空 | 逗号分隔 IP；反代不在本机时必填 |
+| `LAN_GATE_VAPID_SUBJECT` | `mailto:admin@localhost` | 推送联系人。**iOS 必须改成真实邮箱或 https 网址**，否则 Apple 拒发 |
+| `DSH_PUSH_EVENTS` | `agent/turn-stopping` | 触发自动推送的事件名，逗号分隔 |
+| `DSH_PUSH_DEBOUNCE_MS` | `15000` | 两条自动推送的最小间隔 |
+| `DSH_PUSH_SUMMARY` | 关 | 设 `1` 让通知带上本回合最后一条回复（截 120 字） |
+| `DSH_PUSH_TOOL` | 开 | 设 `0` 关掉模型可调用的 `push_notify` 工具 |
+
+上传大小上限（默认 20MB）在插件行的 `config.maxUploadBytes` 里改。
+
+---
+
+## 功能
+
+- 会话列表主屏 + 独立会话页两级页面栈，横向推入推出
+- 主屏插件入口 chips，按已装插件自动出现，显隐可自定义
+- composer 重排：控件图标化，权限/模型菜单变成底部 sheet
+- 会话信息卡：六格统计 + 导出日志 / 重命名 / Fork / 归档
+- 同一回合的推理与工具调用默认折叠成一条「过程 · N 步」
+- 手势：左边缘右滑返回、底部 sheet 下滑关闭
+- 手机本地附件上传：落到会话工作目录 `.dsh-uploads/`，输入框追加 `@` 引用，发不发你说了算
+- 配对码换长期设备令牌，认令牌不认 IP，可随时吊销
+- 管理面（生成配对码 / 管理设备 / 触发推送）只认本机直连，经反代一律 403
+- 真 PWA：manifest + service worker，可装到主屏、可离线打开
+- 真 Web Push：VAPID + aes128gcm，通知默认不带对话正文
+- `push_notify` 工具：模型可在关键节点自己推一条，带限流
+
+深度说明：[界面](docs/interface.md) · [公网接入](docs/remote-access.md)
+
+---
+
+## 已知问题
+
+**iOS 26.x 独立 PWA 视口缩水**：加到主屏后视口底部会少掉一条状态栏高度，普通 Safari 标签页正常。这是 iOS 系统缺陷，缺掉的区域在文档之外，CSS 够不着；本插件做了三层缓解（浅色 manifest 背景 + 安全区补偿 + 强制重排），能减轻但不保证复原。彻底恢复只能整个 App 退出重开。
+
+**经反代访问时设置页的插件配置列表空白**：直连 `127.0.0.1:3080` 正常。根因在 DSH 官方客户端的连接就绪超时判定，不在网关。绕法是要改插件配置时回本机浏览器改，配置存在后端，改完手机侧其它功能不受影响。
+
+---
+
+## 权限与数据
+
+- **网络**：网关只监听本机（默认 `127.0.0.1:3088`），对外暴露完全由你的反代/隧道决定；推送经浏览器推送服务商中转（内容 aes128gcm 端到端加密，服务商读不到）；插件自身不向任何第三方上报数据。
+- **文件**：附件上传只写入当前会话工作目录下的 `.dsh-uploads/`；配对状态与配置存在 `~/.dsh/lan-gate-state.json` / `lan-gate.config.json`。
+- **凭据**：不收集、不存储任何账号密码；设备身份是本插件自己签发的随机令牌（HttpOnly Cookie）。
+
+排障：运行日志在 `~/.dsh/logs/web.log`（网关与推送的行带 `[dsh-zen-remote-*]` 前缀）；手机端界面自检可用调试徽章（首页顶栏连点 5 下开关）。安全问题请走 GitHub Security Advisories 私下报告，不要公开提 issue。
+
+## 上游致谢
+
+本插件的界面层衍生自 [mexiaosqwq/dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile)，通道层衍生自 [zylzyqzz/dsh-mobile-pwa](https://github.com/zylzyqzz/dsh-mobile-pwa)（其自身衍生自 [Bernardxu123/dsh-mobile-gate](https://github.com/Bernardxu123/dsh-mobile-gate)），均为 MIT，原始版权行保留在 [LICENSE](LICENSE)。
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# dsh-zen-remote — bundle patch layer（一个包，三行 insert）
+#
+# 当 profile 的 dsh.profile.bundles 列了这个包时整层生效
+# （`dsh plugin --profile web add dsh-zen-remote` 会自动写进去）。
+# 三行都随包自带，用户不需要在自己的 profile patch 里手挂任何一行。
+- insert:
+    # 界面半边：浏览器端 app 外壳（经 package.json 的 dsh.client 发现）
+    # + host 侧唯一一条路由（手机附件上传端点）。
+    - id: dsh-zen-remote
+      name: dsh-zen-remote
+    # 通道半边：spawn 网关子进程（配对认证 / PWA 注入 / 反代到 DSH）。
+    - id: dsh-zen-remote-gateway
+      name: dsh-zen-remote/lan-gate.mjs
+    # 推送半边：agent 回合结束推送 + 模型工具 push_notify。
+    # 以前要用户自己在 profile 的 cordis.patch.yml 里手挂，现在随包自带。
+    - id: dsh-zen-remote-push
+      name: dsh-zen-remote/dsh-push.mjs

package/cordis.patch.yml.example

@@ -0,0 +1,16 @@
+# dsh-zen-remote — 静态挂载示例
+#
+# 不想走 `dsh plugin add` 的话，把下面这段抄进你 DSH profile 的
+# cordis.patch.yml，并把 <ABSOLUTE_PATH> 换成本仓库的 clone 目录。
+# 走 `dsh plugin add` 的正常安装不需要这个文件——包自带的
+# cordis.patch.yml 已经把三行都挂好了。
+- insert:
+    - id: dsh-zen-remote
+      name: dsh-zen-remote
+      path: file:///ABSOLUTE_PATH/dsh-zen-remote/lib/index.js
+    - id: dsh-zen-remote-gateway
+      name: dsh-zen-remote-gateway
+      path: file:///ABSOLUTE_PATH/dsh-zen-remote/lan-gate.mjs
+    - id: dsh-zen-remote-push
+      name: dsh-zen-remote-push
+      path: file:///ABSOLUTE_PATH/dsh-zen-remote/dsh-push.mjs

package/docs/interface.md

@@ -0,0 +1,200 @@
+# 手机界面（界面半边详解）
+
+> `dsh-zen-remote` 的界面半边完整文档：信息架构、断点策略、安全区体系、调试徽章、兼容插件。
+> 安装与快速上手见[根 README](../README.md)；通道侧细节见 [remote-access.md](remote-access.md)。
+> 界面基座衍生自 MIT 的 [mexiaosqwq/dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile)。
+
+## v2.0：从「窄屏适配」到「app 化外壳」
+
+v1.0.0（fork 自 [mexiaosqwq/dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile)）做的是「桌面布局压成窄屏」——保留桌面那套抽屉/侧栏，靠 CSS 把它们塞进手机宽度。v2.0 把手机端重写成「两级页面栈」的 app 信息架构：启动直接落会话列表主屏，点进去是独立的会话页，两页之间横向推入/推出，不再是「桌面页面的缩小版」。改造范围只到手机断点（<768px）；平板保持 v1.0.0 抽屉行为不倒退，桌面逐像素不变。
+
+这次重写建立在上游 v1.0.0 打下的底子上（分主题 CSS 结构、构建脚本、平板兼容段大量沿用），在此向 [mexiaosqwq](https://github.com/mexiaosqwq/dsh-web-mobile) 的原始工作表示感谢。
+
+## 效果
+
+| 会话列表主屏 | 会话页 | 会话信息卡 | composer 权限 sheet |
+| --- | --- | --- | --- |
+| ![会话列表主屏](../assets/home.png) | ![会话页](../assets/session.png) | ![会话信息卡](../assets/info.png) | ![composer 权限 sheet](../assets/sheet.png) |
+
+## 特性
+
+### 会话列表主屏
+
+启动永远落在这一屏（推送深链直达会话除外），不再是桌面抽屉的窄屏版本：
+
+- 会话按圆角卡片排列（左侧头像色块 + 标题/状态两行 + 右侧时间），运行中的会话带状态点；
+- 顶部就是当前 workspace 名，点开弹出切换单（含「全部」）；
+- 会话列表上方一条可横滑的插件入口 chips（文件浏览、用量、Session log 等，按你实际装的插件动态出现）：手写适配的几个之外，**任何在官方侧栏注册了快捷入口的插件都会被自动发现**，装上就长出对应 chip，卸载后自动消失，不用等插件适配更新；行尾「···」打开显隐自定义单，选择保存在本地，刷新后还在；
+- 右下「＋ 新建会话」文字胶囊，点按直接在当前 workspace 建会话；
+- 右上角设置图标是官方设置弹窗的入口（迁到这里，不再挤在抽屉里）。
+
+### 两级页面栈与转场
+
+会话列表（主屏）与会话页是两个独立层，横向推入/推出转场；进会话页点行，回列表点头部返回按钮或左缘右滑。官方侧栏在手机断点下直接隐藏，不再是「点开的抽屉」——因为已经没有抽屉需要点开了。
+
+### 会话页头部五件套
+
+会话页头部只留五样东西：返回 · 会话名（+ 运行状态点）· 当前视图名（对话/轨迹，带双点指示）· 信息卡入口 · better-sidebar 入口。官方的 Chat/Trajectory 页签视觉隐藏但 DOM 还在，点信息卡里的分段控件相当于代点它。
+
+### composer 重排
+
+输入区整个按 app 输入条的思路重排：
+
+- 底排控件全部图标化（附件 · 权限 · 模型 · 上下文环 · 发送），不再是挤在一起的文字按钮；
+- 权限、模型这两个官方弹出菜单被 CSS 整成从底部升起的 sheet 样式（结构还是官方的，只换了皮肤）；
+- 分支/Todo 这类 mini chips 挪到输入卡外上方；
+- composer 顶部不画分割线，改用渐变 mask——消息滚动到顶部/底部时自然淡入淡出，比一条硬边界更贴近原生 app。
+
+### 会话信息卡
+
+会话页头部的 ⓘ 打开一张底部信息卡，把原来占位置的统计栏收纳进来：轮数/步数/首字延迟/模型耗时/工具耗时/token 与缓存命中六格统计、Chat/Trajectory 切换、以及导出日志/重命名/Fork 会话/归档四个操作。
+
+### 回合过程折叠
+
+Chat 视图里，同一回合内的推理块、工具调用块默认折叠成一条「过程 · N 步」摘要行，点开才展开；最终回复文本永远直接可见。运行中的回合摘要行会跟着步数实时更新。仅手机断点生效。
+
+### 手势
+
+- 会话页左边缘往右滑 = 返回列表（有浮层或工作台开着的话先关掉它）；
+- 各类底部 sheet（信息卡、chips 自定义单、权限/模型菜单）支持下滑关闭。
+
+### 附件上传
+
+composer 最左的回形针打开的是**手机本地**的文件选择器（iOS 上会弹相册/拍照/选取文件三选一）——官方那套文件选择器是在跑 DSH 的电脑上弹窗，手机远程用不了。图片和文件一视同仁：都上传到会话工作目录的 `.dsh-uploads/`，composer 上方出现可删除的预览 chip（图片缩略图、文件图标+文件名），并把 `@.dsh-uploads/文件名` 追加到输入框——发不发、什么时候发，由你按官方发送键决定,不会替你自动发出。
+
+安全上的几句话：这个功能给插件的 host 半区新增了一条 HTTP 路由（`POST /_dsh/mobile-nav/upload`），只接受同源请求，文件名清洗后只取叶子名，写入路径校验不允许越出工作目录，单文件默认上限 20MB（可在 profile 里的插件行用 `maxUploadBytes` 调整）。远程访问时，这条路由和其它请求一样在 网关半边的配对墙之后。
+
+### 设置页与用量面板打通
+
+主屏右上角的设置图标就是官方设置弹窗的入口（近全宽 sheet 皮肤，沿用 v1.0.0 的适配）；如果你装了 dsh-usage-stats，它的用量/余额入口会作为一个 chip 出现在主屏 chips 行里，点开即用，不用先钻进设置。
+
+### 调试徽章
+
+手机主屏顶栏连续点 5 下（或访问 `?mobile-nav-debug=1`）唤出悬浮诊断条，显示 URL/视口/媒体查询/浮层状态/JS 错误，手机端问题取证用。桌面调试时可以用 `?mobile-nav-inset=54` 或 `?mobile-nav-inset=54,34` 伪造安全区（假刘海），在没有真实刘海屏的浏览器里也能复现顶部/底部安全区相关的布局。
+
+### 安全区体系与 iOS 26.x 视口缩水
+
+页面各表面的安全区留白统一收进两个可注入的 CSS 变量（`--mnav-sat`/`--mnav-sab`），平时读 `env(safe-area-inset-*)`，调试参数在时可以整体假冒——这是后面两层缓解的基础。
+
+在这套变量之上，iOS 26.x 的 Safari/PWA 上出现了一个已知系统缺陷：独立（加到主屏）PWA 第一次弹出软键盘后，布局视口会永久性地比屏幕矮一截（`innerHeight`/`visualViewport.height`/`100dvh` 一起变小），直到整个 app 被彻底退出重开。这不是本插件的 bug，社区已有记录（[参考文章](https://dev.to/cederhook/fixing-the-ios-standalone-pwa-keyboard-bug-that-shrinks-your-viewport-for-good-63d)），本插件只做了两层缓解，不是根治：
+
+1. **视口下沉检测**——检测到系统在底部裁掉一截可视区域时，把底部安全区补偿归零，避免在已经空白的系统条上再叠一层空白；
+2. **主动摘窗重排**——在输入框失焦、冷启动 1 秒/3 秒、切回前台后各触发一次「强制页面重排」，逼 WebKit 重新测量视口；能不能真正治好缩水，取决于具体机型和 iOS 版本，失败几次后会自动停手不再重试。
+
+苹果修好这个系统级问题之前，两层缓解只能减少影响面，不能保证每次都完全复原。
+
+## 断点策略
+
+| 宽度 | 行为 |
+| --- | --- |
+| < 768px（手机） | 本文档描述的 app 化布局全量生效 |
+| 768–1023px（平板） | 保持 v1.0.0 现状：抽屉 + 设置/预览浮层限宽居中，不倒退 |
+| ≥ 1024px（桌面） | 严格 no-op，逐像素与未安装时一致 |
+
+## 更新日志
+
+### v2.0.0
+
+**新增**
+
+- 两级页面栈 app 化重排：会话列表主屏 + 独立会话页，横向转场取代桌面抽屉；
+- 会话页头部五件套（返回/会话名/视图指示/信息卡/better-sidebar 入口）；
+- composer 重排：图标化底排控件、权限与模型菜单变身底部 sheet、顶部渐变 mask 取代硬分割线；
+- 会话信息卡：Chat/Trajectory 切换 + 六格统计 + 导出/重命名/Fork/归档四个操作，从占地方的底部统计栏搬进按需打开的 sheet；
+- 手势两件套：左缘右滑返回列表、各类底部 sheet 支持下滑关闭；
+- 回合过程默认折叠：多步回合收成一条「过程 · N 步」摘要行，最终回复始终可见；
+- 移动端附件上传：手机本地选择器 + 会话工作目录落盘 + composer 预览 chip + 草稿 @ 引用手动发送(见「附件上传」一节的安全说明)；
+- 主屏插件入口 chips：任务看板/SSH/文件浏览/用量等按已装插件动态出现，显隐可自定义并本地持久化；未手写适配的插件也能自动长出 chip——从官方侧栏的快捷入口区里现场收割图标/文案/点击目标；
+- 调试徽章：顶栏 5 连点或 `?mobile-nav-debug=1` 唤出，新增 `?mobile-nav-inset=` 伪造安全区参数，方便桌面复现刘海相关布局。
+
+**修复**
+
+- iOS 独立 PWA 键盘弹出后视口永久变矮的缓解（检测 + 主动重排，非根治，见上文说明）；
+- 整页橡皮筋回弹导致顶栏/composer/FAB 跟手指一起位移的问题（锁文档滚动 + 消息区单独滚动）；
+- PWA 冷启动首帧安全区未就位（首帧 `viewport-fit=cover` 改由 网关半边注入，不再等插件 JS 迟到补）；
+- 会话行三点菜单弹出时抽屉/列表状态错乱、workbench 关闭按钮在桌面端泄漏等一系列实机反馈热修。
+
+**内部**
+
+- 作用域与 网关半边 理清分工：本插件管排版与交互，网关半边 只管通道（认证/推送/PWA 壳），两边 CSS 不再重叠；
+- 新增 host 半区（`src/index.ts`）：从纯 client 插件变为带一条上传路由的插件；
+- 大量实机反馈驱动的迭代热修（S1–S8 各切片）。
+
+### v1.0.0
+
+**新增 / 改进**
+
+- 全屏预览浮层:预览底部浮层可一键放大到全视口(标题栏缩放按钮,刘海安全区适配),关闭预览或抽屉时自动还原;
+- 设置弹窗重构:分类标签收进单行横向滚动(细滚动条提示),顶部工具栏并入标签行共用一行,手机上隐藏「打开配置文件」按钮,选项区显著变大;
+- 分支胶囊:git 分支芯片移入输入卡片(todo 卡片之上),点击目标加大、按压即时反馈;
+- 会话头部紧凑与顺序稳定:模式徽标窄处省略、subagent 按钮居中、文件按钮固定保留;
+- 抽屉底部顺序:文件浏览 / 导出会话日志 固定在用量徽章之上;
+- 模型 ID 完整显示:composer 行内有空间时不再省略;
+- 文件树 / 预览交互:仅文件行可打开预览(目录行不再误弹缓存预览)、已选中行可重开、折叠按钮可靠关闭、预览打开时文件树自动让位;
+- 诊断徽章:`?mobile-nav-debug=1` 实时显示 URL/视口/媒体查询/浮层/JS 错误,默认 no-op。
+
+**修复**
+
+- 目录选择器被设置弹窗规则劫持(issue #12):点笔形「编辑」进入手动输入后弹窗被顶到屏幕顶部、路径输入框被隐藏——目录选择器不再命中移动端设置适配规则;
+- 预览浮层全屏几何规则回归(1779cd4)以及关闭后全屏标记残留;
+- 抽屉底部徽章平票错序;subagent 弹层小屏溢出;统计栏误标 todo 面板。
+
+**内部**
+
+- CSS 按主题拆为 `src/client/styles/`(base / layout / compat / misc),client effects 拆分为独立模块;构建器支持子目录递归内联。
+
+### v0.2.0
+
+**新增 / 改进**
+
+- 平板/宽幅移动端(768–1023px):设置弹窗与 Explorer/Preview 浮层限宽居中,避免右侧大块空白;
+- Markdown 表格在移动端撑满消息列宽,减少表格内/右侧留白;
+- 用户消息气泡自适应宽度:短消息紧凑靠右,长消息可撑满消息列宽;
+- 模型选择器:模型名可完整显示,切换菜单在触发按钮上方水平居中;
+- 底部权限/模型选择/上下文小圈间距优化(12/10/12)。
+
+**修复**
+
+- 预览浮层右上角缩放/收起按钮无法关闭的问题;
+- 用户消息气泡全宽后因 `content-box` 导致溢出屏幕的问题;
+- 模型切换菜单在小屏下偏左/溢出的问题。
+
+## 兼容插件
+
+- [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)(移动端全宽抽屉,本插件在会话页头部给它留入口位)——本机实测 **0.12.2**
+- [dsh-usage-stats](https://github.com/Ychris12138/dsh-usage-stats)(用量与余额,主屏 chips 行可直接打开)
+- [@opendsh/dsh-plugin-scheduled-tasks](https://github.com/Ceelog/dsh-plugins)(定时任务,主屏 chips 行自动收割入口)——本机实测 **0.2.0**
+- dsh-at-file(@文件引用)
+- [dsh-vision-toolkit](https://www.npmjs.com/package/@anionex/dsh-vision-toolkit)(图像 Q&A/OCR,配合手机端附件上传使用)
+- [dsh-web-ui 全家桶](https://www.npmjs.com/package/@linxin666/dsh-web-ui-all)(文件树 / 预览 / 任务看板 / SSH / 宠物 / 会话统计 / 远程配对 / 设置)——沿用上游兼容规则,本次未扩展
+
+## 安装
+
+```sh
+dsh plugin add dsh-zen-remote
+```
+
+装完重启 `dsh web`。手动写法与本地开发装法见[根 README](../README.md#安装)。
+
+## 构建
+
+```sh
+pnpm install
+pnpm build   # 产物 lib/ 与源码同步入库,改动源码后重新构建再提交
+```
+
+## 验证
+
+- `pnpm verify` 类型检查、`pnpm test` 全量测试;`dsh --profile web --dump-config` 应出现插件层;
+- 自检脚本:`node scripts/check-sunk-viewport.mjs`、`node scripts/check-attach-upload.mjs`、`node scripts/check-upload-endpoint.mjs`(需 Node ≥ 23.6);
+- 移动端(390px):启动落会话列表、进出会话页转场、composer 权限/模型 sheet、信息卡统计与四个操作、附件上传;
+- 平板(768px):抽屉 + 限宽居中,与 v1.0.0 一致;
+- 桌面端(≥1024px):与未安装时一致。
+
+## 兼容性
+
+需要 `:has()`(Chromium 105+);`prefers-reduced-motion: reduce` 下自动禁用动画。
+
+## License
+
+[MIT](../LICENSE)