# MetonaAI Desktop — UI/UX 设计集成方案

综合 2026 年 AI Agent 交互设计前沿趋势 + MetonaToast 组件库研究成果，产出 MetonaAI Desktop 完整的用户界面设计方案，确保"可见思维、可控行动、可信结果"。

📊 研究来源: Fuselab Creative / Ant Design X / A2UI / Hermes Agent 📦 集成组件: MetonaToast v2.0.0
📋 文档层级：本文档是 用户界面与交互设计的权威定义，与《构建指南》第九章(React 前端)对应。冲突时以本文档为准。

## 📊 2026 AI Agent UI/UX 趋势综述

通过分析 Fuselab Creative、UX Tigers、Ant Design X、Google A2UI、The Skins Factory 等权威来源，提炼出 6 大核心趋势：

# | 趋势 | 核心要求 | Metona 对应
--- | --- | --- | ---
1 | 可解释 AI（Explainable AI） | 用户必须看到 Agent 在想什么、做什么、为什么 | TraceViewer 实时展示 Thought → ToolCall → Observation 全链路
2 | Agentic UX / RICH 范式 | 角色(Role) + 意图(Intention) + 会话(Conversation) + 混合界面(Hybrid UI) | SOUL.md 定义角色 + Chat 对话 + Tool Panel 混合 UI
3 | 透明与可控 | 每步提供 override 控制、用户可随时中断/修正 | Abort 按钮、工具调用前确认弹窗、参数可编辑
4 | A2UI — AI 说出 UI | Agent 以声明式 JSON 描述 UI 意图，客户端原生渲染 | 预留 A2UI 接口，Agent 可动态生成卡片/表格/图表
5 | 多模态混合界面 | 文本 + 代码 + 图表 + 图片 + 3D 混合呈现 | MessageItem 支持 Markdown + 代码高亮 + 图片 + Mermaid 图表
6 | 优雅错误恢复 | 错误不是终点，是引导用户修正的入口 | MetonaToast error/warning 通知 + 错误上下文面板

💡 Fuselab Creative 核心论断："Agent UX 与传统 UI 的根本区别在于 — Agent 界面必须传达系统正在做什么、解释其推理逻辑、在每一步提供覆盖控制、并从错误中优雅恢复。设计挑战是在保持用户信任的同时允许系统自主操作。"

## 🧩 Agent 交互设计模式

### Ant Design X — RICH 范式

维度 | 含义 | Metona 实现
--- | --- | ---
Role（角色） | Agent 的身份、性格、能力边界 | SOUL.md → System Prompt RoleDefinition
Intention（意图） | 理解用户目标，主动规划 | ReAct Loop → Thought 思考过程实时展示
Conversation（会话） | 多轮对话 + 历史上下文 | ChatPanel + Session 管理 + Memory 检索
Hybrid UI（混合界面） | 对话 + 传统 UI 混合 | Chat + Tool Panel + TraceViewer + Settings 同屏

### Agent UI 五大核心面板

    1. 对话面板  →  2. 思维面板  →  3. 工具面板  →  4. 工作区面板  →  5. 状态栏

    核心交互链路:  用户输入 → Agent思考 → 工具执行 → 结果展示 → 反馈通知
                       │           │           │          │
                  实时流式    折叠/展开    参数+耗时    Markdown渲染
                       │           │           │          │
                  MetonaToast  TraceViewer  ToolCallCard  MessageItem

## 📢 MetonaToast 项目分析

`metona-toast` v2.0.0 — 你的自研通知组件库，已发布到 npm。 纯 JavaScript，零依赖，gzip <10KB，设计精致。

特性 | 详情 | Metona Desktop 用途
--- | --- | ---
80+ 图标 | success/error/warning/info/loading 及扩展 | 工具结果通知、LLM 错误提示、操作确认
11 种动画 | slide/fade/scale/bounce/flip/rotate/zoom/slideUp/Down/Left/Right | 用 bounce 表示重要通知，fade 表示信息
主题系统 | light/dark/auto/warm + registerTheme() | 与 Electron 暗色模式无缝同步，auto 跟随系统
国际化 | zh-CN / en-US + addTranslations() | 根据用户系统语言自动切换
插件系统 | keyboard(ESC关闭)/persistence(localStorage)/accessibility | keyboard 插件让用户 ESC 关闭所有通知
可拖拽关闭 | Pointer Events 拖拽，旋转+透明反馈 | 自然手势关闭，符合现代交互习惯
毛玻璃效果 | backdrop-filter: blur(14px) saturate(180%) | 与 Electron 窗口背景融合，有层次感
链式调用 | loading()→success() / loading()→error() | 工具执行中显示 loading，完成后转为 success/error
confirm/prompt | 对话框式确认和输入 | 高风险工具调用前的用户确认
progress/countdown | 进度条和倒计时 | 长时间操作（模型下载、文件处理）

