jiangchen/DSHWatch_Server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3ea27d747faca442722d40b56e6f849bb3f6b6d5
DSHWatch_Server/docs/DESIGN.md
T

13 KiB
Raw Blame History

DSHWatch 设计与颗粒度对齐报告

版本：v0.1（讨论稿） 目标：让小米手环 10 Pro（VelaOS 快应用）通过手机网关远程管理 DeepSeek Harness；手机端为完整客户端，手表端为阉割版但核心功能可用。

1. 一句话目标

把 DeepSeek Harness 变成"可被远程控制的服务"：DSH 里装一个插件（dsh-watch），插件主动连到一个 Node 中继服务器（DSHWatch_Server），手机 APP（DSHWatchPhone）连同一个服务器；手表（DSHWatch）没有网络只能走蓝牙，由手机 APP 作为网关转发。这样手表和手机都能看状态、选会话、发指令、输入文字、中断任务。

2. 总体架构

             ┌─────────────────────────────┐
             │  DeepSeek Harness（本机）      │
             │  + dsh-watch (插件)    │
             └──────────────┬──────────────┘
                            │  ws/wss 主动外连
                            ▼
             ┌─────────────────────────────┐
             │  DSHWatch_Server (Node)      │
             │  · 鉴权 / 转发 / 在线广播     │
             └───┬─────────────────┬───────┘
                 │  ws/wss          │  ws/wss
    ┌────────────▼────────┐   ┌─────▼──────────────┐
    │  DSHWatchPhone      │   │ 其他客户端(可选)     │
    │  Android APP        │   └────────────────────┘
    └──────────┬─────────┘
               │  BLE / 小米穿戴 SDK (MessageApi)
    ┌──────────▼─────────┐
    │  DSHWatch           │
    │  Vela 手表快应用     │
    └────────────────────┘

关键事实（调研结论）：

  • 手表（VelaOS）与手机之间的数据通道是 system.interconnect（BLE）。它要求手机侧是一个 原生 Android APP，且该 APP 的包名和签名必须与手表 rpk 的一致（参考官方 demo interconnect_image_demo：android_program/ 是原生 Android 工程，src/ 是手表快应用）。
  • 手机快应用（system.bluetooth 等）无法直接充当该互联对端，因此 DSHWatchPhone 采用原生 Android APP（用户已确认）。
  • 麦克风：Vela 提供 system.record 录音 API，但官方"支持明细"表里 小米手环 8 Pro / 9 / 9 Pro / 10 均标为"不支持"，小米手环 10 Pro 未单独列出，按同系列判断大概率也不支持应用级麦克风。→ 手表语音输入先不承诺，作为"真机验证后再说"的可选增强。

3. 四个组成部分

3.1 DSHWatch_Server（Node 中继）

  • 技术：Node + ws。
  • 职责：鉴权（userId + token）、请求/响应转发、事件广播、在线状态维护。
  • 不存会话内容，纯转发。
  • 健康检查：GET /health。
  • 部署：腾讯云/公网，建议 nginx/caddy 挂 TLS（wss://）。

3.2 dsh-watch（DSH 插件）

  • 运行在 Harness 内，apply(ctx, config)。
  • 配置：userId / token / serverUrl / reconnectMs / timeoutMs。
  • 主动外连服务器，注册 userId。
  • 把 DSH apiProxy 的方法透传成远程 RPC：
    • harness.status、harness.prompt
    • session.*（list/create/history/prompt/cancel/rename/fork/models/selectModel/attachment）
    • goal.、subagent.、workspace.、host.
    • skill.list、agentPreset.、llm.、settings.、credentials.
  • 推送事件：session/event、session/projection、status 快照。

3.3 DSHWatch（Vela 手表快应用）

  • 只能 BLE，因此不直接连服务器；通过 system.interconnect 与手机 APP 通信，手机 APP 代它与服务器交互。
  • 页面结构（按用户要求）：
    • 主页（中间）：DeepSeek 吉祥物大图 + 状态提示。
    • 左页：进入具体会话（会话列表 / 历史摘要）。
    • 右页：设置（服务器地址、userId、token、连接状态、余额显示预留等）。
    • 左右滑动 3 页；底部指示器：当前页为长条，其他为小点。
    • 支持唤出键盘输入、快捷指令、中断。

3.4 DSHWatchPhone（Android APP）

  • 技术：Android 原生 + 小米穿戴 SDK（Wearable / MessageApi / AuthApi / NodeApi / NotifyApi）+ WebSocket（okhttp-ws）联服务器。
  • 职责：
    1. 作为手表 BLE 互联对端（接收/发送 connect.send 数据）。
    2. 作为服务器客户端（userId + token），显示完整 DSH 状态、会话、命令流。
    3. 双向转发：服务器 ↔ 手表。
  • UI 相对自由，规划见 §6。

