From 83d833ea3c13e165ba70e6413d3fdbd9b6517629 Mon Sep 17 00:00:00 2001 From: QQ Date: Tue, 17 Nov 2026 08:39:22 +0800 Subject: [PATCH] Import docs/design/README.md --- docs/design/README.md | 67 ++++++------------------------------------- 1 file changed, 8 insertions(+), 59 deletions(-) diff --git a/docs/design/README.md b/docs/design/README.md index d95fe85..28cf7b1 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -1,63 +1,12 @@ -# DSH Remote 设计文档 +# 设计文档 -核对日期:2026-10-27;这是设计快照,不代表当前版本已发布或完成新增运行时验收。 - -本目录描述当前产品和实现边界。运行方式见[根 README](../../README.md),线协议以 -[protocol.md](../protocol.md)为准,实现约束见 [AGENTS](../../AGENTS.md),未完成工作见 -[TODO](../TODO.md)。源码中存在的能力不等于已完成跨设备、跨平台或真机验收。 - -## 文档导航 - -| 文档 | 内容 | +| 文档 | 维护范围 | | --- | --- | -| [产品定位](PRODUCT.md) | 用户、产品目标、仓库边界与设计原则 | -| [界面设计系统](DESIGN.md) | 当前 Android 主题、导航、会话工具与交互规则 | -| [Plugin 产品设计](plugin/product-design.md) | Host、Remote 工作区入口、领域与用户路径 | -| [Plugin 功能设计](plugin/functional-design.md) | 生命周期、数据面、allowlist、工具与恢复 | -| [共享基础](shared-foundation.md) | 身份、授权、加密、传输和共享包职责 | -| [协议 Schema 对齐](protocol-schema-alignment.md) | schema、fixtures、版本与验证边界 | -| [CodeX 内存展示投影](codex-session-history-projection-prompt.md) | App Server authority、原生 UI 载体与生命周期 | -| [OpenCode 原生归档](acp-session-archive.md) | 直接调用原生 HTTP API、能力协商、跨连接目录同步及并发边界;不含恢复 | +| [产品定位](PRODUCT.md) | 用户路径、仓库边界和设计原则 | +| [界面设计系统](DESIGN.md) | Android / Desktop 的交互规则;具体 token 以源码为准 | +| [Plugin 功能设计](plugin/functional-design.md) | 生命周期、业务域、路径隔离与恢复 | +| [控制面恢复](control-recovery.md) | 共用授权租约,以及 WebRTC / 独立 Relay 的保留条件 | -[原始需求提示词](../archive/vibe-coding.md)已归档,只用于追溯需求;当前设计不以原始提示词作为实现依据。 +线协议统一维护在 [protocol.md](../protocol.md),账号和凭据维护在 [Host 接入指南](../plugin-integration.md),加密与网络分别见[端到端加密](../end-to-end-encryption.md)和[网络与传输](../network.md)。不在设计目录重复维护同一组协议字段、版本矩阵或测试数量。 -## 当前交付范围 - -- 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 与会话归属 | - -当前兼容范围见[兼容说明](../compatibility.zh.md):开发基线 `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 已验收。 - -## 主路径 - -1. Host 通过账号密码、GitHub/知乎授权或主机匹配码加入账号;实际授权方式取决于 Server 支持。 -2. Client 使用同一账号获得独立身份和设备凭据;Server membership 与 Host 本地 pinned trust 同时成立。 -3. Client 固定 Host identity,经 Noise IK 建立加密业务通道。 -4. 选择可用后端和工作区,再进入会话;既有 Harness 工作区和 CodeX Project 均可在 Remote 入口选择。 -5. 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 仍只注册已有目录。具体边界见[协议](../protocol.md)。 - -## 验证边界 - -已有 Harness / CodeX Desktop、Android 主链路和 WebRTC 互操作验证;后续新增工具、模型选择、AGY 加密跨设备链路、Windows、原生 APK、长连接及复杂 HMR 需按 TODO 单独验收。 -本次文档同步不增加运行时验收记录。 +运行和安装见[文档入口](../README.md);未完成工作统一在 [TODO](../TODO.md),版本变更统一在 [CHANGELOG](../CHANGELOG.md)。临时实施计划、现场验收和发布评审不作为长期设计文档。