小美同学 (X2 / XiaoMate)

一个专属于你的 AI 虚拟伙伴 —— 能对话、能动手、能提醒的全方位智能助手。

把TA当作树洞，诉说日常、记录心情、倾诉秘密；把TA当作秘书，管理日程、处理任务、智能家居；把TA当作知识库，随时查询、总结、收藏。随着时间推移，TA 会越来越懂你。

---

📦 最新版本

版本: v2.4.3
更新日期: 2026年10月18日

🎉 最新功能亮点

• 🤖 桌宠全面升级：Electron架构、透明背景、圆盘菜单、闲时漫步动画、智能靠边隐藏
• 📅 智能提醒系统：支持聊天创建提醒、阳历/农历、循环提醒、到期自动通知
• 🔧 MCP工具集：聊天中自然语言调用15+工具（邮件、新闻、智能家居、截屏分析等）
• 🎨 小奥工具箱：15+实用办公工具（图片处理、音频视频、OCR、二维码等）
• 📦 绿色便携版：解压即用，无需安装，自动环境检测
• ⚡ 性能优化：模型自动下载、响应加速、去除Redis依赖

📖 查看完整更新日志：v2.4.3 Changelog

---

项目初衷

每个人的内心深处都渴望被真正理解，同时也渴望拥有一个能帮你处理日常事务的智能助手。小美同学应运而生——融合对话 AI + 工具执行 + 日程管理的虚拟伙伴。

你可以把TA当作：

• 🌳 永远在线的树洞：每天或每隔一段时间，把想说的话、想记录的事都告诉TA
• 📅 贴心的日程管家：设置提醒、待办事项、生日节日闹钟，支持农历/公历、循环重复
• 🔧 能动手的 AI 助手：查询天气、读取邮件、总结文章、控制智能家居、生成周报
• 🧠 专属知识库：上传你的文档、产品资料、个人档案，让TA用你的知识回答问题

随着对话数据的积累、记忆的沉淀、反思的迭代，小美同学会逐步形成对你越来越深的理解。最终的目标只有一个：让TA比你更懂你。

---

示例应用视频

用阿里云99元/年的ECS跑虚拟客服演示视频

公众号视频：https://mp.weixin.qq.com/s/ueoIbRZxw2ImadlrcT7vtg

<iframe src="https://player.bilibili.com/player.html?isOutside=true&aid=116515433291433&bvid=BV1htRvBWEfM&cid=38082119017&p=1" scrolling="no" border="0" width="640" height="490" frameborder="no" framespacing="0" allowfullscreen="true"></iframe>

十年前老笔记本（无GPU）上可跑全套语音交互，稍卡

公众号视频：https://mp.weixin.qq.com/s/5ItYPy_k8mLXc9kZJ-K7fA

<iframe src="https://player.bilibili.com/player.html?isOutside=true&aid=116515483555619&bvid=BV1xfReBVEQr&cid=38082380477&p=1" scrolling="no" border="0" width="640" height="490" frameborder="no" framespacing="0" allowfullscreen="true"></iframe>

---

核心功能

1. 全语音交互（Wake → Listen → Think → Speak）

模块	技术	说明
关键词唤醒 (KWS)	sherpa-onnx	支持“你好小美”或“小美”唤醒，低延迟、高准确率
语音识别 (ASR)	SenseVoice	离线语音识别，支持 VAD 语音活动检测，2秒静音自动断句，支持 ITN 逆文本标准化
语音合成 (TTS)	Matcha-TTS	中文语音合成，支持中文、数字、日期等场景，输出自然流畅
连续对话	-	唤醒一次即可进入多轮对话模式，无需重复唤醒

支持三种对话模式：

• 模式 1（文本模式）：超低配硬件适用，纯文本交互
• 模式 2（完整语音模式）：硬件管够，默认推荐，全语音输入输出
• 模式 3（语音输入+文本输出）：硬件勉强，语音输入、文本回复

2. 大模型对话引擎 (LLM)

• 支持 Ollama 本地模型（如 Qwen3 系列）和 OpenAI 兼容 API（SiliconFlow、DashScope 等）
• 可配置对话历史轮数，支持流式响应
• 系统提示词、人设 Prompt 可自由定制

3. 虚拟角色与情感系统