4. 通信协议设计

4.1 手表 ↔ 手机（BLE/interconnect）

手表通过 @system.interconnect 的 connect.send({ data }) 发给手机；手机通过小米穿戴 SDK MessageApi.sendMessage(nodeId, byte[]) 发给手表。数据用 JSON 文本 + base64 分片（参考官方 demo 的分片协议）。

定义消息信封（手表→手机 / 手机→手表）：

  • 方向：to = "watch" | "phone"
  • type：hello / status / event / command / text / ack / cancel / settings / heartbeat
  • seq：序号（手表端简单递增）
  • payload：具体负载，可含 sessionId、content、text、settings 等。

示例：

{ "to":"phone", "type":"command", "seq":3, "payload":{ "sessionId":null, "kind":"prompt", "content":"帮我看看今天的任务" } }

4.2 手机 ↔ 服务器（WebSocket）

  • 握手：{ "type":"hello", "role":"client", "userId":"...", "token":"..." }
  • 请求：{ "type":"request", "requestId":"...", "method":"session.prompt", "params":{...} }
  • 响应：{ "type":"response", "requestId":"...", "ok":true, "result":{...} }
  • 事件推送：{ "type":"event", "event":{ "type":"session/event", "sessionId":"...", "event":{...} } }
  • 状态推送：{ "type":"status", "status":{...} }
  • 心跳：{ "type":"ping" } / { "type":"pong" }

4.3 DSH 插件 ↔ 服务器（WebSocket）

  • 握手：{ "type":"hello", "role":"dsh", "userId":"...", "token":"..." }
  • 服务器转发客户端 request 给插件；插件回 response。
  • 插件主动推 event / status。

5. 手表端 UI 与交互细则

5.1 首页切换（对齐用户需求）

  • 三页：左（会话）— 中（主页/吉祥物）— 右（设置）。
  • 左右滑动切换（用 Vela swiper 组件或手动 swipe 手势 + translate）。
  • 底部指示器：
    • 当前页：长条（圆角矩形，宽约 20px）。
    • 非当前页：小圆点（约 6px，半透明）。
    • 居中对齐，位于页面下方。

技术落地：Vela 提供原生 swiper（container/swiper），支持 index / loop / previousmargin / nextmargin / change 事件 / swipeTo 方法。内置 indicator 只有统一圆点，做不成"当前页长条"，所以把 indicator=false，自己在 swiper 下方用 3 个条目渲染指示条，靠 change 事件驱动高亮。详见 docs/WATCH_UI.md。

5.2 主页（中间页）

  • 中心：DeepSeek 吉祥物大图（复用 dsh-whale-widget 的 DSniang1.png，蓝色 maid 妹；低分辨率屏幕用压缩版）。
  • 吉祥物下方：当前状态一行字：
    • 在线 / 离线 / 思考中 / 执行中 / 等待批准。
  • 顶部：小字显示"当前会话 id 前 6 位 + 标题"。
  • 点击吉祥物：进入"详情"（分骨架：状态卡片 / 最近事件 / 快捷操作）。

5.3 左页（会话）

  • 会话列表（最近 N 条，后台 session.list）。
  • 每行：会话标题（或 id 前几位）、是否 running、最近活动时间。
  • 点击某行：设为当前会话，并跳到主页。

5.4 右页（设置）

  • 服务器地址（input）。
  • userId（input）。
  • token（input，可显示/隐藏）。
  • 连接状态（已连接/重连中/离线）。
  • 手环与手机连接状态（getReadyState / 轮询）。
  • 余额显示预留（暂不实现，用户稍后定）。
  • 主题/动效开关。

5.5 输入与指令

  • 键盘：唤起 watch 键盘（参考 Vela 输入法组件 /pages/keyboard），支持中英文。
  • 快捷指令：预设几条常用命令（如"查看今日任务"、"总结当前进度"、"停止"）。
  • 语音：预留，但默认关闭（system.record 大概率不支持）。

5.6 动效

  • 状态变化时吉祥物切换：DSniang02.png（带气泡）作"思考"态，rua.gif 作交互彩蛋。
  • 列表更新时用 tid 避免闪烁（官方 FAQ 建议）。

6. 手机端 UI（相对自由，规划版）

首页：

  • 顶部：连接状态徽标（服务器 / Harness / 手表）。
  • 中部：当前会话卡片 + 吉祥物缩略图 + 最近事件流。
  • 底部：输入框 + 发送 + 快捷指令 + 取消。

