零安装哲学:learn-from-materials能力探测与可选依赖策略全解析
零安装哲学:learn-from-materials能力探测与可选依赖策略全解析
learn-from-materials 是一款把 PDF、EPUB、书籍和课件转化为可追溯、可测验、可记笔记的交互式学习网页的开源工具。它的最大特色之一,是"零安装哲学":不自动安装任何依赖,先用只读命令探测本地解析能力,再为每种格式准备回退方案。本文将带你完整理解它的能力探测机制与可选依赖策略。
learn-from-materials 是什么?
简单说,这是一个"材料变学习页"的工具:你给它一本书、一份 PDF 或一套 PPT,它会提取原文、建立可追溯的知识库(.learnkb/ 目录),最后渲染出一个可交互的离线学习网页——包含核心框架卡片、内容导学、术语大全、行动规则、动态自测和本地笔记六大模块。
生成页面的效果大致如下,内容单元保留了原文的 PDF 页码定位,点击即可查看核心思想、关键框架与行动要点:
框架卡片模块则负责"先抓住材料的知识骨架",把书中的关键判断整理成带编号、带出处引用的框架卡片:
页面首次打开时还有"小巴"引导,帮你在一分钟内学会切换模块、核对出处、发起自测:
零安装哲学:为什么从不自动安装依赖?
很多工具遇到缺库时会默默执行 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 为例,提取器的实际路由是:
- 先查
pdftotext(系统命令); - 没有则依次尝试 PyPDF2、pdfminer;
- macOS 上再尝试系统 PDFKit(Swift 调用,零安装);
- 都读不到文字层时,判定可能是扫描件,标记"无文字层/待 OCR",而不是盲目硬解。
整个链条在 scripts/extractor/utils.py 的 extract_single_file() 中组织,每一步都如实打印"正在尝试什么、成功还是失败"。这种"逐级降级 + 如实报告"的设计,正是零安装哲学能成立的底气——不是没有依赖,而是任何一档依赖缺失都不会让流程悄悄失败。
顺带一提,格式识别本身也不依赖扩展名:对未知后缀,提取器会嗅探文件头魔数(%PDF 是 PDF,PK 开头的 ZIP 再细分为 EPUB/DOCX/PPTX),并把 ZIP 容器交给 scripts/extractor/archive_safety.py 做路径穿越、条目数、展开体积等安全校验后才解析。
给新手的实用建议
- 装完先体检:拿到仓库后,先跑
python3 scripts/extract.py --check,两秒看清本机能力版图,再决定要不要补任何组件; - 按需补装,固定版本:确实缺什么,就自己在虚拟环境里装对应包(如
pdfminer.six),项目从不替你决定版本; - 别为"缺 ✗"焦虑:只要常用格式显示"可用"或"存在回退",学习页生成流程完全不受影响;
- MOBI 用户注意:只有电子书的 MOBI/AZW/AZW3 格式是硬依赖 Calibre,装好后
ebook-convert出现在 PATH 里即可; - 信任但核验:能力探测只反映"工具在不在",扫描件的 OCR 边界、图表的视觉复核仍需按 references/ 目录下的审计规则如实记录。
延伸阅读
- scripts/extractor/dependencies.py:依赖分组、探测与报告的核心实现
- scripts/extractor/utils.py:
--check入口与逐格式回退路由 - scripts/extract.py:提取器命令行入口
- SECURITY.md:设计边界、压缩容器保护与隐私说明
- README.md:功能全景与快速开始
零安装并不是"不依赖",而是一种把依赖关系摊在阳光下、把决定权交给用户的工程态度。理解了这套能力探测与回退策略,你就能在任何一台电脑上,快速、安全地把材料变成自己的学习网页。


