e2hang/EzVibeR

Fork 0

Files

Claude Agent 205c57e9b7 Update: Usage

2026-06-20 14:55:47 +08:00

11 KiB

Raw Permalink Blame History

09 · 常见问题 FAQ

按问题频率排序。看完还没解决请看终端日志（开发模式直接看 npm run tauri:dev 的输出；生产构建看 ~/.local/share/com.ezviber.plus/logs/ 或终端）。

启动 / 窗口

Q1. 双击桌宠会被最大化 / 全屏

A: 这是已修复的 bug（2026-06-11）。双击透明区域被 dblclick capture listener 拦截掉，不会触发最大化。如果遇到，确认版本是 2026-06-11 之后。

Q2. 桌宠窗口不置顶 / 切桌面就消失

A: 这是 Tauri 2 在 Wayland/GNOME 下的已知 bug（tauri-apps/tauri#13121）。 软件默认会自动 set_var("GDK_BACKEND", "x11") 强制走 XWayland。如果你主动设了 EZVIBE_FORCE_WAYLAND=1 就跳过了这个保护 → 关掉。其他情况：

KDE 也有类似问题，但概率小
关闭桌宠后从托盘恢复时有时属性会丢，再点一次托盘「显示桌宠」就行

Q3. 桌宠关闭后从托盘恢复位置变了 / 尺寸变了

A: 预期行为。当前版本不记忆关闭前的精确位置。窗口默认按 live2d.conf.json 的 width/height/x/y 建。手工调一次大小后会自动存盘。

跨 workspace 重建（拖完关 → 重建）有 Tauri#14913 bug，当前没有干净 workaround。

Q4. 关了桌宠窗口想完全退出软件

A: 托盘 → 关闭软件。

桌宠窗口右上角 ❌ 按钮 / 任务栏右键关闭只是隐藏窗口，软件在托盘继续跑。

Q5. 托盘图标消失了

Linux：检查 libappindicator 装了没；KDE 用户可能要装 libappindicator-gtk3；GNOME 需要装扩展 AppIndicator Support
macOS：系统设置 → 控制中心 → 菜单栏额外项 → 启用
Windows：自动出现在右下角系统托盘，点「^」展开可能看到

Q6. 打开桌宠后系统变卡

A: 几个可能：

移动窗口时频繁触发 write_config（throttle 100ms）→ 低端机可能成瓶颈。建议别狂拖窗口。
你的模型超复杂（贴图 200+ 张）→ 换简单模型
截图功能走 Portal 占用 → 暂停截图（不点桌宠身体就行）

Q7. 窗口右下角冒出奇怪滚动条，桌宠在抖

A: 已修复（2026-06-14）。如果还遇到，确认版本是 2026-06-14 之后。html/body 锁了 overflow: hidden。

模型 / Live2D

Q8. 桌宠加载出来了但是空的 / 全白

A: 检查 model3.json 引用的 .moc3 / texture 路径对不对。控制台会打 [DEBUG-EMOTION] 无模型 之类。

💡 推荐直接在浏览器打开 http://127.0.0.1:<port>/<path>.model3.json 看能不能加载（端口在 live2d.conf.json 的 port 字段里）。

Q9. 表情/动作没切

A: 三个常见原因：

你的模型没那么多表情/动作 → 配置中心 → 「🎭 当前 Live2D 模型能力」看实际有哪些
关键词没匹配上 → 改模型的表情名（中文优先）或加新动作
pixi-live2d-display v0.4.0 老 bug → 已知有些模型（March 7th）表情加载失败，软件有 workaround（直接读 exp/xxx.exp3.json），重启软件试试

Q10. 表情切换后回不去原始状态

A: 已知。软件记录了"上一个表情的参数 ID"试图清掉，但模型里某些参数被永久设值时恢复不了。重启软件可以重置（启动时调用 coreModel.getParameterDefaultValue 抓快照）。

Q11. 模型怎么删除 / 我有多个模型想换着用

A: 模型目录里有几个子目录，就会自动识别几个。点工具栏 👁 随机换一个。也可以在配置中心加网络模型 URL。

聊天 / LLM

