Google Workspace

Gmail, Календарь, Диск, Документы, Таблицы через gws CLI или Python.

Метаданные навыка


Источник	Встроенный (установлен по умолчанию)
Путь	`skills/productivity/google-workspace`
Версия	`1.1.0`
Автор	Nous Research
Лицензия	MIT
Платформы	linux, macos, windows
Теги	`Google`, `Gmail`, `Calendar`, `Drive`, `Sheets`, `Docs`, `Contacts`, `Email`, `OAuth`
Связанные навыки	`himalaya`

Справочник: полный SKILL.md

к сведению

Ниже приведено полное описание навыка, которое VibeOS загружает при его активации. Агент видит эти инструкции, когда навык активен.

Google Workspace

Gmail, Календарь, Диск, Контакты, Таблицы и Документы — через управляемый VibeOS 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 от VibeOS.

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

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

Сначала определите сокращение:

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

Шаг 0: Проверка, выполнена ли настройка

$GSETUP --check

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

Шаг 1: Определение потребностей пользователя

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

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

Только почта → Этот навык не нужен. Используйте навык himalaya — он работает с паролем приложения Gmail (Настройки → Безопасность → Пароли приложений) и настраивается за 2 минуты. Проект Google Cloud не требуется. Загрузите навык himalaya и следуйте его инструкциям по настройке.
Почта + Календарь → Продолжайте с этим навыком, но используйте --services email,calendar при авторизации, чтобы экран согласия запрашивал только необходимые разрешения.
Только Календарь/Диск/Таблицы/Документы → Продолжайте с этим навыком и используйте более узкий набор --services, например calendar,drive,sheets,docs.
Полный доступ к Workspace → Продолжайте с этим навыком и используйте набор сервисов по умолчанию all.

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

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

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

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

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

Создайте или выберите проект: https://console.cloud.google.com/projectselector2/home/dashboard

Включите необходимые API в библиотеке API: https://console.cloud.google.com/apis/library Включите: Gmail API, Google Calendar API, Google Drive API, Google Sheets API, Google Docs API, People API

Создайте OAuth-клиент здесь: https://console.cloud.google.com/apis/credentials Учётные данные → Создать учётные данные → Идентификатор клиента OAuth 2.0

Тип приложения: «Desktop app» → Создать

Если приложение всё ещё в режиме тестирования, добавьте учётную запись Google пользователя как тестового пользователя здесь: https://console.cloud.google.com/auth/audience Аудитория → Тестовые пользователи → Добавить пользователей

Скачайте JSON-файл и сообщите мне путь к нему

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

Когда пользователь предоставит путь:

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

Если пользователь вставил не путь к файлу, а сами значения client ID / client secret, самостоятельно создайте для них корректный JSON-файл Desktop OAuth, сохраните его в явно указанное место (например, ~/Downloads/vibeos-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 в ~/.vibeos/google_oauth_last_url.txt.

Правила для агента на этом шаге:

Извлеките поле auth_url и отправьте пользователю этот точный URL одной строкой.
Сообщите пользователю, что браузер, скорее всего, покажет ошибку на http://localhost:1 после подтверждения, и это нормально.
Попросите пользователя скопировать ВЕСЬ URL перенаправления из адресной строки браузера.
Если пользователь получает Error 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 пользователю и попросите его повторить попытку, используя только что полученный URL перенаправления из браузера.

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

$GSETUP --check

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

Примечания

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

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

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

GAPI="python ${VIBEOS_HOME:-$HOME/.vibeos}/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 экспортируются в
# разумный формат по умолчанию: Документы→pdf, Таблицы→csv, Презентации→pdf, Рисунки→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 search: [{id, threadId, from, to, subject, date, snippet, labels}]
Gmail get: {id, threadId, from, to, subject, date, labels, body}
Gmail send/reply: {status: "sent", id, threadId}
Calendar list: [{id, summary, start, end, location, description, htmlLink}]
Calendar create: {status: "created", id, summary, htmlLink}
Drive search: [{id, name, mimeType, modifiedTime, webViewLink}]
Drive get: {id, name, mimeType, modifiedTime, size, webViewLink, parents, owners}
Drive upload: {status: "uploaded", id, name, mimeType, webViewLink}
Drive download: {status: "downloaded", id, name, path, mimeType}
Drive create-folder: {status: "created", id, name, webViewLink}
Drive share: {status: "shared", permissionId, fileId, role, type}
Drive delete: {status: "trashed" | "deleted", fileId, permanent}
Contacts list: [{name, emails: [...], phones: [...]}]
Sheets get: [[cell, cell, ...], ...]
Sheets create: {status: "created", spreadsheetId, title, spreadsheetUrl}
Docs create: {status: "created", documentId, title, url}
Docs append: {status: "appended", documentId, inserted_at, characters}

Правила

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

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

Проблема	Решение
`NOT_AUTHENTICATED`	Выполните шаги настройки 2–5 выше
`REFRESH_FAILED`	Токен отозван или истёк — повторите шаги 3–5
`HttpError 403: Insufficient Permission`	Отсутствует область API — `$GSETUP --revoke`, затем повторите шаги 3–5
`AUTHENTICATED (partial)` или «Token missing scopes»	Новые возможности записи (запись/удаление на Диске, создание/редактирование Документов) требуют повторной авторизации. `$GSETUP --revoke`, затем повторите шаги 3–5 для предоставления расширенных областей.
`HttpError 403: Access Not Configured`	API не включён — пользователю необходимо включить его в Google Cloud Console
`ModuleNotFoundError`	Выполните `$GSETUP --install-deps`
Advanced Protection блокирует авторизацию	Администратор Workspace должен добавить идентификатор клиента OAuth в белый список

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

$GSETUP --revoke

Метаданные навыка​

Справочник: полный SKILL.md​

Google Workspace

Ссылки​

Скрипты​

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

Шаг 0: Проверка, выполнена ли настройка​

Шаг 1: Определение потребностей пользователя​

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

Шаг 3: Получение URL авторизации​

Шаг 4: Обмен кода​

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

Примечания​

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

Gmail​

Календарь​

Диск​

Контакты​

Таблицы​

Документы​

Формат вывода​

Правила​

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

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

Метаданные навыка

Справочник: полный SKILL.md

Ссылки

Скрипты

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

Шаг 0: Проверка, выполнена ли настройка

Шаг 1: Определение потребностей пользователя

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

Шаг 3: Получение URL авторизации

Шаг 4: Обмен кода

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

Примечания

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

Gmail

Календарь

Диск

Контакты

Таблицы

Документы

Формат вывода

Правила

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

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