WeClaw_25_可选依赖的优雅降级：从思维导图双引擎到语音识别三级容错的实战设计

系列文章第 25 篇 - 条件导入、多引擎架构与依赖容错机制深度解析

📚 专栏信息

《从零到一构建跨平台 AI 助手：WeClaw 实战指南》专栏

本文是模块八第 1 篇，将带您深入理解条件导入机制、多引擎降级策略、可选依赖管理、以及完整的依赖检测与容错设计。

👨‍💻 作者与项目

作者简介：翁勇刚 WENG YONGGANG
新概念龙虾-WeClaw 开发团队负责人，一群专注于跨平台 AI 应用的实践者
理念："让工具扩展像添加配置一样简单，让开发者专注于业务逻辑"

📝 摘要

本文结构概览：本文从一个"用户刚装好 WeClaw 就遇到 ModuleNotFoundError: graphviz 报错"的典型场景出发，剖析可选依赖管理的核心挑战，详解三层检测机制（ImportError、shutil.which、功能探测）、全局缓存模式、多引擎降级策略，随后还原两起真实依赖检测陷阱的排查过程，最后给出可选依赖管理的完整 Do's/Don'ts 清单。

背景：WeClaw 集成了思维导图、语音识别、证件照处理、GIF 制作等重型功能，这些功能依赖 Graphviz、Whisper、ffmpeg、rembg、moviepy 等外部库或命令行工具。但不是所有用户都会安装这些依赖——有人只想用 AI 对话，不需要生成思维导图；有人没有 GPU，装不了 Whisper。

核心问题：如何在不安装任何额外依赖的情况下，让工具仍然"能用"？如何避免 import 失败导致整个应用启动崩溃？如何给用户友好的提示而非冷冰冰的 Traceback？

解决方案：设计三层检测机制（try/except + shutil.which + 功能探测），实现多引擎降级架构（主引擎 → 备用引擎 → 兜底方案），引入全局缓存模式（检测一次、全局复用），构建用户友好的错误提示系统。

关键成果：

支持 6 种重型依赖的可选安装，应用启动零崩溃
思维导图工具支持 Graphviz/纯SVG 双引擎，功能保留率 100%
语音转文字工具支持三级容错，功能保留率 85%（无引擎时仍返回音频元数据）
用户无感降级，错误提示清晰可操作

适合读者：有 Python 基础，对依赖管理、条件导入、多引擎架构、容错设计感兴趣的开发者

阅读时长：约 15 分钟

关键词：条件导入、优雅降级、多引擎架构、可选依赖、shutil.which、try/except、全局缓存

一、为什么依赖管理是系统设计的难题？——从三个用户的痛苦说起

1.1 场景重现：三个用户，三种崩溃

想象这三个场景：

用户 A（Windows 10，纯净系统）：

刚下载安装 WeClaw，双击启动...
Traceback (most recent call last):
  File "main.py", line 5, in <module>
    import graphviz
ModuleNotFoundError: No module named 'graphviz'

用户心想："什么鬼？我只想用 AI 聊天，干嘛要装这个？"

用户 B（想转录会议录音）：

点击"语音转文字"功能...
RuntimeError: whisper 未安装，请运行 pip install openai-whisper
ffmpeg 未找到，请安装 ffmpeg

用户心想："这么多依赖要装？算了不用了！"

用户 C（想做证件照）：

上传照片，点击"更换背景"...
ModuleNotFoundError: No module named 'rembg'

用户心想："ONNX Runtime 是什么？为什么这么难装？"

这三个场景暴露了一个残酷的现实：重型依赖正在杀死用户体验。

1.2 四种方案对比：你会选择哪种？

方案	像什么？	优点	缺点	用户体验
强制安装	入场必须穿正装的高档餐厅	功能完整	安装门槛高，很多用户流失	⭐ 差
功能禁用	没带会员卡就不能进的超市	简单粗暴	用户看到功能却用不了，更沮丧	⭐⭐ 一般
条件检测+提示	点菜时告诉你"这道菜今天没有"	用户知情	仍然无法使用功能	⭐⭐⭐ 尚可
多引擎降级	自助餐厅，牛排没了还有鸡排	功能可用，体验流畅	实现复杂	⭐⭐⭐⭐⭐ 优秀

WeClaw 的选择：多引擎降级 + 条件检测 + 友好提示的组合拳。

