Chunk Advisor v1.0
Консольный инструмент подбора чанков при разработке на 1С. Итоги разработки, пользовательская документация, результаты тестирования. На основе //infostart.ru/1c/articles/2643659/
Python 3.10+ 15 чанков MIT License 22.03.202601Назначение программы
Chunk Advisor — консольное приложение на Python, которое помогает 1С-разработчикам быстро подбирать релевантные чанки (фрагменты требований к коду) и формировать качественные промпты для ИИ-инструментов.
Программа автоматизирует выбор стандартов безопасности, производительности, работы с БСП и других правил платформы 1С. Сгенерированный с её помощью промпт гарантирует, что ИИ-инструмент (ChatGPT, Claude, GitHub Copilot) будет учитывать корпоративные стандарты и лучшие практики при написании кода.
Кому полезна программа:
- 1С-разработчикам уровня Junior+ и Middle, которые регулярно используют ИИ в работе
- Техническим лидам, стандартизирующим подход к разработке в команде
- Командам, формирующим и расширяющим собственную базу стандартов кодирования
02Рекомендации по использованию
Для новых и нетиповых задач
Используйте режим подбора по описанию (пункт 1 меню). Опишите задачу свободным текстом — программа проанализирует запрос, найдёт релевантные ситуации в матрице и предложит оптимальный набор чанков. Это самый быстрый путь для задач, которые вы ещё не встречали.
Для типовых и повторяющихся задач
Создайте именованный шаблон (пункт 4 меню) с переменными вида {document_name}, {project}. При следующем применении шаблона программа запросит только значения переменных — вся остальная подготовка уже сделана.
Для обучения команды
Покажите новым разработчикам раздел «Примеры готовых промптов» (пункт 6). Семь встроенных примеров демонстрируют, какие чанки используются для характерных задач: разработки документов, интеграций, оптимизации отчётов, работы с расширениями. Это хорошая точка входа для понимания логики подбора.
Для адаптации под внутренние стандарты
Через режим администратора (python main.py --admin) добавляйте собственные чанки — например, внутренние стандарты наименования объектов, требования к архитектуре конкретного проекта или специфику конкретной конфигурации. После сохранения изменений в JSON нажмите Enter — программа перезагрузит базу без перезапуска.
При работе с ИИ-инструментами
Сформированный промпт содержит полные тексты всех выбранных чанков с требованиями, примерами правильного и неправильного кода на BSL, и раздел --- ЗАДАЧА --- с вашим контекстом. Такой промпт даёт ИИ весь необходимый контекст — вставляйте его в ChatGPT, Claude, Copilot или любой другой инструмент целиком, без дополнительной редактуры.
03Пользовательская документация
3.1 Системные требования
- Python 3.10 или выше
- Операционная система: Windows 10+, Linux (Ubuntu 20.04+), macOS 12+
- Для Linux: системный пакет
xclipилиxselдля работы буфера обмена - Дисковое пространство: ~50 МБ (включая зависимости)
3.2 Установка и запуск
# 1. Распаковать архив проекта cd chunk_advisor # 2. Создать виртуальное окружение (рекомендуется) python -m venv .venv source .venv/bin/activate # Linux / macOS .venv\Scripts\activate # Windows # 3. Установить зависимости pip install -r requirements.txt # 4. Для Linux -- установить xclip для буфера обмена sudo apt install xclip # Debian / Ubuntu # 5. Запустить программу python main.py # 6. Режим администратора (редактирование базы знаний) python main.py --admin
data/storage/chunks.json содержит полные тексты 15 чанков. Без этого файла программа запустится, но не сможет формировать промпты. Файл поставляется отдельным документом «Справочник чанков».3.3 Структура файлов
chunk_advisor/
+-- main.py # точка входа, CLI (--admin, --help)
+-- requirements.txt # зависимости проекта
+-- README.txt # краткая документация
+-- core/
| +-- models.py # Pydantic-модели: Chunk, Situation, Template...
| +-- knowledge_base.py # загрузка JSON, поиск по базе, reload()
| +-- recommender.py # подбор чанков (токенизация + скоринг)
| +-- prompt_builder.py # сборка промпта из чанков и контекста
+-- data/storage/
| +-- chunks.json # 15 чанков с полными текстами
| +-- matrix.json # матрица ситуаций (категории, keywords, chunk_ids)
| +-- examples.json # 7 примеров готовых промптов
+-- user_data/ # SQLite БД (создаются автоматически при первом запуске)
| +-- history.db # история запросов
| +-- templates.db # шаблоны пользователя
+-- ui/
| +-- console.py # весь UI (Rich: таблицы, меню, ввод/вывод)
+-- utils/
+-- text_processor.py # pymorphy3 + rapidfuzz: токенизация и скоринг
3.4 Главное меню
CHUNK ADVISOR v1.0 -- Консультант по подбору чанков ---------------------------------------------------- 1. Подобрать чанки по описанию задачи 2. Выбрать чанки по категориям 3. Посмотреть все чанки 4. Мои шаблоны 5. История запросов 6. Примеры готовых промптов 7. Выход ---------------------------------------------------- Для входа в режим администратора: python main.py --admin
3.5 Режим 1: Подбор по описанию задачи
Самый удобный режим для большинства задач. Введите описание на свободном языке — несколько строк, пустая строка завершает ввод. Программа выполняет морфологический анализ через pymorphy3, находит релевантные ситуации по взвешенному скорингу (rapidfuzz), собирает чанки из топ-3 ситуаций и гарантированно добавляет чанк 7 (Универсальный).
Опишите вашу задачу (пустая строка = завершить ввод): > Нужно создать документ Заявка на закупку с табличной частью > Документ должен проводиться и формировать движения по регистру > Анализирую запрос... Рекомендуемые чанки: ID Название Краткое описание 7 Универсальный (базовые требования) ... 5 Клиент-серверное взаимодействие ... 3 Обработка ошибок и транзакций ... 2 Сохранение отладочной информации ... Хотите изменить набор чанков? [д/н]: н Введите контекст задачи (Enter = использовать запрос как контекст): > Проект 1С УНФ 3.0. Расширение АПРО_Доработки. > Промпт сформирован! [c] скопировать в буфер [s] сохранить в файл [t] сохранить как шаблон [Enter] вернуться в меню
После любого экспорта (копирование или сохранение в файл) промпт автоматически сохраняется в историю.
Редактирование набора чанков (при ответе «д»):
Текущий набор: [7, 5, 3, 2] Команды: a 4 -- добавить чанк с ID 4 r 3 -- убрать чанк с ID 3 list -- показать все чанки для выбора ok -- подтвердить текущий набор
3.6 Режим 2: Выбор по категориям
Выберите категорию из 13 доступных, затем одну или несколько ситуаций внутри неё. Программа соберёт чанки согласно матрице и добавит универсальный чанк. Удобно, когда вы уже знаете, к какой категории относится задача.
Доступные категории: Работа с формами, Запросы и данные, Транзакции и блокировки, Обработка ошибок, Стандартизация кода, Динамические списки, Интеграции, Регистры, Производительность, Расширения конфигурации, Исключительные ситуации, Файловые операции, Тестирование и отладка.
3.7 Режим 3: Просмотр всех чанков
Постраничный список всех 15 чанков (по 10 на страницу). Введите номер чанка — откроется его полный текст со всеми требованиями и примерами кода BSL. Управление: [n] следующая страница, [p] предыдущая, [0] в меню.
3.8 Режим 4: Мои шаблоны
Шаблоны хранятся в user_data/templates.db и доступны без режима администратора. Шаблон содержит фиксированный набор чанков и шаблон контекста с переменными. При применении программа запрашивает значения переменных и подставляет их через str.format_map().
Мои шаблоны:
ID Название Чанки Использований
1 Создание документа УНФ 7, 5, 3, 2 5
2 Оптимизация отчёта 4, 11, 7 3
[номер] применить [d номер] удалить [c] создать [0] в меню
> 1
Шаблон: "Создание документа УНФ"
Чанки: [7, 5, 3, 2]
Контекст: Проект 1С УНФ {version}. Задача: создать документ "{doc_name}".
Заполните переменные:
version [3.0]: 3.0.12
doc_name: ЗаявкаНаЗакупку
Промпт сформирован!
3.9 Режим 5: История запросов
Последние 10 сгенерированных промптов из user_data/history.db. Введите номер записи — откроется полный текст промпта. Доступно копирование в буфер обмена.
3.10 Режим 6: Примеры готовых промптов
7 встроенных примеров для характерных задач 1С-разработки:
- Разработка документа (создание «Заявки на закупку» в расширении)
- Оптимизация отчёта (ускорение медленного отчёта по продажам)
- Массовая загрузка данных (10 000 строк номенклатуры из Excel)
- Отчёт с группировками (продажи по контрагентам по месяцам)
- Интеграция с маркетплейсом (выгрузка остатков на Ozon)
- Фоновая обработка документов (массовое проведение за день)
- Расширение с новым функционалом (добавление реквизита)
3.11 Режим администратора
Запуск: python main.py --admin. Пароль не требуется (инструмент для внутреннего использования).
РЕЖИМ АДМИНИСТРАТОРА -- Управление базой знаний ------------------------------------------------- 1. Редактировать чанки (открывает chunks.json) 2. Редактировать матрицу (открывает matrix.json) 3. Редактировать примеры (открывает examples.json) 4. Добавить новый чанк 5. Добавить новую ситуацию 6. Проверить целостность данных (все chunk_ids существуют, нет дублей) 7. Выход
После сохранения изменений в любом JSON-файле программа автоматически перезагружает базу знаний через knowledge_base.reload() без перезапуска. Проверка целостности (пункт 6) подтверждает, что все chunk_ids в матрице и примерах ссылаются на существующие чанки, нет дублирующихся идентификаторов.
04Отчёт о соответствии техническому заданию
Разработка велась согласно финальному ТЗ v3, утверждённому 19.03.2026. Ниже — проверка каждого функционального требования по результатам инспекции кода и тестирования.
| Требование ТЗ | Реализация | Статус |
|---|---|---|
| Хранение базы знаний (чанки, матрица, примеры) | JSON-файлы в data/storage/, загрузка и валидация через Pydantic v2 |
ВЫПОЛНЕНО |
| 15 чанков с полными текстами требований | Все 15 чанков заполнены (873–2260 символов каждый), заглушек нет | ВЫПОЛНЕНО |
| Интеллектуальный подбор чанков по запросу | pymorphy3 (лемматизация) + rapidfuzz.token_set_ratio, взвешенный скоринг: вес 3 за ключевые слова, вес 2 за нечёткое совпадение с названием ситуации | ВЫПОЛНЕНО |
| Чанк 7 (Универсальный) всегда добавляется | chunk_ids.add(7) в recommender.py + отдельный limit-fix для гарантии |
ВЫПОЛНЕНО |
| Формирование промпта с полными текстами чанков | PromptBuilder.build(): блоки === ЧАНК N: Название ===\n{full_text} + раздел --- ЗАДАЧА --- |
ВЫПОЛНЕНО |
| История запросов (SQLite, автосохранение) | HistoryManager: history.db, автосохранение после любого экспорта |
ВЫПОЛНЕНО |
| Шаблоны пользователя с переменными | TemplateManager: templates.db, подстановка {var} через format_map, счётчик usage_count |
ВЫПОЛНЕНО |
| Экспорт: буфер обмена и файл | pyperclip (с graceful fallback на вывод текста при недоступности), запись в .txt | ВЫПОЛНЕНО |
| Просмотр всех чанков постранично | Пункт 3 меню, 10 чанков на страницу, просмотр полного текста по ID | ВЫПОЛНЕНО |
| Режим администратора с перезагрузкой базы | --admin, меню из 7 пунктов, kb.reload() без перезапуска |
ВЫПОЛНЕНО |
| Проверка целостности данных | validate_integrity(): все chunk_ids существуют, нет дублей среди ID чанков и ситуаций | ВЫПОЛНЕНО |
| 7 встроенных примеров промптов | examples.json: 7 полных примеров с chunk_ids и контекстом | ВЫПОЛНЕНО |
| Покрытие тестами core/ и utils/ не менее 80% | pytest-cov: 93% для core/ и utils/ | ВЫПОЛНЕНО |
| Работа на Windows и Linux | Протестировано на Windows 11 и Ubuntu 22.04 | ВЫПОЛНЕНО |
05Результаты тестирования
5.1 Тестовые сценарии подбора чанков
Все тестовые сценарии из ТЗ (раздел 11.2) выполнены успешно. Проверка: рекомендованный набор содержит все обязательные chunk_ids.
| Запрос пользователя | Обязательные чанки | Результат |
|---|---|---|
| создать новую форму документа | 5, 7 | PASS |
| оптимизировать медленный отчёт | 4, 11 | PASS |
| интеграция с внешним API через HTTP | 9, 2, 3 | PASS |
| загрузка номенклатуры из excel | 14, 3 | PASS |
| расширение конфигурации добавить реквизит | 12, 7 | PASS |
5.2 Функциональные пользовательские сценарии
| Сценарий | Windows 11 | Ubuntu 22.04 |
|---|---|---|
| Запуск программы, отображение меню | PASS | PASS |
| Подбор по описанию + копирование в буфер | PASS | PASS |
| Подбор по описанию + сохранение в файл | PASS | PASS |
| Автосохранение истории после экспорта | PASS | PASS |
| Выбор по категориям, навигация | PASS | PASS |
| Создание, применение, удаление шаблона | PASS | PASS |
| Переменные в шаблоне подставляются корректно | PASS | PASS |
| Просмотр истории, повторное копирование | PASS | PASS |
| Примеры промптов: формирование и копирование | PASS | PASS |
| Просмотр всех чанков постранично | PASS | PASS |
| Режим администратора, проверка целостности | PASS | PASS |
| Перезагрузка базы без перезапуска | PASS | PASS |
| Буфер недоступен -- вывод текста на экран | PASS | PASS |
5.3 Покрытие кода тестами
Измерение выполнено через pytest-cov. Порог ТЗ: 80% для core/ и utils/.
| Модуль | Покрытие | Порог ТЗ | Статус |
|---|---|---|---|
| core/models.py | 97% | 80% | PASS |
| core/knowledge_base.py | 91% | 80% | PASS |
| core/recommender.py | 95% | 80% | PASS |
| core/prompt_builder.py | 100% | 80% | PASS |
| utils/text_processor.py | 88% | 80% | PASS |
| ИТОГО core/ + utils/ | 93% | 80% | PASS (+13%) |
06Выявленные баги и внесённые исправления
В ходе инспекции кода (code review) и тестирования были выявлены и исправлены следующие проблемы.
Баг 1 — Невозможность выйти из выбора категорий
Файл: ui/console.py, функция ask_choice()
Суть: функция принимала только диапазон 1..N и зацикливалась при любом другом вводе. Ввести 0 для выхода было невозможно, проверка if cat_idx < 0 в main.py никогда не выполнялась.
Исправление: добавлена явная обработка ввода «0» с возвратом -1 как сигнала выхода.
Баг 2 — История не сохранялась при экспорте в файл
Файл: main.py, функция mode_advise()
Суть: history.save() вызывался только внутри блока копирования в буфер. Если пользователь выбирал «сохранить в файл» без копирования — запись в историю не создавалась.
Исправление: введён флаг exported, история сохраняется после любого успешного экспорта.
Баг 3 — Обрезка top_k могла исключить чанк 7
Файл: core/recommender.py
Суть: после сортировки по ID список обрезался result[:top_k]. При большом наборе чанков (ID > 7) чанк 7 мог оказаться за пределами лимита, несмотря на гарантию его присутствия.
Исправление: чанк 7 добавляется уже после обрезки — гарантия соблюдается всегда.
Баг 4 — Режим администратора не вызывал reload()
Файл: main.py, функция run_admin_mode()
Суть: пункты меню 1–5 выводили только подсказку «откройте файл в редакторе» и не вызывали kb.reload(). Изменения в JSON не применялись без перезапуска программы.
Исправление: после каждой подсказки добавлен input() (ожидание сохранения пользователем) и вызов kb.reload().
Прочие замечания (исправлены)
- Удалены неиспользуемые импорты в
ui/console.py: KnowledgeBase, Recommender, PromptBuilder, HistoryManager, TemplateManager - Удалён
import uuidвcore/models.py— пакет импортировался, но нигде не использовался - Исправлена опечатка в UI: «завершить ввода» → «завершить ввод»
- Матрица ситуаций расширена с 5 до 13 категорий — теперь охватывает все 15 чанков
07Лицензия MIT
Программа распространяется на условиях лицензии MIT. Вы вправе свободно использовать, копировать, изменять, объединять, публиковать, распространять, сублицензировать и продавать копии программы при условии сохранения уведомления об авторских правах и текста лицензии во всех копиях.
MIT License Copyright (c) 2026 Chunk Advisor Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Коммерческое использование разрешено. Требование одно: сохранять уведомление об авторских правах во всех копиях и производных работах.
Автор: Сергей Космачев (ksnik)
Статус: финальная версия, готова к производственному использованию
Вступайте в нашу телеграмм-группу Инфостарт