UI感知引擎
人工智能代理的感知层——对网络界面的类人理解。
将结构化（DOM+a11y树+CSS）、可视化（三层视觉管道）和时态数据融合为一个统一的 UI场景图 法学硕士可以流利地推理。作为MCP服务器公开，以便Claude可以导航和检查任何实时URL。
它的作用
- 在真正的Playwright浏览器中导航到任何URL
- 从实时DOM中提取紧凑、LLM可读的场景图
- 通过OmniParser V2直观地检测UI元素，通过Qwen3 VL理解布局，并通过Claude Vision进行深度UX分析
- 跟踪UI转换和状态之间的差异
- 预测启示（你可以与之交互的内容，以及当你这样做时会发生什么）
- 将所有内容显示为Claude可以直接调用的MCP工具
MCP工具
| 工具 | 说明 |
|---|---|
navigate | 导航到URL并返回初始场景图 |
get_scene | 重新捕获当前场景（压缩文本或完整JSON） |
get_affordances | 按优先级列出交互元素 |
act | 执行浏览器操作：单击、键入、滚动、悬停、按键、导航、等待 |
get_console_logs | 返回捕获的浏览器控制台消息 |
get_network_errors | 返回失败的网络请求 |
get_screenshot | 捕获屏幕截图并将其作为图像返回 |
detect_elements | 运行元素检测（OmniParser或Claude Vision回退） |
analyze_visual | 通过Qwen3 VL进行视觉理解：层次结构、对比度、间距、用户体验 |
compare_states | 当前与前一场景的差异图——显示了发生了什么变化 |
watch | 开始实时关键帧捕获（CDP截屏+感知哈希） |
stop_watch | 停止关键帧捕获并返回更改摘要 |
三层视觉管道(visual=true)
两者 navigate 和 get_scene 接受可选 visual: true 参数。启用后，引擎将运行一个三层视觉管道：
- A级：OmniParser V2 --快速元素检测（~0.8s）。YOLOv8+Florence-2模型在8100端口上作为Python sidecar运行。检测带有边界框和标签的按钮、输入、图像、图标和其他UI元素。
- B层：Qwen3 VL经Ollama --视觉理解（~2-4s）。使用检测到的元素上下文分析屏幕截图，以评估视觉层次结构、对比度问题、间距问题、启示清晰度和状态指标。
- C级：Claude Vision API --深度用户体验分析（约3-5s，仅按需）。通过以下方式请求时提供详细的定性分析
analyze_visual或depth: 'deep'.
优雅的退化： 如果支持服务不可用，每一层都会自动跳过。该系统适用于运行的任何服务组合——从所有三层到仅进行结构分析，根本没有视觉服务。
使用 detect_elements 仅用于快速A级检测，或 analyze_visual 对于整个A+B级管道。
act 操作类型
| 类型 | 参数 |
|---|---|
click | x, y |
clickSelector | selector |
type | text, selector （可选） |
scroll | direction (up/down), amount （可选） |
hover | x, y |
wait | ms |
navigate | url |
back | — |
pressKey | key |
安装
来自npm
npm install -g ui-perception-engine或者在不安装的情况下使用：
npx ui-perception-engine安装Playwright浏览器（仅限第一次）：
npx playwright install chromium来源
git clone https://github.com/dirkknibbe/uipe.git
cd uipe
pnpm install
pnpm build克劳德代码MCP配置
添加到您的Claude Code MCP配置中(~/.claude/mcp.json 或项目 .mcp.json):
{
"mcpServers": {
"ui-perception-engine": {
"command": "npx",
"args": ["ui-perception-engine"]
}
}
}或者，如果全局安装：
{
"mcpServers": {
"ui-perception-engine": {
"command": "uipe"
}
}
}或者从本地克隆：
{
"mcpServers": {
"ui-perception-engine": {
"command": "node",
"args": ["/path/to/uipe/ui-perception-engine/dist/src/mcp/index.js"],
"env": {
"OLLAMA_URL": "http://localhost:11434",
"OLLAMA_MODEL": "qwen3-vl:8b",
"OMNIPARSER_URL": "http://localhost:8100",
"ANTHROPIC_API_KEY": "sk-ant-..."
}
}
}
}环境变量
| 变量 | 目的 |
|---|---|
ANTHROPIC_API_KEY | Claude Vision API-检测回退+深度分析（C级） |
OLLAMA_URL | ollama服务器URL（默认值： http://localhost:11434) |
OLLAMA_MODEL | 视觉模型名称（默认值： qwen3-vl:8b) |
OMNIPARSER_URL | OmniParser V2侧边栏URL（默认值： http://localhost:8100) |
看 .env.example 查看可配置变量的完整列表，包括帧捕获、浏览器和时间设置。
地方视觉服务
三层愿景管道使用两个本地服务。两者都是可选的——没有它们，系统会优雅地降级。
Ollama（B级——视觉理解）：
# Install Ollama: https://ollama.com
ollama pull qwen3-vl:8b
ollama list # verify model is available
# Ollama serves on http://localhost:11434 by defaultOmniParser V2（A级——元素检测）：
OmniParser作为Python FastAPI sidecar在端口8100上运行。看 本地视觉交接文件 第5节了解完整的设置说明。
# Quick check if OmniParser is running:
curl -s http://localhost:8100/health没有本地服务： 如果Ollama和OmniParser都没有运行， visual=true 回到Claude Vision API（需要 ANTHROPIC_API_KEY).如果根本没有视觉服务可用，引擎将使用仅结构分析（DOM+a1y树）。
与使用 live-deployment-check 技能
这 live-deployment-check 技能直接与此MCP服务器配对，以直观地验证部署的站点或应用程序——捕捉仅在真实浏览器中出现的损坏图像、空路线、卡住的旋转器和占位符文本。
工作流程
1. navigate(url) → load the page, get initial scene
2. get_scene() → re-capture after JS hydrates (critical for SPAs)
3. get_console_logs() → check for JS errors (type="error")
4. get_network_errors() → check for failed API/resource requests
5. Scan scene output → look for broken signals (see below)
6. act() on nav links → walk routes, verify each one loads
7. Report findings → list what's working and what's broken场景输出中的常见信号
# Broken image:
img[img]:"broken"
# Empty SPA route (component failed to load):
router-outlet[element] ← no children = problem
# Stuck loading spinner:
progressbar[progressbar] ← present after JS settles = API error
# Route loaded correctly:
router-outlet[element]
app-order-list[element]:"Order Management..." ← has content = good示例
// After deploying an Angular app
navigate("http://your-app.vercel.app")
get_scene() // wait for hydration
→ check router-outlet has content, no broken img nodes
// Walk routes
act({ type: "clickSelector", selector: "a[href='/orders']" })
get_scene()
→ verify orders page loaded
act({ type: "clickSelector", selector: "a[href='/customers']" })
get_scene()
→ verify customers page loaded检查什么
- 破碎的图像 —
img节点与"broken"内容 - 空路线 —
router-outlet没有子元素 - 旋转器卡住 —
progressbar之后仍然存在get_scene() - 占位文本 —
undefined,null,TODO, `` 在可见文本中 - 错误页面 --404或错误组件呈现，而不是预期内容
发展
pnpm test # run tests
pnpm test:watch # watch mode
pnpm lint # lint
pnpm build # compile TypeScript
pnpm mcp # start MCP server (after build)
pnpm start:dev # check services + start MCP server建筑
src/
├── config.ts ← centralized config (dotenv)
├── types/ ← shared types (contracts between pipelines)
├── browser/ ← BrowserRuntime (Playwright)
├── pipelines/
│ ├── structural/ ← DOM + a11y tree extraction
│ ├── visual/
│ │ ├── index.ts ← Three-tier orchestrator (detect/understand/deep)
│ │ ├── omniparser.ts ← OmniParser V2 client (Tier A)
│ │ ├── claude-vision.ts ← Claude Vision API (Tier C)
│ │ ├── ollama-vision.ts ← Qwen3-VL via Ollama (Tier B)
│ │ └── frame-capture.ts ← CDP screencast + perceptual hashing
│ ├── fusion/ ← merge visual + structural → SceneGraph
│ ├── temporal/ ← change detection + state tracking
│ └── affordance/ ← predict interaction outcomes
├── mcp/ ← MCP server (12 tools)
└── utils/视口默认值： 1280x720（可通过环境配置） 屏幕截图格式： PNG（无损，视觉模型需要）