# star

**Repository Path**: xiaojian221/star

## Basic Information

- **Project Name**: star
- **Description**: 基于大模型开发的一个用语音对话的方式来控制电脑的应用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-20
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 语音桌面助手（Voice Desktop Assistant）— 介绍&运行说明

> 版本：2025-10-25  

---

## 1. 项目简介（What & Why）

**语音桌面助手**是一套本地化智能自动化系统：前端支持文本/语音输入，后端通过 LLM 将意图解析成“可执行计划（Plan）”，执行器在 Windows 桌面上完成应用启动、UI 操作、音乐播放、提醒等任务；所有会话和动作均**落库到 MySQL**，用于当天/本周复盘与可视化看板。

**核心能力**

- 自然语言 / 语音指令 → 自动执行（打开应用、搜索、播放音乐、定时提醒等）
- 无坐标 UI 自动化（基于 **pywinauto(UIA)**，具有控件搜索/启发式聚焦）
- 新增指令（示例）：**收集今天的热点话题并整理素材（本地笔记生成）**、**消息提醒（本地系统级提醒 + 语音播报/蜂鸣）**
- 全流程**事件落库**（session / input / plan / action），支持**当天&本周复盘**并**排除中间动作**
- 简洁 API（登录 / 执行 / 统计）+ Vue 前端仪表盘

---

## 2. 技术栈（Tech Stack）

### 后端

- **FastAPI**（Web API, 认证、路由、CORS、静态资源）
- **PyJWT**（JWT 鉴权，HS256）
- **passlib[pbkdf2_sha256]**（密码哈希，避免 bcrypt 72 字节限制/版本冲突）
- **PyMySQL**（MySQL 读写，utf8mb4）
- **faster-whisper（可选）** + **ffmpeg（可选）**（本地 ASR & 音频转码）
- **pywinauto (UIA)**（Windows 桌面 UI 自动化）
- **pyttsx3 / PowerShell SAPI**（本地 TTS）
- **threading.Timer**（轻量定时提醒）
- **python-docx / Markdown**（文档/笔记输出，可选）

### 前端

- **REACT + Electron**
- 状态管理：**Pinia**
- 路由：**Vue Router**
- 网络：**Axios**（JWT Bearer Token）
- 主要页面：登录、控制台（指令输入/录音）、今日/本周复盘看板、设置

### 基础设施

- **MySQL 5.7+ / 8.0+**（建议 8.0）
- 操作系统：**Windows 10/11**（执行器依赖）

---

## 3. 架构总览（Architecture）

```
[REACT 前端] ──Axios──► [FastAPI]
    登录/控制台             │  认证/JWT/路由
    今日/本周看板          │  解析器 asr2plan(LLM)
                           │  执行器 executor(UI 自动化/TTS/提醒/笔记)
                           ▼
                       [MySQL]
                sessions / inputs / plans / actions / auth_users
```

**数据流（以“播放音乐”例）：**

1) 前端提交文本/录音 → `/agent/submit`  
2) 后端：ASR（可选）→ 解析器将文本转为 **Plan(JSON)**  
3) 执行器按 Plan 原语执行（聚焦输入框、搜索、回车、播放等）  
4) 全部 **事件落库**：输入 → Plan → 每一个动作（action）  
5) 前端从 `/analytics/day|week` 拉取数据，渲染复盘看板（**排除中间动作**）

---

## 4. 模块规格（Modules）

### 4.1 解析器 `asr2plan.py`

- 输入：自然语言文本
- 输出：Plan(JSON)：`{ say, actions:[{type, params, confirm}...] }`
- 规范：**actions** 必须是 JSON 对象数组（字符串会导致解析异常）
- 新增意图：在“正则/规则”或 LLM 提示词里加入新指令 → 产出规范化 action（如 `collect_hot_topics` / `schedule_reminder`）

### 4.2 执行器 `executor.py` / `step3_executor_windows_generic.py`

