DSH Pocket

English | 中文

把 DeepSeek Harness 装进你的口袋：一个包、一个设置页，手机扫二维码就实时看到电脑上的同一个界面——人在外面也能用。

⭐ 顺手留颗 Star，作者能高兴一整天  ·  行，给你一颗 Star

这是什么

你不在电脑前，也想用电脑上的 DeepSeek Harness。

• 下班路上，agent 在电脑上跑任务，你想掏出手机看看它干到哪了、结果如何
• 出门在外，突然想让电脑上的 agent 查点资料、写段代码，但没有远程桌面、没有 SSH
• 电脑在宿舍/办公室，你人在外面，想随时"操控你的 DeepSeek Harness"——发任务、看输出、点审批

DSH Pocket 就是干这个的：装上它，手机扫个码，就能实时看到并操控电脑上的 DeepSeek Harness 界面——人在外面也能用。

实际效果——手机上的界面就是电脑上的界面，实时同步：

✨ 特性

特性	说明
📶 局域网扫码	装好即用：设置 → Pocket，打开就有局域网二维码，手机连同一 WiFi 扫码即开（自动识别本机局域网 IP，WSL 环境自动取 Windows 物理网卡 IP）
🌐 公网扫码（人在外面）	点「开启公网访问」→ cloudflared 隧道 → 出公网二维码，4G/任何网络都能访问
🔐 访问密码	局域网与公网各一把 8 位数字密码（本机浏览器免密码）：局域网密码常驻、可在设置页点「刷新」换新，也可一键关闭（关闭后局域网扫码直连）；公网密码每次开启公网自动换新，旧链接立即作废，不受开关影响
🔑 自定义密码	公网/局域网密码都可在设置页设成自己固定的 8 位数字——自定义后公网不再自动换新（issue #33）
🌍 多语言	全部界面与终端日志跟随 DSH 的全局语言选择（设置 → 语言，中文 / English）——包括手机上的访问密码页；没显式选过语言时，界面跟浏览器、日志跟系统 locale
🛡️ 下载校验	cloudflared 二进制按 GitHub 官方 SHA-256 逐字节校验，镜像只是搬运工
⚡ 实时同步	流式输出走 WebSocket 全透传——电脑上在输出，手机上同步在滚，可双向操作；内置心跳保活（防路由器 NAT/省电机制静默断链，断线自动重连）
📱 移动端适配	窄屏自动变抽屉布局（移植 dsh-web-mobile，MIT）：侧栏抽屉、会话全宽、状态栏安全区、触控优化
🗜️ 传输压缩	大 JSON 响应自动 gzip/brotli（长会话 17MB → ~1MB）；brotli 走质量 6——默认的 q11 压 17MB 要 40 秒，手机直接超时，q6 约 130ms 且输出更小
🔁 隧道自动恢复	DSH 重启后自动重新拉起之前开着的公网隧道，无需手动重开
🧩 零依赖安装	一个 npm 包、一个设置页，没有核心/适配器要分开装；无需账号、无需服务器
🤖 Telegram 机器人	把 BotFather token 贴进设置页，聊天里直接派活、看结果——不用扫码不用开网页；配对码默认拒绝，未配对的聊天什么都问不出来

🚀 怎么用

入口在哪：安装完成并重启 dsh web 后，打开 设置，左侧边栏就能看到 「Pocket」 入口（手机图标，和「通用设置」「模型」同级）：

前提：电脑上已装好 DeepSeek Harness。如果终端提示 dsh: command not found（找不到 dsh 命令），先安装：

npm install -g @deepseek-ai/dsh     # 全局安装；验证：dsh --version
# 不想全局装？每次命令前加 npx：npx @deepseek-ai/dsh <命令>

# 1. 装插件（一个包全都有）
dsh plugin --profile web add dsh-pocket -w

# 2. 重启 dsh web
npx @deepseek-ai/dsh web

局域网（同一 WiFi）

设置 → Pocket → 手机扫「📶 局域网」二维码 → 输入 8 位访问密码（点「刷新」可换新，或点「自定义」设成自己固定的 8 位数字）→ 打开的就是电脑上的 DSH，实时同步。

