good/browser-helper

Fork 0

Files

xiongxiao d95452b807 feat: 删除不再使用的浏览器代理插件导出；添加使用指南文档

2026-01-22 12:49:00 +08:00

8.7 KiB

Raw Permalink Blame History

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

快速开始

环境初始化

# 安装依赖
pnpm install

# 初始化项目（安装依赖、数据库、浏览器）
pnpm run init

启动服务

# 开发模式启动服务
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 类是浏览器自动化的核心组件，提供以下功能：

// 连接浏览器
await core.connect();

// 获取页面实例
const page = await core.getPage();

// 设置记录就绪状态
await core.setReady(true);

// 监听响应
core.on('search/notes', (data) => {
  console.log('捕获响应:', data);
});

启动流程

启动浏览器进程（通过 start-browser.js）
Playwright 通过 CDP 协议连接到浏览器
加载浏览器上下文和页面
注册请求/响应监听器
开始执行自动化任务

常见问题

1. 浏览器无法连接

确保浏览器进程已启动：

pnpm run browser  # 生产模式
# 或
pnpm run dev:browser  # 开发模式

2. 数据库初始化失败

运行数据库迁移：

pnpm run push

3. 搜索无结果

检查搜索关键词是否正确，确保小红书搜索页面能正常访问。

License

MIT

8.7 KiB Raw Permalink Blame History Unescape Escape