@az7627/dsh-mobile-remote

Readme

# @az7627/dsh-mobile-remote

DeepSeek Harness Web GUI 的手机响应式适配与 WireGuard 远程增强插件（双面包，不改 Harness 源码、不改 npx 安装内容）。npm 包名带作用域（无作用域的 `dsh-mobile-remote` 已被他人占用）。

## 功能

- **手机布局（≤760px 视口）**：三栏外壳单栏化；侧边栏变为左滑抽屉（含遮罩与左上角菜单按钮）；details 面板变为全屏覆盖层；拖拽把手隐藏；iOS safe-area、输入框 16px 防缩放、触控目标 ≥36px。
- **弹窗手机化**：真正的模态对话框（primitives Modal 与设置面板）在手机上全屏化，内容区独立滚动；普通弹层面板（菜单、上下文面板等）保留自己的盒子与背景，不受影响。
- **弹层防越界**：菜单、列表、带背景阴影的面板等浮层若出屏，自动平移到屏幕内（先钳宽度、再横向平移）；触发器位置变化（如工具栏换行）时跟随重算；抽屉、详情面板等自带 transform 动画的表面不受干扰。已实测 320–430px 六档宽度下模型选择菜单始终完整在屏。
- **预设标签精简**：窄屏下 Agent 预设按钮只显示图标 + `标准` / `极简` / `PTC` / `创造`（英文同理），去掉"模式"二字；桌面端保持全称。
- **桌面零改动**：所有规则收窄在媒体查询内，桌面布局与列宽不受影响。
- **目录选择页重建**：本插件把 Harness 的目录选择交互钉为 Web 目录页，并以自研界面取代内置 browse 对话框（宿主 browse 后端保留）。桌面端：大对话框 + 左侧快捷目录（主文件夹/下载/桌面/文档/图片/音乐/视频 + 底部"此电脑"/根目录）、**分栏（Miller columns）浏览**、四键工具栏（后退/前进/上一级/刷新）、面包屑路径栏（每级可点击，点击空白处可输入路径跳转）；手机端：**快捷目录落地页 → 单列列表 + 返回键**，全屏呈现。任何绑定方式下"添加工作区"都可用，且不再弹系统对话框。
- **文件管理**：侧边栏"设置"上方新增"文件管理"入口——与选择器同一分栏视图；每打开一个目录追加一栏、放不下时底部横向滚动条自动定位到最新栏、**每栏独立滚动条且展开新栏时原栏滚动位置保持**；**右键菜单**（重命名、复制、粘贴、删除、下载、选择打开方式、复制文件地址、属性、新建、上传、刷新、在终端中打开），粘贴自动加 `-copy-2` 后缀防重名；按扩展名打开（文本预览/编辑保存、图片/视频/音频内联预览、PDF 新标签页、未知类型自定义打开方式），十六进制编辑（64KB 分窗、8MB 上限）、上传（8MB）、下载、删除（非空文件夹二次确认）；**文件夹属性显示递归统计的真实大小**；**隐藏文件以半透明显示**；手机端保留行内触控按钮。
- **真 PTY 交互终端**：侧边栏"终端"按钮（位于文件管理上方）打开浏览器内终端——宿主 **node-pty**（Windows 走 ConPTY）会话 + 客户端 **xterm.js** 渲染：行编辑、ANSI 颜色、全屏 TUI 应用（more/vim/top 等）都能用；终端跟随视口 fit 并同步 PTY 尺寸；输出为有界环形缓冲（256KB），轮询 60ms；**空闲回收**：客户端停止轮询（页面关闭而未走关闭 RPC）10 分钟后自动杀掉会话，避免 PowerShell 进程泄漏。文件管理右键"在终端中打开"可在任意目录启动终端；Windows 默认 PowerShell（`-NoProfile`），其他平台 bash。
- **手机设置页可用（回环补丁）**：rc.6 对非 loopback 浏览器把设置作用域钉为 `persistence:"memory"`——手机上的设置标签页（插件配置/通用/模型/欢迎）不发任何请求、整页空白。本插件在可信远程会话中把连接句柄的 `isLoopback` 置真，并对已消费旧值的设置消费者条目（settings-plugins / settings-general / settings-models / deliverables）做一次 fiber 重应用，让它们重新绑定到主机持久化传输（经下文的特权转发通道）。桌面（loopback）完全不受影响。
- **远程增强**：断线重连状态条；通用设置里的"远程访问状态"行（绑定地址 / 信任来源 / 目录选择后端 / 插件版本，手机可自查）；PWA 增强（standalone manifest + PNG 图标 + apple-touch-icon）。
- **非安全上下文修复**：手机经 `http://隧道IP`（非安全源）访问时浏览器不提供 `crypto.randomUUID`，导致所有 RPC（设置、目录列表、模型/插件/预设）报 `crypto.randomUUID is not a function`。插件启动时安装 UUIDv4 回退（基于 `crypto.getRandomValues`，任何源可用），手机上接口恢复正常。
- **特权 API 解除 loopback 钉死**：rc.6 把设置/凭据/Agent 预设/模型发现等方法钉为仅本机可用（手机上 403 forbidden）。插件把同源特权调用转发到自己的 trusted-host 通道，宿主侧再以**回环请求**交给内置 apiProxy 分发（信任边界仍是 profile 里的 trustedHosts，即 WireGuard 隧道地址）。