局域网密码默认开启（安全优先）。只有自己用、嫌每次输麻烦的话，可以在局域网标签页把「局域网访问密码」切到关——之后同一网络下扫码直连、无需密码。公网始终要密码，不受这个开关影响。

公网（人在外面）

同一页点「开启公网访问」→ 每次都会先弹出安全免责声明，勾选「我已知情」后才能开启（公司/涉密网络请先确认合规）→ 等隧道建立（首次会下载 cloudflared，macOS/Linux 走清华镜像秒下；下载文件按官方 SHA-256 校验）→ 手机扫「🌐 公网」二维码 → 打开链接输入 8 位访问密码（密码显示在设置页公网区块，默认每次开启公网变新，也可点「自定义」设成固定密码——自定义后不再换新）→ 人在外面（4G/公司网）也能访问。

更新到新版本：dsh plugin --profile web update dsh-pocket --latest -w（跨大版本时 --latest 是必须的，^0.x 范围不会自动升到 1.x）。

Telegram 机器人（聊天里直接派活）

设置 → Pocket → 「Telegram」标签页，三步接好：

1. Telegram 里找 @BotFather，发 /newbot，起个名字
2. 复制它给你的 token（形如 123456789:AA…）
3. 贴进设置页输入框，点「关联机器人」→ 点「启动机器人」

然后在 Telegram 里给机器人发 /start <配对码>（配对码显示在设置页，15 分钟有效、点「刷新」换新、配对成功即作废）完成配对。之后直接发消息就是给 DSH 派活，跑完把最终答复发回来；续聊上下文保留（同一话题继续追问），/new 开新话题、/stop 打断当前任务。

命令	作用
/start <配对码>	配对这个聊天（唯一不要求已配对的命令）
直接发文本	派活；跑完回最终答复（长回复自动拆段）
/new	下一条消息开全新话题（清掉续聊上下文）
/stop	打断当前任务

安全模型与扫码同源：默认拒绝——未配对的聊天除 /start 外收不到任何东西（连「有没有在跑任务」都问不出来）；token 只存本机 $DSH_HOME/dsh-pocket/bot.json（权限 0600）、永不出主机；配对后的聊天能像手机界面一样操控你的电脑（跑任务、改文件），请只配对你自己的账号，「已配对聊天」列表里随时可解除。注意：机器人走的是 BotFather 的长轮询（不需要公网回调/HTTPS 证书，人在内网也能用），但续聊范围是进程生命周期内——重启 dsh web 后各聊天从新对话开始（诚实降级）。

⚠️ 安全（必读）

• DSH 能执行你电脑上的代码。局域网与公网都需要 8 位数字密码（本机浏览器免密码；登录后种会话 cookie，12 小时有效）
• 开启公网访问前必须阅读并勾选免责声明（每次开启都会弹框；服务端强制校验，无法绕过）：公网 = 把能执行代码的 DSH 暴露到互联网，请使用强密码、用完即关、涉密网络勿用
• 局域网密码可在设置页关闭（默认开启）。关闭后同一网络内的任何设备扫码即可直连——公用 WiFi 下别关。开关状态存 $DSH_HOME/dsh-pocket/settings.json，改动会立即作废已登录会话
• 密码暴力破解防护：同一 IP 连续失败指数退避，超过阈值锁定 15 分钟
• DNS rebinding 防护：代理校验 Host 头，只放行本机地址 / localhost / *.trycloudflare.com（或环境变量 DSH_POCKET_ALLOWED_HOSTS 列出的域名）——任意网页都拿不到「经代理进 DSH」的同源读权限
• cloudflared 下载文件按官方 SHA-256 逐字节校验后才执行；国内加速镜像只是 CDN，给错一个字节都会被拒
• 公网 URL 由 cloudflared 随机分配，每次重启会变化（旧链接自动失效，相当于天然轮换）；每次开启公网密码自动换新，旧会话同步作废（设置页「自定义」设成固定密码后不再自动换新）
• 会话 cookie 是随机 id 而非密码本身（HttpOnly + SameSite=Strict；隧道段加 Secure），且不会转发给上游 DSH
• 密码存本机 $DSH_HOME/dsh-pocket/token（权限 0600），可随时重开公网换新；自定义标记同样存本机 settings.json
• Telegram 机器人：配对后的聊天与手机界面同一信任级别（能跑任务、改文件）——默认拒绝、只配对自己账号；bot token 存 $DSH_HOME/dsh-pocket/bot.json（权限 0600）、永不出主机；「已配对聊天」随时可解除，解除立即生效
• 注意：代理运行期间，你浏览的任意网页都可以向代理发请求（同源保护由代理自己承担，见上两条）——请勿在不可信网络里开着代理用 DSH 执行敏感操作

