Drive Manager
v0.1.0-beta.8 실데이터 검증 완료

AI는 분류하고, 사람이 검토하고,
한 번에 안전하게 적용합니다.

gdrive-organizer는 Google Drive를 메타데이터만으로 스캔해 LLM이 정리 plan을 만들고, 사용자가 검토한 뒤 batch API로 적용·롤백할 수 있는 CLI 도구입니다. 이 페이지는 실제 1500+ 파일 Drive에서 검증된 기능만 정리합니다.

Plan → Apply 분리

AI는 plan을 만들 뿐, 적용은 사용자 승인 후. dry-run · 트래시드 부모 가드 · 스냅샷 freshness 검사가 기본 작동합니다.

완전 롤백 지원

모든 적용은 rollback log를 남기고, 한 줄 명령으로 이전 상태로 되돌릴 수 있습니다. 실패한 op도 로그에 API 에러까지 기록됩니다.

파일 내용은 보내지 않음

LLM에는 파일명·경로·MIME 타입 같은 메타데이터만 전송. 본문은 분류 대상이 아닙니다.

빠른 시작 — 5단계

설치·OAuth 설정이 끝났다는 가정. 처음 보는 Drive에 대해서도 30분 안에 한 사이클을 돌릴 수 있습니다.

  1. STEP 1
    스캔
    scan

    Drive 메타데이터를 한 번에 수집해 로컬에 저장.

  2. STEP 2
    분류
    classify

    LLM이 분류·정리 plan을 생성.

  3. STEP 3
    검토
    plan show · view

    CLI 표 또는 웹 뷰어에서 plan 확인.

  4. STEP 4
    적용
    plan apply --dry-run

    dry-run으로 destination 분포 확인 후 실 적용.

  5. STEP 5
    필요시 롤백
    plan rollback

    마지막 적용을 한 번에 되돌리기.

# 1. 스캔 (전체 메타데이터 수집)
$ gdrive-organizer scan

# 2. AI 분류 → plan 생성
$ gdrive-organizer classify --preset migration

# 3. 검토 (CLI 또는 웹 뷰어)
$ gdrive-organizer plan show
$ gdrive-organizer view              # http://localhost:8765

# 4. dry-run으로 destination 분포 확인 후 실제 적용
$ gdrive-organizer plan apply --dry-run
$ gdrive-organizer plan apply -y

# 5. 문제 발견 시 롤백
$ gdrive-organizer plan rollback -y

스캔 scan

Flat-crawl 전략: files.list 한 번으로 전체 파일을 내려받고 메모리에서 트리를 재구성합니다. 재귀 폴더별 쿼리 대비 API 호출이 100배 적습니다. 결과는 로컬 JSON 스냅샷으로 저장되고, 이후 --incremental로 변경분만 동기화할 수 있습니다.

기본 전체 스캔 
$ gdrive-organizer scan
# Scanning Drive... (1532 files)
# scan complete: 1532 files in 2 pages, 19.12s total
┌──────────────┬───────────────────────────┐
│ Files        │ 1222                      │
│ Folders      │ 310                       │
│ Total items  │ 1532                      │
│ Duration     │ 19120ms                   │
│ Snapshot     │ 2026-05-04T...json.gz     │
└──────────────┴───────────────────────────┘
증분 스캔 후 변경분만 
$ gdrive-organizer scan --incremental
# Changes API로 마지막 스캔 이후의 추가/수정/삭제만 가져옴
# Incremental scan complete.
# Files: 1224 | Folders: 310

change token이 만료(7일 이상 미사용)된 경우엔 친절한 에러로 전체 스캔을 안내합니다.

고급 옵션 — 부분 스캔, 필터, 빠른 측정용 --minimal-fields b8 신규

특정 폴더만

$ gdrive-organizer scan --folder 1abc2def...

필터 무시 (전체 포함)

$ gdrive-organizer scan --no-filter

빠른 측정용 슬림 필드셋 b8 

$ gdrive-organizer scan --minimal-fields
# 플래너가 강하게 필요로 하는 필드만 요청 → 페이지당 응답이 더 작고 빠름
# 트레이드오프: permissions / revisions enrichment 단계는 건너뜀

스캔이 느릴 때 --minimal-fields on/off로 두 번 측정해 비교하세요. 결과는 docs/SCAN-PERFORMANCE.md에 기록.

