code-vcli — 为 AI 模型提供 Web 开发视觉能力

感谢 LINUX DO 社区。

AI 编码模型（如 GLM、DeepSeek、Qwen-max）能写代码，但无法「看见」屏幕。

code-vcli 给它们一双眼睛：把截图 / 网页截图 / 文档图片转成结构化文本和 JSON，让没有视觉能力的模型也能看懂 UI 布局、按钮位置、卡片结构，准确完成 web 开发任务。

支持三条识别路线：纯 OCR（PP-OCRv6）、纯 VLM（Qwen2.5-VL 视觉理解）、OCR + VLM Mix（OCR 与 VLM 顺序执行）。Mix 不会把无限长度的 OCR JSON 原样塞给 VLM，而是按 token 预算去重、空间采样和压缩；完整 OCR 文字、坐标与布局另存为 artifact，供 Agent 按需读取。推理在本地完成，图片不上传。

文档站：https://gusheng107.github.io/code-vcli/

平台

• Windows 10/11（PowerShell / CMD / Windows Terminal）
• macOS（Apple Silicon 与 Intel，zsh / bash）
• Linux（x64 / arm64，bash / zsh）

需要 Node.js 22+ 和 Python 3.10+。

安装

直接使用 npm 安装：

npm i code-vcli

安装过程会自动部署运行依赖、用户级 vcli 启动入口并加入 PATH。首次安装后重新打开终端，即可直接运行：

vcli help

安装位置：

Windows：    %LOCALAPPDATA%\.code-vcli\bin\vcli.cmd
macOS/Linux：~/.code-vcli/bin/vcli
配置目录：    ~/.code-vcli/

重新打开终端后，直接运行 vcli 进入可交互 CLI，或查看完整帮助：

vcli help

查看当前生效的 CLI 路径：

# Windows
where vcli

# macOS / Linux
which vcli

初始化

首次使用先初始化环境（创建 venv、选择计算模式与能力、下载模型）：

vcli init

初始化时按提示选择：

• 计算模式：CPU（仅 OCR）或 GPU（可装 OCR 和/或 VLM）。
• 能力组合（GPU 模式）：仅 OCR / 仅 VLM / 都要（--mix 需要两者）。
• OCR 放置（GPU + 含 OCR 时）：默认选择 CPU 或 GPU；运行时也可通过 --ocr-backend 临时覆盖。Mix 会在 OCR 完成后释放其资源，再加载 VLM。
• VLM 模型：项目提供 A1、A2、B1、B2、C1、C2 六个组合。系统按显存与平台推荐；选择超出显存建议的型号会警告并要求确认。Apple MPS 与 AMD ROCm 使用 BF16，bitsandbytes NF4 仅支持 Windows/Linux NVIDIA CUDA。

跳过交互用默认值：

vcli init --yes
vcli init --yes --workspace "E:\code-vcli-data"
# 明确安装 GPU + OCR/VLM + GPU OCR + B2
vcli init --yes --compute gpu --capabilities both --ocr-backend gpu --vlm-option B2

已安装环境再次运行 vcli init 会先询问是否卸载现有能力：输入 n（默认）保留现有安装，仅增量增补/调整能力（例如为「仅 OCR」增加 VLM）；输入 y 则卸载后全新安装。系统自动对比差异，只下载新增模型、复用 venv/PyTorch 等共同依赖。

升级 code-vcli 后，已安装的环境通过 vcli init 自动同步最新推理脚本到工作区，无需重新下载模型。

初始化会在工作区下自动创建 files/ 文件夹，建议把待识别的截图统一放到这里方便管理。通过 vcli info 可查看当前工作区路径。

~/.code-vcli/              工作区（默认）
├── files/                 截图存放目录（init 时自动创建）
├── models/                模型权重
└── venv/                  Python 虚拟环境

使用

