# База знаний и переиндексация

> Что читает бот, как часто перечитывает сайты, как подхватывает зеркала и учится на ответах операторов.

Бот отвечает только по базе знаний. В ней страницы ваших сайтов, которые мы прочитали, и вопросы с ответами, которые вы одобрили или написали. Здесь — что мы читаем, когда перечитываем и как сделать, чтобы бот видел ваши правила.

## Что мы читаем
- **Сначала карта сайта.** Мы берём страницы из sitemap вашего сайта — того, что указан в `robots.txt`, или того, что лежит по обычному адресу. Sitemap в gzip тоже подойдёт.
- **Без карты сайта — по ссылкам.** Сайт без sitemap мы читаем с главной страницы, переходя по ссылкам.
- **Только страницы под адресом сайта.** Если адрес сайта `example.com/help/`, мы читаем только страницы под `/help/`.
- **`robots.txt` соблюдается.** Закрытые им страницы мы не читаем. Для своего сайта вы можете снять запрет с отдельных адресов: «Дополнительно» › «Читать вопреки robots.txt». Приложение попросит подтвердить, что сайт ваш, и сохранит ваше имя и дату.
- **Только HTML-страницы.** PDF и документы, на которые ссылается сайт, мы не читаем: загрузите их как файлы ([Файлы](#files)).
- **Без JavaScript.** Мы читаем HTML, который отдаёт сервер. Текст, который скрипт дорисовывает после загрузки страницы, мы не видим.
- **Меню и футер — один раз.** То, что повторяется на каждой странице, хранится один раз и не заслоняет правила.

Если страницы нет в sitemap, впишите её в «Дополнительные страницы». С каждого сайта мы читаем до 2000 страниц.

## Сайты
В разделе проекта «Знания» сверху — итог «ИИ знает: 2 сайта, 12 файлов…» и кнопка «Перечитать всё». Каждое число ведёт к своей части: «Сайты», «Файлы» или раздел «Вопросы и ответы». Ниже — [что ИИ знает о проекте](#card), сайты, файлы и строка о том, что скоро можно будет подключить. Читать ли новые домены чата, задаётся в «Установка» › «Домены» ([Правило доменов](#domain-rule)).

В «Сайтах» — ваши сайты и сайты, найденные на ваших доменах, по строке на сайт. В строке видно, сколько страниц прочитано и когда. Общее расписание названо один раз в пояснении части; у сайта с другим расписанием оно написано в его строке. Точка в начале серой строки появляется, только когда сайт требует внимания: тогда рядом коротко сказано, что не так, например «не видно ссылок». Для всех таких сайтов внизу части одна строка «Поручить ИИ-агенту» с промптом для разработчика.

Владелец или администратор нажимает «Добавить сайт». Для сайта нужен только адрес. Остальное — в «Дополнительно», по строке на настройку: что сейчас и «Изменить». Редактор открывается под строкой, по одному за раз; сохраняет вся форма разом.

- **Карта сайта:** найдём сами, возьмём ваш адрес или обойдёмся без неё и пойдём по ссылкам.
- **Какие страницы:** все, только перечисленные разделы или все, кроме них.
- **Дополнительные страницы:** адреса, которых нет в карте сайта.
- **Читать вопреки robots.txt:** разделы, которые robots.txt закрывает от чтения.
- **Название:** по умолчанию — адрес сайта.
- **Перечитывать:** как у всех сайтов (каждый день), каждую неделю или только по запросу.

Раздел записывается как начало адреса после домена: `/ru/faq/` — все страницы, чей адрес начинается так. Звёздочка заменяет любые символы, в том числе `/`: `/blog/*/2024/` или `*/archive/`. Точку и другие знаки экранировать не нужно, а целый адрес, вставленный в поле, сам потеряет домен. Тем, кто пишет регулярные выражения, остаётся «Своё выражение».

В проекте до 20 сайтов. Первый сайт — основной: из него берутся описание сайта и цвета виджета. Если текст страницы уже есть в другом источнике, он хранится один раз.

Кнопка «…» в строке изменяет или удаляет сайт. Страницы удалённого сайта сразу уходят из базы знаний. Хотя бы один свой сайт в проекте остаётся всегда. Операторы видят список без кнопок.

## Файлы
Правила, оферту, AML-политику или прайс, которых нет на сайте, загрузите файлами: перетащите их на часть «Файлы» или нажмите «Загрузить файлы». Файлы показаны сеткой карточек: значок с расширением, имя, размер и число фрагментов. Когда файлов больше 12, появляются поиск и сортировка, а сетка сворачивается после двух рядов. Флажок в углу карточки выбирает её, чтобы удалить несколько файлов сразу.

- **Форматы.** PDF, DOCX, Markdown, TXT и HTML, до 10 МБ каждый. Формат мы определяем по самому файлу. Старый `.doc` откройте в Word и сохраните как `.docx`.
- **Заголовки.** Бот делит файл на разделы по заголовкам. В PDF заголовок — строка, набранная крупнее текста; в Word — стиль заголовка или короткий абзац целиком жирным. Номера страниц и колонтитулы мы убираем.
- **Ссылка в ответе.** У файла нет адреса на вашем сайте, поэтому бот ссылается на страницу с его текстом — ровно тем, по которому он отвечает, с переходом к нужному разделу. Название файла в строке источника открывает эту страницу.
- **Сканы.** В скане нет текста, только картинки страниц. Такой файл не прочитается, и в строке будет написано почему. Сохраните документ с текстовым слоем.
- **Длинные файлы.** Мы читаем до миллиона символов файла. Если файл длиннее, в строке будет написано, что прочитано только начало.
- **Новая версия.** Перетащите новый файл на карточку старого или выберите «…» › «Заменить файл». Окно покажет оба файла, «сейчас» и «новый», и спросит подтверждение. Если загрузить файл с именем, которое уже есть, окно предложит «Заменить файл» или «Добавить как новый». Бот сразу перечитает новую версию, ссылки в прежних ответах откроют новый текст. Файл сам не перечитывается: он меняется, только когда вы загружаете новый. Одинаковый файл дважды не загрузится.

В проекте до 100 файлов; они не входят в 20 источников.

## Правило доменов
Зеркала меняются быстрее, чем кто-то успевает править настройки. В «Установка» › «Домены» строка «Читать новые домены» включает правило доменов: оно само читает ваши новые домены. Выше в том же блоке — домены, где загружался чат, и что ИИ делает с каждым; у домена, который ждёт вас, — кнопка «Разрешить».

- **Маска.** Правило смотрит только на домены, которые подходят под маску: «Дополнительно: маска и новый домен» › «Маска домена». Синтаксис тот же, что у [списка доменов](https://tolkly.io/docs/ru/domains.md#strict). По умолчанию это поддомены основного сайта, например `*.brand.com`. Для зеркал с номером напишите `brand*.com`: звёздочка заменяет любые буквы и цифры. Маска сохраняется, когда вы уходите из поля. Там же «Добавить домен» вносит ваш домен в список разрешённых заранее: ИИ прочитает его, когда на нём загрузится чат.
- **«Какие домены»: «Только разрешённые» или «Кроме заблокированных».** По умолчанию — только разрешённые: домен подходит, только когда вы его разрешили — в «Установка» › «Домены», в Telegram или скриптом зеркал. Без этого в ответы могла бы сама попасть копия вашего сайта с одной изменённой деталью, например адресом кошелька. Заблокированный домен не читается никогда.
- **Копия — это зеркало.** Мы сравниваем новый домен с основным сайтом: до 20 страниц, начиная с главной, текст с текстом, и `rel=canonical` главной. Копию мы заново не читаем: ответы посетителю на ней и так ведут на этот домен.
- **Свой текст — это сайт.** Домен со своим текстом становится сайтом проекта и читается каждый день. Группа компании в Telegram получает сообщение о каждом таком домене: «зеркало …» или «новый сайт … проиндексирован».
- **Когда срабатывает.** Когда вы разрешаете домен, и раз в сутки. В списке видны домены, на которых был чат, и что правило делает с каждым. Если убрать домен из списка или заблокировать, его сайт уйдёт вместе со страницами при следующей проверке.

## Запуски, которые ждут вас
Если за один запуск изменилось бы или пропало больше 45% страниц сайта, ничего не записывается. Бот отвечает по прежним страницам. Так выглядит защита от ботов, припаркованный домен или сломанный сайт.

Точка в строке становится оранжевой, а в строке написано, что изменилось: «Изменились 11, пропали 1 из 12 страниц». Группа компании в Telegram тоже получает сообщение со ссылкой на источники.

- Если сайт правда изменился, нажмите «Принять изменения»: сайт прочитается заново и запишется.
- «Отклонить» оставит старые страницы. Следующий запуск проверит снова.

Сайты меньше 10 страниц не удерживаются.

## Как сделать правила читаемыми
- Разместите правила, лимиты и условия на обычной HTML-странице, а не на картинке или во всплывающем окне, которое рисует скрипт. Правила только в PDF загрузите как [файл](#files).
- Добавьте эту страницу в sitemap.
- Не закрывайте её в `robots.txt`.
- Держите её под адресом сайта.
- Меняете правило — меняйте и страницу: бот цитирует то, что на ней написано.

### Поручить ИИ-агенту вашего сайта
Если последнее чтение сайта прошло плохо, владельцы и администраторы видят в «Сайтах» строку «Поручить ИИ-агенту». Она появляется, когда:

- `robots.txt` закрывает главную страницу;
- прочитано меньше 5 страниц;
- страницы пришли без текста: их рисуют скрипты или закрывает вход в аккаунт.

Промпт просит агента, который правит ваш сайт:

- перечислить страницы справки в sitemap;
- отдавать их с сервера;
- пустить нас в `robots.txt`;
- держать FAQ вне входа в аккаунт;
- проверить всё через `curl`.

Ниже промпт с примером сайта. Скопировать его можно через «Открыть в…» › «Промпт для ИИ-агента».

```text
Сделай этот сайт читаемым для чата поддержки Tolkly: он отвечает посетителям только по страницам самого сайта, а его краулер сейчас читает их плохо.

Сайт: https://your-site.example
Краулер: user agent "TolklyBot/0.1 (+https://github.com/tolkly/tolkly)"; в robots.txt он читает группы для TolklyBot и для *

1. Прочитай https://tolkly.io/docs/en/knowledge.md. Если страница не открывается, хватит этого промпта.
2. Найди страницы с ответами, которые нужны посетителям: справка, FAQ, правила и условия, цены и лимиты, контакты.
3. Отдавай sitemap.xml со всеми этими страницами — по адресу https://your-site.example/sitemap.xml или указанный строкой "Sitemap:" в robots.txt. Если sitemap есть, краулер читает только перечисленные в нём страницы и не ходит по ссылкам, поэтому страница, которой там нет, не прочитается никогда.
4. Отдавай эти страницы с сервера: их текст должен быть в HTML, который присылает сервер, без выполнения JavaScript. В одностраничном приложении используй серверный рендеринг фреймворка или пререндер этих маршрутов; пустая оболочка, которую заполняют скрипты, читается как страница без текста. Не оставляй на них <meta name="robots" content="noindex">.
5. В robots.txt пусти краулер: ни одна строка Disallow в группе для TolklyBot или для * не должна закрывать главную страницу и эти страницы. Строка Allow не открывает то, что закрыл Disallow для этого краулера, поэтому убери или сузь сам Disallow. И не отклоняй этот user agent файрволом, CDN или защитой от ботов.
6. Держи FAQ и правила вне входа в аккаунт: страница, которая просит краулер войти, читается как страница без текста.
7. Проверь: curl -A "TolklyBot/0.1 (+https://github.com/tolkly/tolkly)" <адрес страницы справки> выводит текст ответа в HTML, https://your-site.example/robots.txt не закрывает ни одну из этих страниц, а sitemap их перечисляет. Потом перечисли изменённые файлы и скажи мне нажать «Перечитать» у сайта в разделе «Знания» в Tolkly.
```

## Ежедневная переиндексация
Каждый сайт перечитывается по своему расписанию в 04:00 по Москве: каждый день (по умолчанию) или каждую неделю. Сайт с «Только по запросу» сам не перечитывается. В форме сайта это время показано в часовом поясе проекта, например «Перечитывается каждый день в 04:00 (Москва)».

- Изменённые страницы читаются заново, остальные остаются как есть.
- Страницы, пропавшие из sitemap, уходят из базы знаний. Сайт, который читается по ссылкам, не теряет страниц из-за одного неудачного запроса.

## Переиндексация вручную
Если правку нужно учесть уже сегодня, владелец или администратор нажимает «Перечитать» (стрелка в строке сайта) или «Перечитать всё» над списком. Что может быть написано в строке:

| Надпись | Что значит |
|---|---|
| «Ещё не прочитан» | Добавлен, ещё не прочитан (оранжевая точка) |
| «Ждёт очереди…» | Сначала читается другой сайт или проект |
| «Читаем сайт…» | Запуск идёт |
| «Прочитан … · Каждый день · следующий …» | Готово |
| «Не прочитан …: сайт не ответил» | Запуск не удался (красная точка). Бывает ещё «сайт нас не пустил (защита от ботов или вход)», «сайт ответил ошибкой», «сервер перезапустился во время запуска» |
| «Изменились …, пропали … из … страниц» | Запуск ждёт вашего решения (оранжевая точка) |
| «robots.txt закрывает от нас главную» | Ваш `robots.txt` закрывает от бота саму главную страницу (красная точка) |

## Если запуск не удался
Неудачный запуск не повторяется до следующего раза по расписанию. Когда сайт снова отвечает, нажмите «Перечитать». А пока бот отвечает по страницам, прочитанным раньше. Если ошибка повторяется, напишите нам.

## Что ИИ знает о проекте
С каждым вопросом ИИ получает описание вашего проекта, на каком бы домене ни был чат. По умолчанию это заголовок и описание главной страницы основного сайта. Оно показано в блоке «Что ИИ знает о проекте» вверху «Знаний». Владелец или администратор нажимает «Изменить», пишет описание своими словами (до 1500 символов) и нажимает «Сохранить». Основной сайт перечитается, чтобы учесть новое описание. «Взять с главной» вернёт прежнее.

## Вопросы и ответы
Когда закрывается разговор, в котором отвечал оператор, ИИ сохраняет его ответ как черновик: вопрос и ответ, только словами оператора. Черновики ждут в разделе проекта «Вопросы и ответы» на вкладке «Новые». Самые частые — сверху («Спросили 3 раза»).

Ответ можно написать и самому, не правя сайт и не загружая файл: «Написать ответ» в «Вопросах и ответах», «Ответить» у вопроса в «Отчёты» › «Чего не хватает в базе знаний» или «Написать ответ» у частого вопроса, на который бот откажет. «Сохранить и одобрить» сразу кладёт ответ в базу знаний, «Сохранить в новые» оставляет его на потом.

- Если похожий вопрос уже есть, сначала покажем его ответ: поправьте его или нажмите «Всё равно сохранить».
- Вопрос станет заголовком страницы ответа, поэтому в нём не может быть номера заказа или транзакции, почты или телефона.
- Для временного («вывод сегодня задерживается») задайте «Действует до» в «Дополнительно»: после этого дня бот перестанет по нему отвечать, а страница ответа закроется.

- **«Одобрить»**: дальше бот сам отвечает на этот вопрос. В чате он ссылается на «Ответ поддержки» («Support answer» в проекте на английском). У ответа своя страница.
- **«Изменить»**, затем «Сохранить и одобрить»: сначала поправьте текст.
- **«Отклонить»**: если вопрос зададут снова, черновик заново не появится. «Всё же одобрить» вернёт его.
- **«Снять»** у одобренного ответа: бот сразу перестаёт по нему отвечать, страница ответа закрывается, а сам ответ уходит в «Отклонены».

Писать, одобрять, править и отклонять могут только владельцы и администраторы. Операторы видят, что стало с их ответами.