@anonyjcy/dsh-plugin-mobile-touch

Readme

# 📱 dsh-plugin-mobile-touch

[![DSH Market 收录徽章](https://raw.githubusercontent.com/2BingLing/dsh-market/master/assets/readme/badge-listed-zh.svg)](https://dsh.market/?q=AnonyJcy%2Fdsh-plugin-mobile-touch)
[![npm version](https://img.shields.io/npm/v/@anonyjcy/dsh-plugin-mobile-touch.svg?color=blue)](https://www.npmjs.com/package/@anonyjcy/dsh-plugin-mobile-touch)
[![GitHub release](https://img.shields.io/github/v/release/AnonyJcy/dsh-plugin-mobile-touch?color=blue)](https://github.com/AnonyJcy/dsh-plugin-mobile-touch/releases)
[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**简体中文** | [English Version](README.en.md)

> **DeepSeek Harness (DSH)** 移动端与 iPad 触控交互深度优化插件。  
> 针对 iPadOS / Safari WebKit 渲染引擎与触控手势管线深度定制，彻底解决手势拦截卡死、会话切换输入法弹起误触、全页弹性颠簸与侧边栏折叠抖动等全链路痛点。

---

## 🌟 核心问题深度剖析与解决方案（踩坑实录与内核原理解析）

在 iPad (Safari/WebKit) 上使用现代 Web 应用（如 DeepSeek Harness Web GUI）时，经常会遇到一系列严重影响体验的底层内核与手势冲突。本项目在研发过程中深入攻克了以下关键机制：

### 1. HTML5 拖拽属性（`draggable="true"`）导致的触控滑动卡死
* **问题表象**：在左侧工作区列表中滑动时，10 次里有 8~9 次完全滑不动、像被锁死一样，只有极快猛甩才能偶尔滑一下。
* **深层根因**：DSH 为了支持 PC 端鼠标拖拽排序，在每个会话行上声明了 `draggable={true}`。在 iPadOS 15+ 上，WebKit 支持了多任务拖放手势；当手指触碰带有 `draggable` 的 DOM 节点时，WebKit 会启动约 50ms 的长按拖拽识别等待。只要手指稍有自然停顿，WebKit 的 `DragGestureRecognizer` 就会抢占手势并强制派发取消信号，**直接掐死纵向滚动**！
* **解决对策**：在 `touchstart` / `pointerdown` 捕获阶段第 0 毫秒即时剥离触碰链条上的 `draggable` 属性，配合 `MutationObserver` 和原型链封杀，确保 WebKit 100% 毫无延迟地分发为纵向顺滑滚动。

### 2. 会话切换时自带虚拟软键盘频繁弹起占半屏
* **问题表象**：在 iPad 上点击切换查看不同历史会话时，系统巨大的软键盘自动弹起遮挡半屏并引起视口剧烈抖动。
* **深层根因**：DSH 核心的 `InputBar.tsx` 在 `sessionId` 切换时，React `useEffect` 默认会自动调用 `textarea.focus()`。桌面端用于快速输入，但在移动端触屏上会直接强行拉起系统软键盘。
* **解决对策（Keyboard Focus Guard）**：在原型链层面拦截 `HTMLTextAreaElement.prototype.focus`。仅当检测到用户手指在过去 350ms 内**真实直接点击了输入框本身**时才放行聚焦；所有会话切换、页面加载引起的自动聚焦全部在底层被静默压制，**浏览历史对话绝不再误弹键盘**。

### 3. iPad 1024px 临界值抖动导致侧边栏自动缩窄
* **问题表象**：点击会话或者滑动后，左侧工作区突然自动折叠成只有图标的 56px 小窄条。
* **深层根因**：DSH 内置 `SIDEBAR_AUTO_COLLAPSE = 1024` 阈值判定。iPad 屏幕分辨率恰好落在 1024px 临界线上；会话切换引起的重绘或微小尺寸波动（1023.5px 与 1024px 间横跳）会导致 DSH 误判进入手机窄屏模式并重置折叠状态。
* **解决对策（Sidebar Persistence）**：智能识别平板屏幕（$\ge 768\text{px}$）并常驻锁定侧边栏展开状态，仅当用户主动点击左上角折叠按钮时才进行收起，切换会话永不缩水。

### 4. 局部滑动带跑整个页面（Overscroll Chaining & PreventDefault）
* **问题表象**：手指在工作区滑动时，整张网页跟着上下晃动甚至触发浏览器下拉刷新。
* **深层根因**：在 WebKit 触控管线中，当内部容器滑动如果未在拖拽时消费事件，WebKit 会将手势冒泡升级为整个 Window 窗口的弹性橡皮筋下拉（Rubberband Bounce）。
* **解决对策**：在独占式树状触控引擎中，拖拽滑动时精准执行 `e.preventDefault()` 并对 `scrollTop` 实施严格物理边界收敛，切断全页回弹链条，页面稳如磐石。

---

## ✨ 核心特性一览

- 🎯 **智能硬件感知**：自动识别 `pointer: coarse`、多点触控与移动端环境，**仅在触控屏上激活**；桌面鼠标环境零开销、零干扰。
- ⚡ **独占式树状列表触控引擎（Dedicated Tree Scroller）**：100% 毫秒级即时滑动响应，配合物理阻尼算法实现丝滑 ProMotion 惯性滑行。
- 🛡️ **软键盘智能防误弹守卫（Focus Guard）**：彻底解决切换对话时虚拟输入法跳出占屏的痛点。
- 📌 **iPad 平板大屏侧边栏常驻守护**：杜绝 1024px 临界值抖动引起的侧边栏自动缩窄。
- 📏 **精准原生滚动条渲染**：彻底消除破碎变形与遮罩遮挡，等比例精准反映滚动进度。
- 🔌 **全域自动自适应（Future-Proof）**：后续安装或开发的任何新 UI 插件无需单独写适配代码，自动享有触控优化。

---

## 🚀 安装与部署

### 方式一：通过 npm / pnpm 安装（官方 npm 源）

```bash
# npm 安装
npm install -D @anonyjcy/dsh-plugin-mobile-touch

# pnpm 安装
pnpm add -D @anonyjcy/dsh-plugin-mobile-touch

# 运行 CLI 一键挂载到 DSH Web Profile
npx @anonyjcy/dsh-plugin-mobile-touch install
```

### 方式二：克隆仓库直接安装（本地使用）

```bash
git clone https://github.com/AnonyJcy/dsh-plugin-mobile-touch.git
cd dsh-plugin-mobile-touch

# 一键挂载到 DSH Web Profile (~/.dsh/profiles/web)
node bin/cli.js install

# 检查安装状态与健康度
node bin/cli.js status
```

---

## 🛠️ CLI 命令一览

```bash
node bin/cli.js install [profile]    # 挂载触控优化插件到 DSH profile（默认: web）
node bin/cli.js uninstall [profile]  # 从 DSH profile 干净卸载插件
node bin/cli.js verify [profile]     # 校验安装与软链接完整性
node bin/cli.js status [profile]     # 查看当前安装状态与配置路径
```

---

## 📄 开源许可证

本项目基于 [MIT License](./LICENSE) 开源。