Make scripts better

2026-04-30 10:57:18 +03:00 · 2026-04-30 10:57:18 +03:00 · e8ad7df469
commit e8ad7df469
parent ba56147e95
12 changed files with 614 additions and 432 deletions
--- a/SKILL.md
+++ b/SKILL.md
@ -1,94 +1,129 @@
 ---
 name: meeting-report
-description: "Генерирует PDF-отчёт по аудиозаписи встречи: расшифровка, аналитический пересказ, ключевые решения и задачи. Использует faster-whisper (model small), ffmpeg, weasyprint."
+description: Generates meeting reports from audio recordings using local Whisper ASR
+version: 1.0.0
+metadata:
+  openclaw:
+    requires:
+      env:
+        - WHISPER_URL
+        - WHISPER_API_KEY
+        - HOTWORDS_PATH
+      bins:
+        - ffmpeg
+        - ffprobe
+        - pandoc
+        - python3
+        - xelatex
+    primaryEnv: WHISPER_API_KEY
+    emoji: "📝"
+    os:
+      - linux
+      - darwin
 ---

-# Навык: автоматическая генерация отчёта по аудиозаписи встречи
+# Meeting Report Skill

-## Важные ограничения (читай первым!)
- **ОБЯЗАТЕЛЬНО установи переменные окружения** перед запуском транскрипции: `MKL_SERVICE_FORCE_INTEL=1 OMP_NUM_THREADS=2`. Без этого скрипт упадёт на втором чанке с ошибкой "Intel oneMKL FATAL ERROR: Cannot load libctranslate2.so".
- **НЕ пытайся запускать `faster-whisper`** как отдельную команду без этих переменных. Это Python-библиотека, вызывается через скрипты (`local_whisper.py`, `transcribe.sh`) с правильными параметрами.
- **НЕ изобретай свои собственные команды** для транскрипции или конвертации. Всё уже реализовано в готовых bash-скриптах.
- **Единственное, что ты должен сделать** – определить папку с аудио, убедиться, что переменные окружения установлены, и выполнить один скрипт.
- **Для генерации PDF:** Если `pandoc` не работает (нет шрифтов кириллицы), используй `weasyprint` (Python пакет).
- **Все процессы более 5 минут запускай в фоне** (`nohup ... &`) — execute_code имеет таймаут 5 минут.
+## Описание / Description
+Этот навык транскрибирует аудиозаписи совещаний с помощью локально развёрнутого Whisper ASR, объединяет транскрипции из нескольких источников и создаёт структурированный отчёт о встрече в форматах Markdown и PDF.

-## Структура навыка
- `scripts/overlay.sh` — обёртка запуска с MKL переменными
- `scripts/local_whisper.py` — транскрипция аудио through faster-whisper
- `scripts/transcribe_chunked.sh` — транскрипция больших файлов (>30 мин) с разбиением на чанки
- `scripts/merge_transcriptions.py` — объединение результатов транскрипции
- `scripts/generate_pdf.py` — генерация PDF через weasyprint
- `README.md` — полная документация
- `QUICKSTART.md` — шпаргалка по быстрому запуску
+## Триггеры / Triggers
+- "meeting report", "generate report", "transcribe meeting", "audio report", "отчёт о встрече", "сформируй отчёт", "расшифруй запись"

-## Как именно запускать
+## Инструкции / Instructions

-### Шаг 0. Определи директорию встречи
-Пользователь укажет папку с аудиофайлами. По умолчанию:
-```
-/app/hermes_data/meetings/YYYY-MM-DD/
-```
-Если пользователь указал другой путь – используй его.
+### 1. Подготовка окружения / Environment setup
+Убедитесь, что установлены требуемые переменные окружения:
+- `WHISPER_URL` – URL локального Whisper сервера (например, `http://localhost:8000`)
+- `WHISPER_API_KEY` – API ключ для доступа к Whisper серверу (Bearer токен)

-### Шаг 1. Проверь наличие аудиофайлов
+### 2. Запуск генерации отчёта / Generate a report
 ```bash
-ls /app/hermes_data/meetings/2026-03-18/*.wav
+bash scripts/generate_report.sh <meeting-date-dir>
 ```

-### Шаг 2. Установи переменные окружения (КРИТИЧНО!)
+Пример:
+
 ```bash
-export MKL_SERVICE_FORCE_INTEL=1
-export OMP_NUM_THREADS=2
-```
-Или передай перед python3:
-```bash
-MKL_SERVICE_FORCE_INTEL=1 OMP_NUM_THREADS=2 python3 local_whisper.py ...
+bash scripts/generate_report.sh 2026-04-29
 ```
+Ожидаемая структура:

-### Шаг 3. Запусти транскрипцию
-Для коротких файлов (<30 мин):
-```bash
-bash scripts/overlay.sh /app/hermes_data/meetings/2026-03-18
-```
+text
+2026-04-29/
+├── *.WAV               # исходные аудиофайлы (Saramonic, Zoom H2n)
+├── transcription/      # создаётся автоматически
+├── merged.json         # объединённые сегменты
+├── merged_plain.txt    # сплошной текст для LLM
+└── report.pdf          # финальный отчёт
+3. Что делает generate_report.sh
+Обнаруживает источники – Saramonic (*.WAV), Zoom H2n (SR*XY.WAV, SR*MS.WAV)

-Для длинных файлов (>30 мин):
-```bash
-bash scripts/transcribe_chunked.sh /app/hermes_data/meetings/2026-03-18
-```
+Конвертирует в MP3 и транскрибирует через Whisper (с поддержкой hotwords)

