![\"npm\"](\"https://img.shields.io/badge/npm-v0.6.0-blue\"){kind=icon}
\n ![\"license\"](\"https://img.shields.io/github/license/Yvesnihaohaode/fallback-vision\")
\n ![\"node\"](\"https://img.shields.io/badge/node-%3E%3D20-brightgreen\"){kind=icon}
\n ![\"stars\"](\"https://img.shields.io/github/stars/Yvesnihaohaode/fallback-vision?style=social\")
\n\n AI Gateway with Visual Fallback, Hybrid Search & Protocol Translation\n
\n\n\n
\n 中文 | English\n
\n\n---\n\n## 它是什么\n\nFallback Vision 是一个 **AI 网关**，坐在你的应用和 AI 模型之间，解决三个核心痛点：\n\n1. **文字模型看不到图片** → 自动调用视觉模型分析图片，把描述传给主模型推理\n2. **Claude Code / Codex 不兼容 MiMo 搜索** → 本地混合搜索引擎，4 个后端并行竞赛\n3. **Anthropic 和 OpenAI 协议不互通** → 自动双向转换，一套网关两种协议都能用\n\n```\n你的应用 → Fallback Vision → 检测到图片？→ 视觉模型看图 → 主模型推理 → 回答\n → 搜索请求？→ 4 后端竞赛 → 最快结果返回\n → 协议不同？→ 自动转换 → 上游模型\n```\n\n## 核心特性\n\n### 视觉回退路由\n主模型没有多模态能力？没关系。Fallback Vision 自动检测图片，调用视觉模型生成结构化描述，再交给主模型推理。**主模型永远看不到原始图片，只看到分析结果。**\n\n支持的主模型：MiMo、DeepSeek、OpenAI、Claude、Gemini、Qwen 等任意 OpenAI 兼容 API。\n\n### 混合搜索引擎\nMiMo 不支持 Claude Code 的 `web_search` / `web_fetch`？Fallback Vision 用 4 个搜索后端（**Bing / Sogou / Brave / Google**）并行竞赛，最快返回结果的获胜。\n\n- **时效性过滤**：`day` / `week` / `month`，搜索\"最新\"信息不再过时\n- **智能增强**：查询含\"最新/latest\"等关键词时自动启用时效过滤\n- **代理友好**：兼容各种网络环境\n\n### 协议转换\nClaude Code 发 Anthropic 格式，Codex 发 OpenAI 格式——Fallback Vision 自动双向转换，流式 SSE 也完全支持。\n\n### 一键启动\n```bash\nfv-claude # 启动服务 + 配置 Claude Code + 打开 claude\nfv-codex # 启动服务 + 配置 Codex + 打开 codex\nfv-stop # 停止服务 + 恢复原始配置\n```\n\n### cc-switch 集成\n`fv-claude` 启动时自动备份你的 Claude 配置（cc-switch 等），`fv-stop` 停止时自动恢复。不影响现有配置。\n\n## Quick Start\n\n### npm（推荐）\n\n```bash\nnpm install -g fallback-vision\nfv-claude # Claude Code 模式\nfv-codex # Codex 模式\n```\n\n### Docker\n\n```bash\ndocker run -d -p 8789:8789 \\\n -v ~/.fallback-vision:/root/.fallback-vision \\\n yvesnihaohaode/fallback-vision:latest\n```\n\n### 源码\n\n```bash\ngit clone https://github.com/Yvesnihaohaode/fallback-vision.git\ncd fallback-vision\nnpm install\nnpm run build\nnode bin/fv-claude.js\n```\n\n所有方式都会自动打开 Web UI（http://127.0.0.1:8789）让你配置 API。\n\n## 配置\n\n浏览器打开 http://127.0.0.1:8789 进入 Web Dashboard：\n\n| 配置项 | 说明 |\n|--------|------|\n| 客户端类型 | Codex (OpenAI) 或 Claude Code (Anthropic) |\n| 主模型 | Provider + API Key + Base URL + 模型名 |\n| 视觉模型 | Provider + API Key + Base URL + 模型名 |\n| 本地搜索 | MiMo 专属，解决 web_search/web_fetch 不可用 |\n\n## 架构\n\n```\n┌─────────────────────────────────────────────────────┐\n│ Fallback Vision │\n│ │\n│ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │\n│ │ Protocol │→│ Router │→│ Pipeline │ │\n│ │ Detector │ │ │ │ ┌─────────────┐ │ │\n│ │ Anthropic │ │ Vision? │ │ │ Vision Model│ │ │\n│ │ OpenAI │ │ Search? │ │ │ → describe │ │ │\n│ └──────────┘ └──────────┘ │ └──────┬──────┘ │ │\n│ │ ↓ │ │\n│ ┌──────────┐ │ ┌─────────────┐ │ │\n│ │ Search │←──────────────│ │ Main Model │ │ │\n│ │ 4 backends│ │ │ → reason │ │ │\n│ │ race │ │ └─────────────┘ │ │\n│ └──────────┘ └───────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────┐ │\n│ │ Web Dashboard (http://127.0.0.1:8789) │ │\n│ │ Config · Logs · Metrics │ │\n│ └──────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────┘\n```\n\n更详细的架构说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。\n\n## 一键命令\n\n| 命令 | 用途 |\n|------|------|\n| `fv-claude` | 启动服务 + 打开 Claude Code |\n| `fv-codex` | 启动服务 + 打开 Codex |\n| `fv-claude-docker` | Docker 启动 + Claude Code |\n| `fv-codex-docker` | Docker 启动 + Codex |\n| `fv-stop` | 停止服务 + 恢复原始配置 |\n| `fallback-vision-setup` | 交互式向导 |\n| `fallback-vision` | 仅启动服务 |\n\n## 适用场景\n\n- **MiMo / DeepSeek 用户**：用 Claude Code 也能搜索，不用换模型\n- **多模型用户**：一个网关统一管理 MiMo、DeepSeek、OpenAI 等多个 Provider\n- **文字模型用户**：不需要单独的视觉模型，Fallback Vision 自动帮你调用\n- **Codex + Claude Code 双修**：一套服务两种协议都能用\n\n## 开发\n\n```bash\nnpm test # 运行 62 个测试\nnpm run dev # 热重载开发\nnpm run lint # 类型检查\n```\n\n## 文档\n\n- [架构文档](docs/ARCHITECTURE.md)\n- [路线图](docs/ROADMAP.md)\n- [更新日志](CHANGELOG.md)\n- [English README](docs/README_EN.md)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}