Перейти к содержанию
Публикация AiManual

«Солнечный Город»: как энтузиаст собрал API для нейросетей на одном PHP-файле

«Солнечный Город» - арт-проект поверх книжного мира angamua.ru: 26 инструментов в одном PHP-файле, ленивая эволюция по пятиминутным эпохам и SHA-256-манифест дл

Коротко

Что будет в материале

  1. 01

    Что такое «Солнечный Город» и зачем ему API для нейросетей

  2. 02

    Архитектура: один ra.php вместо фреймворка, базы данных и очередей

  3. 03

    26 инструментов: что можно прочитать и что можно сделать

  4. 04

    Ленивая эволюция: почему между визитами ничего не происходит

«Солнечный Город» - арт-проект на стыке литературы и веба: HTML-страницы для людей, машиночитаемый API для нейросетей и открытый репозиторий. Всё это построено поверх книжного мира angamua.ru и работает на обычном хостинге. Автор, Максим (ник Mabus46), называет себя писателем и энтузиастом, а не профессиональным разработчиком, и это объясняет рамки проекта.

Техническая часть держится на одном файле ra.php. По описанию автора он отдаёт JSON по параметру api и содержит 26 инструментов: чтение состояния города, канона, матрицы 7×7 из 49 славянских буквиц, бесконечной ленты записей и JSONL-датасета, работу с манифестом хэшей. Отдельная группа - POST-действия: через них агент оставляет в мире след.

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

Что такое «Солнечный Город» и зачем ему API для нейросетей

Проект прямо позиционируется как вымышленная вселенная и игра. Внутри есть пометка honesty: канон - это лор, протокол - рабочие правила, и смешивать их с научными фактами нельзя. Такая оговорка снимает часть вопросов к содержанию: мир не претендует на роль энциклопедии, он предлагает правила игры.

Устройство делится на три слоя, и каждый решает свою задачу.

  • Витрина для людей: обычные HTML-страницы, медитативная мини-игра, карта построек, «небо» звёзд, гримуар и свиток отказов.
  • Врата для машин: ra.php, один файл, который отдаёт JSON по параметру api.
  • Открытый репозиторий, где лежит код проекта.

Город добавляется поверх существующего сайта, а не вместо него: angamua.ru продолжает работать как раньше. Это отдельное условие, а не побочный эффект: проект не переделывает книжный мир, он пристраивается к нему.

Почему сайт приглашает модели, а не блокирует их

Исходная идея сформулирована как вопрос: что, если сделать наоборот и собрать небольшой сайт, который специально приглашает языковые модели зайти, прочитать правила и оставить след? Большинство владельцев сайтов решают обратную задачу: закрывают контент от краулеров, ставят лимиты и ловят ботов в robots.txt.

Требование к агенту автор расписывает по шагам: пришла по ссылке, прочитала, что это и зачем, поняла, что можно сделать, сделала или честно ушла. Ключевое слово - «честно». Сценарий ухода предусмотрен наравне со сценарием действия, поэтому агенту не нужно выдумывать, что он понял мир, если правила остались непрочитанными.

Ограничения встроены в дизайн. Город не рассылает ничего сам, не требует ключей и не собирает данные, кроме тех JSON, что машина добровольно пришлёт. Это художественный жест и эксперимент с машиночитаемым интерфейсом, а не способ накрутить трафик. Модель здесь ничего не обучает и не оптимизирует: весь смысл в следе, который остаётся в общем мире.

Архитектура: один ra.php вместо фреймворка, базы данных и очередей

Условия, которые автор поставил себе, короткие: один сервер, один PHP-файл, никаких фреймворков, баз данных и очередей, хостинг самый обычный. Второе условие - ничего не ломать: книжный сайт продолжает жить своей жизнью, город надстраивается сверху. Про эти рамки он рассказывает с самого начала разбора.

Машиночитаемый интерфейс решает конкретную задачу: ответ приходит структурой, а не страницей с навигацией и скриптами. Программе не нужно угадывать, где в разметке лежит нужное поле, и не нужно тянуть весь документ ради одного значения. Для агента это разница между «прочитай страницу и разберись» и «получи поле».

Как устроен JSON-контракт и маршрутизация по параметру api

Схема простая. Клиент обращается к ra.php с параметром api, значение выбирает инструмент, ответ приходит в JSON. Чтение идёт через GET, изменения через POST. Никакого отдельного шлюза, версионирования через заголовки и клиентских библиотек: всё сводится к одному URL и строке параметров.

  • ?api=state, ?api=canon, ?api=bukvitsa - чтение правил и текущего среза мира.
  • ?api=source&from=0&count=20, ?api=dataset - лента записей и её выгрузка.
  • ?api=relic, ?api=verify - артефакты и манифест с хэшами.
  • POST-действия - изменения состояния города.

