k12u/dsh-ios-pwa

DSH Mobile

一个用于在智能手机上操作 DeepSeek Harness 的 React / TypeScript PWA，以及从同一源提供服务的轻量级 Gateway。

已针对真实的 Harness RC.1 进行验证：启动、HTTPS/WSS 初始同步，以及对文本提示的真实模型响应。验收测试——包括浏览器操作、iPhone / Android 以及 Push 投递——尚未完成。 目标 API 已对照官方 Harness 0.1.2-rc.1 发行版和参考 Gateway 0.7.1 进行交叉核对。

本地预览

需要 Node.js 22.12 或更高版本（CI 使用 24）。

npm ci
npm run build
npm run dev

在 5 分钟内从控制台打开 http://localhost:8787/pair?t=... 链接。预览 Agent 是一个演示，不运行任何模型或 shell。你可以验证 Inbox 审批和问题、Sessions、对话流式传输以及图片附件。重启会重置演示状态和设备认证。

localhost 和 127.0.0.1 是不同的源。在浏览器中，请完全按照显示的内容使用 localhost 链接。HTTP 例外仅用于回环开发。若要向智能手机提供服务，请使用配置了 HTTPS 源的 Harness 插件。

在 Mac 上，如果 Node.js / pnpm 本身尚未安装，请通过你的用户 nix-darwin / Home Manager 配置进行管理。本项目不会修改系统或 shell 设置。

作为 Harness 插件使用

1. 将此仓库放置在运行官方 dsh web 的主机上，然后安装依赖并构建。
2. 将 gateway/cordis.patch.yml 中的 publicOrigin 更改为 PWA 的实际 HTTPS 源。
3. 添加插件并重启 Harness。

dsh plugin --profile web add link:/absolute/path/dsh-ios-pwa/gateway
dsh web

示例：

- insert:
- id: mobile-pwa
name: dsh-plugin-mobile-pwa
config:
publicOrigin: https://your-host.example
port: 8787
pushSubject: mailto:operator@example.com

如果省略 pushSubject，则不会通告 Push 能力。VAPID 密钥、已认证设备的哈希以及 Push 订阅以 0600 权限存储在 ~/.local/state/dsh-mobile/ 中。存储位置可以通过 dataDir 或 DSH_MOBILE_DATA_DIR 环境变量更改（dataDir 优先）。兼容性冒烟测试使用隔离的临时目录。请勿将此数据提交到 Git。

Gateway 仅监听 127.0.0.1:8787。将 Tailscale Serve 或你的 HTTPS 反向代理指向此端口。仅 Gateway 端口对外转发。请勿转发 Harness Web UI 端口或原始 Remote API。Gateway 一并提供 /、/api/、/ws/mobile 和 /push/。
在 Harness 主机上打开 http://localhost:/mobile-pwa，即可签发一个配对二维码 / 链接，其有效期为 5 分钟且仅限单次使用。用手机的标准相机扫描即可连接。首次启动时，该链接也会出现在控制台中。已认证的设备可以从 PWA 的“设置”中撤销，而已配对的设备可以从“设置 → 添加设备”签发一个新的单次链接，这样无需访问主机即可配对另一部手机。

此本地管理页面目前不会在侧边栏中添加链接；请直接打开上面的 URL。浏览器永远不会收到长期有效的令牌；取而代之的是设置一个 HttpOnly; Secure; SameSite=Strict; Path=/ Cookie。

架构与边界

Official Harness (external runtime)
→ gateway/src/adapters/
→ gateway/src/normalization/adapter.ts
→ packages/protocol/ (Zod + TypeScript)
→ packages/domain/
→ web/src/state/ + projections/
→ React UI

- packages/protocol：一个自包含的 Mobile Protocol v1，是与参考原生客户端的线上协议相互独立的契约。会剥离未知字段并忽略未知事件。
- gateway/src/adapters：对 Host API、原始事件、HITL 瀑布流以及任务 / 目标投影进行规范化。PWA 永远不知道 Harness 版本。
- gateway/src/auth：一次性配对、过期 Cookie、撤销、速率限制。
- gateway/src/push：使用 Node crypto / fetch 实现 RFC 8291 加密和 RFC 8292 VAPID。通知正文绝不包含工具参数或对话内容。
- web：收件箱 / 任务 / 会话、对话 / 活动 / 文件、通用审批 / 问题渲染器、重连以及 PWA 外壳。
- vendor/mobile-gateway：参考 Gateway 的已保存源码和契约测试。不属于发行版的一部分。只有复用的 Host Adapter 被放置在 gateway/src/adapters/upstream 中。

