# vision-eye

纯本地视觉插件包：给纯文本大模型（DeepSeek、Qwen 纯文本版等）接上"眼睛"。
MCP server（工具层）+ Claude Agent Skill（触发层）+ 本地视觉模型（推理层）。
**零云端 API、零 API key，图片不出本机**（仅首次模型下载需联网，支持
`HF_ENDPOINT=https://hf-mirror.com` 镜像）。

## 安装

```bash
pip install vision-eye          # 形态 A：复用本机 Ollama 视觉模型
vision-eye install              # 自动检测环境并分级
vision-eye doctor               # 诊断后端 / 模型 / 降级历史
```

### 安装形态

| 形态 | 条件 | 行为 |
|---|---|---|
| A | Ollama 已有视觉模型（qwen*vl / minicpm-v / llava 等，模糊匹配） | 复用，不下载 |
| B-GPU | CUDA 可用且显存 ≥ 8GB | Qwen2.5-VL-3B int4 + SmolVLM-500M 兜底 |
| B-CPU | 无 GPU / 显存或磁盘不足 | 仅 SmolVLM-500M |

## MCP 注册（Claude Code）

```bash
claude mcp add vision-eye -- vision-eye serve
```

## 工具

| 工具 | 功能 |
|---|---|
| describe_image | 通用描述（focus 可选） |
| extract_text | OCR，保留布局 |
| parse_table | 表格转 markdown |
| analyze_ui | 截图元素识别与报错诊断 |
| zoom_region | 放大局部细看 (x, y, w, h) |

- 返回 < 500 token，超长截断并提示用 zoom_region
- 压缩到最长边 2048px；MD5(压缩后字节+prompt) 缓存于 `~/.vision-eye/cache/`
- 三级降级链自动兜底，降级结果带 `[precision: low]` 标记（复杂图表结论需谨慎）
- 降级日志：`~/.vision-eye/logs/`，`vision-eye doctor` 查看

## CLI

```bash
vision-eye install / doctor / serve / daemon / cache clear
```

`daemon` 常驻模式预加载模型，提供 streamable HTTP（默认 127.0.0.1:8765）。