# 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