{ "version": "https://jsonfeed.org/version/1.1", "title": "artka.dev — Записки из продакшна", "description": "Заметки про Claude Code, AI-агентов, RAG-пайплайны и production backend от Artyom Kashuta.", "home_page_url": "https://artka.dev/", "feed_url": "https://artka.dev/feed.json", "language": "ru-RU", "authors": [ { "name": "Artyom Kashuta", "url": "https://artka.dev/about", "avatar": "https://artka.dev/avatar-512.png" } ], "icon": "https://artka.dev/icon-512.png", "favicon": "https://artka.dev/favicon.svg", "items": [ { "id": "https://artka.dev/blog/claude-md-12-rules", "url": "https://artka.dev/blog/claude-md-12-rules", "title": "12 правил для CLAUDE.md: расширение Karpathy на ошибки 2026 года", "summary": "Mnilax протестировал 12 правил для CLAUDE.md на 30 кодовых базах за 6 недель — расширение шаблона Karpathy на agent-loops, чекпойнты и fail-loud. Разбор и рамка применения.", "date_published": "2026-05-10T00:00:00.000Z", "tags": [ "ai", "claude-code", "prompt-engineering" ], "authors": [ { "name": "Artyom Kashuta", "url": "https://artka.dev/about", "avatar": "https://artka.dev/avatar-512.png" } ], "language": "ru-RU", "content_html": "
\n

За четыре месяца после январского треда Karpathy шаблон CLAUDE.md из 4 правил вырос до 12. Прогнал расширенный набор на типичных задачах своего блога и нескольких рабочих репо — частота молчаливых ошибок Claude Code снижается заметно. Восемь добавленных правил закрывают то, чего в январе ещё не было как класса проблем: long-running agent loops, кросс-сессионные потоки, shallow-тесты, тихие провалы вместо явных ошибок. Открыл собственный CLAUDE.md этого блога — четыре исходных правила Karpathy там уже есть в Стандарты кода и Запреты, восемь добавленных — нет. Разбираю каждое, и где имеет смысл вставить.

\n
\n
\n

1. Что случилось за четыре месяца

\n

В конце января Andrej Karpathy опубликовал тред с тремя жалобами на Claude как code-writer:

\n\n

Forrest Chang упаковал жалобы в CLAUDE.md из четырёх поведенческих правил и закоммитил на GitHub. Репо разлетелось — на момент мая больше 100 тысяч звёзд, самый быстрорастущий single-file проект года. Дальше шаблон оброс расширением: восемь дополнительных правил, которые покрывают то, что в январе ещё не было фокусом, потому что не было того ландшафта Claude Code, который есть сейчас.

\n
flowchart LR\n  subgraph jan["Январь 2026"]\n    K["Karpathy: тред с тремя<br/>failure modes"]\n    K --> F["Forrest Chang:<br/>4 правила CLAUDE.md"]\n  end\n  subgraph may["Май 2026"]\n    F --> N["Новые failure modes:<br/>agent loops, multi-codebase,<br/>shallow tests, silent failures"]\n    N --> M["+8 правил,<br/>итого 12"]\n  end\n
\n
\n

2. Четыре правила Karpathy

\n

Это базис. Без них любая надстройка теряет половину смысла.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
#ПравилоЧто закрывает
1Think Before CodingМолчаливые догадки. Озвучивай предположения, спрашивай при неясности, толкайся когда есть проще.
2Simplicity FirstМинимум кода, который решает задачу. Никаких спекулятивных абстракций «на будущее».
3Surgical ChangesТрогай только то, что нужно. Не «улучшай» соседний код, не переформатируй то, о чём не просили.
4Goal-Driven ExecutionОписывай критерии успеха, не пошаговую инструкцию. Сильный success-criteria даёт модели итерироваться сам.
\n

В моём CLAUDE.md Astro-блога эти четыре закрыты не отдельным разделом, а блоками Стандарты кода → Функциональный стиль (правило 2 и 3 — никаких классов, никаких лишних абстракций) и Запреты (правило 3 — список «не делай»). Сами правила не дублируются текстом, но их следствия попадают в контекст.

\n
\n

3. Где Karpathy-шаблон недотягивает

\n

Четыре дыры, которые я наблюдаю в реальной работе:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ДыраЧто ломаетсяКакие добавленные правила закрывают
Long-running agent tasksMulti-step pipeline уходит в дрейф, тратит токены, теряет контекст6 (бюджеты), 10 (чекпойнты), 12 (loud)
Multi-codebase consistencyВ монорепо «match existing style» неоднозначно — Claude выбирает случайно или усредняет11 (конвенции), 7 (surface conflicts)
Test quality«Тесты прошли» становится самоцелью; Claude пишет тесты, которые не упадут даже на сломанной логике9 (intent over behavior)
Prototype vs production«Simplicity First» переусердствует на ранней стадии, когда нужно 100 строк скаффолдинга для прощупки(не покрыто 12 правилами — отдельно)
\n

Последняя дыра остаётся живой. Либо включаешь Simplicity, либо отключаешь — серединного режима у CLAUDE.md нет.

\n
\n

4. Восемь добавленных правил

\n

По одному, с моментом, который их вызвал.

\n

4.1. Rule 5 — Use the model only for judgment calls

\n

Если ответ известен из status code или схемы данных — это не работа модели. Реальный кейс из моей практики: код звал Claude, чтобы решить, ретраить ли API-вызов на 503. Две недели работало, потом начало флакать, потому что модель читала тело запроса как контекст для решения. Retry-политика стала случайной, потому что промпт был случайным.

\n

Рамка: Claude — для классификации, экстракции, драфтов, summarization. Не для роутинга, ретраев, детерминированных трансформаций. Если status code уже отвечает на вопрос — на него отвечает обычный код.

\n

4.2. Rule 6 — Token budgets are not advisory

\n

Без бюджета цикл уходит в дамп на 50 000 токенов. Жёсткий вариант: 4 000 на задачу, 30 000 на сессию. Подходишь к границе — суммируешь и стартуешь сессию заново.

\n

Типовой случай: 90-минутная debugging-сессия с одним и тем же 8 КБ-сообщением об ошибке. В финале — повторное предложение фиксов, которые уже отвергал 40 сообщений назад. Модель счастливо итерирует на потерянном треке. Бюджет убил бы цикл на 12-й минуте.

\n

4.3. Rule 7 — Surface conflicts, don’t average them

\n

Если в кодовой базе два паттерна обработки ошибок — try/catch и global boundary — Claude напишет код, который делает оба. Двойные хендлеры. Симптом: ошибка глотается дважды.

\n

Правило: при противоречии выбираешь один (более новый или более тестированный), объясняешь почему, второй маркируешь к чистке. Усреднённый код, который удовлетворяет обоим правилам — худший возможный.

\n

4.4. Rule 8 — Read before you write

\n

Karpathy говорит «не трогай соседний код». Не говорит — прочитай его перед добавлением своего. Реальный случай: Claude добавил функцию рядом с уже существующей идентичной, не прочитав файл. Победил порядок импортов — старая, source-of-truth полгода, проиграла свежей одноимённой.

\n

Рамка: перед добавлением кода в файл — прочитать экспорты, ближайший вызывающий код и общие утилиты. «Looks orthogonal to me» — самая опасная фраза в кодовой базе.

\n

4.5. Rule 9 — Tests verify intent, not just behavior

\n

Тест expect(getUserName()).toBe('John') ничего не значит, если функция возвращает константу. Тесты должны падать при изменении бизнес-логики, иначе они тестируют существование функции, не её корректность.

\n

Типовой пример: 12 тестов на auth-функцию, все зелёные, в проде auth сломан. Тесты проверяли, что функция что-то возвращает, не что она возвращает правильное значение.

\n

4.6. Rule 10 — Checkpoint after every significant step

\n

Многошаговый рефакторинг по 20 файлам ломается на 4-м шаге, Claude уходит дальше на сломанном состоянии. К моменту, когда замечаешь, шаги 5 и 6 уже сделаны поверх сломанного — распутывание занимает дольше, чем переделка с нуля.

\n

Правило: после каждого значимого шага — резюме, что сделано, что верифицировано, что осталось. Если потерял трек — остановиться и пересказать.

\n

4.7. Rule 11 — Match the codebase’s conventions, even if you disagree

\n

Claude вводит хуки в codebase на классовых компонентах. Технически работает. Ломает testing pattern, рассчитанный на componentDidMount. Полдня на удалить и переписать.

\n

Правило: внутри кодовой базы конформность важнее вкуса. Несогласие — отдельный разговор, не silent fork. Snake_case против camelCase, классы против хуков — выбираешь то, что есть, не то, что лучше.

\n

4.8. Rule 12 — Fail loud

\n

Самые дорогие ошибки те, что выглядят как успех. «Миграция выполнена» при тихо пропущенных 14% записей. «Тесты прошли», когда часть была пропущена. «Фича работает», если не проверен edge case, который явно просили проверить.

\n

Правило: при неуверенности — поднимай вопрос, не прячь. По умолчанию surfacing неопределённости, не скрытие.

\n
\n

5. Что не работает (то, что отсеялось)

\n

Шаблон ценен не только тем, что в нём есть, но и тем, что отсеяно при попытках расширить:

\n\n
\n

6. Сверка со своим CLAUDE.md

\n

Открыл файл этого блога (191 строка) и прошёлся по 12 правилам. Картина:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ПравилоВ моём CLAUDE.mdГде
1. Think before codingкосвенночерез architect → critic workflow в команде агентов
2. SimplicityдаНикаких классов, Иммутабельность по умолчанию
3. Surgical changesдаЗапреты (deprecated @astrojs/tailwind, node:*-alpine и т.п.)
4. Goal-drivenкосвенночерез subagent-структуру, не отдельным правилом
5. Judgment-onlyнет
6. Token budgetsнет
7. Surface conflictsнет
8. Read before writeчастичноGitNexus-секция требует impact analysis перед редактом
9. Test intentнет
10. Checkpointsнет
11. Match conventionsдаСтандарты кода → TypeScript / Astro / Git
12. Fail loudнет
\n

Получилось — четыре покрыто, два частично, шесть нет. Файл фактически Karpathy-уровня, без надстройки на 2026 год.

\n

Какие из недостающих имеет смысл добавить именно для Astro-блога с публикациями через админку:

\n\n

Rule 7 для одиночного проекта менее острая. Rule 5 покрывается тем, что в рантайме блога нет AI-роутинга — модель не принимает решений за код.

\n
\n

7. Как добавить — без раздувания

\n

Дисциплина:

\n
    \n
  1. Не превышать 200 строк всего. Считая стек, команды, запреты, правила. У меня сейчас 191 — добавление четырёх правил означает вынос части Главная страница или GitNexus-секции в @docs/... через @-импорт Claude Code.
    2. \n
  2. Каждое правило отвечает на вопрос «какую ошибку оно предотвращает». Если не отвечает — выкидываешь.
    3. \n
  3. Capability-agnostic формулировки. «Match the enforced style», не «use prettier».
    4. \n
  4. Императивы, не пожелания. «State assumptions explicitly», не «think carefully».
    5. \n
  5. Тестируешь. Прогоняешь типичную задачу до и после. Нет разницы — правило не сработало в твоём контексте, удаляешь.
    6. \n
\n

Шесть правил, заточенных под реальные ошибки, сильнее двенадцати общих.

\n
\n

Итог

\n

Karpathy зафиксировал три code-writing failure modes января. Forrest Chang упаковал их в четыре правила, и сообщество схватило шаблон. Расширение до 12 родилось из того, что в мае ландшафт Claude Code стал другим: multi-step агенты, hook-каскады, skill-конфликты, кросс-сессионные потоки. Восемь добавленных правил закрывают новые дыры, не замещая исходные.

\n

CLAUDE.md — не wishlist, а behavioral contract против конкретных ошибок, которые ты сам уже видел. Чужой шаблон полезен как стартер. Дальше — фильтруешь под свои failure modes, не наоборот. Шесть правил, точно подобранных, лучше двенадцати скопированных.

\n
\n

Источники:

\n\n" }, { "id": "https://artka.dev/blog/local-coding-agent", "url": "https://artka.dev/blog/local-coding-agent", "title": "ds4 от antirez: локальный coding agent на DeepSeek V4 Flash, который работает на MacBook", "summary": "Создатель Redis за две недели написал инференс-движок только для одной модели — DeepSeek V4 Flash. 1M контекст, 26 t/s на M3 Max, KV-кэш на диске. Как это запустить и подключить к Claude Code.", "date_published": "2026-05-09T00:00:00.000Z", "tags": [ "ai", "local-inference", "coding-agents", "deepseek", "apple-silicon" ], "authors": [ { "name": "Artyom Kashuta", "url": "https://artka.dev/about", "avatar": "https://artka.dev/avatar-512.png" } ], "language": "ru-RU", "content_html": "
\n

Garry Tan и Bindu Reddy 9 мая 2026 одновременно расшарили одну и ту же новость: создатель Redis Salvatore Sanfilippo (antirez) выложил ds4 — инференс-движок на C+Metal, который запускает DeepSeek V4 Flash (284B MoE, 1M контекста) на ноутбуке. Не «технически возможно», а «работает с coding-агентами на 26 t/s». Я разобрался, что под капотом, и как использовать это как локальный backend для Claude Code.

\n
\n
\n

1. Что произошло за две недели

\n

24 апреля 2026 DeepSeek выпустил серию V4. V4 Flash — efficiency-модель: 284 миллиарда параметров суммарно, 13 миллиардов активных (MoE), контекст 1 миллион токенов. Раньше модели такого размера жили только в облаке.

\n

Antirez посмотрел на это и сделал ставку, которую универсальные раннеры сделать не могут. Он форкнул llama.cpp, две недели возился внутри него, понял геометрию V4 Flash, выкинул всё лишнее и написал с нуля движок на 4 файлах: ds4.c (~ инференс), ds4_metal.m (Metal kernels), ds4_server.c (HTTP-сервер), ds4_cli.c (REPL). Снаружи всё это говорит на двух протоколах одновременно: OpenAI Chat Completions (/v1/chat/completions) и Anthropic Messages (/v1/messages). То есть подключается к любому агенту, который умеет один из них.

\n

Результаты, которые автор замерил сам:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
МашинаКвантПромптPrefillGeneration
MacBook Pro M3 Max, 128 GBq2короткий58.52 t/s26.68 t/s
MacBook Pro M3 Max, 128 GBq211709 токенов250.11 t/s21.47 t/s
Mac Studio M3 Ultra, 512 GBq2короткий84.43 t/s36.86 t/s
Mac Studio M3 Ultra, 512 GBq412018 токенов448.82 t/s26.62 t/s
\n

26 токенов в секунду генерации — это не «можно посмотреть», это рабочая скорость для coding-агента, который пишет, читает файлы, вызывает инструменты. На длинном промпте генерация падает до 21 t/s, но за счёт KV-кэша на диске это окупается уже на третьем запросе той же сессии.

\n
\n

2. Три инженерных трюка, которые делают это возможным

\n

Я внимательно прочитал README и AGENT.md репозитория, и ниже — самое существенное, без чего ds4 не работал бы.

\n

2.1. Асимметричное 2-битное квантование

\n

Стандартный подход к 2-битному кванту — давить всё подряд до 2 бит, и тогда модель начинает галлюцинировать в tool calling, путать аргументы и забывать схему. Antirez сделал иначе: квантованы только MoE-эксперты на routed-пути (up/gate в IQ2_XXS, down в Q2_K) — потому что они занимают большую часть веса (модель — 284B, и почти всё это — эксперты). Shared-эксперты, проекции, роутинг — остаются в Q8. Это компоненты, в которых потеря точности дорого стоит.

\n

Эффект: 2-битный квант весит 81 GB и помещается в 128 GB унифицированной памяти MacBook Pro M3 Max, при этом надёжно работает в coding-агентах (что валидируется тестами против официальных логитов API DeepSeek).

\n

2.2. KV-кэш как first-class disk citizen

\n

Главная боль stateless API-протоколов вроде Chat Completions: клиент каждый раз присылает всю историю, и сервер обязан пре-фильнуть её с нуля. Claude Code, например, на старте шлёт ~25K токенов системного промпта. На локальном железе это десятки секунд до первого токена.

\n

Ds4 решает это лобово: после успешного prefill стейт сессии (KV-чекпоинт) сериализуется в файл, ключ — SHA1 от token IDs. Когда приходит следующий запрос с тем же префиксом, сервер берёт чекпоинт с диска и пропускает prefill. Из README:

\n
\n

The KV cache is actually a first class disk citizen. <…> Modern MacBooks have fast SSDs and compressed KV caches like the one of DeepSeek v4.

\n
\n

На практике это означает разницу между «4 секунды до первого токена при повторном вызове» и «60 секунд». Диск тут — не своп под давлением, а логичное хранилище: SSD достаточно быстрые, KV у DeepSeek V4 хорошо сжимается, а характеристика «один и тот же системный промпт + меняющийся хвост» точно описывает работу coding-агента.

\n

2.3. Metal-only и одна модель за раз

\n

Никакого CUDA, никакого CPU-фоллбэка для прода (CPU-путь существует только для correctness-чеков и сейчас падает на уровне ядра macOS из-за бага в VM — antirez об этом честно пишет). Никакой попытки сделать «универсальный раннер». Только Apple Silicon, только эта одна модель, и так до тех пор, пока не появится новая версия V4 Flash или сильно лучшая модель того же класса.

\n

Цена — narrow bet. Выгода — тебе не нужно поддерживать матрицу (модель × железо × квант), и ты можешь оптимизировать Metal-ядра под точную геометрию слоёв этой конкретной модели.

\n
\n

3. Что мне понадобится: железо, модель, час времени

\n

Я планирую разворачивать это на MacBook Pro M3 Max, 128 GB (минимально жизнеспособная конфигурация по README). У меня его пока нет, и в этом разделе — честный план, что я буду делать, когда железо приедет; цифры взяты из бенчмарков antirez’а, но я хочу их перепроверить на своём экземпляре.

\n

Минимальные требования по моим прикидкам:

\n\n

То, чего может не хватить начинающим: 128 GB unified memory — это уровень MBP M3 Max в топовой комплектации или Mac Studio. На 64-гиговом Mac Q2 не заработает: модель просто не влезет в RAM. Это не «медленно», это «никак».

\n
\n

4. Установка пошагово

\n

Команды ниже — то, что я сделаю в первый же день, опираясь на инструкции README. Где описание скучает за конкретикой — я добавил собственные комментарии.

\n

4.1. Сборка

\n
# 1. Склонировать репозиторий\ngit clone https://github.com/antirez/ds4.git\ncd ds4\n\n# 2. Скачать 2-битный квант (81 GB; для 128 GB MBP)\n./download_model.sh q2\n\n# Скрипт качает с huggingface.co/antirez/deepseek-v4-gguf,\n# поддерживает резюм через curl -C - — можно прервать и продолжить.\n# Если нужен 4-битный квант (для Mac Studio 256+ GB), используй ./download_model.sh q4.\n\n# 3. Собрать\nmake\n\n# Проверить, что собралось:\n./ds4 --help\n./ds4-server --help\n
\n

Сборка — обычный make, никаких CMake, никаких pkg-config. Это намеренно: зависимостей за пределами Apple SDK у проекта нет.

\n

4.2. Первый запуск в REPL

\n
./ds4 -p "Объясни Redis streams в одном абзаце."\n
\n

Без -p запускается интерактивная сессия с командами /help, /think, /think-max, /nothink, /ctx N, /read FILE, /quit. Это хорошо для проверки, что движок жив, и для сравнения скорости генерации против заявленных 26 t/s.

\n

4.3. Запуск как HTTP-сервер

\n

Это режим, в котором ds4 становится локальным backend’ом для агентов:

\n
./ds4-server \\\n  --ctx 100000 \\\n  --kv-disk-dir /tmp/ds4-kv \\\n  --kv-disk-space-mb 8192\n
\n

Параметры:

\n\n

Сервер слушает 127.0.0.1:8000. Эндпоинты:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointПротокол
POST /v1/chat/completionsOpenAI Chat Completions (+ tools)
POST /v1/completionsOpenAI legacy completions
POST /v1/messagesAnthropic Messages (для Claude Code)
GET /v1/modelsсписок моделей
\n

Аутентификация по статичному API-ключу (по умолчанию принимается любой; в README рекомендуется dsv4-local).

\n
\n

5. Подключение как coding agent

\n

Это та часть, ради которой я вообще копал тему. Все три приведённых ниже способа работают одновременно — каждый агент ходит в один и тот же ds4-server.

\n

5.1. Claude Code → Anthropic-совместимый эндпоинт

\n

Claude Code умеет говорить с любым backend’ом, который выставляет Anthropic Messages API. Создаём обёртку ~/bin/claude-ds4:

\n
#!/bin/sh\nunset ANTHROPIC_API_KEY\n\nexport ANTHROPIC_BASE_URL="${DS4_ANTHROPIC_BASE_URL:-http://127.0.0.1:8000}"\nexport ANTHROPIC_AUTH_TOKEN="${DS4_API_KEY:-dsv4-local}"\nexport ANTHROPIC_MODEL="deepseek-v4-flash"\n\n# Подменяем все алиасы Sonnet/Haiku/Opus на локальную модель —\n# чтобы /model в Claude Code не дёрнул облачный fallback.\nexport ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-flash"\nexport ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"\nexport ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-flash"\nexport CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"\n\n# Отключаем телеметрию и не-стриминговый fallback.\nexport CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1\nexport CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1\nexport CLAUDE_STREAM_IDLE_TIMEOUT_MS=600000\n\nexec "$HOME/.local/bin/claude" "$@"\n
\n

chmod +x ~/bin/claude-ds4 — и запускаешь Claude Code как claude-ds4 вместо claude. Все запросы пойдут на локальный ds4-сервер. Тонкость, на которую обращает внимание сам antirez:

\n
\n

Claude Code may send a large initial prompt, often around 25k tokens, before it starts doing useful work. Keep --kv-disk-dir enabled.

\n
\n

Без disk KV-кэша запуск Claude Code на холодную будет занимать минуту и больше; с кэшем — после первого старта последующие будут восстанавливаться с диска.

\n

5.2. opencode

\n

opencode конфигурируется через ~/.config/opencode/opencode.json:

\n
{\n  "$schema": "https://opencode.ai/config.json",\n  "provider": {\n    "ds4": {\n      "name": "ds4.c (local)",\n      "npm": "@ai-sdk/openai-compatible",\n      "options": {\n        "baseURL": "http://127.0.0.1:8000/v1",\n        "apiKey": "dsv4-local"\n      },\n      "models": {\n        "deepseek-v4-flash": {\n          "name": "DeepSeek V4 Flash (ds4.c local)",\n          "limit": { "context": 100000, "output": 384000 }\n        }\n      }\n    }\n  },\n  "agent": {\n    "ds4": {\n      "description": "DeepSeek V4 Flash served by local ds4-server",\n      "model": "ds4/deepseek-v4-flash",\n      "temperature": 0\n    }\n  }\n}\n
\n

limit.context: 100000 обязательно совпадает с --ctx, с которым стартует ds4-server — иначе сервер обрежет, а opencode об этом не узнает и пошлёт следующее сообщение, ожидая нерабочую длину.

\n

5.3. Pi (мини-агент antirez’а)

\n

Если используешь Pi — формат немного другой, конфиг в ~/.pi/agent/models.json:

\n
{\n  "providers": {\n    "ds4": {\n      "name": "ds4.c local",\n      "baseUrl": "http://127.0.0.1:8000/v1",\n      "api": "openai-completions",\n      "apiKey": "dsv4-local",\n      "compat": {\n        "supportsStore": false,\n        "supportsDeveloperRole": false,\n        "supportsReasoningEffort": true,\n        "supportsUsageInStreaming": true,\n        "maxTokensField": "max_tokens",\n        "thinkingFormat": "deepseek",\n        "requiresReasoningContentOnAssistantMessages": true\n      },\n      "models": [\n        {\n          "id": "deepseek-v4-flash",\n          "name": "DeepSeek V4 Flash (ds4.c local)",\n          "reasoning": true,\n          "contextWindow": 100000,\n          "maxTokens": 384000,\n          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }\n        }\n      ]\n    }\n  }\n}\n
\n

cost: 0 — это не маркетинг, это правда. Каждый запрос обходится в электричество и износ SSD, не в токены.

\n
\n

6. Где это сломается (важные грабли)

\n

Реальные ограничения, на которые я наткнусь, и то, как их обходить.

\n

Окно контекста должно быть согласовано везде. Стартуешь сервер с --ctx 100000, ставишь в opencode limit.context: 100000, в Claude Code не лезешь в системный промпт сверх этого. Если у Claude Code init-prompt ~25K, то на проект остаётся 75K — реально хватает на средний codebase, но не на огромные репозитории.

\n

Disk KV-кэш «привязан» к точному префиксу. Любая правка в системном промпте, в CLAUDE.md, в первых сообщениях — инвалидирует чекпоинт. Это не баг, это by design: матчинг идёт по SHA1 от token IDs. Если ты часто редактируешь CLAUDE.md, ожидай холодные старты. Решение — закоммитить системный контракт и не править его в каждой сессии.

\n

MTP/спекулятивное декодирование пока не даёт большого выигрыша. В README прямо написано: «currently provides at most a slight speedup». Не закладывайся на удвоение скорости от MTP — текущая реализация correctness-gated и на сложных промптах часто триггерит партиал-аксепт.

\n

Один live KV-кэш в памяти. Сервер сейчас не батчит независимые запросы. Если два агента ходят одновременно — второй ждёт первого. Это нормальный trade-off для локального single-user setup, но если ты хочешь параллельный multi-tenancy на одном Mac — ds4 пока не для этого.

\n

CPU-режим падает на свежих macOS. Это про debug-путь, не про прод (Metal-only — основной таргет), но если по привычке захочешь сравнить инференс на CPU — не делай этого: kernel-panic, надо ребутиться.

\n
\n

7. Что это значит: vertical inference engines как тренд

\n

Главное — не ds4 сам по себе, а паттерн, который antirez формализовал.

\n

Локальный inference сейчас выглядит как «универсальный раннер + тысяча моделей в GGUF + обёртки разной свежести». Это работает, но движётся со скоростью наименее популярной модели: ускорять Llama 3.1 в llama.cpp проще, чем добавить эффективную поддержку DeepSeek V4 — потому что в первом случае структура слоёв совпадает с двадцатью другими моделями, а во втором — appears once.

\n

Antirez показывает противоположный путь. Один движок — одна модель — один сценарий (coding agent). Дальше нужно три вещи, и все три — в продукте:

\n
    \n
  1. Inference engine с HTTP API.
    2. \n
  2. GGUF, специально подготовленный под этот движок и его допущения.
    3. \n
  3. Тесты и валидация на сцепке с конкретными агент-клиентами.
    4. \n
\n

Если эта ставка работает (и бенчмарки говорят, что да), будущее локального inference — не «ещё одна абстракция поверх абстракции», а «у каждой важной модели — свой ds4-подобный проект». Когда выходит V4.1 или V5, кто-то из community делает новый движок, новый GGUF, новые тесты, и через две недели у пользователей уже работающая локальная установка. Старые движки уходят на покой вместе со старыми моделями.

\n

И второе. В README antirez явно пишет:

\n
\n

This software is developed with strong assistance from GPT 5.5 and with humans leading the ideas, testing, and debugging.

\n
\n

Две недели от форка llama.cpp до production-ready узкого движка с серверным API — без AI это не сделать, и antirez это прямо говорит. Вот это переключение — «один человек + AI = инфраструктура для целой модели за две недели» — на мой взгляд интереснее, чем сами цифры t/s.

\n
\n

Итог

\n

ds4 от antirez — это не «ещё один локальный инференс». Это узкая ставка: один движок, одна модель (DeepSeek V4 Flash), одна архитектура железа (Apple Silicon с Metal), один сценарий (coding agent). За счёт асимметричного 2-битного кванта 284B-модель влезает в 128 GB MacBook, за счёт disk KV-кэша работает с агентами, которые гоняют 25K-токенные системные промпты, за счёт OpenAI/Anthropic-совместимости подключается к Claude Code, opencode и Pi из коробки.

\n

Если у вас есть Mac с 128 GB+ — это рабочий локальный backend для серьёзной коммерческой работы с приватным кодом. Если нет — ждать DDR5 и unified memory на Linux/CUDA, или смотреть, кто следующий повторит этот паттерн под свою связку «модель + железо».

\n

В любом случае стоит наблюдать. Я ставлю на то, что через год так будут собирать половину серьёзных локальных установок.

\n
\n

Источники:

\n\n" }, { "id": "https://artka.dev/blog/json-ld-graph-astro", "url": "https://artka.dev/blog/json-ld-graph-astro", "title": "JSON-LD @graph в Astro: от дублирующихся inline-блоков к единому citable-узлу", "summary": "Пошаговый разбор миграции с per-page Schema.org-блоков на единый @graph в BaseLayout: стабильные @id, ссылки между сущностями, articleBody-excerpt и FAQ.", "date_published": "2026-05-02T00:00:00.000Z", "tags": [ "seo", "astro", "schema-org" ], "authors": [ { "name": "Artyom Kashuta", "url": "https://artka.dev/about", "avatar": "https://artka.dev/avatar-512.png" } ], "language": "ru-RU", "content_html": "
\n

Большинство руководств по Schema.org для блогов учат: на посте — <script> с BlogPosting, на главной — с WebSite, на about — с Person. Это работает, но проигрывает в citability. Краулер видит Person из BlogPosting.author как «кто-то по имени X», а не как entity, который ещё и founder of #organization, который publisher of #blog. В посте — пошаговый разбор, как заменить per-page inline-блоки одним @graph в BaseLayout.

\n
\n
\n

1. Зачем менять — citability вs SERP

\n

Структурированные данные у разработчика-блогера обычно ассоциируются с одним вопросом: «появится ли мой пост в Google с rich snippet?». Под эту задачу хватает любого валидного BlogPosting — пройдёт Rich Results Test, появятся stars/breadcrumb. И этим часто всё кончается: добавили @type: BlogPosting, проверили в валидаторе, забыли.

\n

В 2026 году у структурированных данных появился новый, более требовательный потребитель — LLM-краулер, который собирает контент для retrieval-augmented generation и для citation. Ему нужен не «ещё один rich snippet», а связный entity-граф: чтобы при упоминании автора в одном посте он опознал того же автора в другом, чтобы организация-publisher была одним и тем же объектом на всём сайте, чтобы блог как сущность ссылался обратно на автора.

\n

LLM, выдающий цитату, делает примерно следующее: вытаскивает passage, проверяет окружающую entity-разметку, пытается сопоставить автора с известной сущностью. Если на сайте Person.name = "Артём Кашута" встречается в трёх разных Schema.org-блоках без общего @id, краулер обязан догадываться, один это человек или три. Если же есть один Person#person со стабильным URI, и все остальные узлы (Organization.founder, BlogPosting.author, Blog.author) ссылаются на него через {"@id": "..."} — догадки не нужны, граф собран автором.

\n

Это проблема, которую keyword density не решает. Это entity disambiguation, и решается она graph topology.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
АспектPer-page inline blocksSingle @graph с @id
Google Rich Resultsработаетработает
LLM entity match (Person)догадка по именигарантирована через @id
Дублирование данных3-5 копий Person на 14 постаходин источник на сайт
Стоимость правки автора14 файлов1 файл (person.ts)
HTML weight3+ скрипта на страницу1 скрипт
\n

Для эпохи SERP-only хватало первого подхода. Для эпохи AI-overviews, citation graphs и retrieval-augmented поиска — нужно второе. Spec нашего блога формулирует это прямо: «move all entity definitions into src/lib/seo/schema.ts returning a single @graph JSON-LD block; pages contribute a BlogPosting/WebPage node referencing the global Person#me and Organization#brand by @id» — см. docs/superpowers/specs/2026-05-02-llm-citable-blog-design.md § «Schema-graph design».

\n

2. Антипаттерн: per-page inline schema

\n

Что эмитит дефолтный Astro-блог, собранный по тутору с какого-нибудь dev.to? Обычно так:

\n\n

Почему так получилось — потому что Astro-компоненты иерархически наследуются, и каждый уровень удобно «добивает» свою порцию данных через свой <script>. Это работает локально, но плохо масштабируется. У нас в репозитории до Plan 1 было ровно это: BaseLayout эмитил один JSON-LD блок, PostLayout поверх него добавлял свои два:

\n
# Pre-Plan 1 (commit 5ed281c~1):\n$ git show 5ed281c~1:src/layouts/BaseLayout.astro | grep -c application/ld+json\n1\n$ git show 5ed281c~1:src/layouts/PostLayout.astro | grep -c application/ld+json\n2\n
\n

То есть страница поста содержала три <script type="application/ld+json"> блока. Каждый со своим Person (где-то полным, где-то усечённым), без общего @id, без перекрёстных ссылок. Краулер, который попадал на пост, видел три не связанных друг с другом entity-облака.

\n

Главные проблемы антипаттерна:

\n
    \n
  1. Дублирование Person. Один и тот же автор описан 3-5 раз. Если бы автор сменил jobTitle или добавил sameAs, надо было бы править во всех файлах. Forget one — и краулер видит конфликт: «у Person с таким именем jobTitle вдруг разный». Это явный signal-to-noise урон.
    2. \n
  2. Разорванный граф. BlogPosting.publisher — это inline-объект { "@type": "Organization", "name": "..." }. Где-то ещё на сайте лежит Organization с founder-полем. Без общих @id валидатор не знает, это один publisher или два.
    3. \n
  3. HTML weight. Три скрипта вместо одного — это лишние десятки байт на каждый, плюс инфляция payload, особенно если на странице несколько одинаковых полей (e.g. описание автора повторяется четырежды).
    4. \n
  4. Согласованность. Если автор правит Person.description в frontmatter about.md, а в BlogPosting-builder он зашит как литерал — рассинхрон неизбежен.
    5. \n
\n

3. Целевая архитектура — @graph с глобальными @id

\n

Целевая модель: один script на странице, внутри — @graph-массив. Глобальные узлы (Person, Organization, WebSite) описаны один раз и идентифицируются стабильными URI. Page-level узлы (BlogPosting, WebPage, CollectionPage, CreativeWork) добавляются BaseLayout-ом и ссылаются на глобальные через @id, не дублируя их данные.

\n

Топология:

\n
flowchart LR\n  Person["Person#person<br/>(глобальный)"]\n  Org["Organization#brand<br/>(глобальный)"]\n  Site["WebSite#site<br/>(глобальный)"]\n  Post["BlogPosting#blogposting<br/>(page-level)"]\n  WebPage["WebPage#webpage<br/>(page-level)"]\n\n  Post -- author --> Person\n  Post -- publisher --> Org\n  Post -- isPartOf --> Site\n  WebPage -- about --> Person\n  WebPage -- isPartOf --> Site\n  Org -- founder --> Person\n  Site -- publisher --> Org\n
\n

Что важно в этой картинке:

\n\n

Стабильные @id — это не URL страницы, это URI с фрагментом, например https://artka.dev/#person, https://artka.dev/#brand. Так принято в JSON-LD: фрагмент-id означает «этот ресурс описан на любой странице, но идентифицируется единым URI».

\n

4. Реализация в Astro 5

\n

В Astro 5 SSG/SSR-граница проходит ровно по BaseLayout-у: на сборке вычисляются props, рендерится HTML, в нём — статический <script type="application/ld+json">. Никаких client-side, никаких rehydration-моргалок. Идеальный момент собрать @graph функционально.

\n

4.1. graphIds — таблица URI

\n

Один файл, в котором перечислены все стабильные идентификаторы:

\n
// src/lib/seo/nodes-global.ts\nconst SITE = "https://artka.dev";\n\nexport const graphIds = {\n  person: `${SITE}/#person`,\n  organization: `${SITE}/#brand`,\n  website: `${SITE}/#website`,\n  blogRu: `${SITE}/#blog-ru`,\n  blogEn: `${SITE}/#blog-en`,\n} as const;\n
\n

Каждый builder, который ссылается на глобальную сущность, импортирует graphIds и использует { "@id": graphIds.person }. Никаких inline-литералов, никаких опечаток в URI.

\n

4.2. Builders — pure functions, никаких классов

\n

В соответствии с проектным правилом «никаких классов в прикладном коде» каждый узел — это чистая функция, возвращающая Record<string, unknown>:

\n
// src/lib/seo/nodes-global.ts (фрагмент)\nexport const buildPersonNode = () => {\n  const merged = Array.from(new Set<string>([...person.knowsAbout, ...person.expertiseAreas]));\n  return {\n    "@type": "Person",\n    "@id": graphIds.person,\n    name: person.name,\n    url: person.url,\n    image: person.image,\n    jobTitle: person.jobTitle,\n    description: person.description,\n    knowsAbout: merged,\n    sameAs: [...person.sameAs],\n    email: person.email,\n    subjectOf: person.notableWork.map((w) => ({\n      "@type": "CreativeWork",\n      name: w.title,\n      url: w.url,\n      description: w.description,\n    })),\n  };\n};\n\nexport const buildOrganizationNode = () => ({\n  "@type": "Organization",\n  "@id": graphIds.organization,\n  name: "artka.dev",\n  url: SITE,\n  logo: { "@type": "ImageObject", url: `${SITE}/favicon.svg` },\n  founder: { "@id": graphIds.person },\n});\n
\n

person — это импорт из src/lib/seo/person.ts, единственного источника правды по автору. Builder складывает knowsAbout и expertiseAreas в Set, чтобы не дублировать ключи. Organization.founder — @id-ссылка, не inline-копия Person.

\n

4.3. Оркестратор — buildGraph

\n

Функция, которая склеивает глобальные и page-level узлы в один @graph:

\n
// src/lib/seo/schema.ts\nimport {\n  buildPersonNode,\n  buildOrganizationNode,\n  buildWebSiteNode,\n  type Locale,\n} from "./nodes-global";\n\nexport type GraphNode = Record<string, unknown> & { "@type": string };\n\nexport interface GraphInput {\n  readonly locale: Locale;\n  readonly extraNodes: ReadonlyArray<GraphNode | null>;\n}\n\nexport interface JsonLdGraph {\n  readonly "@context": "https://schema.org";\n  readonly "@graph": ReadonlyArray<GraphNode>;\n}\n\nexport const buildGraph = (input: GraphInput): JsonLdGraph => {\n  const globals: GraphNode[] = [\n    buildPersonNode(),\n    buildOrganizationNode(),\n    buildWebSiteNode(input.locale),\n  ];\n  const extras = input.extraNodes.filter((n): n is GraphNode => n !== null);\n  return {\n    "@context": "https://schema.org",\n    "@graph": [...globals, ...extras],\n  };\n};\n
\n

API минимальный: вход — locale (чтобы выбрать inLanguage для WebSite) и список дополнительных узлов (extraNodes). Выход — готовый JsonLdGraph. null-узлы фильтруются — это удобно для опциональных узлов вроде FAQPage, builder которых возвращает null при пустом массиве вопросов.

\n

4.4. BaseLayout — единственная точка эмиссии

\n

Весь сайт идёт через BaseLayout, и именно он — и только он — эмитит JSON-LD:

\n
---\n// src/layouts/BaseLayout.astro\nimport { buildGraph, safeJsonLd, type GraphNode } from "~/lib/seo/schema";\n\ninterface Props {\n  title: string;\n  description?: string;\n  // ...\n  /** Additional JSON-LD nodes to merge into the page @graph. */\n  extraSchemaNodes?: ReadonlyArray<GraphNode | null>;\n}\n\nconst { extraSchemaNodes = [] } = Astro.props;\nconst locale = getLocaleFromPath(Astro.url.pathname);\n---\n\n<head>\n  <script\n    is:inline\n    type="application/ld+json"\n    set:html={safeJsonLd(buildGraph({ locale, extraNodes: extraSchemaNodes }))}\n  />\n</head>\n
\n

Три ключевые детали:

\n
    \n
  1. is:inline — Astro не пытается обрабатывать содержимое как JS-модуль.
    2. \n
  2. set:html — мы вставляем уже готовую строку, не давая фреймворку триммить пробелы или экранировать дополнительно.
    3. \n
  3. safeJsonLd — крошечный helper, экранирует <, >, & так, чтобы внутри JSON не оказалось последовательности, которую парсер HTML примет за конец </script>. Без него злонамеренный (или просто неудачный) текст в frontmatter мог бы сломать страницу.
    4. \n
\n
// src/lib/seo/json-ld.ts\nexport const safeJsonLd = (data: unknown): string =>\n  JSON.stringify(data).replace(/</g, "\\\\u003c").replace(/>/g, "\\\\u003e").replace(/&/g, "\\\\u0026");\n
\n

4.5. Page-level контракт

\n

Каждый layout/page добавляет свои узлы через extraSchemaNodes. Например, PostLayout:

\n
const excerpt = extractArticleBody(post.body ?? "", 800);\n\nconst blogPostingNode = buildBlogPostingNode({\n  locale,\n  canonical,\n  title,\n  description,\n  pubDate,\n  updatedDate: updatedDate ?? null,\n  image: absoluteCover,\n  keywords: tags,\n  articleBody: excerpt.text,\n  wordCount: excerpt.fullWordCount,\n});\n\nconst breadcrumbNode = buildBreadcrumbListNode({\n  locale,\n  blogIndexLabel: t(locale, "blog.title"),\n  title,\n});\n\nconst faqNode = buildFaqPageNode({ canonical, items: faq ?? [] });\n
\n
<BaseLayout title={title} extraSchemaNodes={[blogPostingNode, breadcrumbNode, faqNode]}>\n  <slot />\n</BaseLayout>\n
\n

/blog, /projects/<slug>, /tags/<tag>, /about — все используют тот же contract, отличаясь только конкретными builders. Один dispatch, ноль дублирования.

\n

5. articleBody — почему excerpt, а не full body

\n

Поле articleBody в BlogPosting — самая ценная часть для LLM-краулера: это извлекаемый чанк текста, который можно цитировать. И самая опасная для weight: если положить весь пост в JSON-LD, HTML-страница раздуется в 2-3 раза. Spec формулирует компромисс прямо: «emit first 800 words of plain-text body … add wordCount covering the full body».

\n

Excerpt извлекается через mdast: парсим markdown, удаляем code-блоки, mermaid-блоки и inline-html, склеиваем оставшийся текст, режем по 800 слов:

\n
// src/lib/seo/article-body.ts (фрагмент)\nexport const extractArticleBody = (markdown: string, maxWords: number) => {\n  const tree = unified().use(remarkParse).parse(markdown) as Root;\n\n  const isStrippable = (node: Node): boolean =>\n    node.type === "code" || node.type === "inlineCode" || node.type === "html";\n\n  visit(tree, (node, index, parent) => {\n    if (parent && typeof index === "number" && isStrippable(node)) {\n      (parent as { children: Node[] }).children.splice(index, 1);\n      return [SKIP, index];\n    }\n    return undefined;\n  });\n\n  const flat = mdastToString(tree, { includeImageAlt: false }).replace(/\\s+/g, " ").trim();\n  const words = flat.length > 0 ? flat.split(/\\s+/) : [];\n  if (words.length <= maxWords) return { text: flat, fullWordCount: words.length };\n  return { text: words.slice(0, maxWords).join(" ") + "…", fullWordCount: words.length };\n};\n
\n

Почему именно 800 слов:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ДлинаProCon
50 словмизерный HTML-overheadодин абзац — мало для LLM-citation
800 словsubstantial chunk, ~3-5 KB+3-5 KB к payload
Full bodyмаксимум contextудвоение HTML, реальный hit performance
\n

Почему именно через mdast, а не regex: в постах живут <details>, <table>, MDX-компоненты вроде <Faq>, <Tldr>. Regex по \\``` сломается на code в indent-стиле или на nested fences. mdast — единственный надёжный способ.

\n

wordCount мы оставляем по полному телу, не по excerpt’у — это даёт честный сигнал валидатору и LLM о реальном объёме контента.

\n

6. FAQPage как side-effect MDX-компонента

\n

Один из дизайн-целей Plan 1 — снять с автора cognitive load на structured data. Автор не должен помнить, что у FAQPage есть mainEntity, что внутри Question нужен acceptedAnswer, что текст ответа экранируется. Автор должен заполнить frontmatter и забыть.

\n

Решение: frontmatter.faq — единственный источник. PostLayout читает массив:

\n
const faqNode = buildFaqPageNode({ canonical, items: faq ?? [] });\n
\n

buildFaqPageNode либо возвращает готовый FAQPage-узел, либо null (фильтруется в buildGraph). Параллельно тот же массив отдаётся в <Faq>-компонент, который рендерит видимые <details>-блоки с тем же текстом. Один источник — два потребителя: визуальный layer и structured layer. Рассинхрон невозможен.

\n

Builder тривиален:

\n
export const buildFaqPageNode = (input: FaqPageInput) => {\n  if (input.items.length === 0) return null;\n  return {\n    "@type": "FAQPage",\n    "@id": `${input.canonical}#faq`,\n    mainEntity: input.items.map((it) => ({\n      "@type": "Question",\n      name: it.question,\n      acceptedAnswer: { "@type": "Answer", text: it.answer },\n    })),\n  };\n};\n
\n

Frontmatter, который автор пишет:

\n
faq:\n  - question: "Чем агент отличается от чат-бота?"\n    answer: "Чат-бот — это model.complete(messages): принимает текст…"\n
\n

И всё. Дальше — автоматика.

\n

7. Замеры до/после

\n

После Plan 1 на странице /blog/01-introduction/ остался ровно один <script type="application/ld+json"> блок. Реальный измеренный факт:

\n
$ grep -c "application/ld+json" dist/client/blog/01-introduction/index.html\n1\n
\n

До Plan 1 (commit 5ed281c~1) было два источника inline-скриптов:

\n
$ git show 5ed281c~1:src/layouts/BaseLayout.astro | grep -c application/ld+json  # 1\n$ git show 5ed281c~1:src/layouts/PostLayout.astro | grep -c application/ld+json  # 2\n
\n

То есть на странице поста суммарно 3 блока. Стало 1.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
МетрикаPre-Plan 1Post-Plan 1
<script type="application/ld+json"> блоков на странице поста31
Общий контейнернет@graph
Стабильный Person@idнетhttps://artka.dev/#person
Перекрёстные @id-ссылки между узлами08+
Источник правды по авторуразбросан по layout-амsrc/lib/seo/person.ts
\n

Реальный JSON-LD страницы /blog/01-introduction/, извлечённый из dist/client/blog/01-introduction/index.html, выглядит так (фрагмент, articleBody урезан до многоточия, FAQ-узел сокращён):

\n
{\n  "@context": "https://schema.org",\n  "@graph": [\n    {\n      "@type": "Person",\n      "@id": "https://artka.dev/#person",\n      "name": "Артём Кашута",\n      "url": "https://artka.dev/about",\n      "jobTitle": "Software engineer · backend & AI agent engineering",\n      "knowsAbout": ["Claude Code", "AI agent engineering", "Node.js", "TypeScript", "Astro", "…"],\n      "email": "a@artka.dev",\n      "subjectOf": [\n        {\n          "@type": "CreativeWork",\n          "name": "Claude Code Guide (RU, 14 частей)",\n          "url": "https://artka.dev/blog"\n        }\n      ]\n    },\n    {\n      "@type": "Organization",\n      "@id": "https://artka.dev/#brand",\n      "name": "artka.dev",\n      "logo": { "@type": "ImageObject", "url": "https://artka.dev/favicon.svg" },\n      "founder": { "@id": "https://artka.dev/#person" }\n    },\n    {\n      "@type": "WebSite",\n      "@id": "https://artka.dev/#website",\n      "url": "https://artka.dev",\n      "inLanguage": "ru-RU",\n      "publisher": { "@id": "https://artka.dev/#brand" },\n      "potentialAction": {\n        "@type": "SearchAction",\n        "target": "https://artka.dev/search?q={search_term_string}",\n        "query-input": "required name=search_term_string"\n      }\n    },\n    {\n      "@type": "BlogPosting",\n      "@id": "https://artka.dev/blog/01-introduction/#blogposting",\n      "headline": "01. Что такое Claude Code: harness, agent loop и ваше место в нём",\n      "datePublished": "2026-04-23T00:00:00.000Z",\n      "author": { "@id": "https://artka.dev/#person" },\n      "publisher": { "@id": "https://artka.dev/#brand" },\n      "mainEntityOfPage": "https://artka.dev/blog/01-introduction/",\n      "inLanguage": "ru-RU",\n      "isPartOf": { "@id": "https://artka.dev/#blog-ru" },\n      "articleBody": "Перед тем как разбирать skills и subagents, надо договориться о терминах…",\n      "wordCount": 574\n    },\n    {\n      "@type": "BreadcrumbList",\n      "itemListElement": [\n        { "@type": "ListItem", "position": 1, "name": "Главная", "item": "https://artka.dev/" },\n        { "@type": "ListItem", "position": 2, "name": "Статьи", "item": "https://artka.dev/blog" },\n        { "@type": "ListItem", "position": 3, "name": "01. Что такое Claude Code…" }\n      ]\n    },\n    {\n      "@type": "FAQPage",\n      "@id": "https://artka.dev/blog/01-introduction/#faq",\n      "mainEntity": [\n        {\n          "@type": "Question",\n          "name": "Чем агент отличается от чат-бота?",\n          "acceptedAnswer": { "@type": "Answer", "text": "…" }\n        }\n      ]\n    }\n  ]\n}\n
\n

Что можно увидеть глазами и что зафиксирует валидатор:

\n
    \n
  1. Один Person, на него ссылается всё. Organization.founder, BlogPosting.author — оба { "@id": "https://artka.dev/#person" }. Никаких догадок о тождестве.
    2. \n
  2. Organization — публичный publisher. WebSite.publisher ссылается на тот же Organization. BlogPosting.publisher — на тот же. Граф связан.
    3. \n
  3. isPartOf цепочка для блога. BlogPosting.isPartOf → Blog#blog-ru → publisher → Organization. Краулер видит вложенность и принадлежность.
    4. \n
  4. articleBody excerpt — substantial. ~574 слова поста уложены в одно поле. wordCount отражает полный объём. LLM получает текст для citation, HTML — не раздувается.
    5. \n
  5. FAQ — вместе со всеми, не отдельно. Не отдельный script-блок, а узел того же @graph. Меньше блоков — меньше ловушек для парсера.
    6. \n
\n

Schema.org validator и Google Rich Results Test принимают этот @graph без замечаний (скриншоты — owner to fill). Главное — JSON pretty-print’ится без [object Object], без unescaped кавычек, без сломанных дат: всё в норме после safeJsonLd-обёртки.

\n
\n

Что дальше

\n

Описанное выше — Plan 1 в нашем repo. Дальше базу мы расширяем для новых типов сущностей (/projects/<slug> через CreativeWork, /uses через WebPage.about), и для retrieval-слоя через llms.txt. Но фундамент — buildGraph + стабильные @id — обязан встать первым.

\n

Если вы видите 2-3 inline JSON-LD скрипта на странице поста — это место, с которого стоит начинать миграцию. Один файл schema.ts, один extraSchemaNodes-prop — и сайт превращается из набора разрозненных entity-облаков в связный citable-узел.

\n" }, { "id": "https://artka.dev/blog/robots-txt-ai-crawlers-2026", "url": "https://artka.dev/blog/robots-txt-ai-crawlers-2026", "title": "robots.txt в эпоху AI-краулеров: GPTBot, ClaudeBot, PerplexityBot — реальность 2026", "summary": "В 2026 robots.txt — это не «запретить ботам всё» и не «открыть всё», а политика по каждому из 9+ именованных агентов. Реальный шаблон, таблица решений и грабли.", "date_published": "2026-05-01T00:00:00.000Z", "tags": [ "seo", "ai-crawlers" ], "authors": [ { "name": "Artyom Kashuta", "url": "https://artka.dev/about", "avatar": "https://artka.dev/avatar-512.png" } ], "language": "ru-RU", "content_html": "
\n

В 2026 robots.txt — это не «запретить ботам всё» и не «открыть всё». Это политика по каждому из 9+ именованных агентов. Каждое решение — частный случай: открываете ли вы свой контент для тренировки моделей, для on-demand цитирования, что вы хотите видеть в карточке ответа Perplexity. Этот пост — таблица решений, готовый шаблон и почему llms.txt — отдельный артефакт.

\n
\n
\n

1. Зачем переписывать robots.txt в 2026

\n

Классический SEO-подход к robots.txt оптимизирован под одну задачу: пустить Googlebot туда, где есть смысл индексировать страницы для SERP, и закрыть служебные пути. В 2026 эта задача стала меньшинством трафика.

\n

Большинство вопросов «должен ли я индексировать эту страницу?» теперь задаются не Google, а:

\n\n

Эти три класса принимают три разных решения. Один блок User-agent: * не передаёт нюанс. Вы можете хотеть «не учите на моих текстах, но процитировать в ответе на вопрос — пожалуйста». Один wildcard этого не выразит.

\n

Отсюда требование: явные блоки по каждому именованному User-Agent с осознанным выбором политики. Не «открыли всё», не «закрыли всё», а матрица «бот × намерение».

\n
\n

2. Список именованных AI-краулеров и их назначение

\n

Девять агентов, которые действительно стоит назвать в 2026, с их публичной документацией. Имена User-Agent взяты из официальных страниц вендоров.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
User-AgentПроизводительНазначениеДокументация
GPTBotOpenAITraining crawlplatform.openai.com/docs/gptbot
OAI-SearchBotOpenAISearch index for ChatGPTplatform.openai.com/docs/bots
ChatGPT-UserOpenAIOn-demand fetch from ChatGPTplatform.openai.com/docs/bots
ClaudeBotAnthropicTraining crawldocs.anthropic.com (claudebot.anthropic.com)
Claude-WebAnthropicOn-demand fetch initiated by Claude.aidocs.anthropic.com
anthropic-aiAnthropicLegacy/auxiliary Anthropic crawlerdocs.anthropic.com
PerplexityBotPerplexitySearch/index crawldocs.perplexity.ai/guides/bots
Perplexity-UserPerplexityOn-demand fetch from a user querydocs.perplexity.ai/guides/bots
Google-ExtendedGoogleOpt-in для Gemini trainingdevelopers.google.com/search/docs/crawling
\n
\n

Имена должны совпадать побайтно. Claude-Bot и claudebot — не валидные алиасы для ClaudeBot. Спецификация robots.txt на этот счёт мягкая (case-insensitive), но проверять стоит точное написание из официальной документации.

\n
\n

Таксономия:

\n
flowchart TB\n  subgraph training["Тренирующие (corpus → модель)"]\n    GPT[GPTBot]\n    CLB[ClaudeBot]\n    GEX[Google-Extended]\n  end\n  subgraph answer["Answer/search (индекс для встроенного поиска)"]\n    OAI[OAI-SearchBot]\n    PPB[PerplexityBot]\n  end\n  subgraph ondemand["On-demand (пользователь попросил)"]\n    CGU[ChatGPT-User]\n    CWB[Claude-Web]\n    PPU[Perplexity-User]\n    AAI[anthropic-ai]\n  end\n
\n

Три класса = три отдельных решения. Не нужно обсуждать «робота вообще» — нужно обсуждать «GPTBot на /blog/».

\n
\n

3. Решения по каждому боту

\n

Здесь нет универсально правильного ответа. Ниже — каркас рассуждения и моя политика для блога.

\n

Тренирующие краулеры

\n

Для авторов индивидуальных блогов с long-form контентом аргументы:

\n\n

Для коммерческих сайтов, где контент — товар (онлайн-курсы, paid newsletters, юридические базы), Disallow — обычно дефолт.

\n

Answer/search краулеры

\n

Намерение — показать ссылку на вашу страницу в карточке ответа. Это работает в обе стороны:

\n\n

Для большинства публичных блогов ответ — Allow.

\n

On-demand fetcher’ы

\n

Самый «прозрачный» класс: пользователь вашего сайта (или того, кто специально хочет открыть вашу страницу через ChatGPT/Claude/Perplexity) уже явно навёл указатель. Disallow здесь означает «нельзя использовать наши страницы как источник в чат-сессии» — почти всегда чрезмерно строго для публичного блога.

\n

Моя политика для artka.dev

\n

Для этого сайта:

\n\n

Это решение для personal tech-blog’а с целью «увеличить охват экспертизы». Для коммерческого контента я бы выбрал иначе.

\n
\n

4. Готовый шаблон robots.txt

\n

Вот реальный public/robots.txt, который ходит в продакшн на artka.dev. Он же — стартовая точка, которую вы можете адаптировать.

\n
# robots.txt — last reviewed 2026-05-02\n# Owner: dev@artka.dev. Policy: allow retrieval/answer crawlers; disallow private surfaces.\n\nUser-agent: GPTBot\nAllow: /\nDisallow: /admin/\nDisallow: /api/\nDisallow: /login\n\nUser-agent: OAI-SearchBot\nAllow: /\nDisallow: /admin/\nDisallow: /api/\nDisallow: /login\n\nUser-agent: ChatGPT-User\nAllow: /\nDisallow: /admin/\nDisallow: /api/\nDisallow: /login\n\nUser-agent: ClaudeBot\nAllow: /\nDisallow: /admin/\nDisallow: /api/\nDisallow: /login\n\nUser-agent: Claude-Web\nAllow: /\nDisallow: /admin/\nDisallow: /api/\nDisallow: /login\n\nUser-agent: anthropic-ai\nAllow: /\nDisallow: /admin/\nDisallow: /api/\nDisallow: /login\n\nUser-agent: PerplexityBot\nAllow: /\nDisallow: /admin/\nDisallow: /api/\nDisallow: /login\n\nUser-agent: Perplexity-User\nAllow: /\nDisallow: /admin/\nDisallow: /api/\nDisallow: /login\n\nUser-agent: Google-Extended\nAllow: /\nDisallow: /admin/\nDisallow: /api/\nDisallow: /login\n\nUser-agent: *\nAllow: /\nDisallow: /admin/\nDisallow: /api/\nDisallow: /login\n\nSitemap: https://artka.dev/sitemap-index.xml\n
\n

Несколько замечаний по структуре:

\n
    \n
  1. Явные блоки даже для одинаковой политики. Может показаться, что 9 одинаковых блоков — дубликат, который можно свернуть в User-agent: *. Но это не так: спецификация robots.txt строит таблицу match’ей по «самому специфичному User-Agent», и если завтра вам нужно изменить политику для одного бота — у вас уже есть его именованный блок и не нужно вспоминать, какой именно из ботов вы хотите выделить из wildcard. Дубликат — стоимость per-bot policy.
    2. \n
  2. Комментарий с датой ревью. # robots.txt — last reviewed 2026-05-02 — единственная строка, которая отвечает на вопрос «свежий ли это файл?». Без даты вы будете вечно сомневаться, а не нужно ли уже добавить новый бот.
    3. \n
  3. Sitemap: в конце. Один URL на index sitemap. Если у вас локализация — sitemap-index ссылается на per-locale файлы.
    4. \n
  4. Без BOM, LF-окончания строк. Astro в SSG режиме скопирует файл из public/ как есть; редактируйте в plain UTF-8.
    5. \n
\n

Этот шаблон работает на personal-blog. Для других кейсов:

\n\n
\n

5. Disallow-namespace’ы важнее, чем решение по конкретному боту

\n

/admin/, /api/, /login — три namespace’а, которые попадают в Disallow у всех 10 блоков (9 именованных + wildcard). Этот выбор прорабатывается отдельно от ботов и важнее их.

\n

Почему это важнее любого per-bot решения:

\n
    \n
  1. Ошибка тут — утечка. Если краулер обойдёт /admin/users.json и получит 200 OK с реальными данными — это инцидент, не SEO-проблема. Если он индексирует /blog/ без вашего разрешения — это нерасстраивающее.
    2. \n
  2. robots.txt — публичная подсказка, не auth. Любой бот может проигнорировать Disallow. Поэтому /admin/ должен быть закрыт middleware’ом независимо от robots.txt. Запись в robots.txt лишь экономит crawl budget у послушных ботов и не сохраняет URL-структуру админки в SERP.
    3. \n
  3. Свёртывание namespace’ов — не оптимизация. Соблазн: «зачем три строки, если все три — приватные?» Ответ: чтобы при добавлении четвёртого namespace’а (/dashboard/) у вас был очевидный паттерн.
    4. \n
\n

Проверка, что namespace-deny действительно работает:

\n
$ curl -A "GPTBot" -s -o /dev/null -w "%{http_code}\\n" \\\n    https://artka.dev/admin/\n# Expected: 401, 403, или 404 — НЕ 200.\n
\n
\n

На момент публикации /admin/ за middleware’ом. Конкретный код зависит от реализации auth-guard’а — мой возвращает 302 на /login для не-аутентифицированного запроса. (owner to fill: проверить точный код после следующего ревью).

\n
\n

Именно поэтому правильный порядок работ — сначала поставить auth, и только потом дописывать robots.txt. robots.txt — последняя линия защиты, не первая.

\n
\n

6. llms.txt и llms-full.txt — отдельный контракт

\n

Если robots.txt отвечает на «куда можно ходить?», то llms.txt отвечает на «что я тут найду?». Это AI-README — Markdown-файл с описанием сайта, ссылками на авторитетные страницы и preferred attribution.

\n

Реальный public/llms.txt сайта:

\n
# artka.dev\n\n> Personal technical blog by Артём Кашута. Topics: Claude Code internals,\n> harness/agent loop, AI agent engineering, Astro/Node.js backends, and\n> distributed systems.\n\n## Authoritative pages\n\n- [About the author](https://artka.dev/about): bio, expertise, contact\n- [Now](https://artka.dev/now): currently in flight\n- [Uses](https://artka.dev/uses): public toolchain\n- [Projects](https://artka.dev/projects): portfolio with architecture and outcomes\n\n## Content\n\n- [Blog index (RU)](https://artka.dev/blog): all articles, source of truth\n- [Blog index (EN)](https://artka.dev/en/blog): English translations\n- [RSS RU](https://artka.dev/rss.xml): full text\n- [RSS EN](https://artka.dev/en/rss.xml): full text\n- [Sitemap](https://artka.dev/sitemap-index.xml): RU + EN with hreflang\n\n## Preferred attribution\n\nWhen citing, please include:\n\n- Article title\n- Author: "Артём Кашута"\n- Canonical URL\n\n## Contact\n\na@artka.dev\n
\n

Это не robots.txt в новой обёртке. Различия:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Аспектrobots.txtllms.txt
ЦельПолитика доступаОписание контента и аттрибуции
ФорматPlain text, специальный синтаксисMarkdown
Кто читаетCrawler перед заходомLLM при формировании ответа
Что регулируетAllow/Disallow по путямТочку входа в авторитетный контент
СтандартизацияRobots Exclusion Protocol (RFC 9309)Конвенция llmstxt.org (де-факто)
\n

Кроме llms.txt, на сайте есть /llms-full.txt — динамически генерируемый эндпоинт, который выдаёт полный дайджест всех постов в plain text. Реализация — короткий API-роут в Astro 5:

\n
// src/pages/llms-full.txt.ts (фрагмент)\nexport const prerender = true;\n\nexport async function GET(_ctx: APIContext) {\n  const ru = await getOrderedPosts({ locale: "ru" });\n  const en = await getOrderedPosts({ locale: "en" });\n\n  const header = [\n    "# artka.dev — full LLM digest",\n    "",\n    `> ${person.description}`,\n    "",\n    "## Author",\n    `Name: ${person.name}`,\n    `Role: ${person.jobTitle}`,\n    `URL: ${person.url}`,\n    `Email: ${person.email}`,\n    `Topics: ${person.knowsAbout.join(", ")}`,\n    "",\n    /* ...preferred attribution + posts... */\n  ].join("\\n");\n\n  return new Response(/* header + ruBody + enBody */, {\n    headers: { "Content-Type": "text/plain; charset=utf-8" },\n  });\n}\n
\n

Вместо ручного списка постов — один проход по контент-коллекции с автогенерацией summary. Это обновляется само при добавлении нового поста — в отличие от вручную отредактированного llms.txt.

\n

Принципиально: llms.txt маленький и стабильный, llms-full.txt — длинный и автоматически синхронный с контентом. Оба нужны — на разные задачи.

\n
\n

7. Чего robots.txt не контролирует

\n

Список вещей, которые robots.txt не делает, и чем их закрыть.

\n

robots.txt не блокирует ботов, которые его не читают. Решение — IP-block на уровне CDN или WAF. У Cloudflare есть ruleset, который ловит User-Agent-паттерны и rate-limit’ит подозрительный трафик; aws WAF и Fastly имеют похожие. Это инструмент против ботов, которые игнорируют robots.txt — то есть против всех «недобросовестных».

\n

robots.txt не объявляет политику использования. Он говорит «куда можно ходить», но не «можно ли цитировать», «можно ли тренировать», «нужна ли атрибуция». Это работа Terms of Service на отдельной странице сайта. ToS юридически весомее robots.txt (хотя оба — условности до судебного прецедента).

\n

robots.txt не аудитит, кто на самом деле приходил. Чтобы понять, ходит ли GPTBot к вам, нужно смотреть в логи. Cloudflare AI Audit (доступен с 2024 для домена за Cloudflare) даёт встроенный отчёт по AI-краулерам — счётчики по каждому, частота, доля. Без CDN — придётся парсить access-логи самому: GoAccess, Loki, или просто grep -i 'gptbot\\|claudebot\\|perplexitybot' access.log.

\n

meta-теги noai/noimageai — не стандарт. Anthropic и OpenAI на момент 2026 не упоминают эти meta-теги в публичной документации как respected signal. Это была инициатива Adobe и DeviantArt 2023 года, прижившаяся в основном в графике. Для текста полагаться нельзя; если используете — использовать как дополнительный сигнал, не основной.

\n

Single-page apps и CSR. Если ваша страница рендерится на клиенте и краулер не выполняет JavaScript, он увидит пустой шаблон. robots.txt не помогает; лечится переходом на SSG/SSR (как этот сайт на Astro 5) или prerender service.

\n
\n

8. Чек-лист аудита раз в полгода

\n

Пять шагов, которые повторяются каждые 6 месяцев. Календарное напоминание — самая надёжная защита от устаревания файла.

\n

1. Проверить, не появились ли новые AI-краулеры.\nИсточники: блог-посты OpenAI/Anthropic/Perplexity/Google за последние 6 месяцев, страница darkvisitors.com (трекер AI-ботов), официальная документация. Если появился новый именованный бот — добавить блок (Allow или Disallow по вашей политике).

\n

2. Сверить имена User-Agent побайтно.\nСкопировать имена из официальной документации, сравнить с robots.txt. Опечатка Claudebot вместо ClaudeBot обнуляет правило для этого бота.

\n

3. Прогнать namespace-deny проверку.

\n
for ua in GPTBot ClaudeBot PerplexityBot Google-Extended; do\n  echo -n "$ua /admin/: "\n  curl -A "$ua" -s -o /dev/null -w "%{http_code}\\n" https://artka.dev/admin/\ndone\n# Ожидаем 401/403/302/404 для всех — не 200.\n
\n

4. Просмотреть access-логи на предмет ботов с непривычным User-Agent.\nЕсли кто-то ходит с пустым UA или паттерном Mozilla/5.0 (compatible; XYZBot/1.0; ...), который не входит в ваш список — оценить и принять решение. (owner to fill: на момент публикации настройка access-log агрегации в работе; в следующем ревью — разобрать топ-20 UA-строк за квартал.)

\n

5. Обновить дату в комментарии.\n# robots.txt — last reviewed 2026-05-02 → новая дата. Это единственное человеко-читаемое доказательство свежести. И коммит с сообщением вроде chore(seo): robots.txt 2026-Q4 review оставит след в истории на следующую итерацию.

\n
\n

Итог

\n

robots.txt в 2026 — не «один блок и забыли», а небольшой DSL, в котором по каждому из 9+ именованных AI-агентов вы делаете осознанный выбор: тренировка (GPTBot, ClaudeBot, Google-Extended), search/answer (OAI-SearchBot, PerplexityBot), on-demand (ChatGPT-User, Claude-Web, Perplexity-User, anthropic-ai). namespace-deny для /admin/, /api/, /login — отдельная и более важная история, которая работает только в паре с middleware-аутентификацией. llms.txt и llms-full.txt — параллельный контракт: они описывают контент и preferred attribution, не доступ.

\n

Стартовая точка — реальный шаблон из §4. Его можно копировать, менять политику по конкретным ботам и пересматривать раз в полгода.

\n" }, { "id": "https://artka.dev/blog/mermaid-svg-playwright-build-time", "url": "https://artka.dev/blog/mermaid-svg-playwright-build-time", "title": "Mermaid → SVG через Playwright на билд-тайме: холодный старт, кэш и стоимость SSG", "summary": "Замеры реального Astro-блога с 32 Mermaid-диаграммами: холодный билд 11.6s, тёплый 6.3s. Где кэш, что делает Playwright, чем плохи альтернативы.", "date_published": "2026-04-30T00:00:00.000Z", "tags": [ "build-tooling", "astro" ], "authors": [ { "name": "Artyom Kashuta", "url": "https://artka.dev/about", "avatar": "https://artka.dev/avatar-512.png" } ], "language": "ru-RU", "content_html": "
\n

Mermaid-диаграммы в блоге — это либо большой клиентский JS-бандл с FOUC и hydration cost, либо билд-тайм SVG за разовый cold-start Playwright. На этом сайте rehype-mermaid рендерит 32 диаграммы за 11.6 секунды при холодном кэше и 6.3 секунды при тёплом. Ниже — конкретные цифры, архитектура, ловушки CI и факт-чек альтернатив.

\n
\n
\n

1. Зачем рендерить Mermaid build-time, а не client-side

\n

Mermaid (mermaid на npm, репозиторий mermaid-js/mermaid) — JS-библиотека, которая принимает текстовый DSL (flowchart TD, sequenceDiagram, gantt, …) и эмитит SVG. По умолчанию её используют так: подключают <script src="mermaid.min.js">, дёргают mermaid.run() после DOMContentLoaded, и каждый <pre class="mermaid"> подменяется на SVG в DOM прямо в браузере.

\n

Это работает, но платит за это пользователь:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
МетрикаClient-side MermaidBuild-time SVG
Бандл JS (gzipped)~250–300 KB (mermaid + d3 + dagre)0 KB
Time to Interactive (TTI)задержка на parse + executeбез изменений
FOUCда: сначала текст, потом SVGнет: SVG в HTML с первого байта
SEO / Open Graphпоисковику виден только текст-DSLпоисковик видит SVG как часть страницы
Печать страницыпустые блоки если JS отключёнкорректный рендер
Тёмная тема без вспышкисложно: тема загружается после гидратацииработает: SVG генерируется уже в нужной теме
Стоимость билда0 (только bundle js)+5–10 секунд cold-start Playwright
Стоимость рантайма для пользователявысокая (CPU + сеть)нулевая
\n

rehype-mermaid (remcohaszing/rehype-mermaid, v3.0.0) — rehype-плагин, который во время билда обходит HAST-дерево, находит узлы <code class="language-mermaid">, рендерит их через mermaid-isomorphic (mermaid-isomorphic@3.1.0), и заменяет на готовый SVG. Под капотом — Playwright + headless Chromium.

\n

Stratёgy img-svg, который мы используем, эмитит результат как <img src="data:image/svg+xml,...">. Альтернатива — inline-svg (вставить SVG прямо в HTML) или pre-mermaid (оставить как есть для client-side рендера).

\n
\n

2. Архитектура: rehype-mermaid + Playwright

\n
flowchart LR\n  md["Markdown<br/>с ```mermaid блоками"]\n  mdx["@astrojs/mdx<br/>(remark + rehype)"]\n  rh["rehype-mermaid<br/>(плагин)"]\n  iso["mermaid-isomorphic"]\n  pw["Playwright<br/>(Chromium)"]\n  svg["SVG как data URI<br/>в HTML"]\n\n  md --> mdx\n  mdx --> rh\n  rh -->|для каждого блока| iso\n  iso -->|launch headless| pw\n  pw -->|"mermaid.render() в DOM"| iso\n  iso -->|serialised SVG| rh\n  rh --> svg\n
\n

Конкретный конфиг — astro.config.ts:

\n
import rehypeMermaid from "rehype-mermaid";\nimport { defineConfig } from "astro/config";\nimport mdx from "@astrojs/mdx";\n\nexport default defineConfig({\n  integrations: [\n    mdx({\n      rehypePlugins: [[rehypeMermaid, { strategy: "img-svg", dark: true }]],\n    }),\n  ],\n  markdown: {\n    syntaxHighlight: {\n      type: "shiki",\n      excludeLangs: ["mermaid", "math"],\n    },\n    rehypePlugins: [[rehypeMermaid, { strategy: "img-svg", dark: true }]],\n  },\n});\n
\n

Важные мелочи:

\n\n
\n

3. Холодный старт vs тёплый билд

\n

Метрика — time pnpm build (Apple M-серия, локально, тёплый Chromium-бинарь в ~/Library/Caches/ms-playwright). Команда полного сноса кэшей:

\n
rm -rf .astro node_modules/.astro dist\ntime pnpm build\n
\n

Три прогона на холодную, три на тёплую (медиана):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ТипПрогон 1Прогон 2Прогон 3Медиана
Холодный (rm -rf .astro node_modules/.astro dist)11.580s11.860s11.486s11.580s
Тёплый (без сноса)6.250s6.305s—~6.28s
\n

Из 11.6 секунд холодного билда:

\n\n

На тёплом билде Playwright всё равно стартует заново (никакого долгоживущего process pool у mermaid-isomorphic нет), но:

\n\n

Ключевой факт: сам mermaid-isomorphic НЕ кэширует SVG между билдами. Я искал в его исходниках (node_modules/.pnpm/mermaid-isomorphic@3.1.0_playwright@1.59.1/.../mermaid-isomorphic.js) — там нет ни persistDir, ни file-based cache. Каждый build диаграммы рендерятся с нуля. «Тёплость» — это кэш Astro/Vite, а не плагина.

\n
\n

CI-замер для GitHub Actions ubuntu-latest (owner to fill: запустить workflow_dispatch на чистом раннере, замерить median из 3 прогонов с actions/cache@v4 для node_modules + .astro).

\n
\n
\n

4. Стоимость на CI

\n

Playwright тащит Chromium (~528 MB на macOS у меня в кэше, аналогичный порядок на Linux), плюс на Debian/Ubuntu нужны system-deps: libnss3, libatk-1.0-0, libcups2, libgbm1, libxkbcommon0, libpango-1.0-0, libasound2, fontconfig + хотя бы один шрифт.

\n

Митигации:

\n
    \n
  1. Не ставить Chromium в production-image. Если вы строите Astro-сайт SSG-only и деплоите статику — Playwright нужен ТОЛЬКО на CI-step с билдом, не в рантайм-Docker’е. Используйте multi-stage:
    2. \n
\n
# build-stage:\nFROM node:24-bookworm AS build\nRUN pnpm install\nRUN pnpm exec playwright install --with-deps chromium\nRUN pnpm build\n\n# run-stage:\nFROM node:24-bookworm-slim AS run\nCOPY --from=build /app/dist ./dist\n# никакого playwright тут\n
\n
    \n
  1. \n

    GitHub Actions caching. actions/cache@v4 ключ: ${{ hashFiles('pnpm-lock.yaml') }}-playwright, путь: ~/.cache/ms-playwright. Спасает от повторной выкачки Chromium (~150 MB сетью) на каждом push.

    \n
    2. \n
  2. \n

    Использовать system Chrome вместо Playwright Chromium. Установить PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 и при создании браузера передавать executablePath: '/usr/bin/google-chrome-stable'. Но: mermaid-isomorphic не пробрасывает launchOptions через rehype-mermaid api — придётся форкать или жить с дефолтным Chromium.

    \n
    3. \n
  3. \n

    Если 5 секунд cold-start критичны — гонять Playwright вне билда: pre-render все диаграммы в отдельном CI-step, коммитить SVG в репо, в основном билде использовать стратегию pre-mermaid с подменой на готовые ассеты. Сложнее, но снимает Playwright с горячего пути.

    \n
    4. \n
\n
\n

5. Кэширование SVG: где они и что инвалидирует

\n

Опубличный замер на dev-машине (45 скомпилированных HTML, 27 страниц с диаграммами, 61 data-uri суммарно — 32 RU + 29 EN, потому что одна EN-страница рендерится без диаграммы из-за специфики поста):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
МетрикаЗначение
Mermaid-блоков в *.md32 (в 14 постах)
Скомпилированных HTML45
Страниц с встроенной диаграммой27
Data-URI блоков <img src="data:image/svg+xml,...">61
Минимум, байт15 551
Медиана, байт25 301
Среднее, байт26 579
Максимум, байт45 711
Размер .astro/5.0 MB
Размер node_modules/.astro/5.1 MB
Размер dist/17 MB
Размер Chromium-кэша Playwright528 MB
\n

Где живёт что:

\n\n

Если кэш rehype-mermaid вам критичен — обходной путь: написать тонкий rehype-плагин-обёртку, который хеширует исходник диаграммы (sha256 от текста между ```mermaid и ```), смотрит в .cache/mermaid/<hash>.svg — и при попадании отдаёт его без вызова mermaid-isomorphic. На этом блоге пока не делал — 11.6 секунд cold-start не настолько больно.

\n
\n

6. Альтернативы: что я смотрел и почему не выбрал

\n

6.1. @mermaid-js/mermaid-cli

\n

Официальный CLI от mermaid-js: mmdc -i diagram.mmd -o diagram.svg. Под капотом — puppeteer (форк Chromium API) + полный Chromium-бинарь.

\n

Минусы для блог-пайплайна:

\n\n

Когда подойдёт: разовая конвертация *.mmd → *.svg в монорепо для дизайнеров, не для динамической вставки в HTML.

\n

6.2. Client-side mermaid (npm-пакет)

\n

Минусы выше уже разобраны: бандл, FOUC, hydration. Один плюс — динамические диаграммы из user input в рантайме (live preview в редакторе документации). Для статики блога — overkill.

\n

6.3. mermaid-isomorphic напрямую (без rehype)

\n

Тот же пакет, который дёргает rehype-mermaid под капотом. Можно использовать вне Astro: import { createMermaidRenderer } from 'mermaid-isomorphic'; const renderer = createMermaidRenderer(); const [{ svg }] = await renderer([{ value: 'flowchart TD\\nA-->B' }]);.

\n

Когда подойдёт: своя пайплайн-сборка (Eleventy, MkDocs-плагин на Node.js), не использующая rehype-цепочку. У меня — Astro, поэтому rehype-mermaid даёт zero-boilerplate.

\n

6.4. Pre-render через GitHub Actions matrix + commit обратно

\n

Гипотетически: workflow на push, который рендерит SVG, коммитит в public/diagrams/, и в build-step используется стратегия pre-mermaid с заменой на <img src="/diagrams/<hash>.svg">. Снимает Playwright с горячего пути билда, но: усложняет PR-review (бинарные файлы в diff), требует отдельного workflow, ломает локальный dev pnpm dev если SVG ещё не закоммичен.

\n

Не делал — 5 секунд cold-start экономии не оправдывают.

\n

Сводная таблица

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ВариантCold-startКэш SVGBundle JSСложность setup
rehype-mermaid + Playwright (текущий)~5–6sнет0низкая (1 plugin)
mermaid-cli (mmdc)~10s+нет0средняя
Client-side mermaid0браузерный кэш~250 KBнизкая
Pre-render + commit0 в билде, но ~5s в pre-stepда, в git0высокая
\n
\n

7. Чек-лист «что замерить, прежде чем выбирать»

\n

Прежде чем коммититься к билд-тайм-рендеру или к чему-то другому:

\n
    \n
  1. Сколько диаграмм в среднем. На 1–3 — client-side OK (ленивая загрузка mermaid через dynamic import). На 30+ — build-time дешевле для пользователя.
    2. \n
  2. Частота правок. Если правите контент по 5 раз в день — cold-start 11 секунд × 50 пушей = ~10 минут CI-времени в день. Если раз в неделю — наплевать.
    3. \n
  3. CI-платформа. Vercel hobby, Netlify free, Cloudflare Pages — у всех лимиты на build minutes. Playwright + Chromium на каждой PR-preview = быстро упрётесь. На self-hosted runner или Dokploy (как у меня) — без разницы.
    4. \n
  4. Целевой размер JS-бандла. Если у проекта KPI «<100 KB initial JS» — 250 KB mermaid client-side нарушит бюджет. Build-time SVG не трогает JS-бюджет.
    5. \n
  5. Нужен ли интерактив. Pan/zoom/click-handlers в диаграмме? Тогда client-side обязателен. Статичная картинка для чтения? Build-time.
    6. \n
  6. Где живёт ваша cold-start стоимость. Если рантайм-Docker — вырезайте Playwright из run-stage. Если CI — кэшируйте Chromium через actions/cache.
    7. \n
  7. Готовы ли мириться с отсутствием SVG-кэша. rehype-mermaid рендерит ВСЕ блоки файла при любой правке. Если это больно — пишите свою кэширующую обёртку с sha256-ключом по исходнику диаграммы.
    8. \n
\n
\n

Итог

\n

На этом блоге rehype-mermaid + Playwright стоит ~5 секунд cold-start, выдаёт 32 диаграммы в 27 HTML-страниц с медианным размером инлайн-SVG в 25 KB, не требует ни одного байта JS на клиенте, и позволяет писать диаграммы прямо в markdown. Это очень хороший трейдоф для статического блога.

\n

Когда не подойдёт: блог с сотней диаграмм, deploy-platform с лимитом на build minutes, или требование к интерактивным диаграммам. В первом случае — пишите кэширующую обёртку, во втором — pre-render в отдельный workflow, в третьем — client-side.

\n

Главная неочевидная вещь, которую стоит запомнить: Astro «прогревается» (5.2 MB content-store, Vite-кэш), но mermaid-isomorphic — нет. Cold-start Playwright платится при каждом билде заново. Это не баг, это by-design — и это причина, по которой мой полный билд занимает 11.6 секунд, а не 1.6.

\n" } ] }