慧眼识图 v587d/dsh-multimodal-skill

dsh-multimodal-skill · 慧眼

🌐 中文 · English README

给纯文本 LLM 一双慧眼。 一个 DeepSeek Harness（DSH）原生技能 + 零依赖 Python 命令行，为 DeepSeek 等纯文本模型补上图像理解与文档解析（OCR、表格、公式、PDF → Markdown），使用免费额度优先的三方多模态 API，国内网络直连、无需代理。

核心特色 —— 🔄 内容寻址缓存：相同文件 + 相同问题只调一次 API（sha256 指纹、磁盘落盘、跨会话共享、TTL/LRU 自动淘汰），避免重复请求、浪费免费额度；再叠加零依赖（纯 Python 标准库）与自愈服务商链（模型下线 / 限流 / 坏 key 自动切换），开箱即用。

慧眼

《慧眼》，灵感源自 1993 年的流行歌曲《雾里看花》。
作者在使用 DeepSeek 的过程中，仿佛听到它发出这样的呼唤：“借我借我一双慧眼吧，让我把这纷扰看得清清楚楚……”。
如今有了“慧眼-skill”，我终于可以对 DeepSeek 说：“帮我把这张截图看清楚”——它会自动调用 mm_cli.py，把 OCR/解析结果读回上下文，再回答你。

为什么需要这个技能？

DeepSeek（以及许多编码模型）是纯文本的——它们看不见。 当你把截图、PDF 或图表交给智能体时，模型无法理解。这个技能就是那座缺失的桥：

截图 / 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。
- 免费优先 —— 每个默认服务商都有慷慨的免费额度： PaddleOCR 官方 API（每模型 3000 页/日）、MinerU（免 key）、智谱 GLM-4V-Flash（完全免费），另有 SiliconFlow 与 DashScope 兜底。
- 国内网络友好 —— 默认服务商全部国内可达，无需代理（Gemini / Mistral / HuggingFace 国内不可达 —— 已剔除）。
- 自愈 —— 模型下线、限流（429）、队列满、key 失效全部自动处理：候选模型轮换、服务商链切换、退避重试、短期失败记忆。
见 references/troubleshooting.md。
- 格式感知路由 —— txt/md/csv/tsv 与本地 HTML 零模型成本本地解析（stdlib 编码探测、csv → Markdown 表格、html.parser → Markdown）； docx/xlsx/pptx 自动路由到 MinerU 打头；PDF/图片走 PaddleOCR-first 链。
见 references/formats.md。
- 内容寻址缓存 —— sha256(文件 + prompt + 模型) 作 key，TTL（文档 30 天 / 图片 24 小时）、 LRU 淘汰（2000 条 / 2GB）。省配额，让重试免费。
- 干净的输出纪律 —— 结果走 stdout、诊断走 stderr，退出码 0–6 供智能体自动化。
- 面向 LLM 的提取元数据 —— 每次 doc parse 结果都带事实性 头（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、无扩展名匹配 | 先文本探测（整文件可打印比例）→ 仍失败才报错 | 探测 | 报错信息列出所有支持格式 |

每次结果都带 头（--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）。

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

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

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

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（付费模型 / 自定义链）

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（JSONC 允许注释）。
快速查看：mm_cli.py providers。

注：provider 列表在代码中固定（每个 provider 协议不同）；配置只能覆盖模型候选与默认链 —— 不能新增 provider。

快速开始

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。

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 对话，面向截图/照片/图表。
每次调用都走自适应链：按序尝试模型候选 → 模型下线/限流/鉴权失败时轮换或切换服务商 → 聚合错误并给出有意义的退出码（2 用法 / 3 鉴权 / 4 限流 / 5 模型 / 6 网络）。

故障排查

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

License

MIT

中文版（默认） · English

给纯文本 LLM 装上眼睛。 一个 DeepSeek Harness（DSH）原生技能 + 一个零依赖 Python 命令行工具，为 DeepSeek 等纯文本模型补上图像理解与文档解析（OCR、表格、公式、PDF → Markdown），底层调用免费额度优先的第三方多模态 API。所有默认服务商在中国大陆均可直连，无需代理。

核心特性 —— 🔄 内容寻址缓存：同一文件 + 同一提示词只请求一次 API（sha256 指纹，落盘存储，跨会话共享，按 TTL/LRU 自动淘汰）—— 不重复请求，不浪费免费额度 —— 此外还有零依赖（纯 Python 标准库）与自愈式服务商链（模型下线 / 限流 / 密钥失效时自动轮换）。

