obsidian-voice-note/CLAUDE.md

Obsidian Voice Note — плагин голосовых заметок

Что это

Плагин Obsidian: запись голоса с телефона или десктопа → отправка файлом во внешний сервис распознавания → текст в заметку. Mobile-first: основной сценарий — iPhone, десктоп получает то же.

Стек и ограничения

• TypeScript, esbuild (стандартный шаблон obsidian-sample-plugin), vitest для тестов.
• isDesktopOnly: false в manifest.json. Никакого Node API (fs, child_process, path), только Web API и API Obsidian (requestUrl, app.vault).
• Запись: MediaRecorder. Форматы на входе различаются: iOS даёт audio/mp4, Android — audio/webm, десктоп — webm/ogg. Провайдер должен принимать все три или конвертировать.
• Отправка файлом, без стриминга.

Архитектура

• src/core/ — чистый TypeScript без импортов из obsidian: машина состояний записи (created → saved → sent → transcribed → inserted, ветки на потерю сети и обрыв записи), очередь отправки, провайдеры распознавания, формирование markdown-заметки. Покрывается vitest полностью.
• src/obsidian/ — тонкая обёртка: команды, настройки, UI, работа с vault. Юнит-тестов нет, проверяется руками в тестовом vault.
• Провайдер — интерфейс с реализациями: openai-compatible (AITUNNEL по умолчанию; Groq, OpenAI, whisper на VPS — тот же код, другой URL) и при необходимости yandex. Переключение на следующего провайдера по 403/таймауту.
• Ключи API — в настройках плагина (data.json), в git не попадают.

Команды

• npm run dev — сборка в watch-режиме в тестовый vault. Другой vault — через VOICE_NOTE_VAULT=<путь> npm run dev; если vault не найден, копирование пропускается с предупреждением.
• npm test — vitest, вся папка tests/. Зелёным считается весь набор.
• npm run build — продакшн-сборка main.js.
• npm run typecheck — два прохода: весь проект с Node-типами и src/core через tsconfig.core.json без Node-типов (process, Buffer в core — ошибка компиляции).
• Версии зависимостей точные (.npmrc: save-exact=true). Lock-файл не перегенерировать через npm install на одной ОС: npm вычищает опциональные бинарники других платформ.

Тесты

• Golden-тесты: tests/fixtures/<name>.m4a + tests/fixtures/<name>.txt (эталонный транскрипт). Провайдер в тестах мокается; golden-файлы проверяют формирование заметки и обработку ответа, а не сам сервис.
• Тестовый vault: /Users/andrey.epifancev/Library/Mobile Documents/iCloud~md~obsidian/Documents/voice-note-test — синхронизируется между Mac и телефоном.

Первая подсистема

Жизненный цикл записи и очередь (core), затем провайдер, затем обёртка. Тестовая инфраструктура — Task 1 первого плана.

OpenSpec и superpowers

• Вход в любую задачу — superpowers:brainstorming. Skills openspec-propose и openspec-explore сами по себе не запускать.
• Когда brainstorming классифицировал задачу как architectural, структуру change создать через /opsx:propose <id> (или скопировать его шаблон), а содержимое proposal.md, specs/ и design.md написать по итогам brainstorming. tasks.md из OpenSpec не заполнять — задачи живут в плане superpowers.
• /opsx:apply не использовать: исполнение идёт через writing-plans и SDD/executing-plans.
• /opsx:archive <id> — после merge PR, как часть закрытия.