VisionLint Local

Purpose

VisionLint Local 是面向 WorkBuddy 的本地网页视觉与响应式审计 Skill。它把 Playwright 截图、DOM Grounding、确定性布局规则和本地 OpenVINO VLM 组合成可重复执行的审计流程，并在修改代码后执行 verify-fix 判断问题是 fixed、still_present 还是 inconclusive。

Important

只通过 scripts\run.ps1 调用本 Skill。不要直接调用其他 Python 脚本。
正式比赛链路默认 hybrid，需要真实本地模型；rule_only 只能由用户明确选择，不能冒充本地 AI 验收。
默认仅允许 loopback 页面，并阻断页面向公网发起的 HTTP(S)、WebSocket 与 Service Worker egress。
用户显式允许外部资源后，该次运行不再属于“完全离线”证据。
本地视觉模型失败时必须明确报告；比赛入口为 fail-closed，不能把模型失败伪装成视觉分析成功。
第一次运行会创建独立 Python 3.11 环境并安装 Playwright Chromium。第一次 hybrid 运行还可能下载数 GB 的本地模型。
没有云端视觉推理 fallback。

Usage

1. 准备默认本地模型

.\scripts\run.ps1 prepare-model

模型下载使用 .partial 目录；只有 info.json 中所有 required_files 验证通过后才原子完成。下载中断后可再次运行同一命令继续。

若一次 WorkBuddy 调用因模型准备未完成返回退出码 3：

.\scripts\run.ps1 --continue

它会恢复最近一次模型门控请求。

2. 单页审计

.\scripts\run.ps1 audit http://127.0.0.1:8000/index.html

3. 响应式审计

.\scripts\run.ps1 responsive http://127.0.0.1:8000/index.html

4. 修复验证

先保存 baseline，再修改页面：

.\scripts\run.ps1 audit http://127.0.0.1:8000/index.html > baseline.json
.\scripts\run.ps1 verify-fix http://127.0.0.1:8000/index.html --baseline baseline.json

5. 服务状态 / 模型复用证据

.\scripts\run.ps1 status

重点查看：

process_id：连续调用应保持同一 resident server PID；
model.load_count：同一模型/device 的第二次 warm 请求不应再次增加；
model.models[].loaded：模型是否已在进程中常驻；
model.models[].device：实际设备；
model.models[].error：最近模型错误。

公开状态不会返回本机模型绝对路径，只返回模型目录名。

Examples

| 用户意图 | 调用 | | --- | --- | | 检查本地网页 UI | scripts\run.ps1 audit <local-url> | | 检查桌面/平板/手机响应式 | scripts\run.ps1 responsive <local-url> | | 修复后确认问题是否解决 | scripts\run.ps1 verify-fix <local-url> --baseline <report.json> | | 下载/续传本地模型 | scripts\run.ps1 prepare-model / scripts\run.ps1 --continue | | 检查 resident 模型是否复用 | scripts\run.ps1 status | | 用户明确只要规则、不跑 VLM | 在审计命令后加 --runtime-mode rule_only |

Output interpretation

审计成功输出 JSON：

issues[]：问题列表；
category：如 horizontal_overflow、text_clipping、abnormal_overlap；
element_id / selector：DOM 定位；
page_snapshots[]：viewport、截图、DOM 证据；
metadata.vision.status：hybrid 下视觉分析状态，真实成功应为 succeeded；
score：当前审计评分。

verify-fix：

fixed：基线问题不再复现；
still_present：仍能可靠复现；
inconclusive：证据不足，禁止声称已修复；
new_issues：修复后新引入的问题。

Failure handling

退出码 0：命令成功；
退出码 1：运行/配置/服务错误；
退出码 2：参数错误；
退出码 3：模型准备未完成，可运行 scripts\run.ps1 --continue。

遇到失败时先读取 stderr 和 artifacts/runtime/server.log。不要通过删除测试、降低断言或切换 rule_only 来掩盖 hybrid 失败。

Privacy boundary

默认模式：

审计目标必须是 loopback；
浏览器公网 HTTP(S) 子资源默认阻断；
外部 WebSocket 默认阻断；
Service Worker egress 默认阻断；
截图、DOM、规则结果与本地 VLM 推理均留在本机。

allow_external_resources 是显式 opt-in。一旦启用，不要把该次运行描述为“数据绝不出机”。