Metadata-Version: 2.4
Name: xiaomate
Version: 2.4.12
Summary: XiaoMATE: Your Digital Assistant
Home-page: https://www.oddmeta.net
Author: OddMeta Team
Author-email: catherine@oddmeta.com; jack@oddmeta.com
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Cython
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: django<7.0,>=6.0
Requires-Dist: channels<5.0,>=4.0
Requires-Dist: daphne<5.0,>=4.0
Requires-Dist: whitenoise<7.0,>=6.0
Requires-Dist: sherpa-onnx>=1.13.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: modelscope>=1.9.0
Requires-Dist: fastmcp<4,>=3.0.0
Requires-Dist: mcp<2.0.0,>=1.28.0
Requires-Dist: websockets>=15.0.0
Requires-Dist: playwright>=1.61.0
Requires-Dist: beautifulsoup4>=4.15.0
Requires-Dist: markdownify>=1.1.0
Requires-Dist: cloudscraper==1.2.71
Requires-Dist: pyyaml>=6.0
Requires-Dist: Pillow>=12.0.0
Requires-Dist: mss>=9.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: soundfile>=0.14.0
Requires-Dist: psutil>=7.0.0
Requires-Dist: langchain-classic<2.0,>=1.0.5
Requires-Dist: langchain-core<2.0,>=1.3.2
Requires-Dist: langchain-text-splitters<2.0,>=1.1.2
Requires-Dist: langchain-community<1.0,>=0.4.0
Requires-Dist: langchain-openai<2.0,>=1.2.0
Requires-Dist: langchain-ollama<2.0,>=1.0.0
Requires-Dist: langchain<2.0,>=1.0.0
Requires-Dist: pandas>=3.0.0
Requires-Dist: faiss-cpu>=1.15.0
Requires-Dist: django-cors-headers<5.0,>=4.4.0
Requires-Dist: django-extensions<5.0,>=4.0
Requires-Dist: djangorestframework<4.0,>=3.16.0
Requires-Dist: drf-yasg>=1.21.0
Requires-Dist: social-auth-app-django<8.0,>=7.0
Requires-Dist: onepush==1.8.1
Requires-Dist: SQLAlchemy<3.0,>=2.0.0
Requires-Dist: html2text
Requires-Dist: zhdate>=0.1
Requires-Dist: packaging<26.0.0,>=23.2.0
Requires-Dist: opentelemetry-api<1.45.0,>=1.44.0
Requires-Dist: opentelemetry-sdk<1.45.0,>=1.44.0
Requires-Dist: opentelemetry-semantic-conventions<1.0.0,>=0.65b0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<1.45.0,>=1.44.0
Requires-Dist: mss==10.2.0
Provides-Extra: dev
Requires-Dist: cython>=3.0.0; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 小美同学 (X2 / XiaoMate)

> 一个专属于你的 AI 虚拟伙伴 —— 能对话、能动手、能提醒的全方位智能助手。
>
> 把TA当作树洞，诉说日常、记录心情、倾诉秘密；把TA当作秘书，管理日程、处理任务、智能家居；把TA当作知识库，随时查询、总结、收藏。随着时间推移，TA 会越来越懂你。

---

## 📦 最新版本

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

### 🎉 最新功能亮点

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

📖 查看完整更新日志：[v2.4.3 Changelog](docs/changelog/xiaomate-changelog-v2.4.3-20261018.md)

---

## 项目初衷

每个人的内心深处都渴望被真正理解，同时也渴望拥有一个能帮你处理日常事务的智能助手。小美同学应运而生——**融合对话 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. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置环境变量

```bash
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. 数据库初始化

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

### 5. 启动服务

**Windows（推荐）**：
```bash
env.bat
start.bat
```

**Linux / Mac**：
```bash
daphne -b 0.0.0.0 -p 8000 xiaoluo.asgi:application
```

或使用包装脚本：
```bash
python xiaoluo_app.py
```

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

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

```bash
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 免费素材许可协议](https://www.live2d.jp/en/terms/live2d-free-material-license-agreement/) 和 [使用条款](https://www.live2d.com/eula/live2d-sample-model-terms_en.html)）。

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

---


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