Merge branch 'dev'

Author: t41372

.gitignore

@@ -1,15 +1,16 @@
 # Dependencies
-/node_modules
+node_modules/
 
 # Production
-/build
+build/
 
 # Generated files
 .docusaurus
 .cache-loader
 
 # Misc
 .DS_Store
+.env
 .env.local
 .env.development.local
 .env.test.local
@@ -18,3 +19,7 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+.cursorrules
+
+# Ignore all dist directories
+dist/

ai_prompt_gen/ai_prompt.md

@@ -185,9 +185,3 @@ Error calling the chat endpoint
 - 需要不断点击才能使说话功能正常运行
 - 详细说明请参考[模式介绍](./user-guide/frontend/mode.md)
 
-### Electron 应用切换模式导致屏幕一片空白怎么办
-- 属于小概率难以修复的 bug，实测几乎不会触发。
-- 等待几秒，或者重启应用即可解决。
-
-### 模型表情无法显示怎么办
-

docs/faq.md

@@ -15,17 +15,17 @@ sidebar_position: 1
 本项目仍处于早期阶段，目前正在**积极开发中**。
 :::
 
-**Open-LLM-VTuber** 是一款独特的**语音交互 AI 伴侣**，它不仅支持**实时语音对话**和**视觉感知**，还配备了生动的 **Live2D 形象**。所有功能都可以在你的电脑上完全离线运行！
+**Open-LLM-VTuber** 是一款功能强大的**语音交互 AI 伴侣**，它不仅支持**实时语音对话**、**视觉感知**和**多工具调用**，还配备了生动的 **Live2D 形象 (支持 Cubism 5)**。它甚至可以**控制你的浏览器**为你执行任务，并接入**直播平台**与观众互动！所有核心功能都可以在你的电脑上完全离线运行！
 
-你可以把它当作你的专属 AI 伴侣 —— 无论你想要一个`虚拟女友`、`男友`、`萌宠`还是其他角色，它都能满足你的期待。项目完美支持 `Windows`、`macOS` 和 `Linux` 系统，并提供两种使用方式：网页版和桌面客户端（特别支持**透明背景的桌宠模式**，让 AI 伴侣在屏幕上的任意位置时刻陪伴着你）。
+你可以把它当作你的专属 AI 伴侣 —— 无论你想要一个`虚拟女友`、`男友`、`智能助手`还是其他角色，它都能满足你的期待。项目完美支持 `Windows`、`macOS` 和 `Linux` 系统，并提供两种使用方式：网页版和桌面客户端（支持中文界面，并提供**透明背景的桌宠模式**）。
 
-虽然长期记忆功能暂时下线（即将回归），但得益于聊天记录的持久化存储，你随时都能继续之前未完的对话，不会丢失任何珍贵的互动瞬间。
+借助基于 **Letta** 的**长期记忆**系统和聊天记录持久化存储，AI 能够记住过去的对话，让你随时都能继续之前未完的对话，不会丢失任何珍贵的互动瞬间。
 
