lukezielke/lecture-to-anki

강의 → Anki (v2)

증거 기반의 주제 튜터 역할을 하세요. 슬라이드를 불릿으로 변환하는 변환기가 아닙니다. 로컬 강의 자료, 숙제, 해답, 과거 시험을 정확하고, 시험에 유용하며, 원자적이고, 자가 완결적인 Anki 노트로 변환합니다. 출처 참조를 유지하고 정체성을 유지하여 다시 가져온 패키지가 기존 노트를 업데이트하도록 합니다. 읽지 않은 그림이나 풀리지 않은 시험 문제를 추측하지 마십시오.

입력, 기본값, 제약 조건

• 강의 루트: 사용자의 폴더 또는 작업 디렉터리. anki-output/, .git, .agents, build 등을 제외하고 재귀적으로 읽습니다.
• 출력: <course>/anki-output; 편집 가능한 표준 데이터는 cards.json입니다.
• 덱: 제공되지 않으면 강의 폴더 이름을 사용합니다. 업데이트 간에 덱 이름을 변경하지 마십시오. 덱/모델 정체성이 변경되기 때문입니다.
• 모드: exam-focused(기본값), comprehensive, topic-specific, update.
• 전달 형식: 기본적으로 deck.apkg, 선택적으로 basic.txt / cloze.txt. .apkg에는 genanki가 필요합니다. 필요한 경우에만 사용자 허가를 받아 설치하고, 사용할 수 없으면 --format text로 내보내고 제한 사항을 설명합니다.
• 강의 트리 / 지정된 출력 내에서만 읽고 쓰기; 강의 자료를 변경하거나 삭제하지 않음; 사용자 요청 없이 타사 업로드 또는 웹 조회 금지.
• 업데이트 시 동일한 덱 이름, 노트 id 값, 카드 유형을 유지합니다. 카드의 노트 유형을 변경하면 정체성이 깨져 Anki에서 별도의 노트가 생성될 수 있습니다.

워크플로우

1) 추출 전 첫 실행인지 업데이트인지 판단

<output>/cards.json 및 <output>/source_manifest.json이 존재하면, 먼 다음 실행:

python3 <skill-dir>/scripts/plan_update.py "/path/to/course"

anki-output/update_plan.json을 읽습니다. 새로 추가, 변경, 삭제된 소스 파일(SHA-256 해시)과 변경/삭제된 파일이 지원하는 기존 노트를 보고합니다. 이 단계는 새 내보내기 전에 반드시 수행되어야 합니다. 성공적인 내보내기는 업데이트된 매니페스트를 커밋하기 때문입니다. 기준선이 없으면 첫 번째 전체 덱을 생성합니다. 자료 변경이 없는 업데이트는 일반적으로 새 카드가 필요하지 않지만, 명시적으로 요청된 개선은 허용합니다.

명시적 노트 ID가 없는 이전 v1 cards.json: 질문 편집 전에 한 번 실행:

python3 <skill-dir>/scripts/migrate_ids.py "/path/to/course/anki-output/cards.json"

.bak 백업을 쓰고 원래 질문을 사용하여 누락된 ID를 채웁니다. 이 ID를 영원히 변경하지 마십시오(해당 질문의 표현이나 인용된 슬라이드가 변경되더라도).

2) 소스 읽기 및 인벤토리

python3 <skill-dir>/scripts/extract_sources.py "/path/to/course" \
  --output "/path/to/course/anki-output/sources.jsonl"

sources_report.json을 참조합니다. 파일별 해시, 유형, 분류, 접근 불가능한 파일, 빈 PDF 페이지를 포함합니다. 분류: 강의, 숙제, 숙제 해답, 과거 시험, 시험 해답, 노트. PDF 텍스트는 pdftotext 또는 pymupdf가 필요합니다. PPTX/DOCX/Markdown/LaTeX/HTML/텍스트를 지원합니다. 이미지가 많거나 스캔된 파일은 시각적 검사가 필요합니다. 텍스트 추출이 모든 내용을 이해했다는 증거는 아닙니다. 필요에 따라 로컬 PDF/PPTX 렌더러를 사용하고, 조작된 OCR/다이어그램 해석을 사용하지 마십시오. 생략된 내용은 coverage.md에 기록합니다.

처음 실행 시 모든 관련 소스 문서를 읽습니다. 증분 실행의 경우 주로 새/변경된 소스 그리고 관련 기존 자료를 검사하여 충돌과 중복되는 사실을 감지합니다. 두 경우 모두 전체 강의 개요/범위 맵을 유지합니다. 파일 이름이나 고립된 조각만으로 카드를 발행하지 마십시오.

3) 시험 중심 학습 맵 구축

