mimo2codex 0.1.15 → 0.1.17

package/doc/mimoskill.md

@@ -0,0 +1,295 @@
+# mimoskill · Detailed Guide
+
+> English · [中文](./mimoskill.zh.md)
+>
+> Back to: [README English](../README.md) · [README 中文](../README.zh.md)
+
+`mimoskill/` is a bundle of helper scripts + reference docs at the project root. It exists because some things MiMo / DeepSeek / most chat-only LLMs can't natively do (image generation, image understanding when the chat model is text-only, …), and Codex hardcodes a few capability assumptions on the client side that the proxy layer can't override.
+
+The proxy and mimoskill are **completely independent**: mimoskill works without `mimo2codex` running, and mimo2codex works without mimoskill. They compose by **convention**: when the proxy detects a capability gap it leaves a placeholder text in the message that points the LLM at the right `mimoskill/scripts/*.py` script.
+
+## When does it trigger?
+
+> Short answer: **"the chat model does what it can; mimoskill fills the gap."**
+
+| Capability | Chat model can do it | Chat model CAN'T do it |
+|---|---|---|
+| Read / OCR / 识图 an image | proxy forwards the image to the model directly; **mimoskill not triggered** | proxy strips the image and inserts `[N image attachment(s) omitted: … python3 mimoskill/scripts/ocr.py <path> …]`; the LLM reads that placeholder + AGENTS.md and **runs `ocr.py`** |
+| Generate an image | no mainstream chat model has native image-gen | **mimoskill always triggers** — `scripts/generate_image.py` or `scripts/generate_pet.py` |
+| Web search | proxy forwards Codex's `web_search` to MiMo's builtin on `sk-*` (pay-as-you-go) keys; auto-skipped on `tp-*` (token-plan) and DeepSeek | `scripts/mimo_chat.py` follows the same rule — auto-enables web search on MiMo `sk-*`, skips on `tp-*` / pollinations. No flag needed. |
+| TTS / ASR | not exposed in Codex | `scripts/mimo_chat.py` direct call to MiMo's separate endpoints |
+
+The triggering **happens in the LLM**, not in the proxy. The proxy only does protocol translation + minimal compatibility fixups (image stripping, placeholder injection). Codex reads [AGENTS.md](../AGENTS.md) and [mimoskill/SKILL.md](../mimoskill/SKILL.md), notices the placeholder or the user's intent, and decides which script to invoke. The script is an independent subprocess that **bypasses the proxy entirely** — OCR talks to MiMo or pollinations directly, image-gen talks to pollinations or OpenAI directly, etc.
+
+## Layout
+
+```
+mimoskill/
+├── SKILL.md                   # skill manifest the LLM reads — trigger rules, decision tree
+├── scripts/
+│   ├── mimo_chat.py           # direct chat / vision / web-search call to MiMo (stdlib-only)
+│   ├── ocr.py                 # OCR / image recognition. Mimo or free pollinations
+│   ├── generate_image.py      # general image generation (any style / subject)
+│   ├── generate_pet.py        # Codex pet generation (chibi-sticker style)
+│   └── install_pet.sh         # install generated PNG into Codex's pet directory
+├── references/
+│   ├── models.md              # MiMo capability matrix + field quirks
+│   ├── ocr_workflow.md        # full OCR mode reference, exit codes, JSON shape
+│   └── pet_workflow.md        # single-image vs animated bundle generation
+└── assets/
+    └── pet_prompt_template.md # tuned chibi-sticker prompt templates
+```
+
+## Scripts in depth
+
+### `scripts/mimo_chat.py` — chat / vision (no key required)
+
+Stdlib-only Python script for one-shot or streaming chat. Two engines, same `--engine auto|mimo|pollinations` pattern as `ocr.py`:
+
+| Engine | Needs key | Notes |
+|---|---|---|
+| `mimo` | `MIMO_API_KEY` | Best quality. Web search auto-enabled on `sk-*` keys (no flag needed). TTS/ASR also MiMo-only. |
+| `pollinations` | **NO** | Free public endpoint at `text.pollinations.ai`. Text + vision work. No web search / TTS / ASR. |
+
+Auto resolution: `mimo` if `MIMO_API_KEY` set, else `pollinations`. So this script now works **without any key** for text and vision chat.
+
+```bash
+# Zero-setup — uses pollinations fallback
+python3 mimoskill/scripts/mimo_chat.py "tell me a joke"
+python3 mimoskill/scripts/mimo_chat.py --image https://x/y.png "describe this"
+
+# Best quality + MiMo native features (web search auto-on with sk-*, TTS, ASR)
+export MIMO_API_KEY=sk-xxxxxxxxxxxxxxxx
+python3 mimoskill/scripts/mimo_chat.py "今天上海天气"   # web_search auto-included
+python3 mimoskill/scripts/mimo_chat.py --model mimo-v2.5-pro --max-tokens 8000 --stream "long answer please"
+```
+
+For the mimo engine, the script handles MiMo's quirks transparently: `max_completion_tokens` (not `max_tokens`), the required `text` part next to `image_url`, `reasoning_content` round-tripping for multi-turn, web search plugin invocation.
+
+| Flag | Notes |
+|---|---|
+| `--engine` | `auto` / `mimo` / `pollinations` (default auto) |
+| `--model` | default `mimo-v2.5-pro` (mimo engine). For vision use `mimo-v2.5` / `mimo-v2-omni` |
+| `--pollinations-model` | default `openai` (vision-capable). Alternatives: `openai-large`, `openai-fast` |
+| `--image URL` | attach image. Auto-bumps to vision-capable model |
+| `--stream` | SSE streaming |
+| `--max-tokens N` | maps to `max_completion_tokens` on mimo, `max_tokens` on pollinations |
+| `--temperature F` | default 0.7 |
+
+### `scripts/ocr.py` — OCR / image recognition
+
+OCR fallback for when the chat model can't see images. **Two engines** (`--engine auto` picks):
+
+| Engine | Needs key | Quality | Notes |
+|---|---|---|---|
+| `mimo` | `MIMO_API_KEY` | best | Calls `mimo-v2.5` (the vision model) regardless of the chat model in use |
+| `pollinations` | **NO** | decent | Free public endpoint at `text.pollinations.ai`. Rate-limited but no signup |
+
+Auto resolution: `mimo` if `MIMO_API_KEY` is set, else `pollinations`. So users with **only a DeepSeek key** (or no key at all) still get OCR with zero setup.
+
+```bash
+# Zero-setup — uses pollinations fallback when MIMO_API_KEY is unset
+python3 mimoskill/scripts/ocr.py path/to/image.png
+
+# Best quality — set MiMo key
+export MIMO_API_KEY=sk-xxxx
+python3 mimoskill/scripts/ocr.py path/to/image.png   # auto -> mimo
+
+# Force the free engine even when you have a MiMo key (save quota)
+python3 mimoskill/scripts/ocr.py --engine pollinations form.png
+
+# Force MiMo — errors out if MIMO_API_KEY is not set (no silent fallback)
+python3 mimoskill/scripts/ocr.py --engine mimo form.png
+```
+
+Four output modes:
+
+| `--mode` | Output |
+|---|---|
+| `text` (default) | verbatim OCR — line breaks + reading order preserved |
+| `describe` | 2-4 sentence description |
+| `structured` | single JSON object: `text` / `language` / `regions[]` / `summary` |
+| `markdown` | re-render the image as GitHub-flavored Markdown |
+
+Input forms (positional, 0+ args):
+- Local path: `./scan.png`, `C:\foo.jpg`
+- HTTP(S) URL: forwarded as-is
+- `data:image/...;base64,…`: forwarded as-is
+- `-` or piped stdin: read one image's bytes from stdin
+
+Magic-byte MIME sniffing (not file extension): PNG / JPEG / GIF / WebP / BMP. Multi-image positional args batch into one upstream call.
+
+> Full reference: [mimoskill/references/ocr_workflow.md](../mimoskill/references/ocr_workflow.md) (modes, exit codes, JSON shape, lang/prompt knobs, pollinations specifics).
+
+### `scripts/generate_image.py` — general image generation
+
+Thin wrapper over `generate_pet.py` minus the chibi-pet prompt boilerplate, with an optional `--style` for common looks. Same providers, same env vars, same auto-fallback strategy.
+
+```bash
+# Free — auto picks pollinations when no OpenAI key
+python3 mimoskill/scripts/generate_image.py --prompt "japanese garden, watercolor, dawn" --out garden.png
+
+# Best quality — set OpenAI key
+export PET_OPENAI_API_KEY=sk-real-openai-key
+python3 mimoskill/scripts/generate_image.py --prompt "..." --out art.png  # auto -> gpt-image-1
+
+# Common style presets
+python3 mimoskill/scripts/generate_image.py --style anime --prompt "shrine at dusk" --out shrine.png
+```
+
+| `--provider` | Backend |
+|---|---|
+| `auto` (default) | `gpt-image-1` if `PET_OPENAI_API_KEY` set, else `pollinations` |
+| `pollinations` | Free, no key |
+| `gpt-image-1` | OpenAI's official image gen — best quality |
+| `replicate` | Replicate API (any model) |
+| `local-sd` | Local Stable Diffusion |
+
+> `PET_OPENAI_API_KEY` is intentionally **separate from `MIMO_API_KEY` and `OPENAI_API_KEY`** — it's used only for image generation, so leaking it (or just not having one) doesn't affect anything else.
+
+### `scripts/generate_pet.py` — Codex pet generation
+
+Same backends as `generate_image.py`, but with a tuned chibi-sticker prompt built around `--description`. Outputs a PNG sized + framed for Codex's pet picker.
+
+```bash
+# Single static pet (free)
+python3 mimoskill/scripts/generate_pet.py --description "chibi shiba coder" --out pet.png
+
+# Animated multi-state bundle (idle / thinking / typing / sleeping)
+python3 mimoskill/scripts/generate_pet.py --description "chibi cat" --bundle ./shiba/
+```
+
+Prompt templates live in [mimoskill/assets/pet_prompt_template.md](../mimoskill/assets/pet_prompt_template.md). Full workflow in [mimoskill/references/pet_workflow.md](../mimoskill/references/pet_workflow.md).
+
+### `scripts/install_pet.sh` — install pet into Codex
+
+Probes macOS / Linux / Windows for the right pet directory and copies the PNG (or bundle) there. Works around Codex's hardcoded pet paths.
+
+```bash
+bash mimoskill/scripts/install_pet.sh pet.png shiba
+# Then fully quit + relaunch Codex (system tray → Quit, not just close window)
+```
+
+## Three ways to use it
+
+### 1. Direct invocation (any user, no setup)
+
+```bash
+python3 mimoskill/scripts/mimo_chat.py "..."
+python3 mimoskill/scripts/ocr.py invoice.png        # works with no key, free pollinations
+python3 mimoskill/scripts/generate_image.py --prompt "..."
+```
+
+No skill registration required — these are standard Python scripts (stdlib-only, no `pip install` step).
+
+### 2. As a Claude Code skill
+
+Symlink the directory into `~/.claude/skills/`:
+
+```bash
+ln -s "$(pwd)/mimoskill" ~/.claude/skills/mimoskill
+```
+
+Claude reads [SKILL.md](../mimoskill/SKILL.md) and automatically routes relevant requests ("generate a pet from this image", "read the text from this screenshot", "MiMo TTS this paragraph") to the right scripts.
+
+### 3. As a Codex agent guide
+
+Already wired via [AGENTS.md](../AGENTS.md) at the repo root. Codex reads it on each session and routes image-gen / pet / OCR tasks to mimoskill scripts — it **won't** try to `pip install openai` or call OpenAI's image_gen tool when the active backend is MiMo / DeepSeek / Qwen / any non-OpenAI provider.
+
+## Environment variables
+
+| Var | Used by | Notes |
+|---|---|---|
+| `MIMO_API_KEY` | `mimo_chat.py`, `ocr.py` (engine=mimo / auto when set) | MiMo Chat / vision key. **Optional** for both scripts — they fall back to free pollinations when unset |
+| `MIMO_CHAT_ENGINE` | `mimo_chat.py` | `auto` / `mimo` / `pollinations` — same as `--engine` |
+| `MIMO_BASE_URL` | `mimo_chat.py`, `ocr.py` | default `https://api.xiaomimimo.com/v1` |
+| `MIMO_MODEL` / `MIMO_OCR_MODEL` | `ocr.py` model auto-pick | used when `--model` not passed and vision-capable |
+| `MIMO_OCR_ENGINE` | `ocr.py` | `auto` / `mimo` / `pollinations` — same as `--engine` flag |
+| `POLLINATIONS_MODEL` | `ocr.py` | default `openai` (vision-capable). Alternatives: `openai-large`, `openai-fast` |
+| `PET_OPENAI_API_KEY` | `generate_pet.py`, `generate_image.py` | separate from `MIMO_API_KEY` / `OPENAI_API_KEY`; used only for image gen |
+| `REPLICATE_API_TOKEN` | `generate_*.py --provider replicate` | required only when using Replicate backend |
+
+## Common recipes
+
+### Read text from an image, then summarize via the active chat model
+
+```bash
+TEXT=$(python3 mimoskill/scripts/ocr.py invoice.png)
+python3 mimoskill/scripts/mimo_chat.py "Summarize this invoice:\n$TEXT"
+```
+
+Or inside Codex: just paste the image. The proxy strips it, leaves a placeholder pointing at `ocr.py`, Codex runs the script and feeds the text back into the conversation — no manual step.
+
+### Generate a `/hatch` replacement pet (works without OpenAI key)
+
+```bash
+python3 mimoskill/scripts/generate_pet.py --description "chibi shiba coder" --out pet.png
+bash mimoskill/scripts/install_pet.sh pet.png shiba
+# Fully quit + relaunch Codex, pick the new pet from the picker
+```
+
+For higher quality, set `PET_OPENAI_API_KEY=sk-real-openai-key` and `auto` switches to `gpt-image-1`.
+
+### Structured OCR + JSON parse
+
+```bash
+JSON=$(python3 mimoskill/scripts/ocr.py --mode structured invoice.png)
+echo "$JSON" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['summary'])"
+```
+
+### Multi-image batch OCR (one billable call)
+
+```bash
+python3 mimoskill/scripts/ocr.py page1.png page2.png page3.png
+```
+
+All images go in a **single** upstream call; the model can cross-reference (e.g. ID front + back). Output is a single text body in reading order across the images.
+
+## Troubleshooting
+
+<details>
+<summary><b><code>MIMO_API_KEY</code> is not set</b> — ocr.py exits 3</summary>
+
+You explicitly passed `--engine mimo`. Either drop the flag (`auto` will fall back to pollinations) or set the key:
+
+```bash
+export MIMO_API_KEY=sk-xxxx
+python3 mimoskill/scripts/ocr.py form.png
+```
+
+</details>
+
+<details>
+<summary><b>Pollinations returns 429 / rate limit</b></summary>
+
+You hit per-IP rate limits. Either wait + retry, or switch to `--engine mimo` if you have a MiMo key.
+
+</details>
+
+<details>
+<summary><b>Codex shows <code>image_gen tool not available</code> when running /hatch</b></summary>
+
+Codex's `/hatch` is hardcoded to call OpenAI's `image_gen` tool client-side. The proxy can't intercept that. Use `generate_pet.py` instead — see "Generate a /hatch replacement pet" above.
+
+</details>
+
+<details>
+<summary><b><code>pip install openai</code> errors / Codex tries to install openai</b></summary>
+
+That's Codex trying to fall back to the openai Python SDK for image generation. [AGENTS.md](../AGENTS.md) is wired to prevent this — make sure it's at the repo root and the Codex session has read it (start fresh session if you edited AGENTS.md mid-conversation).
+
+</details>
+
+<details>
+<summary><b>Tool returned an image but my model can't see images in tool output</b></summary>
+
+This is by design. Chat Completions `tool` role only accepts string content — image content parts in `function_call_output` are flattened to `[N image attachment(s) omitted from tool output: ...]` placeholders (see `toolOutputToString` in [src/translate/reqToChat.ts](../src/translate/reqToChat.ts)). To feed an image back to the LLM, have the tool save it to disk and return a file path, then re-attach as a user message — at which point the OCR fallback kicks in if the chat model is non-vision.
+
+</details>
+
+## Design notes
+
+- **No `pip install` step.** Every script is stdlib-only. This avoids dependency drift and lets the scripts run on bare Python ≥ 3.8 anywhere.
+- **Network operations are explicit.** No silent retries to alternate endpoints. If you ask for MiMo and there's no key, you get a clear error — not a silent fallback that masks the misconfiguration.
+- **The proxy and mimoskill never call each other.** They're separate processes connected only by `AGENTS.md` / `SKILL.md` conventions. This makes both halves independently testable and replaceable.
+- **Pollinations is the no-key escape hatch.** Used as the free fallback in `ocr.py` (vision), `generate_pet.py` (image gen), `generate_image.py` (image gen). Rate-limited but always available. The project treats it as a first-class option, not a degraded mode.

