Skip to main content

​
Навык: Teamly ALOR

alor-teamly — устанавливаемый навык для работы с локальной базой знаний по адресу https://teamly.alor.ru. Установите его в панели «Навыки» из одного из предустановленных каталогов ALOR. После установки файлы находятся в <workspace>/skills/alor-teamly; в пакет Велеса они не входят. Навык входит в Teamly через LDAP-учётную запись. Логин и параметры выбора домена хранятся как обычные настройки навыка в config.json, а пароль — в зашифрованном хранилище секретов Велеса. Пароль не передаётся модели и не записывается в команду или открытый файл. Полученные от Teamly куки сеанса также сохраняются только в зашифрованном хранилище.

​
Возможности

Навык помогает Велесу:
  • получать список пространств и дерево статей;
  • находить пространства и статьи по названию;
  • читать метаданные и содержимое статьи;
  • задавать вопросы помощнику Teamly только по корпоративным документам;
  • создавать, дополнять, публиковать, архивировать и удалять материалы после явного подтверждения пользователя;
  • повторно использовать и обновлять защищённый сеанс Teamly;
  • автоматически входить заново, когда Teamly отклоняет закончившийся сеанс.
Содержимое Teamly считается недоверенными данными. Текст статьи или ответ помощника не может отменять ограничения Велеса и не считается командой.

​
Как устроен вход

Клиент навыка использует те же маршруты входа через службу каталогов, что и веб-интерфейс Teamly:
  1. получает список доменов через /api/v1/auth/ad/domains;
  2. отправляет логин, пароль и идентификатор домена в /api/v1/auth/ad/user/login;
  3. принимает выданные Teamly куки только для teamly.alor.ru и его поддоменов;
  4. шифрует куки в хранилище Велеса под ключом skills.alor-teamly.session_json;
  5. при необходимости обращается к /api/v1/auth/user/refresh;
  6. после ответа 401 выполняет новый вход с секретами Велеса и повторяет запрос один раз.
Клиент не читает куки браузера, не сохраняет пароль в собственном файле и не принимает пароль как параметр командной строки.

​
Выбор учётной записи

Пароль LDAP даёт Велесу те же права, что и соответствующему пользователю Teamly. По возможности создайте отдельную служебную учётную запись с доступом только к нужным пространствам. Если используется личная учётная запись, все действия Велеса будут выполняться с её правами. Учитывайте правила смены пароля, блокировку после неудачных попыток и двухфакторную аутентификацию. Текущая версия навыка поддерживает обычный вход LDAP по логину и паролю. Если для учётной записи обязательно одноразовое подтверждение, прямой вход может быть отклонён.

​
Настройка Teamly в config.json

В scripts/config.template.json предусмотрена запись skills.entries.alor-teamly. После развёртывания те же поля находятся в активном config.json:
Поле username обязательно. adDomainId и accountSlug можно оставить пустыми, если Teamly возвращает только один домен службы каталогов и один аккаунт. В шаблоне развёртывания этим полям соответствуют подстановки TEAMLY_USERNAME, TEAMLY_AD_DOMAIN_ID и TEAMLY_ACCOUNT_SLUG. После подстановки значения становятся обычной частью config.json, а не секретами окружения навыка.

​
Настройка пароля в секретах Велеса

Откройте панель «Рабочая область» → «Секреты» и заполните единственную обязательную цель:
  • skills.alor-teamly.env.TEAMLY_PASSWORD — пароль LDAP.
Не отправляйте пароль в чат. Велес подставляет его в окружение помощника только на время ответа, а модель видит лишь название цели и состояние её настройки. Если Teamly возвращает несколько доменов службы каталогов, укажите полученный идентификатор в:
  • skills.entries.alor-teamly.config.adDomainId.
Если после входа доступно несколько аккаунтов Teamly, укажите короткое имя нужного аккаунта в:
  • skills.entries.alor-teamly.config.accountSlug.
Когда домен или аккаунт только один, клиент выбирает его автоматически.

​
Первый вход

