📱 dsh-plugin-mobile-touch
DSH Market 收录徽章
简体中文 | English Version
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 源）
# 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
方式二：克隆仓库直接安装（本地使用）
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 命令一览
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 开源。