Q12. 状态点红色「API key 未配置」

A: 三选一：

真的没填 → 配置中心填上
填了但没重启 → 必须重启（见 07-LLM对话.md §5.1）
填了重启了还是红 → 检查 live2d.conf.json 里的 llm_api_key 字段没有前后空格

Q13. 发消息没反应 / 一直「思考中…」

A: 检查顺序：

终端有没有 [401] API key 无效 → 重新填 key
终端有没有 无法连接到 API 服务 → 网络/代理问题，见 Q14
终端有没有 请求超时 → LLM 端点太慢，换个端点或检查网络
终端有没有 Brain reminder failed → 是 reminder 报错，不是对话。和聊天无关

Q14. 在 clash-verge / sing-box 后面连接超时

A: 已知现象：Tailscale / 内网 IP 会被代理劫持到外网节点。 软件已经强制 no_proxy()，但你的系统环境变量（HTTP_PROXY 等）如果已经设了，覆盖不到 reqwest 内部。临时方案：

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy
unset ALL_PROXY all_proxy
npm run tauri:dev

或者把 100.64.0.0/10（Tailscale 网段）加到你的代理"DIRECT"规则里。

Q15. 改完 base_url / model / api_key 还是老的

A: 必须重启。在内存里的 LLM client 不会重读配置。

Q16. LLM 触发了但桌宠没动作 / 没表情

A: 当前版本不再注入动作标签 prompt。模型动起来主要靠事件注入（interact / praise 等），不是 LLM 主动返回。

Q17. 思考气泡没出现

A: 说明你的 LLM 不发 <think>...</think> 块。

DeepSeek / QwQ / o1 / Claude extended thinking 都会发
普通 GPT-4 / Claude Sonnet 不会
想看到效果就换上面任一模型

Q18. 截图发给 AI 后报 60s 超时

A: 已修复为 180s（2026-06-14）。如果你看到错误文案里还写"60s"，那是错误信息的历史遗留，实际超时已经是 180s。如果还遇到：

LLM 端点真的慢 → 换更快的 / 同城
截图特别大 → 截屏时缩小（当前不支持 UI 调）

Q19. RAG / 长期记忆为什么不工作

A: 当前 embedder 是 DummyEmbedder（基于 hash 的伪向量），不是真实语义嵌入。所以"长期记忆"功能当前没意义。架构已就位（SQLite + 向量索引 + 检索），等接入真实 embedder 即可用。

Q20. 多模态报错 `invalid image detail: auto (2013)`

A: 你的 OpenAI 兼容网关严格校验 detail 字段。代码已经主动不传这个字段（兼容 OpenAI 官方默认）。如果你还遇到，确认版本是 2026-06-14 之后，否则升级。

Q21. 我想本地跑（不接云端）

A: 当前不支持内嵌本地推理（历史上曾经用过 llama.cpp，已删除）。 推荐方案：本地起一个 OpenAI 兼容服务（Ollama / LM Studio / vLLM），把 base_url 填成 http://localhost:11434/v1，api_key 随便填一个字符串。模型名填你已经 ollama pull 的名字。

健康提醒

Q22. 提醒间隔太短，被轰炸

A: 默认 90s/180s 是开发用。打开托盘 → 健康提醒，把 remind_water 改 2700（45 min）、remind_stretch 改 3600（60 min）。

Q23. 怎么手动测一次通知（看通知能不能弹）

A: 当前 UI 没有专门的"测试"按钮。两种方式：

临时把 remind_test 间隔改成 5 秒，等 5 秒看
直接看托盘 → 健康提醒 → 列表里 remind_test 那条，编辑改间隔到 5 秒

Q24. 改了规则多久生效

A: 立即生效。点"确认"按钮后，后端 reload_all_behaviors 全量替换，当前 tick 就用新规则。

Q25. 系统通知不弹

A: 依次检查：

Linux：装 libnotify-bin（提供 notify-send 命令），手动跑一次 notify-send "test" "hello" 验证
macOS：系统设置 → 通知 → EzVibeR+ 允许通知
Windows：设置 → 系统 → 通知 → EzVibeR+ 开启

Q26. 22 点到 8 点还会被吵醒

