零安装哲学:learn-from-materials能力探测与可选依赖策略全解析

原创2026-10-17 19:57:502,179 阅读
文章标签:AI 技能AI 应用人工智能知识库知识管理教育文档CLI

零安装哲学:learn-from-materials能力探测与可选依赖策略全解析

learn-from-materials 是一款把 PDF、EPUB、书籍和课件转化为可追溯、可测验、可记笔记的交互式学习网页的开源工具。它的最大特色之一,是"零安装哲学":不自动安装任何依赖,先用只读命令探测本地解析能力,再为每种格式准备回退方案。本文将带你完整理解它的能力探测机制与可选依赖策略。

learn-from-materials 是什么?

简单说,这是一个"材料变学习页"的工具:你给它一本书、一份 PDF 或一套 PPT,它会提取原文、建立可追溯的知识库(.learnkb/ 目录),最后渲染出一个可交互的离线学习网页——包含核心框架卡片、内容导学、术语大全、行动规则、动态自测和本地笔记六大模块。

生成页面的效果大致如下,内容单元保留了原文的 PDF 页码定位,点击即可查看核心思想、关键框架与行动要点:

learn-from-materials 将 PDF 材料转化为可追溯学习网页的内容导学模块

框架卡片模块则负责"先抓住材料的知识骨架",把书中的关键判断整理成带编号、带出处引用的框架卡片:

learn-from-materials 学习页核心框架卡片,展示材料知识骨架与出处引用

页面首次打开时还有"小巴"引导,帮你在一分钟内学会切换模块、核对出处、发起自测:

learn-from-materials 学习页首次打开的引导界面,介绍模块切换与动态自检

零安装哲学:为什么从不自动安装依赖?

很多工具遇到缺库时会默默执行 pip install,而 learn-from-materials 明确拒绝这种"顺手装包"的行为。这一哲学写在 SKILL.md 的核心原则里:

默认不安装任何依赖。缺失能力时输出检查结果和安全安装建议,由用户明确决定是否在隔离环境中安装。

背后是三层考量:

  • 安全可控:SECURITY.md 明确规定"不自动安装 Python、Node.js 或系统依赖",脚本不主动联网、不拼接不可信参数,避免工具替你改动系统环境;
  • 权限最小化:AI Agent 运行环境各不相同,自动装包可能污染共享环境,把决定权交还给用户更稳妥;
  • 透明可预期:缺失能力时只会"报告",你清楚知道少了什么、少了会怎样、补上又该怎么装,而不是事后才发现环境变了。

一个巧妙的兼容设计:--install-missing 被"禁用但保留"

在 scripts/extractor/utils.py 中,旧的 --install-missing 参数并没有被直接删除,而是被刻意保留:

NOTICE: --install-missing is disabled by this Skill. No dependency was installed;
use an available fallback or obtain explicit approval for isolated, fixed-version installation.

也就是说,即使旧脚本或旧文档还在传这个参数,程序也不会真的装任何东西,只会打印一条"该操作已被禁用"的提示。这种"保留接口、明确拒绝"的做法,比静默失败友好得多——scripts/extractor/dependencies.py 中的 normalize_install_mode() 函数负责把这个意图显式化。

一条命令的能力探测:python3 scripts/extract.py --check

这是本文的主角。在项目根目录运行:

python3 scripts/extract.py --check

它是一次纯只读的能力体检:不下载、不安装、不修改环境,只告诉你"你的电脑上现在能解析哪些格式"。入口逻辑在 scripts/extractor/utils.py 的 main() 中——检测到 --check 参数就立刻转入 run_dependency_check()。

探测机制:两种"不装就能查"的方法

能力探测的核心在 scripts/extractor/dependencies.py,只有两个轻量手段:

探测对象 方法 说明
Python 包(如 PyPDF2) importlib.util.find_spec() 只查"能不能找到模块",并不真正 import,不会触发包的初始化逻辑
系统命令(如 pdftotext) shutil.which() 只查命令是否在 PATH 中,不执行它

用"找一下"代替"跑一次",是只读探测的关键:查得快、无副作用,也不会在探测阶段就暴露解析错误。

输出如何解读

run_dependency_check() 会按 9 个功能组逐项打印 ✓/✗,例如:

知识学习助手 — 依赖检查(只读)

  PDF(文字型)
      ✗ python: PyPDF2
      ✗ python: pdfminer.six
      ✗ system: pdftotext
      → 可选增强缺失,存在回退或可跳过

