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

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 네이티브 검색에 그대로 잡혀요. b11 기존 description이 이미 적절하면 LLM이 null을 반환해 재작성을 건너뜁니다 — 매 cycle DESCRIPTION 1242→1.

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...

플래너 지능 b10–b12

같은 Drive에서 classify를 두 번째 돌리면 첫 번째와 거의 같은 plan이 나오는 게 예전 동작이었어요. 지금은 플래너가 "이미 된 일"을 알아채고 빈 plan에 가깝게 줄어듭니다. 실제 사용자 1500-파일 Drive에서 b8 3,944 ops → b12 **221 ops** (94% 감소).

No-op 검출 b10
  • • MOVE: 파일이 이미 destination에 있으면 스킵 — 매 cycle 1,242 → 0/1
  • • SHORTCUT: 같은 (target, parent) 조합이 snapshot에 이미 있으면 스킵 — 중복 생성 박멸
  • • DESCRIPTION b11: LLM 프롬프트가 기존 description이 적절하면 null 반환하라 지시 → 재작성 폭주 방지
Transitive 안전 영역 검출 b10–b12
  • • Drive가 쓰기를 거부하는 폴더와 그 모든 후손을 BFS로 식별
  • • True orphan (parents=[] AND 본인 소유): 부모가 휴지통 → 사용자 manual 처리 필요
  • • External (ownedByMe=False): 외부 공유로 받은 폴더 → 본인 소유 아님, 정리 대상 자동 제외
  • • 둘 다 LLM의 shortcut destination 후보에서 제외 → 100% 실패하던 ops가 plan에 안 들어감
# 같은 Drive에서 두 번 연속 classify 결과 비교 (실 데이터)
                       b8        b10       b11       b12
Total operations    3,944     1,343       356       221
MOVE                1,242         1         1         0
SHORTCUT            1,457       286       349       216
DESCRIPTION         1,242     1,050         1         0
COLOR (backfill)        0        26        26         0  # 한 번 끝
# 첫 plan 대비 감소율: -94%
# 실제 apply: 221/221 (100%) 성공

검토 요청 / 공유받음 분리 b9–b12

Drive 트리에는 사용자가 손댈 수 없는 항목이 두 종류 섞여 있습니다. 뷰어는 그 둘을 명확히 분리해서 보여주고, 플래너는 둘 다 자동으로 작업 대상에서 제외합니다.

⚠️ 검토 요청 (orphan)

기준: parents=[] AND ownedByMe=True

의미: 본인 소유 파일인데 상위 폴더가 휴지통에 있어 Drive UI에서 안 보임 (J6 reparent로 root에 surface).

처리: actionable — Explorer에서 항목 옆 링크로 Drive 열어 부모 복원 또는 파일 이동.

각 파일에 상위 폴더 삭제 - 검토 요망 배지.

👥 공유받음 (external)

기준: ownedByMe=False

의미: 다른 사용자가 공유한 폴더/파일. 사용자에게 읽기 권한만 있음.

처리: informational — 본인 자료가 아니므로 정리 대상에서 자동 제외. 보고 싶을 때만 펼쳐서 확인.

각 항목에 공유받음 배지.

왜 분리가 중요한가 — 둘 다 Drive가 우리 도구의 쓰기를 거부하는 영역이지만, 사용자 행동이 다릅니다. 검토 요청은 사용자가 직접 손댈 수 있는 항목이고, 공유받음은 그냥 "남의 것"입니다. 한 폴더에 섞으면 사용자가 "왜 정리가 안 되지?"하고 의심하게 되는데, 분리하면 명확합니다.

효율적인 사용 패턴

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

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는 시간 + 기존 폴더 컨텍스트 기준입니다. 종류별(이미지/문서/영상/코드) 보관함을 별도 차원으로 두는 옵션은 사용자 피드백을 받은 뒤 결정할 예정입니다.