Источники знаний
Confluence, Figma, Notion и Google Диск как контекст для ответов: инструменты чтения, обращения на странице и макете, область, параметры вместо картинок.
Трекер даёт боту задачу, репозиторий — код, а источник знаний — то, чего нет ни там, ни там: письменный и визуальный контекст команды. Требования, архитектурные решения, регламенты, ранбуки — и макеты: как экран должен выглядеть, из каких токенов собран, как ведёт себя автолейаут. Человек это в вопросе не пересказывает — он предполагает, что вы и так знаете.
В каталоге пять таких источников (у Notion, Google Диска и файлов на диске — свои страницы: Notion, Google Диск, Файлы на диске, — потому что события, область и вход у них устроены иначе):
| Источник | Что даёт модели | Где принимает вопросы |
|---|---|---|
| Confluence | страницы пространств из области подключения — текстом | комментарии к странице |
| Figma | структуру, параметры и токены макетов из области подключения; картинку — только модели, которая видит | комментарии к макету |
| Notion | страницы как markdown и записи баз данных — текстом; результат исследования — дочерней страницей | комментарии к странице |
| Google Диск | документы как markdown, таблицы — листами, презентации — текстом; результат исследования — новым документом в папке | комментарии к документу, таблице, презентации |
| Файлы на диске | папки на сервере и сетевые папки SMB: Word, Excel, PowerPoint (2007+ и 97–2003), PDF и текстовые файлы — инструментами glob, grep, read | нигде: у папки нет комментариев, вопросы задаются в Buff |
Ещё один источник — то, чего у команды нет: интернет. У него своя страница, потому что адреса там называет модель, а границы ставит администратор.
Как это работает
Модель сама решает, когда заглянуть в источник, и делает это инструментами. Ничего не копируется к нам заранее и не индексируется: читается только то, что понадобилось для конкретного ответа. Это решение, а не ограничение — база знаний и макеты остаются в вашем периметре, а счёт приходит за то, что действительно прочитано.
Обращаться со страницы или с макета не обязательно. Как только в поле «Проект разработки» подключения стоит имя вашего проекта (или пространства), модель видит его инструменты в каждом вопросе «Спросить» и в каждом глубоком исследовании этого проекта — в том числе заданных из приложения, рядом с кодом. Этапы разработки задач инструменты подключения не получают.
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 и Figma означает «всё, что открыто учётной записи бота» — как у Notion и Google Диска: границу уже провели права в самой системе. «Нигде» пустой список означает только у трекеров. Права учётной записи бота во внешней системе — внешняя граница, список — внутренняя; разумно иметь обе.
У Figma без списка есть оговорки: её API не умеет перечислить все файлы учётной записи.
Если спрашиваете в приложении, приложите ссылку на макет: сам найти файл по названию бот не
сможет. О вопросе в комментарии бот узнаёт только из вебхука FILE_COMMENT и только в тех
файлах, на которые вебхук заведён (см. «События»). Для этого приёмник событий
коннектора должен быть доступен из интернета. Без вебхука вопросы в комментариях к макетам
до бота не доходят.
Настройка
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 секунд, интервал меняется в настройках подключения. Портов открывать не нужно — кроме Figma без списка файлов и проектов, о ней ниже. У Confluence без списка опрос читает все пространства, открытые учётной записи.
Вебхук Confluence не разбирается по содержимому, а просто будит опрос: полезную нагрузку мы не проверяли на живом сервере. Пользы это не отнимает: ответ приходит сразу, а не в следующий проход.
Вебхук Figma доставляется интеграции: из события FILE_COMMENT берутся файл и номер
комментария, а сам комментарий и его ветка читаются через API — в событии нет ветки, в
которой написан ответ. Со списком файлов или проектов вебхук ускоряет ответ, а опрос
подбирает потерянные вызовы. Без списка вебхук обязателен: только он говорит, в каком
файле бота упомянули, и приёмник событий коннектора тогда должен быть доступен из
интернета — Figma стучится в него из своего облака. Бот отвечает на упоминания только в
файлах, на которые заведён вебхук. Опрос тогда перечитывает файлы, где бота упоминали с
последнего запуска коннектора. Вебхук
Figma заводится через её API (POST /v2/webhooks, событие FILE_COMMENT) на команду,
проект или файл и указывает на ссылку, выданную коннектором; вебхук на команду покрывает
все её файлы.
Чего интеграции не делают
- Не создают и не редактируют страницы и макеты. Публикация результата — это запись в вашу систему, и её нужно ограничивать отдельно; результат возвращается комментарием и ссылкой.
- Не трогают метки, права, библиотеки и вложения — кроме документа исследования, который прикладывается к странице Confluence, если попросили именно исследование. К комментарию Figma файл приложить нельзя — он доступен по ссылке, и в ответе это сказано.
- Не выходят за область подключения — отмеченные пространства, файлы и проекты, а без списка — то, что открыто учётной записи бота.
- Не показывают картинку текстовой модели — см. выше.