Silvius — анализ организационных изменений по документам

Silvius помогает проверить, что произошло с подразделениями и их функциями после реорганизации. Загрузите документы «до» и «после»: приложение сопоставит структуру и обязанности и соберёт заключение с источниками для проверки сотрудником.

Что решает проект

При изменении оргструктуры аналитик вручную читает несколько редакций положений, приложений и инструкций. Переименование пункта легко принять за изменение функции; перенос ответственности между подразделениями — пропустить. Silvius собирает наблюдения в одном месте и оставляет путь от каждого существенного вывода к исходному тексту.

На входе	На выходе
Два комплекта документов: «до» и «после». Поддерживаются DOCX, PDF с текстовым слоем и XLSX.	Карта соответствий подразделений и разделов; реестр и сопоставление функций; находки о возможной потере, дублировании и конфликте интересов; ссылки на фрагменты; заключение и HTML-отчёт.

Выводы агента — гипотезы для ответственного сотрудника, а не автоматическое решение о реорганизации или юридическое заключение. В интерфейсе отдельно показаны результат проверки агента и решение человека.

Запуск

Нужны Node.js 24.14.0–24.x, npm и доступ к npm registry при первой установке. Из корня репозитория:

npm ci
npm start

Откройте http://localhost:3000. Создайте аккаунт по email и паролю (от 10 символов), затем перейдите в «Рабочее пространство». В Windows PowerShell используйте npm.cmd ci и npm.cmd start.

Сервер, сайт и API запускаются одной командой. Отдельная сборка фронтенда, Docker, Google-аккаунт и ручное создание базы данных не нужны. Не открывайте index.html как файл: авторизация и анализ работают через сервер. Остановить сервер можно сочетанием Ctrl+C; при следующем запуске достаточно npm start.

Включить реальный ИИ-анализ

Промпты ролей уже находятся в pipeline/prompts/system/. Для запросов к OpenAI добавьте серверный API-ключ:

# macOS / Linux
cp pipeline/server-config.example.cjs pipeline/server-config.local.cjs

# Windows PowerShell
Copy-Item pipeline/server-config.example.cjs pipeline/server-config.local.cjs

В первой строке созданного pipeline/server-config.local.cjs укажите сам ключ, а не ссылку на него:

const HARDCODED_OPENAI_API_KEY = "ваш_ключ_OpenAI";

Файл исключён из Git. Если он уже существует, отредактируйте его, не копируя шаблон поверх. Затем перезапустите сервер и создайте новое сравнение. Альтернатива локальному файлу — переменная окружения OPENAI_API_KEY. Модель по умолчанию и лимиты заданы в шаблоне конфига; доступ к выбранной модели зависит от вашего OpenAI API-аккаунта.

Для live-запросов включён Fast mode (serviceTier: "fast"). Он уменьшает задержку API, но стоит дороже стандартного режима; фактический tier ответа сохраняется в журнале запуска. Независимые фрагменты извлечения обрабатываются по два одновременно (extractionConcurrency: 2), а результаты сохраняются в порядке документов. Предел вывода для извлечения — extractionOutputTokens: 32000; ответ, оборванный по лимиту токенов, повторяется один раз с увеличенным пределом. Параметры меняются в локальном конфиге и применяются после перезапуска сервера.

Без ключа приложение сохраняет документы, извлекает текст и показывает diff, но смысловой анализ получает состояние «Не настроен API-ключ». Для live-запуска нужен сетевой доступ к OpenAI.

Демонстрация на материалах репозитория

1. Создайте новое сравнение, например «Внутренний аудит: редакция 8 → 9».
2. В колонку «Документы до» загрузите редакцию 8, в «Документы после» — редакцию 9.
3. Нажмите «Запустить анализ». Без ключа доступны вкладки «Документы» и «Текстовый diff».
4. При готовом анализе откройте «Заключение», «Находки», «Подразделения», «Функции» и «Полнота». Из карточки находки перейдите к исходному фрагменту и сверьте его с оригиналом.
5. Подтвердите, отклоните или исправьте нужную находку. Если заключение помечено устаревшим, нажмите «Обновить заключение». Скачайте HTML-отчёт.

Контрольная пара содержит проверяемые изменения текста: например, в пункте 9.15 формулировка «осуществляется» меняется на «может осуществляться», а в пункте 9.37 меняется указанная роль. Есть и перенумерованные пункты с прежним содержанием. Эти примеры помогают проверить, отличает ли агент смысловое изменение от простой перенумерации.

Запуск сохраняется в «Истории» и доступен после перезагрузки страницы. Если процесс остановился посреди анализа, сохранённая работа открывается со статусом «Прервано»; её можно продолжить кнопкой на странице результата.

Проверка без API-ключа

Тестовый режим позволяет пройти интерфейс и весь пайплайн без расходов на модель:

HECTRA_TEST_MODE=1 npm start

В PowerShell: $env:HECTRA_TEST_MODE='1'; npm.cmd start. При создании сравнения включите «Тестовый прогон». Тестовый режим и контрольный сценарий ниже используют синтетические ответы: проверяют связность стадий, сохранение и отображение результатов, но не точность смыслового анализа документов. Тестовый режим явно помечен в интерфейсе и экспорте.

Есть также воспроизводимый контрольный сценарий для двух DOCX из репозитория:

