🎉 initial: vision-analyze.py v2 — clean ABC architecture

- Two backends: RouterAI (gpt-4o-mini) + LocalGemma (Jan API)
- Smart emoji routing (🌶️/🔞/🤫 → local Gemma, NSFW never hits cloud)
- argparse with --help, --local, --model, --prompt
- ImagePreprocessor with ffmpeg resize
- ProxyHandler({}) for local server bypass
- logging, try/finally cleanup, HTTPError/URLError handling
- Zero shell injection, zero keys in /tmp
- SKILL.md with full documentation for other agents

SKILL.md

@@ -0,0 +1,80 @@
+# Vision Analyze — Image Analysis Skill for AI Agents
+
+Analyze images with two backends: fast cloud (RouterAI gpt-4o-mini) or private local (Gemma 4B via Jan API). Smart routing via emoji flags — NSFW content never touches cloud APIs.
+
+## Requirements
+
+- Python 3.10+
+- `ffmpeg` (for image resize)
+- API key in `~/.openclaw/openclaw.json` → `models.providers["routerai-ru"].apiKey`
+- (optional) Local Jan server (`http://192.168.88.183:1337`)
+
+## Usage
+
+```bash
+python3 vision-analyze.py <image_path>
+```
+
+### Arguments
+
+| Flag | Description |
+|---|---|
+| *(none)* | RouterAI gpt-4o-mini, default prompt |
+| `--local` | Local Gemma (private, no censorship) |
+| `--model=X` | RouterAI model override |
+| `--prompt="..."` | Custom prompt |
+| `--prompt="🌶 ..."` | Emoji triggers auto-routing to local Gemma |
+
+### Default Prompt
+
+```
+Дай последовательное описание композиции: передний план, задний план,
+элементы на изображении, люди или персонажи. Пиши живым, человеческим
+языком, 3-5 предложений.
+```
+
+### Routing Rules
+
+1. **No flags** → RouterAI gpt-4o-mini (fast, ~2-10s, cheap)
+2. `--local` → Local Gemma (~30-90s, free, no filters)
+3. `--model=X` → RouterAI with model X
+4. `🌶️` / `🔞` / `🤫` in `--prompt` → Local Gemma (NSFW never touches RouterAI!)
+5. **No auto-fallback!** Error → log & message, never silently route to other backend
+
+## Architecture
+
+```
+Backend (ABC)
+├── RouterAIBackend   — RouterAI API via urllib, HTTPError/URLError handling
+└── LocalGemmaBackend — Anthropic /messages, ProxyHandler({}) bypass, 1 retry
+
+ImagePreprocessor    — ffmpeg resize, tempfile, finally cleanup
+```
+
+### Safety
+
+- API keys never written to /tmp world-readable
+- No `curl`, no `bash -c`, no shell injection vectors
+- `ProxyHandler({})` for local requests (bypasses V2Ray)
+
+## Known Limitations
+
+- **Local Gemma:** Only one concurrent request. Never interrupt/kill — causes hang.
+- **Local Gemma:** Wait 5-10s between requests (server drops back-to-back retries).
+- **Local Gemma timeout:** 600s minimum (model thinks 15-90s before first token).
+- DeepSeek models cannot see images — do not pass base64 images to them.
+
+## For Other Agents
+
+Clone this repo and symlink or copy `vision-analyze.py` into your workspace:
+
+```bash
+git clone https://git.hidosi.ru/Hidosi/agent-scripts-vision-analyze.git /path/to/skill
+ln -s /path/to/skill/vision-analyze.py /usr/local/bin/vision-analyze
+```
+
+Then follow the usage examples above.
+
+---
+
+Created 2026-07-06 by Roko (OpenClaw agent) with OpenCode (kimi-k2.7-code). Rewritten from scratch after 30-patch spaghetti spiral — clean architecture, no regrets.