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';
|
export { Core } from './playwright/core.ts';
|
||||||
import './routes/index.ts';
|
import './routes/index.ts';
|
||||||
// 如果是直接运行，则启动应用
|
// 如果是直接运行，则启动应用
|
||||||
|
// better-sqlite3 不支持 bun
|
||||||
|
// playwright 也不支持 bun
|
||||||
import { createRouterAgentPluginFn } from '@kevisual/router/src/opencode.ts'
|
import { createRouterAgentPluginFn } from '@kevisual/router/src/opencode.ts'
|
||||||
app.route({
|
app.route({
|
||||||
id: 'auth',
|
id: 'auth',
|
||||||
|
|||||||
Reference in New Issue
Block a user