## ⚙️ MetonaToast 集成方案

### 安装与配置

    // electron/main.ts — 主进程不直接使用（Node 环境无 DOM）
    // src/main.tsx — React 渲染进程入口
    import MeToast from 'metona-toast';

    // 全局配置（应用启动时执行一次）
    MeToast.configure({
      position: 'top-right',
      duration: 4000,
      max: 6,
      theme: 'auto',         // 跟随系统暗色模式
      animation: 'slide',
      pauseOnHover: true,
      closeOnClick: true,
      showProgress: true,
      draggable: true,
      locale: 'zh-CN',
    });

    // 安装插件
    MeToast.use('keyboard');       // ESC 关闭所有
    MeToast.use('persistence');    // 配置持久化
    MeToast.use('accessibility');  // 屏幕阅读器

### 场景映射表

Metona 场景 | Toast 调用 | 动画
--- | --- | ---
工具执行成功 | `MeToast.success('文件读取完成')` | slide
工具执行失败 | `MeToast.error('网络请求超时')` | bounce
权限校验被拒 | `MeToast.warning('需要权限确认')` | scale
LLM 开始推理 | `MeToast.info('正在思考...', {duration:0})` | fade
Session 保存 | `MeToast.success('会话已保存')` | slide
MCP Server 连接 | `MeToast.success('MCP 已连接', {title:'filesystem'})` | slideUp
上下文压缩 | `MeToast.info('上下文已压缩', {duration:2000})` | fade
模型下载进度 | `MeToast.progress('下载中...').setProgress(60)` | slide
高风险操作确认 | `MeToast.confirm('确定删除文件？')` | scale

💡 主进程通知桥接：Electron 主进程（Node.js 环境）无法直接调用 DOM Toast。通过 IPC 发送 `mainWindow.webContents.send('toast:show', { type:'success', message:'...' })`， 渲染进程监听并调用 `MeToast[event.type](event.message)`。

## 🏗️ 整体布局设计

参考 Claude Code / Cursor / Hermes Agent 桌面版的布局设计，采用经典的 IDE 式三栏布局。

    ┌──────────────────────────────────────────────────────────────┐
    │  Header Bar    [🔮 MetonaAI Desktop]    [会话] [设置] [— □ ✕] │
    ├──────────┬────────────────────────────────┬──────────────────┤
    │          │                                │                  │
    │  Sidebar │      Main Chat Area            │  Detail Panel    │
    │          │                                │  (可折叠)         │
    │ ┌──────┐ │  ┌──────────────────────────┐  │ ┌──────────────┐│
    │ │ 会话  │ │  │  [Agent] 💭 思考过程...    │  │ │ Trace Viewer  ││
    │ │ 列表  │ │  │  [Agent] 🔧 read_file     │  │ │              ││
    │ │      │ │  │  [Agent] 📄 文件内容        │  │ │ #1 THINKING    ││
    │ │ + 新建│ │  │  [Agent] 结论: ...         │  │ │ #2 PARSING     ││
    │ │      │ │  │                          │  │ │ #3 EXECUTING    ││
    │ │ ──── │ │  │                          │  │ │ #4 OBSERVING    ││
    │ │ 工具  │ │  │                          │  │ │ #5 REFLECTING   ││
    │ │ 管理  │ │  │                          │  │ │ #6 COMPRESSING  ││
    │ │ 工具  │ │  ├──────────────────────────┤  │ ├──────────────┤│
    │ │ 管理  │ │  │  [输入框..............] [发送] │ │ │ Token 用量    ││
    │ │      │ │  │  [📎文件] [🔧工具] [⚙️]     │  │ │ 输入: 1240   ││
    │ │ ──── │ │  └──────────────────────────┘  │ │ 输出: 350    ││
    │ │ 记忆  │ │                                │ └──────────────┘│
    │ │ 搜索  │ │                                │                  │
    │ └──────┘ │                                │                  │
    ├──────────┴────────────────────────────────┴──────────────────┤
    │  Status Bar   🟢 Agent Ready | deepseek-v4-pro | Tokens: 1.2K │
    └──────────────────────────────────────────────────────────────┘