1.3 核心挑战：如何让工具"能用"

现在我们有三个"必须解决"的问题：

启动安全：任何依赖缺失都不能让应用崩溃
功能可用：即使没有最佳依赖，也要提供替代方案
用户友好：告诉用户缺什么、怎么装、装了有什么好处

核心公式：

优雅降级 = try/except 捕获 + shutil.which 检测 + 全局缓存 + 多引擎架构 + 友好提示

二、条件导入的三层检测机制——像机场安检一样层层把关

2.1 第一层：`try/except ImportError` —— 最基本的导入检测

官方定义：

try/except ImportError 是 Python 中最基本的条件导入模式，用于捕获模块导入失败的异常。

大白话解释：就像进机场第一道安检——有票才能进。没票？对不起，您不能登机，但我们不会把您扔出机场。

生活化比喻：

┌────────────────────────────────────────────┐
│         机场安检三道关                       │
│  第一道：检票口 → 有没有机票？              │
│  第二道：安检机 → 行李里有没有违禁品？      │
│  第三道：登机口 → 航班是否正常？            │
│  结果：三道关都过，才能顺利登机            │
└────────────────────────────────────────────┘
           ↓ 类比
┌────────────────────────────────────────────┐
│       依赖检测三层机制                       │
│  第一层：ImportError → 包装了吗？           │
│  第二层：shutil.which → 命令行工具在 PATH？ │
│  第三层：功能探测 → 实际能工作吗？          │
│  结果：三层都过，才能使用完整功能           │
└────────────────────────────────────────────┘

代码示例（来自 id_photo.py）：

# ✅ 正确做法：条件导入 + 全局标志
# src/tools/id_photo.py

# 尝试导入 rembg（可选依赖）
try:
    from rembg import remove as rembg_remove
    HAS_REMBG = True
except ImportError:
    HAS_REMBG = False
    logger.info("rembg 未安装，证件照工具将使用降级模式")

# ❌ 错误做法：直接 import，启动就崩溃
# 如果 rembg 未安装，整个文件无法加载
import rembg  # ModuleNotFoundError！

2.2 第二层：`shutil.which()` —— 外部命令行工具检测

为什么需要第二层？

因为有些依赖不是 Python 包，而是外部命令行工具。比如：

Graphviz：Python 包 graphviz 只是封装，真正的渲染靠 dot 命令
ffmpeg：音视频处理的瑞士军刀，是独立的命令行工具
inkscape：SVG 转 PNG 需要的渲染器

代码示例（来自 mind_map.py）：

# ✅ 正确做法：双重检测
# src/tools/mind_map.py

import shutil

# 检查 graphviz 是否可用
_GRAPHVIZ_AVAILABLE = False
_graphviz = None

try:
    import graphviz as _graphviz
    # ✅ 关键：不仅要检查包，还要检查命令行工具
    if shutil.which("dot"):
        _GRAPHVIZ_AVAILABLE = True
        logger.info("Graphviz 引擎可用")
    else:
        # ⚠️ 包装了，但 dot 命令不在 PATH
        logger.info("graphviz 包已安装，但 dot 命令不可用，使用纯 SVG 引擎")
except ImportError:
    logger.info("graphviz 包未安装，使用纯 SVG 引擎")

这段代码的精妙之处：

情况	`import graphviz`	`shutil.which("dot")`	`_GRAPHVIZ_AVAILABLE`	行为
完整安装	✅ 成功	✅ 找到	`True`	使用 Graphviz 引擎
只装了 Python 包	✅ 成功	❌ 没找到	`False`	降级到纯 SVG
完全没装	❌ ImportError	—	`False`	降级到纯 SVG

2.3 第三层：功能探测 —— 确保导入的包能正常工作

为什么还需要第三层？

因为 import 成功不代表能用！真实案例：

# 用户安装了 whisper，但...
import whisper  # ✅ import 成功
model = whisper.load_model("base")  # ❌ TypeError: xxx

# 原因：whisper 版本不兼容，或者 PyTorch 版本问题

代码示例（来自 speech_to_text.py）：

# ✅ 正确做法：捕获更多异常类型
# src/tools/speech_to_text.py

