vision-bridge

name	vision-bridge
description	Visual collaboration bridge — routes images to an external vision model when the primary text model cannot process images. Returns structured analysis for the text model to review and act on. Two-stage workflow: vision model analyzes → text model reviews and executes.

Vision Bridge

When the primary text model (e.g., DeepSeek, any text-only LLM) cannot view images, automatically delegate image analysis to an external vision model and return the result for continued conversation and execution.

Trigger Conditions

User-initiated (keyword matching):

• Chinese: 视觉协作、看图、分析图像、查看监控、图像分析、图片、看一下、帮我看看
• English: vision bridge, view image, analyze image, image analysis, visual collaboration
• User explicitly requests analysis of an image file or a directory of images

Auto-triggered (capability detection):

• Primary model attempts to read an image file and receives [Unsupported Image]
• Primary model recognizes it cannot handle multimodal input
• Task requires visual analysis that the primary model cannot perform

Architecture

┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│  Text model  │────▶│  vision_bridge   │────▶│ Vision model │
│ (text-only)  │     │     .py script   │     │ (multimodal) │
│              │◀────│                  │◀────│              │
│ Review+act   │     │  text report     │     │ Deep analysis│
└──────────────┘     └─────────────────┘     └──────────────┘

Two-stage workflow:

1. Vision model: image → structured visual analysis → issue identification → recommendations (visual layer only, no code suggestions)
2. Text model: review analysis → map to code/actions → execute changes → verify

Vision model handles pixel-level reasoning; text model handles code-level execution.

Setup

Set environment variables before use:

Environment Variables

Variable	Required	Description
VISION_API_KEY	Yes	API key for the vision model
VISION_BASE_URL	No	API endpoint (default: MiMo V2.5 CN)
VISION_MODEL	No	Model name (default: mimo-v2.5)
VISION_DOMAIN	No	Optional domain context prepended to every analysis prompt

Supported Vision Models

Any Anthropic Messages API-compatible multimodal service:

Model	Base URL
MiMo V2.5	https://token-plan-sgp.xiaomimimo.com/anthropic/v1/messages
Anthropic Claude	https://api.anthropic.com/v1/messages
Custom	(your URL)

Domain Context (optional)

For domain-specific image analysis, set VISION_DOMAIN or use --domain:

# Persistent (env var)
export VISION_DOMAIN="You are analyzing medical X-ray images. Look for fractures, lesions, and abnormalities."

# One-off (flag)
python vision_bridge.py xray.png --domain "You are analyzing medical X-ray images."

Agent Execution Reference

The script lives at scripts/vision_bridge.py within this skill directory. Users interact via natural language — the agent runs these commands internally.

1. Deep analysis (default)

python scripts/vision_bridge.py <image_path>

Output: Visual Observation → Issue Identification → Pattern Analysis → Recommendations

2. Quick description

python scripts/vision_bridge.py <image_path> --brief

3. Custom question

python scripts/vision_bridge.py <image_path> "What anomalies are visible?"

4. Show model reasoning

python scripts/vision_bridge.py <image_path> --verbose

5. Inject domain context

python scripts/vision_bridge.py <image_path> --domain "Analyzing satellite imagery. Focus on cloud cover, terrain, and water bodies."

6. Inject conversation context (recommended)

Generated by the text model from the current conversation; passed as the system field to the vision model:

python scripts/vision_bridge.py <image_path> --context "Mobile UI screenshot. Observe: layout misalignment, text truncation, overlapping components."

Vision Context Guidance Rules

Before calling the vision model, generate a short neutral --context value based on the current conversation.

Format

[Domain/scene, ≤10 words]. Observe: [focus1], [focus2], [focus3 — noun phrases].

Total length ≤ 60 words.

Forbidden words

Forbidden (EN)	Forbidden (中文)	Use instead
expect to see / want to see / hope to find	期望/想要/希望看到	List observation nouns directly
should have / ought to / probably has	应该/应当有/可能有	Remove the presupposition
I think / I believe / I assume	我认为/我觉得	Remove subjective markers
please focus on what I care about	请重点看我关心的	Name the specific noun directly

Example

❌ Wrong: This is an app screenshot, I expect buttons to be aligned and text should not be cut off
✅ Correct: Mobile UI screenshot. Observe: button alignment, text truncation, overlapping component regions.

Workflow Example

User: Check what error screenshots/error.png is showing

Text model: [Image request detected — activating vision-bridge]
            → python scripts/vision_bridge.py screenshots/error.png \
                --context "Application error screenshot. Observe: error type, message text, stack trace."
            → Vision model returns: red dialog, title "Connection Refused", port 5432...

Text model: [Reviews analysis]
            "Error is PostgreSQL connection refused on port 5432.
             Check: Is PostgreSQL running? Firewall rules? Connection string config?"

Text model: [Executes fix]
            → Inspect docker-compose.yml postgres config
            → Verify port in connection string

Vision Model Scope

Should do:

• Describe pixel-level visual phenomena
• Identify issues, anomalies, key information
• Analyze trends and patterns
• Provide visual-layer improvement suggestions

Should NOT do:

• Suggest code changes (no knowledge of the codebase)
• Execute operations (no execution environment)
• Make decisions requiring business context

These boundaries ensure the vision model leverages its reasoning strengths while avoiding uninformed suggestions.

Notes

• Base64-encoded images increase payload size — keep single images under 10 MB
• Vision model calls typically take 10–60 seconds
• For batch analysis, loop calls via shell
• Analysis quality depends on the vision model — use a stronger model for critical tasks
• Never hardcode the API key; always use environment variables