assess-appearance

name	assess_appearance
description	修改小莫助手右下角图标的完整规范——按统一标准重设计动态头像 + 全套状态指示(含录音态)，确保始终动态、美观、且录音状态可见

修改小莫助手右下角图标 · 完整规范

本 Skill 指导如何重设计 / 调整「小莫助手」右下角浮动图标(以下称 FAB 图标)。 目标:让图标始终在动态变化、好看、美观,并且任何重设计后都必须保留全套状态指示(尤其是「录音中」状态)。

适用对象:对 mobius/frontend 前端做自迭代的 agent / 用户。 作用域:仅 FAB 图标本身(assistant-fab + mo-avatar + 状态浮层)。不要改动助手面板(assistant-panel)、消息流、语音后端逻辑。

---

0. 硬性要求(四条铁律,缺一不可)

任何一次图标修改,最终交付必须同时满足以下四条。验收清单(见 §10)逐条核对,任何一条不过则视为失败、返工。

1. 始终动态:空闲态(非打开、非录音、非说话)也必须有持续运行的动画。图标永远「活着」,不允许静止的死图。
2. 美观:配色统一、有光晕(halo)与多层深度阴影、明暗主题双适配、动效顺滑不眩晕。
3. 录音状态可见:.assistant-fab--voice-recording + .assistant-fab__voice-badge 长按录音时的红色麦克风指示必须保留且醒目(见 §5、§6)。
4. 状态系统完整:说话 / 长按 / 录音 / 转写 / 关闭 / 任务完成 六种状态的视觉指示一个都不能少(见 §4),行为契约(TSX 侧)不得破坏。

---

1. 图标在哪里(定位地图)

角色	文件	位置
FAB 按钮渲染 + 状态变量	mobius/frontend/src/components/assistant-chat.tsx	FAB <button> 约 L3372–3413;状态派生约 L3348–3368
图标组件 MoAvatar	同上	MoAvatar() 约 L615–640
粒子常量	同上	MO_PARTICLES = Array.from({length:18},...) 约 L32
长按进入录音	同上	ASSISTANT_FAB_VOICE_HOLD_MS = 1500 约 L37;collapsedVoiceHoldState 约 L1600
FAB 样式(容器/halo/各状态)	mobius/frontend/src/index.css	.assistant-fab* 约 L1446–1638
头像样式(球体/环/核/粒子/keyframes)	同上	.mo-avatar* 约 L4540–4709
状态动画 keyframes	同上	约 L3359–3393
减弱动画兜底	同上	@media (prefers-reduced-motion: reduce) 约 L4711 起

行号会漂移,以选择器名 / 类名 / 函数名为准,行号仅作辅助定位。

---

2. 图标的完整解剖(FAB = 容器 + 头像 + 状态浮层)

<button class="assistant-fab fixed bottom-5 right-5 z-[60] w-14 h-14 rounded-full ...">   ← FAB 容器(见 §3)
  ├── <MoAvatar>                                                                          ← 动态头像本体(见 §3.1)
  │     ├── .mo-avatar                      容器,mo-life-float 漂浮
  │     ├── .mo-avatar__field               渐变能量球,mo-field-breathe 呼吸
  │     ├── .mo-avatar__ring--outer         外轨道环,mo-ring-turn
  │     ├── .mo-avatar__ring--inner         内轨道环,mo-ring-turn-reverse
  │     ├── .mo-avatar__core                白蓝高光核,mo-core-pulse
  │     └── .mo-avatar__particle--1..18     18 粒子,各持 drift-a/b/c + 独立 delay/color
  ├── .assistant-fab__speaking-waves        说话时 3 道扩散波环(可选渲染)
  ├── .assistant-fab__hold-ring             长按蓄力旋转环(可选渲染)
  ├── .assistant-fab__voice-badge           录音(红 Mic)/ 转写(蓝旋转 RefreshCw)徽标(可选渲染)
  ├── .assistant-fab__close                 打开态的关闭 X(可选渲染)
  └── .assistant-fab__completion-badge      任务完成绿色提示(可选渲染)

容器还有个伪元素 .assistant-fab::before —— 这是招牌光晕:conic-gradient + blur + 缓慢旋转,决定了「高级感」,重设计务必保留一个等价光晕层。

2.1 两种尺寸 / 性能变体