AI 분류 classify

스냅샷의 메타데이터를 LLM에 배치로 보내 분류 plan을 만듭니다. 본문은 보내지 않습니다. migration 프리셋은 1500+ 파일 Drive에서 다섯 단계 dogfood로 검증된 기본 모드입니다.

검증됨 migration 프리셋이 한 번에 처리하는 4가지
1
시계열 보관함 이동

모든 파일의 created_time(처음 Drive에 올라간 시점)을 기준으로 🪄 AI 정리/보관함/YYYY/MM 트리에 자동 정렬합니다. modified_time이 아니라 created_time을 쓰는 이유는 — 도구가 파일을 옮기거나 description을 바꾸면 modified_time이 작업 시점으로 갱신돼 모든 파일이 한 폴더로 쏠리기 때문입니다. created_time이 없는 일부 파일은 modified_time으로 폴백하고, 둘 다 없으면 미분류/로 모입니다.

2
기존 폴더 → 바로가기 보존

파일 원래 위치의 의미있는 폴더명을 LLM이 식별해 그 폴더 안에 바로가기를 만듭니다. 시계열로 옮겨도 기존 맥락(주제/프로젝트)을 잃지 않습니다.

3
한국어 description 자동 작성

파일명·경로·MIME 타입 컨텍스트로 LLM이 검색용 한국어 요약 + 키워드를 작성하고 Drive의 description 필드에 주입합니다. Drive 네이티브 검색에 그대로 잡혀요.

4
md5 중복 자동 trash

md5 해시가 같은 파일 그룹에서 가장 오래된 사본을 junk로 식별해 TRASH 후보로 자동 등록합니다. 적용 후에도 Drive 휴지통에 30일 보관되니 안전합니다.

실행
$ gdrive-organizer classify --preset migration
# Analyzing 1532 files in 26 batches (Semaphore=10 parallel)
# LLM phase: 1m 35s wall (13× faster than serial b3)
# Plan saved: ~/.local/share/.../plan-2026-05-04T...json
생성된 plan op 예시 (3번 — description 주입)
# plan-XXXX.json 의 한 op
{
  "file_id": "1A2B3C...",
  "operation": "update_description",
  "new_description": "GDrive Organizer 아키텍처
    설계 문서. 키워드: Google Drive API,
    OAuth, CLI",
  "reason": "설명 주입"
}
사용자 정의 custom 프리셋 — 자체 룰 주입

팀 명명 규칙, 키워드 매핑, 특정 도메인의 분류 기준 등을 자체 system prompt 파일로 만들어 LLM에 직접 지시할 수 있습니다. JSON 응답 컨트랙트(file_id / move_to / shortcuts / new_description)는 자동으로 prompt에 덧붙습니다. 

$ gdrive-organizer classify --preset custom \
    --prompt-file ./team-naming-rules.md
# 사용자 prompt 안에서 분류 기준·폴더 컨벤션을 자유롭게 정의
플래너 안전장치 (자동 적용) — ownedByMe=False(공유받은 파일)와 mimeType=shortcut은 분류 후보에서 제외됩니다. 둘 다 Drive가 move/update를 거부하므로 plan에 들어가면 100% 실패하기 때문입니다. destination 이름 충돌은 (2), (3) 같은 suffix로 자동 rename — 예전엔 drop해서 파일이 영원히 root에 남았던 동작.
사용 가능한 프리셋 목록 / 상세 보기 
$ gdrive-organizer preset list
$ gdrive-organizer preset show migration

계획 검토 plan show

AI가 만든 plan을 적용 전에 반드시 확인하세요. CLI 표는 페이지 단위로 분할 출력해 큰 plan도 차분히 살펴볼 수 있고, 정밀 검토는 웹 뷰어가 더 편합니다.

전체 요약 보기
$ gdrive-organizer plan show
# 가장 최근 plan을 단계별 op 타입 분포로 표시
특정 phase / 페이지네이션
$ gdrive-organizer plan show --phase 2 --per-phase 50
# Phase 2 (Move/Rename)만, 50건씩 출력
Plan은 4 phase로 실행됩니다
Phase 1
폴더 생성
(부모 → 자식 순)
Phase 2
Move / Rename / Trash
(batch API)
Phase 3
바로가기 생성
(검증 후)
Phase 4
설명(description)
업데이트