💻 DSH Desktop（桌面版）

• 桌面版里 dsh-pocket 的扫码同屏正常可用；更新/重启由桌面版管理（插件内这两项自动停用）
• ⚠️ 桌面端 advanced 模式暂不支持手机访问（该模式禁用网页布局、手机拿不到 layout 服务，会白屏）——请切回 compatibility 模式后重启；advanced 模式下手机打开会看到明确的提示层

🩹 常见问题（别踩的坑）

现象	原因与解决
dsh: command not found / 提示 DSH 未定义	dsh CLI 没装：npm install -g @deepseek-ai/dsh，或命令前加 npx @deepseek-ai/dsh
ERR_PNPM_ADDING_TO_ROOT	pnpm 9 对 workspace 根的限制：安装/更新命令末尾加 -w（--workspace-root）
装完/更新了但界面没变化	必须重启 dsh web 才生效；运行中的进程仍加载旧代码
listen EADDRINUSE ... :3081	旧 dsh-pocket 进程还占着端口：macOS/Linux lsof -ti :3081 | xargs kill -9；Windows netstat -ano | findstr :3081（找 LISTENING 的 PID）→ taskkill /PID <PID> /F，后重试
版本停在 0.x 升不上去	^0.x 范围不允许升到 1.x：更新用 --latest（dsh plugin --profile web update dsh-pocket --latest -w）
公网 error 1033	见下方「公网隧道常见问题」——多半是本机代理/VPN（Clash 等 TUN 模式）掐断了隧道
点「重启 dsh web」后页面提示进程在后台运行	自重启的新进程是 detached 后台进程（不挂终端），是页内更新的标准做法；停止它：macOS/Linux lsof -ti :3080 | xargs kill -9；Windows netstat -ano | findstr :3080 → taskkill /PID <PID> /F（日志在 $DSH_HOME 下 dsh-pocket-restart-*.log）

⚠️ 公网隧道常见问题（必读）

现象：点「开启公网访问」后，手机上打开公网地址报 error 1033（Tunnel error）。

最常见原因：本机开着代理/VPN（Clash、Surge、v2ray、sing-box 等，尤其 TUN 模式）。 这类工具会接管全部流量，并常常把 cloudflared 的隧道边缘连接 （*.argotunnel.com、Cloudflare 边缘 IP）掐断，导致隧道注册成功但数据面连不上。

解决（从轻到重，按顺序试）：

1. 先只关闭代理的 TUN 模式，不用退出代理软件——多数情况这一步就够：
   • Clash：设置里关掉「TUN 模式」开关（或右键菜单栏图标 → 取消勾选 TUN 模式）
   • Surge：关「增强模式」；v2ray/sing-box：关「虚拟网卡/路由接管」
   • 然后回设置页重新点「开启公网访问」
2. 仍不行就彻底退出代理软件（不只是关界面：Clash 要右键菜单栏图标 → 退出；若装有 后台服务还要在服务管理器里停掉，ps aux | grep clash 确认进程消失），再重试
3. 给代理加直连规则，放行隧道域名与 Cloudflare 边缘（Clash 规则示例）：

   - DOMAIN-SUFFIX,argotunnel.com,DIRECT
   - DOMAIN-SUFFIX,trycloudflare.com,DIRECT
   - IP-CIDR,198.41.192.0/24,DIRECT,no-resolve
   