• .mo-avatar--lg (46px) 用于 FAB;.mo-avatar--sm (26px) 用于消息气泡头像。
• 尺寸用 em 单位(容器 font-size 决定整体缩放),内部所有 .07em、left:47% 等百分比/em 让粒子在 lg/sm 下等比缩放。重设计时保持 em/百分比体系,别写死 px,否则 sm 头像会崩。
• .mo-avatar--lite:消息列表逐条头像用的性能变体,禁用全部无限动画(animation:none !important)只渲染静态渐变球。禁止改动 lite 的禁动画策略——长会话滚动时 18 粒子 + filter 持续重绘会严重掉帧。

2.2 active 加速态

MoAvatar 的 active prop 为真时(打开/发送中/有活动任务/说话/录音)挂 .mo-avatar--active,把主要动画 animation-duration 调短(球/核 4.8s、粒子 6.4s),让图标「兴奋起来」。重设计应保留这种「空闲慢、活跃快」的节奏对比。

---

3. 动态规范(满足铁律 1:始终动态)

3.1 必须存在的动画层

一份合格的图标至少叠 4 层持续动画,确保任何瞬间都不静止:

1. 漂浮:容器级 mo-life-float(整体轻位移 + 微缩放 + 微旋)。
2. 呼吸/流光:能量球 mo-field-breathe(饱和度/亮度/形状微变)。
3. 环绕:外环 mo-ring-turn + 内环 mo-ring-turn-reverse(双向)。
4. 微粒:≥10 颗粒子用 mo-particle-drift-a/b/c,每颗独立 animation-delay(用负 delay 错峰),避免齐步走显得机械。

当前用 18 颗粒子覆盖球体四周。减少颗数可以,但别低于 10,且每颗 delay 必须各不相同(现在用 -1.1s ~ -8.5s 交错)。

3.2 节奏与缓动

• 周期全部用 infinite;时长相互错开(球 7.4s / 外环 13s / 内环 9.5s / 核 5.8s / 粒子 8.8s)避免周期性同步导致的「卡顿感」。
• 缓动用 ease-in-out / linear(旋转类),禁止线性硬切的闪烁。

3.3 可访问性(必须保留)

• @media (prefers-reduced-motion: reduce) 块约 L4711 起,把 .assistant-fab::before、.assistant-fab--speaking、波环、hold-ring、voice-badge、.mo-avatar 全家动画置为 none。重设计新增的任何动画元素都要补进这个媒体查询,否则违反无障碍。
• MoAvatar 与所有浮层都带 aria-hidden="true"(纯装饰),保留。

---

4. 状态系统(满足铁律 4:六态完整)

FAB 的 className 由 assistant-chat.tsx 约 L3362–3368 动态拼装。这是行为契约,TSX 侧不要改;重设计只动 CSS / DOM 外观。

状态	TSX 变量(约 L3348–3352)	容器 class	渲染的浮层	用户语义
说话中(语音播报播放)	fabSpeaking = voicePlaybackState==='playing'	--speaking	.assistant-fab__speaking-waves	小莫在说话
长按蓄力(未松手,>1.5s 前的过渡)	fabVoiceHolding = !open && state==='holding'	--voice-holding	.assistant-fab__hold-ring	继续按进入语音
录音中	fabVoiceRecording = !open && state==='recording'	--voice-recording	.assistant-fab__voice-badge(红 <Mic>)	松开结束录音
转写中	fabVoiceTranscribing = !open && voiceState==='transcribing'	--voice-transcribing	.assistant-fab__voice-badge(蓝 <RefreshCw> 自旋)	正在转写语音
打开(面板展开)	open	—	.assistant-fab__close(X)	收起小莫
任务完成未读	!open && unreadCompletion>0	—	.assistant-fab__completion-badge(绿)	N 项任务完成

MoAvatar 的 active 在「打开 / 发送中 / 有活动任务 / 说话 / 任一语音态」时为真,加速动画。

重设计守则:每个状态都要有可被一眼区分的视觉(颜色/形状/动效不同),且互不冲突。徽标用 z-index 分层(现在 close=3、badge=5、hold-ring=4、waves=1、completion=6、avatar=2),新增浮层注意层级。

---

5. 录音状态(满足铁律 3:录音可见)—— 最关键

