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,143 @@
+# VisionL 使用示例
+
+> 面向智能体和人工用户的典型场景。
+
+## 场景一：搜索引擎查询
+
+```bash
+# 1. 打开百度
+visionl page open https://www.baidu.com --alias search
+# → {"ok":true,"data":{"id":"p_1234","alias":"search",...}}
+
+# 2. 输入搜索词
+visionl type search "#kw" "VisionL 浏览器"
+
+# 3. 点击搜索
+visionl click search "#su"
+
+# 4. 等待结果加载
+visionl wait search --selector "#content_left"
+
+# 5. 获取页面文本
+visionl text search
+# → {"ok":true,"data":{"text":"搜索结果..."}}
+
+# 6. 用完关闭
+visionl page kill search
+```
+
+## 场景二：多页面信息收集
+
+```bash
+# 同时打开多个信息源
+visionl page open https://news.ycombinator.com --alias hn
+visionl page open https://www.reddit.com/r/programming --alias reddit
+visionl page open https://github.com/trending --alias gh
+
+# 分别提取内容
+visionl text hn
+visionl text reddit
+visionl text gh
+
+# 用完批量关闭
+visionl page kill-all
+```
+
+## 场景三：表单填写
+
+```bash
+# 1. 打开登录页
+visionl page open https://example.com/login --alias login
+
+# 2. 填写表单
+visionl type login "#email" "user@example.com"
+visionl type login "#password" "s3cret"
+
+# 3. 提交
+visionl click login "button[type=submit]"
+
+# 4. 截图验证
+visionl screenshot login -o logged-in.png
+```
+
+## 场景四：页面截图
+
+```bash
+# 打开并截图
+visionl page open https://www.example.com --alias page
+visionl wait page --ms 2000       # 等待渲染
+visionl screenshot page -o page.png
+
+# 滚动后截图
+visionl scroll page --down 600
+visionl screenshot page -o page-scrolled.png
+```
+
+## 场景五：JS 数据提取
+
+```bash
+# 1. 打开页面
+visionl page open https://api.example.com/data --alias data
+
+# 2. 执行 JS 提取 JSON 数据
+visionl eval data "JSON.parse(document.body.innerText)"
+# → {"ok":true,"data":{"result":{"items":[...]}}}
+
+# 3. 获取页面标题
+visionl eval data "document.title"
+# → {"ok":true,"data":{"result":"API Data Page"}}
+```
+
+## 场景六：REST 直通（高级）
+
+```bash
+# 不使用子命令，直接调用 HTTP API
+visionl raw POST /pages '{"url":"https://example.com","alias":"test"}'
+# → {"ok":true,"data":{"id":"p_5678",...}}
+
+visionl raw GET /pages/p_5678/text
+# → {"ok":true,"data":{"text":"..."}}
+
+visionl raw DELETE /pages/p_5678
+# → {"ok":true,"data":null}
+```
+
+## 场景七：智能体自动化工作流
+
+LLM 通过 VisionL 完成机票比价：
+
+```
+1. visionl page open https://flights.example.com --alias flights
+2. visionl type flights "#from" "北京"
+3. visionl type flights "#to" "上海"
+4. visionl type flights "#date" "2026-08-20"
+5. visionl click flights "#search"
+6. visionl wait flights --selector ".results"
+7. visionl text flights
+   → 提取票价信息
+8. visionl eval flights "document.querySelectorAll('.price').length"
+   → 统计结果数量
+9. visionl page kill flights
+```
+
+## 场景八：长时间运行的任务
+
+```bash
+# 打开监控面板
+visionl page open https://monitor.example.com --alias monitor --pretty
+# ✓ 页面已打开
+#   ID:    p_mon_001
+#   URL:   https://monitor.example.com
+#   别名:  monitor
+
+# ... 过了一段时间 ...
+
+# 还是同一个页面
+visionl page list --pretty
+# ✓ 1 个页面
+#   p_mon_001  monitor  https://monitor.example.com  active
+
+# 刷新重新截图
+visionl navigate monitor https://monitor.example.com
+visionl screenshot monitor -o latest.png
+```