402 lines
8.7 KiB
Markdown
402 lines
8.7 KiB
Markdown
# Browser Helper - 浏览器自动化助手使用指南
|
||
|
||
## 项目简介
|
||
|
||
browser-helper 是一个基于 Playwright 的浏览器自动化助手工具，主要用于自动化收集和整理小红书平台信息。通过 AI 辅助过滤无效信息，帮助用户高效收集和整理数据。
|
||
|
||
## 核心功能
|
||
|
||
- **浏览器自动化控制**：通过 Playwright 控制浏览器执行自动化操作
|
||
- **小红书数据采集**：自动搜索、收集笔记、用户、标签等信息
|
||
- **本地数据存储**：使用 SQLite + Drizzle ORM 持久化存储
|
||
- **API 接口服务**：提供 RESTful API 供 AI 助手调用
|
||
|
||
## 技术栈
|
||
|
||
- **运行时**: Bun / Node.js
|
||
- **数据库**: SQLite + Drizzle ORM
|
||
- **浏览器自动化**: Playwright
|
||
- **API 框架**: @kevisual/router
|
||
- **缓存**: LRU Cache
|
||
|
||
## 快速开始
|
||
|
||
### 环境初始化
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 初始化项目（安装依赖、数据库、浏览器）
|
||
pnpm run init
|
||
```
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
# 开发模式启动服务
|
||
pnpm run dev
|
||
|
||
# 启动浏览器（生产模式，使用 pm2）
|
||
pnpm run browser
|
||
|
||
# 开发模式启动浏览器
|
||
pnpm run dev:browser
|
||
|
||
# 启动 Drizzle Studio（数据库可视化工具）
|
||
pnpm run studio
|
||
```
|
||
|
||
## API 接口文档
|
||
|
||
### 认证
|
||
|
||
所有接口都需要通过 `auth` 中间件认证（当前为临时 Token 验证）。
|
||
|
||
### 小红书笔记接口
|
||
|
||
#### 搜索笔记
|
||
|
||
```
|
||
POST /xhs/search-notes
|
||
```
|
||
|
||
**参数**:
|
||
- `keyword`: 搜索关键词（必填）
|
||
- `pushTime`: 发布时间筛选（一天内/一周内/半年内），默认一天内
|
||
- `sort`: 排序方式（综合/最新/最多点赞/最多评论），默认最新
|
||
- `distance`: 距离筛选（不限/同城/附近），默认不限
|
||
- `searchRange`: 搜索范围（不限/已看过/未看过/已关注），默认不限
|
||
- `scrollTimes`: 滚动次数，默认5次
|
||
|
||
#### 获取笔记列表
|
||
|
||
```
|
||
GET /xhs/list
|
||
```
|
||
|
||
**参数**:
|
||
- `page`: 页码，默认1
|
||
- `pageSize`: 每页数量，默认20
|
||
- `search`: 搜索关键词
|
||
- `sort`: 排序方式（ASC/DESC），默认DESC
|
||
|
||
#### 获取单条笔记
|
||
|
||
```
|
||
GET /xhs/get
|
||
```
|
||
|
||
**参数**:
|
||
- `data.id`: 笔记ID
|
||
|
||
#### 创建/更新笔记
|
||
|
||
```
|
||
POST /xhs/update
|
||
```
|
||
|
||
**参数**:
|
||
- `data.id`: 笔记ID（更新时必填）
|
||
- `data.title`: 笔记标题
|
||
- `data.summary`: 笔记摘要
|
||
- `data.description`: 笔记描述
|
||
- `data.tags`: 标签数组
|
||
- `data.data`: 笔记完整数据
|
||
|
||
#### 删除笔记
|
||
|
||
```
|
||
POST /xhs/delete
|
||
```
|
||
|
||
**参数**:
|
||
- `data.id`: 笔记ID
|
||
|
||
### 小红书用户接口
|
||
|
||
#### 获取用户列表
|
||
|
||
```
|
||
GET /xhs-users/list
|
||
```
|
||
|
||
**参数**:
|
||
- `page`: 页码，默认1
|
||
- `pageSize`: 每页数量，默认20
|
||
- `search`: 搜索关键词（模糊匹配昵称、用户名、描述）
|
||
- `sort`: 排序方式（ASC/DESC），默认DESC
|
||
|
||
#### 获取单个用户
|
||
|
||
```
|
||
GET /xhs-users/get
|
||
```
|
||
|
||
**参数**:
|
||
- `data.id`: 用户ID
|
||
|
||
#### 创建/更新用户
|
||
|
||
```
|
||
POST /xhs-users/update
|
||
```
|
||
|
||
**参数**:
|
||
- `data.id`: 用户ID（更新时必填）
|
||
- `data.nickname`: 用户昵称
|
||
- `data.username`: 用户名
|
||
- `data.avatar`: 用户头像
|
||
- `data.description`: 用户描述
|
||
- `data.tags`: 标签数组
|
||
|
||
#### 删除用户
|
||
|
||
```
|
||
POST /xhs-users/delete
|
||
```
|
||
|
||
**参数**:
|
||
- `data.id`: 用户ID
|
||
|
||
### 小红书标签接口
|
||
|
||
#### 获取标签列表
|
||
|
||
```
|
||
GET /xhs-tags/list
|
||
```
|
||
|
||
**参数**:
|
||
- `page`: 页码，默认1
|
||
- `pageSize`: 每页数量，默认20
|
||
- `search`: 搜索关键词
|
||
- `sort`: 排序方式（ASC/DESC），默认DESC
|
||
|
||
#### 创建/更新标签
|
||
|
||
```
|
||
POST /xhs-tags/update
|
||
```
|
||
|
||
**参数**:
|
||
- `data.id`: 标签ID（更新时必填）
|
||
- `data.title`: 标签标题
|
||
- `data.description`: 标签描述
|
||
|
||
#### 删除标签
|
||
|
||
```
|
||
POST /xhs-tags/delete
|
||
```
|
||
|
||
**参数**:
|
||
- `data.id`: 标签ID
|
||
|
||
### 预设搜索场景
|
||
|
||
#### 信息差搜索
|
||
|
||
```
|
||
POST /good/searchInfo
|
||
```
|
||
|
||
**参数**:
|
||
- `keyword`: 搜索关键词，默认"信息差"
|
||
|
||
#### 工作招聘搜索
|
||
|
||
```
|
||
POST /good/searchWork
|
||
```
|
||
|
||
**参数**:
|
||
- `keyword`: 搜索关键词，默认"工作 杭州"
|
||
|
||
#### 交友相亲搜索
|
||
|
||
```
|
||
POST /good/searchDate
|
||
```
|
||
|
||
**参数**:
|
||
- `keyword`: 搜索关键词，默认"相亲 杭州"
|
||
|
||
#### 拼豆搜索
|
||
|
||
```
|
||
POST /good/searchBean
|
||
```
|
||
|
||
**参数**:
|
||
- `keyword`: 搜索关键词，默认"拼豆"
|
||
|
||
#### 网站模板搜索
|
||
|
||
```
|
||
POST /good/searchTemplate
|
||
```
|
||
|
||
**参数**:
|
||
- `keyword`: 搜索关键词，默认"网站模板"
|
||
|
||
## 数据库结构
|
||
|
||
### xhs_note（小红书笔记表）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | text | 笔记ID（主键） |
|
||
| title | text | 笔记标题 |
|
||
| summary | text | 笔记摘要 |
|
||
| description | text | 笔记描述/搜索关键词 |
|
||
| link | text | 笔记链接 |
|
||
| data | text | 完整数据（JSON） |
|
||
| tags | text | 标签 |
|
||
| status | text | 状态（正常笔记/归档/禁止用户/删除/不相关） |
|
||
| authorUrl | text | 作者主页链接 |
|
||
| cover | text | 封面图 |
|
||
| syncStatus | integer | 同步状态 |
|
||
| syncAt | integer | 同步时间 |
|
||
| star | integer | 标记 |
|
||
| userId | text | 用户ID |
|
||
| createdAt | integer | 创建时间 |
|
||
| updatedAt | integer | 更新时间 |
|
||
|
||
### xhs_user（小红书用户表）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | text | 用户ID（主键） |
|
||
| xsec_token | text | XSEC Token |
|
||
| username | text | 用户名 |
|
||
| nickname | text | 昵称 |
|
||
| avatar | text | 头像 |
|
||
| title | text | 标题 |
|
||
| summary | text | 摘要 |
|
||
| description | text | 描述 |
|
||
| link | text | 主页链接 |
|
||
| data | text | 完整数据（JSON） |
|
||
| tags | text | 标签 |
|
||
| bunTags | text | 屏蔽标签 |
|
||
| followersCount | integer | 粉丝数 |
|
||
| followingCount | integer | 关注数 |
|
||
| status | text | 状态 |
|
||
| syncStatus | integer | 同步状态 |
|
||
| syncAt | integer | 同步时间 |
|
||
| star | integer | 标记 |
|
||
|
||
### xhs_tags（小红书标签表）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | text | 标签ID（主键） |
|
||
| title | text | 标签标题 |
|
||
| description | text | 标签描述 |
|
||
| createdAt | integer | 创建时间 |
|
||
| updatedAt | integer | 更新时间 |
|
||
|
||
### cache（缓存表）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| key | text | 缓存键（主键） |
|
||
| value | text | 缓存值 |
|
||
| expireAt | integer | 过期时间 |
|
||
| createdAt | integer | 创建时间 |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
browser-helper/
|
||
├── src/
|
||
│ ├── app.ts # 应用入口和核心配置
|
||
│ ├── index.ts # 主入口，导出 API 插件
|
||
│ ├── db/
|
||
│ │ ├── schema.ts # 数据库表结构定义
|
||
│ │ └── cache.ts # 数据库缓存模块
|
||
│ ├── modules/
|
||
│ │ └── cache.ts # 会话缓存（LRU Cache）
|
||
│ ├── playwright/
|
||
│ │ ├── core.ts # 浏览器核心控制类
|
||
│ │ ├── browser.ts # 浏览器启动逻辑
|
||
│ │ ├── actions.ts # 浏览器操作封装
|
||
│ │ └── index.ts # 导出
|
||
│ └── routes/
|
||
│ ├── index.ts # 路由入口
|
||
│ ├── xhs/ # 小红书相关路由
|
||
│ │ ├── index.ts
|
||
│ │ ├── search-notes.ts # 笔记搜索
|
||
│ │ ├── xhs-list.ts # 笔记 CRUD
|
||
│ │ ├── xhs-user-list.ts # 用户 CRUD
|
||
│ │ └── xhs-tags-list.ts # 标签 CRUD
|
||
│ └── good/ # 预设搜索场景
|
||
│ └── index.ts
|
||
├── storage/
|
||
│ └── browser-helper/
|
||
│ └── data.sqlite3 # SQLite 数据库文件
|
||
├── browser-context/ # 浏览器上下文数据
|
||
├── dist/ # 构建输出目录
|
||
├── typings/ # TypeScript 类型定义
|
||
├── drizzle.config.ts # Drizzle 配置
|
||
├── bun.config.ts # Bun 构建配置
|
||
├── package.json # 项目配置
|
||
└── pnpm-lock.yaml # 依赖锁定
|
||
```
|
||
|
||
## 浏览器控制
|
||
|
||
### Core 类
|
||
|
||
`Core` 类是浏览器自动化的核心组件，提供以下功能：
|
||
|
||
```typescript
|
||
// 连接浏览器
|
||
await core.connect();
|
||
|
||
// 获取页面实例
|
||
const page = await core.getPage();
|
||
|
||
// 设置记录就绪状态
|
||
await core.setReady(true);
|
||
|
||
// 监听响应
|
||
core.on('search/notes', (data) => {
|
||
console.log('捕获响应:', data);
|
||
});
|
||
```
|
||
|
||
### 启动流程
|
||
|
||
1. 启动浏览器进程（通过 `start-browser.js`）
|
||
2. Playwright 通过 CDP 协议连接到浏览器
|
||
3. 加载浏览器上下文和页面
|
||
4. 注册请求/响应监听器
|
||
5. 开始执行自动化任务
|
||
|
||
## 常见问题
|
||
|
||
### 1. 浏览器无法连接
|
||
|
||
确保浏览器进程已启动：
|
||
```bash
|
||
pnpm run browser # 生产模式
|
||
# 或
|
||
pnpm run dev:browser # 开发模式
|
||
```
|
||
|
||
### 2. 数据库初始化失败
|
||
|
||
运行数据库迁移：
|
||
```bash
|
||
pnpm run push
|
||
```
|
||
|
||
### 3. 搜索无结果
|
||
|
||
检查搜索关键词是否正确，确保小红书搜索页面能正常访问。
|
||
|
||
## License
|
||
|
||
MIT
|