Руководства по TRON

llms.txt, .well-known и Agent Skills: как TronSave представляет себя ИИ-агентам

Автор: TronSave Опубликовано 9 мин чтения
Содержание

Обновлено: 7 ноября 2026 г. Детали MCP и OAuth проверены на работающем сервере, версия 1.5.1.

ИИ-агент, попавший на сайт, сталкивается с той же проблемой, что и новый разработчик: что это такое, что здесь можно вызвать и как пройти аутентификацию? В 2026 году на эти вопросы отвечает небольшой набор общепринятых файлов: llms.txt, несколько дескрипторов в /.well-known/ и манифест agent skills. TronSave публикует их все. Ниже — разбор того, что лежит в каждом файле, зачем он нужен и какое единственное правило ни один из этих файлов не может обеспечить.

llms.txt: сводка для чтения

llms.txt лежит в корне сайта и делает для языковых моделей то же, что хороший README делает для разработчика: один абзац о том, что это такое, а затем отобранные ссылки с одним предложением контекста к каждой. Это Markdown, а не схема, и в этом весь смысл: файл предназначен для чтения, а не для парсинга.

У TronSave в нём четыре раздела. Однострочное описание продукта. Ключевые страницы — главная, маркет, инструменты, FAQ — у каждой описание того, что там на самом деле есть. Блок Разработчикам и ИИ-агентам со ссылками на справочник API, каталог API, карточку MCP-сервера, индекс agent skills и документ об аутентификации. И Правовая информация: условия, конфиденциальность, предупреждение о рисках.

Полезная дисциплина здесь — отбор. Sitemap перечисляет каждый URL; llms.txt перечисляет десяток действительно важных и объясняет, почему они важны. Если вашему файлу нужна полоса прокрутки, он перестал выполнять свою задачу.

Каталог .well-known

Если llms.txt — это текст для чтения, то /.well-known/ — для машин. Пять файлов, каждый отвечает на свой вопрос:

Файл Стандарт Отвечает на вопрос
api-catalog RFC 9727 Какие здесь есть API и где лежат их описания?
oauth-protected-resource RFC 9728 Что является защищённым ресурсом и как передаются учётные данные?
mcp/server-card.json MCP Где находится MCP-сервер, какой транспорт и какая аутентификация?
agent-skills/index.json agentskills.io Какие готовые навыки (skills) может загрузить агент?
security.txt RFC 9116 К кому обращаться по поводу уязвимости?

api-catalog — разделение на машину и человека

RFC 9727 определяет linkset: у каждого API есть якорь (anchor), а за ним — ссылки с его описанием. TronSave публикует два якоря — REST API v2 и MCP-эндпоинт, и у каждого есть и service-desc, и service-doc:

{
  "linkset": [
    {
      "anchor": "https://api.tronsave.io/v2",
      "service-desc": [ { "href": ".../api-reference.md",  "type": "text/markdown" } ],
      "service-doc":  [ { "href": ".../api-reference",     "type": "text/html"     } ]
    },
    {
      "anchor": "https://mcp.tronsave.io/mcp",
      "service-desc": [ { "href": ".../mcp/server-card.json", "type": "application/json" } ],
      "service-doc":  [ { "href": ".../api-reference/mcp",    "type": "text/html"        } ]
    }
  ]
}

Самое ценное — именно это разделение. service-doc — HTML-страница, которую читает человек. service-desc — машиночитаемое описание: здесь это Markdown для справочника REST и JSON для карточки MCP. Агент идёт по service-desc и полностью пропускает маркетинговую обёртку.

oauth-protected-resource — сначала API-ключи, OAuth для MCP

Метаданные RFC 9728 обычно сопровождают развёртывание OAuth. У самого REST API TronSave нет OAuth-потока — основные учётные данные там API-ключ или подпись кошелька, — но tronsave.io всё равно публикует дескриптор: в нём указаны ресурс, его сервер авторизации и scopes, ссылка на документацию и то, что bearer-учётные данные передаются в заголовке; рядом лежат соответствующие метаданные oauth-authorization-server. Клиент, который ищет эти файлы, получает ответ, а не 404. MCP-сервер идёт дальше: с 7 ноября 2026 г. mcp.tronsave.io поддерживает полноценный вход через OAuth для эндпоинта https://mcp.tronsave.io/oauth/mcp — с собственными метаданными защищённого ресурса и сервером авторизации (authorization code с PKCE, refresh-токены и эндпоинт регистрации клиентов). Именно так подключаются приложения вроде Claude и Cursor: пользователь входит на странице TronSave с API-ключом или подписью кошелька, и с этого момента приложение аутентифицировано.

