OpenClaw-bot-review/prd/mobile_adaptation_plan.md

OpenClaw Bot Dashboard 手机端适配方案

1. 目标

• 在不牺牲桌面端体验的前提下，完整支持手机端（优先 iPhone 12/13/14、主流 Android 360~430 宽度）。
• 保证核心路径可用：查看 Agents、Models、Sessions、Stats、Alerts、Pixel Office。
• 将“能打开”提升为“可操作”：导航、筛选、测试按钮、弹窗、图表、表格、像素办公室交互都可用。

2. 当前现状与主要问题

基于当前代码结构，手机端主要风险如下：

• 全局布局采用固定左侧边栏（RootLayout + Sidebar），移动端会明显挤压主内容区。
• 多个页面使用桌面间距和密集按钮组（p-8、单行多个 CTA），在小屏上易换行错位或超出。
• 部分页面是“桌面信息密度优先”（尤其 Models 表格、Stats 四卡并排），手机端阅读成本高。
• Pixel Office 为重交互 Canvas 页面，移动端触控手势、性能、弹层可读性未做专项设计。

3. 适配范围

• 全局框架：app/layout.tsx、app/sidebar.tsx、app/globals.css
• 页面：/、/models、/sessions、/stats、/alerts、/skills、/pixel-office
• 组件：弹窗、图表容器、表格容器、按钮组、顶部信息条
• 非目标（本阶段不做）：PWA 离线、原生 App、平板专属布局体系

4. 设计原则

• Mobile First：先定义手机布局，再向 md/lg 扩展。
• 同构信息：手机端不删关键能力，只调整呈现层级与交互方式。
• 降低操作成本：按钮可点面积 >= 40px；关键操作不依赖 hover。
• 性能优先：移动端默认降低高频动画与非必要轮询密度。

5. 方案设计

5.1 全局布局与导航

• 将固定左侧边栏改为响应式双形态：
  • md 及以上：保持当前侧栏。
  • < md：顶部栏 + Drawer 导航（汉堡按钮打开，遮罩点击关闭）。
• 主区域在手机端改为满宽流式，不再预留侧栏 spacer 宽度。
• 顶部栏保留最关键入口：菜单、页面标题、语言/主题（可折叠进菜单）。

5.2 通用页面框架

• 页面外层间距统一改为响应式：
  • 手机：p-3/p-4
  • 桌面：md:p-6/lg:p-8
• 顶部操作区从“单行横排”改为“可换行堆叠”：
  • 手机：纵向分组（主按钮一行，次按钮折叠到更多菜单或下一行）。
  • 桌面：保持横向布局。
• 统一引入移动端工具类：
  • 小字号下限（正文 >= 12px）
  • 触控尺寸类（按钮、开关、输入控件）

5.3 数据展示策略

• Models 页面：
  • 手机端改“宽表”模式为“卡片摘要 + 可展开详情”。
  • 保留“测试模型”入口，但放入每卡片底部操作区。
• Stats 页面：
  • 四个 summary 卡改为 grid-cols-2（超小屏可 grid-cols-1）。
  • 图表保持横向滚动，但提供最小可读宽度和标题固定。
• Sessions 页面：
  • 列表卡片信息分层，弱化次要字段（session key 默认折叠）。
  • 测试按钮改为单独操作行，避免与时间戳争抢空间。

5.4 Pixel Office 专项适配

• 交互模型：
  • 将鼠标语义补齐为触控语义（tap、long-press、drag）。
  • 关键弹层（手机、时钟、沙发等）在手机端改为底部抽屉式（bottom sheet）优先。
• 视图与性能：
  • 根据屏幕宽度动态设置默认缩放与 UI overlay 尺寸。
  • 移动端降低非关键动画密度（虫子数量上限、浮动元素频率可降级）。
• 可用性：
  • 顶部 agent chips 在手机端支持横向滚动，避免遮挡主画布。
  • 保证弹层关闭区域与返回路径明显可点。

5.5 可访问性与可读性

• 增加触屏友好焦点样式、键盘可达性（抽屉/弹窗支持 Esc 关闭）。
• 颜色对比在浅色主题下复核（已有 light mode override，需移动端回归验证）。
• 文案截断策略统一：关键 ID/模型名使用 tooltip 或展开查看。

6. 实施计划（分阶段）

Phase 1：骨架改造（1~2 天）

• 完成全局响应式布局与移动端 Drawer 导航。
• 页面容器与顶部操作区完成响应式重排。
• 建立通用移动端样式规范（spacing、touch target、font scale）。

Phase 2：页面适配（2~3 天）

• 首页、Models、Sessions、Stats、Alerts、Skills 全量适配。
• 模型表格卡片化、统计卡片栅格优化、按钮区重排。

Phase 3：Pixel Office 适配（2~3 天）

• 触控事件补齐、弹层改造（bottom sheet）、性能降级策略。
• 移动端专项交互回归（点击家具、弹窗、返回、滚动冲突）。

Phase 4：收尾与验收（1 天）

• 设备矩阵回归测试。
• 性能与可访问性检查。
• 文档更新与变更说明。

7. 验收标准

• 手机端 360px 宽度下无横向整体溢出。
• 核心页面首屏可在 3 秒内进入可操作状态（本地网络场景）。
• 所有关键按钮可点击区域 >= 40px。
• Pixel Office 在手机端可完成：打开页面、点击家具弹层、关闭弹层、返回其他页面。
• 无阻塞级 UI 缺陷（错位、遮挡、不可点）。

8. 测试计划

• 设备维度：
  • iOS Safari（390x844）
  • Android Chrome（360x800 / 412x915）
• 断点维度：
  • <640、640~767、768~1023、>=1024
• 场景维度：
  • 深浅主题切换
  • 中英文切换
  • 数据量高（agent 多、model 多、session 多）

9. 风险与应对

• 风险：桌面布局回归破坏
  • 应对：采用断点增量改造，桌面样式默认保持不变。
• 风险：Pixel Office 触控改造影响现有鼠标事件
  • 应对：抽象输入层（pointer/touch/mouse），先加兼容层再替换调用点。
• 风险：移动端性能波动
  • 应对：默认启用轻量模式参数，并提供开关。

10. 交付物

• 响应式导航与页面布局改造代码。
• Pixel Office 移动端交互/弹层/性能适配代码。
• 测试记录（设备、断点、问题清单）。
• 更新后的维护文档（适配规则与断点规范）。