AskaEth
985860b2a2
- architecture.md: 新增反检测为核心第一性原理，新增 §3 反检测设计（13 个指纹维度全覆盖） - anti-detection.md: 新增反检测专项文档（14 节，详尽列举检测方式和应对策略） - api.md: POST /pages 新增 profile 参数，新增 GET /profiles 端点 - cli.md: 新增 --profile 全局选项，新增 visionl profiles 命令 - contributing.md: 新增反检测开发规范、检测站点验证要求 - README.md: 更新项目定位和特性描述
4.6 KiB
4.6 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", // 可选
"profile": "desktop-chrome" // 可选，指纹配置模版 ID，默认 "desktop-chrome"
}
响应：
{
"ok": true,
"data": {
"id": "p_a1b2c3d4",
"url": "https://example.com",
"alias": "demo",
"title": "Example Domain",
"status": "active",
"profile": "desktop-chrome"
}
}
列出所有页面
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 /profiles
响应：
{
"ok": true,
"data": [
{ "id": "desktop-chrome", "name": "桌面 Chrome (通用)", "platform": "Linux x86_64" },
{ "id": "desktop-windows", "name": "Windows 10 Chrome", "platform": "Windows NT 10.0" },
{ "id": "desktop-mac", "name": "macOS Chrome", "platform": "Macintosh" }
]
}
健康检查
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 → 客户端 | 页面控制台输出（调试） |
page:detection:warning |
daemon → 客户端 | 页面可能检测到自动化特征 |