# GLM-Vision — 免费视觉桥接（Skill + MCP）

用智谱完全免费的 **GLM-4.6V-Flash** 视觉模型，给 **DeepSeek 等纯文本模型装上"眼睛"**：
图片/截图/OCR/图表/扫描文档 → 文字理解，无缝接入 agent。

## 特性

- ✅ **完全免费**：`glm-4.6v-flash`，128K 上下文，OpenAI 兼容接口
- ✅ **自动轮换**：429 限流/5xx 时自动降级到其他免费视觉模型（`glm-4.1v-thinking-flash`、`glm-4v-flash`）
- ✅ **双形态**：MCP 原生工具 + CLI 兜底（同一份核心代码）
- ✅ **零依赖核心**：`glm_vision.py` 纯 Python 标准库，无需 pip
- ✅ **本地 + URL**：本地图片自动 base64，URL 直传
- ✅ **6 大能力**：描述 / OCR / 图表 / 文档 / 截图 / 定位(grounding)

## 快速开始

### 1. 获取 API Key（免费）

1. 注册：<https://open.bigmodel.cn> （智谱开放平台，手机号即可）
2. 进入 [API Keys](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) 创建密钥
3. `glm-4.6v-flash` 免费，无需充值

### 2. 配置 Key（三选一，按优先级）

```bash
# 方式 A：环境变量（推荐，最安全）
#   Windows 永久设置：
setx ZHIPU_API_KEY "你的key"
#   PowerShell 当前会话：
$env:ZHIPU_API_KEY="你的key"

# 方式 B：全局配置文件
mkdir -p ~/.config/glm-vision
# 写入 config.json:
# {
#   "api_key": "你的key",
#   "base_url": "https://open.bigmodel.cn/api/paas/v4/chat/completions",
#   "model": "glm-4.6v-flash",          # 可选：固定单模型（不轮换）
#   "models": ["glm-4.6v-flash", "glm-4.1v-thinking-flash", "glm-4v-flash"]  # 可选：自定义轮换顺序
# }

# 方式 C：本目录 .env 文件
# ZHIPU_API_KEY=你的key
```

### 3. 安装 MCP 服务器依赖

```bash
pip install mcp
```

### 4. 注册到 opencode

在 `opencode.json`（或 `~/.config/opencode/opencode.jsonc`）的 `mcp` 字段添加：

```json
"mcp": {
  "glm-vision": {
    "type": "local",
    "command": ["python", "E:/tool/.opencode/skills/glm-vision/mcp_server.py"],
    "enabled": true
  }
}
```

重启 opencode 生效。

## CLI 用法

```bash
python glm_vision.py describe <图片路径或URL> [-q "问题"] [--no-thinking]
python glm_vision.py ocr <图片路径或URL> [--no-thinking]
python glm_vision.py chart <图片路径或URL> [-q "问题"]
python glm_vision.py document <图片路径或URL> [-q "问题"]
python glm_vision.py screenshot <图片路径或URL> [-q "问题"]
python glm_vision.py grounding <图片路径或URL> "目标元素" 

# 自定义轮换顺序（逗号分隔）或固定单模型
python glm_vision.py describe <图片> --models glm-4v-flash,glm-4.6v-flash
python glm_vision.py describe <图片> --model glm-4.6v-flash
```

## Python API

```python
from glm_vision import analyze_image
print(analyze_image(["screenshot.png"], mode="ocr"))
print(analyze_image(["https://example.com/chart.png"], mode="chart", question="最高点是哪个月"))
```

## 文件结构

```
glm-vision/
├── SKILL.md           # opencode skill 定义（触发词 + 使用指南）
├── glm_vision.py      # 核心库 + CLI（纯 stdlib，零依赖）
├── mcp_server.py      # MCP 服务器（需要 pip install mcp）
├── requirements.txt   # 仅 mcp
├── examples/
│   └── demo.md        # 示例
```

## 常见问题

| 问题 | 解决 |
|------|------|
| HTTP 429 | 免费模型限流，内置重试；仍失败会自动**降级到下一个免费视觉模型**（轮换），全部失败才报错 |
| 图片太大 | >10MB 自动压缩（需 `pip install pillow`） |
| 没有 response | 检查 Key、网络（bigmodel.cn 国内可直连） |
| 想换模型 | 改 `config.json` 的 `model` 字段；或用 `--models` / `--model` CLI 参数；`models` 数组自定义轮换顺序 |

## 免责声明

- 免费模型的速率限制可能随官方策略变化
- 请遵守智谱开放平台使用条款；不上传违反法律法规的内容