Обзор принципов работы

Ядро DevLingo — это интеллектуальная система «многоуровневых запросов»: начиная с быстрого локального поиска и постепенно переходя к ИИ-обработке. Благодаря этому большинство запросов выполняются за миллисекунды, а даже сложные запросы занимают не более 2 секунд.

Полный рабочий процесс

Пользователь выделяет текст в любом приложении
    ↓
[Активация] Нажатие горячей клавиши ⌘⇧D
    ↓
[Извлечение] TextExtractor получает:
    - Выделенный текст
    - 50 символов контекста до и после (для понимания ИИ)
    - bundleIdentifier текущего приложения (Xcode / Slack / GitHub и т.д.)
    ↓
[Классификация] InputTypeDetector определяет тип ввода:
    - Родной язык → режим Express
    - Одно слово → режим Word
    - 2-4 слова без структуры предложения → режим Phrase
    - Полное предложение ≤20 слов → режим Sentence
    - Несколько предложений или >20 слов → режим Paragraph
    ↓
[Запрос] LookupCoordinator — многоуровневый запрос (подробнее ниже)
    ↓
[Отображение] FloatingPanelController:
    - Всплывающее окно NSPanel под курсором мыши
    - Показ скелетной анимации загрузки
    - Выбор соответствующего подвида (WordView / PhraseView / SentenceView и т.д.)
    - Плавное появление результатов
    ↓
[Взаимодействие] Пользователь может:
    - Нажать кнопку воспроизведения для прослушивания произношения
    - Нажать на слово для рекурсивного запроса
    - Сохранить в «Словарь» (SwiftData)
    - Закрыть всплывающее окно и продолжить работу

Система многоуровневых запросов

Это ключ к производительности DevLingo. Поиск выполняется по приоритету, результат возвращается при первом совпадении:

Уровень 1: Локальная база технических терминов (<50 мс)

Для английского ввода сначала выполняется поиск в локальной базе данных SQLite. Предустановлено 85+ распространённых терминов разработки:

idempotent, deployment, microservice, containerization,
latency, throughput, cache invalidation, API gateway,
circuit breaker, distributed tracing, ...

Процент попаданий — около 30% запросов по терминам разработки. Мгновенный отклик.

Уровень 2: Локальная база фраз разработки (<100 мс)

Для фраз из 2-4 слов выполняется поиск в локальной базе фраз (50+ предустановленных фраз):

yak shaving, bikeshedding, rubber ducking, code smell,
low-hanging fruit, technical debt, nerd sniping, ...

Процент попаданий — около 20% запросов фраз.

Уровень 3: Кэш SwiftData (<10 мс)

Ранее запрошенные слова, фразы и предложения кэшируются локально в SwiftData. При совпадении результат возвращается мгновенно.

Пользователь ранее искал "idempotent" → следующий запрос <10 мс

Процент попаданий — около 50% (зависит от истории использования).

Уровень 4: Claude API (0,5-2 сек)

Если первые три уровня не дали результата, выполняется вызов Claude API для получения структурированного ответа.

Запрос: {
  "text": "gracefully degrade",
  "mode": "phrase",
  "context": "when upstream dependencies are unavailable",
  "sourceApp": "Xcode",
  "userLanguage": "ru-RU"
}

Ответ: {
  "type": "phrase", // compound verb
  "definition_en": "...",
  "definition_zh": "...",
  "examples": [...],
  "pronunciation": {...},
  "register": "technical",
  "l1_tips": "..."
}

:::note Почему многоуровневая архитектура

• 95% частых слов попадают в первые три уровня, ответ менее чем за 100 мс
• 5% редких или новых слов требуют Claude API, но и это всего 1-2 секунды
• Без сети по-прежнему доступны локальная база и кэш
• Экономия квоты пользователя — Claude API тарифицируется по использованию, многоуровневая система сокращает 95% вызовов API :::

Архитектура бэкенда

Бэкенд DevLingo развёрнут на граничных узлах Cloudflare Workers для обработки API-запросов.

