look-at-deepseek

轻量级多渠道识图 MCP 服务器（vision_analyze / vision_ocr / vision_channels / vision_image_info）。支持多服务商级联容灾（顺序 / 竞速）、瞬态错误重试、按渠道熔断（可手动复位）、请求去重缓存、配置热重载、JSONL 请求日志与统计持久化、清晰优先的图片压缩，以及 stdio / Streamable HTTP 双传输（含 TLS 与 /healthz）。

零依赖 TUI 配置向导（OpenTUI/OpenCode 风格），纯 node:readline 实现。

快速开始

# 一键快速配置（只问 服务商 / Base URL / API Key，其余自动推荐）
npx -y look-at-deepseek init --quick

# 完整配置向导（TUI，步骤进度条，支持多模型批量添加）
npx -y look-at-deepseek init

# 生成配置后启动（stdio，供 Claude Code / Grok / Cursor / opencode / codex 等使用）
npx -y look-at-deepseek

# 一键注册到已安装客户端
npx -y look-at-deepseek install

init 向导带 5 步进度指示（① 部署方式 → ② 渠道配置 → ③ 全局设置 → ④ 测试验证 → ⑤ 客户端注册），支持 16 个服务商预设（xAI / OpenAI / Anthropic / DeepSeek / 智谱 / 通义 / 豆包 / Gemini / Groq / Mistral / 硅基流动 / Kimi / MiniMax / Ollama 等）、填入 API Key 后自动拉取模型列表并推荐最佳视觉模型、批量添加同一服务商的多个模型、按模型自动探测能力（多模态 / 上下文窗口 / 输出 token 上限）、熔断参数预设（默认 / 宽松 / 严格 / 自定义）和智能默认值（本地服务自动推荐 15s 超时 + 宽松熔断）。

edit（config 编辑）同样是傻瓜式：编辑模式步骤条（渠道列表 → 字段修改 → 保存验证）、改动即时生效退出自动保存（.bak 备份）、改模型时自动拉取列表并推荐、内置「测试连通性」（不改配置就能就地探测所有渠道的可用性和延迟）。

特性

多渠道级联容灾

config.json 中的 channels 数组按 priority（数字越小越优先）依次尝试；一个渠道失败自动落到下一个，第一个成功即返回。

0.3.0 起支持两种容灾策略（defaults.strategy，也可用 --strategy 或单次调用参数覆盖）：

• priority（默认）：顺序级联，最省 token，仅在渠道真正失败时才切换；
• race：同时向所有健康渠道发起请求，第一个成功即返回（延迟最低，但每个健康渠道都会消耗 token）。

{
  "channels": [
    { "name": "xAI Grok", "base_url": "https://api.x.ai", "api_key": "…", "model": "grok-4.5",
      "api_format": "openai", "wire_api": "responses", "priority": 1, "max_output_tokens": 8192 },
    { "name": "OpenAI", "base_url": "https://api.openai.com", "api_key": "…", "model": "gpt-4o-mini",
      "api_format": "openai", "wire_api": "chat", "priority": 2 }
  ],
  "defaults": {
    "max_tokens": 4096,
    "timeout_seconds": 60,
    "retry_count": 2,
    "breaker_threshold": 3,
    "breaker_cooldown_seconds": 30,
    "breaker_halfopen_attempts": 1,
    "strategy": "priority",
    "cache_ttl_seconds": 0
  }
}

请求去重缓存

defaults.cache_ttl_seconds（默认 0 = 关闭）开启相同请求去重：同样的 prompt + 图片 + 参数在 TTL 内直接返回缓存结果（响应标记 cached: true，渠道显示 (cache)），适合同一张图被反复分析/OCR 的场景（UI 截图、图表）。LRU 淘汰，上限 512 条。

配置热重载

使用 config.json 时默认开启 watch：修改文件后无需重启进程，渠道/参数自动生效（--no-watch 关闭）。热重载通过 MCP logging 通知客户端，失败时保留旧配置。

