Skip to content

Latest commit

 

History

History
499 lines (363 loc) · 37.2 KB

README.ko.md

File metadata and controls

499 lines (363 loc) · 37.2 KB

ΠΑΙΔΕΙΑ · Paideia for opencode

당신의 과목, 당신의 패턴, 당신의 오답, 당신의 치트시트.
당신의 자료에서 출발해 한 과목에 영속적으로 머무는 학습 그래프를 만드는 opencode 기반 명령줄 프로그램입니다 — 모든 산출물이 일반 실러버스가 아니라 당신의 손끝에서 빚어집니다.

라이선스 GitHub 스타 수 최근 커밋 주요 언어   opencode Harness Markdown Node.js Python Ollama Qwen3-VL Tesseract   LaTeX Obsidian

GeekNews #1 on 26.05.26GeekNews Weekly #360
Product Hunt launchInteractive demo at taewoopark.com
원본 PAIDEIA의 소개 기사와 인터랙티브 데모입니다.

English README  ·  taewoopark.com — 저자 사이트

PAIDEIA 패밀리 — 하나의 학습 엔진, 모든 에이전트 런타임

플랫폼 저장소 설명
Claude PAIDEIA 원본 — Claude Code 플러그인.
OpenAI Codex PAIDEIA-codex OpenAI Codex 스킬 + 번들 MCP 서버.
opencode PAIDEIA-opencode opencode를 구동하는 명령줄 프로그램.
hermes-agent PAIDEIA-Hermes Hermes Agent 플러그인: CLI 명령 + 게이트웨이 라우팅.
MCP PAIDEIA-mcp 독립형 로컬 MCP 서버 — Alt 로컬 모델에서 PAIDEIA 구동.
Alt · altalt.org PAIDEIA-Alt Exam Radar — Alt 강의 캡처 플러그인 (altalt.org).

일반적인 학습 도구는 평균적인 실러버스를 가르칩니다. Paideia는 당신의 실러버스를 가르칩니다 —
당신의 교수님 강의노트, 당신의 숙제 경향, 당신의 필기, 당신의 오답에서 출발해서요. 모든 산출물은 당신이 직접 편집할 수 있는 마크다운 파일입니다.

macOS에서 실행한 opencode PAIDEIA


Paideia라는 이름에 대하여

고대 그리스에서 Παιδεία는 수동적인 학생에게 사실을 입력하는 일이 결코 아니었습니다. 그것은 원전과의 구조적 만남, 스승 아래의 안내된 연습, 피드백을 더 깊은 수정으로 접어 넣는 성찰적 대화를 통한 — 한 인간의 평생에 걸친 형성이었습니다.

이 하네스는 그 사이클을, 수학·물리·공학 과목의 시험 대비라는 구체적이고 한정된 문제에 대해 구현합니다:

  ingest ──▶ analyze ──▶ drill ──▶ grade ──▶ weakmap ──▶ cheatsheet
     ▲                                                        │
     └────────────────── 피드백 루프 ─────────────────────────┘

학습 단계의 산출물은 코스 폴더의 마크다운 파일로 남습니다. 에이전트와 별개로 계속 읽고, 편집하고, 버전 관리할 수 있습니다. 새로운 산출물을 생성할 때는 해당 단계의 실행 환경·도구·모델이 필요합니다.


일반적인 학습 도구가 하지 못하는 것

Paideia는 당신의 과목, 당신 교수님의 과제, 당신의 실수에서 출발합니다. 강의노트·교재 챕터·숙제·풀이·스캔 답안을 코스 폴더에 넣으면 그것이 학습의 기준이 됩니다.

일반 커리큘럼이나 직접 만든 플래시카드도 함께 사용할 수 있습니다. Paideia가 더하는 것은 풀이에서 반복 패턴을 추출하고, 숙제 밀도로 연습 우선순위를 정하고, 오답 기록을 다음 드릴에 반영하는 흐름입니다. 아래 표는 이 흐름의 차이를 설명하며, 개별 학습 서비스의 기능이나 요금제를 단정하지 않습니다.

