vcli

打开可交互 CLI，支持识别图片、初始化环境、查看信息。非交互环境输出帮助。

vcli help

显示命令、参数和示例。

vcli init

初始化视觉模型环境：创建 venv、选择计算模式与能力、下载模型权重。首次使用前必须运行。

专属参数

能力选择

示例

跳过交互：vcli init --yes

自定义工作区：vcli init --yes --workspace "E:\code-vcli-data"

GPU + both + GPU OCR + B2：vcli init --yes --compute gpu --capabilities both --ocr-backend gpu --vlm-option B2

需要 Python 3.10+。模型缓存位置：~/.code-vcli/models/。下载依次尝试 HF_ENDPOINT（默认 Hugging Face 官网）、hf-mirror.com 和 ModelScope，并保留可续传文件；OmniParser 只把兼容的 icon_detect/*.pt 作为 YOLO 权重。

已安装环境再次运行 vcli init 会先询问是否卸载现有能力：输入 n（默认）保留现有安装，仅增量增补/调整能力（例如为「仅 OCR」增加 VLM）；输入 y 则卸载后全新安装。升级后再次运行会自动同步最新推理脚本，无需重新下载模型。

vcli run

对图片执行视觉识别。Agent 调用使用 --json。

专属参数

示例

JSON 输出：vcli run ./screenshot.png --json

Web 模式：vcli run ./webpage.png --web

Web 模式 + JSON：vcli run ./webpage.png --web --json

VLM 模式：vcli run ./image.png --vlm --json

Mix 模式：vcli run ./image.png --mix --json

自定义问题：vcli run ./image.png --vlm -p "这张页面主要的操作是什么？"

识别模式

VLM / Mix 模式需要 GPU 模式且已安装 VLM 能力（--mix 还需 OCR），未安装时在 init 中选择对应能力。Web 模式仅在网页/UI 截图场景使用，普通文档截图无需启用 --web。

vcli info

显示 code-vcli 版本、配置目录、工作区、系统环境、Python 和视觉模型状态。

输出内容

vcli install

把当前包安装到用户目录并配置 PATH，支持 Windows、macOS 与 Linux。

专属参数

首次安装

要求 Node.js 22+ 和 Python 3.10+。安装完成后重新打开终端。

查看当前生效路径：Windows 使用 where vcli，macOS/Linux 使用 which vcli。

vcli version

显示当前版本；--check 检查最新版。

专属参数

vcli update

从 npm Registry 更新 code-vcli 到最新版。

JSON 与错误码

run --json：结果保存到工作区 files/，stdout 只返回文件路径；普通 OCR 为纯文字 JSON，OCR 分支只有 Web 模式包含坐标和布局，VLM/Mix 使用各自的结构化字段。

{
  "text": "第一行\n第二行",
  "items": [
    {
      "text": "登录",
      "bbox": [10,20,60,40],
      "type": "ui_text",
      "region": "top-center",
      "cluster_id": 0
    }
  ],
  "layout": {
    "img_size": [1920, 1080],
    "item_count": 10,
    "patterns": {"has_top_nav": true, "has_form": true},
    "cluster_summary": [
      {"id": 0, "size": 3, "arrangement": "vertical", "region": "center"}
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "MODEL_TEXT_EMPTY",
    "message": "未识别到文字"
  }
}

JSON 顶层字段

超长 OCR 与 Mix artifact

Mix 默认最多注入 16,384 OCR tokens（上限 32,768），执行去重、百分比坐标压缩、页面首尾保留、九宫格抽样和金额/日期/UI 标签优先。完整文字保存为 *_ocr.txt，完整坐标与布局保存为 *_ocr_items.json。十万字符级页面先读取 OCR 结果的必要部分，再用 --vlm -p 发起针对性视觉问题。

items[] 字段

错误码