usage 与渠道统计

• 三种上游格式（OpenAI chat / OpenAI responses / Anthropic）的 token 用量都会被解析并随结果返回（[usage] in=X out=Y tokens）；
• vision_channels 实时展示每个渠道的累计统计：调用次数、成功/失败、平均/最近延迟、输入/输出 token，以及熔断状态。

输出 token 上限自动探测

max_tokens 按模型自动探测（OpenRouter 目录 → 内置官方文档数据）：

• 每个渠道可单独设置 max_output_tokens（向导中自动填入探测到的模型上限）；
• 请求时优先级：调用级 maxTokens > 渠道 max_output_tokens > 全局 defaults.max_tokens；
• 向导的全局默认值会建议为各渠道探测值中的最小值（安全兜底）。

速度（识别性能优化）

响应时间 = 上传体积（决定视觉 token 数）+ 上游吞吐 + 等待/重试。按性价比排序的调优旋钮：

• 竞速 failover — defaults.strategy: "race"（或用 --strategy race / 单次调用参数）：同时请求所有健康渠道、取最早返回者。延迟最低，代价是每个健康渠道都消耗 token。交互式随机看图最推荐。
• detail=low：单次调用传 detail=low，省视觉 token、更快；detail=high 更准。快 vs 准的取舍开关。
• 压缩更激进：MCP_COMPRESS_MAX_SIDE 降到 1024（长边）或把 MCP_COMPRESS_REENCODE_MIN_BYTES 降到 256KB，让更多图在上传前被压缩（上传越小 → 视觉 token 越少 → 越快）。注意：过度压缩会牺牲识别精度，请按场景调，别一杆子压到底。
• 渠道 timeout_ms：把过大的超时收紧（如 15~30s），让挂起的上游更快熔断并级联到下一个渠道，而不是傻等 60s。
• 重复请求去重：defaults.cache_ttl_seconds（如 30~60）。同一张图反复分析/OCR（UI 截图、图表、长文档分段）时在窗口内直接命中缓存、零上游成本——高复用场景收益最大。
• 本地模型：Ollama 等本地服务时把 timeout_ms 放宽、熔断放宽，避免本地推理慢被当成故障砍掉。

各渠道可独立配 timeout_ms / 熔断参数 / max_output_tokens，不用所有渠道一刀切。

熔断

• 渠道级：连续 breaker_threshold 次失败后熔断，冷却 breaker_cooldown_seconds 秒，之后半开试探（breaker_halfopen_attempts 次）；
• 未配置的渠道跟随全局 defaults；
• 预设：默认（3 次/30s）、宽松（5 次/60s）、严格（2 次/15s）、自定义；
• 熔断状态可通过 vision_channels 工具实时查看。

瞬态重试

408/409/425/429/500/502/503/504 与网络错误按指数退避重试（2^n 秒，429 遵循 Retry-After）；永久 4xx 立即失败并触发级联。

图片压缩（清晰优先）

默认 256KB 以下原样发送；长边超过 2048px 才缩放；重编码为 JPEG q=90 仅对「重格式（PNG / WebP 无损 / BMP / TIFF）」或「需缩放」的图进行——已是 JPEG 且无需缩放的图原样发送，避免无意义的一代画质损失与 CPU 开销。仅当重编码后更小才替换；透明背景铺白。sharp 为可选依赖，缺失时原样发送（HEIC/AVIF 若无对应解码模块同样优雅回退到原图，不报错）。

支持的照片格式