二层：

  • 会话列表页（搜索、归档、新建）。
  • 设置页（服务器地址、userId、token、主题、通知开关）。
  • 事件/日志页（session/event 原始流，便于调试）。

交互：

  • 与手表操作 1:1 联动，手机可作为完整控制台。
  • 支持会话选择、模型切换（session.models / session.selectModel）、Goal 管理（goal.）、子代理（subagent.）。

7. 功能矩阵（手表 W / 手机 P）

功能 手表 手机 说明
连接状态 W P 服务器 + 手表连接
查看当前 session W P 列表/摘要
选择会话 W P
发送文本指令 W P 手表用键盘/快捷键
中断/取消 W P session.cancel
查看会话历史 W(简) P
查看余额/用量 预留 预留 稍后定
Goal 管理 快捷 P
子代理管理 不 P
模型切换 不 P
通知 W(提醒) P 手机推送 + 手表震动
语音输入 可能不可用 可选 system.record 风险

8. 颗粒度 / 里程碑

对齐"先搞定哪一层"：建议按 P0→P3 推进，每层都有可验收的标准。

P0：链路打通（最小闭环）

  • DSHWatch_Server 可启动，/health 正常。
  • dsh-watch 装入 DSH，配置 userId/token/serverUrl 后连上服务器。
  • Android APP 能连服务器、发一条 session.list / harness.status，收到响应 & 状态推送。
  • 验收：手机看到 Harness 在线状态和当前会话，能发送一条命令并看到返回。

P1：手表侧 UI + 网关

  • DSHWatch 三页滑动 + 底部指示器 + 主页吉祥物。
  • 手表通过 interconnect 与手机 APP 打通（需包名/签名一致，使用配套证书）。
  • 手机 APP 把服务器状态/事件转发给手表；手表显示在线/思考/执行状态。
  • 手表快捷指令能发出命令，手机转发到服务器，结果回显。
  • 验收：手表能看状态、选会话、发预设指令。

P2：完整输入 & 设置

  • 手表键盘输入文本指令。
  • 手表设置页（server/userId/token/连接状态）。
  • 手机端会话列表、事件流、取消、模型/Goal。
  • 验收：手表可手动输入任意指令；手机端体验完整。

P3：增强

  • 余额/用量展示（用户稍后定方案）。
  • 通知/震动、主题、动效、语音（真机验证后）。
  • 验收：设备侧体验接近"1:1 串流"。

9. 资源复用（来自 dsh-whale-widget）

插件目录：D:\project\dsh-whale-widget\assets

文件 尺寸 建议用途
DSniang1.png 610x610 主页主吉祥物（压缩后放入手表）
DSniang02.png 1026x1026 "思考/等待"气泡态
rua.gif 128x128 交互彩蛋/摸头
DSH2.png 2048x1024 手机端/卡片背景（可裁剪）

占位：手表端用图需压缩到合适尺寸（如 240x240 或 320x320，PNG/带透明）。可写一个脚本用 sharp 从原图生成，或者手选。

10. 技术风险 & 待定项

  1. 麦克风：system.record 对小米手环 10 / 10 Pro 大概率不支持 → 语音输入默认关闭，真机验证后再决定。
  2. 包名/签名：手表 rpk 与手机 APP 必须一致，且用同一套证书；官方文档明确"签名不正确会被拒绝通信"。需要先确定一个包名（如 com.dshwatch.app）。
  3. SDK 依赖：手机侧需要用小米穿戴 SDK（XMS Wearable），来自官方 demo 的 android_program/libs。需要先从官方 demo 下载拿 jar/aar。
  4. 公网部署：建议 TLS + 长短 token；不要把 token 写进 git。
  5. Vela 组件能力：swiper、system.record、system.file 等是否都满足，需在真机确认。
  6. 余额显示：用户说可能改，先预留，不做死。

11. 已搭骨架（代码暂停，待颗粒度对齐后继续完善）

  • DSHWatch_Server/server.js：中继 Broker（可跑，已语法检查）。
  • DSHWatch_Server/plugin/：dsh-watch 插件骨架。
  • 后续：Android 工程（DSHWatchPhone 改为原生 Android）、Vela 手表 UI、桌面 profile 插件挂载。

12. 待确认问题

  1. 手表端"分骨架"具体指什么？是状态卡片/功能骨架，还是"分包/子代理"列表？→ 需要用户明确（默认理解为状态 + 最近事件 + 快捷操作）。
  2. 包名用 com.dshwatch.app 可以吗？（决定后统一改）。
  3. 余额显示方案（等用户稍后给）。
  4. 是否要手环本地缓存（离线也能看最近状态）？
Reference in New Issue View Git Blame Copy Permalink