本地ai伴侣MiusAI

MiusAI 项目文档

一个温柔立体的桌面 AI 伴侣项目——集成情感分析、性格成长、语音交互、电脑操控与微信桥接的完整桌面应用

目录

1. 项目概述
2. 项目架构
3. 文件结构
4. 核心模块详解
5. 技术栈
6. 环境准备与安装
7. 配置说明
8. 启动方式
9. 功能清单
10. 复制与扩展指南

1. 项目概述

MiusAI 是一个运行在 Windows 桌面上的 AI 伴侣应用。它不是简单的 ChatGPT 套壳，而是围绕"情感连接"这一核心设计的一整套系统：角色拥有随对话演变的好感度与心情状态，能通过语音听懂你说话、用声音回复你，还能直接操控电脑——打开应用、调节音量、截图锁屏，甚至接入微信让你在手机上和桌面精灵聊天。

项目提供三种交互入口和一个微信桥接服务，共享同一套性格系统、记忆系统和 AI 大脑：

整个项目的核心理念是：AI 不只是回答问题，而是记住你、理解你的情绪、并随时间成长。好感度从 30 起步，随着对话中的开心、感激、爱恋等正向情绪逐步上升；角色心情会根据你的情绪、聊天间隔、甚至当前是深夜还是早晨而变化。这些状态最终通过系统提示词注入到每次 AI 调用中，让同一个底层模型表现出截然不同的回复风格。

2. 项目架构

MiusAI 采用共享内核 + 多入口的架构。三个 Python 入口文件各自独立运行，但都复用同一套核心类（Memory、Personality、Brain、Actions）。微信桥接通过 HTTP API 调用 Flask 服务，Flask 服务内部同样复用 main.py 的核心组件。

┌─────────────────────────────────────────────────────────────────┐ │ 入口层 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ main.py │ │mius_sprite.py│ │ preview.py │ │ │ │ 桌面聊天窗口 │ │ 桌面精灵 │ │ 精灵预览 │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ (仅绘图) │ │ ▼ ▼ ▼ │ ├─────────────────────────────────────────────────────────────────┤ │ API 服务层 │ │ ┌─────────────────────────────────┐ │ │ │ mius_api.py (Flask :5000) │ │ │ │ POST /chat GET /status │ │ │ └──────────────┬──────────────────┘ │ │ │ │ ├────────────────────────┼─────────────────────────────────────────┤ │ 桥接层 │ 核心内核（共享） │ │ ┌─────────────┐ │ ┌──────────────────────────┐ │ │ │ agent.js │────────┘ │ Memory (SQLite 记忆) │ │ │ │ Node.js │ │ SmartPersonality (性格) │ │ │ │ 微信桥接 │ │ Brain (AI 大脑) │ │ │ └──────┬──────┘ │ Actions (电脑操控) │ │ │ │ │ VoiceListener (语音识别) │ │ │ ┌──────▼──────┐ │ VoiceSpeaker (语音合成) │ │ │ │ 微信客户端 │ └───────────┬──────────────┘ │ │ └─────────────┘ │ │ ├──────────────────────────────────────────┼────────────────────────┤ │ AI 推理层 │ 数据层 │ │ ┌─────────────┐ ┌─────────────┐ │ ┌──────────────┐ │ │ │ Ollama │ │ SiliconFlow │ └─▶│ mius_memory │ │ │ │ 本地 │ │ 云端 │ │ .db │ │ │ │ qwen2.5:14b │ │DeepSeek-V3 │ └──────────────┘ │ │ └─────────────┘ └─────────────┘ ┌──────────────┐ │ │ │ config.ini │ │ │ └──────────────┘ │ └─────────────────────────────────────────────────────────────────┘

数据流说明

当用户在桌面窗口或桌面精灵中输入一条消息时，处理流程如下：

1. 入口文件调用personality.update(user_msg)，触发情感分析、趋势计算和性格属性更新
2. 入口文件调用actions.try_execute(user_msg)，尝试匹配电脑操控指令（打开应用、搜索、音量等）
3. 若未匹配操控指令，入口文件调用personality.get_system_prompt()生成动态系统提示词
4. 入口文件通过AIWorker线程调用brain.chat()，根据当前模式选择本地 Ollama 或云端 API
5. AI 回复后，入口文件将对话存入 SQLite 并调用speaker.speak()进行语音朗读