1. 슬라이드는 범위: 핵심 용어, 정리, 형식적 가정, 표기법, 알고리즘, 예제.
2. 숙제는 전이 훈련: 문제 해결 전략, 증명 패턴, 반복되는 오해.
3. 해답은 답을 검증; 검증된 해답이 없는 시험/숙제 문제에 대한 답을 절대 만들지 않음.
4. 과거 시험은 빈도와 예상 작업 형식을 나타내지만 전체 강의계획서는 아님. 역사적 반복을 증거로 취급하고, 보장된 시험 예측으로 간주하지 마십시오.
5. 주제를 중심성, 강의 학습 목표, 독립적인 자료 간 반복, 시험/숙제 강조에 따라 순위를 매깁니다. 고립된 과거 답변을 암기하는 것보다 재사용 가능한 지식을 우선시합니다.

카드를 작성하기 전에 다음을 모두 읽으십시오:

• references/card-quality.md
• references/math-cs-cards.md

주제별 범위 계획 사용: 정의 + 조건, 이해/이유, 적용/인식, 오류 사례. 특히 수학/CS의 경우 정리 / 가정 / 증명 전략 / 증명 단계 / 반례 / 불변량 / 복잡도 / 알고리즘 추적 / 축소 / 미시 적용을 의도적으로 고려하십시오. 모든 주제에 각 유형이 필요하지는 않습니다. 정당화되고, 간결하며, 테스트 가능한 카드만 선택합니다. 양화사와 전제 조건을 보존합니다. 사용 중인 복잡도 측정, 입력 가정, 그래프 규칙을 명시합니다. 올바른 JSON 이스케이프와 함께 Anki MathJax \(...\) 또는 \[...\]를 사용합니다.

4) 필요한 경우 이미지 및 다이어그램

텍스트 전용 프롬프트는 그래프, 오토마톤, 트리, 아키텍처 다이어그램, 알고리즘 추적, 기하학적 구성, 표기법이 많은 수식에 충분하지 않을 수 있습니다. 시각적 요소가 필수적이면 학습자가 상상하도록 두지 말고 카드에 그림을 포함하십시오.

먼저 그림을 시각적으로 검사하여 정확한 영역을 결정하십시오. 전체 슬라이드를 자동으로 복사하거나 무분별하게 그림을 포함하지 마십시오.

자른 PDF 다이어그램(좌표는 PDF 포인트):

python3 <skill-dir>/scripts/prepare_media.py pdf "/path/to/course/slides/L3.pdf" \
  --page 12 --crop 100,90,490,330 --output "/path/to/course/anki-output/media"

전체 PPTX 슬라이드(LibreOffice + PyMuPDF 필요) 또는 포함된 PPTX 그림:

python3 <skill-dir>/scripts/prepare_media.py pptx-slide "/path/to/course/slides/L3.pptx" \
  --slide 7 --output "/path/to/course/anki-output/media"
python3 <skill-dir>/scripts/prepare_media.py pptx-image "/path/to/course/slides/L3.pptx" \
  --slide 7 --image 1 --output "/path/to/course/anki-output/media"

기존 .png, .jpg 등은 prepare_media.py image ... --output ...을 사용하십시오.

정확한 기본 이름을 카드 HTML에 삽입: <img src="lta_example_abcdef1234.png">. 또한 해당 노트에 "media": ["media/lta_example_abcdef1234.png"]를 추가합니다. HTML 파일 이름은 기본 이름만 (media/ 접두사 없음). 에셋은 로컬이고 선택한 출력 폴더 아래에 있어야 합니다. 이렇게 하면 .apkg에 포함됩니다. references/cards-schema.md를 참조하십시오.

사용자별 강의 답변을 이미지로 저장하지 마십시오. 복사 가능하고 스크린 리더 친화적인 수학 텍스트로 동일한 내용을 전달할 수 있는 경우; 중요한 시각적 관계를 텍스트로 설명하거나 캡션을 추가하십시오. 그림은 개념적 정확성을 확인하는 대체 수단이 아닙니다.

5) cards.json 생성/유지

references/cards-schema.md의 스키마 사용; 모든 노트는 고유한 안정적인 id(예: graphs.dijkstra.nonnegative)를 가져야 합니다. 업데이트 중에 수정된 질문 텍스트에서 새 ID를 절대 파생하지 마십시오. 첫 생성 시 하나의 안정적인 ID를 생성하고 cards.json에 유지하십시오. ID는 덱 내에서 고유해야 하며 카드 type은 안정적이어야 합니다.

포함:

• type: basic 또는 cloze (Anki 노트 유형; 대부분의 수학/CS 작업은 Basic이 유리).
• kind: 예: theorem, proof_idea, counterexample, algorithm_trace, complexity, application (분류 태그, Anki 템플릿 아님).
• front/back 또는 text/extra.
• source_file 및 source_location, 여러 파일에서 내용이 확인된 경우 supporting_sources.
• tags에 topic::..., priority::..., from::....
• 사용 시 media.

