EzVibeR/docs/impl/llm-chat-implementation.md

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> 复杂度
• 用户改完 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 命令

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 摘要

# 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 验证。