当前实现(index.css 约 L1528–1545、L1588–1591;TSX 约 L3394–3402):

• 红色麦克风徽标 .assistant-fab__voice-badge:右下角 26px 圆,background: rgba(239,68,68,.96)(红),内含 <Mic> 图标,带白色描边 + 红色外发光阴影,assistant-fab-recording-badge 动画(1s 缩放 + 阴影脉冲扩散)。
• 容器态 .assistant-fab--voice-recording::before:把招牌光晕从青/紫/粉改成「红」基调 conic-gradient,opacity 提到 .9,让整圈泛红,录音感更强。

重设计录音态时必须保证:

1. 红色基调不可去:录音是「危险/进行中」语义,用红(或饱和暖色)与说话(青)/转写(蓝)拉开差距。配色变了仍要保证红是录音专属。
2. 麦克风图标 <Mic> 不可替换为无语义图形:用户要能从图标认出「正在录音」。
3. 徽标必须够大够亮:.assistant-fab__voice-badge 当前 26px、右下外溢 -4px。重设计可调整但别小于 22px、别藏到 FAB 内部不可见。
4. 持续脉冲动效:录音徽标要有 assistant-fab-recording-badge 这类循环动画,「正在采集」感。静态红点不合格。
5. 容器整体要有反应:--voice-recording 改 ::before 光晕色 —— 保留这一层,让录音时整颗图标都泛红脉动,而不只是角落一个小点。
6. 录音态与转写态可区分:转写是蓝 + 自旋 <RefreshCw>(--voice-transcribing),别让两者变一样。

验收时(见 §9)必须人工触发长按录音并确认:徽标出现、为红色、有脉冲动效、整圈泛红、松手后消失。

---

6. 美观规范(满足铁律 2:美观)

6.1 配色(建议沿用既有体系)

• 暗主题球体:青 #2dd4bf / 蓝 #38bdf8/#7dd3fc / 紫 #818cf8/#c4b5fd / 粉 #f472b6/#fda4af / 金 #facc15/#fde68a。高光白蓝核。整体偏「能量/生命」冷调 + 暖点缀。
• FAB 容器暗主题:rgba(10,14,22,.72) 深玻璃底 + 白 14% 描边 + 多层青/金外发光阴影。
• 明主题(.light .assistant-fab*,约 L1615–1638):浅底 + 深字 + 阴影降饱和。改暗主题配色务必同步 .light 一组,明暗都要好看。
• 录音 = 红 #ef4444、转写 = 蓝 #0ea5e9、完成 = 绿 #22c55e、说话 = 青。状态色与球体色系分开,避免混淆。

6.2 深度与质感

• 招牌光晕 .assistant-fab::before:conic-gradient + filter:blur(14px) + 缓慢旋转(mo-halo-turn)。重设计至少保留一层等价光晕;说话态把 opacity/saturate 拉满 + 加速(现 .assistant-fab--speaking::before)。
• 多层 box-shadow:底投影(深度)+ 0 0 0 描边色 + 彩色外发光三层打底。hover 提亮发光。
• 玻璃感用半透明底 + backdrop-filter(关闭按钮 .assistant-fab__close 已用),新增浮层可沿用。
• 内阴影 inset 给球体立体感(__field 的 inset 0 0 ... + 底部暗 inset)。

6.3 动效品味

• 顺滑缓动、周期错峰、幅度克制(位移/缩放 < 5%–8%),不眩晕、不抖。
• 进入/退出用短促 cubic-bezier(如 completion 用 .32s cubic-bezier(.2,.9,.25,1))。
• 旋转类用 linear infinite;呼吸/脉冲用 ease-in-out infinite。

---

7. 修改流程(标准步骤)

1. 先读后改:按 §1 定位,通读 MoAvatar、FAB <button> 渲染段、.assistant-fab* 与 .mo-avatar* 两段 CSS,理解现状再动手。
2. 明确改什么:只改(a)配色/质感、(b)动画节奏、(c)粒子/环/核造型、(d)状态浮层外观。不要改 TSX 的状态变量、长按时长、aria-hidden、lite 性能策略、reduced-motion 策略。
3. 改 CSS 优先:绝大多数外观调整只动 index.css。需要新增 DOM 层(如更多粒子)才动 MoAvatar,且务必同步 reduced-motion。
4. 保持 em/百分比体系:头像内部尺寸继续用 em/%;只有徽标/徽章等「固定信息密度」元素可用 px。
5. 明暗双改:改暗主题一组配色,立刻同步 .light 一组。
6. 补 reduced-motion:新动画元素全部加进 §3.3 媒体查询。
7. 本地构建验证:cd mobius/frontend && npm run build(= vite build)必须通过,见 §8。
8. 人工验收:按 §9 逐状态截图核对,§10 清单全过。
9. 提交上线:见 §11。

