Open Whale 🐳

把手机变成你这台电脑上的 DSH 的个人助理。

电脑上装 dsh-openwhale 插件，手机扫码绑定一次，之后就能像跟助理聊天一样远程使用电脑上的
DeepSeek Harness —— 口语化的回复、回复里的文件、远程关机/开机，都在这一个聊天窗口里。

三种客户端，同一个插件：

┌────────────────────┐   扫码绑定（一次性）   ┌─────────────────────┐
│  安卓 / 网页版手机   │ ◀─────────────────── │   电脑上的插件        │
│                    │                       │   dsh-openwhale     │
│  多个助理           │   WebSocket 长连接     │                     │
│  聊天 / 文件 / 协作  │ ◀───────────────────▶ │  DSH 会话（协作可共享）│
└────────────────────┘                       └─────────────────────┘
▲                                              │
└──── 局域网 · Tailscale · 公网隧道 ────────────┘

它解决什么

目录结构

open-whale/
├── packages/
│   ├── protocol/          协议契约（唯一权威源，v1.1.0），含 31 项单测
│   ├── plugin/            DSH 电脑端插件（纯 ESM、零运行时依赖）
│   │   ├── src/
│   │   │   ├── index.mjs        cordis 插件入口：装配各部件、命令、路由
│   │   │   ├── dsh-bridge.mjs   手机 ↔ DSH 会话桥（会话、消息、事件、文件）
│   │   │   ├── gateway.mjs      HTTP + WebSocket 服务、鉴权、帧路由、会话事件日志
│   │   │   ├── upload.mjs       分块上传（背压、校验、落盘到工作目录）
│   │   │   ├── webchat.mjs      网页版静态资源服务（/openwhale/app）
│   │   │   ├── ws.mjs           自实现 RFC6455 服务端
│   │   │   ├── qr.mjs           自实现 QR 编码器（PNG/SVG/终端）
│   │   │   ├── state.mjs        电脑身份、配对窗口、已绑定手机（原子写）
│   │   │   ├── pairer.mjs       二维码载荷与可用性判断
│   │   │   ├── voice.mjs        个人助理语气 prompt section
│   │   │   ├── power.mjs        关机/重启/取消 + WOL 魔术包
│   │   │   ├── tunnel.mjs       cloudflared 快速隧道生命周期（可选）
│   │   │   ├── wol-proxy.mjs    局域网唤醒代发（可选）
│   │   │   └── protocol.mjs     ← 由 packages/protocol 生成的自包含副本
│   │   └── test/
│   ├── mobile/            Open Whale 手机应用（Expo / React Native / TS）
│   └── webchat/           网页版客户端（零构建、原生 ESM、PWA）
├── docs/
│   ├── install.md         安装与配置
│   ├── security.md        安全模型与威胁分析
│   ├── mobile-build.md    手机端本地出包（Android APK）
│   ├── iOS-HarmonyOS.md   iOS 出包与鸿蒙适配（网页版/ArkTS 壳）
│   └── remote-power.md    远程开关机的真实边界
└── scripts/run-tests.mjs  一次跑完所有包的测试

下载这一版

去 Releases 下载（每个版本都带
SHA256SUMS.txt 可校验）：

插件也发布在 npm 上，可以按包名安装（升级时 dsh plugin 的 update 同样适用）：

dsh plugin --profile desktop add dsh-openwhale

APK 由 GitHub Actions 在发布时构建（本仓库作者的环境里没有 JDK 与 Android SDK），用 debug
keystore 签名，适合个人自用安装；要出正式签名的包见 docs/mobile-build.md。

自己打包插件：

node scripts/build-plugin-package.mjs            # → release/dsh-openwhale-2.2.1.tgz（含网页版）
node scripts/build-plugin-package.mjs --npm-dir  # → release/npm-package/（npm publish 用）

快速开始

1. 电脑端：装插件

从 Release 的 tarball 或 npm 安装：

dsh plugin --profile desktop add ./dsh-openwhale-2.2.1.tgz
# 或者
dsh plugin --profile desktop add dsh-openwhale

开发时可以直接装源码目录（改动只需重启 DSH）：

cd open-whale
dsh plugin --profile desktop add ./packages/plugin

（把 desktop 换成你实际使用的 profile 名。）装完重启 DSH。详细步骤与排错见 docs/install.md。

2. 电脑端：拿到绑定二维码

浏览器打开 http://127.0.0.1:/openwhale（插件固定端口是 8787，也可以直接开
http://127.0.0.1:8787/openwhale）。页面上有两个二维码：

• 手机 App 扫码：给安卓应用扫；
• 网页版扫码（鸿蒙 / iOS / 任意浏览器）：用系统相机扫，会直接打开网页版并自动绑定。

二维码有效期 10 分钟、只能用一次，绑定成功后立即失效。

3. 手机端：绑定

• 安卓：安装 APK → 打开 → 扫第一个二维码（也支持相册识图 / 手动输入地址）。
• 鸿蒙 / iOS / 浏览器：系统相机扫第二个二维码，或直接打开
  http://<电脑地址>:8787/openwhale/app 后在页面里粘贴配对内容。

4. 选择连接方式（建议）

配对页 / 手机设置里可以选：

> Tailscale 地址（100.x.x.x）现在是独立的连接方式，不再被当成局域网；自动模式会优先
> 用它，不会再让公网隧道抢在前面。

5. 之后

直接打开应用/网页即可，不需要再扫码。出问题时第一个该看的地方：
$DSH_HOME/openwhale/openwhale.log（插件自己的日志）。

远程连接怎么走