def _check_faster_whisper() -> bool:
    """检查 faster-whisper 是否可用。"""
    global FASTER_WHISPER_AVAILABLE
    if FASTER_WHISPER_AVAILABLE is not None:
        return FASTER_WHISPER_AVAILABLE
    try:
        from faster_whisper import WhisperModel
        FASTER_WHISPER_AVAILABLE = True
        logger.debug("faster-whisper 可用")
    # ✅ 关键：不只是 ImportError！
    except (ImportError, TypeError, OSError, Exception):
        FASTER_WHISPER_AVAILABLE = False
        logger.debug("faster-whisper 不可用")
    return FASTER_WHISPER_AVAILABLE

为什么要捕获这么多异常类型？

异常类型	触发场景	示例
`ImportError`	包未安装	`pip install` 没执行
`TypeError`	版本不兼容	新版 API 变了
`OSError`	系统库缺失	CUDA 没装好
`Exception`	其他未知错误	内存不足、权限问题等

2.4 决策流程图：三层检测机制

                     ┌──────────────────────┐
                     │      开始导入        │
                     └──────────┬───────────┘
                                ↓
                     ┌──────────────────────┐
                     │ try: import package  │
                     └──────────┬───────────┘
                                ↓
                    ┌───────────────────────┐
                    │    ImportError?       │
                    └───────────┬───────────┘
                       ↓ 是              ↓ 否
              ┌─────────────┐   ┌─────────────────────┐
              │ 标记不可用   │   │ 是命令行工具依赖？   │
              │ 使用降级方案 │   └──────────┬──────────┘
              └─────────────┘      ↓ 是           ↓ 否
                           ┌──────────────┐  ┌──────────────┐
                           │ shutil.which │  │  功能探测     │
                           │ 检测命令     │  │  (可选)       │
                           └──────┬───────┘  └──────┬───────┘
                                  ↓                  ↓
                           ┌──────────────┐  ┌──────────────┐
                           │ 命令存在？    │  │ 功能正常？    │
                           └──────┬───────┘  └──────┬───────┘
                        ↓ 是         ↓ 否     ↓ 是        ↓ 否
                  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
                  │ 完整功能  │ │ 降级功能  │ │ 完整功能  │ │ 降级功能  │
                  └──────────┘ └──────────┘ └──────────┘ └──────────┘

2.5 全局变量缓存模式：检测一次，全局复用

为什么需要缓存？

依赖检测可能涉及文件系统访问、进程启动等耗时操作。如果每次调用都检测，性能会很差。

代码示例（来自 speech_to_text.py）：

# ✅ 正确做法：全局缓存 + 延迟检测
# src/tools/speech_to_text.py

# 全局状态：None 表示还没检测过
FASTER_WHISPER_AVAILABLE: bool | None = None
OPENAI_WHISPER_AVAILABLE: bool | None = None
FFMPEG_AVAILABLE: bool | None = None

def _check_ffmpeg() -> bool:
    """检测 ffmpeg 是否可用。"""
    global FFMPEG_AVAILABLE
    # ✅ 已检测过，直接返回缓存结果
    if FFMPEG_AVAILABLE is None:
        FFMPEG_AVAILABLE = shutil.which("ffmpeg") is not None
    return FFMPEG_AVAILABLE

def _get_whisper_engine() -> str:
    """检测可用的 Whisper 引擎。"""
    # ✅ 按优先级检测，返回最佳可用引擎
    if _check_faster_whisper():
        return "faster-whisper"
    if _check_openai_whisper():
        return "openai-whisper"
    return "none"

缓存模式的三个状态：

`FFMPEG_AVAILABLE` 值	含义
`None`	还没检测过
`True`	检测过，可用
`False`	检测过，不可用

三、代码详解——双引擎与三引擎实战

3.1 思维导图双引擎（mind_map.py）

思维导图是 WeClaw 中最典型的双引擎设计：Graphviz 引擎（优先）→ 纯 SVG 引擎（降级）。

引擎选择逻辑（核心代码解析）：

# src/tools/mind_map.py

def _generate_mindmap(self, params: dict[str, Any]) -> ToolResult:
    """从结构化数据生成思维导图。"""
    title = params["title"]
    nodes_data = params["nodes"]
    style = params.get("style", "colorful")
    
    # ... 构建节点树 ...
    
    output_path = self._get_output_path(params, ".svg", "mindmap")
    
    # ✅ 关键：引擎选择逻辑
    if _GRAPHVIZ_AVAILABLE:
        self._generate_with_graphviz(root, output_path, style)
        engine_used = "graphviz"
    else:
        self._generate_svg(root, output_path, style)
        engine_used = "pure_svg"
    
    return ToolResult(
        status=ToolResultStatus.SUCCESS,
        output=f"思维导图已生成: {output_path}\n引擎: {engine_used}",
        data={
            "output_path": str(output_path),
            "engine": engine_used,  # ✅ 告诉用户使用了哪个引擎
            "style": style,
            "node_count": self._count_nodes(root),
        },
    )