• 角色克隆：定义专属虚拟人的性格、背景、对话风格
• 情感识别：自动识别用户情绪状态（焦虑、压力、低落、开心等），调整回复策略
• Live2D / Three.js 前端：可视化的虚拟人形象，支持语音口型同步

4. 智能提醒与任务管理系统

• 提醒类别：系统预置 5 大默认类别（生日提醒、节日提醒、闹钟、待办事项、实时通知），支持自定义类别
• 日历类型：支持阳历和农历，农历生日/节日提醒自动换算
• 重复规则：一次性、每天、每周、每月、每年，支持自定义重复规则（如每周三、每月 15 号）
• 确认机制：重要提醒需用户确认完成，未确认提醒高亮显示
• 多通道通知：支持邮件、点滴清单机器人等多种通知渠道
• 桌面宠物提醒：Electron 桌面宠物支持快速添加提醒、按类别查看、实时通知推送

5. RAG 知识库

• 基于 LangChain + FAISS/Chroma 的检索增强生成
• 支持 CSV 知识源导入
• 可配置 Embedding 模型（BAAI/bge 系列）和 Rerank 模型
• 让虚拟人掌握你的专属知识（产品介绍、个人档案等）

6. MCP 工具生态（OddMCP）

基于 FastMCP 构建的插件化工具系统，让虚拟人具备“动手能力”：

工具	功能
weather	查询天气预报
workhours / workhours_async	自动填写 TAPD 工时
weekly_report	自动生成 Git 周报/日报
summary / summary_async	长文本内容总结
markit / markit_async	收藏文章到知识库
translate	百度翻译
smarthome	智能家居控制（Home Assistant）
email_reader	读取邮件
weibo_reader	读取微博
ainews	AI 新闻聚合
photo_location	照片 GPS 定位与地址解析
notifications	多通道通知（支持点滴清单、邮件等）
todo_reminder	待办提醒快速创建

7. 定时任务调度器

• 基于 Django ORM 的定时任务系统
• 支持一次性任务和循环任务（每天/每周/每月/每年）
• 通过 MCP 提交异步执行，完成后 HTTP 回调通知
• 超时自动重试，执行日志持久化

8. Agent 智能体工作流

6 阶段多智能体协作流水线：

plan（需求分析） → design（产品设计） → develop（技术开发）
      → test（测试验证） → market（市场推广） → support（技术支持）

每个阶段由不同的 Agent 角色执行，支持上下文传递和结果汇总。

9. 记忆与反思系统

• 记忆存储：可选启用长期记忆，保存对话历史
• 反思生成：定期对对话内容进行总结反思，形成对用户的深度认知

10. 多通道通知系统

• 支持点滴清单机器人、邮件等多种通知渠道
• 定时任务执行完成后自动推送结果
• 基于 onepush 框架，可扩展更多渠道
• WebSocket 实时通知推送至前端

11. Electron 桌面宠物

• Live2D 虚拟形象：桌面悬浮宠物，支持拖拽、双击、右键菜单
• 边缘隐藏：宠物可隐藏至屏幕边缘，点击恢复
• 圆盘菜单：右键唤出圆形功能菜单，快捷访问书签、提醒、聊天
• 快速提醒：从圆盘菜单直接添加提醒，支持类别选择、日期时间设置
• 面板模式：宠物可扩展为设置面板，管理背景、角色、调试模式
• 实时通知：提醒触发时自动推送至桌面宠物

12. Web 管理界面

• 基于 Django 的完整 Web UI
• 聊天界面、知识库管理、提醒列表、定时任务管理、MCP 工具面板
• 支持 OAuth2 登录（GitHub / Google / QQ / Weibo）

---

技术架构