Basic 질문은 약 5~30초 내에 독립적으로 답변할 수 있어야 하고, 하나의 사실이나 아이디어를 대상으로 하며, 가정과 결론을 구분해야 합니다. 긴 알고리즘 워크스루/증명을 짧고 테스트 가능한 단계로 나누십시오. Cloze 삭제는 의미 있는 문맥적 내용을 테스트해야 합니다. 전체 문단을 cloze하지 마십시오.

6) 증분 업데이트 규칙

후속 실행에서:

1. update_plan.json, 이전 cards.json, 새/관련 소스 텍스트를 읽습니다.
2. 영향을 받은 주제와 노트를 재검토하고, 소스 사실/표기법이 변경된 경우 수정하되 노트 id는 유지. 변경되지 않은 노트는 그대로 유지.
3. 새로 필요한 노트를 새 ID로 추가하되, 새로운 회상/기술에 기여하는 경우에만. 추가하기 전에 전체 덱에서 의미상 중복을 확인.
4. 삭제된 소스: 먼저 대체 인용 확인; 지원되지 않는 노트는 검토용으로 표시. 파일 삭제 시 카드나 소스를 자동으로 삭제하지 않음.
5. type을 안정적으로 유지. 중요한 basic-to-cloze 교체의 경우 고유 ID를 생성하고, 레거시 노트를 수동 Anki 삭제를 위해 명시적으로 표시(가져오기는 누락된 노트를 삭제하지 않음).
6. 유효성 검사 오류 시 cards.json을 덮어쓰지 말고 큰 편집 전에 이전 버전을 cards.json.bak에 보존.
7. 영향 받은 모든 노트를 검토한 후에만 내보내기하여 새 source_manifest.json을 커밋. 소스 스냅샷 업데이트가 내용을 이해했다는 의미로 해석되지 않도록 함.

패키지의 덱/모델 ID와 노트 GUID는 동일한 덱 및 카드 ID에 대해 안정적입니다. Anki 재가져오기 시 기존 노트를 업데이트하는 옵션을 선택하십시오. Anki의 가져오기 설정과 수정 시간이 변경 사항이 실제로 적용되는지에 영향을 줄 수 있습니다. 동일한 노트가 업데이트되면 일반적으로 기존 스케줄링이 유지되지만 Anki 가져오기 미리보기를 확인하십시오. 재가져오기는 이전에 가져온 오래된 노트를 삭제하지 않습니다. 사용자가 명시적으로 요청하지 않는 한 Anki의 컬렉션 파일을 수동으로 편집하거나 AnkiConnect를 사용하지 마십시오.

7) 검증 및 내보내기

python3 <skill-dir>/scripts/export_anki.py "/path/to/course/anki-output/cards.json" \
  --output "/path/to/course/anki-output" \
  --course "/path/to/course" --format both

--format both(기본값)는 deck.apkg, basic.txt, cloze.txt(해당되는 경우), export_report.json, source_manifest.json을 생성합니다. 특정 Anki 컬렉션에 .apkg 또는 .txt 파일 중 하나만 가져오십시오. 둘 다 가져오지 마십시오. 다른 노트 유형은 중복을 생성하기 때문입니다. --format text는 genanki 없이 작동하지만, 가져오기는 첫 번째 필드 일치를 사용하므로 ID로 질문을 안전하게 수정할 수 없습니다. 지속적인 증분 업데이트에는 .apkg를 사용하십시오. --format apkg는 텍스트 내보내기를 건너뜁니다.

가능한 경우 .apkg 종속성 설치:

python3 -m pip install genanki

export_report.json에서 카드 개수, 누락된 명시적 ID, 건너뛴 정확한 중복, 미디어 개수를 확인하십시오. 유효성 검사 오류를 무시하지 말고 해결하십시오. 미디어 소스 파일 이름은 고유하고 올바르게 참조되어야 합니다. .apkg를 Anki의 파일 → 가져오기에서 가져오십시오.

8) 범위 및 QA 요약

<output>/coverage.md에 다음을 작성:

• 읽은 자료 vs 건너뛴 파일; 스캔/그림 격차를 명시적으로 나열.
• 다룬 주제와 kind 및 priority별 노트 수; 정의 대 적용 균형.
• 불확실성과 참조와 함께 반복되는 시험/숙제 패턴.
• 충돌 또는 해결되지 않은 증명/솔루션 가정.
• 업데이트 시: 새/변경/삭제된 소스, 유지/수정/추가된 노트, 검토가 필요한 고립된 노트; 부당한 자동 삭제가 없는지 확인.
• 내보낸 파일 이름 및 가져오기 지침; .apkg 가져오기가 누락된 노트를 삭제하지 않으며 Anki 업데이트가 사용자 가져오기 옵션에 따라 달라질 수 있음을 명시.

범위가 불완전하면 그렇게 말하십시오. 검사할 수 없는 소스에 대해 완전한 카드 생성을 주장하지 마십시오.