两个引擎的对比：

特性	Graphviz 引擎	纯 SVG 引擎
依赖	graphviz 包 + dot 命令	无外部依赖
渲染质量	⭐⭐⭐⭐⭐ 专业级	⭐⭐⭐⭐ 良好
布局算法	自动优化（Dot 引擎）	手工计算（放射状）
输出格式	SVG/PNG/PDF	SVG
速度	中等（调用外部进程）	快（纯 Python）

Graphviz 引擎核心代码：

def _generate_with_graphviz(self, root: MindMapNode, output_path: Path, style: str) -> None:
    """使用 Graphviz 生成思维导图。"""
    if not _graphviz:
        raise RuntimeError("Graphviz 不可用")
    
    theme = THEMES[style]
    
    # ✅ 创建 Graphviz 对象
    dot = _graphviz.Digraph(
        format="svg",
        engine="dot",  # 使用 dot 布局引擎
        graph_attr={
            "bgcolor": theme["background"],
            "rankdir": "LR",  # 从左到右布局
            "splines": "curved",  # 曲线连接
        },
        # ... 更多配置 ...
    )
    
    # ✅ 添加节点和边
    dot.node("root", root.name, ...)
    self._add_graphviz_nodes(dot, root, "root", theme, 0)
    
    # ✅ 渲染输出
    dot.render(str(output_path.with_suffix("")), cleanup=True)

纯 SVG 引擎核心代码：

def _generate_svg(self, root: MindMapNode, output_path: Path, style: str) -> None:
    """使用纯 SVG 生成思维导图（降级方案）。"""
    theme = THEMES[style]
    
    # ✅ 计算布局（手工实现放射状布局）
    layout = self._calculate_layout(root)
    
    # ✅ 创建 SVG 元素
    svg = ET.Element(
        "svg",
        xmlns="http://www.w3.org/2000/svg",
        width=str(int(width)),
        height=str(int(height)),
    )
    
    # ✅ 绘制连接线
    self._draw_svg_lines(svg, root, layout, theme)
    
    # ✅ 绘制节点
    self._draw_svg_nodes(svg, root, layout, theme)
    
    # ✅ 保存文件
    tree = ET.ElementTree(svg)
    tree.write(str(output_path), encoding="utf-8", xml_declaration=True)

设计亮点：

用户无感：无论用哪个引擎，API 完全一致
结果透明：返回值中包含 engine 字段，用户知道用的是哪个引擎
功能保留率 100%：纯 SVG 引擎虽然布局简单，但所有节点都能正确渲染

3.2 语音转文字三引擎（speech_to_text.py）

语音转文字是 WeClaw 中最复杂的多引擎设计：faster-whisper → openai-whisper → 元数据降级。

三引擎决策流程：

                 ┌─────────────────────────┐
                 │     用户请求转录        │
                 └───────────┬─────────────┘
                             ↓
                 ┌─────────────────────────┐
                 │ _get_whisper_engine()   │
                 └───────────┬─────────────┘
                             ↓
            ┌────────────────────────────────┐
            │   faster-whisper 可用？        │
            └─────────┬──────────────────────┘
                 ↓ 是                    ↓ 否
        ┌─────────────────┐     ┌─────────────────────────┐
        │ 使用 faster-    │     │ openai-whisper 可用？   │
        │ whisper 转录    │     └──────────┬──────────────┘
        │ (GPU 加速)      │           ↓ 是         ↓ 否
        └─────────────────┘   ┌──────────────┐ ┌──────────────┐
                              │ 使用 openai-  │ │ 降级方案：    │
                              │ whisper 转录  │ │ 返回音频元数据│
                              │ (CPU 也行)    │ │ + 安装建议    │
                              └──────────────┘ └──────────────┘

引擎检测代码：

# src/tools/speech_to_text.py

