From 20fe461bcd7939bb06b65d6db9e8d5ea21bea78e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E6=B5=B7=E5=AF=8C?= Date: Fri, 30 Jan 2026 00:33:01 +0800 Subject: [PATCH] docs: add API documentation in Markdown format --- api-docs/README.md | 357 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 357 insertions(+) create mode 100644 api-docs/README.md diff --git a/api-docs/README.md b/api-docs/README.md new file mode 100644 index 0000000..2756272 --- /dev/null +++ b/api-docs/README.md @@ -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) 了解最新更新。