Mac-приложение
  ↓ HTTPS (Bearer token)
Cloudflare Workers (Edge)
  ├─ API Gateway (маршрутизация Hono)
  ├─ Auth Middleware (проверка JWT)
  ├─ Lookup Endpoint (/api/lookup)
  │   └─ Claude API Client (проксирование ИИ-запросов)
  ├─ TTS Endpoint (/api/tts)
  │   └─ Google Cloud TTS (проксирование синтеза произношения)
  └─ Data Sync Endpoints
      └─ Cloudflare D1 (база данных пользователей)

Ключевые компоненты

• Фреймворк Hono: лёгкий HTTP-фреймворк, оптимизированный для Cloudflare Workers
• База данных D1: SQLite на Cloudflare, хранит словарь пользователя и данные синхронизации
• Хранилище KV: сессионные токены, кэш ограничения частоты запросов, кэш ответов API
• Прокси Claude API: Mac-приложение проксирует запросы к Claude через Workers, избегая хранения API-ключей локально

Извлечение текста и контекст

TextExtractor использует AXUIElement (API Универсального доступа macOS) для получения:

Пользователь выделил в Slack: "idempotent"

Результат извлечения:
{
  "selectedText": "idempotent",
  "beforeContext": "We need to make sure this endpoint is ",
  "afterContext": " for retry requests.",
  "sourceApp": "com.tinyspeck.slackmacgap",  // Slack
  "fullSentence": "We need to make sure this endpoint is idempotent for retry requests."
}

Этот контекст передаётся Claude, помогая ИИ понять: «idempotent здесь используется в контексте проектирования API», а не в каком-либо ином.

Алгоритм определения типа ввода

if текст содержит символы родного языка:
  → режим Express
elif количество_слов == 1:
  → режим Word
elif количество_слов in [2, 3, 4]:
  if содержит полную структуру предложения:
    → режим Sentence
  else:
    → режим Phrase
elif количество_предложений > 1 or количество_слов > 20:
  → режим Paragraph
else:
  → режим Sentence

:::tip Интеллектуальное определение Определение типа ввода происходит локально мгновенно, без вызовов API. Пользователь никогда не ощутит задержки на этапе «определения типа ввода». :::

Всплывающее окно

FloatingPanelController создаёт NSPanel (всплывающее окно):

Характеристики:
- Отображается поверх всех приложений (Level: screenSaver)
- Позиция: непосредственно под курсором мыши (смещение y +20px, чтобы не закрывать текст)
- Начальное состояние: скелетная анимация загрузки
- При получении данных: плавное появление, удаление скелета
- Взаимодействие: полная прозрачность для мыши (не блокирует фоновые приложения)
- Закрытие: клик снаружи, нажатие ESC, автоматическое закрытие через 5 минут бездействия

Целевые показатели производительности

• Запрос к локальной базе: <50 мс (99-й перцентиль)
• Попадание в кэш: <10 мс
• Полный сквозной запрос (с API): <2 сек (99-й перцентиль)
• Время появления всплывающего окна: <300 мс (воспринимаемая скорость)
• Генерация TTS-аудио: первый раз <2 сек, последующие из кэша <100 мс

:::note Стратегия кэширования TTS-аудио также кэшируется локально и в KV — произношение одного и того же слова синтезируется только один раз. :::

Конфиденциальность данных

Текст пользователя
  ↓
Mac-приложение (шифрование HTTPS)
  ↓
Cloudflare Edge (мгновенная обработка)
  ├─ Запрос к Claude API (временный, не используется для обучения)
  └─ Кэширование результатов в KV (автоматическое истечение)
  ↓
Результат возвращается на Mac
  ↓
Локальное хранение SwiftData (на устройстве, опциональная облачная синхронизация в D1)

Текстовое содержимое не сохраняется, если пользователь не сохраняет его в словарь намеренно. Подробнее в разделе Конфиденциальность данных и безопасность.

Философия архитектуры DevLingo: «Скорость в приоритете, ИИ как помощник, конфиденциальность на первом месте».