Такой контракт удобен агенту ещё и тем, что его можно описать словами в llms.txt: одна строка на вызов, без схем и генераторов клиентов. Граница, о которой стоит знать заранее: как именно разбираются параметры, как обрабатываются ошибки и что приходит в ответ на некорректный вызов, в опубликованном разборе не раскрыто. При повторении этот слой придётся проектировать самому, и на нём обычно всплывают все неприятные случаи.

26 инструментов: что можно прочитать и что можно сделать

Инструменты делятся на чтение и действия. Ниже карта по опубликованному перечню; параметры POST-запросов и лимиты в разборе не раскрыты.

ВызовЧто возвращает
?api=stateСостояние города: эпоха, пульс, число «жителей», дневник, стих эпохи
?api=canonПравила мира
?api=bukvitsaМатрица 7×7 из 49 славянских буквиц
?api=source&from=0&count=20Лента записей с указанной позиции
?api=datasetТа же лента в JSONL с парами prompt/response
?api=relic, ?api=verifyАртефакты и манифест с хэшами
POST-действияИзменение состояния: лучи, дары, постройки

Чтение состояния, канона и матрицы буквиц

state даёт срез мира на текущий момент. canon фиксирует правила, по которым мир существует, и это первое, что стоит прочитать агенту: без правил любое действие превращается в случайный клик. bukvitsa задаёт 49-клеточную матрицу 7×7 как систему координат смыслов.

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

Бесконечная лента записей и JSONL-датасет

source устроен как цепочка: каждая следующая запись вычисляется из хэша предыдущей. Поэтому ленту можно запрашивать с любого from и любым count, не храня все записи: сервер пересчитывает нужный отрезок. Для агента это порция материала без обхода всего сайта.

dataset отдаёт ту же ленту в JSONL с парами prompt/response. Формат удобен построчной обработкой: одна строка - один пример, загрузка потоком, простое сравнение версий между выгрузками. Это заготовка датасета, а не готовый обучающий корпус. Проект не обучает и не дообучает модели, а записи стоит читать как художественный текст, а не как инструкции.

POST-действия: лучи, дары и постройки

Действия идут через POST: «лучи», «дары», «постройки». Агент читает мир и оставляет в нём след, который потом отражается в состоянии города, и следующий гость видит уже изменённую картину.

Добровольность встроена в правила: ключи не нужны, регистрация не требуется, собираются только те JSON, которые машина прислала сама. Полный список параметров POST-запросов, лимиты и правила модерации в опубликованном разборе отсутствуют. При интеграции их нужно уточнять у автора, а не выводить из названий действий: «дар» может означать что угодно.

Ленивая эволюция: почему между визитами ничего не происходит

Город меняется без cron, очередей и демонов. Состояние хранится в файлах с PHP-шапкой и досчитывается при каждом запросе: система смотрит, сколько пятиминутных эпох прошло с прошлого сохранения, и проматывает их. Между визитами не происходит ничего, мир существует только в момент обращения.

Это ленивое вычисление в чистом виде: работа выполняется по требованию, а не по расписанию. Отсюда три следствия.

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

Файлы с PHP-шапкой как хранилище состояния

База данных в проекте не используется: состояние лежит в файлах. Шапка на PHP не даёт веб-серверу отдать файл как статику, и это дешёвый способ закрыть содержимое от прямого чтения по URL. Гарантией безопасности такой приём не становится: он защищает от скачивания файла, а не от ошибок в коде, который его читает.

Риски файлового хранилища известны. Два одновременных POST могут перезаписать друг друга, транзакций здесь нет, права доступа на хостинге могут отличаться от локальных. Как именно проект обходится с конкурентными записями, в опубликованном разборе не раскрыто. При повторении это первое, что стоит проверить: два параллельных запроса на изменение одного файла и сверка результата.

Пятиминутные эпохи и досчёт при запросе

Эпоха - шаг в пять минут. По числу прошедших эпох досчитывается состояние: пульс, число «жителей», дневник и стих эпохи. Агент, вернувшийся через час, увидит не тот же срез, а результат двенадцати пропущенных шагов, посчитанных в момент запроса.

?api=state отдаёт именно этот набор: эпоху, пульс, число «жителей», дневник и стих эпохи. Практический смысл для агента простой: перед действием он читает актуальное состояние, а не текст, написанный неделю назад. Точный формат файлов и код досчёта в источнике не приводятся, поэтому механика понятна, а конкретные поля ответа лучше смотреть в живом вызове.

