| 1 | # Русский для агента: читать запросы и писать ответы (literacy v1) |
| 2 | |
| 3 | **doc_id:** `kb-russian-literacy-agent-v1` |
| 4 | **audience:** CASA-агент (не замена школьного РКШ); слой **до** доменных KB (C#, грамматика нормы). |
| 5 | **Цель:** понимать **разные формулировки** задачи и отвечать **связным русским**, не только находить страницу по совпадению слов. |
| 6 | |
| 7 | **Связь:** норма письма — [`kb-russian-language-rules-v1.md`](kb-russian-language-rules-v1.md); C# — `kb-csharp-console-grade8-v1` (software-dotnet-csharp). |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ## 0. Педагогика: сначала читать и писать, потом C# |
| 12 | |
| 13 | - Человек в 8 классе **сначала** читает условие задачи, **потом** пишет код. Агент без слоя literacy — «слепой к учебнику по оглавлению». |
| 14 | - **Читать** = извлечь намерение: что просят (написать / объяснить / найти / исправить), объект (программа, правило, число), ограничения. |
| 15 | - **Писать** = короткий связный ответ пользователю на русском (что понял, что сделаю, откуда взял факт) — не обязательно длинный эссе. |
| 16 | - Один запрос может быть **перефразирован** — смысл тот же, слова другие; literacy-KB хранит **кластеры перефразов**. |
| 17 | - Код на C# и ключевые API — на **английском**; literacy связывает русское ТЗ с английскими якорями (`Console`, `TryParse`). |
| 18 | - Ошибка literacy: перепутать «объясни» и «напиши программу» — разные действия CEN. |
| 19 | |
| 20 | --- |
| 21 | |
| 22 | ## 1. Глаголы намерения (что просит пользователь) |
| 23 | |
| 24 | - **Напиши / сделай / создай** — просьба **сгенерировать** артефакт (код, файл, текст). |
| 25 | - **Объясни / расскажи / что такое** — просьба **объяснить** из памяти, без обязательного emit кода. |
| 26 | - **Найди / покажи / где в KB** — навигация, `open_kb`, top claims. |
| 27 | - **Исправь / почини / отладь** — есть ошибка; нужен разбор и правка. |
| 28 | - **Сравни / чем отличается** — два объекта или два правила. |
| 29 | - **Проверь / верно ли** — да/нет + краткое обоснование по claim. |
| 30 | - **Перефразируй / своими словами** — тот же смысл, другая формулировка (тест literacy). |
| 31 | - Русский **повелительный** часто без «ты»: «Напиши программу» = «Напиши ты программу». |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ## 2. Существительные задачи (объект запроса) |
| 36 | |
| 37 | - **Программа / приложение / консоль** — обычно домен **code** (C# console). |
| 38 | - **Игра** — чаще code; уточнить правила (угадай число, счёт). |
| 39 | - **Текст / абзац / письмо** — домен **grammar** / стиль. |
| 40 | - **Ошибка / баг / не компилируется** — code + §20 ошибок компилятора. |
| 41 | - **Правило / норма / запятая** — grammar KB. |
| 42 | - **Число / сумма / среднее / максимум** — уточнить: объяснение или программа. |
| 43 | |
| 44 | --- |
| 45 | |
| 46 | ## 3. Чтение: кластер «сумма двух чисел» (перефразы → один смысл) |
| 47 | |
| 48 | - Канон: **ввести два целых, вывести сумму**. |
| 49 | - Перефразы запроса (все ведут к одному intent `code.sum_two`): |
| 50 | - «сумма двух чисел» |
| 51 | - «сложи два целых» |
| 52 | - «программа складывает два числа с клавиатуры» |
| 53 | - «пользователь вводит a и b, вывести a+b» |
| 54 | - «add two integers console» |
| 55 | - Якоря для поиска в code-KB: `TryParse`, `Sum`, `два`, `ReadLine`. |
| 56 | - Не путать с **средним оценок** (там деление и цикл по N). |
| 57 | |
| 58 | --- |
| 59 | |
| 60 | ## 4. Чтение: кластер «приветствие по имени» |
| 61 | |
| 62 | - Канон: спросить **имя**, вывести **приветствие**. |
| 63 | - Перефразы: |
| 64 | - «Hello с именем» |
| 65 | - «поздороваться с пользователем» |
| 66 | - «программа спрашивает как тебя зовут» |
| 67 | - «как тебя зовут и здоровается» |
| 68 | - «hello with user name from console input» |
| 69 | - «консоль привет имя ReadLine» |
| 70 | - Якоря: `ReadLine`, `Hello`, `WriteLine`, `name`. |
| 71 | - Фраза целиком: «программа спрашивает как тебя зовут и здоровается» → `Console.Write` имя, `ReadLine`, приветствие. |
| 72 | |
| 73 | --- |
| 74 | |
| 75 | ## 5. Чтение: кластер «таблица умножения» |
| 76 | |
| 77 | - Канон: для числа **N** напечатать строки умножения на 1..10 (или одну строку в упрощённом варианте). |
| 78 | - Перефразы: |
| 79 | - «таблица умножения на семь» |
| 80 | - «выведи 7×1 7×2 …» |
| 81 | - «цикл for таблица» |
| 82 | - Якоря: `for`, `×`, `умнож`, `10`. |
| 83 | |
| 84 | --- |
| 85 | |
| 86 | ## 6. Чтение: кластер «максимум из трёх» |
| 87 | |
| 88 | - Канон: три числа → вывести **наибольшее**. |
| 89 | - Перефразы: |
| 90 | - «найди максимум среди трёх» |
| 91 | - «большее из a b c» |
| 92 | - «if сравнить три числа» |
| 93 | - «max of three numbers console» |
| 94 | - «наибольшее среди трёх введённых» |
| 95 | - Якоря: `max`, `if`, `трёх`, `трех`. |
| 96 | |
| 97 | --- |
| 98 | |
| 99 | ## 7. Чтение: кластер «угадай число» |
| 100 | |
| 101 | - Канон: загадать 1..100, цикл подсказок **больше/меньше/угадал**. |
| 102 | - Перефразы: |
| 103 | - «игра угадай число» |
| 104 | - «загадай число от 1 до 100 пока не угадают» |
| 105 | - «Random и while больше меньше» |
| 106 | - «guess the number 1 to 100» |
| 107 | - «guess number higher lower until correct» |
| 108 | - Якоря: `Random`, `secret`, `Higher`, `Lower`, `while`. |
| 109 | - Фраза: «загадай число от 1 до 100 пока не угадают» = `Random.Next(1, 101)` + цикл `while` + подсказки. |
| 110 | |
| 111 | --- |
| 112 | |
| 113 | ## 8. Чтение: кластер «меню в консоли» |
| 114 | |
| 115 | - Канон: цикл: показать пункты, `switch` или `if` по выбору, выход по 0. |
| 116 | - Перефразы: |
| 117 | - «консольное меню 1 2 3» |
| 118 | - «выбор пункта switch» |
| 119 | - «повторять пока не выйти» |
| 120 | - Якоря: `switch`, `case`, `меню`, `Choice`. |
| 121 | |
| 122 | --- |
| 123 | |
| 124 | ## 9. Чтение: кластер «счёт от 1 до N» |
| 125 | |
| 126 | - Канон: ввести **N**, напечатать 1, 2, …, N. |
| 127 | - Перефразы: |
| 128 | - «счётчик до n» |
| 129 | - «вывести все числа от 1 до введённого» |
| 130 | - «цикл for от 1 до N» |
| 131 | - «count from 1 to entered n» |
| 132 | - «введи n и выведи все числа 1..n» |
| 133 | - Якоря: `for`, `N`, `счётчик`. |
| 134 | |
| 135 | --- |
| 136 | |
| 137 | ## 10. Чтение: кластер «среднее оценок» |
| 138 | |
| 139 | - Канон: ввести количество оценок, ввести оценки, **среднее арифметическое**. |
| 140 | - Перефразы: |
| 141 | - «средний балл» |
| 142 | - «average grades» |
| 143 | - «сумма оценок делить на количество» |
| 144 | - Якоря: `avg`, `sum`, `grades`, `double`. |
| 145 | |
| 146 | --- |
| 147 | |
| 148 | ## 11. Письмо: как отвечать пользователю (кратко) |
| 149 | |
| 150 | - Начать с **что понял**: «Нужна консольная программа: сумма двух целых с ввода». |
| 151 | - Дать **опору**: сослаться на раздел KB или `concept_id` (в IDE — doc_path). |
| 152 | - Если **emit кода** ещё нет — честно: «Нашёл в памяти эталон; генерация файла — следующий шаг». |
| 153 | - Предложение — **законченное**, с подлежащим и сказуемым; не телеграф «сумма два числа try parse». |
| 154 | - Списки — с дефисом или нумерацией; в коде — отдельным блоком. |
| 155 | - Тон нейтральный, на **ты** если пользователь на «ты» (по политике сессии). |
| 156 | - Не выдумывать факты вне claims; если пусто — «в памяти нет, открой KB / sync». |
| 157 | |
| 158 | --- |
| 159 | |
| 160 | ## 12. Письмо: шаблоны ответа (чтение → ответ) |
| 161 | |
| 162 | - Объяснение: «По памяти: … (claim). Это значит, что …» |
| 163 | - Навигация: «Открой раздел … в `kb-csharp-console-grade8-v1`, §…» |
| 164 | - Перед кодом: «Сейчас соберу `Program.cs` с `TryParse` и циклом …» |
| 165 | - После ошибки компиляции: «Компилятор сообщает CS… — обычно это …; исправление: …» |
| 166 | |
| 167 | --- |
| 168 | |
| 169 | ## 13. Английский в запросах (чтение) |
| 170 | |
| 171 | - Смешанный запрос нормален: «напиши console app sum two ints». |
| 172 | - Ключевые API искать по **английским** токенам: `Console`, `ReadLine`, `static`, `void`. |
| 173 | - «write a program» = «напиши программу» → intent emit code. |
| 174 | - «fix compile error» = исправь ошибку сборки. |
| 175 | - Не требовать перевода всего KB на EN; достаточно **двуязычных якорей** в перефразах (§3–10). |
| 176 | |
| 177 | --- |
| 178 | |
| 179 | ## 14. Ловушки понимания (читать внимательно) |
| 180 | |
| 181 | - **Только** / **именно** — сужают задачу: «только for, без while». |
| 182 | - **Не** / **без** — запрет: «без массива» → не использовать `[]`. |
| 183 | - «Два числа» ≠ «список чисел» ≠ «N чисел». |
| 184 | - «Вывести» = `Console.WriteLine`, не «сохранить в файл» (если не сказано). |
| 185 | - «Самое простое» — минимальный код, один файл, без лишних классов. |
| 186 | - Вопрос «как» — чаще объяснение; «сделай» — чаще код. |
| 187 | |
| 188 | --- |
| 189 | |
| 190 | ## 15. Маршрутизация: literacy → домен |
| 191 | |
| 192 | | Сигналы в запросе | Домен | Следующий KB | |
| 193 | |-------------------|--------|----------------| |
| 194 | | программа, консоль, C#, код, игра, compile | **code** | kb-csharp-console-grade8-v1 | |
| 195 | | запятая, орфография, согласно, пароним, текст | **grammar** | kb-russian-language-rules-v1 | |
| 196 | | перефраз, своими словами, тот же смысл | **literacy** | этот документ | |
| 197 | | regex, выражение, MRE | **regex** | kb-regex-mre3-ru-chapter-map-v1 | |
| 198 | |
| 199 | - При конфликте: уточнить одним вопросом («Нужен готовый код или объяснение правила?»). |
| 200 | |
| 201 | --- |
| 202 | |
| 203 | ## 16. Метрики literacy (Exp J0) |
| 204 | |
| 205 | - **read@1** — перефраз запроса → top claim содержит якорь intent (bench `queries_paraphrase.jsonl`). |
| 206 | - **write@sketch** — ответ содержит связное пересказанное условие (ручная или LLM-оценка позже). |
| 207 | - Цель v1: read@1 ≥ **0.85** на 30 перефразах при полном sync literacy + language store. |
| 208 | - Ниже 0.7 — расширять кластеры §3–10, не добавлять C#. |
| 209 | |
| 210 | --- |
| 211 | |
| 212 | ## 17. Операционное использование |
| 213 | |
| 214 | - Store: `language-agent-lab-v0` (union с grammar + literacy). |
| 215 | - Sync: `manifests/kb-bundles-russian-literacy-v1.json`, скрипт `run_exp_j0_literacy_sync.ps1`. |
| 216 | - Перед Exp K emit: прогнать paraphrase bench; code-agent опирается на digest после literacy-маршрута (будущий P3). |
| 217 | |
| 218 | **Версия:** v1 · 2026-05-29 |
| 219 | |
| 220 | |