Vision Bridge

vision-bridge — Vision for non-vision LLMs

Your underlying model has no native vision capability. For anything that requires "seeing" an image, do NOT use the Read tool — call the bundled script vision-bridge.py, which asks an external vision model to "look" for you and returns text.

When to trigger

• The user shares a local image path or network image URL
• The message contains Saved attachments: listing images
• The user asks to describe, recognize, analyze, interpret an image; extract text (OCR); understand screenshots, charts, tables, QR codes, memes, captchas
• Any task that needs information from an image

Script location & modes

Script: scripts/vision-bridge.py in this skill. Requires only Python 3.9+ standard library — zero third-party dependencies (no pip install). Cross-platform: Windows / Linux / macOS / fish.

If python is unavailable on Windows, use py -3 vision-bridge.py ... instead.

Common options: --model <model>, --max-tokens <n>, --temperature <0~2>, --json (raw JSON response), config --region global|china (pin a regional base URL).

First use: configure once

Principle: the API key is only written to an environment variable — never into code, scripts, or any project file, to prevent leakage. Run check before recognizing; only guide the user when VISION_API_KEY is missing, and never ask again afterwards.

When not configured, guide the user (offer one of two options):

1. Run python vision-bridge.py check, confirm configured=false.
2. Tell the user a vision model API key is needed (default agnes, model agnes-2.5-flash); ask them to choose one way:
   • Method A (user hands the key over): ask the user to paste the API key into the chat; when received, run python vision-bridge.py config "<user key>" to persist it. Do not repeat the key in plaintext in the session afterwards.
   • Method B (user configures it themselves): send the user this command — they only replace the placeholder inside the quotes:

     python vision-bridge.py config "your-vision-api-key"
     

3. Ask the user to restart the terminal (system env vars only take effect for new processes), then verify with python vision-bridge.py check.
4. After configuration, immediately recognize the current image.

If the user already has a key and insists on pasting it, reject placeholders like sk-xxx or your-vision-api-key before persisting.

Usage

Examples:

python vision-bridge.py "D:\photos\example.png" "Describe this image"
python vision-bridge.py --url "https://example.com/a.png" "Extract the text"
python vision-bridge.py "img1.png" "img2.png" "Compare these two images"

The script: base64-encodes local images → submits all images at once → timeout/retry/error classification (401=bad key, 404=wrong model/URL, 429=rate limited) → prints text to stdout. Surface stderr error messages to the user verbatim on failure.

Regional base URLs

The default is agnes agnes-2.5-flash (free and unlimited; see the Agnes docs) via an auto-selected regional endpoint (an apihub API key works on both):

Selection priority: VISION_BASE_URL (explicit) > system language (Chinese locale → .cn, otherwise → .com) > default .com.

To pin a region explicitly (e.g. a Chinese user on an English system), use:

python vision-bridge.py config --region china "your-key"   # writes VISION_BASE_URL too
python vision-bridge.py config --region global "your-key"

To use any other OpenAI-compatible vision service:

# Windows
setx VISION_BASE_URL "https://your-provider/v1"
setx VISION_MODEL "your-vision-model"
# Linux / macOS (write to ~/.bashrc or ~/.zshrc)
export VISION_BASE_URL="https://your-provider/v1"
export VISION_MODEL="your-vision-model"

Notes

• Bilingual UI: script output auto-switches Chinese/English based on system language; force with VISION_LANG=zh or VISION_LANG=en.
• Images over 10MB trigger a warning (some APIs reject very large images).
• agnes-2.5-flash is a thinking model: recognition may take 10–90 s (script timeout is 120 s). To use a faster model, set VISION_MODEL.
• The script auto-extracts the final answer from the thinking output (when content is empty, it takes the conclusion in reasoning_content); default output is clean text, --json outputs the raw API response.
• config writes to system environment variables; the script re-reads system config, so it works in the current session immediately — but a new terminal is where each shell actually loads the variable. Restart the terminal if another program does not see it.
• Windows writes via winreg directly to the registry (not setx): supports special characters like & ^ % and has no 1024-char limit.
• config never prints the plaintext key, so it is safe to copy for the user.
• 401 = bad/expired key; 404 = wrong model or API URL; 429 = rate limited.