Разработчику

Для ИИ-агентов

llms.txt, Markdown-версия каждой страницы и промпт, который ставит чат через Claude Code или Cursor.

Открыть в…
На странице

Эта документация написана и для людей, и для ИИ-агентов, которые пишут код. Всё ниже доступно по обычному HTTP, без аккаунта и ключа.

С чего начать

АдресЧто это
https://tolkly.io/llms.txtКороткая карта документации (llmstxt.org): описание, инструкции для агентов, ссылки на Markdown каждой страницы
https://tolkly.io/llms-full.txtВсе английские страницы одним файлом
https://tolkly.io/docs/ru/llms.txtТо же на русском; страницы без перевода даны на английском

Исходник документации — английский, он всегда полный. Русские страницы — его перевод.

Markdown каждой страницы

У каждой страницы есть Markdown-версия, собранная из того же исходника, что и HTML. Ссылки в ней абсолютные и ведут на Markdown-версии других страниц. Агент переходит по ним, не разбирая HTML.

  • Добавьте .md к адресу страницы: https://tolkly.io/docs/en/install.md.
  • Или запросите Markdown по адресу самой страницы: сервер учитывает заголовок Accept.
Terminal
curl -H 'Accept: text/markdown' https://tolkly.io/docs/en/install

Страница, отданная как HTML, отвечает с Vary: Accept и указывает свою Markdown-версию и llms.txt:

HTTP
Link: </docs/en/install.md>; rel="alternate"; type="text/markdown", </llms.txt>; rel="describedby"; type="text/plain"

Такой же <link rel="alternate" type="text/markdown"> есть в <head> HTML. На каждой странице «Копировать как Markdown» кладёт Markdown-версию в буфер обмена, а «Открыть в…» открывает её в Claude или ChatGPT с вопросом о ней.

Промпт для установки

В приложении, в разделе проекта «Установка», под кодом установки владельцы видят «Поручить ИИ-агенту». Это промпт ниже, в котором уже подставлены проект и endpoint. Здесь вместо id проекта стоит your-project. На страницах установки его копирует «Открыть в…» → «Промпт для ИИ-агента».

Установи на этот сайт чат поддержки Tolkly.

Проект: your-project
Endpoint виджета: https://api.tolkly.io

1. Прочитай https://tolkly.io/llms.txt, затем https://tolkly.io/docs/en/install.md и раздел про стек этого сайта в https://tolkly.io/docs/en/frameworks.md. Если они не открываются, хватит этого промпта.
2. Определи, как устроен сайт: статический HTML, серверный фреймворк (Next.js, Nuxt, Laravel, Django…), одностраничное приложение (React на Vite, Vue, Angular) или CMS (WordPress, Tilda, Битрикс).
3. Добавь эти две строки ровно один раз, в общий шаблон всех страниц, прямо перед </body>:

   <script type="module" src="https://api.tolkly.io/widget.js"></script>
   <tolkly-chat project="your-project"></tolkly-chat>

   Других атрибутов не добавляй: название, приветствие, цвета и кто отвечает приходят с сервера. Скрипт загружай с https://api.tolkly.io, не копируй его в проект и не включай в сборку.
4. В одностраничном приложении чат должен переживать смену страниц: тег вне router outlet (index.html или корневой layout), скрипт загружается один раз, а не на каждой странице. В TypeScript JSX объяви tolkly-chat как intrinsic element, без приведения к any.
5. Если сайт отдаёт Content-Security-Policy, разреши https://api.tolkly.io, https://ru.tolkly.io в script-src, connect-src и img-src и добавь blob: в img-src (превью файлов). В style-src ничего не нужно: виджет использует constructed stylesheets (Chrome 73+, Firefox 101+, Safari 16.4+). Если политика использует nonce, поставь тот же атрибут nonce на тег <tolkly-chat>, чтобы и старый Safari получил стили. Если в script-src есть 'strict-dynamic', источники-адреса не действуют: поставь nonce и на тег <script> виджета. Если политика этого не позволяет, остановись и скажи мне.
6. Не добавляй список разрешённых доменов: чат работает на любых моих доменах по умолчанию.
7. Если посетители входят на сайте, спроси меня, прежде чем добавлять подпись посетителя (https://tolkly.io/docs/en/identity.md). Секрет хранится на сервере в переменной окружения и никогда не попадает в код страницы.
8. Проверь в браузере: запусти сайт, открой две разные страницы и убедись, что кнопка чата есть на обеих, а во вкладке сети запрос к https://api.tolkly.io/v1/projects/your-project/widget отвечает 200 без поля "refused". Запрос из curl ничего не доказывает: без Origin страницы он разрешён всегда. Потом перечисли изменённые файлы. Через несколько минут после выкладки в разделе проекта «Установка» в Tolkly появится, что чат работает на этом сайте.

Чего в промпте нет, и это намеренно:

  • Секрета. Секрет подписи остаётся у владельца. Он сам кладёт его на сервер сайта через переменную окружения (Подпись посетителя).
  • Поддельных запросов. Проверка — настоящая страница в браузере. Запрос с выдуманным Origin записал бы чужой сайт в домены проекта.
  • Настроек чата. Название, цвета и приветствие меняет владелец, а не код сайта.

В чём агенты ошибаются

  • Тег ставится один раз, в общий шаблон всех страниц. Не в компонент страницы и не дважды.
  • У тега только endpoint и project. Тема, приветствие и кто отвечает приходят с сервера (атрибуты).
  • Скрипт загружается с endpoint как модуль. Его не копируют в репозиторий и не включают в сборку.
  • При Content-Security-Policy в style-src ничего добавлять не нужно, 'unsafe-inline' тоже. Если в политике есть nonce для стилей, тот же nonce ставится на тег (CSP).
  • Список разрешённых доменов не нужен, если владелец его не просил: по умолчанию чат работает на любом домене (домены).