# dsh-pocket

> 给 DSH 加一个扫码同屏入口，手机扫二维码就能实时看到并操作电脑上的 DeepSeek Harness，局域网直连、公网走 cloudflared 隧道。

## Metadata

- Author: [@shaobeichen](https://github.com/shaobeichen)
- Repo: <https://github.com/shaobeichen/dsh-pocket.git>
- GitHub: [shaobeichen/dsh-pocket](https://github.com/shaobeichen/dsh-pocket)
- Stars: 273
- Language: JavaScript
- License: [GPL-2.0](https://spdx.org/licenses/GPL-2.0.html)
- Topics: `deepseek`, `deepseek-harness`, `deepseek-harness-plugin`, `dsh`, `dsh-plugin`, `dsh-plugin-market`, `dsh-plugins`, `mobile`, `qr`, `remote`, `tunnel`
- Forks: 22
- Open Issues: 7
- Last push: 2026-08-20T13:40:16.000Z
- Added: 2026-08-16T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:shaobeichen/dsh-pocket
```

## Wiki

## 一句话定位
给电脑上的 DeepSeek Harness 加一个手机入口：手机扫码就能在浏览器里看到与电脑实时同步的同一个界面，可看输出、可发任务、可点审批。

## 核心能力
- 局域网扫码直连：插件启动后自动起代理，扫描设置页中的二维码即可在同一 WiFi 下访问电脑上的 DSH
- 公网扫码穿透（人在外面也能用）：一键建立 cloudflared 隧道，生成随机公网 URL，4G 或任何网络都能连回电脑
- 双密码隔离保护：公网与局域网各有独立 8 位数字密码，公网密码每次开启自动换新、旧链接立即作废
- WebSocket 实时同屏：流式输出与事件通道透传，电脑端在输出内容时手机端同步滚动，可双向操作
- 移动端 UI 适配：窄屏自动改为抽屉布局，含状态栏安全区与会话全宽优化
- 流量压缩：大 JSON 响应自动以 gzip/brotli 流式压缩，长会话可从 17MB 压到 1MB 左右，手机加载更快
- 隧道自恢复：DSH 重启后 cloudflared 子进程会被回收，插件会在下次启动时按持久化标记自动重新拉起之前的公网隧道
- 一键更新/自重启：设置页可检测新版本并自动重启宿主进程（detached 交接，不撞端口）

## 技术实现
- **语言**: JavaScript（ESM + 部分 CJS） / 含少量内联 HTML 注入脚本
- **关键依赖**: `@deepseek-ai/cordis`（宿主框架，`peerDependencies`）、`qrcode`（生成二维码 data URL）、`cloudflared`（运行时下载的二进制，公网隧道依赖）
- **架构模式**: 单包单插件，注入 DSH Host 后由 `lib/index.js#apply` 启动一个 0.0.0.0 反向代理（默认 3081）把入站请求的 Host/Origin 改写为 loopback 转发到本机 DSH；同时通过 `ctx.connection.rpc.handle` 在 `/dsh-pocket` loopback 通道注册设置页 RPC
- **入口文件**: `lib/index.js`（Cordis apply）、`bin/dsh-pocket.mjs`（独立 CLI）、`client/index.jsx`（设置页签 React 入口）

## 适用场景
下班路上、出差途中或家里客厅到书房的场景：人不在电脑前但想看电脑上的 agent 跑到哪一步、想给电脑上的 agent 发新任务或审批某项操作。另一个用途是把电脑锁屏、让手机当唯一操控终端，省得远程桌面或 SSH 那一套配置。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | >= 22 | `package.json#engines` 声明 |
| DeepSeek Harness（DSH） | 需与 `@deepseek-ai/cordis ^4.0.1` 配套的版本 | 仓库未在 `package.json` 中显式声明具体 DSH 版本号 |
| 平台 | macOS / Windows / Linux | 跨平台；Windows 首次开启公网时下载 cloudflared 较慢（单线程），可手动安装或挂代理 |
| 原生模块 | 无 | 全部依赖为纯 JS，公网隧道依赖的 cloudflared 是二进制，首次开启时按需下载到 `$DSH_HOME/dsh-pocket/bin/` |

## 安装方式
```bash
dsh plugin --profile web add github:shaobeichen/dsh-pocket
```

## 配置项
本插件无需额外配置。插件启动后所有可调项（局域网密码开关、密码刷新、公网隧道开关、一键更新/重启）都在 DSH 设置页的「手机访问」页签中通过 UI 完成。内部会写入的文件：

- `$DSH_HOME/dsh-pocket/settings.json`：局域网访问密码开关（默认开启，UI 可关）
- `$DSH_HOME/dsh-pocket/token`：公网访问密码（每次开启公网自动重写）
- `$DSH_HOME/dsh-pocket/token-lan`：局域网访问密码（设置页手动刷新）
- `$DSH_HOME/dsh-pocket/tunnel-auto.json`：公网隧道「开启中」标记，供 DSH 重启后自动恢复
- `$DSH_HOME/dsh-pocket/cloudflared(.exe)`：首次开启公网时下载的 cloudflared 二进制缓存

## 常见问题

**Q: 装好后从哪儿打开？**

A: 重启 dsh web 后进入 DSH 的「设置」页面，左侧边栏会多出一项「手机访问」入口（与「通用设置」「模型」同级）。局域网二维码会立刻出现，无需任何配置。

**Q: 局域网和公网模式有什么区别？**

A: 局域网要求手机与电脑在同一 WiFi，访问走内网，延迟低、不耗流量；公网模式通过 cloudflared 隧道拿到一个随机 trycloudflare.com 子域，4G 或任意网络都能用，但 URL 与访问密码每次开启都会换。

**Q: 访问密码是必须的吗？**

A: 公网链接始终要 8 位数字密码（每次开启自动换新、旧链接立即作废）。局域网密码默认开启，可在设置页局域网区块一键关闭——关闭后同网段设备扫码即可直连（公网不受影响）。

**Q: 装完/更新完为什么没生效？**

A: 必须重启 dsh web 进程，正在运行的进程仍加载旧插件代码。设置页有「一键重启」按钮（桌面版环境除外），或在终端重启 dsh web 后再访问。

**Q: 公网模式报 error 1033 怎么办？**

A: 通常是本机代理/VPN（Clash、Surge、v2ray、sing-box 等 TUN/增强模式）掐断了 cloudflared 隧道。先只关代理的 TUN 模式，不行就彻底退出代理软件；仍然不行就给代理加直连规则放行 argotunnel.com / trycloudflare.com；网络实在不通时改用「手机热点 + 局域网模式」效果完全一致。

**Q: 端口 3081 被占用怎么处理？**

A: 旧 dsh-pocket 进程还占着端口时，插件会自动尝试下一个端口（最多连续 10 个）。仍冲突时需手动结束旧进程：macOS/Linux 用 `lsof -ti :3081 | xargs kill -9`，Windows 用 `netstat -ano | findstr :3081` 找 LISTENING 的 PID 后 `taskkill /PID <PID> /F`。

**Q: 在 DSH Desktop 上能用吗？**

A: 扫码同屏在桌面版正常工作，但一键更新和一键重启由 DSH Desktop 自己管理，本插件在这两项上主动禁用避免冲突。桌面端「advanced」模式暂不支持手机访问（页面会被覆盖一层提示），需在桌面端设置切回「compatibility」模式后重启。

**Q: 升级到 1.x 版本怎么操作？**

A: 使用 `dsh plugin --profile web update dsh-pocket --latest -w`（带 `--latest` 才能跨 `^0.x` 范围升到 1.x），更新完成后记得重启 dsh web 让新代码生效。

## 上手难度
入门 — 装好重启 DSH 后，扫码即用；遇到代理/端口等异常时按 README 排障表逐项检查即可，没有需要理解的概念或配置项。

## 已知问题与限制
- DSH Desktop「advanced」模式暂不支持手机访问（桌面版 advanced 组合禁用了网页版 ui-layout，手机页拿到的是 compatibility patch 但无桌面 layout 服务），设置页会自动叠加一层提示引导用户切回 compatibility 模式
- 公网隧道依赖本机出站到 Cloudflare 边缘节点（`*.argotunnel.com`、`*.trycloudflare.com` 与 Cloudflare 边缘 IP），代理/VPN 的 TUN/增强模式常会掐断隧道连接（表现为 error 1033）
- Linux 上若缓存目录里残留了 Homebrew bottle 格式的 cloudflared（ELF 解释器为 `@@HOMEBREW_PREFIX@@` 占位符），启动时会直接报 ENOENT；插件会读 ELF 文件头检测并丢弃坏缓存、自动重新下载
- Web 推送通知（Web Push）已被移除：依赖 Google FCM 等境外服务，国内直连被墙，普通用户用不上
- 安装包未在 `package.json#engines` 或 `peerDependencies` 中声明具体 DSH 宿主版本范围，仅声明需与 `@deepseek-ai/cordis ^4.0.1` 兼容

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-pocket](https://deepseek-plugin.org/plugins/shaobeichen/dsh-pocket)
Wiki generated by AI (model: `MiniMax-M3`)