적용 & 롤백 plan apply / rollback

token bucket으로 Drive write rate를 자체 제한하고, batch API로 100 op씩 묶어 호출합니다. 모든 적용은 rollback log로 기록되어 한 줄 명령으로 되돌릴 수 있습니다.

b8 신규 Dry-run이 destination 분포를 보여줍니다

Phase 요약 다음에, 어느 폴더에 몇 개가 들어갈지 상위 15개를 표로 출력합니다. AI 분류가 이상한 곳에 모는 경우를 적용 전에 잡아낼 수 있어요. 

$ gdrive-organizer plan apply --dry-run

# 1) Phase 요약
┌─────────┬─────────────┬───────┐
│ Phase 1 │ FOLDER      │    87 │
│ Phase 2 │ MOVE        │  1222 │
│ Phase 2 │ RENAME+MOVE │   853 │
│ Phase 3 │ SHORTCUT    │   105 │
└─────────┴─────────────┴───────┘

# 2) b8 신규: destination별 분포
┌──────────────────────────┬─────┐
│ /🪄 AI 정리/Photos        │ 412 │
│ /🪄 AI 정리/Documents     │ 287 │
│ /🪄 AI 정리/Code         │ 198 │
│ ...                      │ ... │
└──────────────────────────┴─────┘
... 9 more folders
실제 적용
$ gdrive-organizer plan apply -y
# Phase 1: Creating 87 folders...
# Phase 2: Processing 2075 file operations...
#   ███████████████ 2075/2075
# Phase 3: Creating 105 shortcuts...
# Success: 2266
# Refreshing snapshot via incremental scan...
# Snapshot refreshed.

b7 적용 직후 자동 incremental 재스캔 → 뷰어와 다음 plan이 항상 최신 상태.

b8 신규 실패 시 정확한 원인 표시 
# Success: 2265
# Failed: 1
            ┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
            ┃ File ID   ┃ Error                ┃
            ┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
            │ 1bevOv... │ HttpError 403:      │
            │           │ cannotMoveTrashedItem │
            └───────────┴──────────────────────┘
# Rollback log: ~/.local/share/.../rollback-2026-05-04T...json

예전엔 카운트만 떴고 실패 원인은 grep해야 했습니다. 이제 표로 즉시 확인.

마지막 적용을 되돌리기 
$ gdrive-organizer plan rollback -y
# Reversing in reverse phase order so deps are respected:
# shortcuts → moves → folder trash
# Rollback complete: 2265 operations reversed.

가장 최근 rollback log를 자동 선택. 의존 순서를 반대로 풀기 때문에 안전합니다.

유용한 옵션
$ plan apply --verbose     # dry-run에서 op 한 줄씩
$ plan apply --no-rescan   # 자동 재스캔 끄기
$ plan apply --force       # 스냅샷 freshness 가드 우회
$ plan apply --latest-plan # 승인된 subset 대신 전체 plan
적용 전에 자동 작동하는 가드
  • • 스냅샷 freshness — 60분 이상 된 스냅샷이면 적용을 거부하고 재스캔을 안내합니다.
  • • 트래시드 부모 가드 — destination 폴더가 이미 trash로 옮겨졌다면 거부 (보이지 않는 곳에 파일이 들어가는 사고 방지).
  • • shortcut 검증 — 바로가기 → 바로가기 체인, 미해결 placeholder 등 100% 실패하는 op는 사전 차단.
  • • Rate limit — token bucket으로 write rate 제한 + exponential backoff 재시도.

웹 뷰어 view

FastAPI + Tailwind 로컬 서버. 큰 plan은 CLI 표보다 뷰어가 훨씬 편합니다. 스캔으로 스냅샷이 갱신되면 자동으로 다시 읽어옵니다 — 서버 재시작 불필요. 

$ gdrive-organizer view
# Starting dashboard at http://localhost:8765
# 브라우저 자동 열림
Dashboard

스캔 통계, 최근 plan 요약, Drive 사용량 한눈에.

Explorer

트리 탐색, 파일 검색, MIME 타입별 필터.

Plan Review

op별 검토, subset 승인, 적용·롤백 트리거.

Permissions

공유 범위 점검, 외부 공유 파일 식별.

Duplicates

