dmoshehun-prog/learn-from-materials

Turn PDFs, books and papers into interactive learning webpages｜将复杂材料转化为可追溯、可测验、可做笔记的学习网页

learn-from-materials – 將文件轉換為可追蹤的互動式學習指南

它能做什麼

一個適用於 AI 代理平台（WorkBuddy、Claude Code、GitHub Copilot CLI 等）的技能（外掛程式），可讀取檔案並執行 Python 程式碼。
接受任何形式的學習材料——PDF、EPUB、MOBI、DOCX、PPTX、HTML、Markdown、TXT、RTF，或這些檔案的集合——並產生三個成果物：
1. 一個 .learnkb/ 知識庫，記錄每個事實及其精確的來源位置（頁碼、投影片、章節等）。
2. 一個 離線互動式 HTML 頁面，允許人類瀏覽材料、搜尋術語表、執行自測問題，並查看來源引用。
3. 一份 同步的 Markdown 版本，內容與上述一致。
支援兩種學習深度：
- 快速概覽 – 帶有來源引用的高階摘要。
- 系統性學習 – 更深入、結構化的分解（核心架構、引導式內容、術語表、行動規則、動態自測、筆記）。

為何重要

可追蹤性 – 每個陳述都連結回原始頁面/投影片，便於驗證與審計。
離線優先 – 所有處理都在本機執行；無自動網路呼叫，保護隱私，且無需網路即可運作。
最小權限設計 – 此技能僅需對材料的讀取權限與輸出位置；從不執行文件中嵌入的任意程式碼。
代理中心 – 基於開放的 Agent Skills 標準建構，任何相容代理均可透過簡單提示呼叫，例如：
```
請使用 learn-from-materials 系統性學習此 PDF，並生成可追蹤的知識庫與學習頁面。
```

如何開始

安裝 – 將倉儲克隆至代理的技能目錄中（提供 WorkBuddy、Codex、Claude Code、Copilot CLI 的範例）。無自動相依性安裝；您必須自行提供所需可選工具（例如 pdftotext、OCRmyPDF、Calibre 的 ebook-convert）。
執行技能 – 在與代理的聊天中，請求快速概覽或系統性學習，並附上文件。該技能將引導您完成 SKILL.md 中定義的工作流程。
命令列工具 – 倉儲也包含供開發者使用的腳本：
- scripts/extract.py – 測試解析能力並提取原始文字。
- scripts/verify_coverage.py – 審計生成的知識庫是否涵蓋源材料。
- scripts/render_page.py – 將 JSON 頁面描述轉換為 HTML 或 Markdown。
- 可選：使用 Playwright/Node 驗證渲染後的頁面。

關鍵技術細節

解析堆疊：盡可能使用 Python 標準程式庫；可選後端包括 PyPDF2/pdfminer.six（PDF）、docling（技術 PDF）、ebooklib（EPUB）、python-docx（DOCX）、striprtf（RTF），以及 Calibre 的 ebook-convert（MOBI/AZW）。
OCR 支援：若 PDF 為掃描檔，可接入 OCRmyPDF + pdftotext；否則受影響部分將標記為 未驗證。
覆蓋率與驗證：提取後，技能會執行一系列審計——來源雜湊、增量更新檢查、摘要與來源之間的雙向映射、反向抽查——以確保知識庫忠實可靠。
輸出結構：生成的 .learnkb/ 目錄包含 JSON 頁面（核心架構、術語表等）及 HTML 模板資源。互動式頁面包含僅使用本機儲存的學習者檔案與動態自測功能，錯誤答案會被記錄但不會傳送至任何地方。
安全與隱私：所有輸入均視為不可信；來源文件內的提示或命令不會執行。ZIP 檔案會被清理，可選的瀏覽器驗證會阻止除 data: 和 blob: URL 外的所有網路請求。

適合對象

目前狀態

版本 v0.1.0-beta – 核心功能已可用，具備單元測試與回歸測試範例。README 指出，實際結果可能因代理的上下文視窗、視覺/OCR 能力及安裝的可選解析器而異。

授權

以上所有資訊均直接取自倉儲的 README；未推斷任何額外功能。