# 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) 了解最新更新。