感谢 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 Agent 调用时建议始终带 --json。普通 OCR 的 JSON 只保存全文、模式和引擎；在 OCR 分支中，只有 --web 会额外输出文字框坐标、UI 元素和页面布局：
vcli run ./webpage.png --web --jsonMix 默认最多向 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。
仓库提供 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。