8.4 KiB
Agent Persona 设计
更新日期：2026-10-22。本文保存供水前端当前的 Persona 视觉与交互规格，作为后续调整的基线。资源解析、再生成及缓存实现见 动画资源说明；通用控件和语义表面继续遵循 样式设计指南。
1. 形象与材质
采用 Obsidian 原生 Rive 水纹球，保留柔和羽化、流动反射、不规则边缘水纹和状态机。配色采用已选定的 02「冰水蓝」：浅色水体承载白色高光，暗部保持蓝色，外围水纹提供地图上的辨识度。主体底色具有较高遮蔽度，减少地图道路穿过球体的现象。
| 角色 | 当前值 | 用途 |
|---|---|---|
| 球面底色 | #DCEFFA |
浅冰蓝底层，独立于流动反射 |
| 底色不透明度 | 待机 94%，活动 98% | 保持主体清楚，避免背景纹理干扰 |
| 水体反射 | #299FDF |
提供蓝色层次与流动感 |
| 同色相暗部 | #1482BC |
保留体积，避免灰黑混色 |
| 高光 | #FFFFFF |
保留清晰、干净的反射 |
| 外围水纹 | #4C9ECC |
提高浅色地图上的辨识度 |
颜色直接写入 Rive 资源，不使用 CSS 色相、亮度或对比度滤镜。通用 UI 仍引用共享语义颜色；上表仅定义动画资源本身的材质。参数源为 obsidian-material.json。
以下为当前资源的实际静态帧，用于辨认在线与离线外观；运动行为以第 4 节为准。
| 在线待机 | 离线静水待机 |
|---|---|
 |
 |
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。
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 带版本参数，使旧缓存自然更新。缓存范围与校验逻辑见 动画资源说明。
7. 实现与维护
| 入口 | 文件 |
|---|---|
| 业务形象与降级 | AgentPersona |
| 原生状态机接入 | Persona |
| 桌面悬浮按钮 | AgentCollapsedRail |
| 标题区 | AgentCommandPanel |
| 资源生成与原版还原 | build-agent-persona.mjs |
| 资源版本与缓存 | persona-resource.ts |
材质与离线参数以对应 JSON 为准，悬停沿用原始资源中的几何与指针约束；改动时同步本文与资源说明。原始解析数据保留以便逐字节还原 .riv；该数据不等于作者完整的 .rev 编辑器工程。
验收时检查 64px 桌面入口、64px 标题形象与 40px 手机入口，覆盖默认、悬停进入与退出、快速切换、离线和恢复在线。桌面检查 1024/1440px 视口及 400/640px 面板，手机检查 320/375px。确认左上间距一致、按压无缩放、首次加载无画面硬切、底色能遮蔽地图、离线无外围光圈、缓存刷新后仍加载当前版本。
资源级检查使用固定时间步对照原版与修改版：在线状态保持相同材质下的逐像素一致；悬停检查左右移动时局部高光跟随指针，移出后完全恢复。工作台检查鼠标坐标实际到达悬浮入口和标题形象的 Rive 监听器，不能仅断言 hover 开关变化。离线检查完整球体、持续变化和光圈关闭。运行命令见 资源说明，各次实际验证结果记录在 实施记录。