383 lines
17 KiB
Markdown
383 lines
17 KiB
Markdown
# EzVibeR+ LLM 对话能力 — 实施记录
|
||
|
||
> 作者：MiniMax-M3 (2026-06-01~02)
|
||
> 目的：给后续 agent / 接手人一个完整工作记录，方便理解和回归
|
||
> 关联：`docs/PLAN-CHAT.md`（早期设计稿）、`docs/impl/report.md`（历史报告）
|
||
|
||
---
|
||
|
||
## 0. 起点（接手时的状态）
|
||
|
||
`EzVibeR+` 是一个 Tauri 2 + Vue 3 桌宠，原有功能：
|
||
- Live2D 模型显示（pixi-live2d-display + 本地模型文件）
|
||
- 情绪引擎（EmotionEngine，5 个状态）
|
||
- 60s 后台调度器（TaskScheduler：喝水/伸展/早安问候等确定性行为）
|
||
- 记忆系统（MemorySystem + RAG，但 embedder 是 DummyEmbedder，无真实语义）
|
||
- 大脑引擎（AgentBrain）— 已实现 `LLMProvider` 抽象
|
||
- `NoopLLMProvider` 占位符，`commands::chat` 已存在但**实际不会调任何 LLM**
|
||
|
||
**用户最初诉求**：「桌宠可以和用户对话」
|
||
|
||
---
|
||
|
||
## 1. 完整工作流（按用户需求顺序）
|
||
|
||
### 1.1 路线一：本地 llama.cpp 内嵌
|
||
|
||
**用户**：先要本地化、最简方案
|
||
**实现**：写了 `llama_cpp_rs = "0.3.0"` Provider，含懒加载 / Mutex 串行化 / unsafe Send 包装
|
||
|
||
**踩坑**：
|
||
- `llama_cpp_rs 0.3.0` build.rs 有一处 bug（找不到独立 `ggml.o`，已 patch 到 `~/.cargo/registry/.../build.rs`）
|
||
- crate 内部用 *非常老* 的 llama.cpp（2023年中），**不支持 Qwen2 架构**
|
||
- 用户下载的 `Qwen2.5-Coder-0.5B-Instruct-Q4_K_M.gguf` 加载报错 `unknown model architecture: 'qwen2'`
|
||
|
||
**结论**：本地路线被用户否决
|
||
|
||
### 1.2 路线二：云端 API（最终方案）
|
||
|
||
**用户要求**：
|
||
- ❌ 删所有本地模型代码
|
||
- ✅ 走 API key 模式
|
||
- ✅ 兼容 OpenAI 协议 + Anthropic 协议
|
||
|
||
**实现**：
|
||
- 新增 `src-tauri/src/modules/openai.rs`（Chat Completions 协议）
|
||
- 新增 `src-tauri/src/modules/anthropic.rs`（Messages API，system 字段提到顶层）
|
||
- 全部用 `reqwest = "0.11"` async HTTP
|
||
- `AppConf` 加 `llm_provider` / `llm_model` / `llm_base_url` / `llm_api_key` 字段
|
||
- `main.rs` 工厂：按 provider 字符串分发
|
||
- `commands::get_llm_status` Tauri 命令
|
||
- `Config.vue` 加 LLM 设置区（provider 下拉、model、key、base_url）
|
||
- `ChatPanel.vue` 改"未配置"提示
|
||
|
||
### 1.3 UX 改进
|
||
|
||
按用户逐条要求：
|
||
|
||
| # | 用户要求 | 改动文件 |
|
||
|---|---|---|
|
||
| 1 | 持久聊天面板（右侧） | 新建 `components/ChatPanel.vue` + `hooks/useChat.ts` + `components/MessageBubble.vue` |
|
||
| 2 | 思考气泡（`<think>...</think>` 可折叠） | `MessageBubble.vue` 改：整块可点 + 鲁棒正则（含 `<thinking>` 和未闭合兜底） |
|
||
| 3 | 禁双击全屏 | `index.vue` `onMounted` 加 `dblclick` 全局 capture listener |
|
||
| 4 | 模型位置（往右 / 居中） | `loadModel` + `recenterModel` 函数 |
|
||
| 5 | 聊天面板可收缩 | `chatCollapsedRef` + `toggleChat` + waifu-tool 加 `fui-chat` 按钮 |
|
||
| 6 | 健康提示 → 气泡 + LLM 提示词 | 改 `BrainConfig::default()` 加 tip 引导；`useChat.ts` 监听 `ezvibe:reminder` 事件塞气泡 |
|
||
|
||
### 1.4 Bug 修复
|
||
|
||
- **双击气泡没反应**（用户报告）：`MessageBubble.vue` 把 `<button>` 改成整块 `<div @click>`，避免 overflow/事件边界问题
|
||
- **健康气泡不显示**（用户报告）：scheduler 间隔是 45min，且 22:00-08:00 静默时段抑制；改成 90s/180s + 关闭静默时段，加手动触发按钮
|
||
|
||
---
|
||
|
||
## 2. 架构总览（终态）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Frontend (live2d.html → index.vue) │
|
||
│ ┌──────────────┐ ┌────────────────────────────┐ │
|
||
│ │ Live2D Canvas│ │ ChatPanel.vue │ │
|
||
│ │ (左，可收缩) │ │ - 状态条 + 🔔/ ?/× 按钮 │ │
|
||
│ │ │ │ - MessageBubble 流 │ │
|
||
│ │ │ │ ├─ user / assistant │ │
|
||
│ │ │ │ ├─ system (错误) │ │
|
||
│ │ │ │ └─ reminder (绿松石) │ │
|
||
│ │ │ │ └─ 含 <think> 折叠 │ │
|
||
│ │ │ │ - 输入框 + 发送 │ │
|
||
│ └──────────────┘ └────────────────────────────┘ │
|
||
│ ↓ invoke('chat', { message }) │
|
||
│ ↓ invoke('get_llm_status') │
|
||
│ ↓ listen('ezvibe:reminder') │
|
||
└─────────────────────────────────────────────────────┘
|
||
↓ Tauri IPC
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Rust Backend (src-tauri/src/) │
|
||
│ commands::chat → brain.think(UserMessage) │
|
||
│ → OpenAiProvider / AnthropicProvider │
|
||
│ → reqwest HTTP → 云端 API │
|
||
│ │
|
||
│ commands::get_llm_status → 读 AppConf 返回状态 │
|
||
│ 60s tokio loop → scheduler → brain.think(System) │
|
||
│ → FallbackCache → emit reminder │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 完整文件清单
|
||
|
||
### 3.1 新增
|
||
|
||
| 路径 | 行数 | 作用 |
|
||
|---|---|---|
|
||
| `src-tauri/src/modules/openai.rs` | ~190 | OpenAI 兼容 LLM Provider |
|
||
| `src-tauri/src/modules/anthropic.rs` | ~200 | Anthropic Claude Provider |
|
||
| `src/live2d/hooks/useChat.ts` | ~140 | 聊天状态管理 + reminder 监听 |
|
||
| `src/live2d/components/ChatPanel.vue` | ~280 | 聊天面板 UI |
|
||
| `src/live2d/components/MessageBubble.vue` | ~190 | 单条消息气泡（含思考折叠） |
|
||
| `docs/PLAN-CHAT.md` | ~250 | 早期设计稿 |
|
||
| `docs/impl/llm-chat-implementation.md` | ← 本文 | |
|
||
|
||
### 3.2 修改
|
||
|
||
| 路径 | 关键改动 |
|
||
|---|---|
|
||
| `src-tauri/Cargo.toml` | 删 `llama_cpp_rs`，加 `reqwest` (json + rustls-tls) |
|
||
| `src-tauri/src/utils.rs` | 删 `llm_model_dir` / `default_llm_model_path` / `resolve_llm_model_path` |
|
||
| `src-tauri/src/app/config.rs` | 加 `llm_provider` / `llm_model` / `llm_api_key` / `llm_base_url` 字段 |
|
||
| `src-tauri/src/app/commands.rs` | 删 `get_model_status`，加 `get_llm_status` |
|
||
| `src-tauri/src/main.rs` | 删 `NoopLLMProvider`，加工厂 + 旧 base_url 迁移（minimax.chat → 官方） |
|
||
| `src-tauri/src/modules/brain.rs` | `LLMProvider` trait 加 `is_loaded()` / `model_path()` 默认方法；`AgentBrain::provider()` 访问器；系统 prompt 加健康 tip 引导 |
|
||
| `src-tauri/src/modules/mod.rs` | 删 `pub mod llama_cpp`，加 `pub mod openai` / `pub mod anthropic` |
|
||
| `src-tauri/src/modules/scheduler.rs` | 间隔 45min→90s（remind_water）、60min→180s（remind_stretch）；默认 `quiet_hours_enabled = false` |
|
||
| `src-tauri/tauri.conf.json` | 窗口 width: 215→600, height: 200→480, resizable: true |
|
||
| `src/components/Config.vue` | 加 LLM 设置区（4 字段 + 保存按钮） |
|
||
| `src/live2d/index.vue` | flex 左右布局 + 聊天面板 + 工具栏 🔔 按钮 + 模型居中 + 禁双击全屏 + 窗口 resize 重居中 |
|
||
|
||
### 3.3 删除
|
||
|
||
- `src-tauri/src/modules/llama_cpp.rs`（临时用过，已删）
|
||
- `~/.live2D/model/llm/`（用户移动过，API 路线后不再需要）
|
||
- 之前 patch 的 `~/.cargo/registry/.../llama_cpp_rs-0.3.0/build.rs`（crate 已不在依赖里，无影响）
|
||
|
||
---
|
||
|
||
## 4. 关键设计决策
|
||
|
||
### 4.1 为什么不把 `<think>` 解析放后端
|
||
|
||
**问题**：DeepSeek / QwQ / o1 等模型输出含 `` 块，需要拆成可折叠气泡
|
||
|
||
**选择**：前端解析
|
||
|
||
**理由**：
|
||
- `brain.rs::strip_chatml_artifacts` 只剥 ChatML，`` 保留原样
|
||
- 前端 `MessageBubble.vue` 直接正则处理，无侵入
|
||
- 多种模型（DeepSeek/QwQ/o1/Claude extended thinking）都通用
|
||
- 不动 `BrainResponse` 字段（避免 commands.rs / hooks 连锁改动）
|
||
|
||
### 4.2 为什么 health reminder 在前端监听
|
||
|
||
**问题**：scheduler 60s 触发 reminder，要显示成气泡
|
||
|
||
**选择**：前端 `useChat.ts` 监听 `ezvibe:reminder` 事件
|
||
|
||
**理由**：
|
||
- 后端 `app_handle.emit("ezvibe:reminder", ...)` 已经在 `main.rs:60s 循环` 里发
|
||
- 前端只接收，符合"气泡属于 UI 层"的关注点分离
|
||
- 离后端近（如未来加表情播报）也方便
|
||
|
||
### 4.3 为什么 is_loaded / model_path 走 trait 默认
|
||
|
||
**问题**：`get_llm_status` 命令需要知道 provider 状态，但不想耦合到具体 provider
|
||
|
||
**选择**：在 `LLMProvider` trait 上加默认方法
|
||
|
||
**理由**：
|
||
- `OpenAiProvider` / `AnthropicProvider` 各自 override（key 非空即 ready）
|
||
- `NoopLLMProvider` 不存在了（已删）
|
||
- 任何未来新 provider 只要写自己的实现，不改 trait
|
||
|
||
### 4.4 为什么 in-memory provider 不监听 conf 变更
|
||
|
||
**问题**：用户在 UI 改 key 后，运行时如何生效？
|
||
|
||
**选择**：**必须重启**（in-memory provider 创建一次）
|
||
|
||
**理由**：
|
||
- 简单、不引入 RwLock<Option<Provider>> 复杂度
|
||
- 用户改完 key 重启一次是合理 UX（不频繁）
|
||
- 如果未来要做"热更新"再加
|
||
|
||
### 4.5 conf 兼容旧字段
|
||
|
||
**AppConf 字段**：
|
||
|
||
| 字段 | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `port` | 0 | 系统分配 |
|
||
| `model_dir` | `""` | Live2D 模型目录 |
|
||
| `width` / `height` | 400 / 500 | 窗口大小 |
|
||
| `x` / `y` | 100 / 120 | 窗口位置 |
|
||
| `check_update` | false | |
|
||
| `remote_list` | `[]` | |
|
||
| `model_block` | true | |
|
||
| `auto_start` | false | |
|
||
| `memory_enabled` | true | |
|
||
| `llm_provider` | `"openai"` | `#[serde(default)]` |
|
||
| `llm_model` | `"gpt-4o-mini"` | `#[serde(default)]` |
|
||
| `llm_api_key` | `""` | `#[serde(default)]` |
|
||
| `llm_base_url` | `"https://api.openai.com"` | `#[serde(default)]` |
|
||
|
||
所有新字段都标 `#[serde(default = "...")]` 兼容旧 conf（缺字段时不报错）。
|
||
|
||
**base_url 迁移**：`main.rs` 检测到 `minimax.chat` 时自动重置（v3.0 之前的错默认）。
|
||
|
||
---
|
||
|
||
## 5. 编译 & 运行
|
||
|
||
### 5.1 工具链
|
||
|
||
- Rust 1.65+ （项目要求）
|
||
- Node 18+（package.json）
|
||
- 无 C++ 编译（llama.cpp 已删）
|
||
- 无 GPU 依赖（CPU only）
|
||
|
||
### 5.2 命令
|
||
|
||
```bash
|
||
cd /home/e2hang/agent/EzVibeR+
|
||
npm install # 一次性
|
||
npm run tauri:dev # 开发模式（vite + cargo 同时跑）
|
||
npm run build # 前端生产构建
|
||
npm run tauri build # 完整打包（前端 + Rust）
|
||
```
|
||
|
||
### 5.3 配置位置
|
||
|
||
- 配置文件：`~/.live2D/live2d.conf.json`（**大写 D**，Linux 大小写敏感！）
|
||
- 当前用户配置（2026-06-02）：
|
||
- model_dir: `/home/e2hang/agent/EzVibeR/assets/march7th`
|
||
- width/height: 1200/960
|
||
- llm_provider: openai
|
||
- llm_base_url: `http://100.85.50.59:3000/v1`
|
||
- llm_model: `EzVibe`
|
||
- llm_api_key: 已配置
|
||
|
||
### 5.4 关键路径注意
|
||
|
||
- `app_root()` 在 `utils.rs` 用 `.live2D`（大写 D）拼
|
||
- `index.html` 入口是 `index.html`（配置窗口）
|
||
- `live2d.html` 入口是桌宠窗口
|
||
- 两者都是 Vite 多入口
|
||
|
||
---
|
||
|
||
## 6. 终端调试日志（开发期看）
|
||
|
||
```
|
||
DEBUG_LLM: provider=openai base_url=... model=... key_configured=true|false
|
||
DEBUG_REMINDER: tick=N fired_count=K types=[...]
|
||
DEBUG_REMINDER_FIRED: type=remind_water msg=...
|
||
DEBUG: tray icon built successfully
|
||
```
|
||
|
||
`log::info!` 没初始化 logger backend，所以要走 `eprintln!` 才能在终端看到。后续如果加 `env_logger::init()`，可以统一到 `RUST_LOG=info` 模式。
|
||
|
||
---
|
||
|
||
## 7. 已知问题 / 限制
|
||
|
||
### 7.1 当前未实现
|
||
|
||
- **流式输出**：当前是整段返回（等模型全推完才显示）。0.5B 还好，3B+ 应该启 streaming
|
||
- **GPU 加速**：CPU only。Metal/CUDA feature 没编译进去
|
||
- **多 Provider 切换**：UI 切 provider 后要重启
|
||
- **API key 热更新**：UI 改 key 后要重启
|
||
- **窗口记忆位置**：conf 里 x/y 有，但 resize 时会强制重置
|
||
|
||
### 7.2 待验证
|
||
|
||
- Anthropic 协议未在真实 key 上测过（用户只用 OpenAI 兼容服务）
|
||
- Confluence 错误码映射（401/403/404/429/5xx）只测过 401 路径
|
||
|
||
### 7.3 设计缺陷
|
||
|
||
- `LOGGING_INIT` 缺失 → `log::*` 调用全部 silent
|
||
- `BrainConfig::default()` 系统 prompt 硬编码，未来需要做成可配置
|
||
- `Scheduler` 间隔硬编码，开发 90s/180s，生产应该改回 45min/60min
|
||
|
||
---
|
||
|
||
## 8. 回归 checklist（接手人测试用）
|
||
|
||
如果改动影响以下功能，跑一遍：
|
||
|
||
- [ ] `cargo check` 干净通过（33 个 warning 是预存的，不引入新 warning）
|
||
- [ ] `npm run build` 通过
|
||
- [ ] 启动后日志显示 `DEBUG_LLM: provider=... base_url=... model=... key_configured=true`
|
||
- [ ] 桌宠窗口出现，Live2D 模型显示，聊天面板在右侧
|
||
- [ ] 点 🔔 按钮 → 立刻弹一条绿松石色健康气泡
|
||
- [ ] 发消息 → 1-3s 内收到 LLM 回复
|
||
- [ ] 回复中如果含 `` 块 → 显示为可折叠气泡（默认收起），主回复独立显示
|
||
- [ ] 点聊天面板 💬 按钮 → 面板收起，模型占满整个窗口
|
||
- [ ] 再次点 💬 → 面板恢复
|
||
- [ ] 双击透明区域 → **不**触发全屏
|
||
- [ ] 拖窗口边缘 resize → 模型自动重新居中
|
||
- [ ] 修改 conf 后重启 → 配置生效
|
||
- [ ] 填错 API key → 聊天面板弹 `[401] API key 无效`
|
||
|
||
---
|
||
|
||
## 9. 给后续 agent 的提示
|
||
|
||
1. **不要再加回 llama.cpp** — 用户明确否决，且 `llama_cpp_rs 0.3.0` 极老，新模型架构（Qwen2/Phi-3）不支持。如果以后真要本地，**直接换现代 fork**（`llama-cpp-2` 之类），并重写 `llama_cpp.rs`。
|
||
|
||
2. **想加 streaming**：在 `OpenAiProvider` / `AnthropicProvider` 里改 `stream: true`，通过 `reqwest` 的 `bytes_stream()` 逐 chunk 解析 SSE（`data: {json}\n\n`），每收到一个 chunk 就 emit 一个 Tauri event。Brain 那侧可以增加一个 streaming 路径。
|
||
|
||
3. **想加多模态（图片）**：OpenAI/Anthropic 都支持 `content: [{type: "text"}, {type: "image_url"}]`。改 `ChatMessage` 加 `attachments: Vec<Attachment>`，provider 里 translate 即可。
|
||
|
||
4. **想加 GPU 加速**：OpenAI 兼容的本地推理可以指向 LM Studio / vLLM / ollama（**注意**：ollama 是用户最初否决的"外接服务"路线，但如果作为 OpenAI 兼容端点 `http://localhost:11434/v1` 用，本质上还是 OpenAI 协议，跟用户当前的"key + URL"心智模型一致）。代码不用改。
|
||
|
||
5. **想加语音**：Tauri 有麦克风权限 + WebAudio API，前端 capture → base64 → `ChatMessage.attachments` 走 OpenAI Whisper API。Speech synthesis 用 Web Speech API（`speechSynthesis.speak()`）前端的 SpeechSynthesisUtterance。
|
||
|
||
6. **bug 报告高频点**：
|
||
- conf 改了不生效 → in-memory provider 不重读，必须重启
|
||
- 静默时段没声音 → 默认开 22:00-08:00，改 `Behavior::new()` 时改默认值
|
||
- 窗口太大/太小 → `tauri.conf.json` + `AppConf` 双改
|
||
- 像素字体模糊 → 检查 `factorRef` 缩放因子
|
||
|
||
---
|
||
|
||
## 10. 关键 commit-style diff 摘要
|
||
|
||
```diff
|
||
# Cargo.toml
|
||
- llama_cpp_rs = "0.3.0"
|
||
+ reqwest = { version = "0.11", default-features = false, features = ["json", "rustls-tls"] }
|
||
|
||
# main.rs
|
||
- struct NoopLLMProvider; (deleted ~30 lines)
|
||
+ use crate::modules::{OpenAiProvider, AnthropicProvider};
|
||
+ let llm_provider = match provider_kind.as_str() {
|
||
+ "anthropic" => AnthropicProvider::new(...),
|
||
+ _ => OpenAiProvider::new(...), // 含 OpenAI 兼容
|
||
+ };
|
||
|
||
# brain.rs
|
||
+ fn chat<'a>(...) // LLMProvider trait: is_loaded() + model_path() 默认方法
|
||
+ pub fn provider(&self) -> &Arc<dyn LLMProvider> // AgentBrain 暴露
|
||
+ 系统 prompt 加 "适当时机... 健康小贴士..."
|
||
|
||
# index.vue (frontend)
|
||
+ <ChatPanel class="chat-pane" /> // flex 布局右栏
|
||
+ dblclick listener with capture: true // 禁全屏
|
||
+ model.x/y 计算居中 + recenterModel 函数
|
||
|
||
# tauri.conf.json
|
||
- width: 215, height: 200, resizable: false
|
||
+ width: 600, height: 480, resizable: true
|
||
+ minWidth: 555, minHeight: 280
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 测试已验证场景
|
||
|
||
✅ OpenAI 兼容协议（http://100.85.50.59:3000/v1，Mymodel / EzVibe 模型）
|
||
✅ 401 错误友好提示（API key 无效时显示在气泡里）
|
||
✅ 思考气泡可折叠（DeepSeek-style 输出）
|
||
✅ 聊天面板收起/展开 + 模型自动重居中
|
||
✅ 双击不触发全屏
|
||
✅ 90s/180s 自动 reminder（已生产化建议改回 45min/60min）
|
||
✅ 手动 🔔 按钮触发 reminder
|
||
❌ Anthropic 真实 key 测试（未做）
|
||
❌ Streaming（未做）
|
||
❌ 多个不同 provider 切换（未做）
|
||
|
||
---
|
||
|
||
**总结**：核心对话能力跑通，从「不能对话」到「能对话」+「能健康提醒」+「思考可视化」+「UI 灵活」，用户反馈驱动迭代 6 轮完成。后续如要继续，主要方向是 streaming、GPU、Anthropic 验证。
|