축 Paideia 일반 강좌 또는 구조화하지 않은 채팅
풀이 패턴 (P1..Pk) 내 과목의 풀이에서 추출하고 출처를 인용 과목 자료와 별도 지시가 필요
드릴 우선순위 교수님의 숙제 비중으로 가중 별도로 정하고 관리해야 함
치트시트 오답으로 주의점을 고르고 코스 인덱스에서 참조 내용을 가져옴 별도로 구성하고 갱신해야 함
세션을 넘는 과목 상태 코스 폴더의 마크다운 + 메타데이터 서비스와 맥락 제공 방식에 따라 다름
동의하지 않는 산출물 수정 에디터에서 .md를 열어 저장 도구의 편집·내보내기 지원에 따라 다름
다음 학기로 준비 자료 옮기기 코스 폴더를 복사하고 바뀐 자료를 수정 관련 자료와 이력을 옮겨야 함
이해의 변화 이력 파일을 커밋하면 git log / git diff로 확인 도구의 버전 관리 지원에 따라 다름
산출물의 위치 내 디스크의 텍스트 파일 서비스에 따라 다름

모델 작업은 실행 환경이 담당하고, 학습 그래프는 언제든 열고 읽고 수정하고 비교할 수 있는 파일로 남습니다. 제공자를 바꾸거나 구독을 중단해도 이미 만들어진 파일은 사라지지 않습니다.

기본 답안 OCR은 vision이며 실행 환경의 비전 경로로 페이지 이미지를 읽습니다. 로컬 답안 OCR을 쓰려면 Ollama와 qwen3-vl:8b를 설치한 뒤 .course-meta에 OCR_ENGINE: ollama로 지정하거나 grade에 --ocr=ollama 옵션을 붙이세요. 모델을 다운로드하는 것만으로 엔진이 바뀌지는 않습니다. tesseract도 로컬 선택지입니다. 로컬 OCR은 전사 단계를 기기 안에서 처리하며, 이후 분석·채점은 설정된 모델을 사용하므로 전사된 텍스트가 외부 모델에 전달될 수 있습니다.


핵심 원리: 숙제 밀도가 곧 출제 확률입니다

숙제는 Paideia가 시험 준비 시간을 배분하는 일차 신호입니다. 과제가 많이 배정된 절은 더 연습하고, 숙제가 없는 절은 기본적으로 참조 자료로 둡니다. 이 티어는 학습 우선순위이며, 통계적으로 측정한 출제 확률이나 실제 시험 범위에 대한 보장은 아닙니다.

티어 해당 절의 숙제 수 처리 모의고사 배점 목표
🔥🔥 출제 핵심 3개 이상 가장 집중해서 연습 ≥70%
🔥 출제 유력 2개 다음 순서로 연습 ~25%
🟡 출제 가능 1개 가볍게 복습 ≤5%
⚪ 저위험 0개 기본적으로 참조용 기본 0

paideia quiz all, paideia mock 90, paideia hwmap hot은 이 순위를 사용합니다. 배점은 문제를 생성하는 에이전트에 주는 지침이므로, 정확한 비율이 필요하면 생성된 모의고사를 확인하세요. 사용자의 요청과 Exam Radar로 가져온 강의 강조 신호도 복습 범위를 결정하는 데 참고할 수 있습니다.


형성 사이클, 단계별 해설

Mac에서 실제 실행한 CLI를 로컬 터미널 뷰어로 촬영했습니다. 코스 자료는 검증용으로 만든 작은 예제입니다. · 촬영 조건

paideia status
paideia status — course · D-N · phase
paideia --help
paideia --help — command reference
paideia ingest
paideia ingest — Markdown ingest
paideia doctor
paideia doctor — dependency check

셸에서 paideia <명령>을 실행합니다. 이 에디션은 독립적인 Node.js 프로그램입니다. 파일과 단계별 작업 명세를 준비한 다음, 모델 작업을 위해 opencode run을 시작합니다. status를 포함한 명령 17개를 제공하며 init은 init-course의 별칭입니다.

초기 설정·진단·상태 확인·마크다운 복사는 로컬에서 수행합니다. 모델을 사용하는 단계는 각각 별도 CLI 호출입니다. 두 단계로 진행하는 blind/twin 연습에서는 paideia blind <id> --strategy "…" 또는 paideia twin <id> --strategy "…"로 접근법을 제출합니다. 답변을 기다리는 PAIDEIA 채팅 세션은 유지하지 않습니다. 생성된 수식은 Obsidian에서 읽을 수 있습니다.

