# VoiceFocus

**Repository Path**: pan-yunyi/voice-focus

## Basic Information

- **Project Name**: VoiceFocus
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VoiceFocus AI - 智能专注与效率桌面助手

![Python](https://img.shields.io/badge/Python-3.10~3.13-blue)
![PySide6](https://img.shields.io/badge/PySide6-6.6~6.11-green)
![DeepSeek](https://img.shields.io/badge/AI-DeepSeek_V3.2-purple)
![License](https://img.shields.io/badge/License-MIT-orange)

VoiceFocus AI 是一个基于大模型的智能桌面伴侣。它不仅提供日常对话和日程管理，还通过**多级断网机制**和**沉浸式专注覆盖**来提升你的专注力。全程支持语音交互，无需键盘。

本项目是《开源软件导论》课程的结课项目，由 3 人团队协作开发。

## 核心功能

- **AI 语音交互**：大模型对话（DeepSeek）、麦克风语音识别 (STT)、拟人化语音播报 (TTS)，全部在后台线程运行，不卡 UI。
- **多级防拖延**：沉浸式番茄钟 + 三级自动降级网站屏蔽（hosts → PAC 代理 → 心理威慑）+ 置顶全屏覆盖窗口。
- **智能日程管家**：自然语言添加日程、到点提醒、每日专注数据 matplotlib 图表总结。

## 技术架构

```
用户语音/文本输入
       │
       ▼
┌─────────────┐   QThread    ┌─────────────┐
│  UI 层       │──Signal/Slot→│  AI 引擎     │
│  PySide6     │←─Signal/Slot─│  STT/TTS/Chat│
└──────┬──────┘   Workers    └──────┬──────┘
       │                            │
       ▼                            ▼
┌─────────────┐              ┌─────────────┐
│  系统控制    │←────────────→│  SQLite DB   │
│  屏蔽/计时   │              │  日程/记录    │
└─────────────┘              └─────────────┘
```

关键设计：
- **面向接口** (`src/interfaces.py`)：用 Python Protocol（3.10+）定义三方契约，三人基于 Mock 数据独立开发。
- **QThread 异步模型**：所有 AI/语音操作在 PySide6 QThread 工作线程中执行，通过 Signal/Slot 回传结果。
- **OpenAI 兼容 API**：通过 `openai` SDK 的 `chat.completions.create()` 接口对接 DeepSeek，同一套代码可切换 OpenAI/DeepSeek/通义千问等服务。
- **三级自动降级屏蔽**：hosts（需管理员）→ PAC 代理（无需管理员，Chrome/Edge 生效）→ 仅心理威慑。
- **安全兜底**：atexit 钩子 + 启动清理，确保异常退出后网络自动恢复。

## 项目结构

```
VoiceFocus/
├── main.py                     # 程序入口，组装各模块
├── requirements.txt            # Python 依赖
├── .env.example                # API Key 配置模板
├── src/
│   ├── interfaces.py           # 三方接口契约 (Protocol)
│   ├── core/                   # A同学：AI 引擎
│   │   ├── ai_engine.py        #   大模型对话（同步 + 异步双轨 API）
│   │   └── workers.py          #   QThread 工作线程（STT/TTS/Chat）
│   ├── system/                 # B同学：系统控制
│   │   ├── blocker.py          #   三级自动降级网站屏蔽器
│   │   └── controller.py       #   专注会话管理 + 数据库
│   └── ui/                     # C同学：用户界面
│       ├── main_window.py      #   主窗口
│       └── focus_overlay.py    #   专注模式全屏覆盖窗口
└── docs/plans/                 # 设计文档与开发计划
```

## 小组分工

| 角色 | 姓名 | 工作目录 | 核心任务 |
| :--- | :--- | :--- | :--- |
| **A - AI引擎师** | 潘韵伊 | `src/core/` | 大模型对话、QThread 语音工作线程、Prompt 工程 |
| **B - 系统安全官** | 刘晓川 | `src/system/` | 三级网站屏蔽、SQLite 数据库、专注会话管理 |
| **C - 产品体验官** | 王瑞 | `src/ui/` | PySide6 界面、专注覆盖窗口、matplotlib 图表 |

## 环境搭建与运行

> 本指南面向**电脑上没有任何开发环境**的同学，按顺序做完即可运行项目。

### 第 1 步：安装 Git

Git 是代码版本管理工具，用来从 Gitee 下载和同步项目代码。

1. 下载：https://git-scm.com/downloads/win
2. 安装时一路点 **Next** 用默认选项即可
3. 安装完成后打开**命令提示符**（按 `Win+R`，输入 `cmd`，回车），验证安装：

```bash
git --version
```

看到类似 `git version 2.xx.x` 的输出就说明安装成功。

### 第 2 步：安装 Python

本项目需要 **Python 3.10 ~ 3.13**，推荐安装 **Python 3.12**。

1. 下载：https://www.python.org/downloads/
2. **安装时务必勾选 `Add Python to PATH`**（页面最下方的复选框），然后点 Install Now
3. 安装完成后**重新打开**命令提示符，验证安装：

```bash
python --version
```

看到类似 `Python 3.12.x` 的输出就说明安装成功。如果显示的不是你安装的版本或者提示找不到命令，说明 PATH 没配好，需要重新安装并勾选 Add to PATH。

### 第 3 步：克隆项目

在命令提示符中，先切到你想放项目的目录（比如桌面），然后克隆：

```bash
cd %USERPROFILE%\Desktop
git clone https://gitee.com/pan-yunyi/voice-focus.git
cd voice-focus
```

### 第 4 步：创建虚拟环境

虚拟环境是项目专属的 Python 隔离空间，依赖装在里面不会影响系统。只需创建一次：

```bash
python -m venv .venv
```

执行后项目目录下会多出一个 `.venv` 文件夹。

### 第 5 步：激活虚拟环境并安装依赖

> **重要**：每次打开新的命令行窗口都需要先激活虚拟环境，激活后命令行前面会出现 `(.venv)` 前缀。

```bash
.venv\Scripts\activate
```

看到 `(.venv)` 前缀后，升级 pip 并安装项目依赖：

```bash
python -m pip install --upgrade pip
pip install -r requirements.txt
```

> **PyAudio 安装失败？** 这个包依赖 C 编译环境，Windows 上容易报错。改用以下命令：
> ```bash
> pip install pipwin
> pipwin install pyaudio
> ```

### 第 6 步：配置 API Key

```bash
copy .env.example .env
```

用记事本或编辑器打开项目目录下的 `.env` 文件，把 `sk-xxxxxxxxxxxxxxxxxxxxxxxx` 替换成你的 DeepSeek API Key。

> **没有 API Key？** 没关系，不改也能运行——AI 对话会返回 `[Mock AI]` 模拟回复，不影响其他功能。

### 第 7 步：运行项目

```bash
.venv\Scripts\activate
python main.py
```

窗口弹出后点击按钮，终端打印了状态信息就说明运行正常。

### 第 8 步：退出

关闭程序窗口后，在命令提示符中输入以下命令退出虚拟环境：

```bash
deactivate
```

`(.venv)` 前缀消失即表示已退回系统环境。

### 日常开发速查

以后每次开发只需要三步：

```bash
cd 你的项目路径\voice-focus
.venv\Scripts\activate
python main.py
```

### 依赖版本参考

> 以下版本经过适配验证（截至 2026-03-29）。`pip install -r requirements.txt` 会自动安装正确版本，无需手动指定。

| 依赖 | 包名 | 推荐版本 | 用途 |
| :--- | :--- | :--- | :--- |
| Python | — | 3.10 ~ 3.13（推荐 **3.12**） | 运行环境 |
| PySide6 | `PySide6` | ≥6.6, <7.0（最新 6.11） | Qt GUI 框架 |
| OpenAI SDK | `openai` | ≥1.14, <3.0（最新 2.30） | 大模型 API（对接 DeepSeek） |
| SpeechRecognition | `SpeechRecognition` | ≥3.10.1, <4.0（最新 3.15） | 语音识别 |
| PyAudio | `PyAudio` | ≥0.2.14 | 麦克风录音 |
| Edge-TTS | `edge-tts` | ≥6.1.9, <8.0（最新 7.2） | 微软在线语音合成 |
| matplotlib | `matplotlib` | ≥3.8.3, <4.0（最新 3.10） | 数据可视化图表 |
| python-dotenv | `python-dotenv` | ≥1.0, <2.0（最新 1.2） | 环境变量管理 |
| pytest | `pytest` | ≥8.1, <10.0（最新 9.0） | 单元测试 |
| SQLite | Python 内置 `sqlite3` | 3.41+（Python 3.12 自带） | 本地数据库 |
| DeepSeek API | 通过 `openai` 调用 | deepseek-chat (V3.2) | 大模型服务端 |

## 协作规范

### 分支模型

每人一个开发分支，定期合并到 `master`：

```bash
# 拉取最新代码
git checkout master
git pull origin master

# 切到自己的开发分支
git checkout dev-你的名字
git merge master

# 开发完成后提交
git add .
git commit -m "feat(模块名): 完成了xxx功能"
git push origin dev-你的名字

# 然后在 Gitee 上创建 Pull Request 合并到 master
```

### 目录隔离

- A 同学**只写** `src/core/` 下的文件
- B 同学**只写** `src/system/` 下的文件
- C 同学**只写** `src/ui/` 下的文件
- 公共文件（`interfaces.py`、`main.py`）修改前在群里沟通

### 调用别人的功能

查看 `src/interfaces.py` 中定义的接口，直接调用即可。当前未实现的方法会返回 Mock 数据，不影响你的开发。

### A/B 同学协作说明

如果你是 A 或 B 同学，请先阅读协作说明文档，里面包含 UI 已完成内容、接口依赖与联调流程：

- `docs/README_AB.md`

## 开发里程碑

| 阶段 | 时间 | 目标 |
| :--- | :--- | :--- |
| 第 1 周 | 3/25 - 3/31 | 架构搭建、接口定义、Mock 框架跑通 |
| 第 2 周 | 4/1 - 4/10 | 核心功能模块攻坚（AI 接入、网站屏蔽、UI 布局） |
| 第 3 周 | 4/11 - 4/17 | 系统集成联调，发布 Alpha 内测版 |
| 第 4 周 | 4/18 - 4/23 | 交叉测试、Bug 修复、UI 优化，发布 Beta 版 |
| 第 5 周 | 4/24 - 4/29 | 代码冻结、录制 Demo、撰写汇报 PPT |