Источники знаний
Confluence и Figma как контекст для ответов: инструменты чтения, обращения на странице и на макете, область видимости, параметры вместо картинок.
Трекер даёт боту задачу, репозиторий — код, а источник знаний — то, чего нет ни там, ни там: письменный и визуальный контекст команды. Требования, архитектурные решения, регламенты, ранбуки — и макеты: как экран должен выглядеть, из каких токенов собран, как ведёт себя автолейаут. Человек это в вопросе не пересказывает — он предполагает, что вы и так знаете.
В каталоге два таких источника:
| Источник | Что даёт модели | Где принимает вопросы |
|---|---|---|
| Confluence | страницы отмеченных пространств — текстом | комментарии к странице |
| Figma | структуру, параметры и токены отмеченных макетов; картинку — только модели, которая видит | комментарии к макету |
Третий источник — то, чего у команды нет: интернет. У него своя страница, потому что адреса там называет модель, а границы ставит администратор.
Как это работает
Модель сама решает, когда заглянуть в источник, и делает это инструментами. Ничего не копируется к нам заранее и не индексируется: читается только то, что понадобилось для конкретного ответа. Это решение, а не ограничение — база знаний и макеты остаются в вашем периметре, а счёт приходит за то, что действительно прочитано.
Confluence
| Инструмент | Что делает |
|---|---|
search_pages | ищет по отмеченным пространствам — заголовки, выдержки, адреса |
get_page | читает страницу целиком, вместе с обсуждением |
get_page_children | перечисляет дочерние страницы раздела |
Страница приходит текстом, а не разметкой. Confluence хранит её как разметку с макросами, таблицами и вставками; интеграция переводит это в читаемый текст, сохраняя заголовки, списки, таблицы, код и адреса ссылок. Ничего при этом не обрезается: обрезанный регламент — это тихо потерянное требование.
Figma
| Инструмент | Что делает |
|---|---|
list_files | перечисляет подключённые макеты — ключ, название, проект |
get_file | структура файла: страницы, фреймы, размеры, стили и компоненты — до заданной глубины |
get_node | узел с поддеревом и параметрами: положение и размер, автолейаут, заливки и обводки в hex, скругления, эффекты, типографика и текст, стили и переменные по именам, компонент экземпляра и его свойства |
get_styles | дизайн-токены: опубликованные стили со значениями, стили файла, переменные по режимам — где план Figma даёт их читать |
search_nodes | поиск узлов по словам в имени слоя или в тексте |
get_comments | обсуждения макета: ветки, к какому узлу приколоты, решены ли |
render_node | отрисовать узел в PNG — только для модели, которая читает изображения |
Макет приходит параметрами, как панель инспектора. Узел в Figma ссылается на стили и переменные идентификаторами — интеграция превращает их в имена («Кнопка/Малахит», «Цвет/Акцент»), потому что имя есть в документации дизайн-системы, а идентификатор не читает никто. Цвета — в hex, отступы и интервалы — числами, шрифты — семейством, начертанием, размером и межстрочным интервалом. Ничего не обрезается: у фрейма с сорока слоями в ответе сорок слоёв.
Не каждая модель видит картинки. Большинство моделей, на которых работает Buff, читают
только текст. Поэтому интеграция построена от параметров: всё, что перечислено выше, кроме
render_node, работает с любой моделью. Единственный инструмент с картинкой помечен в
каталоге отметкой «картинка», и платформа предлагает его лишь модели, которая читает
изображения — по описанию модели у провайдера, без ручной настройки. Текстовой модели он не
показывается вовсе, так что модель, которая не умеет смотреть, никогда не получит
изображение, которое «прочитала бы» наугад.
Обращения на странице и на макете
Всё, что описано в «Интеграциях с трекерами», работает и здесь: упоминание бота или команда через слэш в комментарии — это вопрос, исследование или черновик задачи, а ответ приходит комментарием в то же обсуждение. Разница одна: у страницы и у макета нет ветки кода, поэтому ответ считается на уровне проекта разработки, к которому привязано подключение.
В Figma ветка — это корневой комментарий, приколотый к месту на макете. Вопрос в ответе на него продолжает тот же разговор, и ответ бота приходит в ту же ветку.
Область видимости
У подключения есть список того, где бот работает, — и он действует в обе стороны: вне списка бот не читает обращения и не пишет ответы.
| Источник | Что в списке | Где это взять |
|---|---|---|
| Confluence | ключи пространств (DOC, OPS) | в адресе страницы: /spaces/DOC/pages/… |
| Figma | ключи файлов и/или номера проектов | ключ — в адресе файла figma.com/design/КЛЮЧ/…; номер проекта — в адресе проекта figma.com/files/project/НОМЕР/… |
Пустой список означает «нигде», а не «везде». Права учётной записи бота во внешней системе — внешняя граница, список — внутренняя; разумно иметь обе.
Настройка
Confluence
| Поле | Значение |
|---|---|
| Адрес | https://wiki.corp.local для Data Center и Server, https://ваша-компания.atlassian.net/wiki для Cloud — вместе с /wiki, иначе интеграция стучится не туда |
| Учётные данные | токен учётной записи бота; для Cloud — почта и API-токен (учётная запись вводится рядом с секретом) |
| Пространства | DOC, OPS — ключи, а не названия |
| Псевдоним | короткое имя бота, например buff. В Cloud у учётных записей нет логина, поэтому там оно особенно кстати |
Проверка связи отвечает не «ок», а версией Confluence, учётной записью, под которой вошли, и тем, сколько из отмеченных пространств реально доступно.
Figma
| Поле | Значение |
|---|---|
| Адрес API | подставлен: https://api.figma.com — менять не нужно |
| Адрес выдачи картинок | подставлен: хранилище, откуда Figma отдаёт отрисованные изображения, — менять не нужно |
| Учётные данные | personal access token учётной записи бота (Figma принимает его в своём заголовке) |
| Файлы, проекты | ключи файлов и/или номера проектов — достаточно одного из списков |
| Псевдоним | короткое имя бота, например buff |
Проверка связи говорит, кто вошёл, сколько файлов в области и сколько из них доступно, и читаются ли переменные на этом плане Figma: API отдаёт переменные (Variables) только планам Enterprise, остальным интеграция берёт токены из опубликованных стилей и привязок узлов — и говорит об этом прямо, а не пустым списком.
Из командной строки: connector install figma, затем
connector instance add figma --config projects=4815162342 — адрес API подставится сам.
События
Опрос работает всегда: раз в 20 секунд интеграция читает комментарии отмеченных пространств или файлов. Портов открывать не нужно.
Вебхук у обоих источников устроен иначе, чем у трекеров: он не разбирается по
содержимому, а просто будит опрос. У Confluence — потому что полезную нагрузку мы не
проверяли на живом сервере; у Figma — потому что событие FILE_COMMENT не несёт ветки, в
которой написан ответ, и без обращения к API не понять, куда отвечать. Пользы это не
отнимает: ответ приходит сразу, а не в следующий проход. Вебхук Figma заводится в
настройках команды или файла на выданную коннектором ссылку.
Чего интеграции не делают
- Не создают и не редактируют страницы и макеты. Публикация результата — это запись в вашу систему, и её нужно ограничивать отдельно; результат возвращается комментарием и ссылкой.
- Не трогают метки, права, библиотеки и вложения — кроме документа исследования, который прикладывается к странице Confluence, если попросили именно исследование. К комментарию Figma файл приложить нельзя — он доступен по ссылке, и в ответе это сказано.
- Не ищут по всему Confluence и по всей Figma — только по отмеченным пространствам, файлам и проектам.
- Не показывают картинку текстовой модели — см. выше.