215 lines
11 KiB
Markdown
215 lines
11 KiB
Markdown
# 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](https://github.com/tauri-apps/tauri/issues/13121)）。
|
||
**软件默认会自动** `set_var("GDK_BACKEND", "x11")` 强制走 XWayland。
|
||
如果你**主动**设了 `EZVIBE_FORCE_WAYLAND=1` 就跳过了这个保护 → 关掉。
|
||
其他情况：
|
||
- KDE 也有类似问题，但概率小
|
||
- 关闭桌宠后从托盘恢复时**有时**属性会丢，再点一次托盘「显示桌宠」就行
|
||
|
||
### Q3. 桌宠关闭后从托盘恢复位置变了 / 尺寸变了
|
||
A: **预期行为**。当前版本不记忆关闭前的精确位置。窗口默认按 `live2d.conf.json` 的 `width/height/x/y` 建。手工调一次大小后会自动存盘。
|
||
> 跨 workspace 重建（拖完关 → 重建）有 [Tauri#14913](https://github.com/tauri-apps/tauri/issues/14913) bug，**当前没有干净 workaround**。
|
||
|
||
### Q4. 关了桌宠窗口想完全退出软件
|
||
A: **托盘 → 关闭软件**。
|
||
> 桌宠窗口右上角 ❌ 按钮 / 任务栏右键关闭**只是隐藏窗口**，软件在托盘继续跑。
|
||
|
||
### Q5. 托盘图标消失了
|
||
A:
|
||
- **Linux**：检查 `libappindicator` 装了没；KDE 用户可能要装 `libappindicator-gtk3`；GNOME 需要装扩展 [AppIndicator Support](https://extensions.gnome.org/extension/615/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: 三个常见原因：
|
||
1. 你的模型没那么多表情/动作 → 配置中心 → 「🎭 当前 Live2D 模型能力」看实际有哪些
|
||
2. 关键词没匹配上 → 改模型的表情名（中文优先）或加新动作
|
||
3. 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: 三选一：
|
||
1. 真的没填 → 配置中心填上
|
||
2. 填了但没重启 → **必须重启**（见 [07-LLM对话.md §5.1](07-LLM对话.md)）
|
||
3. 填了重启了还是红 → 检查 `live2d.conf.json` 里的 `llm_api_key` 字段**没有前后空格**
|
||
|
||
### Q13. 发消息没反应 / 一直「思考中…」
|
||
A: 检查顺序：
|
||
1. 终端有没有 `[401] API key 无效` → 重新填 key
|
||
2. 终端有没有 `无法连接到 API 服务` → 网络/代理问题，见 Q14
|
||
3. 终端有没有 `请求超时` → LLM 端点太慢，换个端点或检查网络
|
||
4. 终端有没有 `Brain reminder failed` → 是 reminder 报错，不是对话。**和聊天无关**
|
||
|
||
### Q14. 在 clash-verge / sing-box 后面连接超时
|
||
A: 已知现象：Tailscale / 内网 IP 会被代理劫持到外网节点。
|
||
**软件已经强制 `no_proxy()`**，但**你的系统环境变量**（`HTTP_PROXY` 等）如果已经设了，覆盖不到 `reqwest` 内部。临时方案：
|
||
```bash
|
||
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 **没有专门的"测试"按钮**。两种方式：
|
||
1. 临时把 `remind_test` 间隔改成 5 秒，等 5 秒看
|
||
2. 直接看托盘 → 健康提醒 → 列表里 `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. 截图失败"无可用截图方式"
|
||
A:
|
||
- **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`（默认就是这个保护）。如果你设了，关掉：
|
||
```bash
|
||
# 启动时不要有这个变量
|
||
unset EZVIBE_FORCE_WAYLAND
|
||
npm run tauri:dev
|
||
```
|
||
或显式让软件走 X11：
|
||
```bash
|
||
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: 一旦开启鼠标穿透，**点不到桌宠了**。只能：
|
||
- **右键托盘 → 显示桌宠**（如果窗口在，会顶到最前 + 关掉穿透 — 但当前代码没关穿透，需要重启）
|
||
- **重启软件**（最稳）
|
||
|
||
> 💡 这是一个**小坑**，尽量**别点 🔒 穿透按钮**。
|
||
|
||
---
|
||
|
||
如果你遇到这里没有列出的问题：
|
||
1. 先重启软件（很多奇怪问题重启就好）
|
||
2. 看终端 `eprintln!` 输出的 `DEBUG_*` 日志
|
||
3. 看 `~/.live2D/live2d.conf.json` 是不是被你手改坏了
|
||
4. 实在不行删 `~/.live2D/live2d.conf.json` 重启，自动重建默认配置
|
||
|
||
返回 [00-README.md](00-README.md)。
|