没有对 Harness 本身进行分叉、打包或原生封装。没有创建任何 GitHub 分叉或公共仓库。一个验收测试 Gateway 部署在 dsh1 tailnet 内。

将原始 API 挡在 React 之外的边界由检查导入解析的测试以及将额外内部字段送入 Adapters 的 HTTP 契约测试来保护。历史记录、快照、会话创建结果和实时事件在发送前都会经过共享的 Zod schema。例如，assistant/chunk 在 Adapter 中被转换为 message.delta，而 PWA 永远不会解释 turn / step / chunk。活动中显示的参数和结果也是规范化后的字符串预览。

同步与运行

连接顺序为 hello → 权威快照 → 在获取该快照期间缓冲的事件。所选会话的历史记录也会被重新获取，并且在完成之前写入保持禁用。显示状态绝不会仅靠 WebSocket 重连来恢复。
历史记录和实时事件在 Adapter 中产生相同的 ID / seq。延迟的历史页面也会被接受，其中消息完成正文被视为权威。HITL 不会由回执来确定；它会在正式 resolved 事件或重连后的快照上确定。重复的提示请求 ID 会在单个 Gateway 进程内阻止 24 小时内的重复执行。浏览器从不自动重发。

应用不假设 socket 在后台运行后仍然存活；它会在 visibility / pageshow / online 时重新同步。401 会停止重试并返回配对界面；Gateway 停止会导致重试间隔上限约为 30 秒。

图片在客户端限制为 PNG / JPEG / WebP / GIF，每张 3.5 MB，最多 4 张图片。实际的图片验证和会话成员资格检查由官方 Harness 处理。图片通过专用的受 Cookie 保护的路由获取。没有用于读取任意路径的 API。通用文件传输、SHA-256 下载验证和 Web Share 属于第二阶段。

PWA 和更新

包含 manifest、192/512px 图标、独立显示和安全区域支持。Service Worker 仅处理公共 shell / 哈希资源以及 Push。API、配对、对话和凭据从不存储在 Cache API 中。

IndexedDB 最多存储 50 个 workspace / session / task 摘要，每类最多保留 7 天。对话、图片、工具结果以及未解决的审批 / 问题从不存储。离线时，显示最后获取的信息，并禁用写入。

更新在用户通过更新横幅明确重新加载时应用。应用从不在使用过程中自动重新加载 Agent 或 UI。

对于 iPhone Push，请将应用添加到主屏幕，从那里打开它，并在“设置”中授予通知权限。不支持订阅 API 的浏览器会显示说明。Push 提供方仅限于指定的 Apple / FCM / Mozilla / Windows 主机；不具备获取任意外部 URL 的能力。

验证

npm run build
npm test
npm run test:upstream
npm run test:network

构建后运行 npm test。它会针对已发布的 RFC 向量验证 HTTP 处理器、真实 WebSocket 帧的内存转发、并发快照 / 事件、Origin / Cookie / revoke、请求幂等性、历史记录合并、HITL、XSS、PWA 资源和 Push。

test:network 适用于 TCP 可用的环境。它还会通过真实 socket 额外验证配对 / 流式传输 / 重连。test:upstream 针对保存的原始 Host Adapter 运行契约测试；它并不声称原始 Gateway 的所有测试都已运行。

DSH_BIN=/path/to/node_modules/@deepseek-ai/dsh/lib/bin.js npm run test:harness
Harness 冒烟测试使用临时的 DSH_HOME，并验证官方运行时 + 插件启动、静态服务、配对、host/workspace/session 快照，以及 WebSocket hello / snapshot 初始同步。使用模型的完整 prompt / HITL / 图像路径需要在真实连接上进行单独验证。

CI 包括 build / contracts / network smoke，以及针对最新公开 stable / RC / alpha 版本的每周和手动 Harness 启动矩阵。CI 尚未运行，且不保证所有通道之间的兼容性。

静态布局文档也可以生成：

npm run preview:static

test-results/preview.html 是一个屏幕预览，不包含通信。

单包分发

npm run build
npm pack --workspace gateway

该 tarball 包含 Gateway、编译后的共享 contracts 以及 PWA 资源。运行时依赖仅有 ws 和 zod；Harness 保持外部依赖。更改 Protocol 时，请同时更新此分发单元。

另请参阅：Mobile Gateway、原生移动客户端、RFC 8291、RFC 8292。有关来源和许可信息，请参阅 THIRD_PARTY_NOTICES.md。