简介

环境要求

项目以 Windows 桌面应用为主要交付目标，开发环境需要 Node.js、npm 和可访问外部 OTA 平台及云端数据库的网络环境。

安装

在项目根目录安装主应用依赖：

npm install

如果需要单独开发爬虫或数据库子项目，再分别安装对应依赖：

cd scripts/ai-web-crawler
npm install

cd ../../database
npm install

配置

大模型配置位于根目录 llm-config.json。正式发布时请使用模板值或环境注入，不要提交真实密钥。

{
  "provider": "openai",
  "apiKey": "YOUR_API_KEY",
  "baseURL": "https://example.com/v1",
  "model": "model-name",
  "temperature": 0.7,
  "maxTokens": 4096
}

应用启动后，ConfigManager 会读取该文件并同步到 Electron 用户数据目录。窗口尺寸、日志路径、语言、Skill 路径和数据库连接也由配置管理器统一维护。

提供商

系统支持多个模型提供商。不同提供商通过统一的 Agent 接口接入，业务层不需要关心具体模型来源。

网络

应用需要同时访问模型服务、云端 MySQL、OTA 公网和 OTA 商家后台。若部署在酒店内网或受限网络中，应提前放通相关域名和端口。

初始化

开发模式建议开两个终端：一个负责 Webpack 监听，一个负责启动 Electron。

npm run dev
npm start

首次进入应用后完成登录，系统会初始化数据库、Agent、Skill、心跳任务和浏览器视图。

使用

在左侧浏览器登录 OTA 平台，在右侧 AI 助手输入自然语言需求。AI 会根据意图选择合适的 Skill。

Windows

当前项目以 Windows 为主要交付平台，打包配置使用 NSIS 安装器。启动脚本中包含 chcp 65001，用于保证中文日志和命令行输出使用 UTF-8 编码。

生产环境建议使用打包后的安装包或便携版，不建议直接在用户机器上运行开发模式。

AI 浏览器

应用内置 BrowserView，支持多标签、导航控制、Google 登录状态同步，并开放本地 CDP 端口供 Playwright 自动化连接。

AI 助手

AI 助手由 PiAgentManager 管理，负责模型调用、会话历史、工具上下文、进度事件和 Skill 调用。

数据看板

Dashboard 通过 preload 暴露的安全 IPC 访问主进程，再由主进程读取数据库中的房价、房态、竞品和日历数据。

定时任务

心跳任务配置位于 tasks/schedule.json。修改配置后需要重启应用。

{
  "id": "api-booking-backend",
  "skill": "api-booking-backend-price",
  "platform": "booking",
  "cron": "40 20 * * *",
  "enabled": true,
  "params": {
    "cookieDomain": "admin.booking.com",
    "hotelId": 15994510
  }
}

自动恢复

自动恢复是系统的核心闭环。它用于处理 OTA 接口改版、Cookie 变化、请求参数变化、API 返回空壳等情况。

HeartbeatManager.executeTask()
  -> 执行当前 API 脚本
  -> 检测响应是否为空
  -> 策略 B：读取脚本并尝试修复
  -> 策略 A：调用爬虫重新拦截 API
  -> 写入新脚本
  -> 再次执行并验证
  -> data-store 入库

恢复流程不会只依赖 Agent 的文字判断，而是会通过独立数据验证确认输出文件是否可用。

智能调价

smart-pricing 负责生成调价建议，smart-price-adjust 负责在 OTA 后台执行调价。建议和执行是分离的，生产环境应先确认方案再执行真实修改。

智能回复

smart-reply 会从当前浏览器页面提取评价、点评或 IM 消息内容，并生成可直接复制使用的专业回复。

适用场景包括差评安抚、好评感谢、客诉回应、咨询回复和平台消息处理。

整体架构

项目由 Electron 主应用、Skills 定义层、Scripts 执行层、Agent Prompt、数据库模块和定时任务配置组成。

Hotel-Agent/
├── src/          # Electron 主应用源码
├── skills/       # Skill 定义
├── scripts/      # Skill 可执行脚本
├── agent/        # Agent 人设和 Prompt
├── database/     # 数据库访问模块
├── tasks/        # 定时任务配置
├── data/         # 运行时数据
└── docs/         # 项目文档

主进程

src/main/ 是项目的业务中心，负责窗口、浏览器、登录认证、数据库、Agent、Skill、调度和日志。

渲染进程

src/renderer/ 负责前端 UI，包括分屏布局、地址栏、聊天面板、登录页、酒店控制台和质检页面。

Skills

skills/ 中每个目录都包含一个 SKILL.md。系统启动时扫描并注册 Skill。

Scripts

scripts/ 是工具执行层，包含 API 采集脚本、数据入库、数据库查询、文件操作、Playwright 爬虫和 OTA 自动调价。

数据库

database/ 是独立 TypeScript 子项目，主应用通过构建产物访问 MySQL。

数据流

系统的数据流分为实时采集、解析入库和历史查询三层。

实时采集:
用户/定时任务 -> SkillExecutor -> api-* script -> OTA API -> 原始 JSON

解析入库:
原始 JSON -> data-store adapter -> 标准结构 -> MySQL

历史查询:
Dashboard/AI 助手 -> IPC -> databaseManager -> MySQL -> UI/对话结果

API 请求统一经过 scripts/api-runtime，该运行时负责 Cookie 注入、限速、重试、重定向和标准输出。

IPC

渲染进程不直接访问 Node.js、Electron 或数据库。所有能力由 src/preload/index.ts 通过 contextBridge 暴露。

本地开发

推荐以主项目为入口开发。涉及爬虫或数据库模块时，再进入对应子项目单独编译。

# 主应用开发
npm run dev
npm start

# 爬虫子项目
cd scripts/ai-web-crawler
npm run build

# 数据库子项目
cd database
npm install

主应用的 Webpack 配置包含 main、preload、renderer 和 google-auth-subprocess 四个入口。

添加 Skill

新增 Skill 通常需要同时添加定义文件和执行脚本。

skills/my-new-skill/SKILL.md
scripts/my-new-skill/index.js

SKILL.md 需要包含名称、描述、脚本路径、类型、参数定义和使用说明。脚本应通过标准输入或参数读取上下文，并将 JSON 结果输出到标准输出。

测试

项目使用 Jest 和 ts-jest。当前测试覆盖心跳任务、记忆系统、国际化和部分主进程模块。

npm test
npm run test:watch

涉及真实 OTA 平台、Cookie、远程数据库和调价提交的能力，建议使用测试账号进行手工链路验证。

安全

应用遵循 Electron 安全实践：渲染进程不直接启用 Node.js 能力，所有操作通过 preload 暴露的白名单 API 完成。

命令

日志

应用日志默认写入 Electron 用户数据目录，文件名为 hotel-ai-browser.log。开发阶段还可以查看 data/api-results/ 和诊断 JSON 文件。

打包发布

应用使用 electron-builder 打包，产物输出到 release/。

npm run build
npm run package

新增 Skill 或 Script 后，需要确认 package.json 的 extraResources 已包含对应资源。