--- id: meta.sources title: Источники данных и протокол ведения корпуса type: reference status: stable last_reviewed: 2026-11-15 --- # Источники данных и протокол ведения корпуса Ответ на вопрос «откуда берётся контент» — для обоих справочников, плюс правила формата хранения, при которых правка части не требует переписывания корпуса. ## 1. llama.cpp Handbook — только из официальных материалов Источники, в порядке авторитета: | Источник | Что даёт | Как попадает в репо | |---|---|---| | `docs/` официального репо (github.com/ggml-org/llama.cpp) | сборка, бэкенды, сервер, веб-UI, мультимодальность | **закупка (vendoring)** на пиннутом теге → `sources/llama-cpp/<тег>/docs/` | | `--help` утилит (`llama-cli`, `llama-server`, `llama-quantize`, `llama-bench`, …) | точные флаги, дефолты, диапазоны | captured на зафиксированной сборке (этап 3) → `sources/llama-cpp/<тег>/help/*.txt` | | `tools/*/README.md`, `examples/` | сервер API, сэмплеры, квантование | вместе с docs из того же клонa | | исходники (`arg.cpp`, `common/`) | спорные случаи: точная семантика флага | чтение при пиннинге; ссылка на файл+строку в карточке | **Правило разбора:** статья пишется по русски своими словами, но **каждый факт — из закупленного источника**; команды и имена флагов — дословно. Где источник молчит (например, дефолт не описан) — стоит пометка «⚠️ проверить на версии X», а не догадка. Прямой копипаст абзацев не допускается (кроме цитат команд/вывода — в code-блоках). **Обновление версии:** тег меняется в одном месте → скрипт перекачивает docs → diff → точечная правка статей, чьи факты изменились; `version` + `last_reviewed` в frontmatter. Скрипт: [scripts/fetch-llama-cpp-docs.sh](../scripts/fetch-llama-cpp-docs.sh). ## 2. LLM Handbook — пишет ассистент, заземлённый на канонические источники Контент генерируется ассистентом (моделью), но не «из головы в пустоту»: - каждая статья опирается на **канонические публичные источники**: перво статьи (Attention Is All You Need и наследники), тех-отчёты моделей (Llama, Qwen, Gemma…), документация llama.cpp/HF для практических деталей — список в `sources` frontmatter; - сомнительное или быстро устаревающее помечается в тексте, а не утверждается; - статьи проходят человеческое ревью (`status: review`), для `stable` — сверка источников и `last_reviewed`; - генерация корпуса — **волнами по MVP-оглавлению сразу целиком**, не «по запросу»: черновик всего корпуса → ревью → точечные правки. Так связи между статьями согласованы с первого дня. ## 3. Общий слой данных — числа из YAML, не из прозы Всё, что зависит от версии или модели (дефолты, диапазоны, bpw, размеры), живёт только в [shared/data/*.yaml](../shared/data/README.md). Статьи ссылаются на карточки, ассистент читает YAML. Числа в прозе дублировать запрещено — см. [CONVENTIONS §6](CONVENTIONS.md). ## 4. Формат хранения: атомарность и стабильные якоря Принцип: **единица правки = единица файла**. Правка одного факта не должна требовать переписывания чего-либо ещё. 1. **1 статья = 1 файл**, имя = слаг ID. Худший случай правки — переписать один файл целиком; соседние файлы не трогаются. 2. **Версионно-числовое — в YAML** (`shared/data/`): правится одна запись карточки, статьи и ассистент перечитывают. Статья вообще не содержит дефолтных чисел в прозе. 3. **Глоссарий — один каталог с фиксированными ID** (`g.*`): правится строка определения; статьи ссылаются на ID, а не на текст. 4. **Стабильные заголовки секций:** внутри статьи заголовки `##` имеют устойчивые формулировки («Как это работает», «Связь с llama.cpp», «Диагностика», …) — ссылки на якоря секций переживают правки текста. Переименование заголовка = правка всех ссылок на него (CI напомнит битыми ссылками). 5. **Связи — в crossmap + frontmatter**, не вшиты в текст: перестройка навигации не требует правки статей ([CROSSMAP](../shared/crossmap/CROSSMAP.md)). 6. **Закупленные источники — read-only**: `sources/**` не редактируется руками, только перекачкой скриптом. Наши правки — в статьях, ссылающихся на источник. 7. **Уровни изложения — не в файлах**: лёгкий/средний/профессиональный — это стили рендеринга ассистентом (сценарий A0, t=0) из единого канона; хранится одна версия каждой статьи ([SPEC, §5](../assistant/SPEC.md#уровни-изложения-a0-хранится-один-канон-стили--в-промпте)). ## 5. Протокол правок ассистентом (как я вношу изменения) - **Точечная правка** — инструментом точечной замены в одном файле; соседние файлы не перегенерируются никогда. - **Полная перезапись файла** — только при создании статьи или переделке её структуры; это локализовано одним файлом по свойству №1 из §4. - **Правка числа** — в YAML-карточке, не в статье. - **Правка термина** — в глоссарии; статьи не содержат копий определений. - **После правки** — обновить `last_reviewed` в изменённом файле; при смене версии llama.cpp — `version` и пометки «⚠️ проверить». - **Никогда:** «регенерация всего корпуса», массовые переименования без редиректов через `aliases`, правки в `sources/**`. ## 6. Чего корпус не делает - Не сочиняет дефолты флагов до capture `--help` на зафиксированной сборке. - Не цитирует блоги/форумы как первоисточник факта (только как «мнение», с пометкой). - Не хранит скриншоты вывода вместо текста: вывод — текстом в code-блоках (поиск и diff).