mirror of
https://github.com/violettoolssite/CFspider.git
synced 2026-04-05 03:09:01 +08:00
358 lines
7.0 KiB
Markdown
358 lines
7.0 KiB
Markdown
# CFspider 智能浏览器 API 文档
|
||
|
||
CFspider 智能浏览器提供了一套完整的 AI 工具 API，用于自动化浏览器操作。
|
||
|
||
## 目录
|
||
|
||
- [页面状态工具](#页面状态工具)
|
||
- [导航工具](#导航工具)
|
||
- [点击工具](#点击工具)
|
||
- [输入工具](#输入工具)
|
||
- [页面分析工具](#页面分析工具)
|
||
- [标签页管理](#标签页管理)
|
||
- [视频分析工具](#视频分析工具)
|
||
- [技能系统](#技能系统)
|
||
|
||
---
|
||
|
||
## 页面状态工具
|
||
|
||
### get_current_page
|
||
|
||
获取当前页面的状态信息。在执行操作前调用此工具检查页面状态，避免重复操作。
|
||
|
||
**参数**: 无
|
||
|
||
**返回示例**:
|
||
```
|
||
[当前页面状态]
|
||
URL: https://www.jd.com/
|
||
标题: 京东(JD.COM)-正品低价、品质保障
|
||
域名: www.jd.com
|
||
路径: /
|
||
加载状态: 已完成
|
||
视频: 检测到视频元素
|
||
页面预览: 多快好省...
|
||
```
|
||
|
||
---
|
||
|
||
## 导航工具
|
||
|
||
### navigate_to
|
||
|
||
导航到指定 URL。会自动检测是否已在目标页面，避免重复导航。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| url | string | 是 | 目标 URL |
|
||
|
||
**示例**:
|
||
```json
|
||
{
|
||
"url": "https://cn.bing.com"
|
||
}
|
||
```
|
||
|
||
**返回**:
|
||
- 成功: `已跳转到 https://cn.bing.com`
|
||
- 已在目标页面: `[已在目标页面] 当前已经在 bing.com 了`
|
||
|
||
---
|
||
|
||
## 点击工具
|
||
|
||
### click_text
|
||
|
||
点击包含指定文本的元素。这是最常用的点击方式。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| text | string | 是 | 要点击的文本内容 |
|
||
|
||
**示例**:
|
||
```json
|
||
{
|
||
"text": "京东"
|
||
}
|
||
```
|
||
|
||
### click_element
|
||
|
||
使用 CSS 选择器点击元素。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| selector | string | 是 | CSS 选择器 |
|
||
|
||
**示例**:
|
||
```json
|
||
{
|
||
"selector": "#search-btn"
|
||
}
|
||
```
|
||
|
||
### click_by_index
|
||
|
||
通过索引点击元素。需要先调用 `scan_interactive_elements` 获取元素列表。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| category | string | 是 | 元素类别: inputs, buttons, links, selects |
|
||
| index | number | 是 | 元素索引号（从1开始） |
|
||
|
||
**示例**:
|
||
```json
|
||
{
|
||
"category": "links",
|
||
"index": 3
|
||
}
|
||
```
|
||
|
||
### visual_click
|
||
|
||
使用视觉模型精确定位并点击元素。适用于 DOM 查找失败的情况。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| target | string | 是 | 目标描述（如"红色登录按钮"） |
|
||
|
||
**示例**:
|
||
```json
|
||
{
|
||
"target": "蓝色的搜索按钮"
|
||
}
|
||
```
|
||
|
||
### click_search_button
|
||
|
||
专门用于点击搜索按钮。自动识别页面上的搜索按钮并点击。
|
||
|
||
**参数**: 无
|
||
|
||
---
|
||
|
||
## 输入工具
|
||
|
||
### input_text
|
||
|
||
在输入框中输入文本。自动查找并聚焦输入框。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| text | string | 是 | 要输入的文本 |
|
||
| selector | string | 否 | 可选的 CSS 选择器 |
|
||
|
||
**示例**:
|
||
```json
|
||
{
|
||
"text": "Python 教程"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 页面分析工具
|
||
|
||
### scan_interactive_elements
|
||
|
||
扫描并列出页面上所有可交互元素（按钮、链接、输入框等）。
|
||
|
||
**参数**: 无
|
||
|
||
**返回示例**:
|
||
```
|
||
INTERACTIVE ELEMENTS ON PAGE:
|
||
|
||
INPUTS (2):
|
||
1. [text] id=search placeholder="搜索"
|
||
2. [password] id=password
|
||
|
||
BUTTONS (3):
|
||
1. "登录" id=login-btn
|
||
2. "注册"
|
||
3. "搜索"
|
||
|
||
LINKS (10):
|
||
1. "首页"
|
||
2. "产品"
|
||
...
|
||
```
|
||
|
||
### get_page_content
|
||
|
||
获取页面的主要文本内容。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| max_length | number | 否 | 最大字符数（默认500） |
|
||
|
||
### read_full_page
|
||
|
||
使用视觉模型阅读完整页面内容。会自动滚动页面并分析每一屏。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| max_scrolls | number | 否 | 最大滚动次数（默认10） |
|
||
|
||
### find_element
|
||
|
||
根据描述查找元素。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| description | string | 是 | 元素描述（如"搜索按钮"） |
|
||
|
||
### check_element_exists
|
||
|
||
检查指定元素是否存在并可见。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| selector | string | 是 | CSS 选择器 |
|
||
|
||
---
|
||
|
||
## 标签页管理
|
||
|
||
### new_tab
|
||
|
||
新建标签页。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| url | string | 否 | 新标签页要打开的 URL |
|
||
|
||
### switch_tab
|
||
|
||
切换到指定标签页。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| index | number | 否 | 标签页索引（从0开始） |
|
||
| title | string | 否 | 标签页标题关键词 |
|
||
|
||
### close_tab
|
||
|
||
关闭标签页。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| index | number | 否 | 要关闭的标签页索引（默认当前） |
|
||
|
||
### list_tabs
|
||
|
||
列出所有打开的标签页。
|
||
|
||
**参数**: 无
|
||
|
||
---
|
||
|
||
## 视频分析工具
|
||
|
||
### summarize_video
|
||
|
||
总结页面上正在播放的视频内容。通过抽取关键帧进行视觉分析。
|
||
|
||
**参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| frame_count | number | 否 | 要分析的帧数（默认10，最多40） |
|
||
| focus | string | 否 | 分析重点（如"人物"、"教程步骤"） |
|
||
|
||
**示例**:
|
||
```json
|
||
{
|
||
"frame_count": 20,
|
||
"focus": "产品演示"
|
||
}
|
||
```
|
||
|
||
**返回示例**:
|
||
```
|
||
[视频分析] 时长: 5分30秒 | 分析帧数: 20
|
||
|
||
关键帧内容:
|
||
[0:33] 讲师介绍项目背景
|
||
[1:06] 展示代码编辑器
|
||
[1:39] 演示运行效果
|
||
...
|
||
|
||
[总结]
|
||
这是一个编程教程视频，讲师演示了如何创建一个 React 组件...
|
||
```
|
||
|
||
---
|
||
|
||
## 技能系统
|
||
|
||
### 技能匹配
|
||
|
||
系统会根据用户指令和当前域名自动匹配相关技能，提供操作建议。
|
||
|
||
### 技能学习
|
||
|
||
- **成功操作**: 40% 概率保存学习记忆
|
||
- **失败操作**: 20% 概率保存教训
|
||
- **熟练度提升**: 使用次数越多，技能熟练度越高
|
||
|
||
### 熟练度等级
|
||
|
||
| 等级 | 条件 | 说明 |
|
||
|------|------|------|
|
||
| 新手 | 使用 < 5 次 | 刚开始学习 |
|
||
| 入门 | 使用 < 20 次或成功率 < 60% | 有一些经验 |
|
||
| 熟练 | 使用 < 50 次或成功率 < 80% | 能够较好完成 |
|
||
| 精通 | 使用 < 100 次或成功率 < 90% | 很少出错 |
|
||
| 大师 | 使用 >= 100 次且成功率 >= 90% | 炉火纯青 |
|
||
|
||
### 遗忘曲线
|
||
|
||
- 超过一周不用：置信度每周下降 2%
|
||
- 超过一个月不用：置信度每月下降 5%
|
||
- 低置信度模式可能被随机"遗忘"
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
### 连接错误
|
||
|
||
当网络连接失败时，会显示重试按钮，用户可以选择重试。
|
||
|
||
### 登录选择
|
||
|
||
当检测到登录页面时，会弹出选择按钮：
|
||
- **自动登录**: AI 记住账号信息并自动登录
|
||
- **手动登录**: 用户手动登录，AI 不记住信息
|
||
|
||
---
|
||
|
||
## 数据存储
|
||
|
||
所有学习数据永久保存在用户目录：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `skills.json` | 技能学习数据 |
|
||
| `learning-memory.json` | 操作记忆 |
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
查看 [UPDATE_LOG.md](../cfspider-browser/UPDATE_LOG.md) 了解最新更新。
|