{/ Эта страница автоматически передается из навыков SKILL.md с помощью сайта/scripts/generate-skill-docs.py. Редактируйте исходный SKILL.md, а не эту страницу. /}

Рабочая область Google

Gmail, Календарь, Диск, Контакты, Таблицы и Документы — через управляемый Hermes OAuth и тонкую CLI-обертку. Если установлен gws, его используют как бэкенд для более широкого охвата Google Workspace; в противном случае он использует встроенную реализацию Python-клиента.

Справочники

• references/gmail-search-syntax.md — Операторы поиска Gmail (is:unread, from:, newer_than: и т.д.)

Скрипты

• scripts/setup.py — Настройка OAuth2 (запустить один раз для авторизации)
• scripts/google_api.py — CLI-обертка для совместимости. Он предпочитает gws для операций, когда он доступен, сохраняя при этом существующий контрактный вывод JSON Hermes.

Первоначальная настройка

Настройка полностью неинтерактивна — вы управляете ею шаг за шагом, чтобы она работала. на CLI, Telegram, Discord или любой платформе.

Сначала определите длину:

GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"

Шаг 0: проверьте, настроение ли уже

$GSETUP --check

Если выводит AUTHENTICATED, переходите к Использованию — настройка уже выполнена.

Шаг 1: Триаж — спросите пользователя, что ему нужно

Перед началом настройки OAuth задайте пользователю ДВА вопросы:

Вопрос 1: «Какие сервисы Google вам нужны? Только почта или также Календарь/Диск/Таблицы/Документы?»

• Только почта → Этот навык не нужен. Используйте навыки «Гималаи» вместо него — он работает с паролем приложения Gmail (Настройки → Безопасность → Пароли приложений) и навредить за 2 минуты. Проект Google Cloud не нужен. Загрузите его навыки и следуйте его сильным настройкам.

• Почта + Календарь → Продолжайте с этим навыком, но викорируйте --службы электронной почты, календаря во время аутентификации, чтобы экран был запрошен только те разрешения, которые им действительно нужны.

• Только Календарь/Диск/Таблицы/Документы → Продолжайте с этим навыком и вскормите более узкий набор --services, например календарь,диск,листы,документы.

• Полный доступ к Workspace → Продолжайте с этим навыком и воспользуйтесь набором сервисов по умолчанию. все.

Вопрос 2: «Использует ли ваша учетная запись Google Advanced Protection (требуются аппаратные ключи безопасности для входа)?» Если вы не уверены, вероятно, нет — это то, в чем вы бы явно зарегистрировались».

• Нет/Не уверен → Обычная настройка. Продолжайте ниже.
• Да → Администратор своей рабочей области должен добавить идентификатор OAuth-клиента в список разрешенных приложений организации, прежде чем сработает Шаг 4. Сообщите им об этом заранее.

Шаг 2: создание учетных данных OAuth (однократно, ~5 минут)

Сообщите пользователю:

Вам нужен OAuth-клиент Google Cloud. Это одноразовая настройка:

1. Создать или выбрать проект: https://console.cloud.google.com/projectselector2/home/dashboard
2. Включите необходимые API из библиотеки API: https://console.cloud.google.com/apis/library Включите: API Gmail, API Календаря Google, API Google Диска, API Google Таблиц, API Документов Google, API людей
3. Создайте OAuth-клиент здесь: https://console.cloud.google.com/apis/credentials Учетные данные → Создать учетные данные → Идентификатор клиента OAuth 2.0
4. Тип приложения: «Настольное приложение» → Создать
5. Если приложение все еще находится в режиме тестирования, укажите учетную запись пользователя Google как тестового пользователя здесь: https://console.cloud.google.com/auth/audience Аудитория → Тестовые пользователи → Добавить пользователей
6. Загрузите JSON-файл и сообщите мне путь к файлу.

Важное примечание для CLI Hermes: если путь к файлу начинается с /, НЕ отправляйте только голый путь как отдельное сообщение в CLI, так как он может быть принят за слеш-команду. Отправьте его в предложении, например: Путь к JSON-файлу: /home/user/Downloads/client_secret_....json

Как только они обеспечивают путь:

$GSETUP --client-secret /path/to/client_secret.json

Если они в своих именах имеют сырые значения идентификатора клиента/секрета клиента вместо пути к файлу, напишите для них сами валидный JSON-файл Desktop OAuth, сохраните его где-нибудь явно (например, ~/Downloads/hermes-google-client-secret.json), затем запустите --client-secret для этого файла.

