# ElectronClient

**Repository Path**: YYKACN/ElectronClient

## Basic Information

- **Project Name**: ElectronClient
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 运营咖 · AI 口播工坊 — Electron 桌面客户端

基于 **Electron 42** 的桌面应用，为「AI 智能口播视频生成工具」提供 Windows 桌面端运行环境。客户端负责管理 3 个 Python 后端服务（API、TTS、数字人引擎）的全生命周期，并通过 Chromium 内核渲染 React 前端界面。

在线体验：[www.yyka.cn](https://www.yyka.cn) — 运营咖 AI 智能创作平台。

> 🛒 **源码售价：¥799 元（买断制）** — 含全部源码，提供本地部署指导，一次付费终身使用。
> ### 联系方式

- 📧 **邮箱**：yykacn@qq.com
- 💬 **微信/QQ**：188895970
- 🐛 **技术问题**：直接提 [GitHub Issue](https://github.com/mengdongshike/ai_video_tool/issues)
- 💼 **商务合作**：邮件标题注明「AI口播工坊 商业合作」

---

## 目录

- [项目简介](#项目简介)
- [架构说明](#架构说明)
- [快速开始](#快速开始)
- [进程管理机制](#进程管理机制)
- [开发指南](#开发指南)
- [打包分发](#打包分发)
- [商业化信息](#商业化信息)

---

## 项目简介

**运营咖 AI 口播工坊**（`ai-video-tool`）是一套面向自媒体运营者的桌面工具，提供 AI 驱动的一键口播视频生成能力。桌面客户端作为整个系统的：

- **启动器**：环境检测 → 依赖安装 → 服务拉起 → 界面跳转，全流程自动化
- **进程管家**：管理 3 个 Python 微服务（API、TTS 语音合成、数字人推理）的启动/监控/优雅退出
- **容器壳**：以无框 Chromium 窗口承载 Vite + React 前端，通过 `contextBridge` 暴露安全的 IPC 通信

### 核心功能

| 功能 | 描述 |
|------|------|
| 环境检测 | 启动时自动检测 GPU、CUDA、Python 虚拟环境、模型文件是否完备 |
| 服务编排 | 按依赖顺序启动 API → TTS → Latent 三个服务，完成后自动跳转主界面 |
| 平台登录 | 内嵌浏览器窗口支持抖音、小红书、B站 Cookie 扫码/账密登录 |
| 封面编辑器 | 独立的封面设计编辑窗口 |
| 优雅退出 | 关闭时先 SIGTERM 后 `taskkill /F /T` 清除进程树，不留僵尸进程 |

---

## 架构说明

```
ElectronClient/
├── package.json                # Electron 42 + electron-builder 配置
├── dist/                       # 打包产物（exe 安装包等）
├── src/
│   ├── index.html              # 主界面入口（Vite 构建的 React SPA）
│   ├── main/                   # 主进程 (Node.js)
│   │   ├── main.js             # 应用入口：窗口管理、IPC 注册、启动流程编排
│   │   ├── service_manager.js  # 进程管理器：环境检测、依赖安装、服务启停
│   │   └── login-preload.js    # 登录窗口 preload：反爬虫伪装（隐藏 webdriver 等）
│   ├── renderer/               # 渲染进程
│   │   ├── preload.js          # contextBridge API 暴露
│   │   └── loading.html        # 启动加载页（进度条 + 品牌展示）
│   └── assets/                 # 图标、Vite 编译产物
```

### 技术栈

| 层 | 技术 |
|----|------|
| **桌面框架** | Electron 42.0.0 |
| **打包** | electron-builder 26.x |
| **主进程** | Node.js（CommonJS） |
| **渲染进程** | React + TypeScript + Vite |
| **IPC 通信** | `contextBridge` + `ipcRenderer.invoke` / `webContents.send` |
| **进程管理** | `child_process.spawn` / `execFile` |

### 系统拓扑

```
┌─────────────────────────────────────────┐
│         Electron 主进程                   │
│  main.js  ←── 启动流程编排 ──→ app       │
│    │                                    │
│    ├── ServiceManager                   │
│    │   ├── checkEnv()   (Python 脚本)    │
│    │   ├── installDeps() (按需装 torch)   │
│    │   └── startAll()                   │
│    │       ├── spawn: api_server.py  :8000│
│    │       ├── spawn: tts_service.py :8101│
│    │       └── spawn: latent_service.py:8102│
│    │                                    │
│    └── BrowserWindow                    │
│        ├── loading.html (启动进度条)       │
│        ├── index.html  (React 主界面)    │
│        └── 登录窗口 (各平台 Cookie 采集)   │
└─────────────────────────────────────────┘
```

### 三个 Python 服务

| 服务 | 端口 | 虚拟环境 | 说明 |
|------|------|---------|------|
| **API 服务** | `8000` | 项目内置 `python/` | 主业务 API，含 Cookie 存储接口 |
| **TTS 服务** | `8101` | `venv_tts` | 文字转语音合成引擎 |
| **Latent 服务** | `8102` | `venv_latent` | 数字人推理引擎 |

---

## 快速开始

### 环境要求

- **操作系统**：Windows 10/11 (x64)
- **Node.js**：≥ 18.x
- **Python**：项目内置 `AI_video_tool/python/python.exe`（无需系统安装 Python）
- **GPU**：NVIDIA 显卡（推荐 GTX 1060 及以上），用于数字人推理加速

### 安装与启动

```bash
# 1. 克隆仓库（或直接进入项目目录）
cd ElectronClient

# 2. 安装 Node 依赖
npm install

# 3. 启动开发模式（直接加载本地文件）
npm start

# 4. （可选）开发模式下前端 Vite 热更新
# 在另一个终端：
cd src
npx vite --port 5173
```

启动后，客户端将依次执行：

1. **环境检测** → 运行 `scripts/check_env.py` 检查 GPU/CUDA/模型
2. **依赖修复** → 自动修正虚拟环境路径，按需安装缺失的 torch 包
3. **服务启动** → 按 8000 → 8101 → 8102 顺序启动，每个服务等待端口就绪
4. **界面跳转** → 从 `loading.html` 切换到 React 主界面

### 目录依赖

客户端依赖上级目录的 Python 项目：

```
F:\Hermes\
├── ElectronClient\       # ← 本目录（Electron 桌面客户端）
└── AI_video_tool\        # Python 后端项目
    ├── python\           # 内置 Python 解释器
    ├── venv_tts\         # TTS 虚拟环境
    ├── venv_latent\      # 数字人虚拟环境
    ├── services\         # Python 服务脚本
    │   ├── api_server.py
    │   ├── tts_service.py
    │   └── latent_service.py
    └── scripts\          # 工具脚本
        ├── check_env.py
        └── install_deps.py
```

---

## 进程管理机制

### 生命周期

```
app.whenReady()
    │
    ├─ 1. ServiceManager.checkEnv()
    │     └─ execFile(python, check_env.py) → JSON 报告
    │
    ├─ 2. ServiceManager._repairAllVenvs()
    │     └─ 修正 venv_tts/venv_latent 的 pyvenv.cfg 路径（首次运行）
    │
    ├─ 3. ServiceManager.installDeps()
    │     └─ spawn(python, install_deps.py) → 按需安装 torch + 缺失包
    │
    ├─ 4. ServiceManager.startAll()
    │     ├─ start('api', 'python', 'api_server.py', 8000)
    │     ├─ start('tts', 'venv_tts', 'tts_service.py', 8101)
    │     └─ start('latent', 'venv_latent', 'latent_service.py', 8102)
    │
    └─ 5. win.loadFile('index.html')
```

### 服务启动 (`ServiceManager.start`)

- 使用 `child_process.spawn` 启动 Python 子进程
- 启动后轮询 `127.0.0.1:{port}` 直到 TCP 连接成功（最长等待 60s）
- 所有子进程的 stdout/stderr 会打印到主进程控制台

### 优雅退出 (`ServiceManager.stopAll`)

```
1. 对所有子进程发送 SIGTERM
2. 等待 500ms
3. 对每个 PID 执行: taskkill /F /T /PID {pid}
   └─ /T: 同时杀死整个进程树（防止 uvicorn/torch 子进程残留）
4. 清空服务记录
```

> **注意**：只杀死本程序启动的进程，不会影响系统中其他 Python 程序。

### 进度回调

`ServiceManager` 通过回调函数向渲染进程推送实时进度：

```js
manager.setProgressCallback((percent, message, detail) => {
    win.webContents.send('progress-update', { percent, message, detail });
});
```

渲染进程通过 `preload.js` 暴露的 `electronAPI.onProgressUpdate()` 接收，驱动 `loading.html` 的进度条和状态文字。

### Cookie 管理

登录窗口通过 `login-preload.js` 伪装成真实 Chrome 浏览器（隐藏 `navigator.webdriver`、注入 `window.chrome` 等），在用户完成平台登录后：

1. 拦截窗口关闭事件
2. 提取 Cookie（按平台域名过滤）
3. 通过 HTTP POST 发送到后端 API（`/api/cookies/{platform}` 和 `/api/publish/cookies/{platform}`）
4. 通知主窗口 `cookie-updated` 事件

---

## 开发指南

### 目录结构

```
ElectronClient/
├── package.json
├── src/
│   ├── main/              # 主进程（Node.js）
│   │   ├── main.js        # 应用入口 & IPC 注册
│   │   ├── service_manager.js  # 进程管理核心
│   │   └── login-preload.js    # 登录窗口反检测
│   ├── renderer/          # 渲染进程
│   │   ├── preload.js     # contextBridge API
│   │   └── loading.html   # 启动页
│   ├── index.html         # 主界面（Vite 构建产物入口）
│   └── assets/            # 静态资源（图标、构建产物）
└── dist/                  # electron-builder 打包输出
```

### 添加新的 IPC 通道

1. 在 `src/renderer/preload.js` 中通过 `contextBridge.exposeInMainWorld` 暴露方法
2. 在 `src/main/main.js` 中通过 `ipcMain.handle` 注册处理器
3. 渲染进程调用：`window.electronAPI.yourMethod()`

```js
// preload.js
contextBridge.exposeInMainWorld('electronAPI', {
    yourMethod: (arg) => ipcRenderer.invoke('your-channel', arg),
});

// main.js
ipcMain.handle('your-channel', async (event, arg) => {
    // 处理逻辑
    return result;
});
```

### 添加新的 Python 服务

在 `ServiceManager.startAll()` 中添加一行：

```js
await this.start('service_name', 'venv_name', 'script.py', port);
```

参数说明：
- `service_name`：日志标签
- `venv_name`：虚拟环境目录名（或 `'python'` 使用内置 Python）
- `script.py`：`services/` 下的脚本文件名
- `port`：服务监听端口

### 调试

```bash
# 开启 Electron DevTools（开发模式）
npm start

# 主进程日志会打印到启动终端
# 渲染进程可通过 Ctrl+Shift+I 打开 Chrome DevTools
```

---

## 打包分发

### 构建配置

使用 **electron-builder**，配置在 `package.json` 的 `build` 字段：

```json
{
  "build": {
    "win": {
      "icon": "./src/assets/icon.ico"
    },
    "directories": {
      "output": "dist",
      "buildResources": "build"
    }
  }
}
```

### 打包命令

```bash
# 生成 Windows 安装包（NSIS）
npm run build
```

产物输出到 `dist/` 目录：
- `ai-video-tool Setup 1.0.0.exe` — NSIS 安装程序
- `ai-video-tool Setup 1.0.0.exe.blockmap` — 增量更新块映射
- `builder-effective-config.yaml` / `builder-debug.yml` — 构建调试信息

### 分发包内容

打包时需要确保以下资源随包分发：

| 资源 | 说明 |
|------|------|
| `AI_video_tool/` | Python 后端（需与 exe 同目录或相对路径） |
| `AI_video_tool/python/` | 内置 Python 解释器 |
| `AI_video_tool/venv_tts/` | TTS 虚拟环境 |
| `AI_video_tool/venv_latent/` | 数字人虚拟环境 |
| `AI_video_tool/models/` | AI 模型文件 |
| `ai-video-tool Setup 1.0.0.exe` | 安装程序 |

> ⚠️ **注意**：当前 `package.json` 的 `build.files` 为空数组 `[]`，打包时不会自动包含 Python 后端。完整分发需要额外配置 `extraResources` 或将 Python 目录与 exe 一起部署。

---

## 商业化信息

### 品牌

- **品牌名**：运营咖（YYKA）
- **产品名**：AI 口播工坊
- **定位**：面向自媒体运营者的一站式 AI 口播视频生成桌面工具

### 目标用户

- 短视频创作者（抖音、小红书、B站）
- 企业新媒体运营团队
- 教育培训机构内容制作

### 盈利模式建议

| 模式 | 说明 |
|------|------|
| **SaaS 订阅** | 按月/年付费，提供不同套餐（视频时长、数字人数量、音色库） |
| **点数计费** | 按实际生成的视频分钟数消耗点数 |
| **企业定制** | 为企业客户提供私有化部署 + 定制数字人形象 |
| **增值服务** | 高级音色库、专属数字人克隆、批量制作等增值功能 |

### 授权与许可

- 项目许可证：MIT
- 第三方依赖许可证请参见各依赖包的声明

### 免责声明

本工具仅供合法用途。使用者应确保：
- 拥有生成内容中使用的肖像、声音等素材的合法授权
- 遵守各内容平台的用户协议和相关法律法规
- 生成的内容不侵犯第三方知识产权

---

## License

MIT © 运营咖