dsh-harness-remote — 手机远程连接 DeepSeek Harness

dsh-harness-remote 是一个开源社区产品：用手机远程连接 DeepSeek Harness（DSH），离开电脑后也能盯住 agent、接收通知、一键审批、回答提问、继续对话。对标 Claude Code Remote Control 的定位，但面向 DSH 开源生态，代码与数据都留在用户本机，手机只是视口。

• 跨端：React Native + Expo（TypeScript），iOS + Android 一套代码，EAS 云构建无需 Mac 即可出 iOS 包。
• 审批流程：会话列表待办横幅直达审批列表页，多选批量批准/拒绝、提问批量跳过；处理历史按时间倒序可查；通知点击深链直达 approval/:rpcId。
• 会话列表：搜索（标题/workspace/最近消息，大小写不敏感）、按 workspace 分组（无 workspace 归「其他」）、上下文压力分档提醒（<70 正常 / 70–85 偏高 / ≥85 告警）；在线时顶部「＋ 新会话」直接创建 DSH 会话。
• 聊天体验：DeepSeek 风格大圆角输入框 + 圆形发送按钮；长按消息操作菜单（复制全文/按代码块分别复制）；代码块默认展开可折叠 + 轻量语法高亮（关键词/字符串/注释/数字四类）；流式暂停为真中断（session.cancel RPC，失败自动回退本地暂停渲染并提示）；同时兼容 DSH Desktop 新版事件流（user/message、assistant/chunk、assistant/message）。
• 远程优先首屏（R1）：App 首屏就是「远程连接我的电脑」，只填电脑上显示的连接地址（自动补全 ws://…:4090）+ 可选 6 位码；同一 Wi-Fi/扫码等低频能力收进「更多连接方式」，不做专业术语展示。
• 电脑端一键远程（R4）：dsh-remote remote 自动启动内置 relay（4090 被占用自动选空闲端口）→ 自动探测并桥接本机 DSH API（DSH_WEB_URL / 127.0.0.1:56734 / 127.0.0.1:3080）→ 注册 console → 取一次性 6 位配对码 → 打印小白卡片 + 远程二维码（含端口）+ 扫码载荷；手机配对后即可看到 DSH 会话、发消息、审批。Windows 用户可直接双击 dsh-remote-remote.bat，不用敲命令。
• LAN 起步、传输可插拔：自动发现 + 二维码配对 + 最近主机一键重连，也可以手动直连局域网内的 DSH（host:3080）；传输层抽象为 Transport 接口，连接页输入 relay:// / ws:// URL 即切换 Relay 模式（M3 中继：控制面 + E2E 加密 + 离线队列，自部署不托管）。
• 插件能力面（R2）：协议新增 plugin.list / plugin.exec 契约；App 会话长按菜单动态展示用户 DSH 插件指令，设置页插件入口进入插件列表（命令 + 设置，单屏克制）。dsh-harness-remote 自身不做插件宿主——用户 DIY 插件通过 DSH 插件系统 + R2 能力面在手机端呈现。
• 设置迁移（R3）：设置页分「连接 / 模型与权限 / 插件 / 显示 / 关于」；host.settings.get/set 能力可探测（读不到自动隐藏）；模型选择、思考强度、上下文容量、审批权限状态；App 本地字体大小；外观：浅色（默认）/ 深色 / 跟随系统；检查更新走 GitHub Releases 对比。
• 低门槛连接（P2）：首启 3 步引导 → 扫码电脑上的配对二维码即连（dshremote://pair 深链）；同一局域网点「自动发现」列出可用实例；冷启动自动重连最近主机。
• 协议对齐：纯 TS 协议包（packages/protocol，零 RN 依赖）与 DSH 原生类型零失真对齐；宽容解码，线上层永不因未知数据崩溃。
• 设计：UI 设计系统 v7（docs/design/UI-SYSTEM-v7.md）——双主题默认浅色、可手动切换/跟随系统，DeepSeek 官方主按钮蓝（浅 #3964FE / 深 #5686FE）、官方黑色鲸鱼、Space Grotesk 显示字体；统一入场/退场动效，尊重系统「减弱动态」。

界面预览

远程连接页	设置页	插件页	会话列表	聊天

截图来自 Web 预览（390×844 视口）；远程连接页/设置页/插件页为 R1/R3 新界面（relay 配对闭环联调实截），会话列表/聊天沿用 v7 截图。真机观感一致（通知/扫码为原生能力，Web 会优雅降级）。

仓库结构

dsh-harness-remote/
├── apps/
│   └── mobile/            # Expo RN App（iOS + Android）
│       ├── app/           # expo-router 页面：连接、会话列表、聊天、审批列表/详情/历史、设置
│       ├── src/
│       │   ├── transport/ # ConnectionProvider + pipeline（装配 ConnectionLoop）
│       │   ├── data/      # SessionStore：会话镜像、折叠、投影派生
│       │   ├── notify/    # 通知分类器 → 本地通知（expo-notifications）+ 后台保活
│       │   ├── discovery/ # 最近主机 / 子网自动发现 / 配对深链 / 首启引导
│       │   ├── ui/        # 设计系统 v7 组件（WhaleMark/StatusChip/Button/Field/…）
│       │   ├── theme.ts   # DSH 设计令牌 v7（双主题：浅 #3964FE / 深 #5686FE）
│       │   └── theme-context.tsx # ThemeProvider + useTheme（默认浅色，可切换深色/跟随系统）
│       └── app.json       # EAS 配置（云构建）
├── packages/
│   └── protocol/          # TS 协议核心（纯 TS，零运行时依赖）
│       └── src/           # envelopes / codec / rpc / ws / transport / loop / dto / relay(M3)
├── mock-harness/          # DSH /api + WS 测试桩（回放 conformance fixtures）
├── tools/
│   └── capture/           # 录制真实 DSH 流量 → conformance fixtures
├── harness-plugin/        # DSH 宿主配对插件（M2：token 签发/校验/配对围栏；M3 出站中继客户端，E2E 加密数据面）
├── relay/                 # M3 中继服务器（WS 控制面 + E2E 密文转发 + 离线队列；自部署，不托管）
├── docs/
│   ├── ARCHITECTURE.md / PROTOCOL.md / COMPATIBILITY.md / SECURITY.md
│   └── design/            # UI-SYSTEM.md / BRAND.md / CONNECTION-UX.md
└── package.json / pnpm-workspace.yaml / tsconfig 等

