Codex Vision

给 Codex 装上"眼睛"的插件：当当前模型无法接收图片输入时，用本地 Ollama 视觉模型识别图片内容。

• 默认模型：qwen2.5vl:7b（Ollama 本地）
• 端点：http://127.0.0.1:11434
• 云端兜底：DashScope（阿里云通义千问）qwen-vl-max
• 全程本地离线处理，图片不上传公网（仅使用 DashScope 兜底时会发送到阿里云）

功能特性

特性	说明
🖼️ 本地离线识别	默认走本地 Ollama，图片不出本机
🧩 多模型适配	任意 Ollama 多模态模型（Qwen-VL / LLaVA / ...）可切换
🎚️ 双识图档位	code（侧重提取代码/文字，省 token）与 general（完整画面描述）
🩺 健康检测	自动检查 Ollama 服务与模型是否就绪，未安装时提示拉取命令
⚡ 图片本地压缩	大图自动降采样（默认 ≤2048px），降低推理耗时与内存
🧹 临时文件清理	压缩产生的临时文件用完自动删除
⚙️ 配置不碰代码	模型、地址、端口、精度、档位全部可经 config.json 调整
☁️ 云端兜底	设置 DASHSCOPE_API_KEY 即可切换到 DashScope

目录结构

codex-vision-plugin/
├── .agents/plugins/marketplace.json   # Codex 插件市场清单（插件注册入口）
├── plugins/
│   └── vision/                        # vision 插件根目录
│       ├── config.example.json        # 配置模板（复制为 config.json 生效）
│       ├── .codex-plugin/plugin.json  # 插件元数据（名称/版本/能力）
│       └── skills/vision/
│           ├── SKILL.md               # skill 描述与用法
│           ├── agents/openai.yaml     # agent 接口描述
│           └── scripts/describe_image.py  # 核心识别脚本
├── README.md
├── LICENSE                            # MIT
└── .gitignore

插件加载目录说明：.agents/plugins/marketplace.json 是 Codex 市场入口，声明 vision 插件位于 ./plugins/vision；实际识别逻辑在 plugins/vision/skills/vision/。安装插件时 Codex 会按 marketplace 声明的路径加载，不要移动 plugins/vision 目录，否则插件无法被识别。

环境要求

依赖	版本要求	说明
Python	≥ 3.9	运行识别脚本
Ollama	≥ 0.3.x（推荐最新）	本地模型服务
视觉模型	qwen2.5vl:7b（约 6GB）	也可换 llava 等轻量模型
Pillow	可选（≥ 8.0）	仅用于图片压缩，不装则跳过压缩

显存最低配置：qwen2.5vl:7b 建议 6GB 以上显存（或 8GB 内存运行 CPU 版）；显存紧张可换 qwen2.5vl:3b 或 llava:7b。

安装

1. 安装 Codex 插件

codex plugin marketplace add https://github.com/rongyaozhixing/codex-vision-plugin
codex plugin add vision@codex-vision

2. 安装 Ollama 并拉取模型

# Windows（安装包自动装到 %LOCALAPPDATA%\Programs\Ollama）
ollama pull qwen2.5vl:7b

# Linux / macOS
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5vl:7b

# 显存紧张可拉轻量模型
# ollama pull llava:7b

3. （可选）配置 DashScope 兜底

# Windows PowerShell
setx DASHSCOPE_API_KEY "sk-xxxx"

# Linux / macOS
export DASHSCOPE_API_KEY="sk-xxxx"

使用方法

基本用法

python plugins/vision/skills/vision/scripts/describe_image.py --image path/to/image.png

识图档位

# code 模式：侧重提取截图/图片中的代码和文字（默认 max_tokens 1024）
python .../describe_image.py --image code_screenshot.png --mode code

# general 模式：完整画面描述（默认 max_tokens 512，也是默认档位）
python .../describe_image.py --image photo.png --mode general

