opencodecli-mimo-image-describe

English version: README_EN.md

通过 opencode CLI 调用内置多模态模型（默认 opencode/mimo-v2.5-free）识别本地图片。跨平台（Windows / macOS / Linux）、跨 agent 可用。

一个 Skill（技能）+ 一个 Python wrapper 脚本，即可让任意支持调命令的 agent 获得"看图"能力。

项目初衷

当前市面上的大模型可以分为两类：一类是综合能力出色，但不具备原生多模态能力的模型（例如 deepseek-v4-flash）；另一类是具备多模态能力，但综合逻辑表现往往逊色一些。

很多优秀文本模型明明能写出高质量的代码与内容，却因为"看不了图"，在面对图片输入时直接失效——识别、描述、审图这些基础需求全都无法满足。

这个 skill 的初衷就是：给没有多模态能力的大模型补上一双"眼睛"，让它们也能完成图片识别与描述。

实现思路很简单——不改造模型本身，而是通过外部桥接：

• 使用者仍以文本模型为主力（保持它最强的逻辑与生成能力）；
• 遇到需要读图的任务时，由本 skill 调用 opencode 内置的多模态模型代为读取图片，返回文字描述；
• 把结果作为"线索"交还给文本模型，让它在不改变身份、不引入视觉能力的前提下，继续完成后续任务。

为什么选择 opencode CLI

要实现上面的"桥接"，需要一个能稳定调用多模态模型的外部通道。之所以选 opencode CLI，理由很直接：

• 开源项目：代码完全开放，可审计、可二次开发，不依赖某个封闭平台的稳定性。
• 配置简单：安装即可用，模型、认证等都走 opencode 已有的统一配置，无需为多模态能力单独搭一套环境。
• 能直接调用：提供 opencode run 命令行，一条命令即可指定模型、传入提示词和图片文件，非常适合脚本化桥接。
• 有符合需求的免费模型（至少目前有）：内置 opencode/mimo-v2.5-free 免费多模态模型，本 skill 默认即可开箱使用，无需额外付费或申请。

特性

• 开箱即用：默认使用 opencode 内置多模态模型 opencode/mimo-v2.5-free，安装后即可用。
• 模型可换：通过环境变量 OPENCODE_MIMO_MODEL 指定其它多模态模型。
• 复用现有认证：走 opencode 已配置的认证，无需额外 API key。
• 跨平台：Windows / macOS / Linux 全覆盖，自动探测 opencode 可执行文件（PATH、常见安装位置、OPENCODE_BIN 环境变量）。
• 跨 agent：不依赖任何特定 agent 的运行时，核心是 opencode run 命令行 + Python 脚本，opencode / Claude Code / Cursor AI / 自研 agent 均可调用。
• 易安装：复制目录即可用，无需 npm 包、无需构建。
• 批量模式：--build 一次识别多张图片，输出 JSON 描述清单。
• 输出净化：自动清除 ANSI 控制字符、PowerShell 报错外壳、opencode 尾部提示。

快速开始

# 1. 确认 opencode 已安装
opencode --version

# 2. 单张图片识别（默认提示词，默认用内置模型 opencode/mimo-v2.5-free）
python scripts/describe_image.py /path/to/photo.jpg

# 3. 单张图片 + 自定义提示词
python scripts/describe_image.py /path/to/photo.jpg "这张图的主体是什么？画面里有没有文字？"

# 4. 批量生成描述清单
python scripts/describe_image.py --build descriptions.json /path/to/a.jpg /path/to/b.jpg

命令行说明：见 docs/USAGE.md。

安装

• 安装为 skill 供 opencode / Claude Code / Cursor 等 agent 自动发现：见 docs/INSTALL.md。
• 单纯当成命令行工具用：把 scripts/ 目录放进 PATH 即可。

原理

wrapper 实际执行：

opencode run -m opencode/mimo-v2.5-free "<提示词>" -f "<图片绝对路径>"

三条铁律（踩坑总结）：

1. 提示词必须在 -f 之前。-f 会把其后所有位置参数都当作文件路径。
2. 图片路径用绝对路径。
3. 输出含 ANSI 控制字符，请用 wrapper 脚本调用以自动清理。

详见 docs/USAGE.md。

配置

环境变量	作用	默认值
OPENCODE_MIMO_MODEL	指定 opencode 可用的多模态模型 ID	opencode/mimo-v2.5-free
OPENCODE_BIN	显式指定 opencode 可执行文件完整路径	自动探测
MIMO_INTERVAL	批量模式每张图之间的等待秒数，规避免费模型频率限流	4（设为 0 关闭）

目录结构

opencodecli-mimo-image-describe/
├── SKILL.md              # Skill 定义（agent 发现入口）
├── scripts/
│   └── describe_image.py # 跨平台 wrapper：识别单张/批量图片
├── docs/
│   ├── INSTALL.md        # 各操作系统 + 各 agent 安装指南
│   ├── USAGE.md          # 用法详解与示例
│   └── AGENTS.md         # 跨 agent 适配说明
├── LICENSE
├── CHANGELOG.md
└── README.md

许可

MIT