docs: 项目架构设计文档（中文）及使用指南

- architecture.md: 完整架构设计（技术栈、API、CLI、生命周期、测试策略） - api.md: REST + WebSocket 接口文档 - cli.md: CLI 命令参考 - contributing.md: 开发规范与 JSON 转义要求 - quickstart.md: 快速开始指南 - llm-integration.md: 智能体集成指南 - examples.md: 8 个典型使用场景
2026-08-12 20:14:54 +08:00
parent 4f7854ab6e
commit 0c437a96f1
9 changed files with 1548 additions and 0 deletions
@@ -0,0 +1,345 @@
+# 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 → 客户端 | 页面控制台输出（调试） |