区域 | 宽度 | 内容
--- | --- | ---
Header Bar | 全宽 | Logo + 窗口控制 + 快捷操作
Sidebar (可折叠) | 260px | 会话列表、工具管理、记忆搜索、MCP 管理
Main Chat Area | 弹性 | 消息流 + 输入框 + 流式渲染
Detail Panel (可折叠) | 320px | TraceViewer + Token 用量 + 工具状态
Status Bar | 全宽 | Agent 状态、Provider 信息、Token 统计

### 布局模式

为适应不同场景和屏幕尺寸，提供三种布局模式：

模式 | Sidebar | DetailPanel | Chat 区域 | 触发方式
--- | --- | --- | --- | ---
默认模式 | 展开 260px | 展开 320px | 弹性（约 1340px @1920） | 默认状态
紧凑模式 | 折叠 56px 图标条 | 折叠 48px 图标条 | 弹性（约 1816px @1920） | `Cmd/Ctrl+B` + `Cmd/Ctrl+J`
专注模式 | 隐藏 | 隐藏 | 全宽（约 1920px） | `Cmd/Ctrl+Shift+F`

💡 布局设计原则：Sidebar 和 DetailPanel 均为可折叠抽屉式，默认展开完整面板，折叠后只保留图标条（悬停可预览，点击展开为浮层）。Chat 区域在两侧折叠时获得最大宽度，适合宽屏代码展示和 Markdown 渲染。

### 消息布局：全宽卡片流

放弃传统聊天应用的左右分栏气泡布局，采用全宽卡片流布局（参考 Claude / ChatGPT）。Agent 的核心交互是任务执行而非聊天，工具调用结果、代码块、表格都需要全宽展示。

消息类型 | 布局 | 对齐 | 宽度
--- | --- | --- | ---
User Message | 浅色背景卡片 + 用户头像 | 左对齐 | 全宽（max-width: 768px 居中）
Agent Thought | 缩进灰色虚线框 | 左对齐 | 全宽（可折叠）
Agent ToolCall | 缩进彩色卡片 + 状态图标 | 左对齐 | 全宽
Agent Answer | 无背景或极浅背景 + Agent 头像 | 左对齐 | 全宽 Markdown 渲染

💡 为什么不用气泡布局：传统左右分栏气泡将用户消息右对齐，导致 Agent 的长回复（含代码块、表格、图表）被压缩到一半宽度。全宽卡片流让所有内容都能利用完整宽度，阅读体验显著提升。用户消息虽然全宽，但通过 `max-width: 768px` 居中限制可读性。

## 💬 聊天面板设计

### 消息类型矩阵

消息角色 | 视觉样式 | 内容渲染 | 交互
--- | --- | --- | ---
User Message | 全宽 / 浅色背景卡片 / 用户头像 / 左对齐 | 纯文本 + 附件缩略图 | 双击编辑 / 右键菜单
Agent Thought | 左对齐 / 虚线边框 / 💭 图标 / 可折叠 | 纯文本（等宽字体） | 默认折叠，点击展开
Agent Tool Call | 左对齐 / 紫色边框 / 🔧 图标 | 工具名 + JSON 参数 + 状态图标 | 悬停显示参数详情、点击跳转 Trace
Agent Tool Result | 左对齐 / 青色边框 / 📄 图标 | 结果摘要 + 文件路径/行数/耗时 | 点击打开完整结果
Agent Answer | 左对齐 / 无背景 / Agent 头像 | Markdown + 代码高亮 + 图表 | 代码块一键复制、链接可点击
System Notification | 居中 / 灰色 / 小字 | 时间戳 / 状态变化 | 不可交互

### 流式渲染策略