- 内置动作：`open_app/open_url/web_search/ui_sequence/say`
- 增强：`focus_search_box/paste/dump_tree/key/play_first_result`
- 新增动作：
  - **collect_hot_topics**：本地抓取热点（或调用 API/向量库），输出 **Markdown/Word**，不打开网页
  - **schedule_reminder**：解析 `delay_sec/at/at_ts`，定时在本机弹窗 + TTS/蜂鸣  
- 语音 & 声音：`say()` 使用 `pyttsx3` 或 PowerShell SAPI 兜底；提醒音 `winsound.Beep()`（Windows）

### 4.3 落库 `event_store.py`（MySQL）

- 表：
  - `agent_sessions(id, user_id, source, ts_created, ...)`
  - `agent_inputs(id, session_id, modality, text, audio_path, ...)`
  - `agent_plans(id, session_id, model, plan_json, ...)`
  - `agent_actions(id, session_id, type, params, ok, err, ts_created, ...)`
  - `auth_users(id, username, password_hash, created_at)`
- API：`start_session / log_input / log_plan / log_action / end_session / ensure_user`

### 4.4 Web API（FastAPI）

- `POST /auth/login`：登录获取 JWT
- `POST /agent/submit`：提交文本/音频，执行计划（或 dry-run）
- `GET  /analytics/day`：当天复盘（**排除中间动作**，仅统计外显意图）
- `GET  /analytics/week`：本周复盘（**排除中间动作**）
- 说明：外显意图白名单 `USER_VISIBLE_INTENTS=("open_app","open_url","web_search","play_music","collect_hot_topics","schedule_reminder")`

---

## 5. 数据模型（简版 DDL）

```sql
CREATE TABLE IF NOT EXISTS auth_users (
  id BIGINT PRIMARY KEY,
  username VARCHAR(64) UNIQUE,
  password_hash VARCHAR(128) NOT NULL,
  created_at DATETIME(3) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE IF NOT EXISTS agent_sessions (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id BIGINT,
  source VARCHAR(16),          -- text|voice|web
  asr_device VARCHAR(32),
  ts_created DATETIME(3) NOT NULL DEFAULT NOW(3)
);

CREATE TABLE IF NOT EXISTS agent_inputs (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  session_id BIGINT,
  modality VARCHAR(16),        -- text|voice
  text TEXT,
  audio_path VARCHAR(512),
  ts_created DATETIME(3) NOT NULL DEFAULT NOW(3)
);

CREATE TABLE IF NOT EXISTS agent_plans (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  session_id BIGINT,
  model VARCHAR(64),
  plan_json JSON,
  ts_created DATETIME(3) NOT NULL DEFAULT NOW(3)
);

CREATE TABLE IF NOT EXISTS agent_actions (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  session_id BIGINT,
  type VARCHAR(64),
  params JSON,
  ok TINYINT(1),
  err TEXT,
  ts_created DATETIME(3) NOT NULL DEFAULT NOW(3)
);
```

---

## 6. 运行环境 & 快速启动

### 6.1 前置

- **Windows 10/11**
- **Python 3.10+**
- **MySQL 8.0+**（确保已创建数据库，用户有表结构权限）
- （可选）**ffmpeg**：处理非 wav 音频转码
- （可选）显卡驱动（本地 ASR 需要 GPU 则配置 CUDA）

### 6.2 安装依赖

```bash
# 创建虚拟环境（示例）
conda create -n star python=3.10 -y
conda activate star

# 后端依赖
pip install fastapi uvicorn "python-multipart" pydantic pyjwt passlib[bcrypt]==1.7.4 pymysql
# 如 bcrypt 有冲突，保留 passlib 并使用 pbkdf2_sha256（默认已切 pbkdf2）
pip install passlib

# 可选：ASR
pip install faster-whisper soundfile

# UI 自动化 & TTS
pip install pywinauto pyttsx3 pyperclip
```

### 6.3 环境变量

```bash
set STAR_DB_HOST=127.0.0.1
set STAR_DB_PORT=3306
set STAR_DB_USER=root
set STAR_DB_PASSWORD=yourpass
set STAR_DB_NAME=star

# JWT
set STAR_JWT_SECRET=dev-secret-change-me
set STAR_TOKEN_TTL_MIN=120

# 默认用户
set STAR_DEFAULT_USER_ID=1
```

