5.2 KiB
5.2 KiB
DSH Remote 设计文档
核对日期:2026-10-27;这是设计快照,不代表当前版本已发布或完成新增运行时验收。
本目录描述当前产品和实现边界。运行方式见根 README,线协议以 protocol.md为准,实现约束见 AGENTS,未完成工作见 TODO。源码中存在的能力不等于已完成跨设备、跨平台或真机验收。
文档导航
| 文档 | 内容 |
|---|---|
| 产品定位 | 用户、产品目标、仓库边界与设计原则 |
| 界面设计系统 | 当前 Android 主题、导航、会话工具与交互规则 |
| Plugin 产品设计 | Host、Remote 工作区入口、领域与用户路径 |
| Plugin 功能设计 | 生命周期、数据面、allowlist、工具与恢复 |
| 共享基础 | 身份、授权、加密、传输和共享包职责 |
| 协议 Schema 对齐 | schema、fixtures、版本与验证边界 |
| CodeX 内存展示投影 | App Server authority、原生 UI 载体与生命周期 |
| OpenCode 原生归档 | 直接调用原生 HTTP API、能力协商、跨连接目录同步及并发边界;不含恢复 |
原始需求提示词已归档,只用于追溯需求;当前设计不以原始提示词作为实现依据。
当前交付范围
- Plugin:常驻 Host 与本地 Remote 工作区入口同时存在,不提供用户可见的 Client 模式。
- Desktop / 连接本机 Harness 的浏览器:复用官方 Harness UI,提供远程 Header、Files、Terminal 和受限开发服务预览。
- Android:账号授权、Host / Workspace / Session / Chat、图片 Prompt、历史恢复、工作区快捷入口,以及按后端能力接入的会话工具。
- VS Code:账号授权、Host 信任固定、Harness 工作区/会话导航、Prompt 与基础审批;实时更新和恢复仍有待办。
- Browser 扩展:只换取独立设备凭据、显示在线 Host、打开同源 Remote Web。
apps/server:可自部署的单账号、文件持久化 Server,支持可配置的 WebRTC LAN/P2P/TURN 与加密 Relay,提供登录与设备状态页和 Docker 部署入口。- 完整多账号 Server、Remote Web 会话 UI、Admin 及其数据库、队列和部署基础设施由独立仓库实现。
数据面与领域
| 领域 | Host 接入 | Client 展示 | 边界 |
|---|---|---|---|
| Harness | 官方 Typert Remote Gateway(rc.2 ApiProxy 已移除) | Desktop 原生 UI、Android / VS Code Client | 原生会话契约,固定 endpoint allowlist |
| CodeX | stdio App Server,codex.app.* |
Desktop 内存载体、Android 内存投影 | 不写 DSH 存储;Project / Thread authority |
| Cursor / AGY / Pi / OpenCode / Claude | ACP gateway,agent.acp.* |
浏览器可用的 Desktop 内存载体、Android 投影 | 独立后端 capability、工作区 ID 与会话归属 |
当前兼容范围见兼容说明:开发基线 0.2.1-rc.1,保留 0.2.0-rc.2 / rc.1,并接纳后续 0.2.2 RC 版本。Host / Android legacy ApiProxy 实现已移除。Client 按加密 capability 与 workspaceTypes.available 判断协议支持及实际就绪;未来版本范围接纳不代表 runtime 已验收。
主路径
- Host 通过账号密码、GitHub/知乎授权或主机匹配码加入账号;实际授权方式取决于 Server 支持。
- Client 使用同一账号获得独立身份和设备凭据;Server membership 与 Host 本地 pinned trust 同时成立。
- Client 固定 Host identity,经 Noise IK 建立加密业务通道。
- 选择可用后端和工作区,再进入会话;既有 Harness 工作区和 CodeX Project 均可在 Remote 入口选择。
- Prompt、stream、审批和会话工具进入对应领域的固定 allowlist;退出或断线清理旧句柄,恢复时重新读取历史。
访问与配置
- 文件树和预览只读;Harness 使用官方
workspaceFiles/officeToPdf或 dsh-file-viewer provider,CodeX / ACP 使用 Host 验证过的会话根和受限工具载体。 - 原生终端默认开启,可在 Host 本地关闭;按设备固定归属、按连接校验输入权,断线不重放输入。
loopback.ports默认空;仅允许 Host 出站访问127.0.0.1的明确白名单端口。Desktop 的预览代理只监听本机。- Remote 不得修改插件自身终端、loopback 或后端访问设置。后端开关热更新对应进程和 capability,ACP 初始化不阻塞 Harness Remote。
- AGY 图片缓存仅写专用私有 tmp;独立
workspace.upload.v1允许向 Host 验证的当前会话工作区根上传文件,不接受 Client 自报路径。官方workspace/create可创建缺失的 Harness 工作区目录;CodeX Project 仍只注册已有目录。具体边界见协议。
验证边界
已有 Harness / CodeX Desktop、Android 主链路和 WebRTC 互操作验证;后续新增工具、模型选择、AGY 加密跨设备链路、Windows、原生 APK、长连接及复杂 HMR 需按 TODO 单独验收。 本次文档同步不增加运行时验收记录。