微信桥接的数据流类似，区别在于消息通过 HTTP 传输：微信消息 → agent.js → Flask/chat接口 → 复用上述核心流程 → JSON 返回回复 → agent.js → 微信。

设计要点：main.py 和 mius_sprite.py 各自维护独立的 Brain 实例和内存中的对话历史（self.history），但共享同一个 SQLite 数据库文件mius_memory.db。同时运行多个入口时，持久化记忆是共享的，但实时对话上下文是隔离的。

3. 文件结构

项目根目录结构简洁，所有核心代码集中在少数几个文件中：

MiusAI/ ├── main.py # 桌面聊天窗口入口（PyQt6 QMainWindow） ├── mius_api.py # Flask HTTP API 服务，供微信桥接调用 ├── mius_sprite.py # 桌面精灵入口（透明置顶窗口 + 对话气泡） ├── preview.py # 精灵预览（纯 QPainter 绘制二次元角色） ├── config.ini # API 配置（密钥、模型、端点） ├── requirements.txt # Python 依赖清单 ├── start_mius.bat # 一键启动脚本（API + 微信桥接） ├── mius.png # 桌面精灵角色立绘图片 ├── mius_memory.db # SQLite 记忆数据库（运行时自动生成） ├── __pycache__/ # Python 编译缓存（自动生成） └── mius-wechat-bridge/ # 微信桥接子项目 ├── agent.js # 微信桥接主程序 ├── package.json # Node.js 依赖配置 ├── package-lock.json # 依赖锁定文件 └── node_modules/ # Node.js 依赖（npm install 后生成）

注意：mius_memory.db是运行时自动创建的 SQLite 数据库，包含对话记录、用户信息和情绪历史。复制项目时不需要携带此文件，首次运行会自动生成。但若希望保留已有的性格数据（好感度、信任度等），则需要一并复制。

4. 核心模块详解

MiusAI 的核心逻辑由七个模块组成，全部定义在 main.py 中（mius_sprite.py 有简化版本，mius_api.py 通过 import 复用）。以下逐一拆解每个模块的职责与实现要点。

4.1 智能情感分析器 EmotionAnalyzer

情感分析器是性格系统的基础。它通过关键词匹配 + 强度修饰词的方式，从用户消息中提取情绪标签和强度值。

分析器维护了一个包含八种情绪的词典：开心、难过、生气、焦虑、疲惫、感激、爱恋、夸奖。每种情绪关联若干中文关键词。当用户消息中命中某个关键词时，分析器会进一步检查是否被强度修饰词修饰（如"很"“非常”"超级"会放大强度，“有点”"不太"会缩小强度），最终返回得分最高的情绪标签和数值化强度。

# 情绪词典示例emotion_words={"开心":["哈哈","开心","好玩","有趣","棒",...],"难过":["难过","伤心","哭","不开心",...],...}# 强度修饰词intensity_modifiers={"很":1.5,"非常":2.0,"超级":2.5,"极度":3.0,"有点":0.6,"稍微":0.5,"不太":0.4,...}

这种基于规则的方法虽然不如深度学习模型精确，但零延迟、无需额外模型加载，且对于中文日常聊天的常见情绪表达覆盖面足够。分析结果直接驱动性格系统的属性变化。

4.2 智能性格系统 SmartPersonality

性格系统是 MiusAI 区别于普通聊天机器人的核心。它维护五个动态属性，并在每次对话后根据情感分析结果更新它们：

性格更新逻辑在update()方法中，每次对话触发一次。更新过程分为七个步骤：

1. 情感分析——调用 EmotionAnalyzer 获取当前消息的情绪标签和强度
2. 趋势分析——检查最近 5 条情绪历史，判断是上升、下降还是稳定
3. 偏好学习——根据消息长度、是否包含问号、是否倾诉等，学习用户的交互偏好
4. 情绪驱动调整——开心增加好感，难过增加信任（共情），爱恋大幅增加好感并触发害羞
5. 趋势驱动调整——情绪下降趋势会让角色进入"担心"状态
6. 时间间隔调整——超过 3 小时未对话进入"寂寞"，超过 30 分钟进入"小委屈"
7. 深夜检测——23:00 至 6:00 之间，平静状态自动转为"困倦"

所有属性会通过save_personality()持久化到 SQLite 的user_info表中，下次启动时自动恢复。这意味着角色的性格是跨会话成长的——你今天和她建立的好感度，明天打开应用依然存在。