A: 默认 quiet_hours_enabled = false，24h 都触发。编辑对应提醒把"是否启用静默时段"打开，"静默开始小时"填 22，"静默结束小时"填 8。

截图

Q27. 截图后整个聊天面板点不动了

A: 已修复（2026-06-19）。后端 set_focus() 在 show 之后立即调。确认版本是 2026-06-19 之后。如果还遇到：随便点一下桌宠窗口内任意位置拿回焦点。

Q28. 截图截到桌宠自己了

A: 不会。流程是 hide → sleep 250ms → 截图 → show。如果还截到桌宠，说明 WM（窗口管理器）合成太慢，250ms 不够——当前不支持配置。备用：截图前手动把桌宠拖到屏幕边缘外（玩笑）。

Q29. 截图失败"无可用截图方式"

Linux：sudo apt install imagemagick（虽然 Portal 优先，但 Portal 不可用时兜底要这个）
macOS / Windows：在系统设置里授权屏幕录制给 EzVibeR+
重启软件

Q30. 截图存哪了？磁盘满了

A: 存在 <app-data>/sessions/<当前会话 id>/images/，启动会自动 GC 孤儿。截图消息会一直引用，不会被 GC 删。清空方法：删整个会话（聊天面板 🗑）。

多会话 / 数据

Q31. 怎么导出某个对话

A: 工具栏点 🔍 展开工具栏 → ⬇ MD 或 ⬇ JSON → 浏览器下载。

Q32. 删了某个会话能恢复吗

A: 不能。删了就是删了，包括该会话的所有截图。记得提前导出。

Q33. 重启后某条消息的图片显示「截图加载中…」

A: 已修复（2026-06-19）。PersistedMessage 加了 #[serde(rename_all = "camelCase")] + alias 兼容。如果还遇到，确认版本是 2026-06-19 之后。旧 jsonl 用 snake_case 写入，新版用 camelCase，alias 双向兼容。

Q34. 换电脑后图片都不显示了

A: app-data 路径必须一致。你 app-data 在哪，新机器也放哪。改了用户名（如 /home/old/ → /home/new/）就坏。

Q35. 我能改消息的标题吗

A: 能，✎ 按钮重命名即可。提醒中心除外（系统保留）。

平台特定

Q36. macOS 启动后被 Gatekeeper 拒

A: 首次启动按住 Ctrl 点 EzVibeR+.app → 打开 → 确认。或：xattr -d com.apple.quarantine /Applications/EzVibeR+.app。

Q37. Windows Defender 报警

A: 未签名应用的正常现象。点"更多信息" → "仍要运行"。

Q38. Linux Wayland 下完全不能用

A: 不要设 EZVIBE_FORCE_WAYLAND=1（默认就是这个保护）。如果你设了，关掉：

# 启动时不要有这个变量
unset EZVIBE_FORCE_WAYLAND
npm run tauri:dev

或显式让软件走 X11：

GDK_BACKEND=x11 npm run tauri:dev

Q39. Linux 截图只截到 workspace 1

A: Wayland + mutter 下用 convert x:root 兜底时可能这样。首选 Portal 截图会自动跟随当前 workspace。Portal 失败才回退到 convert。检查 Portal 是否可用：which xdg-desktop-portal 应该有输出。装好 xdg-desktop-portal-gtk / -gnome / -kde（取决于你的 DE）。

Q40. 鼠标穿透怎么关回来

A: 一旦开启鼠标穿透，点不到桌宠了。只能：

右键托盘 → 显示桌宠（如果窗口在，会顶到最前 + 关掉穿透 — 但当前代码没关穿透，需要重启）
重启软件（最稳）

💡 这是一个小坑，尽量别点 🔒 穿透按钮。

如果你遇到这里没有列出的问题：

先重启软件（很多奇怪问题重启就好）
看终端 eprintln! 输出的 DEBUG_* 日志
看 ~/.live2D/live2d.conf.json 是不是被你手改坏了
实在不行删 ~/.live2D/live2d.conf.json 重启，自动重建默认配置

返回 00-README.md。

11 KiB Raw Permalink Blame History Unescape Escape