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,286 @@
+# VisionL CLI 命令参考
+
+> 适用版本：v1
+
+## 安装
+
+```bash
+# 全局安装（需要先构建）
+npm install -g ./packages/cli
+
+# 或开发模式
+cd packages/cli && npm link
+```
+
+安装后可使用 `visionl` 命令。
+
+## 全局选项
+
+| 选项 | 说明 |
+|------|------|
+| `--pretty` | 人类可读格式输出（默认 JSON） |
+| `--port <n>` | daemon 端口（默认 9527） |
+| `--help` | 查看帮助 |
+
+---
+
+## 页面管理
+
+### `visionl page open`
+
+打开新页面。
+
+```bash
+visionl page open <url> [--alias <name>]
+```
+
+**示例：**
+
+```bash
+visionl page open https://www.baidu.com --alias baidu
+# {"ok":true,"data":{"id":"p_a1b2c3d4","url":"https://www.baidu.com","alias":"baidu","title":"百度一下，你就知道","status":"active"}}
+```
+
+### `visionl page list`
+
+列出所有已打开页面。
+
+```bash
+visionl page list
+# {"ok":true,"data":[{"id":"p_a1b2c3d4","url":"...","alias":"baidu",...}]}
+```
+
+### `visionl page info`
+
+查看页面详情。
+
+```bash
+visionl page info <id|alias>
+visionl page info baidu
+```
+
+### `visionl page kill`
+
+关闭指定页面。
+
+```bash
+visionl page kill <id|alias>
+```
+
+### `visionl page kill-all`
+
+关闭所有页面。
+
+```bash
+visionl page kill-all
+```
+
+---
+
+## 页面操作
+
+### `visionl click`
+
+点击指定元素。
+
+```bash
+visionl click <id|alias> <selector>
+
+# 示例
+visionl click baidu "#su"
+```
+
+### `visionl type`
+
+在输入框中输入文本。
+
+```bash
+visionl type <id|alias> <selector> <text>
+
+# 示例
+visionl type baidu "#kw" "VisionL浏览器"
+```
+
+### `visionl scroll`
+
+滚动页面。
+
+```bash
+visionl scroll <id|alias> [--down <px>] [--bottom]
+
+# 示例
+visionl scroll baidu --down 300
+visionl scroll baidu --bottom
+```
+
+### `visionl navigate`
+
+页面跳转。
+
+```bash
+visionl navigate <id|alias> <url>
+```
+
+### `visionl eval`
+
+在页面中执行 JavaScript。
+
+```bash
+visionl eval <id|alias> <js-code>
+
+# 示例
+visionl eval baidu "document.title"
+# {"ok":true,"data":{"result":"百度一下，你就知道"}}
+```
+
+### `visionl wait`
+
+等待条件满足。
+
+```bash
+visionl wait <id|alias> [--selector <sel>] [--ms <n>]
+
+# 等待选择器出现
+visionl wait baidu --selector "#content"
+# 等待 2 秒
+visionl wait baidu --ms 2000
+```
+
+---
+
+## 内容获取
+
+### `visionl screenshot`
+
+获取页面截图。
+
+```bash
+visionl screenshot <id|alias> [-o <file.png>]
+
+# 输出 base64（默认）
+visionl screenshot baidu
+
+# 写入文件
+visionl screenshot baidu -o screenshot.png
+```
+
+### `visionl text`
+
+获取页面纯文本。
+
+```bash
+visionl text <id|alias>
+# {"ok":true,"data":{"text":"百度一下，你就知道\n..."}}
+```
+
+### `visionl html`
+
+获取页面 HTML 源码。
+
+```bash
+visionl html <id|alias>
+# {"ok":true,"data":{"html":"<!DOCTYPE html>..."}}
+```
+
+---
+
+## Daemon 管理
+
+### `visionl daemon start`
+
+手动启动 daemon。
+
+```bash
+visionl daemon start [--port <n>]
+
+# 默认端口 9527
+visionl daemon start
+# 指定端口
+visionl daemon start --port 8080
+```
+
+### `visionl daemon stop`
+
+优雅关闭 daemon（不杀死已打开的页面）。
+
+```bash
+visionl daemon stop
+```
+
+### `visionl daemon status`
+
+查看 daemon 运行状态。
+
+```bash
+visionl daemon status
+# {"ok":true,"data":{"running":true,"pid":12345,"port":9527}}
+```
+
+---
+
+## REST 直通
+
+直接向 daemon 发送原始 HTTP 请求。
+
+```bash
+visionl raw <METHOD> <path> [body]
+
+# 示例
+visionl raw POST /pages '{"url":"https://example.com"}'
+visionl raw GET /pages
+visionl raw GET /pages/p_abc123/text
+visionl raw DELETE /pages/p_abc123
+```
+
+---
+
+## 自动拉起
+
+CLI 在执行页面命令前会自动检测 daemon 是否存活。如果 daemon 未运行，会自动启动。
+
+自动拉起流程：
+
+1. 向默认端口（9527）发送 `GET /health`
+2. 无响应时检查 `~/.visionl/daemon.pid` 中的进程是否存活
+3. 都不行则 `spawn` 启动 daemon
+4. 轮询健康检查，最多等待 3 秒
+5. 超时则报错退出
+
+**状态文件：**
+
+- `~/.visionl/daemon.pid` — daemon PID
+- `~/.visionl/daemon.port` — daemon 端口
+
+---
+
+## 输出格式
+
+### JSON（默认）
+
+每行一个 JSON 对象，LLM 直接解析：
+
+```json
+{"ok":true,"data":{"id":"p_a1b2c3d4","url":"https://example.com","title":"Example"}}
+```
+
+### 人类可读（--pretty）
+
+```bash
+visionl page open https://example.com --pretty
+# ✓ 页面已打开
+#   ID:    p_a1b2c3d4
+#   URL:   https://example.com
+#   标题:  Example Domain
+#   状态:  active
+```
+
+---
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 成功 |
+| 1 | 一般错误（页面不存在、选择器未找到等） |
+| 2 | daemon 不可达 |
+| 3 | 无效参数 |