## 安装

### 从 npm 安装（推荐）

```powershell
dsh plugin --profile web add @az7627/dsh-mobile-remote
```

重启 `npx @deepseek-ai/dsh web` 生效。

- 更新：重新执行上面的 add（pnpm 会装最新版）
- 卸载：`dsh plugin --profile web remove @az7627/dsh-mobile-remote`

### 本地开发（link 安装）

```powershell
dsh plugin --profile web add C:\path\to\dsh-mobile-remote
```

改完源码 `pnpm run build` 后重启 `npx @deepseek-ai/dsh web` 即生效，无需重新 add。

## 手机（WireGuard）远程访问

> **重要（rc.6 实测）**：rc.6 的 webserver 只接受 `127.0.0.1` / `0.0.0.0` 绑定，且 CLI 有意拒绝 `0.0.0.0`——**无法直接把服务绑到 10.66.66.1**。远程访问采用：本机绑定 + WireGuard 地址端口转发，目录选择由本插件钉为 Web 目录页（上面已说明）。

1. profile（`~/.dsh/profiles/web/cordis.patch.yml`）的 `web-runtime` 配置需包含隧道地址的 `trustedHosts`（例如 `10.66.66.1` 与 `10.66.66.1:3080`），手机请求才能通过 /api 信任栅栏。
2. 安装端口转发（一次，需管理员）：
   ```powershell
   netsh interface portproxy add v4tov4 listenaddress=10.66.66.1 listenport=3080 connectaddress=127.0.0.1 connectport=3080
   ```
3. 启动（本机绑定）并访问手机地址 `http://10.66.66.1:3080`。

推荐的无人值守启动方式（`scripts/start-dsh-web.ps1`）：

```powershell
pwsh -File scripts\start-dsh-web.ps1 -InstallPortProxy   # 一次：安装端口转发（管理员）
pwsh -File scripts\start-dsh-web.ps1                     # 启动（检测接口/端口占用/转发状态）
pwsh -File scripts\start-dsh-web.ps1 -RegisterStartup    # 可选：注册登录自启计划任务
```

## 目标版本

按 DeepSeek Harness **0.1.0-rc.6** 的 Web 外壳 DOM 契约实现（三栏 inline grid、`data-sidebar-collapsed`/`data-details-collapsed` 状态属性、`ctx.layout` 面板契约、`shell.overlay`/`settings.general.item` 槽位）。核心升级后需重新验证并随版本跟进。

## 开发

```powershell
pnpm install
pnpm run typecheck
pnpm test
pnpm run build
# 一次性测试实例（必须！与真实 ~/.dsh 完全隔离，避免污染真实会话日志）：
pwsh -File scripts\start-test-dsh.ps1            # 启动 http://127.0.0.1:3097
pwsh -File scripts\start-test-dsh.ps1 -Remove    # 清空隔离测试目录
# 实测（针对上面的隔离实例）：
node scripts/verify-mobile.mjs
node scripts/verify-file-manager.mjs http://127.0.0.1:3097
node scripts/verify-terminal.mjs http://127.0.0.1:3097
node scripts/verify-settings-loopback.mjs http://127.0.0.1:3097   # 手机权威仿真（10.66.66.1 映射回环）
node scripts/verify-usage-remote.mjs http://127.0.0.1:3097        # token-usage /usage 信任栅栏
```

> ⚠️ 不要用共享 `~/.dsh` 的实例跑验证脚本：验证浏览器打开会话会触发加载修复，向真实会话日志写入 closers，与运行中实例的写入冲突会造成日志 seq gap。

## License

MIT