단계 하는 일 커맨드 산출물
Encounter 교수의 신호를 읽음 paideia ingest converted/**/*.md — 모든 강의·교재·과제·솔루션을 깔끔한 마크다운으로
Structure 코스의 문법을 추출 paideia analyze course-index/{summary,patterns,coverage}.md — 토픽 트리, 반복 풀이 패턴(P1..Pk), HW밀도 시험등급
Practice 숙제 비중에 가중한 능동 회상 paideia quiz twin blind chain mock quizzes/ twins/ chain/ mock/ — 종이에 푸는 문제
Reflection 손글씨 작업이 점수가 됨 paideia grade answers/converted/<name>.md + errors/log.md — 에이전트 비전(기본)/Ollama/Tesseract OCR 후 전략 채점
Diagnosis 오답을 우선순위 약점 리포트로 압축 paideia weakmap weakmap/weakmap_<ts>.md — 추가 전용 이력
Distillation 한 페이지, 오답 기반, 인쇄용 paideia cheatsheet derive pattern cheatsheet/final.md, derivations/<slug>.md

보조: paideia hwmap은 HW밀도 기반 학습 우선순위를, paideia status는 사이클상 현재 위치를 보여주고, paideia init-course는 새 코스 폴더를 부트스트랩합니다.


설치

사전 요구사항

필수

  • Node ≥ 18.17 (하네스 실행 — 순수 ESM, 런타임 의존성 0)
  • opencode (실행 엔진) — npm i -g opencode-ai, 그리고 한 번 opencode auth login
  • Python 3.9+ + 렌더링용 pdf2image·pillow. PAIDEIA가 사용하는 Python 환경에서 python3 -m pip install pdf2image pillow 명령을 실행하세요. 로컬 Tesseract·폴백에는 pytesseract, PDF 내보내기 폴백에는 reportlab을 추가합니다. PAIDEIA_PYTHON으로 가상환경 인터프리터를 선택할 수 있습니다.
  • Unix 계열 셸(bash/zsh). Windows는 WSL2.
  • macOS: brew install poppler tesseract tesseract-lang
  • Linux (Debian/Ubuntu): apt-get install poppler-utils tesseract-ocr tesseract-ocr-kor

선택 — --ocr=ollama 모드용 (모든 페이지 이미지가 기기에 머무름)

  • ollama + qwen3-vl:8b 모델 (~6GB). brew install ollama && ollama pull qwen3-vl:8b.

기본 답안 OCR은 vision이며 위 렌더링 의존성과 정상 작동하는 opencode 비전 모델이 필요합니다. ollama를 선택하려면 로컬 Ollama 서버가 실행 중이어야 합니다. 모델 다운로드만으로 엔진이 바뀌지는 않습니다.

하네스 설치

git clone https://github.com/OPTIMETA/PAIDEIA-opencode
cd PAIDEIA-opencode
npm link          # 또는: npm i -g .  → `paideia`를 PATH에 등록
paideia doctor    # 설치 점검 (opencode, python, poppler, tesseract)

빌드 단계 없음. 직접 실행도 가능: node /경로/PAIDEIA-opencode/bin/paideia.mjs ….

코스별 부트스트랩

이 코스에 쓸 폴더 안에서 터미널을 열고 실행:

paideia init-course

대화형으로:

  1. 이 코스의 인터페이스 언어를 물어봅니다 — en(기본) 또는 ko. 이후 모든 프롬프트·드릴 지시·생성 MD 서술이 이를 따릅니다. 구조 토큰(파일 경로, 커맨드 이름, 패턴 ID P1, P2, …, YAML 키, 등급 마커)은 언어와 무관하게 영어로 유지됩니다.
  2. 기본 OCR 엔진을 물어봅니다: vision(에이전트 비전), ollama(로컬 Qwen3-VL), tesseract.
  3. COURSE_NAME, EXAM_DATE, EXAM_TYPE, USER_WEAK_ZONES를 물어봅니다.
  4. 디렉토리 골격을 생성합니다.
  5. .course-meta(모든 커맨드와 vision_ocr.py가 읽는 INTERFACE_LANG+OCR_ENGINE), AGENTS.md 코스 컨텍스트, 그리고 instructions 키로 AGENTS.md를 폴더 내 모든 실행에 로드하는 opencode.json을 씁니다.
  6. 코스용 ignore 규칙을 추가합니다. 코스 폴더에 .git이 없으면 git init·파일 스테이징·초기 커밋을 시도하고, 기존 저장소에는 자동 커밋하지 않습니다. 이후 변경은 직접 커밋하세요.