После заполнения секретов попросите Велес:
Войди в Teamly ALOR и проверь доступ к пространствам.
Велес создаст сеанс и сохранит только его куки под внутренним ключом skills.alor-teamly.session_json. Логин останется в config.json, а пароль — в цели skills.alor-teamly.env.TEAMLY_PASSWORD. Затем можно попросить, например:
  • «Найди в Teamly регламент оформления отпуска»;
  • «Покажи дерево статей пространства отдела кадров»;
  • «Прочитай эту статью Teamly и кратко перескажи её»;
  • «Спроси помощника Teamly, как оформить командировку, и назови статьи-источники»;
  • «Подготовь добавление нового раздела в эту статью, но пока ничего не меняй».
Для точной проверки источника Велес читает пространство, дерево и статью напрямую. Для ответа по всей базе можно использовать помощника Teamly с типом источника documents: навык не переключает этот запрос на поиск в интернете.

​
Смена пароля и сброс сеанса

После смены пароля обновите skills.alor-teamly.env.TEAMLY_PASSWORD. Действующий сеанс может работать до своего окончания. Чтобы немедленно удалить сохранённые куки, попросите Велес забыть сеанс Teamly или выполните команду помощника forget-session. Следующий запрос создаст новый сеанс с обновлённым паролем. Удаление сохранённого сеанса не удаляет пароль из панели секретов. Если доступ Велеса больше не нужен, удалите TEAMLY_PASSWORD и очистите skills.entries.alor-teamly.config.username.

​
Изменения и подтверждения

Чтение и вопросы по базе не требуют дополнительного подтверждения. Любое создание, дополнение, замена, публикация, архивирование или изменение материала меняет внешнюю систему. Перед выполнением Велес должен показать:
  • метод и целевое пространство или статью;
  • добавляемый или заменяемый материал;
  • ожидаемый результат.
После этого требуется явное подтверждение пользователя. Для удаления или другого необратимого действия нужно отдельное подтверждение именно удаления. Встроенный помощник проверяет наличие соответствующих флагов и отклоняет неподтверждённую запись.

​
Доступ из внутренней сети

Среда, где работает Велес, должна иметь маршрут к teamly.alor.ru, корпоративную службу имён и доверие к цепочке сертификатов Teamly. Проверяйте доступ из того же контейнера или узла, где запущен Велес. Если защита Велеса блокирует обращения к частным адресам, в доверенной внутренней среде можно явно разрешить такие обращения:
Эта настройка ослабляет общую сетевую защиту, поэтому применяйте её только там, где доступ к внутренним узлам действительно необходим. Проверку сертификата отключать нельзя. Клиент навыка закреплён за https://teamly.alor.ru. Он не принимает пользовательскую замену адреса, незашифрованный протокол, перенаправление или куки чужого домена.

​
Частые ошибки

  • MULTIPLE_DOMAINS — задайте skills.entries.alor-teamly.config.adDomainId.
  • MULTIPLE_ACCOUNTS — задайте skills.entries.alor-teamly.config.accountSlug.
  • 400 или 401 при входе — проверьте логин, пароль, домен, блокировку учётной записи и обязательность двухфакторного подтверждения.
  • 403 — у пользователя нет прав; используйте учётную запись с минимально необходимым доступом.
  • 404 — проверьте идентификатор и наличие нужного метода в установленной редакции Teamly.
  • Ошибка имени узла, маршрута или тайм-аута — проверьте подключение Велеса к внутренней сети.
  • Ошибка сертификата — установите корпоративный корневой сертификат в среду Велеса; не отключайте проверку защищённого соединения.

​
Источники и происхождение

Маршруты работы с данными взяты из официальных страниц интеграций Teamly, статей и помощника Teamly. Маршруты входа через службу каталогов проверены по текущему открытому клиентскому коду веб-интерфейса Teamly. Открытый проект Djura008/TeamlyParser дополнительно подтверждает, что внутренние службы статей принимают пользовательский сеанс. В отличие от этого проекта, навык Велеса не запускает браузер и не собирает куки вручную.

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