每组最后的状态行很有讲究,共三种:

  • 可用:至少一条解析路径就绪;
  • 可选增强缺失,存在回退或可跳过:没装也没关系,走回退;
  • 缺失且无内置回退:只有 MOBI/AZW/AZW3 这一组会出现,因为它依赖 Calibre 的 ebook-convert,没有内置替代。

macOS 用户还有惊喜:系统自带的 Swift + PDFKit 会被识别为一条"零安装"的 PDF 文字层解析路径(macos_pdfkit_available() 检测 swift 命令),无需装任何 Python 包。

九组可选依赖与回退策略

依赖清单集中定义在 scripts/extractor/config.py 的 PYTHON_DEPENDENCIES 映射表和 dependencies.py 的 DEPENDENCY_GROUPS 分组里。整张"能力地图"如下:

格式场景 可选组件 缺失时的行为
文字型 PDF pdftotext、PyPDF2、pdfminer.six(任一即可),macOS 还有系统 PDFKit 自动回退到任一可用路径
表格/公式密集 PDF Docling 回退到文字提取链,并标注视觉复核边界
扫描版 PDF OCRmyPDF + pdftotext 标记"需 OCR/视觉复核",不冒充文字层
EPUB ebooklib + Beautiful Soup 回退到标准库 ZIP/HTML 解析
DOCX python-docx 优先走标准库 ZIP/XML 解析器
RTF striprtf 回退到基础正则清理
HTML Beautiful Soup 回退到标准库 html.parser
PPTX/PPTM 无 标准库解析即可,保留幻灯片编号与备注
MOBI/AZW/AZW3 Calibre ebook-convert ⚠️ 唯一无内置回退,缺失时明确报错退出

几个值得注意的细节:

  • "任一可用即可"语义:文字型 PDF 组带 any_tool_suffices 标记,pdftotext、PyPDF2、pdfminer 三者有一就行,避免"装了三件套"的强迫症;
  • 标准库优先:DOCX 组的标准库解析器反而比 python-docx 更优先,能保留正文顺序、表格、脚注和图片占位,可选包只是兼容回退;
  • 缺失即告知:每次真正提取时,prepare_dependencies() 会针对当前格式打印"可使用可选包 XX,当前将使用回退方案 YY",让你随时知道正在走哪条路。

真实流程:一个 PDF 的解析回退链

以最常见的文字型 PDF 为例,提取器的实际路由是:

  1. 先查 pdftotext(系统命令);
  2. 没有则依次尝试 PyPDF2、pdfminer;
  3. macOS 上再尝试系统 PDFKit(Swift 调用,零安装);
  4. 都读不到文字层时,判定可能是扫描件,标记"无文字层/待 OCR",而不是盲目硬解。

整个链条在 scripts/extractor/utils.py 的 extract_single_file() 中组织,每一步都如实打印"正在尝试什么、成功还是失败"。这种"逐级降级 + 如实报告"的设计,正是零安装哲学能成立的底气——不是没有依赖,而是任何一档依赖缺失都不会让流程悄悄失败。

顺带一提,格式识别本身也不依赖扩展名:对未知后缀,提取器会嗅探文件头魔数(%PDF 是 PDF,PK 开头的 ZIP 再细分为 EPUB/DOCX/PPTX),并把 ZIP 容器交给 scripts/extractor/archive_safety.py 做路径穿越、条目数、展开体积等安全校验后才解析。

给新手的实用建议

  1. 装完先体检:拿到仓库后,先跑 python3 scripts/extract.py --check,两秒看清本机能力版图,再决定要不要补任何组件;
  2. 按需补装,固定版本:确实缺什么,就自己在虚拟环境里装对应包(如 pdfminer.six),项目从不替你决定版本;
  3. 别为"缺 ✗"焦虑:只要常用格式显示"可用"或"存在回退",学习页生成流程完全不受影响;
  4. MOBI 用户注意:只有电子书的 MOBI/AZW/AZW3 格式是硬依赖 Calibre,装好后 ebook-convert 出现在 PATH 里即可;
  5. 信任但核验:能力探测只反映"工具在不在",扫描件的 OCR 边界、图表的视觉复核仍需按 references/ 目录下的审计规则如实记录。

延伸阅读

零安装并不是"不依赖",而是一种把依赖关系摊在阳光下、把决定权交给用户的工程态度。理解了这套能力探测与回退策略,你就能在任何一台电脑上,快速、安全地把材料变成自己的学习网页。

登录后查看全文
learn-from-materials