단일 채점 호출에서 엔진 덮어쓰기: paideia grade --ocr=vision 경로/answer.pdf.

기존 코스 폴더 (마이그레이션)

INTERFACE_LANG이 없으면 en으로 취급하며, 한국어 설명을 원하면 INTERFACE_LANG: ko를 추가합니다. 다른 에디션에서 이동할 때는 AGENTS.md·opencode.json·OCR 엔진도 확인하세요. Codex의 codex-native는 vision, qwen3-vl은 ollama에 대응합니다. .course-meta가 있으면 init-course는 --force 없이 재초기화하지 않습니다. 강제 실행 시 메타데이터를 다시 쓰고, 변경된 기존 AGENTS.md는 .bak으로 백업하며, 기존 opencode.json은 보존합니다. 개인 이력과 직접 편집한 산출물을 유지하세요.


코스 폴더 구조

paideia init-course 후 폴더는 이렇게 보입니다:

my-course/
├── .course-meta                     # 코스명, 시험일, 인터페이스 언어(en|ko), OCR 엔진
├── AGENTS.md                        # opencode가 매 실행 로드하는 코스 컨텍스트 (opencode.json 경유)
├── opencode.json                    # instructions: ["AGENTS.md"] + 무인 실행용 permission
├── .gitignore                       # 원본 PDF 스캔·OCR 스크래치 숨김; 학습 그래프 자체는 커밋 유지
│
├── materials/                       # 원본 파일을 여기 넣습니다 (PDF/MD)
│   ├── lectures/  textbook/  homework/  solutions/
│
├── converted/                       # 생성 마크다운 — 재변환 전에 편집 내용 보존
│   └── lectures/ textbook/ homework/ solutions/   # `paideia ingest` 출력 (비전 전사 LaTeX)
│
├── course-index/                    # 지식 베이스 — `paideia analyze`가 생성
│   ├── summary.md  patterns.md  coverage.md  radar.md
│
├── answers/                         # 손글씨 스캔 PDF를 여기 넣습니다
│   └── converted/                   # `paideia grade`가 OCR 마크다운을 씀
│
├── errors/log.md                    # 추가 전용 YAML 오답 로그 (weakmap+cheatsheet의 씨앗)
│
├── quizzes/ mock/ twins/ chain/     # 생성 문제 (숨김 정답/솔루션 형제 파일 포함)
├── derivations/ cheatsheet/ weakmap/
└── .paideia/run/                    # opencode에 넘긴 합성 스테이지 spec (실행마다 1개)

원본은 materials/, 답안 스캔은 answers/에 넣으세요. 마크다운 산출물은 모두 편집할 수 있지만 재생성으로 덮어쓸 수 있으니 보존할 수정은 커밋하세요. errors/log.md와 weakmap 이력은 원본 PDF만으로 복구할 수 없는 개인의 시도 기록이므로 보관해야 합니다. 에디션별 컨텍스트 파일과 OCR 엔진 이름은 다르니 FAQ의 코스 이동 안내를 확인하세요.


읽기 팁: Obsidian을 쓰세요

Paideia는 모든 것을 LaTeX 수식($...$, $$...$$)이 든 평문 마크다운으로 씁니다. 아무 에디터로도 읽히지만 **Obsidian**이 자연스럽습니다:

  • 설정 없이 MathJax로 수식 렌더링
  • 백링크로 quizzes/q_<ts>.md에서 인용된 converted/lectures/chN.md §K로 바로 이동
  • 코스 폴더 전체가 그대로 볼트
  • 완전 오프라인·무료·로컬 — Paideia 철학(당신의 노트, 당신의 디스크, 당신의 도구)과 일치

터미널은 마크다운 프리뷰가 있어도 수식에 약합니다 — 그것과 싸우지 마세요.


강의를 담는 쪽: Alt