-### Шаг 4. Создай аналитический отчёт
-После получения `transcription/merged_plain.txt`:
-1. Прочитай транскрипцию
-2. Создай `report.md` со структурой:
-   - Краткая выжимка (1-2 абзаца)
-   - Ход совещания (подробно)
-   - Ключевые решения (список)
-   - Задачи и ответственные (срок действия)
-   - Итоги и следующие шаги
+Объединяет транскрипции из нескольких источников (основной + аудитория)

-### Шаг 5. Генерация PDF
-Если pandoc недоступен:
-```bash
-python3 scripts/generate_pdf.py report.md report.pdf
-```
+Конвертирует готовый report.md в PDF с помощью pandoc и xelatex

-## Типичные ошибки
+4. Ручное использование скриптов / Manual script usage
+Транскрипция одного файла:

-| Ошибка | Причина | Решение |
-|--------|---------|---------|
-| `Intel oneMKL FATAL ERROR` | Нет переменных окружения | Добавить `MKL_SERVICE_FORCE_INTEL=1 OMP_NUM_THREADS=2` |
-| `No WAV file found` | Нет аудиофайлов | Положить WAV в папку встречи |
-| `weasyprint: command not found` | Нет пакета | `pip install weasyprint` |
-| `ffmpeg: command not found` | Нет ffmpeg | `apt-get install ffmpeg` |
+bash
+bash scripts/transcribe.sh <meeting_dir> <audio.WAV> <output_name>
+Объединение двух JSON транскрипций:

-## Время обработки
- Модель small: ~5-10 мин на 10 мин аудио
- 1 час аудио = 30-60 минут обработки
- Запускай в фоне: `nohup bash script.sh > /tmp/transcribe.log 2>&1 &`
- Следи: `tail -f /tmp/transcribe.log`
+bash
+python3 scripts/merge_transcriptions.py <primary.json> <secondary.json> <output_dir>
+Конкатенация WAV в MP3:

-## Результат
- `transcription/merged_plain.txt` — полная транскрипция
- `report.md` — аналитический отчёт Markdown
- `report.pdf` — финальный PDF документ
+bash
+bash scripts/concat_wav.sh <output.mp3> <input1.WAV> <input2.WAV> ...
+Чанковое транскрибирование (очень длинные записи):
+
+bash
+bash scripts/transcribe_chunked.sh <input.mp3> <output_name> <output_dir>
+5. Горячие слова / Hotwords
+Файл hotwords.txt содержит термины, организацию, имена и аббревиатуры, повышающие точность распознавания. Переопределяется через переменную HOTWORKS_PATH.
+
+## 6. Инструкции для агента по формированию отчёта / Agent instructions for report generation
+
+После того как скрипт `generate_report.sh` завершил транскрипцию и объединение источников, агент **обязан** самостоятельно создать файл `report.md` в директории встречи.
+
+### Требования к отчёту `report.md`
+
+- **Содержание**: детальное, информативное описание хода встречи, включая:
+  - обсуждавшиеся темы и вопросы,
+  - принятые решения и договорённости,
+  - ход встречи
+  - назначенные задачи и ответственных,
+  - ключевые выводы и следующие шаги.
+- **Стиль**: корпоративный, деловой, соответствующий IT‑компании (чётко, по делу, без разговорной речи).
+- **Формат**: Markdown с заголовками, списками, выделением важного.
+- **Запрещено**: прямые цитаты из транскрипции. Пересказывайте содержание своими словами, сохраняя все смысловые детали.
+- **Язык**: русский (основной), технические термины допустимы на английском.
+
+### Как агент должен действовать
+
+1. **Дождаться завершения работы** `generate_report.sh` (или выполнить его самостоятельно).
+2. **Прочитать содержимое** файла `merged_plain.txt` (или `merged.txt`), который лежит в папке встречи.  
+   Этот файл содержит полный текст транскрипции без таймкодов (или с ними, но для пересказа удобнее plain).
+3. **Создать (перезаписать) файл** `report.md` в директории `report`, лежащей в папке встречи, следуя указанным выше требованиям.
+4. **Сгенерировать PDF** одним из способов:
+   - **Способ А (рекомендуемый):** повторно выполнить `bash scripts/generate_report.sh <meeting-date-dir>`.  
+     Скрипт обнаружит уже существующий `report.md` и сконвертирует его в `report.pdf`.
+   - **Способ Б:** вручную выполнить команду `pandoc report.md -o report.pdf --pdf-engine=xelatex ...` (параметры см. в скрипте).
+
+### Пример запроса агента пользователю
+
+После того как транскрипция готова, агент может написать:
+
+> Транскрипция встречи завершена. Я подготовлю на её основе детальный отчёт в корпоративном стиле (без прямых цитат) и сохраню его в `report.md`, а затем сконвертирую в PDF. Подождите немного.
+
+После выполнения агент сообщает: «Отчёт сгенерирован: `/path/to/meeting/report.pdf`».
+
+Примечания / Notes
+Скрипты ожидают локальный Whisper сервер, совместимый с API OpenAI (endpoint /v1/audio/transcriptions), с аутентификацией Bearer.
+
+Для длинных сегментов рекомендуется использовать transcribe_chunked.sh. Он автоматически разбивает аудио по паузам тишины.
+
+Для PDF требуется установленный pandoc, xelatex и шрифты DejaVu.