如何实现优雅降级的依赖探测：book-to-skill dependencies.py最佳实践拆解

如何实现优雅降级的依赖探测book-to-skill dependencies.py最佳实践拆解【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill本文基于 book-to-skill 项目把任意技术书籍 PDF 转换成 Claude Code / Copilot 可加载技能的工具中真实运行的依赖管理代码拆解它如何用探测 → 降级 → 提示三板斧让缺少任何可选依赖的环境都能完成转换。为什么依赖探测是转换工具的命门 book-to-skill 需要解析 PDF、EPUB、DOCX、HTML、RTF、MOBI 等 7 类格式。每种格式都有最优解析器如 docling、trafilatura但新手用户很少会把十几个包一次性装齐。一个粗暴的做法是缺依赖就报错退出。book-to-skill 选择了另一条路——✅ 有最优依赖 → 用最优路径⚠️ 缺依赖但有替代方案 → 静默降级到次优解析器甚至 Python 标准库❌ 完全没有替代如 MOBI 必须依赖 Calibre→ 明确告知用户这是硬性缺失这套逻辑集中在 book_to_skill/dependencies.py 一个文件里约 300 行职责清晰到可以整段抄作业。声明式依赖清单用数据描述谁需要什么 DEPENDENCY_GROUPS 是一个有序列表每个条目描述一种格式及其依赖关键字段包括字段含义新手可借鉴点modules可选 Python 包列表依赖以清单而非硬编码 if/else 表达any_of_modules列表中任一满足即可表达替代品语义any_tool_suffices模块或系统命令满足一个即可模块与系统工具互为后备systemPATH 中的外部命令 安装提示把怎么装写进数据note降级说明文案用户永远知道当前处于哪一级例如 EPUB 组声明了ebooklib bs4并注明缺失时回退到标准库 zipfile 解析器。依赖关系、满足条件、降级话术全部声明式集中管理后面所有函数探测、体检、安装提示都只消费这份数据不需要知道具体格式。三级降级链从最优解析器到标准库 ⚡以 PDF 为例项目定义了三层链路智能层pdf_inspector分类器可选加速层文本层pdftotext/pypdf/pdfminer三者任一即可any_tool_suffices: True技术文档层docling仅--mode technical表格、代码、公式需要否则回退文本链核心探测函数 python_module_available() 只用了一行importlib.util.find_spec——只查能不能 import绝不真正 import。这是关键最佳实践真正 import 重型库如 docling可能耗时数秒甚至触发副作用探测阶段必须零副作用、零耗时。系统命令侧则用shutil.which()判断 PATH 中是否存在如 prepare_dependencies() 中对pdftotext的检查。一个聪明的边界案例pipx 隔离环境探测 真实世界中最容易误伤用户的场景是用户明明用 pipx 装了 doclingwhich docling能找到可执行文件但当前解释器import docling会失败——于是程序报缺失用户一脸懵。isolated_install_hint() 针对这个场景做了精确处理值得逐条品味它先确认 PATH 上确实有同名可执行文件才认为是隔离环境安装它绝不说依赖可用——因为解析器是 import 它PATH 上的二进制不能让 import 成功。代码注释原话Never claims the module is available它进一步推断 pipx 的目录布局venv/bin/tool的兄弟python直接告诉用户可以用哪个解释器运行提取脚本对应的测试 tests/test_isolated_install_hint.py 特别断言了报告必须保留 ✗ 缺失标记提示只加诊断、不改分类——探测结果与诊断提示严格分离这是很多项目会踩的坑。安装交互设计ask / yes / no 三种模式 发现缺失依赖后要不要自动pip install项目没有二选一而是提供了三态安装模式normalize_install_mode()模式触发方式行为ask默认交互终端问一句装还是降级y/nyes--install-missing yes或环境变量BOOK_SKILL_INSTALL_MISSINGyes直接安装no--no-install-missing直接用降级链细节很讲究非交互场景CI、管道绝不挂起等待输入——sys.stdin.isatty()判断后自动走降级环境变量 命令行双通道且命令行优先级更高方便脚本化安装走 install_python_packages()用当前解释器sys.executable -m pip避免装到错误环境、600 秒超时、装完invalidate_caches()后二次校验装失败也能优雅落到 fallbackpip 包名与模块名的映射放在 config.py 的 PYTHON_DEPENDENCIES如pdfminer模块 ↔pdfminer.six包探测与安装共享同一份映射杜绝拼错包名。一条命令自检--check 依赖体检报告 run_dependency_check() 被scripts/extract.py --check调用入口见 scripts/extract.py无需任何文件即可输出全格式体检报告book-to-skill — dependency check PDF (text-heavy) ✓ python: pypdf ✗ system: pdftotext (poppler-utils) → ready — any one of pdftotext / pypdf / pdfminer is enough MOBI / AZW / AZW3 ✗ system: ebook-convert (Calibre) → MISSING — required, no fallback三个设计亮点满足度判定集中在一处#L287-L296any_tool_suffices→ 任一工具any_of_modules→ 任一模块否则全部满足。三种语义互斥且可读缺失 ≠ 错误函数永远返回退出码 0可选依赖缺失不是故障只有 MOBI 组因required: True才标 MISSING — no fallback报告即处方结尾自动去重并打印一条可直接复制的pip install ...命令和系统包安装提示——用户看完报告就能动手新手可以直接抄的 5 个实践要点 ✅依赖清单数据化格式→依赖→满足条件→降级话术全部收敛到一份声明式配置逻辑函数只消费数据探测零副作用用find_spec/which判断可用性绝不真实 import区分可选缺失与硬性缺失状态词ready / fallback available / MISSING让用户一眼看懂当前环境等级提示只诊断、不改结论即使检测到 pipx 环境缺失标记照打避免自相矛盾的输出交互三态 非交互兜底ask/yes/no 覆盖人类、自动化、CI 三类场景任何模式下程序都不会卡死完整的依赖探测代码可以逐行阅读book_to_skill/dependencies.py约 327 行用户视角的体检命令说明见 docs/install.md 与 SKILL.md。如果你想理解整体流水线中依赖探测所处的位置可继续阅读 docs/architecture.md。优雅降级的本质不是容忍残缺环境而是让用户在残缺环境里依然能拿到可预期的结果并且清楚知道离最佳结果还差哪一步——这正是 dependencies.py 最值得借鉴的地方。【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考