AskaEth
0c437a96f1
- architecture.md: 完整架构设计（技术栈、API、CLI、生命周期、测试策略） - api.md: REST + WebSocket 接口文档 - cli.md: CLI 命令参考 - contributing.md: 开发规范与 JSON 转义要求 - quickstart.md: 快速开始指南 - llm-integration.md: 智能体集成指南 - examples.md: 8 个典型使用场景
287 lines
4.5 KiB
Markdown
287 lines
4.5 KiB
Markdown
# 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 | 无效参数 |
|