From fa7511a36fb30ea2c06eb7a43f7e803ee17f2678 Mon Sep 17 00:00:00 2001 From: mzhoot Date: Sat, 20 Jun 2026 09:27:22 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 57 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 41 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 22da074..e4d21ab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ - +```markdown # AGENTS.md ## Правила для агентов и участников проекта КВС @@ -15,31 +15,56 @@ - Новые классы **не создавать**. Код пишется процедурно: функции принимают данные, возвращают данные. 3. **Изоляция логики важнее DRY.** - Если модуль может быть автономным — он должен быть автономным. Допустимо дублирование кода ради независимости модуля от других. Пример: `kvs_pass2_encoder_mutsize.py` содержит копии функций из `kvs_pass2_encoder_fixsize.py`, чтобы не импортировать их и оставаться полностью самостоятельным. + Если модуль может быть автономным — он должен быть автономным. Допустимо дублирование кода ради независимости модуля от других. Пример: кодировщики фиксированного и переменного размера содержат копии функций, чтобы не импортировать их и оставаться полностью самостоятельными. 4. **Русские названия везде, кроме ELF.** - Внутри компилятора — русские имена секций, директив, регистров. В ELF-файле — стандартные латинские имена (`.text`, `.data`, `.bss`). + - Внутри компилятора — русские имена секций, директив, регистров, инструкций. + - В ELF-файле — стандартные латинские имена (`.text`, `.data`, `.bss`). + - Имена файлов, переменных и функций в коде — **английские** (кроме русифицированных скриптов верхнего уровня). ### Структура проекта ``` -kvs_lexer.py — лексер (исходник → токены) -kvs_parser.py — парсер (токены → AST) -kvs_pass1.py — первый проход: генерация CSV с заглушками для неизвестных меток -kvs_pass2.py — второй проход: разрешение меток (замена заглушек на реальные адреса) -kvs_pass3.py — третий проход: подстановка констант в команды -kvs_pass4.py — четвёртый проход: перекодирование инструкций с подставленными значениями -kvs_builder.py — сборщик ELF (CSV → исполняемый файл) -kvs_data.py — общие константы и данные (регистры, инструкции, функции) -kvs_encoder.py — фасад кодировщика (реэкспорт из fixsize + mutsize) -kvs_encoder_fixsize.py — кодировщик инструкций фиксированного размера -kvs_encoder_mutsize.py — кодировщик инструкций переменного размера + диспетчер -kvs_build.py — главный сборочный скрипт (запускает все проходы по порядку) +квс_сборка.py — Главный сборочный скрипт (запускает все проходы по порядку) +квс_лексер.py — Лексер (исходник → токены) +квс_парсер.py — Парсер (токены → AST) +квс_проход1.py — Первый проход: генерация CSV с заглушками для неизвестных меток +квс_проход2.py — Второй проход: разрешение меток (замена заглушек на реальные адреса) +квс_проход3.py — Третий проход: подстановка констант в команды +квс_проход4.py — Четвёртый проход: перекодирование инструкций с подставленными значениями +квс_проход5.py — Пятый проход: генерация корректных таблиц секций для совместимости с toolchain +квс_проход6.py — Шестой проход: постобработка и сортировка CSV для визуального анализа +квс_финсбор.py — Сборщик ELF (CSV → исполняемый файл) +kvs_data.py — Общие константы и данные (регистры, инструкции, функции) +kvs_encoder.py — Фасад кодировщика (реэкспорт из fixsize + mutsize) +kvs_encoder_fixsize.py — Кодировщик инструкций фиксированного размера +kvs_encoder_mutsize.py — Кодировщик инструкций переменного размера + диспетчер ``` +### Русификация + +**Русифицированы (пользовательская часть):** +- Имена скриптов верхнего уровня: `квс_*.py` (кроме `квс_финсбор.py`, `квс_сборка.py`) +- Комментарии и документация в большинстве файлов +- Пользовательский синтаксис: инструкции, регистры, директивы + +**Остались на английском:** +- Имена файлов: `kvs_data.py`, `kvs_encoder.py`, `kvs_encoder_fixsize.py`, `kvs_encoder_mutsize.py` +- Внутренние имена переменных, констант и функций внутри этих файлов +- Технические идентификаторы в коде (ключи словарей, имена функций) + ### Стиль -- Комментарии и документация на русском. +- Комментарии и документация — на русском (в русифицированных файлах). - Имена функций — `snake_case`, осмысленные. - Размеры инструкций — явные числа, никаких `suffix`-трюков. - Каждая директива резервирования — отдельная ветка `if`, а не словарь. +- Для файлов, оставшихся на английском (`kvs_*.py`), комментарии допустимы на русском или английском — по усмотрению автора. + +### Важно + +- `kvs_build.py` переименован в `квс_сборка.py` — используйте актуальное имя. +- `kvs_builder.py` переименован в `квс_финсбор.py`. +- Все проходы (`kvs_pass*.py`) переименованы в `квс_проход*.py`. +- Кодировщики и `kvs_data.py` **не переименованы** — их имена остались на английском. +``` \ No newline at end of file