auth.md — честный ответ для сервисов без OAuth

Поскольку у REST API нет OAuth-потока, который можно было бы обнаружить, реальная схема аутентификации описана в самодостаточном auth.md. Он конкретен ровно там, где это экономит время интегратору:

  • REST API принимает ключ в заголовке apikey в нижнем регистре.
  • MCP-сервер принимает его в заголовке authorization со схемой ApiKey.
  • Подпись кошелька TRON — третий путь, и в документе прямо сказано, что вы никогда не отправляете приватный ключ, только подпись.

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

Файл честно признаёт и то, чего нет. Не существует программного эндпоинта динамической регистрации OAuth для получения API-ключа (у отдельного OAuth-входа MCP-сервера есть свой эндпоинт регистрации для клиентских приложений), поэтому в нём объясняется, как ключ получает человек: подключить кошелёк на сайте или воспользоваться Telegram-ботом. Затем блок agent_auth повторяет те же факты в структурированном виде: тип идентичности anonymous, тип учётных данных api_key и ссылка на документацию по регистрации.

Карточка MCP-сервера

Компактный дескриптор MCP-сервера TronSave: имя и версия, транспорт (http-streamable) с эндпоинтом и методами, блок возможностей с объявлением tools, resources и prompts (у каждого — listChanged), две поддерживаемые схемы аутентификации с точным форматом заголовка и ссылки на quickstart и документацию.

Объявлять возможности, которых у вас нет, — не пустая формальность. Агент, который знает, что resources и prompts отсутствуют, перестаёт их искать.

Манифест agent skills

Самый новый слой. agent-skills/index.json следует схеме обнаружения agentskills.io и объявляет один навык, tronsave-api, типа skill-md — Markdown-документ, который агент может загрузить как рабочие инструкции:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "tronsave-api",
      "type": "skill-md",
      "url": "https://tronsave.io/.well-known/agent-skills/tronsave-api/SKILL.md",
      "digest": "sha256:bc8a8647...9141b"
    }
  ]
}

Обратите внимание на digest. Манифест содержит SHA-256 файла навыка, поэтому клиент может проверить, что скачал именно то, что сайт собирался опубликовать. Навыки — это инструкции, по которым агент будет действовать, поэтому их целостность стоит проверять, чего маркетинговой странице никогда не требуется.

Правило, которое не может обеспечить ни один манифест

Каждый из перечисленных файлов — это снимок. А сервис продолжает меняться.

Конкретный пример из этого же стека. Когда эта статья была впервые написана в августе 2026 г., манифест навыков описывал MCP-сервер с 27 типизированными инструментами, хотя живой tools/list возвращал 29, а карточка сервера указывала GET среди методов транспорта, хотя GET был отключён. К 28 октября 2026 г. сервер (версия 1.2.0) возвращал 53 инструмента, а в карточке сервера методы исправили на POST и DELETE, но quickstart по адресу mcp.tronsave.io/quickstart всё ещё говорил о 25 инструментах. 7 ноября 2026 г. живой сервер сообщал версию 1.5.1 — по-прежнему с 53 инструментами, — а карточка сервера всё ещё указывала 1.2.0.

Ничто из этого не является ошибкой на пути агента — это обычное расхождение между опубликованным документом и работающим сервисом. Вывод справедлив для любой подобной интеграции: используйте манифесты для обнаружения, а сервер — как источник истины. Получайте список возможностей во время выполнения через tools/list, а не зашивайте в код число, прочитанное в файле, и позвольте рукопожатию согласовать версию протокола, вместо того чтобы навязывать её.

Что агенту делать с учётными данными

Обнаружение заканчивается аутентификацией, и модель сессий заслуживает отдельного абзаца, потому что у неё реальные последствия. Рыночные данные и котировки не требуют входа вообще: на работающем сервере (версия 1.5.1, проверено 7 ноября 2026 г.) 18 из 53 инструментов публичны, и каждый инструмент объявляет свой уровень доступа в _meta["io.tronsave/auth"]. Для всего остального вход создаёт один из двух типов сессии с разными правами: ApiKey-сессия ограничена операциями внутреннего аккаунта, а сессия по подписи привязана к кошельку и нужна для инструментов, связанных с идентичностью пользователя, и для большинства изменений на платформе. API-ключ не даст вам незаметно доступ уровня подписи — на таких инструментах он просто вернёт ошибку.

