AskaEth
0c437a96f1
- architecture.md: 完整架构设计（技术栈、API、CLI、生命周期、测试策略） - api.md: REST + WebSocket 接口文档 - cli.md: CLI 命令参考 - contributing.md: 开发规范与 JSON 转义要求 - quickstart.md: 快速开始指南 - llm-integration.md: 智能体集成指南 - examples.md: 8 个典型使用场景
4.1 KiB
4.1 KiB
VisionL REST API 接口文档
适用版本：v1
通用约定
Base URL
http://127.0.0.1:9527
端口可通过启动参数 --port 修改。
响应格式
所有响应统一为 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
请求体：
{
"url": "https://example.com",
"alias": "demo" // 可选
}
响应：
{
"ok": true,
"data": {
"id": "p_a1b2c3d4",
"url": "https://example.com",
"alias": "demo",
"title": "Example Domain",
"status": "active"
}
}
列出所有页面
GET /pages
响应：
{
"ok": true,
"data": [
{
"id": "p_a1b2c3d4",
"url": "https://example.com",
"alias": "demo",
"title": "Example Domain",
"status": "active"
}
]
}
页面详情
GET /pages/:id
响应： 同上 data 中的单个对象。
杀死页面
DELETE /pages/:id
响应：
{ "ok": true, "data": null }
页面操作
跳转
POST /pages/:id/navigate
请求体：
{ "url": "https://new-url.com" }
响应：
{
"ok": true,
"data": {
"url": "https://new-url.com",
"title": "New Page"
}
}
点击元素
POST /pages/:id/click
请求体：
{ "selector": "#login-button" }
响应：
{ "ok": true, "data": { "success": true } }
输入文本
POST /pages/:id/type
请求体：
{
"selector": "#username",
"text": "hello world"
}
响应： 同 click。
滚动
POST /pages/:id/scroll
请求体（至少提供一个）：
{
"deltaY": 500,
"toBottom": true
}
响应： 同 click。
执行 JavaScript
POST /pages/:id/eval
请求体：
{
"code": "document.title"
}
响应：
{
"ok": true,
"data": {
"result": "Example Domain"
}
}
注意：
result类型取决于 JS 代码返回值，可以是 string、number、boolean、object 或 null。
等待条件
POST /pages/:id/wait
请求体（至少提供一个）：
{
"selector": ".loaded",
"ms": 2000
}
响应： 同 click。
内容获取
截图
GET /pages/:id/screenshot
响应：
{
"ok": true,
"data": {
"base64": "iVBORw0KGgoAAAANS...",
"mime": "image/png"
}
}
纯文本
GET /pages/:id/text
响应：
{
"ok": true,
"data": {
"text": "页面正文内容..."
}
}
HTML
GET /pages/:id/html
响应：
{
"ok": true,
"data": {
"html": "<!DOCTYPE html>..."
}
}
Daemon 管理
健康检查
GET /health
响应：
{ "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 → 客户端 | 页面控制台输出（调试） |