Skip to main content

​
Навык: Google Workspace

google-workspace — встроенный навык Велеса для работы с сервисами Google: Gmail, календарём, диском, контактами, таблицами и документами. Навык перенесён из Hermes Agent и адаптирован под хранилище секретов Велеса. Файл клиента Google, токен доступа и временное состояние авторизации сохраняются не открытыми файлами, а в зашифрованном локальном хранилище.

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

Навык подходит, когда Велесу нужно:
  • найти или прочитать письма в Gmail;
  • отправить ответ после подтверждения пользователя;
  • посмотреть или создать событие в календаре Google;
  • найти, загрузить, скачать, переместить в корзину или открыть доступ к файлам на диске Google;
  • прочитать или обновить таблицу Google;
  • создать, прочитать или дополнить документ Google;
  • найти контакт в адресной книге Google.
Для задач только с почтой можно использовать этот навык, если уже настроен доступ Google Workspace. Если нужен только Gmail и пользователь не хочет создавать проект Google Cloud, проще выбрать отдельный почтовый способ с паролем приложения, если он доступен в окружении.

​
Что входит в навык

В каталоге veles/skills/google-workspace/ находятся:
  • SKILL.md — инструкция для Велеса;
  • scripts/setup.py — пошаговая настройка доступа;
  • scripts/google_api.py — единый командный интерфейс к сервисам Google;
  • scripts/gws_bridge.py — мост для внешней программы gws;
  • scripts/google_secrets.py — работа с зашифрованными секретами Велеса;
  • references/gmail-search-syntax.md — справка по поисковым операторам Gmail.
Скрипт google_api.py сначала пытается использовать gws, если она установлена. Если gws нет, он работает через библиотеки Google для Python.

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

Пользователю нужен проект Google Cloud, включённые интерфейсы Gmail, Calendar, Drive, Sheets, Docs и People, а также файл клиента OAuth 2.0 типа “Desktop app”. Удобная команда для настройки: 
GSETUP="python ${VELES_HOME:-$HOME/.veles}/skills/google-workspace/scripts/setup.py"
Проверка текущего состояния: 
$GSETUP --check
Обычный порядок настройки: 
$GSETUP --client-secret /path/to/client_secret.json
$GSETUP --auth-url --services email,calendar,drive,docs --format json
$GSETUP --auth-code "PASTE_THE_REDIRECT_URL_OR_CODE" --format json
$GSETUP --check
После успешной настройки данные хранятся в зашифрованном файле секретов Велеса:
  • skills.google-workspace.google_client_secret_json — файл клиента Google;
  • skills.google-workspace.google_token_json — токен Google;
  • skills.google-workspace.google_oauth_pending_json — временное состояние авторизации до обмена кода на токен.
Для записи и чтения этих значений нужен VELES_SECRETS_MASTER_KEY. Если ключ не задан, скрипт настройки остановится с ошибкой и объяснит, что нужно настроить главный ключ секретов.

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

Удобная команда для работы: 
GAPI="python ${VELES_HOME:-$HOME/.veles}/skills/google-workspace/scripts/google_api.py"
Примеры чтения: 
$GAPI gmail search "is:unread" --max 10
$GAPI gmail get MESSAGE_ID
$GAPI calendar list
$GAPI drive search "quarterly report" --max 10
$GAPI contacts list --max 20
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
$GAPI docs get DOC_ID
Примеры действий, которые меняют данные: 
$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
$GAPI calendar create --summary "Meeting" --start 2026-03-01T10:00:00Z --end 2026-03-01T10:30:00Z
$GAPI drive share FILE_ID --email user@example.com --role reader
$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
$GAPI docs append DOC_ID --text "Additional content"

​
Правила безопасности

Велес должен получить явное подтверждение пользователя перед действиями, которые меняют внешние данные:
  • отправка писем и ответов;
  • создание или удаление событий календаря;
  • удаление файлов с диска Google;
  • выдача доступа к файлам;
  • изменение таблиц и документов.
Для удаления файлов предпочтительно использовать перенос в корзину. Необратимое удаление допустимо только после отдельного явного подтверждения.

​
Частые проблемы

NOT_AUTHENTICATED означает, что настройка ещё не завершена или в секретах нет токена Google. Запустите setup.py --check, затем повторите шаги авторизации. REFRESH_FAILED обычно означает, что токен отозван или устарел. Нужно заново получить ссылку авторизации и обменять новый код. HttpError 403: Insufficient Permission означает, что текущему токену не хватает разрешений. Обычно помогает setup.py --revoke и повторная авторизация с нужным набором сервисов. HttpError 403: Access Not Configured означает, что нужный интерфейс Google не включён в проекте Google Cloud. ModuleNotFoundError означает, что не установлены библиотеки Google для Python. Для локальной установки можно использовать: 
$GSETUP --install-deps

​
Связанные страницы