llm_vision: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

本地 MCP 服务器：为无视觉能力的模型（如 deepseek 系）提供视觉——模型传入本地图片路径，服务器调用阿里 DashScope 视觉模型，返回文字结果。已注册在 .mcp.json（可移植形式，cwd: "."），本项目内任何 Claude Code 会话直接可用 describe_image / extract_text。images/ 目录被 gitignore（测试图不入库），冒烟/对比脚本可用参数传入图片路径或自备 images/ 测试图。

常用命令

uv sync                                     # 安装依赖（Python 3.12，uv 管理）
uv run pytest tests/ -q                     # 全量测试（68 个，多数离线不花钱）
uv run pytest tests/test_dashscope_client.py -v   # 单文件测试
uv run python main.py                       # 启动 MCP 服务器（stdio；Claude Code 会按 .mcp.json 自动拉起）
uv run python scripts/smoke_test.py [图片路径 ...]   # 真实 API 冒烟（消耗额度；绕缓存；缺省用 images/ 自备图，无图时提示传路径）
uv run python scripts/compare_models.py qwen3-vl-plus qwen3.7-plus   # 模型对比（同样耗额度）

架构

main.py（FastMCP 薄注册）
  ├── describe_image(image_path, prompt?, perspective="normal")   → LLM_VISION_MODEL（默认 qwen3-vl-plus）
  ├── extract_text(image_path, prompt?)     → LLM_VISION_OCR_MODEL（默认 qwen3.5-ocr）
  └── 共用 _analyze_image 管线
        → image_cache 命中检查（可选注入，内容寻址，仅存文本回答）
        → image_loader.load_image（路径/扩展名白名单/10MB 校验，base64+MIME 推断；HEIC/HEIF 走 macOS sips 转换）
        → image_preprocess.preprocess_image（超 1568px 等比缩放 / 超 1.5MB 重压，macOS sips 零依赖，临时文件处理后即删；无 sips 平台跳过）
        → dashscope_client.DashscopeClient.chat（超时/网络/5xx 重试，等比递减预算 ≤2×timeout）

• 工具恒返回字符串：成功返回模型回答，失败返回可读中文错误信息，绝不抛异常到客户端。错误消息以「文件不存在」「不支持的图片格式」「图片过大」「视觉模型调用失败」等开头——测试断言依赖这些前缀，改动错误文案需同步测试
• 依赖注入：DashscopeClient(api_key, timeout, max_retries=2, transport=None) 的 transport 仅测试注入（httpx.MockTransport），生产传 None。测试注入模式：max_retries=0（即时失败，不等待退避）、缓存测试用 tmp_path 作 cache_dir、重试测试 monkeypatch.setattr("time.sleep", ...) 跳过退避。新增测试不要发真实请求
• mcp SDK 是 2.0.0：mcp.server.fastmcp 已移除，用 from mcp.server import MCPServer as FastMCP；断言工具注册可用 mcp._tool_manager（私有接口），端到端验证用 stdio 子进程（tests/test_main.py 里有完整范式）
• 模型可配置：环境变量 LLM_VISION_MODEL / LLM_VISION_OCR_MODEL / LLM_VISION_TIMEOUT（默认 120）/ LLM_VISION_MAX_RETRIES（默认 2）/ LLM_VISION_DESCRIBE_PROMPT / LLM_VISION_OCR_PROMPT / LLM_VISION_CACHE（默认开）/ LLM_VISION_CACHE_DIR / LLM_VISION_MAX_EDGE（默认 1568）/ LLM_VISION_COMPRESS（默认开）。注意 qwen3-vl-plus-latest 别名已 404 失效，勿用
• 改默认值需同步 5 处：config.py 的 DEFAULT_* 常量、tests/test_config.py 的 test_defaults 断言、README ×2 环境变量表、CLAUDE.md 本条、docs/model-eval-2026-08-05.md 结论——只改常量不同步测试会静默失败（此前踩过）
• _analyze_image 签名约定：第 5、6 参数 max_edge / compress_enabled（预处理），第 7 参数 cache（ImageCache | None）。cache 默认 None = 不缓存——smoke 脚本天然绕过缓存验证真实 API；错误字符串永不入缓存
• 升级模型前先读 docs/model-eval-2026-08-05.md：三模型对比结论（qwen3-vl-plus 唯一零幻觉、qwen3.7-plus 为候选、qwen3.5-omni-plus 有视觉错误），选新模型以它为依据
• 工具 docstring 即 MCP 工具描述：模型靠它理解工具意图，修改 docstring 会改变模型调用行为
• describe_image 双视角：perspective 参数二选一——normal（默认，DEFAULT_NORMAL_DESCRIBE_PROMPT 自然描述）与 critical（DEFAULT_DESCRIBE_PROMPT 审视视角：客观描述 + 主动报告异常 + 区分事实/推测 + 不找补）。docstring 明确写了「用户提及页面/界面问题（不好看/有问题/检查/找 bug）必须用 critical」——视觉模型会把渲染 bug 合理化，审视指令是实测教训（2026-08-06）。显式 prompt 优先于视角默认；LLM_VISION_DESCRIBE_PROMPT 只覆盖 critical 视角。改这两段提示词会改变模型输出风格，评估文档/README 如引用旧文案需同步