自动模式下的优先级是「上次成功 → Tailscale → 局域网 → 公网隧道」；某个地址连不上会换下一个，
连续失败时手机端会告诉你在试哪些地址、建议换哪种连接方式。

云隧道不可用时，局域网/Tailscale 方案不受影响 —— 这条路径是刻意保证的（插件对可选部件全部容错）。

远程开关机

关机 / 重启：电脑在线时可用，默认 30 秒宽限窗口，期间手机或电脑都能取消。电脑端可一键禁用（禁用后仍允许取消）。

开机：电脑关机后自己什么都没在跑，任何跑在它上面的软件都不可能唤醒它。真正可行的路径只有三条：

1. 有一台常开的设备在同一局域网里替你发魔术包（插件内置「唤醒代理」，配置 wol.targets）；
2. 手机与目标电脑在同一局域网时，手机自己发广播；
3. 完全断电只能带外手段（智能插座 + 主板「来电自启」）。

并且需要在目标电脑上：BIOS 打开 Wake on Magic Packet、关闭 Windows 快速启动、网线连接。
详见 docs/remote-power.md。

安全

• 二维码里是一次性、10 分钟有效的绑定密钥；绑定成功即失效，截图外发无长期价值。
• 绑定后认证靠手机侧 Ed25519 私钥签名（私钥只在手机安全存储/浏览器本地，从不上传）。
• 二维码携带电脑公钥，手机可据此验证 hello/ack 的签名，冒名顶替的隧道会被识别。
• 重放的握手会被随机数防重放表拒绝。
• 手机只能读取本次对话中产出（或电脑主动发送）的文件，不能请求电脑上任意路径。
• 会改变电脑状态的 HTTP 接口（协作开关、解绑、改名、发送文件、连接方式）只接受本机
  loopback 请求，因此即使配对页通过公网隧道打开，别人也无法远程改你的设置。
• 详见 docs/security.md（含威胁分析与已知限制）。

测试

本项目不依赖任何第三方运行时库（QR 编码器、WebSocket、协议、状态层、上传层全部自实现），
因此测试可以直接跑，无需安装依赖：

cd open-whale
node scripts/run-tests.mjs          # 全部：43 个测试文件 / 656 项测试（v2.2.1 基线）
node scripts/run-tests.mjs qr       # 只跑文件名含 "qr" 的
node packages/mobile/scripts/check-syntax.mjs   # 手机端 TS 语法检查

> 测试运行器的实现不平凡，原因写在 scripts/run-tests.mjs 顶部的注释里：在这个沙箱环境中
> node --test、node:test 的 run() 流、以及 process.exitCode 都不可靠，所以运行器让每个
> 测试文件在自己的子进程里运行、把输出重定向到文件描述符（不用管道），再依据子进程自己打印的
> node:test 摘要判定成败。缺失摘要一律算失败。

测试覆盖（含手机端与网页版）：

真实的装机验证（需要本机有 DSH）：

# 隔离环境，不动你正在用的 DSH_HOME
export DSH_HOME=<某个空目录>
dsh plugin --profile e2e add <本仓库>/packages/plugin
dsh --profile e2e --no-open
# 另开一个终端
node scripts/verify-install.mjs http://127.0.0.1:3080

该脚本会走完：读 health → 取二维码并按真实协议校验 → 打开网页版静态资源 → 用真实 Ed25519
密钥完成绑定 → 用二维码里的公钥验证电脑签名 → 能力协商 → 会话快照 → 发一条消息并验证
同一 msgId 重发只受理一次（v2.2.0 幂等性）。

已知限制

• 远程开机受物理条件限制（见上），插件只能提供能力与检查清单。
• 快速隧道不适合长期使用：无 uptime 保证、域名会变、部分地区不稳定。长期请用 Tailscale 或自建隧道。
• 鸿蒙原生应用：RNOH 尚未支持 RN 0.86 / Expo SDK 57，本版交付的是网页版 PWA（可添加到
  主屏幕，体验接近原生）；鸿蒙原生壳可用 DevEco 的 ArkTS Web 组件包一层，见 docs/iOS-HarmonyOS.md。
• iOS：本版提供 app.json iOS 配置、eas.json 与 GitHub Actions 模拟器构建流水线；真机安装 /
  TestFlight 需要 Apple 开发者账号（Expo 不支持在 Windows 本地构建 iOS）。
• 手机端 UI 与原生模块调用尚未在真机回归（开发环境没有 Android SDK/JDK）；出包由 GitHub
  Actions 完成。纯逻辑层有完整单测。
• 手机端尚未实现：后台保活、唤醒代理原生模块（目前只做引导）。
• 自动批准工具调用默认关闭（走 DSH 原有审批策略）；开启后手机发来的请求会跳过审批。

设计取舍（为什么这样做）

• 零依赖：插件要靠一次复制就装进 profile，任何依赖树或构建步骤都会变成装机失败点。
  QR、WebSocket、协议、上传全部自带。
• 协议自包含：packages/protocol 是唯一权威源，插件内 src/protocol.mjs 是生成副本，
  由 test/protocol-copy.test.mjs 保证不漂移。
• 协议只增不改：v2.2.0 升到 1.1.0（能力协商 + 新帧），2.1.0 与 2.2.0 可混用，用户不必
  同时升级两端。
• 幂等靠客户端 id：手机离线队列会重发，所以电脑端按 (设备, msgId) 去重；这是「同一条
  消息投递两次」的解。
• 多端同步靠事件日志：每个会话一份有界事件日志 + 游标，新加入/断线的手机能追上进度；
  窗口失效时退化成快照。
• 音色只作用于手机会话：用 agent 作用域的 prompt section，不影响桌面会话。
• 未知帧一律忽略：电脑端和手机端可以独立升级。