---

8. 构建命令

# 仅验证前端编译是否通过(快):
cd /app/mobius/frontend && npm run build

# 纯前端改动,编译 + promote 产物(不重启后端、无交互,适合自动化迭代):
cd /app && python3 start.py --only-update-frontend

# 全量(编译 + 重启后端 + code-server,非交互环境会卡 attach 提示,慎用):
cd /app && python3 start.py

vite build 报错先修 TSX/CSS 语法,再继续。

---

9. 人工验收(逐状态,建议截图核对)

浏览器打开应用,操作右下角小莫图标,确认每个状态视觉正确:

• 空闲态(刚进页面、未打开):球体呼吸、双环旋转、粒子飘移、外圈光晕缓转 —— 明显在动。
• hover:放大发光增强。
• 打开:出现 X 关闭符;active 加速,动画变快。
• 说话(触发一条回复的语音播报):3 道扩散波环 + 容器轻微上浮 + 光晕加亮加速。
• 长按蓄力(收起态长按 FAB < 1.5s):hold-ring 旋转环出现。
• 录音中(长按 ≥ 1.5s):右下红色 Mic 徽标 + 脉冲扩散 + 整圈泛红光晕(§5 六条逐条确认)。
• 转写中(松手后短暂):徽标变蓝 + RefreshCw 自旋。
• 任务完成:未读时绿色「任务已完成」徽章从上方弹出。
• 明主题:切换 light,所有状态配色/可读性正常,不刺眼。
• reduced-motion:系统开「减弱动态效果」,所有无限动画停止、静态仍美观、各状态徽标仍可辨认。
• 消息气泡 sm 头像:lite 态静态球,长会话滚动不卡顿。

---

10. 交付验收清单(铁律对照)

• 铁律 1 始终动态:空闲态 ≥4 层动画在跑、粒子 ≥10 颗错峰、全 infinite。
• 铁律 2 美观:配色统一、招牌光晕在、多层深度阴影、明暗双适配、动效不眩晕。
• 铁律 3 录音可见:红 Mic 徽标 + 脉冲 + 泛红光晕,§5 六条全过。
• 铁律 4 状态完整:说话/长按/录音/转写/关闭/完成六态一个不缺且可区分。
• npm run build 通过。
• 未破坏 TSX 状态契约、长按时长、aria-hidden、lite 性能、reduced-motion。
• sm 头像未崩(em 体系完好)。
• 任一条不过 → 返工,不得交付。

---

11. 提交上线(遵循项目规则)

每次完成修改,先 commit 所有文件(含非本人改动的),再执行 python3 start.py 更新代码。

• commit message 格式:<用户名>: <代码变动说明>(用户名用英文或拼音,如 chenyang: ...)。
• commit message 仅说明本次图标变动(配色/动效/状态等)。
• commit 后 python3 start.py(或 --only-update-frontend)编译 + promote 前端产物。

---

12. 禁止事项(反模式)

• ❌ 把空闲态改成静止死图(违反铁律 1)。
• ❌ 删除/弱化红色录音徽标或去掉其脉冲动效(违反铁律 3)。
• ❌ 丢弃任何一种状态浮层或让两态外观撞车(违反铁律 4)。
• ❌ 拆掉招牌光晕 .assistant-fab::before、改用扁平无阴影。
• ❌ 给头像内部写死 px(破坏 sm/lg 等比缩放)。
• ❌ 改动 lite 性能变体的 animation:none 策略。
• ❌ 新增动画却不补 prefers-reduced-motion。
• ❌ 改暗主题配色却忘了同步 .light 一组。
• ❌ 改 TSX 的状态派生 / 长按时长 / aria-hidden 等行为契约。
• ❌ 跳过 npm run build 与人工逐状态验收就交付。