为什么需要这个技能？

DeepSeek（以及许多编程模型）是纯文本的 —— 它们看不见。 当你把截图、PDF 或图表粘贴进智能体时，模型无从理解。这个技能就是那座缺失的桥：

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

模型把提取出的 Markdown 当作自己的「视网膜」：忠实的 OCR 与版面解析交给专业 API（在忠实解析上，0.9B 的文档 VLM 能胜过前沿模型 —— OmniDocBench），文本模型只管语义。

亮点

- 零依赖 —— 一个 mm_cli.py，纯 Python 标准库（urllib/json/base64）。不用 pip install，没有 requirements.txt，不用 venv。
- 免费优先 —— 每个默认服务商都有慷慨的免费额度：PaddleOCR 官方 API（每模型每天 3,000 页）、MinerU（免费，无需密钥）、智谱 GLM-4V-Flash（完全免费），另有 SiliconFlow 与 DashScope 兜底。
- 对国内网络友好 —— 所有默认服务商在中国大陆均可直连，无需代理。（Gemini/Mistral/HuggingFace 在国内被墙 —— 已移除。）
- 自愈 —— 模型下线、限流（429）、队列满、密钥失效都能自动处理：候选模型轮换、服务商兜底链、退避，以及短期失败记忆。见 references/troubleshooting.md。
- 按格式路由 —— txt/md/csv/tsv 与本地 HTML 在本地解析，零模型开销（标准库编码探测，csv → Markdown 表格，html.parser → Markdown）；docx/xlsx/pptx 自动路由到 MinerU 作为链首；PDF/图片沿用 PaddleOCR 优先的链。见 references/formats.md。
- 内容寻址缓存 —— 键为 sha256(file + prompt + model)，带 TTL（文档 30 天 / 图片 24 小时），LRU 淘汰（2,000 条 / 2 GB）。省配额，重试不花钱。
- 输出纪律 —— 结果走 stdout，诊断信息走 stderr，退出码 0–6 供智能体自动化使用。
- 面向 LLM 的提取元数据 —— 每个 doc parse 结果都带一个事实性的 头（format、mode、provider、model、pages、stats、over），让消费结果的 LLM 清楚知道是谁解析了这个文件，自己判断可信度、决定要不要验证。绝不编造置信度分数。
- 输出护栏 —— 交给 LLM 的每个字符串都要对照可配置上限检查（字节数 / 行数 / 单行 / 估算 token 数，默认 64K token）。超限时不输出全文：写入 UTF-8 文件并返回路径，LLM 用自己的 harness 工具读取或 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（其他服务商没有这个能力，会被过滤掉） | 否 | MinerU 官方支持 Office；flash ≤10MB/20 页；大文件请转成 PDF |
| 旧版 Office（.doc/.xls/.ppt） | OLE2 D0CF11E0 magic | 没有服务商支持 → 明确报错，提示转成 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 | ✅ | 标题/列表/表格/链接/图片/代码块；提取内容太短时回退到 mineru（JS 渲染的页面） |
| 未知 | 无 magic，扩展名也不匹配 | 先做文本探测（全文件可打印字符比例）→ 只有探测也失败才报错 | 探测 | 报错信息会列出所有支持的格式 |
每条结果都带一个 头（加 --json 时是 meta 字段）：format（分组）、mode（local = 本地确定性解析 / model = 厂商模型）、provider/model（实际解析器）、pages（厂商有上报时才有）、stats（字节/行数/token 统计）和 over（超限标记）。超限时，paths.result 指向导出的 UTF-8 文件（paths.source 指向原始本地文件）。技能只报告事实——置信度判断、是否建议人工复核，都交给调用它的 LLM。

环境要求

| 要求 | 检查方式 |
| Python 3.8+ | python3 --version |
| DeepSeek Harness (DSH) | dsh --version（dsh web 或 dsh CLI） |
| 至少一个 API key | 见配置 |
| 网络 | 中国大陆可用（默认）；无需代理 |

安装（DSH 原生技能）

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

方案 1：软链接（推荐——单一数据源）

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

方案 2：git clone（用 git pull 更新）

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

方案 3：项目级目录（只对当前项目生效）

把 SKILL.md（连同 scripts/、references/）放进项目的 .dsh/skills/dsh-multimodal-skill/。

