101 lines
8.4 KiB
Markdown
101 lines
8.4 KiB
Markdown
# Agent Persona 设计
|
|
|
|
更新日期：2026-10-22。本文保存供水前端当前的 Persona 视觉与交互规格，作为后续调整的基线。资源解析、再生成及缓存实现见 [动画资源说明](agent-persona-resource.md)；通用控件和语义表面继续遵循 [样式设计指南](style-design-guide.md)。
|
|
|
|
## 1. 形象与材质
|
|
|
|
采用 Obsidian 原生 Rive 水纹球，保留柔和羽化、流动反射、不规则边缘水纹和状态机。配色采用已选定的 02「冰水蓝」：浅色水体承载白色高光，暗部保持蓝色，外围水纹提供地图上的辨识度。主体底色具有较高遮蔽度，减少地图道路穿过球体的现象。
|
|
|
|
| 角色 | 当前值 | 用途 |
|
|
| --- | --- | --- |
|
|
| 球面底色 | `#DCEFFA` | 浅冰蓝底层，独立于流动反射 |
|
|
| 底色不透明度 | 待机 94%，活动 98% | 保持主体清楚，避免背景纹理干扰 |
|
|
| 水体反射 | `#299FDF` | 提供蓝色层次与流动感 |
|
|
| 同色相暗部 | `#1482BC` | 保留体积，避免灰黑混色 |
|
|
| 高光 | `#FFFFFF` | 保留清晰、干净的反射 |
|
|
| 外围水纹 | `#4C9ECC` | 提高浅色地图上的辨识度 |
|
|
|
|
颜色直接写入 Rive 资源，不使用 CSS 色相、亮度或对比度滤镜。通用 UI 仍引用共享语义颜色；上表仅定义动画资源本身的材质。参数源为 [obsidian-material.json](../design/agent/obsidian-material.json)。
|
|
|
|
以下为当前资源的实际静态帧，用于辨认在线与离线外观；运动行为以第 4 节为准。
|
|
|
|
| 在线待机 | 离线静水待机 |
|
|
| --- | --- |
|
|
| <img src="../public/agent/obsidian-water-idle.png" width="64" height="64" alt="冰水蓝在线 Persona，有外围水纹"> | <img src="../public/agent/obsidian-water-offline.png" width="64" height="64" alt="冰水蓝离线 Persona，无外围光圈"> |
|
|
|
|
## 2. 尺寸与定位
|
|
|
|
| 使用位置 | 画布尺寸 | 布局要求 |
|
|
| --- | --- | --- |
|
|
| `AgentPersona` 默认 | 64 × 64px | 固定尺寸，不随状态变化 |
|
|
| 桌面收起入口 | 64 × 64px | 画布填满按钮命中范围 |
|
|
| 桌面与手机面板标题栏 | 64 × 64px | 与名称、状态共同形成身份区 |
|
|
| 手机地图入口 | 40 × 40px | 使用同一资源，适应地图工具栏 |
|
|
|
|
桌面收起入口距地图左侧 **12px**，距顶部导航下沿 **12px**。两个方向由同一定位层的内边距控制；当前导航高 56px，因此入口左上角为视口中的 `(12px, 68px)`。这里的顶部距离以导航下沿为起点。
|
|
|
|
尺寸指整个 Rive 画布，包含资源固有的羽化留白。放大时保留画板比例，不裁掉外围水纹。悬浮入口仅显示 Persona；状态通过按钮名称与悬停提示提供，避免增加卡片、状态点、箭头或底圈。
|
|
|
|
## 3. Agent 标题区
|
|
|
|
身份行高 **80px**，左右内边距 12px、上下 8px。左侧为 64px Persona，旁边上下排列名称“供水助手”和连接状态；右侧集中排列对话操作。
|
|
|
|
| 内容 | 规格与行为 |
|
|
| --- | --- |
|
|
| 名称 | 14px、半粗，与现有标题排版一致 |
|
|
| 连接状态 | 12px 辅助文字配共享 `StatusDot`；显示实际的“连接中 / 在线 / 离线” |
|
|
| 操作 | 新建对话、历史、折叠；手机末项为关闭，每项命中范围 40 × 40px |
|
|
| 上下文行 | 高 36px，保留会话标题与项目或个人范围切换 |
|
|
|
|
身份行与上下文行保持连续的浅色表面，在标题区底部使用分隔线。历史展开、键盘导航和关闭后焦点恢复沿用现有行为。320px 手机宽度下，名称、状态和三个操作均应完整显示且互不重叠。
|
|
|
|
## 4. 动画与状态
|
|
|
|
动画由 Rive WebGL2 的同一个 `default` 状态机驱动，业务层提供真实状态。在线水纹持续流动；离线保持完整球体，通过节奏与光圈变化表达连接不可用。
|
|
|
|
| 状态 | 呈现 |
|
|
| --- | --- |
|
|
| `idle` | 原生待机流动与外围水纹 |
|
|
| `thinking` | 原生处理状态动画 |
|
|
| `listening` | 原生等待输入动画，具体含义由业务映射决定，不单凭形象表示麦克风录音 |
|
|
| `speaking` | 原生输出状态动画 |
|
|
| `asleep` | 内部柔光低速、小幅流动，外围三层光圈透明度为 0 |
|
|
| `hover` | 鼠标附近的局部白色反射随指针移动，与当前业务状态叠加 |
|
|
|
|
离线设计称为“静水待机”。在线与离线以 **600ms** 混合切换，可见实例保持挂载；离线球体持续运动，恢复在线后恢复外围光圈。离线悬停也不重新打开外围光圈。
|
|
|
|
离线三层循环周期为 **15s / 19.25s / 31.375s**，位移与呼吸振幅为原来的 25%，完整旋转保持循环闭合。时间轴速率由 60 调至 24，约为原速 40%；此值不代表屏幕渲染帧率上限。详细图层参数见 [obsidian-offline.json](../design/agent/obsidian-offline.json)。
|
|
|
|
## 5. 悬停与点击
|
|
|
|
悬停沿用原版三层反射的尺寸、渐变、亮度和淡入淡出。白色高光跟随鼠标所在位置：从左侧移到右侧时，高光随之移动；鼠标离开后恢复常态。不能只打开 `hover` 布尔值而遗漏坐标，否则原生指针目标停在默认中心，造成球体中间大片变白。球体、点击范围和常态外围水纹尺寸均保持原定义。
|
|
|
|
共享 `Persona` 保留 Rive 原生指针监听，将主指针的进入、移动、离开和取消转交给画布；坐标转换与资源内的跟随约束由 Rive 完成。触摸及按压不转交动画，不绑定 View Model。悬浮入口和标题形象共用这条通路，画布就绪后才接收交互。
|
|
|
|
点击、触摸轻点及 Enter / Space 展开对话，离线时同样可用。球体不添加 Motion 按压缩放、弹簧回弹或按下变暗；触摸按下不模拟 hover。外层面板的布局动画独立维护，Resizable 连续调宽保持直接响应。
|
|
|
|
## 6. 加载、降级与缓存
|
|
|
|
首次加载显示当前资源导出的静态帧。Rive 加载后先等待 600ms 完成原生进入动画，再以 **180ms CSS 透明度渐变**衔接，尺寸和位置保持固定。在线、离线分别使用相应的本地 PNG，避免银灰占位与蓝色动画之间的突变。
|
|
|
|
系统开启“减少动态效果”时显示静态帧，不初始化 Rive；资源失败时保留相应静态形象与按钮功能。强制颜色模式显示高对比轮廓，保留焦点和键盘操作。元素离开视口或页面隐藏时卸载渲染实例，可见后恢复。
|
|
|
|
客户端按页面内存、Cache Storage、网络的顺序取得资源。仅共享不可变 `.riv` 字节，每个可见入口独立创建动画实例；不共享实例或绑定 View Model。资源重建时同步生成 SHA-256 版本，URL 带版本参数，使旧缓存自然更新。缓存范围与校验逻辑见 [动画资源说明](agent-persona-resource.md)。
|
|
|
|
## 7. 实现与维护
|
|
|
|
| 入口 | 文件 |
|
|
| --- | --- |
|
|
| 业务形象与降级 | [AgentPersona](../src/features/agent/components/agent-persona.tsx) |
|
|
| 原生状态机接入 | [Persona](../src/shared/ai-elements/persona.tsx) |
|
|
| 桌面悬浮按钮 | [AgentCollapsedRail](../src/features/agent/components/agent-collapsed-rail.tsx) |
|
|
| 标题区 | [AgentCommandPanel](../src/features/agent/components/agent-command-panel.tsx) |
|
|
| 资源生成与原版还原 | [build-agent-persona.mjs](../scripts/build-agent-persona.mjs) |
|
|
| 资源版本与缓存 | [persona-resource.ts](../src/shared/ai-elements/persona-resource.ts) |
|
|
|
|
材质与离线参数以对应 JSON 为准，悬停沿用原始资源中的几何与指针约束；改动时同步本文与资源说明。原始解析数据保留以便逐字节还原 `.riv`；该数据不等于作者完整的 `.rev` 编辑器工程。
|
|
|
|
验收时检查 64px 桌面入口、64px 标题形象与 40px 手机入口，覆盖默认、悬停进入与退出、快速切换、离线和恢复在线。桌面检查 1024/1440px 视口及 400/640px 面板，手机检查 320/375px。确认左上间距一致、按压无缩放、首次加载无画面硬切、底色能遮蔽地图、离线无外围光圈、缓存刷新后仍加载当前版本。
|
|
|
|
资源级检查使用固定时间步对照原版与修改版：在线状态保持相同材质下的逐像素一致；悬停检查左右移动时局部高光跟随指针，移出后完全恢复。工作台检查鼠标坐标实际到达悬浮入口和标题形象的 Rive 监听器，不能仅断言 hover 开关变化。离线检查完整球体、持续变化和光圈关闭。运行命令见 [资源说明](agent-persona-resource.md)，各次实际验证结果记录在 [实施记录](history/agent-chat-ui-implementation-notes.md)。
|