vcli run ./image.png              # OCR 模式：整图 OCR（PP-OCRv6）
vcli run ./screenshot.png --web   # OCR + Web：网页截图，叠加 YOLO 元素检测
vcli run ./image.png --json       # 纯 OCR JSON：只含全文/模式/引擎，保存到工作区 files/
vcli run ./webpage.png --vlm      # VLM 模式：Qwen2.5-VL 结构化视觉理解（需已装 VLM）
vcli run ./webpage.png --mix      # Mix：OCR 后释放资源，再加载 VLM
vcli run ./webpage.png --mix --ocr-backend cpu   # CPU OCR + GPU VLM
vcli run ./webpage.png --mix --ocr-backend gpu   # GPU OCR + GPU VLM
vcli run ./webpage.png --mix --mix-ocr-context-tokens 8192
vcli run ./image.png --vlm -p "这张页面主要的操作是什么？"
vcli run ~/.code-vcli/files/login.png --web --json   # 直接引用 files/ 下的截图

识别模式：

| 模式 | 说明 | 命令 | | --- | --- | --- | | --ocr（默认） | 纯 OCR，PP-OCRv6，可选 --web | vcli run ./image.png | | --vlm | 纯 VLM 结构化视觉理解，返回视觉事实 text 及 summary/elements/annotations/layout | vcli run ./image.png --vlm | | --mix | OCR 与 VLM 顺序执行；返回完整视觉说明和 OCR 证据，annotations 仅作额外批注结构 | vcli run ./image.png --mix |

--vlm / --mix 需要 GPU 模式且已安装 VLM 能力（--mix 还需 OCR）。未安装时会在初始化界面选择对应能力后使用。

VLM 与 Mix 使用截图无关的通用系统提示词：先逐区扫描并完整覆盖图中可靠可见的信息，不因内容小、在边缘或与附加问题无关而漏掉；同时禁止猜测、脑补、自动纠错和弄虚造假，无法可靠确认的内容不输出。text 只包含模型概述与页面分区中的视觉事实；summary 只保存纯视觉概述，不混入图像尺寸、坐标、字段名或运行诊断；elements / layout 提供空间与页面结构；annotations 只额外记录叠加批注及其目标关联。Mix 的文字转写以 OCR 扫描结果为主要依据，VLM 负责补充图形、布局、状态和关系；-p 内容只作为附加任务拼接在默认任务之后。完整 OCR items 始终保存到 artifact，体积较小时也会内联在 Mix 主结果中。

AI 调用场景

给 AI Agent 调用时建议始终带 --json。普通 OCR 的 JSON 只保存全文、模式和引擎；在 OCR 分支中，只有 --web 会额外输出文字框坐标、UI 元素和页面布局：

vcli run ./webpage.png --web --json

超长网页、表格与文档

Mix 默认最多向 VLM 注入 16,384 个 OCR tokens，上限 32,768。压缩过程保留页面首尾、九宫格空间覆盖、金额/日期/数字、UI 标签等高价值项，并输出 ocr.context 统计。完整数据拆为：

• *_ocr.txt：完整线性文字，适合 Agent 先快速阅读；
• *_ocr_items.json：完整文字框、坐标和布局；
• *_output.json：VLM 结果、有限 OCR 预览、artifact 路径和压缩统计。

十万字符级页面使用两阶段调用：

vcli run ./page.png --json
# Agent 读取 OCR JSON 中必要部分后，构造针对性问题
vcli run ./page.png --vlm -p "结合我提取的关键字段，判断页面的主要操作和异常状态"

也可用 --mix-ocr-context-tokens 0 禁止 Mix 自动注入 OCR，仅保留 OCR artifact 与图像理解。

Web 模式输出示例：

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

Web 模式原理：先用 PP-OCRv6 全图识字，再用 YOLO 定位 UI 元素，通过 IoU、中心点距离、面积比把文字归入元素。输出会去除重复 OCR 框、低置信空元素和可由 bbox 推导的冗余字段；每项仅保留 text、bbox、type、region、cluster_id，组排列信息集中在 layout.cluster_summary。

AI Agent Skill

仓库提供 code-vcli Skill，让 AI Agent 调用 vcli CLI 对截图执行本地视觉识别与网页 UI 元素解析。Skill 内含完整的 CLI 安装、初始化、调用流程，Agent 加载后即可知道如何使用 vcli。

推荐通过 Skills CLI 全局安装（会自动放入对应 Agent 的 skills 目录）：

npx skills add GuSheng107/code-vcli --skill code-vcli -g

也可以在文档站 Skills 页面下载 ZIP 手动安装，解压后将 code-vcli 文件夹放入所用 Agent 的 skills 目录即可。

命令