### 6.4 启动后端

```bash
python app.py
# 或
uvicorn app:app --reload --host 127.0.0.1 --port 8787
```

- 首次启动会自动创建 `auth_users` 和默认管理员：**admin/admin123**。

### 6.5 启动前端（遵循《前端设计文档》）

```bash
# Node 18+ / PNPM 或 NPM
npm run electron:dev
```

- `.env` 设置 `VITE_API_BASE=http://127.0.0.1:8787`  
- 登录后将 `token` 放到 `Authorization: Bearer <token>` 请求头

---

## 7. API 速查

### 7.1 登录

```
POST /auth/login
Body: { "username":"admin", "password":"admin123" }
Resp: { "token":"...", "user_id":1, "username":"admin", "expires_at":"..." }
```

### 7.2 执行任务

```
POST /agent/submit (multipart/form-data)
- mode: text|audio
- text: "打开QQ / 10秒后提醒我喝水 / 收集今天的热点话题并整理素材"
- audio: <file>             # mode=audio 时
- dry_run: false            # 预览不执行

Header: Authorization: Bearer <token>
Resp: { session_id, input_text, plan, result }
```

### 7.3 今日/本周复盘（**排除中间动作**）

```
GET /analytics/day?scope=me
GET /analytics/week?scope=me
Header: Authorization: Bearer <token>
```

---

## 8. 指令扩展指引（Intent & Action）

1. **解析层**：在 `asr2plan.py` 的规则或提示中加入新意图 → 产出统一 actions：  

   ```json
   {"type":"your_action","params":{"k":"v"}}
   ```

2. **执行层**：在 `executor.EXECUTORS` 注册处理函数：  

   ```py
   EXECUTORS["your_action"] = lambda p: your_action_impl(p)
   ```

3. **统计层**：如果是外显意图，加入 `USER_VISIBLE_INTENTS`；在 `/analytics/*` 查询中自然生效。

---

## 9. 故障排查（Troubleshooting）

- **401 登录失败**：确认 `admin/admin123`，或数据库 `auth_users` 是否存在；后端 `STAR_JWT_SECRET` 一致。  
- **AttributeError: jwt.encode**：请安装 `pyjwt` 而非 `jwt`：`pip uninstall jwt; pip install pyjwt`。  
- **bcrypt 相关错误**：已改用 `pbkdf2_sha256`；确保 `passlib` 安装完成。  
- **(1146) Table doesn't exist**：首次启动后端会建表；如未成功，请确认数据库连接/env。  
- **(2013) Lost connection to MySQL**：调大 `connect_timeout`、`wait_timeout`，或复用连接池；本项目已在查询前做**列存在检查**，长时 idle 场景建议定期 `ping(reconnect=True)`。  
- **UI 自动化无效/窗口被抢焦点**：执行器有 `wait_window/activate_app/focus_search_box`，必要时调整 `title_re`；使用 `dump_tree` 获取控件树。  
- **ASR 无法识别**：安装 `ffmpeg` 并传 WAV；或禁用 ASR，直接用 `mode=text`。

---

## 10. 安全与权限

- JWT 有效期可通过 `STAR_TOKEN_TTL_MIN` 调整；  
- 存储最小化：仅落库必要的参数（敏感数据避免入库）；  
- Windows 上 UI 自动化建议在**本地用户桌面会话**执行；若做服务化需 Session 0 → 会话注入/代理（不在本项目范围）。

---

## 11. 未来路线（Roadmap）

- 插件化意图中心（统一注册/路由）  
- 本地向量检索（热点材料/企业知识库）  
- 更完善的调度（APScheduler/Windows 计划任务）  
- 前端富交互的“自动化食谱”与“一键复用”  
- 权限与审计（多用户、多终端）

---

## 12. 版权与协议

本项目用于内部学习与演示。第三方应用/网站的抓取与自动化请遵守其服务条款。