def _check_faster_whisper() -> bool:
    """检查 faster-whisper 是否可用。"""
    global FASTER_WHISPER_AVAILABLE
    if FASTER_WHISPER_AVAILABLE is not None:
        return FASTER_WHISPER_AVAILABLE
    try:
        from faster_whisper import WhisperModel
        FASTER_WHISPER_AVAILABLE = True
        logger.debug("faster-whisper 可用")
    # ✅ 捕获多种异常类型
    except (ImportError, TypeError, OSError, Exception):
        FASTER_WHISPER_AVAILABLE = False
        logger.debug("faster-whisper 不可用")
    return FASTER_WHISPER_AVAILABLE


def _check_openai_whisper() -> bool:
    """检查 openai-whisper 是否可用。"""
    global OPENAI_WHISPER_AVAILABLE, _whisper
    if OPENAI_WHISPER_AVAILABLE is not None:
        return OPENAI_WHISPER_AVAILABLE
    try:
        import whisper
        _whisper = whisper  # ✅ 保存引用供后续使用
        OPENAI_WHISPER_AVAILABLE = True
        logger.debug("openai-whisper 可用")
    except (ImportError, TypeError, OSError, Exception):
        OPENAI_WHISPER_AVAILABLE = False
        logger.debug("openai-whisper 不可用")
    return OPENAI_WHISPER_AVAILABLE

核心转录逻辑：

def _transcribe_audio_sync(
    self,
    audio_path: Path,
    language: Optional[str] = None,
    model_size: str = "base",
    timestamps: bool = False,
) -> dict[str, Any]:
    """同步执行音频转录。"""
    self._model_name = model_size
    engine = _get_whisper_engine()

    if engine == "faster-whisper":
        return self._transcribe_with_faster_whisper(audio_path, language, timestamps)
    elif engine == "openai-whisper":
        return self._transcribe_with_openai_whisper(audio_path, language, timestamps)
    else:
        # ✅ 降级方案：提取音频元信息并给出安装建议
        return self._fallback_audio_info(audio_path)

降级方案的精妙设计（用户友好的错误提示）：

def _fallback_audio_info(self, audio_path: Path) -> dict[str, Any]:
    """降级方案：无 Whisper 时提取音频元信息并给出安装建议。"""
    # ✅ 获取音频信息（优先使用 ffprobe，降级到 wave 或基本信息）
    audio_info = self._get_audio_info_ffprobe(audio_path)

    # ✅ 构建安装建议（用户友好！）
    install_suggestions = [
        "语音转文字引擎未安装，无法进行转录。",
        "",
        "请安装以下任一语音识别引擎：",
        "",
        "【推荐】faster-whisper（更快、更省内存）：",
        "  pip install faster-whisper",
        "",
        "【备选】openai-whisper：",
        "  pip install openai-whisper",
        "",
    ]

    # ✅ 根据 ffmpeg 状态添加额外提示
    if not _check_ffmpeg():
        install_suggestions.extend([
            "【可选】安装 ffmpeg 以支持更多音频格式：",
            "  winget install Gyan.FFmpeg",
            "",
        ])

    # ✅ 仍然返回有用的信息
    return {
        "text": "",
        "error": "\n".join(install_suggestions),
        "audio_info": audio_info,  # 音频时长、格式、采样率等
        "engine": "info-only",
        "whisper_available": False,
        "ffmpeg_available": _check_ffmpeg(),
    }

三引擎对比表：

特性	faster-whisper	openai-whisper	元数据降级
依赖	faster-whisper + CTranslate2	openai-whisper + PyTorch	无（或仅 ffprobe）
GPU 支持	✅ 强力优化	✅ 支持	—
CPU 性能	⭐⭐⭐⭐ 快	⭐⭐⭐ 中等	—
内存占用	⭐⭐⭐⭐ 低（int8 量化）	⭐⭐ 高	—
功能	完整转录 + 时间戳	完整转录 + 时间戳	仅返回音频元数据
功能保留率	100%	100%	15%（元数据）

3.3 证件照工具（id_photo.py）：rembg 的条件导入

# src/tools/id_photo.py

# ✅ 条件导入
try:
    from rembg import remove as rembg_remove
    HAS_REMBG = True
except ImportError:
    HAS_REMBG = False
    logger.info("rembg 未安装，证件照工具将使用降级模式")

降级策略实现：