4. 网络实在不通时，改用局域网模式：手机开热点 → 电脑连手机热点 → 扫局域网码， 效果完全一样（人在外面也能用）

其他可能：企业防火墙/校园网拦截出站；此时请让 IT 放行或改用热点。

首次开启时「下载 cloudflared」失败/卡住：

• macOS/Linux：优先走清华镜像（实测 ~3MB/s，几秒下完）；失败自动回退官方 GitHub + 加速源。
• Windows：无清华镜像（Homebrew 不支持 Windows），走官方直连下载（约 50MB，单线程会慢，属正常，耐心等几分钟；也可挂代理加速）。
• 全部失败时设置页会给出提示。备选方案（任选其一）：

1. 手动装好命令行 cloudflared 后重试（装好后 dsh-pocket 直接用 PATH 里的，不再下载）：
   • macOS：brew install cloudflared；Linux：sudo apt install cloudflared 或官网下载
   • Windows：winget install cloudflared 或官网下载
   • 任何平台：npm i -g cloudflared
2. 挂代理（系统代理/Clash 等）后重新点「开启公网访问」
3. 手动下载二进制放到 $DSH_HOME/dsh-pocket/bin/ 目录（$DSH_HOME 一般是 ~/.dsh，Windows 是 %USERPROFILE%\.dsh；文件名用 cloudflared（Windows 加 .exe）或发布资产名均可，插件都认）

🗂 架构（单包）

文件	说明
lib/index.js	插件入口：自动起代理 + 注册 RPC + 公网访问密码管理（8 位数字，每次开启变新）+ 桌面端环境适配
lib/settings.mjs	设置持久化：局域网密码开关（默认开启）存 $DSH_HOME/dsh-pocket/settings.json
lib/service.mjs	服务：代理生命周期（端口自适应）、公网隧道（自动恢复）、状态快照（含二维码）
lib/proxy.mjs	改头反向代理：Host/Origin → loopback，HTTP + WebSocket 透传 + polyfill 注入 + gzip/brotli 压缩 + 公网访问令牌认证
lib/tunnel.mjs	cloudflared：多镜像源下载（清华优先）/自适应多线程/启动/解析公网 URL（HTTP/2）
lib/auth.mjs	访问认证：PIN 生成/存储、会话 cookie（12 小时）、同 IP 暴力破解指数退避锁定、Host 白名单（DNS rebinding 防护）
lib/bot.mjs	Telegram 机器人通道：长轮询传输与生命周期、配对码、命令路由
lib/bot-bridge.mjs	DSH 桥：把一条聊天文本跑成一轮回复（上下文续聊、/new、/stop）
lib/locale.mjs	服务端文案语言：跟随 DSH 全局语言选择（设置 → 语言）
lib/restart.js	自重启：detached 交接重新拉起 dsh web，让更新后的代码生效
lib/web-rpc.js	loopback RPC：pocket.status / tunnel.start / tunnel.stop（需先勾选安全免责声明）/ token.lanRefresh / lanAuth.setEnabled / pin.setCustom / bot.status·setToken·start·stop·pairRefresh·unlink / pocket.version / pocket.update / pocket.restart
client/	设置页「手机访问」+ 移动端适配（dsh-web-mobile 移植）
bin/dsh-pocket.mjs	CLI：局域网/公网模式，打印 URL + 二维码

🛠 开发

npm install
node client/build.mjs   # 改 client/ 后重新打包
npm test                # 代理 / 认证 / 压缩 / 隧道 / 服务 / RPC / 设置 / 机器人（98 测试）

🤝 致谢

• 移动端适配移植自 mexiaosqwq/dsh-web-mobile（MIT）
• 公网隧道基于 cloudflared

📄 License

GPL-2.0 —— 自由软件许可：可自由使用、修改、分发，但修改版必须同样以 GPL 开源并保留版权声明；商用同样适用。

说明：移动端适配部分移植自 dsh-web-mobile（MIT 许可，兼容 GPL），其版权声明保留在 client/mobile/LICENSE.dsh-web-mobile。

---

有问题？欢迎反馈：遇到 Bug、有想法、想提需求，请到 GitHub Issues 告诉我们 🙏