93 lines
5.1 KiB
Markdown
93 lines
5.1 KiB
Markdown
# 项目概览：zn-ai (智念AI)
|
||
|
||
**zn-ai** 是一款基于 Electron 和 Vue 3 构建的桌面应用程序，旨在自动化处理各类酒店管理平台（OTA）的任务，如飞猪、美团、抖音和携程/去哪儿。它结合了传统的浏览器自动化技术（通过 Playwright）与 AI 能力（集成 OpenAI），以提供智能辅助功能。
|
||
|
||
## 技术栈
|
||
|
||
* **核心框架**: Electron (v38), TypeScript
|
||
* **前端**: Vue 3, Vite, TailwindCSS, Element Plus
|
||
* **自动化**: Playwright (通过 CDP 连接), Node.js 子进程
|
||
* **AI 集成**: OpenAI SDK (流式对话补全)
|
||
* **构建工具**: Electron Forge, Vite
|
||
* **状态管理**: Pinia
|
||
* **持久化存储**: electron-store, dexie (IndexedDB 封装)
|
||
|
||
## 项目结构
|
||
|
||
### `src/main` (主进程)
|
||
处理应用生命周期、窗口管理、IPC 通信以及任务编排。
|
||
|
||
* **`process/`**: 包含核心业务逻辑。
|
||
* `runTaskOperationService.ts`: 管理任务操作，启动本地 Chrome，并执行自动化脚本。
|
||
* `runAgentService.ts`: AI Agent 执行的占位符/入口。
|
||
* **`service/`**: 各种功能的模块化服务。
|
||
* `execute-script-service/`: 启动 Node.js 子进程以安全地运行自动化脚本。
|
||
* `config-service/`: 管理应用程序配置。
|
||
* `logger/`: 使用 `electron-log` 进行集中式日志记录。
|
||
* `window-service/`: 管理 Electron 窗口。
|
||
* **`providers/`**: AI 模型提供商。
|
||
* `OpenAIProvider.ts`: 支持流式传输的 OpenAI 对话补全实现。
|
||
* **`scripts/`**: 由主进程执行的自动化脚本。
|
||
* `fg_trace.js`: 飞猪自动化脚本。
|
||
* `mt_trace.js`: 美团自动化脚本。
|
||
* `dy_hotel_trace.js` / `dy_hot_spring_trace.js`: 抖音自动化脚本。
|
||
* `xc_trace.js`: 携程/去哪儿自动化脚本。
|
||
* `open_all_channel.js`: 在浏览器中打开所有已配置渠道的脚本。
|
||
* `common/tabs.js`: 用于连接 Chrome 并智能管理/复用标签页的工具。
|
||
* **`utils/chrome/`**: Chrome 管理助手。
|
||
* `launchLocalChrome.ts`: 启动带有 `--remote-debugging-port=9222` 参数的本地 Chrome 实例。
|
||
|
||
### `src/renderer` (渲染进程)
|
||
使用 Vue 3 构建的用户界面。
|
||
|
||
* **`views/`**: Vue 页面组件。
|
||
* `dashboard/`: 主仪表盘。
|
||
* `home/`: 聊天界面（AI 交互）和任务中心。
|
||
* `task/`: 任务管理视图。
|
||
* `setting/`: 应用程序设置（账号、渠道、系统配置）。
|
||
* **`components/`**: 可复用的 UI 组件（Header, SideMenus, TaskList）。
|
||
* **`api/`**: 后端或 IPC 通信的 API 定义。
|
||
* **`store/`**: 用于状态管理的 Pinia store（用户信息等）。
|
||
|
||
### `src/common`
|
||
主进程和渲染进程共用的常量、类型和工具。
|
||
|
||
## 核心功能与架构
|
||
|
||
### 1. 本地 Chrome 自动化
|
||
本应用不使用 Electron 自带的浏览器进行自动化。相反，它会启动一个开启了远程调试（`--remote-debugging-port=9222`）的 **本地 Google Chrome 实例**。这使得自动化脚本能够挂载到一个“真实”的浏览器会话中，从而保留 Cookie、登录状态和扩展程序。
|
||
|
||
### 2. 任务执行流程
|
||
1. **触发**: 用户从 UI 发起任务或打开渠道。
|
||
2. **IPC**: 渲染进程向主进程发送 IPC 消息（`IPC_EVENTS.OPEN_CHANNEL` 或 `IPC_EVENTS.EXECUTE_SCRIPT`）。
|
||
3. **服务**: `runTaskOperationService` 处理该请求。
|
||
* 确保本地 Chrome 正在运行 (`launchLocalChrome`)。
|
||
* 根据渠道或任务类型决定运行哪个脚本。
|
||
4. **执行**: `executeScriptService` 启动一个独立的 Node.js 子进程（使用带有 `ELECTRON_RUN_AS_NODE` 的 `process.execPath`）来运行特定的 `.mjs` 脚本。
|
||
5. **自动化**: 脚本（例如 `fg_trace.mjs`）使用 `playwright` 连接到 `http://127.0.0.1:9222`。
|
||
* 它使用 `common/tabs.js` 查找目标 URL 的现有标签页或创建一个新标签页。
|
||
* 它在页面上执行操作（导航、点击、抓取）。
|
||
|
||
### 3. 标签页管理策略
|
||
`src/main/scripts/common/tabs.js` 模块提供了智能的标签页复用功能：
|
||
* **目标匹配**: 检查现有标签页是否匹配目标 URL 或源（Origin），以避免打开重复的标签页。
|
||
* **空白页复用**: 如果可用，复用 `about:blank` 标签页。
|
||
* **标签页索引**: 可以针对特定的标签页索引（用于有序打开渠道）。
|
||
* **隐身模式 (Stealth)**: 注入脚本以隐藏自动化信号（`navigator.webdriver`）。
|
||
|
||
### 4. AI 集成
|
||
应用程序集成了兼容 OpenAI 的 API（在 `OpenAIProvider` 中配置）以提供聊天功能。`home` 视图可能作为用户与 AI Agent 交互的界面，潜在用于指导任务或检索信息。
|
||
|
||
### 5. 渠道支持
|
||
应用程序支持多个 OTA 渠道，配置在 `src/renderer/constant/channel.ts` 并在 `runTaskOperationService.ts` 中映射：
|
||
* **飞猪 (fz)**
|
||
* **美团 (mt)**
|
||
* **抖音 (dy)** - 酒店和温泉类别
|
||
* **携程/去哪儿 (xc)**
|
||
|
||
## 开发命令
|
||
|
||
* `npm start`: 以开发模式启动应用 (Electron + Vite HMR)。
|
||
* `npm run package`: 打包应用程序以进行分发。
|
||
* `npm run lint`: 对代码库进行 Lint 检查。
|