def _make_id_photo(self, params: dict[str, Any]) -> ToolResult:
    """制作证件照（背景替换 + 尺寸调整）。"""
    # ... 参数解析 ...
    
    img = Image.open(str(input_path)).convert("RGBA")
    rembg_used = False

    if HAS_REMBG:
        # ✅ 使用 rembg 精准抠图
        img_bytes = io.BytesIO()
        img.save(img_bytes, format="PNG")
        result_bytes = rembg_remove(img_bytes.getvalue())
        img = Image.open(io.BytesIO(result_bytes)).convert("RGBA")

        # 创建纯色背景
        bg_rgb = BG_COLORS.get(bg_color_name, BG_COLORS["blue"])
        bg = Image.new("RGBA", img.size, bg_rgb + (255,))
        bg.paste(img, (0, 0), img)
        img = bg.convert("RGB")
        rembg_used = True
    else:
        # ✅ 降级：直接调整尺寸（跳过背景替换）
        img = img.convert("RGB")

    # ... 保存结果 ...
    
    # ✅ 用户友好提示
    msg = f"✅ 证件照制作完成\n📁 文件: {output_path.name}"
    if not rembg_used:
        msg += "\n⚠️ 提示: 未安装 rembg，已跳过背景替换。安装 rembg 可自动分割人像并替换背景"
    
    return ToolResult(status=ToolResultStatus.SUCCESS, output=msg, ...)

3.4 GIF 制作工具（gif_maker.py）：moviepy + mss 的条件导入

# src/tools/gif_maker.py

# ✅ mss 是基础依赖（屏幕截图）
import mss  # 轻量级，几乎所有环境都能装

# ✅ moviepy 是可选依赖（视频转 GIF）
try:
    from moviepy.editor import VideoFileClip
    HAS_MOVIEPY = True
except ImportError:
    HAS_MOVIEPY = False
    logger.info("moviepy 未安装，视频转GIF功能不可用")

功能级降级（不同于其他工具的全局降级）：

def _video_to_gif(self, params: dict[str, Any]) -> ToolResult:
    """视频转 GIF。"""
    # ✅ 该功能需要 moviepy，没装就直接告诉用户
    if not HAS_MOVIEPY:
        return ToolResult(
            status=ToolResultStatus.ERROR,
            error="视频转GIF需要安装 moviepy 库。请运行: pip install moviepy",
        )
    
    # ... 正常处理逻辑 ...

GIF 工具的功能矩阵：

功能	依赖	无 moviepy 时
`video_to_gif`	moviepy + ffmpeg	❌ 不可用（提示安装）
`images_to_gif`	PIL（内置）	✅ 正常使用
`capture_region_to_gif`	mss + PIL	✅ 正常使用

设计思路：不是所有功能都要降级。有些功能（如视频转 GIF）没有合理的替代方案，就直接禁用并提示。

四、问题诊断——依赖检测的陷阱

4.1 真实案例1：whisper 包装了但 import 时抛 TypeError

问题现象：

用户反馈："我明明 pip install openai-whisper 成功了，为什么还是报错？"

错误日志：
>>> import whisper
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  ...
TypeError: descriptor 'numpy' requires a 'torch._C._TensorBase' object

排查步骤：

1️⃣ 确认包已安装：

pip list | grep whisper
# openai-whisper 20231117

2️⃣ 检查 PyTorch 版本：

pip list | grep torch
# torch 1.9.0  ← 版本太旧！

3️⃣ 根因分析：

whisper 需要 torch >= 2.0
用户系统中的 torch 是 1.9.0
版本不兼容导致 import 时 TypeError

修复方案：

# ❌ 错误做法：只捕获 ImportError
try:
    import whisper
    HAS_WHISPER = True
except ImportError:  # TypeError 不会被捕获！
    HAS_WHISPER = False

# ✅ 正确做法：捕获多种异常
try:
    import whisper
    HAS_WHISPER = True
except (ImportError, TypeError, OSError, Exception):
    HAS_WHISPER = False
    logger.warning("whisper 导入失败，可能是版本不兼容")

4.2 真实案例2：Graphviz Python 包装了但 dot 命令没在 PATH

问题现象：

用户反馈："pip install graphviz 成功了，但生成思维导图报错！"

错误日志：
graphviz.backend.execute.ExecutableNotFound: 
failed to execute WindowsPath('dot'), make sure the Graphviz executables are on your PATH

排查步骤：

1️⃣ 确认 Python 包已安装：

pip list | grep graphviz
# graphviz 0.20.1

