ds-harness-remote-fast/docs/design/DESIGN.md

181 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# DSH Remote 界面设计系统
更新时间:2026-10-30;以下描述当前源码与交互规则,不代表真机可访问性验收。
## 1. 设计来源
Android token 以 [theme.ts](../../apps/android/src/ui/theme.ts)为准,主题切换由
[theme-context.tsx](../../apps/android/src/ui/theme-context.tsx)管理,导航以 [App.tsx](../../apps/android/App.tsx)为准。
Desktop 复用 Harness 官方 Workspace / Session / Conversation UI;Remote 只增加账号、Host/工作区选择、设置和 Header。
CodeX / ACP 在内存中投影到同一原生 UI,不增加独立会话页面或持久化展示数据库。
## 2. 主题与颜色
Android 支持跟随系统、浅色与深色主题;当前 token 是源码中的 sRGB/RGBA 值,不使用早期 OKLCH moss 方案。
2026-10-30 调整全局色彩系统,对齐高可读性与精简卡片规范:主要文字与图标统一为纯深墨色 `#0F0F0F`、页面画布 `#F8F8F8`、分组卡片 `#FFFFFF`、分组标题与次级说明 `#59606D`、右侧箭头 `#B9B9BB`、细线分隔线 `#EDEDED`,悬浮主操作按钮采用 DeepSeek 蓝调柔和微光投影 `brandGlowShadow`。
| 角色 | 浅色 | 深色 | 用途 |
| --- | --- | --- | --- |
| background | `#F8F8F8` | `#0B0D11` | 页面画布 |
| surface | `#FFFFFF` | `#161A21` | 不透明浮层与输入框 |
| card | `#FFFFFF` | `rgba(255, 255, 255, 0.05)` | 卡片背景 |
| cardOpaque | `#FFFFFF` | `#17191D` | 卡片与画布合成色,用于遮住滑动删除底层 |
| grouped | `#FFFFFF` | `rgba(255, 255, 255, 0.05)` | 设置式分组列表 |
| elevated | `#FFFFFF` | `#1D222B` | 浮动标题栏按钮 |
| surfaceStrong | `#ECEFF4` | `#232832` | 胶囊、按下态 |
| ink | `#0F0F0F` | `#F2F4F7` | 主要文字、图标 |
| muted | `#59606D` | `#A2A9B6` | 分组标题、次级说明文字 |
| subtle | `#B9B9BB` | `#7A8291` | 右侧箭头、次级占位 |
| primary / accent | `#4D6BFE` | `#6F89FF` | 主要操作与选中态 |
| inverse / onInverse | `#0F0F0F` / `#FFFFFF` | `#F2F4F7` / `#0B0D11` | 浮动主操作(如侧栏「新建对话」胶囊) |
| success | `#1E8449` | `#4CC07D` | 成功 / 在线状态 |
| warning | `#95600A` | `#E0A53A` | 需注意状态 |
| danger | `#C2362F` | `#F2736C` | 错误与危险操作 |
| border | `#EDEDED` | `#2B313C` | 边框与卡片内分隔线 |
| separator | `#EDEDED` | `#252B35` | 卡片内分隔线 |
完整 pressed/soft/disabled/separator/scrim 等值引用源码,不在各组件复制新色表。
状态同时提供文字或图标,不单靠颜色区分在线、重连、权限或选中项。
## 3. 字体与尺寸
Android 使用系统字体,代码与文本预览使用等宽字体;字体随系统缩放。
| token | 字号 / 行高 | 字重 |
| --- | --- | --- |
| hero | 32 / 38 | 700 |
| title | 24 / 30 | 700 |
| heading | 18 / 24 | 600 |
| body | 16 / 24 | 400 |
| bodyStrong | 16 / 22 | 600 |
| small | 14 / 20 | 400 |
| smallStrong | 14 / 20 | 600 |
| caption | 12 / 16 | 500 |
spacing:4、8、12、16、20、24、32、40 dp;radius:8、12、16、22(分组/卡片)、28(输入栏/底部弹层)dp 和 pill。
标题栏标题统一 17 / 700;分组标签 15 常规 muted;列表行标签 16;说明文字 13。
共享组件([components.tsx](../../apps/android/src/ui/components.tsx)):TopBar 不再绘制顶栏底色与分割线,
返回键与右侧操作分别放入带轻阴影的圆形 / 胶囊浮动按钮;`IconButton filled` 为蓝色主操作圆钮;
`GroupCard` / `GroupRow` 提供设置式分组列表(线性图标、标签、值、开关或箭头,分割线与文字对齐);
`FilterChip` 为选中浮起的筛选胶囊;`Button` 统一为胶囊形,新增 `inverse` 黑色变体。
新增自定义平滑 `Toggle` 开关组件([toggle.tsx](../../apps/android/src/ui/toggle.tsx)),全量替代原生/旧版 `Switch` 控件。
多设备与多后端在界面上显式呈现:首页显示「N 台 · M 台在线」与按平台区分的设备图标,最近访问带设备标签;
工作区页始终显示后端胶囊(DSH / CodeX / Claude 等);列表全面采用扁平设计:首页设备卡与最近访问为半透明白色卡片搭配线性图标,工作区页为平铺文件夹列表(chevron、文件夹、名称、计数)。
页面和控件使用共享 token;操作区域保持足够触达空间,图标按钮提供可访问名称。
具体点击区域、长标题、大字体和窄屏效果应以组件及实际设备检查为准。
屏幕旋转:Android 不锁定方向,跟随系统旋转设置;同一导航/连接状态在横竖屏复用。
聊天消息与输入栏在宽窗口中使用居中的可读列(最大 760 dp);底部弹层与工作区对话框的最大高度
按当前窗口计算(窗口高度低于 520 dp 时约占 92%),内容超出时在层内滚动;横屏或短窗口中压缩
输入栏与隐私提示,并在旋转后重新同步 IME inset,避免用旧方向的键盘坐标计算底部留白。
这些规则由 `apps/android/src/ui/responsive.ts` 与各面板共同实现,不代表已完成大字体、TalkBack
或分屏窗口的真机验收。
## 4. Android 导航
主机会话侧边栏:顶部为 24dp 主机名大标题(点击回到工作区),右侧为刷新与返回两个浮动圆钮,点击遮罩或系统返回键仅收起侧边栏。其下为「工作区 / 插件 / 自动化任务」带线性图标的 17dp 导航行,以及多后端时的筛选胶囊(选中项为白色浮起胶囊)。「工作区」分组标签使用 15dp muted 常规字重,保留搜索、视图选项与添加工作区图标。“最近访问”汇总最近使用且未归档的对话(含运行中对话),运行状态以绿色圆点显示;下方工作区保持目录顺序。工作区行 15dp 加粗、对话行 16dp 正文,最小 44–46dp 高度、圆角 16dp;对话相对工作区缩进,不绘制树状连线或行分割线。选中对话使用 surfaceStrong 灰底与加粗标题。「新建对话」为右下角浮动的 inverse 黑色胶囊(深色主题下为白色),列表底部预留空间避免遮挡。
侧栏展开/折叠状态按主机和分组保存在手机,重新打开或重启应用后恢复;恢复完成前显示加载状态,避免先展开再收起。工作区无折叠记录时默认收起,当前会话不会触发自动展开;搜索可临时展开匹配结果,不覆盖折叠记忆。该偏好独立于主机工作区页。
完成 bootstrap 后,优先处理会话链接及用户开启的上次会话恢复;否则仅在账号下恰好一台设备且已信任、在线时自动进入其工作区。其他情况进入设备列表;未配置时先进入 Server 设置/账号授权。返回设备列表不会重复触发本次启动的自动跳转。
登录页提供「扫码登录」点击入口:初始不请求 provider、不生成二维码,点击入口后才加载并在页内展示二维码,
手机扫码授权后自动注册本设备;手机、平板和大屏都保留知乎/GitHub 浏览器 OAuth 与邮箱密码登录,大屏使用
更大的二维码。二维码只编码 Server 返回的同源 `scanUrl`,不包含账号 token;修改服务地址会作废旧二维码,
离开扫码页停止轮询。
平板聊天在宽度 ≥760 dp 且(高度 ≥520 dp 或宽度 ≥1000 dp)时采用双栏:左侧常驻主机会话列表,右侧显示
会话头部、消息与输入栏;在左栏切换会话只更新右侧内容,左栏头部的返回按钮回到工作区。双栏时右侧
会话头部不再显示返回箭头,轨迹视图通过右侧操作图标关闭。窄屏与短窗口仍为手机单栏,会话列表继续
以 Modal 抽屉打开。
连接进度页在主机名下以居中的单行 `DSH 版本号 | Plugin 版本号` 展示设备目录报告的版本,缺失时明确显示版本不可用。
工作区页标题只显示带下划线、整段可点击的主机名,点击进入主机信息;右上角只保留新建工作区入口。
网络路径与详细诊断在已连接主机的信息页直接展开,并复用于对话信息面板。
首页及单操作标题栏两侧保留对称空间,标题按屏幕居中;返回、更多和新建图标不加外层按钮背景、边框或阴影。
主机信息页在主机名后提供编辑图标用于重命名,右侧展示系统类型,同一行不重复展示网络类型;设备信息分别列出 DSH 和 Remote 插件版本。
主机列表以纯文字显示在线/离线状态,不使用圆点或胶囊底色;重命名入口仅保留在主机信息页。
信息行的标签按文字宽度占位、最多占行宽的 40%,右侧内容使用剩余空间,避免短标签造成不必要的换行。
主路径:设备列表 → 信任/连接 → 工作区内的会话列表 → Chat。
设备详情、连接详情、设置和关于页面属于辅助路径,不使用早期匿名 Pair device 配对流程。
收藏/最近工作区快捷入口先连接所属 Host,再打开该工作区最近会话;没有会话时定位工作区。
工作区作为连接后的首页,返回设备列表;Chat 返回对应工作区/会话路径。
返回设备列表保留当前连接。Android 不提供独立「对话」菜单或跨工作区平铺的会话列表页;会话统一从所属设备的工作区进入。
语言支持跟随系统、英文、简体中文、日语、繁体中文、西语、德语、法语;默认显示跟随系统、简体中文、English,点击「More ...」展开全部语言,已选择新增语言时保持展开。主题支持跟随系统、浅色、深色。
设置页按语言、外观、工作区设置、默认权限、连接与设备信息排列,语言始终为首组。全面使用 GroupCard 分组卡片与 GroupRow 行,偏好开关统一使用 Toggle 组件,外观支持浅色/深色/跟随系统的实时预览瓦片,底部提供红色的退出登录与重置本地数据高危操作行。设备名称放在底部身份信息中。说明紧邻对应选项,删除重复解释,保留生效时机、Host 支持条件及权限边界。
设置页提供默认关闭的全局「会话精简模式」开关,复用现有偏好列表与 Toggle;保存后下次打开会话生效。支持的 Host 缩减历史工具详情,正文与工具状态保留;关闭后重新打开加载完整历史,旧 Host 保持原有行为。
重连保留支持恢复的工作区/会话选择,换 Host 时丢弃其他 Host 的内存领域状态。
## 5. 会话与输入
会话标题保持单行,点击打开对话信息面板:完整标题、所属工作区、主机、工作区类型、完整目录与对话数,以及当前连接方式、加密与网络详情。点击工作区回到当前主机工作区页并定位该工作区;未分组时回到主机工作区列表。断线时不展示旧网络数据为当前连接。当前标题栏提供轨迹切换、新会话,离线时增加重连动作;标题栏不直接列出 Files/Terminal。
正文使用会话列表或轨迹视图,历史分页与实时帧保持顺序;模型和思考程度仅显示后端报告的选项。
输入栏 `+` 提供附件与工具访问入口;「快捷提示词」在 `+` 旁单独展示,打开后可选择发送、管理和编辑。
Files / Terminal 从「工具访问」选择;轨迹同时有标题栏入口。`/` 命令和 `@` 上下文菜单沿用 Host 支持的语义。
文字/图片发送根据当前后端与 capability 限制;Cursor 仅文字,AGY 图片必须遵守其大小、数量和缓存提示。
未知模型显示沿用 Host 设置;AGY 选择模型/effort 待 Host 确认,历史回复不因后续切换而改标。
会话离线显示文字状态和恢复动作,禁止向无输入权终端或无效会话继续提交操作。
断线期间输入框仍可编辑:草稿按会话加密保存在本机,切后台与重连都不会清空;发送与需要连接的动作仍保持禁用,恢复连接后只由用户手动发送。
Agent 单次审批、会话权限策略选择、终端输入权是不同交互,不能混为一个开关。
## 6. Files 与 Terminal
当前工具按 Harness / CodeX / ACP 的会话 scope 和 capability 接入;CodeX 工具不再属于禁止项。
不支持某 endpoint 的 Host/后端显示明确错误,不将工具操作转到另一后端。
Files:目录优先、显示当前路径,刷新与层级返回位于面板 Header;文本等宽、可选择、分页只读。
图片适应容器,PDF/Office 使用本地 PDF.js 预览;取消、超限、转换超时和文件版本变化均应有可恢复状态。
PDF 不开放脚本、外链、导出或明文缓存;文本选择和 TalkBack 体验仍待验收。
Terminal:使用本地打包的 xterm WebView,打开面板只列出现有终端;标题栏「+」才创建新终端。
区分连接、已退出、缺少输入权和 Host 已关闭功能;输入/调整尺寸受连接输入权约束,关闭有确认。
断线不重放输入。终端保持独立深色画布、可访问名称、screen-reader 模式与键盘/特殊按键入口。
工具面板使用共享安全区、键盘 inset 和模态层;IME、硬件键盘、长输出、TalkBack、大字体和真实文件预览另行真机验证。
## 7. Desktop Remote 入口与设置
侧栏底部插件入口保持纵向排列,Remote 位于 DS Bot 等已有插件入口下方、「更多」上方。展开侧栏时 Remote 使用 36px 高的整行图标与文字按钮,长 Host 名称省略;折叠侧栏时使用 36px 图标按钮。悬停显示 Remote 或当前 Host 名称与退出提示,已连接时点击返回本地工作区,两种宽度均保留键盘焦点。DS Bot 团队模式保留账户头像与「连接插件」的原有同一行布局,Remote 独立占据其下方一行,不把 Bot 的内部操作拆成多行。
Remote 模态框展示账号授权、Host、后端分组、实际就绪状态和已有工作区;添加目录入口按领域 authority 限制。
Header 显示远端 Host、传输路径、加密说明、退出和「预览服务」。本机 preview URL 不作为 Android / Remote Web 地址。
详细 Remote 设置中,终端开关切换即保存;端口输入右侧「保存访问设置」只提交 loopback 白名单。
Agent 后端统一列表展示 CodeX / Cursor / AGY,命令可发现不等于已登录或就绪;检测失败关闭后端,检测恢复后由用户开启。
配置保存热更新对应后端,不需要重启整个 DSH。访问设置仅 Host 本地可编辑。
## 8. 状态、文案与验证
状态变化显示文字和具体恢复动作;错误不以 undefined 或内部异常作为主要文案。
图标按钮提供名称、selected/disabled/expanded 状态与必要的辅助提示;无障碍结果以实际检查为准。
动效令牌集中在 `apps/android/src/ui/motion.ts`:手机端全屏 480ms、Sheet 380ms(退出 260ms)、指示器 420ms、同屏微位移 160ms,展开/收起统一 `cubic-bezier(.32,.72,0,1)`,交错 25ms;只补间 `transform` 与 `opacity`,不补间 `width/height/top/margin`。
界面文案、布局和样式不单独增加自动化测试。类型检查、必要人工烟测和真实设备验证承担展示质量检查;
终端输入权、事件顺序、权限与恢复等核心边界由契约测试保护。未完成验收见[TODO](../TODO.md)。
移动端不再持久化对话正文预览,也不提供清理历史缓存入口。草稿、收藏、阅读位置与最近访问仍加密保存,旧版正文预览在恢复本机状态时移除。
### Android Bot 模式(2026-10-22)
主机工作区标题栏「+」左侧为 Bot 入口,Bot 模式右上角三点菜单左侧为工作区切换图标,首页三点按钮复用首页操作菜单(设备、设置、关于、检查更新),新建 Bot / 群聊通过对应分区旁的「+」进入。标题居中,主机标题点击打开设备信息,不承担模式切换。Bot 模式使用独立的原生
团队页和对话页:主 Bot 使用紧凑横排、48dp 原版角色头像和小星标,略大于团队成员,不展示常驻就绪状态,团队使用紧凑无边框列表且不重复主 Bot;群聊使用成员头像组合,支持 Bot/群聊创建和管理。原版 v0.2.0 角色路径、配色与默认外观算法在 Android 本地渲染,第三方许可与 NOTICE 随素材保留。对话保留官方
Harness 历史、流式内容与审批,DS Bot 问答/交互卡片用原生控件展示,通过固定 Bot 接口提交。
模式切换仅影响本机导航,按服务器、账号、主机及固定身份记住 Agent/Bot 选择,再次进入主机或重启 App 后恢复;主机未启用 ds-bot 或 Remote 缺少能力时展示错误,不显示本地或
其他主机数据。记忆、连接器等 Host 本地管理边界不变。源码实现不等于真机/跨设备验收。
Bot 控件统一复用 App Button/IconButton、ModalSurface 与 theme token:主提交用 primary,拒绝用 secondary、取消与历史加载用 quiet;危险操作使用分隔后的红色图标行。BotChoice 统一模型、成员、问答和卡片的单/多选样式与 checked/disabled 语义;弹层统一标题、关闭入口和内容间距。样式随浅色/深色主题切换。
### DS Bot 0.2.1 cards (2026-10-24)
Android 私聊输入框提示 `/btw`;旁问以独立卡片显示问题、答案、时间与运行状态,取消仅作用于旁问。
群聊达到接力上限时显示原因及「继续群聊」。图表使用原生 SVG 并提供数据表;计算卡片在本地解释
受限公式,数值输入有步进和范围提示,滑块支持无障碍增减。HTML 显示摘要与主机打开提示。
保留现有主题、原生卡片与操作按钮;不把旁问写入 Harness 历史。真机交互与 TalkBack 待验收。