| 输入 | 格式 | |------|------| | 本地路径 | png / jpg / jpeg / webp / gif / bmp / tif / tiff / heic / heif / avif | | 远程 URL | 以上全部 + 任意 image/*（按 media type 透传） | | base64 | 任意 image/*（需声明 imageMediaType） |

heic / heif / avif 的解码依赖 sharp（libvips）是否编译了对应模块；vision_image_info 通过魔数可无解码识别这些新格式（报告格式名，尺寸由 sharp 补齐）。

命令

look-at-deepseek init [--config <path>]       交互式向导（等价 --init）
look-at-deepseek init --quick [--config <path>]  一键快速配置（只问 3 个问题）
look-at-deepseek edit [--config <path>]       字段级编辑渠道（等价 --edit，裸 --config 也可）
look-at-deepseek install [--config <path>] [--yes]  注册到 Claude Code / Grok / Cursor / VS Code / Claude Desktop / opencode / codex
look-at-deepseek check [--config <path>] [--test] [--log-file <path>]  非交互健康检查，退出码 0=全通 / 1=有失败 / 2=配置缺失或无效
look-at-deepseek [options]                    启动 MCP 服务器

check 适合 CI/脚本：打印渠道表 → 对每个渠道做 HEAD 连通性探测（不消耗 token）→ --test 追加一笔真实 1-token 识图，--log-file 把探测与识图结果写入 JSONL。

配置路径解析：--config > MCP_CONFIG 环境变量 > 当前目录 ./config.json。

init / edit 的渠道管理支持克隆渠道（复制配置后改模型/名称，快速加备用模型）与调整优先级（↑↓ 上下移，与相邻渠道交换优先级）。

客户端（harness）支持矩阵

install 一键注册到已安装的客户端，其余按官方配置文件手动注册：

| Harness | 注册方式 | 配置位置 | |---------|----------|----------| | Claude Code | install 自动（合并 ~/.claude.json） | ~/.claude.json 的 mcpServers | | Claude Desktop | install 自动（合并 ~/.claude.json） | 同上 | | Grok Build | install 自动（grok mcp add） | 由其 CLI 维护 | | Cursor | install 自动（~/.cursor/mcp.json） | ~/.cursor/mcp.json 的 mcpServers | | VS Code | install 自动（code --add-mcp） | 用户级 mcpServers | | opencode | install 自动（合并 opencode.json） | ~/.config/opencode/opencode.json 的顶级 mcp 块 | | codex CLI | install 自动（追加 config.toml） | ~/.codex/config.toml 的 [mcp_servers.vision] 表 |

已支持的服务端类型：stdio（以上全部）与 Streamable HTTP（Claude Code / Cursor / VS Code / 任意 HTTP MCP 客户端，--host / --port / --token / TLS 部署，见下文 Docker）。

install 按各客户端约定逐一注册，绝不覆盖：已存在的 mcpServers.vision / [mcp_servers.vision] 会跳过并提示手动处理；注册前对原文件做 .bak 备份。HTTP 模式下输出对应的 claude mcp add --transport http 命令供手工接入。

工具

| 工具 | 说明 | |------|------| | vision_analyze | 图片理解。task 参数内置 6 类任务模板（describe 描述 / chart 图表解读 / ui 界面审查 / formula 公式提取 / translate 翻译 / meme 梗图解读），outputFormat=json 让模型返回对应 JSON 对象（图表→数据表、UI→组件/问题清单）；多图时自动编号 图 1/图 2 并支持按编号引用；返回附带 usage 与渠道信息 | | vision_ocr | 高保真文字提取，支持 plain / markdown / json 三种输出格式与语言偏好 | | vision_channels | 渠道健康巡检：熔断状态 + 累计统计（成功/失败/延迟 P50/P95/输入输出 token）+ 去重缓存命中率；reset=true 一键复位全部熔断，resetChannel=<priority> 复位单个；零 API 成本 | | vision_image_info | 图片元信息（宽高/格式/大小），本地用 sharp 或魔数头解析、远程仅 HEAD 探测，零 API 成本 |

可观测性

• JSONL 请求日志（--log-file <path> / defaults.log_file）：每次调用（成功/失败/缓存命中）与热重载等生命周期事件各落一行，含 ts / 工具 / 策略 / 渠道 / 模型 / 延迟 / token 用量 / 错误——排查"哪个渠道慢、为什么挂"的直接证据链；
• 统计持久化（--stats-file <path> / defaults.stats_file）：累计渠道统计与缓存计数跨重启保留（启动恢复 + 每 30s 落盘 + 退出落盘，损坏文件自动降级为空）；
• 熔断手动复位：渠道被熔断后无需等冷却——vision_channels 传 resetChannel=<priority> 或 reset=true 立即恢复；
• /healthz 增强：除基础信息外返回 cache: {hits, misses, hitRate} 与每个渠道的 breakers: [{name, state}]。

服务器模式（HTTP）

npx -y look-at-deepseek init   # 部署方式选择「服务器 HTTP」
npx -y look-at-deepseek        # 监听 0.0.0.0:3000，Bearer token 鉴权

• 未鉴权的 /healthz 返回 { ok, version, channels, strategy, uptimeSeconds }，供负载均衡/探活使用；
• TLS：--tls-cert <pem> --tls-key <pem> 直接以 HTTPS 提供服务；
• Claude Code 连接：claude mcp add --transport http vision http://<服务器地址>:3000/mcp --header "Authorization: Bearer <token>"。

Docker 部署

# 构建（安装最新发布版，无需源码）
docker build -t look-at-deepseek .

# 运行（挂载配置；令牌通过 --token 或 MCP_TOKEN 传入）
docker run -d --name lads -p 3000:3000 \
  -v "$PWD/config.json:/app/config.json" \
  look-at-deepseek --token <your-token>

# 健康检查
curl http://localhost:3000/healthz

或直接使用 compose（自带 healthcheck 与 restart 策略）：

docker compose up -d     # 挂载 ./config.json，监听 3000
curl http://localhost:3000/healthz

TLS 证书挂载示例：-v /etc/letsencrypt/live/example.com:/app/tls:ro，容器参数加 --tls-cert /app/tls/fullchain.pem --tls-key /app/tls/privkey.pem。

环境变量

| 变量 | 说明 | |------|------| | MCP_CONFIG | 配置文件路径 | | MCP_TRANSPORT / MCP_HOST / MCP_PORT / MCP_TOKEN | HTTP 传输 | | MCP_TIMEOUT_MS / MCP_MAX_TOKENS / MCP_RETRY_COUNT | 调优 | | MCP_BREAKER_THRESHOLD / MCP_BREAKER_COOLDOWN_MS / MCP_BREAKER_HALFOPEN_ATTEMPTS | 熔断 | | MCP_STRATEGY / MCP_CACHE_TTL_SECONDS | 容灾策略（priority/race）与去重缓存秒数 | | MCP_LOG_FILE / MCP_STATS_FILE | JSONL 请求日志路径 / 统计持久化路径 | | MCP_TLS_CERT / MCP_TLS_KEY | HTTPS 证书与私钥路径 | | VISION_API_BASE_URL / VISION_MODEL / VISION_API_KEY / VISION_API_PATH / VISION_WIRE_API | 单渠道兜底 | | MCP_COMPRESS_MIN_BYTES / MCP_COMPRESS_MAX_SIDE / MCP_COMPRESS_JPEG_QUALITY / MCP_COMPRESS_REENCODE_MIN_BYTES | 压缩策略 |

开发

npm install
npm run dev       # tsx 直接跑源码
npm run build     # 编译到 dist
npm test          # 源码测试（node --import tsx）
npm run test:build # 编译后测试
npm run lint

已知问题

• Claude Code 2.1.x 的 mcp add 对 -- 后的任何旗标（-y / --config / -e）会报 "unknown option"（issue #79638），install 通过直接合并 ~/.claude.json 绕过。
• Windows 下带空格的路径（如 C:\Program Files\nodejs\node.exe）会被 CLI 解析器拆开，注册时统一转换为 8.3 短路径（C:\PROGRA~1\nodejs\node.exe）。

License

MIT