v8unpack-agent

Прикладной инструмент над upstream-распаковщиком v8unpack: превращает выгрузку конфигурации 1С в читаемый текстовый слой, машиночитаемую опись форм и компактный контекст для LLM.

Задача пакета — дать агенту достоверные сведения о формах и модулях без угадывания. Где данные нечитаемы, результат помечается как неполный, а не достраивается догадками.

Границы и non-goals

• Пакет не распаковывает контейнер сам: дерево выгрузки готовит upstream v8unpack, а агент работает с уже раскрытым каталогом.
• Production-адаптера одиночного Form.bin в пакете нет: реализацию распаковщика передаёт вызывающая сторона.
• Функций index_cf() и rag.rebuild() не существует; векторная индексация находится вне scope пакета.
• Пакет не подключается к живой информационной базе и не читает её данные.

Кто что решает

Установка

Основная установка из PyPI:

pip install v8unpack-agent

Исторический pre-release 0.1.0rc1 остаётся доступным в PyPI и по умолчанию не выбирается резолверами (нужен явный pin или --pre):

pip install v8unpack-agent==0.1.0rc1

Установка актуального состояния main напрямую из Git остаётся вариантом для проверки ещё не опубликованных изменений:

pip install git+https://github.com/MRDK80/v8unpack-agent.git

Установка для разработки из клона:

pip install -e ".[test]"

upstream v8unpack нужен для фактического извлечения текстов, включая поддержку внешних отчётов .erf.

Быстрый старт: CLI

Один прогон — один отчёт и один код возврата. На вход подаётся каталог уже распакованной выгрузки.

v8unpack-agent-run <корень_выгрузки> --report-path post-run.json

Аргумент --report-path обязателен, значения по умолчанию нет, а каталог-родитель должен существовать заранее.

Degraded — неуспешное завершение: неполный контекст не должен выглядеть успехом для автоматизации. Полное описание аргументов, стадий и кодов причин — в docs/runner.md, схема отчёта — в docs/run_report.md.

Быстрый старт: Python

Каноническая цепочка: обнаружение источников, распаковка по FormBinSource, обновление индекса.

from pathlib import Path

from v8unpack_agent import unpack_all_forms, update_forms_index
from v8unpack_agent.form_artifact import FormArtifact
from v8unpack_agent.form_identity import FormBinSource
from v8unpack_agent.scan_forms import scan_forms

dump_root = Path("unpacked_cf")
unpacked_root = Path("text_layer")


def unpack_one(source: FormBinSource, root: Path) -> FormArtifact:
    """Здесь вызывается реальное извлечение текстов из source.bin_path."""
    return FormArtifact.for_form(root, source.name)


scan_index = scan_forms(dump_root)
print(f"Найдено форм: {scan_index.total}")

artifacts = unpack_all_forms(dump_root, unpacked_root, unpack_one)
index = update_forms_index(dump_root, unpacked_root, artifacts)
index.save(Path("forms_index.json"))

Распаковщик получает FormBinSource и корень текстового слоя — ровно два аргумента. Существующая трёхаргументная реализация подключается только через adapt_legacy_unpacker(). Подробный разбор и отбор по form_ids — в docs/pipeline.md, готовые сценарии — в examples/README.md.

Пайплайн

Ключевые возможности

• Одноимённые формы разных владельцев не затирают друг друга: идентичность — form_id, а не имя.
• Формы без кода попадают в опись: elem-only ветка заполняет elem_json_path.
• Частичный результат всегда явный: extraction_ok=False невозможен без непустого extraction_warnings.
• Ссылочные типы реквизитов приводятся к имени объекта метаданных; неизвестный UUID остаётся Ref#<uuid> и не угадывается.
• Сервисные формы отделены от объектных, чтобы метрика покрытия не занижалась архитектурным паттерном платформы.
• Дрейф детектируется по хешам модуля и структуры, а не только по времени изменения файла.
• Сериализация индексов переносима: в файлы пишутся только относительные POSIX-пути, одинаковые на POSIX и NT.

Версии схем

Три независимые версии, которые не сравниваются друг с другом.

Публичная поверхность

Документация

Начало работы

• Текущее состояние реализации
• Процесс контрибуции
• История изменений

Пайплайн и запуск

• Контракт пайплайна и FormUnpacker
• Production runner, CLI и коды возврата
• Схема отчёта о запуске

Формы и разбор

• Структура элементов и UnindexedReason
• Классификация форм и метрика покрытия
• Сводка по форме
• Контекст для LLM
• Маршрутизация путей формы
• Структура управляемых форм
• Структура внешних обработок и отчётов
• Запросы СКД

Метаданные и индексы

• Опись форм и индекс ссылочных типов
• Реквизиты объекта из raw-секции header
• Разрешение data_path
• Общие модули
• Контроль дрейфа

Исследования

Датированные протоколы с агрегатами; выводы не переписываются задним числом.

• Доля неиндексированных форм
• Разрешение ссылочных типов
• Нессылочные типовые грани
• Кросс-конфигурационная проверка типов
• Пустые реквизиты объекта
• Структура Form.bin
• Валидация на третьей выгрузке

Примеры и политики

• Исполняемые примеры
• Политика ветвления
• Аудит документации

Известные ограничения

• Обычные (неуправляемые) формы хранят разметку в бинарном виде и частично не читаются; такие формы получают unknown и исключаются из знаменателя метрики.
• Квалификаторы реквизитов и составные типы не декодируются.
• Индекс ссылочных типов строится только для видов метаданных с доказанной ссылочной формой; остальные UUID остаются Ref#<uuid>.
• В режиме mode="external" индекс ссылочных типов не собирается.
• Распаковщики из examples/ и тестов — заглушки и не читают бинарный формат.
• Пакет ещё не опубликован в индексе пакетов (issue #149).

Тесты

pytest

Фикстуры синтетические: реальная выгрузка для прогона не требуется. Порядок работы с ветками, проверки перед PR и требования к обезличенности описаны в CONTRIBUTING.md.

Связанное

• saby-integration/v8unpack — upstream-распаковщик на Python, лицензия MIT.

Лицензия

MIT — см. LICENSE.