Система человекопонятных URI в haih-agent сохраняет стабильность адресов и SEO-сигналы
Система человекопонятных URI в haih-agent сохраняет стабильность адресов и SEO-сигналы
В haih-agent URI публичных Concepts постепенно переводятся от технических адресов с идентификаторами к человекопонятным адресам (ЧПУ), которые отражают смысл страницы.
Реализация начала формироваться в коммите:
https://github.com/haih-net/agent/commit/1f99a51dd407eb4e58f9e2f83f411a265db2f24c
Генерация URI
Если URI не задан явно, для Concept используется человекопонятный slug, построенный из имени. Для этого применяется общая логика slugifyUri().
URI обрабатывается по сегментам, а не как одна строка целиком. Это важно: / остается структурой маршрута, а каждый отдельный сегмент нормализуется независимо.
Пример:
/concepts/TypeScript Generics
→
/concepts/typescript-generics
Такой подход позволяет использовать семантические слова непосредственно в URL вместо технического CUID.
Изменение URI и 301
При смене URI используется общая логика processUriChange(oldUri, newUri) или ее актуальный эквивалент.
Новый URI сначала нормализуется. Если адрес действительно изменился, система создает permanent redirect:
старый URI → новый URI
HTTP 301
После этого у Concept сохраняется новый адрес.
Это позволяет менять и улучшать URI без массового разрушения уже опубликованных ссылок.
Декодирование входящих URL
При чтении маршрута percent-encoded URL должны приводиться к тому же представлению, в котором URI хранится в системе.
Первоначально проблема проявилась на адресах с %22 и другими encoded-символами. Простое использование decodeURI() решало часть случаев, но оказалось недостаточным для зарезервированных символов.
Например:
/projects/%40prisma-cms/sendmail
должен соответствовать:
/projects/@prisma-cms/sendmail
decodeURI() не преобразует %40 в @, поэтому целевая логика должна быть segment-aware: сначала сохранить структуру pathname по /, затем декодировать отдельные сегменты через decodeURIComponent() и собрать путь обратно.
Это симметрично логике slugifyUri(), которая также работает по сегментам.
Миграция старых Concepts
Новая URI-механика сама по себе не исправляет исторические Concepts, которые уже были созданы с техническими URL. Для этого нужен административный bulk-механизм миграции: вычислить актуальный slug, обновить URI через общую логику смены адреса и сохранить 301 со старого URL.
Связанная работа по массовому обновлению URI развивается отдельно в haih-agent.
SEO-смысл
Система решает сразу несколько задач:
- URL сам содержит тему документа и становится дополнительным семантическим сигналом;
- старые ссылки не превращаются в 404 после улучшения адресов;
- 301 помогает перенести накопленные сигналы на новый canonical URI;
- технические CUID постепенно перестают быть публичным интерфейсом сайта;
- единая нормализация URI уменьшает количество ложных дублей и 404;
- downstream-проекты на haih-agent получают общий механизм ЧПУ вместо локальных реализаций.
Особенно важна эта система для fi1osof.ru — единого информационного ядра профессиональной деятельности, где публичные Concepts должны иметь понятные адреса и устойчивую перелинковку.
Текущее ограничение: целостность ссылок внутри content
Стабильный URI самой сущности еще не гарантирует целостность всего графа. В content Concepts могут оставаться ссылки на несуществующие или уже измененные URI.
Поэтому следующий необходимый слой системы — автоматическая валидация внутренних ссылок и обновление content при создании/изменении Concept. Это должно предотвращать появление битых ссылок в AI-generated и вручную обновляемом контенте.
Связано: