diff --git a/docs/design/DESIGN.md b/docs/design/DESIGN.md index cc6034a..b274c07 100644 --- a/docs/design/DESIGN.md +++ b/docs/design/DESIGN.md @@ -1,180 +1,56 @@ -# DSH Remote 界面设计系统 +# 界面设计系统 -更新时间:2026-10-30;以下描述当前源码与交互规则,不代表真机可访问性验收。 +本文维护交互原则和组件归属。具体颜色、字号、间距、时长及响应式阈值以源码为准,不在文档复制一份容易失配的 token 表。 -## 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,不增加独立会话页面或持久化展示数据库。 +- Android:[theme.ts](../../apps/android/src/ui/theme.ts)、[theme-context.tsx](../../apps/android/src/ui/theme-context.tsx)、[components.tsx](../../apps/android/src/ui/components.tsx)。 +- 动效与弹层:[motion.ts](../../apps/android/src/ui/motion.ts)、[sheet.tsx](../../apps/android/src/ui/sheet.tsx)。系统减少动态效果设置必须有降级。 +- 窗口适配:[responsive.ts](../../apps/android/src/ui/responsive.ts);导航入口为 [App.tsx](../../apps/android/App.tsx)。 +- 官方菜单图标的来源与许可见[图标说明](../official-menu-icons.md)。 +- Desktop 复用 Harness 原生 Workspace / Session / Conversation UI;Remote 负责账号、Host、工作区选择、设置及远程状态。CodeX / ACP 使用内存投影,不另建持久化会话界面。 -## 2. 主题与颜色 +## 主题与可访问性 -Android 支持跟随系统、浅色与深色主题;当前 token 是源码中的 sRGB/RGBA 值,不使用早期 OKLCH moss 方案。 -2026-10-30 调整全局色彩系统,对齐高可读性与精简卡片规范:主要文字与图标统一为纯深墨色 `#0F0F0F`、页面画布 `#F8F8F8`、分组卡片 `#FFFFFF`、分组标题与次级说明 `#59606D`、右侧箭头 `#B9B9BB`、细线分隔线 `#EDEDED`,悬浮主操作按钮采用 DeepSeek 蓝调柔和微光投影 `brandGlowShadow`。 +支持系统、浅色和深色主题,组件使用共享 token。文字、图标、选中状态和错误应保持可辨认,不只靠颜色传递状态。 -| 角色 | 浅色 | 深色 | 用途 | -| --- | --- | --- | --- | -| 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` | 卡片内分隔线 | +系统字体缩放、按钮名称、焦点反馈、selected/disabled/expanded 语义及键盘适配由共享组件承载。代码与文本预览使用等宽字体。TalkBack、大字体、短窗口和原生设备效果需要目标平台检查,不能将源码中的属性视作无障碍认证。 -完整 pressed/soft/disabled/separator/scrim 等值引用源码,不在各组件复制新色表。 -状态同时提供文字或图标,不单靠颜色区分在线、重连、权限或选中项。 +## 导航与状态 -## 3. 字体与尺寸 +主路径为账号/Server → 设备 → 工作区及会话 → 聊天。会话抽屉按后端、工作区和当前 Host 展示目录,提供搜索、收藏/最近访问与创建入口。折叠、草稿、阅读位置和最近访问按既有加密存储 scope 保存;跨 Host 不复用会话 authority。 -Android 使用系统字体,代码与文本预览使用等宽字体;字体随系统缩放。 +Agent / Bot 切换是本机导航偏好,不修改 Host 界面模式。重连不能将不可用后端替换为另一个后端,或把 Remote 请求回落到 Local 数据。设备信息与会话信息显示实际版本、连接、加密与目录;断线时不把旧网络数据显示为当前状态。 -| 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 | +Chat 的全屏输入、Sheet、抽屉和图片查看沿用统一动效。关闭 Sheet 播完退出动画再卸载,避免内容跳变;减少动态效果时压低时长并取消位移/缩放。 -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;操作区域保持足够触达空间,图标按钮提供可访问名称。 -具体点击区域、长标题、大字体和窄屏效果应以组件及实际设备检查为准。 +- 历史、流式正文、分析和工具活动保持所属后端的顺序与失败状态;pending 问答/审批不藏在已折叠的活动中。 +- 手动向上滚动停止跟随;回到最新消息恢复跟随。程序滚动不能误判为用户阅读意图。 +- `+` 提供附件与工具访问,快捷提示词独立展示,轨迹有标题栏入口。实际入口以当前后端 capability 为准。 +- Agent 离线仍可编辑草稿,发送保持禁用;断线不能清空或自动发送草稿。Bot 草稿目前是组件内存状态,不承诺落盘恢复。 +- 模型、effort 和权限只显示上游提供且确认的值;未知状态明确显示沿用 Host 设置。Agent 审批、会话策略与终端输入权分别呈现。 +- 文件上传、Prompt 投递和取消显示真实进度与不确定结果,不因超时自动重放 mutation。 -屏幕旋转:Android 不锁定方向,跟随系统旋转设置;同一导航/连接状态在横竖屏复用。 -聊天消息与输入栏在宽窗口中使用居中的可读列(最大 760 dp);底部弹层与工作区对话框的最大高度 -按当前窗口计算(窗口高度低于 520 dp 时约占 92%),内容超出时在层内滚动;横屏或短窗口中压缩 -输入栏与隐私提示,并在旋转后重新同步 IME inset,避免用旧方向的键盘坐标计算底部留白。 -这些规则由 `apps/android/src/ui/responsive.ts` 与各面板共同实现,不代表已完成大字体、TalkBack -或分屏窗口的真机验收。 +## 响应式与键盘 -## 4. Android 导航 +App 跟随系统旋转。同一导航和连接状态适应手机、平板、分屏与短窗口;聊天保持居中的可读列,满足尺寸条件时采用左目录/右会话双栏。 -主机会话侧边栏:顶部为 24dp 主机名大标题(点击回到工作区),右侧为刷新与返回两个浮动圆钮,点击遮罩或系统返回键仅收起侧边栏。其下为「工作区 / 插件 / 自动化任务」带线性图标的 17dp 导航行,以及多后端时的筛选胶囊(选中项为白色浮起胶囊)。「工作区」分组标签使用 15dp muted 常规字重,保留搜索、视图选项与添加工作区图标。“最近访问”汇总最近使用且未归档的对话(含运行中对话),运行状态以绿色圆点显示;下方工作区保持目录顺序。工作区行 15dp 加粗、对话行 16dp 正文,最小 44–46dp 高度、圆角 16dp;对话相对工作区缩进,不绘制树状连线或行分割线。选中对话使用 surfaceStrong 灰底与加粗标题。「新建对话」为右下角浮动的 inverse 黑色胶囊(深色主题下为白色),列表底部预留空间避免遮挡。 +浮层和对话框按当前窗口限制高度,长内容在层内滚动,提交操作保持可达。使用实时安全区及键盘 inset,旋转后重新测量,不叠加过期的 IME 留白。Bot 表单同样使用键盘避让与可滚动内容。 -侧栏展开/折叠状态按主机和分组保存在手机,重新打开或重启应用后恢复;恢复完成前显示加载状态,避免先展开再收起。工作区无折叠记录时默认收起,当前会话不会触发自动展开;搜索可临时展开匹配结果,不覆盖折叠记忆。该偏好独立于主机工作区页。 +## 文件、终端与 Bot -完成 bootstrap 后,优先处理会话链接及用户开启的上次会话恢复;否则仅在账号下恰好一台设备且已信任、在线时自动进入其工作区。其他情况进入设备列表;未配置时先进入 Server 设置/账号授权。返回设备列表不会重复触发本次启动的自动跳转。 -登录页提供「扫码登录」点击入口:初始不请求 provider、不生成二维码,点击入口后才加载并在页内展示二维码, -手机扫码授权后自动注册本设备;手机、平板和大屏都保留知乎/GitHub 浏览器 OAuth 与邮箱密码登录,大屏使用 -更大的二维码。二维码只编码 Server 返回的同源 `scanUrl`,不包含账号 token;修改服务地址会作废旧二维码, -离开扫码页停止轮询。 +Files 的目录、只读预览、分页和保存动作复用会话 scope。图片/PDF/Office 使用本地受限 renderer;不执行 Host HTML/SVG、PDF 脚本或任意外链。显式保存文件与普通内存预览是两条不同流程,限制见[Android 说明](../../apps/android/README.md)。 -平板聊天在宽度 ≥760 dp 且(高度 ≥520 dp 或宽度 ≥1000 dp)时采用双栏:左侧常驻主机会话列表,右侧显示 -会话头部、消息与输入栏;在左栏切换会话只更新右侧内容,左栏头部的返回按钮回到工作区。双栏时右侧 -会话头部不再显示返回箭头,轨迹视图通过右侧操作图标关闭。窄屏与短窗口仍为手机单栏,会话列表继续 -以 Modal 抽屉打开。 +Terminal 使用本地 xterm WebView,明确区分输入权、退出、离线及 Host 禁用状态。关闭面板释放订阅,结束终端才终止进程;重连恢复有界屏幕,不重放输入。 -连接进度页在主机名下以居中的单行 `DSH 版本号 | Plugin 版本号` 展示设备目录报告的版本,缺失时明确显示版本不可用。 -工作区页标题只显示带下划线、整段可点击的主机名,点击进入主机信息;右上角只保留新建工作区入口。 -网络路径与详细诊断在已连接主机的信息页直接展开,并复用于对话信息面板。 -首页及单操作标题栏两侧保留对称空间,标题按屏幕居中;返回、更多和新建图标不加外层按钮背景、边框或阴影。 -主机信息页在主机名后提供编辑图标用于重命名,右侧展示系统类型,同一行不重复展示网络类型;设备信息分别列出 DSH 和 Remote 插件版本。 -主机列表以纯文字显示在线/离线状态,不使用圆点或胶囊底色;重命名入口仅保留在主机信息页。 -信息行的标签按文字宽度占位、最多占行宽的 40%,右侧内容使用剩余空间,避免短标签造成不必要的换行。 +Bot 团队、群聊、管理、问答和卡片使用共享 Button、IconButton、Sheet、表单与主题。管理和审批先经过当前认证通道,再由 DS-Bot 固定 handler 校验;原生 UI 只覆盖已接入功能。卡片使用受限原生图表/公式,不执行模型 HTML 或脚本。 -主路径:设备列表 → 信任/连接 → 工作区内的会话列表 → Chat。 -设备详情、连接详情、设置和关于页面属于辅助路径,不使用早期匿名 Pair device 配对流程。 -收藏/最近工作区快捷入口先连接所属 Host,再打开该工作区最近会话;没有会话时定位工作区。 -工作区作为连接后的首页,返回设备列表;Chat 返回对应工作区/会话路径。 -返回设备列表保留当前连接。Android 不提供独立「对话」菜单或跨工作区平铺的会话列表页;会话统一从所属设备的工作区进入。 +## Desktop 与维护 -语言支持跟随系统、英文、简体中文、日语、繁体中文、西语、德语、法语;默认显示跟随系统、简体中文、English,点击「More ...」展开全部语言,已选择新增语言时保持展开。主题支持跟随系统、浅色、深色。 -设置页按语言、外观、工作区设置、默认权限、连接与设备信息排列,语言始终为首组。全面使用 GroupCard 分组卡片与 GroupRow 行,偏好开关统一使用 Toggle 组件,外观支持浅色/深色/跟随系统的实时预览瓦片,底部提供红色的退出登录与重置本地数据高危操作行。设备名称放在底部身份信息中。说明紧邻对应选项,删除重复解释,保留生效时机、Host 支持条件及权限边界。 +Remote 只设置自身贡献的样式,不覆盖 Harness 全局 CSS 或其他插件布局。侧栏折叠/展开、长 Host 名称、键盘焦点和 Windows 拖拽区必须兼容。 -设置页提供默认关闭的全局「会话精简模式」开关,复用现有偏好列表与 Toggle;保存后下次打开会话生效。支持的 Host 缩减历史工具详情,正文与工具状态保留;关闭后重新打开加载完整历史,旧 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 待验收。 +功能范围和剩余工作统一见 [TODO](../TODO.md);临时截图、设备日志和测试数量不保存在设计系统中。