# Multimodal Perception（视觉感知 MCP + Codex Skill）

让 Codex 背后的文本模型拥有"视觉感知能力"：视觉模型作为视觉专家提供观察报告，
主文本模型结合视觉结果完成最终分析、推理和决策。

## 架构

```text
用户 → Codex + 主文本模型
        → 判断当前推理是否需要视觉信息
        → 需要时调用 analyze_image(image, question) MCP
        → 视觉专家返回观察报告（文本或 JSON）
        → 主模型结合视觉结果继续推理
```

## 文件结构

```text
vision-mcp/
├── server.py        # FastMCP 入口与 analyze_image(image, question)
├── model_client.py  # 单一 OpenAI-compatible 视觉模型客户端
├── config.py        # 配置加载（环境变量 / .env）
├── requirements.txt
└── README.md
```

## 配置

复制 `.env.example` 为 `.env` 并填写视觉模型 API Key：

```dotenv
QWEN_API_KEY=sk-...
```

默认使用 Qwen3-VL（`qwen3-vl-flash`）。可通过环境变量覆盖端点与模型：
`VISION_BASE_URL`、`VISION_MODEL`、`VISION_PROVIDER`、`VISION_TIMEOUT` 等。

## MCP 工具

```text
analyze_image(
    image: str,      # 本地路径 / http(s) URL / base64 / data URI / PDF
    question: str    # 主模型希望从图中了解什么
)
```

- 简单问题（如"这是什么"）→ 返回简洁文本描述。
- 结构/技术分析（控制框图、电路、图表、工程图等）→ 返回 JSON 视觉报告：
  `observation` / `key_elements` / `preliminary_analysis` / `possible_issues` / `uncertainty`。

## Skill

`skills/multimodal-perception/SKILL.md`：告诉主模型"你不是纯文本 Agent，
任务依赖视觉信息时调用视觉能力，不要猜测；视觉报告只提供观察与初步判断，
最终推理由主模型完成"。

## Codex Desktop 挂载

```toml
[mcp_servers.multimodal_router]
command = 'E:\csprogram\vision-mcp\.venv\Scripts\python.exe'
args = [ 'E:\csprogram\vision-mcp\server.py' ]
startup_timeout_sec = 30

[mcp_servers.multimodal_router.env]
PYTHONUTF8 = '1'
PYTHONIOENCODING = 'utf-8'
```

修改配置或代码后需重启 Codex Desktop，并新建会话生效。