zleap-parser 0.1.4__py3-none-any.whl

zleap_parser/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,27 @@
+# Third-Party Notices
+
+## MinerU HTML webcrawler rules
+
+URL 正文提取、正文图片筛选和 Markdown 渲染的部分实现位于：
+
+- `src/zleap_parser/url_collector/webcrawler/article_extractor.py`（参考原 `htmlx.py` 逐字节复制后改名）
+- `src/zleap_parser/url_collector/webcrawler/models.py`
+- `src/zleap_parser/url_collector/webcrawler/http_client.py`（同步入口保留参考异步签名，依赖延迟导入）
+- `src/zleap_parser/url_collector/webcrawler/proxy.py`
+- `src/zleap_parser/url_collector/webcrawler/resource_cache.py`
+- `src/zleap_parser/url_collector/markdown.py`
+- `src/zleap_parser/url_collector/resource_cache.py`
+
+`article_extractor.py`（原 `htmlx.py`）副本 SHA-256：
+`3b54647de752f05d28c65bc2229b3a85f6d09583237188977c4f61d6608ceeaf`
+
+这些实现派生自用户提供的 `mineru-html-feat-crawl-0714` 中
+`dripper/crawl/vendors/webcrawler` 代码，原项目采用 Apache License 2.0。
+Apache License 2.0 全文随本项目发布于 `LICENSES/Apache-2.0.txt`。
+
+原项目 NOTICE：
+
+> This project contains code and model weights derived from Qwen3.  
+> Original Qwen3 Copyright 2024 Alibaba Cloud, licensed under Apache License 2.0.  
+> Modifications and additional training Copyright 2025 OpenDatalab Shanghai AILab,
+> licensed under Apache License 2.0.

zleap_parser/__init__.py

@@ -0,0 +1,71 @@
+"""zleap_parser：zleap 文档解析 SDK。
+
+把本地文件或远程 HTML URL 解析为 markdown，经 ``zleap-sag`` 提取结构化产物、
+``octx`` 打包为 ``*.octx`` 归档文件路径；远程 HTML 由同步 Camoufox 渲染。
+返回值携带本次调用的 LLM token 用量。
+
+快速上手::
+
+    import zleap_parser
+    from zleap_parser import LLMConfig, EmbeddingConfig
+
+    zleap_parser.config(
+        llm=LLMConfig(base_url="https://api.xxx.com/v1", api_key="sk-...", model="gpt-4o"),
+        embedding=EmbeddingConfig(model="text-embedding-3", dimensions=1024),
+    )
+
+    parser = Parser()
+    result = parser.parse(file="/path/to/document.pdf")  # 或 parse(url="https://...")
+    octx_path = result["result"]  # *.octx 归档路径
+    usage = result["usage"]  # LLM token 用量：prompt_tokens / completion_tokens / total_tokens
+"""
+
+from __future__ import annotations
+
+from zleap_parser.adapters import BaseAdapter
+from zleap_parser.config import (
+    CacheConfig,
+    Config,
+    EmbeddingConfig,
+    LLMConfig,
+    RedisConfig,
+    config,
+    get_global_config,
+    set_global_config,
+)
+from zleap_parser.exceptions import (
+    AdapterNotFoundError,
+    ConfigError,
+    ConversionError,
+    DownloadError,
+    ExtractError,
+    TimeoutError,
+    ZleapParserError,
+)
+from zleap_parser.parser import Parser
+from zleap_parser.search import SEARCH_SOURCE_DOMAINS, SearchMode, SearchResult
+
+__version__ = "0.1.3"
+
+__all__ = [
+    "AdapterNotFoundError",
+    "BaseAdapter",
+    "CacheConfig",
+    "Config",
+    "ConfigError",
+    "ConversionError",
+    "DownloadError",
+    "EmbeddingConfig",
+    "ExtractError",
+    "LLMConfig",
+    "Parser",
+    "RedisConfig",
+    "SEARCH_SOURCE_DOMAINS",
+    "SearchMode",
+    "SearchResult",
+    "TimeoutError",
+    "ZleapParserError",
+    "config",
+    "get_global_config",
+    "set_global_config",
+]