| 命令 | 说明 | | --- | --- | | vcli | 交互界面 | | vcli init [options] | 初始化环境；支持计算模式、能力、OCR 后端和 A1-C2 VLM 选项 | | vcli run <image> [options] | 识别图片 | | vcli info | 环境信息 | | vcli update | 更新到最新版 | | vcli install [--force] | 安装到用户目录并加入 PATH | | vcli version [--check] | 版本信息 | | vcli help | 帮助 |

init 关键参数：

--yes                         跳过交互，使用默认/显式值
--workspace <path>            工作区
--compute <cpu|gpu>           计算模式
--capabilities <ocr|vlm|both> 能力组合
--ocr-backend <cpu|gpu>       默认 OCR 后端
--vlm-option <A1..C2>         VLM 官方模型组合

run 参数：

<image>                    图片路径（必填）
    --ocr <ppocrv6>        OCR 引擎（默认 ppocrv6）
    --vlm                  使用 VLM 视觉理解
    --mix                  OCR + VLM 顺序执行（需已装 both）
-p, --prompt <text>        VLM/Mix 附加问题（拼接到默认提示词后）
-w, --web                  网页/UI 场景
    --json                 输出紧凑 JSON 并返回文件路径
    --timeout <seconds>    推理超时
    --min-confidence <0~1> 空 UI 元素保留阈值
    --ocr-backend <cpu|gpu> 本次 OCR/Mix 覆盖 OCR 位置
    --mix-ocr-context-tokens <0~32768> Mix OCR token 预算（默认 16384）

支持 png / jpg / jpeg / webp / bmp / tiff / tif，上限 20 MB。

模型

• PP-OCRv6：CPU 使用 OpenVINO，GPU 使用 RapidOCR Torch CUDA/MPS；两套模型可与 GPU VLM 顺序配合。
• OmniParser V2 YOLO：UI 元素检测（--web 启用）。

VLM 提供以下模型与量化组合：

| ID | 模型 | 建议显存 | 说明 | | --- | --- | --- | --- | | A1 | Qwen2.5-VL 3B BF16 | 8GB+ | 小模型原生精度 | | A2 | Qwen2.5-VL 3B NF4 INT4 | 4GB+ | bitsandbytes 运行时量化，最省显存，仅 NVIDIA CUDA | | B1 | Qwen2.5-VL 7B BF16 | 16GB+ | 7B 原生精度 | | B2 | Qwen2.5-VL 7B NF4 INT4 | 8GB+ | bitsandbytes 运行时量化，16GB NVIDIA GPU 推荐 | | C1 | Qwen2.5-VL 32B BF16 | 72GB+ | 32B 原生精度 | | C2 | Qwen2.5-VL 32B NF4 INT4 | 24GB+ | bitsandbytes 运行时量化，高显存 NVIDIA CUDA |

Apple MPS 与 AMD ROCm 只支持 BF16（A1/B1/C1）；NF4 仅支持 Windows/Linux NVIDIA CUDA。A2/B2/C2 下载对应的官方 BF16 权重，并在加载时通过 bitsandbytes 转为 4-bit。显存不足会警告并由用户确认，平台不兼容则在下载前停止。

模型下载依次尝试 HF_ENDPOINT（未设置时为 Hugging Face 官网）、hf-mirror.com，最后回退到 ModelScope。三个 Qwen2.5-VL 仓库在 ModelScope 使用相同权重分片；OmniParser 使用相同的 icon_detect/model.pt，并兼容其他 .pt 文件名。icon_caption/model.safetensors 属于不同模型，不会被误作 YOLO 检测权重。各下载源都会复用已完成文件或分片，HTTPS 代理环境变量同样生效。

隐私和安全

• 图片本地处理不上传，无遥测。
• 模型缓存位置：~/.code-vcli/models/
• 工作区：~/.code-vcli/ 或自定义路径，截图建议放到工作区下的 files/

开发

npm install
npm run check    # 类型检查
npm run build    # 编译到 dist/
npm run build:skill-zip  # 生成 Skill 下载包

要求 Node.js 22 或更高版本。

Web 模式输出紧凑布局信息：页面级 layout.patterns / cluster_summary，元素级 region / cluster_id。Mix 另输出 OCR artifact 与 token 压缩统计。详见 skills/code-vcli/SKILL.md。

许可

AGPL-3.0-or-later。