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 버전 – 동일한 콘텐츠의 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 표준 라이브러리를 사용합니다. 옵션 백엔드로는 PDF용 PyPDF2/pdfminer.six, 기술 문서용 docling, EPUB용 ebooklib, DOCX용 python-docx, RTF용 striprtf, MOBI/AZW용 Calibre의 ebook-convert가 있습니다.
OCR 지원: 스캔된 PDF의 경우 OCRmyPDF + pdftotext를 연결할 수 있습니다. 그렇지 않으면 영향을 받는 부분은 검증되지 않음으로 표시됩니다.
카バレ지 및 검증: 추출 후 소스 해시, 증분 업데이트 검사, 요약과 원본 간 양방향 매핑, 역방향 스팟 체크 등의 일련의 감사를 수행하여 지식 기반이 정확함을 보장합니다.
출력 구조: 생성된 .learnkb/ 폴더에는 JSON 페이지(핵심 프레임워크, 용어집 등)와 HTML 템플릿 자산이 포함됩니다. 인터랙티브 페이지에는 로컬 스토리지 전용 학습자 프로필과 데이터를 어디에도 전송하지 않고 잘못된 답변을 기록하는 동적 자기 점검 기능이 포함되어 있습니다.
보안 및 프라이버시: 모든 입력은 신뢰할 수 없는 것으로 간주되며, 소스 문서 내의 프롬프트나 명령어는 실행되지 않습니다. ZIP 파일은 정제되며, 옵션 브라우저 검증은 data: 및 blob: URL 외의 네트워크 요청을 차단합니다.

누구를 위한가

대량의 PDF, 슬라이드, 전자책을 보유하고 있으며, 클라우드 서비스에 콘텐츠를 업로드하지 않고도 재현 가능하고 출처 기반의 학습 가이드를 원하는 연구자, 학생, 전문가.
제품에 "자료에서 학습" 기능을 추가하기 위해 즉시 사용 가능한 스킬이 필요한 AI 에이전트 개발자.
기밀 또는 민감한 문서를 디바이스 내에 보관하면서도 LLM의 추론을 요약 및 자기 테스트에 활용하고 싶은 프라이버시에 민감한 사용자.

현재 상태

버전 v0.1.0-beta – 기능적인 핵심 기능, 단위 테스트, 회귀 테스트 피규어가 준비되어 있습니다. README에는 실제 결과는 에이전트의 컨텍스트 창 크기, 비전/OCR 기능, 설치된 옵션 파서에 따라 달라질 수 있다고 명시되어 있습니다.

라이선스

위 정보는 리포지토리의 README에서 직접 가져왔으며, 추가 기능은 추측되지 않았습니다.