Imported from askidmobile/RustASR (AGENTS.md). Install upstream with npx skills add askidmobile/RustASR. Copyright stays with the author.

AGENTS.md (RustASR)

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

Контекст репозитория

• Язык: Rust (workspace), edition = 2024, rust-version = 1.85.
• Toolchain фиксирован в rust-toolchain.toml (stable + компоненты rustfmt, clippy).
• Основные крейты:
  • crates/asr-core — базовые типы/ошибки/конфиги.
  • crates/audio — загрузка WAV, ресемплинг, mel-спектрограмма.
  • crates/aut-encoder — аудио-энкодер AuT.
  • crates/qwen3-decoder — декодер Qwen3.
  • crates/asr-pipeline — end-to-end пайплайн.
  • crates/asr-cli — CLI бинарь rustasr.
• Артефакты и данные:
  • models/ игнорируется (слишком большой для git).
  • target/, .venv/, *.wav, *.npy тоже игнорируются (см. .gitignore).
  • Cargo.lock игнорируется (*.lock), не рассчитывайте на его наличие/коммит.

Команды сборки/линтинга/тестов

Сборка

• Сборка всего workspace (debug):
  • cargo build --workspace
• Сборка конкретного крейта:
  • cargo build -p asr-pipeline
• Релизная сборка (важно для производительности):
  • cargo build --workspace --release

Форматирование

• Проверка форматирования (без изменения файлов):
  • cargo fmt --all -- --check
• Автоформатирование:
  • cargo fmt --all

Линт (clippy)

• Линт всего workspace (рекомендуемый режим для PR):
  • cargo clippy --workspace --all-targets --all-features -- -D warnings
• Линт одного крейта:
  • cargo clippy -p audio --all-targets --all-features -- -D warnings

Тесты

• Все тесты workspace:
  • cargo test --workspace
• Только один крейт:
  • cargo test -p asr-core

Запуск одного теста (самое важное)

Rust/Cargo поддерживает несколько удобных способов:

• По имени теста (unit или integration):
  • cargo test -p audio test_hann_window
• По имени теста + вывод в консоль (полезно для отладки):
  • cargo test -p asr-pipeline test_pipeline_creation -- --nocapture
• Один integration test файл (например crates/asr-pipeline/tests/transcribe.rs):
  • cargo test -p asr-pipeline --test transcribe
• Один тест внутри integration test файла:
  • cargo test -p asr-pipeline --test transcribe test_pipeline_transcribe_sine_wave -- --nocapture
• Доктесты (если добавляются):
  • cargo test -p asr-core --doc Примечание: часть интеграционных тестов пропускается, если модель не скачана (проверяется наличие models/.../model.safetensors).

Запуск CLI

• Простой smoke-test Candle/устройства:
  • cargo run -p asr-cli -- test --device cpu
  • cargo run -p asr-cli -- test --device metal
• Транскрибация WAV:
  • cargo run -p asr-cli -- transcribe --model models/qwen3-asr-0.6b --audio <path.wav> --device cpu
  • cargo run -p asr-cli -- transcribe --model models/qwen3-asr-0.6b --audio <path.wav> --device metal

Модель и вспомогательные скрипты

Модель хранится локально в models/ и не коммитится.

• Скачать модель с HuggingFace (скрипт на Python):
  • python scripts/download_model.py --model Qwen/Qwen3-ASR-0.6B --output models/qwen3-asr-0.6b В repo также есть скрипты для верификации mel-спектрограмм и сравнения с Python:
• scripts/generate_mel_reference.py
• scripts/compare_mel.py Если агент меняет mel-пайплайн, желательно обновлять/перепроверять эти артефакты локально (но не коммитить *.npy).

Правила стиля кода

Язык комментариев и документации

• Все новые комментарии/док-комменты/README-правки пишите на русском.
• Если правите существующий англоязычный комментарий, переведите его на русский, если это не ломает смысл и не раздувает diff.

Импорты

Соблюдайте стабильный порядок групп импорта:

1. std::...
2. внешние зависимости (candle_core, serde, tracing, ...)
3. внутренние крейты workspace (asr_core, audio, ...)
4. crate::... / super::...

Группы разделяйте пустой строкой. Не используйте wildcard-импорты (use foo::*) в библиотечном коде; исключение — тесты/модули, где это улучшает читаемость.

Форматирование

• Доверяйте rustfmt (конфига rustfmt.toml в repo нет, значит дефолты).
• Старайтесь не спорить с форматтером: лучше реорганизовать код (например, вынести длинные выражения в переменные).
• Для многострочных вызовов используйте висячие запятые (rustfmt сам приведет).

Типы и численные соглашения

• Аудио и mel: f32 (встречается по всему проекту), избегайте неявных f64.
• Размерности/индексы: usize.
• Токены: u32 (см. пайплайн и токенайзер).
• Пути: принимайте impl AsRef<Path> в API, храните PathBuf в структурах.

Именование

• Модули/файлы: snake_case.
• Типы/структуры/enum: CamelCase.
• Функции/методы/поля: snake_case.
• Константы: SCREAMING_SNAKE_CASE.
• Аббревиатуры: сохраняйте принятые в проекте написания (AsrPipeline, AuTConfig, Qwen3Decoder).

Ошибки и обработка ошибок

• В библиотечных крейтах предпочитайте типизированные ошибки через thiserror.
  • Базовый тип ошибок: asr_core::AsrError и asr_core::AsrResult<T>.
• anyhow::Result используйте в основном на границах приложения (CLI, биндинги, инструменты), где важнее контекст, чем строгая типизация.
• Не возвращайте голые String-ошибки из публичного API без причины.
  • Допустимо для внутренних парсеров/загрузчиков, но лучше постепенно переводить на enum ошибки.
• Избегайте unwrap()/expect() в библиотечном коде. Разрешено в тестах и в местах, где условие гарантировано инвариантом (и это явно указано в коде).
• При маппинге ошибок добавляйте контекст: какой файл/тензор/размерность/устройство.

Логирование и вывод

• Для библиотечного кода предпочитайте tracing (trace!/debug!/info!/warn!/error!).
• println!/eprintln! допустимы в CLI и тестах.
• Дебаг-вывод не должен оставаться включенным по умолчанию в hot-path (если он нужен, прячьте за фичу или tracing::debug!).

Производительность и память

• Не аллоцируйте в tight loops без необходимости (особенно в DSP/FFT/mel).
• Используйте Vec::with_capacity при известном размере.
• Избегайте лишних clone() тензоров; отдавайте предпочтение ссылкам и преобразованиям, которые реально нужны.
• Учитывайте устройство и dtype: CPU обычно F32, GPU (Metal/CUDA) может быть BF16.

Тесты

• Тесты должны быть воспроизводимыми: не зависеть от сети и больших моделей по умолчанию.
  • Если тесту нужна модель, делайте явную проверку наличия файлов и пропускайте тест с понятным сообщением.
• Для отладки используйте -- --nocapture.
• Для проверок чисел используйте допуски (abs_diff, MSE), а не строгое равенство, если есть плавающая точка.

Правила Cursor/Copilot

• В репозитории не найдено правил Cursor (.cursor/rules/ или .cursorrules) и Copilot (.github/copilot-instructions.md).
• Если такие файлы будут добавлены, их инструкции имеют приоритет, и этот документ нужно обновить.