使用 `requestAnimationFrame` + 节流（每 16ms 一次）平滑更新 DOM。 Thought 内容进入时显示 `💭 思考中...` 加载动画，收到 `thinking_end` 后折叠。 工具调用使用 `ToolCallCard` 骨架屏先行占位，结果到达时填充。

## 🔍 Trace Viewer 设计

置于右侧 Detail Panel，以时间轴方式展示每次 ReAct 迭代的完整过程。用户可展开每一步查看细节。

    ┌─ Trace Viewer ──────────────────────────────────┐
    │  Session: 数据分析任务     迭代: 2/20            │
    │─────────────────────────────────────────────────│
    │                                                 │
    │  ▼ #1 THINKING                    1.2s  120 tok │
    │     💭 "需要先读取目标文件..."                    │
    │                                                 │
    │  ▶ #2 PARSING                     0.1s          │
    │                                                 │
    │  ▼ #3 EXECUTING                   0.3s          │
    │     🔧 read_file: /data.csv ✓ 5ms               │
    │     📄 1000 rows, 3 cols                        │
    │                                                 │
    │  ▶ #4 OBSERVING                   0.1s          │
    │                                                 │
    │  ▶ #5 REFLECTING                  0.2s          │
    │     💭 "数据结构清晰，可以进行下一步分析..."      │
    │                                                 │
    │  ▶ #6 COMPRESSING                 0.1s          │
    │     📦 上下文已压缩 (3.2K → 1.8K)               │
    │                                                 │
    │  ○ #7 THINKING (当前)                           │
    │     ⏳ 正在调用 LLM...                           │
    │                                                 │
    │─────────────────────────────────────────────────│
    │  Token: 入 1.2K | 出 0.4K | 总计 1.6K          │
    │  耗时: 2.3s | Provider: DeepSeek v4-pro        │
    └─────────────────────────────────────────────────┘

## 🔧 工具调用 UI

### ToolCallCard 状态机

状态 | 图标 | 颜色 | 行为
--- | --- | --- | ---
pending | ⏳ 旋转 | #fbbf24 | 骨架屏占位，等待工具执行
executing | 🔧 脉冲 | #a855f7 | 显示参数摘要
success | ✅ | #34d399 | 显示结果摘要 + 执行耗时
error | ❌ | #f87171 | 显示错误信息 + 重试按钮
blocked | 🚫 | #fb923c | 显示拒绝原因 + 手动授权按钮

### 高风险操作确认流程

    # 用户在聊天面板看到：
    ┌─────────────────────────────────────────┐
    │  🔧 write_file                          │
    │  目标: /home/user/config.yaml           │
    │  风险: ⚠️ MEDIUM — 将覆盖已有文件       │
    │                                         │
    │  [查看差异]  [✅ 确认执行]  [❌ 取消]    │
    └─────────────────────────────────────────┘

    # 用户点击「确认执行」后：
    MeToast.success({ title: '已授权', message: 'write_file 正在执行...' });

    # 用户点击「取消」后：
    MeToast.warning('操作已取消');

### 确认流程优化：信任会话

为避免密集操作场景（如批量重构代码）下逐次确认打断流程，引入信任会话机制：

模式 | 行为 | 触发方式
--- | --- | ---
默认模式 | MEDIUM+ 操作逐次确认 | 默认
信任会话 | MEDIUM 操作不逐次确认，会话结束时生成操作摘要供审查 | 设置中开启
同类免确认 | 同一会话内同类操作（如 write_file）首次确认后不再确认 | 确认弹窗勾选「本次会话不再确认同类操作」
批量确认 | 连续多个同类操作合并为一个确认弹窗 | Agent 连续发起 ≥3 个同类操作时自动触发

⚠ HIGH 级别操作始终需要确认，不受信任会话影响。CRITICAL 级别需要双人复核（未来计划）。
💡 确认弹窗增强：增加「查看命令」展开区域，显示完整的工具调用参数（JSON 格式），让用户做出知情决策。

## ⚙️ 设置面板

分 Tab 展示，配置变更即时持久化到 SQLite 数据库。

