Skip to content

AGENTS.md

Latest commit

 

History

History
137 lines (101 loc) · 8.02 KB

AGENTS.md

File metadata and controls

137 lines (101 loc) · 8.02 KB

AGENTS.md — инструкция для Codex / Claude Code

Этот файл читается AI-агентами автоматически. Содержит правила работы со скриптами в этом репозитории.

Важно: НЕ используйте встроенный Drive connector

Если у вас доступен встроенный «Google Drive» connector (как в ChatGPT/Codex Desktop) — не используйте его для операций «создать файл / положить в папку клиента / переместить». Он архитектурно не принимает parent_id, вы не сможете попасть в проектную папку, файл уедет в «Мой диск».

Для любых операций с Drive — только bash через скрипты этого репо:

  • gdrive_create.py — создать пустой Google Doc/Sheet/Slides/папку в проектной папке
  • gdrive_upload.py — залить локальный файл в проектную папку
  • gdrive_organize.py — разложить свалку файлов по проектам
  • rebuild_project_map.py — обновить реестр клиентов после изменений на Drive

Если задача — «прочитать что в файле» / «пересказать содержимое» — встроенный connector ОК, у нас на это нет своего инструмента.

Что делает этот репозиторий

Два скрипта для наведения порядка на Google Drive Paper Planes:

  • gdrive_organize.py <source_folder_id> [--execute] — разложить сваленные в одной Drive-папке файлы по проектным подпапкам автоматически.
  • gdrive_upload.py <local_file> [--project ...] [--subfolder ...] — залить локальный файл в правильную проектную папку.

Реестр проектов — в project_map.json. Логика OAuth/API — в gdrive_lib.py.

Когда что использовать

Запрос пользователя Скрипт
«Разложи файлы в этой папке по проектам» gdrive_organize.py
«Перенеси файлы из общей в папку клиента X» gdrive_organize.py
«Залей этот файл на Drive» gdrive_upload.py
«Положи документ в Бургер Кинг» gdrive_upload.py с --project
«Создай пустой Google Doc в Бургер Кинг» gdrive_create.py --type doc --project ...
«Сделай таблицу/презентацию в папке клиента X» gdrive_create.py --type sheet/slides
«Создай подпапку в проекте X» gdrive_create.py --type folder

Жёсткие правила

  1. Всегда сначала dry-run. Перед --execute запускайте скрипт без флага, покажите план пользователю, и только после явного подтверждения — реальное перемещение/загрузку. Это операции на shared Drive, видны коллегам.

  2. Никогда не угадывайте ID Drive-папок. Берите только из project_map.json или из ссылки, которую дал пользователь. Если проекта нет в реестре — попросите ссылку у пользователя, не создавайте новые папки на Drive самостоятельно.

  3. Если файл не определяется по имени (нет префикса БК_, Рокада_ и т.п.) — спросите у пользователя, к какому проекту он относится. Не угадывайте.

  4. tokens.json не комитить. В .gitignore уже добавлен — не убирайте.

  5. При добавлении нового проекта в project_map.json — обязательно указывайте drive_folder_url (полный URL папки), не только ID. Это помогает коллегам быстро проверить, что папка та.

Примеры

Сценарий 1: разложить свалку

Пользователь: «В папке 1LbbERfpfZ4O2Xa4OPPmP2rK4z6Rk5hxk много файлов БК и
              РокадаМед, разложи по проектам»

Агент:
  1. Запускает: python3 gdrive_organize.py 1LbbERfpfZ4O2Xa4OPPmP2rK4z6Rk5hxk
  2. Показывает план пользователю
  3. После подтверждения: тот же запуск + --execute
  4. Сообщает итог

Сценарий 2: залить файл

Пользователь: «Залей ./Бургер_Кинг_отчёт.docx на Drive»

Агент:
  1. Запускает: python3 gdrive_upload.py ./Бургер_Кинг_отчёт.docx --dry-run
  2. Показывает: проект = Бургер Кинг, подпапка = Внедрение (default)
  3. Спрашивает: «Подтвердить? Или хочешь в другую подпапку?»
  4. После подтверждения: тот же запуск без --dry-run
  5. Возвращает ссылку

Сценарий 3: проект не в реестре, но есть на Drive

Пользователь: «Залей это в проект Деафон»

Агент:
  1. python3 gdrive_upload.py файл.docx --dry-run
  2. Скрипт говорит: «не нашёл, вот кандидаты с Drive: ★ Деафон (id=...)»
  3. Агент пользователю: «Кандидат — Деафон, под 4. Производство. Добавить
     в реестр и залить?»
  4. python3 rebuild_project_map.py  (обновляет project_map.json)
  5. python3 gdrive_upload.py файл.docx  (теперь detect сработает)

Сценарий 4: совсем новый клиент, папки на Drive нет

Пользователь: «Залей это в новый проект ЗОЛОТО»

Агент:
  1. Запускает discover через gdrive_upload.py --dry-run — пусто
  2. Говорит пользователю: «На Drive нет папки клиента ЗОЛОТО. Создать в РГ1
     или РГ2? Какая типовая структура — стандартные 5 подпапок?»
  3. После явного подтверждения — создаёт папку и подпапки через Drive API
  4. Добавляет в project_map.json (PR), потом заливает файл

Когда обновлять реестр

Запускайте python3 rebuild_project_map.py если:

  • скрипт говорит «★ кандидат под 4. Производство» — клиент есть на Drive, но отсутствует в project_map.json;
  • пользователь упомянул нового клиента, которого вы не видите в реестре;
  • прошло больше месяца с последнего обновления.

Команда сохраняет ручные алиасы, так что её можно прогонять смело.

Технические детали

  • Python 3.9+, без зависимостей (только stdlib).
  • OAuth-токены в ~/.config/mcp-gdrive/tokens.json — см. setup_oauth.md.
  • API: Google Drive v3 + Multipart Upload.
  • Office-форматы (xlsx/docx/pptx) конвертируются в Google формат при загрузке. Чтобы оставить как есть — --no-convert.