md5 기준 중복 파일 그룹 + 잠재 절약 용량 표시.

Settings

제외 규칙·rate limit 등 설정 변경.

보조 도구

본 흐름과 별개로 자주 쓰는 작은 명령들.

파일 내용 보기 / 내보내기
$ gdrive-organizer cat <FILE_ID>
# Workspace 문서는 자동 export
$ gdrive-organizer export <FILE_ID> \
    --format pdf --output ./out.pdf
트리 / 통계 / 권한 요약
$ gdrive-organizer tree --depth 3
$ gdrive-organizer stats
$ gdrive-organizer permissions
제외 규칙 관리
$ config exclude --show
$ config exclude --add-folder 1abc...
$ config exclude --add-ext .tmp
$ config exclude --add-name "node_modules"
새 폴더 만들기
$ gdrive-organizer create-folder "보관함" \
    --parent 1abc2def...

효율적인 사용 패턴

세 가지 검증된 시나리오. 자기 용도에 가까운 걸 골라 그대로 따라하시면 됩니다.

A
처음 정리하는 Drive

수년간 쌓인 1000+ 파일을 한 번에 정리. 가장 일반적인 케이스.

  1. 1.scan --no-filter로 전체 스캔
  2. 2.view에서 통계·중복·권한 한 번 점검
  3. 3.config exclude로 건드리면 안 될 폴더 등록
  4. 4.scan (필터 적용) → classify --preset migration
  5. 5.plan apply --dry-run으로 destination 분포 확인
  6. 6.이상 없으면 plan apply -y
B
정기 유지보수

한 번 정리한 후 주기적으로 새 파일을 같은 룰로 분류.

  1. 1.scan --incremental로 변경분만 갱신
  2. 2.classify --preset migration
  3. 3.plan apply -y — --rescan이 기본이라 끝나면 자동 동기화

매주 1회 cron이나 launchd로 묶어두면 손이 가지 않습니다.

C
조심스러운 부분 적용

전체 plan에서 의심스러운 op를 제외하고 일부만 우선 적용.

  1. 1.view의 Plan Review에서 op별로 체크
  2. 2.승인한 subset만 저장 (approved plan)
  3. 3.plan apply → 자동으로 approved plan을 우선 사용
  4. 4.문제 없으면 다음 사이클에서 나머지를 검토

향후 개선 예정

구현돼 있지만 아직 일반 사용자에게 권하지 않는 기능 + 알려진 한계입니다. 작업 우선순위는 GitHub 이슈로 추적합니다.

실험 중 본문 내용 기반 PARA 분류 (second-brain)

Workspace 문서를 export해서 텍스트 스니펫을 LLM에 넘기고, PARA 방식의 다중 태그(태그/AI, 프로젝트/X 등)를 추출하는 프리셋이 코드에 들어 있습니다. 1500-파일 규모 풀 dogfood가 아직 진행되지 않아 일반 사용자 노출은 보류 중입니다.

로드맵 내용 분석 기반 자동 네이밍 변경

현재는 충돌 회피용 (2), (3) suffix만 자동으로 붙습니다. LLM이 본문/메타데이터를 분석해 의미있는 새 이름을 제안하는 RENAME op는 JSON 컨트랙트 확장과 함께 차후 도입 예정입니다.

작업 중 웹 뷰어 ↔ Drive 라이브 동기화

현재 뷰어는 로컬 스냅샷 파일을 읽고, 새 스냅샷이 저장되면 자동 갱신합니다(b7). 별도 동작 없이 Drive를 실시간으로 비추는 라이브 모드는 아직 미구현 — 우선 scan --incremental 로 동기화하세요.

UX 정리 루트 폴더 구조 단순화

현재 AI가 만드는 트리는 🪄 AI 정리/보관함/YYYY/MM처럼 두 단계 프리픽스가 붙습니다. 사용자 기존 폴더와 분리하려는 취지지만 한 단계 더 단순화하는 안을 검토 중입니다.

로드맵 파일 종류(MIME) 기반 분류 차원

현재 stats는 종류별 카운트만 보여주고, classify는 시간 + 기존 폴더 컨텍스트 기준입니다. 종류별(이미지/문서/영상/코드) 보관함을 별도 차원으로 두는 옵션은 사용자 피드백을 받은 뒤 결정할 예정입니다.