Tab | 内容
--- | ---
LLM 配置 | Provider 选择、API Key、模型名称、参数滑块（temperature/maxTokens/contextWindow）
Agent 配置 | 最大迭代次数、超时、Thinking 开关、反思模式、压缩阈值
工具管理 | 27 个内置工具开关、风险级别配置、路径白名单、命令黑名单
MCP 服务 | Server 列表、添加/删除/启停、连接状态指示灯
外观 | 主题（light/dark/auto）、字体大小、消息密度、动画开关
日志与数据 | 日志级别、数据库位置、数据导出/清理、使用统计

## 🌲 组件树

🎨 UI 组件库：所有 UI 交互组件强制使用 Material UI (MUI)（`@mui/material`）。按钮、输入框、弹窗、选择器、表单控件、标签页、提示、布局、进度条、卡片等均使用 MUI 组件。除非 MUI 确认不存在对应组件，否则禁止自写 UI 组件。Tailwind CSS 仅作为 MUI 的辅助样式补充（间距、颜色变量），不可替代 MUI 组件。

    AppLayout
    ├── Header (Logo + SessionSelector + SettingsButton)
    ├── Sidebar
    │   ├── SessionList (会话列表 + 新建/搜索/分组/置顶)
    │   ├── ToolManager (工具状态 + MCP 管理)
    │   └── MemorySearch (记忆检索面板)
    ├── ChatPanel
    │   ├── MessageList (虚拟滚动 · 全宽卡片流)
    │   │   ├── MessageItem (User/Assistant/Tool/System)
    │   │   ├── ThoughtBlock (可折叠思考内容)
    │   │   ├── ToolCallCard (工具调用卡片)
    │   │   └── ToolResultBlock (工具结果块)
    │   ├── StreamingIndicator (流式加载)
    │   └── ChatInput (输入框 + 附件 + 工具选择 + 上下文指示器)
    ├── DetailPanel (右侧，可折叠为图标条)
    │   ├── TraceViewer (ReAct 迭代追踪)
    │   ├── TokenUsage (Token 统计图表)
    │   └── AgentMonitor (Agent 状态指示)
    ├── StatusBar (状态栏)
    ├── ToastContainer (MetonaToast 通知层)
    ├── OnboardingWizard (首次使用引导)
    └── CommandPalette (Cmd+K 快速搜索)

## 👋 首次使用引导（Onboarding）

首次启动应用时自动展示引导向导，帮助用户完成初始配置。向导完成后不再显示（可通过设置重新触发）。

### 引导流程

1欢迎页：Metona 是什么、能做什么（3 句话 + 动图展示）
2配置 LLM：选择 Provider（DeepSeek/Agnes/Ollama）→ 输入 API Key 或 Ollama 地址 → 测试连接
3自定义 Agent：选择预设角色或自定义 SOUL.md → 填写 USERS.md（技术栈、偏好）
4工作空间：确认默认路径 `~/MetonaWorkspaces/default/` 或选择自定义路径
5开始使用：展示一个示例对话，让用户感受 Agent 能力
💡 设计要点：每一步都可以「跳过」，不强制完成。跳过配置 LLM 的用户会在首次发送消息时提示配置。向导状态记录在 `app_config` 表中（`onboarding.completed = true/false`）。

## ⌨️ 快捷键体系

快捷键是桌面 Agent 应用的核心生产力工具。所有快捷键支持 macOS（Cmd）和 Windows/Linux（Ctrl）。

快捷键 | 功能 | 分类
--- | --- | ---
`Cmd/Ctrl + N` | 新建会话 | 会话
`Cmd/Ctrl + K` | 快速搜索（会话/记忆/文件） | 全局
`Cmd/Ctrl + Enter` | 发送消息 | 输入
`Cmd/Ctrl + Shift + Enter` | 换行（多行输入） | 输入
`Cmd/Ctrl + .` | 中断 Agent 执行 | Agent
`Cmd/Ctrl + Shift + F` | 专注模式（隐藏 Sidebar + DetailPanel） | 布局
`Cmd/Ctrl + B` | 折叠/展开 Sidebar | 布局
`Cmd/Ctrl + J` | 折叠/展开 DetailPanel | 布局
`Cmd/Ctrl + ,` | 打开设置 | 全局
`Cmd/Ctrl + [ / ]` | 历史会话切换（上一个/下一个） | 会话
`Esc` | 关闭弹窗/取消焦点 | 全局
`Cmd/Ctrl + L` | 聚焦输入框 | 输入
`Cmd/Ctrl + Shift + C` | 复制最后一条 Agent 回复 | 编辑
`Cmd/Ctrl + D` | 切换暗色/亮色主题 | 外观