package/doc/mimoskill.zh.md

@@ -0,0 +1,295 @@
+# mimoskill · 详细介绍
+
+> [English](./mimoskill.md) · 中文
+>
+> 回到：[README English](../README.md) · [README 中文](../README.zh.md)
+
+`mimoskill/` 是仓库根目录下一捆**辅助脚本 + 参考文档**。它存在的原因是有些事 MiMo / DeepSeek / 大多数纯文本 LLM 原生做不了（图像生成、纯文本模型看图、…），而 Codex 在客户端硬编码了一些能力假设，代理层压根改不动。
+
+代理（mimo2codex）和 mimoskill **完全独立**：不跑 mimo2codex 也能用 mimoskill，反之亦然。两者通过**约定**协作：代理检测到能力缺口时，会在消息里塞占位文本，指向对应的 `mimoskill/scripts/*.py`。
+
+## 什么时候会触发？
+
+> 一句话：**"模型能做的事 proxy 透传，模型做不了的事 mimoskill 兜底。"**
+
+| 能力 | 当前 chat 模型能做 | 当前 chat 模型做不了 |
+|---|---|---|
+| 看图 / OCR / 识图 | proxy 透传图片给模型；**mimoskill 不触发** | proxy 剥掉图片、塞 `[N image attachment(s) omitted: … python3 mimoskill/scripts/ocr.py <path> …]` 占位文本；LLM 读到占位 + AGENTS.md 后 **去跑 `ocr.py`** |
+| 图像生成 | 没有任何主流 chat 模型自带 image-gen | **mimoskill 永远触发** —— `scripts/generate_image.py` 或 `scripts/generate_pet.py` |
+| 联网搜索 | proxy 在 MiMo `sk-*`（按量）key 下把 Codex 的 `web_search` 翻译成 MiMo 内置的；`tp-*`（套餐）key 与 DeepSeek 自动跳过 | `scripts/mimo_chat.py` 遵循同样规则 —— MiMo `sk-*` 自动启用，`tp-*` / pollinations 跳过。**无需参数** |
+| TTS / ASR | Codex 没接 | `scripts/mimo_chat.py` 直接调 MiMo 的独立端点 |
+
+触发**发生在 LLM 这一层**，不在 proxy 层。proxy 只做协议翻译 + 最小兼容性修整（剥图、塞占位文本）。Codex 读 [AGENTS.md](../AGENTS.md) 和 [mimoskill/SKILL.md](../mimoskill/SKILL.md)，看到占位文本或者用户意图后，自己决定调哪个脚本。脚本是独立子进程，**完全绕开 proxy** —— OCR 直接打 MiMo 或 pollinations，出图直接打 pollinations 或 OpenAI，等等。
+
+## 目录结构
+
+```
+mimoskill/
+├── SKILL.md                   # 给 LLM 看的 skill 清单 —— 触发规则 + 决策树
+├── scripts/
+│   ├── mimo_chat.py           # 直接调 MiMo 聊天 / 视觉 / 联网搜索（纯标准库）
+│   ├── ocr.py                 # OCR / 识图。MiMo 或免费 pollinations
+│   ├── generate_image.py      # 通用图像生成（任意风格 / 主题）
+│   ├── generate_pet.py        # Codex 宠物生成（chibi 贴纸风）
+│   └── install_pet.sh         # 把生成的 PNG 装到 Codex 的宠物目录
+├── references/
+│   ├── models.md              # MiMo 能力矩阵 + 字段坑
+│   ├── ocr_workflow.md        # 完整 OCR 模式参考、退出码、JSON 结构
+│   └── pet_workflow.md        # 单图 vs 多状态动画 bundle
+└── assets/
+    └── pet_prompt_template.md # 调好的 chibi 贴纸提示词模板
+```
+
+## 脚本详解
+
+### `scripts/mimo_chat.py` —— 聊天 / 视觉（无 key 也能用）
+
+纯标准库 Python 脚本，单轮或流式聊天。两个引擎，跟 `ocr.py` 是同一套 `--engine auto|mimo|pollinations`：
+
+| 引擎 | 需要 key | 备注 |
+|---|---|---|
+| `mimo` | 需要 `MIMO_API_KEY` | 最佳质量。`sk-*` key 自动启用 web_search（无需参数），TTS / ASR 也只能用这个 |
+| `pollinations` | **不需要** | 免费公共端点 `text.pollinations.ai`。文本 + 视觉可用，联网搜索 / TTS / ASR 不可用 |
+
+auto 选择：有 `MIMO_API_KEY` 用 mimo，否则 pollinations。**这个脚本现在不依赖任何 key**（纯文本 + 视觉场景）。
+
+```bash
+# 零配置 —— 自动走 pollinations 兜底
+python3 mimoskill/scripts/mimo_chat.py "讲个笑话"
+python3 mimoskill/scripts/mimo_chat.py --image https://x/y.png "描述这张图"
+
+# 最佳质量 + MiMo 原生能力（sk-* key 自动开 web_search，TTS、ASR）
+export MIMO_API_KEY=sk-xxxxxxxxxxxxxxxx
+python3 mimoskill/scripts/mimo_chat.py "今天上海天气"   # 自动带 web_search
+python3 mimoskill/scripts/mimo_chat.py --model mimo-v2.5-pro --max-tokens 8000 --stream "写长一点"
+```
+
+mimo 引擎自动踩好 MiMo 的坑：`max_completion_tokens`（不是 `max_tokens`）、图片必须配 `text` part、多轮 `reasoning_content` 回填、联网搜索插件调用。
+
+| 参数 | 说明 |
+|---|---|
+| `--engine` | `auto` / `mimo` / `pollinations`（默认 auto） |
+| `--model` | 默认 `mimo-v2.5-pro`（mimo 引擎）。视觉用 `mimo-v2.5` / `mimo-v2-omni` |
+| `--pollinations-model` | 默认 `openai`（视觉能力）。可选 `openai-large` / `openai-fast` |
+| `--image URL` | 附图。自动 bump 到视觉能力模型 |
+| `--stream` | SSE 流式 |
+| `--max-tokens N` | mimo 引擎映射到 `max_completion_tokens`，pollinations 映射到 `max_tokens` |
+| `--temperature F` | 默认 0.7 |
+
+### `scripts/ocr.py` —— OCR / 识图
+
+非视觉 chat 模型场景下的兜底。**两个引擎**（`--engine auto` 自动选）：
+
+| 引擎 | 需要 key | 质量 | 备注 |
+|---|---|---|---|
+| `mimo` | 需要 `MIMO_API_KEY` | 最好 | 内部调 `mimo-v2.5`（视觉模型），与外层 chat 模型无关 |
+| `pollinations` | **不需要** | 还行 | 免费公共端点 `text.pollinations.ai`。有 IP 限流，但无需注册 |
+
+auto 选择：有 `MIMO_API_KEY` 用 mimo，否则 pollinations。所以**只配了 DeepSeek key**（或者啥都没配）的用户也能零配置用 OCR。
+
+```bash
+# 零配置 —— 没设 MIMO_API_KEY 时自动走免费 pollinations
+python3 mimoskill/scripts/ocr.py path/to/image.png
+
+# 最佳质量 —— 设 MiMo key
+export MIMO_API_KEY=sk-xxxx
+python3 mimoskill/scripts/ocr.py path/to/image.png   # auto -> mimo
+
+# 强制走免费引擎（即便你有 MiMo key，比如想省额度）
+python3 mimoskill/scripts/ocr.py --engine pollinations form.png
+
+# 强制 MiMo —— 没设 key 直接报错（不静默降级）
+python3 mimoskill/scripts/ocr.py --engine mimo form.png
+```
+
+四个输出模式：
+
+| `--mode` | 输出 |
+|---|---|
+| `text`（默认） | 逐字 OCR —— 保留换行 + 阅读顺序 |
+| `describe` | 2-4 句描述 |
+| `structured` | 单个 JSON：`text` / `language` / `regions[]` / `summary` |
+| `markdown` | 整张图重新渲染成 GitHub-flavored Markdown |
+
+输入形态（位置参数，0+ 个）：
+- 本地路径：`./scan.png`、`C:\foo.jpg`
+- HTTP(S) URL：原样转发
+- `data:image/...;base64,…`：原样转发
+- `-` 或管道 stdin：从 stdin 读一张图的字节
+
+magic-byte 嗅探 MIME（不信任扩展名）：PNG / JPEG / GIF / WebP / BMP。多个位置参数会**一次 upstream 调用**批处理。
+
+> 完整参考：[mimoskill/references/ocr_workflow.md](../mimoskill/references/ocr_workflow.md)（模式、退出码、JSON 结构、lang/prompt 参数、pollinations 细节）。
+
+### `scripts/generate_image.py` —— 通用图像生成
+
+`generate_pet.py` 的薄包装，去掉 chibi 宠物提示词模板、加了可选的 `--style` 常见风格。同样的 providers、同样的环境变量、同样的 auto 兜底策略。
+
+```bash
+# 免费 —— 没设 OpenAI key 时 auto 走 pollinations
+python3 mimoskill/scripts/generate_image.py --prompt "日式庭园，水彩，黎明" --out garden.png
+
+# 高质量 —— 设 OpenAI key
+export PET_OPENAI_API_KEY=sk-real-openai-key
+python3 mimoskill/scripts/generate_image.py --prompt "..." --out art.png  # auto -> gpt-image-1
+
+# 风格预设
+python3 mimoskill/scripts/generate_image.py --style anime --prompt "黄昏的神社" --out shrine.png
+```
+
+| `--provider` | 后端 |
+|---|---|
+| `auto`（默认） | 有 `PET_OPENAI_API_KEY` 走 `gpt-image-1`，否则 `pollinations` |
+| `pollinations` | 免费、无 key |
+| `gpt-image-1` | OpenAI 官方图像生成 —— 最佳质量 |
+| `replicate` | Replicate API（任意模型） |
+| `local-sd` | 本地 Stable Diffusion |
+
+> `PET_OPENAI_API_KEY` 故意**和 `MIMO_API_KEY`、`OPENAI_API_KEY` 分开** —— 只用于图像生成，泄露或不存在都不影响别的事。
+
+### `scripts/generate_pet.py` —— Codex 宠物生成
+
+同样的后端，但内置了一套调好的 chibi 贴纸提示词，围绕 `--description` 组装。输出尺寸 + 留白都按 Codex 宠物选择器适配。
+
+```bash
+# 单张静态宠物（免费）
+python3 mimoskill/scripts/generate_pet.py --description "chibi shiba 程序员" --out pet.png
+
+# 多状态动画 bundle（idle / thinking / typing / sleeping）
+python3 mimoskill/scripts/generate_pet.py --description "chibi 猫" --bundle ./shiba/
+```
+
+提示词模板在 [mimoskill/assets/pet_prompt_template.md](../mimoskill/assets/pet_prompt_template.md)。完整流程见 [mimoskill/references/pet_workflow.md](../mimoskill/references/pet_workflow.md)。
+
+### `scripts/install_pet.sh` —— 装宠物到 Codex
+
+自动探测 macOS / Linux / Windows 的宠物目录，把 PNG（或 bundle）拷过去。绕开 Codex 硬编码的宠物路径问题。
+
+```bash
+bash mimoskill/scripts/install_pet.sh pet.png shiba
+# 然后完全退出 + 重启 Codex（桌面端走系统托盘退出，不只是关窗口）
+```
+
+## 三种用法
+
+### 1. 直接调用（普通用户，零配置）
+
+```bash
+python3 mimoskill/scripts/mimo_chat.py "..."
+python3 mimoskill/scripts/ocr.py invoice.png        # 无 key 也能跑，走免费 pollinations
+python3 mimoskill/scripts/generate_image.py --prompt "..."
+```
+
+不需要注册 skill —— 就是普通 Python 脚本（纯标准库，不用 `pip install`）。
+
+### 2. 当 Claude Code 的 Skill 用
+
+软链到 `~/.claude/skills/`：
+
+```bash
+ln -s "$(pwd)/mimoskill" ~/.claude/skills/mimoskill
+```
+
+之后 Claude 会读 [SKILL.md](../mimoskill/SKILL.md)，遇到相关请求（"帮我从这张图生成宠物"、"读一下这张截图的文字"、"让 MiMo 把这段话朗读了"）自动路由到对应脚本。
+
+### 3. 当 Codex agent 指南
+
+仓库根的 [AGENTS.md](../AGENTS.md) 已经接好。Codex 每次启会话都会读，遇到生图 / 宠物 / OCR 任务会路由到 mimoskill 脚本 —— **不会**再去 `pip install openai`，也不会在用 MiMo / DeepSeek / Qwen / 任何非 OpenAI 上游时尝试调 OpenAI 的 `image_gen` 工具。
+
+## 环境变量
+
+| 变量 | 谁用 | 说明 |
+|---|---|---|
+| `MIMO_API_KEY` | `mimo_chat.py`、`ocr.py`（engine=mimo / auto 时） | MiMo Chat / 视觉 key。两个脚本都**可选** —— 没设会自动走 pollinations |
+| `MIMO_CHAT_ENGINE` | `mimo_chat.py` | `auto` / `mimo` / `pollinations` —— 等价于 `--engine` |
+| `MIMO_BASE_URL` | `mimo_chat.py`、`ocr.py` | 默认 `https://api.xiaomimimo.com/v1` |
+| `MIMO_MODEL` / `MIMO_OCR_MODEL` | `ocr.py` 模型 auto-pick | 没传 `--model` 时使用（必须视觉能力） |
+| `MIMO_OCR_ENGINE` | `ocr.py` | `auto` / `mimo` / `pollinations` —— 等价于 `--engine` 参数 |
+| `POLLINATIONS_MODEL` | `ocr.py` | 默认 `openai`（视觉能力）。可选 `openai-large`、`openai-fast` |
+| `PET_OPENAI_API_KEY` | `generate_pet.py`、`generate_image.py` | 跟 `MIMO_API_KEY` / `OPENAI_API_KEY` 独立；只用于图像生成 |
+| `REPLICATE_API_TOKEN` | `generate_*.py --provider replicate` | 仅 Replicate 后端时需要 |
+
+## 常用组合
+
+### 先 OCR 一张图，再用当前 chat 模型总结
+
+```bash
+TEXT=$(python3 mimoskill/scripts/ocr.py invoice.png)
+python3 mimoskill/scripts/mimo_chat.py "总结这张发票:\n$TEXT"
+```
+
+或者直接在 Codex 里：把图贴进去就行。proxy 剥图后留指向 `ocr.py` 的占位文本，Codex 自己跑脚本把文字喂回对话 —— **完全自动**。
+
+### 生成 `/hatch` 替代宠物（无 OpenAI key 也能用）
+
+```bash
+python3 mimoskill/scripts/generate_pet.py --description "chibi shiba 程序员" --out pet.png
+bash mimoskill/scripts/install_pet.sh pet.png shiba
+# 完全退出 + 重启 Codex，宠物菜单里挑新的
+```
+
+想要更好质量，设 `PET_OPENAI_API_KEY=sk-真OpenAI-key`，auto 会切到 `gpt-image-1`。
+
+### 结构化 OCR + JSON 解析
+
+```bash
+JSON=$(python3 mimoskill/scripts/ocr.py --mode structured invoice.png)
+echo "$JSON" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['summary'])"
+```
+
+### 多图批量 OCR（一次计费）
+
+```bash
+python3 mimoskill/scripts/ocr.py page1.png page2.png page3.png
+```
+
+所有图**单次** upstream 调用，模型可跨图引用（如身份证正反面）。输出是按阅读顺序串联的一段文本。
+
+## 故障排查
+
+<details>
+<summary><b><code>MIMO_API_KEY</code> 未设置</b> —— ocr.py 退出码 3</summary>
+
+你显式传了 `--engine mimo`。要么去掉这个参数（`auto` 会自动降级到 pollinations），要么设 key：
+
+```bash
+export MIMO_API_KEY=sk-xxxx
+python3 mimoskill/scripts/ocr.py form.png
+```
+
+</details>
+
+<details>
+<summary><b>Pollinations 返回 429 / 限流</b></summary>
+
+撞 IP 限流。等会儿再试，或者切到 `--engine mimo`（如果你有 MiMo key）。
+
+</details>
+
+<details>
+<summary><b>Codex 跑 /hatch 时报 <code>image_gen tool not available</code></b></summary>
+
+Codex 的 `/hatch` 在客户端硬编码调 OpenAI 的 `image_gen` 工具，代理拦不住。改用 `generate_pet.py`，见上文「生成 /hatch 替代宠物」。
+
+</details>
+
+<details>
+<summary><b>报 <code>pip install openai</code> 错 / Codex 想装 openai</b></summary>
+
+是 Codex 想用 openai Python SDK 兜底图像生成。[AGENTS.md](../AGENTS.md) 已经预防这条路 —— 确认它在仓库根，且当前 Codex 会话已经读过（编辑完 AGENTS.md 后要开新会话）。
+
+</details>
+
+<details>
+<summary><b>工具返回了图，但模型在工具结果里看不到图</b></summary>
+
+设计如此。Chat Completions 的 `tool` role 历史上只接受字符串 content —— `function_call_output` 里的图片 content part 会被 flatten 成 `[N image attachment(s) omitted from tool output: ...]` 占位文本（详见 [src/translate/reqToChat.ts](../src/translate/reqToChat.ts) 的 `toolOutputToString`）。要把图喂给 LLM，让工具把图存到本地、返回路径，下一轮用户消息再 `@path/to/screenshot.png` 让 ocr.py 类工具读出来 —— 这时如果 chat 模型不支持视觉，OCR 兜底机制就会接管。
+
+</details>
+
+## 设计取舍
+
+- **不需要 `pip install`。** 所有脚本纯标准库。避免依赖漂移，任何裸 Python ≥ 3.8 都能跑。
+- **网络操作明确。** 不偷偷重试备用端点。要 MiMo 又没 key 就直接报错 —— 而不是静默降级掩盖配错。
+- **proxy 和 mimoskill 互不调用。** 两个独立进程，靠 `AGENTS.md` / `SKILL.md` 约定连接。这样两边都能独立测试 / 替换。
+- **Pollinations 是无 key 逃生通道。** 在 `ocr.py`（视觉）、`generate_pet.py`（出图）、`generate_image.py`（出图）里都用作免费兜底。有 IP 限流但永远在线。项目把它当成一等公民，不是"降级模式"。