Шаг 3: Получите авторизацию URL-адреса

Используйте набор сервисов, выбранный на шаге 1. Примеры:

$GSETUP --auth-url --services email,calendar --format json
$GSETUP --auth-url --services calendar,drive,sheets,docs --format json
$GSETUP --auth-url --services all --format json

Это возвращает JSON с полем auth_url, а также сохраняет URL-адрес шифрования в ~/.hermes/google_oauth_last_url.txt.

Правила агента для этого шага: - Извлеките поле auth_url и отправьте этот URL-адрес шифрования одной строкой. - Сообщите пользователю, что браузер, скорее всего, выдаст ошибку на http://localhost:1 после одобрения, и что это ожидаемо. - Скажите им скопировать ВЕСЬ перенаправленный URL из адресной строки браузера. - Если пользователь получает ошибку 403: access_denied, отправьте его напрямую на https://console.cloud.google.com/auth/audience, чтобы добавить себя в качестве тестового пользователя.

Шаг 4: Измените код

Пользователь вставляет обратно либо URL вида http://localhost:1/?code=4/0A...&scope=..., либо просто введите код. Любой вариант подойдет. Шаг --auth-url сохраняет временную ожидающую OAuth-сессию локально, так что --auth-code может преобразовать обмен PKCE позже, даже на безголовых размышлениях:

$GSETUP --auth-code "URL_ИЛИ_КОД_ВСТАВЛЕННЫЙ_ПОЛЬЗОВАТЕЛЕМ" --format json

Если --auth-code не требуется, потому что код истек, уже был использован или пришел из более важных вкладок браузера теперь он возвращает fresh_auth_url. В этом случае немедленно отправьте новый URL-адрес и запросите его внешний вид с самым новым перенаправлением браузера.

Шаг 5: Проверка

$GSETUP --check

Публикация вывода AUTHENTICATED. Настройка завершена — токен будет автоматически обновляться в будущем.

Примечания

• Токен хранится в ~/.hermes/google_token.json и автоматически обновляется.
• Состояние ожидаемой OAuth-сессии/верификатора временно сохраняется в ~/.hermes/google_oauth_pending.json до завершения обмена.
• Если установлен gws, google_api.py указывает ему на тот же файл учетных данных ~/.hermes/google_token.json. Пользователям не нужно запускать отдельный поток gws auth login.
• Для отзыва: $GSETUP --revoke

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

Все команды передаются через API-скрипт. Установите GAPI как расчет:

GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/google_api.py"

Gmail

# Поиск (возвращает JSON-массив с id, from, subject, date, snippet)
$GAPI gmail search "is:unread" --max 10
$GAPI gmail search "from:boss@company.com newer_than:1d"
$GAPI gmail search "has:attachment filename:pdf newer_than:7d"

# Чтение полного сообщения (возвращает JSON с текстом тела)
$GAPI gmail get MESSAGE_ID

# Отправка
$GAPI gmail send --to user@example.com --subject "Привет" --body "Текст сообщения"
$GAPI gmail send --to user@example.com --subject "Отчет" --body "<h1>Q4</h1><p>Детали...</p>" --html
$GAPI gmail send --to user@example.com --subject "Привет" --from '"Исследовательский агент" <user@example.com>' --body "Текст сообщения"

# Ответ (автоматически создает цепочку и устанавливает In-Reply-To)
$GAPI gmail reply MESSAGE_ID --body "Спасибо, мне подходит."
$GAPI gmail reply MESSAGE_ID --from '"Бот поддержки" <user@example.com>' --body "Спасибо"

# Метки
$GAPI gmail labels
$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD

Календарь

# Список событий (по умолчанию следующие 7 дней)
$GAPI calendar list
$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z

# Создать событие (ISO 8601 с часовым поясом обязательно)
$GAPI calendar create --summary "Командный стендап" --start 2026-03-01T10:00:00-06:00 --end 2026-03-01T10:30:00-06:00
$GAPI calendar create --summary "Обед" --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z --location "Кафе"
$GAPI calendar create --summary "Обзор" --start 2026-03-01T14:00:00Z --end 2026-03-01T15:00:00Z --attendees "alice@co.com,bob@co.com"

# Удалить событие
$GAPI calendar delete EVENT_ID

Диск

# Поиск существующих файлов
$GAPI drive search "квартальный отчет" --max 10
$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5

# Получить метаданные одного файла
$GAPI drive get FILE_ID