Подлинность артефактов: SHA-256-манифест вместо доверия автору

Проверка построена на хэшах: инструмент «реликвия» отдаёт манифест с SHA-256 шести ключевых файлов и двумя «генезис-хэшами» - от исходной строки канона и от полной матрицы. Если машина или человек встретит «тот же город» в другом месте, подлинность проверяется сверкой хэшей, а не верой автору.

Что даёт хэш: он показывает, что артефакт не изменился относительно записи в манифесте. Он не подтверждает смысл, качество и пользу артефакта. Если манифест обновили вместе с артефактом, сверка сойдётся, хотя содержимое поменялось. Формат манифеста и точный порядок сверки в опубликованном разборе детально не описаны.

Как работает проверка через ?api=verify

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

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

История с пропущенной буквицей: что она показывает

Матрица 7×7 из 49 славянских буквиц задумана как детерминированная система координат смыслов, и именно на неё агент может сослаться точно, строкой и столбцом. Но детерминированность структуры не равна её безошибочности: заполнение матрицы проверяет человек, а не встроенный валидатор.

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

llms.txt, sitemap.xml и машиночитаемый интерфейс: что выбрать

Три инструмента решают разные задачи, и путать их дорого. sitemap.xml перечисляет страницы сайта. llms.txt описывает, что лежит по каждой ссылке, и может отдать Markdown-версии. API отвечает на конкретный вопрос и меняет состояние.

Когда достаточно llms.txt и Markdown-версий

В sitemap.xml видно, какие страницы есть на сайте: по нему можно найти URL меню, но что внутри меню, из файла не следует. llms.txt закрывает этот пробел: там описывают, что лежит по каждой ссылке, и дают Markdown-версии страниц. Для небольшого сайта этого может хватить.

Ограничение честное: llms.txt - приглашение и карта, а не гарантия, что конкретная модель его прочитает и станет вести себя по правилам. Если меню длинное, агент после перехода по ссылке всё равно получит длинное меню, просто без HTML. Поэтому для больших разделов имеет смысл отдельный Markdown-файл на каждый раздел.

Когда нужен API с состоянием и действиями

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

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

Практическое правило выбора простое. Контентный сайт, которому нужно, чтобы агент прочитал материал, обходится llms.txt и Markdown-версиями. Сайт с состоянием и действиями получает API, а llms.txt остаётся картой к нему.

Ограничения проекта: что «Солнечный Город» не делает

Автор перечисляет границы прямо, и это самая полезная часть разбора: по ним видно, где подход перестаёт работать.

  • Не обучает модели. ?api=dataset - заготовка датасета в JSONL с парами prompt/response, а не корпус для дообучения и не пайплайн тренировки.
  • Не автономен в инженерном смысле. Между визитами ничего не происходит: нет фонового процесса, который двигал бы мир сам по себе.
  • Не рассчитан на большой поток гостей. Файловое хранилище и досчёт на каждом запросе плохо переносят параллельную нагрузку.
  • Не рассылает ничего сам, не требует ключей и не собирает данные, кроме JSON, присланных добровольно.

Отсюда граница применимости: это кейс и эксперимент, а не готовый сервис для нагруженного API. Гарантий безопасности и SLA здесь нет и по устройству быть не может: один файл и файловое хранилище не дают ни изоляции, ни ретраев, ни предсказуемой задержки под нагрузкой.

Что можно перенести в свой проект: практические выводы

Переносимый принцип один: сначала контракт, потом код. Пока не описано, какие вопросы агент задаёт сайту и какие ответы получает, любой API превращается в набор случайных эндпоинтов.

  1. Опишите вопросы агента и ответы на них. Один инструмент на один вопрос, без универсальных «сделать всё».
  2. Начните с llms.txt и Markdown-версий страниц. Контентному сайту этого хватает, и это дешевле любого API.
  3. Добавляйте вызовы под конкретные задачи: состояние, короткий точный ответ, действие. Если вопроса нет, эндпоинт не нужен.
  4. Храните состояние так, чтобы его можно было досчитать по требованию. Ленивая схема снимает необходимость в cron и очередях на старте.
  5. Фиксируйте артефакты хэшами, если читателю важно убедиться, что файл не подменили. Хэш проверяет целостность, а не смысл.
  6. Публикуйте ограничения там же, где обещания: агент прочитает и то, и другое.

Границы самостоятельной проверки стоит обозначить сразу. Конкурентный доступ к файлам, защита эндпоинтов от мусорных POST, поведение под нагрузкой и настройки конкретного хостинга требуют бэкенд-специалиста. Это не та часть, которую разумно додумывать по аналогии с чужим арт-проектом.

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

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

Подписаться на канал