切换模型（LLaVA 等任意 Ollama 多模态模型）

python .../describe_image.py --image image.png --model llava:7b
# 模型未安装时会提示：ollama pull llava:7b

云端兜底

python .../describe_image.py --provider dashscope --image image.png

自定义提示词

python .../describe_image.py --image image.png --prompt "这张图的 UI 风格是什么？"

配置（不碰源码）

复制 plugins/vision/config.example.json 为 plugins/vision/config.json 即可修改，CLI 参数优先于配置文件：

{
  "provider": "ollama",              // ollama | dashscope
  "mode": "general",                 // general | code
  "ollama": {
    "url": "http://127.0.0.1:11434", // Ollama 服务地址
    "model": "qwen2.5vl:7b",         // 默认模型
    "bin": "",                       // ollama 可执行文件路径（留空自动探测）
    "max_tokens": null               // null = 按档位默认（code 1024 / general 512）
  },
  "dashscope": {
    "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "model": "qwen-vl-max",
    "api_key_env": "DASHSCOPE_API_KEY",
    "max_tokens": 512
  },
  "image": {
    "max_side": 2048,                // 超过此像素自动压缩；0 关闭压缩
    "jpeg_quality": 85,
    "auto_cleanup_temp": true        // false 则保留压缩产生的临时文件
  }
}

Ollama 启动配置

脚本会在识别前自动检测 Ollama 服务；未启动时尝试自动拉起：

• Windows：自动查找 %LOCALAPPDATA%\Programs\Ollama\ollama.exe 等常见路径，可用 OLLAMA_BIN 环境变量或 --ollama-bin 指定
• Linux/macOS：自动查找 /usr/local/bin/ollama、/usr/bin/ollama，或 PATH 中的 ollama

手动启动：

# 默认模型目录
ollama serve

# 自定义模型目录（Windows 注意路径格式）
OLLAMA_MODELS="E:\path\to\models" ollama serve

功能演示

例 1：代码截图识别（--mode code）

python .../describe_image.py --image code_snippet.png --mode code
# 输出：完整提取截图中的代码与文字，保留缩进与符号

例 2：界面截图解析（--mode general）

python .../describe_image.py --image app_screenshot.png --mode general
# 输出：完整画面描述（界面结构、元素、文字）

常见报错排查

现象	原因	解决
Ollama binary not found	找不到 ollama 可执行文件	安装 Ollama 或设置 OLLAMA_BIN / --ollama-bin
模型 xxx 尚未安装	模型未拉取	按提示运行 ollama pull xxx
Connection refused / 连不上 11434	Ollama 服务未启动或端口被占用	确认 ollama serve 在运行；检查 --ollama-url 端口
HTTP 500: model not found	Ollama 服务与脚本端模型名不一致	运行 ollama list 查看已装模型名
DashScope 返回 401	API key 无效或过期	重新生成 DASHSCOPE_API_KEY
输出乱码（Windows）	控制台编码问题	脚本已自动强制 UTF-8；在 PowerShell 中执行 chcp 65001
识别很慢	图片过大 / 显存不足	启用压缩（max_side 调小），或换小模型

隐私说明

• 默认全本地：图片经 Ollama 在本机处理，不上传任何公网服务
• 仅当显式使用 --provider dashscope 时，图片才会发送到阿里云 DashScope
• 压缩产生的临时文件用完即删（auto_cleanup_temp，默认开启）

开源协议

本项目基于 MIT License。

• ✅ 可自由使用、修改、分发，包括商业用途
• ✅ 二次开发后无需开源你的改动
• ⚠️ 需保留原始版权声明与许可文本
• ❌ 作者不对使用后果承担任何担保责任

参与贡献

欢迎提交 Issue 与 PR：

• 🐛 Bug 报告 / 功能建议：请打开 Issues（使用模板分类：Bug / Feature / Question）
• 📦 支持新模型、新平台（Windows / Linux / macOS）