💡 输入框智能特性：
• 多行自适应：输入框默认单行，输入多行时自动扩展（最大 6 行后滚动）
• 文件拖拽：拖拽文件到输入框自动添加为附件，显示文件名 + 大小
• 图片粘贴：粘贴剪贴板图片自动转为 base64 附件
• `/` 命令：输入 `/` 弹出命令菜单（`/tool` 选择工具、`/memory` 搜索记忆、`/clear` 清空会话、`/export` 导出会话）
• `@` 提及：输入 `@` 弹出文件/会话提及菜单，快速引用上下文
• 上下文指示器：输入框下方显示当前上下文使用率（如 "Context: 12K / 128K (9%)"），接近上限时变色警告
• 草稿自动保存：未发送的输入内容自动保存，切换会话后恢复

### 右键菜单设计

对象 | 菜单项
--- | ---
消息 | 复制 · 引用回复 · 编辑(仅用户消息) · 删除 · 重新生成(仅 Agent 消息)
工具调用卡片 | 查看参数 · 查看完整结果 · 复制结果 · 重新执行
会话项 | 重命名 · 置顶 · 归档 · 删除 · 导出
代码块 | 复制代码 · 在编辑器中打开
Trace 步骤 | 复制 Thought · 复制工具参数 · 导出步骤详情

## 🎨 主题系统

双主题引擎：CSS Variables（应用级）+ MetonaToast Theme API（通知级），统一 token 体系。

### CSS 变量 Token 体系

    /* 亮色主题 */
    :root[data-theme="light"] {
      --bg-primary: #ffffff;
      --bg-secondary: #f8fafc;
      --bg-tertiary: #f1f5f9;
      --text-primary: #0f172a;
      --text-secondary: #334155;   /* 对比度 ~8:1，满足 WCAG AA */
      --border-color: #e2e8f0;
      --accent: #6366f1;
    }

    /* 暗色主题 */
    :root[data-theme="dark"] {
      --bg-primary: #0f1117;
      --bg-secondary: #1a1d27;
      --bg-tertiary: #252836;
      --text-primary: #e1e4ed;
      --text-secondary: #64748b;    /* 对比度 ~4.6:1，满足 WCAG AA */
      --border-color: #2a2d3a;
      --accent: #818cf8;
    }

💡 主题同步：Electron 的 `nativeTheme.themeSource` 控制 Chromium 的 `prefers-color-scheme`。 MetonaToast 的 `theme:'auto'` 自动跟随。应用级 CSS 通过 `matchMedia('(prefers-color-scheme: dark)')` 监听切换。

## ✨ 动效规范

场景 | 动效 | 时长 | 缓动
--- | --- | --- | ---
消息进入 | 从下方淡入 + 上移 10px | 300ms | ease-out
流式文本 | 逐字出现（CSS typing 模拟） | — | —
Thought 展开 | max-height 过渡 + 淡入 | 250ms | ease
Tool 状态切换 | 图标旋转/脉冲 + 边框颜色渐变 | 400ms | ease-in-out
Sidebar 折叠 | width 过渡 | 300ms | cubic-bezier(0.4,0,0.2,1)
Toast 通知 | 11 种（MetonaToast） | 400-650ms | cubic-bezier (库内)
加载骨架屏 | shimmer 光泽扫过 | 1.5s loop | linear infinite
悬停反馈 | scale(1.02) + shadow 提升 | 150ms | ease-out

### 性能保护机制

动效在低性能设备和用户偏好下自动降级：

条件 | 降级策略
--- | ---
`prefers-reduced-motion: reduce` | 所有动效即时切换（duration: 0ms），流式文本改为闪烁光标
FPS < 30（检测到掉帧） | 骨架屏 shimmer 改为静态灰色背景，悬停 scale 改为仅 shadow
设置中关闭「动画效果」 | 等同于 `prefers-reduced-motion`，所有动效禁用