npm --prefix pipeline run test:control

Он проверяет извлечение, текстовый diff, прохождение стадий и учёт всех доступных блоков. Сводка и HTML-отчёт сохраняются в pipeline/test-results/control-*/; этот каталог не входит в Git. Контрольный сценарий не вызывает OpenAI.

Как устроен анализ

flowchart TD
    A[Документы «до» и «после»] --> B[Извлечение текста и координат]
    B --> C[Карта соответствий]
    C --> D[Реестр функций]
    D --> E[Сравнение и поиск пересечений]
    E --> F[Проверка выводов и полноты]
    F --> G[Заключение с источниками]
    G --> H[Решение сотрудника]

Роль агента	Реализация требований ТЗ
Routing	Связывает разделы и подразделения между комплектами, сохраняя основания; может запросить одно уточнение при существенной неоднозначности.
Extraction	Извлекает подразделения и функции с исполнителем, действием, объектом, условиями и ссылками на текст.
Comparison	Сопоставляет подразделения и функции «до» и «после», включая связи 1:1 и 1:N; сравнивает исполнителя, действие, полномочия, область и условия. Ищет возможные переносы и потери по всему доступному комплекту.
Crosscheck	Ищет возможное дублирование и конфликты ответственности внутри комплекта «после», учитывая пересечения обязанностей и разделение исполнения и контроля.
Judge	Повторно проверяет находки, источники и область покрытия; при конкретной ошибке запрашивает ограниченное исправление.
Synthesis	Составляет понятное заключение: обзор, вопросы и рекомендации только по актуальному реестру находок.

Оркестратор запускает эти роли последовательно. Результаты проверяются по JSON Schema и по существованию ссылок на блоки документа. Для источника сохраняются ID документа, версия извлечения и ID блока. Находка ведёт к исходному блоку, контексту и оригинальному файлу; в интерфейсе видны цитата и доступные координаты — пункт, страница или ячейка. Ссылки сохраняются в HTML-отчёте. Программный текстовый diff помогает увидеть редакционные изменения, а журнал покрытия отличает прочитанные и проверенные блоки от пропусков. Нулевое число непроверенных блоков не гарантирует, что модель поняла каждую функцию правильно.

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

ТЗ требует различать сохранённые, преобразованные и созданные подразделения. Прототип представляет карту групп и связей с источниками; сама связь ещё не подтверждает итоговую классификацию. Юридический факт создания или упразднения требует прямого подтверждения документом. Полноту проверки пересечений между пакетами функций нельзя предполагать по наличию стадии Crosscheck: при неполном покрытии выводы ограничены проверенными связями.

Дополнительные пункты ТЗ о сверке с внешними нормативными требованиями и сравнении с другими операторами пока не оформлены как отдельные рабочие сценарии. Они потребуют заданного корпуса источников и самостоятельных правил проверки; текущий прототип не заявляет, что проверил их автоматически.

Технологии и файлы проекта

Компонент	Где смотреть	Назначение
Сайт	frontend_silvius/	HTML, CSS, JavaScript без сборки: вход, загрузка, история, результаты.
Сервер приложения	server/	Express, SQLite (node:sqlite), сессии, авторизация, CSRF и защищённый доступ к API.
Агентный пайплайн	pipeline/server/	Парсеры DOCX/PDF/XLSX, оркестрация, OpenAI Responses API, проверки, хранение и экспорт.
Контракты и инструкции	pipeline/shared/contracts.js, pipeline/prompts/system/	Схемы результатов и системные промпты ролей.
Проверки	tests/, pipeline/tests/	Интеграционные и модульные тесты сервера и пайплайна.

Локальные аккаунты и сессии лежат в data/silvius.sqlite, исходные файлы и состояния запусков — в data/pipeline/. Каталог data/ не коммитится. Сайт подключает API по /api/hectra/: запросы требуют сессию, а изменяющие запросы — CSRF-токен; запуск и его документы доступны только владельцу. API-ключ остаётся на сервере.

Ограничения и условия использования

• Форматы: DOCX, текстовый PDF и XLSX. Сканированные страницы и изображения оргсхем не распознаются: OCR и анализ изображений не реализованы. Старые бинарные DOC/XLS, TXT и PDF без текстового слоя не дают полноценного анализа.
• Лимиты по умолчанию: до 10 файлов на каждую сторону, до 20 МиБ на файл и до 2 млн символов извлечённого текста на запуск. Изменяются в серверном конфиге.
• Параллельность: один процесс обрабатывает один активный анализ за раз. Для нескольких экземпляров с общим каталогом данных нужны отдельные очередь и координация.
• Публикация: нужны HTTPS, постоянный приватный диск, NODE_ENV=production, корректный APP_URL и SESSION_SECRET длиной от 32 символов. Локальные значения по умолчанию рассчитаны на демонстрацию.

Тесты

npm test

Команда проверяет авторизацию и изоляцию пользователей, загрузку и извлечение файлов, версии источников, diff, стадии агента, ошибки и возобновление запуска. Для проверки качества live-анализа после настройки ключа запустите контрольную пару через интерфейс и вручную проверьте значимые находки и их цитаты.

Если что-то не запускается: проверьте версию Node.js (node --version), что команды выполняются из корня репозитория и что порт 3000 свободен. При другом порте задайте согласованные PORT и APP_URL.