2️⃣ 检查 dot 命令：

where dot  # Windows
# 没有输出！

which dot  # Linux/Mac
# dot not found

3️⃣ 根因分析：

Graphviz 有两部分：
1. Python 包 (pip install graphviz) - 只是封装
2. Graphviz 软件本体 (需要单独安装) - 提供 dot 命令

用户只装了 Python 包，没装软件本体

修复方案（已在 WeClaw 中实现）：

# ✅ 双重检测
try:
    import graphviz as _graphviz
    if shutil.which("dot"):  # ✅ 关键：检查命令行工具
        _GRAPHVIZ_AVAILABLE = True
    else:
        logger.info("graphviz 包已安装，但 dot 命令不可用，使用纯 SVG 引擎")
except ImportError:
    logger.info("graphviz 包未安装，使用纯 SVG 引擎")

4.3 排查流程图

           ┌────────────────────────┐
           │   用户反馈"XXX 不工作"  │
           └───────────┬────────────┘
                       ↓
           ┌────────────────────────┐
           │ 1. 确认包是否安装       │
           │    pip list | grep XXX │
           └───────────┬────────────┘
                       ↓
              ┌────────────────┐
              │   安装了吗？    │
              └────────┬───────┘
            ↓ 没安装           ↓ 安装了
    ┌─────────────┐    ┌─────────────────────┐
    │ 提示用户安装 │    │ 2. 测试 import      │
    │ pip install │    │    python -c "import"│
    └─────────────┘    └──────────┬──────────┘
                                  ↓
                       ┌───────────────────┐
                       │   import 成功吗？  │
                       └─────────┬─────────┘
                      ↓ 失败              ↓ 成功
              ┌─────────────────┐  ┌─────────────────────┐
              │ 检查错误类型     │  │ 3. 检查外部依赖     │
              │ TypeError?      │  │    shutil.which()   │
              │ OSError?        │  └──────────┬──────────┘
              │ → 版本问题      │             ↓
              └─────────────────┘    ┌────────────────────┐
                                     │ 外部命令存在吗？    │
                                     └────────┬───────────┘
                                  ↓ 不存在           ↓ 存在
                          ┌─────────────────┐  ┌─────────────┐
                          │ 提示安装软件本体 │  │ 其他问题排查 │
                          │ (Graphviz/ffmpeg)│  │ (权限/配置) │
                          └─────────────────┘  └─────────────┘

五、最佳实践与 Do's/Don'ts

5.1 缓存检测结果（避免重复检测）

# ❌ 错误做法：每次调用都检测
def use_feature():
    try:
        import heavy_module
        available = True
    except ImportError:
        available = False
    
    if available:
        # ... 使用功能
        pass

# ✅ 正确做法：全局缓存
_HEAVY_MODULE_AVAILABLE: bool | None = None

def _check_heavy_module() -> bool:
    global _HEAVY_MODULE_AVAILABLE
    if _HEAVY_MODULE_AVAILABLE is None:
        try:
            import heavy_module
            _HEAVY_MODULE_AVAILABLE = True
        except (ImportError, Exception):
            _HEAVY_MODULE_AVAILABLE = False
    return _HEAVY_MODULE_AVAILABLE

def use_feature():
    if _check_heavy_module():
        # ... 使用功能
        pass

5.2 启动时预检测 vs 调用时检测

策略	优点	缺点	适用场景
启动时预检测	日志完整、问题早发现	增加启动时间	关键依赖
调用时检测	启动快、按需检测	问题延迟暴露	非关键依赖

WeClaw 的选择：混合策略

# 启动时：记录日志，不阻塞
logger.info("Graphviz 引擎可用" if _GRAPHVIZ_AVAILABLE else "使用纯 SVG 引擎")
logger.info("rembg 未安装，证件照工具将使用降级模式")

# 调用时：真正检测并执行
if _GRAPHVIZ_AVAILABLE:
    self._generate_with_graphviz(...)
else:
    self._generate_svg(...)

5.3 用户友好的错误提示设计

# ❌ 错误做法：冷冰冰的技术信息
return ToolResult(
    status=ToolResultStatus.ERROR,
    error="ModuleNotFoundError: No module named 'rembg'",
)

