From 9b4ea0a3c904fe92631065f4d8b94d47a41d5803 Mon Sep 17 00:00:00 2001 From: Andrey Epifancev Date: Sun, 27 Sep 2026 19:26:25 +0400 Subject: [PATCH] docs(openspec): archive core-recording-lifecycle, promote specs (#1) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01QKHeGuAYh4W1jNdjMConZa --- .../.openspec.yaml | 0 .../README.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/recording-lifecycle/spec.md | 0 .../specs/voice-note-format/spec.md | 0 openspec/specs/recording-lifecycle/spec.md | 126 ++++++++++++++++++ openspec/specs/voice-note-format/spec.md | 62 +++++++++ 8 files changed, 188 insertions(+) rename openspec/changes/{core-recording-lifecycle => archive/2026-09-27-core-recording-lifecycle}/.openspec.yaml (100%) rename openspec/changes/{core-recording-lifecycle => archive/2026-09-27-core-recording-lifecycle}/README.md (100%) rename openspec/changes/{core-recording-lifecycle => archive/2026-09-27-core-recording-lifecycle}/design.md (100%) rename openspec/changes/{core-recording-lifecycle => archive/2026-09-27-core-recording-lifecycle}/proposal.md (100%) rename openspec/changes/{core-recording-lifecycle => archive/2026-09-27-core-recording-lifecycle}/specs/recording-lifecycle/spec.md (100%) rename openspec/changes/{core-recording-lifecycle => archive/2026-09-27-core-recording-lifecycle}/specs/voice-note-format/spec.md (100%) create mode 100644 openspec/specs/recording-lifecycle/spec.md create mode 100644 openspec/specs/voice-note-format/spec.md diff --git a/openspec/changes/core-recording-lifecycle/.openspec.yaml b/openspec/changes/archive/2026-09-27-core-recording-lifecycle/.openspec.yaml similarity index 100% rename from openspec/changes/core-recording-lifecycle/.openspec.yaml rename to openspec/changes/archive/2026-09-27-core-recording-lifecycle/.openspec.yaml diff --git a/openspec/changes/core-recording-lifecycle/README.md b/openspec/changes/archive/2026-09-27-core-recording-lifecycle/README.md similarity index 100% rename from openspec/changes/core-recording-lifecycle/README.md rename to openspec/changes/archive/2026-09-27-core-recording-lifecycle/README.md diff --git a/openspec/changes/core-recording-lifecycle/design.md b/openspec/changes/archive/2026-09-27-core-recording-lifecycle/design.md similarity index 100% rename from openspec/changes/core-recording-lifecycle/design.md rename to openspec/changes/archive/2026-09-27-core-recording-lifecycle/design.md diff --git a/openspec/changes/core-recording-lifecycle/proposal.md b/openspec/changes/archive/2026-09-27-core-recording-lifecycle/proposal.md similarity index 100% rename from openspec/changes/core-recording-lifecycle/proposal.md rename to openspec/changes/archive/2026-09-27-core-recording-lifecycle/proposal.md diff --git a/openspec/changes/core-recording-lifecycle/specs/recording-lifecycle/spec.md b/openspec/changes/archive/2026-09-27-core-recording-lifecycle/specs/recording-lifecycle/spec.md similarity index 100% rename from openspec/changes/core-recording-lifecycle/specs/recording-lifecycle/spec.md rename to openspec/changes/archive/2026-09-27-core-recording-lifecycle/specs/recording-lifecycle/spec.md diff --git a/openspec/changes/core-recording-lifecycle/specs/voice-note-format/spec.md b/openspec/changes/archive/2026-09-27-core-recording-lifecycle/specs/voice-note-format/spec.md similarity index 100% rename from openspec/changes/core-recording-lifecycle/specs/voice-note-format/spec.md rename to openspec/changes/archive/2026-09-27-core-recording-lifecycle/specs/voice-note-format/spec.md diff --git a/openspec/specs/recording-lifecycle/spec.md b/openspec/specs/recording-lifecycle/spec.md new file mode 100644 index 0000000..10647a4 --- /dev/null +++ b/openspec/specs/recording-lifecycle/spec.md @@ -0,0 +1,126 @@ +# recording-lifecycle Specification + +## Purpose +Гарантирует, что каждая завершённая или прерванная голосовая запись сохраняется немедленно и доводится до текста через отправку во внешний сервис с повторами, без дублей между устройствами и без потери данных. + +## Requirements + +### Requirement: Состояния записи + +Запись MUST находиться ровно в одном из состояний: `created` (идёт запись, данные только в памяти), `saved` (аудио и заметка сохранены, ожидает отправки), `sent` (запрос в полёте), `transcribed` (текст получен, не записан; не сохраняется), `retry` (ожидает повтора после временной ошибки), `failed` (требуется ручное действие), `inserted` (финал). Во frontmatter заметки MUST сохраняться только `saved`, `sent`, `retry`, `failed`, `inserted`. Переход, не описанный в этой спецификации, MUST отклоняться ошибкой без изменения записи. + +#### Scenario: Недопустимый переход отклонён +- **WHEN** к записи в состоянии `inserted` применяется событие «отправка начата» +- **THEN** операция завершается ошибкой, запись не изменена + +#### Scenario: Транзитное состояние не попадает в заметку +- **WHEN** получен текст транскрипта +- **THEN** заметка за одну запись переходит из `sent` сразу в `inserted`, значение `transcribed` во frontmatter не появляется + +### Requirement: Сохранение захваченного аудио + +По окончании записи плагин MUST сохранить аудио в `voice/source/` и создать заметку в `voice/inbox/` в состоянии `saved` до любой сетевой операции. Если захвачено 0 байт, MUST NOT создаваться ни аудиофайл, ни заметка. Если запись была прервана (событие остановки не от пользователя), сохраняется всё накопленное, а запись помечается как прерванная. + +#### Scenario: Обычная запись +- **WHEN** пользователь остановил запись длиной 0:47 с непустыми данными в формате `audio/mp4` +- **THEN** в `voice/source/` появился файл `.m4a`, в `voice/inbox/` — заметка со статусом `saved`, и это произошло без сетевых запросов + +#### Scenario: Прерванная запись +- **WHEN** запись прервалась системой после 0:47 с непустыми данными +- **THEN** аудио и заметка сохранены, заметка помечена как прерванная с длительностью 0:47, и запись участвует в очереди как обычная + +#### Scenario: Пустая запись +- **WHEN** запись завершилась (штатно или обрывом) с 0 байт данных +- **THEN** никаких файлов не создано + +### Requirement: Отправка и результат + +Перед отправкой запись MUST перейти в `sent` с отметкой времени начала отправки, записанной в заметку. Очередь MUST обрабатывать записи строго по одной. Результат провайдера — успех с текстом, временная ошибка или постоянная ошибка. Успех с непустым текстом MUST переводить запись в `inserted` с текстом в заметке. Успех с пустым (после обрезки пробелов) текстом MUST переводить запись в `failed` с причиной «нет речи»: это свойство записи, а не ошибка сервиса, повтор бесполезен. + +#### Scenario: Успешное распознавание +- **WHEN** провайдер вернул текст, а запись в момент ответа в `sent` +- **THEN** заметка содержит текст и статус `inserted` + +#### Scenario: В записи нет речи +- **WHEN** провайдер вернул успех с текстом из одних пробелов +- **THEN** запись в `failed` с причиной «нет речи», в заметке — «В записи не распознано речи» + +#### Scenario: Последовательная обработка +- **WHEN** в очереди три готовые к отправке записи +- **THEN** второй запрос к провайдеру начинается только после завершения первого + +### Requirement: Повторы после временных ошибок + +Временная ошибка MUST увеличивать счётчик попыток и переводить запись в `retry` со временем следующей попытки через 30 с, 2 мин, 10 мин и 30 мин после 1-й, 2-й, 3-й и 4-й неудачи соответственно. Пятая неудача подряд MUST переводить запись в `failed`. Постоянная ошибка MUST переводить запись в `failed` сразу, независимо от счётчика. Запись в `retry` MUST NOT отправляться раньше своего времени следующей попытки. + +#### Scenario: Сеть пропала и вернулась +- **WHEN** первая отправка завершилась временной ошибкой в 14:15:03, а следующая попытка после 14:15:33 — успехом +- **THEN** после первой попытки запись в `retry` со следующей попыткой 14:15:33, после второй — в `inserted` + +#### Scenario: Исчерпание попыток +- **WHEN** пять отправок подряд завершились временной ошибкой +- **THEN** запись в `failed`, причина — последняя ошибка + +#### Scenario: Постоянная ошибка +- **WHEN** первая отправка завершилась постоянной ошибкой «401 Unauthorized» +- **THEN** запись сразу в `failed` с этой причиной + +#### Scenario: Время повтора не наступило +- **WHEN** очередь запускается в 14:15:20 для записи со следующей попыткой 14:15:33 +- **THEN** запрос к провайдеру не отправляется + +### Requirement: Восстановление после прерванной отправки + +Запись текущего устройства в `sent`, у которой с начала отправки прошло больше 10 минут, MUST считаться завершившейся временной ошибкой «отправка прервана» и обрабатываться по правилам повторов. + +#### Scenario: Obsidian выгружен во время запроса +- **WHEN** очередь запускается в 14:30:00 и находит запись в `sent` с началом отправки 14:19:00 +- **THEN** запись учитывается как временная неудача и планируется к повтору + +#### Scenario: Запрос ещё может идти +- **WHEN** очередь находит запись в `sent` с началом отправки 2 минуты назад +- **THEN** запись не трогается + +### Requirement: Принадлежность устройству + +Каждая запись MUST хранить идентификатор создавшего её устройства. Автоматическая обработка очереди MUST брать только записи текущего устройства. Идентификатор устройства MUST NOT синхронизироваться между устройствами. + +#### Scenario: Чужая запись не отправляется автоматически +- **WHEN** на маке запускается очередь, а в vault есть запись в `saved`, созданная на iPhone +- **THEN** мак не отправляет её + +### Requirement: Команда «Распознать все ожидающие здесь» + +Команда MUST переназначить текущему устройству все записи других устройств в состояниях `saved`, `retry` и `sent` старше 10 минут, после чего обработать очередь без ожидания времени следующей попытки. Записи в `failed` и `inserted`, а также `sent` не старше 10 минут, MUST NOT затрагиваться. + +#### Scenario: Мак забирает запись телефона +- **WHEN** на маке выполнена команда, а в vault есть запись iPhone в `retry` со следующей попыткой через 20 минут +- **THEN** запись переназначена маку и отправлена сейчас + +### Requirement: Команда «Повторить распознавание» + +Команда для записи в `failed` или `retry` MUST сбросить счётчик попыток в 0, перевести запись в `saved` и запустить очередь. Для записей в других состояниях команда MUST ничего не менять. + +#### Scenario: Повтор после исправления ключа +- **WHEN** запись в `failed` после 401, пользователь исправил ключ и выполнил команду +- **THEN** запись отправлена заново со счётчиком попыток, начатым с нуля + +### Requirement: Удалённая заметка отменяет запись + +Состояние записи живёт только во frontmatter её заметки; очередь находит записи по наличию ключа `voice-id` в любом месте vault, а не по папке. Если заметку удалили, запись MUST считаться отменённой, и её аудиофайл MUST NOT удаляться. Если заметку удалили во время запроса, пришедший результат MUST отбрасываться без ошибки и без воссоздания заметки. + +#### Scenario: Заметка удалена во время запроса +- **WHEN** провайдер вернул текст после того, как заметку удалили +- **THEN** заметка не создана заново, очередь продолжает работу со следующей записью + +#### Scenario: Заметка перенесена в другую папку +- **WHEN** пользователь перенёс заметку в `saved` из `voice/inbox/` в `projects/` +- **THEN** запись по-прежнему обрабатывается очередью + +### Requirement: Повторный запуск очереди + +Если запуск очереди запрошен, пока она уже работает, новый параллельный проход MUST NOT начинаться; вместо этого MUST выполниться ровно один дополнительный проход после завершения текущего. + +#### Scenario: Три запроса во время работы +- **WHEN** очередь обрабатывает запись и за это время запуск запрошен три раза +- **THEN** после текущего прохода выполняется ровно один дополнительный проход diff --git a/openspec/specs/voice-note-format/spec.md b/openspec/specs/voice-note-format/spec.md new file mode 100644 index 0000000..5d1059b --- /dev/null +++ b/openspec/specs/voice-note-format/spec.md @@ -0,0 +1,62 @@ +# voice-note-format Specification + +## Purpose +Определяет, где и под какими именами лежат аудиофайлы и заметки голосовых записей, как в заметке хранится состояние записи и как плагин обновляет заметку, не затрагивая текст пользователя. + +## Requirements + +### Requirement: Идентификатор и имена файлов + +Идентификатор записи MUST иметь вид `YYYYMMDD-HHMMSS-xxxx` (время начала записи в UTC и 4 случайных шестнадцатеричных символа в нижнем регистре). Аудио MUST сохраняться как `voice/source/.`, где расширение определяется по mime без параметров: `audio/mp4` → `m4a`, `audio/webm` → `webm`, `audio/ogg` → `ogg`, любой другой → `bin`. Заметка MUST создаваться как `voice/inbox/YYYY-MM-DD HH-mm-ss.md` по локальному времени начала записи; при занятом имени MUST добавляться суффикс ` (2)`, ` (3)` и т.д. + +#### Scenario: Mime с параметрами +- **WHEN** запись в формате `audio/webm;codecs=opus` начата 27.09.2026 в 14:15:03 на устройстве в поясе UTC+3 +- **THEN** аудио сохранено как `voice/source/20260927-111503-<4 hex>.webm`, заметка — `voice/inbox/2026-09-27 14-15-03.md` + +#### Scenario: Коллизия имени заметки +- **WHEN** заметка `voice/inbox/2026-09-27 14-15-03.md` уже существует +- **THEN** новая заметка создана как `voice/inbox/2026-09-27 14-15-03 (2).md` + +### Requirement: Ключи frontmatter + +Состояние записи MUST храниться в плоских ключах frontmatter: `voice-id`, `voice-status`, `voice-device`, `voice-audio` (wiki-ссылка на аудио), `voice-mime` (исходный mime с параметрами), `voice-attempts`, а также, когда применимо, `voice-next-attempt` и `voice-sent-at` (ISO 8601 UTC), `voice-error`, `voice-interrupted`. Плагин MUST изменять только ключи с префиксом `voice-`, а остальные ключи и их порядок MUST оставаться нетронутыми. При переходе в `inserted` ключи `voice-next-attempt`, `voice-sent-at` и `voice-error` MUST удаляться. Заметка с отсутствующим или некорректным `voice-status` MUST игнорироваться очередью. + +#### Scenario: Пользовательские свойства сохраняются +- **WHEN** пользователь добавил в заметку свойство `tags: [idea]`, а затем запись перешла в `inserted` +- **THEN** `tags: [idea]` на месте в прежней позиции, ключи `voice-*` обновлены + +#### Scenario: Испорченный статус +- **WHEN** пользователь вручную записал `voice-status: foo` +- **THEN** очередь не обрабатывает заметку и не падает + +### Requirement: Тело заметки до распознавания + +Новая заметка MUST содержать вложение аудио `![[<путь к аудио>]]`, затем управляемую область, ограниченную маркерами-комментариями `%%voice-note:%%` и `%%/voice-note%%`. Внутри области MUST отображаться состояние: для `saved`/`sent` — `> [!info] Распознаётся…`; для `retry` — `> [!info] Не удалось отправить, повтор в HH:mm (попытка N/5)` по локальному времени; для `failed` — `> [!warning] Не распознано: <причина>. Команда «Повторить распознавание»`, кроме причины «нет речи», для которой — `> [!info] В записи не распознано речи` (без слова «ошибка» и без призыва повторить). Для прерванной записи над областью MUST стоять строка `> [!note] Запись прервана, сохранено M:SS`, которая остаётся и после вставки текста. + +#### Scenario: Заметка в ожидании повтора +- **WHEN** запись перешла в `retry` после второй неудачи со следующей попыткой в 14:17 по местному времени +- **THEN** область содержит `> [!info] Не удалось отправить, повтор в 14:17 (попытка 2/5)` + +### Requirement: Вставка транскрипта + +При переходе в `inserted` управляемая область вместе с маркерами MUST заменяться текстом транскрипта. Весь текст за пределами области MUST оставаться без изменений. Если маркеры не найдены, транскрипт MUST дописываться в конец заметки через пустую строку. Если запись уже в `inserted`, повторная вставка MUST не менять заметку. Обновление статуса и тела MUST выполняться одной операцией записи. + +#### Scenario: Пользователь дописал текст под заметкой +- **WHEN** под управляемой областью пользователь написал «купить молоко», затем пришёл транскрипт +- **THEN** область заменена транскриптом, «купить молоко» осталось на месте + +#### Scenario: Маркеры удалены вручную +- **WHEN** пользователь стёр маркеры, затем пришёл транскрипт +- **THEN** транскрипт дописан в конец заметки, статус `inserted` + +#### Scenario: Дубль ответа +- **WHEN** транскрипт приходит для записи, уже находящейся в `inserted` +- **THEN** содержимое заметки не изменилось + +### Requirement: Golden-эталоны + +Для каждой пары фикстур `tests/fixtures/.` + `.txt` с эталоном `.note.md` полный путь «захват → очередь → вставка» с провайдером, отвечающим содержимым `.txt`, при фиксированных времени, идентификаторе устройства и источнике случайности MUST давать заметку, побайтно совпадающую с `.note.md`. Провайдер MUST получать байты аудиофикстуры без изменений и исходный mime. + +#### Scenario: test-01 +- **WHEN** прогоняется фикстура `test-01.m4a` с mime `audio/mp4` и ответом из `test-01.txt` +- **THEN** итоговая заметка совпадает с `test-01.note.md`