get_system_prompt()方法将当前性格状态编译为一段中文系统提示词，包含好感度阶段描述、时间段、心情、用户偏好和情绪趋势。这段提示词会被注入到每次 AI 调用的 system 消息中，使底层模型的行为随性格状态动态变化。

4.3 记忆系统 Memory

记忆系统基于 SQLite，使用check_same_thread=False允许跨线程访问（因为语音识别和 AI 工作都在子线程中）。数据库包含四张表：

用户信息的提取逻辑内嵌在消息处理流程中。当消息包含"我叫""我是"时，紧跟的文本会被截取为用户名字存入user_info；同理，“生日”"喜欢"分别提取生日和爱好。这些信息会在后续对话中作为 memory context 注入到系统提示词中，让角色"记住"关于你的事实。

4.4 AI 大脑 Brain

Brain 封装了 AI 推理的调度逻辑，支持本地 Ollama和云端 API两种模式，通过use_local标志位切换。两种模式都遵循 OpenAI 兼容的消息格式。

本地模式 (_chat_local)

通过 HTTP 调用本地运行的 Ollama 服务（默认http://localhost:11434/api/chat），使用qwen2.5:14b模型。请求超时 60 秒，保留最近 6 条对话历史作为上下文。如果本地服务不可用，自动降级到离线回复（简单的关键词匹配兜底）。

云端模式 (_chat_cloud)

调用 SiliconFlow API（https://api.siliconflow.cn/v1/chat/completions），使用deepseek-ai/DeepSeek-V3模型。请求超时 30 秒，保留最近 8 条对话历史，temperature 设为 0.8。如果云端调用失败，自动回退到本地模式。

两种模式的差异体现了设计取舍：本地模式延迟较高（14B 模型推理慢）但完全离线、隐私安全；云端模式响应快、质量高但依赖网络和 API 密钥。用户可以在运行时通过输入cloud或local命令实时切换。

离线兜底：当本地和云端都不可用时，_offline()方法提供最基本的回复能力：识别"你好"“晚安"等常见问候，其余情况返回"嗯…再说一遍好吗？”。这保证了极端情况下应用不会崩溃或无响应。

4.5 电脑操控 Actions

Actions 模块让 Mius 不仅是聊天对象，还能作为语音助手操控电脑。它在每条用户消息进入 AI 之前先尝试匹配操控指令，如果匹配成功则直接执行并返回结果，跳过 AI 调用。

操控能力通过 pyautogui 模拟键盘快捷键和鼠标操作实现，覆盖以下场景：

4.6 语音识别与合成

语音识别 VoiceListener

VoiceListener 是一个 QThread 子类，在独立线程中持续监听麦克风。它使用OpenAI Whisper模型进行离线语音识别——main.py 加载small模型，mius_sprite.py 加载tiny模型（体积更小、速度更快但精度略低）。识别流程为：录制 5 秒音频 → 检测音量是否超过阈值（过滤静音）→ 保存为临时 WAV → Whisper 转写 → OpenCC 繁简转换 → 通过 Qt 信号发射识别文本。

语音合成 VoiceSpeaker

VoiceSpeaker 使用微软的edge-tts服务（免费、无需 API 密钥）将回复文本转为语音。默认使用zh-CN-XiaoyiNeural中文女声。合成过程在守护线程中异步执行：edge-tts 生成音频 → soundfile 读取 → sounddevice 播放。合成前会过滤掉文本中的 emoji 和颜文字符号，避免 TTS 引擎朗读乱码。

4.7 Flask API 服务 (mius_api.py)

mius_api.py 是一个轻量 Flask 应用，提供三个 HTTP 接口，使微信桥接等外部程序能够接入 Mius 的核心能力：

/chat接口内部完整复用了 main.py 的处理逻辑：注入时间上下文、更新性格、提取用户信息、生成系统提示词、调用 AI、保存记录。它还维护了一个内存中的会话缓存session_cache，以conversation_id为键隔离不同微信用户的对话历史。

5. 技术栈

MiusAI 的技术选型兼顾了功能完整性和部署便捷性。所有依赖都是免费或开源的，本地 AI 模式下可以完全离线运行。

版本说明：requirements.txt 中仅锁定了 6 个核心依赖的版本（PyQt6、requests、pyautogui、pyperclip、pygame、Pillow），而 whisper、opencc、edge-tts、sounddevice、soundfile、numpy、flask、flask-cors 等在代码中被 import 但未列入 requirements.txt。复制项目时需要手动补全这些依赖（见第 6 节安装步骤）。

