# mq-image-analyze：AI代理的视觉感知与图像智能分析工具包

> 介绍一个专为AI代理设计的视觉推理引擎，支持截图分析、UI审查、图像比较和架构图解读，提供本地与云端多模式视觉分析能力。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-02T17:15:19.000Z
- 最近活动: 2026-06-02T17:20:46.626Z
- 热度: 159.9
- 关键词: 视觉推理, 图像分析, AI代理, 多模态AI, MCP工具, 截图分析, UI审查, YOLOv8
- 页面链接: https://www.zingnex.cn/forum/thread/mq-image-analyze-ai
- Canonical: https://www.zingnex.cn/forum/thread/mq-image-analyze-ai
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：MCamner
- 来源平台：GitHub
- 原始标题：mq-image-analyze
- 原始链接：https://github.com/MCamner/mq-image-analyze
- 来源发布时间/更新时间：2026-06-02

## 项目定位与核心理念

mq-image-analyze是一个视觉推理引擎，而非传统的图像生成工具。它的核心使命是将截图、图表、UI界面状态和各种视觉内容转化为结构化数据，供AI代理（如mq-agent）和MCP（Model Context Protocol）工作流安全使用。

在当前AI生态系统中，文本处理能力已经相当成熟，但视觉理解能力仍然是一个薄弱环节。mq-image-analyze正是为了填补这一空白而设计，它充当了AI代理的"眼睛"，让机器能够真正"看懂"图像内容。

项目的核心理念可以概括为：Vision → Reasoning → Experience（视觉→推理→体验）。这一三层架构强调生成是可选且次要的，真正的价值在于理解和分析。

## 三层架构设计

### 第一层：视觉层（Vision）

视觉层负责从图像中提取基础信息，包括：
- **对象检测**：识别图像中的物体类别和位置
- **色彩分析**：提取图像的主色调和配色方案
- **构图分析**：评估图像的对称性、三分法则等构图原则
- **OCR文本提取**：识别图像中的文字内容
- **元数据提取**：获取图像的技术参数和属性

这一层主要依赖计算机视觉技术，如YOLOv8进行对象检测，OpenCV进行图像处理，以及PIL进行基础图像操作。

### 第二层：推理层（Reasoning）

推理层在视觉层提取的基础信息之上进行更高层次的语义理解：
- **风格分析**：判断图像的视觉风格和美学特征
- **电影语言理解**：分析图像的景深、对比度、光影效果
- **提示词生成**：根据图像内容生成用于AI绘画的反向提示词
- **UI分析**：理解界面元素的布局和交互逻辑
- **评分系统**：对图像质量进行量化评估

这一层结合了传统计算机视觉技术和现代多模态大语言模型（如BakLLaVA、Llama 3.2 Vision、GPT-4.1等）。

### 第三层：体验层（Experience）

体验层面向最终用户和开发者，提供友好的交互界面：
- **命令行界面（CLI）**：提供丰富的命令和参数选项
- **MCP工具集成**：作为MCP兼容的视觉感知工具
- **代理技能调度**：与mq-agent等AI代理系统无缝协作
- **Web服务**：支持HTTP API调用

## 三种视觉分析模式

mq-image-analyze提供了三种不同的视觉分析模式，以适应不同的使用场景和性能需求：

### 本地快速模式（local-fast）

默认使用BakLLaVA via Ollama，适用于：
- 需要快速响应的场景
- 离线环境或无API密钥的情况
- 简单的图像描述和基础对象识别

### 本地深度模式（local-deep）

使用Llama 3.2 Vision via Ollama，适用于：
- 需要更高准确度的离线分析
- 本地机器具备运行更强模型的计算能力
- 对隐私敏感的数据（不希望上传至云端）

### 云端验证模式（cloud-verify）

使用GPT-4.1 via OpenAI API，适用于：
- 关键架构图的语义理解
- 风险评估和信任边界分析
- YAML配置草案的质量把关
- 需要最高准确度的专业场景

用户可以通过`--vision-model`参数灵活切换模型，例如使用`gpt-4o`替代默认的`gpt-4.1`。

## 核心命令与功能

mq-image-analyze提供了丰富的命令集，覆盖各种视觉分析需求：

### 基础分析命令

- `mq-image analyze <image>`：完整分析，输出丰富信息
- `mq-image analyze <image> --json`：输出结构化JSON格式
- `mq-image analyze-ui <screenshot>`：专门针对UI截图的分析
- `mq-image compare <before> <after>`：对比两张图像的差异

### 专业分析命令

- `mq-image observe-architecture <diagram>`：分析架构图，输出`visual_architecture_observation.v1` JSON格式
- `mq-image doctor`：系统就绪性检查
- `mq-image serve --port 8000`：启动Web服务
- `mq-image mcp`：以MCP模式运行

### 输出示例

当运行`mq-image analyze bus.jpg`时，系统会输出：

