--- id: meta.conventions title: Конвенции — ID, связи, метаданные type: reference status: stable last_reviewed: 2026-11-15 --- # Конвенции проекта Обязательные правила для всех статей. CI (этап 1) будет проверять их автоматически. ## 1. Канонические ID ID глобально уникальны, стабильны навсегда и никогда не переиспользуются. Если статья переименована или слита с другой — старый ID сохраняется в `aliases` цели или заводится редирект. Формат слага: латиница, kebab-case (`^[a-z0-9]+(-[a-z0-9]+)*$`). | Пространство | Формат | Что идентифицирует | Пример | |---|---|---|---| | `llm.*` | `llm.` | статья LLM Handbook | `llm.kv-cache` | | `lcp.*` | `lcp.` | статья llama.cpp Handbook | `lcp.llama-server` | | `tut.*` | `tut.` | сквозной туториал | `tut.quantize` | | `g.*` | `g.` | термин глоссария | `g.kv-cache` | | `p.*` | `p.` | параметр (карточка «параметр ↔ флаг») | `p.temperature` | | `q.*` | `q.` | тип квантования GGUF | `q.q4-k-m` | | `err.*` | `err.` | симптом/ошибка для диагностики | `err.oom-gpu-load` | Имя файла статьи совпадает со слагом ID: `llm.kv-cache` → `llm/kv-cache.md`. **Правило одного термина:** короткое определение живёт только в глоссарии (`g.*`). Статья-концепт включает его переиспользованием (сниппетом), а не копирует. ## 2. Типы связей Связи типизированы и двусторонние (для `implements`, `exposes`, `diagnoses` — обратное направление обязано существовать). Фиксируются в двух местах: в матрице [CROSSMAP](../shared/crossmap/CROSSMAP.md) (машиночитаемая истина) и во frontmatter статей (для навигации по страницам). | Тип | Направление | Смысл | Пример | |---|---|---|---| | `implements` | `llm.X` → `lcp.Y` / флаги / утилиты | реализация концепта в llama.cpp | `llm.attention` → `-fa/--flash-attn` | | `exposes` | `p.X` → флаг CLI / поле API | параметр и его представление в llama.cpp | `p.temperature` → `--temp` / `temperature` | | `handles` | артефакт → формат/утилита | чем и во что превращается артефакт | safetensors → `convert_hf_to_gguf.py` → GGUF | | `diagnoses` | `err.X` → `lcp.Y` | статья, закрывающая симптом | `err.oom-gpu-load` → `lcp.diag-oom` | | `defines` | `g.X` → статья | глоссарий определяет термин, статья раскрывает | `g.kv-cache` → `llm.kv-cache` | | `related` | любые | слабая связь «рядом по теме» | — | ## 3. Метаданные статьи ```yaml --- id: llm.kv-cache # канонический ID, обязателен title: KV-кэш # человекочитаемый заголовок type: concept # concept | how-to | reference | troubleshooting | tutorial | comparison | glossary level: core # base | core | deep status: draft # draft | review | stable version: # для lcp.*: привязка к llama.cpp, напр. "b7492" или ">= b7000"; для llm.* обычно пусто aliases: [KV cache] # альтернативные написания (поиск и поповеры) related: [llm.attention] # слабые связи, ID llm_refs: [] # ссылки на статьи LLM Handbook (для lcp.*/tut.*) llama_cpp_refs: [lcp.common-flags, lcp.diag-oom] # ссылки на статьи llama.cpp (для llm.*/tut.*) parameters: [p.flash-attn] # карточки параметров, затрагиваемые статьёй artifacts: [] # артефакты/форматы (GGUF, safetensors, .gbnf, LoRA-адаптер) sources: # первоисточники: документация llama.cpp, статьи, доклады - https://... last_reviewed: 2026-11-15 # дата последней сверки с источниками --- ``` Семантика полей: - `level`: **base** — читается без подготовки; **core** — нужны соседние base-статьи; **deep** — детали/математика, можно отложить без потери нити. - `status`: **draft** — черновик; **review** — на ревью; **stable** — выверен по источникам, для `lcp.*` дополнительно сверен с версией из `version`. - `version`: числовые дефолты, поведение флагов и примеры вывода валидны только для указанной версии llama.cpp. Всё, что не сверено — помечается в тексте «⚠️ проверить». ## 4. Структура URL сайта (этап 1) `/llm//`, `/llama-cpp//`, `/tutorials//`, `/glossary/` (+ якоря `#g-slug`), `/crossmap/`. Разделы сайта зеркалят каталоги репозитория. ## 5. Правила текста - Язык — русский; общепринятые английские термины (KV cache, top-p, logits) не переводятся насильно, каноническое написание фиксирует глоссарий. - Первое упоминание термина в статье — ссылка на глоссарий (позже — поповер). - Статьи `lcp.*`, описывающие флаги, используют формат карточки: имя → что делает → дефолт (с версией) → влияние → типичная ошибка. - Примеры команд приводятся для Linux/macOS; отличия Windows — отдельной строкой. - Схемы — Mermaid, исходники в `/assets/`. ## 6. Слой данных (data-as-code) Машиночитаемые источники истины живут в `/shared/data/` и переиспользуются везде: reference-статьи рендерят из них таблицы, ассистент и калькулятор читают напрямую. | Файл | Содержимое | ID | |---|---|---| | `parameters.yaml` | карточки параметров: CLI-флаг, поле API, концепт, дефолт, диапазон | `p.*` | | `quants.yaml` | типы квантования: bits-per-weight, применение | `q.*` | | `models.yaml` (этап 4) | референс-архитектуры для `calc_memory` | — | Правила: - `default` / `range` заполняются **только после пиннинга версии llama.cpp**; ✅ выполнено: пиннинг **v1.0.0** (коммит `b1b770d`, закуплен 2026-11-15), дефолты верифицированы и публикуются с пометкой версии. - Каждое числовое значение имеет флаг `verified` (по умолчанию `false`): `false` — приближение для прикидки, `true` — сверено с зафиксированной версией и источником. - Числа не дублируются руками: статья показывает то, что отрендерено из YAML; ассистент называет числа только из YAML или из результатов инструментов. - Изменение данных = PR, как для кода; одновременно проверяется синхронность с [CROSSMAP](../shared/crossmap/CROSSMAP.md) (разделы B и C). ## 7. CI-проверки (этап 1) 1. Уникальность `id` и соответствие имени файла слагу. 2. Все `related` / `llm_refs` / `llama_cpp_refs` / `parameters` указывают на существующие ID. 3. Симметрия связей `implements` / `exposes` / `diagnoses` в CROSSMAP и frontmatter. 4. markdownlint + lychee: 0 битых внутренних ссылок. 5. Vale — стиль (словарь и правила подключим после утверждения style guide). 6. Схема и консистентность `/shared/data/*.yaml`: ID уникальны и совпадают с crossmap; дефолты публикуются только при `verified: true`. 7. Eval-набор ассистента ([assistant/SPEC](../assistant/SPEC.md)): ручной прогон на этапе 4, автоматический в CI — с этапа 5 при доступном провайдере.