dsh-multimodal-skill

dsh-multimodal-skill · 慧眼

<a id="top"></a> **🌐 中文** · **[English README](#english)** > **给纯文本 LLM 一双慧眼。** 一个 DeepSeek Harness（DSH）原生 skill + 零依赖 Python CLI， > 为 **DeepSeek** 等纯文本模型补上**图像理解**与**文档解析**（OCR、表格、公式、PDF → Markdown）， > 使用免费额度优先的三方多模态 API，国内网络直连、无需代理。 > > **核心特色 —— 🔄 内容寻址缓存**：相同文件 + 相同问题只调一次 API（sha256 指纹、磁盘落盘、 > 跨会话共享、TTL/LRU 自动淘汰），**避免重复请求、浪费免费额度**；再叠加零依赖 > （纯 Python 标准库）与自愈 provider 链（模型下线 / 限流 / 坏 key 自动切换），开箱即用。 https://img.shields.io/badge/%E8%AE%B8%E5%8F%AF%E8%AF%81-MIT-blue](LICENSE) https://img.shields.io/badge/Python-3.8%2B-3776AB](https://www.python.org/) https://img.shields.io/badge/%E9%9B%B6%E4%BE%9D%E8%B5%96-%E6%A0%87%E5%87%86%E5%BA%93-brightgreen](scripts/mm_cli.py) https://img.shields.io/badge/%E7%BC%93%E5%AD%98-%E5%86%85%E5%AE%B9%E5%AF%BB%E5%9D%80-28a745](#缓存) https://img.shields.io/badge/DSH-%E5%8E%9F%E7%94%9F%20skill-4B32C3](https://github.com/deepseek-ai/dsh)

慧眼

《慧眼》，灵感源自 1993 年的流行歌曲《雾里看花》。 作者在使用 DeepSeek 的过程中，仿佛听到它发出这样的呼唤：“借我借我一双慧眼吧，让我把这纷扰看得清清楚楚……”。 如今有了“慧眼-skill”，我终于可以对 DeepSeek 说：“帮我把这张截图看清楚”—— 它会自动调用 mm_cli.py，把 OCR/解析结果读回上下文，再回答你。 <!-- Demo (work in progress): --> <p align="left"> <img src="assets/demo.gif" alt="dsh-multimodal-skill demo" width="1000" /> </p>

为什么需要这个 skill？

**DeepSeek（以及许多编码模型）是纯文本的——它们看不见。** 当你把截图、PDF 或图表 交给 agent 时，模型无法理解。这个 skill 就是那座缺失的桥： `` 截图 / PDF / 图片 │ ▼ mm_cli.py（仅 Python 标准库 —— 无需 pip install、无需 venv） │ ├─ 文档 → Markdown (PaddleOCR-VL / MinerU / DeepSeek-OCR) └─ 图片 → 文本 (GLM-4V-Flash / Qwen3-VL / qwen-vl-max) │ ▼ Markdown / 文本 → 回到 LLM 上下文 ` 模型把提取出的 Markdown 当作自己的“视网膜”：忠实 OCR 与版面解析交给专用解析 API （一个 0.9B 的文档 VLM 在忠实解析上胜过前沿通用模型 —— OmniDocBench 基准）， 语义理解由文本模型自己完成。

特性亮点

- **零依赖** —— 只有一个 mm_cli.py，纯 Python 标准库（urllib/json/base64）。 无需 pip install、无需 requirements.txt、无需 venv。 - **免费优先** —— 每个默认 provider 都有慷慨的免费额度： PaddleOCR 官方 API（每模型 3000 页/日）、MinerU（免 key）、智谱 GLM-4V-Flash（完全免费）， 另有 SiliconFlow 与 DashScope 兜底。 - **国内网络友好** —— 默认 providers 全部国内可达，无需代理 （Gemini / Mistral / HuggingFace 国内不可达 —— 已剔除）。 - **自愈** —— 模型下线、限流（429）、队列满、key 失效全部自动处理： 候选模型轮换、provider 链切换、退避重试、短期失败记忆。 见 [references/troubleshooting.md](references/troubleshooting.md)。 - **格式感知路由** —— txt/md/csv/tsv 与本地 HTML 零模型成本本地解析 （stdlib 编码探测、csv → Markdown 表格、html.parser → Markdown）； docx/xlsx/pptx 自动路由到 MinerU 打头；PDF/图片走 PaddleOCR-first 链。 见 [references/formats.md](references/formats.md)。 - **内容寻址缓存** —— sha256(文件 + prompt + 模型) 作 key，TTL（文档 30 天 / 图片 24 小时）、 LRU 淘汰（2000 条 / 2GB）。省配额，让重试免费。 - **干净的输出纪律** —— 结果走 stdout、诊断走 stderr，退出码 0–6 供 agent 自动化。 - **面向 LLM 的提取元数据** —— 每次 doc parse 结果都带事实性 <!-- mm-meta: {...} --> 头（format、mode、provider、model、pages、stats、over）， 消费方 LLM 清楚知道是谁解析的，可自行决定信任与复核。绝不捏造置信度。 - **输出护栏** —— 交给 LLM 的每个字符串都经过可配置上限检查 （字节 / 行数 / 单行 / 估算 token，默认 64K token）。超限时不输出全文： 写入 UTF-8 文件并返回路径，由 LLM 用自己的工具读取/grep。绝不静默截断。

文档格式路由

doc parse 自动探测文件类型（magic bytes 优先、扩展名兜底）并按表格路由。 手动 --provider 可绕过路由（仅调试）。 | 格式 | 探测 | 路由 / 链头 | 本地零模型解析 | 备注 | |---|---|---|---|---| | PDF (.pdf) | %PDF magic | **paddleocr** → mineru → siliconflow | 否 | PaddleOCR 擅长扫描件/版面；≤100 页/文件（PaddleOCR），≤20 页/10MB（MinerU flash） | | 图片 PNG/JPEG/WebP/GIF/BMP | magic bytes | **paddleocr** → mineru → siliconflow | 否 | 可作为单页文档解析；问答走 image ask | | TIFF (.tif/.tiff) | II*\0 / MM\0* magic | **paddleocr** → mineru → siliconflow | 否 | 上游上报为 image/tiff | | Word/Excel/PPT (.docx/.xlsx/.pptx) | PK zip + [Content_Types].xml | **mineru**（其他 provider 无此能力，自动过滤） | 否 | MinerU 官方支持 Office；flash ≤10MB/20 页；大文件转 PDF | | 旧版 Office (.doc/.xls/.ppt) | OLE2 D0CF11E0 magic | 无 provider 支持 → **明确报错**并提示转 docx/pdf | 否 | 避免在不受支持的格式上浪费配额 | | 纯文本 .txt/.md/.tsv/.log/.json/.yaml 等 | 无 magic + 非二进制启发式 | **本地读取**（零配额、零延迟、数据不出本机） | ✅ | 编码自动探测：UTF-16（BOM/启发式）→ UTF-8 → GB18030 → Latin-1 | | CSV/TSV | 文本 + 扩展名 | **本地** csv → Markdown 表格 | ✅ | csv.Sniffer 自动识别分隔符；处理带引号的逗号/换行 | | 本地 HTML (.html/.htm) | 文本 + 扩展名 | **本地** html.parser → Markdown | ✅ | 标题/列表/表格/链接/图片/代码块；JS 渲染页面提取过短时回退 mineru | | 未知 | 无 magic、无扩展名匹配 | **先文本探测**（整文件可打印比例）→ 仍失败才报错 | 探测 | 报错信息列出所有支持格式 | 每次结果都带 <!-- mm-meta: {...} --> 头（--json 时为 meta 字段）： format（分组）、mode（local = 本地确定性解析 / model = 厂商模型）、 provider/model（实际解析器）、pages（厂商上报时）、stats（字节/行/token 测量） 与 over（超限标记）。超限时 paths.result 指向导出的 UTF-8 文件 （paths.source 指向原始本地文件）。skill 只报告事实—— 置信度判断与是否建议人工复核，留给消费方 LLM。

环境要求

| 要求 | 检查 | |---|---| | Python 3.8+ | python3 --version | | DeepSeek Harness（DSH） | dsh --version（dsh web / dsh CLI 均可） | | 至少一个 API key | 见[配置](#配置) | | 网络 | 国内直连（默认 providers）；无需代理 |

安装（DSH 原生 skill）

DSH 的 dsh-skill-filesystem 会自动扫描 ~/.dsh/skills/<name>/SKILL.md （另有项目级 .dsh/skills、.agents/skills、customSkillDirs 等根目录）。 **目录名必须与 frontmatter 的 name 完全一致**（kebab-case）。

方式一：软链接（推荐，单一事实来源）

`bash mkdir -p ~/.dsh/skills ln -sfn "$PWD" ~/.dsh/skills/dsh-multimodal-skill `

方式二：git clone（更新走 git pull）

`bash git clone https://github.com/v587d/dsh-multimodal-skill.git ~/.dsh/skills/dsh-multimodal-skill `

方式三：项目级目录（仅当前项目可用）

把 SKILL.md（连同 scripts/、references/）放进项目的 .dsh/skills/dsh-multimodal-skill/。 装好后**新开/重启一个 DSH 会话**，skill 目录里就会出现 dsh-multimodal-skill； 加载时 DSH 会给出资源根目录（含 scripts/、references/、assets/）， 下文 <skill_dir> 即该目录。

配置

1. API key（.env 或环境变量）

把 skill 目录下的 .env.example 复制为 .env（或直接导出环境变量）。 **建议至少配一个文档 provider + 一个图片 provider。** CLI 读取优先级： **系统环境变量 > .env**。 | 变量 | 服务 | 用途 | 获取地址 | |---|---|---|---| | PADDLEOCR_ACCESS_TOKEN | PaddleOCR 官方 API | 文档解析（默认） | https://aistudio.baidu.com/index/accessToken | | ZHIPUAI_API_KEY | 智谱 GLM | 图片理解（默认） | https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys | | MINERU_API_TOKEN | MinerU 精准 API | 文档解析（可选；flash 模式免 key） | https://mineru.net/apiManage | | SILICONFLOW_API_KEY | SiliconFlow | 图片 + 文档兜底 | https://cloud.siliconflow.cn/account/ak | | DASHSCOPE_API_KEY | 阿里云百炼 DashScope | 图片 + 文档（可选） | https://bailian.console.aliyun.com/ |

2. 可选：config.json（付费模型 / 自定义链）

`bash python3 <skill_dir>/scripts/mm_cli.py config open # 创建并打开 ~/.config/multimodal-skill/config.json ` 除 provider 链与模型候选外，limits 段为交给 LLM 的每个字符串把关（默认值均可配置）： | 检查项 | 键 | 默认 | 用途 | |---|---|---|---| | 总字节 | max_bytes | 5 MB | 整体大小上限 | | 总行数 | max_lines | 20000 | 防止超大行数 | | 单行字节 | max_line_bytes | 4096 | 防止压缩/Base64 大块 | | 估算 token | max_tokens | **64K** | 上下文预算（CJK 加权估算器，小翻译表精确计数 —— 实测约 96ms @ 5MB） | | 输入硬上限 | hard_max_bytes | 20 MB | 读文件前的 stat 预检 | 超限时不输出全文：CLI 写入 UTF-8 文件并返回路径（meta.paths.result； 本地文本输入还有 meta.paths.source），消费方 LLM 可用自己的工具读取/grep 片段。 cache clear 同时清理导出目录。 把付费/指定模型放在管线模型列表最前面即可优先使用 （如 "image_models": ["glm-4.5v", "glm-4v-flash"] —— 付费在前、免费兜底）。 完整模板见 [config.example.json](config.example.json)（JSONC 允许注释）。 快速查看：mm_cli.py providers。 > 注：provider 列表在代码中固定（每个 provider 协议不同）； > 配置只能覆盖模型候选与默认链 —— 不能新增 provider。

快速开始

`bash CLI=python3 <skill_dir>/scripts/mm_cli.py

0. 健康检查 —— 连通性、key、模型

$CLI doctor

1. 把截图粘贴到 DSH 对话 → 出现本地路径 → 提问

$CLI image ask /path/to/screenshot.png "这个报错是什么？"

2. 解析文档（PDF/扫描件/图片）为 Markdown

$CLI doc parse report.pdf --pages 1-20 --out report.md

3. 本地文本/CSV/HTML 本地解析 —— 零配额、零延迟

$CLI doc parse notes.csv # → Markdown 表格 $CLI doc parse page.html # → html.parser 转 Markdown

4. 零配置兜底（MinerU flash，免 key）

$CLI doc parse scan.pdf --provider mineru

5. 超限输出落盘；CLI 返回路径，由 LLM 自行 grep

$CLI doc parse huge.log # → 输出超限，返回落盘路径，由 LLM 自行 grep ` 完整命令参考：[references/api.md](references/api.md)。

Providers 与免费额度（2026-08 实测）

| Provider | 管线 | 免费额度 | 国内可达 | |---|---|---|---| | PaddleOCR 官方 API | 文档 | **每模型 3000 页/日**（异步任务 API） | ✅ | | MinerU | 文档 | flash：免费、免 key、≤20 页/10MB；精准：1000 页/日高优 | ✅ | | SiliconFlow DeepSeek-OCR | 文档 | 免费额度实测零扣费 | ✅ | | 智谱 GLM-4V-Flash | 图片 | 完全免费（GLM-4.6V-Flash 免费，高峰繁忙） | ✅ | | SiliconFlow Qwen3-VL | 图片 | 按量计费（便宜） | ✅ | | DashScope qwen-vl-max/ocr | 图片 + 文档 | 每模型约 100 万 token 免费（90 天） | ✅ |

安全

- key 存放在 .env（权限 600）或环境变量 —— 绝不硬编码；.env 与 config.json 已 gitignore。 - **免费档可能用提交的数据训练**（各 provider 通用政策）—— 不要把机密文档/截图发给免费档； 敏感材料请用付费模型（经 config.json）。 - CLI 绝不自动执行 API 响应中的任何内容；输出为 stdout 上的纯文本/Markdown。 - 报错信息可能回显 provider 响应 —— 不要把你发给解析 API 的文件里塞入机密。

缓存

缓存**纯磁盘、文件化** —— 无内存状态、无守护进程、无加载/退出周期。 每次 CLI 调用都是全新进程，直接读写磁盘条目（写穿）： - **key** = 内容寻址 sha256(文件字节 + 管线 + provider + 模型 + prompt + 参数)；文件名即 key。 - **TTL** 读取时惰性检查：文档 30 天、图片 24 小时（--ttl / --no-cache 覆盖）。 - **LRU** 写入时目录扫描淘汰：2000 条 / 2GB 上限，最早访问的先丢。 简言之：一个 *缓存风味的文件算子* —— 崩溃安全、跨会话共享 （一个会话里解析过的，下一个会话直接省配额）。

工作原理

两条管线（行业最佳实践：忠实解析与开放视觉分开）： - **doc parse** —— 专用文档解析器 → Markdown（表格、LaTeX 公式、阅读顺序）。 PaddleOCR-VL-1.6 属 OmniDocBench SOTA 级别。 - **image ask** —— OpenAI 兼容 VLM 对话，面向截图/照片/图表。 每次调用都走自适应链：按序尝试模型候选 → 模型下线/限流/鉴权失败时轮换或切换 provider → 聚合错误并给出有意义的退出码（2 用法 / 3 鉴权 / 4 限流 / 5 模型 / 6 网络）。

故障排查

常见问题（PaddleOCR 排队慢、GLM 429、MinerU 上传签名、中文输出乱码、缓存怪癖）： [references/troubleshooting.md](references/troubleshooting.md)。

License

[MIT](LICENSE) ---

English

> **[中文版（默认）](#top)** · English > **Give text-only LLMs eyes.** A DeepSeek Harness (DSH) native skill + a > zero-dependency Python CLI that adds **image understanding** and **document > parsing** (OCR, tables, formulas, PDF → Markdown) to any text-only model such > as **DeepSeek**, using free-tier-first third-party multimodal APIs. All > default providers are reachable from mainland China without a proxy. > > **Key feature — 🔄 content-addressed caching**: the same file + the same > prompt hits the API only once (sha256 fingerprint, disk-backed, shared > across sessions, auto-evicted via TTL/LRU) — **no repeated requests, no > wasted free quota** — on top of zero dependencies (pure Python stdlib) and a > self-healing provider chain (auto-rotation on model deprecation / rate > limits / bad keys).

Why this skill?

**DeepSeek (and many coding models) are text-only — they cannot see.** When you paste a screenshot, a PDF, or a chart into your agent, the model has no way to understand it. This skill is that missing bridge: ` screenshot / PDF / image │ ▼ mm_cli.py (Python stdlib only — no pip install, no venv) │ ├─ document → Markdown (PaddleOCR-VL / MinerU / DeepSeek-OCR) └─ image → text (GLM-4V-Flash / Qwen3-VL / qwen-vl-max) │ ▼ Markdown/text → back into the LLM's context ` The model reads the extracted Markdown as its "retina": faithful OCR and layout parsing are delegated to specialist APIs (a 0.9B document VLM beats frontier models on faithful parsing — OmniDocBench), while the text model handles semantics.

Highlights

- **Zero dependencies** — one mm_cli.py, pure Python standard library (urllib/json/base64). No pip install, no requirements.txt, no venv. - **Free-first** — every default provider has a generous free tier: PaddleOCR official API (3,000 pages/day/model), MinerU (free, no key), Zhipu GLM-4V-Flash (fully free), plus SiliconFlow & DashScope fallbacks. - **China-network friendly** — all default providers are mainland-reachable; no proxy required. (Gemini/Mistral/HuggingFace are blocked from CN — dropped.) - **Self-healing** — model deprecation, rate limits (429), queue-full, and bad keys are handled automatically: candidate-model rotation, provider fallback chains, backoff, and a short-lived failure memory. See [references/troubleshooting.md](references/troubleshooting.md). - **Format-aware routing** — txt/md/csv/tsv and local HTML are parsed locally with zero model cost (stdlib encoding detection, csv → Markdown tables, html.parser → Markdown); docx/xlsx/pptx auto-route to MinerU as chain head; PDF/images keep the PaddleOCR-first chain. See [references/formats.md](references/formats.md). - **Content-addressed caching** — sha256(file + prompt + model) keys, TTL (30d documents / 24h images), LRU eviction (2,000 entries / 2 GB). Saves quota, makes retries free. - **Clean output discipline** — results to stdout, diagnostics to stderr, exit codes 0–6 for agent automation. - **LLM-facing extraction metadata** — every doc parse result carries a factual <!-- mm-meta: {...} --> header (format, mode, provider, model, pages, stats, over) so the consuming LLM knows exactly who parsed the file and can decide trust/verification itself. Never fabricated confidence scores. - **Output guardrails** — every string handed to the LLM is checked against configurable limits (bytes / lines / single-line / estimated tokens, default 64K tokens). On over-limit the full text is **not** emitted: it is written to a UTF-8 file and the path is returned, so the LLM reads/greps snippets with its own harness tools. Never silently truncated.

Document format routing

doc parse auto-detects the file type (magic bytes first, extension fallback) and routes accordingly. Manual --provider bypasses routing (debug only). | Format | Detection | Route / chain head | Local zero-model parse | Notes | |---|---|---|---|---| | PDF (.pdf) | %PDF magic | **paddleocr** → mineru → siliconflow | No | PaddleOCR excels at scans/layout; ≤100 pages/file (PaddleOCR), ≤20 pages/10MB (MinerU flash) | | Images PNG/JPEG/WebP/GIF/BMP | magic bytes | **paddleocr** → mineru → siliconflow | No | Parsable as single-page docs; Q&A via image ask | | TIFF (.tif/.tiff) | II*\0 / MM\0* magic | **paddleocr** → mineru → siliconflow | No | Reported upstream as image/tiff | | Word/Excel/PPT (.docx/.xlsx/.pptx) | PK zip + [Content_Types].xml | **mineru** (other providers lack this capability and are filtered out) | No | MinerU officially supports Office; flash ≤10MB/20 pages; convert large files to PDF | | Legacy Office (.doc/.xls/.ppt) | OLE2 D0CF11E0 magic | No provider support → **clear error** with convert-to-docx/pdf hint | No | Avoid wasting quota on unsupported formats | | Plain text .txt/.md/.tsv/.log/.json/.yaml etc. | no magic + non-binary heuristic | **local read** (zero quota, zero latency, data never leaves the machine) | ✅ | Encoding auto-detection: UTF-16 (BOM/heuristic) → UTF-8 → GB18030 → Latin-1 | | CSV/TSV | text + extension | **local** csv → Markdown table | ✅ | csv.Sniffer auto-detects delimiter; handles quoted commas/newlines | | Local HTML (.html/.htm) | text + extension | **local** html.parser → Markdown | ✅ | Headings/lists/tables/links/images/code blocks; falls back to mineru when extraction is too short (JS-rendered pages) | | Unknown | no magic, no extension match | **text probe first** (printable ratio over whole file) → error only if that fails | probe | Error message lists all supported formats | Every result carries a <!-- mm-meta: {...} --> header (meta field with --json): format (group), mode (local = deterministic local parse / model = vendor model), provider/model (actual parser), pages (when the vendor reports it), stats (bytes/lines/tokens measurements) and over (limit flags). When over-limit, paths.result points to the exported UTF-8 file (and paths.source to the original local file). The skill reports facts only — confidence judgment and whether to suggest manual verification are left to the consuming LLM.

Requirements

| Requirement | Check | |---|---| | Python 3.8+ | python3 --version | | DeepSeek Harness (DSH) | dsh --version (dsh web or dsh CLI) | | At least one API key | see [Configuration](#configuration) | | Network | mainland China OK (defaults); no proxy needed |

Install (DSH native skill)

DSH's dsh-skill-filesystem automatically scans ~/.dsh/skills/<name>/SKILL.md (plus project-level .dsh/skills, .agents/skills, customSkillDirs, etc.). **The directory name must exactly match the name in the frontmatter** (kebab-case).

Option 1: symlink (recommended — single source of truth)

`bash mkdir -p ~/.dsh/skills ln -sfn "$PWD" ~/.dsh/skills/dsh-multimodal-skill `

Option 2: git clone (updates via git pull)

`bash git clone https://github.com/v587d/dsh-multimodal-skill.git ~/.dsh/skills/dsh-multimodal-skill `

Option 3: project-level directory (this project only)

Put SKILL.md (with scripts/, references/) into your project's .dsh/skills/dsh-multimodal-skill/. After installing, **start/restart a DSH session** and dsh-multimodal-skill will appear in the skill catalog. When loaded, DSH provides the resource base directory (containing scripts/, references/, assets/) — <skill_dir> below refers to that directory.

Configuration

1. API keys (.env or environment variables)

Copy .env.example to .env in the skill directory (or export the variables). **At least one document provider + one image provider is recommended.** The CLI reads keys with priority: **system environment > .env**. | Variable | Service | Used for | Where to get it | |---|---|---|---| | PADDLEOCR_ACCESS_TOKEN | PaddleOCR official API | document parsing (default) | https://aistudio.baidu.com/index/accessToken | | ZHIPUAI_API_KEY | Zhipu GLM | image understanding (default) | https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys | | MINERU_API_TOKEN | MinerU precision API | document parsing (optional; flash mode needs no key) | https://mineru.net/apiManage | | SILICONFLOW_API_KEY | SiliconFlow | image + document fallback | https://cloud.siliconflow.cn/account/ak | | DASHSCOPE_API_KEY | Alibaba DashScope | image + document (optional) | https://bailian.console.aliyun.com/ |

2. Optional: config.json (paid models / custom chains)

`bash python3 <skill_dir>/scripts/mm_cli.py config open # creates & opens ~/.config/multimodal-skill/config.json ` Beyond provider chains and model candidates, the limits section guards every string handed to the LLM (defaults; all configurable): | Check | Key | Default | Purpose | |---|---|---|---| | Total bytes | max_bytes | 5 MB | overall size cap | | Total lines | max_lines | 20000 | guards huge line counts | | Single-line bytes | max_line_bytes | 4096 | guards minified/base64 blobs | | Estimated tokens | max_tokens | **64K** | context budget (CJK-weighted estimator, exact CJK count via small translate table — benchmarked ~96ms @ 5MB) | | Input hard cap | hard_max_bytes | 20 MB | stat pre-check before reading the file | On over-limit the full text is **not** emitted: the CLI writes it to a UTF-8 file and returns the path (meta.paths.result; plus meta.paths.source for local text inputs), so the consuming LLM can read/grep snippets with its own tools. cache clear also cleans the export directory. Put paid/any model IDs first in a pipeline's model list to prefer them (e.g. "image_models": ["glm-4.5v", "glm-4v-flash"] — paid first, free fallback). See [config.example.json](config.example.json) for the full template (JSONC comments allowed). Quick look: mm_cli.py providers. > Note: the provider list is fixed in code (each provider speaks a different > protocol); configuration can only override model candidates and default > chains — it cannot add providers.

Quick start

`bash CLI=python3 <skill_dir>/scripts/mm_cli.py

0. Health check — connectivity, keys, models

$CLI doctor

1. Paste a screenshot into the DSH chat → you get a local path → ask about it

$CLI image ask /path/to/screenshot.png "What error is shown here?"

2. Parse a document (PDF/scanned/image) into Markdown

$CLI doc parse report.pdf --pages 1-20 --out report.md

3. Local text/CSV/HTML is parsed locally — zero quota, zero latency

$CLI doc parse notes.csv # → Markdown table $CLI doc parse page.html # → Markdown via html.parser

4. Zero-config fallback (MinerU flash, no key needed)

$CLI doc parse scan.pdf --provider mineru

5. Over-limit output is exported to disk; the CLI returns the path

$CLI doc parse huge.log # → 输出超限，返回落盘路径，由 LLM 自行 grep ` Full command reference: [references/api.md](references/api.md).

Providers & free tiers (verified 2026-08)

| Provider | Pipeline | Free tier | Reachable from CN | |---|---|---|---| | PaddleOCR official API | document | **3,000 pages/day/model** (async job API) | ✅ | | MinerU | document | flash: free, no key, ≤20 pages/10MB; precision: 1,000 pages/day high-priority | ✅ | | SiliconFlow DeepSeek-OCR | document | measured zero-cost on free credit | ✅ | | Zhipu GLM-4V-Flash | image | fully free (GLM-4.6V-Flash free, busy at peak) | ✅ | | SiliconFlow Qwen3-VL | image | pay-per-use (cheap) | ✅ | | DashScope qwen-vl-max/ocr | image + document | ~1M tokens/model free (90 days) | ✅ |

Security

- Keys live in .env (permission 600) or environment variables — never hardcoded; .env and config.json are gitignored. - **Free tiers may train on submitted data** (a common policy across all providers) — do not send confidential documents/screenshots to free tiers. Use paid models (via config.json) for sensitive material. - The CLI never auto-executes anything from API responses; outputs are plain text/Markdown on stdout. - Error messages may echo provider responses — don't paste secrets into files you send to parsing APIs.

Caching

Cache is **disk-only, file-backed** — no memory state, no daemon, no load-on-start / flush-on-exit cycle. Every CLI invocation is a fresh process that reads and writes entries directly on disk (write-through): - **Key** = content-addressed sha256(file bytes + pipeline + provider + model + prompt + params); file name *is* the key. - **TTL** checked lazily on read: 30 days for documents, 24 h for images (--ttl / --no-cache to override). - **LRU** eviction by directory scan on write: 2,000 entries / 2 GB cap, oldest-accessed dropped first. In short: a *cache-flavored file operator* — crash-safe, survives restarts, and shared across sessions (a parse cached in one session is a quota saved in the next).

How it works

Two pipelines (industry best practice: keep faithful parsing separate from open-ended vision): - **doc parse** — specialist document parsers → Markdown (tables, LaTeX formulas, reading order). PaddleOCR-VL-1.6 is OmniDocBench SOTA class. - **image ask** — OpenAI-compatible VLM chat for screenshots/photos/charts. Every call runs through an adaptive chain: try model candidates in order → on model-deprecation/rate-limit/auth failure, rotate or switch provider → aggregate error with a meaningful exit code (2 usage / 3 auth / 4 rate / 5 model / 6 network).

Troubleshooting

Common issues (PaddleOCR slow queue, GLM 429s, MinerU upload signature, Chinese output garbling, cache quirks): [references/troubleshooting.md`](references/troubleshooting.md).

License

[MIT](LICENSE)