6. 环境准备与安装

以下步骤从零开始搭建 MiusAI 的完整运行环境。整个过程分为 Python 环境、本地 AI 模型、Node.js 桥接三个部分。

6.1 系统要求

• 操作系统：Windows 10/11（代码使用了 winreg、os.startfile 等 Windows 专属 API）
• Python：3.10+（代码使用了 Python 3.10+ 的语法特性）
• Node.js：18+（仅微信桥接功能需要）
• 本地 AI：建议 16GB+ 内存（运行 qwen2.5:14b 模型），或使用云端模式跳过本地模型
• 麦克风：语音识别功能需要（可选）

6.2 安装 Python 依赖

在项目根目录打开终端，先安装 requirements.txt 中列出的核心依赖：

pipinstall-rrequirements.txt

然后补全代码中实际使用但未列入 requirements.txt 的依赖：

pipinstallopenai-whisper opencc-python-reimplemented edge-tts sounddevice soundfile numpy flask flask-cors

Whisper 模型依赖：openai-whisper 依赖 PyTorch。首次安装时 pip 会自动拉取 torch（约 2GB）。如果你的网络环境不佳，建议先手动安装 PyTorch 再安装 whisper。Whisper 模型文件（small 约 461MB、tiny 约 39MB）在首次使用时自动下载到~/.cache/whisper/目录。

6.3 安装本地 AI 模型（可选）

如果希望使用本地 AI 模式（默认模式），需要安装 Ollama 并拉取模型：

1. 从 ollama.com 下载并安装 Ollama
2. 在终端执行模型拉取命令：

ollama pull qwen2.5:14b

3. 启动 Ollama 服务（安装后默认自动启动，监听localhost:11434）

如果只使用云端模式，可以跳过此步骤——在运行时输入cloud命令切换即可。

6.4 安装微信桥接依赖（可选）

如果需要微信接入功能，进入桥接子项目目录安装 Node.js 依赖：

cdmius-wechat-bridgenpminstall

这会安装 weixin-agent-sdk 和 node-fetch。安装完成后，node_modules/目录会被创建。

6.5 验证安装

安装完成后，可以通过以下命令快速验证各组件是否就绪：

# 验证 Python 依赖python-c"import PyQt6, whisper, edge_tts, sounddevice, flask; print('Python OK')"# 验证 Ollama（如果安装了）curlhttp://localhost:11434/api/tags# 验证 Node.js 桥接cdmius-wechat-bridge&&node-e"import('weixin-agent-sdk').then(()=>console.log('Node OK'))"

7. 配置说明

项目的所有可配置项集中在config.ini文件中。这是一个标准的 INI 格式文件，包含一个[API]节：

[API] api_key = your_api_key_here base_url = https://api.siliconflow.cn/v1 model = deepseek-ai/DeepSeek-V3

安全提示：config.ini 中的 api_key 是敏感信息。复制或分享项目时，务必将密钥替换为占位符。建议将 config.ini 加入 .gitignore，或使用环境变量读取密钥。

可扩展的配置点

除了 config.ini 之外，代码中还有一些硬编码的配置值，复制项目时可能需要调整：

• 本地模型名称：Brain 类中硬编码为qwen2.5:14b，如需使用其他 Ollama 模型需修改源码
• Whisper 模型大小：main.py 使用small，mius_sprite.py 使用tiny
• TTS 语音：VoiceSpeaker 中硬编码为zh-CN-XiaoyiNeural，可改为其他 edge-tts 支持的中文声音
• Flask 端口：mius_api.py 中硬编码为5000，agent.js 中对应127.0.0.1:5000
• 好感度初始值：SmartPersonality 中affection = 30, trust = 20

8. 启动方式

MiusAI 提供多个入口，可以单独运行，也可以通过一键脚本组合启动。

8.1 桌面聊天窗口

最简单的启动方式，打开一个标准聊天窗口：

python main.py

窗口包含标题栏、状态栏（显示好感度、心情、趋势、AI 模式）、聊天记录区和输入框。在输入框中输入文字回车发送，支持三个特殊命令：

• cloud——切换到云端 AI 模式
• local——切换到本地 AI 模式
• info——查看当前记忆和性格状态

8.2 桌面精灵

启动透明置顶的桌面宠物，显示角色立绘图片（mius.png）：

