qwen-mm-plugins-core

本地文件检查

你可以使用 qwen-mm-plugins-core MCP 工具。使用它们读取和可视化受支持的本地文件、检查媒体元数据、裁剪／标注图像，以及保存文档页面或视频帧。优先使用这些 MCP 工具，而非手动编写脚本。

在默认原生模式下，这些工具会返回文本和图像，供 Agent 检查，无需调用模型 API。设置 QWEN_MM_NATIVE_MODE=0 后，共享的图像说明回退机制会将图像结果发送到已配置的 VL 端点，并返回文本说明。

请查看工具列表中的 qwen-mm-plugins-core 工具，了解完整的架构和参数。

何时使用哪种工具

读取与检查：

• 对任何视频／音频，先检查元数据（时长、分辨率、fps、编解码器、比特率、音频／视频／字幕轨道、旋转角度、章节）→ media_info。在运行 read_video 和进行任何剪辑／编辑之前运行它 — 参见下文的先检查元数据。
• 查看文件（PDF、Office、CSV、代码、笔记本、3D 等）→ visualize
• 以动态分辨率读取图像 → read_image
• 读取视频（提取帧）→ read_video
• 将视频的特定帧保存到文件 → save_view（传入 times=[...]）
• 将文档页面保存为图像 → save_view（传入 pages="..."）

生成／标注（会写入图像文件）：

• 从图像中裁剪矩形区域 → crop
• 照片坐标：read_image、crop 和 draw_bbox 会应用 EXIF 方向。请使用显示图像中的 0–1000 坐标，包括 grounding 返回的框。
• 在图像上绘制边界框 → draw_bbox

可视化 — 支持的格式

类别	扩展名	备注
文档	.pdf、.svg	内置（pypdfium2 + resvg）
Office	.docx、.pptx、.vsdx	需要 libreoffice
数据	.csv、.xlsx	文本表格 + 图表图像
代码	.js、.ts、.py、.go、.rs、.md、...	返回文本（markdown 代码块）
纯文本	.txt、.text、.log	返回文本（围栏代码块）
网页	.html、.htm、.mhtml	截图；需要 playwright
图表	.drawio	XML → SVG 渲染
字幕	.srt、.vtt	返回文本
3D 模型	.obj、.stl、.glb、.gltf、.fbx、.ply、.step、.stp	内置；使用 blender 可获得最佳效果
GIS／地理数据	.geojson、.kml、.shp	内置
笔记本	.ipynb	文本单元格 + 嵌入图像
LaTeX	.tex	编译为 PDF；失败时回退到源文件
图像／视频	.jpg、.mp4、...	委托给 read_image／read_video

此表列出了受支持的格式；扩展名未知的文件会返回不支持的类型错误。

使用 pages 指定页面范围，使用 budget 设置分辨率，使用 max_pages 限制输出页数。

先检查元数据

对视频／音频文件运行 media_info，必须先于 read_video 以及任何剪辑／修剪／拼接／复用操作 — 它只读取文件头，因此即使文件很大也能快速完成，并会告知你如何处理源文件。了解 fps 和时长后，read_video 也能更智能地采样。

处理异构素材（运动相机片段、VFX／库存素材、旁白、SFX）时，media_info 能帮你发现可能悄悄破坏剪辑的陷阱 — 请检查：

• VFR（可变帧率 — 常见于手机／运动相机）：media_info 会将其标记为 possibly VFR。要进行逐帧精确剪切，必须先将帧率转换为恒定值（视频编辑步骤）— 切勿假定 VFR 源素材具有固定帧率。
• 旋转角度（rotation 90°/180°）：显示方向与存储像素的方向不同；裁剪或叠加前应先将旋转应用到画面中。
• 片段间 fps／分辨率／DAR 不匹配 → 选定统一的项目时基，并转换不匹配的素材。
• 音频采样率和声道数（旁白、音乐和 SFX 往往各不相同，例如 44.1k 与 48k、单声道与立体声）→ 混音前统一重采样到同一项目采样率。
• 没有音轨／容器的 start_time 异常 → media_info 会指出这两种情况；它们都会导致简单的时间戳计算出现偏移或错误。

提示

分辨率预算：预览使用 small，默认使用 normal（约 1024），精细细节使用 large。

视频策略：fps=0 会自动选择。按 5 分钟分段，使用 fps=1, budget="normal" 快速浏览；然后对感兴趣的片段使用 fps=2, budget="large" 查看细节。使用 start_time/end_time 设置时间范围。

与其他功能的关系

Core 负责文件读取、渲染和基本图像操作。安装以下功能可进行专用模型推理或搜索：

• 使用模型理解媒体 → qwen-mm-plugins-api，按模型系列分组：VL（vision_chat、ocr、grounding）、Omni A/V（带时间戳的字幕生成、多说话人 ASR、时序定位、事件计数），以及 transcribe_audio 和 segmentation。可在此处使用 draw_bbox 为其 grounding 输出添加标注。
• 核实事实 / 识别实体（反向图像搜索 + 网络搜索）→ qwen-mm-plugins-search。先在此处使用 save_view 获取帧。