前言¶
DeepSeek Harness（DSH）桌面 Web GUI 目前不能直接把 Web 服务暴露给手机：桌面宿主固定以 --host 127.0.0.1 --port 0 启动 Web Host，Web GUI 的登录令牌只接受在 GET / 上兑换，Cookie 绑定 hostname + port，即使把服务绑到局域网 IP 也要重新走令牌/端口绑定，且默认没有移动端布局。
本插件提供独立的手机端 HTTP 服务，在同一局域网内用手机浏览全部 DSH 会话、实时查看回复并继续对话。它不依赖桌面 Web GUI 的绑定和登录态，不直接读写 session JSONL，也不修改会话内容，而是通过 ctx.sessionController 获取会话数据。
客户端设计¶
这不是把桌面 Web GUI 简单缩小的响应式页面，而是一个为手机重写的轻量客户端。会话列表、聊天记录、流式输出、工具调用折叠、历史翻页、新建会话和停止回复都针对触屏重新设计。
手机端有独立的访问令牌，持久化在 ~/.dsh/dsh-mobile/state.json；二维码里带的是这个令牌，不是桌面登录令牌。会话读写全部走 sessionController，与桌面 GUI、飞书机器人共享同一套会话记录。SSE 直接转发 sessionController.follow() 的 snapshot / durable event / assistant-stream 帧，所以手机能看到模型的流式输出和工具调用过程。
安装¶
从 npm 安装：
dsh plugin --profile web add @zyfgood/dsh-mobile
桌面版（推荐通过插件页）：
- 打开 DSH 桌面 Web GUI。
- 左侧 插件 → 安装插件 / 从本地安装。
- 填入
@zyfgood/dsh-mobile、本地路径或 tgz 路径，启用插件。 - 完全退出并重新启动 DeepSeek Harness。
- 启动后左下角出现 📱 按钮。
桌面版也可使用本地脚本安装：
powershell -ExecutionPolicy Bypass -File D:\DSHProjects\dsh-mobile\scripts\install-desktop.ps1
使用¶
- 确认手机和电脑在同一个局域网（同一 Wi-Fi，或手机能访问电脑的局域网 IP）。
- 在桌面 Web GUI 左下角点 📱。
- 用手机相机/浏览器扫描二维码，或复制链接发到手机打开。
- 首次打开会自动用二维码里的令牌登录；之后 30 天内免登录。
- 在会话列表点任意会话 → 查看历史 → 在底部输入框继续对话。
- 如果当前回复正在运行，输入框右下角会显示停止按钮；新消息默认排队，当前轮结束后自动处理。
二维码链接形如 http://192.168.1.23:35888/#token=...。令牌放在 URL fragment 里，不会随 HTTP 请求发送到服务器；页面加载后由 JS 读取并 POST /api/login 换取 HttpOnly Cookie，然后从地址栏清掉。
如果手机打不开，最常见的原因是 Windows 防火墙。桌面宿主进程是 DeepSeek Harness.exe；如果它没有允许入站，手机就连不上 35888 端口。可在 Windows 安全中心 → 防火墙和网络保护 → 允许应用通过防火墙，勾选 DeepSeek Harness（或 Node.js）的专用网络。
配置¶
在 profile 的 cordis.patch.yml 中给插件加 config，例如：
- id: dsh-mobile
name: '@zyfgood/dsh-mobile'
config:
host: 0.0.0.0
port: 35888
accessToken: '至少16个字符的固定访问码'
主要配置项：
| 字段 | 默认 | 说明 |
|---|---|---|
enabled |
true |
关闭后不启动手机端服务，桌面入口仍可显示错误 |
host |
0.0.0.0 |
监听地址；0.0.0.0 表示所有 IPv4 网卡，127.0.0.1 表示仅本机 |
port |
35888 |
监听端口；0 由系统分配 |
autoPort |
true |
端口被占用时自动尝试 35888–35898 |
publicHost |
'' |
手机访问使用的主机名/IP；留空自动挑最佳局域网 IPv4 |
accessToken |
'' |
固定访问码（≥16 字符）；留空自动生成并持久化 |
includeSubagents |
false |
会话列表包含子代理会话（只读查看） |
maxSessions |
300 |
最多展示的会话数 |
pageSize |
40 |
每次加载的历史消息数 |
heartbeatSeconds |
15 |
SSE 心跳间隔 |
cookieMaxAgeDays |
30 |
手机登录 Cookie 有效期 |
defaultCwd |
'' |
新建会话默认工作目录 |
allowNewSession |
true |
允许手机端新建会话 |
desktopPanel |
true |
是否在桌面 GUI 显示 📱 入口 |
修改 accessToken 会让所有已登录手机失效。删除 ~/.dsh/dsh-mobile/state.json 会同时轮换令牌和 Cookie 签名密钥。
安全模型¶
这是一个局域网内的访问方案，不是公网穿透。默认 HTTP 下，令牌和消息内容在 Wi-Fi 链路上是明文；对安全敏感的场景请配置 TLS，或只在自己信任的网络使用。
已实现：
- 访问令牌：32 字节随机令牌（或自定义 ≥16 字符），持久化文件，二维码只给已登录的桌面端；
- 签名 Cookie：HMAC-SHA256，
HttpOnly、SameSite=Strict、Path=/；TLS 时加Secure； - 令牌指纹：Cookie payload 里带令牌哈希前缀，轮换令牌立即失效旧 Cookie；
- 登录限速：单 IP 15 分钟最多 20 次失败尝试；
- Origin / Sec-Fetch-Site 检查：拒绝跨站写请求；
- CSP / X-Frame-Options / nosniff / no-referrer：页面不可被嵌套，脚本只允许同源；
- 请求体上限 256KB，登录体 16KB；
- 桌面入口受桌面登录态保护：
/dsh-mobile/status和/qr.svg都过ctx.connection.requestRejection()，未登录桌面拿不到令牌。
未实现 / 注意：
- 没有公网穿透、账号体系、设备管理、远程吊销列表；
- 手机端目前不支持审批操作，只显示“等待批准，请在桌面端处理”；
- 不支持从手机上传附件/图片；
- 子代理会话默认不显示，即使打开也仅只读；
- 手机端服务与桌面 GUI 同进程，DSH 退出后手机端不可用。
桌宠联动¶
配合 @zyfgood/dsh-whale-girl 0.3.0+，鲸鱼右侧鳍里拿着一部小手机；点击手机打开/关闭手机端面板，面板锚定在桌宠上方；右键菜单新增 📱 手机访问 入口；手机首次连上时，桌宠挥手说“手机连上啦～”，手机出现呼吸光环；桌宠隐藏时，手机面板入口自动回退到左下角按钮；没装桌宠或桌宠版本过旧时，手机端保持原来的独立按钮，不会报错。
生态与维护¶
本插件按 DSH 生态的公开约定发布：npm 包声明了 dsh 清单、dsh-plugin / deepseek-harness 关键词和 dsh.catalog 元数据；GitHub 仓库带有 dsh-plugin topic；精选目录 awesome-dsh-plugin 通过 data/plugins/zyfgood__dsh-mobile.yml 提交，dshmarket 和目录站会按日同步。
市场收录由目录维护者审核，不等同于安全审计；安装第三方插件前请自行确认来源。
