# 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": "..." } } ``` --- ## 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 → 客户端 | 页面控制台输出（调试） |