快速开始（用户）

# 1. 电脑安装插件（DSH 设置页会出现「手机远程」）
dsh plugin --profile web add dsh-harness-remote -w

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

# 3. 打开 DSH 设置页 → 手机远程 → 开启公网访问 → 手机 App 扫码

电脑端需要 Node.js 与 DSH；手机 App 从 GitHub Releases 下载 app-release.apk。公网模式走 cloudflared 免费隧道，无需账号/服务器/公网 IP。

开发快速开始

pnpm install
pnpm test
pnpm typecheck
pnpm audit --prod   # 发布前依赖审计

# 起 mock-harness（无需真实 DSH 即可联调；手机同 Wi-Fi 联调时加 --host 0.0.0.0）
pnpm --filter mock-harness build
node mock-harness/dist/cli.js --port 3080

# 开发调试用 CLI（启动 relay + 自动桥接本机 DSH + 打印 6 位配对码与二维码）
# DSH API 探测顺序：$env:DSH_API_URL / $env:DSH_WEB_URL → 127.0.0.1:56734 → 127.0.0.1:3080。
pnpm --filter dsh-harness-remote build
node harness-plugin/dist/cli.js remote

# 录制真实 DSH 流量 → conformance fixtures（需要可达的 DSH）
pnpm --filter @dsh-remote/capture build
node tools/capture/dist/cli.js record --host 127.0.0.1 --port 3080 --out ./fixtures

构建

Android APK（GitHub Actions 自动构建，推荐）

• 打 v* tag 推送，或手动运行 Android APK workflow（workflow_dispatch，可指定 Release tag），Linux runner 会执行 expo prebuild --platform android + gradlew assembleRelease，并把 APK 自动上传到 GitHub Release。
• 本地构建也可：cd apps/mobile && npx expo prebuild --platform android 后在 android/ 执行 ./gradlew assembleRelease（注意 Windows + pnpm 深路径已知会失败，见 BLOCKED.md）。

iOS / EAS 云构建（暂未完成）

iOS App 构建暂未完成：需要 Expo 账号与 Apple 开发者账号，当前尚未产出 iOS 安装包。

cd apps/mobile
npx eas-cli build --profile development   # 开发版（development client）
npx eas-cli build --profile preview       # 内部预览
npx eas-cli build --profile production    # 商店版（自动递增 build number）

前置：eas.json 已配置三个 profile；首次运行 npx eas-cli login + npx eas-cli init（写入 extra.eas.projectId）。真机联调步骤见 docs/MANUAL.md。

文档

• 设计文档（v0，已确认）：docs/superpowers/specs/2026-08-16-dsh-remote-mobile-design.md
• docs/ARCHITECTURE.md — 架构与数据流
• docs/PROTOCOL.md — 协议参考（信封/端点/WS/连接生命周期）
• docs/COMPATIBILITY.md — 协议版本矩阵与 fixtures 回归流程
• docs/SECURITY.md — 安全模型（MVP LAN → M2 配对 → M3 中继）
• docs/MANUAL.md — 真机联调清单（M0/M1 手动验收）
• docs/design/UI-SYSTEM-v7.md — App UI 设计系统 v7（双主题 · DeepSeek 品牌 · 官方黑色鲸鱼）
• docs/design/BRAND.md — 品牌与 App 图标（DeepSeek 官方黑色鲸鱼）
• docs/design/RELAY-M3.md — M3 中继设计（控制面协议/E2E 密钥交换/RelayTransport/部署安全/分阶段计划）

里程碑状态

状态：M0–M2 已通过评审；M3 中继（M3.1–M3.4）已实现并全仓回归绿；R1–R5 远程优先窗口已实现并全仓回归绿；P0–P2（真实 DSH rc.7 接缝、一键远程复用、Expo 推送准备、TLS 实测、配对安全加固）已实现并全仓回归绿（protocol 124 / mobile 117 / harness-plugin 37 / relay 39 / mock-harness 29 / capture 24）。Phase B 真机联调已在 Android 真机（Expo Go）验证通过（连接/会话/流式聊天/发消息/审批/提问/goal 暂停/断线重连），通知/后台保活/真机推送/relay 真机回归需 development build 与设备/账号窗口验证（Expo Go SDK 53+ 限制，见 docs/MANUAL.md）。Android APK 由 GitHub Actions 自动构建并上传 Release；电脑端插件 dsh-harness-remote 由 npm 发布（dsh plugin --profile web add dsh-harness-remote -w 安装）；iOS App 构建暂未完成（需 Expo/Apple 开发者账号）。v0.3.0 发布流程见 PROGRESS。

贡献

• 开发流程与协议改动规范见 CONTRIBUTING.md。
• 行为准则见 CODE_OF_CONDUCT.md。
• 安全问题请走 SECURITY.md 的私密披露渠道。

致谢

协议研究与 mock 方法论参考 sorsama/deepseek-harness-mobile，保持协议兼容。