feat: 删除不再使用的浏览器代理插件导出；添加使用指南文档
This commit is contained in:
@@ -1,3 +0,0 @@
|
||||
import { browserAgentPlugin } from './../../src/index.ts';
|
||||
|
||||
export { browserAgentPlugin }
|
||||
401
AGENTS.md
Normal file
401
AGENTS.md
Normal file
@@ -0,0 +1,401 @@
|
||||
# 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
|
||||
@@ -3,6 +3,8 @@ export { app, db } from './app.ts';
|
||||
export { Core } from './playwright/core.ts';
|
||||
import './routes/index.ts';
|
||||
// 如果是直接运行，则启动应用
|
||||
// better-sqlite3 不支持 bun
|
||||
// playwright 也不支持 bun
|
||||
import { createRouterAgentPluginFn } from '@kevisual/router/src/opencode.ts'
|
||||
app.route({
|
||||
id: 'auth',
|
||||
|
||||
Reference in New Issue
Block a user