310 lines
5.7 KiB
Markdown
310 lines
5.7 KiB
Markdown
# VisionL CLI 命令参考
|
||
|
||
> 适用版本：v1
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
# 全局安装（需要先构建）
|
||
npm install -g ./packages/cli
|
||
|
||
# 或开发模式
|
||
cd packages/cli && npm link
|
||
```
|
||
|
||
安装后可使用 `visionl` 命令。
|
||
|
||
## 全局选项
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--pretty` | 人类可读格式输出（默认 JSON） |
|
||
| `--port <n>` | daemon 端口（默认 9527） |
|
||
| `--profile <id>` | 指纹配置模版（默认 desktop-chrome） |
|
||
| `--help` | 查看帮助 |
|
||
|
||
---
|
||
|
||
## 页面管理
|
||
|
||
### `visionl page open`
|
||
|
||
打开新页面。
|
||
|
||
```bash
|
||
visionl page open <url> [--alias <name>] [--profile <id>]
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
visionl page open https://www.baidu.com --alias baidu --profile desktop-windows
|
||
# {"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>..."}}
|
||
```
|
||
|
||
---
|
||
|
||
## 指纹配置
|
||
|
||
### `visionl profiles`
|
||
|
||
列出可用的指纹配置模版。
|
||
|
||
```bash
|
||
visionl profiles
|
||
# {"ok":true,"data":[{"id":"desktop-chrome","name":"桌面 Chrome (通用)"},{"id":"desktop-windows","name":"Windows 10 Chrome"},...]}
|
||
```
|
||
|
||
| 模版 ID | 说明 | UA 平台 |
|
||
|---------|------|---------|
|
||
| `desktop-chrome` | 桌面 Chrome 通用（默认） | Linux x86_64 |
|
||
| `desktop-windows` | Windows 10 Chrome | Windows NT 10.0 |
|
||
| `desktop-mac` | macOS Chrome | Macintosh Intel |
|
||
|
||
---
|
||
|
||
## Daemon 管理
|
||
|
||
> 当前 CLI **没有 `daemon start/stop` 子命令**。首条页面命令会自动拉起**带反检测浏览器**的 daemon（`boot.js`）；手动启动可选如下方式。
|
||
|
||
### 手动启动浏览器 daemon
|
||
|
||
```bash
|
||
# 方式一：daemon 包 start 脚本（= node ./dist/boot.js）
|
||
cd packages/daemon && npm run start
|
||
|
||
# 方式二：直接节点
|
||
node packages/daemon/dist/boot.js
|
||
|
||
# 方式三：全局 bin（构建后安装）
|
||
visionl-daemon
|
||
|
||
# 指定端口：VISIONL_PORT 环境变量，默认 9527
|
||
VISIONL_PORT=8080 node packages/daemon/dist/boot.js
|
||
```
|
||
|
||
> 注意：必须走 `boot.js`（它初始化 `BrowserManager` 并把它传给 `startServer`）。若直接 `node packages/daemon/dist/server.js`，daemon 会**没有浏览器**，页面路由不注册，`open/list/...` 一律 `not found`（这是已修复的坑）。
|
||
|
||
### 重启 / 停止 daemon
|
||
|
||
没有 `daemon stop` 子命令；结束方式为 `kill <daemon的pid>`（含浏览器常驻进程）即可。
|
||
|
||
### `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 | 无效参数 |
|