API 参考（mm_cli.py）

python3 <skill_dir>/scripts/mm_cli.py <command> [args]

环境变量（官方命名，也可放 skill 目录 .env）： ZHIPUAI_API_KEY / PADDLEOCR_ACCESS_TOKEN / MINERU_API_TOKEN / SILICONFLOW_API_KEY / DASHSCOPE_API_KEY。 优先级：CLI 参数 > 系统环境变量 > .env。

用户配置（config.json）—— 付费模型 / 自定义默认链

配置文件按优先级合并（先到先覆盖）：MM_SKILL_CONFIG 环境变量指向的文件 > ~/.config/multimodal-skill/config.json > skill 目录 config.json。

注意：宿主（Pi / DeepSeek Harness 等）没有 skill 级配置机制，也不会自动迁移 skill 项目里的配置 —— 需手动 config open 创建或复制 config.example.json。 用户配置放 ~/.config/... 可避免 git 更新 skill 时被覆盖。

Provider 列表不可扩展（各 provider 协议不同，由代码内置；mm_cli.py providers 查看全部）；配置只能覆盖模型候选与默认链。配置文件支持 JSONC（// 注释）。

// config.json (JSONC — comments allowed)
{
  "doc_chain": ["paddleocr", "mineru", "siliconflow"],   // providers serving `doc parse`
  "image_chain": ["zhipu", "siliconflow", "dashscope"], // providers serving `image ask`
  "limits": {                                            // 输出校验上限（超限策略待定）
    "max_bytes": 5242880,        // 输出总字节（默认 5MB）
    "max_lines": 20000,          // 输出总行数
    "max_line_bytes": 4096,      // 单行字节上限
    "max_tokens": 65536,         // 估算 token 上限（默认 64K，CJK 加权估算）
    "hard_max_bytes": 20971520   // 输入文件硬上限（stat 预检）
  },
  "providers": {
    "zhipu": {
      "image_models": ["glm-4.5v", "glm-4.6v", "glm-4v-flash"]  // paid models first; tried in order
    },
    "siliconflow": {
      "image_models": ["Qwen/Qwen3-VL-32B-Instruct"],
      "doc_models": ["deepseek-ai/DeepSeek-OCR"]
    }
  }
}

• image_models → image ask；doc_models → doc parse；ocr_models → doc parse --is-ocr
• 付费/任意模型 ID 可直接写入（最优先尝试）；不可用时自动轮换下一个候选。
• 完整模板（全部 5 个 provider、英文注释）见 config.example.json。
• 管理命令：config path（生效路径）/ config show（合并后配置）/ config open （默认编辑器打开，跨平台：Windows os.startfile / macOS open / Linux $VISUAL/$EDITOR/xdg-open）。
• 单次临时覆盖：--model <任意模型ID> 同样会被优先尝试。

退出码

0 成功 / 1 运行时 / 2 用法错误 / 3 鉴权 / 4 限流配额 / 5 模型不可用 / 6 网络。

doctor

mm_cli.py doctor [--provider paddleocr] [--provider zhipu] ...

• 先重置探测缓存，再逐 provider 体检：key 是否存在、连通性、模型列表（siliconflow）。
• zhipu 用免费文本模型真实 ping；paddleocr 探测任务路由。

doc parse — 文档/PDF/图片 → Markdown

mm_cli.py doc parse <file|url> [选项]

选项	说明
--provider	paddleocr / mineru / siliconflow（调试用；缺省按格式感知自动路由：pdf/图片→paddleocr→mineru→siliconflow，docx/xlsx/pptx→mineru，txt/md/csv/html→本地零模型解析）
--model	覆盖模型名；无效名会自动轮换候选
--pages	页码范围，如 1-20 或 2,4-6（PaddleOCR 的 pageRanges / MinerU 的 page_range）
--language	文档语言，默认 ch（MinerU 用）
--is-ocr	强制 OCR（扫描件无文本层时用）
--precision	MinerU 走精准 v4 API（只接受 URL，需 MINERU_API_TOKEN；1000 页/日高优）
--prompt	自定义转换指令（OpenAI 兼容 provider）
--out FILE	结果写入文件（大文档推荐）
--json	结构化输出 {provider, model, usage, meta, text, cache}；meta = 解析事实（format/mode/provider/model/pages）+ stats/over（三校验统计与超限标记）
--no-cache / --ttl N	绕过缓存 / 覆盖缓存 TTL（秒，默认 30 天）
--timeout N	轮询总超时（秒，默认 600）

格式感知路由（详见 formats.md）：

• 本地零配额：txt/md/tsv/log/json/yaml 直读（编码自动探测）；csv/tsv → Markdown 表格； 本地 html → html.parser 提取 Markdown（JS 渲染页自动回退 MinerU）。
• office：docx/xlsx/pptx 链首为 mineru（flash 免 key）；.doc/.xls/.ppt 报错提示转换。
• pdf/图片：默认链 paddleocr → mineru → siliconflow 不变。

输出元信息（面向 LLM 消费方，只含事实）：文本模式输出头为 <!-- mm-meta: {...} --> 注释，--json 时为 meta 字段： format（检测分组）、mode（local=本地确定性解析 / model=解析模型厂商）、 provider/model（实际解析者）、pages（厂商返回的实际页数）、 stats（bytes/lines/max_line_bytes/tokens 事实测量）、over（三校验 + token 超限标记）。 限制值在 config.json 的 limits 段配置（默认：5MB / 20000 行 / 4096 单行 / 64K tokens / 输入硬上限 20MB）。超限策略：全文不输出，落盘为 UTF-8 文件并返回路径 （meta.paths.result，--out 指定时用之；本地文件另附 meta.paths.source）， 由消费方 LLM 用自带 read/grep 工具读取片段。 skill 不输出置信度/质量推断，判断权交给消费方 LLM。

provider 差异：

• paddleocr：异步任务（提交→轮询→JSONL），可上传本地文件或传 URL； 单文件 ≤100 页（超出只解析前 100 页）。
• mineru flash：免 key；本地文件两步上传（建任务→PUT OSS）；≤10MB/20 页。
• mineru --precision：只接受 http(s) URL；≤200MB/200 页。
• siliconflow：base64/URL 直传，同步；大 PDF 注意请求体体积。

image ask — 图片问答/描述

mm_cli.py image ask <image|url> "问题" [选项]

选项	说明
--provider	zhipu（默认首选，glm-4v-flash 免费）/ siliconflow（Qwen3-VL-8B）/ dashscope（qwen-vl-max）。缺省按 zhipu → siliconflow → dashscope 自动链
--model	覆盖模型名（如 glm-4.6v-flash）
--detail	auto/high/low（部分 provider 支持）
--max-tokens	输出上限
--json / --no-cache / --ttl N	同 doc parse（默认 TTL 24h）

• 只接受图片（PNG/JPEG/WebP/GIF/BMP，魔数自动识别）；PDF 请用 doc parse。
• 文档类截图（表格/票据/论文页）建议先 doc parse 再让模型读 Markdown， 保真度远高于小型视觉模型直接看图。

cache

mm_cli.py cache stats   # 条目数/体积/新旧
mm_cli.py cache clear   # 清空结果缓存与探测缓存

缓存目录：~/.cache/multimodal-skill/（可用 MM_SKILL_CACHE_DIR 覆盖）。