掌上遥控器 Gaudi-XIX/dsh-pocket-glide

Pocket DSH Glide（dsh-pocket-glide）

“Curiouser and curiouser!”

DeepSeek Harness 的轻量手机伴侣插件：手机是遥控器，不是掌上 IDE。

设计哲学：手机只做四件事

桌面端负责生产（算力、仓库、工具链、配置），手机端只保留最小通道：把人的决策递进去，把结论拿出来。落到代码上就是四条判据，每个功能都要先过这四关：

1. 只有手机必须亲自做、且 AI 必须在线才能完成的，才做。 桌面 GUI 已经能做好、也不需要人当场拍板的事，不进手机。
2. 手机端不承载桌面配置面。 环境变量、配置档编排、插件安装、工作区、文件树一律留在电脑上。
3. 不为手机引入构建链。 页面是宿主进程直接吐出的 HTML 字符串，没有 React/Vue、没有打包步骤，运行时只依赖一个 pngjs（画二维码）。
4. 触屏交互按手感重写，不靠缩放宽屏布局。 上滑就停、进会话即开即现、键盘不顶碎视口、过程卡原地沉淀。

判据的反面就是这份 README 的第三、四节：我们砍掉了什么，以及什么情况下你不该选我们。

为什么做 Pocket：设计取舍

DSH 在电脑端跑重构、改代码、跑单测时，一个回合往往十几分钟。人离开工位后真实的需求只有两条：

1. 随时下指令：在手机上新建或切换会话，把新的提示词丢给电脑端继续执行；
2. 处理交互门禁：智能体要工具权限、或 ask_user_question 在等人拍板时，手机上点一下放行，别让长任务干等。

把桌面端的模型配置、深层设置、完整文件目录都搬到手机，在窄屏触屏上操作繁琐且容易误触——多出来的能力反而会拖慢上面那两件事。Pocket 的选择是做减法：电脑负责生产，手机负责决策。

和其他 DSH 手机插件比，我们砍掉了什么

左列只写各插件自己在市场条目里写明的事，不评价好坏——它们解决的是不同问题。

| 维度 | 市场上的常见做法 | Pocket 的选择 | 你要付的代价 |
| 手机端看到什么 | 把 DSH 的 Web 界面搬到手机：shaobeichen/dsh-pocket 实时同屏并带设置页；JauLukNgai/dsh-on-phone 直接把网页界面开给手机浏览器；Odefined/dsh-mobile-webui 专门修 Web GUI 的手机视口 | 另一套页面：宿主进程内直出、只对应会话面的纯 HTML/CSS/JS，不是宽屏布局的缩放 | 手机上看不到桌面 UI 的全貌 |
| 暴露面 | 桌面 UI 有什么，手机上基本都能看到 | 白名单，只开四种操作：会话列表、会话内容、发消息、权限审批。环境变量、配置档、插件、文件树一律不上手机 | 手机上改不了配置、看不了文件 |
| 客户端 | 纯 Web（多数）；或配套原生客户端（Clarklevis1995/dsh-plugin-mobile-gateway 的 iOS 客户端、NOirBRight/dsh-mobile-pairing 的 Android 客户端） | 只有 Web：扫码即开，不装 App、不注册账号 | 没有系统级原生推送，通知靠浏览器 + 外带推送通道 |
| 公网通道 | Tailscale（JauLukNgai/dsh-on-phone、IceApriler/dsh-remote-mobile）、自带 quick tunnel、或第三方 relay | 局域网直连 + 自带 cloudflared quick tunnel（出站，两端都不用装东西） | 公网地址随机，重启后会变 |
| 地址变了怎么办 | 手工复制新地址；也有插件做到推送到微信（Hongjun1-RGB/dsh-phone-access 会把每次新隧道地址推给你） | 新地址自动推回手机（Server酱 / WxPusher / Bark），并可一键触发宿主重启 | 要配一个推送凭据 |
| 前端形态 | 镜像桌面 UI 的页面或手机视口补丁 | 无框架、无构建步骤，单运行时依赖，壳约 390 KB | 复杂界面做不了，也不需要 |

第三条判据（无构建链）在市场上并不常见，这是本项目给自己定的工程约束：页面由宿主直接产出，改一行 CSS 就生效，不需要 pnpm build。

功能与能力清单

1. 差异化实现

这一节里有的能力是我们自己踩坑做出来的，有的在别的插件里也有（表里已注明）。真正的差异是整体取舍，不是某一条功能清单。