Obsidian이 읽기 끝단의 동반자라면, **Alt**는 강의가 들어오는 다른 끝단의 동반자입니다. Alt는 강의를 녹음·전사하고, OPTIMETA의 Exam Radar 플러그인이 그 안에서 교수가 구두로 얼마나 강조했는지로 토픽을 랭크합니다. 그것을 paideia alt로 Paideia에 보내면 루프가 닫힙니다: 강의 참석 → 포착 → 시험 신호 추출 → 중요한 것만 공부.


전체 워크플로우 — 예시

Phase 0 — 코스당 한 번 (15분)

cp ~/textbooks/ch*.pdf      ~/courses/my-course/materials/textbook/
cp ~/hw/hw*.pdf             ~/courses/my-course/materials/homework/
cp ~/hw/hw*_sol.pdf         ~/courses/my-course/materials/solutions/

paideia ingest                  # 모든 PDF → 비전 파이프라인 (서브에이전트 병렬, LaTeX 충실)
paideia analyze "약점 힌트"     # patterns + coverage + summary 생성
paideia hwmap hot               # 🔥🔥 시험 핵심 존 표면화

Phase 1 — 진단 (40분)

paideia quiz all 20             # 광범위 진단, 20문제
# 종이에 풀고(40분), answers/diagnostic.pdf 로 스캔
paideia grade                   # OCR + 전략 채점

Phase 2 — 타겟 드릴링 (준비 시간의 대부분)

paideia weakmap                 # 우선순위 약점 리포트
paideia blind hw3-p2            # 알려진 문제의 전략 전용 드릴
paideia blind hw3-p2 --strategy "유수정리(P7), 등고선 고정, 2πi·Σ유수 형태 예상"
paideia twin hw3-p2             # 같은 패턴 새 표면 변형
paideia chain 3                 # 다중 패턴 통합 문제
paideia quiz weakmap 5          # 최신 weakmap 표적 5문제

Phase 3 — 통합 (약 90분)

paideia mock 90                 # HW밀도 가중 90분 모의고사
paideia grade                   # 모의고사 채점

Phase 4 — 압축 (60분, 시험 전날 밤)

paideia cheatsheet --pdf        # 오답 기반 1페이지
paideia weakmap                 # 약점 존 한 번 더 점검

Phase 5 — 쿨다운 (시험 10분 전)

paideia weakmap                 # 상위 3개만. 새로운 건 배우지 말 것.

명령어 (총 17개)

init은 init-course의 별칭입니다.

이 목록은 이 에디션의 실제 제공 기능입니다. 원본의 reindex 또는 graph 명령은 포함하지 않습니다.

