AskaEth
0c437a96f1
- architecture.md: 完整架构设计（技术栈、API、CLI、生命周期、测试策略） - api.md: REST + WebSocket 接口文档 - cli.md: CLI 命令参考 - contributing.md: 开发规范与 JSON 转义要求 - quickstart.md: 快速开始指南 - llm-integration.md: 智能体集成指南 - examples.md: 8 个典型使用场景
346 lines
4.1 KiB
Markdown
346 lines
4.1 KiB
Markdown
# VisionL REST API 接口文档
|
||
|
||
> 适用版本：v1
|
||
|
||
## 通用约定
|
||
|
||
### Base URL
|
||
|
||
```
|
||
http://127.0.0.1:9527
|
||
```
|
||
|
||
端口可通过启动参数 `--port` 修改。
|
||
|
||
### 响应格式
|
||
|
||
所有响应统一为 JSON：
|
||
|
||
```json
|
||
// 成功
|
||
{
|
||
"ok": true,
|
||
"data": { ... }
|
||
}
|
||
|
||
// 失败
|
||
{
|
||
"ok": false,
|
||
"error": {
|
||
"code": "PAGE_NOT_FOUND",
|
||
"message": "页面 p_xyz 不存在"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误码
|
||
|
||
| 错误码 | HTTP 状态码 | 说明 |
|
||
|--------|-----------|------|
|
||
| `PAGE_NOT_FOUND` | 404 | 指定页面不存在 |
|
||
| `DAEMON_UNREACHABLE` | 502 | daemon 不可达（CLI 端产生） |
|
||
| `INVALID_URL` | 400 | URL 格式不合法 |
|
||
| `ALIAS_EXISTS` | 409 | 别名已被使用 |
|
||
| `TIMEOUT` | 408 | 操作超时 |
|
||
| `INTERNAL` | 500 | 内部错误 |
|
||
|
||
### JSON 转义
|
||
|
||
所有响应通过 `JSON.stringify` 序列化。页面内容（如 `text`、`html` 字段）中的
|
||
引号、反斜杠、控制字符均被正确转义，外层 JSON 始终合法。
|
||
|
||
---
|
||
|
||
## 页面管理
|
||
|
||
### 打开页面
|
||
|
||
```
|
||
POST /pages
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"url": "https://example.com",
|
||
"alias": "demo" // 可选
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"id": "p_a1b2c3d4",
|
||
"url": "https://example.com",
|
||
"alias": "demo",
|
||
"title": "Example Domain",
|
||
"status": "active"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 列出所有页面
|
||
|
||
```
|
||
GET /pages
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": [
|
||
{
|
||
"id": "p_a1b2c3d4",
|
||
"url": "https://example.com",
|
||
"alias": "demo",
|
||
"title": "Example Domain",
|
||
"status": "active"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 页面详情
|
||
|
||
```
|
||
GET /pages/:id
|
||
```
|
||
|
||
**响应：** 同上 `data` 中的单个对象。
|
||
|
||
### 杀死页面
|
||
|
||
```
|
||
DELETE /pages/:id
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{ "ok": true, "data": null }
|
||
```
|
||
|
||
---
|
||
|
||
## 页面操作
|
||
|
||
### 跳转
|
||
|
||
```
|
||
POST /pages/:id/navigate
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{ "url": "https://new-url.com" }
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"url": "https://new-url.com",
|
||
"title": "New Page"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 点击元素
|
||
|
||
```
|
||
POST /pages/:id/click
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{ "selector": "#login-button" }
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{ "ok": true, "data": { "success": true } }
|
||
```
|
||
|
||
### 输入文本
|
||
|
||
```
|
||
POST /pages/:id/type
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"selector": "#username",
|
||
"text": "hello world"
|
||
}
|
||
```
|
||
|
||
**响应：** 同 click。
|
||
|
||
### 滚动
|
||
|
||
```
|
||
POST /pages/:id/scroll
|
||
```
|
||
|
||
**请求体（至少提供一个）：**
|
||
|
||
```json
|
||
{
|
||
"deltaY": 500,
|
||
"toBottom": true
|
||
}
|
||
```
|
||
|
||
**响应：** 同 click。
|
||
|
||
### 执行 JavaScript
|
||
|
||
```
|
||
POST /pages/:id/eval
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"code": "document.title"
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"result": "Example Domain"
|
||
}
|
||
}
|
||
```
|
||
|
||
> 注意：`result` 类型取决于 JS 代码返回值，可以是 string、number、boolean、object 或 null。
|
||
|
||
### 等待条件
|
||
|
||
```
|
||
POST /pages/:id/wait
|
||
```
|
||
|
||
**请求体（至少提供一个）：**
|
||
|
||
```json
|
||
{
|
||
"selector": ".loaded",
|
||
"ms": 2000
|
||
}
|
||
```
|
||
|
||
**响应：** 同 click。
|
||
|
||
---
|
||
|
||
## 内容获取
|
||
|
||
### 截图
|
||
|
||
```
|
||
GET /pages/:id/screenshot
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"base64": "iVBORw0KGgoAAAANS...",
|
||
"mime": "image/png"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 纯文本
|
||
|
||
```
|
||
GET /pages/:id/text
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"text": "页面正文内容..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### HTML
|
||
|
||
```
|
||
GET /pages/:id/html
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"html": "<!DOCTYPE html>..."
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Daemon 管理
|
||
|
||
### 健康检查
|
||
|
||
```
|
||
GET /health
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{ "status": "ok" }
|
||
```
|
||
|
||
---
|
||
|
||
## WebSocket 接口
|
||
|
||
### 连接
|
||
|
||
```
|
||
ws://127.0.0.1:9527/ws
|
||
```
|
||
|
||
### 事件类型
|
||
|
||
所有事件 JSON 格式：`{ "type": "...", "data": { ... } }`
|
||
|
||
| 事件 | 方向 | 说明 |
|
||
|------|------|------|
|
||
| `page:created` | daemon → 客户端 | 新页面打开 |
|
||
| `page:closed` | daemon → 客户端 | 页面被杀死 |
|
||
| `page:navigated` | daemon → 客户端 | 页面 URL 发生变化 |
|
||
| `page:crashed` | daemon → 客户端 | Playwright 页面崩溃 |
|
||
| `page:console` | daemon → 客户端 | 页面控制台输出（调试） |
|