From b302e3dbb2fcfefd595c353df81383c0d4d415ec Mon Sep 17 00:00:00 2001 From: Dmitriy Dementiev Date: Tue, 11 Aug 2026 09:44:50 +0300 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=D0=B0=20=D0=BA=D0=BE=D0=BD=D1=84=D0=B8=D0=B3?= =?UTF-8?q?=D1=83=D1=80=D0=B0=D1=86=D0=B8=D1=8F=20=D0=B8=D0=BD=D0=B6=D0=B5?= =?UTF-8?q?=D0=BD=D0=B5=D1=80=D0=BD=D1=8B=D1=85=20=D0=BD=D0=B0=D0=B2=D1=8B?= =?UTF-8?q?=D0=BA=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - инженерным навыкам нужна единая конфигурация трекера задач и доменных документов. - Что: - задокументированы Gitea workflow через tea и стандартные triage-метки. - добавлены доменный словарь и правила работы с ADR, research и specs. - Проверка: - git diff --cached --check. - tea --version: 0.15.1. --- AGENTS.md | 13 +++++++ CONTEXT.md | 33 ++++++++++++++++++ docs/agents/domain.md | 47 +++++++++++++++++++++++++ docs/agents/issue-tracker.md | 66 ++++++++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 15 ++++++++ 5 files changed, 174 insertions(+) create mode 100644 CONTEXT.md create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md diff --git a/AGENTS.md b/AGENTS.md index b162c49..bf76428 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,3 +75,16 @@ All tests mock backends — no real model downloads or transcription. Key test p - `docs/gpu.md` — GPU benchmarks, platform compatibility details - `docs/adr/` — architecture decision records (CUDA bootstrap, batch mode, pluggable backends, compute-type defaults, ONNX-ASR evaluation) +## Agent skills + +### Issue tracker + +Задачи ведутся в Gitea через `tea`; GitHub используется только как зеркало, внешние PR не входят в triage. См. `docs/agents/issue-tracker.md`. + +### Triage labels + +Используются стандартные пять triage-меток. См. `docs/agents/triage-labels.md`. + +### Domain docs + +Репозиторий использует single-context layout. См. `docs/agents/domain.md`. diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..d934c50 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,33 @@ +# Локальная транскрипция + +Контекст описывает язык проекта для локального распознавания аудио и видео и оценки моделей распознавания. + +## Language + +**Движок распознавания**: +Программная среда, которая загружает и исполняет модели распознавания. Обновление движка само по себе не означает изменение выбранной модели или рекомендаций пользователю. +_Avoid_: Модель, ASR-модель + +**Кандидатная модель**: +Модель распознавания, проходящая сравнительную оценку до включения в поддерживаемый каталог или рекомендации проекта. В текущей работе кандидатные модели — GigaAM Multilingual CTC, GigaAM v3 E2E CTC и GigaAM v3 E2E RNN-T. +_Avoid_: Новая модель, новый дефолт + +**Сравнительная оценка**: +Эксперимент, который сопоставляет кандидатную модель с существующими моделями на репрезентативных записях и собирает данные для отдельного решения о дальнейшем использовании. +_Avoid_: Внедрение, смена дефолта + +**Контрольная модель**: +Существующая модель, относительно которой оцениваются качество и скорость кандидатных моделей. В текущем эксперименте основная контрольная модель — OpenVINO Whisper medium. +_Avoid_: Старая модель, текущая модель + +**Поддерживаемая модель**: +Модель, которую пользователь может выбрать явно и для которой проект обеспечивает работоспособный путь транскрипции. Этот статус не означает автоматический выбор или рекомендацию для большинства пользователей. +_Avoid_: Доступная модель, дефолт + +**Модель по умолчанию**: +Поддерживаемая модель, которую проект выбирает без явного указания модели пользователем для определённого пути выполнения. +_Avoid_: Рекомендуемая модель, поддерживаемая модель + +**Интеграционный smoke-тест**: +Минимальный сквозной прогон с реальным движком и моделью, подтверждающий загрузку модели и создание непустых сегментов с корректными таймкодами на короткой записи. Такой тест не является оценкой качества распознавания. +_Avoid_: Проверка качества, бенчмарк diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..d464624 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,47 @@ +# Domain Docs + +Репозиторий использует single-context layout. + +## Перед исследованием кода + +- Прочитать корневой `CONTEXT.md`. +- Прочитать относящиеся к задаче решения из `docs/adr/`. +- Проверить относящиеся к задаче исследования в `docs/research/`. +- Проверить относящиеся к задаче спецификации в `docs/specs/`. +- Если документа нет, продолжить молча: доменные документы создаются лениво + соответствующими навыками. + +## Структура + +```text +/ +├── CONTEXT.md +├── docs/ +│ ├── adr/ +│ ├── research/ +│ │ └── YYYY-MM-DD-slug.md +│ └── specs/ +│ └── YYYY-MM-DD-slug.md +└── src/ +``` + +## Назначение документов + +- `CONTEXT.md` — каноническая терминология предметной области. +- `docs/adr/` — принятые архитектурные решения и их обоснование. +- `docs/research/YYYY-MM-DD-slug.md` — результаты исследований, основанные на + источниках и экспериментах. +- `docs/specs/YYYY-MM-DD-slug.md` — согласованные спецификации изменений. + +## Терминология + +В задачах, тестах, предложениях и документации использовать термины из +`CONTEXT.md`. Не заменять их синонимами, перечисленными в `_Avoid_`. + +Если нужного понятия нет, проверить, действительно ли это доменный термин. +Существенный пробел передать в `domain-modeling`. + +## Конфликты с ADR + +Если предлагаемое изменение противоречит существующему ADR, указать конфликт +явно и объяснить, почему решение стоит пересмотреть. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..2c433a2 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,66 @@ +# Issue Tracker + +Задачи проекта ведутся в Gitea-репозитории `ddmitry/local-transcriber`. + +- Основной remote: `origin` +- Gitea: `https://git.dementev.space` +- CLI: `tea` +- Remote `github` является зеркалом и не используется для управления задачами +- Внешние pull request не входят в очередь triage + +## Доступ + +Перед операциями с задачами проверить наличие `tea`. + +Если команда недоступна, остановиться и предложить пользователю установку: + +```powershell +winget install --id Gitea.tea --exact +``` + +Не переключаться автоматически на GitHub Issues или локальные markdown-задачи. + +Проверить настроенные подключения: + +```powershell +tea login list +``` + +Если подходящего подключения нет, предложить пользователю настроить его через +`tea login add`. Не запрашивать и не выводить токены в переписке или логах. + +## Прокси + +Рабочее окружение использует корпоративный прокси (`HTTP_PROXY` и `HTTPS_PROXY`), +через который `git.dementev.space` недоступен: запрос к API завершается ошибкой +`EOF`. Хост нужно добавить в `NO_PROXY`. + +Разделитель — **запятая**, не точка с запятой: `tea` написан на Go, а Go +разбирает `NO_PROXY` по запятым, и хост после `;` не распознаётся. + +На текущую сессию: + +```powershell +$env:NO_PROXY = "$env:NO_PROXY,git.dementev.space" +``` + +Постоянно, в пользовательских переменных окружения (значение подхватят только +новые процессы): + +```powershell +[Environment]::SetEnvironmentVariable("NO_PROXY", "$env:NO_PROXY,git.dementev.space", "User") +``` + +## Работа с задачами + +Из рабочего дерева использовать Gitea remote `origin`: + +```powershell +tea issues list --remote origin +tea issues create --remote origin +tea issues edit --remote origin +tea labels list --remote origin +``` + +За пределами рабочего дерева явно указывать репозиторий +`ddmitry/local-transcriber` и настроенный Gitea login. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..bf33091 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,15 @@ +# Triage Labels + +Инженерные навыки используют пять канонических triage-ролей. В Gitea им +соответствуют одноимённые метки. + +| Роль навыка | Метка Gitea | Значение | +| --- | --- | --- | +| `needs-triage` | `needs-triage` | Требует оценки сопровождающим | +| `needs-info` | `needs-info` | Ожидает дополнительной информации от автора | +| `ready-for-agent` | `ready-for-agent` | Полностью описана и готова для автономного агента | +| `ready-for-human` | `ready-for-human` | Требует реализации человеком | +| `wontfix` | `wontfix` | Выполняться не будет | + +Когда навык упоминает triage-роль, следует использовать соответствующую метку +из этой таблицы.