CaoMeiYouRen/vision-augment

Latest recorded source activity: October 31, 2026 at 20:13

SkillsMP catalog refreshed: November 9, 2026 at 14:22

skills collected: 1

GitHub stars: 0
GitHub forks: 0

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/CaoMeiYouRen/vision-augment.

Repository README

Repository README source: README.md

Read the source README

Expand full README

# vision-augment 本地优先的多模态视觉 MCP —— 为无视觉 LLM（DeepSeek、GLM 等）提供可自定义端点的看图 / OCR / 文档解析能力。 - **简化配置、本地优先**：不强制依赖云端；OCR 与文档解析全部本地完成 - **视觉理解用视觉模型**：OpenAI 兼容通道链，按序降级，最后兜底本地 Ollama VL（无 key 即用） - **不限制模型渠道**：任意 OpenAI 兼容端点，`base_url + api_key + model` 三元组可配多个 - **uvx 一键分发**：`uvx vision-augment` 直接接入任意 MCP harness ## 架构 ``` MCP client (Hermes / Claude / OpenCode ...) └─ mcp_vision_augment_vision(task_type=reasoning|ocr|document) └─ Router ─┬─ reasoning → OpenAI 兼容通道链 + Ollama 兜底 ├─ ocr → RapidOCR（本地）→ PaddleOCR（可选升级） └─ document → markitdown（本地）→ PaddleOCR-VL / MinerU（可选升级） ``` 所有工具返回统一 JSON envelope：`{task_type, tool_used, code, error, result, confidence, metadata}`，错误码 0-5。 ## 快速开始环境要求：Python >= 3.12，[uv](https://docs.astral.sh/uv/)。 ### 方式一：无 key，本地 Ollama（默认） ```bash ollama pull llava # 或任一视觉模型（llava/vision/qwen2.5-vl/...） uvx vision-augment ``` ### 方式二：自定义 OpenAI 兼容端点（推荐） ```bash uvx vision-augment[ocr,document] # 按需安装本地 OCR/文档引擎 ``` ```yaml # 注册到 Hermes config.yaml（其他客户端见下） mcp_servers: vision-augment: command: uvx args: [vision-augment] env: VISION_AUGMENT_CHANNELS: '[{"base_url": "https://api.example.com/v1", "api_key": "${API_KEY}", "model": "qwen3.7-plus"}]' ``` 无通道配置时自动探测本地 Ollama VL 模型作为兜底；通道配置优先。 ### 本地 OCR/文档引擎（按需安装） - 默认安装（`uvx vision-augment`）**只含视觉理解**（云端通道/Ollama）；OCR 与文档解析是本地引擎，按需通过 extras 安装： - `[ocr]`：RapidOCR（ONNX，跨平台轻量）——`uvx vision-augment[ocr]` - `[document]`：markitdown（docx/pdf/pptx/xlsx/html → Markdown）——`uvx vision-augment[document]` - 引擎未安装时调用对应任务返回 `code=4 dependency_missing`（错误信息附安装命令）；随时可用 `mcp_vision_augment_health` 查看引擎可用状态 - ⚠️ **超时注意**：RapidOCR 引擎首次加载（ONNX 模型初始化）较慢，**首个 OCR 请求可能触发客户端 MCP 超时——重试一次即可**（引擎在 server 进程内缓存，第二次起秒回）；若频繁超时，调大客户端 MCP 工具超时（如 opencode 的 `toolTimeout`），或改用 HTTP 传输（见方式四） ### 方式三：从 GitHub 直接安装（未发布到 PyPI 前） ```bash # 最新 master（PEP 508 语法：extras 在 @ 之前） uvx "vision-augment[ocr,document] @ git+https://github.com/CaoMeiYouRen/vision-augment" # 锁定 tag / commit uvx "vision-augment @ git+https://github.com/CaoMeiYouRen/vision-augment@v0.1.0" # 长期安装到 PATH（等价 pipx） uv tool install "vision-augment[ocr] @ git+https://github.com/CaoMeiYouRen/vision-augment" ``` ### 方式四：HTTP 传输（streamable-http）适合 Docker 部署、远程服务器、多客户端并发场景（stdio 单进程只能服务一个客户端）： ```bash VISION_AUGMENT_TRANSPORT=streamable-http VISION_AUGMENT_PORT=8000 uvx vision-augment ``` - 默认绑定 `127.0.0.1:8000`，MCP 端点 `/mcp`；SDK 对 localhost 自动启用 DNS rebinding 防护 - 跨机器访问：设置 `VISION_AUGMENT_HOST=0.0.0.0`，**并自行加反向代理/鉴权**（远程暴露是部署方责任） - 客户端配置示例（Hermes）： ```yaml mcp_servers: vision-augment: url: http://127.0.0.1:8000/mcp transport: streamable-http ``` > 注意：不要给 `streamable-http` 端点发送空 `params` 的 initialize 探测请求——SDK 会挂起该请求，用合法握手载荷探测。 ### 方式五：Docker 部署（streamable-http）直接使用 CI 构建发布的多架构镜像（`linux/amd64` + `linux/arm64`，发布到 Docker Hub / ghcr.io / 阿里云三个渠道，tag：`latest` / 日期 / `sha-<短hash>`）： ```bash docker compose up -d # 等价：docker run -d --name vision-augment -p 127.0.0.1:8000:8000 caomeiyouren/vision-augment ``` - 自定义镜像源：`DOCKER_IMAGE=ghcr.io/caomeiyouren/vision-augment docker compose up -d` - 通道/密钥等配置通过环境变量或 `.env` 注入，示例见 [docker-compose.yml](docker-compose.yml) - 本地开发构建：`docker build -t vision-augment .`（构建上下文直接安装源码，不依赖 PyPI）与 Hermes 同 compose 网络接入（共享 `networks` 后走容器名）： ```yaml mcp_servers: vision-augment: url: http://vision-augment:8000/mcp transport: streamable-http ``` ### 注册到其他客户端 `env` 字段用于注入通道配置与密钥（与 Hermes 示例中的 env 同理）；通道为空时自动探测本地 Ollama 兜底。 ```jsonc // Claude Desktop: claude_desktop_config.json { "mcpServers": { "vision-augment": { "command": "uvx", "args": ["vision-augment"], "env": { "VISION_AUGMENT_CHANNELS": "[{\"base_url\": \"https://api.example.com/v1\", \"api_key\": \"...\", \"model\": \"qwen3.7-plus\"}]" } } } } ``` ```jsonc // OpenCode: opencode.json（--from 指定 extras 可启用本地 OCR/文档引擎） { "mcp": { "vision-augment": { "type": "local", "command": ["uvx", "--from", "vision-augment[ocr,document]", "vision-augment"], "enabled": true, "env": { "VISION_AUGMENT_CHANNELS": "[{\"base_url\": \"https://api.example.com/v1\", \"api_key\": \"...\", \"model\": \"qwen3.7-plus\"}]" } } } } ``` > 注意：修改配置（通道/模型/extras）后需**重启客户端会话**——MCP server 在启动时加载 env，不重启仍是旧配置。 ## 工具 | 工具 | 说明 | | --- | --- | | `mcp_vision_augment_vision` | 入口：`task_type`（reasoning 看图问答 / ocr 图片文字 / document 文档解析）+ `source`（路径 / file:// / http(s):// / data:URL）+ `task` + `language` | | `mcp_vision_augment_health` | 环境探测：通道/Ollama/OCR/文档引擎配置状态（不含密钥），供 agent 反馈缺失配置 | | `mcp_vision_augment_clear_cache` | 清除本地结果缓存 | ## 安装与使用 Skill 仓库根目录的 `SKILL.md` 符合 [Agent Skills 规范](https://skills.sh/)，可通过 `npx skills` 生态一键安装（需仓库已公开）： ```bash # 全局安装到 opencode / hermes-agent npx skills add CaoMeiYouRen/vision-augment -g -a opencode -a hermes-agent -y # 或项目级安装（不指定 -g） npx skills add CaoMeiYouRen/vision-augment # 查看已安装 npx skills list ``` Skill 安装后 agent 的工作方式： 1. **环境探测**：优先调用 `mcp_vision_augment_health` 检查通道/Ollama/引擎状态，自动向你反馈还缺哪些配置及安装命令（如 `uvx vision-augment[ocr]`） 2. **任务路由**：看图 → `reasoning`；图片文字 → `ocr`；文档解析 → `document`，由 skill 指引 agent 选择 3. **故障闭环**：错误码 0-5 对应的处置路径写在 SKILL.md 中手动安装：把 `SKILL.md` 复制到 `~/.config/opencode/skills/vision-augment/`（opencode）或 `~/.hermes/skills/`（Hermes）等目录即可。 ## 配置（环境变量，均有默认值） | 变量 | 默认 | 说明 | | --- | --- | --- | | `VISION_AUGMENT_CHANNELS` | `[]` | OpenAI 兼容通道 JSON 数组 | | `VISION_AUGMENT_OLLAMA_URL` | `http://127.0.0.1:11434` | 本地 Ollama 地址 | | `VISION_AUGMENT_CACHE_TTL_SECONDS` | `86400` | 缓存 TTL（0=关闭） | | `VISION_AUGMENT_CACHE_DIR` | `~/.cache/vision-augment` | 缓存目录 | | `VISION_AUGMENT_MAX_INPUT_MB` | `50` | 输入大小上限 | | `VISION_AUGMENT_MAX_OUTPUT_CHARS` | `20000` | 输出截断上限 | | `VISION_AUGMENT_ALLOW_URLS` | `false` | 允许 http(s) 输入（防 SSRF，默认关闭） | | `VISION_AUGMENT_DEBUG` | `false` | DEBUG 日志 | | `VISION_AUGMENT_TRANSPORT` | `stdio` | 传输方式：`stdio` / `streamable-http` | | `VISION_AUGMENT_HOST` | `127.0.0.1` | HTTP 绑定地址 | | `VISION_AUGMENT_PORT` | `8000` | HTTP 端口 | 完整说明见 [docs/design.md](docs/design.md#10-配置-schema环境变量)。 ## 开发 ```bash uv sync # 安装开发环境（基础依赖） uv run pytest # 单元测试（不依赖重型引擎） uv run ruff check # 代码检查 ``` 安装可选引擎做集成验证： ```bash uv sync --extra ocr --extra document # RapidOCR + markitdown # 或全量：uv sync --all-extras（含 PaddleOCR，体积大） ``` ## 发布（CI 自动） push 到 `master` 后，[release workflow](.github/workflows/release.yml) 由 [python-semantic-release](https://python-semantic-release.readthedocs.io/) 根据 conventional commits 自动版本化（pyproject + `__version__` + CHANGELOG + tag + GitHub Release），并通过 **Trusted Publisher（OIDC，免 token）** 发布到 PyPI。 Trusted Publisher 配置（PyPI → Publishing → Trusted Publishers → Add pending publisher）： | 字段 | 值 | | --- | --- | | PyPI Project Name | `vision-augment` | | Owner | `CaoMeiYouRen` | | Repository name | `vision-augment` | | Workflow name | `release.yml` | | Environment name | 留空 | 首次发布后 `uvx vision-augment` 即生效。手动发布备选：`uv build && uv publish`（需 `UV_PUBLISH_TOKEN`）。 ## 文档 - [需求文档](docs/requirements.md)（含需求评估与未覆盖问题评估） - [设计文档](docs/design.md)（架构、envelope 契约、通道链、缓存、平台支持矩阵） - [SKILL.md](SKILL.md)（agent 使用技能） ## 许可证 [MIT](LICENSE) © 2026 CaoMeiYouRen

Loading the repository README…

Skills in this repository

Software Developers

1 occupation category · 100% classified

skill

occupation

description

updated

vision-augment

Software Developers

视觉增强 MCP —— 为无视觉能力的 LLM（如 DeepSeek、GLM）提供看图、OCR 与文档解析。当用户需要分析图片/截图内容、识别图片中的文字、解析 docx/pdf/pptx/xlsx/html 文档时使用。工具：mcp_vision_augment_vision（task_type=reasoning|ocr|document）、mcp_vision_augment_health（环境探测）、mcp_vision_augment_clear_cache。

Source text: Chinese

2026-10-31

Showing 1 of 1 collected skill.