zleap_parser/adapters/__init__.py

@@ -0,0 +1,168 @@
+"""格式适配器（插件：注册制、热插拔、可嵌套、防循环）。
+
+新增格式 = 在适配器目录（本包）下新增
+:class:`~zleap_parser.adapters.core.base.BaseAdapter` 子类 + 注册，不改核心框架。
+
+目录约定：
+
+- ``adapters/*_adapter.py``：格式适配器插件（txt / code / html / image / pdf /
+  docx / ppt / xlsx / xml / audio，统一 ``<格式>_adapter.py`` 命名，一眼可辨；
+  ``code_adapter.py`` 为合并实现，单一适配器覆盖全部源码类格式）；
+- ``adapters/core/``：框架基础设施（基类 / 注册表 / 引擎 / mimetype 检测），
+  不是格式插件，请勿在 core 下新增格式；
+- ``adapters/utils/``：适配器共享工具（docling 转换 / fallback runner /
+  torch 噪音静音 / 源码围栏包装 / 图片与 xlsx 资源提取等），非适配器文件一律放这里。
+
+**懒加载约定（M2.5 S4）**：适配器实现模块经 :func:`__getattr__`（PEP 562）
+按需导入——``import zleap_parser.adapters`` 只加载框架核心（基类/注册表/引擎），
+不连带导入 pdf/audio 等重量适配器（避免 docling/torch 等可选依赖 import 链）。
+各格式适配器类与公开 mimetype 常量仍可直接 ``from zleap_parser.adapters import X``，
+首次访问时懒加载对应模块。
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any, Dict
+
+from zleap_parser.adapters.core.base import BaseAdapter, _CallableAdapter  # noqa: F401
+from zleap_parser.adapters.core.engine import AdapterEngine, ensure_readable_file  # noqa: F401
+from zleap_parser.adapters.core.mimetype import M4A_MIMETYPE, detect_mimetype_by_magic
+from zleap_parser.adapters.core.registry import AdapterRegistry
+
+#: 符号 → 定义模块（懒加载映射）：仅访问到该符号时才 import 其模块。
+_LAZY_IMPORTS: Dict[str, str] = {
+    # audio_adapter（音视频 ASR，重：docling/torch/transformers 链路）
+    "AUDIO_MIMETYPES": "zleap_parser.adapters.audio_adapter",
+    "VIDEO_MIMETYPES": "zleap_parser.adapters.audio_adapter",
+    "AudioAdapter": "zleap_parser.adapters.audio_adapter",
+    # 图片类
+    "BMP_MIMETYPE": "zleap_parser.adapters.bmp_adapter",
+    "BmpAdapter": "zleap_parser.adapters.bmp_adapter",
+    "GIF_MIMETYPE": "zleap_parser.adapters.gif_adapter",
+    "GifAdapter": "zleap_parser.adapters.gif_adapter",
+    "JPG_MIMETYPE": "zleap_parser.adapters.jpg_adapter",
+    "JpgAdapter": "zleap_parser.adapters.jpg_adapter",
+    "PNG_MIMETYPE": "zleap_parser.adapters.png_adapter",
+    "PngAdapter": "zleap_parser.adapters.png_adapter",
+    "SVG_MIMETYPE": "zleap_parser.adapters.svg_adapter",
+    "SvgAdapter": "zleap_parser.adapters.svg_adapter",
+    "WEBP_MIMETYPE": "zleap_parser.adapters.webp_adapter",
+    "WebpAdapter": "zleap_parser.adapters.webp_adapter",
+    "ImageAdapter": "zleap_parser.adapters.image_adapter",
+    # 代码/文本类
+    "C_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "CPP_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "CSHARP_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "CSS_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "DART_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "GO_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "JAVA_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "JAVASCRIPT_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "JSON_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "KOTLIN_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "LUA_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "PHP_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "PYTHON_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "R_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "RUBY_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "RUST_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "SCALA_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "SHELL_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "SQL_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "SWIFT_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "TFT_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "TOML_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "TYPESCRIPT_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "YAML_MIMETYPE": "zleap_parser.adapters.code_adapter",
+    "CodeAdapter": "zleap_parser.adapters.code_adapter",
+    "TxtAdapter": "zleap_parser.adapters.txt_adapter",
+    # 文档类（docx/ppt/xlsx/pdf/rtf：docling/markitdown 等可选依赖 import 链）
+    "DOCX_MIMETYPE": "zleap_parser.adapters.docx_adapter",
+    "DocxAdapter": "zleap_parser.adapters.docx_adapter",
+    "HTMLAdapter": "zleap_parser.adapters.html_adapter",
+    "PdfAdapter": "zleap_parser.adapters.pdf_adapter",
+    "PPTX_MIMETYPE": "zleap_parser.adapters.ppt_adapter",
+    "PptAdapter": "zleap_parser.adapters.ppt_adapter",
+    "RTF_MIMETYPE": "zleap_parser.adapters.rtf_adapter",
+    "RTF_MIMETYPES": "zleap_parser.adapters.rtf_adapter",
+    "RtfAdapter": "zleap_parser.adapters.rtf_adapter",
+    "XLSX_MIMETYPE": "zleap_parser.adapters.xlsx_adapter",
+    "XlsxAdapter": "zleap_parser.adapters.xlsx_adapter",
+    "XMLAdapter": "zleap_parser.adapters.xml_adapter",
+}
+
+__all__ = [
+    "AdapterEngine",
+    "AdapterRegistry",
+    "AUDIO_MIMETYPES",
+    "AudioAdapter",
+    "BaseAdapter",
+    "BMP_MIMETYPE",
+    "BmpAdapter",
+    "C_MIMETYPE",
+    "CPP_MIMETYPE",
+    "CSHARP_MIMETYPE",
+    "CSS_MIMETYPE",
+    "CodeAdapter",
+    "DART_MIMETYPE",
+    "DOCX_MIMETYPE",
+    "DocxAdapter",
+    "GIF_MIMETYPE",
+    "GifAdapter",
+    "GO_MIMETYPE",
+    "HTMLAdapter",
+    "ImageAdapter",
+    "JAVA_MIMETYPE",
+    "JAVASCRIPT_MIMETYPE",
+    "JSON_MIMETYPE",
+    "JPG_MIMETYPE",
+    "JpgAdapter",
+    "KOTLIN_MIMETYPE",
+    "LUA_MIMETYPE",
+    "M4A_MIMETYPE",
+    "PHP_MIMETYPE",
+    "PdfAdapter",
+    "PNG_MIMETYPE",
+    "PngAdapter",
+    "PPTX_MIMETYPE",
+    "PptAdapter",
+    "PYTHON_MIMETYPE",
+    "R_MIMETYPE",
+    "RUBY_MIMETYPE",
+    "RUST_MIMETYPE",
+    "RTF_MIMETYPE",
+    "RTF_MIMETYPES",
+    "RtfAdapter",
+    "SCALA_MIMETYPE",
+    "SHELL_MIMETYPE",
+    "SQL_MIMETYPE",
+    "SVG_MIMETYPE",
+    "SvgAdapter",
+    "SWIFT_MIMETYPE",
+    "TFT_MIMETYPE",
+    "TOML_MIMETYPE",
+    "TYPESCRIPT_MIMETYPE",
+    "TxtAdapter",
+    "VIDEO_MIMETYPES",
+    "WEBP_MIMETYPE",
+    "WebpAdapter",
+    "XLSX_MIMETYPE",
+    "XlsxAdapter",
+    "XMLAdapter",
+    "YAML_MIMETYPE",
+    "detect_mimetype_by_magic",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """PEP 562 懒加载：仅当真正访问适配器符号时才 import 其模块。
+
+    - 未声明懒加载的名字直接抛 AttributeError（与模块级 ``__getattr__`` 约定一致）；
+    - 命中后导入模块并取回符号，后续访问走模块缓存，不再重复导入。
+    """
+    module_name = _LAZY_IMPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module = importlib.import_module(module_name)
+    return getattr(module, name)

zleap_parser/adapters/audio_adapter.py

@@ -0,0 +1,368 @@
+"""音视频 ASR 适配器：FFmpeg 标准化音轨（含响度归一化），Docling 转写为会话 Markdown。
+
+所有支持的音频/视频容器先统一转换为 16 kHz、16-bit、单声道 WAV，并做 -23 LUFS
+响度归一化（低音量录音直接喂给 whisper 极易产生重复幻觉），再交给 Docling ASR。
+转写片段先做相邻去重合并（消除 whisper 滑窗重叠重复与幻觉循环），复用 connector
+的 ``chat_conversation`` / ``chat_message`` 结构和 Markdown 渲染器，因此输出与
+飞书等聊天数据源保持一致。
+"""
+
+from __future__ import annotations
+
+import copy
+import logging
+import os
+import shutil
+import subprocess
+import tempfile
+from contextlib import contextmanager
+from importlib import import_module
+from pathlib import Path
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+
+from uuid6 import uuid7
+
+from zleap_parser.adapters.core.base import BaseAdapter
+from zleap_parser.adapters.utils.torch_noise import quiet_torch_noise
+from zleap_parser.exceptions import ConfigError, ConversionError
+
+logger = logging.getLogger("zleap_parser.adapters.audio_adapter")
+
+AUDIO_MIMETYPES = [
+    "audio/aac",
+    "audio/flac",
+    "audio/mp4",
+    "audio/mpeg",
+    "audio/ogg",
+    "audio/wav",
+    "audio/webm",
+    "audio/x-m4a",
+]
+VIDEO_MIMETYPES = [
+    "video/avi",
+    "video/mp4",
+    "video/mpeg",
+    "video/ogg",
+    "video/quicktime",
+    "video/webm",
+    "video/x-matroska",
+    "video/x-msvideo",
+]
+
+MODEL_SPECS = {
+    "tiny": "WHISPER_TINY",
+    "base": "WHISPER_BASE",
+    "small": "WHISPER_SMALL",
+    "medium": "WHISPER_MEDIUM",
+    "large": "WHISPER_LARGE",
+    "turbo": "WHISPER_TURBO",
+    "turbo_native": "WHISPER_TURBO_NATIVE",
+}
+
+# 响度归一化目标（EBU R128 广播标准）：低音量录音先抬升，降低 whisper 幻觉。
+LOUDNORM_FILTER = "loudnorm=I=-23:TP=-1.5:LRA=11"
+# 去重阈值：相邻同文本片段的合并时间容忍（秒，whisper 滑窗重叠重复是首尾相接的）；
+_MERGE_GAP_TOLERANCE = 0.3
+# 物理上不可能的超短片段时长（秒）：whisper 幻觉循环会产出 0.02s 的完整单词。
+_MIN_SEGMENT_DURATION = 0.1
+
+__all__ = [
+    "AUDIO_MIMETYPES",
+    "MODEL_SPECS",
+    "VIDEO_MIMETYPES",
+    "AudioAdapter",
+    "build_asr_messages",
+    "media_to_markdown",
+    "prepare_asr_audio",
+]
+
+
+@contextmanager
+def prepare_asr_audio(source: str, work_dir: Optional[str] = None) -> Iterator[str]:
+    """用 FFmpeg 抽取音轨并统一为 ASR 友好的 16 kHz 单声道 PCM WAV（-23 LUFS）。"""
+    if not os.path.isfile(source):
+        raise ConversionError(f"file not found: {source}")
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        raise ConversionError("音视频转写需要 ffmpeg")
+
+    temporary: Optional[tempfile.TemporaryDirectory[str]] = None
+    if work_dir:
+        os.makedirs(work_dir, exist_ok=True)
+        output_dir = work_dir
+    else:
+        temporary = tempfile.TemporaryDirectory(prefix="zleap-asr-")
+        output_dir = temporary.name
+    wav_path = os.path.join(output_dir, f"{Path(source).stem}_asr.wav")
+    try:
+        try:
+            completed = subprocess.run(
+                [
+                    ffmpeg,
+                    "-hide_banner",
+                    "-loglevel",
+                    "error",
+                    "-y",
+                    "-i",
+                    source,
+                    "-vn",
+                    "-map",
+                    "0:a:0",
+                    "-af",
+                    LOUDNORM_FILTER,
+                    "-acodec",
+                    "pcm_s16le",
+                    "-ac",
+                    "1",
+                    "-ar",
+                    "16000",
+                    wav_path,
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=3600,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise ConversionError("ffmpeg 音轨预处理超时") from exc
+        if completed.returncode != 0 or not os.path.isfile(wav_path):
+            detail = (completed.stderr or "ffmpeg 未产出音轨").strip()
+            raise ConversionError(f"ffmpeg 音轨预处理失败: {detail}")
+        yield wav_path
+    finally:
+        if temporary is not None:
+            temporary.cleanup()
+
+
+def _speaker_for_interval(diarization: Any, start: float, end: float) -> Optional[str]:
+    """按时间区间与各说话人片段的重叠时长，返回重合度最高的说话人标签。"""
+    best_speaker: Optional[str] = None
+    best_overlap = 0.0
+    for segment in getattr(diarization, "segments", []):
+        overlap = max(0.0, min(end, float(segment.end_time)) - max(start, float(segment.start_time)))
+        if overlap > best_overlap:
+            best_overlap = overlap
+            best_speaker = str(segment.speaker)
+    return best_speaker
+
+
+def _speaker_name(index: int) -> str:
+    """按出现顺序生成稳定的说话人名称（speaker_1、speaker_2 …）。"""
+    return f"speaker_{index + 1}"
+
+
+def build_asr_messages(
+    conversation_id: str,
+    result: Any,
+    diarization: Optional[Any] = None,
+) -> List[Dict[str, Any]]:
+    """把 Docling ASR 文本片段转换为统一 ``chat_message`` 列表。
+
+    逐段过滤与合并，消除 whisper 的两类重复产物：
+    - 时长不足 ``_MIN_SEGMENT_DURATION`` 的片段直接丢弃（幻觉循环产出的
+      0.02s「那就是」在物理上不可能是真实语音）；
+    - 时间连续/接近（间隙 ≤ ``_MERGE_GAP_TOLERANCE``）且文本相同的片段合并为
+      一条（30s 滑窗重叠会把同一句转写两次，甚至被分给不同说话人）。
+    """
+    # 先收集原始片段并按起始时间排序，保证合并顺序稳定。
+    items: List[Tuple[str, float, float]] = []
+    for item in getattr(result.document, "texts", []):
+        text = str(getattr(item, "text", "")).strip()
+        sources = getattr(item, "source", None)
+        if not text or not sources:
+            continue
+        track = sources[0]
+        start = max(0.0, float(track.start_time))
+        end = max(start, float(track.end_time))
+        items.append((text, start, end))
+    items.sort(key=lambda item: item[1])
+
+    merged: List[Tuple[str, float, float]] = []
+    for text, start, end in items:
+        if end - start < _MIN_SEGMENT_DURATION:
+            continue
+        if (
+            merged
+            and merged[-1][0] == text
+            and start <= merged[-1][2] + _MERGE_GAP_TOLERANCE
+        ):
+            # 相邻同文本（窗口重叠重复/语气词连击）→ 合并，时间范围扩展。
+            merged[-1] = (merged[-1][0], merged[-1][1], max(merged[-1][2], end))
+        else:
+            merged.append((text, start, end))
+
+    messages: List[Dict[str, Any]] = []
+    speaker_names: Dict[str, str] = {}
+    for text, start, end in merged:
+        speaker_id = _speaker_for_interval(diarization, start, end) if diarization is not None else None
+        if speaker_id is not None and speaker_id not in speaker_names:
+            speaker_names[speaker_id] = _speaker_name(len(speaker_names))
+        sender_name = speaker_names.get(speaker_id or "", "speaker_unknown" if diarization is not None else "转写")
+        message_id = str(uuid7())
+        messages.append(
+            {
+                "chat_message_id": message_id,
+                "chat_conversation_id": conversation_id,
+                "type": "TEXT",
+                "timestamp": 0,
+                "content": text,
+                "sender_id": speaker_id or "asr",
+                "sender_name": sender_name,
+                "sender_avatar": "",
+                "extra_data": {"speaker_id": speaker_id or "", "source": "asr"},
+                "source_id": message_id,
+                "raw_content": text,
+                "parent_id": "",
+                "group_id": message_id,
+                "segment": len(messages),
+                "start_time": start,
+                "end_time": end,
+            }
+        )
+    return messages
+
+
+def _transcribe(prepared_source: str, model: str, language: Optional[str]) -> Any:
+    """调用 Docling ASR 转写预处理音频，返回转换结果对象。
+
+    :param prepared_source: 预处理后的 WAV 路径。
+    :param model: ASR 模型名（MODEL_SPECS 的键）。
+    :param language: 可选语言代码，为 None 时自动识别。
+    :return: Docling 转换结果（``document.texts`` 为转写片段）。
+    """
+    quiet_torch_noise()  # 副作用归位：首次实际转写时才静音 torch/transformers 噪音
+    try:
+        from docling.datamodel import asr_model_specs
+        from docling.datamodel.base_models import InputFormat
+        from docling.datamodel.pipeline_options import AsrPipelineOptions
+        from docling.document_converter import AudioFormatOption, DocumentConverter
+        from docling.pipeline.asr_pipeline import AsrPipeline
+    except ImportError as exc:
+        raise ConversionError(
+            "音视频转写依赖不完整，请启用 media extra "
+            "（uv: `uv run --extra media ...`；pip: `pip install zleap_parser[media]`）"
+        ) from exc
+
+    pipeline_options = AsrPipelineOptions()
+    pipeline_options.asr_options = copy.deepcopy(getattr(asr_model_specs, MODEL_SPECS[model]))
+    if language:
+        asr_options: Any = pipeline_options.asr_options
+        asr_options.language = language
+    converter = DocumentConverter(
+        format_options={
+            InputFormat.AUDIO: AudioFormatOption(
+                pipeline_cls=AsrPipeline,
+                pipeline_options=pipeline_options,
+            )
+        }
+    )
+    try:
+        return converter.convert(prepared_source)
+    except ImportError as exc:
+        raise ConversionError(
+            "音视频转写依赖不完整，请启用 media extra "
+            "（uv: `uv run --extra media ...`；pip: `pip install zleap_parser[media]`）"
+        ) from exc
+
+
+def _diarize(prepared_source: str, speakers: Optional[int]) -> Any:
+    """对预处理音频做说话人分离，返回分离结果对象。
+
+    :param prepared_source: 预处理后的 WAV 路径。
+    :param speakers: 期望说话人数，为 None 时自动推断。
+    :return: 含 ``segments`` 的 Docling 说话人分离结果。
+    """
+    try:
+        from docling.utils.speaker_diarization import diarize
+
+        # Docling 会吞掉这些可选依赖的 ImportError 并返回空结果，预检后才能给出
+        # 可操作的错误信息；导入 resemblyzer 同时覆盖其 pkg_resources 依赖。
+        for dependency in ("librosa", "soundfile", "resemblyzer", "sklearn.cluster"):
+            import_module(dependency)
+    except ImportError as exc:
+        raise ConversionError(
+            "说话人分离依赖不完整，请启用 media extra "
+            "（uv: `uv run --extra media ...`；pip: `pip install zleap_parser[media]`）"
+        ) from exc
+    result = diarize(Path(prepared_source), num_speakers=speakers)
+    if not getattr(result, "segments", None):
+        raise ConversionError("说话人分离未产生有效片段")
+    return result
+
+
+def media_to_markdown(
+    file: str,
+    *,
+    model: str = "turbo",
+    language: Optional[str] = None,
+    enable_diarization: bool = True,
+    speakers: Optional[int] = None,
+    work_dir: Optional[str] = None,
+) -> Tuple[Optional[str], List[str]]:
+    """音频/视频 → 会话 Markdown；原始媒体文件作为关联附件返回。"""
+    # 延迟导入避免 Parser -> adapters -> connector -> Parser 的初始化环。
+    from zleap_parser.chat_utils import build_chat_conversation, conversation_to_markdown
+
+    with prepare_asr_audio(file, work_dir=work_dir) as prepared_source:
+        result = _transcribe(prepared_source, model, language)
+        diarization = _diarize(prepared_source, speakers) if enable_diarization else None
+        conversation = build_chat_conversation(
+            Path(file).stem,
+            title=Path(file).stem,
+            extra_data={
+                "source_type": "media_asr",
+                "model": model,
+                "language": language or "auto",
+                "num_speakers": getattr(diarization, "num_speakers", 0),
+            },
+        )
+        messages = build_asr_messages(conversation["chat_conversation_id"], result, diarization)
+        if not messages:
+            return None, []
+        return conversation_to_markdown(conversation, messages), [file]
+
+
+class AudioAdapter(BaseAdapter):
+    """支持音频和视频容器的 Docling ASR 格式适配器。"""
+
+    mimetypes = [*AUDIO_MIMETYPES, *VIDEO_MIMETYPES]
+    accepts_work_dir = True  # ASR 预处理 WAV 落盘 work_dir
+    requires: tuple = ("docling",)  # ASR 转写依赖 docling（media extra）
+
+    def __init__(
+        self,
+        *,
+        model: str = "turbo",
+        language: Optional[str] = None,
+        enable_diarization: bool = True,
+        speakers: Optional[int] = None,
+    ) -> None:
+        if model not in MODEL_SPECS:
+            raise ConfigError(f"不支持的 ASR 模型: {model}")
+        if language is not None and (not isinstance(language, str) or not language.strip()):
+            raise ConfigError("language 必须是非空语言代码")
+        if not isinstance(enable_diarization, bool):
+            raise ConfigError("enable_diarization 必须是布尔值")
+        if speakers is not None and (
+            isinstance(speakers, bool) or not isinstance(speakers, int) or not 2 <= speakers <= 8
+        ):
+            raise ConfigError("speakers 必须是 2 到 8 的整数")
+        self.model = model
+        self.language = language.strip() if language else None
+        self.enable_diarization = enable_diarization
+        self.speakers = speakers
+
+    def is_available(self) -> bool:
+        """运行环境预检：docling 模块 + ffmpeg 外部二进制均可用。"""
+        return super().is_available() and shutil.which("ffmpeg") is not None
+
+    def parse(self, file: str, *, work_dir: Optional[str] = None) -> Tuple[Optional[str], List[str]]:
+        """音视频文件转会话 Markdown（ASR 转写 + 可选说话人分离）；原始媒体文件作为关联附件返回。"""
+        return media_to_markdown(
+            file,
+            model=self.model,
+            language=self.language,
+            enable_diarization=self.enable_diarization,
+            speakers=self.speakers,
+            work_dir=work_dir,
+        )

zleap_parser/adapters/bmp_adapter.py

@@ -0,0 +1,15 @@
+"""BMP 图片适配器：生成 Markdown 图片块并保留原始 BMP 附件。"""
+
+from __future__ import annotations
+
+from typing import List
+
+from zleap_parser.adapters.core.mimetype import BMP_MIMETYPE
+from zleap_parser.adapters.image_adapter import ImageAdapter
+
+__all__ = ["BMP_MIMETYPE", "BmpAdapter"]
+
+
+class BmpAdapter(ImageAdapter):
+    """BMP 专用适配器，复用通用图片的 Markdown 和附件处理。"""
+    mimetypes: List[str] = [BMP_MIMETYPE]