# Источники знаний

> Confluence и Figma как контекст для ответов: инструменты чтения, обращения на странице и на макете, область видимости, параметры вместо картинок.

Трекер даёт боту **задачу**, репозиторий — **код**, а источник знаний — то, чего нет ни
там, ни там: **письменный и визуальный контекст команды**. Требования, архитектурные
решения, регламенты, ранбуки — и макеты: как экран должен выглядеть, из каких токенов
собран, как ведёт себя автолейаут. Человек это в вопросе не пересказывает — он
предполагает, что вы и так знаете.

В каталоге два таких источника:

| Источник | Что даёт модели | Где принимает вопросы |
|---|---|---|
| [Confluence](/marketplace/confluence) | страницы отмеченных пространств — текстом | комментарии к странице |
| [Figma](/marketplace/figma) | структуру, параметры и токены отмеченных макетов; картинку — только модели, которая видит | комментарии к макету |

Третий источник — то, чего у команды нет: [интернет](/docs/connector/web). У него своя
страница, потому что адреса там называет модель, а границы ставит администратор.

## Как это работает

Модель **сама решает**, когда заглянуть в источник, и делает это инструментами. Ничего не
копируется к нам заранее и не индексируется: читается только то, что понадобилось для
конкретного ответа. Это решение, а не ограничение — база знаний и макеты остаются в вашем
периметре, а счёт приходит за то, что действительно прочитано.

### 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, отступы и интервалы — числами, шрифты — семейством, начертанием,
размером и межстрочным интервалом. Ничего не обрезается: у фрейма с сорока слоями в ответе
сорок слоёв.

<Callout type="warn">
**Не каждая модель видит картинки.** Большинство моделей, на которых работает Buff, читают
только текст. Поэтому интеграция построена от параметров: всё, что перечислено выше, кроме
`render_node`, работает с любой моделью. Единственный инструмент с картинкой помечен в
каталоге отметкой «картинка», и платформа предлагает его лишь модели, которая читает
изображения — по описанию модели у провайдера, без ручной настройки. Текстовой модели он не
показывается вовсе, так что модель, которая не умеет смотреть, никогда не получит
изображение, которое «прочитала бы» наугад.
</Callout>

_Иллюстрация: Вопрос про стиль кнопки: модель нашла узел, прочитала его параметры и назвала стиль по имени — без единой картинки._

## Обращения на странице и на макете

Всё, что описано в [«Интеграциях с трекерами»](/docs/connector/trackers), работает и
здесь: упоминание бота или команда через слэш в комментарии — это вопрос, исследование или
черновик задачи, а ответ приходит комментарием в то же обсуждение. Разница одна: у страницы
и у макета нет ветки кода, поэтому ответ считается на уровне проекта разработки, к которому
привязано подключение.

В Figma **ветка — это корневой комментарий**, приколотый к месту на макете. Вопрос в ответе на
него продолжает тот же разговор, и ответ бота приходит в ту же ветку.

## Область видимости

У подключения есть список того, где бот работает, — и он действует в обе стороны: вне списка
бот не читает обращения и не пишет ответы.

| Источник | Что в списке | Где это взять |
|---|---|---|
| Confluence | ключи пространств (`DOC`, `OPS`) | в адресе страницы: `/spaces/DOC/pages/…` |
| Figma | ключи файлов и/или номера проектов | ключ — в адресе файла `figma.com/design/КЛЮЧ/…`; номер проекта — в адресе проекта `figma.com/files/project/НОМЕР/…` |

<Callout type="warn">
Пустой список означает **«нигде»**, а не «везде». Права учётной записи бота во внешней
системе — внешняя граница, список — внутренняя; разумно иметь обе.
</Callout>

## Настройка

### 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** — только по отмеченным пространствам,
  файлам и проектам.
- **Не показывают картинку текстовой модели** — см. выше.