MoCli

AI‑Powered Desktop Companion with Visual Pointing

📖 简介

MoCli 是一个运行在 Windows 桌面上的 AI 伴侣助手。它以一个优雅的三角形光标驻留在屏幕上，通过语音唤醒或系统托盘与用户交互。

MoCli 能看到你的屏幕、听到你的声音、理解你的意图，并用自然语言回答问题——还能精准地将光标飞向屏幕上的任何元素来指引你。

✨ 核心能力

• 🎯 视觉指向 — 结合 VLM（视觉语言模型）截屏分析，三角形光标会飞向 AI 识别到的目标位置
• 🗣️ 语音唤醒 — 说出唤醒词（默认"贾维斯"）即可开始对话，无需动手
• 🎤 语音识别 (STT) — 基于 SenseVoice 离线语音转文字，隐私安全
• 🔊 语音合成 (TTS) — 对接本地 TTS 服务，AI 回复自动朗读
• 🌀 状态可视化 — 聆听时绿色呼吸圆球，思考时紫色呼吸圆球，待机时静默三角形
• ⚙️ Win11 风格设置面板 — Fluent Design 三栏标签页，支持实时光标坐标显示与定点测试

🏗️ 项目架构

MoCli 采用模块化架构，每个文件职责单一、松耦合：

MoCli/
├── main.py          # 程序入口 — 模块组装、信号编排、VoiceManager
├── settings.py      # 配置管理 — DBManager(SQLite) + 设置面板 + 系统托盘
├── triangle.py      # 三角形光标 — 弹簧物理跟随 + 飞行动画 + 呼吸状态
├── screen.py        # 屏幕截图 — 无损物理像素截屏 + Base64 编码
├── llm.py           # 大模型引擎 — Prompt 构建 + 多模态请求 + 坐标解析
├── wakeup.py        # 语音唤醒 — sherpa-onnx KWS 关键词检测
├── stt.py           # 语音识别 — SenseVoice 离线推理 + WebRTC VAD
├── tts.py           # 语音合成 — aiohttp 异步流式 PCM 播放
├── system_prompt.md # 系统提示词（只读参考）
├── requirements.txt # Python 依赖清单
└── mocli.db         # SQLite 配置数据库（自动生成）

数据流

语音唤醒 ──→ STT识别 ──→ 截屏+构建Prompt ──→ VLM推理 ──→ 解析回复
                                                            │
                              ┌────────────────────────────┤
                              ↓              ↓              ↓
                         气泡显示       光标飞行指向      TTS朗读

🚀 快速开始

环境要求

安装步骤

# 1. 克隆项目
git clone https://github.com/your-repo/mocli.git
cd mocli

# 2. 创建并激活虚拟环境
conda create -p .conda python=3.10 -y
conda activate ./.conda

# 3. 安装依赖
pip install -r requirements.txt

# 4. 下载语音模型（语音功能需要）
# KWS 唤醒模型
# 将 sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01 目录放在项目根目录
# STT 识别模型
# 将 sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17 目录放在项目根目录

# 5. 启动
python main.py

注意：首次运行会自动创建 mocli.db 配置数据库。语音模型目录不存在时，程序会优雅退化为纯文本模式。

⚙️ 配置说明

所有配置通过系统托盘 → 右键 → 设置进入 Win11 风格的设置面板管理。

🧠 大模型 Tab

🗣️ 语音 Tab

⚙️ 高级 Tab

🎯 视觉定位系统

MoCli 使用 0-1000 归一化坐标系 进行视觉定位，这是当前主流 VLM 最擅长的定位方式：

┌──────────────────────────┐
│ (0,0)          (1000,0)  │
│                          │
│        (500,500)         │  ← 屏幕正中央
│                          │
│ (0,1000)      (1000,1000)│
└──────────────────────────┘

换算公式

物理像素 X = ((归一化X + 偏移X) / 1000) × 屏幕宽度
物理像素 Y = ((归一化Y + 偏移Y) / 1000) × 屏幕高度

示例：屏幕 2560×1600，AI 返回 [POINT:500,500:目标]，偏移量 (0,0)
→ 物理坐标 = (1280, 800) = 屏幕正中央 ✅

支持的模型

🎨 光标状态可视化

三角形光标会根据 MoCli 的工作状态自动变换形状和颜色：

📁 语音模型目录结构

MoCli/
├── sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01/
│   ├── encoder-epoch-99-avg-1-chunk-16-left-64.onnx
│   ├── decoder-epoch-99-avg-1-chunk-16-left-64.onnx
│   ├── joiner-epoch-99-avg-1-chunk-16-left-64.onnx
│   └── tokens.txt
│
└── sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17/
    ├── model.int8.onnx
    └── tokens.txt

模型可从 sherpa-onnx 官方仓库 获取。

🔧 技术细节

并发模型

MoCli 采用 方案 A：共享 asyncio 事件循环。wakeup、stt、tts 三个子系统在同一个后台线程的 asyncio 循环中运行，通过 asyncio.Queue 共享音频数据，降低线程切换开销。

DPI 处理

强制设置环境变量 QT_AUTO_SCREEN_SCALE_FACTOR=0，确保截屏坐标与 Qt 窗口坐标 1:1 对齐，避免高 DPI 屏幕下的偏移。

跨线程安全

所有后台线程（AI 请求、语音引擎）通过 pyqtSignal 信号桥与 Qt 主线程通信，避免直接操作 Widget 导致的线程死锁。

配置持久化

使用 SQLite 键值对数据库 (mocli.db)，所有配置修改即时生效，无需重启。

📋 依赖清单

🐛 常见问题

pip install "setuptools<71"
pip install webrtcvad

📄 开源协议

本项目基于 MIT License 开源。