-在后端支持方面，我们集成了丰富多样的 LLM 对话引擎、文本转语音模型和语音识别方案。如果你想让 AI 伴侣更有个性，还可以参考 [角色定制指南](https://open-llm-vtuber.github.io/docs/user-guide/live2d) 来自定义专属的 AI 伴侣形象和人设。
+我们集成了丰富多样的 LLM、TTS、ASR 方案，并支持通过 **MCP 协议**调用外部工具（如网络搜索、时间查询等）。如果你想让 AI 伴侣更有个性，还可以参考 [角色定制指南](user-guide/live2d) 来自定义专属的 AI 伴侣形象和人设。
 
 关于为什么叫 `Open-LLM-Vtuber` 而不是 `Open-LLM-Companion` 或者 `Open-LLM-Waifu`，是因为项目的开发初衷是采用可在 Windows 以外平台离线运行的开源方案，复现闭源的 AI Vtuber `neuro-sama`。
 
-本项目在 `v1.0.0` 版本后进行了代码重构，目前正处于积极开发阶段，未来还有许多令人兴奋的功能即将推出！🚀 查看我们的 [Roadmap](https://github.com/users/t41372/projects/1/views/5)，了解更新计划。
+本项目正处于积极开发阶段，未来还有许多令人兴奋的功能即将推出！🚀 查看我们的 [Roadmap](https://github.com/users/t41372/projects/1/views/5)，了解更新计划。
 
 
 ## 👀 效果演示
@@ -47,30 +47,33 @@ sidebar_position: 1
 - 💻 **好看且功能强大的网页和桌面客户端**：提供网页版和桌面客户端两种使用方式，支持丰富的交互功能和个性化设置，桌面客户端还可以在窗口模式和桌宠模式之间自由切换，让 AI 伴侣随时陪伴在身边
 
 - 🎯 **高级交互功能**：
-  - 👁️ 视觉感知，支持摄像头、屏幕录制和截图，让 AI 伙伴能看到你和你的屏幕
-  - 🎤 语音打断，无需耳机（AI 不会听到自己的声音）
-  - 👥 群组聊天，支持多个 AI 角色同时参与对话交互
-  - 🫱 触摸反馈，可以通过点击或拖拽与 AI 伙伴互动
-  - 😊 Live2D 表情，设置情绪映射让后端控制模型表情
-  - 🐱 宠物模式，支持透明背景全局置顶和鼠标穿透 - 可以将你的 AI 伙伴拖到屏幕上的任意位置
-  - 🗣️ AI 主动说话功能
-  - 💭 AI 内心 OS，AI 的表情、想法和动作可以被看到，但不会被读出来
-  - 💾 聊天记录持久化，可以随时切换到以前的对话
-  - 🌍 TTS 翻译支持（例如，用中文聊天的同时，AI 使用日语声音）
+  - 👁️ **视觉感知**：支持摄像头、屏幕录制和截图，让 AI 伙伴能看到你和你的屏幕。
+  - 🛠️ **工具调用 (MCP 支持)**：AI 可以调用支持 MCP 协议的外部工具（如搜索、时间查询）来完成任务，前端实时显示工具调用状态。
+  - 🌐 **浏览器控制**：AI 可以操作浏览器执行任务，并支持在前端实时查看浏览器画面。
+  - 🔴 **直播对接**：内置 BiliBili 直播客户端，可接收弹幕并与观众互动。也可以灵活实现接口，接入其他直播平台或者制定自己的弹幕处理逻辑。
+  - 🧠 **长期记忆**：基于 Letta 实现长期记忆，让 AI 记住过去的对话。
+  - 🎤 **语音打断**：无需耳机即可打断 AI 发言（AI 不会听到自己的声音）。
+  - 👥 **群组聊天**：支持多个 AI 角色同时参与对话交互。
+  - 👆 **Live2D 交互 (Cubism 5)**：支持最新的 Cubism 5 模型，通过点击与 AI 伙伴互动，表情可通过后端控制。
+  - 🐱 **桌宠模式**：支持透明背景、全局置顶和鼠标穿透 - 可以将你的 AI 伙伴拖到屏幕上的任意位置
+  - 🗣️ **AI 主动说话**：AI 可以根据设定主动发起对话。
+  - 🤔 **AI 内心 OS**：AI 的表情、想法和动作可以被看到，但不会被读出来。
+  - 💾 **聊天记录持久化**：可以随时切换到以前的对话。
+  - 🌍 **TTS 翻译支持**：例如，用中文聊天的同时，AI 使用日语声音。
 
 - 🧠 **广泛的模型支持**：
-  - 🤖 大语言模型 (LLM)：Ollama、OpenAI（以及任何与 OpenAI 兼容的 API）、Gemini、Claude、Mistral、DeepSeek、智谱、GGUF、LM Studio、vLLM 等
-  - 🎙️ 语音识别 (ASR)：sherpa-onnx、FunASR、Faster-Whisper、Whisper.cpp、Whisper、Groq Whisper、Azure ASR等
-  - 🔊 语音合成 (TTS)：sherpa-onnx、pyttsx3、MeloTTS、Coqui-TTS、GPTSoVITS、Bark、CosyVoice、Edge TTS、Fish Audio、Azure TTS等
+  - 🤖 **大语言模型 (LLM)**：Ollama、OpenAI（及兼容 API）、Gemini、Claude、Mistral、DeepSeek、智谱、GGUF、LM Studio、vLLM 等。
+  - 🎙️ **语音识别 (ASR)**：sherpa-onnx、FunASR、Faster-Whisper、Whisper.cpp、Whisper、Groq Whisper、Azure ASR 等。
+  - 🔊 **语音合成 (TTS)**：sherpa-onnx、pyttsx3、MeloTTS、Coqui-TTS、GPTSoVITS、Bark、CosyVoice、Edge TTS、Fish Audio、Azure TTS、OpenAI TTS (及兼容 API)、SparkTTS 等。
 
-- 🔧 **高度可定制**:
-  - ⚙️ **简单的模块配置**：通过简单的配置文件修改，即可切换各种功能模块，无需深入代码
-  - 🎨 **角色随心定制**：导入自定义 Live2D 模型，让你的 AI 伴侣拥有独特外观。通过修改 Prompt，塑造你 AI 伴侣的人设。进行音色克隆，让你的 AI 伴侣有着你想要的声线
-  - 🧩 **Agent自由实现**：继承并实现 Agent 接口，接入任何架构的 Agent，如 HumeAI EVI、OpenAI Her、Mem0 等
-  - 🔌 **良好的可扩展性**：模块化设计让你能轻松添加自己的 LLM、ASR、TTS 等模块实现，随时扩展新特性
+- 🔧 **高度可定制**：
+  - ⚙️ **简单的模块配置**：通过简单的配置文件修改，即可切换各种功能模块，无需深入代码。
+  - 🎨 **角色随心定制**：导入自定义 Live2D 模型，让你的 AI 伴侣拥有独特外观。通过修改 Prompt，塑造你 AI 伴侣的人设。进行音色克隆，让你的 AI 伴侣有着你想要的声线。
+  - 🧩 **Agent自由实现**：继承并实现 Agent 接口，接入任何架构的 Agent，如 HumeAI EVI、OpenAI Her、Mem0 等。
+  - 🔌 **良好的可扩展性**：模块化设计让你能轻松添加自己的 LLM、ASR、TTS、MCP 工具等模块实现，随时扩展新特性。
 
 
 ## 👥 用户评价
 > 感谢开发者把女朋友开源分享出来让大家一起使用
-> 
+>
 > 该女友使用次数已达 10w+

docs/intro.md

@@ -23,7 +23,7 @@ import TabItem from '@theme/TabItem';
 :::
 
 :::warning
-本项目只推荐使用 **Chrome 浏览器**。已知 Edge、Safari 等浏览器都存在不同的问题，比如模型表情无法使用。
+本项目只推荐使用 **Chrome 浏览器**。已知 Edge、Safari 等浏览器都存在不同的问题。
 :::
 
 :::danger 关于代理
@@ -214,7 +214,67 @@ nvcc --version
 从 v1.0.0 版本开始，我们推荐使用 [uv](https://docs.astral.sh/uv/) 作为依赖管理工具。
 
 :::note
-如果你更希望使用 conda 或 venv，也可以使用这些工具。项目完全兼容标准的 pip 安装方式。
+如果你更希望使用 conda 或 venv，也可以使用这些工具。项目自`v1.2.0` 起完全兼容标准的 pip 安装方式。
+
+关于 pip 与 conda 的指南与注意事项
+<details>
+uv 是这个项目的依赖管理工具，我推荐使用 uv。
+
+conda，pip，以及其他的依赖管理工具也可以用，但我们不会测试这些工具，也不会回答这些工具产生的问题 (因为我们 v1.0.0 版本之前用的是 conda，问 python 相关问题的人真的好多啊呱！)。
+
+如果你一定要用，非用不可，请在使用这些工具时重点关注 Python 版本，虚拟环境使用的 Python 执行档等问题，我们在迁移到 uv 之前有很多，很多人遇到了各种各样的问题。
+
+确保你的 Python 版本 >= 3.10, < 3.13。我不确定当前版本与 3.13 的兼容性，你可以试试。
+
+#### 使用 pip 安装项目依赖
+
+> (项目版本 `v1.2.0` 添加)
+
+```sh
+pip install -r requirements.txt
+```
+- 这个 `requirements.txt` 是根据 `pyproject.toml` 文件自动生成出来的，可能会把依赖绑的比较紧。如果出现问题，可以参考 `pyproject.toml` 中声明的依赖版本，自行松绑。亦或是改用 uv 或其他支持以 `pyproject.toml` 声明依赖的工具。
+
+或是
+```sh
+pip install -e .
+```
+- 这个命令会用 pyproject.toml 文件安装依赖，但会把项目本身也一起安装到环境中，我感觉项目更新时有可能会出问题，但我不确定。
+
+
+然后运行项目
+
+```sh
+python run_server.py
+```
+
+之后文档中出现的任何 `uv add`, `uv remove` 命令，可以直接代替换成 `pip install`, `pip uninstall` 等命令。
+
+#### conda
+1. 在当前目录下，创建 conda 环境
+```sh
+conda create -p "./.conda" python=3.10.6
+```
+
+2. 激活这个 conda 环境
+```sh
+conda activate ./.conda
+```
+
+3. 用 pip 安装项目依赖
+```sh
+pip install -r requirements.txt
+```
+
+4. 运行项目
+```sh
+python run_server.py
+```
+
+之后文档中出现的任何 `uv add`, `uv remove` 命令，可以直接代替换成 `pip install`, `pip uninstall` 等命令。
+
+</details>
+
 :::
 
 <Tabs groupId="operating-systems">
@@ -280,7 +340,7 @@ source ~/.zshrc   # 如果使用 zsh
   如果你想要使用桌宠模式或是桌面版本，你可以顺手再下载以 `open-llm-vtuber-electron` 开头的文件。windows 用户下载 exe，macOS 用户下载 dmg文件。这个是桌面版本的客户端。之后等后端配置完成并启动之后，这个electron 版前端可以启动桌宠模式。
 
   </TabItem>
-  <TabItem value="git" label="git 命令拉取">
+  <TabItem value="git" label="Git 命令拉取">
   :::warning
   使用 git 拉取时，请确保网络畅通。中国大陆用户可能需要开启代理。
   :::
@@ -373,7 +433,9 @@ uv run run_server.py
 然后按下 `Ctrl` + `C` 退出程序。
 
 :::info
-`v1.1.0` 版本开始，`conf.yaml` 文件可能不会自动出现在项目目录下。请运行一次项目主程序 `uv run run_server.py` 生成配置文件。
+`v1.1.0` 版本开始，`conf.yaml` 文件可能不会自动出现在项目目录下。请复制 `config_templates` 目录下的 `conf.default.yaml`  或 `conf.ZH.default.yaml` 文件到项目根目录并重命名为 `conf.yaml`。
+
+或者，你也可以通过运行主程序 `uv run run_server.py` 并使用 `Ctrl` + `C` 退出程序来生成配置文件（不推荐使用这个方法）。请注意，退出操作需要及时执行，否则程序会开始下载模型文件（此刻退出可能会导致下次无法启动，解决方案为删除 `models/` 下的全部文件）。
 :::
 
 ### 3. 配置 LLM
@@ -463,28 +525,32 @@ uv run run_server.py
 # 第一次运行可能会下载一些模型，导致等待时间较久。
 ```
 
-运行成功后，访问 `http://localhost:12393` 打开 Web 界面。
+运行成功后，浏览器访问 `http://localhost:12393` 即可打开 Web 界面。
 
 :::tip 桌面应用程序
 如果你更倾向于使用 Electron 应用（窗口模式 + 桌宠模式），可以从 [Open-LLM-VTuber-Web Releases](https://github.com/Open-LLM-VTuber/Open-LLM-VTuber-Web/releases) 下载对应平台的 Electron 客户端。该客户端可在后端服务运行时直接使用，你可能会遇到**安全警告**（由于未进行代码签名）——具体说明和解决方案请查阅[模式介绍](./user-guide/frontend/mode.md)。
 
-有关前端的更多信息，请参考[前端指南](./user-guide/frontend/)
+关于前端的更多信息，请查阅 [前端使用指南](./user-guide/frontend/)
 :::
 
 
 ## 下一步
 - [常见问题](faq.md)
+- [长期记忆 (Letta)](user-guide/backend/agent#letta-agent)
 - [桌宠模式](user-guide/frontend/mode)
 - [修改 AI 角色的设定(提示词)](user-guide/backend/character_settings.md)
-- [AI 群聊 (目前文档欠缺)]
+- [AI 群聊 (目前文档欠缺)](user-guide/backend/group_chat.md)
 - [修改 Live2D 模型](user-guide/live2d)
 - [修改 LLM 大语言模型](user-guide/backend/llm.md)
 - [修改 TTS 模型 (AI 的声音模型)](user-guide/backend/tts.md)
 - [修改 ASR 模型 (语音识别模型)](user-guide/backend/asr.md)
 - [参与讨论，加入社区](community/contact.md)
 - [参与开发](community/contribute.md)
 
+### 长期记忆?
+`1.2.0` 版本加入了基于 Letta (也就是 MemGPT) 的长期记忆实现 ([PR #179](https://github.com/Open-LLM-VTuber/Open-LLM-VTuber/pull/179))，虽然回答延迟会增加，但能实现效果较好的长期记忆。
 
+详见 [Agent -> Letta Agent 页面](user-guide/backend/agent#letta-agent)
 
 
 ### 如果你的项目目录下没有 `conf.yaml` 文件

docs/quick-start.md

@@ -109,3 +109,51 @@ Mem0 是一个实验性的长期记忆解决方案。虽然目前仍在开发中
 :::warning
 由于以上局限性，我们目前不推荐在生产环境中使用 Mem0 智能体。
 :::
+
+
+## Letta Agent
+
+### 简介
+
+[Letta](https://github.com/letta-ai/letta) 是有状态的 AI 系统，能够随着时间推移不断演进和学习，保持记忆和行为的一致性，突破了传统 LLM 的限制。Letta 平台整合了可视化开发环境 (ADE)、生产 API 和复杂的服务器运行时，支持创建和部署有状态代理。
+
+简单理解就是可以让大模型拥有长期记忆，自主管理记忆。
+
+同时也可以查看可视化的记忆库，大概包括：
+- `Core Memory`：例如角色的设定，用户的身份信息等
+- `Archival Memory`: 其它的信息
+
+**要在本项目中使用 Letta 实现长期记忆，有以下几个步骤**
+1. 安装，配置，运行Letta
+2. 在Letta 中创建并配置 Agent
+3. 将 Agent 的 ID 填入我们项目的配置文件中。
+
+由于上述步骤具体操作可能发生变化，前两步请参考 Letta 官方文档。
+
+- [这里是Letta的Github地址](https://github.com/letta-ai/letta)
+- [这里是Letta的官方文档](https://docs.letta.com/)
+
+对于 Windows 和 macOS 用户，目前可以尝试使用测试版本的 [Letta Desktop](https://docs.letta.com/install)。除此之外，Letta可以使用Docker部署，也可以从零自己搭环境运行。
+
+
+### 配置文件
+如需使用，请在`agent_config`下的`conversation_agent_choice`替换为`letta_agent`
+
+同时修改以下内容
+```yaml
+letta_agent:
+        host: 'localhost' #主机地址
+        port: 8283 # 端口号
+        id: xxx #letta server运行的Agent的id编号
+        faster_first_response: True
+        # 句子分割方法：'regex' 或 'pysbd'
+        segment_method: 'pysbd'
+```
+
+:::info
+当在config中设置使用`letta_agent`之后，`conf.yaml`中对于`llm`的配置将会失效，最终使用的大模型取决于Letta Server上正在运行的大模型
+:::
+
+:::warning
+当启用Letta之后，暂时不支持发送图片这种多模态信息。
+:::