커맨드 용도
paideia init-course 새 코스 폴더 부트스트랩 (대화형: 언어, OCR 엔진, 메타, 골격, git)
paideia doctor [--fix] 설치+워크스페이스 진단 (opencode+인증, Python, poppler, tesseract, Ollama/Qwen3-VL, 폴더, .course-meta, 쓰기 경로); --fix는 권한 없이 가능한 항목 복구
paideia status [--banner] 사이클상 위치: paideia · <COURSE> · D-N · <phase> · P<k> ↑
paideia ingest [--force] materials/**의 모든 PDF → converted/** 마크다운 (PDF당 서브에이전트 1개, LaTeX 충실)
paideia analyze [힌트] course-index/{summary,patterns,coverage}.md 생성
paideia hwmap hot|<§> HW밀도 순 🔥🔥 시험 핵심 섹션 표면화
paideia pattern <§|Pk|키워드> course-index의 패턴 카드 표시
paideia derive <대상> derivations/<slug>.md에 깔끔한 레퍼런스 유도
paideia quiz <토픽|§|weakmap> [N] 연습문제 N개, 정답은 _answers.md에 숨김
paideia blind <id> [--strategy "…"] 알려진 문제의 전략 점검 드릴 (제시 후 전략 채점)
paideia twin <id> [--strategy "…"] 알려진 문제의 변형 — 같은 패턴, 새 표면
paideia chain <N> N개 패턴을 묶은 다중 패턴 통합 문제
paideia mock <분> HW밀도 가중 전체 모의고사
paideia grade [--ocr=<엔진>] [경로] .course-meta의 엔진(에이전트 비전/Ollama/Tesseract)으로 답안 PDF OCR, 전략 채점, errors/log.md 추가
paideia weakmap [개념] weakmap/weakmap_<ts>.md에 저장되는 우선순위 약점 리포트
paideia cheatsheet [--pdf] 오답 기반 1페이지
paideia alt [붙여넣기] OPTIMETA Exam Radar(Alt) 내보내기 임포트 → course-index/radar.md + coverage.md 강의강조 열 + 골드존 weakmap

전역 플래그: --model <provider/model> (opencode에 모델 전달), --dry-run (모델 실행 없이 스테이지 spec 합성 + 정확한 opencode 명령 출력).


내부 구조

단계별 실행 방식

프로그램이 코스 루트를 찾고 선행조건을 확인하며 파일과 .paideia/run/의 작업 명세를 준비합니다. 그다음 실행 지시문·--dir·-f <spec>을 붙여 opencode run을 호출합니다. 모델은 명세를 읽고 학습 산출물을 만들며, 프로그램은 임시 파일 정리와 성공한 채점 프로세스 뒤 답안 PDF 보관 처리를 수행합니다.

--dry-run은 모델 호출을 생략하지만 작업 명세 파일은 기록합니다. 모델 단계의 미리보기이며 설정·진단까지 모든 쓰기를 막는 전역 기능은 아닙니다. blind와 twin의 두 번째 단계는 별도 --strategy "…" 호출로 진행합니다.

설정

설정 효과
--model provider/model / PAIDEIA_MODEL 모델 선택. 생략하면 opencode 기본 모델 사용
PAIDEIA_TIMEOUT 긴 자식 프로세스의 제한 시간(초). 기본 1800
PAIDEIA_PYTHON PDF 렌더링·로컬 OCR 인터프리터
PAIDEIA_ASK_PERMISSIONS=1 실행기의 자동 승인 플래그 생략. 코스 opencode.json 권한은 여전히 적용
NO_COLOR=1 / status --plain 색상 없는 상태 출력

부트스트랩은 AGENTS.md와 이를 읽는 opencode.json을 쓰고 edit, bash, webfetch를 허용합니다. 해당 작업의 승인을 받으려면 명시적 권한 규칙도 확인하세요. doctor의 종료 코드는 정상 0, 경고 1, 차단 문제 2이며, 다른 명령은 대체로 성공 0·오류 1입니다. 모델 프로세스의 성공만으로 요청한 모든 산출물이 생성되었음을 보장하지는 않습니다.

인제스트 파이프라인: 모든 PDF를 비전으로

PDF는 페이지 이미지로 렌더링한 뒤 전사하고, 마크다운 원본은 출처 헤더를 붙여 복사합니다. ingest가 변환 자료를 쓰고, analyze가 이를 읽어 summary.md, patterns.md, coverage.md를 만듭니다.

프로그램은 opencode 호출 전에 ingest PDF를 160 dpi, 긴 변 1800 px 이하로 렌더링합니다. 명세는 PDF당 에이전트 하나와 페이지 순서대로 읽기를 요청합니다. 최신 변환본은 건너뛰며 --force로 다시 변환합니다. 같은 분류 안에 이름이 같은 PDF와 .md가 있으면 .md가 우선합니다.

PDF ingest는 항상 opencode의 에이전트 비전을 사용합니다. OCR_ENGINE과 grade --ocr=…는 답안 OCR을 선택하며 ingest를 바꾸지 않습니다. 마크다운만 있는 ingest는 모델 호출 없이 끝날 수 있습니다.

필기 OCR: 세 가지 엔진 중에서 직접 고르실 수 있습니다

종이에 풀고 answers/에 스캔을 넣은 다음 paideia grade를 실행합니다. 엔진은 코스별로 고르고 --ocr=<engine>으로 호출별 변경이 가능합니다.

엔진 기본값? 동작 방식 선택 시점
vision 예 페이지를 렌더링한 뒤 에이전트의 비전 경로로 읽음 비전 모델·도구가 정상 설정되어 있을 때
ollama 선택 로컬 Ollama qwen3-vl:8b, Tesseract 폴백 포함 답안 OCR의 페이지 이미지를 로컬에서 처리할 때
tesseract 선택 로컬 pytesseract 타이핑된 스캔. 필기·수식은 꼼꼼한 확인 필요

기본 답안 OCR은 vision이며 실행 환경의 비전 경로로 페이지 이미지를 읽습니다. 로컬 답안 OCR을 쓰려면 Ollama와 qwen3-vl:8b를 설치한 뒤 .course-meta에 OCR_ENGINE: ollama로 지정하거나 grade에 --ocr=ollama 옵션을 붙이세요. 모델을 다운로드하는 것만으로 엔진이 바뀌지는 않습니다. tesseract도 로컬 선택지입니다. 로컬 OCR은 전사 단계를 기기 안에서 처리하며, 이후 분석·채점은 설정된 모델을 사용하므로 전사된 텍스트가 외부 모델에 전달될 수 있습니다.

라인 단위가 아닌, 전략 기반 채점

채점 지침은 (1) 선택한 패턴 Pk, (2) 변수·치환·기저·경로, (3) 최종 식의 형태를 봅니다. OCR이 불확실하면 전사와 채점 결과를 확인하세요. 오류는 problem_id, pattern, error_type, summary, source, date 필드로 errors/log.md에 추가합니다. 오류 유형은 pattern-missed, wrong-variable, wrong-end-form, algebraic, sign, definition입니다.

치트시트는 코스 인덱스와 오답 이력을 함께 사용합니다. 패턴·공식은 참조 내용을 제공하고, 오답은 주의점과 교정 항목을 결정합니다. --pdf는 cheatsheet/final.md를 pandoc 또는 ReportLab 폴백으로 PDF로 바꿉니다. PDF 생성이 누락되거나 실패해도 경고만 출력하고 종료 코드 0을 반환할 수 있으므로, final.pdf의 존재와 수식 렌더링을 확인하세요.

당신의 풀이에서 추출된 패턴

paideia analyze는 과목의 풀이와 예제를 읽어 반복되는 접근법을 P1, P2, …로 붙이고 converted/의 출처를 인용합니다. 패턴 카드와 숙제 커버리지가 이후 드릴의 맥락이 됩니다. 모델이 만든 인덱스는 실제 과제와 대조해 확인할 수 있습니다.

Append-only 이력

명령은 errors/log.md에 시도를 추가하고 weakmap/에 날짜가 붙은 리포트를 저장합니다. 재변환하거나 에디션을 옮길 때 이 이력을 보존하세요. 문제지와 정답·풀이 파일은 별도로 생성되므로 먼저 문제를 풀고 해답을 여세요.

상태와 세션 배너

paideia status는 코스 · D-N · 단계 · 최다 실수를 보여 줍니다. patterns.md가 없으면 setup, 패턴은 있지만 퀴즈 문제와 인식되는 오답 항목이 함께 있지 않으면 diag, 둘 다 있으면 drill, 모의고사 출처 기록이 인식되면 mock, cheatsheet/final.md나 .pdf가 있으면 cram, 시험 당일이면 cool입니다. 최신 weakmap의 첫 패턴을 우선하고 없으면 오답 로그의 빈도로 판단합니다. 이는 파일 기반 추정이며 숙련도의 증명은 아닙니다.

paideia status --banner는 두 줄 요약을 출력합니다. 직접 실행하는 명령이며 호스트의 세션 시작 훅을 설치하지 않습니다.


배포물

PAIDEIA-opencode/
├── LICENSE                         # MIT
├── README.md  README.ko.md         # 본 파일 + 한국어 미러
├── package.json                    # bin: paideia · ESM · 런타임 의존성 0
├── bin/paideia.mjs                 # 진입점
├── src/
│   ├── cli.mjs                     # 전역 플래그 + 서브커맨드 디스패치
│   ├── core/                       # 하네스 엔진
│   │   ├── opencode.mjs            # 드라이버 — argv 합성, `opencode run` 실행
│   │   ├── prompts.mjs             # 스테이지 spec 합성기 (시스템 + 컨텍스트 + 커맨드)
│   │   ├── render.mjs              # 결정적 PDF → PNG (렌더 + 리사이즈)
│   │   ├── proc.mjs                # 모든 자식 프로세스의 타임아웃·실패 문구 단일 계약
│   │   ├── meta.mjs  workspace.mjs phase.mjs  stage.mjs  args.mjs  i18n.mjs
│   └── commands/                   # 16 커맨드 + status (init-course, ingest, analyze, …)
└── assets/
    ├── prompts/                    # 포팅된 커맨드 지시문 + 공유 _system.md
    └── scripts/
        ├── render_pages.py         # PDF → PNG 렌더 + ≤1800px 리사이즈 (pdf2image + Pillow)
        ├── vision_ocr.py           # 선택: ollama qwen3-vl 드라이버 + tesseract, --ocr=ollama|tesseract 용
        └── md_to_pdf.py            # cheatsheet --pdf: 마크다운 → PDF (pandoc, 없으면 reportlab)

설계 원칙

  1. 수식은 마크다운으로 읽습니다. Obsidian이나 마크다운을 보여 주는 데스크톱 화면에서 코스를 여세요.
  2. 풀이는 종이에 씁니다. 답안을 스캔하고 환경에 맞는 OCR 경로를 고릅니다.
  3. 전략과 전사를 확인합니다. 패턴·변수·최종 형태로 채점하며 OCR과 모델 판단은 교정할 수 있습니다.
  4. 내 과목에서 패턴을 뽑습니다. 제공한 풀이와 예제를 출처로 인용합니다.
  5. 기록한 오답에서 배웁니다. 연습과 치트시트의 주의점에 반영합니다.
  6. 숙제로 우선순위를 정합니다. 밀도를 학습 신호로 삼고 공지된 시험 범위와 대조합니다.
  7. 학습 그래프를 직접 소유합니다. 편집 가능한 마크다운, 보존한 오답 이력, 세션을 넘는 버전 관리입니다.

FAQ

수학 과목이 아닌 경우에도 쓸 수 있나요? 인제스트와 요약은 활용할 수 있지만 연습 과정은 반복되는 문제 풀이 패턴을 전제합니다. 수학·물리·공학 등 정량 과목을 중심으로 설계되었습니다.

다음 세션은 제 작업을 어떻게 기억하나요? 코스 컨텍스트·인덱스·오답 이력이 파일로 남고 다음 명령이 다시 읽습니다. 학습 기록을 대화 이력에만 의존하지 않습니다.

패턴이나 치트시트를 직접 수정해도 되나요? 네. 마크다운 에디터에서 저장하고 재생성 전에 보존할 파일을 커밋하세요. 오답 로그와 weakmap 이력은 따로 유지해야 합니다.

한국어·영어가 섞인 자료도 되나요? .course-meta의 INTERFACE_LANG: en 또는 ko로 생성 설명의 언어를 고릅니다. 파일 경로·패턴 ID·YAML 키·티어 토큰은 유지됩니다. 로컬 OCR 스크립트는 이에 맞는 Tesseract 언어 설정을 사용하므로 필요한 언어팩을 설치하세요.

Ollama가 꼭 필요한가요? 전체 과정이 오프라인인가요? Ollama는 선택 사항이며 기본값은 실행 환경의 비전 경로입니다. 로컬 OCR은 이미지 전사를 기기에서 처리하지만 분석·채점은 설정된 모델을 사용합니다. 엔진별 준비 사항은 위 OCR 표를 참고하세요.

PAIDEIA 에디션 사이에 코스를 옮길 수 있나요? 마크다운 학습 산출물은 폴더 구조를 공유합니다. 먼저 대상 에디션의 컨텍스트 파일(CLAUDE.md / AGENTS.md / PAIDEIA.md)과 엔진 이름(claude / codex-native / vision, ollama / qwen3-vl)을 확인하세요. 기존 메타데이터와 개인 이력을 보존해야 하며, 설정과 명령 목록까지 같지는 않습니다.

모델이 생성한 채점은 확인이 필요한가요? 네. 원본 스캔·전사·참조 패턴·YAML 로그를 대조해 확인하고 고칠 수 있습니다. 상태 표시는 파일에 따른 진행 안내이며 이해도를 독립적으로 측정한 결과는 아닙니다.


연락

GitHub X (Twitter) LinkedIn Instagram Email


라이선스

MIT. 자유롭게 쓰세요. 당신의 코스에 맞게 포크·수정하세요 — 핵심은, 이것이 만드는 학습 그래프가 감내해야 할 고정 상품이 아니라 당신이 빚는 당신의 것이라는 점입니다.

개념·학습 모델·원본 Claude Code 플러그인: OPTIMETA/PAIDEIA. 실행 엔진: opencode.


일반 커리큘럼은 평균적인 학생을 가르친다. Παιδεία — 한 번에 한 학생씩의 형성.