feat(ux): 小白 UX 全面改造 - 错误友好度 + 致命操作强确认 + 空状态 + 新手引导 + 术语表

面向小白用户的产品定位重塑，从七大 UX 痛点逐一改造： ## U1 错误友好度（59 处改造） - 新工具 src/lib/humanize-error.js：自动把后端原始错误（fetch failed、ENETUNREACH、ENOENT 等）映射成「主行 + hint 行动建议 + 折叠技术详情」三段式结构化对象 - toast 组件升级支持 { message, hint, raw } 结构化入参，向后完全兼容 - 14 个 page 文件中所有 toast(t('xxx.failed') + ': ' + e, 'error') 替换为 toast(humanizeError(e, t(...)), 'error') - common.js 加 error.* / errorHint.* 共 13 个新 i18n 键（11 语言）：网络/Gateway 未启动/命令缺失/权限/超时/限流/未找到/鉴权/服务繁忙/通用 ## U2 致命操作强确认（14 处改造） - showConfirm 升级支持结构化对象 { message, impact[], title, confirmText, cancelText, variant } - 加 .modal-impact-list 红边样式（让小白看清楚删了会丢什么） - 14 处致命操作改造，每处显示影响列表 + 红色「删除/移除/重置」按钮 + 灰色「保留」取消： · agents.js 删除 Agent（动态显示 N 个绑定影响） · channels.js 移除平台（动态算 N 个 binding）+ 移除 Agent binding · memory.js 删除记忆文件 · services.js 卸载 Gateway（3 段影响）+ 删除备份 · models.js 批量删模型 · chat.js 删除会话 + 重置会话 · dreaming.js 重置梦境日记 + 清空 grounded 短期记忆 · agent-detail.js 解除渠道绑定 · cron.js 删除任务（OpenClaw + Hermes 两端） - skills.js 原生 confirm() 改 showConfirm - hermes-cron.js 原生 confirm() 改 showConfirm，顺手修末尾多余 `}` 的 syntax 残留 ## U3-C 空状态 emoji+CTA（5 页面） - 通用 .empty-state 组件（大 emoji + 标题 + 副本 + CTA 按钮 + 紧凑变体） - agents.js: 🤖 + 「+ 新建 Agent」CTA - memory.js: 🧠 + 「+ 新建记忆文件」CTA（紧凑版） - cron.js: ⏰ + 「+ 新建任务」CTA - skills.js: 🛠️ + 「技能商店」CTA（点击切 Tab） - channels.js: 💬 + 紧凑提示 - CTA 巧妙复用页面顶部已有按钮的 click，零重复逻辑 ## U3-B Dashboard 新手任务卡片 - 蓝紫渐变卡片，4 步任务自动检测：启动 Gateway / 添加模型 / 创建 Agent / 第一次聊天 - 已完成：✓ 徽章 + 删除线 + 60% 透明 - 未完成：编号徽章 + 蓝色 CTA 按钮跳对应页面 - 全部完成 → 庆祝条「🎉 全部搞定！」+ 关闭按钮 - localStorage 标记，用户主动关闭后永久隐藏 - 14 个新 i18n 键，文案小白化（Gateway 是「发动机」/ Agent 是「分身」/ 模型给 AI 装「大脑」） ## U3-A 术语表页（/glossary） - 25 个核心术语 × 4 大分类（核心 8 / 模型 6 / 接入 5 / 进阶 6） - 搜索框实时过滤 + Tab 切换分类 + 卡片网格布局 - 每条术语：「比喻 + 一句话」描述（避免循环引用）+ 「打开页面 →」CTA 直达配置 - 3 语言（zh-CN / en / zh-TW）完整翻译，其他 8 语言 fallback - 双引擎（OpenClaw + Hermes）共用路由 - dashboard quick-actions 加「📖 面板术语」入口 ## U3-D 术语 ⓘ tooltip - 通用 src/lib/term-tooltip.js helper：termHelpHtml(id) + attachTermTooltips(root) - 8 个高频术语精简表（OAuth / Webhook / Bot Token / API Key / Token / Context Window / Binding / Scope） - channels.js 字段 label 智能匹配关键词自动追加 ⓘ（覆盖 8 个渠道全部敏感字段） - models.js 添加/编辑 provider 的 API Key label 也加 ⓘ - 点 ⓘ → 弹小型 modal 含解释 + 「打开术语表 →」CTA - attachTermTooltips 内部去重，可安全多次调用 ## 累计交付 - 4 个新文件（humanize-error.js / term-tooltip.js / glossary.js page / glossary.js i18n） - 6 个升级文件（toast / modal / components.css / dashboard / channels / models） - 14 个 page 错误 toast 友好化（59 处） - 14 处致命操作强确认 - 5 处空状态升级 + Dashboard 新手卡片 + 术语表 + ⓘ tooltip - 109 个新 i18n 键（11 语言） - Build 全程通过
2026-05-30 04:40:18 +08:00 · 2026-05-14 03:38:47 +08:00
parent 1d6843c4fb
commit e710db6ffb
39 changed files with 1510 additions and 109 deletions
--- a/src/lib/humanize-error.js
+++ b/src/lib/humanize-error.js
@@ -0,0 +1,125 @@
+/**
+ * humanize-error.js — 把后端原始 Error / Tauri Result 字符串映射成小白能看懂的友好文案。
+ *
+ * 用法：
+ *   import { humanizeError } from '../lib/humanize-error.js'
+ *   try { ... } catch (e) {
+ *     toast(humanizeError(e, t('channels.loadFailed')), 'error')
+ *   }
+ *
+ * 返回值：
+ *   {
+ *     message: string  // 用户主行（默认走 context 或匹配到的友好键）
+ *     hint:    string  // 副行小灰字行动建议
+ *     raw:     string  // 原始错误字符串（折叠在「技术详情」里）
+ *   }
+ *
+ * 设计原则：
+ *   - 永远返回对象（toast 组件需要稳定 shape）
+ *   - 永远保留 raw 给开发者排查
+ *   - hint 不强制覆盖 context；context 已含「做什么 + 失败」时 message 用 context
+ */
+
+import { t } from './i18n.js'
+
+const PATTERNS = [
+  // 网络
+  {
+    key: 'network',
+    re: /(failed to fetch|networkerror|networkfailure|enetunreach|econnreset|econnrefused|ehostunreach|err_network|fetch failed|connection refused|connection reset|getaddrinfo|dns error|no route to host|aborted|broken pipe|connect timed out|tcp connect)/i,
+  },
+  // Gateway 未启动（特殊的 connection refused / port not listen 情况）
+  {
+    key: 'gatewayDown',
+    re: /(gateway[^a-z]*(not[^a-z]*(running|ready|reachable)|down|offline|未启动)|managed gateway|未运行|gateway[^a-z]*未就绪)/i,
+  },
+  // 命令未找到 / 二进制丢失
+  {
+    key: 'cmdMissing',
+    re: /(command not found|not recognized as|no such file or directory|enoent|不是.*命令|未找到.*命令|cannot find|missing executable|exec format error)/i,
+  },
+  // 权限
+  {
+    key: 'permission',
+    re: /(permission denied|eacces|operation not permitted|access is denied|拒绝访问|无权限|权限不足|forbidden)/i,
+  },
+  // 鉴权（401/403/无效 token/api key）
+  {
+    key: 'auth',
+    re: /(401|unauthori[sz]ed|invalid (api[_ ]?key|token|credentials)|authentication[^a-z]*(failed|required)|signature.*verification.*failed|身份验证|未授权)/i,
+  },
+  // 限流
+  {
+    key: 'rateLimit',
+    re: /(429|too many requests|rate[_ ]?limit|quota[^a-z]*(exceeded|reached)|limit.*reached|流量限制|超过.*配额)/i,
+  },
+  // 超时
+  {
+    key: 'timeout',
+    re: /(timeout|timed out|deadline exceeded|超时)/i,
+  },
+  // 资源不存在（404）
+  {
+    key: 'notFound',
+    re: /(\b404\b|not found|does not exist|未找到|不存在|no such)/i,
+  },
+  // 服务繁忙（500-504 / "busy" / "unavailable"）
+  {
+    key: 'busy',
+    re: /(\b5\d\d\b|service unavailable|server error|internal server|temporarily unavailable|busy|繁忙)/i,
+  },
+]
+
+const RAW_MAX = 240 // 原始错误字符串保留长度（折叠区显示用，过长截断防止 toast 撑大）
+
+/**
+ * 把任意 error / 字符串 / Tauri Result 转成原始字符串。
+ */
+function toRawString(e) {
+  if (e == null) return ''
+  if (typeof e === 'string') return e
+  if (e instanceof Error) return e.message || e.stack || String(e)
+  if (typeof e === 'object') {
+    // Tauri invoke 失败时通常是字符串；如果是 object，看常见字段
+    if (typeof e.message === 'string') return e.message
+    if (typeof e.error === 'string') return e.error
+    try { return JSON.stringify(e) } catch { return String(e) }
+  }
+  return String(e)
+}
+
+/**
+ * @param {unknown} e          - 原始错误（Error / string / Tauri Result）
+ * @param {string}  [context]  - 操作上下文文案（如 t('channels.saveFailed')）
+ * @returns {{ message: string, hint: string, raw: string }}
+ */
+export function humanizeError(e, context) {
+  const raw = toRawString(e).trim()
+  const rawTruncated = raw.length > RAW_MAX ? raw.slice(0, RAW_MAX) + '…' : raw
+
+  // 1) 用 context 作为主行（已经是用户视角文案，比如「保存失败」）
+  //    没有 context 时用通用「操作未完成」
+  // 2) 匹配关键字定位具体原因 → 生成 hint
+  const ctx = (context && String(context).trim()) || ''
+  let kind = 'generic'
+  for (const p of PATTERNS) {
+    if (p.re.test(raw)) {
+      kind = p.key
+      break
+    }
+  }
+
+  const message = ctx || t(`common.error.${kind}`)
+  const hint = t(`common.errorHint.${kind}`)
+
+  return { message, hint, raw: rawTruncated }
+}
+
+/**
+ * 便捷帮手：直接拿格式化后的字符串（无 hint 折叠 UI，给老 API 兼容）。
+ *   humanizeErrorText(e, ctx) -> "保存失败 · 网络不通"
+ */
+export function humanizeErrorText(e, context) {
+  const h = humanizeError(e, context)
+  return h.hint ? `${h.message} · ${h.hint}` : h.message
+}