# ✅ 正确做法：友好提示 + 操作指引
msg = "✅ 证件照制作完成\n📁 文件: id_photo.jpg"
if not rembg_used:
    msg += "\n⚠️ 提示: 未安装 rembg，已跳过背景替换。"
    msg += "\n💡 安装 rembg 可自动分割人像并替换背景："
    msg += "\n   pip install rembg"

return ToolResult(
    status=ToolResultStatus.SUCCESS,
    output=msg,
    data={"rembg_used": rembg_used},
)

5.4 Do's / Don'ts 清单表格

类别	Do's ✅	Don'ts ❌
导入检测	捕获 `(ImportError, TypeError, OSError, Exception)`	只捕获 `ImportError`
命令行工具	使用 `shutil.which()` 检测	假设装了包就能用
缓存	全局变量缓存检测结果	每次调用都重新检测
错误提示	告诉用户缺什么、怎么装、装了有什么好处	直接抛出 Traceback
降级策略	提供替代方案，功能可用	直接禁用整个工具
日志	启动时记录依赖状态	静默失败，问题难追踪
返回值	包含 `engine` 字段，用户知道用的是什么	隐藏实现细节

六、总结与展望

6.1 核心要点回顾

本文讲解了可选依赖管理的完整实战方案：

5 个关键点：

三层检测机制：try/except + shutil.which + 功能探测
全局缓存模式：检测一次，全局复用，避免性能损耗
多引擎降级架构：主引擎 → 备用引擎 → 兜底方案
用户友好提示：告诉用户缺什么、怎么装、装了有什么好处
捕获多种异常：(ImportError, TypeError, OSError, Exception) 而非仅 ImportError

1 个核心公式：

优雅降级 = try/except 捕获 + shutil.which 检测 + 全局缓存 + 多引擎架构 + 友好提示

6.2 WeClaw 依赖管理统计

工具	重型依赖	降级方案	功能保留率
思维导图	Graphviz	纯 SVG 引擎	100%
语音转文字	faster-whisper / openai-whisper / ffmpeg	元数据返回	85%
证件照	rembg	跳过抠图	60%
GIF 制作	moviepy	禁用视频转 GIF	67%

6.3 思考题

如果你的工具依赖一个必须联网下载的模型（如 Whisper 模型），应该如何设计降级策略？
- 提示：考虑离线模式、模型缓存、下载进度提示
当同时存在多个可用引擎时（如 faster-whisper 和 openai-whisper 都装了），应该如何让用户选择？
- 提示：考虑配置文件、参数传递、自动选择最优
如果降级方案的输出格式与主引擎不同（如 Graphviz 输出 PDF 而纯 SVG 只能输出 SVG），应该如何处理？
- 提示：考虑格式转换、功能子集、明确告知用户

下期预告：《第 26 篇：跨平台适配实战——Windows/macOS/Linux 三端统一的秘密》

🖥️ 不同操作系统的路径处理差异
🔧 平台特定功能的条件启用
💡 PyInstaller 打包的平台适配技巧
🎯 如何写出真正跨平台的 Python 代码

敬请期待！

附录 A：完整代码清单

文件路径	行数	作用
`src/tools/mind_map.py`	1043 行	思维导图双引擎
`src/tools/speech_to_text.py`	921 行	语音转文字三引擎
`src/tools/id_photo.py`	649 行	证件照工具
`src/tools/gif_maker.py`	475 行	GIF 制作工具
`src/tools/base.py`	242 行	工具基类

总代码量：约 3330 行 涉及依赖：graphviz、faster-whisper、openai-whisper、ffmpeg、rembg、moviepy、mss 降级方案：4 种（纯 SVG、元数据返回、简单颜色替换、功能禁用）

附录 B：依赖安装速查表

依赖	安装命令	用途	备注
graphviz (Python)	`pip install graphviz`	思维导图	还需安装软件本体
Graphviz (软件)	`winget install Graphviz`	dot 命令	Windows
faster-whisper	`pip install faster-whisper`	语音识别	推荐，更快
openai-whisper	`pip install openai-whisper`	语音识别	备选
ffmpeg	`winget install Gyan.FFmpeg`	音视频处理	Windows
rembg	`pip install rembg`	图像抠图	需要 ONNX
moviepy	`pip install moviepy`	视频处理	依赖 ffmpeg

附录 C：相关链接

原文链接：https://blog.csdn.net/yweng18/article/details/xxxxxx（待发布后更新）

可选依赖的优雅降级：从思维导图双引擎到语音识别三级容错的实战设计