python mius_sprite.py

精灵默认出现在屏幕右下角，可以拖拽移动。交互方式：

• 双击——弹出聊天输入框
• 右键——打开功能菜单（聊天、语音开关、切换云端/本地、开机自启、查看记忆、退出）
• 左键拖拽——移动精灵位置

8.3 精灵预览

启动纯代码绘制的角色预览（不包含 AI 功能，仅展示动画效果）：

python preview.py

8.4 API 服务 + 微信桥接（一键启动）

使用项目根目录的批处理脚本一键启动 Flask API 和微信桥接：

start_mius.bat

该脚本依次执行：

1. 在后台启动python mius_api.py（Flask 服务监听 :5000）
2. 等待 3 秒确保 API 就绪
3. 在后台启动node agent.js（微信桥接，弹出扫码登录界面）

扫码登录微信后，任何发给该微信号的消息都会被转发给 Mius AI 处理并自动回复。每个微信用户通过userId维护独立的会话上下文。

8.5 手动分步启动

如果需要分别调试，可以手动启动各组件：

# 终端 1：启动 API 服务python mius_api.py# 终端 2：启动微信桥接cdmius-wechat-bridgenodeagent.js

8.6 开机自启

在桌面窗口或桌面精灵中可以通过界面按钮开启开机自启。该功能通过写入 Windows 注册表HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run实现，将当前 Python 解释器和脚本路径注册为开机启动项。

9. 功能清单

以下是 MiusAI 的完整功能列表，按类别分组：

10. 复制与扩展指南

10.1 最小化复制

如果只想复制核心聊天功能（不含桌面精灵和微信桥接），最少需要以下文件：

• main.py——主程序
• config.ini——API 配置（替换为自己的密钥）
• requirements.txt——依赖清单

安装依赖后即可运行。mius_memory.db 会在首次运行时自动创建。

10.2 完整复制

复制完整功能需要所有源码文件和 mius.png 图片。Node.js 桥接需要额外执行npm install。

10.3 替换角色形象

桌面精灵使用mius.png作为角色立绘。替换此文件即可更换角色形象，建议图片尺寸为 180×220 像素（代码中按此尺寸缩放）。如果图片文件不存在，精灵会回退显示文字"🐱 Mius"。

如果希望使用纯代码绘制角色（无需图片文件），可以参考preview.py的实现，将其中的 QPainter 绘制逻辑移植到 mius_sprite.py 的paintEvent方法中。

10.4 替换 AI 模型

本地模式：修改 Brain 类中的qwen2.5:14b为你已通过 Ollama 拉取的其他模型名称（如llama3:8b、qwen2.5:7b等）。

云端模式：修改 config.ini 中的base_url、api_key和model为任何 OpenAI 兼容的 API 服务。代码使用标准的/chat/completions端点，兼容性广泛。

10.5 调整性格参数

性格系统的所有参数都在 SmartPersonality 类中可调：

• 修改emotion_words字典扩展或调整情绪关键词
• 修改intensity_modifiers调整修饰词权重
• 修改update()方法中的属性增减系数改变性格成长速度
• 修改get_system_prompt()中的阶段描述和心情映射改变角色风格
• 修改初始值affection = 30, trust = 20改变起始关系

10.6 扩展操控指令

在 Actions 类的try_execute()方法中添加新的关键词匹配分支即可扩展操控能力。每个分支返回一个字符串作为回复，操控通过 pyautogui 实现。参考现有的音量控制分支：

ifany(winmsg_lowerforwin["音量","声音"]):ifany(winmsg_lowerforwin["大","高"]):for_inrange(5):pyautogui.press("volumeup")return"音量调高了~ 🔊"

10.7 接入其他聊天平台

mius_api.py 提供的 HTTP API 是平台无关的。任何能发送 HTTP 请求的程序都可以接入 Mius。参考 agent.js 的实现模式：维护一个用户 ID 到会话 ID 的映射，每次收到消息时附带conversation_id调用/chat接口，将返回的reply发回给用户即可。

架构启示：MiusAI 展示了一种轻量级 AI 桌面应用的构建模式：用 SQLite 做持久化、用规则引擎做情感分析、用动态系统提示词驱动 LLM 角色扮演、用 Flask + 桥接程序扩展接入渠道。这套模式不依赖任何重型框架，所有核心逻辑控制在单文件千行以内，适合个人开发者快速复制和定制。