# LJWShowProject

**Repository Path**: software-engineering-pre-project/ljwshow-project

## Basic Information

- **Project Name**: LJWShowProject
- **Description**: 前端显示
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-06
- **Last Updated**: 2026-01-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 玄浮窗 (XuanFuChuang) - AI 桌面助手

一个基于 Electron + Vue 3 的智能桌面悬浮球助手，集成语音识别、语音合成、大语言模型对话和应用管理功能。

## ✨ 主要特性

- **智能对话**: 基于大语言模型的智能聊天系统（支持 DeepSeek、OpenAI 等）
- **语音交互**: 集成语音识别（ASR）和语音合成（TTS）
- **工具调用**: 支持网络搜索、时间查询、应用管理等实用工具
- **悬浮球界面**: 优雅的桌面悬浮窗 UI，支持拖拽和自动隐藏
- **多线程对话**: 支持多个独立会话线程，历史记录持久化
- **文本选中监听**: 全局文本选中弹窗功能

## 🏗️ 项目架构

```
xuanfuchuang/
├── desktop_pet/           # Electron + Vue 3 桌面应用
│   ├── src/
│   │   ├── App.vue        # 主应用组件
│   │   ├── main/          # Electron 主进程
│   │   └── components/    # Vue 组件
│   └── scripts/
│       └── dev-with-backends.js  # 多服务启动脚本
├── XTT_INTEGRATION.md     # XTT 语音模型集成文档
└── README.md
```

### 后端服务依赖

项目依赖以下外部服务（需独立部署）：

- **SHUO (端口 30701)**: 基于 LangChain/LangGraph 的 LLM 聊天服务
- **SHUN Apollo (端口 30702)**: 文本选中监听和应用管理服务
- **XIN ASR (端口 30703)**: 语音识别服务
- **CHAO TTS (端口 30704)**: 语音合成服务

## 🚀 快速开始

### 环境要求

- Node.js 18+
- Python 3.11+ (用于后端服务)
- Windows 操作系统

### 安装依赖

```bash
cd desktop_pet
npm install
```

### 配置说明

在 `desktop_pet/src/configelse.txt` 中配置 API：

```
ChatAPI:/init kimi-k2-turbo-preview https://api.moonshot.cn/v1 sk-your-api-key 0.6
SearchAPI:tvly-your-tavily-key
VoiceChoice:false
```

格式说明：
- `ChatAPI`: `/init 模型名 API地址 API密钥 温度`
- `SearchAPI`: Tavily 搜索引擎 API 密钥
- `VoiceChoice`: `true` 启用语音，`false` 禁用语音

### 启动应用

```bash
# 开发模式（自动启动所有后端服务）
npm run dev

# 构建生产版本
npm run build
```

启动脚本会自动：
1. 清理端口 30701-30704 上的占用进程
2. 依次启动 Vite、SHUO、XIN ASR、CHAO TTS、SHUN Apollo
3. 确保 Apollo 服务正确安装和初始化

## 🔧 功能说明

### 对话功能
- 支持流式响应，实时显示 AI 回复
- 自动调用工具（搜索、时间、打开应用等）
- 多线程管理，可创建和切换不同会话

### 语音功能
- 点击语音按钮进行语音识别
- AI 回复自动语音播报（可配置开关）
- 支持中断和重新录音

### 历史记录
- 查看所有会话线程
- 点击切换到历史会话
- 消息显示：用户消息在右侧，AI 回复在左侧

### 应用管理
- 通过对话打开应用："帮我打开记事本"
- 自动识别应用名称并执行

## 📡 API 集成

### SHUO 服务
- `POST /llm/init`: 初始化 LLM 配置
- `POST /tools/tavily/init`: 初始化搜索工具
- `POST /chat/stream`: 流式聊天
- `GET /threads`: 获取会话列表
- `GET /threads/{id}/messages`: 获取会话历史

### Apollo 服务
- `POST /GetExePath`: 获取可执行文件路径
- `POST /OpenApp`: 打开指定应用程序

### ASR 服务
- `POST /asr`: 语音识别

### TTS 服务
- `POST /tts`: 文本转语音

## 🛠️ 开发说明

### 启动脚本工作流程

`scripts/dev-with-backends.js` 负责：
1. 检测并清理端口占用（Windows netstat + taskkill）
2. 查找各服务的 Python 虚拟环境
3. 安装 Apollo 为可编辑包（`pip install -e`）
4. 并行启动所有服务
5. 处理进程退出和错误

### 服务初始化时序

1. 前端启动后等待 3 秒（确保 SHUO 服务就绪）
2. 加载 `configelse.txt` 配置
3. 调用 `/llm/init` 初始化 LLM 模型
4. 调用 `/tools/tavily/init` 初始化搜索工具
5. 工具绑定完成，AI 可调用所有功能

### 消息类型映射

- **后端（LangChain）**: `human`, `ai`, `humanmessage`, `aimessage`, `tool`
- **前端显示**: `user`（右侧）, `assistant`（左侧）

### 响应格式

SHUO 服务返回统一格式：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    // 实际数据
  }
}
```

## 🔒 安全说明

- API 密钥通过配置文件管理，不会硬编码
- IPC 通信使用白名单机制
- 文件操作限制在配置目录

## 📝 更新日志

### 最新版本
- ✅ 迁移至 SHUO LLM Chat 服务（替代 WTS2）
- ✅ 迁移至 SHUN Apollo 服务（替代 LCS）
- ✅ 修复端口冲突自动清理
- ✅ 修复 Apollo 服务启动（可编辑安装）
- ✅ 优化服务初始化时序（3秒延迟）
- ✅ 修复历史记录显示和消息角色映射
- ✅ 修复应用打开功能（工具绑定）

### 历史版本
- 对接 XTT v2.0 语音模型
- 整合应用管理服务
- 添加全局文本选中弹窗
- 初版语音 + 多聊天功能

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request。

## 📄 许可证

[根据实际情况添加许可证]

## 🆘 常见问题

### Q: 服务启动失败怎么办？
A: 检查端口 30701-30704 是否被占用，脚本会自动尝试清理。

### Q: Apollo 服务无法启动？
A: 确保 SHUN/apollo 目录存在且包含 `.venv` 虚拟环境，脚本会自动安装。

### Q: 语音功能无法使用？
A: 检查 ASR (30703) 和 TTS (30704) 服务是否正常启动。

### Q: AI 无法打开应用？
A: 确保 Apollo 服务 (30702) 正常运行，并且服务启动后等待至少 3 秒再使用。

### Q: 历史记录显示异常？
A: 清除浏览器缓存或检查 SHUO 服务是否正常返回数据。