安装完成后，启动或重启 DSH 会话，dsh-multimodal-skill 就会出现在技能目录里。加载时，DSH 会提供资源根目录（包含 scripts/、references/、assets/）——下文中的 <skill_dir> 指的就是这个目录。

配置

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

把 .env.example 复制到技能目录下的 .env（或者直接导出环境变量）。建议至少配一个文档服务商 + 一个图像服务商。 命令行读取 key 的优先级：系统环境 > .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（付费模型 / 自定义链路）

python3 <skill_dir>/scripts/mm_cli.py config open # creates & opens ~/.config/multimodal-skill/config.json
除了服务商链和模型候选之外，limits 段还会守住交给 LLM 的每一段字符串（以下都是默认值，全部可配置）：

| 检查项 | 键 | 默认值 | 用途 |
| 总字节数 | max_bytes | 5 MB | 整体大小上限 |
| 总行数 | max_lines | 20000 | 防止行数过多 |
| 单行字节数 | max_line_bytes | 4096 | 防止压缩过的 / base64 大块内容 |
| 估算 token 数 | max_tokens | 64K | 上下文预算（按 CJK 加权的估算器，CJK 字符数通过小型转换表精确统计——实测 5MB 约 96ms） |
| 输入硬上限 | hard_max_bytes | 20 MB | 读取文件前先做 stat 预检 |

超出限制时，不会输出全文：命令行会把全文写入 UTF-8 文件并返回路径（meta.paths.result；本地文本输入还会返回 meta.paths.source），这样消费端的 LLM 可以用自己的工具读取或 grep 片段。cache clear 也会清理导出目录。

把付费 / 任意模型 ID 放在流水线模型列表的最前面，就会优先使用它们（例如 "image_models": ["glm-4.5v", "glm-4v-flash"] —— 付费的在前，免费的兜底）。完整模板见 config.example.json（允许 JSONC 注释）。快速查看：mm_cli.py providers。

注意：服务商列表在代码里写死（每家服务商说的协议都不一样）；配置只能覆盖模型候选和默认链——不能新增服务商。

快速开始

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

完整命令参考：references/api.md。

服务商与免费额度（2026-08 核实）

| 服务商 | 流水线 | 免费额度 | 国内可访问 |
| PaddleOCR 官方 API | 文档 | 3,000 页/天/模型（异步任务 API） | ✅ |
| MinerU | 文档 | flash：免费，无需 key，≤20 页/10MB；precision：1,000 页/天高优先级 | ✅ |
| SiliconFlow DeepSeek-OCR | 文档 | 实测免费额度内零成本 | ✅ |
| Zhipu 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。
- 免费档可能会用提交的数据做训练（所有服务商的常见政策）——不要把机密文档或截图发给免费档。敏感材料请用付费模型（通过 config.json 配置）。
- 命令行绝不会自动执行 API 响应里的任何内容；输出只是 stdout 上的纯文本或 Markdown。
- 错误信息可能会回显服务商的响应——不要把密钥粘进你发给解析 API 的文件里。

缓存

缓存只落盘、由文件承载——没有内存状态，没有守护进程，没有启动加载、退出刷写的循环。每次调用命令行都是全新进程，直接在磁盘上读写条目（写穿）：

- 键 = 内容寻址的 sha256(file bytes + pipeline + provider + model + prompt + params)；文件名就是键。
- TTL 在读取时惰性检查：文档 30 天，图片 24 小时（用 --ttl / --no-cache 覆盖）。
- LRU 淘汰在写入时扫描目录：上限 2,000 条 / 2 GB，最久未访问的先丢。

一句话：带缓存味道的文件操作器——崩溃安全，重启后仍在，跨会话共享（一个会话里缓存的解析结果，就是下一个会话省下的配额）。

工作原理

两条流水线（业界最佳实践：把忠实解析和开放式视觉分开）：

- doc parse —— 专用文档解析器 → Markdown（表格、LaTeX 公式、阅读顺序）。PaddleOCR-VL-1.6 属于 OmniDocBench SOTA 级别。
- image ask —— 兼容 OpenAI 的 VLM 对话，用于截图、照片、图表。

每次调用都走一条自适应链：按顺序尝试候选模型 → 遇到模型弃用、限流、鉴权失败时轮换或切换服务商 → 汇总错误并给出有意义的退出码（2 用法 / 3 鉴权 / 4 限流 / 5 模型 / 6 网络）。

故障排查

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

许可证

MIT