mirror of
https://github.com/violettoolssite/CFspider.git
synced 2026-04-04 18:59:02 +08:00
docs: add API documentation in Markdown format
This commit is contained in:
陈海富
357
api-docs/README.md
Normal file
357
api-docs/README.md
Normal file
@@ -0,0 +1,357 @@
|
||||
# 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) 了解最新更新。
|
||||
Reference in New Issue
Block a user