💡 流式文本优化：放弃逐字 DOM 更新方案（性能差），改为 `caret-color` 闪烁光标 + CSS `animation` 实现打字机效果。文本内容通过 `requestAnimationFrame` 批量插入（每帧一次），避免高频 DOM 操作。
💡 设置面板增加「动画效果」开关：三档选项——`开启`（全动效）/ `关闭`（禁用所有动效）/ `自动跟随系统`（默认，读取 `prefers-reduced-motion`）。配置存储在 `app_config` 表中（`ui.animationMode = 'auto' | 'on' | 'off'`）。

## 🚧 错误恢复体验

错误不是终点，是引导用户修正的入口。不同错误类型采用不同的交互策略：

错误类型 | UI 展示 | 恢复策略 | 用户操作
--- | --- | --- | ---
工具执行错误 （如文件不存在） | 内联在聊天流中 红色边框卡片 | Agent 自动分析错误 → 决定重试或换策略 | 通常无需操作；如需用户输入，Agent 在聊天中内联提问
LLM 调用错误 （如 API 超时） | 错误卡片 + 操作按钮 | 等待用户决策 | `[重试]` / `[切换 Provider]` / `[查看详情]`
解析错误 （LLM 输出不符合格式） | 用户无感知 （静默重试） | 静默重试（最多 3 次），超出后显示提示 | 超出重试后显示「模型输出异常」+ `[重试]`
权限拒绝 （用户取消操作） | 灰色卡片 | Agent 收到取消信号，调整策略 | `[修改权限设置]` 链接
网络连接错误 | StatusBar 红色指示灯 + Toast | 自动检测网络恢复后提示用户 | `[重试]` / `[离线模式]`（仅 Ollama 可用）

💡 所有错误在 TraceViewer 中留痕：每个错误作为一个独立 Trace 步骤，记录完整的错误信息、堆栈、重试历史。用户可以事后展开查看，不影响正常对话流。

## 📁 会话管理

Sidebar 会话列表支持搜索、分组、置顶、归档，适应长期使用场景。

### 会话列表功能

功能 | 交互方式 | 说明
--- | --- | ---
搜索 | 会话列表顶部搜索框 | 按标题和消息内容模糊搜索（`fuse.js`）
置顶 | 右键菜单 → 置顶 | 置顶会话固定在列表顶部，显示 📌 图标
分组 | 自动按工作空间分组 | 每个工作空间一个折叠组，可展开/收起
归档 | 右键菜单 → 归档 | 归档的会话移入「归档」折叠区，不占主列表空间，可恢复
重命名 | 双击会话标题 / 右键菜单 | 内联编辑，回车保存
导出 | 右键菜单 → 导出 | 导出为 Markdown / JSON
删除 | 右键菜单 → 删除 | 移入回收站（可恢复 30 天）

💡 会话项信息：每个会话项显示——会话标题（自动生成或用户重命名）、最后活跃时间（如「3 分钟前」）、消息数、Agent 状态指示灯（进行中显示绿色脉冲）。

## 🖥️ 窗口管理

Electron 桌面应用的窗口管理习惯设计：

功能 | 行为 | 配置项
--- | --- | ---
关闭窗口 | 最小化到系统托盘（默认），不退出应用 | `app.closeToTray = true`（可关闭）
托盘图标 | 显示 Agent 状态：空闲（白色）/ 思考中（蓝色脉冲）/ 执行中（绿色旋转） | —
托盘菜单 | 新建会话 · 显示窗口 · 退出 | —
多窗口 | 每个工作空间可独立开窗口，窗口标题显示工作空间名称 | `app.multiWindow = true`
全局快捷键 | `Cmd/Ctrl+Shift+M` 从任意应用切换到 Metona 窗口 | 可自定义快捷键
系统通知 | Agent 完成长时间任务时发送系统通知（点击跳转到对应会话） | `app.notifications = true`
开机自启 | 系统启动时自动启动 Metona（最小化到托盘） | `app.autoStart = false`

💡 托盘图标实现：使用 `electron Tray` API，动态切换图标以反映 Agent 状态。托盘图标右键菜单通过 `Menu.buildFromTemplate()` 构建。全局快捷键使用 `globalShortcut.register()`。

🎨 MetonaAI Desktop UI/UX 设计集成方案

研究来源: Fuselab Creative · Ant Design X · Google A2UI · Hermes Agent · Siyu's Newsletter

集成组件: MetonaToast v2.0.0 · 版本 v1.0.0 · 2026-07-15