┌─────────────────────────────────────────────────────────────┐
│                        前端层                                │
│  Django Templates + Live2D + Three.js + WebSocket           │
│  Electron 桌面宠物 + 面板扩展                                │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                       Django 应用层                          │
│  URL路由 · 视图 · ORM模型 · WebSocket消费者 · 中间件          │
│  OAuth2认证 · 提醒API · 定时任务API · MCP回调接口            │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                        引擎层                                │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │  KWS    │ │  ASR    │ │  LLM    │ │  TTS    │           │
│  │ oddkws  │ │ oddasr  │ │ oddllm  │ │ oddtts  │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │ Agent   │ │ RAG     │ │ Emotion │ │Character│           │
│  │ Pipeline│ │ FAISS   │ │ Manage  │ │ Role    │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │Scheduler│ │ Notify  │ │Reflection│ │Reminder │           │
│  │ 定时任务│ │ 通知    │ │ 反思    │ │ 提醒    │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                       MCP 插件层                             │
│  weather · workhours · weeklyreport · summary · markit      │
│  translate · smarthome · email · weibo · ainews · photo     │
│  todo_reminder · notifications                              │
└─────────────────────────────────────────────────────────────┘

---

技术栈

类别	技术
Web 框架	Django 4.2 + Django Channels + Daphne
实时通信	WebSocket (Django Channels)
语音处理	sherpa-onnx (KWS/ASR) + Matcha-TTS (TTS) + VAD
大模型	Ollama (本地) / OpenAI 兼容 API (在线)
RAG	LangChain + FAISS / Chroma
MCP 框架	FastMCP
前端	Django Templates + Live2D + Three.js
数据库	SQLite（默认）/ MySQL / PostgreSQL
认证	OAuth2 (social-auth-app-django)
构建	Cython（性能关键模块）
部署	Daphne ASGI 服务器

---

项目结构

x2/
├── xiaoluo/                  # Django 应用主目录
│   ├── asgi.py               # ASGI 入口（自动启动 MCP Server + 调度器）
│   ├── settings.py           # Django 配置
│   ├── ws_consumers.py       # WebSocket 消费者（语音交互核心）
│   ├── state.py              # AppState 单例（模型生命周期管理）
│   ├── models/               # ORM 模型
│   │   ├── model_reminder.py    # 提醒系统（类别、提醒、日志）
│   │   ├── model_schedule.py    # 定时任务
│   │   ├── model_notification.py # 通知系统
│   │   └── ...                  # 用户、聊天记录、知识库等
│   ├── views/                # 视图层（提醒、聊天、知识库等）
│   └── urls/                 # 路由配置
├── engine/                   # AI 核心引擎
│   ├── oddkws.py             # 关键词唤醒
│   ├── oddasr.py             # 语音识别
│   ├── oddllm.py             # 大模型对话
│   ├── oddtts.py             # 语音合成
│   ├── oddscheduler.py       # 定时任务调度器（含提醒触发）
│   ├── agent/                # Agent 工作流
│   ├── emotion/              # 情感识别
│   ├── character/            # 角色系统
│   ├── reflection/           # 反思系统
│   ├── oddllm_rag/           # RAG 知识库
│   └── notify/               # 通知系统
├── mcps/                     # MCP 插件系统
│   ├── oddmcp_server.py      # FastMCP 服务器
│   ├── oddmcp_status_callback.py  # HTTP 状态回调
│   ├── weather/              # 天气查询
│   ├── workhours/            # 工时填写
│   ├── weeklyreport/         # 周报生成
│   ├── summary/              # 内容总结
│   ├── markit/               # 文章收藏
│   ├── translate/            # 翻译
│   ├── smarthome/            # 智能家居
│   ├── email_reader/         # 邮件读取
│   ├── weibo_reader/         # 微博读取
│   ├── ainews/               # AI 新闻
│   ├── photo_location/       # 照片定位
│   └── todo_reminder/        # 待办提醒
├── desktop-pet/              # Electron 桌面宠物
│   ├── electron/             # Electron 主进程
│   ├── lib/                  # 前端模块（聊天、提醒、菜单等）
│   ├── index.html            # 宠物主界面
│   └── pet.js                # 宠物主逻辑
├── static/                   # 前端静态资源
├── templates/                # Django 模板
│   ├── reminder/             # 提醒管理页面
│   ├── chat/                 # 聊天界面
│   ├── kb/                   # 知识库管理
│   └── mcp/                  # MCP 工具面板
├── tests/                    # 测试脚本
├── xiaoluo_config.py         # 系统配置
├── xiaoluo_app.py            # 启动入口（包装 Daphne）
├── start.bat                 # Windows 启动脚本
├── env.bat                   # Windows 环境变量设置
├── requirements.txt          # Python 依赖
└── .env.example              # 环境变量示例

