Getting Started

Getting Started

한국어 | English

1. 원본 배치

벤더가 준 원본 zip을 압축을 풀지 않고 그대로 아래 위치에 넣습니다 (이미 풀어서 넣어도 동작합니다).

data/
├── chatgpt/   # ChatGPT의 Data export zip을 그대로, 또는 압축을 푼 내용
├── gemini/    # Google Takeout zip을 그대로, 또는 압축을 푼 내용
└── claude/    # Claude(Anthropic)의 데이터 내보내기 zip을 그대로, 또는 압축을 푼 내용

run.py가 각 벤더 폴더에서 필요한 파일을 못 찾으면 그 폴더 안의 *.zip을 자동으로 그 자리에 풀어본 뒤 다시 찾습니다 (common/zip_extract.py). Google Takeout처럼 여러 파트 zip으로 쪼개져 있으면 전부 같은 폴더에 넣으면 됩니다 — 파트별로 순서 상관없이 풀려서 자연스럽게 합쳐집니다. 원본 zip 파일은 지우지 않습니다.

실제 벤더 export가 어떻게 생겼는지 (압축 풀었을 때 기준)

• ChatGPT ("설정 → 데이터 제어 → 내보내기"로 받는 zip): 보통 폴더로 안 감싸져 있고 conversations.json, chat.html, file_*.dat 등이 압축 최상위에 바로 나옵니다. 압축 해제 도구에 따라 폴더 하나로 한 번 더 감싸일 수도 있는데, 그 경우도 재귀 탐색으로 찾으므로 상관없습니다.
• Gemini (Google Takeout에서 "Gemini 앱"만 선택해서 받는 zip): 항상 Takeout/<서비스명>/ 처럼 한 겹 이상 감싸져 있고, 그 안에 내 활동.html과 첨부 미디어 파일들이 나란히 들어있습니다. Takeout/ 폴더째로 data/gemini/에 넣으면 됩니다 (하위 폴더를 직접 뒤져서 꺼낼 필요 없음).
• Claude ("설정 → 계정 → 데이터 내보내기"로 받는 zip): 압축 최상위에 conversations.json(프로젝트에 안 묶인 일반 대화 전체가 배열 하나로), design_chats/ (프로젝트에 묶인 대화가 파일 하나당 하나씩), projects/(프로젝트 메타데이터, 있는 경우만) 등이 나옵니다. 계정 데이터가 많으면 data-...-batch-0000.zip처럼 여러 파트로 나뉠 수 있는데, 현재는 파트 하나만 지원합니다 — 여러 파트를 같은 폴더에 풀면 conversations.json/design_chats/가 파트끼리 서로 덮어써서 일부 대화가 누락될 수 있으므로, 파트가 여러 개라면 각 파트를 따로 처리해야 합니다.

2. 실행

python run.py

data/ 아래 존재가 감지되는 벤더만 자동으로 골라 실행합니다. 특정 벤더만 실행하려면 --vendor chatgpt, --vendor gemini, --vendor claude 중 하나를 지정합니다. --dry-run을 붙이면 실제 파일을 만들지 않고 파싱 결과(세션 수, 스킵 수, 첨부파일 해석 성공/실패 수)만 콘솔에 출력합니다.

원본을 data/<vendor>/로 옮기고 싶지 않으면(예: 다운로드 폴더에 있는 zip을 그대로 쓰고 싶을 때) --input으로 위치를 직접 지정할 수 있습니다 — 코드 어디에도 실제 경로가 박혀있지 않고 매 실행마다 원하는 곳을 가리킬 수 있습니다:

python run.py --vendor gemini --input "gemini=C:\Users\me\Downloads\takeout.zip"

폴더를 넘기면 그 폴더를 그대로 원본으로 쓰고(아무것도 복사/이동 안 함), .zip 파일을 넘기면 원본은 그대로 둔 채 내용만 data/<vendor>/에 풀어서 씁니다.

3. 결과 확인

결과는 result/<vendor>/*.md (+ result/<vendor>/Attachments/)에 생성됩니다. Claude는 예외적으로 프로젝트에 묶인 대화만 result/claude/<프로젝트명>/*.md처럼 프로젝트별 하위 폴더에 생성되고, 프로젝트에 안 묶인 일반 대화는 다른 벤더와 동일하게 result/claude/*.md에 바로 생성됩니다.

4. Obsidian vault에 반영

검토가 끝났으면 --publish로 실제 Obsidian vault에 반영합니다 (경로 설정은 Configuration 참고).

python run.py --publish

변환(2번)과 vault 반영(4번)을 분리해둔 이유는, 실제 PKM 저장소에 파일을 쓰는 건 되돌리기 까다로운 작업이라 result/를 먼저 검토할 수 있게 하기 위함입니다.

종료 코드

• 0: 정상 완료.
• 1: 실행된 벤더가 하나도 없음 (data/<vendor>/에 아무것도 없음).
• 2: 일부 벤더가 부분적으로만 성공함 (예: conversations-*.json 중 하나가 깨져서 파싱 실패) — 콘솔의 [경고]/⚠️ 로그를 확인해야 합니다. 자동화 스크립트에서 이 파이프라인을 호출한다면 반드시 종료 코드를 검사하세요.

요구사항

런타임 파이프라인 자체는 표준 라이브러리만 사용합니다 (Python 3.10+). 외부 패키지 설치가 필요 없습니다. 테스트를 돌리려면 Development를 참고하세요.