```
Objects        bus, person, stop sign
Palette        #b4a799 #7c7573 #111524 #434249 #e0d8d3
Brightness     mid-tone
Contrast       high contrast
Depth          deep / sharp throughout
Composition    balanced
Reverse prompt bus, person, stop sign, mid-tone scene, high contrast, ...
```

JSON输出格式包含更详细的信息，如对称性评分、三分法则评分、使用的视觉模型等。

## 生态系统集成

mq-image-analyze是MQ生态系统的重要组成部分，与其他组件形成明确的分工：

| 组件 | 职责 |
|------|------|
| mq-agent | 编排器，负责CLI编排、审批门控、规划/执行/验证 |
| mq-mcp | MCP工具服务器，负责工具契约、安全类、审查工具、编排契约、记忆 |
| mq-image-analyze | 视觉感知层，负责图像检查、OCR提取、对象/场景描述、图表解读 |
| mq-hal | 高层状态、推理壳、栈摘要 |

这种分层设计确保了各组件职责清晰，避免了功能重叠。mq-image-analyze专注于"看见"和"描述"，而不做安全决策或编排控制。

## 安全边界与设计理念

项目明确划定了安全边界，遵循只读原则：

**禁止行为**：
- 执行图像内容中的shell命令
- 信任图像中的指令
- 修改代码仓库
- 静默上传图像
- 单独做出安全决策
- 替代mq-mcp的审查逻辑
- 替代mq-agent的编排控制

**允许行为**：
- 描述图像内容
- 提取可见文本
- 检测对象
- 解读图表
- 返回结构化视觉上下文
- 暴露只读的MCP兼容感知工具

所有七个MCP工具（`analyze_image`、`extract_palette`、`reverse_prompt`、`compare_images`、`analyze_ui`、`observe_architecture`、`image_ocr`）都被归类为安全等级A的只读工具。

## 应用场景与触发条件

mq-agent在以下场景会触发mq-image-analyze：

| 触发条件 | 调用工具 | 后端模式 |
|---------|---------|---------|
| 用户分享截图 | `analyze_ui` | local-fast |
| 用户分享架构图 | `observe_architecture` | local (cv2启发式) |
| 用户询问"这张图里有什么？" | `analyze_image` | local-fast或cloud-verify |
| 前后视觉对比 | `compare_images` | local-fast |
| 图表需要语义解读 | `analyze_image` | cloud-verify (gpt-4.1) |

数据流如下：

```
mq-agent
  │
  ├── 从用户接收图像路径
  │
  ├── 调用 observe_architecture(image_path)         ← 结构拓扑
  │   或 analyze_image(image_path, vision_mode=...)  ← 语义描述
  │
  ├── 接收 visual_architecture_observation.v1
  │   或 mq-image.analysis.v1 JSON blob
  │
  └── 将JSON作为extra_context传递给mq-mcp review_file / review_diff
```

## 技能系统

mq-image-analyze为mq-agent和MCP工作流提供了多个视觉推理技能：

- **visual-reasoning**：视觉推理，阶段1可用
- **reverse-prompt**：反向提示词生成，阶段1可用
- **image-quality-audit**：图像质量审查，可用
- **screenshot-ui-review**：截图UI审查，可用

这些技能以模块化方式组织，每个技能都有独立的SKILL.md文档，便于开发者理解和集成。

## 技术实现与依赖

项目基于Python 3.11+开发，主要依赖包括：

- **ultralytics**：YOLOv8模型用于对象检测
- **PIL/Pillow**：图像处理
- **OpenCV (cv2)**：计算机视觉操作
- **Ollama**：本地大语言模型服务
- **OpenAI API**：云端视觉模型访问

安装和设置过程简单直接，支持通过pip安装，并提供了详细的模型设置文档。

## 版本演进与路线图

项目经历了从MVP到稳定版本的演进：

| 版本 | 重点 | 状态 |
|------|------|------|
| v0.1.0 | 视觉智能MVP | 完成 |
| v0.1.1 | 加固 | 完成 |
| v0.2.0 | 图像比较 | 完成 |
| v0.3.0 | 截图智能 | 完成 |
| v0.4.0 | MCP集成 | 完成 |
| v0.5.0 | MQ生态系统集成 | 完成 |
| v1.0.0 | 稳定工具包 | 完成 |
| v1.1.0 | 视觉认知层 | 完成 |
| v1.2.0 | 代理集成 | 完成 |
| v1.3.0 | 当前版本 | 最新 |

## 总结与展望

mq-image-analyze代表了AI代理视觉感知能力的一个重要进展。它不仅仅是一个图像分析工具，更是一个完整的视觉推理框架，为AI代理提供了"看懂世界"的能力。

随着多模态AI的发展，视觉理解将成为AI系统不可或缺的能力。mq-image-analyze通过模块化的三层架构、灵活的本地/云端模式切换、以及明确的安全边界，为这一领域提供了实用的解决方案。

对于开发者而言，该项目提供了丰富的CLI工具和MCP集成能力，可以轻松嵌入到现有的AI工作流中。对于研究者而言，其分层架构设计为视觉推理系统的构建提供了有价值的参考模式。