pp-drive-organizer

Python-скрипты, чтобы файлы клиентских проектов Paper Planes лежали на Google Drive там, где должны, а не валились в общую папку. Используется через Codex CLI, Claude Code или просто bash.

Важно для коллег, если вы заходили в репо потому что встроенный Drive connector в ChatGPT/Codex не даёт создать файл в нужной папке — см. раздел ниже. Кратко: он не подходит архитектурно (нет параметра parent), не из-за прав. Решение — этот репо.

Зачем

В Paper Planes Drive-папки клиентских проектов лежат в 4. Производство/РГ1/<Клиент>/ или 4. Производство/РГ2/<Клиент>/, плюс у каждого клиента может быть своя структура подпапок («Внедрение», «Финальные файлы», «Аналитика», «Входящие от клиента», «Административные документы»).

На практике файлы регулярно оказываются не там — либо в корне «4. Производство», либо в случайном месте. Эти скрипты решают две задачи:

1. gdrive_organize.py — раскладывает сваленные в одной папке файлы по проектным папкам автоматически (определяет проект по имени файла).
2. gdrive_upload.py — заливает локальный файл сразу в правильную папку проекта, без ручного поиска ID.

Почему встроенный Drive connector не подходит

Если вы в ChatGPT / OpenAI Codex / Claude Desktop включили готовый «Google Drive» connector — вы быстро упрётесь в то, что нельзя создать файл в конкретной папке клиента. Это не вопрос прав, а ограничение коннектора:

Действие	Встроенный Drive connector	Этот репо
Создать файл	только в «Мой диск», folder_id / parent не принимается	в любую папку (--project, --subfolder)
Переместить файл (move)	нет API	да (gdrive_organize.py)
Обновить parent	нет	да
Удалить	нет	да через прямой Drive API
OAuth scope	ограниченный, серверный (OpenAI)	полный drive, ваш собственный refresh-token

Поэтому встроенный connector годится только «прочитать и пересказать», а любые операции «сделать что-то в проектной папке клиента» — невозможны. Этот репо решает именно эту задачу.

Установка

Требования: Python 3.9+, без сторонних зависимостей.

git clone https://github.com/ntokaeva/pp-drive-organizer.git
cd pp-drive-organizer

Дальше нужно настроить OAuth-токены к своему Google аккаунту. Самый простой способ — запустить интерактивный мастер:

./bootstrap.sh

Он сам открывает нужные страницы Google Cloud Console и собирает токены — займёт 5–15 минут в зависимости от опыта. Если хочешь сделать руками с пониманием каждого шага — см. setup_oauth.md.

После настройки появляется ~/.config/mcp-gdrive/tokens.json и все скрипты начинают работать.

Как сюда подключить Codex / Claude Code

После git clone и настройки tokens.json:

1. Откройте Codex CLI / Claude Code из директории репозитория (cd pp-drive-organizer && codex или cd pp-drive-organizer && claude).
2. Агент автоматически прочитает AGENTS.md и узнает все команды.
3. Дальше можно просто говорить по-русски:
   • «Создай документ "Артефакты встречи 17.05" в МЦ21»
   • «Залей этот файл в Бургер Кинг»
   • «Разложи свалку в папке <id> по проектам»

Агент сам подберёт нужный скрипт и параметры, без указания путей.

Использование

Разложить свалку в одной Drive-папке по проектам

# показать план (dry-run):
python3 gdrive_organize.py 1LbbERfpfZ4O2Xa4OPPmP2rK4z6Rk5hxk

# реально переместить:
python3 gdrive_organize.py 1LbbERfpfZ4O2Xa4OPPmP2rK4z6Rk5hxk --execute

# переопределить подпапку для конкретного проекта:
python3 gdrive_organize.py <ID> --execute --subfolder "БК=Финальные файлы"

ID папки берётся из URL Drive: https://drive.google.com/drive/folders/<этот_кусок>.

Создать пустой Google-документ прямо в проектной папке

# Google Doc в Бургер Кинг → Внедрение (default):
python3 gdrive_create.py "Артефакты встречи 16.05" --project "Бургер Кинг" --type doc

