# AI灵驹浏览器插件 API 文档

## 基础信息

- **插件名称**: AI灵驹浏览器插件
- **版本**: 1.0.0
- **服务协议**: WebSocket隧道 + HTTP代理
- **默认服务器**: `wss://res.dtns.top`
- **访问域名格式**: `http://browser.{clientId}.html.dtns.top`

---

## 一、系统接口

### 1.1 健康检查

检查服务是否正常运行。

**端点**: `GET /health`

**响应示例**:
```json
{
  "status": "ok",
  "clientId": "abc123def456...",
  "registeredDomains": ["browser.abc123...html.dtns.top"],
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

### 1.2 获取插件信息

获取插件版本和能力信息。

**端点**: `GET /api/info`

**响应示例**:
```json
{
  "name": "AI灵驹浏览器插件",
  "version": "1.0.0",
  "clientId": "abc123def456...",
  "registeredDomains": ["browser.abc123...html.dtns.top"],
  "capabilities": ["smart_reply", "dom_query", "click", "type", "navigate", "clipboard", "evaluate"]
}
```

### 1.3 获取已注册域名

**端点**: `GET /api/domains`

**响应示例**:
```json
{
  "success": true,
  "clientId": "abc123...",
  "registeredDomains": ["browser.abc123...html.dtns.top"]
}
```

---

## 二、页面信息接口

### 2.1 获取页面信息

获取当前活动标签页的基本信息。

**端点**: `GET /api/page/info`

**响应示例**:
```json
{
  "success": true,
  "url": "https://example.com",
  "title": "Example Domain",
  "readyState": "complete"
}
```

### 2.2 获取页面可见文本

获取页面中所有可见文本内容。

**端点**: `GET /api/page/visible-text`

**参数**:
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| includePosition | boolean | true | 是否包含位置信息 |
| mergeText | boolean | true | 是否合并文本 |

**响应示例**:
```json
{
  "success": true,
  "text": "合并的文本内容...",
  "blocks": [
    {
      "text": "文本块",
      "x": 100,
      "y": 200,
      "width": 300,
      "height": 20
    }
  ]
}
```

### 2.3 获取可见文本块（仅带位置）

**端点**: `GET /api/page/visible-text/blocks`

**响应示例**:
```json
{
  "success": true,
  "blocks": [...],
  "total": 42
}
```

### 2.4 获取合并的纯文本

**端点**: `GET /api/page/visible-text/merged`

**参数**:
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| separator | string | `\n` | 文本块分隔符 |

**响应示例**:
```json
{
  "success": true,
  "text": "纯文本内容...",
  "length": 1234
}
```

---

## 三、DOM操作接口

### 3.1 执行JavaScript脚本

在当前页面执行任意JavaScript代码。

**端点**: `GET /api/script/evaluate`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| script | string | ✅ | 要执行的JavaScript代码 |

**响应示例**:
```json
{
  "success": true,
  "result": "执行结果",
  "type": "string"
}
```

### 3.2 查询DOM元素

**端点**: `GET /api/query`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| selector | string | ✅ | CSS选择器 |
| all | boolean | ❌ | 是否返回所有匹配元素 |

**响应示例**:
```json
{
  "success": true,
  "result": {
    "text": "元素文本",
    "html": "<div>...</div>",
    "attributes": {...}
  }
}
```

### 3.3 获取元素信息

**端点**: `GET /api/element/info`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| selector | string | ✅ | CSS选择器 |

### 3.4 获取页面元素结构

**端点**: `GET /api/page/elements`

获取完整的DOM元素信息。

**端点**: `GET /api/page/elements/simple` (精简版)

### 3.5 获取页面链接

**端点**: `GET /api/page/links`

**响应示例**:
```json
{
  "success": true,
  "links": [
    {
      "href": "https://...",
      "text": "链接文本",
      "title": "标题"
    }
  ]
}
```

### 3.6 获取页面图片

**端点**: `GET /api/page/images`

### 3.7 获取页面表单

**端点**: `GET /api/page/forms`

### 3.8 获取页面输入框

**端点**: `GET /api/page/inputs`

### 3.9 获取页面按钮

**端点**: `GET /api/page/buttons`

---

## 四、交互操作接口

### 4.1 点击元素

**端点**: `GET /api/click`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| selector | string | ✅ | CSS选择器 |

### 4.2 点击坐标位置

**端点**: `GET /api/click/at`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| x | number | ✅ | X坐标 |
| y | number | ✅ | Y坐标 |
| double | boolean | ❌ | 是否双击 |
| button | string | ❌ | 鼠标按键: left/right/middle |

### 4.3 右键点击

**端点**: `GET /api/click/right`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| x | number | ✅ | X坐标 |
| y | number | ✅ | Y坐标 |

### 4.4 双击

**端点**: `GET /api/click/double`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| x | number | ✅ | X坐标 |
| y | number | ✅ | Y坐标 |

### 4.5 鼠标移动

**端点**: `GET /api/mouse/move`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| x | number | ✅ | X坐标 |
| y | number | ✅ | Y坐标 |

### 4.6 输入文本

**端点**: `GET /api/type`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| selector | string | ✅ | CSS选择器 |
| text | string | ✅ | 要输入的文本 |

### 4.7 智能回复

**端点**: `GET /api/smart_reply`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| text | string | ✅ | 回复文本 |
| context | string | ❌ | 上下文信息 |

---

## 五、页面导航接口

### 5.1 导航到URL

**端点**: `GET /api/navigate`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| url | string | ✅ | 目标URL |

### 5.2 刷新页面

**端点**: `GET /api/refresh`

### 5.3 滚动页面

**端点**: `GET /api/scroll`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| x | number | 水平滚动量 |
| y | number | 垂直滚动量 |

---

## 六、剪贴板接口

### 6.1 复制到剪贴板

**端点**: `GET /api/clipboard/copy`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| text | string | ✅* | 纯文本内容 |
| html | string | ✅* | HTML内容（*二选一） |

### 6.2 读取剪贴板

**端点**: `GET /api/clipboard/read`

**响应示例**:
```json
{
  "success": true,
  "text": "剪贴板文本",
  "html": "<b>HTML内容</b>",
  "length": 100
}
```

### 6.3 追加到剪贴板

**端点**: `GET /api/clipboard/append`

**参数**:
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| text | string | ✅ | 要追加的文本 |
| separator | string | `\n` | 分隔符 |

### 6.4 清空剪贴板

**端点**: `GET /api/clipboard/clear`

---

## 七、可点击元素接口

### 7.1 获取所有可点击元素

**端点**: `GET /api/page/clickable-elements`

**参数**:
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| includePosition | boolean | true | 是否包含位置信息 |
| includeSelector | boolean | true | 是否包含选择器 |

**响应示例**:
```json
{
  "success": true,
  "total": 50,
  "elements": [...],
  "summary": {
    "buttons": 10,
    "links": 30,
    "interactive": 10
  }
}
```

### 7.2 按类型分组的可点击元素

**端点**: `GET /api/page/clickable-elements/grouped`

### 7.3 获取可点击元素选择器列表

**端点**: `GET /api/page/clickable-elements/selectors`

---

## 八、网络监控接口

### 8.1 开始监控

**端点**: `GET /api/network/start`

**参数**:
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| duration | number | 30000 | 监控时长(ms)，0表示持续监控 |

**响应示例**:
```json
{
  "success": true,
  "message": "Network monitoring started for 30000ms",
  "tabId": 123,
  "url": "https://example.com"
}
```

### 8.2 停止监控

**端点**: `GET /api/network/stop`

**响应示例**:
```json
{
  "success": true,
  "summary": {
    "total": 42,
    "byMethod": {"GET": 30, "POST": 12},
    "byStatus": {"200s": 38, "400s": 4},
    "errors": 4,
    "avgDuration": 150
  },
  "requests": [...],
  "totalCount": 42,
  "duration": 30000
}
```

### 8.3 获取监控状态

**端点**: `GET /api/network/status`

### 8.4 获取请求列表

**端点**: `GET /api/network/requests`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| limit | number | 返回数量限制，默认100 |
| method | string | 按方法过滤(GET/POST等) |
| urlPattern | string | URL正则匹配 |

### 8.5 获取请求详情

**端点**: `GET /api/network/request/detail`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| requestId | string | ✅ | 请求ID |

### 8.6 清除网络记录

**端点**: `GET /api/network/clear`

---

## 九、截图接口

### 9.1 截取当前页面

**端点**: `GET /api/screenshot`

**响应示例**:
```json
{
  "success": true,
  "imageData": "data:image/png;base64,..."
}
```

---

## 十、选中文本接口

### 10.1 获取选中的文本

**端点**: `GET /api/selected/text`

**响应示例**:
```json
{
  "success": true,
  "text": "用户选中的文本"
}
```

---

## 十一、标签页管理接口

### 11.1 获取所有标签页

**端点**: `GET /api/tabs/list`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| active | boolean | 仅活动标签页 |
| currentWindow | boolean | 仅当前窗口 |

### 11.2 获取当前标签页

**端点**: `GET /api/tabs/current`

### 11.3 切换标签页

**端点**: `GET /api/tabs/switch`

**参数**（四选一）:
| 参数 | 类型 | 说明 |
|------|------|------|
| tabId | number | 标签页ID |
| index | number | 标签页索引 |
| url | string | URL匹配 |
| title | string | 标题匹配 |
| focusWindow | boolean | 是否聚焦窗口 |

### 11.4 打开新标签页

**端点**: `GET /api/tabs/open`

**参数**:
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| url | string | ✅ | 要打开的URL |
| active | boolean | true | 是否激活新标签页 |
| position | string/number | 'end' | 位置: start/end/索引 |
| windowId | number | - | 指定窗口ID |

### 11.5 批量打开标签页

**端点**: `GET /api/tabs/open/batch`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| urls | array/string | URL列表(支持JSON数组或逗号分隔) |
| active | string | 激活哪个: first/last/索引 |
| position | string | start/end/索引 |
| windowId | number | 窗口ID |

### 11.6 打开或切换标签页

**端点**: `GET /api/tabs/openOrSwitch`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| url | string | ✅ 目标URL |
| active | boolean | 是否激活 |

### 11.7 后台打开标签页

**端点**: `GET /api/tabs/open/background`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| url | string | ✅ 目标URL |

### 11.8 关闭标签页

**端点**: `GET /api/tabs/close`

**参数**（多选一）:
| 参数 | 类型 | 说明 |
|------|------|------|
| tabId | number | 单个标签页ID |
| tabIds | array/string | 多个标签页ID |
| url | string | 按URL匹配关闭 |
| title | string | 按标题匹配关闭 |
| current | boolean | 关闭当前标签页 |

---

## 十二、窗口管理接口

### 12.1 打开新窗口

**端点**: `GET /api/windows/open`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| urls | array/string | 要在新窗口打开的URL列表 |
| active | boolean | 是否聚焦新窗口 |
| width | number | 窗口宽度 |
| height | number | 窗口高度 |
| left | number | X位置 |
| top | number | Y位置 |
| type | string | 窗口类型: normal/popup/panel |

---

## 十三、控制台日志接口

### 13.1 获取控制台日志

**端点**: `GET /api/console/logs`

**参数**:
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| limit | number | 100 | 返回数量 |
| level | string | - | 过滤级别: log/error/warn/info/debug |
| clear | boolean | false | 获取后是否清除 |

### 13.2 开始收集日志

**端点**: `GET /api/console/start`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| duration | number | 收集时长(ms)，0表示持续 |

### 13.3 停止收集日志

**端点**: `GET /api/console/stop`

### 13.4 清除控制台日志

**端点**: `GET /api/console/clear`

### 13.5 执行控制台命令

**端点**: `GET /api/console/exec`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | string | ✅ | 要执行的JavaScript代码 |

**响应示例**:
```json
{
  "success": true,
  "result": "执行返回值",
  "consoleOutput": [
    {"level": "log", "message": "输出内容", "timestamp": 123456789}
  ],
  "error": null
}
```

---

## 十四、配置管理接口

### 14.1 获取配置

**端点**: `GET /api/config`

**响应示例**:
```json
{
  "success": true,
  "config": {
    "clientId": "abc123...",
    "wsServerUrl": "wss://res.dtns.top",
    "autoReconnect": true
  },
  "status": {
    "connected": true,
    "browserDomain": "http://browser.abc123...html.dtns.top",
    "registered": true
  }
}
```

### 14.2 设置客户端ID

**端点**: `GET /api/config/clientId`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| clientId | string | ✅ | 新的客户端ID(20位) |

### 14.3 生成新的客户端ID

**端点**: `GET /api/config/clientId/generate`

### 14.4 设置服务器地址

**端点**: `GET /api/config/server`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| url | string | ✅ | WebSocket服务器地址(ws://或wss://) |

### 14.5 重置配置

**端点**: `GET /api/config/reset`

### 14.6 强制重连

**端点**: `GET /api/config/reconnect`

---

## 通用响应格式

### 成功响应
```json
{
  "success": true,
  ...具体数据
}
```

### 错误响应
```json
{
  "success": false,
  "error": "错误描述信息"
}
```

---

## 注意事项

1. **CORS支持**: 所有接口均支持跨域请求，已配置CORS头
2. **参数传递**: 使用GET请求，参数通过URL查询字符串传递
3. **特殊页面限制**: 无法访问`chrome://`、`edge://`等浏览器内部页面
4. **调试器权限**: 网络监控和控制台功能需要调试器权限
5. **域名格式**: 访问插件的域名格式为 `http://browser.{clientId}.html.dtns.top`
6. **连接状态**: 需要WebSocket保持连接才能使用API