Вход привязан к MCP-соединению, а id сессии передаётся в заголовке транспорта, никогда — в аргументах инструментов. Относитесь к нему как к секрету. Утёкший id сессии позволяет постороннему действовать с правами этой сессии до её истечения — именно поэтому более узкая ApiKey-сессия является правильным выбором по умолчанию для автономной работы.

Если вы делаете то же для своего сайта

Стек достаточно мал, чтобы выпустить его за полдня:

  1. /llms.txt — абзац-сводка и отобранные ссылки с контекстом. Делайте его коротким.
  2. /.well-known/api-catalog — по одному якорю на API, у каждого машинное описание и документация для людей.
  3. /.well-known/oauth-protected-resource — публикуйте его независимо от того, использует ли ваш основной API OAuth.
  4. Документ об аутентификации — точные названия заголовков и их регистр, а также как человеку получить учётные данные.
  5. Карточка MCP-сервера, если у вас есть сервер, с объявлением как имеющихся, так и отсутствующих возможностей.
  6. Манифест agent skills с digest, если вы публикуете навыки.
  7. /.well-known/security.txt — со сроком действия, который вы действительно будете продлевать.

Затем добавьте в процесс релиза одно правило: перегенерируйте манифесты при каждом изменении сервиса. Опубликовать эти файлы дёшево, а забыть о них легко.

FAQ

llms.txt — это стандарт?

Скорее широко принятое соглашение, чем стандарт IETF. А вот файлы в /.well-known/ рядом с ним — api-catalog, метаданные защищённого ресурса, security.txt — это настоящие RFC.

Помогает ли публикация этих файлов SEO?

Напрямую — нет. Они помогают агентам и ассистентам правильно пользоваться вашим сервисом, когда те уже пришли. Считайте их документацией по интеграции по общепринятому адресу, а не фактором ранжирования.

Нужен ли api-catalog, если у меня всего один API?

Да: ценность в предсказуемом расположении, а не в количестве записей. Одного якоря с машиночитаемым описанием достаточно.

Зачем публиковать метаданные защищённого ресурса без OAuth?

Потому что клиенты всё равно их ищут. Ответить идентификатором ресурса и способом передачи учётных данных полезнее, чем отдать 404, даже если для вашего основного API ответ звучит как «мы используем API-ключи, а не OAuth». TronSave делает и то и другое: метаданные для API-ключей на tronsave.io и полноценный вход через OAuth для своего MCP-эндпоинта.

Как получить API-ключ TronSave?

Подключите кошелёк TRON на сайте и войдите либо воспользуйтесь разделом с информацией о пользователе в Telegram-боте. Программного эндпоинта регистрации для API-ключей нет — документ об аутентификации прямо об этом говорит, а не оставляет вас выяснять самостоятельно. MCP-приложения, подключающиеся через вход по OAuth, пропускают этот шаг: страница входа запросит ваш ключ или подпись кошелька.

С чего начать, если я просто хочу пользоваться API?

Официальные SDK оборачивают его на пяти языках, а руководство по автоматизации через API описывает «сырые» эндпоинты. Файлы обнаружения нужны агентам, которым приходится искать дорогу самостоятельно.

Итог

Сделать сервис понятным для ИИ-агента — это не столько новая дисциплина, сколько старая с новой аудиторией: скажите, что вы такое, перечислите, что предоставляете, будьте точны в вопросе учётных данных и признайте, чего не поддерживаете. Файлы общепринятые, усилия небольшие. Настоящей дисциплины требует другое — поддерживать их в актуальном состоянии, ведь агент будет верить вашему манифесту ровно до того момента, когда сервер ему возразит.

TronSave публикует этот блог и описанные здесь файлы обнаружения. Содержимое файлов, количество инструментов и версии протокола отражают то, что было опубликовано и что возвращал работающий сервер на момент написания, и они изменятся — получайте эти данные во время выполнения, а не полагайтесь на приведённые выше цифры. Это не финансовая рекомендация.

TronSave
TronSave

Команда TronSave создаёт маркетплейс энергии и пропускной способности TRON на tronsave.io и пишет эти руководства по результатам проверок в основной сети TRON.

Похожие статьи

Мы используем Google Analytics, чтобы понимать, какие руководства полезны читателям. Файлы cookie устанавливаются, только если аналитика разрешена. Рекламы в блоге нет. Конфиденциальность