# таблица в Финальные файлы:
python3 gdrive_create.py "Калькулятор июнь" --project "БК" --subfolder "Финальные файлы" --type sheet

# презентация с автоопределением проекта по словам в названии:
python3 gdrive_create.py "БК. Презентация HRM v2" --type slides

# подпапка:
python3 gdrive_create.py "Сессия 2026-05" --project "Деафон" --type folder

Типы: doc | sheet | slides | folder. Возвращает ссылку вида https://docs.google.com/document/d/<id>/edit сразу после создания.

Залить один локальный файл

# автоопределение проекта по имени файла (БК_*, Рокада_* и т.п.):
python3 gdrive_upload.py ./БК_отчёт_май.docx

# явно указать проект:
python3 gdrive_upload.py ./отчёт.docx --project "Бургер Кинг / Burger King"

# в конкретную подпапку:
python3 gdrive_upload.py ./отчёт.docx --subfolder "Финальные файлы"

# проверить без заливки:
python3 gdrive_upload.py ./отчёт.docx --dry-run

По умолчанию .xlsx/.docx/.pptx/.csv/.tsv автоконвертируются в Google Sheets/Docs/Slides. Чтобы залить в исходном формате — флаг --no-convert.

Если в целевой папке уже есть файл с тем же именем — он будет обновлён (сохраняется история версий в Drive).

Реестр проектов

В project_map.json — все клиентские папки из «4. Производство» (РГ1 и РГ2, 76 проектов) плюс внешние папки (Рокада мед. Абонент). Реестр автогенерирован обходом Drive на глубину 5, ручные алиасы сохранены.

Обновление реестра

Когда в PP завели нового клиента (появилась новая папка в РГ1/РГ2):

# показать что добавится/удалится:
python3 rebuild_project_map.py --dry-run

# перегенерировать:
python3 rebuild_project_map.py

Скрипт сохраняет ручные алиасы существующих проектов (например короткие «БК», «ТДК», «BK») — переписывает только subfolders и автоалиасы. Внешние проекты вне «4. Производство» (Рокада) сохраняются как есть.

Что делать, если файл не определяется

Если gdrive_organize.py или gdrive_upload.py не смогли определить проект:

1. Скрипты автоматически делают discover — ищут папку на Drive по словам из имени файла, помечают ★ те, что лежат под «4. Производство».
2. Если нужный клиент в списке — запустите rebuild_project_map.py чтобы добавить его в реестр, либо передайте --project '<имя>' явно.
3. Если не нашлось вообще ничего — добавьте проект руками в project_map.json.

Формат записи

Формат записи:

{
  "name": "Бургер Кинг / Burger King",
  "aliases": ["БК", "BK", "Burger King", "Бургер Кинг"],
  "drive_folder_id": "1mSJ07xivFL-...",
  "default_subfolder": "Внедрение",
  "subfolders": {
    "Финальные файлы": "178xILmqjYb0n6rrevdXloe9WnuBWjgpU",
    "Внедрение": "12L9MeLzaVXos7MRrVh0xdgHuThngF2kf",
    ...
  }
}

Добавили нового клиента — присылайте PR с правкой project_map.json.

Использование через Codex / Claude Code

В корне есть AGENTS.md — инструкция, которую агенты подхватывают автоматически. Достаточно сказать:

«Разложи свалку в папке 1LbbERfpfZ4O2Xa4OPPmP2rK4z6Rk5hxk по проектам»

или

«Залей мне этот файл в Бургер Кинг»

и агент сам выберет нужный скрипт и параметры.

Что НЕ умеет (осознанно)

• Не создаёт новые проектные папки на Drive. Если проекта нет в project_map.json — нужно завести вручную и обновить json.
• Не определяет проект по содержимому файла. Только по имени файла и алиасам. Если файл называется report_final.docx без префикса — придётся указать --project явно.
• Не следит за локальной файловой системой. Это разовые ручные операции, не watcher.

Лицензия

MIT — см. LICENSE.