# Audion Docs AI - руководство пользователя

**Содержание**

- [Запуск](#запуск)
- [Рекурсивный Pipeline](#рекурсивный-pipeline)
- [Результаты Аудита](#результаты-аудита)
- [Document TASK](#document-task)
- [Нормализация](#нормализация)
- [Providers И Ключи](#providers-и-ключи)
- [Workbench И Output](#workbench-и-output)
- [Проверка](#проверка)
- [Диагностика](#диагностика)
- [Безопасное Обслуживание](#безопасное-обслуживание)

Audion Docs AI выполняет аудит, нормализацию и преобразование наборов DOCX/PPTX через воспроизводимые локальные pipeline с необязательными AI-этапами.

## Запуск

Для обычной работы используйте GUI. Источники храните в отдельной input-папке и выбирайте отдельный output. Перед большим набором проверьте portable runtime.

GUI является операторской оболочкой над services проекта: выбирает файлы, параметры, шаблоны и provider, а документная логика остаётся в `system_core\` и одинаково работает из CLI.

## Рекурсивный Pipeline

1. Добавьте DOCX и/или PPTX.
2. Выберите target.
3. Выполните `Scan` для инвентаризации документов и объектов.
4. Постройте render map, если нужны визуальные или структурные anchors.
5. Запустите выбранный audit.
6. Просмотрите report до annotation/normalization.
7. Применяйте подтверждённые изменения только к копиям.
8. Удаляйте служебные anchors после проверки.

Нельзя переходить от выбора файлов прямо к разрушительной нормализации. Scan и audit report являются доказательством для каждого класса правок.

## Результаты Аудита

Audit может находить аномалии оформления, несогласованные стили, подозрительную пунктуацию или регистр, структурные дефекты, неподдерживаемые объекты и provider warnings. Достоверные дефекты отделяются от рекомендаций.

В отчёте сохраняются исходный текст и расположение объекта. Неопределённое содержимое не переписывается молча.

## Document TASK

Document TASK формирует структурированный результат по шаблону, точным replacements или извлечённым фактам.

- Выберите источники и утверждённый template.
- Подтвердите output format и обязательные поля.
- Для детерминированных правок используйте exact replacement.
- AI extraction применяется только там, где задача разрешает интерпретацию.
- Проверьте таблицы, headings, страницы и пропущенные значения.

Template задаёт контракт результата. Нельзя импровизировать layout или переименовывать обязательные поля без изменения спецификации задачи.

## Нормализация

Нормализация выполняется после рассмотрения audit. Типовые операции: очистка styles, пробелов и пунктуации, контролируемое восстановление регистра, удаление service anchors и исправление известных структурных дефектов.

Работайте с копиями. Сравнивайте результат визуально и структурно, храните отчёт с объяснением каждого класса изменений.

## Providers И Ключи

Ключи находятся в `config\api_key_*.txt`, не печатаются в logs и не входят в public-документацию. Provider/model выбираются по задаче. Ответ AI является входом для проверки, а не автоматической истиной.

В public-архиве ключи заменяются только во временном staging средствами релиза. Рабочие значения не меняются.

## Workbench И Output

`Source` содержит управляемый список документов, `Target` — выходную папку. `Reset` очищает выбор, `Delete` убирает выбранную запись. Поддерживаются пробелы и кириллица в путях.

Reports, annotated/normalized copies, таблицы и service maps пишутся в управляемые output/report-папки. Корень проекта не используется как workspace.

## Проверка

Перед приёмкой:

- сравните количество входных и выходных документов;
- откройте характерные DOCX/PPTX;
- проверьте таблицы, изображения, notes, колонтитулы и разрывы страниц;
- рассмотрите skipped/unsupported objects;
- подтвердите удаление временных anchors;
- убедитесь, что provider error не стал принятым содержимым;
- сохраните logs и audit report.

## Диагностика

- Пустой scan: проверьте source и extensions.
- Пропали объекты: изучите раздел unsupported в отчёте.
- Битая кириллица или цикл launcher: запустите CMD fixer и сравните FZF/fallback.
- Provider failure: проверьте key, model, сеть и retry.
- Визуальное расхождение: проверьте render map и scope нормализации.
- Locked temp: закройте старый процесс и удалите только управляемые артефакты.

## Безопасное Обслуживание

Cleanup может удалить caches, временные render maps, logs, reports и пересобираемый runtime по политике. Он сохраняет код, config, input, output, templates, keys и каноническую документацию.