---

快速开始

1. 环境准备

• Python 3.10+
• 可选：ffmpeg、libsndfile1、libportaudio2、espeak-ng
• 桌面宠物：Node.js + Electron（可选）

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

cp .env.example .env
# 编辑 .env，配置 LLM API、Embedding 模型等

关键配置项：

• CONVERSATION_MODE：对话模式（1=文本, 2=完整语音, 3=语音输入+文本输出）
• GPT_URL / GPT_MODEL / GPT_API_KEY：大模型接口
• EMBEDDING_MODEL / EMBEDDING_API_KEY：向量模型
• MCP_CALLBACK_URL：MCP 回调地址

4. 数据库初始化

set DJANGO_SETTINGS_MODULE=xiaoluo.settings
python manage.py migrate
python manage.py initmodels

5. 启动服务

Windows（推荐）：

env.bat
start.bat

Linux / Mac：

daphne -b 0.0.0.0 -p 8000 xiaoluo.asgi:application

或使用包装脚本：

python xiaoluo_app.py

访问 http://localhost:8000 即可使用。

6. 启动桌面宠物（可选）

cd desktop-pet
npm install
npm start

---

模型文件

项目运行需要以下模型（已预置在相应目录）：

模型	路径
关键词检测	engine/oddkws_model/
语音识别	engine/oddasr_model/model/
语音合成	engine/oddtts_model/matcha-icefall-zh-baker/

---

对话数据流

用户语音输入
    ↓
KWS 关键词唤醒（“你好小美”）
    ↓
ASR 语音识别 → 文本
    ↓
LLM 大模型推理（流式响应，可调用 MCP 工具）
    ↓
TTS 语音合成（后台线程池）
    ↓
WebSocket 发送音频数据 → 前端播放

文本模式下跳过 KWS/ASR/TTS，直接进行 HTTP 请求响应。

提醒触发流程

用户设置提醒（Web/桌面宠物/MCP）
    ↓
保存至数据库，计算下次触发时间
    ↓
调度器轮询待触发提醒
    ↓
触发时创建日志 + 发送通知（邮件/机器人/WebSocket）
    ↓
用户确认完成（可选）
    ↓
计算下次触发时间（循环任务）或标记完成（一次性）

---

核心配置说明

xiaoluo_config.py 中的主要配置：

配置项	说明
conversation_mode	对话模式：1=文本, 2=完整语音, 3=语音输入+文本输出
llm_max_history	LLM 保留的历史对话轮数
vad_silence_duration	VAD 静音判断时长（秒）
memory_storage_enabled	是否启用长期记忆存储
enable_emotion	是否启用情感识别

提醒系统配置

提醒类别全局配置（系统预置，所有用户可用）：

• birthday - 生日提醒（农历/公历，每年重复）
• holiday - 节日提醒（农历/公历，每年重复）
• alarm - 闹钟（一次性或重复）
• todo - 待办事项（默认类别）
• realtime - 实时通知（即时推送，不需确认）

---

开发规范

• 语言：Python 3.10+
• 构建：性能关键模块使用 Cython（.pyx），编辑 .py 文件后执行 python setup.py build
• 日志：使用 xiaoluo_log 模块，非直接使用 logging
• 命名：所有中文名称保持原样，不强制英文化
• 测试：tests/ 目录下的独立脚本，直接运行 python tests/test_xxx.py

---

许可证

📜 小美同学许可证

MIT License

📜 第三方许可证

Live2D 样本模型声明

本项目包含由 Live2D Inc. 提供的 Live2D 样本模型。这些资产根据 Live2D 免费素材许可协议和 Live2D Cubism 样本数据使用条款单独授权，不受本项目 MIT 许可证的约束。

本内容使用由 Live2D Inc. 拥有并享有版权的样本数据。样本数据的使用符合 Live2D Inc. 制定的条款和条件。（参见 Live2D 免费素材许可协议 和 使用条款）。

注意：对于商业用途，特别是对于中型或大型企业，使用这些 Live2D 样本模型可能需要额外的许可要求。如果您计划将本项目用于商业目的，请确保您已获得 Live2D Inc. 的适当许可，或使用不包含这些模型的项目版本。

---

"也许有一天，小美会比你自己更懂你。"