* 白名单透传：手机端不暴露 DSH 系统级配置，主页只展示置顶会话与最近 24 小时活跃会话；
* 原生轻量直出：不引入前端框架，纯手写 HTML + CSS + JS 由宿主直出（壳约 390 KB），内存占用数兆，微信内置浏览器这类受限 WebView 里也能秒开；
* 临时隧道自愈：无公网 IP 时，手机端可一键触发宿主优雅重启；重启后随机分配的新公网地址会自动推送到手机通知（微信 Server酱 / WxPusher / Bark），点通知直接连回新宿主（推送新地址这件事 Hongjun1-RGB/dsh-phone-access 也做，我们只是把它串成闭环的一步）；
* 微信入站身份门控：微信通道绑定之后，只有绑定的那个人发来的消息才算数；其他人发来的入站整条丢弃——不续推送额度、不改绑定、不回执、不拉起隧道（v0.4.54 起，见 CHANGELOG.md）；
* 针对触屏动力学的细节：
* 会话尾包预取：列表后台预热会话末尾消息，点进会话无白屏等待；
* 流式上滑不强行拽底：用户一上滑就解除贴底，绝不抢视口；轻点向下箭头平滑回底；
* 软键盘动态避让：键盘弹起时输入框精准上浮，不遮挡、不顶碎布局；
* 单折叠卡直播：思考链与工具调用收拢在一张折叠卡内原地更新，不跳屏。

2. 基础功能（同类普遍具备，我们也完整支持）

* 连接与网络：
* 同一 Wi-Fi 下局域网扫码直连（0.0.0.0:43127，端口冲突自动顺延到 43128）；
* 基于 Cloudflare Quick Tunnel 的公网加密穿透（出站连接，无需路由器端口映射）；
* 会话与交互：
* 多会话管理：新建、切换、重命名、删除；
* 消息发送与附件：长文本、图片与通用文件上传；
* 流式输出与渲染：实时流式、思考过程折叠、Markdown 与代码块高亮；
* 门禁审批：敏感操作一键放行/拒绝、ask_user_question 选项应答；
* 任务状态感知：子代理并发任务运行态与状态标记；
* 外观与形态：
* 深色模式：跟随系统或手动切换，禁用态等细节一并覆盖；
* PWA：在 Safari / Chrome 里「添加到主屏幕」后按全屏应用运行。

3. 明确不做（故意砍掉的非目标）

* 不做全量桌面配置与插件管理——环境变量、配置档编排、插件安装属于桌面端的重型管理职责，窄屏上容易误触，还加重认知负担；
* 不做文件树浏览与在机编辑器——手机只负责提需求和放行权限，代码改动交给本地智能体，diff 审查留在大屏；
* 不自建云端服务器与账号系统——纯本地运行、点对点出站穿透，提示词与代码不经第三方云端中转；
* 不打包原生 App（APK / IPA）——省掉安装与发版审核成本，保持链接点开即用。

4. 什么情况下不要选我们

* 你想在手机上做桌面端的全套配置与文件管理 → 用镜像桌面 UI 的插件；
* 你要在手机上改代码、看 diff、跑命令 → 手机不合适，回电脑；
* 你要求两端都走 Tailscale、不要随机公网地址 → JauLukNgai/dsh-on-phone 这类方案更顺；
* 你必须有原生客户端推送与设备令牌体系 → NOirBRight/dsh-mobile-pairing 或 Clarklevis1995/dsh-plugin-mobile-gateway 那类原生路线更合适。

快速使用

1. 安装与启用

dsh plugin --profile desktop add github:Gaudi-XIX/dsh-pocket-glide

也可以把本仓克隆到本地后用 link: 方式注册（tools/install-to-profile.mjs 会先做预检再写配置档）。装完重启 DeepSeek Harness 才会装载。

2. 扫码配对

1. 点 DSH 桌面端侧边栏的 Pocket 图标打开配对面板；
2. 手机相机或微信扫码即可访问（支持「添加到主屏幕」全屏使用，也支持在微信内直接打开）。

3. 配置外带通知（可选）

在桌面配对面板里填推送凭据（微信 Server酱 / WxPusher / Bark）：

* 任务完成或等待输入时收到手机提醒；
* 触发远程重启后，新生成的公网地址自动推送到手机。

运行环境

* 宿主依赖：DeepSeek Harness v0.2.0-rc.1 及以上，Node.js ^22.19.0 || >=24.0.0；
* 架构形态：宿主进程内加载（Cordis 插件），不是独立进程，随 DSH 启动而起、随退出而止，没有后台守护进程；
* 改动生效：改 lib/ 或新增 bundle 必须重启 DeepSeek Harness；手机端还要完全关闭重开页面才拿得到新壳，下拉刷新拿到的仍是旧壳；架构细则：形态、桥的宿主内生命周期、目录与关键常量见仓库内 docs/SPEC-ARCHITECTURE.md（只在开发树里，公开副本不带 docs/，需要时可向维护者索取）；网络端口：默认监听 0.0.0.0:43127（占用自动顺延到 43128，可用 DSH_MOBILE_PORT 指定）；
* 外网访问：内置出站型 Cloudflare Quick Tunnel，无需公网 IP 与端口映射。

版本与变更账：逐版的对外变化（修复 / 契约变更 / 已知边界）见 CHANGELOG.md，其最新一节对应当前 package.json 的 version；更细的逐笔施工账在 git log 里。本仓从 0.2.0 起维护这份变更账。

"In case I don't see you, good afternoon, good evening, and good night."

开源协议

本项目采用 MIT 协议开源。