# Загрузить локальный файл (автоопределение MIME-типа)
$GAPI drive upload /path/to/report.pdf
$GAPI drive upload /path/to/image.png --name "Logo.png" --parent FOLDER_ID

# Скачать (бинарные файлы скачиваются как есть; собственные файлы Google экспортируются в
# разумный формат по умолчанию — Docs→pdf, Sheets→csv, Slides→pdf, Drawings→png)
$GAPI drive download FILE_ID
$GAPI drive download DOC_ID --output ~/doc.pdf
$GAPI drive download DOC_ID --export-mime text/plain --output ~/doc.txt

# Создать папку
$GAPI drive create-folder "Отчеты"
$GAPI drive create-folder "Q4" --parent FOLDER_ID

# Поделиться
$GAPI drive share FILE_ID --email alice@example.com --role reader
$GAPI drive share FILE_ID --email alice@example.com --role writer --notify
$GAPI drive share FILE_ID --type anyone --role reader        # любой по ссылке
$GAPI drive share FILE_ID --type domain --domain example.com --role reader

# Удалить — по умолчанию в корзину (обратимо). Используйте --permanent, чтобы пропустить корзину.
$GAPI drive delete FILE_ID
$GAPI drive delete FILE_ID --permanent

Контакты

$GAPI contacts list --max 20

Таблицы

# Создать новую таблицу
$GAPI sheets create --title "Бюджет Q4"
$GAPI sheets create --title "Инвентаризация" --sheet-name "Склад"

# Чтение
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"

# Запись
$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Имя","Оценка"],["Алиса","95"]]'

# Добавить строки
$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["новая","строка","данные"]]'

Документы

# Чтение
$GAPI docs get DOC_ID

# Создать новый документ (опционально с начальным текстом)
$GAPI docs create --title "Заметки встречи"
$GAPI docs create --title "Черновик" --body "Первый абзац..."

# Добавить текст в конец существующего документа
$GAPI docs append DOC_ID --text "Дополнительный контент для добавления"

Формат

Все команды возвращают JSON. Разбирайте с помощью jq или читайте напрямую. Ключевые поля:

• Поиск в Gmail: [{id, threadId, от, до, тема, дата, фрагмент, метки}]
• Gmail get: {id, threadId, from, to, subject, date, labels, body}
• Отправка/ответ Gmail: {status: "sent", id, threadId}
• Список календаря: [{id, summary, начало, конец, местоположение, описание, htmlLink}]
• Создание календаря: {status: "created", id, summary, htmlLink}
• Поиск на диске: [{id, name, mimeType, ModifiedTime, webViewLink}]
• Получение диска: {id, name, mimeType,modifiedTime, size, webViewLink, родители, владельцы}
• Загрузка на диск: {status: "uploaded", id, name, mimeType, webViewLink}
• Загрузка с диска: {status: "downloaded", id, name, path, mimeType}
• Папка создания диска: {status: "created", id, name, webViewLink}
• Общий доступ к диску: {status: "shared", PermissionId, fileId, role, type}
• Удаление диска: {status: "trashed" | "удален", fileId, постоянный}
• Список контактов: [{имя, адрес электронной почты: [...], телефоны: [...]}]
• Листы получают: [[cell, cell,...],...]
• Создание таблиц: {статус: "создано", электронная таблицаId, заголовок, электронная таблицаUrl}
• Создание документов: {status: "created", documentId, title, url}
• Документы добавляются: {статус: "добавлено", documentId, Inserted_at, символы}

Правила

1. Никогда не отправляйте электронные письма, не создавайте/удаляйте события календаря, не удаляйте файлы на диске, не делитесь файлами и не изменяйте документы/таблицы без подтверждения пользователя. Укажите, что будет сделано (получатели, идентификаторы файлов, требования, роль доступа) и спросите одобрения. Для удаления диска предпочитайте корзину по умолчанию (обратимо) вместо --permanent.
2. Проверьте аутентификацию перед первым использованием — запустите setup.py --check. Если это не так, выполните действия пользователя через переход.
3. Используйте справочник по синтаксису поиска Gmail для сложного запроса — загрузите его с помощью skill_view("google-workspace", file_path="references/gmail-search-syntax.md").
4. Время в календаре должно включать часовой пояс — всегда используйте ISO 8601 со смещением (например, 2026-03-01T10:00:00-06:00) или UTC (Z).
5. Соблюдайте лимиты скорости — избегайте быстрых последовательных вызовов API. Группируйте чтение, когда это возможно.

Устранение неполадок

Отзыв доступа

$GSETUP --revoke